AI260626/group_fqcd_jr
13
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
35109af96f86bf977faffaa4b406db0f84b03a84
group_fqcd_jr/docs/演示用/文档一致性审计报告-2026-09-14.md
T
lzf_0626 36c7a9d8d2 文档：审查报告入库 + 全量校对补注 
## 新入库（`docs/演示用/`）

- `代码库全面审查报告-2026-09-14.md`
- `代码修改方案-2026-09-14.md`
- `记忆系统排查报告-2026-09-14.md`
- `记忆系统修复文档-2026-09-14.md`
- `文档一致性审计报告-2026-09-14.md`
- `多Worker接入方案-2026-09-14.md`

## 全量校对（32 个既有文档 + `AGENTS.md`）

跨 39 个文件、**1125 insertions / 148 deletions**。

⚠️ **这批改动同样不是本次会话写的**。我抽样核对过性质：是**实质内容补充**而不是
格式/换行转换。例如 `docs/44-演示流程.md` 新增两条"2026-09-14 补注"：

- `启动金融Agent平台.bat` 只在**桌面**上，仓库里只有 `启动平台.bat` 这一份
  （两份由同一个 `tools/make_launcher_bat.py` 产出，改完 `start.ps1` 重跑它一起更新）；
- `advisor_t`(9020) 与 `offsite_t`(9006) **不在 `tools/seed_test_rbac.py` 的演示用户里**
  （那里只有 `cust_t`/`risk_t`/`admin_t`/`review_t` 四个），由 `grant_*.py` 系列创建，
  **重跑种子不会重建它们** —— 换机器时这两个账号登录失败，要先查 `sys_user` 有没有这两行，
  而不是查密码。

这两条都是对的地方，与我这一路踩到的现象一致（我确实用到了 `advisor_t`/`offsite_t`）。

**我没有逐字审阅全部 39 个文件**，只抽样确认了改动性质与规模。若其中有需要复核的段落，
请指明文件，我逐处核对。
2026-09-14 20:36:00 +08:00

22 KiB
Raw Blame History

全项目文档一致性审计报告

审计日期：2026-09-14 审计范围：仓库内 docs/ 下全部 110 份 .md（含 docs/演示用/、docs/风控业务演示文档/、docs/验收与审计/、docs/superpowers/） 比对基准：当前源码、配置、以及文档之间的相互一致性 审计方式：全量扫描 → 与代码逐条核对 → 修正 → 复核 重要说明：本次审计只修改文档，未改动任何业务代码。

一、审计方法与可信度说明

1.1 做法

  1. 全量盘点：Glob docs/**/*.md 得到 110 份文档。
  2. 并行审计：按主题分 6 批派只读子代理逐份核对，每份要求给出：
    • 结论（一致 / 过时 / 部分过时）
    • 文档侧证据（原文引用或行号）
    • 代码侧证据（文件:行号）
    • 明确列出"未核实"的部分
  3. 逐条自证：所有子代理给出的计数类结论都被我自己重新 Grep/Read 复核一遍。
  4. 修正：对确实需要同步的文档逐个编辑。
  5. 复核：改完再 grep 确认修改点已生效。

1.2 ⚠️ 一条重要提醒：子代理的计数不可直接采信

审计过程中，有子代理报告 tools/seed_test_rbac.py 的权限数为"72 条"、另一份报"66 条"。 我自己 Grep '^\s*\(9\d{3},' 数出来是 65 条（9001–9065），并以此为准。

结论：凡涉及"多少张表 / 多少条权限 / 多少个接口"这类计数的结论，本报告全部以我本人的 直接复算为准。使用时也建议照此办理——活体核验优于任何文档的记载。

1.3 最高优先级发现：AGENTS.md 自身就含过时信息

AGENTS.md 是"接手先读"的入口文件，它的错误会向所有读者传播，因此本次优先修正它。 三个子代理独立发现了同一批问题（互相印证）：

AGENTS.md 原话 实际 影响
"有四套页面" 实际 6 个角色目录 漏了 employee-advisor/、employee-operations/；且 employee-advisor/ 与 employee-console/ 是两个不同角色，不是改名
"9001-9046 号段" 实际 9001–9065，共 65 条 按旧号段写权限码会直接踩空
"架构师环境还有风控的 9 条白名单" 是该环境的 config_release 配置事实，不是代码常量 会有人在代码里找一个不存在的"9 条清单"

二、已更新的文档清单及主要变更

2.1 核心基线类（5 份）

文档 主要变更
AGENTS.md ① 前端章节："四套页面"→6 角色目录表（含 guest/customer/employee-console/employee-risk/employee-advisor/employee-operations），补 ⚠️ 说明 employee-advisor/ ≠ employee-console/、访客产品页已不走 mock-data.js 而走真实端点 P001/P002；② RBAC 章节：（9001-9046 号段）→（9001-9065 号段，共 65 条），新增号段演进段（逐段列明 17 个区间，并标注 9035-9040/4041-4046 从未存在）；③ "风控的 9 条白名单"→注明是环境 config_release 事实、本机发布脚本只发 4 条；④ TODO.md 行 （实为 51 张业务表）→（实为 89 张业务表）；⑤ 新增"画像有两个存储"条目（值在 MySQL、关系在 Neo4j，不一致时以 MySQL 为准，核验用 python tools/reconcile_graph.py）
docs/05-接口文档.md ① §8.4 工具表：4 个→5 行，search_knowledge 明确为正式名、query_knowledge 为别名，补超时（15s/10s），新增 ⚠️ 块说明"两者都要发布"及各业务线工具；② §18 完成判据：52 张表→90 张 = 89 张业务表 + alembic_version，附 49 → 52 → 89 修正链；③ §19 总目录：把 场外基金运营｜不属于当前系统 改为已落地（正确前缀 + 旧信封 + page/page_size 分页）；④ 新增 §19.1 补充接口段：场外基金、场外运营、访客令牌、客户入驻、推广物料、账户与交易看板，另注 any-of 权限语义与 RK001–RK015
docs/14-Agent组员统一接入说明书.md ① §8 工具表：错误的"4 个公共只读工具"→5 行正确表（search_knowledge 正式名 / query_knowledge 别名仅 visitor+customer），注册行号修正为 L248-388，补"两者都要发布"的 ⚠️，另加各业务线工具表（风控 3 / 投顾 5-6 / NL2SQL 1 / 探针 1）；② §14 当前状态：已注册两个业务 Agent→7 行表（类名 / agent_type / 说明），函数行号 L407-447，并说明注册顺序是追加式
docs/09-底座使用文档.md ① 表数：52 张，其中 51 张业务表→90 张 = 89 业务 + alembic_version，加分域表（场内 51 / 场外推广 17 / 投顾 21）与口径沿革说明（并澄清 audit_schema.py 的期望值是现算的，不是手写清单）；② Agent：两个→7 个表；③ §14 工具表整段重写——原文把 search_knowledge/query_knowledge 的主从关系写反、超时写成 8s、角色写错，均予更正
docs/02-数据库建表设计.md ① 头部：保留场内分项，但补 ⚠️ 说明全库现为 90 张 = 89 业务 + alembic_version（51+17+21），澄清"建成后总表数 51"是场内口径；② 标题 ## 4. 51 张表总览→## 4. 51 张表总览（场内口径） + ⚠️；③ 核验清单行同步说明

2.2 数据库与审计类（2 份）

文档 主要变更
docs/08-数据库结构审计基线.md 在原有 2026-09-11：51 → 68 更新块之后，追加 2026-09-14（第二次）：68 → 89：说明增量是投顾 21 张（advisor_*，迁移 20260910_advisor_* + 20260911_advisor_*）、登记文档待补、给出新公式（51+17+21=89，含版本表 90），并新增 "历史沿革"小节保存 51→68→89 的完整轨迹；空库表行 68 张业务表→89 张业务表
docs/28-场外与推广域数据表登记.md 头部"维护约定"改为：本文回答"场外/推广这 17 张从哪来"（不是"68 张从哪来"），并加 ⚠️ 块统一为 89=51+17+21 口径，明确17 张的登记内容本身无误、不改，投顾 21 张不在本文范围

2.3 流程与架构类（4 份）

文档 主要变更
docs/03-平台端到端流程文档.md ① §11 场外流程："未建设独立业务表前…"→前提已满足，补 ✅ 落地状态（17 表 + OffsiteFundAgent/PromotionMaterialAgent + 3 条路由 + 运营前端页 + 旧信封与 page 分页的差异提示），并补 ⚠️ 说明限额已从"金额"改为份额（10%/20%）；② §15 上线验收：四类 Agent→7 类并列全
docs/22-四大Agent流程实现拆解.md 头部加 "本文是开工前评估稿，多处结论已被实现推翻" 的 ⚠️ 块 + 4 行对照表（52 表→90；"无场外表"→已建 17；"必须新建场外一组表"→已成；金额口径→份额口径）；§5 正文就地标注已完成；核对规则行改为份额口径
docs/38-架构对齐-记忆与画像投影链路.md §三 加 "四个分歧均已收口"对照表（1 沿用主干 outbox；2 直接快照与候选复核并存；3 放弃 ZSY 那套客服 Agent、保留访客/候选/转人工；4 按"只取增量"处理）+ 补 neo4j_profile_projection.py 未被装配的警告（不要加回 __main__.py，否则又成两套图投影）；§四标注三步均已执行完成
docs/36-PR7合并记录与权限号段修正.md 头部加 口径修正块：40 条 / 45 条 / 38 条都是 2026-09-12 当日快照，现为 65 条 / 9001-9065，含号段归属表与"9035-9040、4041-4046 从未存在"的提示；§4、§5.2 就地标注

2.4 客服 / RAG / 前端类（4 份）

文档 主要变更
docs/18-知识检索接入方案.md ⚠️ 本次安全相关性最高的一处。① §4.2：删掉"集合内字段：knowledge_id/title/snippet/…"这段硬编码字段名（AGENTS.md 明令禁止），改为说明运行时探测（app/core/knowledge_schema.py：FIELD_CANDIDATES / REQUIRED_LOGICAL_FIELDS / SchemaCache），并加两套环境 schema 对照表+"Milvus 报 field doc_id not exist 会打挂另一套环境"的后果说明；② 步骤 2 的 search() 签名：去掉 output_fields 的硬编码默认值，改为必传参数 + 要点说明；③ 文件头补 3 条修正（工具正式名 search_knowledge；字段名不得硬编码；配置键名以 RuntimeConfigService 为准）
docs/41-客服Agent前端开发约束_v1.md ① §3 目录树整段替换为真实 6 角色树（逐页列出），附新旧对照表，注明 employee-advisor/ ≠ employee-console/、访客产品页已用 P001/P002；② §12 标题与全节：修掉 4 处不存在的 portal/customer/chat/ 引用（该目录从未落地），改为指向常驻浮窗 portal/common/customer-service-widget/，跳转方式改为浮窗 API window.CustomerServiceWidget.open({ prefill })，并说明会话上下文存 localStorage、无需返回 chat 页
docs/26-JWT密钥管理与轮换.md §8 标题 与"暂无登录接口"的关系→与登录接口的关系：补 ✅ 该缺口已闭环——POST /api/v1/auth/tokens（app/api/controllers/auth.py:24,32，接口编号 A034）已存在，服务端用私钥签发 RS256；并指出验签侧（JwtAuthenticator）与身份解析侧（IdentityService）确实未改，印证原文的预判；原文以删除线保留作设计记录
docs/12-基金行情数据底座接入开发计划.md 头部补 3 件原文完全没写的运行期事实：① MAX_QUOTE_AGE = 15 分钟（app/service/trade_service.py:79），超时后所有委托一律 503 FUND_QUOTE_UNAVAILABLE 且无自动刷新（app/core/errors.py:260-264），补刷命令 tools/sync_market_prices.py（立即生效、无需重启）；② 两个同步脚本未被登记（sync_market_prices.py / sync_nav_history.py）；③ query_fund_quote 15s 超时的算式依据（适配器最坏 8.2s × 1.8），并说明旧 5s 会永远撞工具超时；另补启动链与解释器门槛（必须是"版本≥3.11 且能 import 依赖"，不能只看 --version）

2.5 演示与验收类（5 份）

文档 主要变更
docs/44-演示流程.md ① 补注 启动金融Agent平台.bat 在桌面上、不在仓库里（仓库只有 启动平台.bat），说明两份由 tools/make_launcher_bat.py 统一生成，必须 GBK + CRLF + 无 BOM（缺任一条 cmd 解析错乱，实测报 AT 命令已弃用）；② 账号表下补 ⚠️：advisor_t(9020) 与 offsite_t(9006) 不在 RBAC 种子脚本里（种子只有 cust_t/risk_t/admin_t/review_t 四个），由 grant_*.py 系列创建，重跑种子不会重建；换机器登录失败先查 sys_user 有无该行
docs/42-场内基金知识条目草稿.md 头部补与 docs/43 的关系说明：两份是同主题不同版本（本文=草稿/取数 09-13，docs/43=入库版/取数 09-11），511810 的 0.2332 与 0.2661 两个都是真实 DWJZ、只差两天，入库前须先定用哪一天口径，以免知识库与 fin_product.current_nav 打架
docs/43-场内基金产品手册（知识库入库版）.md §二 产品清单下加 ⚠️ 交叉引用（同上），511810 行净值加 ⚠️ 标记，指向 docs/42 第 220-245 行的查证过程（含 DWJZ vs LJJZ vs 场内交易价的区别）
docs/验收与审计/phase1-acceptance-criteria.md 头部加 "本文是 2026-09-10 的缺口盘点快照、其后已全部补齐" + 7 条逐条订正表（其中第 3 条从 ⚠️"未达成/最大缺口"→✅ 已达成，Milvus 实测命中 score 0.7837；第 7 条从 🔴"规划缺口"→✅ 已达成），正文表头加"已过时"标注 —— 保留老师验收标准原文是本文的价值所在
docs/验收与审计/phase1-acceptance-report.md ① 第 2 条 52 张表→补 ⚠️ 现为 90 张口径；② 第 4 条与文件清单 query_knowledge→标注正式名为 search_knowledge（2 处）
docs/风控业务演示文档/08-数据库依赖与读写边界.md 读取表下补 ⚠️ 实现归属说明：把混在一起的表按 repository 划为三分（风控域 / 身份域 identity_repository.py / 场内交易域只读），并补 ✅ 风控红线 2 的实测复核：risk_repository.py 中没有任何 memory_unit/profile_snapshot 引用，画像只读 fin_customer_profile（8 处以上 join）

2.6 交接与过程产物类（8 份）

文档 主要变更
docs/superpowers/handoff/2026-09-11-交接文档-客服Agent与RAG收尾.md 头部加 4 条复核：① 分支指针 origin/NL_develop 已从 fb7d2f7 前进到 1f62aca（+10 提交），引用 SHA 前请自查；② 本文内部就有三个互相冲突的测试通过数（§0 的 1013 passed vs §4/§7 的 804 passed），说明是"合并前/后"两次快照被混写，以 §0 为准且当前基线一律重跑取数；③ §0 末尾列的"两个最大遗留"现已全部解决（memory_sync_outbox 消费者已接入 runtime.py L551/L523；Redis 密码已配）；④ 表数 52→90 口径。§4 与 §7 的正文数字就地加注
docs/superpowers/analysis/2026-09-10-现状与差距分析.md
…/2026-09-10-范围重定位与画像讨论记录.md
…/客服Agent专项设计方案-分析报告.md
docs/superpowers/plans/2026-09-10-客服Agent与RAG实施计划-qyqy版.md
…/2026-09-10-foundation-safe-migration.md
docs/superpowers/specs/2026-09-10-customer-service-agent-design.md
…/knowledge-retrieval-infra-design.md
…/foundation-safe-migration-design.md		 统一加 "🗂 过程产物 · 结论已归档" 批注，指明：判断当前进度请看 docs/验收与审计/phase1-acceptance-report.md，保留本文是为了留存"当时基于什么事实做了哪些判断"的证据链。（此前 8 份中只有 2 份有类似自述）。个别文件加了针对性提示：customer-service-agent-design 注明实现时工具名由 query_knowledge 改为 search_knowledge；knowledge-retrieval-infra-design 注明实现期有一处偏离（字段名改为运行时探测）

三、经核对无需修改的文档及理由

下列文档经逐条核对与当前实现一致，或已正确自我声明为历史/废弃，故未做修改：

3.1 已自我声明为历史 / 废弃（AGENTS.md 亦已列为"不要用来判断当前进度"）

文档 为什么不用改
docs/04 / docs/06 / docs/10 / docs/13 / docs/99 经 2026-09-11 评审决定保留（删除收益为零、保留成本同样为零），已列在 AGENTS.md 的 D 类"不要用来判断当前进度"；docs/99 自身头部已声明废弃并指向 docs/05。内容未核对、可能过期，属有意保留的历史参考
docs/01-通用Agent平台开发设计.md 只讲 MVC+S 分层约束、BaseAgent 骨架、AgentFactory 契约，不含 Agent 清单与表数，没有过时事实
docs/superpowers/ARCHIVE-2026-09-11-文档清理归档.md 自身就是"归档说明"，已标注被替代的章节

3.2 经核对与实现一致

文档 核对结论
docs/40-前端验收清单.md 实际是正确的：它已列出全部 6 个角色目录（含 employee-advisor），越权矩阵与实现相符；offsite_t/advisor_t 不在种子脚本一事它已有自述
docs/27-NL2SQL接入说明.md query_financial_data / 权限 financial:nl2sql:read / 角色 advisor,operator,admin,super_admin 与 bootstrap.py:301-308 逐字一致；且确认 NL2SQL 不在公共工具列表
docs/17-接口文档易懂版.md 自述"不替代 docs/05"，且内容一致
docs/19 / docs/24 / docs/25 / docs/29 / docs/31 / docs/37 / docs/39 逐条核对与实现一致（docs/24 仅有一条占位电话热线略显陈旧，无实质影响）
docs/21-风控Agent接入设计与实现说明.md 以风控为主题，"51 张"是其孤立环境自己的口径，与全库口径不冲突
docs/28 的登记内容本身 17 张表的逐表登记无缺陷（本次只改了头部口径措辞）
docs/风控业务演示文档/01、03、04、05、11、12、13、14、19、20 与 risk_agent.py 的实现一致：3 个工具 / 4 类意图，注册位置 bootstrap.py:330-349 相符
docs/风控业务演示文档/21 往返核对干净：§3 截断提示对应 risk_agent.py:376-381；§4 密钥路径对应 get_settings().jwt_private_key_path；§7 风控扫描调度器确实尚未接入主 Worker，文档已正确标注为待办
docs/evidence/ 下的取证产物 是运行产出的证据文件，不是需要同步的说明文档

3.3 同主题重复文档中的"权威版"

文档 核对结论
docs/11 / docs/15 / docs/16 三份均已在开头标注"以 docs/14 为准"，且 docs/14 本次已修正 → 重复品无需再改
docs/客服Agent接入底座扩展说明_v1.md 与实现一致
docs/验收与审计/phase1-acceptance-report.md 主体一致（仅表数与工具名两处小注，已改）
docs/33 / docs/34 / docs/35（ZSY 三件套） 不是重复品，是逐层推进的评审往返链，docs/35 为最终版，链条完整、无需改
docs/NL_develop 系列 5 份（交付说明 + 两轮架构师评审 + 两轮回复） 同样不是重复品，是一次完整的评审往返（交付说明即最终版），无需改
docs/客服Agent一期 / 二期 相关 其中分支名（ZSY_develop2、develop）略显陈旧；但该系列已由 docs/36（PR #7 合并记录）接管为权威口径，改动价值低于误改风险，故保留并在此说明

四、本次发现的最值得注意的问题（按严重度）

严重度 问题 处置
🔴 最高 docs/18 硬编码 Milvus 集合字段名（knowledge_id/snippet/…）。AGENTS.md 明令禁止，因为两套开发环境的 schema 不同；硬编码任一套会让 Milvus 直接报 field doc_id not exist → 三集合全失败 → 客服一律"引导人工" 已改为运行时探测的说明，并删掉代码示例里的硬编码默认值
🔴 高 AGENTS.md 自身含三处过时信息（前端"四套页面"、RBAC "9001-9046"、"风控 9 条白名单"）。它是接手入口，错误会传播 已全部修正
🟠 中高 docs/09 §14 把 search_knowledge 与 query_knowledge 的主从关系写反，且超时、角色均错。照此发布白名单会导致访客或登录客户其中一方一问即失败 已整段重写
🟠 中 表数口径在 5 份文档间不一致（49 / 51 / 52 / 68 / 72） 已统一为 89 张业务表 = 场内 51 + 场外/推广 17 + 投顾 21（含版本表 90），并保留历史数值作明确标注的沿革
🟠 中 docs/41 描述了一个从未落地的 customer/chat/ 页面（前端约束文档，会误导实现） 目录树整段替换为真实 6 角色树；剩余 4 处引用改为常驻浮窗
🟡 中低 docs/22 是"开工前评估稿"，多处结论已被实现推翻，但正文未标注 头部加"已作废"块 + 4 行对照表
🟡 中低 交接文档内部就有三个互相冲突的测试通过数，且分支指针已过期 加注说明来历与正确读法，强调"基线一律重跑取数"
🟡 中低 docs/42 / docs/43 对同一只基金的净值不同且互不引用（曾被认为是数据错误） 加交叉引用，明确"两个都是真实值、差异有因（相差两天）、入库前须定口径"

五、留给后续的建议（本次未做）

以下事项属于本次范围之外或需要业务决策，未改动，建议后续处理：

  1. 投顾 21 张表的登记文档仍缺（advisor_*）。AGENTS.md 与 docs/08 均已标注"待补"，建议按 docs/28 的口径另立一份。
  2. docs/36 的正文号段表到 9046 结束是对的（那正是当时的上界），现已在头部加了修正块。若希望正文也完整到 9065，需补充 9047+ 的语义描述。
  3. 风控扫描调度器尚未接入主 Worker（docs/风控业务演示文档/21 §7 已如实标注），属代码待办而非文档问题。
  4. docs/客服Agent一期/二期 的分支名陈旧，但已被 docs/36 接管权威口径，未改（改动价值低于误改风险）。

六、本次审计的编辑纪律（说明）

对每一个过时数字，采用的都是 "保留旧值 + 追加更正" 而非"静默覆盖"：

  • 旧值用删除线或"原文写…"的方式保留；
  • 更正内容带日期戳（2026-09-14）；
  • 尽量指向活体核验命令（如 python tools/audit_schema.py、python tools/check_rbac_seed_consistency.py）。

���由：这些文档里的旧数字在其当时都是正确的；把它们直接抹掉会销毁审计线索， 并且过一段时间又会有人拿着另一个时点的数字来问同样的问题。保留沿革比覆盖更有价值。

本次审计只修改文档，未改动任何业务代码。

Reference in New Issue View Git Blame Copy Permalink