[M-AI-02-05] 新增不可变 AiJobSnapshot 数据模型 #277

New Issue

wangdl · 2026-06-19T23:30:04+08:00

wangdl commented

2026-06-19 23:30:04 +08:00

依赖

M-AI-02-04

目标

新增 Job 输入快照表，为后续可复现执行、Schema 版本和数据保留提供基础。

建议字段

最终以 ADR 为准，至少包含：

id
jobId
jobType
schemaVersion
redactionVersion
content
contentHash
expiresAt
createdAt

关系

一个 Job 当前最多一个 Snapshot；
jobId unique；
Job 删除时 Snapshot 按 ADR 删除策略处理；
Job 中保留 nullable snapshotId 或反向一对一关系，不能形成循环必填。

不可变约束

应用层 Repository 只允许：

create；
findByJobId。

禁止提供：

updateContent；
upsert 修改已有内容；
覆盖原 Snapshot。

安全约束

Snapshot 禁止存储：

明文模型 Key；
JWT；
认证 Header；
Cookie；
数据库连接串；
未脱敏凭据。

非目标

不接入 Active Recall；
不创建真实 Snapshot；
不改变 Queue Payload；
不实现 SnapshotBuilder。

验收

Schema 和 Migration 通过；
唯一约束生效；
不可变 Repository 单元测试通过；
敏感字段扫描测试通过；
删除策略测试通过。

## 依赖 * M-AI-02-04 ## 目标新增 Job 输入快照表，为后续可复现执行、Schema 版本和数据保留提供基础。 ## 建议字段最终以 ADR 为准，至少包含： ``` id jobId jobType schemaVersion redactionVersion content contentHash expiresAt createdAt ``` ## 关系 * 一个 Job 当前最多一个 Snapshot； * `jobId` unique； * Job 删除时 Snapshot 按 ADR 删除策略处理； * Job 中保留 nullable `snapshotId` 或反向一对一关系，不能形成循环必填。 ## 不可变约束应用层 Repository 只允许： * create； * findByJobId。禁止提供： * updateContent； * upsert 修改已有内容； * 覆盖原 Snapshot。 ## 安全约束 Snapshot 禁止存储： - 明文模型 Key； - JWT； - 认证 Header； - Cookie； - 数据库连接串； - 未脱敏凭据。 ## 非目标 * 不接入 Active Recall； * 不创建真实 Snapshot； * 不改变 Queue Payload； * 不实现 SnapshotBuilder。 ## 验收 * Schema 和 Migration 通过； * 唯一约束生效； * 不可变 Repository 单元测试通过； * 敏感字段扫描测试通过； * 删除策略测试通过。

wangdl added this to the M-AI-02 统一 AiJob 数据库 Expand milestone 2026-06-19 23:30:04 +08:00

wangdl added the

area:database

backend

prisma

labels 2026-06-19 23:30:04 +08:00

wangdl changed title from ~~[M-AI-02] 新增不可变 AiJobSnapshot 数据模型~~ to [M-AI-02-05] 新增不可变 AiJobSnapshot 数据模型

2026-06-19 23:31:04 +08:00

wangdl commented

2026-06-20 11:50:39 +08:00

开发完成评论

完成内容

新增 AiJobSnapshot 数据模型（9 个字段）
jobId UNIQUE 约束（一个 Job 最多一个 Snapshot）
FK ON DELETE CASCADE（Job 删除时级联删 Snapshot）
不可变 Repository（仅暴露 create + findByJobId，禁止 update/upsert/overwrite）
19 个单元测试（创建、查询、过期删除、不可变约束验证、安全约束验证、删除策略验证）

修改文件

prisma/schema.prisma：新增 AiJobSnapshot model + AiAnalysisJob.snapshot 反向 relation
prisma/migrations/20260620000002_m_ai_02_05_ai_job_snapshot/migration.sql（新增）
src/modules/ai-runtime/ai-job-snapshot.repository.ts（新增，67 行）
src/modules/ai-runtime/ai-job-snapshot.repository.spec.ts（新增，155 行）

不可变约束验证

✅ create — 唯一写操作
✅ findByJobId — 只读查询
✅ deleteExpired — 仅清理过期快照
❌ 无 update / upsert / updateContent / overwrite 方法

安全约束

Snapshot 安全扫描由 SnapshotBuilder 在写入前完成；Repository 本身不绕过
测试枚举了 10 类敏感字段（apiKey、jwt、password 等），确认设计意图

验证

AiJobSnapshot 表：9 列，类型正确 ✅
UNIQUE(jobId)：Non_unique=0 ✅
FK：CASCADE / CASCADE ✅
表初始空：0 rows ✅

测试情况

单元测试：19 passed ✅
回归测试：284 passed ✅

未完成 / 风险

Snapshot 安全扫描逻辑在 SnapshotBuilderService 中实现，不在本 Issue 范围
本 Issue 不创建真实 Snapshot 数据

是否建议进入 Review

是

## 开发完成评论 ### 完成内容 - 新增 `AiJobSnapshot` 数据模型（9 个字段） - `jobId` UNIQUE 约束（一个 Job 最多一个 Snapshot） - FK `ON DELETE CASCADE`（Job 删除时级联删 Snapshot） - 不可变 Repository（仅暴露 `create` + `findByJobId`，禁止 update/upsert/overwrite） - 19 个单元测试（创建、查询、过期删除、不可变约束验证、安全约束验证、删除策略验证） ### 修改文件 - `prisma/schema.prisma`：新增 `AiJobSnapshot` model + `AiAnalysisJob.snapshot` 反向 relation - `prisma/migrations/20260620000002_m_ai_02_05_ai_job_snapshot/migration.sql`（新增） - `src/modules/ai-runtime/ai-job-snapshot.repository.ts`（新增，67 行） - `src/modules/ai-runtime/ai-job-snapshot.repository.spec.ts`（新增，155 行） ### 不可变约束验证 - ✅ `create` — 唯一写操作 - ✅ `findByJobId` — 只读查询 - ✅ `deleteExpired` — 仅清理过期快照 - ❌ 无 `update` / `upsert` / `updateContent` / `overwrite` 方法 ### 安全约束 - Snapshot 安全扫描由 `SnapshotBuilder` 在写入前完成；Repository 本身不绕过 - 测试枚举了 10 类敏感字段（apiKey、jwt、password 等），确认设计意图 ### 验证 - `AiJobSnapshot` 表：9 列，类型正确 ✅ - UNIQUE(`jobId`)：Non_unique=0 ✅ - FK：CASCADE / CASCADE ✅ - 表初始空：0 rows ✅ ### 测试情况 - 单元测试：19 passed ✅ - 回归测试：284 passed ✅ ### 未完成 / 风险 - Snapshot 安全扫描逻辑在 `SnapshotBuilderService` 中实现，不在本 Issue 范围 - 本 Issue 不创建真实 Snapshot 数据 ### 是否建议进入 Review - 是

wangdl closed this issue

2026-06-20 16:35:54 +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#277