91 lines
7.2 KiB
Markdown
91 lines
7.2 KiB
Markdown
# 编码规则(Coding Rules)
|
|
|
|
> 每次写代码前先读完本文件。这是让 AI 不跑偏、代码质量稳定的硬约束。
|
|
> 与技术细节冲突时,以 [技术栈](03-tech-stack.md) / [架构设计](04-architecture.md) 的事实为准;与"该不该做"冲突时,以 [需求](02-requirements.md) 为准;协议字段以 [api.md](api.md) 为准。
|
|
|
|
## 0. 黄金法则
|
|
|
|
1. **不臆造**:数据字段、文件、接口、依赖,不确定就查证或询问。
|
|
2. **守范围**:只做当前任务要求的事,不顺手加后续功能。
|
|
3. **照架构**:使用既定技术栈和模块边界,不擅自引入新框架。
|
|
4. **小步改**:一次只解决一个问题,不夹带无关重构。
|
|
5. **可验证**:改完必须能构建、能测试、对得上验收标准。
|
|
|
|
## 1. 动手前
|
|
|
|
- 按链路确认:`vision` → `requirements` → `tech-stack` → `architecture` → `tasks`。
|
|
- 找到本任务对应的验收标准,写之前就知道"怎么算做对"。
|
|
- 先找现有函数、组件、工具和测试,复用优先。
|
|
- 如果需求含糊,或改动会偏离原则 / 架构,先问。
|
|
|
|
## 2. 分层与工具链纪律(本项目最容易翻车的地方)
|
|
|
|
- `core/` 的 domain 与 application **禁止 import Gio、SQLite、Windows API**;下载、存储、时间、进程、系统信息一律接口注入。
|
|
- 依赖方向只允许 `app-modern`/`app-win7` → `core`;任何反向 import 都是返工。
|
|
- `core/` 与 `app-win7/` 只使用 **Go 1.20 可编译**的语法与依赖;新增依赖前检查其 go.mod 的 `go` 指令。泛型可用(1.18+),但 1.21+ 的标准库函数(如 `slices`、`maps`、`min/max` 内建)不得进入这两个模块。
|
|
- Gio 代码只出现在 `ui/gio/`;Windows 调用只出现在 `platform/windows/`,且必须有非 Windows stub,保证 `go test ./...` 在 Linux CI 可跑。
|
|
- modern/Win7 的 Gio shell 都按同 package 镜像职责维护:`shell.go` 只放 AppShell 状态/生命周期和根编排,header/navigation、catalog/list、detail、theme/style 分别进入 `shell_header.go`、`shell_catalog.go`、`shell_detail.go`、`shell_style.go`;版本特有声明留在对应文件,不得为减少重复而跨 workspace 共享不兼容 Gio 代码。
|
|
- 仅 Win10+ 存在的 Windows API 必须 LoadLibrary 动态加载、失败降级,不得成为 EXE 导入表强依赖。
|
|
- Gio Layout 每帧禁止 IO(磁盘/网络/哈希/图片解码);后台任务只发布 application.Event,不得直接调用 `ApplyIcon` 或改控件/map。后台 event pump 只入有界 relay 并调用 `Window.Invalidate`;只有 Frame/UI goroutine可以 drain `ApplyEvent`。relay 满队列不得静默丢事件,关闭/取消必须解除背压等待。
|
|
- `CatalogListModel.VisibleItems()` 返回当前只读 snapshot generation:refilter 只在状态变化时构造新 backing array 后发布,同 generation 的每帧读取不得复制;调用方不得修改 slice/item/Tags。旧 generation 在后续 model 变化后保持稳定,但 model 仍是单 owner、非并发安全对象。
|
|
- 图标 Fetcher 必须返回与 context 绑定的流,由 `IconCache` 在分配完整响应前执行声明长度拒绝与 `maxBytes+1` 有界读取;不得恢复为先读任意大 `[]byte` 再校验。缓存并发只允许按 key 去重,不得用横跨磁盘/网络的全局锁换取去重。
|
|
- 图标缓存 entry 是 symlink/reparse point 或非普通文件时必须 fail closed:不读取/跟随、不自动 delete/rename/quarantine、不回退 Fetcher。上层只持有已验证的 icon event identity + 稳定 failure code;UI locator 只能由规范 digest + DPI 生成,不得加入绝对 root、raw error、URL/query、token 或 link target。人工处置只引用 [故障排查](troubleshooting.md)。
|
|
|
|
## 3. 安全纪律(违反即安全事故)
|
|
|
|
- 任何下载内容未通过 SHA-256 + 签名验证,**不得解压执行**;清单验签失败拒绝,不回退到未验证内容。
|
|
- ZIP 与软件包路径必须使用 `core/internal/safepath` 的共享 Windows 安全相对路径策略,拒绝绝对路径、`../`/dot-space 归一化穿越、首尾 ASCII 空格、尾随句点、DOS 设备名、Windows 禁止字符、符号链接逃逸和 entrypoint 指向 payload 外;native 输出路径还必须验证仍在 destination 内。Catalog/storage/app.json/files.json 不得各自复制一套路径规则。
|
|
- ZIP 解压必须保留文件数、展开体积和压缩比硬上限。
|
|
- 安装/更新只走 `staging → current → backup` 原子流程;任何写 `current/` 的捷径都不允许。
|
|
- 程序更新不得触碰 `data/` 与 `licenses/`。
|
|
- 不强杀用户进程;更新前等待正常退出,超时取消。
|
|
- 私钥、真实注册码、真实机器标识不进代码、测试数据和文档;`testdata/` 只放假数据和专用测试密钥对。
|
|
- 日志不记录注册码、令牌、原始硬件标识和敏感查询参数。
|
|
|
|
## 4. 事实来源纪律
|
|
|
|
- 协议字段只信 `docs/api.md` 与 `schemas/`;架构边界只信 `docs/04-architecture.md`;当前现实只信 `docs/current-state.md` 和代码。
|
|
- 不从旧盒子的逆向笔记、备份或草稿推断当前实现;那些是设计输入,不是本仓库事实。
|
|
- 不虚构字段、事件、错误码、配置项。
|
|
- 数据结构变化必须同步更新 `04-architecture.md`、`api.md`、`schemas/` 和相关任务。
|
|
|
|
## 5. 范围纪律
|
|
|
|
- MVP 只做 `02-requirements.md` 中列为 P0 的功能;V1.1/V2 功能只记录,不实现。
|
|
- 需求明确排除的非目标(社区、支付、云同步、插件、驱动)不得实现。
|
|
- 不为"将来可能用到"提前抽象;SDK 拆分(softbox-sdk)是后续独立仓库的事,本仓库不预建。
|
|
|
|
## 6. 代码规范
|
|
|
|
- 标识符使用英文;错误码用稳定英文枚举,UI 负责中文文案。
|
|
- 错误必须处理,不吞错;每个失败路径要能落到用户可见的状态或日志。
|
|
- 注释解释"为什么",不复述"做了什么"。
|
|
- 使用 `gofmt`(必须)与 `go vet`(必须);不手工制造风格分裂。
|
|
- 状态写入一律临时文件 + 原子替换。
|
|
|
|
## 7. 测试与验证
|
|
|
|
完成前至少检查:
|
|
|
|
- [ ] `cd core && go vet ./... && go test -count=1 ./...` 通过(Linux 无头环境)。
|
|
- [ ] 现代版可交叉编译:`cd app-modern && GOOS=windows GOARCH=amd64 go build ./cmd/softbox`。
|
|
- [ ] Win7 版可用 Go 1.20 编译:`cd app-win7 && GOTOOLCHAIN=go1.20.14 GOOS=windows GOARCH=amd64 go build ./cmd/softbox`。
|
|
- [ ] 状态机改动覆盖:成功、失败、取消、断电恢复、回滚。
|
|
- [ ] UI 事件改动使用 fake submitter + ApplyEvent 测试。
|
|
- [ ] 对得上需求验收标准;没有夹带无关改动。
|
|
- [ ] 涉及文档事实变化时,文档已同步。
|
|
- [ ] 已在当前任务文件(`docs/tasks/T-<编号>.md`)的 `## 执行记录` 记录跑过的命令和结果作为证据,不靠"代码已写"判定完成。
|
|
- [ ] 回复里如实说明跑了什么命令、结果如何。
|
|
|
|
## 8. 绝不
|
|
|
|
- 绝不把密钥、token、密码、私钥写进代码或文档样例的真实值里。
|
|
- 绝不为了让测试通过而删除断言、降低验收标准。
|
|
- 绝不擅自删除用户已有文件或重置工作区。
|
|
- 绝不在没说明的情况下改公共协议(manifest/app.json/许可证)、迁移数据结构或升级 Gio/Go 工具链。
|
|
- 绝不绕过签名验证、哈希校验或回滚机制"先跑起来再说"。
|
|
|
|
## 9. 拿不准就问
|
|
|
|
问题要具体,说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。
|