feat: add admin client policy control

docs/04-architecture.md

@@ -20,7 +20,7 @@
 
 - **用户端层（Django 模板 SSR）**：公开首页、注册/登录（Django auth / allauth）、个人中心（余额/充值总额/充值记录/点数记录）、API Key 自助管理、发起扫码充值、模型目录与客户端下载入口。入口 `apps/portal/`，公开首页匿名可访问，其他自助页面用 session 鉴权。T-501/T-608 已落地 `/signup`、`/login`、`/logout` 与 `/dashboard`；注册成功后经计费层一次性发放 10 点试用点数，并写 `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/T-617 已新增公开 JSON 版本检查接口给桌面端自动更新使用，并返回强制更新标记和安装包文件大小字节数。T-610 已在公开首页下载区增加导入模板下载入口，由后台 `ImportTemplate` 配置当前模板。
 - **用户与账号层**：注册用户 `User`、点数钱包 `UserWallet`、`ApiKey`（一用户多把、哈希存储）。入口 `apps/users/`。
-- **软件授权层**：蝦皮圈客户端设备、短期设备会话、套餐、权益、设备席位和授权审计。入口 `apps/licensing/`；T-624/T-625 建立设备观测及调用关联，T-626 建立套餐/权益/席位基础，T-630/T-632 已将产品专属授权切换为账号订阅三阶段模式；通用 API Key 或点数授权不变。
+- **软件授权层**：蝦皮圈客户端设备、短期设备会话、套餐、权益、设备席位、授权审计与客户端启动策略。入口 `apps/licensing/`；T-624/T-625 建立设备观测及调用关联，T-626 建立套餐/权益/席位基础，T-630/T-632 已将产品专属授权切换为账号订阅三阶段模式，T-636 增加全局客户端策略单例与审计；通用 API Key 或点数授权不变。
 - **API 层（DRF）**：对外生成接口、异步图片任务接口、余额查询、支付回调接收、扫码下单、公开版本检查接口。入口 `apps/api/`。生成/余额/模型目录这类对外业务 API **只认 API Key，不接受 Web session**；充值下单/状态查询属于用户端流程，走 Web session + CSRF；支付回调走平台验签；T-607/T-609/T-617 的客户端下载版本检查接口为公开只读例外，不需要 API Key，不读取用户、不扣点，`release.force_update` 仅表示当前发布版本是否强制升级，`release.size_bytes` 仅表示下载文件大小字节数。
 - **计费层**：点数计算、原子扣减（锁 `UserWallet` 行）、退点、充值入账、流水记账。入口 `apps/billing/`。
 - **AI 调用层（Provider Adapter 架构）**：对外只暴露稳定能力，内部用「能力别名 → 具体供应商适配器」解耦。入口 `apps/ai/`，适配器在 `apps/ai/providers/`。
@@ -48,7 +48,7 @@ T-629 已完成：`SoftwareOrder` 属于 `apps.licensing`，与 `RechargeOrder`
 
 T-630/T-632 已完成：蝦皮圈产品授权从设备凭证改为账号订阅。`evaluate_account_authorization(user, product_code)` 只计算数据库真实 `SoftwareEntitlement` 状态，不读取 `DeviceCredential`、`LicenseSeat` 或 `DeviceSession`；`evaluate_subscription_access()` 再按 `CMSHOPEE_SUBSCRIPTION_MODE=open|shadow|enforce` 计算最终访问结果。`open` 和 `shadow` 不写虚假权益，前者提供开发测试访问，后者保留访问并记录真实权益覆盖；`enforce` 才将无订阅/过期结果映射为 403。同一用户可从多台设备调用，过期设备会话不会阻断账号订阅；通用生成入口继续保持原 API Key + 点数语义。
 
-T-635 在公开版本检查接口顶层增加无账号上下文的 `client_policy`，由 `CMSHOPEE_CLIENT_SUBSCRIPTION_POLICY=off|observe|enforce` 和其带时区更新时间生成，成功及错误响应均 `Cache-Control: no-store`。这只控制新版客户端是否检查 / 展示会员门禁，不覆盖 `CMSHOPEE_SUBSCRIPTION_MODE` 的服务端授权；订阅状态接口新增 `real_entitlement_allowed`，仅真实 `active` / `grace` 权益为真，客户端强制门禁必须使用它而非 `open` / `shadow` 的兼容 `allowed`。
+T-635/T-636 在公开版本检查接口顶层增加无账号上下文的 `client_policy`，成功及错误响应均 `Cache-Control: no-store`。`get_published_client_subscription_policy()` 每次请求优先读取 `ClientSubscriptionPolicy(singleton_id=1)` 的 `mode + updated_at`，未创建该记录时才回退 `CMSHOPEE_CLIENT_SUBSCRIPTION_POLICY=off|observe|enforce` 及其带时区更新时间；因此后台保存后无进程缓存、无需重启。数据库单例有固定主键和 CHECK 约束，服务层事务内同时写 `ClientSubscriptionPolicyAudit`，admin 仅超级管理员可操作、审计只读。该策略只控制新版客户端是否检查 / 展示会员门禁，不覆盖 `CMSHOPEE_SUBSCRIPTION_MODE` 的服务端授权；订阅状态接口新增 `real_entitlement_allowed`，仅真实 `active` / `grace` 权益为真，客户端强制门禁必须使用它而非 `open` / `shadow` 的兼容 `allowed`。
 
 T-632 同时简化软件授权 admin：应用索引只展示“会员套餐” (`SoftwarePlan`) 与“用户会员” (`SoftwareEntitlement`)。软件订单、授权事件、设备观测和历史设备授权模型仍注册并保留直接管理地址、权限及历史数据，只是不出现在日常导航；该显示策略不改变数据库结构和授权判定。
 
@@ -125,6 +125,8 @@ T-619 多图理解继续复用上述 URL 下载器和逐跳 SSRF 校验，并额
 | SensitiveWord | 运营配置 | 本地敏感词快筛词库；word、normalized_word、category、action、is_active；T-604 MVP 仅支持 action=block |
 | DownloadRelease | 运营配置 | 客户端下载版本；platform、version、file、external_url、size_bytes、sha256、is_current、force_update、release_notes、created_at、updated_at；每平台当前版本由应用层事务保存时互斥 |
 | ImportTemplate | 运营配置 | 导入商品数据模板；name、file、external_url、sha256、is_current、notes、created_at、updated_at；当前模板由应用层事务保存时互斥 |
+| ClientSubscriptionPolicy | 全局运营配置 | T-636 客户端启动策略单例，固定 `singleton_id=1`，`mode=off|observe|enforce`、最后操作人和时间；仅在存在记录时覆盖 `.env` 兜底 |
+| ClientSubscriptionPolicyAudit | 配置审计 | 每次有效策略变更的前后模式、必填原因、操作人和时间；仅在策略详情页只读展示 |
 | ClientDevice | 客户端登记 | 用户、产品、版本化设备摘要、安装公钥摘要、平台、客户端版本、状态、首次/最后活跃时间；不保存原始机器标识或私钥；`(user, product_code, device_fingerprint)` 唯一 |
 | DeviceSession | 设备登记服务 | 设备、会话 token hash、过期/最后使用/吊销时间；明文只在登记响应出现一次 |
 | DeviceBindingAudit | 设备登记服务 | 用户、设备、来源 API Key、登记/会话/心跳等动作、原因、客户端版本、时间；只读审计 |
@@ -255,7 +257,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/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/T-635 版本检查接口只读取 `DownloadRelease(platform, is_current=True)` 与无状态环境配置；响应 URL 是外部可访问 URL，不暴露本地 `MEDIA_ROOT`，并把 `force_update`、`size_bytes` 和 `client_policy` 作为公开元数据返回。`client_policy` 有独立的配置更新时间且在 `release:null` 时仍返回，不读取用户、订阅、套餐或点数。导入模板下载不新增对外 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/T-635/T-636 版本检查接口只读取 `DownloadRelease(platform, is_current=True)` 与全局 `ClientSubscriptionPolicy`（无记录时读取环境兜底）；响应 URL 是外部可访问 URL，不暴露本地 `MEDIA_ROOT`，并把 `force_update`、`size_bytes` 和 `client_policy` 作为公开元数据返回。`client_policy` 有独立的配置更新时间且在 `release:null` 时仍返回，不读取用户、真实订阅权益、套餐、订单或点数。导入模板下载不新增对外 JSON API，首页直接渲染当前模板下载链接。默认别名唯一性由 model validation、admin 与导入器保证；MySQL 不支持通用 partial unique index，若后续要强制数据库层默认别名唯一，可另评估触发器或约束表。
 
 > 可选增强（接口预留、MVP 不实现）：`account_alias_permission`（按账号授权可用别名，防止调用方点用未授权/昂贵模型）；别名按比例分流到多个模型（灰度/AB/故障转移）。适配器接口需为此留口子。