1173 lines
100 KiB
Markdown
1173 lines
100 KiB
Markdown
# 灵犀 · 信息流素材生产平台 项目开发计划
|
||
|
||
> **文档定位**：把 PRD V1.6 与《技术架构》V0.4 翻译成**可执行、可并行、可验收**的开发计划。
|
||
> **不替代上游**：需求口径以 PRD 为准，技术选型与硬约束以技术架构和 [`AGENTS.md`](../../AGENTS.md) 为准；本文件只回答"先做什么、做到什么程度、前后端怎么并行、怎么验收"。
|
||
|
||
## 0 文档信息与使用说明
|
||
|
||
| 项 | 内容 |
|
||
| --- | --- |
|
||
| 文档名称 | 灵犀 · 信息流素材生产平台 项目开发计划 |
|
||
| 版本 | V0.1（初稿，待评审） |
|
||
| 日期 | 2026-11-02 |
|
||
| 状态 | 待产品 / 技术负责人评审；评审通过后作为建仓与批次执行的依据 |
|
||
| 需求基线 | 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 / M2 迭代级；M3 仅路线概要 |
|
||
| 读者 | 产品 / 技术负责人、Harness 编队、测试、运维 |
|
||
| 维护 | 每批结束回写实际工期与偏差；范围变更同步 §5 与 §13 |
|
||
|
||
### 0.1 版本记录
|
||
|
||
| 版本 | 日期 | 修订内容 |
|
||
| --- | --- | --- |
|
||
| V0.1 | 2026-11-02 | 初稿：开发模式（Harness 全程驱动）、M0 十二批次任务级 WBS、七个管理模块专项、前后端并行与联调机制、质量门禁、风险与验收、待确认事项 |
|
||
|
||
### 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–M3 表述，括号标注对应 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-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）；全程前后端同批并行、契约先行、每批可演示。**
|
||
|
||
### 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 / 系统配置完善 | 40–50 | 4–5 周 | 资产复用率 ≥ 60%；新客户冷启动 ≤ 1 个工作日 |
|
||
|
||
- **关键路径**：`A0 → A1 → A3 → B0 → B2 → B3 → M1-3（图片线）→ M2-1（视频线）`。占用关键路径的批次不得并行插入范围。
|
||
- **最大风险**：表单设计器复杂度（`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["M3 复用<br/>（概要，不排细期）"]
|
||
W0 -. 每批可演示 .-> H4["人类验收门 H4"]
|
||
W1 -. AC-01 .-> D1["业务方现场验收"]
|
||
W2 -. 指标 .-> D2["任务成功率 / 成本曲线"]
|
||
```
|
||
|
||
> 周次为相对周（W1 = A0 启动周），不是日历承诺；换算方式见 §4.5。
|
||
|
||
---
|
||
|
||
## 2 目标、范围与优先级
|
||
|
||
### 2.1 分阶段目标与退出标准
|
||
|
||
| 阶段 | 目标（一句话） | 退出标准 | 判定方式 |
|
||
| --- | --- | --- | --- |
|
||
| M0 地基 | 能装人、能装客户、能装资产、能装行业 | ① 能登录；② 超管可创建角色并分配数据范围；③ 可建行业 / 客户 / 客户组；④ 可配置并发布电商行业包 v1；⑤ 可配 AI 供应商（Mock 连通）；⑥ 可提交空任务并看到进度；⑦ 关键操作审计可查 | 演示脚本（§12.1）+ 权限三态用例 + 审计抽样 |
|
||
| M1 主链路 | 一个真实客户完整走通"要素卡 → 脚本 → 图片 → 导出" | AC-01 达成；交付周期、一次过审率、单条成本可测 | 业务方现场验收 + 埋点 |
|
||
| M2 提效 | 视频线可用、配置可运营、成本可治理 | 单条视频从脚本到成片跑通；成本可查；任务成功率 ≥ 98%；峰值 500 条/日无积压（T3 口径） | 压测 + 成本看板 + 灰度观察 |
|
||
| M3 复用 | 资产复用与经验沉淀 | 资产复用率 ≥ 60%；新客户冷启动 ≤ 1 个工作日；效果回流可用 | 看板 + 抽样 |
|
||
|
||
### 2.2 本计划范围
|
||
|
||
**M0 任务级拆解（§6）**：A0 工程骨架、A1 身份与用户、A2 角色权限、A3 客户行业、A4 字典与配置、A5 审计日志、A6 任务中心、A7 AI 配置、B0 行业包与表单、B1 资产最小集、B2 要素卡与脚本模板、B3 导出骨架。
|
||
|
||
**M1 / M2 迭代级（§5.5 / §5.6）**：以 PRD §7 的 M1、M2 清单为基线；提前 / 后移项见 §2.5。
|
||
|
||
**M3 概要（§5.7）**：PRD §7 的 M3 清单，只给路线、依赖与退出标准，不拆任务卡。
|
||
|
||
### 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 | M3 全部 | 不影响 M0–M2 验收 |
|
||
| 2 | M2 的 M-02 规格矩阵、M-11 自动校验、M-18~M-20 成片入库 | 视频线仍可跑通，效率类指标下降 |
|
||
| 3 | M1 的 S-03 卖点库；M2 的 S-10 版本、S-11 引用、S-15 模板库、S-16 审核链接、S-17 Word 交付包 | 主链路仍闭环 |
|
||
| 4 | B0 设计器降级为 **JSON 编辑 + 试填预览**（不做拖拽与联动 UI） | 行业配置效率下降，第二行业上线变慢 |
|
||
| 5 | B1 资产预览降级为**缩略图 + 元数据**（不做真实合成预览） | 模板准入质量下降，M1 图片线需补 |
|
||
| ✗ 不砍 | 权限、客户隔离、审计、导出留痕、任务幂等、AI 密钥安全 | 触碰 AGENTS §3 红线 |
|
||
|
||
### 2.5 与架构 `T0` 口径的差异说明（必须接受）
|
||
|
||
技术架构 §10.2 的 `T0` 估算为 **25–30 EPD**，只覆盖骨架 + 管理底座 + 行业包 v1；本计划 M0 为 **65–70 EPD**，因为按 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 | 4–5 周 | 复用率 ≥ 60%；冷启动 ≤ 1 工作日 |
|
||
|
||
> 交叉校验：技术架构 T0–T2 净开发 120–145 EPD；本计划 M0–M2 为 175–196 EPD（按各里程碑区间相加；按当前 WBS 实际合计约 190.5），差额来自 M0 增量（设计器 / 资产 / 要素卡 / 导出）与更细的验收口径。若采用架构原口径，可把 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 末集成缓冲）。
|
||
|
||
### 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；关键路径为 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；视频质量不确定性最高（`R-T-02`），必须先做"单镜质量基线"再上批量。注：`M-18~M-20` 在 PRD 功能表标注 P1（M2）、在 §7 归入 M3，本计划按功能表放在 M2，M3 只做完善；其余提前项见 §2.5。
|
||
|
||
### 5.7 M3 概要（不拆任务卡）
|
||
|
||
| 主题 | 范围（PRD 编号） | 依赖 | 退出标准 |
|
||
| --- | --- | --- | --- |
|
||
| 资产复用与度量 | A-10、A-11、S-12、S-18 | M2 资产版本与效果数据 | 复用率 ≥ 60%；复审与降权可用 |
|
||
| 送审与效果回流 | M-21、M-23、M-24（含 M-18~M-20 完善） | 素材库、投放登记 | 素材关联率可测；日指标可导入；爆量判定阈值配置化 |
|
||
| 交付与归档、外部访问 | E-05（完善）、E-06、P-12、P-13、M-22 | 导出、审计、SSO 决策 | 批量重导、SSO、分享链接可用且留痕 |
|
||
| 混合实拍与口播 | M-10、M-13 | 视频线稳定 | 金融口播可用（按 `Q-04` 决策） |
|
||
|
||
### 5.8 关键路径与缓冲
|
||
|
||
- **关键路径**：`A0 → A1 → A3 → B0 → B2 → B3 → M1-3 → M2-1`；
|
||
- **有浮动的批次**：A2（可后 1 日）、A5（可拆两段）、A6 / A7（W2–W3 内可调）、B1（与 B0 并行）；
|
||
- **缓冲安排**：每波次末留 1 日技术债 / 联调缓冲；M0 末额外 3 日集成缓冲（全链路演示 + 审计抽样 + 性能冒烟）；M1/M2 各留 2 日。
|
||
- **关键路径纪律**：关键路径上的批次**不接受插入新范围**；如必须插入，先砍等量范围或顺延里程碑。
|
||
|
||
---
|
||
|
||
## 6 M0 任务级工作分解（WBS）
|
||
|
||
> **编号规则**：`A1-BE-02` = 批次 A1 / 端别 / 序号。端别：`INF` 基础设施、`SH` 共享包、`BE` 后端、`FE` 前端、`QA` 测试。
|
||
> **工量**：EPD（等效人日），已含自检与单测，不含人类评审与联调等待。
|
||
> **门禁**：每批末尾的门禁是进入下一批的必要条件；验收要点写可执行断言，不写主观描述。
|
||
> **开卡时展开**：本表是计划级摘要；批次开卡按 §3.3 补齐接口、鉴权、写范围、风险后执行。
|
||
|
||
### 6.1 A0 工程骨架与契约基线
|
||
|
||
**目标**：一次建对仓库、工具链、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 lint && pnpm typecheck && pnpm test` 全绿；`pnpm compose:up` 三依赖健康；api / web / worker 可启动；OpenAPI 快照入库；CI 在 PR 上可阻断。
|
||
|
||
### 6.2 A1 身份认证与用户管理
|
||
|
||
**目标**：能登录、能装人、能按权限渲染页面。**对应**：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-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-QA-01 | 账号生命周期用例 | QA | 登录 / 刷新 / 登出 / 停用 / 角色变更 / 越权 6 类用例 | A1-BE-04 | 用例全部通过并进 CI | 0.5 |
|
||
|
||
**本批门禁**：登录闭环；用户生命周期可演示；权限三态（有 / 无 / 范围外）用例通过；审计已记录登录与用户变更。
|
||
|
||
### 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 |
|
||
|
||
**本批门禁**：角色可配、范围可解析、SoD 可拦截；权限三态用例全绿；特殊权限默认关闭；人类完成 **H1 权限门**（§3.4）。
|
||
|
||
### 6.4 A3 客户与行业目录
|
||
|
||
**目标**：行业 / 客户 / 客户组 / 客户字段四件事立住，作为全部资产的根节点。**对应**：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 |
|
||
|
||
**本批门禁**：可建行业 → 客户 → 客户组；唯一性与状态机生效；客户字段审批可用；所有查询带客户维度。
|
||
|
||
### 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 |
|
||
|
||
**本批门禁**：字典三层合并可用；编码不可改；阈值只存一处且前后端一致；配置变更可审计。
|
||
|
||
### 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 一致。
|
||
|
||
---
|
||
|
||
## 7 七个管理模块专项（产品与交互口径）
|
||
|
||
> 本章是 A1–A7 的"做什么、页面长什么样、规则是什么"的补充，**不重复** WBS 的实现细节。页面路由与权限点见附录 B / C。
|
||
|
||
### 7.1 用户管理（A1 / P-01）
|
||
|
||
| 项 | 内容 |
|
||
| --- | --- |
|
||
| 页面 | `/login`、`/users`、`/users/new`、`/users/:id`、部门树（内嵌用户页） |
|
||
| 接口 | `POST /auth/login`、`/auth/refresh`、`/auth/logout`、`GET /me`、`GET /users`、`POST /users`、`PATCH /users/{id}`（含角色分配）、`POST /users/{id}/transfer-customers` |
|
||
| 关键规则 | 部门最多两级；手机号唯一；一人可多角色；离职**停用不删**，名下客户必须转交；超管建议 ≤ 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}`；按业务域分 `features/<domain>`，禁止在 `apps/web` 内自建"共享包" |
|
||
| 路由 | 路由表集中声明（路径、标题、权限点、菜单分组）；路由守卫读 `/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 / M1 / M2 末 | 里程碑 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 三对规则生效且有拒绝用例；
|
||
- [ ] 行业两级、客户 / 客户组 / 客户端字段审批可用；
|
||
- [ ] 通用字典三层合并、编码不可改、历史快照可用；
|
||
- [ ] 审计七类关键动作留痕、只读、导出留痕；
|
||
- [ ] 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 | 复用与批量能力上线；周活与岗位覆盖达标 | AC-03 |
|
||
|
||
### 12.4 交付物清单
|
||
|
||
| 类别 | 内容 |
|
||
| --- | --- |
|
||
| 代码 | `apps/api`、`apps/worker`、`apps/web`、`packages/*`、`prisma/`、`infra/` |
|
||
| 文档 | 本计划、批次记录、接口快照、迁移说明、Runbook（T1 前） |
|
||
| 演示 | 每批演示脚本与截图、M0 / M1 验收记录 |
|
||
| 台账 | 风险台账、待确认清单、缺陷台账、AI 调用账本（M2） |
|
||
|
||
### 12.5 发布与灰度
|
||
|
||
| 阶段 | 策略 |
|
||
| --- | --- |
|
||
| M0 | 内测环境部署，仅项目组 + 种子客户使用；每日构建 |
|
||
| M1 | staging 验证 → 生产灰度（1–2 个客户）；功能开关控制新能力 |
|
||
| M2+ | 按客户 / 行业分批放量；迁移先行、代码后行；保留上一版本镜像 |
|
||
|
||
回滚：镜像回滚 + 迁移回滚说明 + 功能开关关闭；每次发布前演练一次。
|
||
|
||
### 12.6 验收记录
|
||
|
||
每批 D5 记录：批次号、日期、参与人、演示项、通过 / 不通过项、遗留缺陷、风险变化、下一批准入结论。
|
||
|
||
---
|
||
|
||
## 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 在阻塞批次开卡前未确认，按"建议默认"执行并登记；若影响面跨模块，升级为 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:view` / `dict:edit` | 字典 |
|
||
| 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 |
|
||
| `/users`、`/users/new`、`/users/:id` | 用户与部门 | `user:view` / `user:manage` | A1 |
|
||
| `/roles`、`/roles/:id` | 角色与权限 | `role:view` / `role:manage` | A2 |
|
||
| `/industries` | 行业管理 | `industry_pack:view` / `customer:manage` | A3 |
|
||
| `/customers`、`/customers/new`、`/customers/:id` | 客户管理 | `customer:view` / `customer:manage` | A3 |
|
||
| `/customer-groups` | 客户组 | `customer_group:manage` | A3 |
|
||
| `/customer-fields/approvals` | 字段审批 | `customer_field:approve` | A3 |
|
||
| `/dicts`、`/dicts/:type` | 字典 | `dict:view` / `dict:edit` | A4 |
|
||
| `/system/configs` | 系统配置 | `system:configure` | A4 |
|
||
| `/audit-logs`、`/audit-logs/:id` | 审计 | `audit:view` | A5 |
|
||
| `/tasks`、`/tasks/:id` | 任务中心 | `media:view` / `media:generate` | A6 |
|
||
| `/ai/providers`、`/ai/routes`、`/ai/prompts`、`/ai/usage` | AI 配置 | `ai:view` / `ai:configure` | A7 |
|
||
| `/industry-packs`、`/industry-packs/:id/versions/:ver` | 行业包与设计器 | `industry_pack:*` | B0–B2 |
|
||
| `/assets`、`/assets/:id` | 资产包 | `asset:*` | B1 |
|
||
| `/brief-cards`、`/brief-cards/new`、`/brief-cards/:id` | 要素卡 | `brief_card:*` | B2 |
|
||
| `/script-templates` | 脚本模板 | `script_template:*` | B2 |
|
||
| `/exports`、`/exports/: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、七个管理模块专项、联调、门禁、风险、验收、待确认 |
|
||
|
||
---
|
||
|
||
> 本计划与 PRD `V1.6`、技术架构 `V0.4` 配套使用；冲突时以 PRD → 技术架构 → 工程规范 → 本计划为序。
|