cmbone/docs/05-coding-rules.md

编码规则

每次写代码前先读完本文件。与技术细节冲突时，以 03-tech-stack.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 组件保持小而直接，不为未来需求提前抽象。
• 审计日志记录用户动作，运行日志记录系统错误，两类日志不要混用。
• 数据统计只做任务要求的指标，不提前做复杂报表平台。

验证要求

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

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

推荐直接运行：

.\init.ps1

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

绝不

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