T-618 require release checksum metadata in admin

progress.md

@@ -1756,6 +1756,7 @@
   - `git diff --check`：通过，仅 Windows CRLF 提示。
 - 测试环境现象：
   - 测试期仍保留 allauth `account.EmailAddress` 条件唯一约束在 MySQL 上不可创建的既有 `models.W036` 警告。
+
 - 决策：
   - T-615 第一版只做日志遥测，不新增 admin 报表或统计表；如后续需要报表，单独评估数据量、索引和保留周期。
   - 旧同步接口下线前必须继续保持成功响应兼容；待新版客户端默认异步、旧路调用归零或低于运营阈值一段时间后，再宣布 deprecated 并单独立下线任务。
@@ -1837,6 +1838,7 @@
   - `git diff --check`：通过，仅 Windows CRLF 提示。
 - 测试环境现象：
   - 测试期仍保留 allauth `account.EmailAddress` 条件唯一约束在 MySQL 上不可创建的既有 `models.W036` 警告。
+
 - 决策：
   - T-616 第一版不重试敏感词、余额不足、未定价、模型 / 别名不可用、参数错误和 Provider 能力错误；这些属于确定性失败，立即失败并退款或在提交阶段不扣点。
   - 重试期间不展示 `error` 给轮询客户端，客户端只需看到 `queued + next_attempt_at` 后继续轮询；最终 `failed` 才表示已退款。
@@ -1861,3 +1863,38 @@
   - `py -3.12 manage.py migrate portal --noinput`：命令 120 秒超时，但随后 `py -3.12 manage.py showmigrations portal` 显示 `portal.0004_downloadrelease_size_bytes` 已应用；未发现残留 `manage.py migrate` 进程。
 - 测试环境现象：
   - 测试期仍保留 allauth `account.EmailAddress` 条件唯一约束在 MySQL 上不可创建的既有 `models.W036` 警告。
+
+## 2026-07-13 文档登记：T-618 客户端发布版本后台必填文件校验元数据
+
+- 状态：TODO（仅任务登记，未改代码）。
+- 背景：T-617 已让版本检查接口返回 `release.size_bytes`，但线上当前发布版本仍可能为空；如果 admin 发布客户端版本时漏填 `sha256` 或 `size_bytes`，桌面端无法完整校验下载文件。
+- 文档变更：
+  - `docs/06-tasks.md`：新增 T-618「客户端发布版本后台必填文件校验元数据」，要求 django-admin 中 `DownloadRelease.sha256` 和 `DownloadRelease.size_bytes` 必填。
+  - `docs/current-state.md`：把 T-618 设为下一个可领取任务。
+- 方案口径：
+  - 第一版只做 admin 表单必填，不直接把数据库字段改成 `NOT NULL`，避免历史记录或线上当前 `size_bytes=null` 造成迁移风险。
+  - 实现时建议给 `DownloadReleaseAdmin` 增加专用 `ModelForm`，字段级要求 `sha256` 必填且保持 64 位十六进制校验，`size_bytes` 必填且 `>=1`。
+  - 上线后必须补齐当前 Windows 发布版本的 `size_bytes`，并验证 `/api/v1/client/releases/latest?platform=windows` 返回正整数。
+- 验证：仅文档更新；提交前执行 `git diff --check`。
+
+## 2026-07-13 实施：T-618 客户端发布版本后台必填文件校验元数据
+
+- 状态：DONE。
+- 背景：T-617 已让版本检查接口返回 `release.size_bytes`，但如果运营在 django-admin 发布客户端版本时漏填 `sha256` 或 `size_bytes`，桌面端无法完整校验安装包。
+- 代码变更：
+  - `apps/portal/admin.py`：新增 `DownloadReleaseAdminForm` 并挂到 `DownloadReleaseAdmin.form`；admin 新增 / 编辑 `DownloadRelease` 时 `sha256` 与 `size_bytes` 必填，继续复用 `sha256` 64 位十六进制校验和 `size_bytes >= 1` 校验。
+  - `apps/portal/tests.py`：新增 admin 表单目标测试，覆盖缺 `sha256` / 缺 `size_bytes` 拒绝保存，以及合法 `sha256 + size_bytes` 可通过表单保存。
+- 文档变更：
+  - `docs/06-tasks.md`：T-618 标记为 DONE，并把实现口径从建议改为已落地。
+  - `docs/api.md`：说明 T-618 起 admin 新增 / 编辑发布版本必须填写 `sha256` 和 `size_bytes`，但 API 仍兼容历史空值。
+  - `docs/04-architecture.md` / `docs/routes.md`：同步客户端下载版本 admin 必填校验元数据口径。
+  - `README.md` / `docs/current-state.md`：同步 T-618 已完成、当前状态与验证结果。
+- 验证：
+  - `.\init.ps1`：通过（Python 3.12.3，依赖已满足，`manage.py check` 0 issues，打印启动命令）。
+  - `py -3.12 manage.py check`：通过，0 issues。
+  - `py -3.12 manage.py makemigrations --check --dry-run`：通过，No changes detected。
+  - `py -3.12 manage.py test apps.portal.tests.PortalAccountFlowTests.test_download_release_admin_requires_sha256_and_size_bytes apps.portal.tests.PortalAccountFlowTests.test_download_release_admin_saves_valid_release_metadata apps.api.tests.ClientLatestReleaseApiTests.test_latest_release_returns_null_size_bytes_when_not_configured apps.api.tests.ClientLatestReleaseApiTests.test_latest_release_is_public_without_api_key_and_returns_current_release --keepdb --noinput --verbosity 2`：通过，4 tests OK。
+- 测试环境现象：
+  - 测试期仍保留 allauth `account.EmailAddress` 条件唯一约束在 MySQL 上不可创建的既有 `models.W036` 警告。
+- 部署提醒：
+  - 代码部署后需要在生产 admin 补齐当前 Windows 发布版本的 `size_bytes`，并验证 `GET /api/v1/client/releases/latest?platform=windows` 返回正整数 `release.size_bytes`。