想法 → 本地优先主本体（Prototype → Flutter，含多线对齐）
本 skill 承载「把一个想法转变成单机独立的软件」的落地方法：PRD（逻辑）→ prototype-v2（静态视觉基线，含 mock.js 数据形状）→ 可选 React Web（web/，可运行视觉事实源）→ Flutter 本地优先主本体。核心是让 AI 在把 HTML 原型转成 Flutter 代码时，视觉、逻辑、数据、契约各归其源，不互相迁就，也不在开发中途返工。
定位与适用边界
主交付物：Flutter 本地优先主本体（桌面/移动端）
- 主形态：Flutter 桌面端 / 移动端（Windows、Android、iOS 等）。
- 数据：本地存储（drift / SQLite），本地为唯一事实源；云端同步仅预留
sync_queue。 - 项目现实（2026-08-23 起）：存在三线并行——Go（业务权威实现）、React Web（视觉事实源）、Flutter（本地优先主本体）。本 skill 的交付物始终是 Flutter 主本体，但流程必须服从《多线开发约束》：
- 业务规则的权威实现在 Go（服务端），Flutter 本地副本只读同步，冲突以服务端为准（离线降级行为以 PRD 为准）。
- 视觉以 React/原型定稿；设计 Token 只改
design/tokens.json再生成；API 契约只改server/api/openapi.yaml。 - AI 等能力通过本地调用或直连第三方服务（自带 Key）。
本 skill 不适用于（应拒绝并说明）：
- 无既有原型/契约，从零搭建云服务端架构（SaaS、多端实时同步服务端）的全新任务。
- 需要新建数据库集群、微服务等基础设施的开发任务。
- 未接入本仓库多线约束、自行另起一套命名/枚举/字段体系的任务。
何时使用（触发条件）
- 用户要求「把一个想法做成单机 / 本地优先 / 离线可用的软件或应用」。
- 用户要求「按原型 / 按 PRD 开发 Flutter 页面或功能」。
- 用户要求「对齐原型与 Flutter 代码 / 实现」。
- 用户要求「产出权威源、差异清单、对齐表」。
- 用户要求「定案 / 解决原型与实现之间的冲突或差异」。
- 改动涉及
design/tokens.json、server/api/openapi.yaml、prototype-v2/mock.js等契约单源，或涉及 Go/React/Flutter 三线字段、枚举、术语对齐。 - 场景涉及「视觉照原型、逻辑照 PRD、数据照契约与代码」的开发意图。
核心原则
- 四源分离：视觉照原型（静态基线）与 React（可运行定稿）还原，功能逻辑照 PRD 实现，数据模型照契约与数据库/代码真相，设计 Token 照
design/tokens.json。四者职责分开，不互相迁就。 - 单一事实源：每类信息只由一个权威源负责（见下），冲突时以更高优先级为准。
- 实现真相 / 代码优先：当文档与代码（数据库表、模型类）冲突时，以代码为真相，回改文档；多线下业务规则的权威实现在 Go 服务端，Flutter 本地副本只读同步。
- 契约单源不可手改生成物：设计 Token 只改
design/tokens.json后跑python scripts/gen_tokens.py；API 契约只改server/api/openapi.yaml（Go 用 swaggo 注解对齐，React 客户端生成）；禁止手改web/src/styles/tokens.css与 Flutter Token。 - 原型 ≠ 功能：原型是视觉/交互基线，不一定是功能/数据源；
mock.js是数据形状参照（原型展示态），正式链路字段形状以契约与代码为准（例：meanings数组 vs 单字符串meaning_zh，见《权威源与差异清单》§2.2）。 - 本地优先：数据、计算、调度都在本地客户端完成；无后端时用本地数据库 + 本地算法（如 FSRS 自研引擎）+ 抽象接口承载能力。
- 多线一致：字段 / 枚举 / 术语三线统一，禁止各线自造；改一处必须三处同步并更新《多线开发约束》对齐表与术语表。
权威源判定规则
| 职责 | 权威源 | 冲突时 |
|---|---|---|
| 需求 / 功能逻辑 | PRD 文档（主 PRD + AI 专项 PRD） | — |
| 静态视觉基线 | prototype-v2/（含 mock.js 数据形状；prototype-clean/ 为其派生交付态，不得独立改动） |
视觉以可控原型为准 |
| 可运行视觉事实源 | web/（React 19 + TS + RTK Query，走 Go API） |
交互先在此定稿，Flutter 对齐 |
| 设计 Token | design/tokens.json（生成物 web/src/styles/tokens.css 与 Flutter Token 禁止手改） |
以 json 为准 |
| API 契约 | server/api/openapi.yaml |
以 yaml 为准 |
| 数据模型 / 表结构 | dev-doc.html + drift 代码 + server/internal/repository/db/schema.sql + openapi schema，四者字段级一致 |
以交叉校验结果为准，文档回改 |
| 页面路由 / 组件 | page-guide.html + 《多线开发约束》模块/路由/端点对齐表 |
— |
| 多线对齐约束 | .trae/documents/多线开发约束.md |
三线冲突以该文档与 openapi.yaml 为准 |
| 工程规范 / 技术约束 | 开发约束与工程规范.html + readai.md |
— |
多线工作流（Go / React / Flutter）
| 线 | 技术栈 | 角色 | 业务事实源 |
|---|---|---|---|
| 线1 Go | Gin + sqlc + SQLite | 后端 API 服务，业务逻辑权威实现 | server/api/openapi.yaml（契约）+ schema.sql（数据） |
| 线2 React | Vite + React 19 + TS + Redux Toolkit | 视觉事实源，交互先在此定稿 | 消费线1 API |
| 线3 Flutter | 多包工作区（melos + drift） | 本 skill 主交付物，本地优先主本体 | drift/SQLite 本地库 + 同一契约 |
数据流约定：React 只读业务数据一律经 Go API；Flutter 本地优先（drift 为本地事实源），云端同步走 sync_queue（本阶段不实现）。
三线变更同步顺序（改契约时强制执行）：
- 改
server/api/openapi.yaml（契约单源）。 - 同步改 Go：
schema.sql/queries.sql→sqlc generate；handler/service/repository 对齐，swaggo 注解更新。 - 生成 React 客户端（orval/openapi-generator），更新
web/页面与路由。 - 对齐 Flutter：drift 表（
melos gen）、模型字段（camelCase ↔ snake_case 映射）、页面与路由。 - 跑校验：
python scripts/check_schema_consistency.py（扩展后含 sqlc schema）+go build ./...（server/）+npm run typecheck（web/）+melos analyze。 - 字段/枚举/术语变更需同步更新《多线开发约束》§2.2 术语表 / §2.3 字段映射 / §2.4 值枚举对齐表。
流程五步
- 定权威源：确认每类信息的单一事实源（含契约单源：tokens.json / openapi.yaml / mock.js 是否涉改），并给出「降级 / 去重建议」（识别旧版、重复文档，避免双源）。
- 产差异清单：交叉比对 PRD ↔ prototype-v2（mock.js）↔ drift 代码 ↔
schema.sql↔ openapi schema ↔seed_words.json，列出冲突与缺口，分五类：
- 导航差异（桌面/移动入口项是否一致）
- 数据模型差异（字段有无、字段形状、枚举码）
- 设置项差异（PRD 有原型无、原型有 PRD 无、选项集不一致）
- 页面/模块覆盖差异（PRD 有原型无、语义不一致）
- 场景/选项覆盖差异 - 逐条定案：对阻塞开发的硬冲突逐条给出决策（参考《权威源与差异清单》§三拍板优先级），记录「定案结论 + 落地动作」。判断原则：
- 多源一致者优先；不一致时以高优先级源为准并回改低优先级源。
- 字段缺失 → 补字段；形状不一致 → 定映射规则；语义冲突 → 明确归属。
- 能不改代码的（如已自洽）只确认规则，不空改。
- 定案需三线同步：涉及契约/字段/枚举的结论必须落到 Go、React、Flutter 三侧。 - 落地代码：按定案改代码（表结构 / 映射 / seeder / 常量 / 契约）。生成物闭环：
- 改design/tokens.json→python scripts/gen_tokens.py（重新生成 tokens.css）
- 改 sqlc schema/queries →sqlc generate（server/ 下）
- 改 drift 表 →melos gen（build_runner --force-jit 已内置）
- 改 openapi.yaml → 生成 React 客户端 + 对齐 Flutter 模型
- 改动导航/路由常量后必须验证目标路由已注册，避免导航崩溃。 - 同步文档：把定案结果回写到《权威源与差异清单》标记「已定案」；同步更新《多线开发约束》对齐表 / 术语表 / 枚举表与相关实施计划文档。
落地注意
- 改动数据库表结构后，必须重新生成代码（drift 的
melos gen/ sqlc 的sqlc generate）并确认生成成功。 - 多包工作区（workspace / melos）的包目录不可随意移动；文档归入英文目录，规避构建工具对中文路径的兼容问题。
- 契约校验脚本：
check_schema_consistency.py（drift ↔seed_words.json↔mock.js，扩展后纳入 sqlc schema）、check_token_consistency.py（待建，tokens.json ↔ tokens.css ↔ Flutter Token）；两者接入 CI（melos lint:ui同层级）。 - 值枚举对齐（写死，禁止分叉）：卡片状态
new/learning/review/relearning/mastered、评分again/hard/good/easy、词形/关系rel_type、口音en-US/en-GB、TTS 引擎system/edge/cloud等，见《多线开发约束》§2.4。 - 字段命名映射：API / DB / JSON 一律 snake_case（
word_id、meaning_zh）；Go 结构体 PascalCase + JSON tag snake_case；Dart camelCase（wordId），与 JSON 映射时按 snake_case 转换。三端同一字段禁止改名。 - API 规范：统一响应
Result{code,message,data}；查询接口一律分页limit（默认 20）/offset（默认 0）；错误码段 0 成功 / 4xx 业务错误 / 500 服务错误；时间统一 ISO 8601。 - 核心数据操作尽量用 try-catch 包裹；查询优先分页；优先构造器注入；组件按需注入（Riverpod Provider 懒加载）。
- Flutter UI 样式一律走 skill
flutter-ui-style（AppPalette / AppSpacing / AppRadius / AppMotion / AppShadow，禁魔法值），从原型 CSS 迁移视觉到 Flutter 时做布局语义映射（Row/Column/Wrap ↔ flex/grid），不照抄 CSS。
