lzf_0626
244f03917b
## 对 ZSY 三件事的核实与裁决（docs/33-ZSY底座扩展确认-回复.md） 1. **访客身份**：`data_scope="public"` 我扫了全平台 26 个消费点，对未知值的行为一致 fail closed（6 处 `== "all"` 判假、1 处 `!= "all"` 会要求 customer_ids 非空否则 403、 1 处显式白名单直接拒），**安全，不用改**。但有一条硬约束必须先确认：全平台有 **72 处 `int(context.user_id)`，只有 3 处做了防御**——若访客的 sub 不是纯数字， 其中"权限被拒时要写审计"的路径会把本该 403 的情况变成 500。已要求他确认 sub 为纯十进制数字、且 visitor 分支复用同一套 `jwt.decode`（含 isdecimal 校验）， 而不是另写第二个鉴权入口。 2. **客服 Agent**：`allowed_roles` 扩集合与确定性安全路由可接受；`recalls_customer_memory` 是新声明字段，已要求**默认值必须是 True**（否则会静默关掉所有既有 Agent 的记忆召回， 界面看不出来、只表现为回答变差）。品牌名（南方科技 → 奶龙基金责任有限公司）属业务 口径，已上报项目方定，不由技术侧拍板。 3. **current_customer_id**：**他的判断正确**。我独立实测 information_schema： `EXTRA=''` 且 `GENERATION_EXPRESSION=''`，配合 baseline_generated.sql 无 GENERATED 子句、seed_profile_demo.py 的注释、profile_repository.py 用原生 SQL 显式写入， 四处一致 ⇒ `docs/00` 第 783 行"生成列"的描述是错的。处置：按真实 schema 映射成 普通可空列、**不改 docs/00**（规则 1）、**不补迁移**（DDL 本身正确，为让文档成真而加 生成列会改变既有列语义，违反规则 4）、但**必须登记这处偏差**。 另：他删了两个死代码文件（含一处硬编码 Milvus 字段名，违反 AGENTS.md §E），方向认同， 但要求他在 PR 里附上两条 git grep 的实际输出以证明"全仓唯一引用是它自己的单测"。 ## 落实我在回复里承诺的两件事 - `docs/08-数据库结构审计基线.md` 新增"六、已知文档偏差"，逐条登记上述偏差（含四处 证据与处置口径），并注明发现方式； - `AGENTS.md` 环境口径新增 `MILVUS_LOCAL_URI` 的坑：配了会让健康检查与部分检索指向 本地 Milvus Lite 文件，出现"健康检查正常、实际查的是另一个库"；并注明 `milvus-lite` 属本地开发依赖，应放 `optional-dependencies` 而非主依赖。 ## 顺带更新 AGENTS.md 的过期口径 - 表数 68 → **89**（场内 51 + 场外/推广 17 + 投顾 21），并注明投顾那 21 张的登记文档待补； - 测试基线从"1034 passed / 1 failed"改为实测值：ruff 干净 / mypy 228 文件 0 错 / 1207 passed 0 failed / integration 99 passed，并指向 docs/32； - mypy 那条从"本机 181 错、双方不可比"改成可操作的判据：先对版本，根因是某一侧虚拟环境 没满足 pyproject 的 sqlalchemy>=2.0,<3 / mypy>=1.14,<2；并写明**不要装 sqlalchemy2-stubs** （那是给 1.4 的，2.0 自带 py.typed，装了反而按 1.4 API 报一批新错）。 文档守卫：42 份无编号冲突。
8.7 KiB
8.7 KiB
项目级开发约束
以下规则对人工开发者和编码 Agent 均为强制约束：
- 数据库以
docs/00-新数据库基线设计.md为不可变业务基线。 - 允许创建新表，允许在已有表中增加新字段。
- 禁止重命名或删除已有表。
- 禁止重命名、删除、复用已有字段，禁止改变已有字段的类型、可空性和既有业务含义。
- 历史结构无法满足新需求时，使用新增字段、新表、兼容视图或应用双读解决。
- 架构固定使用 MVC+S；Agent 属于 Service 层。
- 业务 Agent 必须继承公共
BaseAgent并由AgentFactory创建，不得绕过公共鉴权、记忆、模型路由、工具、合规、审计和事件流程。 - 当前系统业务功能只针对场内基金模拟交易；场外基金运营流程独立，不得写入场内交易表。
修改数据库文档或迁移前，必须对比基线并证明没有改变任何已有表名和已有字段定义。
📖 接手先读（按此顺序，只读这些就够）
⭐ 第 0 步先读这个：
docs/superpowers/handoff/2026-09-11-交接文档-客服Agent与RAG收尾.md—— 客服 Agent + RAG 这条线的交接文档（含合并完成后的第二次更新）：环境口径、交付内容与 可复现验证证据、合并后修掉的 3 个真机故障、已知问题清单（逐条标注当前状态）、Git/PR 状态。 当前工作分支是NL_develop（个人分支 → PR 合回qyqy_develop），不要再用6516ccb。 它是对"当前状态"最准确的一份，读完它再读下面这些。⚠️ 文档现状（2026-09-11 第二次修订）：本文件原先声明"已删除 5 份编号文档"， 那条已作废 —— 经评审，
docs/04/06/10/13/99全部保留（架构师明确要求保留： 删除收益为零，而保留成本同样为零）。它们的内容未被核对过、可能过期， 因此列在下面的 D 类"不要用来判断当前进度"里，只作历史参考。 被删除的只有 10 份过程产物，理由与清单见docs/superpowers/ARCHIVE-2026-09-11-文档清理归档.md。
A. 核心 7 份（无论接手哪条线都必读）
| 序 | 文档 | 承载的唯一权威内容 |
|---|---|---|
| 1 | docs/00-新数据库基线设计.md |
不可变业务基线：表/字段业务语义的唯一来源 |
| 2 | docs/05-接口文档.md |
接口唯一权威：信封/错误码/幂等/SSE、§8.3 知识库管理三端点、§8.4 四个只读工具索引与两段式白名单 |
| 3 | docs/01-通用Agent平台开发设计.md |
MVC+S 分层约束、BaseAgent 执行骨架、AgentFactory |
| 4 | docs/02-数据库建表设计.md |
51 张业务表总览 + DDL + §8 幂等与 Outbox 语义 |
| 5 | docs/03-平台端到端流程文档.md |
一次请求从受理→Worker→审计→事件的全链路与降级矩阵 |
| 6 | docs/08-数据库结构审计基线.md |
三个审计工具 + migration_state_check 的职责；"证明未改基线"的证据出处 |
| 7 | docs/07-测试问题修复记录.md |
无替代：P0-1/2/3 鉴权与 Worker 租约闭环、P1-1~P1-5（含 api_request_receipt 事务幂等） |
B. 按角色补充
| 你接手的是 | 再读这些 |
|---|---|
| 客服 Agent + RAG 这条线 | docs/14（接入入口）→ docs/18（RAG 三集合路由方案）→ docs/19（可运行示例）→ docs/09（底座用法与四工具） |
| 整个底座 | 补 docs/20（第一版→当前的破坏性改动 + §5 四条尚未修复的偏差 + "跑验收前先停常驻 Worker"） |
| 只改某个业务域 | docs/00 → docs/05 → docs/02 → docs/14 → docs/19；行情加 docs/12，前端/联调加 docs/17 |
| 看"现在做到哪了" | docs/验收与审计/phase1-acceptance-report.md（Phase 1 七条验收标准的逐条可复现证据）+ 同目录 phase1-acceptance-criteria.md（老师验收标准原文摘录） |
注：完整的过程台账（
progress.md、各 Task 报告、审计报告）在.superpowers/sdd/2026-09-10-客服Agent与RAG-qyqy版/， 但该目录被.gitignore忽略（属工作区过程产物）—— 因此结论性文档已复制到docs/验收与审计/以保证 git 可见。 若要查过程细节再去看.superpowers/；日常接手只需读本文档列出的这些。
C. 同主题的重复文档（读一份即可，避免信息冲突）
| 主题 | 唯一权威 | 重复品（仅历史参考） |
|---|---|---|
| Agent 组员接入 | docs/14 |
docs/11（旧版说明书）、docs/15（详细手册）、docs/16（入门易懂版）—— 三份已各自在开头标注"以 14 为准" |
| 接口说明 | docs/05 |
docs/17（易懂版，自述"不替代 05"） |
D. ⚠️ 不要用来判断"当前进度"
| 文件 | 为什么 |
|---|---|
TODO.md |
自 2026-09-09 起未随 Phase 1 更新：5 处"49 张表"（实为 51 张业务表）、T8.1 客服 Agent 整节未勾选但已交付、多处标"进行中"其实已完成。当前进度一律以 phase1-acceptance-report.md 为准。 |
docs/04 / 06 / 10 / 13 / 99 |
内容未核对过、可能过期（自相矛盾 / 结论失效 / 清单不全）。经 2026-09-11 评审保留（不再删除），仅作历史参考。不要用它们判断现状 |
E. 环境与命令口径（易错点）
- 解释器：本机用
.\.venv\Scripts\python.exe；架构师环境用D:\conda\envs\jr_py313\python.exe。 两者等价，各用本机可用的那个（.venv被.gitignore忽略、不进仓库，不存在"需要统一"的问题）。 - 数据库现为 90 张表（含
alembic_version）＝ 89 张业务表 = 场内 51 + 场外/推广 17 + 投顾 21。 后 38 张（offsite_*/promotion_*/advisor_*）不进docs/00基线（规则 8）： 场外/推广那 17 张逐表登记见docs/28-场外与推广域数据表登记.md； 投顾那 21 张的登记文档待补（按同样口径另立一份）。 核验命令：python tools/audit_schema.py（若报unexpected先分清是"库里多表"还是"迁移没进来"）。 - 已注册业务 Agent：
FundQueryDemoAgent、CustomerServiceAgent、RiskAgent、PlatformProbeAgent（见app/service/agent/bootstrap.py）。 - 已注册公共只读工具：
search_knowledge（客服知识检索）、check_suitability、query_customer_profile（画像）、query_fund_quote； 工具可用范围 = 代码上限 ∩ 当前 activeconfig_release的发布白名单，缺发布配置则失败关闭。 - ⚠️
config_release是环境数据，不随代码合并：本机 active 版本 id 与架构师环境不同 （本机是我方发布的客服白名单；他那边还有风控的 9 条白名单）。"白名单已发布"必须带环境限定，换环境要重发。 发布脚本tools/publish_customer_service_config.py（同 key 的继承项必须被本次定义覆盖，否则旧值会被子集校验 422 拦下整次发布）。 - ⚠️ Milvus 集合 schema 也因环境而异：本机是
knowledge_id/snippet（无visibility）， 架构师环境是doc_id/content/visibility/chapter…。检索层已改为运行时探测字段名 （app/core/knowledge_schema.py）——不要在任何地方硬编码字段名，那会把另一套环境打挂。 - ⚠️ Docker Desktop 不会常驻：它没运行时 Milvus 不可用（
dockerCLI 报连不上守护进程）。 跑真机验证前先确认 Docker Desktop 在运行。 - ⚠️
MILVUS_LOCAL_URI配了就会"看着正常、查的是另一个库"：一旦在.env里设置它， 健康检查与部分检索链路会指向本地 Milvus Lite 文件。团队/生产环境请保持该变量为空。 对应的milvus-lite属本地开发依赖，应放在pyproject.toml的optional-dependencies，不要进主dependencies。 - 测试基线（2026-09-11 架构师环境实测）：
ruff干净 /mypy app228 个文件 0 错 /pytest tests/unit tests/contract→ 1207 passed, 2 skipped, 0 failed /pytest tests/integration→ 99 passed。完整口径与联调清单见docs/32-平台侧交接与联调准备.md。 - ⚠️ mypy 与测试数必须带环境读：出现"一边上百个错、另一边 0 错"时先对版本，别当代码质量问题。
已知根因是某一侧的虚拟环境没满足
pyproject.toml的sqlalchemy>=2.0,<3/mypy>=1.14,<2。 不要装sqlalchemy2-stubs—— 那是给 SQLAlchemy 1.4 的，2.0 自带py.typed， 装了反而按 1.4 的 API 报一批新错（mapped_column/DeclarativeBase不存在）。