张胜宇
bc61d5c579
## 为什么做这一步 权威文档 74 份此前**只在本机**，评审者 clone 分支后看不到任何设计文档；而仓库里那两份同名目录 是 **2026-09-16 之前的过期副本，连文件名都是旧的**（无体系编号）。本次按「**权威覆盖过期**」入库。 ## 入库内容 | 目录 | 文件数 | 体积 | 说明 | |---|---|---|---| | `客服agent/` | 24 | 0.77 MB | `D2.1`~`D2.6` 对外交付四件套 + 演示脚本/答辩报告 + `_build` 构建工具 | | `开发文档/` | 50 | 2.16 MB | `D1.x` 索引与决策、`D3.x` 方案、`D4.x` 清除与重构留痕、`D5.x` 业务流程、`D6.x` 业务事实基座、`D7.x` 交付物、`D8.x` 规范 | **旧的过期副本整体移除**（`客服Agent执行Todolist.md` → `D2.1-客服Agent执行Todolist.md` 之类 的改名 + 新增 `D2.5`/`D2.6`），入库后目录内容与权威副本**逐文件一致（零差异，已复核）**。 ## 入库前的安全扫描（必须留痕） - 扫描规则：`sk-` 类密钥 / `Bearer` 长串 / `password=`、`api_key=` 赋值 / 会话中出现过的两把明文 key 片段。 - 结论：**真实密钥只出现在 `.env`**（已被 `.gitignore` 命中，未入库）；`.env.example` 与 `config/risk.env.example` 只有**空占位**。 - 文档内唯一命中是 `D3.1` 里一处**截断的示例 JWT**（`Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`）， 末尾带省略号，是接口文档的示意值，**不是可用凭据**。
38 KiB
开发文档规整方案与开发前待决事项
体系编号：
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 |
| 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.mdv5.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，内容：
- 权威链（A1—A5）+ 更新顺序（改需求 → 改 Todolist → 改计划 → 改知识库）
- 每份文档的状态标注（现行 / 底稿 / 已完成 / 已作废 / 待确认）
- "开工只读这 5 份"的粗体提示
- 引用约定：文档内互引一律用「文档编号 + 章节」，不用文件路径
另做 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.mdv5.1 /D3.1-客服Agent需求开发文档与设计方案.htmlv2.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 🔴 两处对原判断的纠正（由「先只读核查」抓出）
- 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。 ⇒ 教训：清权限前必须按权限码反查消费者，不能按「模块已删」推断。 - 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 份全部保留：每一份要么是开发输入，要么被上游依据表或编号引用。两处最关键的发现：
- 🔴
D7.1-需求文档.html不是「过期旧版可删」——它是 TodolistF-07未完成任务的直接操作对象（修复其 24 个失效目录锚点）。删了该任务无法完成。 - 🔴
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-01T-11）· D2.4 §12.1（T-01T-10 / Q-01Q-13）· D1.4 §8（C-01C-06）· D1.1 §8（D-5D-8）· D1.3 §4（D-1D-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 与各节标题逐一对账，不能只看正文是否通顺。