329db944ff
排查发现进度数字三套互相矛盾:总览/现状基线/主台账历史段=147/86、agent-specs=100/127、module-reality=233/0。核机械真值:覆盖 JSON summary=233/233 completed/0 needs(每 op 带 testFiles 证据 + P1rApiCoverageReportTest 校验 summary 自算防手工拨)。⚠️ JSON generatedAt=2026-05-25 未随内容刷新(手工维护痕迹),已在文档标注以 summary+testFiles 为准。
修正:① 总览(我上轮新建,误抄过时台账)147/233→233/233、各域 full、接口门≠端到端两口径分清、定位为人读封面(权威以台账/JSON为准);② 主台账 头部加机械源口径声明(233/0)+门禁中→满+验收债标已清零;③ 现状基线降级为 2026-06-13 历史快照(顶部时效横幅+性质去SSOT);④ AGENTS序2/module-reality 改引用;⑤ agent-specs/.agent 注记历史数字;⑥ meta-schema review 回指 execution v0.2 已证伪地基(待决策提案);⑦ design-docs/00 加'设计≠进度';⑧ dev-baseline 申明旧 SSOT 自称失效。
确立单一真实源:设计=design-docs;进度=进度总账(叙述)+覆盖JSON(机械);人读=项目功能与进度总览(封面)。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
152 lines
13 KiB
Markdown
152 lines
13 KiB
Markdown
# New-Design（新设计）V2 文档大纲（入口）
|
||
|
||
- 版本：v6
|
||
- 更新日期：2026-05-24
|
||
- 目标读者：产品 / 架构 / 前端 / 后端 / 文档维护者
|
||
- 阅读时间：10–20 分钟
|
||
- 边界说明：本文件只负责导航、边界和归属，不重复解释概念；概念解释必须落在对应主文档中。
|
||
- **设计 ≠ 进度**：design-docs 是**设计意图 SSOT**（要建成什么），**不代表已实现**；实现进度见 [`docs/mvp/进度总账.md`](../docs/mvp/进度总账.md)（进度 SSOT）+ [`docs/项目功能与进度总览.md`](../docs/项目功能与进度总览.md)（人读全局）+ 覆盖 JSON（接口门机械源）。
|
||
|
||
## 目标
|
||
|
||
- 形成一套按角色拆分、单一归属、可持续维护的设计文档集。
|
||
- 明确“产品闭环、系统流程、实现约束”分别由谁负责，不允许多份文档各说各话。
|
||
|
||
## 文档集规则（别制造特殊情况）
|
||
|
||
- 角色前缀 + 扁平结构：文件名即归属，避免目录层级变成垃圾桶。
|
||
- 跨文档复用内容只允许“链接 + 一句话摘要”，禁止大段复制粘贴。
|
||
- 术语统一：规范数据(Canonical) / 待审层(Shadow) / 作品(Work) / 章节(Chapter) / 文本块(Block) / 元结构定义(MetaSchema) 等，以 `架构-02-核心数据结构与双轨模型.md` 为准。
|
||
- 临时改造文档只作为迁移依据；临时文档删除后，正式归属由 `产品-*`、`流程-*`、`架构-*`、`前端-*`、`后端-*` 和 `doc/dev/*` 承担，不成为长期单一事实源(Single Source of Truth, SSOT)。
|
||
|
||
## 工程仓库架构
|
||
|
||
阶段 7 以后，Muse 工程按四个仓库协作。仓库名是工程落地边界；业务概念、状态机、Schema 和 API 的单一事实源仍按本文档集的 owner 归属执行。
|
||
|
||
| 仓库 | 来源 / 形态 | 职责 | 主读文档 |
|
||
|---|---|---|---|
|
||
| `muse-cloud/` | fork `YunaiV/yudao-cloud` | 后端主仓；承接网关、system、infra、framework、任务、文件、权限等 Yudao 基础能力，并补 Muse 的 content、knowledge、ai、market、account 业务模块 | `后端-01`、`后端-02`、`后端-03`、`后端-04`、`后端-05` |
|
||
| `muse-admin/` | fork `yudao-ui-admin-vben` | 管理端；承载 Admin Console 的系统治理、元结构、Prompt / Agent、全局知识、市场治理、用户、权限、审计和质量观察 | `产品-02B`、`流程-01A`、`流程-02A`、`前端-01`、`后端-05` |
|
||
| `muse-studio/` | 自研用户端，推荐 Next.js / React | 普通用户创作端；承载我的作品、作品工作台、写作台、智能体工作台、知识库工作台、市场和个人中心 | `产品-02C`、`产品-02D`、`产品-02E`、`产品-02F`、`产品-02G`、`前端-01`、`前端-02`、`前端-03` |
|
||
| `muse-design-docs/` | 当前 `design-docs/` 独立化后的设计文档仓 | 产品、架构、流程、前端、后端、专题的设计 SSOT | `00-文档大纲`、`内容映射表`、各正式分册 |
|
||
|
||
协作约束：
|
||
|
||
- `muse-admin/` 只调用 `/admin-api/**`，不承载普通用户写作台、候选接受或作品知识取舍。
|
||
- `muse-studio/` 只调用 `/app-api/**`，不暴露系统 Prompt、底层 Pipeline、管理员审计或后台配置表。
|
||
- `muse-cloud/` 内部按领域 owner 写事实；`/admin-api/**` 和 `/app-api/**` 只是入口不同，不表示两套领域事实。
|
||
- `muse-design-docs/` 只定义目标设计和 owner 归属；实现仓的代码、迁移和测试必须反向对齐这里的正式文档，不能用实现便利反改产品语义。
|
||
|
||
## 角色视角导航
|
||
|
||
| 角色视角 | 先读 | 再读 | 边界 |
|
||
|---|---|---|---|
|
||
| 管理员控制台(Admin Console) | [产品-02-核心功能与交互边界](产品-02-核心功能与交互边界.md)、[架构-01-系统全貌与边界上下文](架构-01-系统全貌与边界上下文.md)、[流程-01A-管理员操作流程](流程-01A-管理员操作流程(操作视角).md)、[流程-02A-管理员系统处理流程](流程-02A-管理员系统处理流程(系统视角).md) | [后端-05-统一API契约-v1](后端-05-统一API契约-v1.md)、[前端-01-工程结构与核心依赖](前端-01-工程结构与核心依赖.md) | 管理系统能力、全局知识、权限、审计和评测，不替普通用户做单作品创作取舍。 |
|
||
| 普通用户工作区(User Workspace) | [产品-02-核心功能与交互边界](产品-02-核心功能与交互边界.md)、[产品-03-用户旅程与操作流程](产品-03-用户旅程与操作流程.md)、[流程-01B-普通用户操作流程](流程-01B-普通用户操作流程(操作视角).md)、[流程-02B-普通用户系统处理流程](流程-02B-普通用户系统处理流程(系统视角).md) | [前端-01-工程结构与核心依赖](前端-01-工程结构与核心依赖.md)、[前端-02-编辑器与影子层交互](前端-02-编辑器与影子层交互.md)、[前端-03-元引擎与动态表单](前端-03-元引擎与动态表单.md)、[后端-05-统一API契约-v1](后端-05-统一API契约-v1.md) | 包含我的作品(My Works)、单作品的作品工作台(Work Workspace)、写作台、作品规划台、知识与一致性、导入解析、导出交付、记录与用量；不承载管理员配置。 |
|
||
| 个人中心(Personal Center) | [产品-02-核心功能与交互边界](产品-02-核心功能与交互边界.md)、[前端-01-工程结构与核心依赖](前端-01-工程结构与核心依赖.md)、[后端-05-统一API契约-v1](后端-05-统一API契约-v1.md) | [doc/dev/01-总体路线图与阶段依赖](../dev/01-总体路线图与阶段依赖.md)、[doc/dev/09-验收口径与退出条件](../dev/09-验收口径与退出条件.md) | 管理个人信息、令牌(Token)使用、配额、套餐、生成记录总览和授权摘要；不承载单作品深层创作或系统后台配置。 |
|
||
|
||
## 快速导航（按文档职责）
|
||
|
||
### 产品
|
||
|
||
1. [产品-01-产品定位与核心价值](产品-01-产品定位与核心价值.md)
|
||
2. [产品-02-核心功能与交互边界](产品-02-核心功能与交互边界.md)
|
||
3. [产品-03-用户旅程与操作流程](产品-03-用户旅程与操作流程.md)
|
||
4. 需要按步骤执行时，按角色阅读：[流程-01A-管理员操作流程](流程-01A-管理员操作流程(操作视角).md) / [流程-01B-普通用户操作流程](流程-01B-普通用户操作流程(操作视角).md)
|
||
|
||
导入与全书解析相关内容只做归属，不多处重写：
|
||
|
||
- 产品边界：`产品-02-核心功能与交互边界.md`
|
||
- 管理员操作步骤：`流程-01A-管理员操作流程(操作视角).md`
|
||
- 普通用户操作步骤：`流程-01B-普通用户操作流程(操作视角).md`
|
||
- 管理员系统链路：`流程-02A-管理员系统处理流程(系统视角).md`
|
||
- 普通用户系统链路：`流程-02B-普通用户系统处理流程(系统视角).md`
|
||
- 模型与边界：`架构-02-核心数据结构与双轨模型.md`
|
||
- 接口与事务：`后端-05-统一API契约-v1.md`
|
||
- 前端一致性：`前端-02-编辑器与影子层交互.md`
|
||
|
||
### 架构
|
||
|
||
1. [架构-01-系统全貌与边界上下文](架构-01-系统全貌与边界上下文.md)
|
||
2. [架构-02-核心数据结构与双轨模型](架构-02-核心数据结构与双轨模型.md)
|
||
3. [架构-03-关键决策与原则(ADR)](架构-03-关键决策与原则(ADR).md)
|
||
4. [架构-04-状态机与约束清单](架构-04-状态机与约束清单.md)
|
||
|
||
### 后端
|
||
|
||
1. [后端-01-领域模型与聚合设计](后端-01-领域模型与聚合设计.md)
|
||
2. [后端-02-工程结构与模块职责](后端-02-工程结构与模块职责.md)
|
||
3. [后端-03-关键流程实现与接口契约](后端-03-关键流程实现与接口契约.md)
|
||
4. [后端-04-统一数据库Schema-v1](后端-04-统一数据库Schema-v1.md)
|
||
5. [后端-05-统一API契约-v1](后端-05-统一API契约-v1.md)
|
||
6. 系统链路参考：`流程-02A-管理员系统处理流程(系统视角).md` / `流程-02B-普通用户系统处理流程(系统视角).md`
|
||
|
||
### 前端
|
||
|
||
1. [前端-01-工程结构与核心依赖](前端-01-工程结构与核心依赖.md)
|
||
2. [前端-02-编辑器与影子层交互](前端-02-编辑器与影子层交互.md)
|
||
3. [前端-03-元引擎与动态表单](前端-03-元引擎与动态表单.md)
|
||
|
||
### 流程
|
||
|
||
- [流程-01A-管理员操作流程(操作视角)](流程-01A-管理员操作流程(操作视角).md)
|
||
- [流程-01B-普通用户操作流程(操作视角)](流程-01B-普通用户操作流程(操作视角).md)
|
||
- [流程-02A-管理员系统处理流程(系统视角)](流程-02A-管理员系统处理流程(系统视角).md)
|
||
- [流程-02B-普通用户系统处理流程(系统视角)](流程-02B-普通用户系统处理流程(系统视角).md)
|
||
|
||
### 专题补充
|
||
|
||
- [专题-01-正文建议接受(Accept Suggestion)实现规范](专题-01-正文建议接受(Accept%20Suggestion)实现规范.md)
|
||
- [专题-02-Sudowrite对标与Muse产品取舍](专题-02-Sudowrite对标与Muse产品取舍.md)
|
||
- [专题-03-AI编排上下文与质量评测实现规范](专题-03-AI编排上下文与质量评测实现规范.md)
|
||
|
||
说明：专题文档只负责跨文档收束，不抢走 Schema、状态机和统一 API 的单一归属。
|
||
|
||
## 输入 / 输出闭环（你写的东西要能被别人用）
|
||
|
||
| 文档 | 输入（来自哪里） | 输出（给谁用） |
|
||
|---|---|---|
|
||
| 产品-01 | 业务目标 / 用户画像 / 产品战略 | 产品定位、价值主张、产品闭环、非目标 |
|
||
| 产品-02 | 需求 / 约束 / 交互取舍 | 功能边界、决策模型、失败反馈边界 |
|
||
| 产品-03 | 用户旅程 / 长期使用方式 | 单次创作闭环、长期作品闭环、关键决策点 |
|
||
| 架构-01 | 需求边界 / 有界上下文 | 系统全貌、上下文边界、协作规则 |
|
||
| 架构-02 | 核心概念 / 数据结构 | 双轨模型、数据不变式、模型级规则 |
|
||
| 架构-03 | 关键权衡 | 架构决策记录与原则 |
|
||
| 架构-04 | 结构定义 / 接口决策收束 | 生命周期、表级约束、端点前后置条件 |
|
||
| 后端-01 | 架构模型 / 有界上下文规则 | 聚合、实体、不变式 |
|
||
| 后端-02 | 工程约束 / 交付方式 | 模块职责、目录结构、依赖方向 |
|
||
| 后端-03 | 系统流程 / 外部集成 | 事务边界、事件边界、调用链路 |
|
||
| 后端-04 | 双轨模型与接口基线 | 数据库表结构、索引、迁移约束 |
|
||
| 后端-05 | 统一资源语义 | API 契约、异步模式、错误模型 |
|
||
| 前端-01 | 产品边界 / 工程约束 | 前端结构、依赖、目录策略 |
|
||
| 前端-02 | 双轨交互规则 | 编辑器与待审层协作、回滚与刷新策略 |
|
||
| 前端-03 | 元结构驱动规则 | 动态表单与渲染链路 |
|
||
| 流程-01A | 管理员操作步骤 / 决策点 | 管理员配置、治理、审核、回滚、观察和高危处理路径 |
|
||
| 流程-01B | 普通用户操作步骤 / 决策点 | 普通用户创作、资产使用、市场获取、账户处理、可观察反馈和恢复路径 |
|
||
| 流程-02A | 管理员系统链路 | 管理员配置发布、治理、权限、New-API、任务和审计处理 |
|
||
| 流程-02B | 普通用户系统链路 | 普通用户创作、候选、知识、资产、handoff、任务和失败恢复处理 |
|
||
| 专题-01 | 已确认的跨文档决策 | Accept Suggestion 的统一收束稿 |
|
||
| 专题-02 | 外部竞品调研 / 产品取舍判断 | Sudowrite 对标、Muse 优劣势、该学什么与不该学什么 |
|
||
| 专题-03 | doc/dev 中已经收敛为目标设计的 AI 编排缺口 | RAGFlow、Graph Query Provider、上下文组装、Agent/Prompt、Risk Routing、质量评测和默认超级管理员初始化的跨文档实现规范 |
|
||
| doc/dev/* | 当前代码事实 / 阶段目标 / 正式设计归属 | 实现路线图、产品形态影响面、阶段验收门禁(Gate)、真实现状差距 |
|
||
|
||
## 单一归属清单（强制）
|
||
|
||
- 双轨模型：`架构-02-核心数据结构与双轨模型.md`
|
||
- 有界上下文与协作规则：`架构-01-系统全貌与边界上下文.md`
|
||
- 架构决策记录：`架构-03-关键决策与原则(ADR).md`
|
||
- 生命周期与状态机：`架构-04-状态机与约束清单.md`
|
||
- 后端模块职责：`后端-02-工程结构与模块职责.md`
|
||
- 产品旅程与长期闭环：`产品-03-用户旅程与操作流程.md`
|
||
- 系统处理流程：`流程-02A-管理员系统处理流程(系统视角).md` / `流程-02B-普通用户系统处理流程(系统视角).md`
|
||
- AI 编排、检索上下文和质量评测跨文档合同：`专题-03-AI编排上下文与质量评测实现规范.md`
|
||
- 统一数据库表结构：`后端-04-统一数据库Schema-v1.md`
|
||
- 统一接口契约：`后端-05-统一API契约-v1.md`
|
||
- 产品形态与信息架构门禁：`doc/dev/01-总体路线图与阶段依赖.md` 和 `doc/dev/09-验收口径与退出条件.md`
|
||
|
||
## 迁移说明
|
||
|
||
- 映射表：`内容映射表.md`
|
||
- 历史文档源：`doc/new-design/`（仅保留参考，不再作为当前设计单一事实源）
|
||
- 临时改造文档：已于 2026-06-14 完成改造并删除(内容已落入 `产品-*`/`架构-*`/`流程-*` 等正式分册;完整历史见 git)。
|