134 lines
4.9 KiB
Markdown
134 lines
4.9 KiB
Markdown
## 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`
|
||
- 下载快照是统一提交进仓库，还是仅作为本地辅助资产
|
||
- 首批试点是否只选一个页面，还是并行推进多个低风险面板
|