Files

T

ilaandClaude Fable 5 63dc40275f Move trial authorization out of MVP scope

Resolve the requirements-vs-architecture conflict found in the Phase 5
review. License v1 is frozen at nine fields with no expiry field
(perpetual is a bool; update/rebind policy are opaque labels), so it
cannot express a trial period. The implementation and architecture docs
correctly recorded that boundary, but 02-requirements still listed trial
as a P0 capability and an MVP acceptance criterion.

Decision: trial moves to V1.1.

- 02-requirements: drop trial from the user role and P0 feature list;
  acceptance now reads 'authorization state consistent between box and
  sub-apps'; add a V1.1 trial row naming the protocol prerequisite; add
  a scope row stating perpetual:false is display-only and never expires,
  and supports_trial does not grant local trial.
- 00-ai-start-here: remove trial from 'MVP does', add it to 'MVP does
  not' with the protocol reason.
- 04-architecture: development order step 5 no longer lists trial/rebind
  as MVP work.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-20 10:43:21 +08:00

7.2 KiB

Raw Permalink Blame History

需求

本文只描述要什么与怎么算达成,用产品 / 用户语言表达,不涉及技术实现。技术方案、数据结构、字段定义见架构设计与协议合约。

一、业务现状

项	状态
用户	自家系列软件的用户,目前手动下载、解压、升级、输注册码,流程易错
数据	已有系列软件的安装包和授权体系(旧盒子);新 Catalog、许可证格式待按新协议建立
现有系统	参考过一个商用软件盒子的逻辑(下载、更新、注册绑定电脑);本项目为全新自研,不复用其代码和旧注册码算法
约束	需兼容少量 Win7 SP1 用户;下载与更新必须防篡改;不依赖管理员权限

二、用户角色

普通用户:浏览软件列表、下载、更新、启动软件、导入许可证。
Win7 遗留用户:使用 Legacy 版盒子,只能看到并下载兼容自己系统的软件包。
发布者(自己,不在客户端内):通过 Catalog 发布签名清单和软件包、签发许可证、维护撤销名单。

三、功能清单

第一版 MVP(最小闭环)

功能	用户能做什么	优先级
远程软件清单	打开盒子看到签名清单中的软件;断网时看到最后一次验证成功的缓存	P0
分类、标签和搜索	按名称/标签搜索,按分类和「全部/已安装/可更新」视图筛选	P0
本地安装状态识别	每款软件显示未安装/已安装/可更新/下载中/运行中等状态	P0
下载队列与进度	排队、开始、暂停、取消、重试;看到速度、进度和剩余时间;重启后恢复	P0
ZIP 安全解压与安装	下载校验后一键安装;失败不破坏已安装版本	P0
版本检测和更新	有新版本时提示并可一键更新;更新失败自动回滚	P0
软件启动与运行检测	一键启动;运行中的软件不被更新覆盖	P0
盒子自身更新	盒子提示自身新版本并安全自更新,失败可恢复	P0
机器绑定许可证	导入许可证,离线验证,区分已授权/未授权/授权错误	P0
双版本	现代版(Win10/11 x64)和 Win7 遗留版各自可用,更新通道不交叉	P0
日志与失败恢复	关键操作有日志;下载/安装失败有明确提示和重试路径	P0

后续迭代

功能	描述	阶段
试用授权	未注册试用与到期判定;License v1 九字段无到期字段(`perpetual` 仅为布尔、policy 字段为不透明标签),需先定新协议版本或独立签名试用对象,并解决时钟回拨与跨机重置	V1.1
files.json 复核与修复	按文件清单发现缺失/被改文件并修复安装	V1.1
命名管道优雅退出	更新前通知子软件保存并退出(prepare_update/ready)	V1.1
--softbox-info / --softbox-health	子软件标准自检参数接入健康检查	V1.1
Win7 x86 构建	有真实用户需求时提供 32 位遗留版	V2
便携模式	portable.flag 触发相对目录存储	V2
beta 通道	用户可选参与 beta 清单	V2
SQLite 存储	历史记录、全文搜索需求出现后再评估	V2+

四、核心用户故事(MVP)

作为普通用户,我打开盒子后能看到软件列表(断网也能看到缓存的列表),并能搜索和按分类筛选。
我可以点击「下载」,看到进度和速度;下载完成后自动校验、安装,状态变为「已安装」;我点击「启动」即可使用软件。
当软件有新版本时,列表中显示「可更新」;我点击更新,旧版本被安全替换;若更新中途失败,软件仍能以旧版本启动。
我导入许可证文件后,盒子显示已授权的软件;子软件独立启动时同样能识别授权;把许可证复制到别的电脑无法通过验证。
当清单签名被篡改、下载包哈希不符、磁盘不足或断网时,盒子给出明确提示,不执行任何未验证内容,也不破坏已安装的软件。
作为 Win7 用户,我使用遗留版盒子,只看到并下载 Win7 兼容的软件包,不会被推送无法启动的现代版。

五、验收标准(MVP)

清单:断网启动可读取最后验证成功的缓存;伪造或篡改的清单被拒绝且不回退到未验证内容;下架软件通过 status 隐藏而不是改名。
下载:并发默认 2;暂停/取消/重试可用;中断后重启盒子能续传;速度、进度、剩余时间实时刷新。
安装/更新:哈希不符、路径穿越、磁盘不足、目标程序运行中——每种情况都有确定的失败结果且不破坏 current;更新失败后旧版本仍可启动。
启动:启动前检查文件存在、系统兼容和授权;运行中软件在列表显示「运行中」;运行状态通过进程快照检测。
盒子自更新:更新过程中断电/失败,下次启动可恢复旧版;新版启动后写入健康状态。
授权:许可证离线可验证;machine_hash 不匹配即拒绝;更新任何软件都不覆盖许可证与用户数据;授权状态在盒子和子软件中一致。
双版本:两个 EXE 分别在 Win11 和 Win7 SP1 真机可打开并完成「清单→下载→安装→启动」;Win7 版清单不出现现代版软件包。
性能:数百个软件项列表滚动流畅;界面每帧不做磁盘/网络 IO。

六、范围边界与决策

问题	决策
第一版平台	Windows 桌面(现代版 x64 + Win7 遗留版 x64;x86 按需)
是否需要账号	否;授权基于许可证文件 + 机器绑定,无在线账号体系
第一版范围	上表 P0 的最小闭环
软件包格式	ZIP(标准软件包协议 v1),不再依赖 UnRAR.dll
试用	移出 MVP,见「后续迭代」。License v1 的 `perpetual:false` 仅是「非永久许可证」的展示语义,不会自动到期、不产生试用授权;`app.json` 的 `supports_trial` 只表示软件支持试用,不构成本地试用能力。无有效许可证时不授权启动
暂不支持	评论/评分/社区、支付、云同步、皮肤市场、插件脚本、驱动安装
Win7 定位	Legacy:仅兼容与严重修复,有用户占比门槛和停止维护日期

七、待确认 / 风险点

Catalog 服务端:清单签名发布器和对象存储的落地方式(本仓库只消费签名清单,发布侧在 softbox-catalog 仓库);首期可用本地/静态文件模拟,需确认正式域名和存储。
签名密钥管理:Ed25519 私钥的保管和签发流程,谁持有、如何轮换;私钥绝不进入本仓库。
Win7 支持门槛:真实 Win7 用户占比未量化;需确认是否提供 x86 和 Legacy 停止维护日期。
授权迁移:旧盒子存量用户的注册码如何换发为新许可证,人工流程谁负责。
第三方平台风险:下载走自有对象存储/CDN,需确认带宽成本和 URL 防盗链策略。
自动化边界:盒子不强杀用户进程;更新前等待用户关闭软件,超时取消更新。
隐私:只上送/记录 machine_hash,不保存原始序列号和 MAC;日志不含注册码和敏感查询参数。
Authenticode 证书:EXE 代码签名证书的采购与签名流水线接入时间点。

7.2 KiB Raw Permalink Blame History

需求

一、业务现状

二、用户角色

三、功能清单

第一版 MVP(最小闭环)

后续迭代

四、核心用户故事(MVP)

五、验收标准(MVP)

六、范围边界与决策

七、待确认 / 风险点

7.2 KiB

Raw Permalink Blame History