Initial TrueGrowth source import

2026-07-07 09:36:36 +08:00
commit 3b6781d695
2283 changed files with 691996 additions and 0 deletions
--- a/openspec/changes/add-stitch-design-workflow/design.md
+++ b/openspec/changes/add-stitch-design-workflow/design.md
@@ -0,0 +1,133 @@
+## Context
+
+`opentu` 当前的前端结构以编辑器能力为中心，`apps/web/src/app/app.tsx` 负责应用初始化、工作区恢复、URL 状态、崩溃恢复、安全模式等应用级装配；`packages/drawnix/src/drawnix.tsx` 承担核心白板编辑器、工具栏、抽屉、AI 面板、媒体库、项目切换等大量交互能力。
+
+这意味着并不是所有 UI 都适合先进入 Stitch：
+
+- 编辑器核心区域高度依赖本地状态与插件链
+- 外围页面和面板则更接近典型的“信息架构 + 视觉布局”问题，适合由 Stitch 提供方案探索
+
+如果不先定义边界，Stitch 很容易被误用为“直接产出生产代码”的工具，导致设计稿与业务实现失去可维护性。
+
+## Goals / Non-Goals
+
+- Goals:
+  - 为 `opentu` 建立一条可重复使用的 Stitch 设计闭环
+  - 让仓库内持久化保存设计系统上下文与 screen 映射
+  - 优先提升外围页面、抽屉、弹窗、空状态页的设计探索效率
+  - 保持代码实现为交互逻辑与生产行为的唯一真源
+- Non-Goals:
+  - 本次不让 Stitch 直接接管核心白板编辑器 UI
+  - 本次不把 Stitch 生成的 HTML 直接作为生产代码运行
+  - 本次不要求一次性覆盖所有前端页面
+
+## Decisions
+
+- Decision: Stitch 只主导“受边界约束的页面与面板”
+
+  - 优先覆盖弹窗、设置面板、项目抽屉、媒体库、空状态页
+  - 不直接覆盖核心画布、框选、拖拽、缩放、插件联动区域
+
+- Decision: 仓库内必须保存 Stitch 设计资产的映射关系
+
+  - 通过 `.stitch/screens.json` 记录 `surfaceId -> projectId -> screenId`
+  - 通过 `.stitch/DESIGN.md` 沉淀视觉系统、品牌语言与 prompt 约束
+  - 避免 Stitch screen 只存在于外部系统、无法被后续开发和维护复用
+
+- Decision: 设计结果进入代码前必须经过“结构转译”
+
+  - Stitch screen 的 HTML 与 screenshot 只作为视觉参考和结构蓝本
+  - 最终组件仍按 React + 现有工程模式手工实现
+  - 所有状态、事件、服务调用、数据依赖继续留在本地代码
+
+- Decision: 首批只跑通一个最小闭环，再逐步扩展
+
+  - 先选低风险单元，如 `CrashRecoveryDialog`
+  - 跑通完整流程后，再扩展到项目抽屉、设置面板、媒体库等
+
+## Proposed Repository Artifacts
+
+```txt
+.stitch/
+  DESIGN.md
+  screens.json
+  prompts/
+    crash-recovery-dialog.md
+    project-drawer.md
+    settings-panel.md
+  downloads/
+    <surface-id>/
+      screen.json
+      screenshot.png
+      design.html
+```
+
+### Artifact Roles
+
+- `DESIGN.md`
+  - 项目级视觉系统说明
+  - 颜色、字体、圆角、阴影、语气、信息密度等约束
+  - 作为 Stitch prompt 的上下文来源
+
+- `screens.json`
+  - 每个 surface 的唯一映射
+  - 示例：
+
+```json
+{
+  "crash-recovery-dialog": {
+    "projectId": "17192920079115887108",
+    "screenId": "49b0b7c5283f462d8fafd181b7cbaf5b",
+    "entry": "apps/web/src/app/CrashRecoveryDialog.tsx"
+  }
+}
+```
+
+- `prompts/*`
+  - 记录每个页面/模块送入 Stitch 的 prompt
+  - 保证后续编辑与再生成时上下文可追溯
+
+- `downloads/*`
+  - 保存从 MCP 拉回的 HTML / screenshot / metadata 快照
+  - 作为编码阶段的参考输入
+
+## Workflow
+
+1. 选择一个受边界约束的页面/模块
+2. 在 `.stitch/prompts/` 中整理 prompt，并结合 `.stitch/DESIGN.md`
+3. 使用 Stitch 生成或编辑 screen
+4. 将 `projectId` / `screenId` 固化到 `.stitch/screens.json`
+5. 通过 Stitch MCP 拉取 `get_screen`、设计系统与截图
+6. 按仓库规范将结果实现为 React 组件
+7. 完成后回写下载快照与必要的设计说明
+
+## Initial Candidate Surfaces
+
+- `apps/web/src/app/CrashRecoveryDialog.tsx`
+  - 优势：边界清晰、交互简单、适合先跑闭环
+- `packages/drawnix/src/components/project-drawer/*`
+  - 优势：信息层级明确，适合 Stitch 做布局与信息架构
+- `packages/drawnix/src/components/settings-dialog/*`
+  - 优势：表单和分组较多，适合先做视觉系统统一
+- `packages/drawnix/src/components/media-library/*`
+  - 优势：典型内容浏览 UI，适合做卡片、筛选、空状态设计
+
+## Risks / Trade-offs
+
+- 风险: 团队把 Stitch 结果误当成最终代码
+  - Mitigation: 在 spec 中明确“结构参考，不是生产代码”
+
+- 风险: screen 映射与代码实现脱节
+  - Mitigation: 每个 surface 必须在 `.stitch/screens.json` 中绑定入口文件
+
+- 风险: 过早接入复杂编辑器区域，增加返工成本
+  - Mitigation: 首批只选低风险外围页面
+
+- 风险: 外部 Stitch 项目变动无法追溯
+  - Mitigation: 在仓库中保存 prompt、screen 映射和下载快照
+
+## Open Questions
+
+- `.stitch/screens.json` 是否需要加入 `status` 字段，如 `concept / approved / implemented`
+- 下载快照是统一提交进仓库，还是仅作为本地辅助资产
+- 首批试点是否只选一个页面，还是并行推进多个低风险面板