lingxi/docs/开发计划/灵犀_信息流素材生产平台_开发计划_V0.1.md

# 灵犀 · 信息流素材生产平台 项目开发计划

> **文档定位**：把 PRD V1.6 与《技术架构》V0.4 翻译成**可执行、可并行、可验收**的开发计划。
> **不替代上游**：需求口径以 PRD 为准，技术选型与硬约束以技术架构和 [`AGENTS.md`](../../AGENTS.md) 为准；本文件只回答"先做什么、做到什么程度、前后端怎么并行、怎么验收"。

## 0　文档信息与使用说明

| 项 | 内容 |
| --- | --- |
| 文档名称 | 灵犀 · 信息流素材生产平台 项目开发计划 |
| 版本 | V0.1（初稿，待评审） |
| 日期 | 2026-11-02 |
| 状态 | **执行中**：A0 工程骨架与契约基线已完成（2026-11-02）；A1 身份认证与用户管理已完成（2026-11-03）；A2 角色权限与数据范围已完成（2026-11-03）；A3 客户与行业目录已完成（2026-11-04 最终验收）；A4 数据字典与系统配置已完成（2026-11-04）；下一步 A5 |
| 需求基线 | PRD V1.6（[灵犀-信息流广告素材一站式生产平台PRD.md](../PRD/灵犀-信息流广告素材一站式生产平台PRD.md)） |
| 技术基线 | 技术架构 V0.4（[灵犀_信息流素材生产平台_技术架构_V0.1.md](../技术架构/灵犀_信息流素材生产平台_技术架构_V0.1.md)）+ `AGENTS.md` V1.0 + `docs/工程规范/` V1.0 |
| 覆盖范围 | **M0 任务级；M1–M4 迭代级 + 任务组级；M5 预研边界（不排期）** |
| 读者 | 产品 / 技术负责人、Harness 编队、测试、运维 |
| 维护 | 每批结束回写实际工期与偏差；范围变更同步 §5 与 §13 |

### 0.1　版本记录

| 版本 | 日期 | 修订内容 |
| --- | --- | --- |
| V0.1 | 2026-11-02 | 初稿：全项目 M0–M4 开发计划（M0 十二批次任务级 WBS；M1–M4 迭代 + 任务组 WBS；M5 预研边界）、七个管理模块专项、前后端并行与联调机制、质量门禁、风险与验收、待确认事项 |
| V0.1（进度回写） | 2026-11-02 | A0 工程骨架与契约基线完成：批次总览增加状态列、A0 WBS 标注完成、回写执行证据与偏差；不改变原计划范围与验收口径 |
| V0.1（进度回写 A1） | 2026-11-03 | A1 身份认证与用户管理完成：批次总览更新 A1 状态、A1 WBS 标注完成、回写执行证据与遗留；不改变原计划范围与验收口径 |
| V0.1（路由规范回写） | 2026-11-03 | 「平台」更名「管理中心」，前端路由统一为 `/<模块>/<功能>`（A1 用户页改为 `/system/users`）；同步附录 C 页面清单与前端目录约定，不改变功能范围与验收口径 |
| V0.1（A1 部门管理补强） | 2026-11-03 | 补 `/system/departments` 部门管理：WBS 增 A1-BE-05 / A1-FE-04，补页面与接口清单；只停用不删除、有成员/启用子部门禁止停用；不改变其它批次范围 |
| V0.1（进度回写 A4） | 2026-11-04 | A4 数据字典与系统配置完成：批次总览更新 A4 状态、A4 WBS 标注完成、回写门禁与 e2e；权限按 A2 定稿统一 `dict:manage`，新增 `system_config_versions`；不改变原计划范围与验收口径 |

### 0.2　引用约定

| 记号 | 来源 | 含义 |
| --- | --- | --- |
| `R-01` ~ `R-30` | PRD §6 | 跨模块业务规则，实现注释必须带编号 |
| `P-01` ~ `P-18` | PRD §5.4.10 | 平台管理功能编号 |
| `S-xx` / `M-xx` / `A-xx` / `E-xx` | PRD §5.1 / §5.2 / §5.3 / §5.5 | 脚本 / 素材 / 资产 / 导出的功能编号 |
| `Q-01` ~ `Q-32` | PRD §10 | 需求侧待确认问题 |
| `T0` ~ `T3` | 技术架构 §10.2 | 技术交付里程碑（本文按 PRD 的 M0–M4 表述，括号标注对应 T 阶段） |
| `D-01` ~ `D-11` | 技术架构 §8 | 架构决策 |
| `R-T-xx` / `QT-xx` | 技术架构 §11 | 技术风险 / 技术侧待确认 |
| `AS-xx` | 本文件 §0.3 | 计划假设（已按此排期，推翻需重排） |
| `DP-xx` | 本文件 §13 | 计划侧待确认（需要人类决策） |
| `A0` ~ `B3` | 本文件 §5.2 | M0 开发批次编号 |
| `G0` ~ `G5` | 本文件 §10.1 | 每批质量门禁；`H0` ~ `H5` 为 §3.4 的人工决策门 |

### 0.3　计划假设（AS）

| 编号 | 假设 | 依据 / 影响 |
| --- | --- | --- |
| AS-01 | 开发全程由 **DeepSeek Harness 编队**执行：1 名 Lead + 最多 3 名并行 Worker + 独立 Verifier；人类负责范围、口径、验收与发布决策 | 用户明确要求；排期以"批次 + 相对周次"表达，不承诺绝对日期 |
| AS-02 | 工量单位用**等效人日（EPD）**，沿用技术架构 §10.2 的"净开发"口径；编队净产能按 **3.0 EPD/工作日**、缓冲 **25%** 估算 | §10.2 的人日口径可直接对齐；产能系数每批校准 |
| AS-03 | M0 登录先做**账号密码 + JWT**，SSO 只留适配器接口 | 对应 `QT-04`；SSO 协议未定（`Q-10`） |
| AS-04 | M0 的 AI 只做**配置底座 + 调用账本 + Mock Provider**，不接真实计费模型 | 供应商、预算未定（`QT-05` / `Q-09`） |
| AS-05 | M0 只要求**本地 Docker Compose + 1 台 staging** 可用；云厂商与域名在 M1 前确认 | `QT-01` / `QT-03`，备案需提前 2–3 周 |
| AS-06 | **"任务管理"= 跨模块异步任务中心**：统一任务协议、进度（SSE + 轮询）、失败重试、取消、队列健康；不改变各模块任务语义 | 技术架构 §6.4；`media_tasks` 同时承载脚本任务 |
| AS-07 | **"日志管理"= 审计日志中心（业务留痕） + 运行日志观测入口**；运行日志（Pino/OTel）不入业务库 | PRD §5.4.6；架构 §2.7 / 工程规范 08 |
| AS-08 | M0 范围按 PRD §7 的 M0 清单（含行业包、表单设计器、合规规则集、资产最小集、要素卡/脚本模板、导出骨架），**不含**脚本生成与图片生产 | PRD §7；这两项属 M1 |
| AS-09 | UI 以 **Semi Design 组件与交互为基线**，M0 不单独出视觉稿；页面走查用 staging 演示数据完成 | 减少设计依赖；如要求品牌化视觉需另排 |
| AS-10 | 每批默认**前端 Mock 先行 + 后端契约先行**，联调固定在批次第 3–4 日；不等待整批后端完成才启动前端 | 前后端同时开发的核心机制 |
| AS-11 | 本计划覆盖**全项目 M0–M4**：M0 任务级，M1–M4 迭代级 + 任务组级；**M5 为预研，不排期**，只在 §5.9 给进入条件 | PRD §7 分期；用户 2026-11-02 确认「补全所有开发计划，从 M0 到完整结束」 |

> **推翻任一假设的代价**：AS-03 / AS-04 / AS-05 只影响对应批次的实现细节；AS-01 / AS-02 影响全部排期；AS-06 / AS-07 影响 §7 两个模块的范围定义；AS-08 影响 M0 的边界与工期（见 §2.5）。

### 0.4　与既有文档的关系

| 文档 | 关系 | 本文件如何引用 |
| --- | --- | --- |
| PRD V1.6 | 需求唯一来源 | 功能编号、优先级、业务规则、验收标准（AC-01~AC-04）直接引用，不复制口径 |
| 技术架构 V0.4 | 技术与数据唯一来源 | 模块边界、表清单、接口清单、任务协议、部署与观测直接作为任务卡约束 |
| `AGENTS.md` | 硬约束与索引 | §3 硬红线、§5 仓库结构、§6 命令契约是每批门禁的判定依据 |
| `docs/工程规范/` | 落地细则 | Git、API、数据库、测试、日志、密钥、资产命名的检查项进入 §10 门禁 |
| 立项建议 V0.1 | 背景与商业论证 | 只引用分期周期与人力建议做交叉校验，不约束实现 |

---

## 1　计划摘要（一页看懂）

### 1.1　一句话

**先用 6–7 周把"人、角色、客户、字典、日志、任务、AI 配置、行业包"这套地基立住（M0），再用 4–5 周跑通"要素卡 → 脚本 → 图片 → 导出"（M1）；接着 5–6 周上视频线、快筛与 AI 治理（M2），4–5 周做资产复用、送审与效果回流（M3），最后 1–2 周把投放数据、爆量判定与脚本反哺收口（M4，项目交付闭环）。M5（AI 素材生产预研）不在本期排期。全程前后端同批并行、契约先行、每批可演示。**

### 1.2　关键结论

| 阶段 | 范围 | 净工量（EPD） | 参考日历 | 退出标准（摘要） |
| --- | --- | --- | --- | --- |
| **M0 地基**（T0 + M0 增量） | 工程骨架、身份权限、客户行业、字典配置、审计日志、任务中心、AI 配置、行业包与表单设计器、资产最小集、要素卡/脚本模板、导出骨架 | 65–70 | 6–7 周（30–35 个工作日） | 新客户 10 分钟内完成建档与权限分配；电商行业包 v1 可配置、可发布；空任务可提交并看到进度；审计可查 |
| **M1 主链路** | 脚本生成 / 解析 / 校核 / 审核入库 / 编号、图片线（PSD 套版 + 抠图 + 多规格）、预览勾选、导出与归档、金融行业包 v1 试跑 | 48–56 | 4–5 周（20–25 个工作日） | AC-01：1 个真实客户走通"要素卡 → 脚本 → 图片 → 导出"；交付周期与单条成本首次可测 |
| **M2 提效** | 视频逐镜生成 / 拼接 / 校验、快筛、变体矩阵、脚本版本与交付包、AI 路由与额度、成本看板、成片入库与复用、第三行业包 | 62–70 | 5–6 周（25–30 个工作日） | 单条视频从脚本到成片跑通；成本可查；任务成功率 ≥ 98% |
| **M3 复用** | 资产复用度量、效果标签、混合实拍与口播、成片入库与素材库、送审与效果回流、SSO / 系统配置完善 | 45（40–50） | 4–5 周 | 资产复用率 ≥ 60%；新客户冷启动 ≤ 1 个工作日；素材关联率与日指标可测 |
| **M4 交付闭环** | 投放登记完善、日指标、爆量判定与阈值固化、脚本权重反哺、关联率与爆量榜看板 | 12（10–14） | 1–2 周 | 爆量判定口径可配置；榜单可用；反哺进入脚本参考权重 |

- **关键路径**：`A0 → A1 → A3 → B0 → B2 → B3 → M1-3（图片线）→ M2-1（视频线）→ M3-2（效果回流）→ M4-1（爆量判定）`。占用关键路径的批次不得并行插入范围。
- **全项目工量**：M0 68.5 + M1 55 + M2 67 + M3 45 + M4 12 = **247.5 EPD**；参考日历 **20–25 周**（约 5–6 个月，含 25% 缓冲）。
- **最大风险**：表单设计器复杂度（`R-T-04`）、行业包字段与合规规则未定（`Q-15` / `Q-16`）、图片渲染无先例（`R-T-13`）、AI 供应商与预算未定（`QT-05` / `Q-09`）、人类验收瓶颈。
- **排期底线**：M0 不砍权限、审计、客户隔离、导出留痕；其余均可按 §2.4 顺序后移。

### 1.3　管理模块优先的落地映射

用户点名的七个管理模块全部落在 **A1–A7**，且排在行业包与主链路之前：

| 要求的模块 | 批次 | PRD 编号 | 主要交付物 |
| --- | --- | --- | --- |
| 用户管理 | A1 | P-01 | 部门两级、用户生命周期（停用不删）、登录 / 刷新 / 登出、`/me`、路由与按钮权限 |
| 角色管理 | A2 | P-02 / P-03 | 角色 CRUD / 复制 / 停用、权限点勾选树、六类数据范围、特殊权限、SoD 校验 |
| 客户管理 | A3 | P-04 / P-05（P-17 提前到 M0） | 行业目录、客户档案（简称必填）、客户组、客户级字段申请与审批、客户状态机 |
| 数据字典 | A4 | P-06 / P-13（部分） | 通用枚举表、行业作用域三层合并、编码不可改、系统配置与命名规则 |
| 日志管理 | A5 | P-07 | 审计日志 append-only、检索 / 导出、敏感访问留痕、运行日志观测入口 |
| 任务管理 | A6 | 架构 §6.4 / M-05 | 统一任务协议、BullMQ 队列骨架、SSE + 轮询、取消 / 重试 / 幂等、任务中心 |
| AI 配置 | A7 | P-08 | 供应商 / 模型 / 任务映射 / 提示词四层配置、密钥加密、连通性测试、Mock 调用与账本 |
| （地基组成）行业包与表单 | B0 | P-14 ~ P-16 / P-18 | 行业包版本、表单设计器、发布审批、合规规则集、schema 快照 |

> 这七个模块是**横切能力**：业务表都挂 `customer_id`、查询都带 `ScopeContext`、变更都要进审计、阈值都来自 `system_configs`、耗时操作都走任务协议。后补成本极高（立项建议 §「M0 三件必做」），因此必须先做。

### 1.4　交付节奏

```mermaid
flowchart LR
    W0["W1–W7<br/>M0 地基<br/>A0–B3"] --> W1["W8–W12<br/>M1 主链路<br/>脚本 + 图片线"]
    W1 --> W2["W13–W18<br/>M2 提效<br/>视频 + 快筛 + 成本"]
    W2 --> W3["W19–W23<br/>M3 复用<br/>复用 + 送审 + 回流"]
    W3 --> W4["W24–W25<br/>M4 交付闭环<br/>爆量 + 反哺 + 看板"]
    W0 -. 每批可演示 .-> H4["人类验收门 H4"]
    W1 -. AC-01 .-> D1["业务方现场验收"]
    W2 -. 指标 .-> D2["任务成功率 / 成本曲线"]
    W4 -. 交付闭环 .-> D3["M4 验收：爆量口径 + 看板"]
```

> 周次为相对周（W1 = A0 启动周），不是日历承诺；换算方式见 §4.5。

---

## 2　目标、范围与优先级

### 2.1　分阶段目标与退出标准

| 阶段 | 目标（一句话） | 退出标准 | 判定方式 |
| --- | --- | --- | --- |
| M0 地基 | 能装人、能装客户、能装资产、能装行业 | ① 能登录；② 超管可创建角色并分配数据范围；③ 可建行业 / 客户 / 客户组；④ 可配置并发布电商行业包 v1；⑤ 可配 AI 供应商（Mock 连通）；⑥ 可提交空任务并看到进度；⑦ 关键操作审计可查 | 演示脚本（§12.1）+ 权限三态用例 + 审计抽样 |
| M1 主链路 | 一个真实客户完整走通"要素卡 → 脚本 → 图片 → 导出" | AC-01 达成；交付周期、一次过审率、单条成本可测 | 业务方现场验收 + 埋点 |
| M2 提效 | 视频线可用、配置可运营、成本可治理 | 单条视频从脚本到成片跑通；成本可查；任务成功率 ≥ 98%；峰值 500 条/日无积压（T3 口径） | 压测 + 成本看板 + 灰度观察 |
| M3 复用 | 资产复用与经验沉淀 | 资产复用率 ≥ 60%；新客户冷启动 ≤ 1 个工作日；效果回流可用 | 看板 + 抽样 |
| M4 交付闭环 | 投放数据可回流、爆量可判定、经验可反哺 | 爆量判定与阈值可配置；关联率 / 复用排行 / 爆量榜可用；脚本参考权重可回写 | 看板 + 判定抽样 + 全量回归 |

### 2.2　本计划范围

**M0 任务级拆解（§6）**：A0 工程骨架、A1 身份与用户、A2 角色权限、A3 客户行业、A4 字典与配置、A5 审计日志、A6 任务中心、A7 AI 配置、B0 行业包与表单、B1 资产最小集、B2 要素卡与脚本模板、B3 导出骨架。

**M1–M4 迭代级 + 任务组级（§5.5–§5.8、§6.13–§6.16）**：以 PRD §7 的 M1–M4 清单为基线；提前 / 后移项见 §2.5。

**M3 / M4 迭代级（§5.7 / §5.8）**：PRD §7 的 M3、M4 清单；M3 含 A-10/A-11/S-12/S-18/M-10/M-13/E-05/E-06/P-12/P-13/M-21~M-24，M4 含 M-25/M-26 + 阈值固化。

**M5 边界（§5.9）**：M-27 与 AI 素材生产路线属预研，不排期，只给进入条件。

### 2.3　明确不做（越界即评审驳回）

- 通用视频剪辑器、投放执行、效果归因、客户自助登录、计费结算；
- 图片线 AI 生图 / 图生图（`R-29`，M5 前不做）；
- 通用低代码 / 审批引擎（表单设计器只解决要素卡字段，见 PRD §5.4.8）；
- 模型训练与微调、外部 AI 供应商直连（必须走 `platform.ai`）；
- 跨客户资产复用授权流程（M3 再评估）；
- SSO 真实对接（M0 只留适配器，`Q-10` 未定）；
- 生产级多地域 / 私有化部署（`QT-13`）。

### 2.4　排序原则与砍范围顺序

**排序原则**（冲突时按序裁决）：

1. **地基先行**：权限、客户隔离、审计、字典、任务协议先于业务功能；
2. **管理模块优先**：A1–A7 先于行业包与主链路（用户明确要求）；
3. **契约先行**：接口 / 表 / 状态机冻结后才并行写前后端，禁止"先写页面再补接口"；
4. **每批可演示**：任何批次结束必须能演示，不允许"三个批次后一起联调"；
5. **先确定性后生成式**：图片线先于视频线（`D-11`、立项建议 §9.2）。

**砍范围顺序**（工期不足时从下往上砍，砍完必须回写 §13）：

| 顺序 | 可砍内容 | 代价 |
| --- | --- | --- |
| 1 | M4 全部（爆量判定 / 反哺 / 看板） | 交付闭环缺失，M0–M3 验收不受影响 |
| 2 | M3 全部 | 不影响 M0–M2 验收 |
| 3 | M2 的 M-02 规格矩阵、M-11 自动校验、M-18~M-20 成片入库 | 视频线仍可跑通，效率类指标下降 |
| 4 | M1 的 S-03 卖点库；M2 的 S-10 版本、S-11 引用、S-15 模板库、S-16 审核链接、S-17 Word 交付包 | 主链路仍闭环 |
| 5 | B0 设计器降级为 **JSON 编辑 + 试填预览**（不做拖拽与联动 UI） | 行业配置效率下降，第二行业上线变慢 |
| 6 | B1 资产预览降级为**缩略图 + 元数据**（不做真实合成预览） | 模板准入质量下降，M1 图片线需补 |
| ✗ 不砍 | 权限、客户隔离、审计、导出留痕、任务幂等、AI 密钥安全 | 触碰 AGENTS §3 红线 |

### 2.5　与架构 `T0` 口径的差异说明（必须接受）

技术架构 §10.2 的 `T0` 估算为 **25–30 EPD**，只覆盖骨架 + 管理底座 + 行业包 v1；本计划 M0 为 **65–70 EPD（细化 68.5）**，因为按 PRD §7 的 M0 清单额外包含：表单设计器、合规规则集、资产最小集（A-01~A-05）、要素卡 / 脚本模板（S-01/S-02/S-04）、导出骨架（E-01~E-03）；另把**客户级字段审批（P-17）提前到 M0**，避免客户表结构在 M1 二次变更。

**跨里程碑提前项（显式决策，均已在对应表内标注）**：

| 编号 | 原属 | 本计划位置 | 提前的部分与理由 |
| --- | --- | --- | --- |
| P-17 客户级字段审批 | M1 | M0 A3 | 全量；客户表结构一次到位，避免 M1 二次迁移 |
| P-13 系统配置 | M3 | M0 A4 | 仅 `system_configs` 与阈值读取；`R-26` 要求阈值单一来源，先建底座 |
| M-05 任务进度与重试 | M1 | M0 A6 | 仅协议 / 队列 / SSE / 幂等骨架；业务验收在 M1-3 |
| S-10 脚本版本 | M2 | M1-2 | 仅「入库即版本」基础；完整版本链 / diff 在 M2-4 |
| S-11 脚本引用 | M2 | M1-2 | 仅引用写入；引用查询与展示在 M2-4 |
| E-05 成片自动归档 | M3 | M1-4 | 仅归档骨架；策略与批量归档在 M3 完善 |
| M-18~M-20 成片入库 | M3（§7） | M2-3 | PRD 功能表标注 P1（M2），按功能表放 M2；M3 只做完善 |

| 口径 | 范围 | EPD | 参考日历 |
| --- | --- | --- | --- |
| 架构 `T0` | 骨架 + 管理底座 + 行业包 v1 | 25–30 | 3–4 周 |
| 本计划 M0 | `T0` + PRD M0 增量（设计器 / 资产 / 要素卡 / 导出 / P-17 提前） | 65–70 | 6–7 周 |

**建议**：维持完整 M0。若必须先出"能登录能建客户"的可用版本，可把 `B1–B3` 后移到 M1 之前并行，M0 缩到 4–5 周，但 M1 会因要素卡与资产缺失而返工——这与 PRD「多行业的代价」的结论一致（PRD §7 注）。**该取舍需人类确认（`DP-03`）。**

---

## 3　开发模式与协作机制（DeepSeek Harness 全程驱动）

### 3.1　编队与角色

| 角色 | 承担者 | 职责 | 介入频率 |
| --- | --- | --- | --- |
| **人类决策者**（产品 / 技术负责人） | 项目负责人 | 范围裁决、口径确认（§13）、权限点与 SoD 审批、AI 供应商与预算、UI 走查、批次验收、发布签字 | 每批 1 次验收 + 按需 |
| **Lead**（Harness） | 主会话 | 拆任务卡、冻结契约、分派与集成、跑门禁、维护计划文档、对人类的唯一汇报口 | 全程 |
| **后端 Worker**（Harness） | 并行成员 | 模块 / 接口 / 迁移 / 守卫 / 队列 / AI 适配 | 每批 1–2 名 |
| **前端 Worker**（Harness） | 并行成员 | 页面 / 表单渲染 / 权限渲染 / 任务进度 / 联调 | 每批 1–2 名 |
| **基础设施 / 测试 Worker**（Harness） | 并行成员 | Monorepo、CI、Compose、观测、测试与压测 | 每批 0.5–1 名 |
| **Verifier**（Harness，独立上下文） | 并行成员 | 用 PRD / 架构 / 本计划独立复核产出，专抓"越权、跨模块、静默交付、类型逃逸" | 每批末 1 次 |

**并行度约束**：同一时刻活跃 Worker ≤ 3（不含 Lead）；每批任务卡 6–12 张（多数 8–10）；每张卡写范围不得重叠；`prisma/schema.prisma`、`packages/shared`、`pnpm-lock.yaml`、`turbo.json` 为**单写者文件**，由 Lead 或指定 owner 统一改。

### 3.2　批次工作流（每批 4–7 个工作日）

| 步骤 | 时点 | 动作 | 产出 |
| --- | --- | --- | --- |
| ① 开卡 | D1 上午 | Lead 在共享任务板建卡（§3.3），标注依赖 / 写范围 / 验收 / 工量；人类确认范围（H0） | 任务卡 + 写范围清单 |
| ② 冻结契约 | D1 下午 | 后端产出 Zod schema / OpenAPI 草稿 / 迁移草案；前端产出 mock 与页面骨架；Lead 冻结 v0 契约 | 契约快照 + Mock |
| ③ 并行开发 | D2–D3 | 前后端同时实现；前端只依赖契约与 Mock，不等待后端合并 | 功能分支 + 单测 |
| ④ 集成联调 | D3–D4 | 按 §8.2 检查单联调；修契约偏差；跑冒烟 | 联调记录 + 修复清单 |
| ⑤ 门禁 | D4 | `lint` / `typecheck` / `test` / 契约 diff / 权限三态 / 迁移可回滚（§10） | 门禁报告 |
| ⑥ 演示验收 | D4–D5 | 人类按演示脚本走查（§12.2），Verifier 独立复核 | 验收结论 + 缺陷单 |
| ⑦ 回写复盘 | D5 | 回写实际 EPD、偏差原因、决策到本文档 / ADR；更新 §13 | 计划增量 |

> **不允许跳步**：②未冻结不得进 ③；⑤未全绿不得进 ⑥；⑥未通过不得开下一批（可并行开不依赖的批次）。

### 3.3　任务卡规范

每张卡必须包含以下字段，缺一不得开工（DoR）：

| 字段 | 要求 |
| --- | --- |
| 编号 / 标题 | `A1-BE-02 认证与 JWT`，编号与 §6 一致 |
| 模块 / 端 | `identity` / `BE`；禁止跨模块 |
| 背景与目标 | 一句话说明对应 PRD 编号（如 `P-01`）与不做的边界 |
| 接口与数据 | 路由、方法、权限点、请求 / 响应 schema、涉及表与迁移 |
| 验收标准 | 可执行的断言（HTTP 状态、返回码、页面行为、审计记录），不写"体验良好" |
| 依赖 | 前置任务卡编号；未满足即阻塞 |
| 写范围 | 目录 / 文件前缀，用于并行冲突检查 |
| 工量 | EPD（0.5 / 1 / 1.5 / 2） |
| 风险 | 外部依赖、待确认项、可能的返工点 |

**完成定义（DoD）**：代码合入 + 单测覆盖关键规则 + 接口在 OpenAPI 中可见 + 权限点已注册 + 审计已埋点 + 前端空态 / 加载态 / 错误态齐全 + 演示脚本可走通 + 文档（含迁移说明）同 PR。

### 3.4　人类决策门

| 门 | 时机 | 需要确认什么 | 不确认的后果 |
| --- | --- | --- | --- |
| **H0 范围门** | 每批开卡 | 本批范围、砍 / 加项、验收口径 | 返工或范围蔓延 |
| **H1 权限门** | A2 开卡前 | 权限点目录、六类数据范围、SoD 互斥对、特殊权限授予规则 | 权限模型返工，影响全部页面 |
| **H2 AI 门** | A7 开卡前 | 供应商清单、密钥保管方式、Mock 范围、预算阈值 | AI 配置返工，成本不可控 |
| **H3 UI 门** | 每批演示前 | 页面布局、关键交互（表格 / 表单 / 空态）、是否需要视觉稿 | 前端返工 |
| **H4 验收门** | 每批第 4–5 日 | 是否接受本批产出、遗留缺陷是否带病进入下一批 | 缺陷累积 |
| **H5 发布门** | M0 末 / M1 灰度 | 是否可内测、灰度范围、回滚方式 | 线上事故 |

> `H` 门是人的决策，不替代 §10.1 的 `G0`–`G5` 质量门禁；两者对应关系见 §10.1 表后注。

### 3.5　上下文与知识治理

- **唯一事实源**：`AGENTS.md` → 工程规范 → 技术架构 → PRD。禁止凭记忆写版本号、包名、表名、路由（AGENTS §11）。
- **每批必须回写**：实际工期 / 偏差（本文档 §5）、新决策（`docs/adr/ADR-xxx`）、接口（OpenAPI）、权限点（`packages/shared`）、迁移说明。
- **Verifier 独立复核**：复核者不继承 Lead 会话上下文，只拿任务卡 + 代码 + 验收标准，避免"自己验自己"。
- **会话压缩不等于文档**：任何影响后续批次的结论必须落盘到本文件或 ADR，不能只存在于对话里。

### 3.6　并行度、写范围与冲突控制

| 规则 | 做法 |
| --- | --- |
| 写范围隔离 | 每张卡声明目录前缀；同一文件同一时刻只允许一个 owner |
| 单写者文件 | `prisma/schema.prisma`、`prisma/migrations/*`、`packages/shared/*`、`pnpm-lock.yaml`、`turbo.json`、`package.json`（根）由 Lead / 指定 owner 统一改 |
| 迁移编号 | 按批次预分配前缀，禁止两个 Worker 同批改同一迁移；遵循 expand → migrate → contract（AGENTS §3） |
| 合并顺序 | 契约 → 后端 → 前端 → 文档；Lead 负责最终 rebase 与冲突裁决 |
| 冲突升级 | 同一文件被两人修改 → 停止并重排任务，不靠机械 rebase 硬解 |
| 演示数据 | 种子脚本由 Lead 统一维护，避免各批各造一套数据 |

---

## 4　总体开发策略

### 4.1　契约先行（前后端并行的前提）

```mermaid
flowchart LR
    P["PRD / 本计划"] --> S["packages/shared<br/>Zod schema · 错误码 · 权限点 · 枚举"]
    S --> B["NestJS DTO<br/>（静态 Zod + 动态 Ajv）"]
    B --> O["OpenAPI<br/>（构建产物）"]
    O --> F["apps/web<br/>openapi-typescript 生成 client"]
    F --> Q["TanStack Query hooks + 页面"]
    S --> M["MSW / Prism Mock<br/>（后端未就绪时）"]
    M --> Q
```

| 规则 | 说明 |
| --- | --- |
| 单一真源 | DTO 以 `packages/shared` 的 Zod schema 为准；后端不另写一套类型，前端不手写接口类型 |
| 破坏性变更 | `pnpm openapi:diff` 报 breaking 必须升版本并通知前端（工程规范 04 / 06） |
| 字段命名 | JSON body 用 camelCase，query 用 snake_case（`C-01`） |
| 列表信封 | 列表 `{ items, next_cursor }`，单资源不套 `data`（`C-02`） |
| Mock 边界 | Mock 只模拟传输层与状态码，不模拟业务规则；业务规则必须等真接口验证 |

### 4.2　前后端并行配对

| 批次 | 后端主线 | 前端主线 | 共享契约 | 联调点（D3–D4） |
| --- | --- | --- | --- | --- |
| A0 | API / worker 骨架、Prisma 基线、健康检查 | Web 骨架、布局、登录壳、UI 包 | 错误码、分页、OpenAPI 管线 | 登录页可打开；`/health` 200 |
| A1 | 部门 / 用户 / 认证 / 守卫 / `/me` | 登录、用户管理、路由守卫、权限上下文 | `User` / `Me` / `Login` schema | 登录 → 用户 CRUD → 停用即时失效 |
| A2 | 角色 / 权限点 / 数据范围 / SoD | 角色编辑器、权限树、范围选择 | `Role` / `Permission` / `Scope` | 新角色授权后页面即时变化 |
| A3 | 行业 / 客户 / 客户组 / 字段审批 | 行业页、客户页、客户组、审批页 | `Industry` / `Customer` / `CustomerField` | 建客户 → 分配范围 → 越权 403 |
| A4 | 字典 / 系统配置 / 命名规则 | 字典双视图、配置页 | `DictType` / `DictItem` / `SystemConfig` | 字典三层合并、阈值读取一致 |
| A5 | 审计写入 / 检索 / 导出 / 分区 | 审计列表 / 详情 diff / 导出 | `AuditLog` | 操作后审计可查、导出本身留痕 |
| A6 | 任务协议 / 队列 / SSE / 幂等 | 任务中心、进度组件、角标 | `Task` / `TaskEvent` | 提交 → SSE 进度 → 取消 / 重试 |
| A7 | AI 四层配置 / 密钥 / Mock / 账本 | 供应商、模型、映射、提示词页 | `AiProvider` / `AiModel` / `AiMapping` | 保存 → 测试连通 → Mock 调用记账 |
| B0 | 行业包 / schema / 校验 / 发布 / 合规 | 行业包、设计器、试填预览、规则集 | `IndustryPack` / `FormSchema` / `Rule` | schema 保存 → 校验 → 发布 → 客户绑定 |
| B1 | 资产 / 版本 / 引用 / 上传 / 模板校验 | 资产库、上传、引用、预览 | `Asset` / `Presign` | 上传 → 引用保护 → 模板解析结果 |
| B2 | 要素卡 / 物化索引 / 参考物料 / 脚本模板 | form-engine、要素卡填写、模板管理 | `BriefCard` / `ScriptTemplate` | 行业包 schema → 表单渲染 → 检索 |
| B3 | 导出 / 命名 / zip / 签名 URL | 导出弹窗、进度、交付清单 | `Export` / `Manifest` | 勾选 → 导出 → 下载 → 审计 |

### 4.3　管理模块为什么必须先做

1. **横切依赖**：`ScopeContext`、权限守卫、审计埋点、任务协议、字典、系统配置会被后续每个模块调用；后补等于全量返工。
2. **数据归属**：所有业务表挂 `customer_id`，客户与行业目录是资产和生产任务的根节点（PRD §4 / `R-20`）。
3. **红线承接**：客户隔离（`R-04`）、审计（`R-05`）、阈值同源（`R-26`）、低质量标记（`R-30`）都依赖这层底座。
4. **成本最低**：立项建议明确指出 M0 三件必做是数据权限、审计日志、客户资产包，后补成本极高。

### 4.4　每批交付物与可演示性

| 类型 | 最低交付 |
| --- | --- |
| 后端 | 可启动的 API / worker、OpenAPI 快照、迁移与种子、接口冒烟脚本、审计样例 |
| 前端 | 可打开的页面、空 / 加载 / 错误三态、权限渲染、Mock 数据、走查录屏 |
| 数据 | 迁移文件、种子数据（超管 / 示例角色 / 字典 / 电商行业包） |
| 文档 | 本批任务卡回写、接口说明、已知问题与临时开关 |

> 没有 UI 的批次用 `curl` / OpenAPI 演示；没有后端的批次用 Mock 演示。**不允许"等集成后再演示"。**

### 4.5　排期口径与产能校准

| 项 | 口径 |
| --- | --- |
| EPD | 净开发工作量，不含评审等待、外部 API 等待、部署等待（沿用技术架构 §10.2） |
| 编队 | 1 Lead + 3 Worker（前端 / 后端 / 基础设施与测试），效率系数 0.75 |
| 净产能 | **3.0 EPD / 工作日**（已含自检与集成，不含人类评审） |
| 缓冲 | **25%**（评审、联调、返工、外部依赖） |
| 换算 | `日历工作日 = EPD ÷ 3.0 × 1.25`；如编队缩为 1 Lead + 2 Worker，按 2.0 EPD/工作日重算 |
| 校准 | 每批回写"计划 vs 实际"；连续两批偏差 > 20% 触发重排并在 §5 标注 |
| 不承诺 | 不写绝对交付日期；里程碑以"W 周次 + 退出标准"表达；如需对外承诺，由人类按实际起点换算（`DP-03`） |

---

## 5　里程碑与批次计划

### 5.1　里程碑总表

| 里程碑 | 对应架构阶段 | 范围 | 净工量（EPD） | 参考日历 | 退出标准 |
| --- | --- | --- | --- | --- | --- |
| **M0 地基** | T0 + M0 增量 | A0–B3（§6） | 65–70 | 6–7 周 | §12.1 全部通过；电商行业包 v1 发布；审计可查 |
| **M1 主链路** | T1 | 脚本生成 / 校核 / 审核入库 / 编号；图片线；预览勾选；导出归档；金融行业包试跑 | 48–56 | 4–5 周 | AC-01；指标可测 |
| **M2 提效** | T2 | 视频逐镜 / 拼接 / 校验；快筛；变体矩阵；脚本版本与交付包；AI 路由 / 额度；成本看板；成片入库 | 62–70 | 5–6 周 | 视频闭环；成本可查；任务成功率 ≥ 98% |
| **M3 复用** | T3 | 资产复用度量、效果标签、混合实拍与口播、成片入库与素材库、送审与效果回流、SSO / 配置完善 | 40–50（细化 45） | 4–5 周 | 复用率 ≥ 60%；冷启动 ≤ 1 工作日；关联率与日指标可测 |
| **M4 交付闭环** | T3 收尾 | 投放登记完善、日指标、爆量判定与阈值固化、脚本权重反哺、关联率 / 爆量榜看板 | 10–14（细化 12） | 1–2 周 | 爆量口径可配置；反哺生效；M0–M4 回归通过 |

> 交叉校验：技术架构 T0–T2 净开发 120–145 EPD；本计划 M0–M2 为 175–196 EPD（按各里程碑区间相加；按当前 WBS 实际合计 190.5）；M0–M4 合计 225–260（细化 247.5），差额来自 M0 增量（设计器 / 资产 / 要素卡 / 导出）、M3 并入成片入库与效果回流、M4 新增交付闭环与更细的验收口径。若采用架构原口径，可把 B1–B3 后移（见 §2.5）。

### 5.2　M0 批次总览

| 批次 | 状态 | 主题 | 依赖 | EPD | 参考工期 | 并行波次 | 退出条件（摘要） |
| --- | --- | --- | --- | --- | --- | --- | --- |
| **A0** | ✅ 已完成 | 工程骨架与契约基线 | — | 6 | 4–5 日 | W0 | lint / typecheck / test / CI 全绿；三依赖可起；api / web / worker 可启动；OpenAPI 可导出 |
| **A1** | ✅ 已完成 | 身份认证与用户管理 | A0 | 6 | 4–5 日 | W1 | 登录 / 刷新 / 登出；用户生命周期；路由权限；权限三态用例 |
| **A2** | ✅ 已完成 | 角色权限与数据范围 | A1 | 5.5 | 4–5 日 | W2 | 角色可配；SoD 命中拒绝；特殊权限默认关闭；范围过滤生效 |
| **A3** | ✅ 已完成 | 客户与行业目录 | A1 / A2 | 7 | 4–5 日 | W2 | 行业 / 客户 / 客户组可用；唯一性；状态只读；字段审批 |
| **A4** | ✅ 已完成 | 数据字典与系统配置 | A3 | 4 | 3–4 日 | W3 | 三层合并；编码不可改；阈值同源；配置版本 + 审计 |
| **A5** | 未开始 | 审计与日志 | A1 / A4 | 4 | 3–4 日 | W2–W3 | 关键操作全留痕；不可篡改；导出自身审计 |
| **A6** | 未开始 | 任务中心与队列骨架 | A0 / A1 | 6 | 4–5 日 | W2–W3 | 提交 → SSE → 完成 / 失败；幂等；取消 / 重试 |
| **A7** | 未开始 | AI 配置与调用底座 | A0 / A1 / A5 | 6 | 4–5 日 | W3 | 四层配置；Mock 调用；密钥不泄露；账本可查 |
| **B0** | 未开始 | 行业包与表单设计器 | A3 / A4 | 8 | 6–7 日 | W4 | 电商行业包 v1；七项校验；双人发布；快照 |
| **B1** | 未开始 | 资产与模板最小集 | A3 / A5 | 6.5 | 5–6 日 | W4 | 15 类资产；引用保护；PSD 图层校验 |
| **B2** | 未开始 | 要素卡与脚本模板 | B0 | 4.5 | 4–5 日 | W5 | 动态表单渲染；要素卡检索；模板版本 |
| **B3** | 未开始 | 导出骨架与归档 | B1 / B2 | 5 | 4–5 日 | W6 | E-01~E-03；命名规则；审计；签名 URL |

**合计**：12 个批次，68.5 EPD，6–7 周（含 25% 缓冲与 M0 末集成缓冲）。

> **A0 进度（2026-11-02）**：✅ 已完成。10/10 项 WBS 通过；本批门禁 `format:check / lint / typecheck / test / build / test:int / openapi:export / openapi:diff / e2e` 与本地 CI `pnpm ci:local` 全绿；`/health`、`/api/docs`、web 布局与登录壳、worker 启动均实测通过。实现记录与偏差见 [A0 实施报告](./灵犀_A0工程骨架与契约基线_实施报告_V0.1.md)。环境适配：本地 PG/Redis 复用已有 Docker、对象存储使用公网 RustFS、种子仅 `system_configs`（`Q-A0-01`）、Gitea 暂无 runner 时以 `pnpm ci:local` 为准。
>
> **A1 进度（2026-11-03）**：✅ 已完成。10/10 项 WBS 通过；`format:check / lint / typecheck / test` 全绿（shared 121 / api 90 / web 120），`test:int` 33 项（真实 PG / Redis），A1-QA-01 浏览器 e2e 6/6；登录 → 首次登录强改 → 用户列表 / 新建 / 详情 / 停用启用 / 角色调整 / 客户转交占位全链路实测。**补强**：`/system/departments` 部门管理（两级组织树、负责人/排序、只停用不删除、停用拦截）已落地并联调。实现记录、口径与遗留见 [A1 实施报告](./灵犀_A1身份认证与用户管理_实施报告_V0.1.md)。已知遗留：客户转交真实接口（A3）、审计落库（A5）。
>
> **A2 进度（2026-11-03）**：✅ 已完成。8/8 项 WBS 通过；H1 权限门已确认并记录 [ADR-001](../adr/ADR-001-权限点目录与六类数据范围.md)；UI 门三套原型独立评审 A 8 / B 8 / C 7，用户选定 **B 主从分栏**。最终验收（2026-11-03）：`format:check / lint / typecheck / test` 全绿（shared 121 / api 90 / web 120，共 331），`test:int` 33 项（真实 PG / Redis），A2-QA-01 浏览器 e2e 1/1（22.1s，最终版 UI 下复跑通过）；角色可配、SoD 40304、特殊权限默认关闭、六类范围解析与 `ScopeContext` 全链路、系统角色保护、变更审计与 outbox 均实测。收口项：侧栏/页面统一为「角色管理」、列表页头主操作右对齐、角色详情「编辑角色」移入页头、移除重复的权限点目录抽屉。实现记录、口径与遗留见 [A2 实施报告](./灵犀_A2角色权限与数据范围_实施报告_V0.1.md)。已知遗留：A3 前客户目录为空集、A5 审计落库、DP-14 两项特殊权限、导航模块级权限口径。

### 5.3　批次依赖图

```mermaid
flowchart TD
    A0["A0 工程骨架"] --> A1["A1 身份与用户"]
    A1 --> A2["A2 角色与数据范围"]
    A1 --> A3["A3 客户与行业"]
    A2 --> A3
    A3 --> A4["A4 字典与配置"]
    A1 --> A5["A5 审计与日志"]
    A4 --> A5
    A0 --> A6["A6 任务中心"]
    A1 --> A6
    A1 --> A7["A7 AI 配置"]
    A5 --> A7
    A3 --> B0["B0 行业包与设计器"]
    A4 --> B0
    A3 --> B1["B1 资产最小集"]
    A5 --> B1
    B0 --> B2["B2 要素卡与脚本模板"]
    B1 --> B3["B3 导出骨架"]
    B2 --> B3
    B3 --> M1["M1 主链路"]
    M1 --> M2["M2 提效"]
```

### 5.4　并行波次

| 波次 | 并行批次 | 说明 | 关键路径 |
| --- | --- | --- | --- |
| W0 | A0 | 全员先建骨架，避免各写各的 | ✓ |
| W1 | A1 | 身份是全部页面的前置 | ✓ |
| W2 | A2 / A3 / A5 / A6 | 4 个批次争 3 个 Worker：优先 A2 + A3 + A6，A5 从 W2 后段插入 | ✓（A3） |
| W3 | A4 / A7 / A5 收尾 | A4 依赖 A3；A7 依赖 A5 | — |
| W4 | B0 / B1 | 两条独立线：配置线与资产线 | ✓（B0） |
| W5 | B2 / B3 前段 | B3 的导出记录可先用 Mock 数据 | ✓（B2） |
| W6 | B3 收尾 + M0 集成 | 全链路演示 + 审计抽样 + 性能冒烟 | ✓ |

> **争用说明**：W2 的 A5 可拆成"审计写入骨架（A1 后即可）"与"检索 / 导出（A4 后）"两段，前者随 A2/A3 并行，后者在 W3 完成。任务卡已按此拆分（A5-BE-01/02 与 A5-BE-03）。

### 5.5　M1 迭代级计划（T1）

| 迭代 | 主题 | 范围（PRD 编号） | 前后端要点 | 净工量 | 退出标准 |
| --- | --- | --- | --- | --- | --- |
| **M1-1** | 脚本生成与解析 | S-05、S-03、S-07（基础四类）、S-14（基础） | BE：生成任务、提示词组装、JSON 解析、校核规则、失败重试；卖点库标签与使用计数；FE：生成向导、结果列表、失败明细 | 14 | 批量生成可提交，逐条结果可见，解析失败留原文 |
| **M1-2** | 审核入库与编号 | S-08、S-09、S-13、S-10（基础：入库即版本）、S-11（基础：引用写入） | BE：审核状态机、批量审核、原子取号、版本；FE：审核工作台、入库、编号展示 | 12 | 过审入库分配唯一编号；修改产生新版本 |
| **M1-3** | 图片生产线 | M-01、M-03、M-04（安全区 / 警示语）、M-05、M-14 | BE：`render` 包（PSD 解析 / 抠图 / 合成 / 编码）、image 队列、批次快照、低质量标记；FE：批次提交、网格预览、失败重试 | 15 | 单模板端到端出图；批次可重试；低质量有标记 |
| **M1-4** | 预览勾选、导出与收口 | M-03 完整、E-04、E-05（归档骨架）、金融行业包 v1 试跑 | BE：勾选持久化、导出打包、归档、命名；FE：快筛网格、勾选恢复、导出记录、交付清单 | 14 | AC-01 达成；1 个金融客户试跑 1 个批次 |

> M1 合计 48–56 EPD（细化 55）；任务组见 §6.13。关键路径为 M1-3（图片渲染是唯一无先例链路，`R-T-13`），建议从 M1-2 起并行做 PSD 解析 spike（2–3 日，不计入批次正式工量，算风险预备）。注：S-10 / S-11 在 M1 只做基础、E-05 只做归档骨架，完整能力分别在 M2-4 / M3 点亮。

### 5.6　M2 迭代级计划（T2）

| 迭代 | 主题 | 范围（PRD 编号） | 前后端要点 | 净工量 | 退出标准 |
| --- | --- | --- | --- | --- | --- |
| **M2-1** | 视频逐镜生成 | M-06、M-15、M-16 | BE：分镜拆解、关键帧、图生视频、镜头并行、超时控制；FE：视频方向选择、任务进度、在线预览 | 15 | 单条视频从脚本到分镜成片跑通 |
| **M2-2** | 拼接、校验与单镜替换 | M-07、M-11、M-17 | BE：ffmpeg 拼接、音量归一、自动校验、命名；FE：单镜重生成、成片下载 / 导出 | 13 | 成片可下载；校验报告可见；单镜可替换 |
| **M2-3** | 快筛、变体与成片入库 | S-06、M-08、M-09、M-12、M-18~M-20 | BE：变体矩阵、成本预估、分片直传 / 秒传、版本链；FE：分组并排快筛、快捷键、素材库双视图 | 15 | 快筛效率达标；外部成片可入库并转码 |
| **M2-4** | 脚本增强与交付包 | S-10、S-11、S-15~S-17、E-07 | BE：脚本版本链与 diff、引用记录、结构模板库审核、客户在线审核链接、Word 交付包；FE：版本对比 / 回滚入口、模板库、审核链接、交付记录 | 10 | 脚本可版本化与追溯；审核链接与交付包可用且留痕 |
| **M2-5** | AI 治理、资产增强与第三行业 | P-09、P-10、P-11、A-06~A-09、M-02、第三行业包 | BE：路由 / 降级 / 额度 / 预算闸门 / 成本聚合、资产版本与人物场景池、规格矩阵补齐；FE：AI 路由与额度页、成本看板、资产增强 | 14 | 成本可查可分摊；预算 100% 阻断；第三行业包可配置 |

> M2 合计 62–70 EPD（细化 67）；任务组见 §6.14。视频质量不确定性最高（`R-T-02`），必须先做"单镜质量基线"再上批量。注：`M-18~M-20` 在 PRD 功能表标注 P1（M2）、在 §7 归入 M3，本计划按功能表放在 M2，M3 只做完善；其余提前项见 §2.5。

### 5.7　M3 迭代级计划（T3）

| 迭代 | 主题 | 范围（PRD 编号） | 前后端要点 | 净工量 | 退出标准 |
| --- | --- | --- | --- | --- | --- |
| **M3-1** | 资产复用与口播增强 | A-10、A-11、S-12、S-18、M-10、M-13 | BE：复用率统计、复审任务与降权、脚本效果标签、版本 diff / 回滚、TTS + lip sync、相似度提示与来源标签；FE：复用看板、复审工作台、版本对比、口播配置 | 15 | 复用率与排行可统计；复审可执行；口播成片可预览并留痕 |
| **M3-2** | 成片运营与效果回流 | M-21 ~ M-24、E-05（完善）、E-06 | BE：脚本-素材关联与血缘、分享链接、送审登记、投放登记与日指标、批量重导 / 按组导出；FE：关联视图与待办、送审台、投放登记、指标视图 | 16 | 关联率可测；日指标可导入；分享与送审全留痕 |
| **M3-3** | 外部访问与系统完善 | P-12、P-13、M-18 ~ M-20（M2 遗留收口）、检索与性能收口 | BE：SSO / 手机号适配、系统配置、检索与标签、性能收口；FE：登录方式、配置页、全局搜索 | 14 | SSO 或手机号至少一种可用；配置项生效；P95 达标 |

> M3 合计 40–50 EPD（细化 45）；任务组见 §6.15。M-22 分享链接受 `R-28` 开关约束（默认关闭，`DP-18`）；P-12 的 SSO 协议未定（`Q-10` / `DP-04`），M3 先做手机号 + 适配器，SSO 可替换。

### 5.8　M4 迭代级计划（交付闭环）

| 迭代 | 主题 | 范围（PRD 编号） | 前后端要点 | 净工量 | 退出标准 |
| --- | --- | --- | --- | --- | --- |
| **M4-1** | 爆量判定与脚本反哺 | M-25、M-26（查询部分） | BE：爆量判定任务、阈值配置、评级 → 权重映射与反哺、关联率 / 复用排行查询；FE：爆量榜、关联率与排行视图 | 7 | 阈值只读 `system_configs`；判定可重跑且幂等；反哺生效可在脚本参考权重中查到 |
| **M4-2** | 度量看板与项目验收 | M-26（看板）、成本 / 质量 / 资产总览、告警 | BE：指标汇总与导出、告警规则；FE：总看板；QA：M0–M4 全量回归 | 5 | 四类看板可用；告警可触发；全量回归通过 |

> M4 合计 10–14 EPD（细化 12），1–2 周（含验收与全量回归）；任务组见 §6.16。M4 不新增业务表，复用投放登记 / 日指标 / 脚本权重字段；爆量阈值口径见 `DP-16`。

### 5.9　M5 预研边界（不排期）

PRD §7 把 **M-27（素材元素级拆解）** 与「自动字幕 → TTS 配音 → FFmpeg 时间线剪辑 → 一键成片 → 数字人 / 生成式画面」列为 **M5 预研**，不进入本计划排期。进入条件（满足后单独立项，不在本文件加任务卡）：

1. M4 验收通过，M0–M4 的资产 / 效果数据已积累 ≥ 1 个季度；
2. `Q-32` 明确是否做 AI 生图 / 生视频，以及覆盖哪些非电商行业；
3. 预算、版权（肖像 / 音乐 / 模型许可）与算力方案获批。

### 5.10　关键路径与缓冲

- **关键路径**：`A0 → A1 → A3 → B0 → B2 → B3 → M1-3（图片线）→ M2-1（视频线）→ M3-2（效果回流）→ M4-1（爆量判定）`；
- **有浮动的批次**：A2（可后 1 日）、A5（可拆两段）、A6 / A7（W2–W3 内可调）、B1（与 B0 并行）；
- **缓冲安排**：每波次末留 1 日技术债 / 联调缓冲；M0 末额外 3 日集成缓冲（全链路演示 + 审计抽样 + 性能冒烟）；M1–M3 各留 2 日；M4 留 1 日做全量回归；
- **全项目参考日历**：M0 6–7 周 + M1 4–5 周 + M2 5–6 周 + M3 4–5 周 + M4 1–2 周 = **20–25 周**（约 5–6 个月）；
- **关键路径纪律**：关键路径上的批次**不接受插入新范围**；如必须插入，先砍等量范围或顺延里程碑。

---

## 6　任务级工作分解（WBS）

> **编号规则**：`A1-BE-02` = 批次 A1 / 端别 / 序号。端别：`INF` 基础设施、`SH` 共享包、`BE` 后端、`FE` 前端、`QA` 测试。
> **工量**：EPD（等效人日），已含自检与单测，不含人类评审与联调等待。
> **门禁**：每批末尾的门禁是进入下一批的必要条件；验收要点写可执行断言，不写主观描述。
> **开卡时展开**：本表是计划级摘要；批次开卡按 §3.3 补齐接口、鉴权、写范围、风险后执行。

### 6.1　A0 工程骨架与契约基线

> **执行状态：✅ 已完成（2026-11-02）**。以下 10 项 WBS 全部交付并实测；验收证据、环境差异与待确认项见 [A0 实施报告](./灵犀_A0工程骨架与契约基线_实施报告_V0.1.md)。

**目标**：一次建对仓库、工具链、CI 与契约管线，避免后续每个批次各修一遍。
**对应**：技术架构 §10.1；`AGENTS.md` §3 / §5 / §6；工程规范 01–03 / 06 / 09。

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD | 状态 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| A0-INF-01 | Monorepo 与工具链 | INF | pnpm workspace + Turborepo；TS strict；ESLint 9 flat + Prettier + commitlint + lint-staged；`.nvmrc` 24.15.0、`engines`、`packageManager`、`only-allow pnpm`；`apps/api`、`apps/worker`、`apps/web`、`packages/*`、`prisma/`、`infra/` 目录骨架 | — | `pnpm install` 成功；`pnpm lint` / `pnpm typecheck` 可执行；目录与 AGENTS §5 一致；npm / yarn 被拒绝 | 1.0 ✅ |
| A0-INF-02 | 本地依赖与迁移种子 | INF | `docker-compose.dev.yaml`（PG18 / Redis7.4 / MinIO）、健康检查；`.env.example`；Prisma 初始化、首版迁移、种子脚本（超管、示例角色、核心字典、电商行业包占位） | A0-INF-01 | `pnpm compose:up` 三依赖健康；`pnpm db:migrate` 正向成功；种子可重复执行不重复插入 | 0.5 ✅ |
| A0-INF-03 | CI 与质量门禁 | INF | 流水线：`install --frozen-lockfile` → lint → typecheck → test → build → OpenAPI 产物；依赖缓存；失败阻断合并 | A0-INF-01 | 首条 PR 全绿；故意写 `any` / 类型错误 / 未格式化能被拦截 | 0.5 ✅ |
| A0-BE-01 | API 骨架 | BE | NestJS 11 + Fastify；Pino + trace_id；统一错误过滤器（`{code,message,details,trace_id}`）；`/health`；Swagger / OpenAPI 生成；Zod 管道；CORS 与安全头 | A0-INF-01 | `GET /health` 返回 200；错误结构统一；OpenAPI 可导出且含错误码 | 1.0 ✅ |
| A0-BE-02 | Prisma 基线 | BE | Prisma client 封装；迁移基线；`outbox_events` / `idempotency_keys` / `system_configs` 骨架；ULID 主键、软删、时间字段约定 | A0-INF-02 | 迁移可升可回滚；字段命名与工程规范 05 一致；无跨模块表 | 0.5 ✅ |
| A0-SH-01 | shared 包基线 | SH | 错误码枚举（400xx–500xx）、权限点常量骨架与命名规范（`模块:动作`）、ULID、游标分页、时间与命名工具、通用 Zod schema | A0-INF-01 | 前后端同时引用成功；shared 不依赖任何业务包 | 0.5 ✅ |
| A0-FE-01 | Web 骨架 | FE | Vite 6 + React 19 + Router 7 + TanStack Query 5 + Zustand 5；`@douyinfe/semi-ui-19` + `react19-adapter`；路径别名；请求层（token 注入、401 刷新、统一错误提示） | A0-INF-01 | 页面可启动；路由可切换；请求层有单测 | 0.5 ✅ |
| A0-FE-02 | UI 包基线 | FE | Semi 二次封装（表格 / 查询表单 / 弹窗 / 空态 / 错误态 / 加载骨架）；`icons.ts` 统一出口（Remix Icon 语义名）；locale；主题 token | A0-FE-01 | 业务代码不直接引图标库、不内联 SVG；ESLint 可拦截违规引用 | 0.5 ✅ |
| A0-FE-03 | 布局与登录壳 | FE | 侧边导航（按模块分组）、顶栏（用户 / 任务角标占位）、面包屑、401 / 403 / 404 页、登录页静态壳 | A0-FE-01 | 布局可打开；403 页可演示；导航配置集中管理、可按权限过滤 | 0.5 ✅ |
| A0-QA-01 | 冒烟与报告 | QA | 健康检查 / 登录页 / OpenAPI 冒烟用例；覆盖率报告；CI 产物归档 | A0-INF-03 | CI 产出测试报告；3 条冒烟通过 | 0.5 ✅ |

**本批门禁**：`pnpm format:check && pnpm lint && pnpm typecheck && pnpm test` 全绿；`pnpm ci:local` 全绿（含 build、test:int、openapi:export / diff、e2e）；api / web / worker 可启动；OpenAPI 快照入库；CI 流程已配置，Gitea 暂无 runner 时以本地 CI 为准。

> **环境与范围偏差**：本地 PG / Redis 复用已有 `docker-postgres-1` / `docker-redis-1`；S3 使用公网 RustFS（单桶 `lingxi-dev`）；超管 / 角色 / 字典 / 电商行业包种子依赖 A1–A4 的表，A0 仅种子 `system_configs`，已登记为 `Q-A0-01` 并在 A0 报告中说明。

### 6.2　A1 身份认证与用户管理

> **执行状态：✅ 已完成（2026-11-03）**。以下 8 项 WBS 全部交付并实测；验收证据、口径与遗留见 [A1 实施报告](./灵犀_A1身份认证与用户管理_实施报告_V0.1.md)。

**目标**：能登录、能装人、能按权限渲染页面。**对应**：P-01、PRD §5.4.1；架构 §6.2 / §7.1；`R-16` / `R-17` 前置。

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD | 状态 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| A1-BE-01 | 部门与用户 | BE | `departments`（两级，父级最多两级校验）、`users`（手机号唯一、离职停用不删、一人多角色）；用户 CRUD、停用 / 启用、角色绑定、客户转交接口占位 | A0-BE-02 | 建部门超两级被拒；停用后登录被拒；删除用户被拒、只能停用 | 1.0 | ✅ |
| A1-BE-02 | 认证与会话 | BE | 账号密码登录（Argon2）、JWT access + refresh 旋转、`jti` 吊销、登出、失败次数限制、密码策略；SSO 适配器接口（不实现） | A0-BE-02 | 登录 → 刷新 → 登出全链路；旧 refresh 立即失效；错误码 40101 / 40102 正确 | 1.0 | ✅ |
| A1-BE-03 | 守卫链与审计拦截 | BE | `JwtGuard` → `PermissionGuard` → `SpecialPermissionGuard` → `ScopeGuard` 骨架 → 业务校验；`@Audit()` 装饰器与请求上下文（用户、客户、trace_id） | A1-BE-02、A0-SH-01 | 无 token 401；无权限点 40301；守卫顺序可单测 | 1.0 | ✅ |
| A1-BE-04 | `/me` 与权限上下文 | BE | 当前用户、角色、权限点集合、数据范围、可见客户集合；权限变更即时生效（不缓存旧权限） | A1-BE-03 | `/me` 与登录返回一致；角色变更后下一次请求生效 | 0.5 | ✅ |
| A1-BE-05 | 部门管理补强 | BE | `GET /departments/tree?include_disabled`、`POST/PATCH /departments`、`POST /departments/{id}/disable|enable`；负责人/排序；只停用不删除；有在职成员或启用子部门禁止停用 | A1-BE-01 | 两级/超两级/重名/负责人校验；停用三类拦截；无 DELETE | 0.5 | ✅ |
| A1-FE-01 | 登录与会话 | FE | 登录页、token 存储与刷新、登出、会话过期跳转、路由回跳 | A0-FE-03 | 登录 → 刷新页面仍在线；token 过期自动刷新一次；刷新失败回登录 | 0.5 | ✅ |
| A1-FE-02 | 用户管理页 | FE | 用户列表（游标分页 / 筛选）、新建 / 编辑、停用确认、部门筛选、角色多选、客户转交入口 | A0-FE-02 | 列表可分页筛选；停用需二次确认；页面按 `user:manage` 隐藏写操作 | 1.0 | ✅ |
| A1-FE-03 | 权限上下文与路由守卫 | FE | `/me` 全局缓存、权限点 Hook（`usePermission`）、路由级与按钮级控制、403 页 | A1-FE-01 | 无权限路由被拦截；按钮级无权限不渲染（非 `removeChild` 式隐藏） | 0.5 | ✅ |
| A1-FE-04 | 部门管理页 | FE | `/system/departments` 两级组织树 + 详情/内联编辑 + 新建部门/小组 + 停用/启用二次确认；显示已停用、`?id=` 选中可恢复 | A1-FE-01、A1-FE-03 | 无 `user:manage` 只读；停用被拒有明确提示；刷新恢复选中 | 0.5 | ✅ |
| A1-QA-01 | 账号生命周期用例 | QA | 登录 / 刷新 / 登出 / 停用 / 角色变更 / 越权 6 类用例 | A1-BE-04 | 用例全部通过并进 CI | 0.5 | ✅ |

**本批门禁**：登录闭环；用户生命周期可演示；权限有 / 无用例通过（范围外 ScopeContext 随 A2 补齐）；审计已记录登录与用户变更（当前为结构化日志，落库随 A5）。

### 6.3　A2 角色权限与数据范围

**目标**：角色可配置、范围可解析、互斥可校验。**对应**：P-02 / P-03、PRD §5.4.3；`R-16` / `R-17` / `R-18`；架构 §6.2 / §7.1；`D-07`。

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| A2-BE-01 | 角色 CRUD / 复制 / 停用 | BE | `roles`、`role_permissions`；新建 / 复制 / 停用；超管 `is_system=true` 不可改；删除前校验无绑定用户；示例模板 5–7 个可改可删 | A1-BE-01 | 超管不可删改停用（仅显示名可改）；有用户绑定的角色只能停用；复制生成独立角色 | 0.5 |
| A2-BE-02 | 权限点注册与同步 | BE | 代码注册的权限点目录 → 启动时同步 `permissions` 表；`code` 唯一；前端可拉取权限树 | A0-SH-01 | 新增权限点无需手写迁移；`/permissions` 返回树形结构 | 0.5 |
| A2-BE-03 | 角色权限与特殊权限 | BE | 角色 → 权限点绑定；M0 特殊权限五项（导出 / AI 配置 / 审计查看导出 / 行业包发布 / 字段审批）默认关闭、单独授予；跨客户复用、批量删除待架构给编码后补入（`DP-14`） | A2-BE-01 | 新角色默认全空；特殊权限不随角色复制带入；二次确认记录审计 | 0.5 |
| A2-BE-04 | 数据范围与 ScopeContext | BE | 六类范围（全部 / 本部门及下级 / 本部门 / 指定客户组 / 负责客户 / 本人创建）；`data_scopes` 解析为可见客户集合；Repository 强制注入 `customer_id` | A1-BE-03、A2-BE-01 | 范围外写操作 40302、列表裁剪为空、单条 404；SQL 必带客户维度；禁止"先查全量再过滤" | 1.0 |
| A2-BE-05 | SoD 与变更审计 | BE | 三对互斥校验（生成 / 审核、行业包编辑 / 发布、字段申请 / 审批）；保存即校验；变更审计含前后值、影响用户数；受影响用户通知占位 | A2-BE-03 | 命中互斥返回 40304；审计可查"谁改了哪些权限点、影响多少人" | 0.5 |
| A2-FE-01 | 角色编辑器 | FE | 角色列表、权限点勾选树（按模块 / 操作）、六类数据范围选择、特殊权限单独区域、保存前影响面提示 | A1-FE-03 | 权限树与后端目录一致；保存失败展示 40304 与冲突对 | 1.0 |
| A2-FE-02 | 复制 / 模板 / 停用 | FE | 从角色或示例模板复制；停用倒计时与在线用户提示；角色详情展示绑定用户 | A2-FE-01 | 复制后可独立编辑；停用后在线用户下次请求失效 | 1.0 |
| A2-QA-01 | 权限三态与 SoD 用例 | QA | 每个角色相关端点 3 类用例（有 / 无 / 范围外）+ 3 对 SoD 用例；权限变更即时生效 | A2-BE-05 | 用例全部通过；越权访问有审计记录 | 0.5 |

> **A2 完成情况（2026-11-03，最终验收）**：8/8 项 WBS 完成；A2-BE-01~05、A2-FE-01/02、A2-QA-01 全部验收通过，计划状态置为 ✅ 已完成。H1 权限门确认：30 权限点 / 10 模块（保留 `read/write` 只补缺）、特殊权限五项 6 编码、SoD 三对、六类数据范围全链路、超管隐式全集、A2 审计先结构化日志；见 [ADR-001](../adr/ADR-001-权限点目录与六类数据范围.md)。UI 三套原型评审 A 8 / B 8 / C 7，用户选定 B 主从分栏。最终门禁：`test` 331 项全绿（shared 121 / api 90 / web 120），`test:int` 33 项，A2 e2e 1/1（22.1s）；实现与遗留见 [A2 实施报告](./灵犀_A2角色权限与数据范围_实施报告_V0.1.md)。

**本批门禁**：角色可配、范围可解析、SoD 可拦截；权限三态用例全绿；特殊权限默认关闭；人类完成 **H1 权限门**（§3.4）。

### 6.4　A3 客户与行业目录

> **执行状态：✅ 已完成（2026-11-03 开发完成，2026-11-04 UI 对齐 / 本地 CI 最终验收）**。以下 9 项 WBS 全部交付并实测；实现记录、验收证据与遗留见 [A3 实施报告](./灵犀_A3客户与行业目录_实施报告_V0.1.md)。

**目标**：行业 / 客户 / 客户组 / 客户字段四件事立住，作为全部资产的根节点。**对应**：P-04 / P-05 / P-17、PRD §5.4.2 / §5.4.9；`R-20` / `R-04`；架构 §6.3.2。

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD | 状态 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| A3-BE-01 | 行业目录（两级） | BE | `industries`；一级 → 二级最多两级；一级名称全局唯一、二级同父唯一；客户只挂末级行业；删除前校验无子行业 / 客户 / 资产，否则只能停用；有启用子行业时禁止停用 | A2-BE-04 | 重名 40902；有子行业 / 客户时删除被拒；有启用子行业停用被拒；停用后新建客户不可选 | 0.5 | ✅ |
| A3-BE-02 | 客户档案与状态机 | BE | `customers`；简称必填、`(industry_id, name)` 唯一；服务状态（在服务 / 暂停 / 结束）；负责人 / 对接人；交付偏好；套用行业资产包入口 | A3-BE-01 | 简称缺失 42201；暂停只读、不能发起新任务；结束全只读 | 1.0 | ✅ |
| A3-BE-03 | 客户组 | BE | `customer_groups` + `customer_group_members`；客户组作为授权与数据范围最小单位 | A3-BE-02 | 成员增删幂等；数据范围引用客户组后可见集合正确 | 0.5 | ✅ |
| A3-BE-04 | 客户级字段申请与审批 | BE | `customer_fields`；申请（定义 + 用途 + 是否进入生成）→ 审批 → 生效；每客户 ≤ 5 个进入生成字段、基础字段 ≤ 10 | A3-BE-02 | 超限 40001（字段校验失败）；未审批字段不进入生成；审批与变更进审计 | 1.0 | ✅ |
| A3-BE-05 | 客户上下文与归属校验 | BE | 客户上下文中间件；资产 / 任务归属校验函数；跨客户访问统一 404（不暴露存在性） | A2-BE-04、A3-BE-02 | 跨客户访问返回 40401；所有查询带 `customer_id` | 0.5 | ✅ |
| A3-FE-01 | 行业管理页 | FE | 行业列表 / 新建 / 编辑 / 停用；删除前引用提示 | A0-FE-02 | 重名与有客户时的错误可读；停用状态清晰 | 0.5 | ✅ |
| A3-FE-02 | 客户列表与档案 | FE | 列表（行业 / 状态 / 负责人筛选）、详情、分步新建（行业 → 基础信息 → 交付偏好 → 资产包）、简称必填校验 | A3-FE-01 | 分步表单可回退；暂停 / 结束状态只读并提示 | 1.5 | ✅ |
| A3-FE-03 | 客户组管理 | FE | 客户组列表、成员批量添加 / 移除、按客户组授权提示 | A3-FE-02 | 批量操作有确认与结果反馈 | 0.5 | ✅ |
| A3-FE-04 | 字段申请与审批 | FE | 字段定义表单、用途说明、是否进入生成、审批列表、超限提示 | A3-FE-02 | 申请 / 审批状态可追踪；超限给出明确文案 | 0.5 | ✅ |
| A3-QA-01 | 唯一性 / 状态 / 范围用例 | QA | 行业与客户唯一性、状态只读、跨客户越权、字段上限 | A3-BE-05 | 用例全绿；越权访问有审计 | 0.5 | ✅ |

**本批门禁**：可建行业 → 客户 → 客户组；唯一性与状态机生效；客户字段审批可用；所有查询带客户维度。

> **A3 完成情况（2026-11-03 开发完成 / 2026-11-04 最终验收）**：9/9 项 WBS 全部 ✅。两级行业树（ADR-002）、客户档案与状态机、客户组、客户级字段双层与审批、客户转交、真实 `CustomerDirectory`、客户上下文与跨客户 404 全部落地；前端按用户选定混搭实现（行业 B / 客户列表 A / 客户详情 A / 新建 B / 客户组 B / 字段 A），侧栏更名「客户管理」「行业管理」并新增「客户组」。门禁：`format:check / lint / typecheck / test` 全绿（shared 131 / api 90 / web 125，共 346），`test:int` 39 项（5 文件，含 A3 client 6 条），A3 浏览器 e2e 1/1（11.6s），`build` 8/8；实现记录、截图与遗留见 [A3 实施报告](./灵犀_A3客户与行业目录_实施报告_V0.1.md)。已知遗留：B0 行业资产包套用、A5 审计落库、A4 字段上限配置、客户详情面包屑末级名称。

### 6.5　A4 数据字典与系统配置

**目标**：字典与配置成为唯一来源，杜绝前后端硬编码。**对应**：P-06、P-13（部分）、PRD §5.4.5；`R-10` / `R-01` / `R-26`；架构 §5.3 / §5.7。

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| A4-BE-01 | 字典模型与三层合并 | BE | `dict_types` / `dict_items` 通用枚举表；类型 + 编码 + 名称 + 父编码 + 行业 + 排序 + 启用；编码不可改、名称可改；查询按"本行业 + 父行业 + 通用"三层合并 | A3-BE-01 | 一张表同时表达二级树与词表；编码修改被拒；三层合并结果有单测 | 1.0 |
| A4-BE-02 | 系统配置与版本 | BE | `system_configs` 键值 + 版本 + 变更审计；命名规则、导出设置、通知开关、阈值（爆量 / 超时 / 上限）单一来源；前后端同源读取 | A0-BE-02 | 配置变更留前后值；阈值只有一处定义；前端上限读取配置接口 | 0.5 |
| A4-BE-03 | 命名规则服务 | BE | `R-01` 占位符解析（行业 / 客户 / 方向 / 日期 / 序号），中文 / 字母 / 数字 / 下划线 / 短横线校验，同名自动加序号，≤ 100 字符 | A4-BE-02 | 占位符缺失报错；同名序号连续；规则可被导出 / 素材 / 脚本共用 | 0.5 |
| A4-BE-04 | 字典快照 | BE | 字典项被引用时保存填写时快照；字典变更只影响新数据；历史统计按填写时解释（`R-10`） | A4-BE-01 | 改字典名称后历史数据不变；快照查询可复现 | 0.5 |
| A4-FE-01 | 字典管理 | FE | 字典类型列表、条目树 / 词表双视图、行业作用域、排序、启停；编码只读 | A4-BE-04 | 编码不可编辑；树与词表可切换；影响范围提示 | 0.5 |
| A4-FE-02 | 系统配置页 | FE | 命名规则、导出设置、通知、阈值配置；版本与变更记录 | A4-BE-02 | 保存前展示影响面；阈值修改有二次确认 | 0.5 |
| A4-QA-01 | 合并 / 快照 / 同源用例 | QA | 三层合并、编码不可改、快照、阈值前后端一致 | A4-BE-04 | 用例全绿；改字典不影响历史 | 0.5 |

**本批门禁**：字典三层合并可用；编码不可改；阈值只存一处且前后端一致；配置变更可审计。

> **A4 完成情况（2026-11-04）**：7/7 项 WBS 全部 ✅。`dict_types` / `dict_items` 通用枚举表（树 / 词表一张表、编码不可改、三层合并、快照契约）、`system_configs` + `system_config_versions`（26 项配置、版本 / 乐观锁 / 前后值 / 审计日志）、命名规则服务（R-01）、阈值同源（roles / users / customers / customer-fields 读配置）全部落地；前端按用户选定 **方案 A 主从分栏**实现 `/system/dicts`、`/system/dicts/:type`、`/system/settings`，侧栏更名「数据字典」。门禁：`format:check / lint / typecheck / test` 全绿（shared 147 / api 137 / web 154，共 438），`test:int` 58 项（7 文件，含 A4 catalog 10 + config 9），A4 浏览器 e2e 7/7（约 1.1m），`build` 8/8，`openapi:export` + `openapi:diff` 无破坏性变更；实现记录、截图与遗留见 [A4 实施报告](./灵犀_A4数据字典与系统配置_实施报告_V0.1.md)。已知遗留：`refCount` 待 B0/B1、A5 审计落库、详情面包屑末级类型名、字典类型 >100 的分页。

### 6.6　A5 审计与日志

**目标**：关键操作全留痕、不可篡改、可检索可导出。**对应**：P-07、PRD §5.4.6；`R-05`；架构 §5.4.5 / §9.7；工程规范 08。

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| A5-BE-01 | 审计表与 append-only | BE | `audit_logs` 按月分区；应用账号只有 INSERT 权限（DB 层禁 UPDATE / DELETE）；字段：主体、动作、对象、前后值、客户、IP / UA、trace_id | A0-BE-02 | 直接 UPDATE / DELETE 被数据库拒绝；分区可自动创建 | 0.5 |
| A5-BE-02 | 审计采集 | BE | `@Audit()` 装饰器 + 领域事件采集（PRD §5.4.6 七类）：登录 / 登出、权限变更、资产增删改、客户与字典等配置变更、导出、任务提交与结果、敏感数据访问 | A1-BE-03、A4-BE-02 | 关键动作 100% 有记录；失败请求也记录；前后值可 diff | 0.5 |
| A5-BE-03 | 审计检索与导出 | BE | 按人 / 客户 / 时间 / 动作 / 对象检索（游标分页）；导出为异步任务并**自身也写审计**；只读接口 | A5-BE-02 | 检索返回稳定排序；导出记录含"谁导出了审计"；无修改入口 | 0.5 |
| A5-BE-04 | 敏感访问与保留归档 | BE | 客户资产包、成本数据、审计日志查看单独留痕；保留 ≥ 12 个月策略与归档任务占位（`QT-10`） | A5-BE-03 | 查看成本 / 审计也产生审计；归档任务可配置 | 0.5 |
| A5-FE-01 | 审计列表与详情 | FE | 多条件筛选、列表、详情（前后值 diff、trace_id、IP）、只读标识 | A5-BE-03 | 前后值对比可读；无可编辑控件 | 0.5 |
| A5-FE-02 | 审计导出与只读 | FE | 导出（异步进度 + 下载）、导出历史、权限点控制 | A5-FE-01 | 无 `audit:export` 不显示导出；导出后审计列表新增一条 | 0.5 |
| A5-INF-01 | 运行日志与观测 | INF | Pino 字段规范、trace_id 贯通、OTel 接入、日志平台入口（后台只放跳转链接，不入库） | A0-BE-01 | 请求可串 trace；后台"运行日志"入口可跳转；日志无密钥 | 0.5 |
| A5-QA-01 | 不可篡改与留痕用例 | QA | 登录 / 权限 / 资产 / 配置 / 导出 / 任务 / 敏感访问 7 类留痕 | A5-BE-04 | 用例全绿；篡改尝试失败 | 0.5 |

**本批门禁**：关键操作全留痕；审计不可改；导出本身留痕；运行日志与审计分离。

### 6.7　A6 任务中心与队列骨架

**目标**：所有耗时操作走统一任务协议，前端有统一进度体验。**对应**：架构 §6.4 / §3.3；M-05；`D-02` / `D-08`。

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| A6-BE-01 | 任务协议与状态机 | BE | `media_tasks` / `media_items` 基表；状态机**对齐架构 §3.6 九态**（排队 / 生成中 / 部分失败 / 待预览 / 已勾选 / 已导出 / 已入库 / 失败 / 已取消），M0 先点亮排队 / 生成中 / 部分失败 / 失败 / 已取消，其余状态由 B3 / M1 点亮；提交返回 `{taskId, estimatedItems, estimatedCost, estimatedSeconds}`；`Idempotency-Key` 24 小时去重 | A0-BE-02、A0-SH-01 | 重复提交返回同一任务；缺预估字段拒绝提交；状态枚举与架构 §3.6 一致；流转有单测 | 1.0 |
| A6-BE-02 | 队列骨架 | BE | BullMQ 队列组（`script` / `image` / `video` / `export` / `verify`，共 9 个具体队列）；worker 按 `QUEUE` 启动；重试与退避、死信、并发上限；scheduler 与 Redis 锁 | A0-BE-02 | 五个队列组可独立启停；单队列积压不影响其他队列 | 1.0 |
| A6-BE-03 | 进度推送 | BE | SSE `/media-tasks/{id}/events`（心跳、断线重连、Last-Event-ID）+ 轮询兜底；进度落库而非只在内存 | A6-BE-01 | 断网后轮询可恢复；进程重启进度不丢 | 1.0 |
| A6-BE-04 | 任务中心接口 | BE | 跨类型任务列表 / 详情（按客户、状态、类型、时间筛选）、取消、仅重试失败项、失败明细行号 | A6-BE-02 | 取消只影响未开始项；重试不重复成功项 | 0.5 |
| A6-BE-05 | Outbox 事件 | BE | `outbox_events` 写入与投递（至少一次 + 幂等消费）；业务写入与事件同事务 | A0-BE-02 | 事务回滚不产生事件；重复投递不重复处理 | 0.5 |
| A6-INF-01 | 队列监控 | INF | 队列长度 / 等待时长 / 失败率指标、告警规则、worker 健康检查 | A6-BE-02 | 积压与失败率可看；阈值告警可触发 | 0.5 |
| A6-FE-01 | 任务中心 | FE | 列表（类型 / 状态 / 客户 / 时间）、详情（进度条、逐项状态、失败明细、重试 / 取消） | A0-FE-02 | 任务可筛选；失败项可单独重试；取消有确认 | 0.5 |
| A6-FE-02 | 进度组件与角标 | FE | 可复用 SSE 进度组件、全局任务角标、断线降级为轮询、完成通知 | A6-FE-01 | 组件可被后续批次直接复用；断网提示清晰 | 0.5 |
| A6-QA-01 | 幂等 / 取消 / 断线用例 | QA | 重复提交、取消、重试、断线恢复、进程重启恢复 | A6-BE-04 | 用例全绿；无重复产物 | 0.5 |

**本批门禁**：提交 → SSE → 完成 / 失败闭环；幂等与取消生效；队列隔离；进度落库可恢复。

### 6.8　A7 AI 配置与调用底座

**目标**：四层配置可管、密钥安全、Mock 可跑通、调用有账本。**对应**：P-08、PRD §5.4.4；`R-23`；架构 §2.6 / §7.7；`D-10` 前置。

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| A7-BE-01 | 供应商与模型 | BE | `ai_providers`（Base URL、密钥 AES-256-GCM 密文、状态）、`ai_models`（上下文、最大输出、默认参数 JSONB、连通性测试）；出参只给 `hasApiKey` | A0-BE-02、A1-BE-03 | 密钥不出现在响应 / 日志 / 前端 bundle；连通性测试有超时与错误码 | 1.0 |
| A7-BE-02 | 任务映射与提示词 | BE | `ai_task_mappings`（任务类型 → 主 / 备模型 + 任务级参数）、`ai_configs` / `ai_config_versions`（提示词、行业指南）；保存即快照、可回滚、回滚产生新版本 | A7-BE-01 | 合并优先级：任务 > 模型 > 供应商；回滚不覆盖历史 | 1.0 |
| A7-BE-03 | ai-sdk 适配器与 Mock | BE | Provider 适配器接口（方言差异：thinking 开关、JSON 模式、联网搜索）；`platform.ai` 唯一出口；Mock Provider（固定延迟与固定产物）；路由与降级骨架 | A7-BE-02 | 业务模块不直接引模型 SDK；Mock 可被 CI / 压测复用 | 1.0 |
| A7-BE-04 | 调用账本 | BE | `ai_call_logs` / `ai_usage` append-only、按月分区；记录任务、模型、耗时、token / 张 / 秒、估算金额、成败、错误码 | A7-BE-03 | 每次调用有记录；账本禁改；可按客户 / 模型 / 批次查询 | 0.5 |
| A7-FE-01 | 供应商与模型页 | FE | 供应商列表 / 新建 / 编辑 / 启停、密钥输入（只回显是否已配置）、模型列表与默认参数、连通性测试 | A0-FE-02 | 密钥输入后不可回读；测试结果与错误可读 | 0.5 |
| A7-FE-02 | 映射与提示词页 | FE | 任务映射（主 / 备模型、参数覆盖）、提示词编辑与版本历史、回滚确认 | A7-FE-01 | 版本可 diff；回滚需二次确认 | 1.0 |
| A7-FE-03 | 调用日志 | FE | 按任务 / 模型 / 客户 / 时间查询；耗时与费用列；失败原因 | A7-FE-01 | 列表不返回大字段；金额口径与后端一致 | 0.5 |
| A7-QA-01 | 密钥 / 回滚 / Mock 用例 | QA | 密钥泄漏扫描、版本回滚、Mock 全链路、权限（`ai:configure` 特殊权限） | A7-BE-04 | 日志 / 响应 / bundle 无密钥；无权限不可改配置 | 0.5 |

**本批门禁**：四层配置闭环；Mock 调用记账；密钥安全通过自查；人类完成 **H2 AI 门**（§3.4）。

### 6.9　B0 行业包与表单设计器

**目标**：行业差异用配置表达，不发版；电商行业包 v1 可发布。**对应**：P-14 ~ P-16 / P-18、PRD §5.4.7 ~ §5.4.8；`R-11` / `R-12` / `R-13` / `R-15`。

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| B0-BE-01 | 行业包与版本状态机 | BE | `industry_packs` / `industry_pack_versions`；草稿 / 已发布 / 已弃用；发布后不可变；复制行业包；与行业绑定 | A3-BE-01 | 已发布版本修改被拒；复制生成新草稿 | 1.0 |
| B0-BE-02 | Schema 存储与七项校验 | BE | `form_schemas`（JSON Schema + UI 元数据）；校验：变量引用完整性、必填满足生成链路、联动成环、枚举来源有效、引用资产存在、key 唯一、字段总数 ≤ 60 | B0-BE-01 | 七项逐条可测；失败返回 40002 与具体原因 | 1.5 |
| B0-BE-03 | 合规规则集 | BE | `compliance_rules`：禁用词（通用 / 行业 / 客户）、强制提示语、必填资质、审核要点；按行业包版本生效 | B0-BE-01 | 规则可按行业 / 客户覆盖；命中可被后续校核引用 | 0.5 |
| B0-BE-04 | 发布审批 | BE | 草稿 → 自动校验 → 双人复核 → 发布；编辑与发布权限分离；`SoDGuard`；发布审计 | B0-BE-02、A2-BE-05 | 同一人编辑 + 发布被拒；发布后生成版本快照 | 0.5 |
| B0-BE-05 | 客户绑定与快照 | BE | 行业包 → 客户绑定；客户级覆盖入口；要素卡保存 `form_schema_id` 快照引用；历史不回改 | B0-BE-04 | 换行业包不影响历史要素卡；覆盖项可追溯 | 0.5 |
| B0-FE-01 | 行业包与版本 | FE | 行业包列表、版本列表、状态、复制、发布审批入口 | A0-FE-02 | 状态与操作按权限显示；发布前展示校验结果 | 0.5 |
| B0-FE-02 | 表单设计器 | FE | 14 类字段白名单、字段属性（key / 类型 / 必填 / 进入生成 / 变量优先级 / 参与校核 / 可检索 / 生效范围）、分组与排序、两级联动 | B0-BE-02 | 类型不可越白名单；联动最多两级且可检测成环；字段计数提示 | 1.5 |
| B0-FE-03 | 试填预览 | FE | 客户视角预览、真实要素卡试填、变量渲染结果预览 | B0-FE-02 | 试填缺失必填时禁止提交；渲染结果与后端一致 | 0.5 |
| B0-FE-04 | 合规规则集编辑 | FE | 禁用词、强制提示语、资质字段、审核要点；行业 / 客户作用域 | B0-FE-01 | 规则可启用 / 停用；变更进审计 | 0.5 |
| B0-FE-05 | 导入导出 JSON | FE | 行业包 JSON 导出 / 导入（校验后落为草稿） | B0-FE-01 | 导入非法结构被拒；导入不直接发布 | 0.5 |
| B0-QA-01 | 校验 / 快照 / 权限分离 | QA | 七项校验、双人发布、历史快照、字段上限 | B0-BE-05 | 用例全绿；发布链路有审计 | 0.5 |

**本批门禁**：电商行业包 v1 可配置、校验、双人发布；客户可绑定；历史快照可复现；发布与编辑权限分离。

### 6.10　B1 资产与模板最小集

**目标**：15 类资产可管理、可引用保护、模板可校验准入。**对应**：A-01 ~ A-05、PRD §5.3；`R-02` / `R-03`；架构 §7.3 / §7.9。

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| B1-BE-01 | 资产与引用 | BE | `assets` / `asset_versions` / `asset_refs`；15 类 `asset_type`；客户归属 + 软删；被引用只能停用（`R-02`）；已入库修改产生新版本（`R-03`） | A3-BE-05、A5-BE-02 | 被引用删除返回 40901 与引用清单；停用不删数据 | 1.0 |
| B1-BE-02 | 预签名上传 | BE | `/uploads/presign` → 直传 → `complete` 校验（headObject）→ 写元数据；hash 秒传；大小 / 类型限制 | A0-BE-01 | 应用服务器不中转大文件；秒传命中不重复存 | 0.5 |
| B1-BE-03 | 模板图层校验 | BE | `ag-psd` 解析 PSD；图层命名约定校验（工程规范 10）；缺失 / 重复 / 未知前缀拒绝入库；`layer_config` 快照与预览图 | B1-BE-02 | 不合规模板返回明确缺失图层；解析失败不静默跳过 | 2.0 |
| B1-BE-04 | 合成预览骨架 | BE | sharp 读取模板 + 素材生成预览图；预览失败降级为模板图 + 标记 | B1-BE-03 | 预览可生成；失败有降级标记 | 0.5 |
| B1-FE-01 | 资产库 | FE | 按类型 / 行业 / 客户筛选；上传 / 在线创建；启停 / 排序；批量操作骨架 | A0-FE-02 | 15 类可筛选；上传进度可见；停用后不可被新任务引用 | 1.0 |
| B1-FE-02 | 引用与删除保护 | FE | 引用关系查看（双向）、删除失败展示引用清单与替换入口 | B1-FE-01 | 删除失败文案可操作；引用计数准确 | 0.5 |
| B1-FE-03 | 模板上传与预览 | FE | 模板上传、图层校验结果（通过 / 缺失清单）、真实合成预览 | B1-FE-01 | 校验失败不可入库；预览与模板一致 | 0.5 |
| B1-QA-01 | 引用 / 版本 / 解析用例 | QA | 引用保护、版本新增、PSD 解析失败、秒传 | B1-BE-04 | 用例全绿；失败模板不入库 | 0.5 |

**本批门禁**：资产库可用；引用保护生效；模板解析失败明确拒绝；预览可生成。

### 6.11　B2 要素卡与脚本模板

**目标**：行业包 schema 能真正渲染成表单并产出可检索要素卡。**对应**：S-01 / S-02 / S-04、PRD §5.1.1 / §5.1.6；`R-11` / `R-14`。

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| B2-BE-01 | 要素卡、参考物料与物化索引 | BE | `brief_cards` / `brief_card_index`；动态值存 JSONB + 每卡每字段一行索引；参考物料关联与白底图标记（S-02）；按客户与品类检索；必填 / 进入生成校验（`R-14`） | B0-BE-05 | 索引与 JSONB 一致；缺必填禁止提交生成 | 1.0 |
| B2-BE-02 | 脚本模板 | BE | `script_templates` + 版本；启停；结构化字段（方向 / 钩子 / 段落 / 时长档） | B0-BE-01 | 修改产生新版本；停用不影响历史引用 | 0.5 |
| B2-FE-01 | form-engine 包 | FE | 14 类字段渲染器、分组 / 分栏 / 折叠、两级联动、校验、只读模式；只依赖 schema，不写行业分支 | B0-FE-02 | 14 类逐类有 story / 用例；新增行业包无需改代码 | 1.5 |
| B2-FE-02 | 要素卡页面 | FE | 列表 / 详情 / 新建 / 编辑 / 复制 / 停用；按客户与品类筛选；填写完整度提示 | B2-FE-01 | 缺必填不可保存；复制保留 schema 版本引用 | 1.0 |
| B2-FE-03 | 脚本模板 | FE | 脚本模板列表 / 版本 / 启停、结构化字段编辑 | B2-FE-01 | 修改产生新版本；停用不影响历史引用 | 0.5 |

**本批门禁**：任意行业包 schema 可在前端渲染；要素卡可检索；模板版本化；无行业硬编码分支。

### 6.12　B3 导出骨架与归档

**目标**：勾选 → 导出 → 命名 → 审计 → 签名下载的最小闭环。**对应**：E-01 ~ E-03、PRD §5.5；`R-01` / `R-05`；架构 §7.5 / §6.5。

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| B3-BE-01 | 导出与清单 | BE | `exports` / `export_items` / `delivery_manifests`；导出异步任务、状态、逐项结果；清单快照不可变 | A6-BE-01 | 只导出勾选项；清单含条数 / 规格 / 脚本编号 / 成本 | 1.0 |
| B3-BE-02 | 命名与打包 | BE | 命名服务接入（`R-01`）；zip 异步打包；产物短时效签名 URL（不进 JSON）；临时产物 3 天清理 | B3-BE-01、A4-BE-03 | 同名自动序号；URL 过期失效；大文件不中转 | 1.0 |
| B3-BE-03 | 导出审计 | BE | 谁、何时、哪些、导出到哪、包大小、下载次数；导出失败也留痕 | B3-BE-02、A5-BE-02 | 每次导出有记录；下载也留痕 | 0.5 |
| B3-FE-01 | 导出弹窗与记录 | FE | 勾选汇总、预估条数 / 成本、导出进度、历史记录、重新下载 | A6-FE-02 | 未勾选不可导出；进度可恢复；过期提示重导 | 1.0 |
| B3-FE-02 | 交付清单 | FE | 清单详情、按批次下载、字段与后端一致 | B3-FE-01 | 清单不可编辑；导出记录可追溯 | 1.0 |
| B3-QA-01 | E-01 ~ E-03 验收 | QA | 勾选导出、命名、审计、签名 URL 过期 | B3-BE-03 | 用例全绿；导出抽样与审计一致 | 0.5 |

**本批门禁**：导出闭环可演示；命名与审计正确；签名 URL 安全；M0 全链路演示通过。

> **M0 合计**：12 批、68.5 EPD，与 §5.2 一致。

---

### 6.13　M1 任务组（脚本与图片线）

> M1-1 ~ M1-4 的任务组已到「可直接开工」粒度（1–3 EPD），规则同 M0：开卡时补测试数据与验收证据；组内如需再拆子卡由 Worker 在批次计划里补充。

#### M1-1　脚本生成与解析（14 EPD）

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| M1-1-BE-01 | 生成任务与提示词组装 | BE | 批量生成任务（`media_tasks` type=script）；参数 → 模板 → 要素卡 → 上下文槽位；调用 `platform.ai`；失败重试与逐条结果 | B2-BE-02、A7-BE-03 | 批量可提交；逐条独立成败；提示词变量缺失即拒绝提交 | 2.0 |
| M1-1-BE-02 | 生成上下文与 RAG 召回 | BE | 行业指南 / 历史佳作 / 模板三级上下文；召回失败按级降级；召回来源写任务快照 | A7-BE-02、A7-BE-03 | 三级降级可测；上下文快照可复现；不跨客户召回 | 1.5 |
| M1-1-BE-03 | JSON 解析与结构化 | BE | 模型输出 → 分镜 / 标签 / 结构化字段；解析失败保留原文与错误位置，可重试 | M1-1-BE-01 | 解析失败不丢原文；重试只跑失败项；单测覆盖异常 JSON | 2.0 |
| M1-1-BE-04 | 自动质量校核（基础四类） | BE | 结构完整、时长、禁用词、必含项四类；拦截 / 警告分级；规则来自行业包合规集 | M1-1-BE-03、B0-BE-03 | 四类逐条可测；命中可定位到字段；警告不拦截入库 | 2.0 |
| M1-1-BE-05 | 卖点库 | BE | 行业级 / 客户级卖点、标签、使用次数统计；停用不删 | A4-BE-01 | 客户级覆盖行业级；计数准确；停用不影响历史引用 | 1.5 |
| M1-1-FE-01 | 生成向导 | FE | 选客户 / 模板 / 要素卡 / 数量 / 参数；提交前预估条数与成本；Mock 先行 | M1-1-BE-01 | 缺必填不可提交；预估与实际偏差可解释 | 2.0 |
| M1-1-FE-02 | 结果列表与失败明细 | FE | 逐条状态、失败原因、原文查看、单条重试；按任务筛选 | M1-1-BE-03 | 失败项可单条重试；列表刷新不丢筛选 | 1.5 |
| M1-1-QA-01 | 生成链路用例 | QA | 生成 → 解析 → 校核 → 失败重试；Mock 与真实 Provider 各一轮 | M1-1-BE-04 | 用例进 CI；成本与耗时记录可查 | 1.5 |

#### M1-2　审核入库与编号（12 EPD）

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| M1-2-BE-01 | 审核状态机与批量审核 | BE | 待审核 / 通过 / 驳回 / 局部重写；批量操作；审核人与生成人 SoD | A6-BE-01、M1-1-BE-04 | 同一人生成 + 审核被拒（40304）；批量结果逐条返回 | 2.0 |
| M1-2-BE-02 | 原子取号与编号规则 | BE | 客户编码-YYMMDD + 序号；Redis 原子取号；唯一、不重用 | A4-BE-03 | 并发取号不重复；作废号不回收 | 1.5 |
| M1-2-BE-03 | 入库与标签 | BE | 入库为 `scripts`；标签化与检索；入库快照 | M1-2-BE-01 | 未过审不可入库；标签可筛选；快照可复现 | 1.5 |
| M1-2-BE-04 | 版本与引用写入（基础） | BE | 已入库修改 → 新版本 + 重新审核；引用写入 `script_refs` | M1-2-BE-01、B1-BE-01 | 修改不覆盖旧版本；引用关系可反查 | 2.0 |
| M1-2-FE-01 | 审核工作台 | FE | 待审列表、并排对比、通过 / 驳回 / 局部重写、批量 | M1-2-BE-01 | 键盘可完成审核；驳回理由必填 | 2.0 |
| M1-2-FE-02 | 入库与编号展示 | FE | 入库操作、编号展示与复制、版本标记 | M1-2-BE-02 | 编号格式正确；版本切换不串数据 | 1.5 |
| M1-2-QA-01 | 审核 / 编号 / 版本用例 | QA | SoD、并发取号、修改生版本、入库校验 | M1-2-BE-04 | 用例全绿；审计可查 | 1.5 |

#### M1-3　图片生产线（15 EPD）

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| M1-3-BE-01 | render 包与 PSD 解析 | BE | `packages/render`：`ag-psd` 读图层、按前缀定位可替换层、坐标与字体提取；解析结果快照 | B1-BE-03、A6-BE-02 | 命名图层缺失拒绝渲染；解析结果可缓存 | 2.5 |
| M1-3-BE-02 | 抠图与缓存 | BE | 本地 ONNX 抠图（CPU）；按内容 hash 缓存；失败退原图并标 `low_quality` | M1-3-BE-01 | 抠图不出内网；失败降级有原因码；同图不重复推理 | 2.0 |
| M1-3-BE-03 | 合成与多规格编码 | BE | sharp 合成、文字替换、安全区 / Logo / 警示语；JPG / PNG（调色板色数）；单张 ≤ 10s | B1-BE-04、A4-BE-04 | 多规格尺寸正确；超限降质有标记；耗时达标 | 2.5 |
| M1-3-BE-04 | image 队列与批次快照 | BE | 按「模板 × 商品图 × 规格」展开；批次号原子取号；参数与命名快照；中断恢复 | M1-3-BE-03、A6-BE-04 | 100 张中断后可续跑；批次快照可复现 | 2.0 |
| M1-3-BE-05 | 质量校验与低质量标记 | BE | 安全区、Logo 完整、主体不变形、警示语四项；失败不静默通过 | M1-3-BE-03 | 低质量条目默认不勾选；原因码来自字典 | 1.5 |
| M1-3-FE-01 | 批次提交与网格预览 | FE | 物料 / 模板 / 规格选择、预估条数、提交、网格预览与单张放大 | M1-3-BE-04 | 50 张预览不卡；失败图有占位与原因 | 2.0 |
| M1-3-FE-02 | 失败重试与低质量筛选 | FE | 失败项重试、低质量筛选、批次历史 | M1-3-BE-05 | 重试只跑失败项；筛选可组合 | 1.0 |
| M1-3-QA-01 | 图片线端到端 | QA | 模板准入 → 合成 → 降级 → 批次恢复；性能冒烟 | M1-3-BE-05 | 端到端通过；低质量可追踪 | 1.5 |

#### M1-4　预览勾选、导出与收口（14 EPD）

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| M1-4-BE-01 | 勾选持久化与恢复 | BE | 勾选状态与任务项绑定；刷新 / 换设备恢复；未勾选保留 | M1-3-BE-04、A6-BE-04 | 并发勾选不丢；取消勾选即时生效 | 1.5 |
| M1-4-BE-02 | 导出打包与命名 | BE | 按勾选导出；目录结构；命名快照；zip 流式打包（级别 9）；签名 URL | B3-BE-02、M1-4-BE-01 | 未勾选不可导出；同名加序号；URL 短时效 | 2.0 |
| M1-4-BE-03 | 归档骨架 | BE | 导出成功登记 `assets(type=render)`；可被后续复用 | B3-BE-01、M1-4-BE-02 | 归档幂等；失败不回滚导出记录 | 1.5 |
| M1-4-BE-04 | 交付清单 | BE | 清单快照（条数 / 规格 / 编号 / 成本）；按批次查询 | M1-4-BE-02 | 清单不可变；字段与导出包一致 | 1.5 |
| M1-4-FE-01 | 快筛网格与快捷键 | FE | 网格 / 并排预览、保留 / 淘汰 / 收藏、全选反选、同组收敛 | M1-4-BE-01 | 50 张操作不卡；快捷键可发现 | 2.0 |
| M1-4-FE-02 | 导出记录与交付清单 | FE | 导出进度、历史、重下载、清单详情 | M1-4-BE-02 | 过期提示重导；清单不可编辑 | 1.5 |
| M1-4-INF-01 | 字体自检与性能 | INF | 镜像内置中文字体启动自检；图片线并发与内存上限；预览性能埋点 | M1-3-BE-03 | 缺字体启动即失败；并发参数可配 | 1.0 |
| M1-4-QA-01 | AC-01 端到端与金融试跑 | QA | 真实客户走通要素卡 → 脚本 → 图片 → 导出；金融行业包 1 个批次 | M1-4-BE-04、B0-BE-04 | AC-01 达成；交付周期与单条成本可测 | 3.0 |

### 6.14　M2 任务组（视频线与提效）

#### M2-1　视频逐镜生成（15 EPD）

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| M2-1-BE-01 | 分镜拆解 | BE | 脚本 → N 镜（场景 / 景别 / 时长 / 画面 / 台词）；不可解析给原文 | M1-1-BE-03、B2-BE-02 | 拆解结果可编辑；镜头数与时长校验 | 2.0 |
| M2-1-BE-02 | 关键帧生成 | BE | 每镜首帧（图生图）；参考物料锁定（电商白底图）；失败单镜重试 | M2-1-BE-01、A7-BE-03 | 主体不变形；失败不影响其他镜 | 2.0 |
| M2-1-BE-03 | 逐镜生成与重试 | BE | 图生视频；单镜独立超时 / 重试 / 换模型；成本按镜记账 | M2-1-BE-02 | 单镜重来不重跑整条；失败分类可查 | 2.5 |
| M2-1-BE-04 | 镜头并行与拼接前处理 | BE | 镜头并行度、超时、产物落盘与清单；为拼接准备统一编码 | M2-1-BE-03 | 并行不串镜；中断可恢复 | 1.5 |
| M2-1-BE-05 | 视频任务预估与预算 | BE | 转数 / 时长 / 成本预估；单任务预算上限；超限拒绝 | A6-BE-01、A7-BE-04 | 预估与实际可对账；超限 42902 | 1.0 |
| M2-1-FE-01 | 视频制作向导 | FE | 脚本、视频方向（必选）、人物 / 场景 / 景别 / 时长 / 数量、口播与 BGM | M2-1-BE-01 | 缺视频方向不可提交；预估展示清晰 | 2.0 |
| M2-1-FE-02 | 任务详情与镜头状态 | FE | 逐镜状态、失败原因、单镜重试入口、成本累计 | M2-1-BE-03 | 镜头级状态准确；重试有确认 | 2.0 |
| M2-1-QA-01 | 单条视频端到端 | QA | 脚本 → 分镜 → 关键帧 → 逐镜 → 产物；失败与重试用例 | M2-1-BE-04 | 单条视频跑通；成本可查 | 2.0 |

#### M2-2　拼接、校验与单镜替换（13 EPD）

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| M2-2-BE-01 | ffmpeg 拼接与包装 | BE | 拼接、字幕、Logo、警示语、BGM、音量归一；输出比例 / 时长 | M2-1-BE-04 | 音画同步；包装元素位置符合安全区 | 2.0 |
| M2-2-BE-02 | 成片自动校验 | BE | 时长 / 比例 / 黑帧 / 静音 / 字幕错字 / 合规；报告落任务项 | M2-2-BE-01 | 六项可测；失败原因可定位 | 2.0 |
| M2-2-BE-03 | 单镜替换 | BE | 指定镜重生成并替换；只失效该镜关联产物 | M2-1-BE-03 | 替换不重跑整条；版本可追溯 | 2.0 |
| M2-2-BE-04 | 命名与下载 / 导出 | BE | 通用字符 + 占位符命名；下载与导出双通道；同名加序号 | M1-4-BE-02、A4-BE-03 | 命名实时校验；未勾选不可下载 | 1.5 |
| M2-2-FE-01 | 在线预览与断点续播 | FE | 逐条播放 / 暂停 / 重播、断点续播、全选反选、来源脚本 | M2-2-BE-01 | 50 条预览可用；续播位置准确 | 2.0 |
| M2-2-FE-02 | 单镜替换与下载 | FE | 镜头时间轴、替换入口、下载 / 导出 | M2-2-BE-03 | 替换后预览即时更新；命名冲突提示 | 1.5 |
| M2-2-QA-01 | 校验 / 替换 / 命名用例 | QA | 六项校验、单镜替换、命名与下载 | M2-2-BE-04 | 用例全绿；失败项可重试 | 2.0 |

#### M2-3　快筛、变体与成片入库（15 EPD）

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| M2-3-BE-01 | 变体矩阵 | BE | 脚本 × 人物 × 场景 × 时长；2 轴交叉、单批上限、预估 | M2-1-BE-03 | 只支持声明的轴；超上限拒绝 | 2.0 |
| M2-3-BE-02 | 快筛 API | BE | 保留 / 淘汰 / 收藏、理由、同组收敛；筛选与统计 | M2-2-FE-01 | 操作幂等；理由进字典统计 | 1.5 |
| M2-3-BE-03 | 分片直传与秒传 | BE | 分片 / 断点续传 / hash 秒传 / 自动元数据；转码任务 | B1-BE-02 | 大文件不中转；续传可恢复 | 2.0 |
| M2-3-BE-04 | 版本链与采用版本 | BE | 成片版本链、「采用版本」标记、历史不可变 | M2-3-BE-03 | 采用版本唯一；回退可追溯 | 1.5 |
| M2-3-BE-05 | 素材库查询与批量操作 | BE | 双视图数据、批量标签 / 送审 / 打包下载 | M2-3-BE-04 | 批量操作异步可追踪；空结果不误导 | 2.0 |
| M2-3-FE-01 | 并排快筛与快捷键 | FE | 分组并排播放、保留 / 淘汰 / 收藏、同组只留最佳 | M2-3-BE-02 | 3 分钟可筛 50 条；误操作可撤销 | 2.0 |
| M2-3-FE-02 | 素材库双视图与批量 | FE | 列表 / 网格、筛选、批量操作、版本与采用标记 | M2-3-BE-05 | 视图切换保留筛选；批量有进度 | 2.0 |
| M2-3-QA-01 | 快筛效率与入库用例 | QA | 快筛效率、批量、分片 / 秒传、版本链 | M2-3-BE-05 | 效率基线达标；失败可恢复 | 2.0 |

#### M2-4　脚本增强与交付包（10 EPD）

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| M2-4-BE-01 | 脚本版本链与 diff | BE | 完整版本链、字段级 diff、回滚生成新版本 | M1-2-BE-04 | 回滚不删历史；diff 可读 | 2.0 |
| M2-4-BE-02 | 引用记录 | BE | 被哪些素材任务 / 成片引用；引用计数 | M2-4-BE-01 | 计数准确；停用前可查引用 | 1.0 |
| M2-4-BE-03 | 结构模板库 | BE | 人工创建 + 审核发布、使用计数；未发布不可引用 | M1-1-BE-04 | 审核分离；计数准确 | 1.5 |
| M2-4-BE-04 | 客户在线审核链接 | BE | 免登录、短时效、可作废、改稿快照、二维码；开关默认关闭 | M1-2-BE-03、`R-28` | 链接不可枚举；作废即时生效；访问留痕 | 1.5 |
| M2-4-BE-05 | Word 交付包 | BE | 编号 + 标题 + 分镜表；交付记录可查；飞书 P2 预留 | M2-4-BE-01 | 包内容与版本一致；重复导出留痕 | 1.5 |
| M2-4-FE-01 | 版本对比与模板库 | FE | 版本时间线、字段 diff、回滚；模板库审核与计数 | M2-4-BE-01 | 回滚需二次确认；模板状态清晰 | 1.5 |
| M2-4-QA-01 | 交付包与审核链接 | QA | 审核链接安全、Word 包内容、版本回滚 | M2-4-BE-05 | 用例全绿；安全项（越权 / 过期 / 作废）通过 | 1.0 |

#### M2-5　AI 治理、资产增强与第三行业（14 EPD）

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| M2-5-BE-01 | 资产版本 | BE | `asset_versions`、版本对比、历史快照 | B1-BE-01 | 修改生版本；历史可回看 | 1.5 |
| M2-5-BE-02 | 引用关系与失效替换 | BE | 双向引用查询、失效资产替换向导 | M2-5-BE-01 | 替换不破坏引用；操作留痕 | 1.5 |
| M2-5-BE-03 | 人物 / 场景 / 光影 / BGM 池 | BE | 池化管理、行业声明槽位、启停 | M2-5-BE-01 | 槽位由行业包声明；停用不影响历史 | 2.0 |
| M2-5-BE-04 | 提示词模板 | BE | 版本、生效范围（行业 / 客户 / 任务）、发布审核 | A7-BE-02 | 生效范围可叠加；回滚可查 | 1.5 |
| M2-5-BE-05 | 用途路由与降级 | BE | 任务 → 主 / 备模型；健康探测、超时降级、限流 | A7-BE-03 | 主模型失败自动降级；降级可观测 | 2.0 |
| M2-5-BE-06 | 预算闸门与成本聚合 | BE | 预占 / 结算、预算上限、按客户 / 批次 / 模型聚合 | A7-BE-04 | 超预算 100% 阻断；账本可对账 | 1.5 |
| M2-5-FE-01 | 资产增强页 | FE | 版本、引用、池管理、失效替换入口 | M2-5-BE-03 | 版本与引用关系可读 | 1.5 |
| M2-5-FE-02 | 成本看板 | FE | 成本趋势、模型分布、客户 / 批次下钻 | M2-5-BE-06 | 口径与后端一致；导出可用 | 1.5 |
| M2-5-QA-01 | 第三行业包配置与试跑 | QA | 第三个行业包配置 → 校验 → 发布 → 1 个批次试跑 | M2-5-BE-04、B0-BE-04 | 不写行业代码即可配置；试跑通过 | 1.0 |

### 6.15　M3 任务组（复用与回流）

#### M3-1　资产复用与口播增强（15 EPD）

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| M3-1-BE-01 | 复用率与排行统计 | BE | 按客户 / 资产 / 周统计复用率、排行；口径与看板一致 | M2-3-BE-05、M2-5-BE-01 | 口径可复算；空数据不误导 | 2.0 |
| M3-1-BE-02 | 复审任务与降权 | BE | 资产复审任务、过期提醒、降权 / 下线 | M3-1-BE-01 | 复审留痕；降权即时生效 | 2.0 |
| M3-1-BE-03 | 脚本效果标签 | BE | 起量 / 一般 / 未起量人工标注；检索 | M1-2-BE-04、M2-3-BE-04 | 标签可改但留痕；统计可查 | 1.5 |
| M3-1-BE-04 | 版本对比与回滚 | BE | 任一历史版本 diff、回滚为新版本 | M2-4-BE-01 | 回滚不覆盖历史；权限受控 | 2.0 |
| M3-1-BE-05 | 口播 TTS 与 lip sync | BE | 台词 → TTS → 唇形对齐；音色 / 语速配置；失败降级 | M2-1-BE-04、A7-BE-03 | 音画同步；失败可重试且不计费 | 2.5 |
| M3-1-BE-06 | 相似度提示与来源标签 | BE | 实拍 / AI / 混合标签；近 30 天相似度提示 | M3-1-BE-01 | 标签不可缺省；提示阈值可配 | 1.5 |
| M3-1-FE-01 | 复用看板与复审 | FE | 复用率 / 排行、复审列表、降权操作 | M3-1-BE-02 | 下钻可用；操作有确认 | 2.0 |
| M3-1-QA-01 | 复用与口播用例 | QA | 复用口径、复审、口播同步、相似度 | M3-1-BE-05 | 用例全绿；口径与看板一致 | 1.5 |

#### M3-2　成片运营与效果回流（16 EPD）

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| M3-2-BE-01 | 脚本-素材关联与血缘 | BE | 关联 / 解除、血缘视图、未关联待办、关联率统计 | M2-3-BE-05、M1-2-BE-03 | 关联率可按客户 / 周统计；待办可清理 | 2.0 |
| M3-2-BE-02 | 素材分享链接 | BE | 短时效、可作废、外部访问留痕、开关默认关闭 | A5-BE-03、`R-28` | 不可枚举；作废即时；访问有审计 | 2.0 |
| M3-2-BE-03 | 送审与外部提审登记 | BE | 内部送审、外部平台 / 计划 / 时间、驳回原因与截图凭证 | M3-2-BE-01 | 状态可追踪；附件走对象存储 | 2.0 |
| M3-2-BE-04 | 投放登记与日指标 | BE | 平台 / 账户 / 素材 ID / 计划 ID；日 × 素材指标（消耗 / 曝光 / CTR / CVR / ROI） | M2-3-BE-05 | 手工登记幂等；累计口径正确 | 3.0 |
| M3-2-BE-05 | 自动归档完善 | BE | 导出 / 送审 / 投放后自动归档策略；批量归档 | B3-BE-01、M2-3-BE-04 | 归档幂等；失败可重跑 | 1.0 |
| M3-2-BE-06 | 按组导出与批量重导 | BE | 按组 / 清单导出、批量重导、失败项重导 | B3-BE-02 | 重导不重复归档；清单一致 | 1.5 |
| M3-2-FE-01 | 关联 / 送审工作台 | FE | 血缘由、未关联待办、送审登记、凭证上传 | M3-2-BE-03 | 关联操作可撤销；待办可筛选 | 2.0 |
| M3-2-FE-02 | 投放登记与指标 | FE | 登记表单、日指标录入 / 导入、趋势图 | M3-2-BE-04 | 导入校验清晰；指标可累计 | 1.0 |
| M3-2-QA-01 | 关联率与回流用例 | QA | 关联率、分享安全、送审、指标累计 | M3-2-BE-04 | 用例全绿；审计可查 | 1.5 |

#### M3-3　外部访问与系统完善（14 EPD）

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| M3-3-BE-01 | SSO / 手机号登录 | BE | 手机号验证码登录；SSO 适配器（OIDC / SAML 至少一种可插拔）；会话与吊销 | A1-BE-02 | 未配置 SSO 不影响密码登录；吊销即时生效 | 3.0 |
| M3-3-BE-02 | 系统配置完善 | BE | 通知、导出、命名、阈值、保留期配置化；版本与回滚 | A4-BE-02 | 配置项前后端同源；变更留痕 | 1.5 |
| M3-3-BE-03 | 成片入库完善 | BE | 分片 / 秒传、版本链、素材库批量操作收口 | M2-3-BE-05 | 大文件与批量稳定；失败可恢复 | 2.0 |
| M3-3-BE-04 | 检索与性能收口 | BE | 全局检索（脚本 / 素材 / 资产）、索引与慢查询治理 | M3-2-BE-01 | P95 ≤ 500ms；索引命中可观测 | 2.0 |
| M3-3-FE-01 | 登录方式与配置页 | FE | 手机号登录、SSO 入口、系统配置页 | M3-3-BE-01 | 登录方式可切换；配置影响提示 | 2.0 |
| M3-3-FE-02 | 全局搜索与标签 | FE | 全局搜索、标签筛选、结果高亮 | M3-3-BE-04 | 跨类型搜索可用；空态清晰 | 1.5 |
| M3-3-QA-01 | 回归与性能 | QA | 登录方式、配置、检索、M0–M3 回归 | M3-3-BE-02 | 回归通过；性能达标 | 2.0 |

### 6.16　M4 任务组（交付闭环）

#### M4-1　爆量判定与脚本反哺（7 EPD）

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| M4-1-BE-01 | 爆量判定与阈值配置 | BE | 判定任务（消耗阈值 + ROI 达标）；阈值只读 `system_configs`；可重跑、幂等 | M3-2-BE-04、A4-BE-02 | 阈值单源；重跑不重复计；判定结果可追溯 | 2.0 |
| M4-1-BE-02 | 脚本权重反哺 | BE | 爆量素材 → 脚本评级 → 权重映射 → RAG 召回加权 | M4-1-BE-01、M1-1-BE-02 | 权重可查可回滚；派生指标不落库 | 1.5 |
| M4-1-BE-03 | 关联率与排行查询 | BE | 关联率、复用排行、爆量榜查询接口 | M4-1-BE-01 | 排序稳定；口径与看板一致 | 1.5 |
| M4-1-FE-01 | 爆量榜与关联率视图 | FE | 爆量榜、关联率、复用排行、下钻 | M4-1-BE-03 | 榜单可筛选；数字可追溯到明细 | 1.5 |
| M4-1-QA-01 | 判定口径与幂等用例 | QA | 阈值边界、重跑、反哺、权限 | M4-1-BE-02 | 用例全绿；越权不可见 | 0.5 |

#### M4-2　度量看板与项目验收（5 EPD）

| 编号 | 任务 | 端 | 内容与产出 | 依赖 | 验收要点 | EPD |
| --- | --- | --- | --- | --- | --- | --- |
| M4-2-BE-01 | 指标汇总与导出 | BE | 生产 / 质量 / 成本 / 资产四类汇总；导出异步 | M4-1-BE-03 | 口径统一；导出留痕 | 1.5 |
| M4-2-FE-01 | 总看板 | FE | 四类指标总览、趋势、对比 | M4-2-BE-01 | 首屏 ≤ 2s；空态 / 加载态完整 | 1.5 |
| M4-2-INF-01 | 告警与运行报告 | INF | 任务成功率、成本、队列积压告警；周报模板 | A6-INF-01 | 告警可触发；报告可导出 | 1.0 |
| M4-2-QA-01 | M4 验收与全量回归 | QA | M4 验收脚本、M0–M4 回归、性能冒烟 | M4-2-BE-01 | 全量回归通过；验收记录归档 | 1.0 |

---

## 7　七个管理模块专项（产品与交互口径）

> 本章是 A1–A7 的"做什么、页面长什么样、规则是什么"的补充，**不重复** WBS 的实现细节。页面路由与权限点见附录 B / C。

### 7.1　用户管理（A1 / P-01）

| 项 | 内容 |
| --- | --- |
| 页面 | `/login`、`/system/users`、`/system/users/new`、`/system/users/:id`、`/system/departments`（部门管理） |
| 接口 | `POST /auth/login`、`/auth/refresh`、`/auth/logout`、`GET /me`、`GET /users`、`POST /users`、`PATCH /users/{id}`（含角色分配）、`POST /users/{id}/transfer-customers`；`GET /departments/tree`、`POST/PATCH /departments`、`POST /departments/{id}/disable`、`/enable`（不提供删除） |
| 关键规则 | 部门最多两级；手机号唯一；一人可多角色；离职**停用不删**，名下客户必须转交；超管建议 ≤ 2 人、授予二次确认并审计；停用即时生效 |
| 页面状态 | 空态（无用户 / 无搜索结果）、加载骨架、错误重试、无权限 403；停用用户列表默认隐藏、可筛选查看 |
| 验收 | ① 新建用户 → 分配角色 → 登录成功；② 停用后无法登录且在线会话失效；③ 删除按钮不存在，只有停用；④ 部门超两级被拒；⑤ 用户变更进审计 |

### 7.2　角色管理（A2 / P-02、P-03）

| 项 | 内容 |
| --- | --- |
| 页面 | `/roles`、`/roles/:id`（编辑器：权限树 / 数据范围 / 特殊权限三区） |
| 接口 | `GET/POST/PATCH /roles`、`GET /permissions`（复制角色 = 读取现有角色后 `POST /roles`，不加端点） |
| 关键规则 | 仅超管内置且不可改（**仅显示名可改**）；其余角色全部可配；新角色默认全空；特殊权限单独授予、不随复制带入；六类数据范围；三对 SoD 保存即校验；变更即时生效、留痕、通知受影响用户；角色 ≤ 20 个建议值 |
| 交互要点 | 权限点按"模块 × 操作"分组勾选；范围选择展示"可覆盖客户数"；SoD 命中时高亮冲突对并禁止保存；保存前展示"影响 N 名用户" |
| 验收 | ① 新建角色 → 勾选权限 → 分配用户 → 页面即时变化；② 复制角色不携带特殊权限；③ 三对 SoD 各 1 条拒绝用例；④ 角色停用后在线用户下次请求失效；⑤ 变更审计含前后值 |

### 7.3　数据字典与系统配置（A4 / P-06、P-13 部分）

| 项 | 内容 |
| --- | --- |
| 页面 | `/dicts`、`/dicts/:type`（树 / 词表双视图）、`/system/configs` |
| 接口 | `GET/POST/PATCH /dicts`、`/dicts/{type}/items`、`GET/PUT /system/configs` |
| 关键规则 | 一张通用枚举表；编码不可改、名称可改；按行业作用域三层合并（本行业 + 父行业 + 通用）；变更只影响新数据、历史保留快照（`R-10`）；阈值 / 上限只存 `system_configs`（`R-26`） |
| 交互要点 | 编码字段创建后置灰；停用项在历史引用处显示"已停用"而非消失；配置项展示版本与变更记录；阈值修改二次确认并提示影响范围 |
| 验收 | ① 行业二级树与词表共用一张表；② 三层合并结果正确；③ 改名称后历史数据不变；④ 前端上限与后端 DTO 读同一配置；⑤ 配置变更审计可查 |

### 7.4　客户管理（A3 / P-04、P-05）

| 项 | 内容 |
| --- | --- |
| 页面 | `/industries`、`/customers`、`/customers/new`（分步）、`/customers/:id`、`/customer-groups`、`/customer-fields/approvals` |
| 接口 | `GET/POST/PATCH /industries`、`GET/POST/PATCH /customers`、`/customer-groups`、`/customers/{id}/fields`、`/customer-fields/{id}/approve`、`POST /customers/{id}/apply-industry-pack` |
| 关键规则 | 行业两级树；一级名称全局唯一、二级同父唯一；客户名称同末级行业唯一；**简称必填**（用于全部自动命名）；客户必须归属末级行业、不可跨行业移动；暂停只读、结束只读归档（`R-07`）；基础字段 ≤ 10 且永不进入生成，进入生成字段 ≤ 5 且必须审批 |
| 交互要点 | 新建客户为分步表单（行业 → 档案 → 交付偏好 → 资产包），可回退；状态为暂停 / 结束时顶部只读横幅；客户组作为授权单位，批量授权入口清晰 |
| 验收 | ① 重名返回 40902；② 简称缺失 42201；③ 暂停客户不能提交新任务；④ 客户组授权后范围正确；⑤ 字段超限 40001、未审批字段不进入生成 |

### 7.5　日志管理（A5 / P-07）

| 项 | 内容 |
| --- | --- |
| 页面 | `/audit-logs`、`/audit-logs/:id`、`/system/logs`（运行日志平台跳转） |
| 接口 | `GET /audit-logs`、`POST /audit-logs/export` |
| 关键规则 | 审计 append-only（DB 层禁 UPDATE / DELETE）；保留 ≥ 12 个月（`Q-08` 待确认最终值）；导出本身也审计；敏感数据访问（客户资产包 / 成本 / 审计）单独留痕；只读，无编辑入口 |
| 交互要点 | 筛选：人 / 客户 / 时间 / 动作 / 对象；详情展示前后值 diff、trace_id、IP / UA；导出为异步任务，产物短时效 URL |
| 验收 | ① 关键七类动作全留痕；② 直接改库被拒；③ 导出审计新增一条"导出审计"；④ 无 `audit:export` 看不到导出按钮；⑤ 运行日志与审计分开 |

### 7.6　任务管理（A6 / 架构 §6.4、M-05）

| 项 | 内容 |
| --- | --- |
| 页面 | `/tasks`（跨类型任务中心）、`/tasks/:id`（进度 / 逐项 / 失败明细 / 重试 / 取消） |
| 接口 | `POST /media-tasks`、`GET /media-tasks`、`/media-tasks/{id}`、`GET /media-tasks/{id}/events`（SSE）、`POST /media-tasks/{id}/cancel`、`POST /media-tasks/{id}/retry` |
| 关键规则 | 提交必带 `Idempotency-Key`；必须返回预估条数 / 成本 / 时长，缺一不可提交；状态机统一；进度落库、进程重启不丢；取消只影响未开始项；重试只重失败项；队列分组隔离，视频积压不拖垮脚本 |
| 交互要点 | 列表默认按创建时间倒序、支持类型 / 状态 / 客户筛选；详情展示逐项状态与失败行号；SSE 断线自动降级轮询并提示；完成 / 失败有全局通知 |
| 验收 | ① 重复提交返回同一任务；② 断网后轮询恢复；③ 取消 / 重试语义正确；④ 单队列积压不影响其他队列；⑤ 任务中心可查到所有类型任务 |

> 脚本任务复用同一套任务协议（`/script-tasks`，权限 `script:view` / `script:generate`，M1 生效），任务中心按 `type` 合并展示；权限点最终以 `packages/shared` 定稿为准（`DP-01`）。

### 7.7　AI 配置（A7 / P-08）

| 项 | 内容 |
| --- | --- |
| 页面 | `/ai/providers`（含供应商下的模型列表）、`/ai/routes`（任务映射）、`/ai/prompts`、`/ai/usage` |
| 接口 | `GET/POST/PATCH /ai/providers`、`/ai/routes`、`/ai/prompts`、`GET/PUT /ai/budgets`、`GET /ai/usage`（模型 CRUD 作为供应商下的嵌套资源，架构 §6.3.7 未单列端点，A7 前回写架构，见 `DP-15`） |
| 关键规则 | 四层配置（Provider → Model → TaskMapping → CallLog）；合并优先级：任务 > 模型 > 供应商；提示词保存即快照、可回滚、回滚产生新版本（`R-23`）；密钥 AES-256-GCM、主密钥来自环境变量、出参只给 `hasApiKey`；`platform.ai` 是唯一出网入口；内容违规不重试、失败降级到备用模型 |
| 交互要点 | 密钥输入后不可回读、只显示"已配置"；连通性测试有超时与错误分类；任务映射展示主 / 备模型与任务级覆盖；调用日志展示耗时 / 用量 / 估算金额 / 成败 |
| 验收 | ① 响应 / 日志 / bundle 无明文密钥；② 保存 → 快照 → 回滚 → 新版本；③ Mock 调用全链路；④ 无 `ai:configure` 不可改；⑤ 调用账本可按客户 / 模型 / 批次查询 |

> **共同约束**：七个模块的所有列表都使用游标分页与显式白名单筛选；所有写操作进审计；所有查询带 `ScopeContext` 与 `customer_id`（平台级配置除外）；所有错误返回统一结构 `{ code, message, details, trace_id }`。

---

## 8　前后端并行与联调机制

### 8.1　契约与 Mock

| 环节 | 约定 |
| --- | --- |
| 契约来源 | `packages/shared` 的 Zod schema（DTO / 枚举 / 错误码 / 权限点）为唯一真源 |
| 后端产出 | NestJS DTO → OpenAPI；每批 D1 产出 `openapi.v0.json` 快照 |
| 前端消费 | `openapi-typescript` 生成类型 + TanStack Query hooks；禁止手写接口类型 |
| Mock | 前端用 MSW（或 Prism）按 OpenAPI 生成 mock；覆盖成功 / 400 / 401 / 403 / 404 / 409 / 422 / 429 / 500 |
| 契约冻结 | 每批 D1 下午冻结 v0；冻结后如需改，必须同时更新 shared / OpenAPI / mock / 前端类型，并在批次记录中登记 |
| 契约校验 | CI 跑 `pnpm openapi:diff`；破坏性变更必须升版本并通知前端 |

### 8.2　联调检查单（每批 D3–D4 逐项打勾）

1. 登录态与 401 / 403 表现与契约一致；
2. 列表分页 / 筛选 / 排序与游标行为一致；
3. 错误码与前端提示文案映射完整（40001 / 40301 / 40302 / 40303 / 40902 / 42201 …）；
4. 权限点与页面按钮 / 路由一一对应；
5. 审计记录在操作后 1 秒内可查；
6. 空态 / 加载态 / 错误态三态齐全；
7. 关键写操作有二次确认与成功反馈；
8. 任务类操作有预估、进度、失败明细与重试入口。

### 8.3　前端工程约定

| 项 | 约定 |
| --- | --- |
| 目录 | `apps/web/src/{app,pages,features,components,hooks,lib,stores}`；页面按 `pages/<模块>/<功能>/` 与路由一一对应，详见 [11-前端路由与目录规范](../工程规范/11-前端路由与目录规范.md)；禁止在 `apps/web` 内自建"共享包" |
| 路由 | 统一 `/<模块>/<功能>`（见 [11](../工程规范/11-前端路由与目录规范.md)），路由表集中声明（路径、标题、权限点、菜单分组）；守卫读 `/me` 权限；无权限跳 403 |
| 权限渲染 | 统一 `usePermission` / `<Can permission="...">`；禁止 `removeChild` 式隐藏；无权限按钮不渲染但接口仍要校验 |
| 数据请求 | TanStack Query：queryKey 规范、失效策略、乐观更新仅用于勾选类；错误统一 toast + 页面级错误态 |
| 表单 | 优先 Semi Form；动态表单走 `form-engine`；字段校验前后端同源（Zod / schema） |
| 交互 | 危险操作二次确认；批量操作展示影响条数；长任务离开页面有提示 |
| 样式 | Semi token + 少量局部样式；禁止引入其他组件库 / 图标库；禁止内联 SVG（品牌 Logo 除外） |

### 8.4　后端工程约定

| 项 | 约定 |
| --- | --- |
| 模块骨架 | 每个模块 `controller / service / repository / dto / events`；模块间只走 Service 接口或领域事件，禁止跨模块 `prisma.*` |
| 鉴权链 | `JwtGuard → PermissionGuard → SpecialPermissionGuard → ScopeGuard → 业务校验`；路由默认拒绝，白名单显式放行 |
| 数据访问 | Repository 方法必须接收 `ScopeContext`；查询必须带 `customer_id`；禁止"先查全量再过滤" |
| 事务 | 业务写入 + outbox 同事务；外部调用不在事务内；幂等键表 24 小时 |
| 审计 | 变更类接口必须 `@Audit()`；审计字段含主体、对象、前后值、客户、trace_id |
| 错误 | 统一错误码；404 统一措辞避免探测；不把内部异常直接透出 |
| 配置 | 阈值 / 上限只读 `system_configs`；密钥只从环境变量读；日志脱敏 |

### 8.5　演示数据与种子

| 数据 | 内容 | 维护者 |
| --- | --- | --- |
| 超管 | 1 个，首次启动生成随机密码并强制修改 | Lead |
| 示例角色 | 运营 / 设计 / 文案 / 审核 / AI 工程 / 行业配置 / 客户负责人（5–7 个可改可删模板） | A2 |
| 行业与客户 | 电商 1 个行业、2 个客户、1 个客户组 | A3 |
| 字典 | 平台规格、时长档、钩子类型、景别、警示语类型、失败原因、淘汰理由、脚本方向、行业二级 | A4 |
| 行业包 | 电商 v1（草稿 → 发布） | B0 |
| 资产 | 1 个 PSD 模板 + 1 个 Logo + 1 组警示语 | B1 |
| AI | 1 个 Mock 供应商 + 2 个 Mock 模型 + 1 组任务映射 | A7 |

---

## 9　工程与环境准备

### 9.1　建仓清单（A0 必须完成）

```text
根目录：package.json / pnpm-workspace.yaml / turbo.json / tsconfig.base.json
        .nvmrc(24.15.0) / .npmrc / .editorconfig / .gitignore / .env.example
        eslint.config.mjs / prettier.config.mjs / commitlint.config.js / .lintstagedrc
        vitest.config.ts / playwright.config.ts / docker-compose.dev.yaml
        README.md / AGENTS.md / docs/
apps/api：NestJS + Fastify 入口、健康检查、OpenAPI、Pino、错误过滤器
apps/worker：QUEUE 环境变量启动、队列注册、优雅退出
apps/web：Vite + React 19、路由、布局、请求层、Semi 适配
packages/shared：错误码、权限点、Zod 通用 schema、ULID、分页
packages/ui：Semi 封装、icons.ts、locale
packages/form-engine：字段渲染器（B2 落地，先建包占位）
packages/render：PSD / 抠图 / 合成（M1 落地，先建包占位）
packages/ai-sdk：Provider 适配器（A7 落地，先建包占位）
prisma/：schema.prisma、migrations/、seed.ts
infra/：compose、Nginx、监控、备份脚本占位
```

### 9.2　CI 流水线

| 阶段 | 内容 | 失败处理 |
| --- | --- | --- |
| install | `pnpm install --frozen-lockfile` | 阻断（锁文件不一致） |
| static | `pnpm lint` · `pnpm typecheck` · `pnpm format:check` | 阻断 |
| unit | `pnpm test`（Vitest） | 阻断 |
| build | `pnpm build`（api / worker / web） | 阻断 |
| contract | `pnpm openapi:diff`（对上一版快照） | 破坏性变更不得合并 |
| integration | Testcontainers（PG / Redis / MinIO）主链路 | 阻断（M0 起逐步启用） |
| e2e | Playwright 冒烟（登录 / 用户 / 客户 / 字典 / 任务） | 阻断（M0 末起） |
| security | 依赖审计、密钥扫描、`any` / 跨模块 prisma 检查 | 阻断 |

### 9.3　环境矩阵

| 环境 | 用途 | 依赖 | 数据 |
| --- | --- | --- | --- |
| local | 开发 | Docker Compose（PG18 / Redis7.4 / MinIO） | 种子数据 |
| staging | 每批演示 / 联调 | 1 台云主机 + 同 compose | 演示数据，可重置 |
| production | M1 灰度后启用 | 架构 §4.2 拓扑 | 真实数据，迁移先行 |

### 9.4　观测与告警（M0 基线）

- Pino 结构化日志 + `trace_id` 全链路；
- OTel 指标：请求量 / 延迟 / 错误率、任务队列长度 / 等待时长 / 失败率、AI 调用耗时与成本；
- 告警：5xx 突增、队列积压、审计写入失败、AI 连续失败、对象存储不可用；
- 看板：任务中心健康、AI 调用账本（M2 完善成本看板）。

### 9.5　安全基线（M0 必须）

1. 密钥只在环境变量 / 密钥管理，不入库、不进日志、不进 bundle；
2. JWT 签名密钥支持轮换；refresh 旋转 + 吊销；
3. 密码 Argon2；登录失败限流；
4. 上传类型 / 大小校验；预签名 URL 短时效；
5. 依赖审计与许可证检查进 CI；
6. 权限三态用例覆盖每个受保护端点；
7. 审计 append-only 由数据库权限兜底，不能只靠代码。

---

## 10　质量门禁与测试策略

### 10.1　门禁总表

| 门禁 | 时点 | 通过条件 | 不通过处理 |
| --- | --- | --- | --- |
| **G0 批次准入** | 每批 D0 | 批次卡就绪；依赖批次验收通过；契约版本确认；环境可用；本批待确认项已清零或有明确默认 | 不启动，先补条件 |
| **G1 任务卡完成** | 每张卡 | `lint` / `typecheck` / 单测绿；无 `any` / `as` 逃逸；无跨模块 `prisma`；接口有 OpenAPI 描述；关键分支有测试；自查清单勾完 | 打回，不进入集成 |
| **G2 后端批次门** | 每批 D2 | 契约 v0 快照产出；权限三态用例通过；迁移可在空库重复执行；审计写入验证；错误码覆盖 | 本批不交付前端联调 |
| **G3 联调门** | 每批 D4 | 联调检查单 8 项全勾；页面三态齐全；错误提示映射完整；冒烟 E2E 通过 | 延期，不带病验收 |
| **G4 批次验收** | 每批 D5 | DoD 清单 + 演示脚本通过；`openapi:diff` 无未登记破坏性变更；批次记录与风险台账更新 | 不计入完成，顺延 |
| **G5 里程碑** | M0–M4 每个里程碑末 | 里程碑 DoD；AC 映射；性能预算；安全基线；文档同步；回滚演练（M1+） | 不进入下一里程碑 |

> **与人工决策门的关系**：§3.4 的 `H0`–`H5` 是**人的决策点**，不替代本节 `G0`–`G5` 的**质量门禁**。对应关系：`H0`↔`G0`（范围确认后开卡）、`H1`/`H2`/`H3` 为专题评审（分别在 A2 / A7 / 每批演示前）、`H4`↔`G4`（批次验收）、`H5`↔`G5`（里程碑发布）。

### 10.2　测试分层

| 层 | 范围 | 工具 | 何时强制 |
| --- | --- | --- | --- |
| 单元 | shared 工具与 schema、权限判定、状态机、命名生成、字典三层合并、AI 路由优先级 | Vitest | 每张任务卡 |
| 集成 | 登录链路、权限三态、客户隔离、任务幂等 / 重试、审计 append-only、密钥加密、文件预签名 | Vitest + Testcontainers（PG / Redis / MinIO） | 每批 G2 起 |
| 契约 | OpenAPI 快照 diff；前端 mock 与 schema 一致性 | `openapi:diff` + 契约测试 | 每批 |
| E2E | 登录、用户 / 角色、客户、字典、任务中心、AI 配置（Mock） | Playwright | M0 末起，每批冒烟 |
| 性能 | 任务提交 P95、列表 P95、SSE 连接数 | k6 | M1 起 |
| 安全 | 依赖审计、密钥扫描、越权用例、上传校验 | CI + 用例 | 每批 |

覆盖率只升不降；M0 起点行覆盖率 60%，`identity` / `platform` 关键模块 70%。

### 10.3　权限三态矩阵（每个受保护端点必填）

| 端点 | 有权限 | 功能权限缺失 | 特殊权限缺失 | 数据范围外 / 不可见 |
| --- | --- | --- | --- | --- |
| `GET /users` | 200 列表 | 403 `40301` | N/A | N/A |
| `GET /customers` | 200 范围内客户 | 403 `40301` | N/A | 空列表 / 详情 404 |
| `PATCH /customers/{id}` | 200 | 403 `40301` | N/A | 404（不泄露存在性） |
| `POST /media-tasks` | 202 任务 | 403 `40301` | N/A | `40302` / 404 |
| `GET /audit-logs` | 200 | 403 `40301` | 403 `40303` | 按审计范围裁剪 |
| `POST /audit-logs/export` | 202 | 403 `40301` | 403 `40303` | 同上 |
| `PATCH /ai/providers/{id}` | 200 | 403 `40301` | 403 `40303` | N/A |
| `POST /industry-packs/{id}/versions/{v}/publish` | 200 | 403 `40301` | 403 `40303` | N/A |

> 口径（对齐架构 §6.1 错误码表）：**功能权限缺失 → 403 `40301`；数据范围外 → 403 `40302`（写操作）/ 空列表（列表）/ 404（单条，不泄露存在性）；特殊权限缺失 → 403 `40303`；职责互斥 → 403 `40304`**。每个端点必须有对应三态用例，缺用例视为 G2 不通过。

### 10.4　契约与迁移门禁

| 检查 | 规则 |
| --- | --- |
| 破坏性变更 | 删字段 / 改类型 / 改必填 / 改枚举值 / 改错误码 → 必须升版本 + 前端同步 + `openapi:diff` 登记 |
| 迁移 | 一律 expand → migrate → contract；同一发布内禁止"删字段 + 改代码"；迁移必须可在空库与存量库各跑一次 |
| 回滚 | 每个迁移附回滚说明；不可逆操作（删列 / 改类型）必须双人 review + 备份确认 |
| 数据修复 | 禁止在迁移里做业务数据修复；修复走独立脚本并留审计 |

### 10.5　强制双人 Review 清单

权限 / 角色 / 数据范围 · 数据库迁移 · AI 供应商与密钥 · 导出与分享 · 审计与保留期 · 行业包发布 · 跨客户复用。

### 10.6　缺陷分级与阻断规则

| 级别 | 定义 | 处理 |
| --- | --- | --- |
| P0 | 数据泄露 / 越权 / 丢数据 / 密钥泄露 / 审计缺失 | 立即停批修复，修复后补回归用例 |
| P1 | 主流程不可用 / 契约破坏 / 权限判定错误 | 本批内必须清零 |
| P2 | 非主流程缺陷 / 体验问题 | 下一批处理，登记台账 |
| P3 | 建议 / 优化 | backlog |

**硬规则：任何 P0 / P1 未清零，不得进入下一批。**

---

## 11　风险与应对

### 11.1　项目风险

| 编号 | 风险 | 概率 | 影响 | 应对 | 触发信号 |
| --- | --- | --- | --- | --- | --- |
| PR-01 | M0 范围与架构 T0 口径不一致，评审时被压缩 | 高 | 高 | §2.5 显式说明差异与建议；DP-03 早确认；如压缩优先砍资产 / 导出，不砍权限与字典 | 评审会要求回到 25–30 EPD |
| PR-02 | 表单设计器复杂度超预期（R-T-04） | 中 | 高 | 14 类字段白名单 + 硬上限；先"JSON 编辑 + 渲染"降级路径；`form-engine` 独立包可单测 | B2 超期 3 天 |
| PR-03 | 行业包字段 / 合规规则未定（Q-15 / Q-16） | 高 | 中 | 电商包先行；字段清单 B0 开卡前书面确认；上限进配置 | B0 无法开卡 |
| PR-04 | 图片线渲染无先例（R-T-13） | 中 | 高 | M1 前 2 周 spike；单模板端到端优先；模板数量收敛 | PSD 解析失败率 > 10% |
| PR-05 | AI 供应商 / 预算未定（QT-05 / Q-09） | 高 | 中 | Mock 先行 + 适配器隔离；预算 P1 再做；切换供应商不改业务代码 | A7 无法联调真实模型 |
| PR-06 | 权限模型复杂，越权风险（R-16~R-18） | 中 | 高 | H1 权限门先落地；权限三态用例强制；数据范围统一走 ScopeGuard | 出现"先查全量再过滤" |
| PR-07 | 人工验收成为瓶颈 | 高 | 中 | 固定验收窗口；演示脚本预填；缺陷分级；验收人提前指定 | 验收演示连续两次改期 |
| PR-08 | 前后端契约漂移 | 中 | 中 | shared Zod 单一真源；契约冻结；`openapi:diff`；mock 契约测试 | 前端手写接口类型 |
| PR-09 | 迁移 / 种子冲突 | 中 | 中 | 迁移单写者；种子脚本幂等；每批预留迁移窗口 | 两人同改 `prisma/` |
| PR-10 | 中文字体 / 编码环境问题（R-T-18） | 中 | 中 | 镜像内置字体；启动自检；M1 前验证 | 渲染缺字 / 方框 |
| PR-11 | 一个人同时改多模块导致回归 | 中 | 中 | 写范围声明；模块 owner；CI 全量跑 | 同一 PR 跨 > 3 模块 |
| PR-12 | 需求在开发中变更 | 高 | 中 | 变更走批次记录 + 影响面评估；未确认项进 §13；不接"顺手加" | 口头新增需求 |

### 11.2　Harness 协作特有风险

| 编号 | 风险 | 应对 |
| --- | --- | --- |
| HR-01 | 模型幻觉 API / 字段 / 版本号 | 强制先读上游文档；以 `packages/shared` 与 OpenAPI 为准；typecheck + 契约测试兜底；Verifier 抽查 |
| HR-02 | 跨模块 `prisma` 或越权捷径 | ESLint 自定义规则 + 架构测试 + Review 清单 |
| HR-03 | `any` / `as` 逃逸类型 | `no-explicit-any` 与 `no-unnecessary-type-assertion` 阻断；Review 抽查 |
| HR-04 | 静默失败 / 假成功 | 失败必须显式上报；低质量产出打标（`R-30`）；E2E 断言真实结果 |
| HR-05 | 上下文漂移 / 遗忘约束 | 任务卡自包含；每批重读 AGENTS 与批次卡；关键决策落文档 |
| HR-06 | 过度设计 / 提前抽象 | 只做任务卡范围；YAGNI；抽象需两个以上真实用例 |
| HR-07 | 测试只写 happy path | 权限三态 / 负向 / 边界用例强制；覆盖率只升不降 |
| HR-08 | 并行写冲突 | 写范围声明 + 单写者；冲突走 rebase + 复核 |
| HR-09 | token / 成本失控 | 每批限定上下文；复用文档摘要；长任务拆卡；避免重复全量读库 |

### 11.3　风险回顾

每批 D5 更新风险台账（新增 / 关闭 / 概率变化）；每个里程碑做一次复盘，输出"下阶段 Top 3 风险"。

---

## 12　验收与交付

### 12.1　M0 完成定义（DoD）

- [ ] 新环境按 README 一条命令起依赖、一条命令起服务；
- [ ] 超管首登强制改密；用户 / 角色 / 部门可用；
- [ ] 自定义角色 + 权限点 + 六类数据范围 + 特殊权限可用；
- [ ] SoD 三对规则生效且有拒绝用例；
- [ ] 行业两级树（一级 → 二级，客户挂末级）、客户 / 客户组 / 客户端字段审批可用；
- [x] 通用字典三层合并、编码不可改、历史快照可用；
- [x] 系统配置单一来源、阈值 / 上限同源、配置版本与变更记录可用；
- [ ] 审计七类关键动作留痕、只读、导出留痕；
- [ ] AI 四层配置 + Mock 全链路 + 密钥不回显；
- [ ] 任务中心可查 / 可取消 / 可重试，幂等生效；
- [ ] 行业包 v1（电商）草稿 → 校验 → 审核 → 发布；
- [ ] 资产包上传 / 版本 / 停用 / 引用保护；
- [ ] 要素卡与脚本模板可用，表单设计器 14 类字段可用；
- [ ] 权限三态用例覆盖全部受保护端点；
- [ ] `pnpm lint && pnpm typecheck && pnpm test` 全绿；E2E 冒烟通过；
- [ ] 文档与索引同步（README / AGENTS / 本计划）。

### 12.2　每批演示脚本模板

| 步骤 | 操作 | 期望 | 证据 |
| --- | --- | --- | --- |
| 1 | 以不同角色登录 | 菜单 / 按钮按权限差异显示 | 截图 × 2 |
| 2 | 执行本批核心写操作 | 成功反馈 + 审计 1s 内可查 | 截图 + 审计记录 |
| 3 | 越权 / 范围外访问 | 403 / 404 / 空列表符合口径 | 截图 |
| 4 | 触发错误分支 | 错误码与提示文案正确 | 截图 |
| 5 | 刷新 / 重进页面 | 状态持久、无脏数据 | 录屏或截图 |

### 12.3　里程碑退出标准

| 里程碑 | 退出标准 | 对应 AC |
| --- | --- | --- |
| M0 | §12.1 全勾 + 演示通过 + 无 P0/P1 | 支撑 AC-04 |
| M1 | 单客户"要素卡 → 脚本 → 图片素材 → 快筛 → 导出归档"闭环；3 个模板可用；导出留痕 | AC-01、AC-04 |
| M2 | 提效能力上线；至少 3 项指标可量化；成本看板可用 | AC-02 |
| M3 | 复用、成片入库、送审与回流、SSO / 系统配置上线；复用率 ≥ 60%；关联率与日指标可测 | AC-03 |
| M4 | 爆量判定与阈值可配置；脚本反哺生效；四类看板可用；M0–M4 全量回归通过 | AC-02、AC-04 |

### 12.4　交付物清单

| 类别 | 内容 |
| --- | --- |
| 代码 | `apps/api`、`apps/worker`、`apps/web`、`packages/*`、`prisma/`、`infra/` |
| 文档 | 本计划、批次记录、接口快照、迁移说明、Runbook（T1 前） |
| 演示 | 每批演示脚本与截图、M0–M4 验收记录 |
| 台账 | 风险台账、待确认清单、缺陷台账、AI 调用账本（M2） |

### 12.5　发布与灰度

| 阶段 | 策略 |
| --- | --- |
| M0 | 内测环境部署，仅项目组 + 种子客户使用；每日构建 |
| M1 | staging 验证 → 生产灰度（1–2 个客户）；功能开关控制新能力 |
| M2+ | 按客户 / 行业分批放量；迁移先行、代码后行；保留上一版本镜像 |

回滚：镜像回滚 + 迁移回滚说明 + 功能开关关闭；每次发布前演练一次。

### 12.6　验收记录

每批 D5 记录：批次号、日期、参与人、演示项、通过 / 不通过项、遗留缺陷、风险变化、下一批准入结论。

---

### 12.7　全项目完工定义（M0–M4）

- [ ] M0–M4 各里程碑退出标准全部满足（§12.1、§12.3）；
- [ ] AC-01：至少 3 个不同行业包客户可重复走通「要素卡 → 脚本 → 图片 / 视频 → 快筛 → 导出归档」；
- [ ] AC-02：至少 3 项提效指标较基线改善 ≥ 30%，口径与看板一致；
- [ ] AC-03：周活 ≥ 50%，覆盖策划 / 设计 / 投手 3 类岗位；
- [ ] AC-04：权限隔离用例全绿；导出、权限变更、分享访问、AI 调用均可审计；
- [ ] 数据保留期、审计导出、备份恢复演练通过；
- [ ] 代码仓库打 tag `v1.0.0`，交付文档包（计划 / 接口 / 迁移 / Runbook / 验收记录）归档。

---

## 13　待确认清单（需产品 / 技术负责人确认）

| 编号 | 待确认项 | 影响 | 建议默认 | 阻塞批次 |
| --- | --- | --- | --- | --- |
| DP-01 | 「任务管理」是否即跨模块异步任务中心；是否新增 `task:*` 权限点 | 权限模型与页面范围 | 按 AS-06 做任务中心，复用 `media:view` / `media:generate`，暂不新增权限点 | A6 / H1 |
| DP-02 | 「日志管理」是否含运行日志查询入口 | 页面与权限 | 审计中心为主，运行日志跳转 Grafana / Loki，不自研 | A5 |
| DP-03 | M0 范围与排期是否对外承诺；是否接受 6–7 周 | 项目计划与预期 | 维持完整 M0，按 6–7 周排；对外只承诺里程碑不承诺日期 | 立项 |
| DP-04 | 登录方式与 SSO 时点（Q-10） | A1 设计与后续改造 | M0 账号密码 + 刷新令牌；SSO 预留接口 | A1 |
| DP-05 | AI 供应商、密钥保管方式、预算阈值（QT-05 / Q-09） | A7 与 M1 真实调用 | 先 Mock；生产密钥走环境变量 / 密钥管理；预算 P1 | A7 / M2 |
| DP-06 | 云厂商、域名、备案、对象存储（QT-01 / QT-03） | 部署与环境 | 单云 + 托管 PG / Redis / S3 兼容存储 | A0 / M1 |
| DP-07 | 行业包首批字段与审批人（Q-14 / Q-15 / Q-16） | B0 / B2 | 电商包按 PRD 示例字段；审批人=产品负责人 | B0 / B2 |
| DP-08 | UI 视觉稿与走查机制 | 前端效率与返工 | 以 Semi 默认为基线，M0 中补关键页视觉稿 | A0 / M1 |
| DP-09 | Harness 团队规模与并发 Worker 数 | 排期与冲突 | 1 Lead + 3 Worker；写范围隔离 | 全程 |
| DP-10 | 生产运维责任、值班与告警接收人 | 上线 | 开发兼任，M1 前补 Runbook | M1 |
| DP-11 | 数据保留期（Q-08） | 审计 / 日志 / 产物 | 审计 ≥ 12 个月，运行日志 30 天，产物按客户配置 | A5 / M1 |
| DP-12 | 平台清单与尺寸矩阵（Q-03） | 字典与渲染 | 先按 PRD 附录清单，进字典可配 | B0 / M1 |
| DP-13 | 行业包七项校验中哪些阻断、哪些仅警告（PRD §5.4.8 未区分） | B0 / B2 | 结构性问题阻断，内容类问题警告 | B0 / B2 |
| DP-14 | 跨客户复用授权、批量删除两项特殊权限的权限点编码（PRD §5.4.3 要求，架构 §6.3 未给） | 角色编辑器特殊权限区完整性 | M0 先实现五项；两项在 M2/M3 启用前回写架构并补入 `packages/shared` | A2 / M2 |
| DP-15 | AI 模型管理的端点形态（架构 §6.3.7 只有 providers / routes / prompts，未单列 models） | A7 接口契约与前端页面 | 模型作为 `/ai/providers/{id}` 嵌套资源，A7 前回写架构 §6.3.7 | A7 |
| DP-16 | M4 爆量判定阈值与 ROI 口径（PRD 未给数值，`R-26` 要求只存配置） | M4 判定逻辑、榜单与反哺 | 默认「消耗 ≥ 客户日均消耗 3 倍且 ROI ≥ 1.2」，进 `system_configs` 可改 | M4-1 |
| DP-17 | M5 预研（M-27 / AI 素材生产）是否立项、预算与版权方案（Q-32） | 后续路线与资源 | M4 验收后单独立项评估，不在本期承诺 | M5 |
| DP-18 | 公开分享 / 免登录审核链接开关（`R-28`） | M2-4 审核链接、M3-2 素材分享 | 默认关闭，按客户白名单开启；链接短时效、可作废、访问留痕 | M2-4 / M3-2 |

> 处理规则：任一 DP 在阻塞批次开卡前未确认，按"建议默认"执行并登记；若影响面跨模块，升级为 ADR。

---

## 14　附录

### A　任务卡模板

```markdown
### T-<批次>-<序号> <任务名>
- 端：BE / FE / BOTH / INFRA
- 模块：identity / client / catalog / industry / script / media / delivery / platform
- 依赖：<任务号或"无">
- 写范围：<文件 / 目录前缀>
- 目标：<一句话>
- 输入：<上游文档章节 / 契约 / 设计稿>
- 实现要点：<3–6 条>
- 验收标准：<可执行、可断言，3–5 条>
- 测试要求：<单测 / 集成 / 三态用例>
- 工量：<EPD>
- 风险 / 待确认：<DP-xx 或"无">
```

### B　M0 权限点清单（规划，最终以 `packages/shared` 为准）

| 模块 | 权限点 | 说明 |
| --- | --- | --- |
| identity | `user:view` / `user:manage` | 用户查看 / 增改停用转交 |
| identity | `role:view` / `role:manage` | 角色查看 / 增改与授权 |
| client | `customer:view` / `customer:manage` | 客户查看 / 增改 |
| client | `customer:transfer` | 客户转交 |
| client | `customer_group:manage` | 客户组管理 |
| client | `customer_field:apply` / `customer_field:approve`★ | 字段申请 / 审批 |
| industry | `industry_pack:view` / `industry_pack:edit` | 行业包查看 / 编辑 |
| industry | `industry_pack:review` / `industry_pack:publish`★ | 审核 / 发布 |
| catalog | `brief_card:view` / `brief_card:edit` | 要素卡 |
| catalog | `script_template:view` / `script_template:edit` | 脚本模板 |
| catalog | `asset:view` / `asset:edit` / `asset:delete` | 资产（被引用仅停用） |
| media | `media:view` / `media:generate` | 任务查看 / 提交（任务中心复用） |
| delivery | `export:create`★ | 导出 |
| platform | `dict:manage` | 字典（A2 定稿目录，单权限点覆盖查看 / 编辑） |
| platform | `ai:view` / `ai:configure`★ | AI 配置 |
| platform | `audit:view`★ / `audit:export`★ | 审计查看 / 导出（均为特殊权限） |
| platform | `system:configure` | 系统配置 |

★ = 特殊权限，默认关闭，不随角色复制带入。PRD §5.4.3 另有「跨客户复用授权」「批量删除」两项特殊权限；架构 §6.3 尚未给出权限点编码，计划在 M2/M3 启用前回写架构并补入（`DP-14`）。

### C　M0 页面清单

| 路由 | 页面 | 权限点 | 批次 |
| --- | --- | --- | --- |
| `/login` | 登录 | 公开 | A1 |
| `/system/users`、`/system/users/new`、`/system/users/:id` | 用户与部门 | `user:view` / `user:manage` | A1 |
| `/system/departments` | 部门管理（两级组织树、停用/启用） | `user:view` / `user:manage` | A1 |
| `/system/roles`、`/system/roles/:id` | 角色管理 | `role:view` / `role:manage` | A2 |
| `/system/industries` | 行业管理 | `customer:read` / `customer:manage` | A3 |
| `/system/customers`、`/system/customers/new`、`/system/customers/:id` | 客户管理 | `customer:view` / `customer:manage` | A3 |
| `/system/customer-groups` | 客户组 | `customer_group:manage` | A3 |
| `/system/customer-fields/approvals` | 字段审批 | `customer_field:approve` | A3 |
| `/system/dicts`、`/system/dicts/:type` | 字典 | `dict:manage` | A4 |
| `/system/settings` | 系统配置 | `system:configure` | A4 |
| `/system/audit-logs`、`/system/audit-logs/:id` | 审计 | `audit:view` | A5 |
| `/material/tasks`、`/material/tasks/:id` | 任务中心 | `media:view` / `media:generate` | A6 |
| `/system/ai`（后续 `/system/ai/providers` 等） | AI 配置 | `ai:view` / `ai:configure` | A7 |
| `/system/industry-packs`、`/system/industry-packs/:id/versions/:ver` | 行业包与设计器 | `industry_pack:*` | B0–B2 |
| `/assets/library`、`/assets/library/:id` | 资产包 | `asset:*` | B1 |
| `/scripts/framework-cards`、`/scripts/framework-cards/new`、`/scripts/framework-cards/:id` | 要素卡 | `brief_card:*` | B2 |
| `/scripts/templates` | 脚本模板 | `script_template:*` | B2 |
| `/delivery/export`、`/delivery/records`、`/delivery/records/:id` | 导出与归档 | `export:create` | B3 |
| `/403`、`/404` | 异常页 | 公开 | A0 |

### D　接口清单

以技术架构 §6.3 为准；M0 需要实现：`GET /health`（运维探针，架构未列）、`GET /me`、`POST /auth/refresh`、`POST /auth/logout`、`GET /permissions`、`POST /users/{id}/transfer-customers`、`POST /customers/{id}/apply-industry-pack`、`GET /dicts/{type}/items`（除 `/health` 外均见架构 §6.3）。模型管理随 `/ai/providers` 嵌套实现，见 §7.7 注。

### E　术语

| 术语 | 含义 |
| --- | --- |
| 行业包 | 一个行业的内容知识资产（字段 / 术语 / 模板 / 规则），可版本化发布 |
| 要素卡 | 单条素材的输入卡（核心信息 / 卖点 / 必含项 / 禁忌项），脚本生成上游 |
| 快筛 | 人工对素材逐条打标（合格 / 待修 / 淘汰 + 理由） |
| 低质量产出 | 标注 `low_quality` + 原因码的产出，不按成功静默交付 |
| ScopeContext | 请求作用域上下文（用户 / 角色 / 数据范围 / 客户），所有数据访问必带 |
| 特殊权限 | 默认关闭、需单独授予的高危权限（导出 / AI 配置 / 审计 / 发布等） |
| EPD | 人日（Effort Person-Day） |
| Lead / Worker | Harness 编队中的协调者与执行者 |

### F　修订记录

| 版本 | 日期 | 变更 |
| --- | --- | --- |
| V0.1 | 2026-11-02 | 初稿：范围、编队、批次、WBS、七个管理模块专项、联调、门禁、风险、验收、待确认 |
| V0.1（补全） | 2026-11-02 | 按用户确认补全为**全项目 M0–M4**：M1–M4 增加迭代级 + 任务组级 WBS；补 M4 交付闭环、M5 预研边界、全项目完工定义；待确认增至 DP-18 |

---

> 本计划与 PRD `V1.6`、技术架构 `V0.4` 配套使用；冲突时以 PRD → 技术架构 → 工程规范 → 本计划为序。