Files

T

qyqy f7a666fb5a fix(env)+docs: 按架构师第二轮纠正 mypy 根因（环境版本）；补场外/推广域表登记

架构师第二轮答复里有一条技术纠正是对的，我原归因错了：
- 我原判断"184 个 mypy 错是因为缺 SQLAlchemy 2.0 类型信息"——**方向对了一半、结论反了**。
  SQLAlchemy 2.0 自带 py.typed，根本不需要 sqlalchemy2-stubs（那是 1.4 用的）。
- 实测复现矩阵（决定性证据）：
    SQLAlchemy 2.0.34 + mypy 1.14.1 → 173 错（我原来的环境）
    SQLAlchemy 2.0.34 + mypy 1.20.2 → 173 错
    SQLAlchemy 2.0.52 + mypy 1.14.1 →   6 错
    SQLAlchemy 2.0.52 + mypy 1.20.2 →   3 错
  ⇒ 主因是 SQLAlchemy 的**补丁版本**（173→6），mypy 版本是次因（6→3）。
- 已把环境升到 SQLAlchemy 2.0.52 + mypy 1.20.2（均在 pyproject 约束内），
  mypy 从 184 降到 **3 个错**（剩下的 3 个全在同事的 offsite 文件里，非本线代码）。
- 没有把 sqlalchemy2-stubs 写进依赖（采纳架构师明确要求）。
- 交接文档已重写该条，并留下"两个反面教训"：不要装 1.4 的存根包；补丁版差异会造成量级差异，
  若要门禁稳定需把 SQLAlchemy 钉到具体补丁版（属公共约定，未擅自改）。

按架构师裁决补文档（他裁定：不动 docs/00，另立登记）：
- 新增 docs/28-场外与推广域数据表登记.md：17 张表逐表登记（表名/来源迁移/归属域/当前行数），
  并做规则 8 的**两向边界核对**——场内代码零引用这 17 张表（config.py 里的 offsite_ 只是配置项名）、
  场外代码零写场内交易表
- docs/08 审计口径更新为「场内 51 + 场外/推广 17 = 68」，并新增"第四种坏状态"
  （alembic_version 已指向新 revision 但表没建）的处置说明
- 澄清一个易误读点：audit_schema.py 的期望集合是**动态推导**的（读 baseline_generated.sql
  + 扫描 alembic/versions/*.py），表数 51→68 是自动结果，**没有人手工改期望值**；
  代价是只增不减（DROP 表会报 missing 假失败）

测试：3 failed（1 既有 + 2 环境相关）/ 1218 passed；文档守卫 35 份无重号；
mypy 3 错（180 文件）；结构审计 68 张表通过。

2026-09-11 20:00:56 +08:00

5.6 KiB

Raw Blame History

数据库结构审计基线

一、审计工具

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）的业务验收。

5.6 KiB Raw Blame History Unescape Escape