lzf_0626
6516ccb385
相对第一版 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（含失败关闭反证）。
89 lines
4.3 KiB
Python
89 lines
4.3 KiB
Python
"""撤下配置发布的"复核人必须不同于创建人"数据库约束（幂等收敛）。
|
||
|
||
修订原因（产品决策，非技术缺陷）：`config_release` 上原有
|
||
`CONSTRAINT chk_config_release_separation CHECK (reviewer_id IS NULL OR reviewer_id <> created_by)`，
|
||
强制"双人复核"。当前平台是**单管理员部署**（唯一的 admin 身份是 `sys_user.id=9003`），
|
||
该约束使配置发布流程在数据库层无法走通：应用层已按决策放行自审，但提交时 MySQL 仍以
|
||
错误 3819 (`Check constraint 'chk_config_release_separation' is violated`) 拒绝，表现为
|
||
`POST /config-releases/{id}/approve` 必然失败。因此约束必须与代码同步撤下，否则保留的
|
||
是一个"永远不可能被满足"的状态。
|
||
|
||
保留了 `chk_config_release_status`：状态机取值集合未被放宽，本次只撤"复核人身份"限制。
|
||
"审核"这一流程节点本身仍然存在（`pending_review` → `approved` 仍要求调用审核接口并写入
|
||
`reviewer_id`/`reviewed_at`），取消的只是"必须由另一个人操作"。
|
||
|
||
基线合规（`AGENTS.md` 第 3/4 条）：本迁移**不重命名、不删除任何表或字段，也不改变任何
|
||
已有字段的类型、可空性与业务含义**——只删除一个表级 `CHECK` 约束，且 `reviewer_id` 列
|
||
本身及其可空性完全保持原样。`docs/00-新数据库基线设计.md` 未修改（该约束本就不在基线
|
||
文档中，只存在于 `docs/02` 建表设计与旧的 `20260909_agent_platform_v31` 建表语句里）。
|
||
|
||
幂等性：先查 `information_schema.CHECK_CONSTRAINTS` 再决定是否 `ALTER`。因此
|
||
- 既有库（约束存在）：撤下；
|
||
- 空库重建（`baseline_schema` + `agent_platform_v31` 会先建出该约束，再到本迁移）：同样撤下，
|
||
两条路径最终收敛到同一结构，重复执行也不会报 1091/3820。
|
||
不采用"直接改历史迁移 `20260909_agent_platform_v31`"的做法：已发布的迁移文件应保持其
|
||
曾被应用过的事实，收敛交给新迁移完成。
|
||
|
||
影响面：1 张表（`config_release`）、删除 1 个约束、不涉及任何数据行改写。当时表内 5 行
|
||
配置批次（其中 2 行为 `pending_review` 且 `reviewer_id IS NULL`，不违反约束）。
|
||
"""
|
||
|
||
from sqlalchemy import text
|
||
from sqlalchemy.engine import Connection
|
||
|
||
from alembic import op
|
||
|
||
revision = "20260910_drop_review_separation"
|
||
down_revision = "20260909_memory_active_key"
|
||
branch_labels = None
|
||
depends_on = None
|
||
|
||
TABLE = "config_release"
|
||
CONSTRAINT = "chk_config_release_separation"
|
||
SEPARATION_CLAUSE = "reviewer_id IS NULL OR reviewer_id <> created_by"
|
||
|
||
|
||
def _constraint_exists(bind: Connection, table: str, name: str) -> bool:
|
||
"""MySQL 的 CHECK 约束在 information_schema 里挂在表上，按表名+约束名判定。"""
|
||
found = bind.execute(
|
||
text(
|
||
"""
|
||
SELECT 1
|
||
FROM information_schema.TABLE_CONSTRAINTS
|
||
WHERE CONSTRAINT_SCHEMA = DATABASE()
|
||
AND TABLE_NAME = :table
|
||
AND CONSTRAINT_NAME = :name
|
||
AND CONSTRAINT_TYPE = 'CHECK'
|
||
"""
|
||
),
|
||
{"table": table, "name": name},
|
||
).first()
|
||
return found is not None
|
||
|
||
|
||
def upgrade() -> None:
|
||
bind = op.get_bind()
|
||
if _constraint_exists(bind, TABLE, CONSTRAINT):
|
||
op.execute(f"ALTER TABLE `{TABLE}` DROP CHECK `{CONSTRAINT}`")
|
||
|
||
|
||
def downgrade() -> None:
|
||
"""恢复双人复核约束。
|
||
|
||
恢复约束前必须先把"自己审自己"的既有行清掉：MySQL 在 `ADD CHECK` 时会立即校验现有
|
||
数据，只要存在一行 `reviewer_id = created_by` 就会报 3819，导致回退失败。这里把这类
|
||
行的 `reviewer_id` 置回 `NULL`（即回到"尚未复核"状态），而不是删除任何行——`created_at`、
|
||
`reviewed_at`、状态与配置内容都不动。回退会丢失"谁审的"这一条信息，这是恢复旧语义的
|
||
必然代价，仅在整体回退到本迁移之前的状态时使用。
|
||
"""
|
||
bind = op.get_bind()
|
||
if _constraint_exists(bind, TABLE, CONSTRAINT):
|
||
return
|
||
bind.execute(
|
||
text(
|
||
f"UPDATE `{TABLE}` SET `reviewer_id` = NULL " # noqa: S608 - 表名/列名为本模块常量
|
||
f"WHERE `reviewer_id` IS NOT NULL AND `reviewer_id` = `created_by`"
|
||
)
|
||
)
|
||
op.execute(f"ALTER TABLE `{TABLE}` ADD CONSTRAINT `{CONSTRAINT}` CHECK ({SEPARATION_CLAUSE})")
|