管理后台接口

当前范围

后台首期实现独立管理员登录(可选择保持登录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及明确的范围、原因、期限和确认;举报查看或状态处理仍不自动封号/拉黑,举报结果与处罚分别按各自版本保存及审计。