API 接口总览
API 接口总览
更新日期：2026-06-20。
本文是当前后端接口的总览索引，依据 WinTradeCloudService/wt-admin 和 WinTradeCloudService/wt-client 下的 Controller 注解整理。接口明细仍按业务域维护在各 API 分册中，本文用于快速判断接口规模、端别归属、分册边界和近期需要重点关注的路径变更。
当前接口快照
本次盘点解析到 1348 个后端入口方法：
| 后端入口 | 数量 | 使用端 |
|---|---|---|
wt-admin |
839 |
admin、ops、ops-app 的仓配和配送员作业 |
wt-client |
509 |
client、app、商户侧、个人侧和部分 ops 商户发货能力 |
接口统一以后端 Controller 中的 /api/v1 作为版本路径。前端实际访问时由端口前缀拼接：
| 前端入口 | 实际前缀 | 说明 |
|---|---|---|
admin |
/admin/api/v1，必要时 /client/api/v1 |
管理端默认走管理入口，少量客户端查询走客户端入口 |
client |
/client/api/v1 |
微信原生消费者小程序 |
app |
http://47.108.203.59:8092/client/api/v1 |
Expo 消费者 APP 当前直连客户端网关 |
ops |
/client/api/v1，仓配动作切到 /admin/api/v1 |
微信原生运营小程序 |
ops-app |
https://dev.wintrade.asia/client/api/v1 或 https://uat.wintrade.asia/client/api/v1，按 service 切换 /admin/api/v1 |
Expo 运营 APP |
h5 |
/api/v1 代理到 CLIENT_API_ORIGIN |
活动静态页代理客户端接口 |
分册覆盖
| API 分册 | 接口数 | wt-admin |
wt-client |
主要路径前缀 |
|---|---|---|---|---|
| 认证与账户 | 146 |
97 |
49 |
/captcha、/login、/info、/routers、/account、/user/account、/system/user、/system/role、/system/menu、/system/permission |
| 商品与店铺 | 150 |
85 |
65 |
/product、/merchant/shop、/personal/product、/personal/merchant/shop、/search |
| 交易订单与售后 | 67 |
32 |
35 |
/personal/shopping/cart、/personal/order、/personal/return/order、/merchant/order、/order |
| 物流履约 | 233 |
196 |
37 |
/logistics、/system/logistics |
| 商户与结算 | 134 |
82 |
52 |
/merchant/shop、/merchant/inventory、/merchant/wallet、/merchant/deposit-wallet、/merchant/settlement、/merchant/commission-policy |
| 系统基础数据与文件 | 142 |
100 |
42 |
/system/config、/system/dict、/data、/file、/folder、/monitor |
| 营销与消息 | 398 |
215 |
183 |
/marketing/admin、/merchant/marketing、/market、/message、/personal/message、/merchant/message、/employee/message、/user/personal/coupon-wallet |
另有少量 /test/user 和根路径健康类接口未纳入业务分册，默认不作为前端业务联调依据。
近期重点变更
| 变更点 | 当前口径 | 影响文档 |
|---|---|---|
| 新增消费者 APP | app 使用 Expo、React Native、HeroUI Native、Unwind，当前主要复用 client 侧商品、分类、搜索、卡券和登录接口 |
前端技术文档、系统整体架构设计 |
| 新增 OPS APP | ops-app 使用 Expo、React Native、Expo Camera，复用 ops 现场作业业务，按 service 在 client 和 admin 入口间切换 |
前端技术文档、权限控制体系设计、物流履约 |
| 国内仓快速流程路径收敛 | 当前 Controller 和前端封装使用 /api/v1/logistics/domestic-warehouse/...，不再以 /api/v1/logistics/fast-process/... 作为文档主路径 |
物流履约 |
| 海外仓没有独立路径 | 当前没有 /api/v1/logistics/overseas-warehouse/...，海外仓继续使用 /api/v1/logistics/warehouse/...、/api/v1/logistics/warehouse-inventory/... 和 /api/v1/logistics/warehouse/dispatch/... |
物流履约、物流业务流程设计 |
| 仓库存查询补充流转引用 | /api/v1/logistics/warehouse-inventory/package/list 和详情现在会补充 batchNo、shipmentId、shipmentNo，方便现场通过包裹反查批次和车次 |
物流履约 |
| 正式环境域名仍是占位 | client-we、ops-we、ops-app 的 release 入口仍有 api.example.com，正式发版前必须替换为项目正式网关并同步微信合法域名 |
前端技术文档、系统整体架构设计 |
| 营销与消息接口规模最大 | 营销活动、券池、预算、活动价、补贴确认、站内信、订阅、偏好、待办和统计已成为独立大域 | 营销与消息、营销活动中心功能说明 |
端别选型规则
| 场景 | 推荐后端入口 | 说明 |
|---|---|---|
| 平台管理、配置、审核、监控和日志 | wt-admin |
权限通常以 admin: 开头 |
| 消费者浏览、下单、地址、个人钱包、评价和消息 | wt-client |
权限通常以 client:personal: 或 client:user: 开头 |
| 商户自助经营、商户营销、商户消息和商户待办 | wt-client |
权限通常以 client:merchant: 开头 |
| 运营小程序或 OPS APP 的商户发货 | wt-client |
直接使用商户账号登录和商户数据归属 |
| 运营小程序或 OPS APP 的仓库、海外仓、配送员任务 | wt-admin |
当前接口集中在 admin:logistics:*，后续可评估迁移到独立运营端权限前缀 |
| H5 活动会场 | wt-client 代理 |
h5 只做静态会场和客户端接口代理 |
维护规则
- 后端新增、删除或改名 Controller 路径时，先更新对应 API 分册，再更新本文的分册统计和变更点。
- 前端新增接口封装时，需要确认它属于
admin、client、app、ops、ops-app还是h5，不能只看页面所在工程。 - 状态流转、金额、库存、钱包、预算、补贴和结算类接口必须在分册中补充调用顺序和验收口径。
- 如果接口在
wt-admin和wt-client同名存在，文档需要明确调用端和权限差异，避免前端切错服务前缀。