177 lines
9.9 KiB
Markdown
177 lines
9.9 KiB
Markdown
# 编码规则（Coding Rules）
|
||
|
||
> 每次改代码前完整读取。本文件是实现硬约束；产品范围以 [`02-requirements.md`](02-requirements.md) 为准，模块事实以 [`04-architecture.md`](04-architecture.md) 和 [`api.md`](api.md) 为准。
|
||
|
||
## 0. 黄金法则
|
||
|
||
1. **不臆造**：字段、平台规则、路径、依赖和接口必须查仓库事实。
|
||
2. **一次一事**：只实现当前 `DOING` 任务，不夹带 Backlog 和无关重构。
|
||
3. **依赖向内**：UI 和基础设施依赖 application/domain，domain 不依赖框架。
|
||
4. **先验证风险**：Gio 组件、Chrome profile 和图片合成闸门未通过前，不大规模铺业务页面。
|
||
5. **副作用可控**：进程、文件、数据库、剪贴板和恢复操作必须可观察、可失败、可追踪。
|
||
6. **完成有证据**：没有测试、构建和任务要求的 smoke，不得标记 `DONE`。
|
||
|
||
## 1. 动手前
|
||
|
||
- 按 `vision -> requirements -> tech-stack -> architecture -> api/routes -> tasks -> current-state` 建立上下文。
|
||
- 找到任务对应的需求 ID、服务合约和页面。
|
||
- 检查是否已有可复用 package、component、repository 和测试夹具。
|
||
- 运行标准基线并记录当前失败；基线坏时先处理基线。
|
||
- 查看工作区已有改动，保留不属于本任务的用户修改。
|
||
- 若任务会改变第三方平台数据、删除用户文件、保存秘密或扩大自动化范围，先停止并要求产品决策。
|
||
|
||
## 2. Go 规则
|
||
|
||
- package 名短小、全小写、单数优先，不使用 `utils`、`common`、`helpers` 作为无边界杂物包。
|
||
- 公开标识符只在跨包合约需要时导出；先使用小接口，接口由消费者定义。
|
||
- 所有 I/O 方法接收 `context.Context`，不把 context 存在 struct 中。
|
||
- 错误必须包装上下文并保留 `errors.Is/As` 可判定性，不比较底层错误字符串。
|
||
- 不使用 `panic` 处理可预期业务错误；启动期不可恢复错误可以返回到 `main` 后记录并退出。
|
||
- 不忽略返回值，不用空 `recover`，不在 library code 中 `os.Exit`。
|
||
- 时间通过注入的 Clock 获取，测试不依赖真实等待。
|
||
- 金额不用 `float64` 持久化；用最小货币单位整数，比例/汇率用可精确解析表示。
|
||
- 路径用 `filepath`，URL 用 `net/url`，CSV/XLSX 用结构化解析器，不手工拆字符串。
|
||
- 代码必须通过 `gofmt`；注释解释边界和原因，不复述代码。
|
||
|
||
## 3. 分层规则
|
||
|
||
- `internal/domain`：纯规则、实体和值对象，不导入 Gio、driver、Windows API。
|
||
- `internal/application`：用例编排和稳定错误码，不写 SQL、不布局 UI。
|
||
- `internal/infrastructure/sqlite`：repository 和 migration，不出现 UI 文案。
|
||
- `internal/platform`：进程、路径、剪贴板和文件副作用，不决定业务优先级。
|
||
- `internal/ui`：页面状态和展示，不直接打开数据库或启动进程。
|
||
- 不通过全局变量跨层共享数据库、页面状态或 process registry。
|
||
- 新增跨层调用前先更新 `api.md`；不得为绕过接口而从 UI 直接引用 concrete repository。
|
||
|
||
## 4. Gio 规则
|
||
|
||
- widget、clickable、editor、list、drag 和页面状态必须跨 frame 持久存在。
|
||
- layout 函数不得执行 SQL、文件读写、大图解码、网络请求、`Process.Wait` 或阻塞 channel receive。
|
||
- 用户动作只提交 intent；异步结果通过 event channel 返回并调用 window invalidate。
|
||
- 每个异步操作有 busy、success、error 和必要的 cancel 状态。
|
||
- 同一按钮请求进行中防重复提交。
|
||
- 页面切换保留列表筛选和滚动状态；销毁页面时取消所属 context。
|
||
- 固定画布、表格、工具栏和图标按钮设置稳定约束，动态文字不得挤压相邻控件。
|
||
- 关键状态不能只用颜色；图标按钮必须有 tooltip/可访问名称。
|
||
- 项目内组件只在存在真实复用时抽取，不创建通用 UI DSL。
|
||
- UI 自动测试不稳定时可以保留手工 smoke，但 domain/application 行为必须有自动测试。
|
||
|
||
## 5. SQLite 规则
|
||
|
||
- schema 只通过按序 migration 变化，已经提交或发布的 migration 不修改。
|
||
- 每个连接启用外键和 busy timeout。
|
||
- 多表写入、导入提交和计数更新使用事务。
|
||
- repository 查询显式列名，不使用 `SELECT *`。
|
||
- nullable 数据使用明确类型，不用魔法空字符串混淆“未填写”和有效值，除非 schema 已定义为空字符串语义。
|
||
- 列表查询有稳定排序、分页边界和必要索引。
|
||
- 唯一约束、外键约束和 busy 错误映射到稳定应用错误码。
|
||
- 测试使用临时目录的真实 SQLite，不共享开发数据库。
|
||
- 不把密码、Cookie、token、代理秘密或图片二进制写进数据库。
|
||
- 备份恢复前后执行完整性检查；失败必须保留可回滚旧库。
|
||
|
||
## 6. Chrome 与进程规则
|
||
|
||
- 只能用 `exec.CommandContext` 或经审查的等价 API 和独立参数启动，不使用 `cmd /c`、PowerShell 字符串或 shell 拼接。
|
||
- Chrome executable、profile 目录和目标 URL 分别校验。
|
||
- profile 必须是绝对规范路径；managed path 必须位于配置根目录内。
|
||
- 不使用默认用户 Chrome profile 作为 ShopHelm managed profile。
|
||
- 同一 profile 占用时返回 `profile_in_use`，不尝试强制解锁或删除 lock 文件。
|
||
- 不在命令行传密码、Cookie 或代理认证信息。
|
||
- 不默认加 `--remote-debugging-port`、规避检测或安全降级参数。
|
||
- 进程退出必须释放 registry；应用重启后不得相信陈旧 PID。
|
||
- 应用退出默认不杀用户打开的 Chrome；需要关闭能力时必须单独立项和确认。
|
||
- 测试参数生成时用 fake runner，真实 Chrome smoke 只能使用测试 profile 和非生产账号。
|
||
|
||
## 7. 文件、导入和图片规则
|
||
|
||
- 任何用户路径先做存在性、文件类型、权限和规范化检查。
|
||
- 读取外部文件不修改源文件。
|
||
- 写入先落同目录临时文件，成功 close/sync 后原子改名。
|
||
- 默认 `overwrite=false`；即使允许覆盖，也绝不能覆盖底图或叠加图。
|
||
- 图片解码设置尺寸和内存上限，防止异常大文件耗尽内存。
|
||
- 预览和导出共用 `CompositionPlanner`，不得复制位置/缩放公式。
|
||
- Gio framebuffer 截图不能作为正式图片输出。
|
||
- PNG alpha 和 JPG 背景有固定测试。
|
||
- CSV/XLSX 先 preview 后 commit；文件 fingerprint 改变时拒绝提交。
|
||
- 导入错误包含行号、字段和原因；不静默修复未知值。
|
||
- 删除数据库素材关联默认不删除物理文件。
|
||
|
||
## 8. 安全、隐私与合规
|
||
|
||
- 真实账号、密码、token、Cookie、买家隐私、私有 URL 不进入代码、文档、日志、截图或测试数据。
|
||
- 账号标识只用于人类识别；日志中仍应最小化或脱敏。
|
||
- 不实现绕验证码、绕风控、反指纹、刷单、刷评、批量抓取和未经确认的批量消息。
|
||
- 不把 `user-data-dir` 描述成防关联功能。
|
||
- 平台规则变化必须以官方来源为准，记录链接、访问日期和影响。
|
||
- 未来自动化默认具备 dry-run、明确预览、人工确认、速率边界、审计和取消。
|
||
- 操作日志记录 action、entity、result、error code，不记录完整话术、买家详情或命令秘密。
|
||
|
||
## 9. 依赖规则
|
||
|
||
- 新依赖前检查标准库和已引入依赖能否满足。
|
||
- 在 `03-tech-stack.md` 记录用途、版本策略和引入任务。
|
||
- 运行 `go mod tidy` 后审查直接和间接依赖变化。
|
||
- 不引入 ORM、Web 框架、嵌入浏览器、依赖注入框架或第二套图片库，除非新任务明确批准。
|
||
- `gioui.org/x/component` 只有 T-101 通过后才允许保留。
|
||
- 依赖升级单独提交，不与业务功能混在同一任务。
|
||
|
||
## 10. 测试规则
|
||
|
||
最低自动验证：
|
||
|
||
```powershell
|
||
go test ./...
|
||
go vet ./...
|
||
go build -o build/shophelm.exe ./cmd/shophelm
|
||
```
|
||
|
||
按改动增加：
|
||
|
||
- 并发和共享状态：`go test -race ./...`，若目标工具链不支持则记录真实原因。
|
||
- migration/repository：临时数据库从空库迁移，运行 CRUD、约束和重开测试。
|
||
- Chrome：参数单测、fake process 生命周期、Windows 真实 Chrome smoke。
|
||
- 图片：固定夹具 pixel/golden 测试、原图校验和、格式和失败清理。
|
||
- 导入：CSV/XLSX round-trip、错误行、fingerprint 和事务测试。
|
||
- 备份：完整性、恢复成功、损坏备份、替换失败回滚测试。
|
||
- Gio：对应页面手工 smoke，记录窗口尺寸、动作和观察结果。
|
||
|
||
测试禁止：
|
||
|
||
- 为绿灯删除断言、降低验收或跳过失败用例。
|
||
- 使用真实用户数据库、真实 Chrome profile 或真实店铺凭证。
|
||
- 依赖测试执行顺序或固定本机绝对路径。
|
||
|
||
## 11. 文档与提交
|
||
|
||
- 需求变化先改 `02-requirements.md`，再改代码。
|
||
- schema 或 service 合约变化同步 `04-architecture.md` 和 `api.md`。
|
||
- 页面变化同步 `routes.md`。
|
||
- 版本、依赖和命令变化同步 `03-tech-stack.md`、`00-ai-start-here.md`、`current-state.md` 和 `init.*`。
|
||
- 每轮实际命令和结果只追加到 `progress.md`。
|
||
- 提交只包含当前任务相关文件；不重写或撤销用户无关改动。
|
||
- 提交信息建议：`T-XXX: imperative summary`。
|
||
|
||
## 12. 完成定义
|
||
|
||
任务标记 `DONE` 前逐项确认：
|
||
|
||
- [ ] 需求 ID 和任务验收全部满足。
|
||
- [ ] 代码遵守模块和副作用边界。
|
||
- [ ] 自动测试、vet、build 通过。
|
||
- [ ] 任务要求的手工 smoke 已执行并记录环境。
|
||
- [ ] 没有真实秘密、隐私或生产路径进入变更。
|
||
- [ ] 没有无关重构或 Backlog 功能。
|
||
- [ ] 相关文档、任务状态和 current state 已同步。
|
||
- [ ] `progress.md` 有真实验证证据。
|
||
- [ ] `clean-state-checklist.md` 已通过。
|
||
|
||
## 13. 绝不
|
||
|
||
- 绝不明文保存密码。
|
||
- 绝不删除或强制解锁 Chrome profile。
|
||
- 绝不覆盖原始图片作为默认行为。
|
||
- 绝不在 Gio frame 中等待 I/O。
|
||
- 绝不把数据库 `running` 字段当真实进程状态。
|
||
- 绝不静默吞掉导入、恢复或导出中的部分失败。
|
||
- 绝不因为任务困难就跳过高风险闸门。
|