yml2213
3631e70321
- 新增 order_checkouts 表，支持结账明细（消耗/押金扣除/退回/号主入账） - 租客发起结账 → 号主确认 → 已完成（正常路径） - 号主修改结账 → 租客确认修正 → 已完成（修正路径） - 结账阶段任一方发起争议 → 后台仲裁 → 已完成/已关闭/异常（争议路径） - 争议模块适配结账争议类型，仲裁结果新增 mark_abnormal - 超时任务适配新的 pending_checkout_confirm 状态 - 前端结账明细面板、发起结账/确认/修正/拒绝表单全部实现 - 移除旧的 SubmitReturn/ConfirmReturn 接口
86 lines
3.7 KiB
Markdown
86 lines
3.7 KiB
Markdown
# API 规划
|
|
|
|
API 规划以 [项目计划](project-plan.md) 第 10 章为准。
|
|
|
|
一期接口按模块推进：
|
|
|
|
- 认证：短信验证码、手机号登录、Token 刷新、退出登录。
|
|
- 实名：发起认证、查询状态、服务回调。
|
|
- 发布：创建、修改、提交审核、下架、列表、详情。
|
|
- 订单：创建、取消、确认收号、发起结账、确认结账、修改结账、确认/拒绝修正、发起申诉。
|
|
- 交接：提交交接说明、查看交接记录。
|
|
- 钱包：余额、流水、提现预留。
|
|
- 通知：站内信列表、标记已读。
|
|
- 后台：审核、订单、仲裁、资金流水、系统配置、审计日志。
|
|
|
|
## 已实现接口
|
|
|
|
- `POST /api/auth/sms/send`
|
|
- `POST /api/auth/sms/login`
|
|
- `POST /api/auth/refresh`
|
|
- `POST /api/auth/logout`
|
|
- `GET /api/me`
|
|
- `POST /api/realname/start`
|
|
- `GET /api/realname/status`
|
|
- `GET /api/listings`
|
|
- `GET /api/listings/{id}`
|
|
- `POST /api/listings`
|
|
- `PUT /api/listings/{id}`
|
|
- `POST /api/listings/{id}/submit-review`
|
|
- `DELETE /api/listings/{id}`
|
|
- `GET /api/seller/listings`
|
|
- `GET /api/seller/listings/{id}`
|
|
- `POST /api/orders`
|
|
- `GET /api/orders`
|
|
- `GET /api/orders/{id}`
|
|
- `POST /api/orders/{id}/cancel`
|
|
- `POST /api/orders/{id}/handoff`
|
|
- `GET /api/orders/{id}/handoff-records`
|
|
- `POST /api/orders/{id}/confirm-receive`
|
|
- `POST /api/orders/{id}/checkout`
|
|
- `POST /api/orders/{id}/checkout/confirm`
|
|
- `POST /api/orders/{id}/checkout/counter`
|
|
- `POST /api/orders/{id}/checkout/accept`
|
|
- `POST /api/orders/{id}/dispute`
|
|
- `GET /api/disputes`
|
|
- `GET /api/disputes/{id}`
|
|
- `GET /api/wallet/balance`
|
|
- `GET /api/wallet/ledger`
|
|
- `POST /api/files/upload`
|
|
- `GET /api/files/object`
|
|
- `GET /api/notifications`
|
|
- `POST /api/notifications/{id}/read`
|
|
- `GET /api/admin/auth/captcha`
|
|
- `POST /api/admin/auth/login`
|
|
- `POST /api/admin/auth/logout`
|
|
- `GET /api/admin/me`
|
|
- `GET /api/admin/dashboard`
|
|
- `GET /api/admin/users`
|
|
- `POST /api/admin/users/{id}/freeze`
|
|
- `POST /api/admin/users/{id}/unfreeze`
|
|
- `GET /api/admin/orders`
|
|
- `GET /api/admin/orders/{id}`
|
|
- `GET /api/admin/orders/{id}/handoff-records`
|
|
- `GET /api/admin/listings`
|
|
- `GET /api/admin/listings/pending`
|
|
- `GET /api/admin/listings/{id}`
|
|
- `POST /api/admin/listings/{id}/approve`
|
|
- `POST /api/admin/listings/{id}/reject`
|
|
- `POST /api/admin/listings/{id}/offline`
|
|
- `POST /api/admin/listings/{id}/mark-abnormal`
|
|
- `POST /api/admin/orders/{id}/close`
|
|
- `POST /api/admin/orders/{id}/mark-abnormal`
|
|
- `GET /api/admin/disputes`
|
|
- `POST /api/admin/disputes/{id}/arbitrate`
|
|
- `GET /api/admin/wallet/ledger`
|
|
- `GET /api/admin/system-configs`
|
|
- `PUT /api/admin/system-configs/{key}`
|
|
- `GET /api/admin/audit-logs`
|
|
- `GET /api/admin/files/object`
|
|
|
|
说明：`POST /api/listings` 和 `PUT /api/listings/{id}` 支持 `screenshot_urls` 数组，用于保存号主上传的账号资产截图地址。`GET /api/admin/listings` 支持按 `owner_id`、`status`、`review_status` 和 `limit` 查询商品。`GET /api/admin/wallet/ledger` 支持按 `user_id`、`order_id`、`biz_type` 和 `limit` 查询最近资金流水。`GET /api/admin/audit-logs` 支持按 `actor_id`、`action`、`biz_type` 和 `limit` 查询最近审计日志。`/api/admin/*` 当前已使用独立后台登录，后续接入 RBAC 和 Casbin 权限后再按角色收紧访问控制。
|
|
|
|
文件上传说明：`POST /api/files/upload` 使用 `multipart/form-data`，文件字段名为 `file`，可选 `scene` 为 `listing`、`handoff`、`dispute`、`realname`、`avatar`；当前允许 10MB 内的 JPG、PNG、WebP 和 PDF。返回的 `url` 为后端代理访问地址。后台查看私有文件使用 `GET /api/admin/files/object?key=...`。
|
|
|
|
订单超时扫描任务为后端内部任务，不暴露公开 API；超时阈值通过 `/api/admin/system-configs` 调整。
|