chengma/cmhub
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add client release force update flag

Browse Source
This commit is contained in:
QiuSW
2026-07-08 15:38:59 +08:00
parent 30d9df34eb
commit 6646c64a76
14 changed files with 130 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/04-architecture.md
+6 -5
View File
@@ -18,9 +18,9 @@
组件落位：
- **用户端层（Django 模板 SSR）**：公开首页、注册/登录（Django auth / allauth）、个人中心（余额/充值总额/充值记录/点数记录）、API Key 自助管理、发起扫码充值、模型目录与客户端下载入口。入口 `apps/portal/`，公开首页匿名可访问，其他自助页面用 session 鉴权。T-501/T-608 已落地 `/signup`、`/login`、`/logout` 与 `/dashboard`；注册成功后经计费层一次性发放 100 点试用点数，并写 `signup_bonus` 点数流水。T-502 已落地 `/apikeys`，用户可自助生成和删除（吊销）自己的 API Key，明文只显示一次，列表只显示 prefix。T-503/T-608 已扩展 `/dashboard` 并新增 `/records/recharge`、`/records/usage`，只读展示当前用户余额、充值订单、注册赠点与消费/退款流水。T-504 已落地 `/recharge`，用户可创建 pending 充值订单、查看二维码票据，并轮询订单状态；到账仍以服务端回调或主动查单入账后的本地订单状态为准。T-505 已把 Bootstrap/qrcode.js 改成本地 static 自托管，并把充值/点数记录页从固定切片改为分页。T-606 已把 `/` 改为公开首页，并新增 `DownloadRelease` 下载版本配置用于展示 Windows 客户端版本、下载地址、SHA256 与发布说明；T-607 已新增公开 JSON 版本检查接口给桌面端自动更新使用。
- **用户端层（Django 模板 SSR）**：公开首页、注册/登录（Django auth / allauth）、个人中心（余额/充值总额/充值记录/点数记录）、API Key 自助管理、发起扫码充值、模型目录与客户端下载入口。入口 `apps/portal/`，公开首页匿名可访问，其他自助页面用 session 鉴权。T-501/T-608 已落地 `/signup`、`/login`、`/logout` 与 `/dashboard`；注册成功后经计费层一次性发放 100 点试用点数，并写 `signup_bonus` 点数流水。T-502 已落地 `/apikeys`，用户可自助生成和删除（吊销）自己的 API Key，明文只显示一次，列表只显示 prefix。T-503/T-608 已扩展 `/dashboard` 并新增 `/records/recharge`、`/records/usage`，只读展示当前用户余额、充值订单、注册赠点与消费/退款流水。T-504 已落地 `/recharge`，用户可创建 pending 充值订单、查看二维码票据，并轮询订单状态；到账仍以服务端回调或主动查单入账后的本地订单状态为准。T-505 已把 Bootstrap/qrcode.js 改成本地 static 自托管，并把充值/点数记录页从固定切片改为分页。T-606 已把 `/` 改为公开首页，并新增 `DownloadRelease` 下载版本配置用于展示 Windows 客户端版本、下载地址、SHA256 与发布说明；T-607/T-609 已新增公开 JSON 版本检查接口给桌面端自动更新使用，并返回强制更新标记。
- **用户与账号层**：注册用户 `User`、点数钱包 `UserWallet`、`ApiKey`（一用户多把、哈希存储）。入口 `apps/users/`。
- **API 层（DRF）**：对外生成接口、余额查询、支付回调接收、扫码下单、公开版本检查接口。入口 `apps/api/`。生成/余额/模型目录这类对外业务 API **只认 API Key，不接受 Web session**；充值下单/状态查询属于用户端流程，走 Web session + CSRF；支付回调走平台验签；T-607 的客户端下载版本检查接口为公开只读例外，不需要 API Key，不读取用户、不扣点。
- **API 层（DRF）**：对外生成接口、余额查询、支付回调接收、扫码下单、公开版本检查接口。入口 `apps/api/`。生成/余额/模型目录这类对外业务 API **只认 API Key，不接受 Web session**；充值下单/状态查询属于用户端流程，走 Web session + CSRF；支付回调走平台验签；T-607/T-609 的客户端下载版本检查接口为公开只读例外，不需要 API Key，不读取用户、不扣点，`release.force_update` 仅表示当前发布版本是否强制升级。
- **计费层**：点数计算、原子扣减（锁 `UserWallet` 行）、退点、充值入账、流水记账。入口 `apps/billing/`。
- **AI 调用层（Provider Adapter 架构）**：对外只暴露稳定能力，内部用「能力别名 → 具体供应商适配器」解耦。入口 `apps/ai/`，适配器在 `apps/ai/providers/`。
- **内容安全层（本地敏感词 / 后续云审核）**：入口 `apps/moderation/`。T-604 只做 prompt 文本本地敏感词快筛，命中在扣点和调上游前返回 `content_blocked`；云内容安全、图片审核和输出审核保留扩展点，不在 T-604 范围。
@@ -49,7 +49,7 @@ T-305 已实现 `/api/v1/recharge/create` 与 `/api/v1/recharge/status`：两个
T-504 已实现用户端 `/recharge` 页面：GET 展示当前余额、充值表单、当前订单和最近充值；POST 经 `RechargeCreateForm` 校验金额与支付方式后复用 `create_recharge_order()` 创建 pending 订单并重定向到当前订单页，避免刷新重复下单；页面用本地 static 自托管的 qrcode.js 渲染 `code_url`，同时保留可复制支付票据兜底；浏览器每秒轮询 `/api/v1/recharge/status`，订单 paid 后刷新页面重新读取余额。页面不直接写 `UserWallet.points_balance` 或 `PointsLedger`。当 `PAYMENT_CALLBACK_MODE=mock` 时，页面必须醒目提示二维码为测试票据，不能用于微信/支付宝真实支付。当前因支付宝可信 IP 未配置，用户端表单暂只开放微信支付，底层支付宝 API / 回调 / SDK 路径保留。
T-306 已实现对外 API 安全加固：`download_image_input()` 在请求前校验 `image_url` 协议与解析后的 IP，只允许公网 `http` / `https`，拒绝私有、回环、链路本地、保留、组播、未指定地址；重定向由服务端手动跟随并逐跳重新校验，响应按 `IMAGE_URL_MAX_BYTES` 流式限长读取。`REST_FRAMEWORK` 全局默认认证为空、默认权限为 `IsAuthenticated`，外部 API 和用户端 session API 必须显式声明认证类；生成接口挂 `GenerateRateThrottle`，认证失败挂 IP 限流；充值下单通过 `RECHARGE_MAX_AMOUNT_CNY` 控制单笔上限。T-607 版本检查接口已显式使用 `AllowAny` / 空认证，且只返回公开发布元数据。
T-306 已实现对外 API 安全加固：`download_image_input()` 在请求前校验 `image_url` 协议与解析后的 IP，只允许公网 `http` / `https`，拒绝私有、回环、链路本地、保留、组播、未指定地址；重定向由服务端手动跟随并逐跳重新校验，响应按 `IMAGE_URL_MAX_BYTES` 流式限长读取。`REST_FRAMEWORK` 全局默认认证为空、默认权限为 `IsAuthenticated`，外部 API 和用户端 session API 必须显式声明认证类；生成接口挂 `GenerateRateThrottle`，认证失败挂 IP 限流；充值下单通过 `RECHARGE_MAX_AMOUNT_CNY` 控制单笔上限。T-607/T-609 版本检查接口已显式使用 `AllowAny` / 空认证，且只返回公开发布元数据和强制更新标记。
**计费层（`apps/billing`）**
@@ -98,7 +98,7 @@ T-306 已实现对外 API 安全加固：`download_image_input()` 在请求前
| PricingRule | 运营配置 | 操作类型 × **能力别名字符串**（+ 可选分辨率）→ 点数单价；不外键到具体 AiModel |
| ExchangeRate | 运营配置 | 金额 → 点数 的汇率（如 1 元 = N 点），按 `currency + effective_from` 取当前有效值 |
| SensitiveWord | 运营配置 | 本地敏感词快筛词库；word、normalized_word、category、action、is_active；T-604 MVP 仅支持 action=block |
| DownloadRelease | 运营配置 | 客户端下载版本；platform、version、file、external_url、sha256、is_current、release_notes、created_at、updated_at；每平台当前版本由应用层事务保存时互斥 |
| DownloadRelease | 运营配置 | 客户端下载版本；platform、version、file、external_url、sha256、is_current、force_update、release_notes、created_at、updated_at；每平台当前版本由应用层事务保存时互斥 |
关键事实：
@@ -196,13 +196,14 @@ CREATE TABLE download_release (
external_url VARCHAR(200) NOT NULL DEFAULT '', -- 有则优先，后续切 CDN/对象存储
sha256 VARCHAR(64) NOT NULL DEFAULT '',
is_current BOOLEAN NOT NULL DEFAULT FALSE,
force_update BOOLEAN NOT NULL DEFAULT FALSE, -- 当前版本是否强制升级
release_notes LONGTEXT NOT NULL,
created_at DATETIME(6) NOT NULL,
updated_at DATETIME(6) NOT NULL
);
```
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 已实现 `DownloadRelease`，admin 可上传安装包或填写 `external_url` 并标记当前版本；`external_url` 优先于 `file.url`，每平台仅一个当前版本由模型 `save()` 在事务内把同平台旧 current 置为 false。T-607 版本检查接口只读取 `DownloadRelease(platform, is_current=True)`，不新增表；响应 URL 是外部可访问 URL，不暴露本地 `MEDIA_ROOT`。默认别名唯一性由 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 已实现 `DownloadRelease`，admin 可上传安装包或填写 `external_url`、标记当前版本、配置是否强制更新；`external_url` 优先于 `file.url`，每平台仅一个当前版本由模型 `save()` 在事务内把同平台旧 current 置为 false。T-607/T-609 版本检查接口只读取 `DownloadRelease(platform, is_current=True)`；响应 URL 是外部可访问 URL，不暴露本地 `MEDIA_ROOT`，并把 `force_update` 作为公开发布元数据返回。默认别名唯一性由 model validation、admin 与导入器保证；MySQL 不支持通用 partial unique index，若后续要强制数据库层默认别名唯一，可另评估触发器或约束表。
> 可选增强（接口预留、MVP 不实现）：`account_alias_permission`（按账号授权可用别名，防止调用方点用未授权/昂贵模型）；别名按比例分流到多个模型（灰度/AB/故障转移）。适配器接口需为此留口子。