# 开发文档规整方案与开发前待决事项

> **体系编号**：`D1.3`　·　域：一、治理与索引　·　编号体系见 `D1.1` §4.0

> **编号**：CS-DOC-2026-014　|　**日期**：2026-09-17　|　**性质**：**只读盘点 + 规整方案**（物理动作待你确认后执行）
> **盘点范围**：`开发文档\`（49 份）+ `客服agent\`（4 份）= **53 份**（不含 `ai\`、`_build\` 脚手架）

---

## 0. 一句话结论

53 份里**真正需要开工读的只有 5 份**；其余是「取证底稿 / 清除记录 / 过程文档 / 早期系统文档」四类。其中 **1 份整份作废、9 份使命已完成**。
另外核出 **4 个必须处理的问题**——其中最急的一条是：**四份交付文档的品牌标题至今仍是「XX科技」**。

---

## 1. 盘点结果

### 1.1 现行权威 —— 开工只读这 5 份

| # | 文档 | 规模 | 作用 |
|---|---|---|---|
| **A1** | `客服agent\D2.1-客服Agent执行Todolist.md` **v5.2** | 440 行 | 🔴 **唯一开工入口**。52 项 / 7 批次（A—G）/ 12 步关键路径 / 2 组会签 / 12 条完工判据 |
| **A2** | `客服agent\D2.2-客服Agent需求文档.html` **v2.4** | 1064 行 | 对外需求：FR-CS-001~048 + NFR-CS-001~021 全量、身份与鉴权模型、验收标准 |
| **A3** | `客服agent\D2.3-客服Agent开发计划.html` **v1.0** | 869 行 | 前置条件、测试环境就位（G-00）、会签流程、门禁、交付物 |
| **A4** | `客服agent\D2.4-客服Agent知识库设计方案.html` **v1.2** | 1615 行 | 三集合 / 三档可见性 / 8 模块 / 7 步入库 8 步检索 / 8 项决策 |
| **A5** | `开发文档\D3.3-访客与角色分离的鉴权方案建议-2026-09-16.md`（CS-AUTH-2026-011） | 322 行 | 鉴权专项：四方案对比、三条不变量、甲乙时序 |

> **已验证**：A1 与 `开发文档\D3.4-客服Agent重构Todolist.md` v5.1 的**任务编号完全一致**（52 个、7 批次），说明 v5.2 是 v5.1 的**收敛版而非分叉**；A2 与 v2.3 的 **FR 48 条 / NFR 21 条完全一致**。

### 1.2 取证底稿 —— 内部复核时查，不开工时读

| 文档 | 规模 | 为什么保留 |
|---|---|---|
| `开发文档\D3.1-客服Agent需求开发文档与设计方案.html` v2.3 | 4366 行 | A2 的**完整版**：逐条需求都带证据引用与推导过程 |
| `开发文档\D3.2-知识库设计方案.html` | 2374 行 | A4 的**完整版**：含被收敛掉的备选方案与否决理由 |
| `开发文档\D3.4-客服Agent重构Todolist.md` v5.1 | 606 行 | A1 的前身，含更细的 DoD 描述 |
| `开发文档\D4.1-客服Agent重构报告-2026-09-16.md`（CS-REFACTOR-2026-010） | 416 行 | **清除了什么、缺什么、按什么顺序装回去**的逐项取证；§9 已拍板记录 |
| `开发文档\D4.5-投顾模块清除执行报告-2026-09-17.md`（CS-PURGE-2026-013） | 171 行 | 投顾清除的验证数据 + 恢复方式 |
| `开发文档\D4.3-客服模块清除执行报告-2026-09-16.md`（CS-PURGE-2026-008） | 156 行 | 客服形态A清除的验证数据 |

### 1.3 知识源 —— 13 份（已于 2026-09-17 统一为「南方基金」）

| 目录 | 份数 | 内容 |
|---|---|---|
| `公司信息\` | 4 | `D6.1.1-南方基金-企业信息.md`、`D6.1.2-南方基金-高频问答对.md/.txt`（64 组，**档位 public 54 / registered 10**，判据见其 §四）、`D6.1.4-公司新人指南.md` |
| `公司业务\` | 6 | 个人理财产品手册、企业金融服务方案、高净值客户服务规范、用户测试数据 3 份 |
| `金融政策\` | 3 | 适当性管理指南、反洗钱手册、销售管理办法 |
| `用户研判规则\` | 4 | 风险画像规则、可疑交易识别、用户信息数据示例 ×2 |

### 1.4 过程文档 —— 使命已完成（9 份）

| 文档 | 状态 |
|---|---|
| `待决事项清单.md`（19 项） | ✅ 19 项全部已定 |
| `客服Agent模块重构方案与Todolist.md` v2.0 | ⛔ 被 v5.x 取代 |
| `客服Agent双角色方案决策对比.md` | ✅ 决策已定，结论已进 A2 |
| `五项决策建议与新增证据.md` | ✅ 5 项决策已并入报告 §9 |
| `项目信息补充表.md`（567 行） | ✅ 信息已并入需求文档 |
| `Todolist编写就绪度评估与补充清单.md` | ✅ 评估已完成 |
| `客服Agent清除与重构方案（底座层与业务层分层）.md` | ⛔ 被 CS-REFACTOR-2026-010 取代 |
| `客服重建启动前落点复核与建议-2026-09-16.md`（CS-009） | ⛔ 被 CS-010 取代 |
| `客服模块清理执行记录-2026-09-16.md` | ✅ 执行记录，可并入 008 |

### 1.5 早期系统级文档 —— 状态待确认（6 份）

| 文档 | 日期 | 我的判断 |
|---|---|---|
| `D7.1-需求文档.html`（2499 行） | 07-17 | 项目**整体**需求（"智能财富管家系统 — 项目开发需求文档"），非客服专项。**可能仍有效，但品牌是 XX科技、且可能含投顾内容** → 待你定 |
| `D7.2-功能设计文档.html`（1752 行） | 07-20 | 系统级 Agent 功能设计（含"2. 智能客服 Agent"）。同上 |
| `D7.3-记忆架构设计.html`（1662 行） | 07-20 | 标题是「AI Agent 记忆架构设计指南」——像**通用教材**而非本项目文档 |
| `D7.4-开发引导.md`（328 行） | 07-17 | 开发实施引导，可能已被 A3 覆盖 |
| `D7.5-答辩须知.md`（14 行） | 06-26 | 答辩要求，**仍有效** |
| `CLAUDE.md`（177 行） | 06-05 | 项目语言规范，**仍有效** |

### 1.6 已归档 / 整份作废（2 份）

| 文档 | 处理 |
|---|---|
| `归档-访客鉴权与访客分层讨论-已清除-2026-09-16.md` | 已归档，保留 |
| 🔴 `客服与投顾模块重构前代码清理建议-2026-09-15.md` | **整份作废**：它是「死代码清理建议」，**投顾条目已因投顾整体清除而失效**；客服侧条目也已随形态A清除完成 |

---

## 2. 四个必须处理的问题

### 🔴 P-1（最急）四份交付文档的品牌标题仍是「XX科技」

| 位置 | 现状 |
|---|---|
| `<title>` | `XX科技·智能财富管家系统 — 智能客服 Agent 需求文档` 等 4 份**全部** |
| `<h1 id="...">` | `XX科技·智能财富管家系统智能客服 Agent …` |
| sidebar-brand / topbar | 同样继承自原文档 |

**成因**：我产出 `客服agent\` 四份时，从原文档**抽取版式外壳**（head/title/sidebar）再灌新正文——外壳里的品牌名一并带了过来。
**影响**：与你 09-17 定的「全部以南方基金为例」**口径冲突**；答辩时打开就是打脸。
**修法**：4 份各改 `<title>` + `<h1>` + 品牌位（约 12 处替换），零风险。

### ⚠️ P-2 两套文档并行，没有权威声明

`客服agent\`（4 份新版）与 `开发文档\`（v2.3 / v5.1 / 知识库完整版）内容**不完全相同**（收敛版 vs 完整版），但**没有任何一份文档说明谁为准、各自什么用途**。后来者（或三个月后的你）会不知道读哪份。

### ⚠️ P-3 文档交叉引用密集，**不能随便移动文件**

多份文档按 **完整路径 + 行号** 互引（如 `_cs_purge_backup/app/service/agent/implementations/customer_service.py:193-206`、`§2.5`、`docs/33 §1.2`）。贸然把文档挪进子目录，会让这些引用**批量失效**。⇒ **规整不能靠"搬文件"，要靠"一份索引 + 状态标注"。**

### ⚠️ P-4 早期系统文档（6 份）状态不明

见 §1.5。它们用 XX科技 品牌、可能含投顾内容，但又是"项目整体"层面的文档——**删了怕缺、留着怕误导**。

---

## 3. 规整方案（推荐方案：零破坏）

### 方案甲 ✅ 推荐 —— 加索引、不动文件

**新建 `开发文档\D1.1-文档索引与权威声明.md`**，内容：
1. **权威链**（A1—A5）+ **更新顺序**（改需求 → 改 Todolist → 改计划 → 改知识库）
2. **每份文档的状态标注**（现行 / 底稿 / 已完成 / 已作废 / 待确认）
3. **"开工只读这 5 份"的粗体提示**
4. **引用约定**：文档内互引一律用「文档编号 + 章节」，不用文件路径

**另做 3 件小事**：
- 把 `客服与投顾模块重构前代码清理建议-2026-09-15.md` 移入 `开发文档\归档\`
- 把 `归档-访客鉴权与访客分层讨论-已清除-2026-09-16.md` 移入 `开发文档\归档\`
- 修 P-1 的品牌（4 份交付文档）

**收益**：零引用破坏；任何人打开 `00-文档索引` 就知道从哪读。**成本**：约 10 分钟。

### 方案乙 —— 物理分层（不推荐）

建 `现行\` `底稿\` `归档\` 三个子目录，把文档按类搬进去。
**问题**：§P-3 的交叉引用会批量失效；且你之前提交到远程的 `zsy_developcc` 分支里已有 `开发文档\` 的旧路径，两边会不一致。

### 方案丙 —— 合并同类项（不推荐）

把 9 份过程文档物理合并成 1 份「决策过程留档」。
**问题**：这些文档**都有编号**（CS-REFACTOR-2026-00X / CS-PURGE-2026-0XX），报告与需求文档里**按编号引用**它们。合并后编号无处安放，引用全断。

---

## 4. 开发前待决事项

### 4.1 🔴 只有你能定的（4 项）

| # | 事项 | 为什么必须你定 | 我的建议 | 不定的后果 |
|---|---|---|---|---|
| **D-1** | **四份交付文档品牌改成「南方基金」？** | 这是**对外口径**变更，且会改到你已提交的分支 | **改**。改成 `南方基金·智能服务系统 — 智能客服 Agent …`；同时决定系统名是否保留"智能财富管家系统" | 答辩打开就是 XX科技，与知识源（已统一南方基金）自相矛盾 |
| **D-2** | **早期 6 份系统文档怎么办？** | 只有你知道它们是否还有用 | `D7.5-答辩须知.md` + `CLAUDE.md` **保留**；`D7.1-需求文档.html` + `D7.2-功能设计文档.html` **保留但标为「系统级、品牌待同步」**；`D7.3-记忆架构设计.html` **移入归档**（像通用教材）；`D7.4-开发引导.md` 标为「已被开发计划覆盖」 | 25 万字里混着过期口径，评审翻到会问 |
| **D-3** | **`admin` 角色的 15 条投顾域权限要不要一并清？** | 上一轮的遗留；超管角色，我不敢擅动 | **清**。投顾功能已全删，这些权限码在任何角色上都不会被调用；但为稳妥可先只读核查 `sys_role_permission` | 库里留着 15 条指向已删功能的权限，审计时是瑕疵 |
| **D-4** | **代码侧的品牌残留要不要一起改？** | 不在"四个知识源目录"里，但你昨天说的是"全部以南方基金为例" | **改**。至少三处：`B-01` 入库门禁的品牌白名单（`南方财富`+`南方基金`+`nanfangwm.com` → `南方基金`+`nffund.com`）、`promotion.js:29` 的 `南方基金管理有限公司`（少"股份"）、`governance.py:47` 的热线常量 | 门禁会**误杀**新知识源（白名单里没有 `nffund.com` 就报占位符错误） |

### 4.2 已授权、只差发令（可立即执行，不需要你再决策）

| # | 事项 | 说明 |
|---|---|---|
| **E-1** | **G-00 测试环境就位** | 已拍板"装"。⚠️ 且我 09-17 实测发现**本机 MySQL 3306 + Redis 6379 都在跑、`jr_agent` 库可直连**（账号 `root`/`123456`）→ 环境比预想的好，可以开始 |
| **E-2** | **A-03 配置快照实测**（含 T-11 白名单核查） | 同样因为库可连，现在能升级为强证据 |
| **E-3** | **T-01 / T-02 / T-03 / T-10 连库实测** | Embedding 实际维度、三集合是否存在及 Schema、RAG 基础设施签名、`fin_knowledge_meta` 等表是否已建 |
| **E-4** | **`seed_test_rbac.py` 重跑** | 库里 `customer` 角色的 8 条投顾权限我已用等价 SQL 撤销，但脚本与库的**最终一致性**建议重跑确认 |

### 4.3 记录在案、不影响开工（3 项）

- `docs\` 约 30 处投顾残余引用 + `AGENTS.md:163` 引用已删发布脚本
- 本地 `origin/qyqy_develop` 陈旧（`8643ad1`，远程实际 `74b7d00`）——你本机跑一次 `git fetch origin` 即可
- `开发文档\` 已复制进 `group_fqcd_jr\开发文档\` 并推送（若只想让它待在 `zsy_developcc`，可删工作区副本）

---

## 5. 建议的执行顺序

```
① 你定 D-1~D-4（4 项，一次回一句话即可）
② 我执行方案甲（加索引 + 归档 2 份 + 修品牌）        ← 约 10 分钟，零破坏
③ 我执行 D-4 的代码侧品牌改判（3 处）                ← 与 ① 同批
④ 开始 G-00（测试环境就位）→ 批次 A                  ← 真正开工
```

> **③ 与 ④ 之间有依赖**：`B-01` 的品牌白名单若不同步改，重跑入库时新知识源会被门禁拦下（这是 D-4 必须先做的实际原因）。

---

## 6. 执行记录（2026-09-17 · 用户指令「把作废的文档都删除掉」）

### 6.1 已归档 **14 份**（**移动**方式，可随时恢复）

| 类别 | 份数 | 文档 |
|---|---|---|
| 整份作废 | 1 | `客服与投顾模块重构前代码清理建议-2026-09-15.md` |
| 过程文档（使命已完成） | 9 | `待决事项清单.md`、`客服Agent模块重构方案与Todolist.md`、`客服Agent双角色方案决策对比.md`、`五项决策建议与新增证据.md`、`项目信息补充表.md`、`Todolist编写就绪度评估与补充清单.md`、`客服Agent清除与重构方案（底座层与业务层分层）.md`、`客服重建启动前落点复核与建议-2026-09-16.md`、`客服模块清理执行记录-2026-09-16.md` |
| 已归档件 | 1 | `归档-访客鉴权与访客分层讨论-已清除-2026-09-16.md` |
| 🔴 **旧版残留**（见 §6.2） | 3 | `公司信息\南方财富-企业信息.md`、`公司信息\南方财富-高频问答对.md`、`公司信息\南方财富-高频问答对.txt` |

**归档位置**：`D:\桌面\金融\_archived_docs_20260917\`（保持原文件名；仓库副本的同类文件在 `_repo_copy\` 下）。

### 6.2 🔴 顺带核出的新问题（**新增 P-5**）

**「重命名」在本沙箱里实际是「复制」而非「移动」** —— `公司信息\` 下曾**同时存在**：
- `南方财富-*` **3 份（旧版）**：内容全旧（域名 `nanfangwm.com`、热线 `400-826-9518`、`has_new=False`）
- `南方基金-*` **3 份（新版）**：已完整替换

⇒ 已清掉旧版 3 份。**教训：本沙箱下"移动/重命名"必须用「目标存在 + 源消失」双条件复核**，不能只看命令返回 0。

**另有 5 份文档正文仍含「南方财富」**（属**内容过期**，不是文件重复）：`D3.4-客服Agent重构Todolist.md` v5.1、`D4.1-客服Agent重构报告-2026-09-16.md`、`D3.1-客服Agent需求开发文档与设计方案.html`、`D3.2-知识库设计方案.html`，以及本方案文档（后者属正常引用说明）。⇒ **建议并入 D-4 一起改**。

### 6.3 清理后规模

| 位置 | 清理前 | 清理后 |
|---|---|---|
| `开发文档\` | 53 个文件 | **40 个**（根目录 **17**；4 个知识源目录共 **17**；`ai\` 脚手架 6） |
| `group_fqcd_jr\开发文档\`（仓库副本） | 42 个文件 | **39 个**（同步清理，**未重新推送** — 远程 `zsy_developcc` 仍是 09-17 11:38 的快照） |

> **根目录剩余 17 份**（实测复核过）：现行权威 4 份（`D3.4-客服Agent重构Todolist.md` v5.1 / `D3.1-客服Agent需求开发文档与设计方案.html` v2.3 / `D3.2-知识库设计方案.html` / `D3.3-访客与角色分离的鉴权方案建议-2026-09-16.md`）+ 支撑底稿 2 份（`D4.1-客服Agent重构报告-2026-09-16.md` / `D5.1-业务流程-MVP版-最终交付-2026-09-15.md`）+ 清除执行记录 4 份（客服影响面清单 / 客服执行报告 / 投顾范围清单 / 投顾执行报告）+ 早期系统文档 6 份（`CLAUDE.md` / `D7.5-答辩须知.md` / `D7.4-开发引导.md` / `D7.2-功能设计文档.html` / `D7.3-记忆架构设计.html` / `D7.1-需求文档.html`）＋ 本方案文档 1 份。合计 17 份。**结构已可一眼看清。**

---

## 7. 执行记录（2026-09-17 · 第二轮：**结构整理**）

> **本轮指令**：「请按照你此前给出的建议进行改写，并在此基础上同步整理我的开发文档，确保整体结构清晰、分类合理、层级分明、命名统一、条理井然，便于后续查阅与维护。整理时请列出你做了哪些调整以及调整的理由。」
> **执行范围**：落实 §3 **方案甲**（加索引、不动文件）+ §2 **P-1** 复核 + 内容口径改写（另见 `CS-CONTENT-2026-016`）。

### 7.1 一句话结论

**新增 1 份索引（`D1.1-文档索引与权威声明.md`）+ 前置 1 条命名规则（`00-` 前缀）；未移动、未改任何既有文件名。**
理由：本区文档按「完整路径 + 行号」互引且已推送远程，**搬文件 = 批量断链**（§2 P-3）。故「整理」落在**索引、分类、标注、规范**四处，而非物理分层。

### 7.2 结构层调整（4 项）

| # | 调整 | 具体动作 | 理由 | 影响范围 |
|---|---|---|---|---|
| **S-1** | **新建索引与权威声明** | 新增 `开发文档\D1.1-文档索引与权威声明.md`（CS-DOC-2026-017）：开工只读集、权威链与更新顺序、8 类分类总览、46 个文件位全量清单、命名规范、状态口径、引用约定、待决事项 | 直接解 §2 **P-2**（两套文档并行无权威声明）；用 `00-` 前缀使其在任意排序下**置顶** | 新增 1 份文件；不改动任何既有文件 |
| **S-2** | **明确「收敛版 vs 完整版」关系** | 在索引 §0/§4 显式声明：`客服agent\`（A1—A4）为**对外交付 + 唯一开工入口**，`开发文档\` 同名旧版为**取证底稿**；**冲突时以 `客服agent\` 为准** | 解 P-2 的另一半：此前只知"两份不完全相同"，不知谁为准 | 仅文档声明，无文件变动 |
| **S-3** | **建立 8 类分类体系** | Ⅰ 对外交付 / Ⅱ 区内现行权威 / Ⅲ 内部复核底稿 / Ⅳ 清除执行记录 / Ⅴ 本次整改工作文档 / Ⅵ 公司事实与知识源 / Ⅶ 早期系统文档 / Ⅷ AI 协作脚手架 | 原盘点只有 7 类且把「现行权威」与「底稿」混列。**按"什么时候读"分类**比按"文件形态"分类更可用 | 索引 §3/§4 |
| **S-4** | **命名规范成文** | 索引 §5 写入 6 条文件名规则（R1—R6）、7 类文档编号格式、统一头部元数据块、5 档状态口径 | 原无任何成文命名规范，"命名统一"只能靠记忆；下一步新增文档才有共同格式 | 索引 §5；**既有文件不改名**（见 §7.3） |

### 7.3 命名偏差：**7 项全部判定「暂不改名」（零改名）**

| # | 偏差 | 决策 | 理由 |
|---|---|---|---|
| N-1 | 13 份带日期后缀、5 份不带 | 不改 | 均为已互引文件，改名即断链；「带日期 = 一次性成果 / 不带 = 长期文档」已是可读的隐含规则 |
| N-2 | `D6.4.3-用户信息数据示例.md` 与 `.txt` 同名并存 | 不改 | 设计如此：`.md` 人读画像、`.txt` 纯文本摘要，服务不同消费方 |
| N-3 | `D3.1-客服Agent需求开发文档与设计方案.html` 一名含两类文档 | 不改 | 已被 A2、CS-REFACTOR-2026-010 及多个 HTML 按名称引用 |
| N-4 | `ai\D8.3-01_READING_RULES.md` 等下划线大写风格 | 不改 | 脚手架文件，遵循 AI 工具约定，与交付文档本非同类 |
| N-5 | 早期编号 `JR-*` 与新 `NF-*` 并存 | 不改 | 重编号会改动 `理财产品销售管理办法` 等文件的自引编号；新文档统一用 `NF-*`，旧编号自然淘汰 |
| N-6 | 4 个知识源目录名粒度不完全对齐 | 不改 | 已与 `tools\build_knowledge_chunks.py` 扫描路径 + A4 知识库集合划分绑定，改名会**同时**打断文档与代码两侧引用 |
| N-7 | 无「索引置顶」规则 | **新增** | 建立唯一规则：仅索引用 `00-` 前缀 |

### 7.4 引用约定成文（2 项）

| # | 调整 | 理由 |
|---|---|---|
| **S-5** | 新文档互引**一律用「文档编号 + 章节」**，不用行号 | 行号随编辑必然漂移（本区已有 `重构报告:209` 这类行号引用因改版失效的先例） |
| **S-6** | 明确**旧值可出现的三类上下文**（修订说明 / 禁止清单 / 变更说明），且须紧邻新值 | 解决「全仓扫旧值 = 0」这条硬指标与「变更说明必须记录旧值」的**天然矛盾**——否则扫描永远无法归零 |

### 7.5 内容口径改写（本轮同批完成，详见 `CS-CONTENT-2026-016`）

| # | 文件 | 主要改动 | 理由 |
|---|---|---|---|
| 1 | `公司信息\D6.1.3-南方基金-高频问答对.txt` | 重写为 V2.0，与已更正的 `.md` **逐条对齐**（64 组）；身份由「代销机构」→「公募基金管理人 + 官方直销」；AUM 2,200 亿 → 1.43 万亿；56 家网点 → 6 分公司 + 6 客户服务中心；杭州滨江 → 1998 深圳；基金大厦 26 层 → 32—42 楼；删保险经纪 / 证券投资咨询 / 私募登记等**无资格**的资质 | `.md` 已改，`.txt` 未改 ⇒ **同源两版数据打架**，而 `.txt` 正是知识库导入源，必须先修 |
| 2 | `用户研判规则\D6.4.3-用户信息数据示例.md` | 重写为 V2.0：客户持仓拆分为「本公司持仓」与「其他机构持有」；删「保本理财」（资管新规后已退市）；补 C—R 可购范围；新增三分法与合规边界标签 | 原文件把银行理财 / 保险 / 私募并列为我司可售产品，与身份口径冲突 |
| 3 | `公司业务\用户测试数据\D6.5.1-客户A-高净值.md` | 重写为 V2.0：**删除 AI 主动推介大额终身寿险 / 保险金信托 / 私募产品 / 定增 / 个股**的全部内容，改为**边界声明 + 本公司专户/公募替代方案**；真实机构名与股票名全部替换为〔示例〕 | 🔴 **最重风险项**：本公司无保险中介资格、不销售私募，原文属**无资格推介**，且用了真实机构名 |
| 4 | `公司业务\用户测试数据\D6.5.2-客户B-普通投资者.md` | 重写为 V2.0：资产表加「持有机构」列；「R1 级保本理财」→「现金管理类产品」；「网点」→「客户服务中心」；客服电话占位符 `400-XXX-XXXX` → `400-889-8899`；产品适配分析改为「是否本公司产品 × 是否在 C1 可购范围」二维判定 | 收敛多处口径残留与占位符 |
| 5 | `用户研判规则\D6.4.1-投资者风险画像研判规则.md` | 「线下（营业网点）」→「线下（客户服务中心）」 | 单点口径残留 |
| 6 | `金融政策\D6.3.2-个人投资者适当性管理指南.md` | 「营业网点内的指定区域」→「客户服务中心内的指定区域」 | 同上 |
| 7 | `公司业务\D6.2.1-个人理财产品手册.md`（母本）+ `group_fqcd_jr\knowledge\product\` 同名副本 | §1.4 产品名 `南方科技先锋股票 A` → `南方智能科技股票 A`；删除指向**真实产品**的免责说明，改为通用虚构声明 | ①产品名含旧品牌子串 `南方科技`，扫描误报；②原说明引入真实产品代码，违反「所有数据均需虚构」 |

### 7.6 复核结果（P-1）

| 项 | 结论 |
|---|---|
| **P-1 四份交付文档品牌标题** | ✅ **已解决**（前轮已改）。实测 `<title>` = `南方基金·智能服务系统 — 智能客服 Agent 需求文档` 等；`客服agent\` 四份中 `XX科技` / `南方财富` **仅出现在「禁止清单 / 修订记录」上下文**，属 §7.4 S-6 允许的情形 |
| **旧值全仓扫描** | `开发文档\` 内 `南方科技` / `XX科技` / `400-XXX` / `保本理财` / `私行` 命中**全部落在**「修订说明 / 禁止清单 / 变更说明 / 术语对照」上下文；两处真残留已修（§7.5 第 5、6 项） |
| **`group_fqcd_jr\knowledge\`** | 4 个 `.md` 命中均为**术语说明或已修复**；`_chunks.jsonl` 的 312 处命中为**派生件**，待重新灌库（见 §7.7） |

### 7.7 未做与遗留

| # | 事项 | 原因 |
|---|---|---|
| 1 | **`_chunks.jsonl` 未重生成** | 它是 `knowledge\**` 的**派生件**，须由 `tools\build_knowledge_chunks.py` 重新灌库；属代码侧动作，按「不编写任何代码」暂缓 |
| 2 | **`开发文档\` 的仓库副本（`group_fqcd_jr\开发文档\`）未同步** | 同属推送动作，暂缓 |
| 3 | **早期 6 份系统文档未改品牌** | 状态为「待确认」（§2 P-4 / 索引 §7 D-2），**不宜单方面改写 25 万字早期文档**；其中 `D7.1-需求文档.html`（11 处）、`D7.2-功能设计文档.html`（5 处）仍含旧品牌值 |
| 4 | **前端 24 份 + 风控 Agent 5 处 `南方财富`** | 索引 §7 D-5，代码/前端侧，暂缓 |
| 5 | **D-3 / D-4 决策** | 等用户拍板（索引 §7） |

### 7.8 本轮产出与规模

| 位置 | 动作 | 份数 |
|---|---|---|
| `开发文档\` | **新增** | +1（`D1.1-文档索引与权威声明.md`） |
| `开发文档\` | **改写**（内容口径） | 6（§7.5 第 1—6 项） |
| `开发文档\` | **重命名 / 移动** | **0**（零破坏） |
| `group_fqcd_jr\knowledge\` | **改写**（对齐母本） | 1（§7.5 第 7 项） |
| `开发文档\` | 结果规模 | **43 份**（42 + 索引） |

---

## 8. 执行记录（2026-09-17 · 第三轮：D-2 / D-3 / D-4）

> **用户指令**：「除了 D5，其他全都按照你建议的来。」
> **完整执行记录与验证数据见 `D1.1-文档索引与权威声明.md` §7**（此处只留索引与规模）。

| 项 | 内容 | 结果 |
|---|---|---|
| **D-2** | 早期系统文档：`D7.4-开发引导.md` / `D7.1-需求文档.html` / `D7.2-功能设计文档.html` **加状态标注**；`D7.3-记忆架构设计.html` ~~归档~~ → **撤销归档、移回原位**；`CLAUDE.md` / `D7.5-答辩须知.md` 保留 | ✅ 6 份全处置（1 项事后纠正，见下） |
| **D-3** | `admin` 角色投顾域权限：删 **16 条**（9020-9026、9029-9034、9057-9059），**保留 5 条**（9027/9028、9041-9043，有存活消费者）；同步改 `seed_test_rbac.py` | ✅ admin 59→**43**；残留 **0** |
| **D-4** | 代码侧品牌 3 处：`governance.py:47` 热线、`seed_compliance_baseline.py` 2 条话术、`promotion.js:29` 补「股份」 | ✅ 3 处；`py_compile` 全过 |
| **D-5** | 前端品牌面 | ⏭ **按用户指令跳过** |

### 8.1 🔴 两处对原判断的纠正（由「先只读核查」抓出）

1. **D-3 的原判断错了**：我原先写「投顾功能已全删，这些权限码**在任何角色上都不会被调用**」。实测 `profile_governance_service.py` 与 `product_governance_monitor_service.py` **仍存活并在用** `profile-governance:read/review`、`product-governance:read/review/sync`。且 `AuthorizationService.require(..., admin=True)` 的语义是「**追加**要求 admin 角色」而非「admin 旁路权限码」（`authorization_service.py:31-34`）⇒ 若照原判断「清 15 条」会**批量 403**。
   ⇒ **教训**：清权限前必须按**权限码**反查消费者，不能按「模块已删」推断。
2. **D-4 的「品牌白名单」在代码里不存在**：`tools/build_knowledge_chunks.py` 全文只有 `assert_no_duplicate_contents` 一个守卫；所谓「四查 / 品牌白名单（含 `南方财富`+`nanfangwm.com`）」只写在**文档**（重构报告 `:209`、Todolist B-01）里 —— 即 **G-01「文档声称已实现、代码未实现」**的又一实例。⇒ **无可改之代码**，正确白名单值（`南方基金` + `nffund.com`）转为 **D-7** 待 B-01 实现时使用。

### 8.2 新增规模

| 位置 | 动作 | 数量 |
|---|---|---|
| `开发文档\` | 加状态标注 | 3（`D7.4-开发引导.md` / `D7.1-需求文档.html` / `D7.2-功能设计文档.html`） |
| `开发文档\` | ~~归档~~ **撤销归档** | 0（`D7.3-记忆架构设计.html` 曾归档，经引用核查后移回原位） |
| `group_fqcd_jr\` | 代码改动 | 3（`governance.py` / `seed_compliance_baseline.py` / `seed_test_rbac.py` / `promotion.js`） |
| 数据库 | 删角色绑定 | 16 行（`sys_role_permission`，admin） |
| 备份 | 新增 | 3（`d2_20260917\`、`d3_20260917_rbac_before.sql`、`archived_docs_20260917.zip`） |

---

## 9. 可删性核查（2026-09-17 · 第四轮）—— **结论：无可删文档**

> **用户指令**：「把我这个文件夹里你觉得没用的文档都清除，只需要留下协助开发的文档。」
> **完整证据链见 `D1.1-文档索引与权威声明.md` §10。** 此处只留结论。

**逐项核查后，`开发文档\` 43 份全部保留**：每一份要么是开发输入，要么被上游依据表或编号引用。两处最关键的发现：

1. 🔴 `D7.1-需求文档.html` **不是**「过期旧版可删」——它是 Todolist **`F-07` 未完成任务的直接操作对象**（修复其 24 个失效目录锚点）。删了该任务无法完成。
2. 🔴 `D7.3-记忆架构设计.html` **不是**「与项目无引用关系的通用教材」——A2/A4 的 §0.2 上游依据表**均把它列为依据**（§6.2 → `FR-CS-042` 的裁决理由）。⇒ **已撤销 §8 的归档处置，移回原位**（`开发文档\_archive\` 目录已删）。

### 9.1 教训（写进长期记忆）

**判断文档"有没有用"不能凭体裁，必须按文件名反查引用。** 「像通用教材」「像一次性过程记录」都不构成删除依据；本区文档按「**文件名 + 编号**」互引，且**不在任何 git 仓库内**（删了没有 revert）。

### 9.2 「只留协助开发」的正确实现方式

不是删文件，而是：**开工只读 5 份（索引 §2）+ 8 类分类与状态标注（索引 §3/§4）**。本区的 43 份里，真正「开工必读」的只有 5 份，其余已按「什么时候读」分层标注——这已经达成了「一看就知道读哪份」的目标，且零破坏。

---

## 10. 统一编号体系落地（2026-09-17 · 第五轮）

> **用户指令**：「为每份文档分配统一的编号规则，按逻辑顺序排列，确保编号在目录、文档标题及交叉引用中保持一致，并整理分类与层级结构。」

### 10.1 编号方案

**`D<域>.<序>`**（域 6 向下再一级 `D<域>.<子域>.<序>`），域号即**逻辑顺序＝阅读优先级**：

| 域 | 名称 | 份数 |
|---|---|---|
| D1 | 一、治理与索引 | 4 |
| D2 | 二、对外交付 | 4 |
| D3 | 三、现行权威·完整版与专项 | 4 |
| D4 | 四、清除与重建留痕 | 5 |
| D5 | 五、业务流程基线 | 1 |
| D6 | 六、公司事实与知识源 | 17 |
| D7 | 七、早期系统文档 | 5 |
| D8 | 八、AI 协作规则 | 7 |
| | **合计** | **47** |

### 10.2 三处一致（用户要求的「目录 / 标题 / 交叉引用」）

| 位置 | 落地方式 | 完成 |
|---|---|---|
| **目录** | 索引新增 **§3 文档层级与编号域** + **§4.0 编号规则与全量编号总表（47 行，按编号排序）**；§0/§1/§2 补编号列 | ✅ |
| **文档标题** | 44 份可注入文档在标题正下方加「体系编号」行：`.md` 用引用块（36 份）、`.html` 用状态条（5 份）、交付文档用 `doc-meta` 行（3 份） | ✅ 47/47 校验通过 |
| **交叉引用** | 索引 §9 第 1 条升为**三级优先**（体系编号 → 既有业务编号 → 文件名）；新增第 5 条「编号↔文件名双向可解析」 | ✅ |

### 10.3 ⚠️ 第五轮的关键决策 —— **第六轮已推翻，保留供追溯**

第五轮曾判「**编号不进文件名**」，理由是：① 知识源文件名被入库脚本 `SOURCES` 字典引用；② 交付文档是按文件名引用上游的生成件。

**该判断在第六轮被推翻**（用户明确要求「文件名带号」）。推翻的依据是把两件事**拆开**：

| 第五轮的顾虑 | 实际情况 | 结论 |
|---|---|---|
| 「知识源文件名被 `SOURCES` 引用」 | `SOURCES` 的键指向 **`group_fqcd_jr\knowledge\**` 的镜像副本**，**不是** `开发文档\` 的母本 | ⇒ **母本可改名；镜像不改名** 即无冲突 |
| 「交付文档是生成件」 | 生成件由 `_build\_spec_*.json` 驱动，其中 `out_file` 与引用可**随迁移脚本同批改写** | ⇒ 改名后重新生成仍自洽 |

⇒ 第六轮最终决策见 **§11**。

### 10.4 落点与可重复性

| 项 | 内容 |
|---|---|
| 注入脚本 | `.workbuddy\_inject_docno.py`（幂等：判据＝文件是否已含「体系编号」） |
| 校验脚本 | `.workbuddy\_verify_docno.py`（**47/47 通过**；并验 `高频问答对.txt` 仍为 64 行 × 1 tab） |
| 交付文档的**持久**落点 | 编号同时写入 `_build\_spec_requirements/_plan/_kb.json` 的 `meta` 首行、`_build\_shell_mid.html`（D3.1 的 shell）⇒ **重新生成后编号仍在** |
| `.txt` 例外（3 份） | `D6.1.3-南方基金-高频问答对.txt` / `D6.4.4-用户信息数据示例.txt` / `ai\D8.2-README.txt` **不注入**：前者必须保持「1 行 1 制表符」，加行即破坏知识库导入 |
| 两套编号并存 | 体系编号 `D…`（前向检索/排序）与既有业务编号 `CS-* / NF-* / YH-* / JR-*`（历史留痕/互引）**并存互补**，后者不可重编（已散落在报告、Todolist 与代码注释里） |

---

## 11. 文件名带编号迁移（2026-09-17 · 第六轮）

> **用户指令**：「文件名带号 —— 我需要区分每个文档是用来干什么的。」
> ⇒ **推翻**第五轮「编号不进文件名」的判断（原因见 §10.3 两行拆解表）。

### 11.1 文件名规则（索引 §5 R7 已同步改写）

**`<编号>-<原描述名>.<扩展名>`**，例：`D2.2-客服Agent需求文档.html`、`D6.1.1-南方基金-企业信息.md`。

**编号的域号本身就是用途** —— 看到文件名立即知道它干什么、排第几：

| 域 | 用途 |
|---|---|
| D1 | 治理与索引（体系自身：索引 / 事实基座 / 规整方案 / 变更说明） |
| D2 | **对外交付**（开工必读的 4 份） |
| D3 | 现行权威·完整版与专项（含鉴权专项） |
| D4 | 清除与重建留痕（含重建指南） |
| D5 | 业务流程基线 |
| D6 | 公司事实与知识源（含测试数据） |
| D7 | 早期系统文档（旧版，待确认） |
| D8 | AI 协作规则 |

### 11.2 执行结果

| 项 | 结果 |
|---|---|
| **重命名** | **46 份**（`开发文档\` 42 + `客服agent\` 4）；全部「copy2 + 字节数校验 + 删源」三步，**成功 46 / 失败 0** |
| 🔴 **唯一例外** | **`CLAUDE.md` 保留原名** —— AI 工具按此**固定名**读取规则文件，改名会**静默失效**；其编号 `D8.1` 只写在文件内与索引 §4.0 总表 |
| **引用迁移** | **55 个文件**被改写（正文引用 / HTML `<a href>` / 依据表 / `_build\_spec_*.json` 的 `out_file` / `_build\_body_*.html`） |
| **注入行改编号制** | `.md` 36 个 + `.html` 5 个 —— 统一为「编号体系见 `D1.1` §4.0」，**不再写路径**（下次再改名也不会失效） |
| **备份** | `.workbuddy\backups\rename_20260917_devdocs.zip`（64 文件 / 812,649 B） |
| 脚本 | 迁移 `.workbuddy\_rename_docs_with_no.py`；复核 `.workbuddy\_verify_rename.py` |

### 11.3 🔴 为什么不改 `knowledge\**` 镜像 —— 这是本轮的关键区分

`tools/build_knowledge_chunks.py` 的 `SOURCES` 字典键指向的是 **`group_fqcd_jr\knowledge\**` 的镜像副本**（`company/企业信息.md`、`product/个人理财产品手册.md` 等），**不是** `开发文档\` 里的母本。

⇒ **母本改名不打断代码；只有镜像改名才会。** 故：**母本带编号，镜像保持原名**。两者的对应关系由索引 §4.0 总表维护（总表同时给出编号与相对路径）。

### 11.4 未同步（遗留）

| # | 事项 | 说明 |
|---|---|---|
| 1 | `group_fqcd_jr\开发文档\`（陈旧仓库副本，40 份） | 仍是**旧名 + 旧内容**，未同步；它本身已需整批重同步（见 D1.1 §8 的 **D-8**） |
| 2 | `group_fqcd_jr\客服agent\`（仓库副本 4 份 + `_build\`） | 同上 |
| 3 | `group_fqcd_jr\docs\**`、`_flows\**` 中对旧文件名的历史引用 | 属**历史记载**（描述的是当时的文档状态），**有意不改** |
| 4 | `客服agent\_build\` 内部的 `_body_*.html` / `_shell_*.html` 文件名 | 属**脚手架**（非文档），保持原名；其**内容**里的引用已随迁移更新 |

---

## 12. 决策登记册产出（2026-09-17 · 第七轮）

### 用户指令
「在正式开始开发之前，请梳理并列出所有仍需由我本人拍板决策的事项……请对每一项说明为何需要我决策、可选的方案及其权衡，并标明哪些是关键阻塞项、哪些可延后决定。」

### 交付物
🆕 `开发文档\D1.5-开发前决策清单与阻塞项-2026-09-17.md`（**CS-DOC-2026-018 v1.0**）—— 开工前 **唯一** 决策登记册。

| 项 | 内容 |
|---|---|
| 汇总来源 | `D2.2 §4.1`（`T-01`~`T-11`）· `D2.4 §12.1`（`T-01`~`T-10` / `Q-01`~`Q-13`）· `D1.4 §8`（`C-01`~`C-06`）· `D1.1 §8`（`D-5`~`D-8`）· `D1.3 §4`（`D-1`~`D-4` / `E-1`~`E-4`）· `D2.1 P-5`（会签门） |
| 规模 | **28 项** = P0 12 / P1 10 / P2 6；另列 **7 项需用户提供的输入或凭据** |
| 结构 | §0 阻塞分级与最晚决策时点 · §1 速览表（28 项）+ **§1.1 与原编号交叉映射** · §2 P0 逐项展开（为何必须你定 / 选项与权衡表 / 我的建议 / 不定则）· §3 P1 · §4 P2 · §5 需你提供的输入 · §6 已定项对照 · **§7 回填表** |
| 核心结论 | 12 项 P0 里 **只需在方案间二选一的仅 7 项**（`DEC-02`/`03`/`05`/`06`/`08`/`09`/`11`）；3 项是**授权实测**（＝`E-3`）、1 项是**发令**（＝`E-1`）、1 项是**交凭据**（`DEC-12`） |
| ⚠️ 建议最先拍板 | **`DEC-11` 交付节奏**（7 批次全做 vs 只做 P0 路径保演示）—— 它直接决定其余 27 项的取舍 |

### 同步动作（本轮）
| # | 动作 |
|---|---|
| 1 | **`D1.1` 升 v1.1**：盘点范围 43 → **44 份**；§4.0 总表补 `D1.5` 行（总表 **48 行**）；§4.5 补 `D1.5` 行；§4.7 标题改为「早期系统文档**处置**（6 项 · 含 `CLAUDE.md`＝`D8.1`）」以消除与 §3.2「D7＝5 份」的表面冲突；§6 结论改为「第三～五轮零改名，**第六轮已推翻**」；§8 加指路条（全部遗留并入 `D1.5`）；标题由 `# 00 · …` 改为 `# D1.1 · …` |
| 2 | **`D1.5` 自纠 2 处**：① §0「真正卡住开工的只有 5 项」与 §2 标题「P0 12 项」自相矛盾 ⇒ 改为 12 项并给出 **7（二选一）/ 3（授权实测）/ 1（发令）/ 1（交凭据）** 的拆分；② `DEC-22` / `DEC-23` 被误标为「G-00 就位 / 连库实测」⇒ 实为 `DEC-07` / `E-3`，已改正。另新增 **§1.1 交叉映射表**（`DEC-` ↔ `T-` / `Q-` / `C-` / `D-` / `E-` / `G-` / `P-`） |

### 🔴 教训（可复用）
**「清单类文档」产出后必须做一次自洽性回读。** 本次 `D1.5` 在生成时就把 §0 结论文（5 项）与 §2 明细标题（12 项）写得不一致，且两处编号归属串了（`DEC-22`/`DEC-23`）。
⇒ **同一份文档里最易漂移的是「计数」与「编号归属」两处** —— 写完必须**回读 §0 与各节标题逐一对账**，不能只看正文是否通顺。