feat: 第二版——接口契约对齐 docs/05，修复静默故障与数据库基线
相对第一版 46fc976 的完整变更。组员迁移对照表见 docs/20。
一、对外契约对齐 docs/05（破坏性，共 4 处，组员需按 docs/20 调整）
1) 配置发布端点改为文档规定的复数资源名：submit→validations、
approve→reviews（需 body decision）、activate→activations、
rollback→rollbacks；第一版这 4 个动词式路径 docs/05 从未定义过。
2) 错误码由 8 个笼统码改为 15 个具体语义码（FORBIDDEN→AGENT_PERMISSION_DENIED、
UNAUTHORIZED→AUTHENTICATION_REQUIRED、CONFLICT→RESOURCE_VERSION_CONFLICT、
RESOURCE_NOT_FOUND→RUN_NOT_FOUND/SESSION_NOT_FOUND 等），
输入类错误状态码 400→422。
3) POST /api/v1/agent-runs 与 GET /api/v1/agent-runs/{run_id} 统一为
{data, meta} 信封（data 内字段名与语义未变）。
4) 错误响应体统一为 {error:{code,message,retryable,field_errors}, meta:{trace_id}}，
不再返回 FastAPI 默认的 {"detail": ...}。
二、数据库基线与约束
新增 39 张表的基线迁移（链根）与联合唯一键纠偏（4 张表、删 8 增 4，幂等收敛）；
撤下 config_release 的双人复核 CHECK（应用层已允许自审，审核节点保留，
自审如实写入 reviewer_id）；记忆 active key 生成列与唯一键；
activate 开始记录 supersedes_release_id 使版本链可追溯。
docs/00 基线未修改，未重命名或删除任何表与字段。
三、修复会静默出错或无报错的缺陷
- 跑完集成测试后平台会静默失去生效配置：清理只删自己创建的版本，却没有恢复被它
顶成 superseded 的原生效版本，且审计一并删除因而完全无痕，表现为所有工具被拒
但没有任何报错。已修清理逻辑并加恢复。
- Worker 单轮异常导致进程退出；记忆抽取调用方的“事务已开始”异常；
召回缓存丢失 degraded 标记；连接时区未生效导致 created_at/updated_at 差 8 小时；
.env 与 os.getenv 密钥来源分裂导致“没有可用的已批准模型端点”。
- 记忆信号识别漏判与跨键误命中；SSE 未带 Accept 的协商行为。
四、功能补齐
记忆链路 P1/P2/P3（抽取、受控词表、召回与缓存、生命周期级联及投影事件）、
fin_* 场内交易只读 ORM 层、agent_intent_config 状态流转并在运行期真正生效、
限流（Redis 固定窗口、故障一律放行）、游标校验、trace_id 中间件、
示例业务 Agent fund_query_demo 与一键端到端验证脚本，以及审计/指纹/迁移状态工具。
五、文档与验证
新增 docs/19（业务 Agent 接入实操）、docs/20（第一版迁移指南）与 docs/evidence 证据；
docs/01/02/06/08/09/17 同步实现现状。
验证结果：ruff 通过、mypy 103 文件无错、unit+contract 447 passed、
integration 29 passed、acceptance_check --production 7 PASS、
demo_agent_e2e 9/9 PASS（含失败关闭反证）。
This commit is contained in:
@@ -0,0 +1,192 @@
|
||||
"""约束与映射一致性审计：文档基线 ↔ MySQL 实际结构 ↔ SQLAlchemy ORM。
|
||||
|
||||
只读，不修改数据库，也不写入任何文件。补足 audit_schema.py（只比表名/列存在）
|
||||
与 schema_fingerprint.py（只对字段做指纹）无法覆盖的盲区：
|
||||
|
||||
1. docs/00-新数据库基线设计.md 声明的唯一键 vs information_schema.STATISTICS；
|
||||
2. ORM 列 vs 库列。ORM 多出的列会让运行期 SQL 直接报错；库多出的 NOT NULL 列
|
||||
会让写入静默失败。
|
||||
3. 任一不一致以非零退出码暴露，便于纳入提交前检查链。
|
||||
|
||||
凭据来自 .env 的 MYSQL_DSN，不在脚本内硬编码口令。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from sqlalchemy import create_engine, text
|
||||
from sqlalchemy.engine import Connection
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
sys.path.insert(0, str(ROOT))
|
||||
|
||||
from app.core.config import get_settings # noqa: E402
|
||||
from app.model import ( # noqa: E402,F401
|
||||
audit,
|
||||
configuration,
|
||||
conversation,
|
||||
fund,
|
||||
memory,
|
||||
platform,
|
||||
session,
|
||||
)
|
||||
from app.model.base import Base # noqa: E402
|
||||
|
||||
BASELINE_DOC = ROOT / "docs" / "00-新数据库基线设计.md"
|
||||
UNIQUE_KEY = "唯一键"
|
||||
COMBINED_FLAG = "联合唯一键"
|
||||
COMBINED_KEY_RE = re.compile(UNIQUE_KEY + r"[^()]*\(([^)]+)\)")
|
||||
SKIP_FIELDS = {"字段", "表名"}
|
||||
|
||||
|
||||
def normalize(columns: Any) -> tuple[str, ...]:
|
||||
"""列顺序不影响唯一性语义，排序后再比较以避免顺序噪音。"""
|
||||
return tuple(dict.fromkeys(sorted(str(column) for column in columns)))
|
||||
|
||||
|
||||
def document_unique_keys() -> dict[str, set[tuple[str, ...]]]:
|
||||
"""解析基线文档中每个 `#### \\`表名\\`` 小节声明的唯一键。"""
|
||||
document = BASELINE_DOC.read_text(encoding="utf-8")
|
||||
heads = list(re.finditer(r"(?m)^#### `([^`]+)`", document))
|
||||
expected: dict[str, set[tuple[str, ...]]] = {}
|
||||
for index, match in enumerate(heads):
|
||||
name = match.group(1)
|
||||
following = re.search(r"(?m)^#{3,5} ", document[match.end():])
|
||||
end = match.end() + following.start() if following else len(document)
|
||||
keys: set[tuple[str, ...]] = set()
|
||||
combined_flag_columns: list[str] = []
|
||||
for line in document[match.end():end].splitlines():
|
||||
if not line.startswith("|"):
|
||||
continue
|
||||
cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
|
||||
if len(cells) < 3:
|
||||
continue
|
||||
field, rule = cells[0].strip("`"), cells[2]
|
||||
if not field or field in SKIP_FIELDS or set(field) <= {"-", " "}:
|
||||
continue
|
||||
matched = False
|
||||
for raw in COMBINED_KEY_RE.findall(rule):
|
||||
columns = tuple(
|
||||
dict.fromkeys(cell.strip().strip("`") for cell in raw.split(",") if cell.strip())
|
||||
)
|
||||
if columns:
|
||||
keys.add(normalize(columns))
|
||||
matched = True
|
||||
if COMBINED_FLAG in rule:
|
||||
combined_flag_columns.append(field)
|
||||
elif UNIQUE_KEY in rule and not matched:
|
||||
keys.add((field,))
|
||||
if len(set(combined_flag_columns)) > 1:
|
||||
keys.add(normalize(combined_flag_columns))
|
||||
if keys:
|
||||
expected[name] = keys
|
||||
return expected
|
||||
|
||||
|
||||
def database_unique_keys(connection: Connection) -> dict[str, set[tuple[str, ...]]]:
|
||||
rows = connection.execute(
|
||||
text(
|
||||
"""
|
||||
SELECT TABLE_NAME, INDEX_NAME, COLUMN_NAME, SEQ_IN_INDEX
|
||||
FROM information_schema.STATISTICS
|
||||
WHERE TABLE_SCHEMA = DATABASE() AND NON_UNIQUE = 0 AND INDEX_NAME <> 'PRIMARY'
|
||||
ORDER BY TABLE_NAME, INDEX_NAME, SEQ_IN_INDEX
|
||||
"""
|
||||
)
|
||||
).all()
|
||||
grouped: dict[tuple[str, str], list[str]] = {}
|
||||
for table, index, column, _sequence in rows:
|
||||
grouped.setdefault((table, index), []).append(column)
|
||||
result: dict[str, set[tuple[str, ...]]] = {}
|
||||
for (table, _index), columns in grouped.items():
|
||||
result.setdefault(table, set()).add(normalize(columns))
|
||||
return result
|
||||
|
||||
|
||||
def orm_columns() -> dict[str, set[str]]:
|
||||
return {
|
||||
table.name: {column.name for column in table.columns}
|
||||
for table in Base.metadata.sorted_tables
|
||||
}
|
||||
|
||||
|
||||
def database_columns(
|
||||
connection: Connection,
|
||||
) -> tuple[dict[str, set[str]], dict[str, set[str]]]:
|
||||
"""返回 (普通列, 生成列)。生成列由 MySQL 计算，不要求 ORM 映射。"""
|
||||
rows = connection.execute(
|
||||
text(
|
||||
"""
|
||||
SELECT TABLE_NAME, COLUMN_NAME, GENERATION_EXPRESSION
|
||||
FROM information_schema.COLUMNS
|
||||
WHERE TABLE_SCHEMA = DATABASE()
|
||||
"""
|
||||
)
|
||||
).all()
|
||||
plain: dict[str, set[str]] = {}
|
||||
generated: dict[str, set[str]] = {}
|
||||
for table, column, expression in rows:
|
||||
target = generated if str(expression or "").strip() else plain
|
||||
target.setdefault(table, set()).add(column)
|
||||
return plain, generated
|
||||
|
||||
|
||||
def main() -> int:
|
||||
settings = get_settings()
|
||||
engine = create_engine(settings.mysql_dsn.replace("mysql+asyncmy", "mysql+pymysql"))
|
||||
constraint_problems: list[str] = []
|
||||
mapping_problems: list[str] = []
|
||||
generated_columns: list[str] = []
|
||||
with engine.connect() as connection:
|
||||
expected = document_unique_keys()
|
||||
actual = database_unique_keys(connection)
|
||||
for table in sorted(expected):
|
||||
existing = actual.get(table, set())
|
||||
for key in sorted(expected[table] - existing):
|
||||
constraint_problems.append(f"[{table}] MISSING in DB : UNIQUE ({', '.join(key)})")
|
||||
for key in sorted(existing - expected[table]):
|
||||
constraint_problems.append(f"[{table}] EXTRA in DB : UNIQUE ({', '.join(key)})")
|
||||
|
||||
orm = orm_columns()
|
||||
database, generated = database_columns(connection)
|
||||
for table in sorted(orm):
|
||||
if table not in database:
|
||||
mapping_problems.append(f"[{table}] ORM table does not exist in database")
|
||||
continue
|
||||
for column in sorted(orm[table] - database[table]):
|
||||
mapping_problems.append(f"[{table}] ORM column not in DB : {column}")
|
||||
for column in sorted(database[table] - orm[table]):
|
||||
if column in generated.get(table, set()):
|
||||
generated_columns.append(f"[{table}].{column}")
|
||||
continue
|
||||
mapping_problems.append(f"[{table}] DB column not mapped : {column}")
|
||||
engine.dispose()
|
||||
|
||||
print(f"constraint check: {len(expected)} documented tables compared")
|
||||
if constraint_problems:
|
||||
print("--- unique key mismatches ---")
|
||||
for problem in constraint_problems:
|
||||
print(" " + problem)
|
||||
if mapping_problems:
|
||||
print("--- orm/database mapping mismatches ---")
|
||||
for problem in mapping_problems:
|
||||
print(" " + problem)
|
||||
if generated_columns:
|
||||
print(f"note: {len(generated_columns)} generated column(s) intentionally not mapped: "
|
||||
+ ", ".join(generated_columns))
|
||||
|
||||
total = len(constraint_problems) + len(mapping_problems)
|
||||
if total:
|
||||
print(f"\nFAILED: {total} mismatch(es) "
|
||||
f"(constraints={len(constraint_problems)}, mapping={len(mapping_problems)})")
|
||||
return 1
|
||||
print("\nPASSED: unique keys and ORM mappings match the baseline")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Reference in New Issue
Block a user