40d4bdb527
断链扫描发现 design-docs 把整套 doc/dev/00..09(路线图/阶段/IA验收门禁/真实现状差距)当 SSOT/门禁权威反复引用约 16 处,但该套文档 git 全历史从未创建 → 读者按图索骥全 404。职责实已被现有文档承担,逐处改指或墓碑标注:路线图/阶段→进度总账;验收门禁→覆盖 JSON+verification 规则;真实现状差距→项目功能与进度总览;产品形态→产品/架构分册;RAGFlow 落地→muse-module-knowledge。 改动:00-文档大纲(SSOT归属/角色导航再读列断链/专题-03描述/职责表/单一归属 共5处 + v6→v7);内容映射表(dev路线图块/产品形态行/个人中心/Sa-Token/IA-0~3门禁/IA gate 共~11处 + v6→v7);架构-03 ADR(参考落地2处 + v9→v10)。 验证:断链扫描 3→1(唯一剩 dev-baseline 历史区格式占位符,无害);design-docs 残留 doc/dev 仅墓碑文字标注,0 可点击断链。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
18 KiB
18 KiB
内容映射表（New-Design(新设计) V2）
- 版本：v7
- 更新日期：2026-06-20
- 目标读者：文档维护者/架构/前端/后端/产品
- 阅读时间：10–15 分钟
- 边界说明：本文件只做“内容归属与迁移策略”定义，不承载业务/架构细节；细节必须落到对应 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
- dev 路线图（⚠️
doc/dev/*规划未落地、从未创建；职责已由实际文档承担）：- 真实现状与目标差距 →
docs/项目功能与进度总览.md - 总体路线图 / 阶段 →
docs/mvp/进度总账.md - 验收口径与退出条件 → 覆盖 JSON
p1r-api-coverage.json+.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 - 状态机与约束：主文档
架构-04-状态机与约束清单.md - 后端模块职责：主文档
后端-02-工程结构与模块职责.md - 统一数据库表结构：主文档
后端-04-统一数据库Schema-v1.md - 统一接口(API)契约：主文档
后端-05-统一API契约-v1.md - 产品形态与 IA gate：产品形态见
产品-01/02/03+架构-01；阶段路线图见docs/mvp/进度总账.md；验收门禁见覆盖 JSON + verification 规则（原doc/dev/01、doc/dev/09规划未落地）