docs(admin): 补充管理后台 API 与数据库文档 (#12)

新增 admin 模块接口文档(auth login/me、admins CRUD、audit-logs、feedback 处理、stats 概览、user coins/detail/status、wallet 流水、withdraw 对账/刷新/列表) + admin_user/admin_audit_log 两张表文档,更新 api/database README 索引。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: OuYingJun1024 <1034284404@qq.com>
Reviewed-on: #12
Co-authored-by: ouzhou <ouzhou@wonderable.ai>
Co-committed-by: ouzhou <ouzhou@wonderable.ai>
This commit was merged in pull request #12.
This commit is contained in:
ouzhou
2026-06-06 15:58:23 +08:00
committed by marco
parent 07c0b7502c
commit 0e42e96ddb
33 changed files with 800 additions and 18 deletions
+37
View File
@@ -0,0 +1,37 @@
# POST /admin/api/withdraws/reconcile — 批量对账(扫超时 pending 单)
> 所属:Admin·提现 组(前缀 `/admin/api/withdraws` | 鉴权:Bearer admin_token(角色:`finance``super_admin` 恒通过) | [← 返回 API 索引](./README.md)
扫描创建时间超过 `older_than_minutes` 分钟、仍为 `pending` 的提现单,逐单调微信查单并归一化(成功落 `success`;失败/已撤销则退款落 `failed`;查到 `WAIT_USER_CONFIRM` 视为用户放弃,撤单+退款)。用于解开"扣了款但转账没发起/没确认"的孤儿单。单笔失败不影响其余(内部 rollback 后继续,下轮再试)。
> 路由注册顺序上,静态路径 `/reconcile` 必须在路径参数 `/{out_bill_no}/refresh` 之前声明。
## 入参
- 路径:无
- query:
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `older_than_minutes` | int | ❌ | 15 | 只扫创建时间早于「现在 − N 分钟」的 pending 单;`ge=0` |
- body:无
## 出参
响应 `200`:`ReconcileResult`
**ReconcileResult**
| 字段 | 类型 | 说明 |
|---|---|---|
| `checked` | int | 本次扫到的超时 pending 单数量 |
| `resolved` | int | 其中被归一化为终态(success/failed)的数量 |
## 错误码
- `401` 未带/无效/过期 admin token、管理员被禁用(响应头带 `WWW-Authenticate: Bearer`
- `403` 角色不足(需 `finance``super_admin`
- `422` query 参数校验失败(如 `older_than_minutes < 0`
- `503` 微信支付未配置(捕获 `WxPayNotConfiguredError``detail="微信支付未配置"`
## 说明
- 调用底层 `app.repositories.wallet.reconcile_pending_withdraws`(内部逐单调微信查单/撤单/退款,各自 commit)。
- 写操作记审计 [admin_audit_log](../database/admin_audit_log.md)`action="withdraw.reconcile"``detail``{checked, resolved}`,含触发管理员与客户端 IP)。
- 关联 [withdraw_order](../database/withdraw_order.md)。