2026-07-20 00:43:58 +08:00
|
|
|
# 编码规则(Coding Rules)
|
|
|
|
|
|
|
|
|
|
> 每次写代码前先读完本文件。与技术细节冲突时,以 [技术栈](03-tech-stack.md) / [架构设计](04-architecture.md) 为准;与"该不该做"冲突时,以 [需求](02-requirements.md) 为准;协议字段以 [api.md](api.md)(权威源 `soft_quay` 仓库)为准。
|
|
|
|
|
|
|
|
|
|
## 0. 黄金法则
|
|
|
|
|
|
|
|
|
|
1. **不臆造**:数据字段、文件、接口、依赖,不确定就查证或询问。
|
|
|
|
|
2. **守范围**:只做当前任务要求的事,不顺手加后续功能。
|
|
|
|
|
3. **照架构**:使用既定技术栈和组件边界,不擅自引入新框架。
|
|
|
|
|
4. **小步改**:一次只解决一个问题,不夹带无关重构。
|
|
|
|
|
5. **可验证**:改完必须能构建、能测试、对得上验收标准。
|
|
|
|
|
|
|
|
|
|
## 1. 动手前
|
|
|
|
|
|
|
|
|
|
- 按链路确认:`vision` → `requirements` → `tech-stack` → `architecture` → `tasks`。
|
|
|
|
|
- 找到本任务对应的验收标准,写之前就知道"怎么算做对"。
|
|
|
|
|
- 先找现有函数、组件、工具和测试,复用优先。
|
|
|
|
|
- 未定项(06-tasks 裁定清单)未裁定前不得替用户在代码里做决定。
|
|
|
|
|
|
|
|
|
|
## 2. 协议对齐纪律(本项目最容易翻车的地方)
|
|
|
|
|
|
|
|
|
|
- canonicalization / 签名的跨实现回归**只消费** `soft_quay/testdata/catalog/canonical-vectors.json` 的静态期望值(`document`/`signed_payload_base64`/`signature`/`want_error`);**禁止**用本仓库 canonicalizer 或测试私钥重新生成"正确"向量。
|
|
|
|
|
- 签名域规则严格执行 [api.md](api.md) §签名域:只移除顶层 `signature`;拒绝重复键、尾随数据、浮点/指数、`-0`、非法 surrogate;signature 必须是唯一标准 padded Base64(64 字节),CR/LF/空白/padding 变体一律拒绝;大整数保持原始十进制 token 不失精度。
|
|
|
|
|
- 协议字段只信 `soft_quay/docs/api.md` 与 `soft_quay/schemas/`;本仓库不得单方面新增/修改协议字段,需要变更时先在客户端仓库定稿,再同步本仓库文档与实现。
|
|
|
|
|
- 不定义第二套验签域(package 级、图标级或其他);单公钥协议升级前不做 key ID / 轮换字段。
|
|
|
|
|
- 发布前必须通过 Schema 校验:`additionalProperties: false`、id 唯一且 `^[a-z0-9-]+$`、SemVer 合法、architectures 与 packages 键一一对应、URL 为无用户信息无 fragment 的绝对 HTTPS。
|
|
|
|
|
|
|
|
|
|
## 3. 安全纪律(违反即安全事故)
|
|
|
|
|
|
|
|
|
|
- **私钥永不落地**:私钥不进代码、配置样例、环境变量明文、日志、测试数据、数据库;`testdata/` 只放与客户端 corpus 公钥配对的专用测试密钥对。
|
|
|
|
|
- 签名服务只对清单 / 许可证 / 撤销名单三类已知结构签名;拒绝任意字节签名请求。
|
|
|
|
|
- Ingestion 对候选 ZIP 必须校验:包结构(app.json/files.json/payload)、app.json 与登记的 id/version/channel/min_os/architecture 一致、解压防护(路径穿越、文件数/体积/压缩比上限——复用客户端已验证的安全规则,不另造宽松版)。
|
|
|
|
|
- 双通道清单生成后必须有通道隔离断言:win7 清单不得含不兼容包。
|
|
|
|
|
- Publisher 必须先确认包与图标可下载,再发布引用它们的清单;失败时清单不得切换。
|
|
|
|
|
- 许可证与审计:不保存原始硬件序列号/MAC;日志不记录注册码、令牌、敏感查询参数;审计记录 append-only。
|
|
|
|
|
- 云凭据、真实生产域名配置不入库;用环境配置 + `.example` 占位文件。
|
|
|
|
|
|
|
|
|
|
## 4. 事实来源纪律
|
|
|
|
|
|
|
|
|
|
- 协议只信 `soft_quay` 仓库;架构边界只信 `docs/04-architecture.md`;当前现实只信 `docs/current-state.md` 和代码。
|
2026-07-20 00:44:26 +08:00
|
|
|
- 原始设计规格已拆分进编号文档后删除;不要从 git 历史里的旧设计稿推断当前约定,以编号文档为准。
|
2026-07-20 00:43:58 +08:00
|
|
|
- 不虚构字段、事件、错误码、配置项。
|
|
|
|
|
- 数据结构变化必须同步更新 `04-architecture.md`、`api.md` 和相关任务;涉及协议的必须先走客户端仓库。
|
|
|
|
|
|
|
|
|
|
## 5. 范围纪律
|
|
|
|
|
|
|
|
|
|
- 只做 `02-requirements.md` 列出的第一版功能;「后续迭代」表中的功能只记录,不实现。
|
|
|
|
|
- 不做面向客户端的运行时 API、账号会话、评论评分等清单外功能。
|
|
|
|
|
- 不为"将来可能用到"提前抽象。
|
|
|
|
|
|
|
|
|
|
## 6. 代码规范
|
|
|
|
|
|
|
|
|
|
- 标识符使用英文;错误码用稳定英文枚举,UI 负责中文文案。
|
|
|
|
|
- 错误必须处理,不吞错;每个失败路径要能落到操作者可见的状态或审计/日志。
|
|
|
|
|
- 注释解释"为什么",不复述"做了什么"。
|
|
|
|
|
- 状态与产物写入一律临时文件 + 原子替换。
|
|
|
|
|
- (若选 Go)使用 `gofmt` 与 `go vet`;加密只用标准库 `crypto/ed25519`。
|
|
|
|
|
|
|
|
|
|
## 7. 测试与验证
|
|
|
|
|
|
|
|
|
|
完成前至少检查:
|
|
|
|
|
|
|
|
|
|
- [ ] corpus 全向量回归通过(合法向量字节一致,非法向量按 `want_error` 拒绝)。
|
|
|
|
|
- [ ] Schema 校验闸门通过;构造的非法样例被拒绝。
|
|
|
|
|
- [ ] 涉及签名 / 发布 / Ingestion 的改动覆盖:成功、校验失败、签名服务不可用、发布中断各路径。
|
|
|
|
|
- [ ] 对得上需求验收标准;没有夹带无关改动。
|
|
|
|
|
- [ ] 涉及文档事实变化时,文档已同步。
|
|
|
|
|
- [ ] 已在当前任务文件(`docs/tasks/W-<编号>.md`)的 `## 执行记录` 记录跑过的命令和结果作为证据。
|
|
|
|
|
- [ ] 回复里如实说明跑了什么命令、结果如何。
|
|
|
|
|
|
|
|
|
|
## 8. 绝不
|
|
|
|
|
|
|
|
|
|
- 绝不把私钥、token、密码、云凭据写进代码或文档样例的真实值里。
|
|
|
|
|
- 绝不用本仓库实现自举 corpus 期望值,或为让回归通过而修改向量。
|
|
|
|
|
- 绝不为了让测试通过而删除断言、降低验收标准。
|
|
|
|
|
- 绝不在没说明的情况下改公共协议(manifest/app.json/许可证)或抢在客户端仓库前变更协议。
|
|
|
|
|
- 绝不绕过 Schema 校验、签名流程或发布原子性"先跑起来再说"。
|
|
|
|
|
- 绝不擅自删除用户已有文件或重置工作区。
|
|
|
|
|
|
|
|
|
|
## 9. 拿不准就问
|
|
|
|
|
|
|
|
|
|
问题要具体,说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。
|
