# T-636 客户端订阅策略 django-admin 运营开关

## 背景

T-635 已经通过公开版本检查接口向新版 cmshopee 客户端发布启动订阅策略，
但策略只能通过修改 `.env` 后重启 Web / Generate 服务变更。该方式不适合日常
运营，也无法在 django-admin 中留下明确的变更原因和操作者。

客户端策略和 `CMSHOPEE_SUBSCRIPTION_MODE` 的服务端授权仍是两件事：前者只
决定新版客户端是否检查 / 展示会员门禁，后者才决定产品专属生成接口是否按真实
权益拦截。本任务不得混淆或合并这两套开关。

## 目标

1. 让超级管理员在 django-admin 中用单一枚举切换 `off`、`observe`、`enforce`。
2. 每次变更必须留存原因、操作者、前后值和时间。
3. 公开版本检查接口在下一次请求立即发布后台策略，无需重启服务。
4. 未配置后台策略时完全保留 T-635 `.env` 行为，保证上线不改变当前客户端。

## 实施范围

### 数据模型与策略来源

- 新增全局单例 `ClientSubscriptionPolicy`，仅保存一个固定主键记录；字段至少有
  `mode`、`updated_by`、`created_at`、`updated_at`。
- 模式只能是 `off|observe|enforce`，输出继续复用 T-635 的统一映射：
  `off -> false/false`、`observe -> true/false`、`enforce -> true/true`。
- 新增不可修改的策略审计记录，保存 `previous_mode`、`mode`、必填 `reason`、
  `changed_by`、`changed_at`。审计不保存 API Key、用户权益、点数、订单、prompt
  或图片。
- 迁移只创建空表，不写预置策略记录。策略解析顺序固定为：数据库单例存在时优先
  使用其 `mode + updated_at`；记录不存在时回退
  `CMSHOPEE_CLIENT_SUBSCRIPTION_POLICY` 与
  `CMSHOPEE_CLIENT_SUBSCRIPTION_POLICY_UPDATED_AT`。
- 公开接口每次请求读取单例，不使用进程内缓存；因此 admin 保存成功后下一次请求
  即生效。数据库不可用仍按既有 Django 请求失败语义处理，不得静默发布错误策略。

### django-admin

- 日常导航只增加“客户端订阅策略”一个入口；审计仅作为该详情页的只读 inline，
  不单独出现在导航。
- 仅超级管理员可新增或编辑；不允许删除。首次创建后禁止新增第二条记录。
- 表单除 `mode` 外必须填写“变更原因”。服务层负责事务内写单例与审计，禁止通过
  admin 直接 `save()` 绕过审计。
- 展示当前 `CMSHOPEE_SUBSCRIPTION_MODE` 为只读信息，明确它是服务端授权模式；
  本页不得修改该环境变量，也不得修改权益、套餐、席位、凭证、订单、钱包或点数。
- 相同模式不应制造伪变更审计；要求运营选择不同模式后再保存。

### API 与兼容

- `GET /api/v1/client/releases/latest?platform=windows` 顶层 `client_policy` 结构、
  `policy_version=1`、字段类型和 `Cache-Control: no-store` 保持 T-635 合约。
- 有发布、`release:null` 和无下载地址路径均使用同一策略来源；既有
  `force_update`、`size_bytes` 等发布字段不回归。
- 此接口仍匿名只读、无账号上下文，不读取 `SoftwareEntitlement`、套餐、点数、
  订单、API Key 或生成模型；新增的仅是全局策略配置读取。
- 不修改 `CMSHOPEE_SUBSCRIPTION_MODE`，不改变通用或专属生成接口、计费预扣 /
  确认 / 退款、支付回调、软件订单、异步图片任务或旧客户端行为。

## 部署与回滚

1. 备份生产应用和数据库，发布代码并执行 `migrate`；迁移不会创建策略记录。
2. 首次部署后确认 `.env` 兜底策略仍为 `off`，公开接口保持
   `subscription_check_enabled=false`、`subscription_enforcement_enabled=false`。
3. 超级管理员可创建单例并按 `off -> observe -> enforce` 灰度；每次保存立即以新的
   `updated_at` 发布，无需重启。
4. 需要紧急取消客户端门禁时，在后台将模式改为 `off`；若后台记录尚未创建，继续
   使用 `.env` 兜底。不要把此操作误认为取消服务端授权。
5. 若需恢复到纯 `.env` 来源，必须先在维护窗口以受控数据操作移除单例记录；本任务
   的 admin 不提供删除入口，避免误删和审计丢失。

## 验收条件

1. 无后台记录时三种合法 `.env` 配置保持 T-635 映射与启动校验。
2. 后台记录存在时优先于 `.env`；保存 `observe` / `enforce` 后下一次公开请求立即
   返回正确双布尔值与稳定、带时区的 `updated_at`。
3. 模型层和后台均不能创建第二条记录，后台不能删除；非超级管理员不能新增或编辑。
4. 每次有效变更都写一条只读审计，包含前后模式、非空原因、操作者和时间；相同模式
   被表单拒绝，不写伪审计。
5. 审计不出现在 admin 日常导航，策略页可只读查看历史；服务端授权模式只读展示。
6. 版本检查接口继续匿名、`Cache-Control: no-store`，且发布字段和无发布路径不回归；
   不查询或泄露用户、权益、套餐、点数、订单、API Key 或密钥。
7. 同步更新 `docs/api.md`、`docs/env.md`、`docs/deployment.md`、
   `docs/04-architecture.md`、`docs/current-state.md`、任务状态、`progress.md` 和
   Obsidian 客户端契约。
8. `makemigrations --check --dry-run`、`migrate`、`check`、目标 API / licensing /
   admin 测试、`init.ps1` 与 `git diff --check` 通过。

## 状态

DONE。代码、迁移、目标回归与生产部署均已完成。

## 实施结果

- 新增 `ClientSubscriptionPolicy` 与 `ClientSubscriptionPolicyAudit`，迁移
  `licensing.0006_client_subscription_policy` 只建空表。策略固定主键为 `1`，并由
  数据库 CHECK 约束拒绝第二个主键；没有预置记录，保留既有 `.env` 兜底。
- `get_published_client_subscription_policy()` 每次公开版本检查优先读取后台单例，
  用其 `updated_at` 发布原有 `client_policy` 结构；未创建记录时继续调用 T-635
  的环境配置校验。没有进程内缓存，后台保存后下一次请求立即生效。
- django-admin 新增“客户端订阅策略”入口：仅超级管理员可新增 / 编辑，不能删除；
  表单强制填写原因，服务层在事务内写策略和只读审计。策略详情显示当前服务端订阅
  模式，但不允许修改它；审计只作为 inline 展示，不增加导航噪音。
- 未改通用 / 专属生成、服务端订阅授权、用户权益、套餐、点数、支付、软件订单或
  异步图片任务。

## 生产部署

- 2026-07-28 已部署到 `185.216.248.75` / `https://cm.833729.com`，应用 revision
  为 `2171968`；发布归档 SHA256 为
  `f9c386125226813a5f679487832bda7f28474428bfe173f8a2a53b5e84f08a17`。
- 发布前备份位于 `/root/cmhub_deploy_backups/cmhub-before-t636-20260728_154417`；
  线上 `licensing.0006_client_subscription_policy` 已成功应用。
- 未创建 `ClientSubscriptionPolicy` 或审计记录，因此继续使用现有 `.env`
  `off` 兜底；公网接口返回 HTTP 200、`Cache-Control: no-store`、
  `subscription_check_enabled=false` 和 `subscription_enforcement_enabled=false`。
- `cmhub-web`、`cmhub-generate`、Nginx、MySQL 8.4 均为 active；66 个图片 worker
  未重启且保持 active。下一步由超级管理员在 admin 创建策略记录后按
  `off -> observe -> enforce` 灰度，无需重启服务。