系统整体架构设计
系统整体架构设计
更新日期：2026-05-31。
本文用于指导 admin、client、ops、h5 与 WinTradeCloudService 的前后端联调。文档重点说明系统边界、请求链路、接口前缀、鉴权方式、核心业务联调顺序和排查路径。
架构目标
系统整体架构需要满足以下目标：
| 目标 | 说明 |
|---|---|
| 多端统一 | admin、client、ops 共用同一套后端业务能力 |
| 入口清晰 | 管理端能力走 admin 接口入口，客户端能力走 client 接口入口 |
| 权限可控 | 平台、商户、消费者、仓库管理员、配送员按身份和权限访问数据 |
| 状态一致 | 商品、订单、物流、结算等状态以后端为准，前端只展示和触发动作 |
| 联调可追踪 | 每个页面、接口、状态和错误都能定位到明确模块和责任边界 |
总体架构
flowchart TD
Admin["admin 平台管理端<br/>Vue 3 + Element Plus"] --> AdminProxy["/admin/api/v1<br/>/client/api/v1"]
Client["client 消费者小程序<br/>微信原生小程序 + Vant WeApp"] --> ClientGateway["/client/api/v1"]
Ops["ops 运营小程序<br/>微信原生小程序 + Vant WeApp"] --> ClientGateway
Ops --> AdminGateway["/admin/api/v1"]
H5["h5 活动会场<br/>Bun 静态服务"] --> H5Proxy["/api/v1"]
AdminProxy --> AdminApi["wt-admin<br/>管理端接口入口"]
AdminGateway --> AdminApi
ClientGateway --> ClientApi["wt-client<br/>客户端接口入口"]
H5Proxy --> ClientApi
AdminApi --> Domain["业务模块"]
ClientApi --> Domain
Domain --> Business["wt-business<br/>订单 / 商户 / 结算"]
Domain --> Logistics["wt-logistics<br/>物流 / 仓配 / 运单"]
Domain --> User["wt-user<br/>账户 / 地址 / 钱包"]
Domain --> Market["wt-market<br/>营销活动 / 优惠券 / 活动价"]
Domain --> Message["wt-message<br/>消息 / 待办"]
Domain --> File["wt-file<br/>文件 / OSS"]
Domain --> System["wt-system<br/>菜单 / 权限 / 字典"]
端口职责
| 端口 | 目录 | 主要接口入口 | 负责内容 | 不负责内容 |
|---|---|---|---|---|
| 平台管理端 | admin |
/admin/api/v1，少量 /client/api/v1 查询 |
平台配置、商户监管、商品治理、订单查询、物流配置、营销、系统管理 | 消费者购物体验和现场扫码作业 |
| 消费者小程序 | client |
/client/api/v1 |
登录、浏览、购物车、下单、支付、售后、评价、地址、消息 | 平台审核、后台配置、仓内作业 |
| 运营小程序 | ops |
默认 /client/api/v1，仓配作业可用 /admin/api/v1 |
商户发货、仓库作业、海外仓作业、配送员任务 | 平台全量管理和消费者导购 |
| 活动 H5 | h5 |
/api/v1 代理到客户端接口 |
运营活动会场、活动素材展示、外部分享落地页 | 后台配置、完整交易和现场作业 |
| 后端服务 | WinTradeCloudService |
wt-admin、wt-client |
权限、业务规则、状态流转、数据持久化、消息、文件 | 前端页面交互和本地缓存 |
代码入口映射
| 仓库 | 关键入口 | 联调时优先查看 |
|---|---|---|
admin |
src/api、src/views、src/router、src/store、src/utils/http/index.ts |
页面请求路径、菜单权限、Token 注入、代理前缀和表格分页参数 |
client |
api/index.js、api/request.js、api/config.js、pages、components、custom-tab-bar |
微信登录、商品搜索、店铺、购物车、订单、消息、文件 URL 和本地缓存 |
ops |
api/auth.js、api/logistics.js、api/system.js、utils/auth.js、utils/request.js、pages |
角色入口识别、商户发货、仓入库、中转、派送、配送员任务和服务前缀切换 |
h5 |
server.ts、scripts/build.ts、public/activity、public/assets |
活动静态页、默认活动跳转、资源路径和 /api/v1 代理 |
WinTradeCloudService |
wt-admin、wt-client、wt-business、wt-logistics、wt-user、wt-market、wt-message、wt-file、wt-system |
Controller 路径、权限标识、领域 Service、状态机、数据模型和统一异常 |
后端模块分层
| 层级 | 模块 | 联调关注点 |
|---|---|---|
| 接口入口 | wt-admin、wt-client |
路径、方法、参数、鉴权、权限、响应结构 |
| 核心业务 | wt-business |
商品、购物车、订单、售后、商户、结算 |
| 物流履约 | wt-logistics |
发货单、包裹、运单、车次、批次、仓作业、配送 |
| 账户资金 | wt-user |
用户、账户、地址、钱包、支付流水 |
| 营销消息 | wt-market、wt-message |
营销活动、优惠券、券池、活动价、预算、补贴、Banner、广告、公告、消息、待办 |
| 基础能力 | wt-system、wt-file |
菜单、角色、权限、字典、地区、文件 |
| 公共支撑 | wt-common、wt-framework |
统一响应、异常、安全、上下文、工具 |
接口入口层不应承接复杂业务规则。联调发现业务规则问题时，优先定位到领域模块，而不是只调整 Controller 或前端判断。
跨模块调用关系
后端当前虽然是单体多模块工程，但业务规则已经按领域拆分。复杂业务通常由 Controller 调用 Service，Service 再编排 Component、Repository 和其他领域 Service。
flowchart LR
Controller["wt-admin / wt-client Controller"] --> Service["领域 Service"]
Service --> Component["业务 Component"]
Component --> Repository["Repository / Mapper"]
Component --> OtherService["跨领域 Service"]
Service --> Event["消息 / 待办 / 定时任务"]
典型跨模块链路：
| 链路 | 后端编排 |
|---|---|
| 下单 | wt-client 订单 Controller -> wt-business 订单 Service -> 商品价格、库存、地址、优惠券组件 |
| 支付 | 订单 Service -> 支付流水、个人钱包、优惠券用券、商户结算快照、平台交易钱包 |
| 物流履约 | 物流 Controller -> wt-logistics 仓作业组件 -> 包裹、车次、批次、运单、仓库存 |
| 商户结算 | 结算批次 Controller -> wt-business 结算组件 -> 订单项、佣金策略、钱包流水 |
| 营销活动 | 营销 Controller -> wt-market 活动和券池 Service -> wt-business 订单营销组件 -> wt-user 卡券钱包 |
| 消息待办 | 业务模块产生事件或调用组件 -> wt-message 生成站内信、待办、派发记录 |
联调定位时建议先判断链路属于哪个“业务动作”，再看动作所在组件。比如订单金额异常不应只看订单 Controller，还需要看当前价格、活动价、优惠券和运费组件。
请求链路
admin
admin 请求封装在 admin/src/utils/http/index.ts：
| 项 | 当前约定 |
|---|---|
默认 baseURL |
/admin/api/v1 |
| 开发代理 | admin/vite.config.ts 中 /admin 代理到 VITE_ADMIN_API_URL，/client 代理到 VITE_CLIENT_API_URL |
| 鉴权头 | Authorization: Bearer <token> |
| 成功码 | code = 200 |
| 分页参数 | 前端会把 pageNo、pageNum、current 归一到 page，把 size、pageSize 归一到 limit |
| 登录失效 | HTTP 401 或业务 401 弹出重新登录提示 |
联调时如果管理端接口 404，需要先确认接口是 /admin/api/v1 还是 /client/api/v1，再确认 Vite 代理目标。
client
client 请求封装在 client/api/request.js，环境配置在 client/api/config.js：
| 小程序版本 | 请求域名 |
|---|---|
| 开发版 | https://dev.wintrade.asia/client/api/v1 |
| 体验版 | https://uat.wintrade.asia/client/api/v1 |
| 正式版 | https://api.example.com/client/api/v1 |
特点：
- 默认所有相对路径都会拼到
/client/api/v1。 - Token 从本地缓存
token读取，并写入Authorization。 - 业务响应
code不等于200且不在allowedBusinessCodes时，会抛出业务错误。 - 微信登录接口允许透传未绑定手机号等特定业务码。
ops
ops 请求封装在 ops/utils/request.js，环境配置在 ops/api/config.js：
| 项 | 当前约定 |
|---|---|
| 默认入口 | /client/api/v1 |
| 管理端入口 | getServiceBaseUrl('admin') 可将基础路径切换为 /admin/api/v1 |
| 鉴权头 | Authorization: Bearer <token> |
| 成功码 | code = 200 或 code = 0 |
| 登录失效 | 401 时清理会话并跳转登录页 |
ops 的商户和员工查询能力偏 client，仓库和配送员作业能力当前多在 admin 入口。联调时必须逐个接口确认服务入口，不能只看页面属于运营小程序。
h5
h5 请求和静态路由由 h5/server.ts 处理：
| 项 | 当前约定 |
|---|---|
| 默认端口 | 3016 |
| 默认活动入口 | /activity/618/ |
| 根路径处理 | / 会 302 跳转到默认活动入口 |
| 活动短路径 | /activity/<活动标识> 会补 / 后再访问 |
| 接口代理 | /api/v1/** 透传到 CLIENT_API_ORIGIN，默认 http://localhost:8090 |
| 静态缓存 | /assets/ 下资源使用长缓存，活动 HTML、CSS 和 JS 使用 no-cache |
h5 不直接使用 /admin/api/v1 或 /client/api/v1 前缀。部署时如果活动页需要访问线上客户端接口，应通过 CLIENT_API_ORIGIN 指向对应后端或网关。
接口前缀规范
| 前缀 | 使用场景 | 示例 |
|---|---|---|
/admin/api/v1 |
平台管理、平台审核、系统配置、仓配作业管理接口 | /admin/api/v1/product/spu/page、/admin/api/v1/logistics/warehouse/inbound/preview |
/client/api/v1 |
消费者、商户、员工等客户端接口 | /client/api/v1/login/wechat、/client/api/v1/personal/order/page |
/api/v1 |
后端 Controller 内部声明的统一版本路径，或 h5 活动页代理路径 |
Controller 中声明 /api/v1/product/spu，h5 请求 /api/v1/marketing/platform/activity/page |
前端实际请求地址一般由“端口前缀 + Controller 路径去掉 /api/v1 后的业务路径”组合而成。例如：
| Controller 路径 | admin 请求 |
client 请求 |
|---|---|---|
/api/v1/product/spu/page |
/admin/api/v1/product/spu/page |
/client/api/v1/product/spu/page |
/api/v1/personal/order/page |
通常不用 | /client/api/v1/personal/order/page |
/api/v1/logistics/warehouse/inbound/preview |
/admin/api/v1/logistics/warehouse/inbound/preview |
通常不用 |
鉴权和权限模型
sequenceDiagram
participant FE as 前端
participant API as 后端入口
participant Auth as 鉴权与权限
participant Biz as 业务模块
FE->>API: 请求 + Authorization
API->>Auth: 校验 Token
Auth-->>API: 当前用户与账户关系
API->>Auth: 校验权限标识
Auth-->>API: 允许或拒绝
API->>Biz: 调用业务逻辑
Biz-->>API: 返回统一响应
API-->>FE: code / data / msg
联调规则：
- 未登录接口只能用于验证码、登录、微信登录、注册等明确公开能力。
- 其他接口必须带
Authorization: Bearer <token>。 - 页面按钮可见不代表接口一定可调用，后端权限才是最终准入。
- 管理端登录后必须验证
/api/v1/info和/api/v1/routers返回。 - 小程序微信登录未绑定手机号时，不写入完整登录态。
统一响应和错误处理
| 情况 | 后端表现 | 前端处理 |
|---|---|---|
| 成功 | code = 200，返回 data |
正常渲染 |
| 登录过期 | HTTP 401 或业务 401 |
清理登录态并跳转登录 |
| 业务失败 | code != 200，返回 msg 或 message |
展示业务错误，保留页面上下文 |
| HTTP 失败 | 非 2xx 状态码 |
展示网络或服务异常 |
| 特殊业务码 | 例如微信登录需绑定手机号 | 前端通过白名单透传并进入指定流程 |
联调时后端应优先返回明确业务错误信息。现场作业类页面尤其需要展示阻断原因，例如包裹状态不允许入库、当前仓不匹配、配送员身份不正确。
状态和幂等原则
系统内大量动作会改变状态或资金数据，前端不能只靠按钮置灰保证安全，最终以后端状态机和幂等校验为准。
| 动作 | 后端保障重点 | 前端联调重点 |
|---|---|---|
| 创建订单 | 幂等键、购物车归属、库存和价格试算 | 重复点击不应生成重复订单 |
| 支付订单 | 支付状态校验、钱包流水、优惠券锁定校验 | 支付失败后能重新试算或释放优惠 |
| 取消订单 | 订单状态、优惠券释放、库存和支付状态 | 取消后刷新订单和卡券状态 |
| 发货 | 发货明细状态、包裹和运单创建 | 防止同一明细重复发货 |
| 仓入库 | 车次、批次、包裹状态、当前仓和库位 | 扫码失败展示后端阻断原因 |
| 派送签收 | 配送员身份、任务归属、包裹状态 | 只允许本人任务操作 |
| 结算执行 | 批次防重复、订单完成状态、佣金策略快照 | 重复执行不应重复入账 |
| 预算充值和用券 | 钱包流水、预算流水、券状态、预算余额 | 金额展示以后端返回为准 |
后端动作接口出现失败时，前端应重新查询当前资源详情，而不是基于本地状态继续下一步。
核心业务联调链路
登录和权限
flowchart TD
A["获取验证码"] --> B["账号密码登录"]
B --> C["保存 Token"]
C --> D["获取用户信息"]
D --> E["获取菜单路由"]
E --> F["进入业务页面"]
验收点：
token能写入请求头。- 当前用户、角色、权限、账户关系返回完整。
- 管理端菜单和按钮权限与接口权限一致。
微信登录和个人账户
flowchart TD
A["wx.login 获取 code"] --> B["微信登录接口"]
B --> C{"是否已绑定手机号"}
C -->|是| D["保存登录态"]
C -->|否| E["调用手机号绑定"]
E --> D
D --> F["获取个人资料和账户关系"]
验收点：
- 未绑定手机号时不会写入完整登录态。
- 绑定成功后能拿到
userId、personalAccountId。 - 头像上传后能刷新资料和本地缓存。
商品上架到购买
flowchart TD
A["维护类目 / 品牌 / 属性"] --> B["创建 SPU"]
B --> C["创建 SKU"]
C --> D["店铺上架"]
D --> E["平台审核"]
E --> F["消费者浏览商品"]
F --> G["加入购物车或直接购买"]
G --> H["创建订单"]
验收点：
- 消费者只看到已上架且可售商品。
- SKU 当前价和订单确认页价格一致。
- 图片通过文件 URL 正常展示。
营销活动到订单用券
flowchart TD
A["创建平台或商户活动"] --> B["配置活动范围"]
B --> C["配置券池或活动价"]
C --> D["充值预算池"]
D --> E["启动活动"]
E --> F["消费者领券或命中活动价"]
F --> G["订单试算"]
G --> H["创建订单并锁券"]
H --> I["支付成功并用券"]
I --> J["生成分摊、预算流水和补贴确认"]
验收点：
- 活动未启动、已暂停或已结束时，不应继续参与领券和价格计算。
- 用户领券后能在卡券钱包看到卡券和流水。
- 带券下单后卡券进入锁定，支付成功后变为已使用。
- 平台承担和商户承担金额能在订单项、分摊记录和预算流水中追踪。
- 补贴确认和结算推进不能丢失操作人和业务单号。
订单到商户发货
flowchart TD
A["订单预创建"] --> B["正式创建订单"]
B --> C["支付订单"]
C --> D["生成或查询发货单"]
D --> E["商户处理发货明细"]
E --> F["包裹进入物流链路"]
验收点：
- 预创建只校验和展示，不产生不可回滚副作用。
- 正式创建和支付动作幂等。
- 发货明细与订单商品能对应。
海外仓作业
flowchart TD
A["查询待入库车次"] --> B["确认车次到仓"]
B --> C["入库预查询"]
C --> D{"可入库"}
D -->|是| E["正式入库"]
D -->|否| F["展示阻断原因"]
E --> G["仓内复核"]
G --> H{"后续流向"}
H -->|中转| I["创建中转上下文"]
H -->|派送| J["创建派送上下文"]
验收点：
- 海外仓接口使用通用仓路径，不使用不存在的海外仓独立路径。
- 仓库必须满足
abroad = true。 - 派送加包受包裹状态和复核状态限制，前端展示后端原因。
配送员任务
flowchart TD
A["配送员登录"] --> B["查询本人任务"]
B --> C["查看任务详情"]
C --> D{"配送结果"}
D -->|签收| E["签收完成"]
D -->|失败| F["上报失败"]
F --> G["失败件退仓"]
验收点：
- 配送员只能看到本人任务。
- 签收、失败、退仓都需要校验任务归属。
- 操作完成后任务列表和详情立即刷新。
联调环境约定
| 环境 | admin |
小程序 |
|---|---|---|
| 本地开发 | Vite 代理 /admin 和 /client 到后端地址 |
微信开发者工具，使用开发版域名 |
| 测试联调 | 指向 dev.wintrade.asia 或测试后端 |
develop 环境走 https://dev.wintrade.asia/client/api/v1 |
| 预发验收 | 指向 uat.wintrade.asia |
trial 环境走 https://uat.wintrade.asia/client/api/v1 |
| 正式发布 | 指向正式后端 | release 环境正式域名需替换当前占位值 |
h5 本地默认地址为 http://localhost:3016/activity/618/。活动页联调时需要同时确认静态资源路径和 CLIENT_API_ORIGIN，否则页面能打开但接口会请求到错误环境。
小程序联调需要在微信公众平台配置合法域名。涉及头像、凭证或附件上传时，还需要配置 uploadFile 合法域名。
前后端联调流程
- 后端确认接口路径、方法、请求参数、响应字段、权限标识和错误码。
admin在src/api增加或调整接口封装，client和ops在各自api/增加或调整接口封装。- 前端页面只依赖封装后的接口，不直接拼接复杂请求。
- 双方用同一组测试账号验证登录态和账户关系。
- 先联调查询接口，再联调新增、修改、删除和业务动作接口。
- 对业务动作接口验证重复点击、状态不满足、权限不足和参数缺失。
- 对核心流程执行端到端联调，例如商品上架到下单、订单到发货、入库到派送。
- 将确认后的接口归档到
doc/API对应文档。
数据和账号准备
| 数据 | 用途 |
|---|---|
| 平台管理员账号 | 管理端登录、菜单、权限、审核、配置 |
| 商户账号 | 店铺、库存、发货、结算 |
| 消费者账号 | 微信登录、购物车、下单、地址、售后 |
| 仓库管理员账号 | 仓入库、中转、派送上下文 |
| 配送员账号 | 本人派送任务、签收、失败、退仓 |
| 商品基础数据 | 类目、品牌、属性、SPU、SKU、价格策略 |
| 物流基础数据 | 物流公司、仓库、库位、路线、包裹类型、运费规则 |
| 资金基础数据 | 钱包、佣金策略、结算测试订单 |
排查路径
| 现象 | 优先排查 |
|---|---|
| 404 | 前缀是否应该是 /admin/api/v1 或 /client/api/v1，后端 Controller 路径是否一致 |
| 401 | Token 是否存在、是否过期、请求头是否带 Bearer |
| 403 | 用户角色、菜单权限、接口权限标识 |
| 查询为空 | 当前账号的数据权限、账户关系、分页参数是否被转换 |
| 图片不显示 | fileId 是否存在，文件 URL 接口是否返回可访问地址 |
| 小程序请求失败 | 合法域名、环境版本、基础域名、网络超时 |
| 微信登录异常 | wx.login 的 code、微信配置、手机号绑定流程 |
| 订单金额不一致 | SKU 当前价、价格策略、运费、优惠、币种 |
| 物流状态无法推进 | 包裹状态、当前仓、库位、复核状态、任务占用 |
| 配送员看不到任务 | 员工账户类型、任务归属、接口入口和权限 |
文档维护规则
- 业务目标和阶段规划维护在
业务功能规划.md。 - 后端模块、数据模型、权限和排查维护在
后端技术文档.md。 - 前端工程、页面和联调注意事项维护在
前端技术文档.md。 - 具体接口按业务域维护在
doc/API。 - 本文只维护跨端架构、联调约定和端到端流程，不替代具体 API 文档。