opc/soft_quay_web
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a89821a5718c43551349018a7f2709b0f2f5e34f
soft_quay_web/docs/05-coding-rules.md
T
ilaandClaude Fable 5 a89821a571 Initialize harness coding docs from design spec 
Split docs/softbox-catalog-design.md into the numbered harness doc set
(00-06, api.md, current-state, agent-context, tasks) following the
harness_coding_docs template and soft_quay conventions. Register the
nine open decision items from the design spec into the 06-tasks
roadmap as W- tasks and backlog entries. Keep the original design
spec as an archived design input with a header note.

Recreated after the repository's previous git history was lost to an
external reset; content matches the original initial commit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-20 00:43:58 +08:00

5.6 KiB
Raw Blame History

编码规则(Coding Rules)

每次写代码前先读完本文件。与技术细节冲突时,以 技术栈 / 架构设计 为准;与"该不该做"冲突时,以 需求 为准;协议字段以 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 §签名域:只移除顶层 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 和代码。
  • docs/softbox-catalog-design.md 是原始设计规格,编号文档拆分后以编号文档为准;两者冲突时先修文档再动代码。
  • 不虚构字段、事件、错误码、配置项。
  • 数据结构变化必须同步更新 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. 拿不准就问

问题要具体,说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。

Reference in New Issue View Git Blame Copy Permalink