105 lines
4.8 KiB
Markdown
105 lines
4.8 KiB
Markdown
# AI 开发入口
|
||
|
||
> 给 AI coding agent 的项目入口。硬性编码规则见 [`05-coding-rules.md`](05-coding-rules.md)。
|
||
|
||
## 一句话定位
|
||
|
||
`cmbone` 是一个 Windows-first、可扩展到其他平台的 Wails v3 + Vue 3 + SQLite 可复用桌面应用模板。
|
||
|
||
模板目标不是做空泛框架，而是沉淀桌面端常用模块：应用壳、设置、登录、主业务模块、操作日志、数据统计和常用业务组件。第一批业务样例使用“电商商品图片 AI 优化”来验证模板是否能支撑真实业务闭环。
|
||
|
||
## 必读顺序
|
||
|
||
每次开始写代码前，按这个顺序建立上下文：
|
||
|
||
1. [`01-vision.md`](01-vision.md)：为什么做、为谁做、什么不做。
|
||
2. [`02-requirements.md`](02-requirements.md)：模板 MVP 要什么、怎么算达成。
|
||
3. [`03-tech-stack.md`](03-tech-stack.md)：既定技术选型。
|
||
4. [`04-architecture.md`](04-architecture.md)：系统结构、职责划分、数据模型和关键难点。
|
||
5. [`05-coding-rules.md`](05-coding-rules.md)：写代码前必须遵守的规则。
|
||
6. [`06-tasks.md`](06-tasks.md)：领取本轮唯一任务。
|
||
7. [`../progress.md`](../progress.md)：历史执行记录、验证结果、阻塞点和关键决策。
|
||
8. [`current-state.md`](current-state.md)：当前代码现实、可运行命令、下一步任务。
|
||
|
||
仓库根目录的 `AGENTS.md` 和 `CLAUDE.md` 是仓库级规则，优先级高于本目录中的建议。
|
||
|
||
## 固定开工流程
|
||
|
||
1. `pwd`：确认在 `D:\chengma\cmbone` 或对应克隆目录。
|
||
2. 读 [`../progress.md`](../progress.md) 和 [`current-state.md`](current-state.md)：恢复已验证状态、下一步和当前 blocker。
|
||
3. `git log --oneline -5`：看清最近发生了什么。
|
||
4. 运行 `.\init.ps1`，Git Bash / WSL 用 `./init.sh`。
|
||
5. 如果基线失败，先修基线，不在坏的起点上叠新功能。
|
||
6. 基线绿了，再从 [`06-tasks.md`](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`](../progress.md)，并覆盖更新 [`current-state.md`](current-state.md) 的当前快照。
|
||
- 结束会话前过一遍 [`clean-state-checklist.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`](02-requirements.md)、[`routes.md`](routes.md)，再看现有 Vue 组件。
|
||
|
||
做后端服务：先看 [`api.md`](api.md)、[`04-architecture.md`](04-architecture.md)，再看 `internal/services/`。
|
||
|
||
做登录：先看 [`04-architecture.md`](04-architecture.md) 的 AuthProvider 边界，不把账号密码写死在前端。
|
||
|
||
做日志：区分审计日志和运行日志，先看 [`04-architecture.md`](04-architecture.md) 的数据模型。
|
||
|
||
做统计：只围绕 MVP 指标，不提前做复杂报表平台。
|
||
|
||
做运行 / 打包：先看 [`03-tech-stack.md`](03-tech-stack.md) 和 [`current-state.md`](current-state.md)。
|
||
|
||
## 验证命令
|
||
|
||
```powershell
|
||
.\init.ps1
|
||
```
|
||
|
||
等价拆分命令：
|
||
|
||
```powershell
|
||
go test ./...
|
||
cd frontend
|
||
npm run build
|
||
cd ..
|
||
go build -o bin\cmbone.exe .
|
||
```
|