WinTrade 文档说明
WinTrade 文档说明
本文是 doc 目录的文档索引，用于说明本目录内各文档的定位、阅读顺序和相互关系，帮助读者快速判断“该看哪份文档”。
文档地图
| 文档 | 定位 | 适合回答的问题 |
|---|---|---|
| 系统整体架构设计 | 系统总览 | 四端职责怎么划分、请求链路怎么走、接口前缀怎么区分、联调问题从哪里排查 |
| 业务功能规划 | 业务总览 | 平台有哪些角色、核心业务主线是什么、当前阶段重点和风险是什么 |
| 前端技术文档 | 前端说明 | admin、client、ops、h5 各自的工程结构、页面模块、接口封装和关键流程是什么 |
| 后端技术文档 | 后端说明 | WinTradeCloudService 的模块结构、接口入口、权限、通用机制和数据域是什么 |
| 权限控制体系设计 | 权限专题 | 登录态、角色、菜单、权限标识、按钮控制、数据归属和权限变更如何生效 |
| 账户角色功能说明 | 后台角色说明 | 每种账户角色负责哪些功能、可见哪些菜单、不应分配哪些业务入口 |
| 物流业务流程设计 | 物流流程 | 商户发货、仓入库、中转、派送、配送员签收等流程如何衔接 |
| 营销活动中心功能说明 | 营销流程 | 平台活动、商户活动、优惠券、活动价、预算、补贴和订单用券如何闭环 |
| 营销活动业务逻辑梳理 | 营销逻辑 | 平台邀请、商户报名、活动范围、活动价、优惠券、预算和补贴的后端规则 |
| 营销活动业务逻辑 Mermaid 图 | 营销图示 | 用流程图和时序图快速查看营销活动配置、领券、用券和结算链路 |
| 活动目录 | 活动方案集合 | 具体运营活动方案入口，例如 618 夏季数码焕新节 |
| API / 认证与账户 | API 分册 | 登录、验证码、用户资料、账户关系、地址、钱包、角色、菜单和权限接口 |
| API / 商品与店铺 | API 分册 | 类目、品牌、属性、SPU、SKU、价格、店铺、上架、评价、收藏和足迹接口 |
| API / 交易订单与售后 | API 分册 | 购物车、下单、支付、订单查询、确认收货、退货和售后接口 |
| API / 物流履约 | API 分册 | 发货单、包裹、运单、车次、批次、仓作业和配送员任务接口 |
| API / 商户与结算 | API 分册 | 商户资料、仓库、库存、钱包、保证金、提现、佣金和结算接口 |
| API / 系统基础数据与文件 | API 分册 | 字典、参数、语言、地区、组织、币种、文件、监控、日志和工具接口 |
| API / 营销与消息 | API 分册 | 营销活动中心、优惠券、卡券钱包、Banner、广告、公告、消息、订阅、偏好、待办、派发和统计接口 |
阅读顺序
建议按目标选择阅读路径：
| 目标 | 推荐阅读 |
|---|---|
| 快速了解系统全貌 | 系统整体架构设计 到 业务功能规划 |
| 理解前端工程 | 前端技术文档 |
| 理解后端工程 | 后端技术文档 |
| 理解权限体系 | 权限控制体系设计 |
| 理解后台角色职责 | 账户角色功能说明 |
| 联调交易主链路 | 业务功能规划 到 交易订单与售后 API 到 物流履约 API |
| 联调物流和仓配 | 物流业务流程设计 到 物流履约 API |
| 联调营销和优惠券 | 营销活动中心功能说明 到 营销活动业务逻辑梳理 到 营销与消息 API 到 交易订单与售后 API |
| 配置 618 活动 | 活动目录 到 618 活动总览 到 营销活动操作指南 |
| 联调活动 H5 | 系统整体架构设计 到 前端技术文档 到 活动目录 |
| 排查金额、结算和补贴 | 业务功能规划 到 商户与结算 API 到 营销活动中心功能说明 |
| 查某类接口 | 直接阅读 API/ 下对应分册 |
文档关系
| 类型 | 作用 | 边界 |
|---|---|---|
| 架构说明 | 描述系统边界、端口职责、请求链路、接口前缀、鉴权和联调路径 | 不展开单个业务域的详细接口表 |
| 业务规划 | 描述平台定位、角色分工、业务主线、阶段目标和待确认事项 | 不替代 API 分册和代码实现说明 |
| 前端说明 | 描述 admin、client、ops、h5 的工程结构、页面模块、请求封装和关键流程 |
不记录每个页面的所有字段细节 |
| 后端说明 | 描述 WinTradeCloudService 的模块分层、接口入口、通用机制和核心数据域 |
不逐条列出全部接口 |
| 权限专题 | 描述登录态、RBAC、菜单路由、按钮权限、账号归属和变更生效机制 | 不替代每个业务接口的权限明细 |
| 流程说明 | 描述物流等跨模块、跨端的状态流转和作业恢复路径 | 不替代接口分类文档 |
| 营销说明 | 描述营销活动中心的配置、商户报名、领券、用券、预算、补贴和结算衔接 | 不替代具体 Controller 接口表 |
| API 分册 | 按业务域归纳接口用途、路径、权限、调用端和后端 Controller | 不展开页面交互设计和系统整体架构 |
后端逻辑查阅路径
不同问题建议按“业务现象 -> API 分册 -> 后端模块 -> 领域组件”的顺序定位，避免只看前端页面。
| 问题类型 | 先看文档 | 再看后端模块 |
|---|---|---|
| 登录、权限、菜单、角色 | 权限控制体系设计 和 认证与账户 API | wt-admin、wt-client、wt-system、wt-framework |
| 商品价格、店铺上架、搜索 | 商品与店铺 API | wt-business、wt-market |
| 购物车、下单、支付、售后 | 交易订单与售后 API | wt-business、wt-user |
| 商户钱包、佣金、结算 | 商户与结算 API | wt-business、wt-user |
| 仓入库、中转、派送、签收 | 物流业务流程设计 和 物流履约 API | wt-logistics、wt-business |
| 活动、优惠券、预算、补贴 | 营销活动中心功能说明、营销活动业务逻辑梳理 和 营销与消息 API | wt-market、wt-business、wt-user、wt-quartz |
| 文件、字典、地区、定时任务 | 系统基础数据与文件 API | wt-file、wt-system、wt-quartz |
文档维护规则
md/是源文档目录，docs/和site/由构建脚本生成，不直接手改。- 后端新增 Controller 或业务组件时，至少同步对应 API 分册和业务说明。
- 涉及状态机、金额、库存、钱包、预算和结算的改动，需要同步补充“调用顺序”和“验收口径”。
- 新增文档需要同步
scripts/sync-docs.js的路由映射和docmd.config.js的导航。 - 文档中的中文、英文和数字之间保留空格，避免复制接口说明时产生乱码。