67 lines
4.1 KiB
Markdown
67 lines
4.1 KiB
Markdown
---
|
||
id: T-201
|
||
title: Catalog 模块正式接入
|
||
phase: 2
|
||
deps: [T-101]
|
||
status: DONE
|
||
created: 2026-07-16
|
||
issue: null
|
||
context_ref: 9da72ca0d8563fb5dca8a5675461e49dc656b74e
|
||
claim_branch: null
|
||
work_branch: agent/codex/T-201
|
||
write_paths:
|
||
- 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`。
|