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 份无编号冲突。
7.0 KiB
数据库结构审计基线
一、审计工具
tools/schema_fingerprint.py 读取 MySQL information_schema 中每张表的字段名、类型、可空性、
默认值、额外属性、字符集、排序规则和生成表达式，并输出 SHA-256 指纹。2026-09-09 起指纹
同时覆盖索引与唯一键（STATISTICS）以及外键（KEY_COLUMN_USAGE + REFERENTIAL_CONSTRAINTS），
因为只对字段做指纹无法发现约束漂移。它不读取业务行数据，支持 --out 直接落 UTF-8 文件。
tools/audit_constraints.py 做三向比对：docs/00 声明的唯一键 ↔ 库实际唯一索引、
ORM 映射 ↔ 库列名（生成列单独归类为 note）。任一不一致返回非零退出码，可纳入提交前检查。
tools/audit_schema.py 仍负责表名与列存在性比对，与上述两个工具互补。
二、历史指纹记录
2026-09-09 在补建会话表前保存了 49 张既有表指纹；迁移 20260909_session 之后再次比对，
49 张既有表全部一致，新增 svc_conversation_session。随后新增 api_request_receipt，
该表是公共 HTTP 幂等回执，不能替代 request_idempotency。
三、2026-09-09 约束纠偏
tools/generate_baseline_sql.py 旧实现只按规则列里的"唯一"字样逐字段生成 UNIQUE KEY，
无法表达 docs/00 中的 唯一键 (a, b) 写法，导致四张表的联合唯一键被拆成两个单列唯一键：
| 表 | 纠偏前（错误） | 基线要求 |
|---|---|---|
fin_market_price |
UNIQUE(product_id)、UNIQUE(trade_date) | UNIQUE(product_id, trade_date) |
fin_nav_history |
UNIQUE(product_id)、UNIQUE(nav_date) | UNIQUE(product_id, nav_date) |
fin_holding |
UNIQUE(customer_id)、UNIQUE(product_id) | UNIQUE(customer_id, product_id) |
sys_customer_assignment |
UNIQUE(customer_id)、UNIQUE(employee_role) | UNIQUE(customer_id, employee_role) |
后果：场内日线与净值每产品只能存一行、持仓每客户只能有一个产品，属结构性阻断。
四张表在纠偏时均为 0 行，故纠偏无数据风险。迁移 20260909_constraint_fix 删除 8 个错误
唯一键、新增 4 个联合唯一键；docs/00 基线文档未做任何修改，纠偏的是库与生成器。
验证证据（docs/evidence/）：
20260909-before-constraint-fix.sql：纠偏前 52 张表SHOW CREATE TABLE全量快照；20260909-fingerprint-before.json与20260909-fingerprint-after.json：纠偏前后结构指纹；- 两份指纹的差异恰好 4 张表（上表四张），其余 47 张结构未变；
tools/audit_constraints.py：约束差异由 12 条降为 0。
四、既有库对齐（方案 A）
⚠️ 2026-09-11 更新：业务表数已从 51 变为 68。 同事那条线（袁聪）合并进来的 11 个 alembic 迁移新建了 17 张表 ——
offsite_*（场外基金运营，10 张）与promotion_*（推广域，7 张）。 这 17 张不进docs/00基线（它冻结的是场内交易域），由docs/28-场外与推广域数据表登记.md单独登记。口径统一为：场内 51（docs/00） + 场外/推广 17（docs/28） = 68 张业务表 （另加 alembic_version，库内共 69 张）
tools/audit_schema.py的期望值随迁移自动增长（它读baseline_generated.sql+ 扫描alembic/versions/*.py的CREATE TABLE，不是手写清单），所以本次 68 是自动结果， 没有人手工改过期望值。架构师合并后会看到表数从 51 跳到 68，那是这 11 个迁移的预期结果， 不是有人绕过基线偷偷建表（机制与代价详见docs/28-场外与推广域数据表登记.md§5）。
基线表补入 Alembic 链首（20260909_baseline_schema）后，按库的来源分三种情况：
| 库状态 | 特征 | 操作 |
|---|---|---|
| 空库 | 无 alembic_version 记录、无业务表 |
alembic upgrade head，全量建出 68 张业务表（原为 51，见上方更新） |
| 由 Alembic 建起 | alembic_version 已位于链上 |
直接 alembic upgrade head；Alembic 不会重跑祖先迁移，无需 stamp |
| 手工或脚本建库 | 有业务表但 alembic_version 为空 |
直接 upgrade 会重建已有表而失败，必须先 alembic stamp <当前结构对应版本>，再 upgrade head |
⚠️ 本次合并实测到的第四种坏状态（原文档未覆盖，值得记一笔）：
alembic_version已指向较新的 revision，但部分表并不存在 —— 即"版本号跑了、表没建"。 本库当时就是这种状态（alembic_version = 20260910_drop_review_separation，而offsite_*/promotion_*一张都没有）。它靠alembic upgrade heads收敛： Alembic 只跑alembic_version之后的迁移，所以恰好补建了缺失的表。 架构师那边是另一种坏状态（"表没建、版本号也没跑"），同样靠这一条收敛。
tools/migration_state_check.py 只读诊断这三种状态：读取迁移链 head、alembic_version 记录与
业务表数量，并按结构特征（生成列、联合唯一键、代表性表）由新到旧推断库实际所处版本，输出可执行
的建议命令。三种状态均已实测：空库判定正确；jr 库判定为"已在 head、无需操作"；手工库场景
（建表后清空版本记录）提示 stamp 到 20260909_memory_active_key，按其建议执行后 upgrade head
无任何 Running upgrade 输出，即未误重建表。
五、边界
数据库约束仍以 docs/00-新数据库基线设计.md 为业务权威。指纹与约束审计只证明结构一致，
不替代状态机、并发语义和跨存储投影（Milvus/Neo4j）的业务验收。
六、已知文档偏差（docs/00 与真实 schema 不一致之处）
docs/00 是不可变业务基线（AGENTS.md 规则 1），不因下列偏差修改；但偏差必须登记，
否则每换一个人接手就会重新踩一次。发现新偏差请追加到本节。
| # | 位置 | 文档描述 | 真实 schema | 处置 |
|---|---|---|---|---|
| 1 | profile_snapshots.current_customer_id |
docs/00 第 783 行描述为**「生成列」** |
不是生成列：information_schema.COLUMNS 实测 EXTRA=''、GENERATION_EXPRESSION=''；alembic/baseline_generated.sql 的建表语句无 GENERATED 子句；tools/seed_profile_demo.py 注释写明「不是生成列，必须显式写入」；profile_repository.py 用原生 SQL 显式写入 |
按真实 schema 映射成普通可空列；不改 docs/00；不补迁移（DDL 本身正确，错的只是文档描述；为"让文档成真"而加生成列会改变既有列语义，违反规则 4）。四处证据一致，2026-09-11 复核 |
发现方式：ZSY 那条线在合并前先按
AGENTS.md与docs/00/01/05/09/14/20逐条过规则， 撞到"文档说生成列、代码却显式写入"这处矛盾后做了实测。这个自查习惯值得保持—— 本次三家里，只有这条线在合之前把"撞到底座规则"的地方单独清理成了一个提交。