Continental-AG/conti-docs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add initial reference document in Word format with structured headings and content

Browse Source
This commit is contained in:
Guangfei.Zhao
2026-08-24 18:46:37 +08:00
parent 70c5cef4e1
commit d43d33c3cd
197 changed files with 9230 additions and 3754 deletions
Download Patch File Download Diff File Expand all files Collapse all files
prd/modules/README.md
+151
View File
@@ -0,0 +1,151 @@
# PRD 模块需求文件
本目录把 [`../Continental-Retail-APP-PRD.md`](../Continental-Retail-APP-PRD.md) 第 4 章的 14 个业务模块拆成独立文件，便于分模块维护、分模块评审、分模块指派负责人。
## ⚠️ 同步契约（必读）
| 项 | 约定 |
| --- | --- |
| **谁为准** | **本目录为准。** 需求变更一律改本目录的模块文件 |
| 主文件第 4 章 | **不要直接编辑，改动会在下次回灌时被覆盖。** 已于 2026-08 完成首次回灌，主文件升至 V1.1，与本目录一致 |
| 主文件其余章节 | 第 1–3、5–10 章与附录 A/B/C/D 仍以主文件为准，本目录只做**只读引用** |
| 回灌方式 | 跑 `scripts/build_prd.py backfill`（先 `--dry-run` 看差异）。范围仅限各模块文件 `## 附：本模块归拢信息` 分界线**以上**的部分，分界线以下不回灌 |
| 回灌时机 | 需要出 Word / PDF 交付件时，或模块文件改完想让主文件跟上时。脚本是幂等的，多跑无害 |
| 派生数据 | 附录 D.2、头部规模声明、附录 C.3 首句、10.2 图例计数、各模块头部信息表的「需求条数」行——**这五处由脚本重算，不要手改** |
| 仍需手工维护 | **附录 A / B / C.2 与 10.2 的条目正文**。脚本只校验数目对不对（对不上会在 `verify` 里报出来），不替你写条目 |
| 编号规则 | 沿用主文件 1.7：`REQ-<模块码>-<3位序号>`，**一经分配不再复用**，删除时保留编号并标注「已废弃」 |
| 待确认标记 | 沿用 `TODO(REQ-xxx-nnn)`，**禁止使用 `tbd`** |
三条命令，都用仓库根目录的 `.venv`（自带 pandoc 与 Pillow，系统 Python 跑不了）：
```bash
.venv/Scripts/python.exe scripts/build_prd.py verify # 只校验，不改文件
.venv/Scripts/python.exe scripts/build_prd.py backfill --dry-run # 看回灌会改什么
.venv/Scripts/python.exe scripts/build_prd.py backfill # 回灌，末尾自动跑 verify
.venv/Scripts/python.exe scripts/build_prd.py export # 压缩配图 + 出 docx
```
`export` 做两件事：把 `prd/` 下三个图源目录的 PNG **就地**调色板量化（首次跑：**23.4 MB → 9.7 MB**；已量化的跳过，日后新加的截图会自动压掉，免得仓库又长胖），再用 pandoc 生成 `prd/Continental-Retail-APP-PRD.docx`（约 9.8 MB，含全部 173 张图与三级目录）。**PDF 不由脚本生成**——pandoc 转 PDF 要 LaTeX，本机没装，用 Word 打开 docx 另存。
> 量化是有损的（256 色）。这批截图是扁平 UI 图，实测中位 RMS 误差 0.82/255、最差一张 3.10（延保「扫描车牌」，取景框里有实拍照片），文字与控件肉眼无差别。**原图都在 git 历史里**，要取回某张跑 `git checkout <commit> -- prd/xxx.png`。
版式模板是 `scripts/reference.docx`，首次 `export` 时自动生成（pandoc 默认模板 + 把东亚字体钉成标题「微软雅黑」/ 正文「等线」，否则换台机器 Word 会自挑中文字体）。**已存在就原样使用**，在 Word 里改过的版式不会被脚本覆盖；想重置就删掉它再跑一次。
> 主文件与本目录并存，漂移风险真实存在。降低漂移的唯一手段是：**只在本目录改需求**，主文件第 4 章当只读产物看待。
## 模块索引
「需求 / 待确认」两列是**本目录各模块文件的现值**；括号内是逐图核对前的 2026-08 基线，两者的差额就是核图时新增的条目。**主文件[附录 D.2](../Continental-Retail-APP-PRD.md#d2-模块级追溯汇总) 与[第 10.2 节](../Continental-Retail-APP-PRD.md#102-待确认项清单)已按括号外的现值同步**，下次改需求后须再同步一次。
| 序 | 文件 | 章节 | 模块码 | 粒度 | 需求 | 待确认 | 完成度 | 图 | 现状承载系统 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 01 | [账号登录](./01-LGN-账号登录.md) | 4.1 | LGN | 14 维 | 11 | 7 | 36% | 1 | O2O（用户主数据） |
| 02 | [APP 首页与导航](./02-HOM-APP首页与导航.md) | 4.2 | HOM | 14 维 | 16（15） | 11（10） | 31% | 5 | ROOS / O2O / 延保 |
| 03 | [销售](./03-SAL-销售.md) | 4.3 | SAL | 14 维 | 37（14） | 11（6） | 70% | 28 | F6 + O2O |
| 04 | [提醒](./04-RMD-提醒.md) | 4.4 | RMD | 14 维 | 7 | 2 | 71% | 3 | F6（PC 端，App 内嵌 H5） |
| 05 | [延保](./05-WTY-延保.md) | 4.5 | WTY | 14 维 | 38（10） | 6（5） | 84% | 43 | 延保门店端 |
| 06 | [采购](./06-PUR-采购.md) | 4.6 | PUR | 14 维 | 18（13） | 12（7） | 33% | 9 | ROOS（马牌）+ F6（非马牌） |
| 07 | [库存](./07-INV-库存.md) | 4.7 | INV | 6 维 | 11（7） | 9（5） | 18% | 12 | O2O + ROOS |
| 08 | [我的 / 个人中心](./08-MIN-我的.md) | 4.8 | MIN | 6 维 | 20（6） | 13（6） | 35% | 16 | ROOS + O2O + 延保 |
| 09 | [门店管理](./09-STM-门店管理.md) | 4.9 | STM | 6 维 | 14（7） | 13（6） | 7% | 14 | O2O |
| 10 | [财务与对账](./10-FIN-财务与对账.md) | 4.10 | FIN | 6 维 | 14（7） | 12（5） | 14% | 11 | O2O + ROOS |
| 11 | [返利中心](./11-RBT-返利中心.md) | 4.11 | RBT | 6 维 | 11（6） | 7（3） | 36% | 10 | O2O + 延保 |
| 12 | [经营业绩与报表](./12-PRF-经营业绩与报表.md) | 4.12 | PRF | 6 维 | 9（6） | 7（4） | 22% | 8 | O2O + ROOS + 延保 |
| 13 | [营销与会员](./13-MKT-营销与会员.md) | 4.13 | MKT | 6 维 | 8（5） | 7（4） | 13% | 7 | O2O |
| 14 | [福利兑换（MSIP）](./14-MSP-福利兑换.md) | 4.14 | MSP | 6 维 | 8（6） | 4 | 50% | 0 | MSIP |
| | **合计** | | | | **222**（121） | **121**（74） | **46%** | **167** | |
模块索引。完成度 =（需求条数 − 待确认）÷ 需求条数。
> **括号内的 D.2 基线曾有一处错**：STM 行原记「需求条数 8」，但当时 4.9 正文只有 REQ-STM-001~007 共 7 条且无空号，上表括号内按实际的 7 记（故基线合计 121 实为 120）。根因是 V1.0 的 STM-006/007 挂错了 TODO 编号，已在回灌时连同 FIN、MKT 的同类错位一并修正，主文件 10.2 各行标注了原编号以便追溯。详见 [09-STM 的附-5](./09-STM-门店管理.md#附-5-本次拆分新增发现)。
>
> 逐图核对把需求条数从 121 提到 222（+101）、待确认从 74 提到 121（+47 净增：新增 49 条、裁决关闭 2 条）。**增量全部来自逐张核看 167 张配图**：现状截图里实际存在、而 2026-08 版正文一字未提的机制（如门店本地化服务项目价目表、消费券额度按补货率累积、延保生效的两段式确认、扫码出库的「去延保」分支），以及设计稿与现状互相冲突、必须裁决的口径。各模块文件的 `附-5` 逐条列明了触发证据。
**需求依据**（主文件 4.0 模块总览）：LGN 业务需求 + 设计稿；HOM 业务需求 + 设计稿 3 版；SAL 业务需求 + 原型图 + O2O 订单截图；RMD 业务需求 + 原型图；WTY 业务需求 + 延保小程序 44 张截图；PUR 业务需求 + ROOS 截图 + 设计稿；INV / FIN / RBT / PRF / MKT 现状截图反推；MIN / STM 业务需求 + 现状截图 + 设计稿；MSP 现状入口 + 设计稿 + 业务确认（页面待补）。
> 第 4 章共 173 张图中的 167 张归属这 14 个模块；其余 6 张分布在主文件 2.7 现状小程序功能全景（4 张）与 6.1 / 6.2 后台管理（2 张），不在本目录范围内。
## 模块文件结构
每个文件以 `## 附：本模块归拢信息` 为分界线：
- **分界线以上** —— 1:1 对应主文件 4.x 正文，保留原有小节编号（如 `4.7.1`）。回灌主文件时只处理这部分。
- **分界线以下** —— 从主文件其它章节归拢来的本模块分片：业务数据字典（附录 A）、权限矩阵（附录 B）、待确认项（10.2）、配图清单（附录 C）。这部分**不回灌**，主文件的附录仍是全局视图。
> **文件标题必须与主文件 4.x 标题逐字一致**（如 `# 4.9 门店管理`，**不要**加模块码写成 `# 4.9 门店管理（STM）`）。两个原因：一是回灌时只需把 `#` 降为 `##`，不改标题文字；二是主文件附录 C 用 `[4.9 门店管理](#49-门店管理)` 这类锚点自引，各模块之间的互链也复用同一套 slug —— 标题一改，**上百条链接同时静默失效**。模块码写在下方信息表的「模块码」行和文件名里，标题里不重复。
## 配图说明规范（四段式）
每张图正下方接四段，段名加粗 + 破折号，与主文件 1.8.1 的写法一致：
```markdown
![现状-O2O 扫码入库](../mini-program-images/O2O/扫码入库.png)
**页面内容** —— 一句话：这是什么页、有哪些主要区块
**关键交互** —— ①控件 → 结果 ②控件 → 结果
**可用角色** —— 店长 …；技工 …
**需求关联** —— REQ-xxx-nnn、REQ-xxx-nnn
```
硬性规则：
1. **页面内容只写一句话**，说清「这是什么页 + 有哪些主要区块」即可，**不逐个控件描述文案、颜色、位置**。一句写不下的，说明细节该放到别处：交互过程写进「关键交互」，结论与推断写进图下的 `>` 引用块，冗长的取值清单与脏数据明细写进 `附-5` 的证据列 —— **不在图下重复**。
2. **写之前必须实际打开该 PNG**，不得据文件名臆造。空态、测试数据、已选中的筛选值属于会误导读者的关键信息，须用一句点明（如「**本图为空态**，记录行字段无法确认」）。看不清或无法判断的写「本图无法确认 xxx」，**不猜**。
3. **关键交互**用 ①②③ 编号，每条写成「控件 → 结果」。纯静态展示图写「无交互，仅作内容佐证」。
4. **可用角色**沿用主文件附录 B 图例：✅ 完整权限 · 🔸 受限 · ⚙️ 需店长/后台显式授权 · ✗ 无权限 · ❓ 待确认。有待确认的就地带 `TODO(REQ-xxx-nnn)`。
5. **需求关联**列 REQ 编号并锚到本文件的业务规则小节；不支撑任何编号需求的写「—（仅作现状佐证）」。
6. 图片一律用**相对路径**引用，从本目录出发要多一层 `../`：`../app-design-images/`、`../mini-program-images/{O2O,ROOS,Warranty}/`、`../images/`。
## 链接写法
| 目标 | 写法 |
| --- | --- |
| 本模块内小节 | `[4.7.4](#474-业务规则)` |
| 其它模块整节 | `[4.9 门店管理](./09-STM-门店管理.md#49-门店管理)` |
| 其它模块内小节 | `[4.2.5](./02-HOM-APP首页与导航.md#425-导航收敛与角色化配置)` |
| 主文件其它章节 / 附录 | `[痛点 2.3](../Continental-Retail-APP-PRD.md#23-进销存--erp-数据)` |
锚点按 GitHub 规则从标题生成：转小写、去掉标点（含中文全角 `（）、，`）、空格换 `-`。所以 `## 4.14 福利兑换（MSIP）` 的锚点是 `#414-福利兑换msip`，`## 2.3 进销存 / ERP 数据` 的是 `#23-进销存--erp-数据`（`/` 被删除后留下两个空格，成为双连字符）。**写完链接要点开验证**——锚点错了不会报错，只是不跳转。
主文件本身仍须满足 CLAUDE.md 的「自包含、只用锚点、不引用其它 md」约束；本目录是仓库内部工作副本，不受该约束限制。
## 状态与待办
**14 个模块文件已全部建成**，167 张配图逐张核看后写了四段式说明，主文件 10.2 与附录 A/B/C 的本模块分片已归拢到各文件的 `附-1` ~ `附-4`，逐图核对中新增的需求与待确认项记在各文件的 `附-5`。**2026-08 已完成首次回灌**，主文件升至 V1.1。
拆分完成后跑过的一致性核对（结果均为通过）：
| 核对项 | 结果 |
| --- | --- |
| 图片路径可解析 | 167 处引用，磁盘缺失 **0** |
| 图不丢 | 主文件第 4 章 167 张 ∩ 本目录 167 张，双向差集**均为空** |
| 每张图都有说明 | 缺四段式说明的图 **0**（拆分前的基线是 173 张里 94 张裸图） |
| REQ 不丢不重 | 主文件第 4 章 121 个编号，每个**恰好**归属一个模块文件；本目录现有 222 个 |
| 待确认项 | 主文件 10.2 共 97 条 = 第 4 章 74 条 + 章外 23 条；74 条**全部**落到对应模块的 `附-3`，本目录现为 121 条 |
| 链接可达 | 全仓 md 共 1784 条带锚点/跨文件链接，失效 **0** |
> 最后一项曾一次性失效 139 条：模块文件的一级标题当初写成了 `# 4.9 门店管理（STM）`，多出的模块码改变了 slug，而上百条互链是按主文件的 `## 4.9 门店管理` 生成的。已把 14 个 H1 全部对齐主文件标题，另修正 `#d2-模块覆盖度`→`#d2-模块级追溯汇总`（主文件实为「D.2 模块级追溯汇总」）等 10 处失效目标。规则见上文[模块文件结构](#模块文件结构)与[链接写法](#链接写法)。
回灌后在**主文件一侧**另跑过一轮（结果均为通过）：
| 核对项 | 结果 |
| --- | --- |
| 图片路径可解析 | 173 处引用，磁盘缺失 **0** |
| 站内锚点 | 1289 条，失效 **0**；正文无跨文件链接（满足 CLAUDE.md 的自包含约束，`modules/` 的指引只写在 HTML 注释里） |
| REQ 编号 | 全文 296 个不同编号，正文重复定义 **0** |
| TODO ↔ 10.2 | 正文 146 个 `TODO(...)` 与 10.2 的 144 条 + 2 条已关闭**双向对齐**，无孤儿 |
| 计数三处联动 | 头部规模声明 / 附录 C / 附录 D.2 / 10.2 均为 296 需求、144 待确认、173 图、44 表；D.2 逐行累加与合计行一致，各行完成度按公式复算无误 |
| `tbd` | 全文 **0**（唯一一处出现在 1.8 的「本文档不使用 `tbd`」这句禁令本身） |
待办：
- [x] **回灌主文件**（2026-08 完成）—— 需求条数 121 → 222、待确认 74 → 121（全文 97 → 144、296 条需求），主文件的规模声明、附录 B / C / D.2 与第 10.2 节已同步，第 4 章开头加了指向本目录的 HTML 横幅
- [x] **构建脚本 [`scripts/build_prd.py`](../../scripts/build_prd.py)**（2026-08 完成）—— `backfill` / `verify` / `export` 三个子命令，见上文[同步契约](#-同步契约必读)。首次机器回灌顺带修好了主文件里 10 处被早前一次编辑误删字符的句子（模块文件留着完好原文）
- [x] **`prd-export/` 已删除**（2026-08）—— 那是一整套与 `prd/` 一模一样的图片副本，仓库白背 31 MB。改成配图就地量化，docx 直接出到 `prd/Continental-Retail-APP-PRD.docx`
- [ ] **PDF 待重出**：原 `prd-export/Continental-Retail-APP-PRD.pdf` 是 2026-08-21 的 V1.0 版，内容已过时，已随目录删除。脚本不生成 PDF，须用 Word 打开新 docx 另存到 `prd/Continental-Retail-APP-PRD.pdf`
- [ ] 主文件附录 A 缺 INV / RBT / MKT / MSP 四个模块的字段清单，需业务补（已记为 `TODO(REQ-INV-011)` 等，见各文件 `附-1`）
- [ ] 补采两张截图：延保「待补充装车视频」tab（附录 C 第 6、7 行指向的两个文件截图像素一致，该 tab 实际未拍到）、O2O「交易手续费说明」的抖音团购段（被底部按钮遮挡）
- [ ] 人工抽查：用 VS Code 的 Markdown 预览打开任一模块文件，确认图片经 `../` 正常渲染、四段式说明与图上所见一致（路径已机器校验，渲染效果需肉眼确认）