PUT/api/v1/admin/users/{userId}/vip
管理员Cookie,ADMIN_USER_VIP_WRITE,OWNER且仅dev非prodJSON 响应接入指南 ↗

设置或取消用户测试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显示环境不支持。隔离浏览器覆盖两向调整、独立版本、只读权限、读写失败、并发和迟到响应,以及中英日韩与桌面/手机布局。真实环境验收仅读取,不替用户选择测试目标或更改实际会员;各批实际验证结果记录在项目当前进度。