后台管理接口（/admin）

所有后台接口前缀为 /admin，需 Authorization: Bearer {token} 请求头。

在线接口文档（Apifox，可在线调试）：https://s.apifox.cn/28f8b0b7-abda-470f-8013-4e1b924c47f0

1. 认证接口（/admin/auth）

方法	路径	说明	认证
POST	`/admin/auth/login`	管理员登录（账号+密码）	否
POST	`/admin/auth/wx-login`	微信公众号授权登录	否
POST	`/admin/auth/apple-login`	Apple 授权登录	否
POST	`/admin/auth/refresh-token`	刷新 Token	是
GET	`/admin/auth/tokens`	查询已签发的所有 Token	是
DELETE	`/admin/auth/tokens/{tokenId}`	销毁指定 Token	是
POST	`/admin/auth/logout`	退出登录	是
GET	`/admin/auth/info`	获取当前管理员信息（含角色/按钮权限）	是

2. 管理员管理（/admin/admins）

方法	路径	说明	权限
GET	`/admin/admins`	管理员列表（分页）	admins.index
POST	`/admin/admins`	创建管理员（支持传入头像 `avatar`）	admins.create
GET	`/admin/admins/{id}`	管理员详情	admins.index
PUT	`/admin/admins/{id}`	更新管理员（支持传入头像 `avatar`）	admins.edit
DELETE	`/admin/admins/{id}`	删除管理员	admins.delete
GET	`/admin/admins/profile`	当前管理员资料	-
PUT	`/admin/admins/profile`	更新当前管理员资料	-
POST	`/admin/admins/avatar`	更新头像	-
PUT	`/admin/admins/change-password`	修改当前管理员密码	-
GET	`/admin/admins/{id}/roles`	获取管理员角色	admins.edit
PUT	`/admin/admins/{id}/roles`	分配管理员角色	admins.edit
PUT	`/admin/admins/{id}/toggle-status`	切换管理员状态	admins.edit
PUT	`/admin/admins/{id}/reset-password`	重置管理员密码	admins.edit
GET	`/admin/admins/{id}/login-histories`	管理员登录历史	admins.index

3. 前台用户管理（/admin/users）

方法	路径	说明	权限
GET	`/admin/users`	用户列表（分页）	users.index
GET	`/admin/users/{id}`	用户详情	users.index
PUT	`/admin/users/{id}`	更新用户信息	users.edit
DELETE	`/admin/users/{id}`	删除用户	users.delete
PUT	`/admin/users/{id}/toggle-status`	切换用户状态	users.edit
PUT	`/admin/users/{id}/reset-password`	重置用户密码	users.edit
PUT	`/admin/users/{id}/reset-contact`	重置用户手机号/邮箱	users.edit
PUT	`/admin/users/{id}/adjust-balance`	调整用户积分/金币余额	users.edit
PUT	`/admin/users/{id}/extend-vip`	延长 VIP 有效期	users.edit
GET	`/admin/users/{id}/login-histories`	用户登录历史	users.index
GET	`/admin/users/{id}/socials`	用户第三方绑定	users.index
GET	`/admin/users/{id}/point-trades`	用户积分流水	users.index
GET	`/admin/users/{id}/coin-trades`	用户金币流水	users.index
GET	`/admin/users/export`	导出用户列表（xlsx）	users.export
GET	`/admin/users/{id}/point-trades/export`	导出用户积分流水（xlsx）	users.export
GET	`/admin/users/{id}/coin-trades/export`	导出用户金币流水（xlsx）	users.export
GET	`/admin/users/{user}/wallet`	指定用户钱包概览	users.index
GET	`/admin/users/{user}/wallet-trades`	指定用户钱包流水（分页）	users.index
PUT	`/admin/users/{user}/adjust-wallet`	后台调整用户余额	wallet.adjust

4. 角色管理（/admin/roles）

方法	路径	说明	权限
GET	`/admin/roles`	角色列表	roles.index
POST	`/admin/roles`	创建角色	roles.create
GET	`/admin/roles/{id}`	角色详情	roles.index
PUT	`/admin/roles/{id}`	更新角色	roles.edit
DELETE	`/admin/roles/{id}`	删除角色	roles.delete
GET	`/admin/roles/permissions`	获取全部权限列表	roles.index
GET	`/admin/roles/{id}/permissions`	获取角色权限	roles.index
PUT	`/admin/roles/{id}/permissions`	分配角色权限	roles.edit

5. 菜单管理（/admin/menus）

方法	路径	说明	权限
GET	`/admin/menus`	获取菜单树	menus.index
POST	`/admin/menus`	创建菜单	menus.create
GET	`/admin/menus/{id}`	菜单详情	menus.index
PUT	`/admin/menus/{id}`	更新菜单	menus.edit
DELETE	`/admin/menus/{id}`	删除菜单	menus.delete
GET	`/admin/routes`	获取前端路由配置（按当前管理员权限过滤）	-

6. 缓存管理（/admin/cache）

方法	路径	说明	认证
POST	`/admin/cache/clear`	清理应用缓存（types=all/settings，支持数组多选）	是

7. 配置管理（/admin/settings）

方法	路径	说明	权限
GET	`/admin/settings`	配置列表（分页）	settings.index
POST	`/admin/settings`	创建配置	settings.create
GET	`/admin/settings/{id}`	配置详情	settings.index
PUT	`/admin/settings/{id}`	更新配置	settings.edit
DELETE	`/admin/settings/{id}`	删除配置	settings.delete
GET	`/admin/settings/groups`	获取配置分组列表	settings.index
GET	`/admin/settings/input-types`	获取支持的输入类型	settings.index
PUT	`/admin/settings/batch`	批量更新配置值	settings.edit

8. 字典管理（/admin/dicts）

方法	路径	说明	权限
GET	`/admin/dicts`	字典类型列表（分页，支持关键字/状态筛选）	dicts.index
POST	`/admin/dicts`	创建字典类型	dicts.create
GET	`/admin/dicts/{id}`	字典详情（含字典项）	dicts.index
PUT	`/admin/dicts/{id}`	更新字典	dicts.edit
DELETE	`/admin/dicts/{id}`	删除字典（级联删除字典项）	dicts.delete

9. 字典数据管理（/admin/dict-items）

方法	路径	说明	权限
GET	`/admin/dict-items`	字典项列表（分页，支持按 dict_id 筛选）	dict-items.index
POST	`/admin/dict-items`	创建字典项	dict-items.create
GET	`/admin/dict-items/{id}`	字典项详情	dict-items.index
PUT	`/admin/dict-items/{id}`	更新字典项	dict-items.edit
DELETE	`/admin/dict-items/{id}`	删除字典项	dict-items.delete

10. 地区管理（/admin/areas）

方法	路径	说明	权限
GET	`/admin/areas`	获取地区树	areas.index
POST	`/admin/areas`	创建地区	areas.create
GET	`/admin/areas/{id}`	地区详情	areas.index
PUT	`/admin/areas/{id}`	更新地区	areas.edit
DELETE	`/admin/areas/{id}`	删除地区	areas.delete

11. 通知管理（/admin/notifications）

方法	路径	说明	认证
GET	`/admin/notifications`	通知列表（分页）	是
GET	`/admin/notifications/unread`	未读通知列表/未读数	是
PUT	`/admin/notifications/mark-read`	标记单条已读	是
PUT	`/admin/notifications/mark-all-read`	全部标记已读	是
DELETE	`/admin/notifications/clear-read`	清理已读通知	是

12. 评论管理（/admin/comments）

方法	路径	说明	权限
GET	`/admin/comments`	评论列表（分页，支持 `status`/`source_type`/`keyword`/`user_id` 过滤）	comments.index
GET	`/admin/comments/{comment}`	评论详情（含 `ip_address`、`is_reply`、`parent_comment` 上级评论摘要）	comments.index
GET	`/admin/comments/{comment}/replies`	回复列表（分页，返回该评论下的直接回复）	comments.index
POST	`/admin/comments/{comment}/review`	审核评论（`status` 取 `approved`/`rejected`/`review`，可选 `remark`）	comments.edit
POST	`/admin/comments/{comment}/ai-review`	AI 敏感词命中智能复核（先本地词库检测命中词，再由 AI 语境复核减少误杀；返回 `suggestion`(approve/reject)/`reason`/`hits`，仅辅助建议不改状态）	comments.edit
DELETE	`/admin/comments/{comment}`	删除评论	comments.delete
GET	`/admin/comments/export`	导出评论列表（xlsx）	comments.export

评论父子关系通过多态自关联实现：回复的 source_type='comment'、source_id 指向父评论 ID。列表接口不返回 ip_address，仅详情接口返回。

13. 实名认证（/admin/identity-verifications）

方法	路径	说明	权限
GET	`/admin/identity-verifications`	认证记录列表（分页，支持 `keyword`/`user_id`/`type`/`status`/`start_date`/`end_date` 过滤）	identity-verifications.index
GET	`/admin/identity-verifications/stats`	认证统计（总量/待审/今日新增/已通过/已驳回）	identity-verifications.index
GET	`/admin/identity-verifications/{verification}`	认证记录详情（含证件附件 URL）	identity-verifications.index
POST	`/admin/identity-verifications/{verification}/approve`	审核通过（同步 `users.identity_verified`/`identity_type`）	identity-verifications.edit
POST	`/admin/identity-verifications/{verification}/reject`	审核驳回（必填 `reason`、可选 `remark`）	identity-verifications.edit

同一用户同时仅允许一条 pending/review 记录；已认证用户禁止再次提交，驳回后可重新提交。

14. 反馈管理（/admin/feedbacks）

方法	路径	说明	权限
GET	`/admin/feedbacks`	反馈列表（分页，支持 `keyword`/`type`/`status`/`priority` 过滤）	feedbacks.index
GET	`/admin/feedbacks/stats`	反馈统计（总量、待推进、今日新增、已闭环）	feedbacks.index
GET	`/admin/feedbacks/{feedback}`	反馈详情（含附件图片、客户端信息）	feedbacks.index
PUT	`/admin/feedbacks/{feedback}`	处理反馈（调整 `status`/`priority`、填写 `admin_remark`）	feedbacks.edit
POST	`/admin/feedbacks/{feedback}/draft-reply`	AI 草拟处理回复（按反馈类型/标题/内容生成 `draft` 草稿，不修改反馈）	feedbacks.edit
DELETE	`/admin/feedbacks/{feedback}`	删除反馈	feedbacks.delete
GET	`/admin/feedbacks/export`	导出反馈列表（xlsx）	feedbacks.export

14b. 举报管理（/admin/reports）

方法	路径	说明	权限
GET	`/admin/reports`	举报列表（分页，支持 `keyword`/`status`/`category`/`reportable_type`/`handler_id`/`start_date`/`end_date` 过滤）	reports.index
GET	`/admin/reports/stats`	举报统计（总量、待处理、今日新增、已结案）	reports.index
GET	`/admin/reports/{report}`	举报详情（含 `reason`、`evidence`、`reportable_snapshot` 被举报对象快照、`process_actions`/`process_remark` 处理记录）	reports.index
PUT	`/admin/reports/{report}`	处理举报（`status` ∈ `resolved`/`rejected`，可选 `remark`，可选 `actions` 联动处置数组：含 `type` ∈ `hide_comment`/`delete_comment`/`freeze_user` 与可选 `reason`；冻结为永久，不携带时长字段，需管理员人工解冻）	reports.edit
POST	`/admin/reports/{report}/ai-triage`	AI 举报智能初判（结合举报分类/描述/被举报内容返回 `suggestion`(uphold/reject)/`reason`，仅辅助建议不改状态；已结案返回 422）	reports.edit
GET	`/admin/reports/export`	导出举报列表（xlsx，同步/异步双通道，阈值 1000 行）	reports.export

被举报对象使用多态 reportable_type 存储 morph alias（comment / user，由 Relation::enforceMorphMap() 全局别名统一管理；列表筛选参数 reportable_type 同样按 alias 取值），详情接口返回按 reportable_snapshot.type 区分的快照（comment/user），对象已被删除时返回 null。
联动处置仅在 status=resolved 时执行；status=rejected 不下发动作。
冻结用户为永久冻结（仅设置 status=FROZEN，用户表未存储冻结截止时间），需管理员通过「用户管理 → 状态切换」人工解冻。
同一管理员连续处理的中间状态由 pending → processing 自动流转，避免多人重复操作；已结案（resolved/rejected）的举报不可再次处理。
状态机：pending（待处理） → processing（处理中，自动） → resolved（已处理）/ rejected（已驳回，管理员手动）

15. 公共选项（/admin/common）

方法	路径	说明	认证
GET	`/admin/common/source-types`	多态源类型选项列表（基于 `config/morph_maps.php`，返回 `[{label, value}]`）	是

与业务模块无关的通用选项、枚举、字典类接口统一由 CommonController 承载，仅需登录态，不绑定业务权限。

16. 验证码管理

方法	路径	说明	权限
GET	`/admin/phone-codes`	短信验证码列表	phone-codes.index
GET	`/admin/phone-codes/{id}`	短信验证码详情	phone-codes.index
GET	`/admin/mail-codes`	邮件验证码列表	mail-codes.index
GET	`/admin/mail-codes/{id}`	邮件验证码详情	mail-codes.index

17. 上传管理（/admin/uploader）

方法	路径	说明	认证
POST	`/admin/uploader/file`	上传通用文件	是
POST	`/admin/uploader/image`	上传图片	是
POST	`/admin/uploader/video`	上传视频	是
POST	`/admin/uploader/apk`	上传 APK 安装包	是
POST	`/admin/uploader/token`	获取直传 Token（S3 兼容）	是

上传成功后返回字段包含附件 id，前端可直接用于附件管理。

18. 附件管理（/admin/attachments）

方法	路径	说明	权限
GET	`/admin/attachments/disks`	获取可用存储磁盘列表	attachments.index
GET	`/admin/attachments`	附件列表（分页+筛选）	attachments.index
POST	`/admin/attachments/register`	直传完成后登记元数据	attachments.create
GET	`/admin/attachments/{id}`	附件详情	attachments.index
PUT	`/admin/attachments/{id}/rename`	重命名显示名	attachments.edit
PUT	`/admin/attachments/{id}/move`	移动物理路径	attachments.edit
DELETE	`/admin/attachments/{id}`	删除单个附件	attachments.delete
DELETE	`/admin/attachments`	批量删除附件（ids 数组）	attachments.delete
GET	`/admin/attachments/{id}/download`	流式下载	attachments.index
GET	`/admin/attachments/{id}/temporary-url`	临时签名 URL	attachments.index

列表筛选参数：per_page、type、disk、keyword、extension、uploader_id、start_date、end_date。

附件资源字段：

字段	类型	说明
id	int	附件 ID
name	string	显示名称
original_name	string	原始文件名
disk	string	存储磁盘
path	string	存储路径
url	string\|null	可访问 URL（公有盘直链，私有盘为 null）
type	object	附件类型（value + label）
extension	string	扩展名
mime_type	string	MIME 类型
size	int	字节数
size_text	string	人类可读大小
exists	bool	物理文件是否存在（仅详情接口返回）
uploader	object\|null	上传者摘要（id + name）
created_at	string	创建时间

19. 应用管理（/admin/apps）

方法	路径	说明	权限
GET	`/admin/apps`	应用列表（分页，支持关键字/状态/日期筛选，预加载各平台最新版本）	apps.index
POST	`/admin/apps`	创建应用	apps.create
GET	`/admin/apps/{id}`	应用详情	apps.index
PUT	`/admin/apps/{id}`	更新应用	apps.edit
DELETE	`/admin/apps/{id}`	删除应用（软删除）	apps.delete

应用资源字段包含 latest_versions（各平台最多 3 条已发布版本，按 build 倒序）。

20. 应用版本管理（/admin/apps/{app}/versions）

方法	路径	说明	权限
GET	`/admin/apps/{app}/versions`	版本列表（分页，支持平台/状态/版本号/强制更新/日期筛选）	app-versions.index
POST	`/admin/apps/{app}/versions`	创建版本	app-versions.create
GET	`/admin/apps/{app}/versions/{version}`	版本详情	app-versions.index
PUT	`/admin/apps/{app}/versions/{version}`	更新版本	app-versions.edit
DELETE	`/admin/apps/{app}/versions/{version}`	删除版本（已发布状态不可删除）	app-versions.delete
POST	`/admin/apps/{app}/versions/{version}/publish`	发布版本（自动将同平台旧已发布版本置为废弃）	app-versions.edit
POST	`/admin/apps/{app}/versions/{version}/withdraw`	撤回版本（仅已发布状态可撤回）	app-versions.edit
POST	`/admin/apps/{app}/versions/{version}/obsolete`	废弃版本	app-versions.edit

21. 审计日志（/admin/audit-logs）

方法	路径	说明	权限
GET	`/admin/audit-logs`	审计日志列表（分页，支持时间范围/管理员/方法筛选）	audit-logs.index
GET	`/admin/audit-logs/{id}`	审计日志详情（含请求体、响应）	audit-logs.index
GET	`/admin/audit-logs/export`	导出审计日志（xlsx）	audit-logs.export

22. 调度任务日志（/admin/schedule-logs）

方法	路径	说明	权限
GET	`/admin/schedule-logs`	调度日志列表（分页，支持任务名/状态/时间范围筛选）	schedule-logs.index
GET	`/admin/schedule-logs/{id}`	调度日志详情	schedule-logs.index

23. 钱包管理（/admin/wallet）

方法	路径	说明	权限
GET	`/admin/wallet/stats`	钱包统计（总余额、总冻结、累计充值、累计提现、待审提现数）	wallet.index
GET	`/admin/wallet/trades`	全局钱包流水列表（分页，支持 `owner_type`/`owner_id`/`type`/`status`/关键词/时间范围筛选）	wallet.index
GET	`/admin/wallet/trades/{trade}`	钱包流水详情（含持有者摘要、业务来源摘要、前后余额快照）	wallet.index
GET	`/admin/wallet/trades/export`	导出钱包流水（xlsx）	wallet.export

24. 提现审核（/admin/wallet/withdraws）

方法	路径	说明	权限
GET	`/admin/wallet/withdraws/stats`	提现统计（总量/待审/今日新增/已通过/已驳回/打款成功/打款失败）	wallet.withdraws
GET	`/admin/wallet/withdraws`	提现申请列表（分页，支持 `owner_type`/`owner_id`/`status`/`account_type`/`order_no`/`start_date`/`end_date` 筛选）	wallet.withdraws
GET	`/admin/wallet/withdraws/{withdraw}`	提现申请详情（含 `owner` 关联、收款账户脱敏展示）	wallet.withdraws
POST	`/admin/wallet/withdraws/{withdraw}/approve`	审核通过（可选 `remark`，状态转 `approved`，保持冻结待打款）	wallet.withdraws
POST	`/admin/wallet/withdraws/{withdraw}/reject`	审核驳回（必填 `reason`、可选 `remark`，自动解冻并通知用户）	wallet.withdraws
POST	`/admin/wallet/withdraws/{withdraw}/transfer`	标记已打款（可选 `remark`，状态转 `success`，扣减冻结余额并通知用户）	wallet.withdraws
POST	`/admin/wallet/withdraws/{withdraw}/fail`	标记打款失败（必填 `reason`、可选 `remark`，自动解冻并通知用户）	wallet.withdraws
GET	`/admin/wallet/withdraws/export`	导出提现申请（xlsx，阈值 2000 条同步导出）	wallet.export

提现状态流转：pending →（approve）approved →（transfer）success；pending →（reject）rejected（自动解冻退回）；approved →（fail）failed（自动解冻退回）。已进入终态（success/rejected/failed）的记录不可重复操作，接口幂等返回。响应使用 Admin\WithdrawResource，收款账号通过 maskedAccountInfo() 脱敏（前 2 + **** + 后 4）。

25. 充值订单（/admin/wallet/recharges）

方法	路径	说明	权限
GET	`/admin/wallet/recharges`	充值订单列表（分页，支持 `owner_type`/`owner_id`/`pay_status`/`pay_channel`/`order_no`/时间范围筛选）	wallet.orders
GET	`/admin/wallet/recharges/stats`	充值统计（累计/今日金额、赠送总额、订单数、成功率）	wallet.orders
GET	`/admin/wallet/recharges/{recharge}`	充值订单详情（含渠道原始回调报文）	wallet.orders
POST	`/admin/wallet/recharges/{recharge}/confirm`	手动确认到账（幂等，入账并发站内信通知）	wallet.orders
POST	`/admin/wallet/recharges/{recharge}/close`	关闭订单（仅待支付可关闭）	wallet.orders
GET	`/admin/wallet/recharges/export`	导出充值订单（xlsx）	wallet.export

支付渠道对接已挂起，当前到账依赖管理员手动确认。确认接口具备三重幂等保障（行锁 + 状态判定 + transaction_id 唯一索引），重复调用不会重复入账。详见 docs/technical-solutions/wallet.md 第 12.1 节。

26. 数据概览（/admin/dashboard）

方法	路径	说明	认证
GET	`/admin/dashboard/stats`	仪表盘统计数据	是

27. 监控接口（/admin/monitor，读取 Pulse 数据）

方法	路径	说明
GET	`/admin/monitor/servers`	服务器性能指标
GET	`/admin/monitor/queues`	队列负载
GET	`/admin/monitor/reverb/connections`	Reverb 连接数
GET	`/admin/monitor/reverb/messages`	Reverb 消息吞吐
GET	`/admin/monitor/cache`	缓存命中率
GET	`/admin/monitor/exceptions`	异常统计
GET	`/admin/monitor/slow-queries`	慢查询
GET	`/admin/monitor/slow-requests`	慢请求
GET	`/admin/monitor/slow-jobs`	慢任务
GET	`/admin/monitor/slow-outgoing-requests`	慢外部请求
GET	`/admin/monitor/usage`	使用情况

28. 调试接口（/admin/debug，仅 local 环境，读取 Telescope）

方法	路径	说明
GET	`/admin/debug/tags`	获取标签列表
POST	`/admin/debug/tags`	监控指定标签
DELETE	`/admin/debug/tags`	取消监控标签
POST	`/admin/debug/toggle-recording`	开启/暂停记录
GET	`/admin/debug/entries`	条目列表（分页）
GET	`/admin/debug/entries/{id}`	条目详情
PUT	`/admin/debug/entries/{id}/resolve`	标记已解决
DELETE	`/admin/debug/entries`	删除条目

29. 队列管理（/admin/queue，代理 Horizon 数据）

方法	路径	说明
GET	`/admin/queue/stats`	队列总体统计
GET	`/admin/queue/workload`	队列工作负载
GET	`/admin/queue/masters`	Master 进程状态
GET	`/admin/queue/monitoring/tags`	监控标签列表
GET	`/admin/queue/monitoring/jobs`	监控任务列表
POST	`/admin/queue/monitoring/tags`	添加监控标签
DELETE	`/admin/queue/monitoring/tags/{tag}`	移除监控标签
GET	`/admin/queue/metrics/jobs`	任务吞吐指标
GET	`/admin/queue/metrics/jobs/{id}`	任务指标详情
GET	`/admin/queue/metrics/queues`	队列指标
GET	`/admin/queue/metrics/queues/{id}`	队列指标详情
GET	`/admin/queue/batches`	批处理列表
GET	`/admin/queue/batches/{id}`	批处理详情
POST	`/admin/queue/batches/{id}/retry`	重试失败批次
GET	`/admin/queue/jobs/pending`	待处理任务
GET	`/admin/queue/jobs/completed`	已完成任务
GET	`/admin/queue/jobs/silenced`	静默任务
GET	`/admin/queue/jobs/failed`	失败任务
GET	`/admin/queue/jobs/failed/{id}`	失败任务详情
POST	`/admin/queue/jobs/failed/{id}/retry`	重试失败任务
GET	`/admin/queue/jobs/{id}`	任务详情

30. AI 聊天（/admin/chat，SSE 流式）

全部接口需 chat.use 权限点，缺失时返回 403。

方法	路径	说明	认证
GET	`/admin/chat/conversations`	会话列表	是（`chat.use`）
GET	`/admin/chat/conversations/{id}`	会话详情（含消息历史）	是（`chat.use`）
POST	`/admin/chat`	发送消息（SSE 流式响应）	是（`chat.use`）
POST	`/admin/chat/approve`	审批工具调用并继续执行	是（`chat.use`）
DELETE	`/admin/chat/conversations/{id}`	删除会话	是（`chat.use`）

工具可用性随当前管理员角色权限动态过滤（详见「AI 助手」功能文档的权限控制章节），无权限的工具不会暴露给模型，越权调用在执行层兜底拒绝。

SSE 流式响应通过 text/event-stream 逐行推送以下事件类型：

text：文本增量
reasoning：思考过程
tool_call：工具调用信息
tool_approval_required：需要人工审批的敏感操作
error：错误
done：流结束

31. 用户分群管理（/admin/user-segments）

方法	路径	说明	权限
GET	`/admin/user-segments`	分群列表（分页，支持 `keyword`/`type`/`group`/`status` 筛选）	segments.index
POST	`/admin/user-segments`	新建分群（规则分群必填 `code` + `rule`）	segments.create
GET	`/admin/user-segments/options`	启用手动分群下拉选项（公告群发复用）	segments.index
GET	`/admin/user-segments/{id}`	分群详情（含 `users_count`）	segments.index
PUT	`/admin/user-segments/{id}`	更新分群（规则分群禁止改 `code`/`rule`/`type`）	segments.edit
DELETE	`/admin/user-segments/{id}`	删除分群（级联清理 memberships）	segments.delete
PUT	`/admin/user-segments/{id}/toggle-status`	启用/停用切换	segments.edit
POST	`/admin/user-segments/{id}/sync`	手动触发规则同步（增量 diff）	segments.edit
GET	`/admin/user-segments/{id}/preview`	规则预览（不写库，返回 `total` + `sample`）	segments.index
GET	`/admin/user-segments/{id}/users`	分群下用户列表（分页，支持 `keyword` 筛选）	segments.index
POST	`/admin/user-segments/{id}/attach`	单分群批量绑定用户（>1000 异步入队返回 202）	segments.edit
POST	`/admin/user-segments/{id}/detach`	单分群批量解绑用户（>1000 异步入队返回 202）	segments.assign
POST	`/admin/user-segments/batch-attach`	笛卡尔批量打标（任一维度 >1000 异步入队）	segments.edit
POST	`/admin/user-segments/batch-detach`	笛卡尔批量解标（任一维度 >1000 异步入队）	segments.assign

分群类型：type=1 手动分群（人工打标/解标），type=2 规则分群（基于规则 JSON 自动匹配，定时同步 + 手动同步）。规则分群的 code 必填且唯一，更新时不可修改 code/rule/type。批量操作超过 BATCH_LIMIT=1000 时自动入队 BulkSegmentTaskJob，返回 202 + task_id，任务完成后发送站内信通知。

分群资源字段：

字段	类型	说明
id	int	分群 ID（从 10000000 起）
code	string\|null	分群编码（规则分群必填且唯一）
name	string	分群名称
label_type	string	标签样式（default/primary/success/warning/danger/info）
type	int	分群类型（1=手动，2=规则）
type_label	string	分群类型标签
group	string\|null	分组（用户画像/运营分群/风控等）
description	string\|null	分群说明
sort	int	排序权重（越小越靠前）
status	bool	启用状态
rule	object\|null	规则定义（仅 type=2 有效）
last_synced_at	string\|null	最近一次规则刷新时间
last_synced_user_count	int\|null	最近一次规则匹配用户数
users_count	int\|null	分群用户数（仅详情接口返回）
created_at	string	创建时间
updated_at	string	更新时间

规则 JSON 结构：

json

{
  "version": 1,
  "logic": "and",
  "conditions": [
    {
      "field": "status",
      "operator": "=",
      "value": 1
    },
    {
      "field": "last_active_at",
      "operator": ">",
      "value": "now-7d"
    }
  ]
}

规则字段（25 个）：

主表字段：status、identity_status、identity_type、vip_expires_at、last_login_at、last_active_at、created_at、available_points、available_coins、login_count、balance（可用余额）、frozen_balance（冻结余额）、email、phone、username（后三者仅支持 is_null/is_not_null 判定绑定状态）
profile 关联字段：gender、birthday、province_id（省份 ID）、city_id（城市 ID）
extra 关联字段：email_verified_at（邮箱验证时间，仅支持空值判定）
关系存在性字段：social_provider（社交平台绑定，= 已绑定 / != 未绑定，取值 wechat_mp/wechat_app/wechat_mini_program/apple/douyin/kuaishou/xiaohongshu）
关系计数字段：recharge_count（充值次数，仅统计已到账）、withdraw_count（提现次数）、invite_count（邀请人数），仅支持比较操作符
关系求和字段：recharge_total（累计充值金额，仅统计已到账，支持比较与 between；无充值记录的用户不会被 = 0 类条件命中）

gender（性别：0=保密/1=男/2=女）、birthday（生日）、province_id、city_id 字段位于 user_profiles 表，通过 profile 关联查询；email_verified_at 位于 user_extras 表，通过 extra 关联查询。

操作符（11 种）：=、!=、>、>=、<、<=、between、in、not_in、is_null、is_not_null。

动态时间值：now、today、now-7d、now-3h、today-1d 等。

32. 分群异步任务（/admin/segment-tasks）

方法	路径	说明	权限
GET	`/admin/segment-tasks`	当前管理员的异步任务列表（分页，支持 `status`/`type` 筛选）	segments.assign
GET	`/admin/segment-tasks/{id}`	异步任务详情（含进度百分比）	segments.assign

任务由批量打标/解标超限时自动创建，仅可查看本人提交的任务。任务状态流转：pending → running → completed/failed。

任务资源字段：

字段	类型	说明
id	int	任务 ID
admin_id	int	提交任务的管理员 ID
type	string	任务类型（attach 打标 / detach 解标）
type_label	string	任务类型标签
status	string	状态（pending/running/completed/failed）
status_label	string	状态标签
total_count	int	计划处理总数
processed_count	int	已处理数
added_count	int	实际新增/解绑数
progress_percent	int	进度百分比（0-100）
error_message	string\|null	失败原因
started_at	string\|null	开始执行时间
finished_at	string\|null	完成时间
created_at	string	创建时间

33. AI 知识库（/admin/knowledge-documents）

RAG 知识库管理。文档保存后自动派发异步索引任务（段落分块 + Embedding 向量化，经队列执行），仅「已完成索引且启用」的文档参与语义检索；AI 助手内置 SearchKnowledgeBase 工具按 knowledge-documents.index 权限检索知识库。

方法	路径	说明	权限
GET	`/admin/knowledge-documents`	文档列表（分页，支持 `keyword` 标题搜索、`status` 索引状态、`is_enabled` 筛选）	knowledge-documents.index
POST	`/admin/knowledge-documents`	新增文档（自动派发索引任务，状态置为 pending）	knowledge-documents.create
GET	`/admin/knowledge-documents/{id}`	文档详情（含原始内容 content）	knowledge-documents.index
PUT	`/admin/knowledge-documents/{id}`	更新文档（content 变更时自动重建索引）	knowledge-documents.edit
PUT	`/admin/knowledge-documents/{id}/toggle-status`	切换启用状态（停用不参与检索）	knowledge-documents.edit
POST	`/admin/knowledge-documents/{id}/reindex`	重建索引（重置为 pending 并重新分块向量化）	knowledge-documents.edit
DELETE	`/admin/knowledge-documents/{id}`	删除文档（分块级联删除）	knowledge-documents.delete
GET	`/admin/knowledge-documents/{id}/chunks`	文档分块列表（分页）	knowledge-documents.index
POST	`/admin/knowledge-documents/search`	语义检索测试（`query` 必填、`limit` 默认 5 最大 10，按余弦相似度降序返回 Top-N 分块及来源文档、得分）	knowledge-documents.index

索引状态流转：pending → processing → ready/failed；失败原因记录在文档 error 字段，可通过 reindex 重建。向量模型由 config/ai.php 的 volc provider 提供（默认 doubao-embedding-vision-251215，可用 VOLC_EMBEDDINGS_MODEL / VOLC_EMBEDDINGS_DIMENSIONS 覆盖）。

文档资源字段：

字段	类型	说明
id	int	文档 ID
title	string	文档标题
content	string	原始内容（仅详情接口返回）
status	string	索引状态（pending/processing/ready/failed）
status_label	string	索引状态文案
status_type	string	索引状态标签样式
is_enabled	bool	是否启用
chunks_count	int	分块数量
tokens	int	向量化消耗的 Tokens
error	string\|null	最近一次索引失败原因
created_by	int\|null	创建管理员 ID
created_at	string\|null	创建时间
updated_at	string\|null	更新时间

34. AI 辅助内容生产（/admin/announcements、/admin/banners）

复用 laravel/ai 一次性生成能力为运营场景提供 AI 辅助（Copywriter 文案 Agent + Seedream 绘图）。所有接口仅生成内容不落库，由管理员检查后通过原有 CRUD 接口提交。

方法	路径	说明	权限
POST	`/admin/announcements/ai-copy`	AI 生成公告文案（入参 `brief` 需求简述；返回 `title`/`summary`/`content`(HTML)）	announcements.create
POST	`/admin/banners/ai-copy`	AI 生成 Banner 文案（入参 `brief`；返回 `title` 与 `image_prompt` 绘图提示词）	banners.create
POST	`/admin/banners/ai-image`	AI 生成 Banner 配图（入参 `prompt` 绘图提示词；Seedream 3:2 横版绘图并落盘，返回 `path`/`url`；生图调用已设置 300 秒超时）	banners.create

配套的审核辅助接口分布见各业务章节：评论 AI 复核（12 章）、反馈 AI 草拟（14 章）、举报 AI 初判（14b 章）。

协议管理（/admin/agreements）

方法	路径	说明	权限
GET	`/admin/agreements`	协议列表（分页，支持 `keyword` 标题搜索、`category` 类别、`status` 状态筛选）	agreements.index
POST	`/admin/agreements`	创建协议	agreements.create
GET	`/admin/agreements/{id}`	协议详情	agreements.index
PUT	`/admin/agreements/{id}`	更新协议	agreements.edit
PUT	`/admin/agreements/{id}/toggle-status`	切换状态（草稿→已发布→已归档）	agreements.edit
DELETE	`/admin/agreements/{id}`	删除协议（软删除）	agreements.delete

协议类别（category）使用字典管理，字典编码为 agreement_category，字典项的 value 即为协议类别编码。前台公开接口 GET /api/v1/agreements/{category} 按类别返回最新已发布版本。状态流转：draft →（toggle）published（自动写入 effective_at）→（toggle）archived →（toggle）published。

文档来源：PRD 第 6.3 节

后台管理接口（/admin） ​

1. 认证接口（/admin/auth） ​

2. 管理员管理（/admin/admins） ​

3. 前台用户管理（/admin/users） ​

4. 角色管理（/admin/roles） ​

5. 菜单管理（/admin/menus） ​

6. 缓存管理（/admin/cache） ​

7. 配置管理（/admin/settings） ​

8. 字典管理（/admin/dicts） ​

9. 字典数据管理（/admin/dict-items） ​

10. 地区管理（/admin/areas） ​

11. 通知管理（/admin/notifications） ​

12. 评论管理（/admin/comments） ​

13. 实名认证（/admin/identity-verifications） ​

14. 反馈管理（/admin/feedbacks） ​

14b. 举报管理（/admin/reports） ​

15. 公共选项（/admin/common） ​

16. 验证码管理 ​

17. 上传管理（/admin/uploader） ​

18. 附件管理（/admin/attachments） ​

19. 应用管理（/admin/apps） ​

20. 应用版本管理（/admin/apps/{app}/versions） ​

21. 审计日志（/admin/audit-logs） ​

22. 调度任务日志（/admin/schedule-logs） ​

23. 钱包管理（/admin/wallet） ​

24. 提现审核（/admin/wallet/withdraws） ​

25. 充值订单（/admin/wallet/recharges） ​

26. 数据概览（/admin/dashboard） ​

27. 监控接口（/admin/monitor，读取 Pulse 数据） ​

28. 调试接口（/admin/debug，仅 local 环境，读取 Telescope） ​

29. 队列管理（/admin/queue，代理 Horizon 数据） ​

30. AI 聊天（/admin/chat，SSE 流式） ​

31. 用户分群管理（/admin/user-segments） ​

32. 分群异步任务（/admin/segment-tasks） ​

33. AI 知识库（/admin/knowledge-documents） ​

34. AI 辅助内容生产（/admin/announcements、/admin/banners） ​

协议管理（/admin/agreements） ​