txagent-y/txagent-y
9
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
0d9eae10ec
txagent-y/docs/dev/admin-api/README.md
qingfeng 0d9eae10ec docs(admin-api): clarify ppv audit routes
2026-04-10 14:21:50 +08:00

12 KiB
Raw Blame History

运营后台 API 接口文档目录（按模块拆分）

版本： v1.0
基于文档： API-运营后台接口文档-产品视角.md
拆分日期： 2026-03-31
接口总数： 68 个

统一规范

分页/排序/筛选 Query 参数规范

所有列表类接口（GET /admin/api/v1/.../list 形式）必须遵守如下统一 Query 约定，前后端无需逐接口确认：

参数 类型 默认 说明
page int 1 页码，从 1 起
pageSize int 20 每页条数，最大 100
sortBy string created_at 排序字段（白名单，由各接口列出）
sortOrder string desc 排序方向：asc / desc
keyword string — 模糊搜索关键词（按各接口指定列）
status string/int — 状态筛选，枚举值与"状态枚举映射"段一致
startDate date — 时间区间起（按 created_at；ISO8601 yyyy-MM-dd 或 RFC3339）
endDate date — 时间区间止（含当日，闭区间）

响应统一信封：

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [...],
    "pagination": { "total": 123, "page": 1, "pageSize": 20 }
  }
}

审计日志写入规范

所有 update/delete/敏感操作类接口（含状态变更、金额变更、权限变更、内容审核动作）必须写入 admin_operation_log，并满足：

  1. 写入 admin_operation_log 必须与业务 UPDATE/DELETE 在同一事务内，避免出现"动作发生但审计缺失"。
  2. 在事务内先 SELECT 旧值（建议 SELECT ... FOR UPDATE），再执行 UPDATE，最后把 old_value / new_value 存入 admin_operation_log 的 JSONB 列。
  3. 必填字段：admin_id、action、target_type、target_id、description、old_value、new_value、ip、user_agent、created_at。
  4. 删除类操作请使用软删（deleted_at），并把删除前完整行写入 old_value。

模块索引

# 模块 接口数 文件
01 登录与权限 10 ADMIN-AUTH-01~05, ADMIN-ROLE-01~05
02 内容审核 10 AUDIT-01~07、AUDIT-PPV-01~02
03 举报处理 2 REPORT-A01~02
04 用户管理 6 USER-A01~06
05 财务管理 9 FIN-01~09
06 数据注水 4 BOOST-01~04
07 推荐位管理 3 REC-01~03
08 平台配置 12 CFG-01~12
09 数据统计 5 STATS-01~05
10 客服工具 3 CS-01~03
11 内容管理 4 POST-A01~04

接口总览

01 登录与权限（10个）

  • ADMIN-AUTH-01 运营后台登录 — POST /admin/api/v1/auth/login
  • ADMIN-AUTH-02 获取当前管理员信息 — GET /admin/api/v1/auth/me
  • ADMIN-AUTH-03 管理员列表 — GET /admin/api/v1/admins
  • ADMIN-AUTH-04 创建/编辑管理员 — POST /admin/api/v1/admins
  • ADMIN-AUTH-05 禁用/启用管理员 — PATCH /admin/api/v1/admins/:adminId/status
  • ADMIN-ROLE-01 获取角色列表 — GET /admin/api/v1/roles
  • ADMIN-ROLE-02 获取权限清单 — GET /admin/api/v1/permissions
  • ADMIN-ROLE-03 创建角色 — POST /admin/api/v1/roles
  • ADMIN-ROLE-04 编辑角色 — PUT /admin/api/v1/roles/:roleId
  • ADMIN-ROLE-05 删除角色 — DELETE /admin/api/v1/roles/:roleId

02 内容审核（10个）

  • AUDIT-01 获取待审核内容列表 — GET /admin/api/v1/audit/contents
  • AUDIT-02 审核通过帖子内容 — POST /admin/api/v1/audit/contents/:contentId/approve
  • AUDIT-03 审核拒绝帖子内容 — POST /admin/api/v1/audit/contents/:contentId/reject
  • AUDIT-PPV-01 获取待审核 PPV 素材列表 — GET /admin/api/v1/audit/ppv-materials
  • AUDIT-PPV-02 审核 PPV 素材 — POST /admin/api/v1/audit/ppv-materials/:materialId/review
  • AUDIT-04 获取待审核Banner/头像列表 — GET /admin/api/v1/audit/avatars
  • AUDIT-05 审核Banner/头像 — POST /admin/api/v1/audit/avatars/:id/review
  • AUDIT-06 获取待审核创作者申请列表 — GET /admin/api/v1/audit/creator-applications
  • AUDIT-07a 创作者申请审核-通过 — POST /admin/api/v1/audit/creator-applications/:id/approve
  • AUDIT-07b 创作者申请审核-拒绝 — POST /admin/api/v1/audit/creator-applications/:id/reject

03 举报处理（2个）

  • REPORT-A01 获取举报列表 — GET /admin/api/v1/reports
  • REPORT-A02 处理举报 — POST /admin/api/v1/reports/:reportId/handle

04 用户管理（6个）

  • USER-A01 用户列表查询 — GET /admin/api/v1/users
  • USER-A02 用户详情 — GET /admin/api/v1/users/:userId
  • USER-A03 封禁用户 — POST /admin/api/v1/users/:userId/ban
  • USER-A04 解封用户 — POST /admin/api/v1/users/:userId/unban
  • USER-A05 创作者列表查询 — GET /admin/api/v1/creators
  • USER-A06 创作者详情 — GET /admin/api/v1/creators/:creatorId

05 财务管理（9个）

  • FIN-01 提现审核列表 — GET /admin/api/v1/finance/withdrawals
  • FIN-02 提现审核通过 — POST /admin/api/v1/finance/withdrawals/:withdrawalId/approve
  • FIN-03 提现审核拒绝 — POST /admin/api/v1/finance/withdrawals/:withdrawalId/reject
  • FIN-04 确认打款 — POST /admin/api/v1/finance/withdrawals/:withdrawalId/confirm-paid
  • FIN-05 退款处理 — POST /admin/api/v1/finance/refunds
  • FIN-06 退款记录列表 — GET /admin/api/v1/finance/refunds
  • FIN-07 充值订单列表 — GET /admin/api/v1/finance/recharge-orders
  • FIN-08 平台收入统计 — GET /admin/api/v1/finance/revenue
  • FIN-09 钱包交易流水列表 — GET /admin/api/v1/finance/transactions

06 数据注水（4个）

  • BOOST-01 设置内容注水 — POST /admin/api/v1/boost/contents
  • BOOST-02 关闭内容注水 — POST /admin/api/v1/boost/contents/:postId/close
  • BOOST-03 设置创作者注水 — POST /admin/api/v1/boost/creators
  • BOOST-04 查看注水状态列表 — GET /admin/api/v1/boost/list

07 推荐位管理（3个）

  • REC-01 获取推荐位列表 — GET /admin/api/v1/recommend/slots
  • REC-02 设置推荐位 — POST /admin/api/v1/recommend/slots
  • REC-03 移除推荐位 — DELETE /admin/api/v1/recommend/slots/:slotId

08 平台配置（12个）

  • CFG-01 充值档位管理 — GET/POST /admin/api/v1/config/recharge-tiers、PUT/DELETE /admin/api/v1/config/recharge-tiers/:id
  • CFG-02 首充奖励配置 — GET/PUT /admin/api/v1/config/first-recharge
  • CFG-03 签到奖励配置 — GET/PUT /admin/api/v1/config/checkin
  • CFG-04 至尊赠币配置 — GET/PUT /admin/api/v1/config/supreme-bonus
  • CFG-05 分成比例配置 — GET/PUT /admin/api/v1/config/revenue-share
  • CFG-06 支付通道管理 — GET/PUT /admin/api/v1/config/payment-channels
  • CFG-07 预设标签管理 — GET/POST /admin/api/v1/config/tags、PUT/DELETE /admin/api/v1/config/tags/:id
  • CFG-08 敏感词库管理 — GET/POST /admin/api/v1/config/sensitive-words、DELETE /admin/api/v1/config/sensitive-words/:id
  • CFG-09 公告管理 — GET/POST /admin/api/v1/config/announcements、PUT/DELETE /admin/api/v1/config/announcements/:id、POST /admin/api/v1/config/announcements/:id/publish|offline
  • CFG-10 系统配置（App API 域名） — GET/PUT /admin/api/v1/config/system
  • CFG-11 分类管理 — GET/POST /admin/api/v1/config/categories、PUT/DELETE /admin/api/v1/config/categories/:id
  • CFG-12 域名管理 — GET/POST /admin/api/v1/config/domains、PUT/DELETE /admin/api/v1/config/domains/:id

09 数据统计（5个）

  • STATS-01 平台数据总览 — GET /admin/api/v1/stats/overview
  • STATS-02 用户增长统计 — GET /admin/api/v1/stats/user-growth
  • STATS-03 收入统计 — GET /admin/api/v1/stats/revenue
  • STATS-04 内容统计 — GET /admin/api/v1/stats/content
  • STATS-05 创作者排行榜 — GET /admin/api/v1/stats/creator-ranking

10 客服工具（3个）

  • CS-01 查看用户聊天记录 — GET /admin/api/v1/cs/messages/:userId
  • CS-02 查看用户消费记录 — GET /admin/api/v1/cs/transactions/:userId
  • CS-03 手动发放代币 — POST /admin/api/v1/cs/issue-coins

11 内容管理（4个）

  • POST-A01 帖子列表（全量） — GET /admin/api/v1/posts
  • POST-A02 帖子详情 — GET /admin/api/v1/posts/:postId
  • POST-A03 创作者作品列表 — GET /admin/api/v1/creators/:creatorId/posts
  • POST-A04 强制下架帖子 — PATCH /admin/api/v1/posts/:postId/takedown

通用约定

  • Base URL： https://api.txfans.com/admin/v1
  • 路径前缀： /admin/api/v1/（与C端 /api/v1/ 隔离）
  • 数据格式： JSON（Content-Type: application/json）
  • 认证方式： Admin Bearer Token（独立 JWT secret，与C端不互通）
  • 分页参数： page（页码，默认1）、pageSize（每页条数，默认20，最大100）
  • API字段风格： camelCase | DB字段风格： snake_case
  • 统一响应： { "code": 0, "message": "success", "data": {} }

统一错误码

code 说明
0 成功
400 参数错误
401 未认证/Token过期
403 无权限（RBAC校验不通过）
404 资源不存在
409 资源冲突/重复操作
422 业务逻辑错误
423 账号已锁定
429 请求频率限制
500 服务器内部错误

权限矩阵

接口模块 超级管理员 内容审核员 财务审核员 运营专员 客服
后台账号管理 ✅ — — — —
内容审核 ✅ ✅ — — —
举报处理 ✅ ✅ — — ✅
用户管理 ✅ — — ✅ ✅（只读）
封禁/解封 ✅ — — ✅ —
提现审核 ✅ — ✅ — —
退款处理 ✅ — ✅ — ✅
充值订单 ✅ — ✅ — —
数据注水 ✅ — — ✅ —
内容管理（浏览/排查） ✅ ✅ — ✅ ✅（只读）
强制下架帖子 ✅ ✅ — — —
推荐位 ✅ — — ✅ —
平台配置 ✅ — — — —
活动/标签/敏感词 ✅ — — ✅ —
数据统计 ✅ — ✅（财务） ✅ —
查看聊天记录 ✅ — — — ✅
手动发币 ✅（审批） — — ✅（发起） —

敏感操作审计

以下操作必须写入 admin_operation_log：

操作 接口 风险等级
封禁用户 USER-A03 高
提现审核 FIN-02/03 高
确认打款 FIN-04 高
退款处理 FIN-05 高
手动发放代币 CS-03 高
查看聊天记录 CS-01 中
修改分成比例 CFG-05 高
修改充值档位 CFG-01 中
域名变更 CFG-11 高
强制下架帖子 POST-A04 高

待确认事项

# 问题 影响接口
1 运营后台角色权限划分是否如上述5种角色？ 全部
2 创作者被封禁后，其内容和订阅用户如何处理？ USER-A03
3 手动发放代币是否需要双人审批？ CS-03
4 提现是否需要T+7冻结期？ FIN-01/02
5 内容审核是否接入第三方AI审核？ AUDIT-01/02/03/AUDIT-PPV-01/02
6 数据注水是否需要审批流程？ BOOST-01/03
7 退款是否需要多级审批？ FIN-05
8 运营后台是独立部署还是共用后端？ 全部