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
commit a89821a571
24 changed files with 1913 additions and 0 deletions
@@ -0,0 +1,135 @@
+# 架构设计
+
+> 系统结构、职责边界、数据模型与发布流水线。协议字段以 [api.md](api.md)(权威源 `soft_quay` 仓库)为准;原始设计规格见 [softbox-catalog-design.md](softbox-catalog-design.md)。
+
+## 一、信任模型(一切设计的出发点)
+
+客户端 `soft_quay` 对远端内容的信任**仅来自 Ed25519 签名**:
+
+```text
+soft_quay_web(持私钥)          soft_quay 客户端(内置公钥)
+─────────────────────────         ─────────────────────────
+用受限规范 JSON + 私钥签名   ──►   拉取 → 去掉顶层 signature → 同规则规范化
+生成 manifest-modern/win7.json     → Ed25519 验签 → Schema/channel/架构过滤
+上传对象存储 / CDN(HTTPS)          → 缓存;验签失败则拒绝、退回上次可信缓存
+包 url/size/sha256 写入清单         → 下载 → 同句柄 size→SHA-256→安全解压
+```
+
+由此推出的硬性要求:
+
+1. **规范化必须字节级一致**:发布端与客户端对同一 JSON 输入必须产出逐字节相同的规范字节与签名;共用 `canonical-vectors.json` corpus 作为跨实现回归基线,发布端不得自举期望值。
+2. **私钥保管是最高安全目标**:私钥泄露 = 可伪造任意清单 / 包记录 / 许可证 = 客户端全线沦陷。
+3. **客户端不做在线校验**:下架、撤销、版本兼容都必须能"离线表达"在签名文件里(status 字段、签名撤销名单 + 宽限期)。
+
+## 二、组件与职责
+
+```text
+             ┌─────────────────────────────────────────────┐
+子软件 app-* CI │ 构建标准 ZIP 包 + Release 元数据             │
+             └───────────────┬─────────────────────────────┘
+                             │ 上传候选包
+                             ▼
+┌──────────────────────────────────────────────────────────────┐
+│ soft_quay_web                                                │
+│  ┌────────────┐   ┌────────────┐   ┌──────────────────────┐   │
+│  │ Ingestion  │──►│ Registry   │──►│ Manifest Generator   │   │
+│  │ 包接收校验  │   │ 元数据/发布 │   │ 双通道清单组装        │   │
+│  └────────────┘   │ 记录 (DB)  │   └──────────┬───────────┘   │
+│        │          └────────────┘              │ 待签名规范字节  │
+│        │ size/SHA-256                          ▼               │
+│        │                          ┌──────────────────────┐    │
+│        │                          │ Signing Service      │    │
+│        │                          │ (Ed25519 私钥,隔离/  │    │
+│        │                          │  KMS/HSM,受限接口)  │    │
+│        │                          └──────────┬───────────┘    │
+│        ▼                                     ▼                 │
+│  ┌────────────┐   ┌────────────┐   ┌──────────────────────┐   │
+│  │ License &  │   │ Web 管理端  │   │ Publisher (发布器)    │   │
+│  │ Revocation │   │ (UI)       │   │ 上传对象存储/CDN      │   │
+│  └────────────┘   └────────────┘   └──────────┬───────────┘   │
+│        │ 审计日志 (append-only)                 │              │
+└────────┼──────────────────────────────────────┼──────────────┘
+         ▼                                        ▼
+   审计/合规存档                       对象存储 / CDN(静态托管)
+                                                  │ HTTPS
+                                                  ▼
+                                          soft_quay 客户端
+```
+
+| 组件 | 职责 | 不含 |
+| --- | --- | --- |
+| Ingestion | 接收子软件 CI 的 ZIP 候选包;校验包协议结构(app.json/files.json/payload)、计算 size 与 SHA-256、比对声明版本/ID/架构 | 构建子软件、跑子软件业务 |
+| Registry | 软件元数据、发布记录、包坐标(url/size/sha256)、status、channel、Catalog 版本 | 子软件源码、客户端状态 |
+| Manifest Generator | 从 Registry 按 channel 组装双通道清单,产出**待签名规范字节** | 签名(委托签名服务) |
+| Signing Service | 唯一持有 Ed25519 私钥;只对清单/许可证/撤销名单三类受控结构签名 | 业务逻辑、任意数据签名 |
+| License & Revocation | 绑定 machine_hash + products 签发许可证;维护签名撤销名单 + 宽限期 | 保存原始硬件序列号/MAC |
+| Publisher | 签名清单、ZIP 包、图标上传对象存储/CDN;保证原子发布(先包后清单) | 生成未签名/未校验产物 |
+| Web 管理端 | 发布者操作界面与编排;签名经受控接口调用 | 直接持有私钥 |
+| Audit | append-only 记录每次发布/下架/撤销/签发 | 可被覆盖的可变日志 |
+
+### 关键边界
+
+- **签名服务是唯一持钥点**:其余组件(含 Web 后台)只能提交"受限结构 + 请求签名",拿回签名串,拿不到私钥。
+- **Web 管理端不等于签名端**:私钥不进 Web 进程。
+- **协议 Schema / corpus 单一权威源**:引用 `soft_quay/schemas/` 与 `canonical-vectors.json`,CI 校验发布端产物能被同一份 corpus 与 Schema 通过。
+
+## 三、数据模型(建议,W-201 定稿)
+
+> 首期里程碑(协议对齐)不需要数据库;下面是 Registry 落地时的起点草案,定稿后更新本节并删除"建议"标注。
+
+```text
+Software 1 ──── * Release 1 ──── * PackageArtifact
+   │                 │
+   │                 └──── * AuditEvent(所有实体的操作都产生)
+   └ id 永久稳定
+
+License * ──── RevocationEntry(按 license_id 撤销)
+```
+
+| 实体 | 关键字段 | 说明 |
+| --- | --- | --- |
+| Software | `id`(永久稳定)、name、description、category、tags、icon(sha256)、homepage、tutorial、entry_exe、requires_admin、status | 客户端列表页唯一来源;一行对应清单里一个 app |
+| Release | software_id、version(SemVer)、channel(modern/win7)、min_os、architectures、created_at、catalog_version | 一次版本发布;同 software 同 channel 只有一个 active release 进清单 |
+| PackageArtifact | release_id、arch(386/amd64)、url、size、sha256、signature、ingested_at | 来自 Ingestion 的校验结果;url 为发布后的绝对 HTTPS |
+| License | license_id、machine_hash、products[]、issued_at、perpetual、update_policy、rebind_policy | 不保存原始硬件标识 |
+| RevocationEntry | license_id、revoked_at、reason 摘要 | 进入签名撤销名单 |
+| AuditEvent | actor、action、target、content_digest、signature_fingerprint、at | append-only,不可修改 |
+
+## 四、发布流水线
+
+```text
+子软件 CI 产出标准 ZIP 包 + Release 元数据
+  → Ingestion 校验包结构 / app.json 一致性 / 计算 size + SHA-256
+  → Registry 登记发布记录(url 坐标、status、channel、Catalog 版本)
+  → Schema 校验(manifest/app schema)
+  → Manifest Generator 组装 modern/win7 待签名规范字节
+  → Signing Service 用 Ed25519 私钥签名
+  → CI 用 canonical-vectors corpus + Schema 回归验证产物
+  → Publisher 原子上传:先传 ZIP 包/图标到对象存储,再切换签名清单
+  → soft_quay 客户端发现新版本
+```
+
+- 一个产品可产出多目标(如 `json-parser_1.4.2_windows_amd64.zip`、`..._win7_amd64.zip`);只生成实际支持并测试过的目标。
+- **原子性**:包必须先于清单可用,避免客户端拿到指向尚未上传包的清单。
+
+## 五、签名与密钥管理
+
+- **私钥隔离**:理想部署为 KMS/HSM 或独立最小权限签名服务;Web 后台与业务进程只经受控接口请求签名,不接触私钥材料(保管方案 W-003 裁定)。
+- **只签受控结构**:清单 / 许可证 / 撤销名单;不对任意字节签名。
+- **公钥分发**:客户端内置公钥;测试用公钥见 corpus。正式公钥的内置与更新方式随密钥轮换设计裁定(Backlog,需客户端协议升级)。
+- **签名审计**:每次签名请求记录操作者、目标结构摘要、时间、密钥指纹。
+
+## 六、版本 / 协议兼容管理
+
+| 版本类型 | 示例 | 用途 |
+| --- | --- | --- |
+| 产品版本 | 1.4.2 | 用户看到的软件版本 |
+| SDK 版本 | sdk/core v1.2.0 | 公共能力兼容性 |
+| 软件包协议 | schema_version 1 | 盒子与包的结构协议 |
+| Catalog 版本 | 2026.07.16.1 | 目录发布时间 |
+
+原则:SDK 升级不强迫历史软件立即升级;盒子至少兼容当前与前一个包协议版本;清单顶层 `min_box_version` 声明所需最低盒子版本。
+
+## 七、开发顺序
+
+见 [任务路线图](06-tasks.md):Phase 0 裁定与骨架 → Phase 1 协议对齐核心(最高风险先行)→ Phase 2 登记与本地模拟发布闭环 → Phase 3 签名隔离与正式发布 → Phase 4 许可证与撤销 → Phase 5 Web 管理端与审计。