docs(spec): add project init template cloning design spec

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-08 20:28:54 +08:00
parent 50f95c61ed
commit 23cf8c3a1e
1 changed files with 181 additions and 0 deletions
@@ -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<string, DocumentAST>;
+}
+
+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`。