T-635 cmshopee 客户端启动订阅策略接口

背景

新版 cmshopee 客户端需要在启动时远程获知是否检查会员套餐、是否在客户端侧展示会员门禁。客户端已经匿名请求 GET /api/v1/client/releases/latest?platform=windows，第一版应复用该公开版本检查接口发布策略，避免新增启动请求。

现有订阅状态接口的 allowed 是当前服务端运行模式下的最终访问结果。在 open 或 shadow 模式，无真实权益的账号仍可能得到 allowed=true。客户端不能把该字段当作真实会员有效性，否则在未来切换客户端门禁时会误放行。

目标

版本检查响应顶层发布稳定、公开、无账号上下文的 client_policy。
用一个受校验的配置枚举表达客户端策略，输出兼容桌面端所需的两个布尔字段。
订阅状态接口明确返回真实权益是否可用，消除 open / shadow 的歧义。
策略仅影响客户端体验；服务端产品专属接口仍由 CMSHOPEE_SUBSCRIPTION_MODE 独立授权。

范围

公开版本检查接口

在 GET /api/v1/client/releases/latest?platform=windows 的顶层新增：

{
  "platform": "windows",
  "release": null,
  "message": "暂未发布",
  "client_policy": {
    "policy_version": 1,
    "subscription_check_enabled": true,
    "subscription_enforcement_enabled": false,
    "updated_at": "2026-07-28T10:00:00+08:00"
  }
}

client_policy 不得为 null，在有当前发布和 release:null 两条成功路径都必须返回；release 的既有字段和语义不变。
policy_version 当前固定为整数 1；两个开关必须是 JSON 布尔值； updated_at 必须是带时区的 ISO 8601 字符串，代表配置最后变化时间，不能使用每次请求的当前时间。
该接口继续匿名、只读、无 API Key / Cookie / 用户 / 套餐 / 点数查询，不扣点，不占用生成接口限流；响应不得含 API Key、用户、套餐、内部路径、后台 ID 或密钥。
成功响应设置 Cache-Control: no-store，保证客户端紧急回退不会长期受 CDN 或浏览器缓存影响。

配置

新增 CMSHOPEE_CLIENT_SUBSCRIPTION_POLICY=off|observe|enforce，默认 off。非法值必须阻止 Django 启动，不能静默降级。
输出映射固定为：off -> false/false、observe -> true/false、 enforce -> true/true。不使用两个独立环境变量，避免出现非法的 false/true 组合。
新增 CMSHOPEE_CLIENT_SUBSCRIPTION_POLICY_UPDATED_AT，要求为带时区 ISO 8601 时间；每次把策略改为 observe 或 enforce 时必须同步显式更新。未配置时只允许默认 off 使用仓库固定的基线时间；非 off 未配置或时间非法时阻止启动。
该配置与已有 CMSHOPEE_SUBSCRIPTION_MODE=open|shadow|enforce 完全独立。前者只控制新版客户端是否请求 / 展示门禁，后者才控制服务端专属生成接口的最终放行。不得因客户端策略变更而创建、修改或删除权益、套餐、订单、点数、 API Key 或异步任务。

订阅状态真实权益语义

GET /api/v1/cmshopee/subscription/status 顶层新增 real_entitlement_allowed。仅当 entitlement_status 为 active 或 grace 时为 true；该字段不受 open / shadow / enforce 的最终放行模式影响。
保留现有 allowed、status、code、access_source 和 entitlement_status，不改变服务端当前授权或既有客户端兼容行为。
文档删除未实现的 legacy / revoked 状态承诺：当前真实权益状态只以 active、grace、required、expired 为准；禁用账号 / API Key 仍由认证层返回 HTTP 403 account_disabled，不是状态接口的成功 JSON 状态。

非目标与兼容

不新增数据库模型、迁移、admin 配置页或运行时热修改能力；环境变量变更后按既有部署方式重启 Web / Generate 服务生效。
不改通用 /api/v1/generate/*、产品专属生成接口的授权逻辑、上游调用、预扣 / 确认 / 退款、UserWallet、PointsLedger、充值支付或软件订单。
旧客户端会忽略新增顶层字段，仍按自身内置逻辑工作；新客户端应只在 policy_version=1 且字段类型合法时采纳策略。无法获取策略时客户端应进入 “检测开启、强制关闭”的观察回退，不能提示用户重复付费。

验收条件

off、observe、enforce 三种合法配置分别返回 false/false、true/false、true/true，类型均为 JSON boolean。
非法枚举、非 off 缺少更新时间、无时区或非法更新时间均阻止 Django 启动或在配置读取处抛出明确 ImproperlyConfigured，不得向外发布矛盾策略。
有当前发布、没有当前发布、当前发布无下载地址三种成功响应均包含 client_policy；原有 release 字段与 force_update、size_bytes 不回归。
版本检查接口匿名可用，忽略 Session / API Key，响应为 Cache-Control: no-store，且不访问或泄露用户、订阅、点数、模型、密钥、文件系统路径或后台 ID。
open / shadow 下无权益账号仍可能保持现有 allowed=true，但 real_entitlement_allowed=false；真实 active / grace 权益为 true，过期 / 未开通为 false。
CMSHOPEE_SUBSCRIPTION_MODE 与客户端策略任意组合均不改变既有产品专属接口的服务端授权结论；通用生成、扣点、退款、充值和软件订单回归通过。
同步更新 docs/api.md、docs/env.md、docs/deployment.md、 docs/04-architecture.md、docs/current-state.md、任务状态和 progress.md；及 Obsidian 的客户端接口契约。
manage.py check、目标 API / licensing 测试、迁移一致性、编译检查和 git diff --check 通过。

状态

DONE。

实施结果

新增 config/client_subscription_policy.py，以单一 CMSHOPEE_CLIENT_SUBSCRIPTION_POLICY=off|observe|enforce 解析并发布策略，固定输出 policy_version=1 与两个 JSON 布尔字段；非法模式、非 off 缺更新时间、无时区或非法时间均抛出 ImproperlyConfigured。
GET /api/v1/client/releases/latest 的当前发布、无发布和无下载地址路径均返回顶层 client_policy，所有响应设置 Cache-Control: no-store；接口仍只查询 DownloadRelease 和环境配置。
GET /api/v1/cmshopee/subscription/status 新增 real_entitlement_allowed，仅在真实权益为 active 或 grace 时为 true，保留既有最终访问 allowed 兼容字段。
未新增模型、迁移、admin 配置或运行时写入，不改通用 / 专属生成、点数账本、充值支付、软件订单或服务端订阅强制模式。

验证结果

py -3.12 -m py_compile config\client_subscription_policy.py config\settings.py apps\api\views.py apps\api\tests.py apps\licensing\services.py apps\licensing\tests.py：通过。
py -3.12 manage.py check：通过，0 issues。
隔离 SQLite 目标回归：ClientLatestReleaseApiTests、订阅状态核心场景和 SubscriptionModeUnitTests 共 27 tests OK，覆盖三种策略、无发布策略、非法配置、no-store、真实权益 active / grace / required / expired 语义。
py -3.12 manage.py makemigrations --check --dry-run：No changes detected；旧本地 MySQL 地址拒绝连接，仅产生迁移历史检查 warning，本任务无迁移。
./init.ps1 和 git diff --check：通过。

生产部署

2026-07-28 已部署到 185.216.248.75，线上 .deploy_revision 为 1c100c5。
部署前备份位于 /root/cmhub_deploy_backups/cmhub-before-t635-20260728_151900，包含发布前应用代码和 .env。
线上保持 CMSHOPEE_SUBSCRIPTION_MODE=enforce，新增客户端策略明确设置为 CMSHOPEE_CLIENT_SUBSCRIPTION_POLICY=off，更新时间为 2026-07-28T15:19:19+08:00；不改变服务端授权。
cmhub-web、cmhub-generate、Nginx、MySQL 8.4 均为 active；66 个图片 worker 未重启且均 active，failed units 为 0。
公网 GET /api/v1/client/releases/latest?platform=windows 返回 HTTP 200、 Cache-Control: no-store 和 client_policy=false/false。

8.3 KiB Raw Blame History Unescape Escape