后端技术文档

更新日期：2026-05-31。

本文以 WinTradeCloudService 当前代码结构为准，描述后端模块、接口入口、通用机制和数据模型。历史数据库资料的有效内容已归并到本文，不再单独维护 doc/database。

技术栈

后端当前是单仓库多 Maven 模块结构。wt-admin 和 wt-client 是 Web 入口模块，业务逻辑由领域模块承接；公共配置、安全、异常和工具能力沉淀在 wt-framework 和 wt-common。

模块结构

模块依赖边界

接口层应尽量薄。新增业务规则优先落在领域模块的 Service 或 Component 中，避免 Controller 直接复制业务逻辑。

领域组件职责

后端业务中常见的 Component 用于承接跨 Service 编排、复杂状态校验和事务边界内的业务动作。

新增业务规则建议优先落在对应领域组件中。例如优惠券下单不应分散在 Controller，而应由订单 Service 调用营销订单组件统一处理。

接口入口

后端主要有两个 Controller 入口：

接口统一使用 /api/v1 前缀。前端根据网关或请求封装将端口前缀映射为管理端或客户端访问路径。

入口选择原则

通用接口约定

• 查询列表通常使用 GET /list，分页通常使用 GET /page。
• 详情通常使用 GET /{id} 或业务语义详情路径。
• 新增使用 POST，修改使用 PUT，删除使用 DELETE。
• 业务动作使用语义化子路径，例如 /publish、/approve、/payment、/shipping、/complete。
• 接口返回统一响应结构，分页结果通常返回 content、records 或 rows，前端封装会兼容这些字段。
• 权限标识通常写在 @Operation 描述中，例如 admin:product:spu:query、client:merchant:message:edit。

请求和响应规范

分页字段在历史接口中存在多种返回形态，前端已做兼容。新增接口应尽量统一分页模型，减少 content、records、rows 混用。

事务、幂等和异常

交易、资金、库存、物流和营销动作都需要严格处理事务和幂等。

异常处理原则：

• 业务校验失败抛出 BusinessException，由统一异常处理转换响应。
• Controller 不应通过大段 try/catch 吞掉业务错误。
• 状态机动作失败时，错误信息应能让前端展示可操作原因。
• 涉及金额和钱包的操作需要保留业务单号，便于通过流水反查。
• 事务提交后才触发不可回滚的异步副作用，例如消息派发或外部通知。

幂等建议：

鉴权与权限

• 登录接口返回 token，后续请求通过 Authorization: Bearer <token> 传递。
• admin 登录后通过 /api/v1/info 获取用户信息，通过 /api/v1/routers 获取菜单路由。
• 微信小程序登录使用 /api/v1/login/wechat，未绑定手机号时继续调用 /api/v1/login/wechat/phone/bind。
• 平台权限由用户、角色、菜单、权限标识组成；后端负责接口权限校验，前端负责菜单和按钮可见性控制。

权限标识规则

权限标识建议按 端别:领域:资源:动作 组织：

后端新增接口时，需要同步确认菜单、按钮、角色和接口权限是否完整，否则会出现页面可见但接口被拒绝，或接口可访问但页面无入口的问题。

文件能力

文件接口分为文件和文件夹两组：

• 文件：访问 URL、普通上传、预签名上传、按路径上传、上传完成、移动、复制、删除。
• 文件夹：子文件和子文件夹列表、分页、详情、新建、修改、移动、复制、删除。
• 小程序头像当前走后端直传接口 /api/v1/system/user/profile/avatar/upload，不再依赖前端直传 OSS。

文件业务建议：

1. 普通业务图片优先通过文件模块上传并保存 fileId。
2. 页面展示时通过文件 URL 接口换取可访问地址。
3. 大文件或需要客户端直传时使用预签名上传，并在上传完成后调用完成接口。
4. 富文本中的图片应保存文件标识，避免只保存临时外链。

商品、价格和营销

商品价格现在由货架价格、原价格策略、活动价、优惠券和运费共同影响。当前价格计算是订单金额的基础，前端不应自行重算。

订单项会保存价格和营销快照，包括 promotionId、promotionData、couponDiscountAmount、platformCouponAmount、merchantCouponAmount 和 merchantSettlementBaseAmount，用于后续结算和退款追溯。

物流状态与仓作业

物流域以 wt-logistics 为核心，包含发货单、包裹、运单、车次、批次、仓库存和配送任务。

关键流程：

1. 商户或平台生成发货单和发货明细。
2. 包裹进入车次和批次，形成运单和轨迹。
3. 仓库管理员确认车次到仓。
4. 仓库管理员按批次号、包裹号或运单号执行入库预查询。
5. 满足条件后正式入库，包裹进入仓内库存。
6. 仓内复核后，包裹可进入中转或派送准备流程。
7. 配送员领取或被分配派送任务，执行签收、失败上报或退仓。

海外仓当前使用通用仓接口 /api/v1/logistics/warehouse/...，通过场景组件校验仓库类型。当前派送加包允许 ARRIVED 或 STORED 包裹，但要求 reviewed = true，并校验当前仓、库位和目的地区；INBOUND 包裹需要先完成复核。

物流对象关系

仓作业状态关注点

消息与待办

消息中心支持多角色消息：

• 平台消息：模板、内容、路由规则、派发计划、派发日志、统计、公告。
• 个人消息：个人站内信、未读数、已读、置顶、重要标记、删除、订阅和偏好。个人订阅当前包含 SKU 到货、SKU 降价、店铺上新、订阅状态查询和订阅分页。
• 商户消息：商户站内信、未读数、已读、置顶、重要标记、删除和偏好。
• 员工消息：员工消息、员工待办和偏好。

待办适合承接审核、订单、发货、售后、仓作业等需要人工处理的业务事项。

消息域建议和业务事件解耦：业务模块只发出明确事件，消息模块根据模板、订阅、偏好和路由规则决定接收人、渠道和内容。这样能避免订单、物流、结算模块直接硬编码消息内容。

数据模型

当前数据模型按业务模块划分，不再按旧文档中的 mall-* 独立服务维护。核心数据域如下：

数据一致性重点

定时任务

wt-quartz 承接周期性任务和任务日志。业务任务本身通常调用领域组件，不应在任务类里堆复杂规则。

新增定时任务时需要同步：任务 Bean 名称、方法名、推荐 cron、影响数据、是否幂等、失败重试策略。

开发约定

• 新增接口优先沿用现有 Controller 风格和 /api/v1 版本路径。
• 非必要不要在接口层使用 try/catch，让统一异常处理承接业务异常。
• 查询接口保持幂等，业务动作接口使用明确动作路径。
• 权限标识需要与菜单和前端按钮控制保持一致。
• 涉及中文的文案、注释和文档必须确保编码正常，中文与英文、数字之间保留空格。

排查入口