76a7e0d312
承临时-02 拍板(B' installed_ref + KB 先行)出 KB 物化执行版 plan，拆 U0-U4 可独立验证实现单元。出 plan 时一手代码核验揪出四条改变工作量/性质的硬事实(均 spot-check 坐实):①kb_id 当前被 market assetId 污染(KnowledgeHandoffLanding sourceId=assetId)→物化须去污染改写;②assetId→发布者 dataset 反查链跨 BC 断(market.api 仅 HandoffTokenApi)→需新增 MarketAssetSourceApi 本地读端口;③多租户共享同一 RAGFlow dataset 必越权(retrieveChunks body 不含 tenant+document_ids=null 全量返回、parseChunks 无 chunk 租户二次过滤)=安全红线→U0 从"验证能否共享"转为"共享前先补 chunk 级隔离"硬门;④muse_source_propagation_target 表零命中→U4 回滚改基于真实 source_event 机制。 物化落点严格在 knowledge 绑定路径(非 install、handoff 非物化桥、安装解耦不动)。初版判定不需新 Flyway 迁移(V5/V14 已备列)。决策点 D1(共享 S/复制 C/暂缓 H)待人类先看 U0 spike 证据再拍。两图文(text+mermaid + html 人读图)+大纲注册。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
14 KiB
14 KiB
New-Design（新设计）V2 文档大纲（入口）
- 版本：v8
- 更新日期：2026-06-25
- 目标读者：产品 / 架构 / 前端 / 后端 / 文档维护者
- 阅读时间：10–20 分钟
- 边界说明：本文件只负责导航、边界和归属，不重复解释概念；概念解释必须落在对应主文档中。
- 设计 ≠ 进度：design-docs 是设计意图 SSOT（要建成什么），不代表已实现；实现进度见
docs/mvp/进度总账.md（进度 SSOT）+docs/项目功能与进度总览.md（人读全局）+ 覆盖 JSON（接口门机械源）。
目标
- 形成一套按角色拆分、单一归属、可持续维护的设计文档集。
- 明确“产品闭环、系统流程、实现约束”分别由谁负责，不允许多份文档各说各话。
文档集规则（别制造特殊情况）
- 角色前缀 + 扁平结构：文件名即归属，避免目录层级变成垃圾桶。
- 跨文档复用内容只允许“链接 + 一句话摘要”，禁止大段复制粘贴。
- 术语统一：规范数据(Canonical) / 待审层(Shadow) / 作品(Work) / 章节(Chapter) / 文本块(Block) / 元结构定义(MetaSchema) 等，以
架构-02-核心数据结构与双轨模型.md为准。 - 临时改造文档只作为迁移依据；临时文档删除后，正式归属由
产品-*、流程-*、架构-*、前端-*、后端-*承担，不成为长期单一事实源(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-核心功能与交互边界、架构-01-系统全貌与边界上下文、流程-01A-管理员操作流程、流程-02A-管理员系统处理流程 | 后端-05-统一API契约-v1、前端-01-工程结构与核心依赖 | 管理系统能力、全局知识、权限、审计和评测，不替普通用户做单作品创作取舍。 |
| 普通用户工作区(User Workspace) | 产品-02-核心功能与交互边界、产品-03-用户旅程与操作流程、流程-01B-普通用户操作流程、流程-02B-普通用户系统处理流程 | 前端-01-工程结构与核心依赖、前端-02-编辑器与影子层交互、前端-03-元引擎与动态表单、后端-05-统一API契约-v1 | 包含我的作品(My Works)、单作品的作品工作台(Work Workspace)、写作台、作品规划台、知识与一致性、导入解析、导出交付、记录与用量；不承载管理员配置。 |
| 个人中心(Personal Center) | 产品-02-核心功能与交互边界、前端-01-工程结构与核心依赖、后端-05-统一API契约-v1 | — | 管理个人信息、令牌(Token)使用、配额、套餐、生成记录总览和授权摘要；不承载单作品深层创作或系统后台配置。 |
快速导航（按文档职责）
产品
- 产品-01-产品定位与核心价值
- 产品-02-核心功能与交互边界
- 产品-03-用户旅程与操作流程
- 需要按步骤执行时，按角色阅读：流程-01A-管理员操作流程 / 流程-01B-普通用户操作流程
导入与全书解析相关内容只做归属，不多处重写：
- 产品边界：
产品-02-核心功能与交互边界.md - 管理员操作步骤：
流程-01A-管理员操作流程(操作视角).md - 普通用户操作步骤：
流程-01B-普通用户操作流程(操作视角).md - 管理员系统链路：
流程-02A-管理员系统处理流程(系统视角).md - 普通用户系统链路：
流程-02B-普通用户系统处理流程(系统视角).md - 模型与边界：
架构-02-核心数据结构与双轨模型.md - 接口与事务：
后端-05-统一API契约-v1.md - 前端一致性：
前端-02-编辑器与影子层交互.md
架构
后端
- 后端-01-领域模型与聚合设计
- 后端-02-工程结构与模块职责
- 后端-03-关键流程实现与接口契约
- 后端-04-统一数据库Schema-v1
- 后端-05-统一API契约-v1
- 系统链路参考：
流程-02A-管理员系统处理流程(系统视角).md/流程-02B-普通用户系统处理流程(系统视角).md
前端
流程
专题补充
说明：专题文档只负责跨文档收束，不抢走 Schema、状态机和统一 API 的单一归属。
临时件（评审/迁移依据，落定后归并或删除，不作长期 SSOT）
- 临时-01-AI流SSE长任务超时修复方案（评审版）——AI 真生成"长任务候选丢失"的 SSE 协议/时序 bug 修复方案对比，待人类 review 后执行；配套人读图
.html。SSE 接口语义归属仍属后端-05，本件不重定义概念。 - 临时-02-market-install下游物化方案（评审版）——市场安装的 agent/kb 到“可真用”的两个物化断点（知识库检索
no_dataset门 + 智能体 runtime 实体缺失）诊断与 C/B'/B/暂缓 四方案对比，待人类拍板物化深度/时机/数据集共享；配套人读图.html。owner 边界与表结构归架构-02/后端-04，handoff 边界与 ADR-016/017/020 只引用不重定义。 - 临时-03-market-install-KB物化执行plan（执行版）——承临时-02 拍板（B' installed_ref + KB 先行），把 KB 物化拆成 U0–U4 可独立验证实现单元；一手代码核验揪出四条硬事实（kb_id 被 assetId 污染、跨 BC 反查链断需新
MarketAssetSourceApi、多租户共享同一 RAGFlow dataset 必越权→U0 转为“共享前先补 chunk 级隔离”硬门、muse_source_propagation_target表不存在）；物化落点在 knowledge 绑定路径（非 install）。待人类拍 D1（共享 vs 复制 vs 暂缓）后执行；配套人读图.html。owner 边界引 临时-02/架构-02/专题-03/ADR-020，不重定义。
输入 / 输出闭环（你写的东西要能被别人用）
| 文档 | 输入（来自哪里） | 输出（给谁用） |
|---|---|---|
| 产品-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 | 已收敛为目标设计的 AI 编排缺口 | RAGFlow、Graph Query Provider、上下文组装、Agent/Prompt、Risk Routing、质量评测和默认超级管理员初始化的跨文档实现规范 |
| (原 doc/dev/* 规划未落地) | 职责已由实际文档承担 | 路线图/阶段 → docs/mvp/进度总账.md；验收门禁 → 覆盖 JSON + verification 规则；真实现状差距 → docs/项目功能与进度总览.md |
单一归属清单（强制）
- 双轨模型：
架构-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 - 产品形态：
产品-01/02/03+架构-01；阶段路线图/验收门禁：docs/mvp/进度总账.md+ 覆盖 JSON（原doc/dev/01、doc/dev/09规划未落地）
迁移说明
- 映射表：
内容映射表.md - 历史文档源：
doc/new-design/（仅保留参考，不再作为当前设计单一事实源） - 临时改造文档：已于 2026-06-14 完成改造并删除(内容已落入
产品-*/架构-*/流程-*等正式分册;完整历史见 git)。