DGJ2.0 业务文档详细化标准与完成度矩阵

1. 文档目标

这份文档不是业务说明，而是 01-48 全部业务文章的统一验收标准和施工进度表。后续每篇文章都必须回答五类问题：

1. 业务为什么存在，谁在什么条件下发起，完成后产生什么结果。
2. 请求从哪个入口进入，经过哪些 Controller、Service、Model、表和外部系统。
3. 主单、明细、库存、金额、状态和消息如何随步骤变化。
4. 失败时停在哪里，是否回滚、重试、幂等、补偿，应该怎样排查和回归。
5. 一次真实请求如何沿日志、业务键和表字段变化被完整还原，而不是只看到最终状态。

只有标题和文件清单、只有一段文字流程、只有表名没有读写关系，都不算“详细完成”。

2. 统一阅读脉络

每篇文档按下面的阅读顺序组织，让产品、前端、后端、测试和运维都能沿同一条线理解业务：

flowchart LR
    A[业务场景与参与角色] --> B[入口与请求参数]
    B --> C[Controller 与 Service 调用链]
    C --> D[表读写和数据快照]
    D --> E[状态/数量/金额变化]
    E --> F[MQ 与外部系统]
    F --> G[异常、幂等和补偿]
    G --> H[排查 SQL 与日志]
    H --> I[回归用例和改动风险]

3. 每篇文章的强制结构

业务文章应尽量包含以下章节；字典类文章可以合并章节，但不能省略对应信息。

4. 图示最低要求

普通业务链路至少包含两张图；有状态、有异步或跨系统时需要增加相应图。

不能用一张没有判断和数据变化的装饰图代替上述内容。图中的节点名称必须能在正文或代码中找到对应证据。

5. 接口表统一字段

每个接口表至少使用下面这些列：

接口请求必须区分：

• 业务显式传入字段，例如 orderId、qty、reason。
• 登录上下文字段，例如 JXCSID、JXCUID、JXCUNAME。
• 兼容别名，例如 activity_id 和 activityId。
• 金额和数量单位，例如元、分、基础单位、箱数。
• 服务端生成字段，例如单号、创建时间、来源类型，不要误写成前端必传。

6. 数据读写矩阵统一字段

涉及库存和额度时，还要说明：

• 查询维度是 sid、skuId、invId、仓库、货位还是批次。
• 展示值是实时计算、缓存、快照还是报表同步值。
• 增加和减少分别由什么交易类型产生。
• 并发保护使用行锁、条件更新、Redis 锁还是外部幂等。

7. 请求、日志与字段变化追踪标准

原有接口表和表读写矩阵回答“可能涉及什么”，追踪层必须进一步回答“这一笔请求实际走了哪条路、停在哪一步、数据在该步怎样变化”。每篇业务文章至少补齐下面三张表。

7.1 多入口请求链路表

要求：

• 同一业务存在 PC、App、Inner、OpenAPI、MQ、回调或定时任务时，必须分行列出，不能混成一个“入口”。
• 写清路径差异在哪里产生、在哪里重新汇合、是否共享事务和幂等键。
• HTTP 路径不能从方法名臆测；静态代码只能证明 Controller/方法时，路径标记为待网关确认。

7.2 日志证据矩阵

日志内容必须遵守：

• 只记录类/方法、路径、脱敏业务键、状态和错误摘要，不复制 Cookie、Token、手机号或客户隐私。
• 明确哪些代码确实写日志，哪些只能通过类名、业务单号和上下游日志反查；不能把建议新增的日志写成当前已有。
• 本地优先检查 application/logs/ 和模块日志；预发/生产按绝对时间、时区、服务、路径、request_id、业务单号查询。
• 当链路没有统一 traceId 时，必须列出可替代的关联键，例如 sid + billNo、srcOrderNo、payOrderNo、oa_number、msgId。

7.3 环节数据变更台账

要求：

• 每个关键步骤都列出读取条件和写入动作；不能只写一张“涉及表清单”。
• 状态必须写成 旧值 -> 新值；新增记录写“无 -> 新记录”；删除说明软删字段还是物理删除。
• 数量和金额写明增减方向、单位、分片和快照/实时口径。
• 标明数据库事务边界，以及事务外的 Provider、MQ、缓存、文件和报表同步副作用。
• 回查必须使用真实业务键和只读方法，不能以直接改表作为排查步骤。

7.4 一次请求的证据闭环

flowchart LR
    A["入口请求与登录上下文"] --> B["网关或 Controller 日志"]
    B --> C["Service 校验与事务"]
    C --> D["主表/明细/数量/金额变化"]
    D --> E["MQ、Provider、缓存或报表副作用"]
    E --> F["下游日志与回调"]
    F --> G["最终状态和只读回查"]
    G --> H{"证据是否连续"}
    H -->|"是"| I["形成可复现结论"]
    H -->|"否"| J["标记缺失日志或待环境确认"]

8. 证据可信度标记

9. 完成定义

一篇文章必须同时满足以下门槛才能标为“详细完成”：

• 有清晰的业务边界、角色、前置条件和最终结果。
• 核心业务接口覆盖完整，并给出真实字段和调用链。
• 至少有业务流程图和系统时序/数据流图；有状态时补状态图。
• 核心表全部进入读写矩阵，关联键能从入口追到下游。
• 状态、数量和金额口径引用实际枚举或代码计算。
• 主流程之外包含失败、并发、幂等、事务、超时和补偿。
• 排查步骤可以按真实单号或 ID 执行，SQL 默认只读且无真实敏感数据。
• 回归清单覆盖正常、异常、重复、权限和历史兼容场景。
• 本地 Markdown 渲染通过，Mermaid 可显示，站内搜索可检索。
• 多入口链路能够逐条区分，并说明汇合点和最终业务事实。
• 日志矩阵能从一个业务键找到入口、业务处理、下游和回调证据；没有日志的环节明确标记。
• 数据变更台账按步骤给出读表、写表、字段旧值到新值、事务和异步副作用。

10. 01-48 基础详细化完成度矩阵

状态说明：初稿 表示已有模块说明但未达到本页门槛；补强中 表示正在核对代码并重写；详细完成 表示已通过内容和渲染验收。

当前结果：01-48 共 48 篇文章均已达到上一版“详细完成”内容门槛，并通过本地 Markdown 渲染和线上知识地图回读。2026-07-22 起新增“多入口请求链路、日志证据矩阵、环节数据变更台账”三个追踪门槛；其补强进度单独记录在第 11 节，不能用基础详细化完成状态替代新门槛验收。表中的“有待确认项”是代码仓库无法独立证明的生产环境事实，例如线上 DDL/索引、网关鉴权、MQ binding、调度频率、真实调用流量和外部系统 SLA。

11. 文章级请求日志与数据变更补强进度

第 09 篇是规划文档，不作为业务请求链路验收对象。2026-07-22 文章级审计结果为 47/47 篇完成，但这只证明每篇文章至少有一组总追踪表，不是最终验收。

12. 子模块级独立追踪进度

用户进一步确认，要求不是“每篇文章整体完整”，而是文章内所有业务子模块各自拥有完整链路。现已从 47 篇业务文章拆出 416 个子模块，并增加第二层严格门槛：

• 每个子模块使用稳定 ID 和独立三级标题；
• 每个子模块独立说明入口/触发、请求/业务键、代码链路、读取事实、写入与字段变化、日志证据、异常与补偿；
• 查询类模块也要明确“只读、不写业务表”，不能为了凑字段伪造数据变化；
• 静态代码无法证明的生产日志、索引、调度和外部合同继续标记待环境确认；
• 最终以 python3 scripts/audit-dgj2-docs.py --require-submodules 全量通过为准。

当前进度以各业务子模块独立链路覆盖矩阵为准。在达到 416/416 前，本文不再使用“所有模块最终完成”的表述。

13. 原详细化分批执行顺序

为避免只补目录不补链路，按业务依赖分批完成：

1. 第一批：03 采购、04 销售、05 秒杀，先形成详细样板。
2. 第二批：01 系统、02 商品库存、06 移动商城、07 渠道、08 财务同步。
3. 第三批：10-18 地基字典和核心排查手册，与前两批相互校验。
4. 第四批：19-25 平台维护专题。
5. 第五批：26-40 仓储、财税、账号、运营和专项业务。
6. 第六批：41-48 报价、电池、首配、大客户、成本、地址、消息和 OpenAPI。

每完成一批，都要同步更新本矩阵、README 入口，执行本地渲染检查，再发布到统一知识地图。

13. 质量检查建议

内容检查重点不是行数，而是可追踪性：

rg -n "^## |```mermaid|接口总表|表读写矩阵|异常|幂等|回归|证据" \
  work/team-manage-local/interview_docs/12_DGJ2业务梳理/*.md

代码证据检查示例：

rg -n "function submitOrder|function submitInvPo|function addOutBound" \
  application/controllers application/service application/Services

rg -n "BILLSTATUS_|ORDER_STATUS_|SRC_ORDER_TYPE_" application/KzData/Enums

发布验收还要检查：文章列表能发现新文档、标题和表格可读、Mermaid 不显示源码、桌面和移动端无横向内容遮挡、站内搜索可按业务单号关键词和方法名找到文章。