oh-my-muse/design-docs/内容映射表.md
zizi 81a8d1377f docs(设计): 新增专题-08自动化测试方案SoT,蒸馏G1/G4需求缺口
- 新增 专题-08-自动化测试方案:四层测试金字塔、确定性/语义分界判据、语义评测方法论(双盲评委/对照实验Gate B/回放)、测试可判定性合同
- 登记归属:00-文档大纲 + 内容映射表
- 蒸馏G1(收紧自动确认):产品-02 §6.4/§9.1 纳入达标自动确认四条件,消除唯一入口矛盾
- 蒸馏G4(运行时叙事门):专题-04 §4.2.1 补三维量表与通过线(设定≥7.0/角色·场景≥6.0)及四步裁决
- 新增 docs/plans 缺口跟踪:登记10项需求缺口与蒸馏状态
2026-07-30 23:25:15 +08:00

216 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 内容映射表New-Design(新设计) V2
- 版本v8
- 更新日期2026-07-17
- 目标读者:文档维护者/架构/前端/后端/产品
- 阅读时间1015 分钟
- 边界说明:本文件只做“内容归属与迁移策略”定义,不承载业务/架构细节;细节必须落到对应 V2 文档里,避免重复。
## 核心原则(别把简单事做复杂)
- 单一归属:一个概念只能有一个“主文档”,其他地方只能引用。
- 消灭特殊情况:重复解释=坏味道;用引用替代复制。
- 角色分离:产品/架构/后端/前端/流程各写各的,越界内容一律改为引用。
## V2 目标文件清单(角色前缀 + 扁平结构)
- 入口:`00-文档大纲.md`
- 产品:
- `产品-01-产品定位与核心价值.md`
- `产品-02-核心功能与交互边界.md`
- `产品-03-用户旅程与操作流程.md`
- 架构:
- `架构-01-系统全貌与边界上下文.md`
- `架构-02-核心数据结构与双轨模型.md`
- `架构-03-关键决策与原则(ADR).md`
- `架构-04-状态机与约束清单.md`
- 后端:
- `后端-01-领域模型与聚合设计.md`
- `后端-02-工程结构与模块职责.md`
- `后端-03-关键流程实现与接口契约.md`
- `后端-04-统一数据库Schema-v1.md`
- `后端-05-统一API契约-v1.md`
- 前端:
- `前端-01-工程结构与核心依赖.md`
- `前端-02-编辑器与影子层交互.md`
- `前端-03-元引擎与动态表单.md`
- 流程:
- `流程-01A-管理员操作流程(操作视角).md`
- `流程-01B-普通用户操作流程(操作视角).md`
- `流程-02A-管理员系统处理流程(系统视角).md`
- `流程-02B-普通用户系统处理流程(系统视角).md`
- 专题:
- `专题-01-正文建议接受(Accept Suggestion)实现规范.md`
- `专题-02-Sudowrite对标与Muse产品取舍.md`
- `专题-03-AI编排上下文与质量评测实现规范.md`
- `专题-04-生成质量门控与创作健康度设计方案.md`
- `专题-05-AI统一交互协议与外部AgentAdapter设计.md`
- `专题-06-元数据驱动的智能体架构.md`
- `专题-07-知识消费契约与质量闭环.md`
- `专题-08-自动化测试方案.md`
- dev 路线图(⚠️ `doc/dev/*` 规划未落地、从未创建;职责已由实际文档承担):
- 真实现状与目标差距 → [`docs/项目功能与进度总览.md`](../docs/项目功能与进度总览.md)
- 总体路线图 / 阶段 → [`docs/mvp/进度总账.md`](../docs/mvp/进度总账.md)
- 验收口径与退出条件 → 覆盖 JSON `p1r-api-coverage.json` + [`.agents/rules/verification-and-anti-false-green.md`](../.agents/rules/verification-and-anti-false-green.md)
## 工程仓库归属
本节只定义仓库级归属不替代各分册的产品、架构、Schema、API 或状态机定义。
| 仓库 | 内容归属 | 对应主文档 | 迁移 / 落地策略 |
|---|---|---|---|
| `muse-cloud/` | 后端主仓fork `YunaiV/yudao-cloud`,承接 Yudao 平台能力和 Muse 业务模块 | `后端-01` / `后端-02` / `后端-03` / `后端-04` / `后端-05` | 以 `后端-02` 的模块 owner 和 `后端-05` 的 API 前缀为落地边界;旧 SQL 只能作为历史快照 |
| `muse-admin/` | 管理端fork `yudao-ui-admin-vben`,承接管理员控制台 | `产品-02B` / `流程-01A` / `流程-02A` / `前端-01` / `后端-05` | 只调用 `/admin-api/**`;复用 Vben 的菜单、权限、表格和表单体系,不复用用户端写作工作台 |
| `muse-studio/` | 自研用户端;推荐 Next.js / React / TypeScript | `产品-02C` / `产品-02D` / `产品-02E` / `产品-02F` / `产品-02G` / `前端-01` / `前端-02` / `前端-03` | 只调用 `/app-api/**`;承载普通用户创作、资产、市场和个人中心,不复用 Vben 后台 layout |
| `muse-design-docs/` | 当前 `design-docs/` 独立化后的产品与架构 SSOT | `00-文档大纲` / `内容映射表` / 各正式分册 | 继续按阶段和 owner 管理设计;实现仓必须对齐这里的正式 owner不用临时文档反向覆盖正式分册 |
## 新产品形态内容归属(正式文档)
说明:
- 本节归属新增的新产品形态(Product Shape)内容,不属于历史 `doc/new-design/` 迁移表,避免和旧源文档映射冲突。
- 临时改造文档删除后,以这里指向的正式文档为归属入口;本表只做导航,不重复定义字段、状态机、接口或表结构。
| 内容 | 正式归属 | Notes |
|---|---|---|
| 新产品形态(Product Shape)总体定义 | `产品-01` / `产品-02` / `产品-03` / `架构-01` | 产品文档定义角色、价值和旅程;架构文档定义系统边界;阶段影响面与验收门禁见 `docs/mvp/进度总账.md` + 覆盖 JSON`doc/dev/*` 规划未落地)。 |
| 管理员控制台(Admin Console) | `产品-02` / `架构-01` / `后端-05` / `前端-01` | `产品-02` 定功能边界;`架构-01` 定系统边界;`后端-05` 定接口;`前端-01` 定信息架构。 |
| 我的作品(My Works) | `产品-02` / `产品-03` / `流程-01B` / `前端-01` | 只做作品列表与入口;单作品深层流程归作品工作台。 |
| 作品工作台(Work Workspace) | `产品-03` / `流程-01B` / `流程-02B` / `前端-02` | 承载写作、规划、知识、导入、导出、记录与用量的单作品创作空间。 |
| 作品规划台(Planning Desk) | `产品-02` / `产品-03` / `架构-02` / `前端-03` | 产品定义用户语言和 AI 辅助边界;模型归属仍看 `架构-02`,前端动态表单看 `前端-03`。 |
| 知识与一致性 | `产品-02` / `流程-01B` / `流程-02B` / `架构-02` / `前端-02` / `后端-05` | 产品和流程定义用户动作;模型边界看 `架构-02`;编辑器侧交互看 `前端-02`;接口看 `后端-05`。 |
| 全局知识库(Global Knowledge Base) / 局域知识库(Local Knowledge Base) | `架构-01` / `架构-02` / `后端-04` / `后端-05` | 架构定义边界和模型归属;表结构以 `后端-04` 为准;接口以 `后端-05` 为准。 |
| 个人中心(Personal Center) | `产品-02` / `前端-01` / `后端-05` | 承载个人信息、用量、配额、套餐、生成记录总览和授权摘要;不承载单作品深层创作或管理员配置。 |
| 使用日志 | `产品-02` / `后端-05` / `前端-01` | 普通用户可见的生成记录、任务记录、令牌(Token)使用和成本提示;系统审计不混入普通用户入口。 |
| Sa-Token 认证授权基座 | `架构-01` / `架构-03` / `后端-01` / `后端-02` / `后端-04` / `后端-05` / `前端-01` | Sa-Token 只负责登录认证、RBAC、接口鉴权、会话、当前用户和基础审计上下文不替代 Muse 产品架构和 Shadow -> Canonical 业务规则。 |
| AI 编排、检索上下文和质量评测合同 | `专题-03` / `流程-02A` / `流程-02B` / `后端-03` / `后端-04` / `后端-05` | `专题-03` 收束 RAGFlow、Graph Query Provider、Context Assembly、Agent/Prompt、Risk Routing、评测聚合和默认超级管理员初始化的跨文档目标设计精确表结构和 API 仍看 `后端-04` / `后端-05`。 |
## 信息架构门禁归属
信息架构门禁(Information Architecture Gate, IA Gate)属于产品形态与文档对齐门禁,不是新的工程实现大阶段,也不重排 S0-S5 技术依赖。
| Gate | 正式归属 | Notes |
|---|---|---|
| IA-0角色边界与信息架构重构 | `产品-02` / `架构-01` / `前端-01` / `后端-05` | 验收管理员、普通用户、个人中心的入口和权限边界。 |
| IA-1普通用户作品工作台 | `产品-02` / `产品-03` / `流程-01B` / `流程-02B` / `前端-01` / `前端-02` | 验收我的作品、作品工作台及单作品深层流程归属。 |
| IA-2管理员控制台 | `产品-02` / `架构-01` / `流程-01A` / `流程-02A` / `前端-01` / `后端-05` | 验收管理员配置能力、权限、审计和接口归属。 |
| IA-3作品规划台和高质量小说维度 | `产品-02` / `产品-03` / `架构-02` / `前端-03` | 验收作品规划维度是否进入 AI 辅助、上下文或检查链路。 |
## 映射总表Source → Target → Notes
说明:
- 策略:`保留`=尽量原样迁移;`改写`=按 V2 边界重写;`引用`=只保留一句话 + 指向主文档。
- “主文档”负责给出定义/动机/约束;其他文档只能引用,不得重复解释。
- 本节只处理历史 `doc/new-design/` 到 V2 文档的迁移;新产品形态和 IA gate 看上面的正式归属表。
### `doc/new-design/00-文档大纲设计.md`
| Source 章节 | Target | 策略 | Notes |
|---|---|---:|---|
| 文档目标与读者/总体统计 | `00-文档大纲.md` | 改写 | 只保留“目标/读者/导航”,删除历史统计噪音。 |
| 各文档详细大纲 | `00-文档大纲.md` | 改写 | 作为 V2 索引骨架;文件名改为 V2。 |
| ADR(架构决策记录) 列表与格式 | `架构-03-关键决策与原则(ADR).md` | 改写 | ADR(架构决策记录) 是架构主文档;其他地方只能引用 ADR(架构决策记录) 编号。 |
### `doc/new-design/01-概要设计.md`
| Source 章节 | Target | 策略 | Notes |
|---|---|---:|---|
| 1 系统定位与核心价值 | `产品-01-产品定位与核心价值.md` | 改写 | 去掉实现细节;保留“为谁/解决什么/价值”。 |
| 2 核心概念(总览) | `架构-02-核心数据结构与双轨模型.md` | 改写 | 概念主文档归架构;产品文档只引用。 |
| 2.1 Canonical(规范数据) vs Shadow(待审层) | `架构-02-核心数据结构与双轨模型.md` | 保留/改写 | 定义/边界/数据流规则在此;前后端分别写实现引用。 |
| 2.2 Block(文本块)(细粒度内容单元) | `架构-02-核心数据结构与双轨模型.md` + `后端-01-领域模型与聚合设计.md` | 改写 | 架构只说“数据结构与不变式”;后端说“聚合/版本/冲突”。 |
| 2.3 Knowledge Graph | `架构-02-核心数据结构与双轨模型.md` + `后端-01-领域模型与聚合设计.md` | 改写 | 架构:三层结构与能力边界;后端:实体/关系/存储策略。 |
| 2.4 Meta-driven(元结构驱动) | `架构-02-核心数据结构与双轨模型.md` + `前端-03-元引擎与动态表单.md` | 改写 | 架构:为什么;前端:怎么渲染;后端如涉及 schema 聚合再引用。 |
| 3 架构原则 | `架构-03-关键决策与原则(ADR).md` | 改写 | 原则要短、可执行;删除重复论述,保留检查清单。 |
| 4 顶层架构图/有界上下文 | `架构-01-系统全貌与边界上下文.md` | 改写 | 只保留 BC(有界上下文) 边界/协作规则;实现细节一律引用后端/前端。 |
| 4.2/4.3 数据流向总结 | `架构-01-系统全貌与边界上下文.md` + `架构-02-核心数据结构与双轨模型.md` | 改写 | “系统视角链路”放架构-01“模型规则”放架构-02。 |
| 5 ADR(架构决策记录) 全部 | `架构-03-关键决策与原则(ADR).md` | 保留/改写 | 统一 ADR(架构决策记录) 编号与链接;产品/前后端引用编号即可。 |
### `doc/new-design/02-架构设计.md`
| Source 章节 | Target | 策略 | Notes |
|---|---|---:|---|
| 1 技术栈选型(后端) | `后端-02-工程结构与模块职责.md` | 改写 | 只保留“依赖/模块/职责”;把“为什么”留在 ADR(架构决策记录)。 |
| 1 技术栈选型(前端) | `前端-01-工程结构与核心依赖.md` | 改写 | 依赖清单/目录结构归前端-01。 |
| 1 数据栈/AI 栈/Key 管理 | `后端-03-关键流程实现与接口契约.md` | 改写 | 这是后端契约与安全边界的一部分,不进架构文档。 |
| 2 部署架构Docker Compose 等) | `后端-02-工程结构与模块职责.md` | 引用 | V2 不重复贴大段 compose只保留入口与关键约束必要时指向旧文档历史。 |
| 3 外部集成New-API(接口)/Dify/Ragflow | `后端-03-关键流程实现与接口契约.md` | 改写 | 以“接口契约/失败模式/边界”组织,而不是配置粘贴。 |
| 4 数据架构Schema(结构定义)/Redis/pgvector(向量扩展) | `架构-02-核心数据结构与双轨模型.md` + `后端-01-领域模型与聚合设计.md` | 改写 | 架构讲模型与规则;后端讲落地与表/索引。 |
| 5 安全与认证 | `后端-03-关键流程实现与接口契约.md` | 改写 | 后端主文档;架构文档只引用安全边界。 |
### `doc/new-design/03-领域设计.md`
| Source 章节 | Target | 策略 | Notes |
|---|---|---:|---|
| DDD(领域驱动设计) 设计哲学/聚合根原则/BC(有界上下文) 划分 | `后端-01-领域模型与聚合设计.md` + `架构-01-系统全貌与边界上下文.md` | 改写 | BC(有界上下文) 边界归架构-01聚合/不变式归后端-01。 |
| Content BC(内容上下文) / Knowledge BC(知识上下文) / Admin BC(管理上下文) / AI BC(人工智能上下文) 模型 | `后端-01-领域模型与聚合设计.md` | 保留/改写 | 结构保留,术语统一为 V2去掉与流程重复解释。 |
| 跨上下文协作/事件驱动/接口隔离 | `架构-01-系统全貌与边界上下文.md` + `后端-03-关键流程实现与接口契约.md` | 改写 | 架构只定义协作规则;后端定义接口契约与事务边界。 |
### `doc/new-design/04-前端工程结构.md`
| Source 章节 | Target | 策略 | Notes |
|---|---|---:|---|
| 技术架构/依赖/目录结构 | `前端-01-工程结构与核心依赖.md` | 保留/改写 | 保留可执行信息;删除与后端/部署无关噪音。 |
| 编辑器子系统ParagraphBlock/插件/状态) | `前端-02-编辑器与影子层交互.md` | 改写 | 以“编辑体验 + Shadow(待审层) 交互”为主线。 |
| 影子存储Zustand(状态库)/TanStack Query(Query缓存库) | `前端-02-编辑器与影子层交互.md` | 改写 | 只讲前端侧的数据拥有与同步策略。 |
| 元引擎Meta Engine(元引擎)/动态表单 | `前端-03-元引擎与动态表单.md` | 保留/改写 | 与架构-02 的 Meta-driven(元结构驱动) 概念互相引用,不重复定义。 |
### `doc/new-design/05-后端工程结构.md`
| Source 章节 | Target | 策略 | Notes |
|---|---|---:|---|
| Maven(构建工具) 多模块/目录结构/包规范 | `后端-02-工程结构与模块职责.md` | 保留/改写 | 这是后端工程主入口;别把流程/产品混进来。 |
| Spring AI 集成/配置 | `后端-03-关键流程实现与接口契约.md` | 改写 | 以“调用链路/失败模式/Key 边界”为主。 |
| 关键服务Ner/Consistency/ShadowRepo | `后端-03-关键流程实现与接口契约.md` | 改写 | 以流程阶段组织;服务实现细节少说,多说契约与边界。 |
| API(接口) 端点清单 | `后端-03-关键流程实现与接口契约.md` | 改写 | 收敛成“端点/输入输出/权限/事务边界”表格。 |
### `doc/new-design/06-产品操作流程.md`
| Source 章节 | Target | 策略 | Notes |
|---|---|---:|---|
| 流程总览/用户旅程地图 | `产品-03-用户旅程与操作流程.md` + `流程-01A-管理员操作流程(操作视角).md` + `流程-01B-普通用户操作流程(操作视角).md` | 改写 | 产品文档给“旅程/决策点”;流程文档给“步骤化可执行流程”。 |
| 主流程详解(步骤 1-5 | `流程-01B-普通用户操作流程(操作视角).md` | 保留/改写 | 按步骤重写,补齐输入/输出与决策点。 |
| UI(界面) 交互关键点Editor/ShadowPanel | `产品-02-核心功能与交互边界.md` + `前端-02-编辑器与影子层交互.md` | 改写 | 产品只定义边界与行为;前端说实现机制。 |
| 用户决策点触发AI/冲突处理) | `产品-02-核心功能与交互边界.md` + `流程-01B-普通用户操作流程(操作视角).md` | 改写 | 决策点应短且明确;技术解释引用架构/后端。 |
### `doc/new-design/07-业务处理流程.md`
| Source 章节 | Target | 策略 | Notes |
|---|---|---:|---|
| 流程总览/系统处理模型 | `流程-02A-管理员系统处理流程(系统视角).md` + `流程-02B-普通用户系统处理流程(系统视角).md` | 保留/改写 | 系统视角按管理员治理链路和普通用户业务链路拆分。 |
| 核心系统流程 | `流程-02A-管理员系统处理流程(系统视角).md` + `流程-02B-普通用户系统处理流程(系统视角).md` + `后端-03-关键流程实现与接口契约.md` | 改写 | 流程文档讲“状态机/数据流”;后端文档讲“接口/事务/错误”。 |
| 数据流转/一致性保证 | `架构-02-核心数据结构与双轨模型.md` + `后端-03-关键流程实现与接口契约.md` | 改写 | 模型规则归架构-02一致性手段归后端-03。 |
| 触发机制/事件总线/未来智能体编排 | `架构-03-关键决策与原则(ADR).md` + `后端-03-关键流程实现与接口契约.md` | 引用 | 未来项别在流程文档里发散;留 ADR(架构决策记录)/后端引用。 |
## 重复概念的“主文档”归属(强制)
- 双轨Canonical(规范数据)/Shadow(待审层)):主文档 `架构-02-核心数据结构与双轨模型.md`
- 有界上下文BC(有界上下文))与协作规则:主文档 `架构-01-系统全貌与边界上下文.md`
- ADR(架构决策记录)/原则:主文档 `架构-03-关键决策与原则(ADR).md`
- 产品旅程与决策点:主文档 `产品-03-用户旅程与操作流程.md`(步骤细化在 `流程-01A/01B`
- 系统处理模型:主文档 `流程-02A-管理员系统处理流程(系统视角).md` / `流程-02B-普通用户系统处理流程(系统视角).md`
- AI 编排、检索上下文和质量评测合同:主文档 `专题-03-AI编排上下文与质量评测实现规范.md`
- 元数据驱动的智能体架构(横切):主文档 `专题-06-元数据驱动的智能体架构.md`owns 六个概念——
- 元数据驱动的智能体架构agent = f(作品 + 元数据 + 知识库),元引擎 + 功能链双枢
- 三体关系muse-cloud主权/ dify-agent能力执行/ dify-rag检索基座/ New-API模型网关
- target type 结构本体23 型清单 + domain 逐值语义 + 拆分判据(术语权威仍在 `架构-02` §9
- 统一创作数据读取器AI 上下文的服务端读合同三级裁剪、fail-closed omittedSources
- base 内置种子清单23 项四档全局 schema 的叠加与继承机制
- 拆书通用抽取与参考作品:`reference_work` 档案 + 范式 lineageGlobal/Local KB 两处浇铸;参照作品面 = 系统侧证据资产,非第四类知识库,见其 §6.4
- 知识效用闭环(横切):主文档 `专题-07-知识消费契约与质量闭环.md`owns 四个概念——
- 知识消费选择契约按用途generation/planning/detection/extraction的默认合同、注入视图两档、排序信号截断规则归 `专题-03` §4.2
- 知识质量三性:可命中 / 可行动 / 可持续(输入侧检尺,与 `专题-04` 输出侧维度分立、单向咬合)
- 回放评测:参考书=标准答案的知识策略离线评估(机制归 `专题-04` §10 框架,定义在本册)
- 长线进度消费语义:演变历程 {章,台阶,周期} 的规划/检测/写作三期消费
- 边界备注:参照作品面的浇铸位归 `专题-06` §6.4;输出侧质量维度仍归 `专题-04`;术语权威仍在 `架构-02`
- 测试可判定性(横切):主文档 `专题-08-自动化测试方案.md`owns 四个概念——
- 测试金字塔分层L1 数据不变式/状态机、L2 接口契约/事务/幂等、L3 前端交互/不丢稿、L4 AI 语义质量
- 确定性/语义分界判据:「能否不看正文含义、只比对结构与数值判定对错」+ 混合体处理纪律
- 语义评测方法论双盲评委、对照实验两臂对等Gate B 范式、回放评测n=1 不下结论
- 测试可判定性合同:每个功能要可测必须提供的判据;未提供视为需求未闭合
- 边界备注:不重定义状态机/Schema/API/质量维度,只引用各 owner具体质量维度仍归 `专题-04`,知识效用仍归 `专题-07`
- 状态机与约束:主文档 `架构-04-状态机与约束清单.md`
- 后端模块职责:主文档 `后端-02-工程结构与模块职责.md`
- 统一数据库表结构:主文档 `后端-04-统一数据库Schema-v1.md`
- 统一接口(API)契约:主文档 `后端-05-统一API契约-v1.md`
- 产品形态与 IA gate产品形态见 `产品-01/02/03` + `架构-01`;阶段路线图见 [`docs/mvp/进度总账.md`](../docs/mvp/进度总账.md);验收门禁见覆盖 JSON + verification 规则(原 `doc/dev/01``doc/dev/09` 规划未落地)