soft_quay/docs/tasks/T-201.md

id, title, phase, deps, status, created, issue, context_ref, claim_branch, work_branch, write_paths

id	title	phase	deps	status	created	issue	context_ref	claim_branch	work_branch	write_paths
T-201	Catalog 模块正式接入	2	T-101	DONE	2026-07-16	null	9da72ca0d8563fb5dca8a5675461e49dc656b74e	null	agent/codex/T-201	docs/tasks/T-201.md core/catalog/ schemas/ testdata/catalog/ testdata/README.md docs/api.md docs/04-architecture.md docs/current-state.md

问题 / 背景

Phase 1 已验证 Catalog 顶层签名与最后有效缓存回退，但仍只有“可信 JSON 字节”，没有正式的 HTTPS 获取、协议字段校验、modern/win7 通道约束、OS/架构过滤和上下架处理。若在结构或通道校验前写缓存，签名正确但客户端无法消费的清单也可能替换最后可用版本。

方案

1. 在 core/catalog 建立 manifest/app/package 强类型模型和严格解析校验，拒绝未知字段、重复软件 ID、非法枚举、非 HTTPS 包 URL及不一致的架构映射。
2. Loader 支持在缓存替换前执行文档 validator；正式 Client 固定按“验签 → Schema/通道校验 → 缓存 → 目标过滤”加载。
3. 增加有体积上限的 HTTPS Fetcher，并保留 Fetcher/Cache 注入以便无网络测试。
4. 目标过滤同时处理 manifest channel、min_os、architectures、package 架构与 status：hidden 不展示，deprecated 与 incompatible 可见但不可安装并给出稳定原因码。
5. 在 schemas/ 落地 manifest 与 app.json 的 JSON Schema；同步协议与架构文档。

验收要点

• 签名、结构、通道全部通过后才替换缓存；结构非法或通道错误时回退最后验证且可消费的缓存。
• HTTP 获取只允许 HTTPS、拒绝非 2xx/超限响应。
• modern/win7、最低 OS、386/amd64 与 package 映射过滤正确。
• active 可安装；deprecated 可见不可安装；hidden 不进入结果；不兼容项可见并返回稳定原因。
• manifest.schema.json 与 app.schema.json 可由标准 JSON 解析器读取，示例字段与 docs/api.md 一致。
• Go 1.20 core vet/test、完整双目标闸门和治理校验通过。

边界（不改什么）

• 不实现 installed-app.json、SemVer 比较和本地 12 状态识别（T-202）。
• 不实现 Gio 列表、详情或图标资源下载（T-203/T-204）。
• 不冻结密钥轮换字段或图标 URL；发布端跨实现签名向量仍需在独立仓库对齐。
• 不引入第三方 Schema、HTTP 或 SemVer 依赖。

协作约束

未启用 Gitea；本任务在 agent/codex/T-201 分支串行执行。正式 Client 必须保护“最后可消费缓存”，不能把 validator 放到缓存写入之后。

执行记录

• 2026-07-16:建立 manifest/app/package 强类型模型、严格 Parser 与正式 Client；加载顺序固定为“HTTPS 获取 → Ed25519 验签 → 字段/Schema/channel 校验 → 缓存替换 → 目标过滤”。
• 2026-07-16:Loader 增加缓存写入前 DocumentValidator；测试证明签名正确但 channel/结构不匹配的远端清单不会覆盖最后可消费缓存。
• 2026-07-16:增加有响应体上限和 HTTPS 重定向约束的 HTTPFetcher；错误状态、非 HTTPS 与超限响应均返回稳定错误。
• 2026-07-16:实现 modern/win7、Windows 7 SP1/10/11、386/amd64 过滤；active 可安装，deprecated 与 incompatible 可见不可安装并带稳定原因，hidden 不进入目录结果。
• 2026-07-16:正式协议补充必填 category，与 tags 分别承担单分类与搜索标签；图标仍仅定义 sha256: 内容引用，未越权确定分发 URL。
• 2026-07-16:新增 schemas/manifest.schema.json、schemas/app.schema.json，并同步 docs/api.md、docs/04-architecture.md、docs/current-state.md 与公开虚构 testdata。
• 定向验证通过:go -C core test -count=1 ./catalog。
• Schema 语法验证通过:python -m json.tool schemas/manifest.schema.json、python -m json.tool schemas/app.schema.json。
• 完整验证通过:./scripts/verify_phase0.ps1，包含 Go 1.20.14 core vet/test、治理/边界/版本检查及 modern/win7 双目标测试与构建。
• 提交前检查通过:git diff --check。