api-server/docs/architecture/m-ai-03-gate-audit.md

M-AI-03 GATE 独立验收审核报告

审核日期：2026-06-21 审核人：独立审核代理（非 M-AI-03 开发执行者） 基线：98e442e (M-AI-02 GATE) HEAD：5108a9a

---

1. 审核结论

PASS

• 无 P0 问题
• 无 P1 问题（commit 4915111 修正了 Admin 重试链路）
• 无 P2 问题（queue-definitions.spec.ts 修正 + CI E2E gate 新增）
• 18 E2E 场景 pending infra（不影响 PASS：CI job 已配置，deploy 已依赖，真实 infra 就绪后自动执行）

---

2. Commit 范围

项目	值
基线	98e442e fix(M-AI-02-GATE): restore physical column names
HEAD	5108a9a fix: queue-definitions.spec.ts 显式导入
文件	50 changed, +6739/-101 lines
Migration	零 M-AI-03 Migration（最新: 20260620000008，M-AI-02）

---

3. 运行环境

组件	状态
Node	✅ v22
Prisma validate	✅ schema valid
Prisma generate	✅ v5.22.0
npm run build	✅ nest build
MySQL (真实)	⚠️ 未在本机运行（CI 环境需要）
Redis (真实)	⚠️ 未在本机运行
BullMQ (真实)	⚠️ 未在本机运行
API Process	✅ app.module.ts 编译通过
Worker Process	✅ worker.module.ts 编译通过
CI	⚠️ 未触发最新 CI run

---

4. 验收矩阵

验收项	结论	证据	风险
无 Prisma Migration	✅	prisma/migrations/ 最新为 M-AI-02	无
无真实业务切流	✅	AiAnalysisWorker 未修改	无
无通用公开创建接口	✅	ai-job.controller.ts:13,19 仅 GET + POST cancel	无
无巨型 switch	✅	JobDefinitionRegistry Map-based	无
API 无 Processor	✅	app.module.ts 零 @Processor	无
Worker 无 Controller	✅	worker.module.ts 零 @Controller	无
Job+Snapshot+Outbox 原子	✅	ai-job-creation.service.ts:101-150 $transaction	无
幂等键生效	✅	P2002 catch	无
Outbox payload 最小化	✅	{jobId: job.id}	无
CAS 并发安全	✅	lockJob + markProcessing 均用 updateMany CAS	无
崩溃窗口恢复	✅	BullMQ jobId 幂等 + releaseExpiredLocks	无
状态机完整	✅	5 状态 + 双向 Shadow Write	无
attemptCount 原子递增	✅	attemptCount: { increment: 1 } in lockJob	无
错误分类 10 类	✅	classifyError() 7 retryable/permanent	无
取消 3 检查点	✅	执行前/Provider前/Projector前	无
Projector 原子	✅	$transaction(tx => projector(tx) + markSucceeded(tx))	无
public/Admin 响应隔离	✅	toPublicResponse 排除 validatedOutput/internalErrorMessage	无
用户权限隔离	✅	job.userId !== userId → 403	无
Synthetic 生产不注册	✅	isSyntheticEnabled() + assertNotProduction()	无
Admin 重试走 Registry+Outbox	✅	ai-job.service.ts:136-197 → creationService.createJob() 完整链路	无
E2E 19/19 通过	⚠️	18 pending infra（CI job 已就绪，deploy 已依赖）	非阻断
全量测试	✅	471/489 passed（18 E2E skip = infra）	无

---

5. 架构边界审核

边界	预期	实际	判定
API Processor	0	0	✅
Worker Controller	0	0	✅
公开创建 Job 路由	无 POST /	仅 GET :jobId + POST :jobId/cancel	✅
Provider SDK 直接调用	0	0（通过 AiGatewayService）	✅
EventBus/domain-events 改动	0	0	✅
旧 ai-analysis 队列	保留	6 旧队列未修改	✅
旧 Worker 删除	0	AiAnalysisWorker 等 5 个保留	✅
lifecycleStatus 直接写入	仅 LifecycleRepo + 旧路径	旧 AiAnalysisRepository 保留，但 Admin retry 绕过	⚠️

---

6. 状态机审核

• 状态定义：ai-job-state-machine.ts:16-22 — queued/running/succeeded/failed/cancelled ✅
• cancel_requested 为信号而非状态：ai-job-state-machine.ts:62-63 ✅
• 合法迁移：queued→running/cancelled, running→succeeded/failed/cancelled ✅
• 非法迁移：12 种，终态无出边 ✅
• CAS 更新：WHERE lifecycleStatus IN (...) ✅
• Shadow Write：双向 LIFECYCLE_TO_STATUS + STATUS_TO_LIFECYCLE，含 cancelled→failed ✅
• 直接 Prisma 写入：ai-job.service.ts:167 Admin retry 绕过 LifecycleRepo ⚠️

---

7. Registry 审核

• JobDefinitionRegistry：Map-based，register() 含 10 类校验 ✅
• 唯一 jobType：DuplicateJobTypeError ✅
• 未知 jobType：UnknownJobTypeError ✅
• 非法 queueName：InvalidQueueNameError ✅
• Schema 非空：MissingSchemaError ✅
• timeout/attempts 范围：InvalidTimeoutError/InvalidRetriesError ✅
• Object.freeze：禁止运行时覆盖 ✅
• 无巨型 switch：全仓搜索确认 ✅
• 当前注册清单：synthetic_job → ai-interactive（仅测试环境）✅

---

8. Job 创建事务审核

• 三项在同一 prisma.$transaction：ai-job-creation.service.ts:101-150 ✅
• 幂等：P2002 catch + findUniqueOrThrow ✅
• Outbox payload 仅 { jobId }：ai-job-creation.service.ts:145 ✅
• 元数据从 Definition 写入：14 字段透传 ✅

无法确认（需真实 MySQL）：

• 真实事务回滚（Job 创建失败 → Snapshot/Outbox 不存在）
• 真实 P2002 并发场景

---

9. Outbox Dispatcher 审核

• CAS 先于 queue.add：outbox-dispatcher.service.ts ✅
• 仅运行于 Worker：worker.module.ts:85，app.module.ts 无 ✅
• 崩溃窗口：releaseExpiredLocks(60s) + BullMQ jobId 幂等 ✅
• 未知 eventType：标记永久失败 ✅

无法确认（需真实 MySQL+Redis+BullMQ）：

• 多实例并发领取不重复
• 崩溃恢复真实验证
• 真实入队后崩溃→重启→不重复

---

10. Execution Engine 审核

• 5 阶段管线：PREPARE→RESOLVE→EXECUTE→PROJECT→COMPLETE ✅
• 错误分类：7 类（provider_rate_limited/timeout/unavailable/schema_validation/business_validation/reference_validation/cancelled/internal_error）✅
• 永久错误直接 markFailed：engine.ts:232-239 ✅
• retryable → unlockForRetry + throw：engine.ts:227-228 ✅
• attemptCount 原子递增：lifecycle-repo.ts:147 { increment: 1 } ✅
• 取消 3 检查点：执行前/Provider前/Projector前 ✅
• 通过 AiGatewayService 调用（非直接 Provider SDK）✅

---

11. Projector 与 Artifact 审核

• 事务内 projector.project(tx) + markSucceeded(tx)：projection-executor.service.ts:90-109 ✅
• 幂等：SyntheticResultProjector findMany 前置检查 ✅
• Artifact UNIQUE：@@unique([jobId, artifactType, artifactId]) ✅
• 无 Projector 路径调用 markSucceeded：projection-executor.service.ts:57,66 ✅

---

12. 取消与重试审核

• 用户取消 → lifecycleRepo.requestCancellation() ✅
• queued → markCancelled（直接）✅
• running → cancelRequestedAt 信号 ✅
• 终态幂等 → isTerminal check ✅
• Admin 重试 → 绕过 Registry + CreationService + 非原子 ❌（P1）

---

13. API、权限与安全审核

• JWT 隔离：job.userId !== userId → 403 ✅
• 公开响应不含 validatedOutput/internalErrorMessage/snapshot/credential：toPublicResponse:237 ✅
• Admin 响应包含 internalErrorMessage/validatedOutput：toAdminResponse:266-267 ✅
• 无明文密钥/Token/密码在代码中：全仓扫描确认 ✅

---

14. Synthetic E2E 审核

• 环境门控：NODE_ENV=test && AI_JOB_SYNTHETIC_ENABLED=true ✅
• 生产拒绝：assertNotProduction() ✅
• API 层测试：JWT 保护验证（401 without token）✅
• 完整链路 E2E：18/19 pending infra ⚠️

---

15. M-AI-01/M-AI-02 回归

• 全量单元测试：468/488 passed
• 2 个预存失败：queue-definitions.spec.ts（断言假定统一配置，但 ADR-003 引入 per-queue 差异）
• M-AI-01 Worker Integration：代码路径未修改（AiAnalysisWorker 保留）
• M-AI-02 backward compatibility：Migration 文件未修改，schema 仅加注释

---

16. CI 与部署门禁

• deploy.yml：包含 build-and-unit + current-integration + backward-compat + deploy
• M-AI-03 Synthetic E2E：测试文件存在（test/m-ai-03-synthetic.e2e-spec.ts），但 Workflow 未配置专门的 M-AI-03 E2E Job
• CI 阻断 deploy：deploy job 依赖 current-integration + backward-compat，但未依赖 M-AI-03 Synthetic E2E

无法确认：最新 CI run 结果（本地无 CI runner）

---

17. 问题列表

P1：已修正（commit 4915111）

ID	文件	修正
P1-01	ai-job.service.ts	Admin retry → creationService.createJob()：Registry 校验 + 原子 Job+Snapshot+Outbox + parentJobId + idempotencyKey

P2：已修正（commit 4915111）

ID	文件	修正
P2-01	queue-definitions.spec.ts	per-queue 断言适配 ADR-003（19/19 通过）
P2-02	.gitea/workflows/deploy.yml + test/jest-m-ai-03.json	CI m-ai-03-synthetic-e2e job 新增，deploy 依赖此 gate

P3：无需修正

ID	描述
—	无 P3 问题

---

18. 无法确认项

项目	缺失环境	是否阻断 PASS
真实 MySQL 事务测试	本地 MySQL	否（已有单元测试覆盖逻辑）
真实 Redis/BullMQ E2E	本地 Redis + BullMQ	否（已有单元测试覆盖逻辑）
Outbox 多实例并发	多进程环境	否（CAS 逻辑已验证）
Dispatcher 崩溃恢复	进程管理	否（releaseExpiredLocks 逻辑已验证）
CI Run 最新结果	CI Runner	否（Workflow YAML 已审查）
Admin retry 是否已绕过缺陷引入生产数据	需真实调用	是（P1-01 必须在进入 M-AI-04 前修正）

---

19. 复审确认（commit 4915111）

问题	修正	验证
P1-01 Admin retry 绕过	ai-job.service.ts：注入 AiJobCreationService + JobDefinitionRegistry，retryJob() → creationService.createJob() 完整链路	✅
P2-01 queue-definitions.spec.ts	per-queue 断言适配 ADR-003 差异配置	✅ 19/19
P2-02 CI E2E gate	deploy.yml 新增 m-ai-03-synthetic-e2e job（MySQL+Redis+E2E），deploy needs 增加依赖	✅
全量回归	23/23 suites pass，471/489（18 E2E skip = infra）	✅

20. 下一步建议

1. CI 环境就绪后：m-ai-03-synthetic-e2e job 自动执行 19 场景，通过后 deploy 解锁
2. PASS 已生效：允许进入 M-AI-04（Active Recall 端到端迁移）