wangdl/api-server
2
0
Fork 0
Code Issues 28 Pull Requests Actions Packages Projects Releases Wiki Activity

[M-AI-04-08-GATE] Active Recall 统一 Job Engine 迁移验收与切换 #303

New Issue
Closed
opened 2026-06-21 12:48:14 +08:00 by wangdl · 2 comments
wangdl commented 2026-06-21 12:48:14 +08:00
Owner
Copy Link

类型 / 标签

  • gate
  • active-recall
  • release
  • migration

风险等级

P0

依赖

  • M-AI-04-01 至 M-AI-04-07（全部 Issue）

背景

汇总 M-AI-04 所有验收项，独立审核迁移是否达到生产标准，并决定是否停止旧链路接收新 Active Recall 请求。

目标

  1. 独立审核 Active Recall 迁移各项门禁
  2. 输出 PASS / CONDITIONAL PASS / FAIL 最终结论

审核范围

迁移契约

  • HTTP 契约保持兼容
  • 输入、输出与旧业务语义一致
  • 幂等键稳定
  • 状态映射明确
  • 回滚流程可执行

Definition

  • 注册信息完整
  • Snapshot 最小且可重放
  • 无敏感信息
  • 生产环境 Definition 正常注册

Executor

  • 仅通过 AiGateway
  • 无数据库副作用
  • AbortSignal 生效
  • 输出验证完整
  • 错误分类正确

Projector

  • 原子 / 幂等
  • Artifact 完整
  • 重复消费安全
  • 失败无部分结果

入口

  • Legacy 和 Unified 分支明确
  • 不存在双执行
  • Unified 通过 CreationService
  • 无 Controller 直接入队
  • 无自动 Legacy fallback

真实运行

必须看到真实链路：HTTP → MySQL → Outbox → Redis/BullMQ → Worker → Engine → Projector → Active Recall Result

CI

  • Active Recall E2E 实际运行
  • 不是 0s / 不是 skipped
  • 基础设施故障时失败
  • 失败阻止 Deploy

回归

继续通过：M-AI-01 Worker Integration / M-AI-01 HTTP E2E / M-AI-02 backward compatibility / M-AI-03 单元与架构测试 / Active Recall Legacy E2E / Active Recall Unified E2E

切换策略

分阶段：

  1. 仅测试环境 Unified
  2. 生产测试用户白名单
  3. 少量用户
  4. 默认 Unified
  5. 停止 Legacy 接收新请求

不得在没有运行证据时直接全量切换。

问题分级

  • P0: 数据丢失、跨用户访问、重复扣费或重复业务结果、敏感信息泄露、无法回滚
  • P1: Projector 非原子、幂等失效、双执行、状态查询不兼容、新链路绕过 CreationService、真实 E2E 未执行
  • P2: 日志字段缺失、Admin 可观测性不足、少量非核心错误场景未覆盖
  • P3: 深度故障恢复、压力测试、旧代码清理、性能优化

最终结论

只能选择：PASS / CONDITIONAL PASS / FAIL

  • PASS: 允许默认启用 Unified、停止 Legacy 接收新请求、进入 M-AI-05
  • CONDITIONAL PASS: 只允许测试环境/白名单用户/小范围验证，不得全量切换
  • FAIL: 回退到 Legacy，修复 P0/P1 后重新审核

PASS 后进入

M-AI-05：Feynman 与复习产物迁移

完成证据

必须提供：Commit 范围、迁移契约、Definition、Snapshot 示例、Redis Payload、HTTP 请求响应、Outbox 记录、BullMQ Job、Worker 日志、Projector 事务、Artifact、幂等结果、Feature Flag 切换、回滚记录、CI Run、最终 Gate 报告

验收标准

  • 迁移契约门禁全部通过
  • Definition 门禁全部通过
  • Executor 门禁全部通过
  • Projector 门禁全部通过
  • 入口门禁全部通过
  • 真实运行链路验证通过
  • CI 门禁全部通过
  • 回归门禁全部通过
  • 所有 P0/P1 问题已修复
  • 输出最终 Gate 报告（PASS / CONDITIONAL PASS / FAIL）

建议执行顺序

第 8 个执行（M-AI-04 最终门禁）

## 类型 / 标签 - gate - active-recall - release - migration ## 风险等级 P0 ## 依赖 - M-AI-04-01 至 M-AI-04-07（全部 Issue） ## 背景 汇总 M-AI-04 所有验收项，独立审核迁移是否达到生产标准，并决定是否停止旧链路接收新 Active Recall 请求。 ## 目标 1. 独立审核 Active Recall 迁移各项门禁 2. 输出 PASS / CONDITIONAL PASS / FAIL 最终结论 ## 审核范围 ### 迁移契约 - HTTP 契约保持兼容 - 输入、输出与旧业务语义一致 - 幂等键稳定 - 状态映射明确 - 回滚流程可执行 ### Definition - 注册信息完整 - Snapshot 最小且可重放 - 无敏感信息 - 生产环境 Definition 正常注册 ### Executor - 仅通过 AiGateway - 无数据库副作用 - AbortSignal 生效 - 输出验证完整 - 错误分类正确 ### Projector - 原子 / 幂等 - Artifact 完整 - 重复消费安全 - 失败无部分结果 ### 入口 - Legacy 和 Unified 分支明确 - 不存在双执行 - Unified 通过 CreationService - 无 Controller 直接入队 - 无自动 Legacy fallback ### 真实运行 必须看到真实链路：HTTP → MySQL → Outbox → Redis/BullMQ → Worker → Engine → Projector → Active Recall Result ### CI - Active Recall E2E 实际运行 - 不是 0s / 不是 skipped - 基础设施故障时失败 - 失败阻止 Deploy ### 回归 继续通过：M-AI-01 Worker Integration / M-AI-01 HTTP E2E / M-AI-02 backward compatibility / M-AI-03 单元与架构测试 / Active Recall Legacy E2E / Active Recall Unified E2E ## 切换策略 分阶段： 1. 仅测试环境 Unified 2. 生产测试用户白名单 3. 少量用户 4. 默认 Unified 5. 停止 Legacy 接收新请求 不得在没有运行证据时直接全量切换。 ## 问题分级 - **P0**: 数据丢失、跨用户访问、重复扣费或重复业务结果、敏感信息泄露、无法回滚 - **P1**: Projector 非原子、幂等失效、双执行、状态查询不兼容、新链路绕过 CreationService、真实 E2E 未执行 - **P2**: 日志字段缺失、Admin 可观测性不足、少量非核心错误场景未覆盖 - **P3**: 深度故障恢复、压力测试、旧代码清理、性能优化 ## 最终结论 只能选择：**PASS** / **CONDITIONAL PASS** / **FAIL** - PASS: 允许默认启用 Unified、停止 Legacy 接收新请求、进入 M-AI-05 - CONDITIONAL PASS: 只允许测试环境/白名单用户/小范围验证，不得全量切换 - FAIL: 回退到 Legacy，修复 P0/P1 后重新审核 ## PASS 后进入 M-AI-05：Feynman 与复习产物迁移 ## 完成证据 必须提供：Commit 范围、迁移契约、Definition、Snapshot 示例、Redis Payload、HTTP 请求响应、Outbox 记录、BullMQ Job、Worker 日志、Projector 事务、Artifact、幂等结果、Feature Flag 切换、回滚记录、CI Run、最终 Gate 报告 ## 验收标准 - [ ] 迁移契约门禁全部通过 - [ ] Definition 门禁全部通过 - [ ] Executor 门禁全部通过 - [ ] Projector 门禁全部通过 - [ ] 入口门禁全部通过 - [ ] 真实运行链路验证通过 - [ ] CI 门禁全部通过 - [ ] 回归门禁全部通过 - [ ] 所有 P0/P1 问题已修复 - [ ] 输出最终 Gate 报告（PASS / CONDITIONAL PASS / FAIL） ## 建议执行顺序 第 8 个执行（M-AI-04 最终门禁）
wangdl added this to the M-AI-04 Active Recall 端到端迁移 milestone 2026-06-21 12:48:14 +08:00
wangdl commented 2026-06-21 15:16:21 +08:00
Author
Owner
Copy Link

GATE 审核完成

结论: CONDITIONAL PASS

审核范围

门禁 验收项数 通过 风险
迁移契约 5 5 0
Definition 4 4 0
Executor 5 5 0
Projector 5 5 0
入口 5 5 0
真实运行 — ⚠️ 需 CI Docker
CI 4 3 Worker test 已知超时
回归 255 tests 255 0

P0/P1 追踪

  • 1 P0 已修复（跨用户所有权）
  • 6 P1 已归档（0 阻塞 Unified 测试环境启用）

条件

  1. 仅测试环境启用 Unified
  2. 生产默认 Legacy
  3. CI Docker 就绪后可升级为 PASS

Gate 报告

docs/architecture/m-ai-04-gate-audit.md

Commit 范围

b7cafbb..4447569 (26 files, +3535/-37)

## GATE 审核完成 ### 结论: **CONDITIONAL PASS** ### 审核范围 | 门禁 | 验收项数 | 通过 | 风险 | |------|----------|------|------| | 迁移契约 | 5 | 5 | 0 | | Definition | 4 | 4 | 0 | | Executor | 5 | 5 | 0 | | Projector | 5 | 5 | 0 | | 入口 | 5 | 5 | 0 | | 真实运行 | — | ⚠️ | 需 CI Docker | | CI | 4 | 3 | Worker test 已知超时 | | 回归 | 255 tests | 255 | 0 | ### P0/P1 追踪 - 1 P0 已修复（跨用户所有权） - 6 P1 已归档（0 阻塞 Unified 测试环境启用） ### 条件 1. 仅测试环境启用 Unified 2. 生产默认 Legacy 3. CI Docker 就绪后可升级为 PASS ### Gate 报告 `docs/architecture/m-ai-04-gate-audit.md` ### Commit 范围 `b7cafbb..4447569` (26 files, +3535/-37)
wangdl commented 2026-06-21 15:29:45 +08:00
Author
Owner
Copy Link

BATCH-02 完成报告

结论: BATCH-02 PASS

1. 变更范围

文件 变更
src/worker.module.ts +AiJobModule import (P1-01)
src/modules/ai-job/ai-job-execution-engine.ts PROJECT phase try-catch + incrementProjectorFailed (P1-02)
test/m-ai-04-active-recall.e2e-spec.ts fail() → throw new Error() (P2-01)

2. 观测接入点

事件 位置 方法 状态
Job 创建成功 ActiveRecallService.submit() logJobCreated + incrementUnifiedRequests ✅
Job 创建失败 ActiveRecallService.submit() catch logJobCreateFailed + incrementUnifiedCreateFailed ✅
执行成功 Engine COMPLETE phase incrementUnifiedExecuteSuccess + logExecutionCompleted ✅
执行失败 Engine catch block incrementUnifiedExecuteFailed + logExecutionFailed ✅
重试 Engine catch (retryable) incrementUnifiedRetry ✅
Projector 失败 Engine PROJECT try-catch incrementProjectorFailed ✅ NEW

3. E2E Fail-Closed 修复

检查项 行为
MySQL 不可用 throw new Error() → 11 failed
Redis 不可用 checkInfra() → throw → 11 failed
禁止 soft-pass 无 return/continue/|| true

4. Unified Job 状态证据

P1-01 修复后，Worker 可通过 AiJobModule 解析 AI_JOB_EXECUTION_ENGINE：

  • WorkerModule.imports 包含 AiJobModule
  • AiJobModule 提供 AI_JOB_EXECUTION_ENGINE token
  • AiInteractiveJobWorker 的 @Optional() @Inject(AI_JOB_EXECUTION_ENGINE) 解析成功
  • Worker 不再静默跳过 Unified Job (:43-49 不再触发)

5. Legacy 回归

  • AiAnalysisWorker 未修改
  • AiAnalysisService.analyze() 未修改
  • active-recall.service.ts Legacy 分支未修改

6. 测试结果

npm run build: PASS
npm test (ai-job+active-recall): 13 suites, 255 passed, 0 failed
E2E (no infra): 11 failed (correct hard-fail)

7. 结论

BATCH-02 PASS

  • P1-01: Worker 可执行 Unified Job ✅
  • P1-02: 全观测覆盖（create/execute/retry/fail/projector）✅
  • P2-01: E2E fail-closed ✅
  • Legacy 回归 0 失败 ✅
  • 无 Schema/DB 变更 ✅
## BATCH-02 完成报告 ### 结论: BATCH-02 PASS --- ### 1. 变更范围 | 文件 | 变更 | |------|------| | `src/worker.module.ts` | +AiJobModule import (P1-01) | | `src/modules/ai-job/ai-job-execution-engine.ts` | PROJECT phase try-catch + incrementProjectorFailed (P1-02) | | `test/m-ai-04-active-recall.e2e-spec.ts` | fail() → throw new Error() (P2-01) | --- ### 2. 观测接入点 | 事件 | 位置 | 方法 | 状态 | |------|------|------|:---:| | Job 创建成功 | ActiveRecallService.submit() | logJobCreated + incrementUnifiedRequests | ✅ | | Job 创建失败 | ActiveRecallService.submit() catch | logJobCreateFailed + incrementUnifiedCreateFailed | ✅ | | 执行成功 | Engine COMPLETE phase | incrementUnifiedExecuteSuccess + logExecutionCompleted | ✅ | | 执行失败 | Engine catch block | incrementUnifiedExecuteFailed + logExecutionFailed | ✅ | | 重试 | Engine catch (retryable) | incrementUnifiedRetry | ✅ | | Projector 失败 | Engine PROJECT try-catch | incrementProjectorFailed | ✅ NEW | --- ### 3. E2E Fail-Closed 修复 | 检查项 | 行为 | |--------|------| | MySQL 不可用 | throw new Error() → 11 failed | | Redis 不可用 | checkInfra() → throw → 11 failed | | 禁止 soft-pass | 无 return/continue/\|\| true | --- ### 4. Unified Job 状态证据 P1-01 修复后，Worker 可通过 AiJobModule 解析 AI_JOB_EXECUTION_ENGINE： - `WorkerModule.imports` 包含 `AiJobModule` - `AiJobModule` 提供 `AI_JOB_EXECUTION_ENGINE` token - `AiInteractiveJobWorker` 的 `@Optional() @Inject(AI_JOB_EXECUTION_ENGINE)` 解析成功 - Worker 不再静默跳过 Unified Job (`:43-49` 不再触发) --- ### 5. Legacy 回归 - `AiAnalysisWorker` 未修改 - `AiAnalysisService.analyze()` 未修改 - `active-recall.service.ts` Legacy 分支未修改 --- ### 6. 测试结果 ``` npm run build: PASS npm test (ai-job+active-recall): 13 suites, 255 passed, 0 failed E2E (no infra): 11 failed (correct hard-fail) ``` --- ### 7. 结论 **BATCH-02 PASS** - P1-01: Worker 可执行 Unified Job ✅ - P1-02: 全观测覆盖（create/execute/retry/fail/projector）✅ - P2-01: E2E fail-closed ✅ - Legacy 回归 0 失败 ✅ - 无 Schema/DB 变更 ✅
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
adr
Area: adr
architecture
Area: architecture
area:activity
活动/统计
area:admin
管理后台
area:admin-api
area:ai
AI/RAG
area:ai-runtime
AI Runtime / AI 分析体系相关
area:analytics
area:api
API 接口
area:auth
认证与授权
area:cos
对象存储
area:database
数据库/Migration
area:import
文件导入/解析
area:knowledge
知识库/知识点
area:learning-info
area:learning-session
area:quiz
测验/自测
area:reading-event
area:reading-progress
area:review
复习系统
area:security
安全相关
audit
Area: audit
audit:api-admin-info
audit:api-info
audit:planned
已完成宏观规划，尚未代码审查
audit:reviewed
backend
Area: backend
billing
Area: billing
blocked-by:api-info-aggregation
blocked-by:api-info-core
blocked-by:api-info-ops
blocked-by:api-info-schema
blocked-by:processor
blocked-by:schema
compatibility
Area: compatibility
gate
Area: gate
infrastructure
Area: infrastructure
priority:p0
最高优先级，阻塞发布
priority:p1
高优先级，里程碑必需
priority:p2
中优先级，后续版本
prisma
Area: prisma
release
Area: release
repo:api
API 仓库 Issue
status:blocked
被阻塞
status:done
已完成
status:partial
status:todo
type:aggregation
type:bug
缺陷修复
type:design
设计
type:docs
文档
type:feature
新功能
type:migration
type:refactor
重构
type:test
work:admin-api
work:aggregation
work:api
work:artifact
题目/卡片产物
work:audit
work:circuit-breaker
熔断
work:contract
work:design
架构/协议设计工作
work:docs
work:export
work:extend-existing
work:internal-api
Runtime 内部接口
work:job
Job 调度相关
work:new-module
work:new-table
work:ops
work:query
work:quota
额度/限流
work:schema
Prisma Schema 设计
work:security
work:service
Service 层实现
work:snapshot
Snapshot 构建
work:test
No Label
Milestone
No items
No Milestone M-AI-04 Active Recall 端到端迁移
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#303
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?