shop_helm/docs/05-coding-rules.md

编码规则（Coding Rules）

每次改代码前完整读取。本文件是实现硬约束；产品范围以 02-requirements.md 为准，模块事实以 04-architecture.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. 测试规则

最低自动验证：

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 字段当真实进程状态。
• 绝不静默吞掉导入、恢复或导出中的部分失败。
• 绝不因为任务困难就跳过高风险闸门。