[M-AI-03] 实现 Job Definition Registry 与注册校验 #287

New Issue

wangdl · 2026-06-20T16:43:30+08:00

wangdl commented

2026-06-20 16:43:30 +08:00

类型 / 标签

backend
architecture
registry

风险等级

P1

依赖

M-AI-03-02
M-AI-03-03

目标

建立可扩展 Job Definition Registry，替代未来的巨型 switch(jobType)。

Definition 必须声明

jobType
queueName
priority
attempts
backoff
timeoutMs
inputSchemaVersion
outputSchemaVersion
promptKey
promptVersion
modelTier
inputSchema
outputSchema
executor
businessValidator
referenceValidator
projector

Registry 要求

启动时注册；
Job Type 唯一；
未知 Job Type 拒绝；
Queue Name 必须在允许列表；
Schema Version 必须非空；
timeout 和 attempts 必须合法；
Projector 必须存在；
禁止运行时动态覆盖；
启动时输出已注册 Definition 清单。

依赖注入

使用明确的 Provider Token 或多 Provider 注册。

禁止：

单文件大 switch；
字符串拼接动态 import；
运行时扫描整个文件系统；
静默覆盖重复 Job Type。

非目标

不注册真实业务 Job Definition（仅 Synthetic）；
不实现 Execution Engine。

验收标准

重复注册导致启动失败
非法 Queue Name 导致启动失败
缺少 Schema 导致启动失败
未知 Job Type 执行时抛出明确错误
Registry 顺序稳定（多次启动同一顺序）
启动时输出已注册 Definition 清单
单元测试覆盖全部注册校验路径

## 类型 / 标签 - backend - architecture - registry ## 风险等级 P1 ## 依赖 - M-AI-03-02 - M-AI-03-03 ## 目标建立可扩展 Job Definition Registry，替代未来的巨型 `switch(jobType)`。 ## Definition 必须声明 ``` jobType queueName priority attempts backoff timeoutMs inputSchemaVersion outputSchemaVersion promptKey promptVersion modelTier inputSchema outputSchema executor businessValidator referenceValidator projector ``` ## Registry 要求 - 启动时注册； - Job Type 唯一； - 未知 Job Type 拒绝； - Queue Name 必须在允许列表； - Schema Version 必须非空； - timeout 和 attempts 必须合法； - Projector 必须存在； - 禁止运行时动态覆盖； - 启动时输出已注册 Definition 清单。 ## 依赖注入使用明确的 Provider Token 或多 Provider 注册。禁止： - 单文件大 switch； - 字符串拼接动态 import； - 运行时扫描整个文件系统； - 静默覆盖重复 Job Type。 ## 非目标 - 不注册真实业务 Job Definition（仅 Synthetic）； - 不实现 Execution Engine。 ## 验收标准 - [ ] 重复注册导致启动失败 - [ ] 非法 Queue Name 导致启动失败 - [ ] 缺少 Schema 导致启动失败 - [ ] 未知 Job Type 执行时抛出明确错误 - [ ] Registry 顺序稳定（多次启动同一顺序） - [ ] 启动时输出已注册 Definition 清单 - [ ] 单元测试覆盖全部注册校验路径

wangdl added this to the M-AI-03 统一 Job Engine、Registry 与 Outbox milestone 2026-06-20 16:44:54 +08:00

wangdl commented

2026-06-20 17:25:57 +08:00

开发完成评论

完成内容

JobDefinition 接口冻结（job-definition.types.ts）：对齐 ADR-003 §2.1，涵盖 queue/execution/input/output/prompt/model/credential/security
JobDefinitionRegistry（job-definition-registry.ts）：
- register(def): 启动时注册，全部校验 fail-fast，返回 Object.freeze
- get(jobType): 运行时查询，未注册抛出 UnknownJobTypeError
- getAll(): 返回注册顺序的 Definition 列表（Map 保持插入顺序）
- has(jobType): boolean 检查
- onModuleInit(): 空 Registry 输出 warn，已注册输出清单
10 类校验错误：
DuplicateJobType / UnknownJobType / InvalidJobType / InvalidQueueName /
MissingSchema / InvalidTimeout / InvalidRetries / InvalidCredentialMode /
InvalidPromptKey / MissingBackoff
校验覆盖：jobType 格式（6 边界）/ queueName 白名单 / schema 非空 / timeout[1000,600000] / maxRetries[0,10] / retryBackoff / credential allowedModes+defaultMode / metadata label+domain

修改文件

src/modules/ai-job/job-definition.types.ts（新增，96 行）
src/modules/ai-job/job-definition-registry.ts（新增，266 行）
src/modules/ai-job/job-definition-registry.spec.ts（新增，343 行）
src/modules/ai-job/ai-job.module.ts（更新，+2 providers）

测试情况

npx jest --testPathPatterns="ai-job" --no-coverage → 119/119 通过（4 suites）
TypeScript 编译：无错误

验收标准对照

重复注册导致启动失败 → DuplicateJobTypeError + 测试
非法 Queue Name 导致启动失败 → InvalidQueueNameError + 2 测试（非法+合法 each）
缺少 Schema 导致启动失败 → MissingSchemaError + 4 测试（input/output/promptKey/promptVersion）
未知 Job Type 抛出明确错误 → UnknownJobTypeError + 测试
Registry 顺序稳定 → getAll 返回 Map 插入顺序 + 测试
启动时输出已注册 Definition 清单 → onModuleInit + 2 测试（空+非空）
单元测试覆盖全部注册校验路径 → 43 测试，覆盖 10 类错误 + 全部合法性路径

是否建议进入 Review

是

## 开发完成评论 ### 完成内容 - **JobDefinition 接口冻结**（`job-definition.types.ts`）：对齐 ADR-003 §2.1，涵盖 queue/execution/input/output/prompt/model/credential/security - **JobDefinitionRegistry**（`job-definition-registry.ts`）： - `register(def)`: 启动时注册，全部校验 fail-fast，返回 Object.freeze - `get(jobType)`: 运行时查询，未注册抛出 UnknownJobTypeError - `getAll()`: 返回注册顺序的 Definition 列表（Map 保持插入顺序） - `has(jobType)`: boolean 检查 - `onModuleInit()`: 空 Registry 输出 warn，已注册输出清单 - **10 类校验错误**： DuplicateJobType / UnknownJobType / InvalidJobType / InvalidQueueName / MissingSchema / InvalidTimeout / InvalidRetries / InvalidCredentialMode / InvalidPromptKey / MissingBackoff - **校验覆盖**：jobType 格式（6 边界）/ queueName 白名单 / schema 非空 / timeout[1000,600000] / maxRetries[0,10] / retryBackoff / credential allowedModes+defaultMode / metadata label+domain ### 修改文件 - `src/modules/ai-job/job-definition.types.ts`（新增，96 行） - `src/modules/ai-job/job-definition-registry.ts`（新增，266 行） - `src/modules/ai-job/job-definition-registry.spec.ts`（新增，343 行） - `src/modules/ai-job/ai-job.module.ts`（更新，+2 providers） ### 测试情况 - `npx jest --testPathPatterns="ai-job" --no-coverage` → **119/119 通过**（4 suites） - TypeScript 编译：无错误 ### 验收标准对照 - [x] 重复注册导致启动失败 → DuplicateJobTypeError + 测试 - [x] 非法 Queue Name 导致启动失败 → InvalidQueueNameError + 2 测试（非法+合法 each） - [x] 缺少 Schema 导致启动失败 → MissingSchemaError + 4 测试（input/output/promptKey/promptVersion） - [x] 未知 Job Type 抛出明确错误 → UnknownJobTypeError + 测试 - [x] Registry 顺序稳定 → getAll 返回 Map 插入顺序 + 测试 - [x] 启动时输出已注册 Definition 清单 → onModuleInit + 2 测试（空+非空） - [x] 单元测试覆盖全部注册校验路径 → 43 测试，覆盖 10 类错误 + 全部合法性路径 ### 是否建议进入 Review - 是

wangdl closed this issue

2026-06-21 12:37:50 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#287