管理后台接口¶
当前范围¶
后台首期实现独立管理员登录(可选择保持登录30天)、主动修改密码、用户列表、VIP渠道配置与操作审计。接入先读后台登录与安全,后台要求HTTPS,JSON业务要求JWE;新增媒体文件端点保留Cookie/CSRF并采用文件传输。
没有硬编码默认密码。首个管理员使用服务器受控随机初始化密码,登录后直接进入账号列表。网页菜单依次为账号列表、版本管理、全局配置、操作记录;账号安全页面已移除,改密接口仍保留。管理员创建、角色编辑、用户禁用或删除界面尚未实现。
左侧按管理员认证、用户账号与资料、用户头像与相册、全局配置和操作审计分组。默认只展开当前阅读模块,搜索可跨模块定位接口。
管理员认证¶
后台登录与安全说明独立Cookie、CSRF及JWE规则。
| 接口 | 方法 | 路径 |
|---|---|---|
| 管理员登录 | POST | /api/v1/admin/auth/login |
| 读取管理员会话 | GET | /api/v1/admin/auth/session |
| 退出管理员会话 | POST | /api/v1/admin/auth/logout |
| 修改管理员密码 | PUT | /api/v1/admin/auth/password |
后台媒体交付¶
| 接口 | 方法 | 路径 |
|---|---|---|
| 申请后台媒体下载 | POST | /api/v1/admin/media/downloads |
头像、相册、审核图片、动态音视频与封面、举报证据和OSS明信片图片先经过独立管理员授权,再由CDN返回文件正文;每次联网读取保留会话、权限及对象归属检查。数据库兴趣图标与尚未迁移的历史图片保留原API。原文件接口继续兼容,CDN拒绝不自动降级。
已有 Spring Security 的 ADMIN 权限边界用于保护框架管理端点;/actuator/* 属于运维接口,不等同于管理后台网页 API。
用户账号与资料¶
后台代改国家也要求目标用户为当前有效VIP;OWNER身份不替代用户权益,失败不写资料或成功审计,见保存用户资料。
账号渠道缺失时,后续合法登录、刷新或Bearer认证请求自动补录一次,已有值不覆盖;仍未补获则显示“未记录”。字段与验证范围见用户账号列表,无需管理员手工填写。 账号列表顶部五项统计可直接点击筛选,使用原GET /api/v1/admin/users的statistic参数(ALL/TODAY/MALE/FEMALE/GENDER_UNSET),服务器先过滤再分页;点击清空其他条件并回到第一页,用户总数或重置恢复全部,后续查询可继续叠加条件。今日口径与基础统计共用北京时间自然日,顶部数值保持全量。
后台资料读取、版本化修改与媒体暂存接口已部署;OWNER可写,VIEWER只读。昵称新写入为1–8个UTF-16代码单元,去除首尾空白后不能为空,历史昵称按原值保留;介绍保持30字符;我会的语言与想学习的语言保存后必须不同,部分修改按已存值合并校验,重复返回400 PROFILE_LANGUAGES_SAME。资料接口不能修改性别、注册状态、VIP或登录身份;dev且非prod运行配置下可通过独立VIP测试接口调整会员状态。JSON要求JWE,明确的文件路径使用HTTPS及独立Cookie/CSRF,不套JSON加密。账号列表已接入头像及“查看详情”弹窗,展示基本资料、介绍、语言、兴趣与相册,并提供独立VIP测试调整区:OWNER按canAdjust设置/取消VIP,成功同步列表徽章;VIEWER及不可调整状态只读,冲突或结果不明先重读。资料编辑、相册管理及字典选择器的网页接入仍待完成。
| 接口 | 方法 | 路径 |
|---|---|---|
| 用户账号列表(头像、资料国家与IP归属地、昵称、渠道、注册账号、注册时间/步骤、VIP、性别) | GET | /api/v1/admin/users |
| 用户基础统计(今日注册、总数、男女) | GET | /api/v1/admin/users/statistics |
| 资料编辑字典 | GET | /api/v1/admin/catalogs/profile |
| 读取用户VIP测试状态 | GET | /api/v1/admin/users/{userId}/vip |
| 设置或取消用户测试VIP | PUT | /api/v1/admin/users/{userId}/vip |
| 读取用户详细资料 | GET | /api/v1/admin/users/{userId}/profile |
| 后台保存用户资料与相册 | PATCH | /api/v1/admin/users/{userId}/profile |
兴趣标签管理¶
OWNER维护分类、四语名称、图标、排序及启停,VIEWER只读。JSON独立Cookie/CSRF/JWE;图标精确文件入口仍要求HTTPS/Cookie/写CSRF。保存即生效,版本冲突须重读;只启停分类/标签,不物理删除历史。
| 接口 | 方法 | 路径 |
|---|---|---|
| 读取兴趣标签管理目录 | GET | /api/v1/admin/interests |
| 创建兴趣分类 | POST | /api/v1/admin/interests/groups |
| 保存兴趣分类 | PUT | /api/v1/admin/interests/groups/{id} |
| 创建兴趣标签 | POST | /api/v1/admin/interests/tags |
| 保存兴趣标签 | PUT | /api/v1/admin/interests/tags/{id} |
| 读取兴趣图标库 | GET | /api/v1/admin/interests/icon-library |
| 上传兴趣标签图标 | POST | /api/v1/admin/interests/icons |
| 后台读取兴趣图标 | GET | /api/v1/admin/interests/icons/{id} |
| 丢弃未使用兴趣图标 | DELETE | /api/v1/admin/interests/icons/{id} |
用户封禁与申诉¶
三档封禁为ACCOUNT、ACCOUNT_IP、ACCOUNT_IP_DEVICE;API已部署,网页配套进行中,第三档启用边界见封禁接入。新增读写权限由OWNER/VIEWER区分,账号生命周期status保持原含义,列表banned单独表示有效运营处罚。
App手机号/邮箱发码前提示产生的申诉可能kind=ACCOUNT且userId为空,属于尚未确认账号所有权的收件;后台按申诉列表人工核实,不能只凭kind绑定处罚账号。
| 接口 | 方法 | 路径 |
|---|---|---|
| 读取封禁与访问目标 | GET | /api/v1/admin/users/{userId}/enforcement |
| 按三档封禁账号 | POST | /api/v1/admin/users/{userId}/bans |
| 解除指定封禁 | POST | /api/v1/admin/users/{userId}/bans/{id}/revoke |
| 查询封禁申诉 | GET | /api/v1/admin/access-appeals |
| 旧申诉核查(已停用) | POST | /api/v1/admin/access-appeals/{id}/review,仅兼容返回405 |
用户头像与相册¶
| 接口 | 方法 | 路径 |
|---|---|---|
| 后台暂存用户头像 | POST | /api/v1/admin/users/{userId}/avatars |
| 后台读取用户头像 | GET | /api/v1/admin/users/{userId}/avatars/{id} |
| 后台暂存用户相册照片 | POST | /api/v1/admin/users/{userId}/album-photos |
| 后台读取用户相册照片 | GET | /api/v1/admin/users/{userId}/album-photos/{id} |
| 后台丢弃未保存相册照片 | DELETE | /api/v1/admin/users/{userId}/album-photos/{id} |
版本与升级¶
版本创建即发布已与新版后台、V18配套上线,并通过381项服务器回归及浏览器验收;创建成功原子替换同渠道当前目标,历史记录只读,保留停用。支持版本号精确筛选、全量版本前缀候选及平台/地区/渠道/状态组合查询,状态仅PUBLISHED/WITHDRAWN。OWNER可写、VIEWER只读,发布和停用与审计同事务,停用校验expectedVersion。App升级查询结构保持不变,验证和部署状态见各独立接口页。
| 接口 | 方法 | 路径 |
|---|---|---|
| 读取版本发行渠道 | GET | /api/v1/admin/versions/channels |
| 查询可筛选的版本号 | GET | /api/v1/admin/versions/names |
| 查询版本列表 | GET | /api/v1/admin/versions |
| 读取版本详情 | GET | /api/v1/admin/versions/{id} |
| 创建并发布版本 | POST | /api/v1/admin/versions |
| 停用版本 | POST | /api/v1/admin/versions/{id}/withdraw |
创建必须显式提交publish=true,旧页面缺少标记的“保存草稿”请求返回400且不写入。旧保存草稿、二次发布、删除草稿页面仅保留迁移说明,新版不再提供这些端点。V18保留原草稿为WITHDRAWN/publishedAt=null的未生效历史,不自动发布占位链接,也不占用真实发布构建号。
充值配置¶
按正式九渠道 → 国家 → 套餐独立保存,以人民币净收入为基准换算币种;原平台入口保留兼容,真实支付尚未接入。
| 接口 | 方法 | 路径 |
|---|---|---|
| 充值配置目录 | GET | /api/v1/admin/recharge/catalog |
| 读取渠道充值概况 | GET | /api/v1/admin/recharge/channels/{channel} |
| 读取渠道国家套餐 | GET | /api/v1/admin/recharge/channels/{channel}/{country} |
| 保存渠道国家套餐 | PUT | /api/v1/admin/recharge/channels/{channel}/{country} |
| 批量初始化渠道国家套餐 | POST | /api/v1/admin/recharge/channels/{channel}/initialize |
| 读取充值配置 | GET | /api/v1/admin/recharge/{platform}/{country} |
| 保存充值配置 | PUT | /api/v1/admin/recharge/{platform}/{country} |
国家范围:Google Play为美国、日本、韩国;App Store为中国大陆、美国、日本、韩国;国内七渠道每个渠道仅中国大陆。其他地区的App套餐展示沿用对应商店渠道的美国配置。
全局配置¶
全局配置页按发行渠道分别维护VIP准入开关;协议管理使用独立菜单。
| 接口 | 方法 | 路径 |
|---|---|---|
| 读取全局配置 | GET | /api/v1/admin/configuration |
| 保存全局配置 | PATCH | /api/v1/admin/configuration |
协议管理¶
独立菜单进入协议管理,顶部切换四类协议。国内四类固定中文,国际四类各中英日韩;缺少正文显示未配置。OWNER直接编辑当前正文,网页/手机共用同一富文本实例。保存成功即发布生效,自动生成正文版本和生效时间;再次修改仍直接保存,旧正文保留历史UUID。currentRevision标记当前版本,历史及VIEWER只读。附加资料保留,法律复核按实际声明记录,不作为第二次发布门槛。旧id或expectedVersion冲突、超时均保留输入,先核对再操作,不自动重发。
| 接口 | 方法 | 路径 |
|---|---|---|
| 协议类型与资料清单 | GET | /api/v1/admin/agreements/catalog |
| 协议历史版本 | GET | /api/v1/admin/agreements |
| 协议完整详情 | GET | /api/v1/admin/agreements/{id} |
| 创建协议并立即生效 | POST | /api/v1/admin/agreements |
| 保存协议并立即生效 | PUT | /api/v1/admin/agreements/{id} |
| 净化并预览 | POST | /api/v1/admin/agreements/preview |
| 导入基础协议并生效 | POST | /api/v1/admin/agreements/import-seeds |
单独发布接口已移除。保存、当前正文、登录同意版本快照与后台审计同事务;App下一次目录请求即可取得新链接。V19将各合法配置位最近保存的已有内容接入当前可读范围,原文及复核声明保持。
用户资料审核¶
拒绝操作支持按资料项选择快捷理由,默认不选;仅选择“其他”显示必填输入框。确认后仍通过既有reason提交正文,四语、并发与未知结果核对规则保持,详见审核单项。
头像、相册、昵称和个性签名分别先审后公开;规则、本人状态与旧资料补审见资料审核。菜单“用户资料审核”一次读取列表、统计及当前账号头像/性别/资料国家;侧栏气泡显示全局待审资料项总数,0时隐藏,审核成功及窗口恢复后同步,并在可见页面每30秒按需检查;复用队列接口最小分页,不新增统计端点。左侧只显示头像、昵称和国旗角标,内容区只展示新提交内容,图片为圆角缩略图,同会话内的账号头像与审核图片共用限额/有效期内存及IndexedDB缓存,切回菜单或恢复身份后的强制刷新可复用已验证图片,退出/换号/权限变化清空,加载中不先显示默认头像;点击在同一弹窗放大及切换本页已加载图片,右侧“同意”点击即提交、不再弹窗,提交中防重复,成功刷新列表与待审数量;冲突或未知结果须手动刷新核对,不自动重发。“拒绝”继续弹窗选择理由,使用现有reason字段(必填,最多500字符);OWNER可决定、VIEWER只读。
用户审核顶部按头像、相册、昵称、个性签名切换,默认头像待审;当前分类的状态与数量在下方紧凑显示,保留关键词查询、分页和刷新,侧栏气泡始终表示全局待审总数。
| 接口 | 方法 | 路径 |
|---|---|---|
| 读取用户资料审核队列 | GET | /api/v1/admin/profile-reviews |
| 读取用户资料审核详情 | GET | /api/v1/admin/profile-reviews/{id} |
| 审核用户资料单项 | POST | /api/v1/admin/profile-reviews/{id}/review |
| 读取资料审核头像 | GET | /api/v1/admin/profile-reviews/{id}/avatars/{source} |
| 读取资料审核相册图片 | GET | /api/v1/admin/profile-reviews/{id}/photos/{source}/{photoId} |
操作审计¶
| 接口 | 方法 | 路径 |
|---|---|---|
| 操作记录 | GET | /api/v1/admin/audit |
首期与后续边界¶
后台网页与Java后端在同一仓库维护,使用独立网页目录,复用现有Java应用和业务模块。后台账号、会话与操作权限独立于App用户;客户端admin标识或VIP状态不授予管理员权限。
首期角色为OWNER和VIEWER,权限由后端控制;VIP设置保存带版本冲突检测。OWNER可通过独立用户VIP测试接口在dev且非prod设置/取消测试VIP;真实支付订单、退款、付费会员发放、账号注销和任意配置新增仍不作为当前可用能力。
每个HTTP方法与路径独立维护契约和真实验证范围;界面菜单不会替代后端授权。
后台版本页面由Java-web-1按创建即发布契约配套调整,接口成功后通过App升级检查返回符合条件的当前目标;Flutter接口结构不变。包上传、签名核验、应用商店自动提交、灰度/定时发布尚未实现。
提前准备¶
可以先阅读快速接入与请求封装、请求与响应及加密与认证。公共系统信息接口可用于验证网络连接。
管理网页也可使用标准请求测试核对版本、渠道和浏览器实例标识:发送 X-Client-Type: admin、X-Platform: web、X-Channel: admin_web,并提供其余公共请求头。该接口只维护这一份契约,不授予管理员权限。
后续每个后台接口单独成页,明确身份、权限及失败响应。查看文档维护规范
管理网页和 App 共用AES 加密协议及公钥查询;标准请求测试仅验证公共封装,不授予后台权限。
互动与内容审核¶
OSS新视频的封面由上传确认流程自动保存,后台列表、详情及封面读取复用原字段与权限;不要求App或管理员另传首帧,不在审核列表查询时截帧。旧视频无封面继续按真实空值显示。
2026-11-05已部署并可接入。先读互动与审核接入,包含字段模型及实际验证范围。动态、评论和回复发布成功只表示待审核,公开内容必须APPROVED。后台通过“动态审核 → 话题配置”进入,侧栏不单独显示话题入口,页面复用下方话题配置接口,提供四语编辑、分类/关键字筛选、排序和今日话题配置,并从网页静态资源中选择当前UI设计的100张话题图片。话题保存后立即生效,接口只保存iconKey,不保存图片URL。配置页与Java保存逻辑、V39迁移已配套发布,旧话题审核入口固定返回405。顶部位置独立读取今日灵感、去看看世界、认识新朋友和今日热门话题,编辑继续复用原有保存接口;不受普通列表筛选影响。
评论列表、详情与审核回执增加作者及直接回复对象的当前头像、资料国家和昵称;仅后台可读,按页批量查询。列表区分直接评论动态与回复,并明确回复给谁;原路径、权限、筛选与审核版本保持。
| 接口 | 方法 | 路径 |
|---|---|---|
| 读取动态审核队列 | GET | /api/v1/admin/posts |
| 读取动态审核数量 | GET | /api/v1/admin/posts/statistics |
| 读取工作区全局待处理数量 | GET | /api/v1/admin/community/statistics |
| 读取动态审核详情 | GET | /api/v1/admin/posts/{id} |
| 审核动态内容 | POST | /api/v1/admin/posts/{id}/review |
| 删除已通过动态 | DELETE | /api/v1/admin/posts/{id} |
| 读取审核动态图片 | GET | /api/v1/admin/posts/{postId}/photos/{id} |
| 读取审核音视频 | GET | /api/v1/admin/posts/{postId}/files/{id} |
| 读取审核视频封面 | GET | /api/v1/admin/posts/{postId}/files/{id}/poster |
| 读取评论审核队列 | GET | /api/v1/admin/comments |
| 读取评论审核详情 | GET | /api/v1/admin/comments/{id} |
| 审核评论或回复 | POST | /api/v1/admin/comments/{id}/review |
| 读取话题配置列表 | GET | /api/v1/admin/topics |
| 读取App顶部话题配置 | GET | /api/v1/admin/topic-placements |
| 读取话题完整配置 | GET | /api/v1/admin/topics/{id} |
| 创建并立即生效话题 | POST | /api/v1/admin/topics |
| 更新话题并立即生效 | PUT | /api/v1/admin/topics/{id} |
| 已停用的话题审核入口 | POST | /api/v1/admin/topics/{id}/review |
| 读取互动举报处理队列 | GET | /api/v1/admin/content-reports |
| 读取举报详情和私有证据 | GET | /api/v1/admin/content-reports/{id} |
| 处理互动举报 | PATCH | /api/v1/admin/content-reports/{id} |
| 读取私有举报证据 | GET | /api/v1/admin/content-reports/{reportId}/evidence/{id} |
互动举报驳回无需填写理由,沿用原处理接口并发送resolution:"";处理完成仍须说明,版本、权限、终态及同事务审计保持。网页顶部切换举报详情/举报处理/账号封禁,默认举报处理,确认按钮固定在底部;封禁与举报处理分别明确确认。
明信片审核与举报¶
先读明信片接入。首信和回信都须人工审核通过后投递,数据与已接入状态分别说明。
| 接口 | 方法 | 路径 |
|---|---|---|
| 读取首信或回信人工审核队列 | GET | /api/v1/admin/postcards |
| 读取私密明信片人工审核详情 | GET | /api/v1/admin/postcards/{id} |
| 审核私密首信或回信 | POST | /api/v1/admin/postcards/{id}/review |
| 读取明信片审核原图 | GET | /api/v1/admin/postcards/{cardId}/photos/{id} |
| 读取私密明信片举报处理队列 | GET | /api/v1/admin/postcard-reports |
| 读取私密明信片举报详情 | GET | /api/v1/admin/postcard-reports/{id} |
| 处理私密明信片举报 | PATCH | /api/v1/admin/postcard-reports/{id} |
举报队列复用原列表、详情、处理及证据契约;新增USER目标,旧列表默认CONTENT,新版页面显式scope=ALL并按真实类型显示,USER不读取关联动态。列表、详情和处理回执新增targetUser/reporter最小当前资料,按页批量读取;网页展示头像及昵称,不将账号UUID当作名称。目标为USER本人、POST作者或COMMENT作者,评论不使用父动态作者代替;App回执不增加后台身份字段。网页右侧使用现有独立账号封禁表单,需要ADMIN_ENFORCEMENT_READ/WRITE及明确的范围、原因、期限和确认;举报查看或状态处理仍不自动封号/拉黑,举报结果与处罚分别按各自版本保存及审计。