cmbone/docs/00-ai-start-here.md

AI 开发入口

给 AI coding agent 的项目入口。硬性编码规则见 05-coding-rules.md。

一句话定位

cmbone 是一个 Windows-first、可扩展到其他平台的 Wails v3 + Vue 3 + SQLite 可复用桌面应用模板。

模板目标不是做空泛框架，而是沉淀桌面端常用模块：应用壳、设置、登录、主业务模块、操作日志、数据统计和常用业务组件。第一批业务样例使用“电商商品图片 AI 优化”来验证模板是否能支撑真实业务闭环。

必读顺序

每次开始写代码前，按这个顺序建立上下文：

1. 01-vision.md：为什么做、为谁做、什么不做。
2. 02-requirements.md：模板 MVP 要什么、怎么算达成。
3. 03-tech-stack.md：既定技术选型。
4. 04-architecture.md：系统结构、职责划分、数据模型和关键难点。
5. 05-coding-rules.md：写代码前必须遵守的规则。
6. 06-tasks.md：领取本轮唯一任务。
7. ../progress.md：历史执行记录、验证结果、阻塞点和关键决策。
8. current-state.md：当前代码现实、可运行命令、下一步任务。

仓库根目录的 AGENTS.md 和 CLAUDE.md 是仓库级规则，优先级高于本目录中的建议。

固定开工流程

1. pwd：确认在 D:\chengma\cmbone 或对应克隆目录。
2. 读 ../progress.md 和 current-state.md：恢复已验证状态、下一步和当前 blocker。
3. git log --oneline -5：看清最近发生了什么。
4. 运行 .\init.ps1，Git Bash / WSL 用 ./init.sh。
5. 如果基线失败，先修基线，不在坏的起点上叠新功能。
6. 基线绿了，再从 06-tasks.md 领取唯一任务。

当前阶段

当前项目处于：可复用桌面应用模板的 Phase 1 基础模块建设阶段。

优先路径：

1. Phase 0：保持迁移后的 Wails/Vue/SQLite 基线可运行、可测试、可构建。
2. Phase 1：建立 Windows-first 的应用壳、主布局、设置和登录边界。
3. Phase 2：实现商品图片 AI 优化样例、审计日志、运行日志和数据统计。
4. Phase 3：补齐组件示例、测试、打包和交接文档。

领取任务规则

• 只领取第一个状态为 TODO 且依赖均为 DONE 的任务。
• 开始前把该任务状态改为 DOING。
• 本轮只完成这一个任务。
• 验收通过后把状态改为 DONE。
• 完成后把执行记录追加到 ../progress.md，并覆盖更新 current-state.md 的当前快照。
• 结束会话前过一遍 clean-state-checklist.md。

模板 MVP 边界

MVP 只做：

• 应用壳：主窗口、侧边导航、顶部用户区、内容区，Windows 10+ 优先。
• 窗口策略：主窗口默认不最大化，初始 1280x800，居中且可调整大小；第二窗口保持小窗。
• 登录：本地固定账号 provider 和真实后端 provider 的可替换边界。
• 设置：主题、语言、窗口行为、快捷键、数据目录和日志策略。
• 主业务样例：电商商品图片 AI 优化的任务列表、状态、结果和失败反馈。
• 操作日志：审计日志用于记录用户动作，运行日志用于排错。
• 数据统计：今日处理图片数、AI 优化成功率、平均耗时、失败任务数、今日操作日志数、最近 7 天处理趋势。
• 常用组件示例：输入框、多选框、下拉框、多行文本、表格、筛选和分页。

MVP 不做：

• 完整权限系统、角色系统或企业 SSO。
• 完整 macOS / Linux 体验承诺；当前是 Windows-first，其他平台保持结构可扩展。
• 自研 UI 组件库；优先复用 Ant Design Vue。
• 复杂 BI 报表、自动更新和插件市场。
• 未确认接口前的真实 AI 服务深度集成。

常见任务该看哪里

做页面 / UI：先看 02-requirements.md、routes.md，再看现有 Vue 组件。

做后端服务：先看 api.md、04-architecture.md，再看 internal/services/。

做登录：先看 04-architecture.md 的 AuthProvider 边界，不把账号密码写死在前端。

做日志：区分审计日志和运行日志，先看 04-architecture.md 的数据模型。

做统计：只围绕 MVP 指标，不提前做复杂报表平台。

做运行 / 打包：先看 03-tech-stack.md 和 current-state.md。

验证命令

.\init.ps1

等价拆分命令：

go test ./...
cd frontend
npm run build
cd ..
go build -o bin\cmbone.exe .