diff --git a/docs/superpowers/specs/2026-09-08-project-init-template-cloning-design.md b/docs/superpowers/specs/2026-09-08-project-init-template-cloning-design.md new file mode 100644 index 00000000..114ae3d1 --- /dev/null +++ b/docs/superpowers/specs/2026-09-08-project-init-template-cloning-design.md @@ -0,0 +1,181 @@ +# 项目创建即时克隆全生命周期文档模板副本设计规范 +# (Project-Init Template Cloning & Full-Lifecycle Workflow Visualization Spec) + +- **归档路径**: `docs/superpowers/specs/2026-09-08-project-init-template-cloning-design.md` +- **编制日期**: 2026-09-08 +- **当前状态**: 待实施 (Draft / Pending Plan) +- **技术栈**: React 19 + TypeScript + FlowMind Token 设计系统 + Vite + Go 协同服务 + +--- + +## 一、 业务背景与用户价值 (Background & User Value) + +在以往的项目运行模式中，交付物（Deliverables）往往随着智能体在对话中的逐步触发而离散生成。这种模式存在明显的业务认知断层： +1. **全局缺乏把控**：用户在刚新建一个医疗器械研发项目时，无法立刻获知整个立项和研发全生命周期到底包含哪些工作流（Workflows）、跨越哪些成熟度阶段（V0.1、V0.5、V1.0）、需要输出哪些法定与受控交付物； +2. **渐进获知的被动感**：用户需要“边走边看”，在与智能体多轮漫长问答、逐步触发任务后，才逐渐清楚下一步是什么阶段，体验如同“开盲盒”； +3. **前置规划与批注阻断**：用户和项目负责人无法在智能体开跑前，针对后续各阶段的标准骨架提出先验约束或章节批注要求。 + +### 核心用户诉求 +> **“每个项目创建后，系统应立即在本项目中创建全套文档模板的独立副本，并允许用户在创建后即刻查看。即使只是初始模板，也不需要等待智能体真正生成才看得到。用户可以一上来就对项目的工作流、阶段、交付物有全面、直观的概念。”** + +--- + +## 二、 架构设计与核心机制 (Architecture & Mechanics) + +``` +┌────────────────────────────────────────────────────────────────────────────────────────┐ +│ 新建项目触发 (Project Creation) │ +│ 输入：项目名称 (ProjectName)、申报器械 (DeviceType)、当前用户 (CurrentUser) │ +└──────────────────────────────────────────┬─────────────────────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────────────────────────────────────┐ +│ 全生命周期模板克隆工厂 (Template Cloning Factory) │ +│ 1. 映射标准七大交付物规范 (V0.1 intake, V0.5 research/reg/dev/urs/design, V1.0 quote) │ +│ 2. 注入已知元数据 ({{project_name}}, {{device_type}}, {{generated_at}} 等) │ +│ 3. 未决章节标注「待智能体填报 / 待确认」，解析为块状 AST │ +│ 4. 赋予独立项目命名空间：docId = doc-p{projectId}-{taskKey}, isTemplateOnly = true │ +└──────────────────────────────────────────┬─────────────────────────────────────────────┘ + │ + ┌─────────────────────┴─────────────────────┐ + ▼ ▼ +┌──────────────────────────────────────────┐┌───────────────────────────────────────────┐ +│ 项目级隔离交付物仓库 (Deliverables) ││ 右侧工作台全局呈现 (Workbench) │ +│ • 绑定 projectId，杜绝跨项目数据穿透 ││ • 抽屉与顶部 Tab 显示全套 7 份受控交付物 │ +│ • 标记 isTemplateOnly: true ││ • 标有「📄 初始模板」徽标与所属阶段 │ +│ • 状态 lifecycleState: 'template' ││ • 默认激活展示首份《用户初始需求收集表》 │ +│ • 责任人绑定当前用户与默认质量主管 ││ • 支持完整块级浏览、大纲导航与前置批注 │ +└──────────────────────────────────────────┘└───────────────────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────────────────────────────────────┐ +│ 智能体执行平滑填报演进 (Smooth Agent Transition) │ +│ 1. 智能体小队在对话中推进任务时，根据 (projectId, taskKey) 自动寻址到现有模板副本 │ +│ 2. 真实生成内容无缝替换骨架内容，保留用户已有批注 │ +│ 3. isTemplateOnly: true ──> false，状态升级为「✍️ 编制中 (drafting)」 │ +└────────────────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 三、 七大标准受控模板注册表 (Template Registry) + +系统建立全生命周期固定模板注册表，严格对齐后端 `internal/bizdev/service.go` 的 3 个成熟度阶段与 `templates/docs/*.md` 标准规范： + +| 阶段代码 | 阶段名称 | 任务键 (taskKey) | 交付物标题 (Title) | 核心章节与骨架特征 | +| :--- | :--- | :--- | :--- | :--- | +| **V0.1** | 闪电摸底与盲区探测 | `intake` | 用户初始需求收集表 | 研发背景、临床与使用场景、客户诉求与约束、阻塞与待确认清单 | +| **V0.5** | 方案成型与法规对齐 | `research` | 全球竞品技术与临床深度调研报告 | 竞品横向性能对标三线表、外科临床痛点、FTO专利回避流程图、商业化突破建议 | +| **V0.5** | 方案成型与法规对齐 | `feasibility_reg` | 注册路径与合规可行性评估报告 | 监管分类与强制性国标/行标矩阵、双CMOS分光拓扑图、微弱荧光SNR信噪比数学模型 | +| **V0.5** | 方案成型与法规对齐 | `feasibility_dev` | 设计开发可行性评估报告 | 技术可行性分析、关键工程化差距评估表、失效场景与工程风险应对预案 | +| **V0.5** | 方案成型与法规对齐 | `user_requirements` | 医疗器械用户需求规范表 (URS) | 临床用户角色画像、可追溯用户需求条目清单 (UR-001 ~ UR-00N)、验收思路 | +| **V0.5** | 方案成型与法规对齐 | `prelim_design` | 系统初步架构与电路规格设计书 | 核心光学设计指标、FPGA高速图像时空配准算法模型、整机功耗与芯片选型 | +| **V1.0** | 工程拆解与商业锁定 | `cdo_quote` | CDO商业报价单与工时测算清单 | CDO行业定价模型、全阶段WBS研发工时分解表、专用物料与第三方检验规费、商业结算里程碑 | + +--- + +## 四、 详细设计与技术规格 (Technical Specifications) + +### 1. 数据模型扩展 (`web/src/types/workbench.ts`) +```typescript +export interface DeliverableItem { + docId: string; // 唯一标识，如 doc-p172580123-intake + projectId: number; // 绑定归属的项目ID (彻底实现项目级物理/逻辑隔离) + taskKey: string; // 对应任务键: intake, research, feasibility_reg 等 + title: string; // 交付物标题 + stage: StageKey; // 所属成熟度阶段: 'V0.1' | 'V0.5' | 'V1.0' + category: DeliverableCategory; // 'workflow' | 'shared' | 'private' + isFixedWorkflow: boolean; // 是否为受控主线工作流文档 (固定为 true) + isTemplateOnly: boolean; // 是否仅为初始模板副本 (true 表示待智能体填报) + lifecycleState: DocLifecycleState;// 'template' | 'drafting' | 'reviewing' | 'approving' | 'approved' + isClaimed: boolean; // 编制人是否已认领 (模板状态查看不算认领) + author: string; + reviewer: string; + approver: string; + updatedAt: string; + summary?: string; + sourceMessageSnippet?: string; +} +``` + +### 2. 模板工厂模块 (`web/src/engine/templateFactory.ts`) +提供专门的克隆工厂方法： +```typescript +export interface TemplateFactoryParams { + projectId: number; + projectName: string; + deviceType: string; + creatorId: number; + creatorName: string; +} + +export interface TemplateFactoryResult { + deliverables: DeliverableItem[]; + docASTMap: Record; +} + +export function createProjectTemplateDeliverables( + params: TemplateFactoryParams +): TemplateFactoryResult; +``` +- **变量替换规则**： + - `{{project_name}}` $\rightarrow$ `params.projectName` + - `{{device_type}}` $\rightarrow$ `params.deviceType` + - `{{generated_at}}` $\rightarrow$ 当前格式化时间（如 `2026-09-08 20:30`） + - `{{snapshot_id}}` $\rightarrow$ `SNAP-INIT-${params.projectId}` + - 其他如 `{{customer_name}}` 填入默认客户或“待确认”； + - 正文中提示语保留清晰指示：“（待智能体小队结合需求与法规库编制）”。 + +### 3. 项目隔离与交付物过滤规则 (`web/src/App.tsx`) +```typescript +// 1. 严格按激活项目切分交付物 +const currentProjectDeliverables = useMemo(() => { + return deliverables.filter((doc) => doc.projectId === activeSession.projectId); +}, [deliverables, activeSession.projectId]); + +// 2. 结合三层隐私规则过滤最终可见列表 +const visibleDeliverables = useMemo(() => { + return currentProjectDeliverables.filter((doc) => { + if (doc.category === 'workflow' || doc.category === 'shared') return true; + return doc.creatorId === currentUser.id; + }); +}, [currentProjectDeliverables, currentUser.id]); +``` + +### 4. 界面交互与视觉设计 +1. **抽屉面板与 Tab 栏徽标**： + - 处于 `isTemplateOnly: true` 时，显示灰青色边框徽标 `[ 📄 初始模板 ]`，与已生成的 `[ ✍️ 编制中 ]` 形成鲜明视觉区分； + - 附带 Tooltip 提示：“项目预置标准模板，点击可查阅大纲与章节规范，支持提前添加批注”； +2. **大纲与全景块阅读**： + - 点击任一模板，右侧立即渲染该模板的完整块级内容（Markdown $\rightarrow$ Block AST）； + - 大纲树（TOC）完整高亮，三线表、Mermaid 图正常展示； + - 允许用户在右侧批注栏为模板各个块添加“前置指导意见”； +3. **新建项目默认落地**： + - 用户点击「新建项目」并输入名称后，系统不仅创建项目，同时自动将首个文档（`intake` 模板）选为激活文档，右侧立刻呈现该项目专属的《用户初始需求收集表》模板骨架，让用户获得即时的掌控感。 + +### 5. 智能体执行平滑填报机制 +当用户在左侧与参谋小队对话并触发阶段或任务执行（如“开始调研”、“生成可行性报告”）时： +1. 参谋小队完成生成后，根据 `activeSession.projectId` 和 `taskKey` 寻址到现存的模板副本； +2. 将智能体生成的真实内容写入该 `docId` 的缓存中； +3. 更新该交付物属性： + - `isTemplateOnly: false` + - `lifecycleState: 'drafting'` + - `summary`: 更新为智能体提取的真实摘要 + - `updatedAt`: 更新为当前时间 +4. 右侧视图平滑刷新，完成从“模板骨架”到“正式受控草稿”的生命周期升级。 + +--- + +## 五、 测试与质量验证计划 (Testing & Quality Gates) + +根据本仓库《测试报告规范准则》，落地后需进行以下专项验证： +1. **单元测试 (`web/src/engine/templateFactory.test.ts`)**： + - 验证模板克隆工厂是否能完整产生 7 份标准交付物与 7 份有效 AST； + - 验证宏变量替换的准确性，确保无残留的生硬模板语法； + - 验证各文档的 `projectId`、`taskKey`、`stage` 和 `isTemplateOnly` 元数据装配正确； +2. **项目隔离与集成测试 (`web/src/engine/projectTemplateIntegration.test.ts`)**： + - 验证切换不同项目（如 `sess-001` 与新项目）时，交付物集合与文档内容严格隔离； + - 验证智能体填报后 `isTemplateOnly` 标志的平滑翻转； +3. **前端全量回归与端到端实测**： + - 运行 `npm run test` 确保 100% 通过； + - 控制台取样与归档测试报告至 `.doc/test-reports/2026-09-08-project-init-template-cloning-test-report.md`。