docs: 同步CS模块模板与接口追溯

2026-03-11 18:39:44 +08:00 · 2026-03-11 18:39:44 +08:00 · 5a0488f885
commit 5a0488f885
parent 2f580f26d8
3 changed files with 151 additions and 0 deletions
--- a/docs/design/00_Management/01_Project_Progress.md
+++ b/docs/design/00_Management/01_Project_Progress.md
@ -114,6 +114,7 @@

 > 说明：本表中的历史记录按当时原始表述保留；当前正式数据库口径统一以“达梦数据库 8.0+”为准。

+| 2026-03-11 | `13_CS_Detailed` 结构对齐补完（模板同步） | 对 `docs/design/02_Detailed_Design/13_CS_Detailed.md` 执行与 REV 同步的结构化补完：1）新增“客户服务模块统一约束”与“接口与数据追溯矩阵”；2）为 `CS-001~CS-007` 全模块补充“接口映射”；3）补充 `CS-005`、`CS-006` 核心数据与各模块落地边界；4）为 `CS-003`、`CS-007` 增加支付相关流程图，强化渠道侧到营收侧的协同链路表达。 | 用户要求继续将“统一约束 + 追溯矩阵 + 接口映射”模板同步到 `13_CS_Detailed.md`。 | 正面影响，客户服务模块文档结构与营收模块保持一致，接口追溯与评审路径更清晰；渠道受理与 `SYS-002/008/009/010` 协同边界明确，可降低后续改稿与联调阶段的口径偏差。 |
 | 2026-03-11 | `12_REV_Detailed` 设计补完（结构化增强） | 补完 `docs/design/02_Detailed_Design/12_REV_Detailed.md`：1）新增“营收模块统一约束”章节；2）新增“接口与数据追溯矩阵”，统一 `REV-001~REV-009` 对应 `IF-REV-*` 与核心数据域；3）为各 REV 模块补充“接口映射”段落；4）补齐 `REV-009` 缺失的“接口映射 + 落地边界”；5）为 `REV-004/005/006/008` 增加流程图，强化评审可读性与协同边界说明。 | 用户要求补完 `12_REV_Detailed.md`，并提升评审可交付性与跨文档追溯效率。 | 正面影响，营收模块正文从“说明型”提升为“可追溯、可评审、可维护”结构；接口、数据、协同边界更清晰，减少详细设计与接口/数据库专题之间的理解偏差。 |
 | 2026-03-11 | `docs/design` P2 优化（Archive 标签化与抽检自动化） | 完成 P2 持续优化：1）新增 `scripts/generate-archive-tag-index.sh` 并生成 `docs/design/04_Appendix/Archive/00_Archive_Tag_Index.md`，对 Archive 文档按“来源/用途/可信级别”标签化；2）新增 `scripts/ai-weekly-audit-diff.sh` 并输出 `docs/design/00_Management/14_AI_Audit_Diff_Latest.md` 差异清单；3）在 `Makefile` 接入 `archive-tag-index` 与 `ai-audit-diff` 命令；4）同步更新 `12_AI_Weekly_Audit_Template.md`、`04_Appendix/README.md`、`00_Management/README.md`、`scripts/README.md` 的入口说明。 | 用户要求执行 P2 优化清单，需把“标签化 + 自动化”从规划项落地为可执行资产。 | 正面影响，Archive 资料从“目录分类”升级为“可检索标签资产”；AI 抽检从人工记录升级为脚本化差异输出，周检可复用、可对比、可追踪，后续持续治理成本显著降低。 |
 | 2026-03-11 | `docs/design` P1 修复（治理口径与统一入口） | 执行 P1 修复清单：1）更新 `00_Management/04_Writing_Guide.md` 中数据库选型与术语标准，统一为“达梦数据库 8.0+”；2）修复 `00_Management/03_Task_Checklist.md` 与 `00_Management/01_Project_Progress.md` 当前交付总结中的旧数据库表述；3）增强 `00_Management/11_Main_Doc_Chapter_Index.md` 的数据库导航，新增 `METER/INST` 专题边界与 `02_Table_Specs` 映射入口；4）更新 `00_Management/10_AI_Retrieval_Whitelist.md`，将 `02_Table_Specs.md` 纳入 P2 映射检索。 | 用户要求“执行 P1 修复清单”，需完成跨文档术语映射统一与入口完善。 | 正面影响，治理文档与主文档口径进一步对齐，减少历史术语对 AI 检索与评审的干扰；数据库主口径与映射补充入口更清晰，P0/P1/P2 检索链路更加稳定。 |
--- a/docs/design/00_Management/03_Task_Checklist.md
+++ b/docs/design/00_Management/03_Task_Checklist.md
@ -138,6 +138,15 @@

 ## ✅ 最新完成任务 (持续更新)

+### 📋 `13_CS_Detailed` 模板同步补完
+
+- [x] **完成客户服务模块结构与追溯增强** ✅ (2026-03-11)
+  - [x] 新增“客户服务模块统一约束”章节，明确渠道侧与 `SYS-002/008/009/010` 协同边界 ✅
+  - [x] 新增“接口与数据追溯矩阵”，覆盖 `CS-001~CS-007` 的接口与数据域映射 ✅
+  - [x] 为 `CS-001~CS-007` 全模块补充“接口映射”段落 ✅
+  - [x] 补充 `CS-005`、`CS-006` 核心数据与全模块落地边界描述 ✅
+  - [x] 为 `CS-003`、`CS-007` 增加支付流程图，提升渠道协同评审可读性 ✅
+
 ### 📋 `12_REV_Detailed` 设计补完（结构化增强）

 - [x] **完成营收模块正文补完与追溯增强** ✅ (2026-03-11)
--- a/docs/design/02_Detailed_Design/13_CS_Detailed.md
+++ b/docs/design/02_Detailed_Design/13_CS_Detailed.md
@ -14,6 +14,8 @@ retrieval_priority: P1

 - [文档定位](#sec-position)
 - [客户服务详细设计正文](#sec-content)
+  - [客户服务模块统一约束](#sec-cs-rules)
+  - [接口与数据追溯矩阵](#sec-cs-trace)
  - [CS-001 账户绑定管理](#mod-cs-001)
  - [CS-002 信息查询服务](#mod-cs-002)
  - [CS-003 在线缴费服务](#mod-cs-003)
@ -32,6 +34,32 @@ retrieval_priority: P1

 # 客户服务模块详细设计

+<a id="sec-cs-rules"></a>
+
+## 客户服务模块统一约束
+
+1. 客户服务模块负责渠道侧受理与展示，核心账务、发票、通知结果均由 `SYS-002` 统一落账与回写。
+2. 支付、发票、消息分别通过 `SYS-009`、`SYS-008`、`SYS-010` 协同完成，客户服务模块不直接承载外部平台业务规则。
+3. 账户绑定、在线支付、发票申请、业务办理等关键动作必须进行身份校验与权限校验，禁止匿名高风险操作。
+4. 支付与发票场景必须具备幂等控制，避免重复下单、重复开票、重复回写导致业务状态不一致。
+5. 渠道请求、结果回写、人工补偿动作应保留可追溯日志，满足审计与争议处理要求。
+
+<a id="sec-cs-trace"></a>
+
+## 接口与数据追溯矩阵
+
+> 说明：详细接口字段与报文以 `../03_Technical_Design/03_Interface_Design.md` 为准。
+
+| CS 模块 | 关键接口 | 核心数据域（摘要） | 主要协同对象 |
+|---|---|---|---|
+| CS-001 账户绑定管理 | `IF-CS-001` | `biz_cust_app_binds`、`biz_cust`、`biz_account` | 微信、支付宝、微网厅 |
+| CS-002 信息查询服务 | `IF-CS-002` | `biz_charge*`、`biz_reading_data`、`biz_invoice` | 客户渠道、`SYS-002` |
+| CS-003 在线缴费服务 | `IF-CS-003` | `biz_charge*`、`biz_collection`、`bk_transaction*` | `SYS-009` |
+| CS-004 电子发票服务 | `IF-CS-004` | `biz_invoice*`、`biz_cust_invoice` | `SYS-008` |
+| CS-005 营业网点服务 | `IF-CS-005` | `biz_outlets`、`biz_business_types` | 客户渠道 |
+| CS-006 业务办理服务 | `IF-CS-006` | `biz_process*`、`biz_content_attach` | 工单系统、`SYS-010` |
+| CS-007 柜面扫码支付 | `IF-CS-007` | `biz_collection`、`bk_transaction*`、`biz_charge` | 营业厅、`SYS-009` |
+
 <a id="mod-cs-001"></a>

 ## CS-001 账户绑定管理
@ -52,6 +80,17 @@ retrieval_priority: P1
 - `biz_cust`
 - `biz_account`

+### 接口映射
+
+- `IF-CS-001`：渠道账户绑定、解绑、默认账户切换。
+- `IF-REV-001`：客户与账户信息查询，校验绑定对象合法性。
+
+### 落地边界
+
+- **已落地**：渠道绑定关系、客户与账户主数据引用。
+- **部分落地**：多渠道同账号合并策略依赖业务规则与运营配置共同控制。
+- **文档先行**：跨渠道统一身份画像与复杂合并规则仅保留设计语义。
+
 <a id="mod-cs-002"></a>

 ## CS-002 信息查询服务
@ -74,6 +113,18 @@ retrieval_priority: P1
 - `biz_charge_detail`
 - `biz_invoice`

+### 接口映射
+
+- `IF-CS-002`：账单、欠费、缴费、用水、发票等聚合查询。
+- `IF-REV-001`：客户基础信息查询与状态校验。
+- `IF-REV-010`：统计类查询场景复用营收统计接口能力。
+
+### 落地边界
+
+- **已落地**：账单、缴费、发票、客户信息等基础查询链路。
+- **部分落地**：部分专题分析更多依赖报表端，不在渠道侧单独建模。
+- **文档先行**：个性化推荐与预测分析不作为当前已实现能力表述。
+
 <a id="mod-cs-003"></a>

 ## CS-003 在线缴费服务
@ -82,6 +133,18 @@ retrieval_priority: P1

 提供微信支付、支付宝支付、银行卡支付、预存款支付等在线缴费能力。

+### 业务流程
+
+```mermaid
+flowchart TD
+    A[提交缴费请求] --> B[校验账单与应缴金额]
+    B --> C[创建业务订单]
+    C --> D[调用SYS-009下单]
+    D --> E[接收支付回调/查询结果]
+    E --> F[更新核销状态]
+    F --> G[返回缴费结果]
+```
+
 ### 关键规则

 1. 下单前再次校验账单未缴状态和应缴金额。
@ -95,6 +158,18 @@ retrieval_priority: P1
 - `bk_transaction`
 - `bk_transaction_callback`

+### 接口映射
+
+- `IF-CS-003`：客户渠道支付下单入口。
+- `IF-EXT-004`、`IF-EXT-005`：支付下单协同与结果回写。
+- `IF-REV-006`：账单核销与收费状态更新。
+
+### 落地边界
+
+- **已落地**：渠道下单、支付回调、账单核销主链路。
+- **部分落地**：失败补偿策略部分由支付平台与人工复核协同处理。
+- **文档先行**：复杂营销组合支付与分账能力暂不宣称为已实现。
+
 <a id="mod-cs-004"></a>

 ## CS-004 电子发票服务
@ -115,6 +190,18 @@ retrieval_priority: P1
 - `biz_cust_invoice`
 - `biz_invoice_taxrate`

+### 接口映射
+
+- `IF-CS-004`：客户侧发票申请与状态查询。
+- `IF-EXT-006`、`IF-EXT-007`：发票开具协同与结果回写。
+- `IF-REV-008`：营收侧发票主流程协同。
+
+### 落地边界
+
+- **已落地**：发票申请、开票信息校验、开票结果回写。
+- **部分落地**：红冲、补开等复杂票据后处理以发票服务能力为主。
+- **文档先行**：多税率拆票、批量异步重试等高级策略仅保留设计语义。
+
 <a id="mod-cs-005"></a>

 ## CS-005 营业网点服务
@ -129,6 +216,21 @@ retrieval_priority: P1
 2. 网点服务以查询与引导为主，不在本模块中虚构额外业务实体表。
 3. 与 CS-006 业务办理服务协同，支持从网点查询跳转到线上办理。

+### 核心数据
+
+- `biz_outlets`
+- `biz_business_types`
+
+### 接口映射
+
+- `IF-CS-005`：网点信息、可办事项、预约入口查询。
+
+### 落地边界
+
+- **已落地**：网点查询与办事引导能力。
+- **部分落地**：预约排队等能力可能由外部排队系统承载。
+- **文档先行**：导航路线规划与实时客流预测仅保留扩展方向。
+
 <a id="mod-cs-006"></a>

 ## CS-006 业务办理服务
@ -143,6 +245,23 @@ retrieval_priority: P1
 2. 办理结果与客户资料、工单状态、报装或表务流程联动更新。
 3. 触达通知通过 `SYS-010` 完成结果通知。

+### 核心数据
+
+- `biz_process`
+- `biz_process_transfer`
+- `biz_content_attach`
+
+### 接口映射
+
+- `IF-CS-006`：办理申请提交、进度查询、补件上传。
+- `IF-EXT-008`：办理结果通知协同。
+
+### 落地边界
+
+- **已落地**：办理申请、进度查询、补件与状态联动。
+- **部分落地**：复杂跨部门并行审批流程依赖后端流程引擎配置。
+- **文档先行**：智能预审与自动分单规则暂不表述为已实现能力。
+
 <a id="mod-cs-007"></a>

 ## CS-007 柜面扫码支付
@ -151,6 +270,17 @@ retrieval_priority: P1

 支持营业厅柜台二维码收款、票据关联、结果回传，是柜台收费场景对线上支付能力的补充入口。

+### 业务流程
+
+```mermaid
+flowchart TD
+    A[柜面发起扫码收款] --> B[生成支付订单]
+    B --> C[客户扫码支付]
+    C --> D[接收支付结果回写]
+    D --> E[更新账单核销状态]
+    E --> F[打印或展示收费凭证]
+```
+
 ### 关键设计

 1. 柜面扫码支付与 REV-003 营业收费统一核销口径。
@ -163,3 +293,14 @@ retrieval_priority: P1
 - `bk_transaction`
 - `bk_transaction_callback`

+### 接口映射
+
+- `IF-CS-007`：柜面扫码支付订单创建与结果回写。
+- `IF-EXT-004`、`IF-EXT-005`：支付渠道协同。
+- `IF-REV-006`：收费核销与账单状态更新。
+
+### 落地边界
+
+- **已落地**：柜面扫码收款、支付回写、账单核销协同。
+- **部分落地**：柜台班结与对账汇总由营收后台统一统计。
+- **文档先行**：多终端并发收款冲突治理保留为后续优化方向。