设置或取消用户测试VIP¶
请求参数¶
面向管理后台网页,要求可信HTTPS、独立管理员HttpOnly Cookie和ADMIN_USER_VIP_WRITE,OWNER且仅dev非prod。JSON请求及响应均使用真实JWE,App Bearer不授予后台身份。写操作必须同源Origin及X-Admin-CSRF。
八项公共请求头全部校验,固定admin/web/admin_web,版本、构建号、持久安装UUID、请求ID及毫秒时间戳按公共请求头;四语响应见公共协议,权限与加密见后台安全及JWE。
两个字段均必填且不接受null;无查询参数,路径userId为目标账号UUID。仅ACTIVE账号允许调整,封禁与资料注册的准入规则独立保持。
| 字段 | 类型 | 约束 |
|---|---|---|
| vipActive | boolean | true设为VIP,false取消VIP,显式目标状态;不是反转命令 |
| expectedVersion | integer(int64) | ≥0,必须等于最近读取的version;无覆盖记录首次传0 |
不接受其他字段。false会在dev且非prod配置下强制非VIP,即使存在付费权益;它不撤销、退款或修改付款记录。覆盖无自动到期,持续到再次调整;目前不提供删除覆盖/恢复付款默认值的操作。prod忽略已有测试覆盖并拒绝调整,客户端X-Channel不能开启本功能。
请求示例¶
在已验证HTTPS同源网页执行;示例UUID为合成数据,安装ID复用浏览器持久值,Cookie由浏览器管理。currentVip来自本用户最近一次GET;csrfToken来自登录或恢复会话的认证响应。
import {createJweEncryption} from '../../examples/budyoo-encryption.mjs';
const url = new URL('/api/v1/admin/users/11111111-1111-4111-8111-111111111111/vip', location.origin);
const headers = {
'Accept-Language': 'zh-CN',
'X-Client-Type': 'admin', 'X-Platform': 'web',
'X-App-Version': '1.0.0', 'X-App-Build': '1', 'X-Channel': 'admin_web',
'X-Device-Id': installationId,
'X-Request-Id': crypto.randomUUID(), 'X-Request-Timestamp': String(Date.now()),
'X-Admin-CSRF': csrfToken, // 从已认证会话取值,只保存在内存
};
const codec = createJweEncryption({baseUrl: location.origin});
const encrypted = await codec.prepare({url, method: 'PUT', headers,
body: {vipActive: true, expectedVersion: currentVip.version}});
const response = await fetch(url, {method: 'PUT', headers: encrypted.headers,
body: encrypted.body, credentials: 'same-origin', redirect: 'error'});
const result = await encrypted.decode(response);
成功响应¶
HTTP200,Cache-Control:no-store,回传合法请求ID。以下为通过认证解密后的JSON,线上外层仍为JWE。
{"code":"SUCCESS","message":"操作成功。","data":{
"userId":"11111111-1111-4111-8111-111111111111",
"vipActive": true, "testOverride": true, "version": 1, "canAdjust":true
},"errors":[]}
| data字段 | 类型 | 可空 | 说明 |
|---|---|---|---|
| userId | string(UUID) | 否 | 目标用户 |
| vipActive | boolean | 否 | 当前服务端实际判断;开发测试覆盖生效时使用覆盖值,否则使用已确认且生效、未到期、未撤销的付费权益 |
| testOverride | boolean | 是 | true强制VIP,false强制非VIP;无覆盖或非开发模式返回null |
| version | integer(int64) | 否 | 独立测试版本,无记录为0;成功写入递增,不能用资料version替代 |
| canAdjust | boolean | 否 | 当前管理员为OWNER、环境为dev且非prod、目标账号ACTIVE时为true;服务端仍独立校验 |
失败响应¶
| HTTP | code | 条件 |
|---|---|---|
| 400 | BAD_REQUEST/VALIDATION_FAILED | 非法UUID、请求体或字段校验失败 |
| 400 | INVALID_CLIENT_HEADERS | 必填公共头缺失、重复或格式错误 |
| 401 | UNAUTHORIZED | 未登录、会话过期、安装不匹配或只有App Bearer |
| 403 | FORBIDDEN/ADMIN_CSRF_INVALID | 无对应权限、跨站Origin或写入CSRF不合法 |
| 404 | NOT_FOUND | 目标账号不存在 |
| 426 | HTTPS_REQUIRED | 未使用允许的HTTPS入口 |
| 503 | SERVICE_UNAVAILABLE | 数据库、审计或Redis不可用;不能当成功或无VIP |
| 400/409 | 加密协议错误码 | JWE缺失、篡改、过期、重放,见公共加密协议 |
| 403 | ADMIN_VIP_TEST_ONLY | 环境不是dev且非prod |
| 403 | ACCOUNT_DISABLED | 目标已禁用或已删除 |
| 409 | ADMIN_VIP_CONFLICT | 版本已变化,包含重复提交旧版本;先重新读取,不自动覆盖 |
{"code":"ADMIN_VIP_CONFLICT","message":"VIP状态已发生变化,请刷新后再调整。","data":null,"errors":[]}
code固定,message与errors[].message支持中文、英文、日文、韩文,缺省或不支持语言回退英文。网关429/413等不保证为已认证JWE,不当作成功业务响应。
接入说明¶
写入与USER_VIP_TEST_ENABLE/USER_VIP_TEST_DISABLE审计在同一事务提交;审计记录管理员、目标账号、请求ID和前后VIP/测试值/版本摘要,不存付款或凭证。审计失败整体回滚。账号锁与注销、资料写入串行;并发同版本只成功一个。
成功使用响应更新详情及列表徽章。返回409、超时或网络结果未知时先重新GET核对,不自动重发;重新调整须采用新version。canAdjust=false时只展示状态,不能通过隐藏按钮代替权限判断。App原Token在后续请求立即读取新状态,无需退出重登;不会跳过四步资料、封禁或改变渠道门槛。已建立WebSocket的即时VIP撤销仍未接入。
这只是开发测试能力,无支付下单、核验、退款、期限或赠钻语义。注销清理非财务测试覆盖;真实有效付费记录仍按原财务规则阻止注销,取消测试VIP不能绕过。
实现位于admin/users与membership,经identity/api账号锁编排,不直接跨模块写表。V31新增独立测试表,迁移不自动创建覆盖值或改变旧权益。服务器隔离PostgreSQL/Redis测试覆盖真实Cookie/CSRF/JWE、OWNER/VIEWER、两向调整及App和列表一致性、版本冲突/并发、字段与账号校验、审计回滚、dev/prod模式隔离、四语、注销和V30→V31旧数据保留。用户详情已接入VIP测试调整区,读取失败可重试,保存期间禁止重复提交,关闭或切换用户后忽略迟到结果;成功同步详情及列表徽章,409或结果不明先重读且不自动重发,403 ADMIN_VIP_TEST_ONLY显示环境不支持。隔离浏览器覆盖两向调整、独立版本、只读权限、读写失败、并发和迟到响应,以及中英日韩与桌面/手机布局。真实环境验收仅读取,不替用户选择测试目标或更改实际会员;各批实际验证结果记录在项目当前进度。