From 28879666256e9f0506dea394eac6bed6296e5493 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Mon, 13 Jul 2026 17:51:43 +0800 Subject: [PATCH] T-618 require release checksum metadata in admin --- README.md | 2 +- apps/portal/admin.py | 13 +++++++++++++ apps/portal/tests.py | 35 +++++++++++++++++++++++++++++++++++ docs/04-architecture.md | 2 +- docs/06-tasks.md | 2 ++ docs/api.md | 4 ++-- docs/current-state.md | 10 ++++++---- docs/routes.md | 2 +- progress.md | 37 +++++++++++++++++++++++++++++++++++++ 9 files changed, 98 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index a8ad608..ec367a0 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Python 3.12 / Django 5.2 LTS + DRF / django-admin / 用户端 Django 模板 SSR ## 当前状态 -Phase 2 计费核心已完成，Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端已完成 T-501~T-505，Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档，Phase 6 已完成 T-601 可用别名发现、T-602/T-603 django-admin 中文化、T-604 中文敏感词本地过滤、T-605 免邮箱验证策略落地、T-606 公开首页 + 客户端下载入口、T-607 桌面端最新版本检查接口、T-608 新用户注册赠送 100 点试用点数、T-609 桌面端版本强制更新标记、T-610 首页导入模板下载入口、T-611 用户端品牌名统一为“虾皮圈”、T-612 生图同步接口止血、T-613 抽生成核心 service、T-614 生图异步任务化接口、T-615 旧同步生图接口遥测 / 弃用口径、T-616 生图失败自动重试 2 次与 T-617 桌面端版本文件大小字段。用户可通过公开首页进入注册、登录、下载客户端和下载导入模板；新用户注册后经计费层自动获得 100 点并写注册赠点流水；登录后可扫码充值并轮询到账，生成 / 删除（吊销）API Key，查看余额、充值总额、分页充值记录、分页点数记录与可用模型；桌面端可匿名请求最新客户端版本 JSON，并读取 `release.force_update` 判断是否必须升级、读取 `release.size_bytes` 校验安装包大小；新版桌面端可用异步生图提交 / 轮询接口，旧同步生图接口继续兼容并写结构化用量日志；运营可在 django-admin 检索用户、钱包、API Key、计费规则、汇率、充值订单、点数流水、注册赠点记录、调用记录、图片生成任务、客户端发布版本和导入模板，并通过计费层带原因手工调点。生产侧仍需补真实支付回调到账闭环，并按日志观察旧同步生图接口迁移进度。详见 [`docs/current-state.md`](docs/current-state.md)。 +Phase 2 计费核心已完成，Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端已完成 T-501~T-505，Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档，Phase 6 已完成 T-601 可用别名发现、T-602/T-603 django-admin 中文化、T-604 中文敏感词本地过滤、T-605 免邮箱验证策略落地、T-606 公开首页 + 客户端下载入口、T-607 桌面端最新版本检查接口、T-608 新用户注册赠送 100 点试用点数、T-609 桌面端版本强制更新标记、T-610 首页导入模板下载入口、T-611 用户端品牌名统一为“虾皮圈”、T-612 生图同步接口止血、T-613 抽生成核心 service、T-614 生图异步任务化接口、T-615 旧同步生图接口遥测 / 弃用口径、T-616 生图失败自动重试 2 次、T-617 桌面端版本文件大小字段与 T-618 客户端发布版本后台必填校验元数据。用户可通过公开首页进入注册、登录、下载客户端和下载导入模板；新用户注册后经计费层自动获得 100 点并写注册赠点流水；登录后可扫码充值并轮询到账，生成 / 删除（吊销）API Key，查看余额、充值总额、分页充值记录、分页点数记录与可用模型；桌面端可匿名请求最新客户端版本 JSON，并读取 `release.force_update` 判断是否必须升级、读取 `release.size_bytes` 校验安装包大小；新版桌面端可用异步生图提交 / 轮询接口，旧同步生图接口继续兼容并写结构化用量日志；运营可在 django-admin 检索用户、钱包、API Key、计费规则、汇率、充值订单、点数流水、注册赠点记录、调用记录、图片生成任务、客户端发布版本和导入模板，客户端发布版本新增 / 编辑时必须填写 SHA256 与文件大小，并通过计费层带原因手工调点。生产侧仍需补真实支付回调到账闭环，并按日志观察旧同步生图接口迁移进度。详见 [`docs/current-state.md`](docs/current-state.md)。 > ⚠️ 涉及资金/点数。改动充值、扣费、退款、对账相关代码前，先读 [`docs/05-coding-rules.md`](docs/05-coding-rules.md) 第 8 节与 [`docs/04-architecture.md`](docs/04-architecture.md) 第四节计费时序。 diff --git a/apps/portal/admin.py b/apps/portal/admin.py index a82b83d..cad5a0f 100644 --- a/apps/portal/admin.py +++ b/apps/portal/admin.py @@ -1,10 +1,23 @@ +from django import forms from django.contrib import admin from .models import DownloadRelease, ImportTemplate +class DownloadReleaseAdminForm(forms.ModelForm): + class Meta: + model = DownloadRelease + fields = "__all__" + + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + self.fields["sha256"].required = True + self.fields["size_bytes"].required = True + + @admin.register(DownloadRelease) class DownloadReleaseAdmin(admin.ModelAdmin): + form = DownloadReleaseAdminForm list_display = ( "platform", "version", diff --git a/apps/portal/tests.py b/apps/portal/tests.py index 095b41f..c0ec16a 100644 --- a/apps/portal/tests.py +++ b/apps/portal/tests.py @@ -416,6 +416,41 @@ class PortalAccountFlowTests(TestCase): self.assertFalse(old_release.is_current) self.assertTrue(new_release.is_current) + def test_download_release_admin_requires_sha256_and_size_bytes(self): + form_class = admin.site._registry[DownloadRelease].form + base_data = { + "platform": DownloadRelease.Platform.WINDOWS, + "version": "1.2.3", + "external_url": "https://download.example.com/cmhub-1.2.3.zip", + "release_notes": "发布说明", + } + + missing_sha256_form = form_class(data={**base_data, "size_bytes": "123456"}) + missing_size_form = form_class(data={**base_data, "sha256": "a" * 64}) + + self.assertFalse(missing_sha256_form.is_valid()) + self.assertIn("sha256", missing_sha256_form.errors) + self.assertFalse(missing_size_form.is_valid()) + self.assertIn("size_bytes", missing_size_form.errors) + + def test_download_release_admin_saves_valid_release_metadata(self): + form_class = admin.site._registry[DownloadRelease].form + form = form_class( + data={ + "platform": DownloadRelease.Platform.WINDOWS, + "version": "1.2.3", + "external_url": "https://download.example.com/cmhub-1.2.3.zip", + "sha256": "b" * 64, + "size_bytes": "123456", + "release_notes": "发布说明", + } + ) + + self.assertTrue(form.is_valid(), form.errors) + release = form.save() + self.assertEqual(release.sha256, "b" * 64) + self.assertEqual(release.size_bytes, 123456) + def test_import_template_only_keeps_one_current(self): old_template = self.create_import_template( name="旧模板", diff --git a/docs/04-architecture.md b/docs/04-architecture.md index c935f62..29305d1 100644 --- a/docs/04-architecture.md +++ b/docs/04-architecture.md @@ -224,7 +224,7 @@ CREATE TABLE import_template ( ); ``` -T-102 已实现 `AiModel` / `ModelAlias` 的 Django models、admin、迁移与别名解析。T-103 已补 `AiConfigAuditLog`，admin 里保存/删除模型配置或能力别名时自动写审计日志。T-202 已实现 `PricingRule` / `ExchangeRate` 与 `apps.billing.pricing` 计算函数：定价按 `operation_type + alias + resolution` 查 active 规则，优先 exact resolution，再回退到空 resolution 默认价；缺规则抛 `NoPricingRuleError(code="no_pricing_rule")`。T-203 已实现 `apps.billing.services`：`precharge_call()` 锁 `UserWallet` 行预扣并写 pending 调用与 consume 流水；`mark_call_success()` 确认成功不再改余额；`refund_call_points()` 锁调用记录并幂等退点，写 refund 流水。T-401 已在同一计费层新增 `adjust_wallet_points()`，供 admin 手工调点使用。T-606/T-609/T-617 已实现 `DownloadRelease`，admin 可上传安装包或填写 `external_url`、标记当前版本、配置是否强制更新和文件大小字节数；`external_url` 优先于 `file.url`，每平台仅一个当前版本由模型 `save()` 在事务内把同平台旧 current 置为 false。T-610 已新增 `ImportTemplate`，admin 可上传导入模板或填写 `external_url` 并标记当前模板；`external_url` 优先于 `file.url`，当前模板互斥同样由应用层事务处理，不使用 MySQL 不支持的条件唯一约束。T-607/T-609/T-617 版本检查接口只读取 `DownloadRelease(platform, is_current=True)`；响应 URL 是外部可访问 URL，不暴露本地 `MEDIA_ROOT`，并把 `force_update` 和 `size_bytes` 作为公开发布元数据返回。导入模板下载不新增对外 JSON API，首页直接渲染当前模板下载链接。默认别名唯一性由 model validation、admin 与导入器保证；MySQL 不支持通用 partial unique index，若后续要强制数据库层默认别名唯一，可另评估触发器或约束表。 +T-102 已实现 `AiModel` / `ModelAlias` 的 Django models、admin、迁移与别名解析。T-103 已补 `AiConfigAuditLog`，admin 里保存/删除模型配置或能力别名时自动写审计日志。T-202 已实现 `PricingRule` / `ExchangeRate` 与 `apps.billing.pricing` 计算函数：定价按 `operation_type + alias + resolution` 查 active 规则，优先 exact resolution，再回退到空 resolution 默认价；缺规则抛 `NoPricingRuleError(code="no_pricing_rule")`。T-203 已实现 `apps.billing.services`：`precharge_call()` 锁 `UserWallet` 行预扣并写 pending 调用与 consume 流水；`mark_call_success()` 确认成功不再改余额；`refund_call_points()` 锁调用记录并幂等退点，写 refund 流水。T-401 已在同一计费层新增 `adjust_wallet_points()`，供 admin 手工调点使用。T-606/T-609/T-617/T-618 已实现 `DownloadRelease`，admin 可上传安装包或填写 `external_url`、标记当前版本、配置是否强制更新和文件大小字节数；T-618 起 admin 新增 / 编辑发布版本时 `sha256` 与 `size_bytes` 必填，但数据库仍保留空值兼容历史记录；`external_url` 优先于 `file.url`，每平台仅一个当前版本由模型 `save()` 在事务内把同平台旧 current 置为 false。T-610 已新增 `ImportTemplate`，admin 可上传导入模板或填写 `external_url` 并标记当前模板；`external_url` 优先于 `file.url`，当前模板互斥同样由应用层事务处理，不使用 MySQL 不支持的条件唯一约束。T-607/T-609/T-617 版本检查接口只读取 `DownloadRelease(platform, is_current=True)`；响应 URL 是外部可访问 URL，不暴露本地 `MEDIA_ROOT`，并把 `force_update` 和 `size_bytes` 作为公开发布元数据返回。导入模板下载不新增对外 JSON API，首页直接渲染当前模板下载链接。默认别名唯一性由 model validation、admin 与导入器保证；MySQL 不支持通用 partial unique index，若后续要强制数据库层默认别名唯一，可另评估触发器或约束表。 > 可选增强（接口预留、MVP 不实现）：`account_alias_permission`（按账号授权可用别名，防止调用方点用未授权/昂贵模型）；别名按比例分流到多个模型（灰度/AB/故障转移）。适配器接口需为此留口子。 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 1d90690..21fdba4 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -97,6 +97,7 @@ | T-616 | 生图失败自动重试 2 次 | T-614, T-615, T-203 | 给异步生图 worker 增加临时性上游失败自动重试，降低 `api.vectorengine.ai` 偶发 `Read timed out` 对用户的失败率。**业务口径**：“2 次重试”定义为第 1 次正常执行 + 失败后最多再重试 2 次，即最多 3 次上游调用；提交阶段仍只预扣一次。**只重试临时性错误**：`upstream_timeout`、网络连接错误、上游 502/503/504 等；不重试 `content_blocked`、`insufficient_points`、`no_pricing_rule`、模型/别名配置不可用、参数错误、Provider 配置错误等确定性错误。**数据结构**：复用现有 `attempt_count` 表示已开始执行次数；新增 `next_attempt_at`（允许下次抢占时间）和必要的 metadata-only admin 展示；如需记录最后一次错误，继续使用 `error_code` / `error_message`，不得保存 provider raw。**状态机**：`queued -> running(attempt_count+1)`；若成功则 `succeeded` 并确认已预扣调用；若可重试失败且 `attempt_count < 3`，任务回到 `queued`、设置 `next_attempt_at=now+backoff`、保留 `CallRecord.pending`、不退点；若不可重试或已到最终次数，才 `failed` 并调用计费层幂等退点。**worker 抢任务**：只抢 `status=queued` 且 `next_attempt_at IS NULL OR next_attempt_at <= now` 的任务；避免 66 worker 立即反复打爆上游。**配置**：新增 `IMAGE_TASK_MAX_RETRIES=2`、`IMAGE_TASK_RETRY_BACKOFF_SECONDS=10,30`（或等价配置），同步 `.env.example`、`env.md`、`deployment.md`；生产要提醒最坏耗时约 `上游硬截止 * 3 + backoff`，桌面端轮询超时需覆盖。**接口兼容**：轮询响应可新增可选字段 `attempt_count`、`max_attempts`、`next_attempt_at`，但不得删除既有字段；旧客户端忽略新字段仍可工作。**日志**：扩展 `event=image_task_processed`，包含 `attempt`、`max_attempts`、`retrying`、`next_attempt_at`、`duration_ms`、`error_code`，不得记录 prompt、base64、provider raw 或密钥。**账务验收**：第 1/2 次 `upstream_timeout` 回到 queued 且不退点；第 3 次成功只扣一次并成功确认；连续 3 次失败只退一次；非重试错误立即失败并只退一次；幂等提交仍返回同一 task，不重复预扣；reaper 与迟到 worker 不得把已最终失败/已退款任务改回成功。**测试**：覆盖上述账务、状态机、backoff 抢占、轮询新增字段兼容、worker 日志字段和敏感信息不泄露；`makemigrations` / `migrate` / `check` / 目标测试 / `init` 通过并在 `../progress.md` 留证据 | DONE | | T-617 | 桌面端版本检查接口增加文件大小字段 | T-607, T-609 | 在 `GET /api/v1/client/releases/latest?platform=windows` 的当前版本响应中，为 `release` 对象新增 `size_bytes` 字段，用于桌面端下载后比对文件大小。**接口兼容**：只新增字段，不删除既有 `version` / `download_url` / `sha256` / `release_notes` / `force_update` / `published_at`；无当前版本或无下载地址时仍返回 `release:null`，不返回顶层 `size_bytes`。**数据来源**：`DownloadRelease` 新增 `size_bytes` 可空正整数字段，单位字节，django-admin 可填写并在列表展示；老数据为空时接口返回 `null`，客户端只在值为正整数时做大小校验。**安全**：接口仍公开匿名只读，不读取用户、不扣点、不暴露后台 ID、本地文件路径或内部状态。**文档**：同步 `api.md`、`routes.md`、`04-architecture.md`、`02-requirements.md`、`current-state.md`。**测试**：覆盖有值返回整数、未配置返回 `null`、未发布响应不返回顶层字段、响应字段白名单更新、admin 字段可见；`makemigrations --check` / `check` / 目标测试通过并在 `../progress.md` 留证据 | DONE | +| T-618 | 客户端发布版本后台必填文件校验元数据 | T-617 | 把 django-admin 里 `DownloadRelease` 的 `sha256` 和 `size_bytes` 改为必填，避免运营发布客户端安装包时漏填校验元数据，导致桌面端无法完整校验下载文件。**范围**：本任务只要求 admin 后台保存时必填；为兼容历史数据和现有 API 合约，第一步不直接把数据库字段改成 `NOT NULL`，`size_bytes` 仍允许旧记录为空，API 暂保持可返回 `null`；若后续要数据库级强约束，需先单独回填全量历史发布记录再做迁移。**实现**：`DownloadReleaseAdmin` 已挂专用 `ModelForm`，将 `sha256`、`size_bytes` 设为 required，并保留 `sha256` 64 位十六进制校验、`size_bytes >= 1` 校验；admin 新增 / 编辑保存时未填会显示字段级错误，不写库。**生产数据**：上线后必须补齐当前 `windows` 发布版本的 `size_bytes`，再验证 `/api/v1/client/releases/latest?platform=windows` 返回正整数 `release.size_bytes`；已有 `sha256` 继续保留并核对。**兼容性**：不删除既有 API 字段，不改变无当前版本时的 `release:null`；非 admin 的历史数据、迁移和只读接口不应因空值直接 500。**文档**：同步 `api.md`、`04-architecture.md`、`routes.md`、`current-state.md` 和 `progress.md` 的发布校验口径。**测试**：已覆盖 admin 表单缺 `sha256` / 缺 `size_bytes` 拒绝保存、合法 `sha256 + size_bytes` 可保存、API 仍能读取历史空值记录、当前版本补齐后接口返回正整数；`check` / `makemigrations --check` / 目标测试通过并在 `../progress.md` 留证据 | DONE | ## 里程碑 @@ -113,6 +114,7 @@ - M11：生图异步任务化（先止血、后共享 core、再新老接口共存并观察旧路用量，T-612~T-615）。 - M12：生图失败自动重试（T-616）。 - M13：桌面端版本文件大小校验元数据（T-617）。 +- M14：客户端发布版本后台必填校验元数据（T-618）。 ## 待办池（Backlog） diff --git a/docs/api.md b/docs/api.md index d8b55b3..e083328 100644 --- a/docs/api.md +++ b/docs/api.md @@ -138,9 +138,9 @@ GET /api/v1/client/releases/latest?platform=windows } ``` -字段说明：`force_update` 为布尔值，表示桌面端是否必须升级到该版本；未勾选时返回 `false`。`size_bytes` 为整数或 `null`，单位字节；后台未填写时返回 `null`，客户端应只在该值为正整数时校验下载后的本地文件大小。客户端可先做版本号比较，再按 `force_update=true` 阻止继续使用旧版本或进入强制升级流程，下载完成后同时校验 `size_bytes` 和 `sha256`。 +字段说明：`force_update` 为布尔值，表示桌面端是否必须升级到该版本；未勾选时返回 `false`。`size_bytes` 为整数或 `null`，单位字节；T-618 起 django-admin 新增 / 编辑客户端发布版本时要求填写 `sha256` 和 `size_bytes`，但历史记录或非 admin 导入数据仍可能为空，客户端应只在该值为正整数时校验下载后的本地文件大小。客户端可先做版本号比较，再按 `force_update=true` 阻止继续使用旧版本或进入强制升级流程，下载完成后同时校验 `size_bytes` 和 `sha256`。 -要点：接口只查 `DownloadRelease(platform, is_current=True)`；`download_url` 优先使用 `external_url`，否则用 `file.url` 生成绝对 HTTPS URL；`published_at` MVP 可使用 `DownloadRelease.updated_at`；`force_update` 使用后台发布版本上的布尔配置，默认 `false`；`size_bytes` 使用后台填写的安装包字节数，可为空。响应不得包含本地 `MEDIA_ROOT`、文件系统路径、后台 ID、`is_current`、用户信息、API Key、模型配置或任何密钥字段。成功和“暂未发布”均返回 HTTP 200，方便桌面端静默检查；非法平台返回 `400 bad_request`。无当前版本或当前版本没有下载地址时返回 `release:null`，不返回独立的 `force_update` / `size_bytes` 顶层字段。 +要点：接口只查 `DownloadRelease(platform, is_current=True)`；`download_url` 优先使用 `external_url`，否则用 `file.url` 生成绝对 HTTPS URL；`published_at` MVP 可使用 `DownloadRelease.updated_at`；`force_update` 使用后台发布版本上的布尔配置，默认 `false`；`size_bytes` 使用后台填写的安装包字节数，可为空以兼容历史记录。响应不得包含本地 `MEDIA_ROOT`、文件系统路径、后台 ID、`is_current`、用户信息、API Key、模型配置或任何密钥字段。成功和“暂未发布”均返回 HTTP 200，方便桌面端静默检查；非法平台返回 `400 bad_request`。无当前版本或当前版本没有下载地址时返回 `release:null`，不返回独立的 `force_update` / `size_bytes` 顶层字段。 ### `POST /api/v1/generate/title` diff --git a/docs/current-state.md b/docs/current-state.md index fee1b15..b986e7a 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -11,12 +11,14 @@ ## 当前快照 -- 日期：2026-07-09 -- 阶段：Phase 6 增强（MVP 后）；Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化已完成，Phase 5 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档已完成，Phase 6 T-601 可用别名发现、T-602 django-admin 中文化第 1-3 层、T-603 django-admin 字段级中文化、T-604 中文敏感词本地过滤、T-605 免邮箱验证策略落地、T-606 公开首页 + 客户端下载入口、T-607 桌面端最新版本检查接口、T-608 新用户注册赠送 100 点试用点数、T-609 桌面端版本检查接口增加强制更新标记、T-610 首页导入模板下载入口、T-611 用户端品牌名统一为虾皮圈、T-612 生图同步接口止血、T-613 抽生成核心 service、T-614 生图异步任务化接口、T-615 旧同步生图接口遥测 / 弃用口径、T-616 生图失败自动重试 2 次与 T-617 桌面端版本文件大小字段已完成；后续仍需处理真实支付回调到账闭环、客户端下载包发布和生产侧旧同步接口用量观察 +- 日期：2026-07-13 +- 阶段：Phase 6 增强（MVP 后）；Phase 3 对外 API 与充值已完成到 T-306，Phase 4 用户端 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化已完成，Phase 5 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档已完成，Phase 6 T-601 可用别名发现、T-602 django-admin 中文化第 1-3 层、T-603 django-admin 字段级中文化、T-604 中文敏感词本地过滤、T-605 免邮箱验证策略落地、T-606 公开首页 + 客户端下载入口、T-607 桌面端最新版本检查接口、T-608 新用户注册赠送 100 点试用点数、T-609 桌面端版本检查接口增加强制更新标记、T-610 首页导入模板下载入口、T-611 用户端品牌名统一为虾皮圈、T-612 生图同步接口止血、T-613 抽生成核心 service、T-614 生图异步任务化接口、T-615 旧同步生图接口遥测 / 弃用口径、T-616 生图失败自动重试 2 次、T-617 桌面端版本文件大小字段与 T-618 客户端发布版本后台必填校验元数据已完成；后续仍需处理真实支付回调到账闭环、客户端下载包发布和生产侧旧同步接口用量观察 - 技术栈：系统 Python 3.12.3 + Django 5.2.15 + DRF 3.16.1 + django-allauth 65.18.0 + PyMySQL 1.1.3 + cryptography 49.0.0 + requests 2.34.2 + ahocorapy 1.6.2 + wechatpayv3 2.0.2 + python-alipay-sdk 3.4.0 + django-admin；MySQL 8.4 已接入 settings，并支持 `MYSQL_CONNECT_TIMEOUT` / `MYSQL_READ_TIMEOUT` / `MYSQL_WRITE_TIMEOUT`；用户端已用 Django 模板 SSR + Bootstrap + allauth 落地注册登录；生产部署口径为 VPS / 宝塔 + Nginx + Gunicorn(gthread) + systemd；详见 `03-tech-stack.md` 与 `deployment.md` - 生产代码：已有最小 Django 工程骨架：`manage.py`、`config/`；T-002 已创建 `apps/users|portal|billing|ai|api`；T-003 已把自定义 `User` 注册进 django-admin；T-004 已完成 email 唯一性、init 版本断言、app 顺序、`.env.example` 与 `pyproject.toml`；T-101 已新增 `apps/ai/providers/`（Provider 接口、注册表、chat/gemini/images/images_edits 适配器）；T-102 已新增 `AiModel` / `ModelAlias`、Fernet 加密密钥存储、别名解析、admin 配置页、`import_ai_models` 导入命令；T-103 已新增 `AiConfigAuditLog` 审计表、admin 只读页面和后台保存/删除审计 hook；T-104/T-105 已完成录制 title/image smoke 与审核修补；T-201 已新增 `UserWallet` / `ApiKey`、`PointsLedger` / `CallRecord`、对应 admin 与迁移；T-202 已新增 `PricingRule` / `ExchangeRate`、`apps.billing.pricing` 计费计算函数、admin 配置页与迁移；T-203 已新增 `apps.billing.services`，实现并发安全预扣、成功确认与幂等失败退点；T-204 已新增 `billing.0003_pointsledger_unique_ledger_change_type_per_call`，用 MySQL 可落地的 `ref_call + change_type` 复合唯一约束兜底防重复 refund；T-301 已新增 `apps.api.authentication.ApiKeyAuthentication` 与 `ExternalApiView`；T-302 已新增生成接口编排、序列化器、图片本地存储和 `/api/v1/generate/title|image` 路由；T-303 已新增 `apps.billing.services.get_balance_snapshot()` 与 `/api/v1/balance` 余额查询接口；T-304 已新增 `RechargeOrder`、充值回调验签适配器、幂等入账服务、微信/支付宝回调路由与迁移 `billing.0004_rechargeorder_and_more`；T-305 已新增 `create_recharge_order()`、微信/支付宝扫码下单 mock/SDK 入口、`/api/v1/recharge/create` 与 `/api/v1/recharge/status`；T-306 已新增 `apps.api.throttles`、`apps.api.exceptions`、`REST_FRAMEWORK` 安全默认认证、生成/认证失败限流、`image_url` SSRF 防护与响应大小上限、充值单笔金额上限；T-501/T-608 已接入 allauth 注册登录路径，注册成功后 adapter 调用 `grant_signup_bonus()` 经 billing 一次性发放 100 点并写 `signup_bonus` 流水，新增 `SignupBonusGrant(user UNIQUE)` 幂等标记、admin 只读检索和 `billing.0007` 迁移；T-502 已新增 `/apikeys`、API Key 创建表单、列表页和删除（吊销）动作，生成后明文只显示一次，列表只显示 prefix；T-503/T-608 已扩展 `/dashboard` 为个人中心汇总，并新增 `/records/recharge` 充值记录与 `/records/usage` 点数记录，只读展示当前用户数据和注册赠点 / 消费 / 退款流水；T-504 已新增 `/recharge` 页面、`RechargeCreateForm`、充值导航入口和轮询脚本，页面创建 pending 订单、展示二维码票据、轮询 `/api/v1/recharge/status`，订单 paid 后刷新余额；T-505 已把 Bootstrap 5 CSS 与 qrcode.js vendoring 到 `apps/portal/static/portal/vendor/`，页面不再依赖 jsdelivr，并把充值记录 / 点数记录改为 Django `Paginator` 分页；T-401 已新增 `adjust_wallet_points()` 手工调点服务、钱包 admin 专用调点表单与模板，后台可管理/检索用户、钱包、API Key（脱敏）、计费规则、汇率、充值订单、点数流水、注册赠点记录和调用记录，流水/订单/调用记录保持只读；T-402 已新增 `docs/mvp-acceptance.md`，按 P0 验收矩阵记录 MVP 完整验收结论、测试证据和已知限制；T-403 已新增 `docs/deployment.md` 与 `requirements-production.txt`，并在 settings 中补齐 `STATIC_ROOT`、`CSRF_TRUSTED_ORIGINS`、共享 `CACHES`、HTTPS cookie、proxy SSL、HSTS 环境变量与 `ACCOUNT_SIGNUP_RATE_LIMIT` 注册限流配置；T-601 已新增 `apps.ai.catalog.get_public_model_catalog()`、`GET /api/v1/models` 与 portal `/models` 只读页面，只展示 active 可调用别名、能力、是否需要原图和点数单价，不解密 provider key，不暴露底层 SKU / URL / key / `extra_body`；T-604 已新增 `apps.moderation`、`SensitiveWord` 模型/admin/迁移、keyword provider、归一化管线和共享 cache 版本失效，生成接口已改为 prompt 先审再读取图片/计费/扣点/调上游；T-606 已新增公开首页 `/`、`DownloadRelease` 模型/admin/迁移、首页 SSR 模板、共享 `portal/brand.css`，并把现有 portal 页面套入同一套品牌 token；T-607/T-609 已新增 `ClientLatestReleaseView` 与 `/api/v1/client/releases/latest`，公开匿名返回当前客户端版本 JSON，`release.force_update` 表示该版本是否强制升级；`portal.0002_downloadrelease_force_update` 已给 `DownloadRelease` 增加 `force_update` 字段，admin 可编辑和筛选；T-610 已新增 `ImportTemplate` 模型/admin/迁移 `portal.0003_importtemplate`，首页读取当前模板并在“下载客户端”旁展示“下载导入模板”，本地文件 URL 转为当前站点绝对 URL，`external_url` 优先；T-611 已把用户端 portal 可见品牌名统一为“虾皮圈”，包括页面标题、顶部导航、首页 H1、用户端“虾皮圈 API Key”文案和 allauth 邮件模板；T-612 已新增 `AI_IMAGE_UPSTREAM_DEADLINE_SECONDS`，生图 Provider 上游请求和上游返回图片 URL 下载会按 `min(AiModel.timeout_seconds 或分辨率默认值, 硬截止)` 控制读取超时，超时返回 `upstream_timeout` 并走既有失败退点路径；T-613 已把旧同步生成链路抽成 `GenerationInput`、`prepare_generation()`、`precharge_generation()`、`execute_precharged_generation()` 与 `GenerationResult`，旧 view 只负责 serializer 和异常转 HTTP，后续异步 worker 可复用已预扣执行 / 确认 / 退点阶段。 - T-614/T-616 生产代码补充：已新增 `ImageGenerationTask` 与 `api.0001_initial`，新增 `POST /api/v1/generate/image/tasks`、`GET /api/v1/generate/image/tasks/{task_id}`、`apps.api.image_tasks` 任务服务、`run_image_tasks` management command 和只读 admin；异步提交支持 `Idempotency-Key` 去重 / 冲突检测，worker 使用 DB 任务表、租约、心跳与 reaper，成功返回 cmhub 托管 URL；T-616 已通过 `api.0002_imagegenerationtask_next_attempt_at_and_more` 增加 `next_attempt_at` 与 `(status, next_attempt_at)` 索引，临时性 `upstream_timeout` / `upstream_error` 默认最多重试 2 次，重试期间不退点，最终失败 / 僵任务才走计费层幂等退款。 - T-617 生产代码补充：`DownloadRelease` 已新增 `size_bytes` 可空正整数字段和迁移 `portal.0004_downloadrelease_size_bytes`，django-admin 可填写并在列表展示；`GET /api/v1/client/releases/latest` 的 `release` 对象新增 `size_bytes`，有值返回整数，未配置返回 `null`，未发布时仍只返回 `release:null`。 +- T-618 生产代码补充：`DownloadReleaseAdmin` 已挂专用 `ModelForm`，后台新增 / 编辑客户端发布版本时 `sha256` 与 `size_bytes` 必填；数据库字段仍兼容历史空值，API 仍可读取历史 `size_bytes=null` 记录。 +- 最新验证：T-618 客户端发布版本后台必填文件校验元数据已验证 `.\init.ps1` 开工前通过；`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 在 MySQL 条件唯一约束上的既有 `models.W036` 警告。 - 最新验证：T-617 桌面端版本文件大小字段已验证 `py -3.12 manage.py makemigrations --check --dry-run` 通过，No changes detected；`py -3.12 manage.py check` 通过，0 issues；`py -3.12 manage.py test apps.api.tests.ClientLatestReleaseApiTests --keepdb --noinput --verbosity 2` 通过，12 tests OK，覆盖 `size_bytes` 有值、未配置为 `null`、未发布不返回顶层字段、响应字段白名单和 admin 字段可见；`py -3.12 manage.py migrate portal --noinput` 120 秒超时，但 `py -3.12 manage.py showmigrations portal` 确认 `portal.0004_downloadrelease_size_bytes` 已应用，且无残留 migrate 进程。测试期仍保留 allauth 在 MySQL 条件唯一约束上的既有 `models.W036` 警告。 - T-614 实现取舍补充：worker 执行前会基于任务快照复跑 `prepare_generation()`，即复审 prompt 并重解析别名 / Provider / 定价；账务使用已预扣 `CallRecord.points_cost`，不会重复扣点。短队列下这是偏安全取舍，词库变更后排队任务仍可被拦截并退款；若后续队列积压或频繁切换模型，应单独做提交时模型配置快照。异步 submit 对 `image_base64` 只解码并保存输入文件，桌面端主链路推荐继续使用；`image_url` 会在 submit 阶段完成 SSRF 校验、远程下载和大小限制，可能阻塞提交请求，属于边缘兼容路径。 - T-615 生产代码补充：已新增 `apps.api.telemetry`，旧同步 `POST /api/v1/generate/image` 与新异步提交 `POST /api/v1/generate/image/tasks` 都写 `cmhub.api.generation_usage` 结构化日志事件 `generation_route_usage`；字段白名单为 `route_type`、API Key ID/前缀、`user_id`、`X-Client-Version`、别名、状态、耗时、错误码和 HTTP 状态，不记录 API Key 明文、prompt、图片 base64 或 provider raw。 @@ -66,9 +68,9 @@ 任务状态以 [`06-tasks.md`](06-tasks.md) 为准，历史执行记录见 [`../progress.md`](../progress.md)。 -- 已完成：T-001 初始化 Django + DRF 项目骨架；T-002 建立 apps 目录、自定义 User 与配置；T-003 接通 django-admin 与最小测试；T-004 Phase 0 骨架审核修补；T-101 Provider 适配器层 + 移植 cmbot 调用；T-102 AiModel + ModelAlias 模型 + 别名解析；T-103 配置变更审计；T-104 跑通一次录制标题生成；T-105 Phase 1 AI 层审核修补；T-201 User / UserWallet / ApiKey / PointsLedger / CallRecord 模型；T-202 PricingRule / ExchangeRate 模型 + 计费计算；T-203 并发安全扣点 / 退点；T-204 Phase 2 计费核心审核加固；T-301 API Key 鉴权；T-302 生成标题 / 图片接口；T-303 余额查询接口；T-304 充值回调；T-305 扫码充值下单 + 轮询；T-306 Phase 3 对外 API 安全加固；T-501 注册 / 登录（allauth）；T-502 API Key 自助管理页；T-503 个人中心 / 记录页；T-504 充值页（扫码 + 轮询到账）；T-505 Phase 4 用户端审核优化；T-401 运营后台完善；T-402 完整验收 MVP；T-403 部署 / 运行文档；T-601 可用别名发现；T-602 django-admin 中文化（第 1-3 层）；T-603 django-admin 中文化（第 4 层·字段级）；T-604 中文敏感词本地过滤；T-605 免邮箱验证策略落地；T-606 公开首页 + 客户端下载入口；T-607 桌面端最新版本检查接口；T-608 新用户注册赠送 100 点试用点数；T-609 桌面端版本检查接口增加强制更新标记；T-610 首页导入模板下载入口；T-611 用户端品牌名统一为虾皮圈；T-612 生图同步接口止血（上游硬截止 + 长请求池校准）；T-613 抽生成核心 service（计费+审核+上游共享 core）；T-614 生图异步任务化接口（提交+轮询，新增不动旧接口）；T-615 旧同步生图接口用量遥测 + 弃用口径；T-616 生图失败自动重试 2 次。 +- 已完成：T-001 初始化 Django + DRF 项目骨架；T-002 建立 apps 目录、自定义 User 与配置；T-003 接通 django-admin 与最小测试；T-004 Phase 0 骨架审核修补；T-101 Provider 适配器层 + 移植 cmbot 调用；T-102 AiModel + ModelAlias 模型 + 别名解析；T-103 配置变更审计；T-104 跑通一次录制标题生成；T-105 Phase 1 AI 层审核修补；T-201 User / UserWallet / ApiKey / PointsLedger / CallRecord 模型；T-202 PricingRule / ExchangeRate 模型 + 计费计算；T-203 并发安全扣点 / 退点；T-204 Phase 2 计费核心审核加固；T-301 API Key 鉴权；T-302 生成标题 / 图片接口；T-303 余额查询接口；T-304 充值回调；T-305 扫码充值下单 + 轮询；T-306 Phase 3 对外 API 安全加固；T-501 注册 / 登录（allauth）；T-502 API Key 自助管理页；T-503 个人中心 / 记录页；T-504 充值页（扫码 + 轮询到账）；T-505 Phase 4 用户端审核优化；T-401 运营后台完善；T-402 完整验收 MVP；T-403 部署 / 运行文档；T-601 可用别名发现；T-602 django-admin 中文化（第 1-3 层）；T-603 django-admin 中文化（第 4 层·字段级）；T-604 中文敏感词本地过滤；T-605 免邮箱验证策略落地；T-606 公开首页 + 客户端下载入口；T-607 桌面端最新版本检查接口；T-608 新用户注册赠送 100 点试用点数；T-609 桌面端版本检查接口增加强制更新标记；T-610 首页导入模板下载入口；T-611 用户端品牌名统一为虾皮圈；T-612 生图同步接口止血（上游硬截止 + 长请求池校准）；T-613 抽生成核心 service（计费+审核+上游共享 core）；T-614 生图异步任务化接口（提交+轮询，新增不动旧接口）；T-615 旧同步生图接口用量遥测 + 弃用口径；T-616 生图失败自动重试 2 次；T-617 桌面端版本检查接口增加文件大小字段；T-618 客户端发布版本后台必填文件校验元数据。 - 正在进行：无。 -- 待开始：无固定编号任务；后续按真实支付回调到账闭环、客户端发布和线上旧同步接口用量观察继续拆任务。 +- 待开始：后续按真实支付回调到账闭环、客户端发布和线上旧同步接口用量观察继续拆任务。 - 当前 blocker：支付商户真实密钥/证书与生产 SDK 依赖仍待提供；微信回调到账闭环仍需真实支付验收；真实 AI 标题生成已在线上跑通，图片生成慢 / 504 / 客户端超时风险已拆为 T-612~T-616 并完成工程侧处理。 - 下一个可领取任务：无固定编号任务；建议优先补真实支付回调到账闭环，其次处理客户端发布与生产旧同步接口用量观察。 diff --git a/docs/routes.md b/docs/routes.md index 9b3480b..b4e526d 100644 --- a/docs/routes.md +++ b/docs/routes.md @@ -57,7 +57,7 @@ T-614 已落地 `/api/v1/generate/image/tasks` 与 `/api/v1/generate/image/tasks | 模型配置 | AiModel | 维护上游模型（url/model/api_key[加密脱敏]/api_type/capabilities/timeout） | | 能力别名 | ModelAlias | 维护对外别名 → 具体模型的映射；换供应商在此改指向 | | 配置审计 | AiConfigAuditLog | 只读查看 AiModel / ModelAlias / 密钥变更：谁、何时、改了什么 | -| 客户端下载版本 | DownloadRelease | 上传安装包或填写外部下载地址，标记每个平台当前版本、是否强制更新和文件大小字节数；展示版本、SHA256、强制更新标记与发布说明 | +| 客户端下载版本 | DownloadRelease | 上传安装包或填写外部下载地址，标记每个平台当前版本、是否强制更新和文件大小字节数；新增 / 编辑时必须填写 SHA256 与文件大小字节数；展示版本、SHA256、强制更新标记与发布说明 | | 导入模板 | ImportTemplate | 上传导入模板或填写外部下载地址，标记当前模板；展示模板名称、SHA256 与说明 | ## 后台职责约定 diff --git a/progress.md b/progress.md index c8a1634..7c0792e 100644 --- a/progress.md +++ b/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`。