soft_quay_web/docs/01-vision.md

# 项目愿景

## 一、核心目标

soft_quay_web 要解决:SoftBox 软件发布者(自己)发布自家系列软件时,元数据、签名、托管、许可证分散、无审计、私钥无处安放的问题。

> 让发布者在一个后台里完成「登记软件 → 接收构建包 → 校验 → 签名 → 生成双通道清单 → 上传 → 客户端发现新版本」,而**签名私钥永不离开发布系统,客户端只内置公钥**。

它把整个 SoftBox 产品家族的"信任根"收敛到一处:客户端拿到的每一份清单、每一个安装包、每一张许可证,都能用内置 Ed25519 公钥**离线验签**,不依赖任何在线接口的可用性。

它不是应用商店服务,也不是动态在线 API:最终产物是放在对象存储 / CDN 上的**静态签名文件**。

## 二、目标用户

- **软件发布者(自己)**:唯一的人类操作者;集中、安全、可审计地发布 / 下架 / 撤销软件、签发许可证。
- **子软件 CI(app-* 仓库)**:机器角色;向本系统提交标准 ZIP 候选包。
- **soft_quay 客户端(间接)**:不直接访问本系统,只消费静态签名产物;它的离线验签规则是本系统一切设计的约束来源。

## 三、设计原则

遇到取舍时,以这些原则为准:

- **静态分发优先**:产物是静态签名文件,不是运行时动态 API;客户端离线验签。
- **私钥隔离至上**:Ed25519 私钥是整个体系的信任根,只存在于受控签名服务,绝不进客户端、代码仓库或普通后台进程。
- **协议以客户端为权威源**:清单 / 包协议 Schema 与签名向量 corpus 以 `soft_quay` 为准,发布端**字节级对齐**,不另造 canonicalizer 或第二套验签域。
- **通道隔离**:modern / win7 双通道全程不交叉,Win7 用户永不拿到无法启动的现代版包。
- **可审计**:每次发布、下架、撤销、许可证签发都有不可否认的 append-only 记录。
- **先协议后界面**:先做到产物能被客户端验签通过,再迭代 Web 管理界面。

## 四、核心价值主张

| 价值点 | 说明 |
| --- | --- |
| 单一信任根 | 一处持钥、一处签名;客户端全线离线验真 |
| 一站式发布 | 登记、校验、签名、双通道清单、上传在一条流水线完成 |
| 离线可表达的治理 | 下架(status)、撤销(签名名单 + 宽限期)都能表达在静态签名文件里 |
| 双通道安全 | modern / win7 清单隔离,遗留用户不被误伤 |
| 不可否认审计 | 每次签名与发布动作可追溯到操作者与时间 |

## 五、不做什么(非目标)

- 不含子软件业务源码——那些在各自 `app-*` 仓库。
- 不含盒子的下载 / 更新 / 安装 / 授权实现——那些在 `soft_quay` 客户端。
- 不做面向客户端的运行时接口、账号会话——客户端只拉静态签名文件。
- 不生成未测试目标的占位包。
- 不定义第二套包级验签域——外层清单 Ed25519 签名已覆盖 package 的 `url/size/sha256/signature` 文本。

> MVP 的具体功能范围与验收标准,见 [需求](02-requirements.md)。