hfb_sys/docs/api.md

API 规划

API 规划以 项目计划 第 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}/return
• POST /api/orders/{id}/confirm-return
• POST /api/orders/{id}/dispute
• GET /api/disputes
• GET /api/disputes/{id}
• GET /api/wallet/balance
• GET /api/wallet/ledger
• 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/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 权限后再按角色收紧访问控制。

订单超时扫描任务为后端内部任务，不暴露公开 API；超时阈值通过 /api/admin/system-configs 调整。