cmbone/docs/05-coding-rules.md

# 编码规则

> 每次写代码前先读完本文件。与技术细节冲突时，以 [`03-tech-stack.md`](03-tech-stack.md) 和 [`04-architecture.md`](04-architecture.md) 为准。

## 黄金法则

1. 不臆造：字段、接口、依赖和文件必须来自当前代码或文档。
2. 守范围：只做当前任务，不顺手加后续功能。
3. 照架构：使用既有 Wails、Vue、SQLite、平台模块边界。
4. 小步改：一次解决一个问题，不夹带无关重构。
5. 可验证：完成前必须测试或构建通过。

## 动手前

- 先读 `AGENTS.md`、`00-ai-start-here.md`、`current-state.md` 和当前任务。
- 查找现有函数、组件、工具和测试，复用优先。
- 需求不清或会影响架构时，先说明问题再决定。
- 不确定 Wails API 时，优先看本项目现有代码和已锁版本，不直接按最新文档改。

## 代码规范

- Go 代码用 `gofmt`。
- TypeScript / Vue 保持当前项目风格。
- 错误必须返回或展示，不静默吞掉。
- 后端服务方法签名变化必须同步前端 bindings。
- 前端 UI 文案走现有 i18n 体系，避免新增硬编码中文/英文。
- 新依赖必须说明必要性；能用标准库或现有依赖解决时不新增。
- 登录、AI、日志和统计能力必须经过 service / provider 边界，不写死在页面组件里。
- 常用输入框、多选框、下拉框、多行文本、表格等优先使用 Ant Design Vue，不自研基础控件。

## 模块规则

- `main.go` 不写业务逻辑。
- SQLite 读写集中在 store 或明确服务层，不散落到多个模块。
- 平台差异放在 `platform/`。
- 前端 bindings 不承载业务逻辑。
- 通用 UI 组件保持小而直接，不为未来需求提前抽象。
- 审计日志记录用户动作，运行日志记录系统错误，两类日志不要混用。
- 数据统计只做任务要求的指标，不提前做复杂报表平台。

## 验证要求

代码改动完成前至少运行相关命令：

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

推荐直接运行：

```powershell
.\init.ps1
```

验证失败时，不要标记任务完成。无法运行时，必须在回复和 `progress.md` 里写清原因。

## 绝不

- 不提交密钥、token、密码、本地数据库或用户配置。
- 不提交 `node_modules`、`frontend/dist`、`bin`。
- 不用删除测试、降低断言的方式制造通过。
- 不擅自 reset、checkout 或删除用户未要求删除的文件。
- 不把依赖升级和功能改动混在同一个任务里。