docs: 标准化接口主文档导航与章节锚点
This commit is contained in:
parent
d95fffc630
commit
3ba723f8f4
@ -111,6 +111,7 @@
|
||||
|
||||
| 变更时间 | 变更类型 | 变更内容 | 变更原因 | 影响评估 |
|
||||
| ---------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| 2026-03-11 | `03_Interface_Design` 主文档导航与锚点标准化 | 持续优化接口主文档可检索性：1）重构 `docs/design/03_Technical_Design/03_Interface_Design.md` 顶部导航为“章节导航（精简）”，将原目录链接统一切换为 `sec-*` 显式锚点；2）为“接口设计范围、设计原则、接口视图、外部接口、内部接口、数据对象、接口安全、实现状态”补齐稳定锚点；3）同步更新 `docs/design/00_Management/11_Main_Doc_Chapter_Index.md` 的接口主文档入口，统一改为标准化锚点。 | 用户要求“也做吧”，需要将接口主文档与已完成的概要/详细/技术主文档保持同一导航与锚点规范 | 正面影响，接口主文档章节跳转稳定性提升，避免依赖自动标题锚点；主文档章节索引与正文章节映射一致，AI 检索命中与跨文档定位效率进一步提高。 |
|
||||
| 2026-03-11 | `03_Technical_Design` 主文档导航与锚点标准化 | 持续优化技术专项主文档可检索性：1）重构 `docs/design/03_Technical_Design/01_Database_Design.md` 顶部导航为“章节导航（精简）”，移除旧目录块并为核心章节补齐 `sec-*` 稳定锚点；2）重构 `docs/design/03_Technical_Design/04_Security_Design.md` 导航并补齐 `sec-*` 锚点；3）重构 `docs/design/03_Technical_Design/05_Deployment_Design.md` 导航并补齐 `sec-*` 锚点，同时清理文档尾部误混入的脚本片段；4）同步更新 `docs/design/00_Management/11_Main_Doc_Chapter_Index.md`，将数据库/安全/部署入口统一切换到标准化锚点。 | 用户要求“持续优化”，需要将技术主文档导航策略与既有概要/详细设计保持同一锚点标准，降低检索与跳转不稳定问题 | 正面影响，技术主文档形成统一“精简导航 + 显式锚点”口径，跨文档链接稳定性提升；部署主文档去除非正文噪音后更符合交付文档定位；索引入口与正文章节映射一致，便于 AI 与人工协同维护。 |
|
||||
| 2026-03-11 | 主文档导航索引与检索白名单持续优化 | 持续优化 AI 检索与导航资产：1）重写 `docs/design/00_Management/11_Main_Doc_Chapter_Index.md`，将旧目录路径（`01_High_Level`、`02_Detailed`、`03_Technical`）统一修正为 `01_Overview`、`02_Detailed_Design`、`03_Technical_Design`，并补充详细设计分模块正文入口；2）更新 `docs/design/00_Management/10_AI_Retrieval_Whitelist.md`，将章节索引与模块追溯索引提升至 P1，并将 `11~15` 分模块正文纳入 P2；3）同步修订 `docs/design/01_Project_Overview.md` 对详细设计目录职责的描述。 | 用户要求“持续优化”，需要在已完成重构基础上继续提升导航准确性与 AI 检索稳定性 | 正面影响，主文档导航与白名单策略与当前目录结构完全对齐，减少旧路径误导和检索漂移；分模块正文入口更明确，便于按模块持续迭代。 |
|
||||
| 2026-03-11 | `01_Detailed_Design` 模块正文去重重构 | 将 `docs/design/02_Detailed_Design/01_Detailed_Design.md` 中五大模块章节（统一平台、营收业务、客户服务、表务、报装与签章）改为“章节定位 + 模块摘要矩阵 + 分模块正文链接”，移除重复详细正文；同步将 `02_Module_Traceability_Index.md` 的模块级链接切换至 `11_UP_Detailed.md`、`12_REV_Detailed.md`、`13_CS_Detailed.md`、`14_METER_Detailed.md`、`15_INST_Detailed.md`，确保主详设与分模块正文职责清晰且链接可用。 | 用户要求“模块正文改为仅保留摘要 + 链接到分模块文件，彻底去重” | 正面影响，主详设从“重复正文集合”收敛为“总册导航与口径文档”，显著降低双份维护成本，后续按模块独立迭代时的一致性和可追溯性更高。 |
|
||||
|
||||
@ -138,6 +138,14 @@
|
||||
|
||||
## ✅ 最新完成任务 (持续更新)
|
||||
|
||||
### 📋 `03_Interface_Design` 主文档导航锚点标准化
|
||||
|
||||
- [x] **完成接口主文档导航精简与稳定锚点改造** ✅ (2026-03-11)
|
||||
- [x] 重构 `03_Interface_Design.md` 顶部为“章节导航（精简）”，移除旧目录锚点依赖 ✅
|
||||
- [x] 为接口主文档核心章节补齐 `sec-*` 显式锚点（范围、原则、接口视图、外部、内部、数据对象、安全、状态）✅
|
||||
- [x] 更新 `11_Main_Doc_Chapter_Index.md` 的接口章节入口为标准化锚点 ✅
|
||||
- [x] 更新项目进度文件记录本次持续优化动作 ✅
|
||||
|
||||
### 📋 `03_Technical_Design` 主文档导航锚点标准化
|
||||
|
||||
- [x] **完成技术主文档导航精简与稳定锚点改造** ✅ (2026-03-11)
|
||||
|
||||
@ -70,12 +70,12 @@
|
||||
|
||||
| 快速入口 | 链接 |
|
||||
| --- | --- |
|
||||
| 接口设计范围 | [接口设计范围](../03_Technical_Design/03_Interface_Design.md#接口设计范围) |
|
||||
| 设计原则与统一约束 | [设计原则与统一约束](../03_Technical_Design/03_Interface_Design.md#设计原则与统一约束) |
|
||||
| 外部接口设计 | [外部接口设计](../03_Technical_Design/03_Interface_Design.md#外部接口设计) |
|
||||
| 内部接口设计 | [内部接口设计](../03_Technical_Design/03_Interface_Design.md#内部接口设计) |
|
||||
| 数据对象与表口径 | [数据对象与表口径](../03_Technical_Design/03_Interface_Design.md#数据对象与表口径) |
|
||||
| 接口安全与异常处理 | [接口安全与异常处理](../03_Technical_Design/03_Interface_Design.md#接口安全与异常处理) |
|
||||
| 接口设计范围 | [接口设计范围](../03_Technical_Design/03_Interface_Design.md#sec-scope) |
|
||||
| 设计原则与统一约束 | [设计原则与统一约束](../03_Technical_Design/03_Interface_Design.md#sec-principles) |
|
||||
| 外部接口设计 | [外部接口设计](../03_Technical_Design/03_Interface_Design.md#sec-external-interface) |
|
||||
| 内部接口设计 | [内部接口设计](../03_Technical_Design/03_Interface_Design.md#sec-internal-interface) |
|
||||
| 数据对象与表口径 | [数据对象与表口径](../03_Technical_Design/03_Interface_Design.md#sec-data-object) |
|
||||
| 接口安全与异常处理 | [接口安全与异常处理](../03_Technical_Design/03_Interface_Design.md#sec-security-exception) |
|
||||
|
||||
### 2.5 安全与部署主文档
|
||||
|
||||
|
||||
@ -20,16 +20,17 @@ retrieval_priority: P0
|
||||
| **编写日期** | 2026-03-11 |
|
||||
| **文档状态** | 🔄 持续完善 |
|
||||
|
||||
## 目录
|
||||
- [接口设计范围](#接口设计范围)
|
||||
- [设计原则与统一约束](#设计原则与统一约束)
|
||||
- [SYS-002 接口视图](#sys-002-接口视图)
|
||||
- [外部接口设计](#外部接口设计)
|
||||
- [内部接口设计](#内部接口设计)
|
||||
- [数据对象与表口径](#数据对象与表口径)
|
||||
- [接口安全与异常处理](#接口安全与异常处理)
|
||||
- [实现状态说明](#实现状态说明)
|
||||
## 章节导航（精简）
|
||||
- [接口设计范围](#sec-scope)
|
||||
- [设计原则与统一约束](#sec-principles)
|
||||
- [SYS-002 接口视图](#sec-rev-interface-view)
|
||||
- [外部接口设计](#sec-external-interface)
|
||||
- [内部接口设计](#sec-internal-interface)
|
||||
- [数据对象与表口径](#sec-data-object)
|
||||
- [接口安全与异常处理](#sec-security-exception)
|
||||
- [实现状态说明](#sec-status)
|
||||
|
||||
<a id="sec-scope"></a>
|
||||
## 接口设计范围
|
||||
|
||||
本文档用于描述福建水务营收系统的接口边界、调用方式、核心接口清单以及与外围子系统的协同关系，重点统一 `SYS-002` 营收业务系统的接口口径。
|
||||
@ -44,6 +45,7 @@ retrieval_priority: P0
|
||||
|
||||
> 说明：本文档优先描述正式设计边界与业务接口职责，不将 backend 中尚未明确识别的内部实现细节误写为既有接口事实。对于历史资料中存在、但当前 backend 未完全确认的接口对象，统一按“文档先行”处理。
|
||||
|
||||
<a id="sec-principles"></a>
|
||||
## 设计原则与统一约束
|
||||
|
||||
### 接口设计原则
|
||||
@ -81,6 +83,7 @@ retrieval_priority: P0
|
||||
}
|
||||
```
|
||||
|
||||
<a id="sec-rev-interface-view"></a>
|
||||
## SYS-002 接口视图
|
||||
|
||||
### 模块分组
|
||||
@ -119,6 +122,7 @@ retrieval_priority: P0
|
||||
| SYS-009 支付与银行结算 | 微信/支付宝支付、银行实时收费、代扣、对账、结算 | 发起订单、接收支付结果、维护账单核销状态 | 承接支付渠道、交易流水、回调、对账与结算 |
|
||||
| SYS-010 消息服务 | 催缴通知、缴费结果通知、办理进度通知 | 生成待通知业务事件与目标用户 | 承接短信、微信公众号、站内信等触达能力 |
|
||||
|
||||
<a id="sec-external-interface"></a>
|
||||
## 外部接口设计
|
||||
|
||||
## 外部接口分类
|
||||
@ -241,6 +245,7 @@ retrieval_priority: P0
|
||||
| 业务说明 | 接收远传读数、设备状态、异常告警，触发抄表校验与开账准备 |
|
||||
| 核心数据支撑 | `biz_meter_read`、`biz_reading_data`、`biz_last_reading` |
|
||||
|
||||
<a id="sec-internal-interface"></a>
|
||||
## 内部接口设计
|
||||
|
||||
## SYS-002 内部接口清单
|
||||
@ -740,6 +745,7 @@ sequenceDiagram
|
||||
SYS002-->>Job: 返回催缴任务执行结果
|
||||
```
|
||||
|
||||
<a id="sec-data-object"></a>
|
||||
## 数据对象与表口径
|
||||
|
||||
### SYS-002 接口核心数据对象
|
||||
@ -832,6 +838,7 @@ sequenceDiagram
|
||||
| 发送结果回写 | `sendTime` | `sendTime` | 发送时间 | 消息结果 |
|
||||
| 发送结果回写 | `msg` | `resultMsg` | 结果说明 | 返回消息 |
|
||||
|
||||
<a id="sec-security-exception"></a>
|
||||
## 接口安全与异常处理
|
||||
|
||||
### 认证与鉴权
|
||||
@ -922,6 +929,7 @@ sequenceDiagram
|
||||
- 外部结果晚到：允许按幂等键补写回执，但不得回退已确认成功状态。
|
||||
- 人工兜底场景：支付异常、银行回盘异常、发票状态冲突等需保留人工复核入口与操作日志。
|
||||
|
||||
<a id="sec-status"></a>
|
||||
## 实现状态说明
|
||||
|
||||
### 已落地
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user