保存协议并立即生效¶
请求参数¶
仅OWNER。要求独立Cookie、HTTPS、真实JWE、Origin、X-Admin-CSRF及完整八项公共头,固定admin/web/admin_web。路径id为当前正文UUID,无查询参数;历史记录不可作为保存目标。
| 字段 | 类型/必填 | 约束及省略语义 |
|---|---|---|
| expectedVersion | integer(int64),是 | 当前详情version,非负;字符串、小数、负数拒绝 |
| type | string,是 | 原terms/privacy/recharge/vip,不可变更 |
| locale | string,是 | 原正文语言;国内zh-CN,国际四语之一 |
| serviceRegion | string,是 | 原domestic/overseas,不可变更 |
| jurisdiction | string,否 | 省略按地区归一CN/GLOBAL;不能更改归属 |
| title | string,是 | 非空,原输入最多120个UTF-16代码单元 |
| bodyHtml | string,是 | 最多60000个UTF-16代码单元、160000个UTF-8字节,净化后非空 |
| contentVersion | string,否 | 可省略;传入时必须为读取的原版本。新版本由服务器自动生成 |
| summary | string,否 | 省略/null保留,空字符串清除,最多500个UTF-16代码单元 |
| publicationFields | object,否 | 省略/null保留,{}清除;键来自类型目录,每值string且最多2000个UTF-16代码单元 |
| legalReviewed | boolean,否 | 省略/null为false;不会因保存自动生成审核结论 |
| effectiveAt | ISO8601或null,否 | 兼容旧字段;生效时间始终由本次保存确定 |
这是完整正文保存,不是任意字段PATCH。状态、publicEnabled、currentRevision、发布时间及其他未知字段拒绝。HTML净化、国内重要区保护和四语错误保持。
请求示例¶
await request('agreements/11111111-1111-4111-8111-111111111111', 'PUT', {
expectedVersion: 2, type: 'terms', locale: 'en', serviceRegion: 'overseas',
title: 'Terms of Service', bodyHtml: '<p>填写修改后的实际正文。</p>'
});
统一后台封装提供Accept-Language及八项X-*元数据、Cookie、Origin、CSRF、JWE;不在页面拼接凭据。
成功响应¶
HTTP200及no-store,data为完整详情。有实际内容修改时:
- 返回新的id和自动生成的contentVersion,version为原版本加1。
- status=PUBLISHED、currentRevision=true、publicEnabled=true;publishedAt/effectiveAt为本次服务端保存时间。
- 旧id的正文、内容版本和阅读地址保持,currentRevision变为false。
- 当前正文、同意版本快照及AGREEMENT_UPDATE审计同事务提交。
正文、标题、摘要、附加资料和复核声明都没有变化时返回原记录,不新增版本或无故使用户同意失效。请求超时后不能假定未保存。
失败响应¶
| HTTP | code | 条件 |
|---|---|---|
| 400 | INVALID_AGREEMENT/BAD_REQUEST | 字段、长度、归属、JSON类型或未知字段非法 |
| 400 | AGREEMENT_IMPORTANT_REQUIRED | 国内重要区和法定例外不完整 |
| 400 | INVALID_CLIENT_HEADERS/加密错误码 | 元数据或JWE不合法 |
| 401 | UNAUTHORIZED | Cookie失效或身份不符 |
| 403 | FORBIDDEN/ADMIN_CSRF_INVALID | 角色、Origin或CSRF不符 |
| 404 | NOT_FOUND | id不存在 |
| 409 | AGREEMENT_CONFLICT | expectedVersion过期,或id已是历史正文 |
| 426 | HTTPS_REQUIRED | 非HTTPS |
| 503 | SERVICE_UNAVAILABLE | 持久化、Redis或审计失败,事务回滚 |
{"code":"AGREEMENT_CONFLICT","message":"协议已变化,请重新读取后保存。","data":null,"errors":[]}
code固定,提示中英日韩;409、超时和未知结果保留输入,暂停重复提交并先读取当前正文核对。
接入说明¶
后台直接编辑当前正文,保存后采用响应的新id/version继续编辑;不要继续PUT旧id,也不再以PUBLISHED触发用户手填下一版本。历史选择只读,可返回当前版本。网页/手机复用同一编辑器,切换尺寸与取消不写入。
App下一次读取目录即取得新链接。用户协议和隐私政策保存会自动切换登录同意版本,旧登录配置收到CONSENT_VERSION_CHANGED后刷新并要求重新明确同意。阅读不自动替用户勾选。
2026-11-04已随V19与新版后台配套部署,417项服务器Java回归零失败/错误/跳过,覆盖保存生效、旧正文保留、同意版本、并发、权限/JWE/CSRF、审计回滚与迁移。公网60组旧渠道语言组合、7项访问边界及20个独立HTML链接只读验证通过;运行库原20份正文与UUID保持,未伪造法律复核。后台保存交互另通过18项浏览器夹具及24组四语布局,真实运行库未写入测试正文。