升鲜宝后端 API 与手机端 API 开发说明（一）---升鲜宝生鲜配送供应链管理系统重构版

升鲜宝后端 API 与手机端 API
开发说明

项目源代码改造版 · Spring Boot + MyBatis-Plus

适用范围：管理后台 API、手机端 API、小程序 API、POS/API、公共 API、开放 API

版本：V1.0
日期：2025-04-21

文档目录

文档目标与总体结论
API 分层原则：入口分开，业务共用
管理后台 API 与手机端 API 的利弊分析
升鲜宝推荐后端分层架构
API 路径、命名与版本规范
Spring Boot 项目结构与包命名规范
DTO / VO / Query / Convert 设计规范
权限、租户、数据权限与字段权限设计
管理后台 API 开发规范
手机端 API 开发规范
公共 API、开放 API、POS/API 的边界
核心业务域 API 清单建议
我的中心模块 API 改造示例
代码骨架与标准模板
旧项目 API 改造实施路线图
测试、审计、日志、缓存与上线检查
附录：接口评审清单与迁移清单

1. 文档目标与总体结论

本说明用于指导升鲜宝供应链管理系统在 Spring Boot 项目中，统一改造"后端管理端 API"和"手机端 API"的代码结构、接口命名、权限控制、DTO/VO 设计、Service 复用、缓存与审计策略。

本文重点不是简单新增接口，而是建立一套可长期演进的 API 分层规范，方便后续逐步改造商品、订单、采购、仓储、门店、POS、CRM、财务、打印、设置等模块。

1.1 最终结论

升鲜宝推荐原则：
API 入口分开
业务 Service 共用
Domain 规则共用
Mapper / Entity 共用
DTO / VO 按端区分
权限、数据范围、字段输出按端区分

|-----------------|----------|--------------------------------------------|
| 层级 | 是否共用 | 说明 |
| Controller | 不建议完全共用 | 管理后台、手机端、POS、小程序、开放接口的入口语义不同，应独立定义路径和返回结构。 |
| Facade | 按端聚合 | 手机端常用 BFF 聚合接口；后台端偏 CRUD 与配置管理。 |
| Service | 必须共用 | 业务规则和写入逻辑不能重复实现，应统一在 Service / Domain 层。 |
| Domain Service | 必须共用 | 审核、库存、成本、价格、权限等核心规则必须统一。 |
| Mapper / Entity | 必须共用 | 统一数据访问和数据模型，避免产生两套表或两套实体。 |
| DTO / VO | 建议分开 | 不同端请求字段、展示字段、权限字段不同，避免字段泄露和返回臃肿。 |
| 权限编码 | 建议分开 | 后台管理权限和手机端操作权限颗粒度不同。 |

2. API 分层原则：入口分开，业务共用

升鲜宝是企业级业务系统，未来会存在 PC 后台、移动 App、小程序、POS 收银端、仓库 PDA、司机端、供应商协同端、客户协同端等多个入口。不同入口面对的角色不同、交互方式不同、接口版本节奏不同，因此不建议把所有接口混在一个 Controller 中。

2.1 正确的共用方式

controller/admin -> Admin API：后台配置、审核、维护、统计
controller/app -> App API：移动端页面展示、个人操作、移动业务动作
controller/pos -> POS API：收银、离线同步、设备相关
controller/open -> Open API：第三方对接、签名、限流
controller/common -> Common API：字典、文件、地区、验证码等公共能力

以上入口可以不同，但最终都调用同一批 Service / Domain / Mapper。

2.2 错误的共用方式

把 PC 后台列表接口直接给手机端使用，导致手机端拿到大量无用字段。
手机端新增接口直接操作 Mapper，绕开后台 Service 规则。
后台端和手机端各写一套审核、反审核、库存扣减、成本计算逻辑。
用同一个 VO 同时返回给后台和手机端，造成权限字段、内部状态、审计字段泄露。
同一个接口内部大量 if 判断 terminalType，导致 Controller 越来越难维护。

3. 管理后台 API 与手机端 API 的利弊分析

3.1 分开接口的优点

|-----------|---------------------------------|-------------------------|
| 优点 | 说明 | 对升鲜宝的价值 |
| 安全性更高 | 后台管理字段、权限字段、审计字段不直接暴露给手机端。 | 降低越权、字段泄露、误操作风险。 |
| 职责更清晰 | 后台 API 偏管理配置，手机 API 偏页面展示和移动操作。 | 代码结构清楚，后续模块多人协作更容易。 |
| 返回更轻量 | 手机端只返回页面需要的字段。 | 减少移动网络传输，提高页面响应速度。 |
| 版本更好管理 | App/小程序发版慢，需要 v1/v2 兼容；后台可快速升级。 | 避免后台改动影响已上线移动端。 |
| 权限更容易落地 | 后台权限、手机端权限、POS 权限颗粒度不同。 | RBAC + 数据权限 + 字段权限更好配置。 |
| 支持 BFF 聚合 | 手机页面可用一个接口聚合用户、菜单、授权、消息等。 | 减少移动端多次请求。 |

3.2 分开接口的缺点与解决办法

|-----------------|----------------------------|----------------------------------------------|
| 缺点 | 风险 | 解决办法 |
| Controller 数量变多 | 初期看起来目录更多。 | 按 app/admin/pos/open/common 分包，命名统一。 |
| DTO / VO 变多 | 维护对象增加。 | 用 Convert 层统一转换，DTO/VO 只做入参与出参。 |
| 可能重复业务 | 如果 Controller 写业务，会产生两套逻辑。 | 规定业务只能写在 Service / Domain，Controller 只收参和返回。 |
| 接口文档变多 | 前端联调需要区分端。 | 统一 Swagger 分组、Apifox 分组、接口命名规范。 |

3.3 什么时候可以共用接口

|----------|------------------|--------------------------|
| 接口类型 | 是否适合共用 | 示例 |
| 公共字典 | 适合 | /api/common/dict/list |
| 地区树 | 适合 | /api/common/area/tree |
| 文件上传 | 适合，但要控制业务类型 | /api/common/file/upload |
| 验证码 | 适合 | /api/common/captcha |
| 用户资料 | 可共用基础能力，但输出要按端过滤 | /api/common/user/current |
| 菜单管理 | 不适合 | 后台维护菜单，手机端只读取可见菜单。 |
| 订单审核 | 不适合直接共用 | 后台审核和移动端操作要区分权限、日志、终端来源。 |
| 系统设置 | 不适合直接共用 | 后台配置全局参数，手机端保存个人偏好。 |

4. 升鲜宝推荐后端分层架构

推荐采用"多入口 Controller + Facade 聚合 + Service 业务复用 + Domain 规则中心 + Mapper 数据访问"的结构。

请求入口层
├── AdminController：后台管理接口
├── AppController：手机端/小程序接口
├── PosController：POS / 设备接口
├── OpenController：第三方开放接口
└── CommonController：公共接口

聚合编排层
├── Facade：页面聚合、跨 Service 编排、权限过滤、VO 组装

业务服务层
├── Service：业务能力、事务边界、幂等校验、状态机
├── DomainService：库存、成本、价格、审核、权限等核心规则

数据访问层
├── Mapper：MyBatis-Plus 数据访问
├── Entity：数据库实体
└── QueryFacade：复杂查询、排序白名单、分页适配

基础能力层
├── Security：JWT、RBAC、数据权限
├── Cache：Redis / Caffeine
├── Log：操作日志 / 审计日志
├── ErrorCode：错误码
└── Util：公共工具

4.1 Controller 职责边界

|--------|--------------------------------|-----------------------------|
| 职责 | 允许做 | 禁止做 |
| 参数接收 | 接收 DTO / Query / PathVariable。 | 不要直接接收 Entity 作为业务入参。 |
| 参数校验 | @Validated、简单必填校验。 | 不要写复杂业务规则。 |
| 权限入口 | @PreAuthorize、接口权限声明。 | 不要在 Controller 写复杂数据权限 SQL。 |
| 调用服务 | 调用 Facade 或 Service。 | 不要直接调用 Mapper。 |
| 统一返回 | 包装 Result / PageResult。 | Service 接口不要返回 Result。 |

4.2 Facade 职责边界

负责页面级聚合接口，例如手机端首页、我的中心、订单详情、商品详情。
负责调用多个 Service 后组装 VO。
负责按端过滤字段、菜单、按钮、操作入口。
负责组合查询，不直接承载核心业务写入规则。
复杂写入仍由 Service 作为事务边界。

4.3 Service 职责边界

Service 是后台、手机端、POS、开放接口共用的业务能力层。
审核、反审核、库存过账、成本计算、付款、核销等必须写在 Service / Domain 中。
Service 方法不要返回 Result，直接返回业务对象或 void，异常用 SxbException 抛出。
Service 方法要具备幂等性、状态校验、租户隔离、操作日志能力。

5. API 路径、命名与版本规范

5.1 推荐路径前缀

|-------------|-------------------|-----------------------------|
| 前缀 | 用途 | 示例 |
| /api/admin | PC 管理后台 API | /api/admin/pms/goods/page |
| /api/app | 手机 App / 小程序 API | /api/app/mine/home |
| /api/pos | POS 收银端 API | /api/pos/sale/order/create |
| /api/pda | 仓库 PDA / 手持终端 API | /api/pda/wms/pick/task/list |
| /api/open | 第三方开放接口 | /api/open/order/push |
| /api/common | 公共接口 | /api/common/dict/list |

5.2 业务域路径建议

|---------|---------|--------------------------------|--------------------------------|
| 业务域 | 域编码 | 后台路径示例 | 手机路径示例 |
| 系统/RBAC | sys | /api/admin/sys/user/page | /api/app/user/current |
| 我的中心 | mine | /api/admin/mine/menu/page | /api/app/mine/home |
| 商品中心 | pms | /api/admin/pms/goods/page | /api/app/pms/goods/search |
| 采购 | pur | /api/admin/pur/order/page | /api/app/pur/order/detail |
| 供应商 | sup | /api/admin/sup/supplier/page | /api/app/sup/order/confirm |
| 订单 | oms | /api/admin/oms/order/page | /api/app/oms/order/list |
| 仓库 | wms | /api/admin/wms/stockin/page | /api/app/wms/task/list |
| 门店仓储 | hwms | /api/admin/hwms/inventory/page | /api/app/hwms/stocktake/create |
| POS | pos | /api/admin/pos/shift/page | /api/pos/sale/submit |
| CRM | crm | /api/admin/crm/customer/page | /api/app/crm/lead/create |
| 财务 | fin | /api/admin/fin/receivable/page | /api/app/fin/bill/list |

5.3 动作命名规范

|--------|------------------|---------------------|
| 场景 | 推荐路径 | 说明 |
| 分页查询 | GET /page | 后台列表查询使用 page。 |
| 详情 | GET /detail/{id} | 按 ID 获取详情。 |
| 新增 | POST /save | 创建新记录。 |
| 修改 | POST /update | 更新记录。 |
| 删除 | POST /delete | 逻辑删除，支持批量时使用 ids。 |
| 启用 | POST /enable | 状态动作。 |
| 停用 | POST /disable | 状态动作。 |
| 审核 | POST /approve | 单据审核。 |
| 反审核 | POST /unapprove | 单据反审核。 |
| 导出 | POST /export | 复杂条件建议 POST。 |
| 导入 | POST /import | 上传文件并按 schemeId 执行。 |

5.4 手机端版本管理

手机端、小程序、POS 端发版周期与后台不同，建议从一开始支持版本前缀。

推荐：
/api/app/v1/mine/home
/api/app/v2/mine/home

也可在初期先使用：
/api/app/mine/home

但 Controller 内部要保留版本兼容意识，避免随意删除字段或改变字段语义。

6. Spring Boot 项目结构与包命名规范

以下结构适合升鲜宝单体模块化项目，也适合未来逐步拆分微服务。

src/main/java/com/sxb/scm
├── common
│ ├── result
│ ├── exception
│ ├── security
│ ├── tenant
│ ├── datasource
│ ├── permission
│ ├── log
│ ├── cache
│ └── utils
│
└── modules
├── sys
├── mine
├── pms
├── pur
├── sup
├── oms
├── wms
├── hwms
├── pos
├── crm
└── fin

6.1 单个业务模块标准结构

modules/{domain}
├── controller
│ ├── admin
│ ├── app
│ ├── pos
│ └── open
├── facade
├── service
│ └── impl
├── domain
├── mapper
├── entity
├── dto
├── vo
├── query
├── convert
├── enums
├── constant
├── validator
└── support

|------------------|----------------------------------|
| 目录 | 职责 |
| controller/admin | PC 管理后台 API。 |
| controller/app | 手机 App / 小程序 API。 |
| controller/pos | POS、PDA、设备端 API。 |
| controller/open | 外部系统对接 API。 |
| facade | 页面聚合与跨服务编排。 |
| service | 业务接口，Controller 调用入口，不返回 Result。 |
| domain | 核心业务规则、状态机、库存/成本/审核引擎。 |
| mapper/entity | MyBatis-Plus 数据访问与实体。 |
| dto/query/vo | 入参、查询条件、出参。 |
| convert | Entity、DTO、VO 转换。 |
| validator | 业务校验器。 |

7. DTO / VO / Query / Convert 设计规范

7.1 命名规范

|----------|--------------------|-------------------------|
| 类型 | 命名示例 | 说明 |
| 新增 DTO | GoodsSaveDTO | 新增业务入参。 |
| 修改 DTO | GoodsUpdateDTO | 修改业务入参。 |
| 状态 DTO | OrderApproveDTO | 审核、反审核、启停等动作入参。 |
| 查询 Query | GoodsPageQuery | 分页查询条件。 |
| 后台 VO | AdminGoodsDetailVO | 后台详情返回，可包含管理字段。 |
| 手机端 VO | AppGoodsItemVO | 手机端列表返回，字段精简。 |
| 聚合 VO | MineHomeVO | 页面聚合返回。 |
| 转换器 | GoodsConvert | Entity <-> VO/DTO 转换。 |

7.2 Entity 不直接作为接口入参

不建议 Controller 直接接收 Entity，因为 Entity 对应数据库字段，容易暴露 deleted、tenantId、createUserId、approveStatus、成本价等内部字段。

错误示例：
@PostMapping("/save")
public Result<Void> save(@RequestBody PmsGoodsEntity entity) { ... }

推荐示例：
@PostMapping("/save")
public Result<Void> save(@Validated @RequestBody GoodsSaveDTO dto) { ... }

7.3 后台 VO 与手机端 VO 分开

|------------|------------|-----------------------|
| 字段类型 | 后台 VO | 手机端 VO |
| 主键 ID | 返回 | 按需返回，必要时可加密或只返回业务 ID。 |
| 创建/修改时间 | 返回 | 一般不返回，除非页面需要。 |
| 删除标记 | 不返回或仅管理页返回 | 不返回。 |
| 权限编码 | 管理页可返回 | 不返回。 |
| 成本价/毛利 | 按权限返回 | 默认不返回。 |
| 展示名称/图标/状态 | 返回 | 返回。 |

8. 权限、租户、数据权限与字段权限设计

8.1 认证信息建议

JWT 或登录上下文中建议包含以下信息，便于后台和手机端统一鉴权。

|--------------|-------------------------|
| 字段 | 说明 |
| userId | 当前登录用户 ID。 |
| tenantId | 当前租户 ID。 |
| orgId | 组织 ID。 |
| shopId | 门店 ID，可为空。 |
| warehouseId | 仓库 ID，可为空。 |
| roleCodes | 角色编码集合。 |
| terminalType | admin/app/pos/pda/open。 |
| language | 当前语言，支持 i18n。 |

8.2 权限分层

|----------|--------------------------|--------------------------------|
| 权限类型 | 说明 | 示例 |
| 菜单权限 | 控制能否看到模块菜单。 | pms:goods:menu |
| 按钮权限 | 控制新增、修改、删除、审核等动作。 | oms:order:approve |
| 场景权限 | 同一个基础能力在不同业务场景下控制。 | goods:select:orderCreate |
| 数据权限 | 控制能看到哪些租户、组织、门店、仓库、客户数据。 | tenant/org/shop/customer scope |
| 字段权限 | 控制成本价、毛利、手机号等敏感字段是否返回。 | goods:costPrice:view |

8.3 数据权限处理建议

后台列表查询必须经过 DataScopeEngine，支持租户、组织、门店、仓库、客户、供应商等范围。
手机端接口默认只能访问当前用户绑定的门店、仓库、司机任务、客户范围。
QueryFacade 负责排序白名单、分页适配、别名映射，避免前端传任意 SQL 字段。
复杂 JOIN 查询要明确表别名，例如 o.tenant_id、o.shop_id，便于数据权限注入。

9. 管理后台 API 开发规范

管理后台 API 主要面向系统管理员、老板、财务、采购主管、仓库主管、客服、运营人员。它的特点是配置、管理、审核、查询、导入导出、统计报表。

9.1 后台接口常用能力

|--------|------------------|-------------------------|
| 能力 | 接口建议 | 说明 |
| 分页查询 | GET /page | 支持多条件、排序白名单、数据权限。 |
| 详情 | GET /detail/{id} | 返回完整管理字段。 |
| 新增 | POST /save | DTO 入参，Service 事务处理。 |
| 修改 | POST /update | DTO 入参，不允许越权修改租户字段。 |
| 删除 | POST /delete | 逻辑删除，记录操作日志。 |
| 审核 | POST /approve | 单据状态机，幂等校验。 |
| 反审核 | POST /unapprove | 必须反向回滚库存/成本/关联单据。 |
| 导入 | POST /import | 结合 EasyExcel 与导入方案配置中心。 |
| 导出 | POST /export | 大数据量使用异步导出任务。 |

9.2 后台 Controller 模板

@RestController
@RequestMapping("/api/admin/pms/goods")
@RequiredArgsConstructor
public class AdminGoodsController {

private final GoodsService goodsService;

@GetMapping("/page")
@PreAuthorize("hasAuthority('pms:goods:page')")
public Result<PageResult<AdminGoodsPageVO>> page(@Validated GoodsPageQuery query) {
return Result.ok(goodsService.pageAdminGoods(query));
}

@PostMapping("/save")
@PreAuthorize("hasAuthority('pms:goods:save')")
public Result<Void> save(@Validated @RequestBody GoodsSaveDTO dto) {
goodsService.saveGoods(dto);
return Result.ok();
}
}

10. 手机端 API 开发规范

手机端 API 面向业务员、司机、仓库员、门店员工、收银员、团长、客户、供应商协同用户等移动场景。它的核心不是"完整管理字段"，而是"少请求、轻字段、弱网可用、操作安全"。

10.1 手机端接口设计原则

页面聚合：一个页面尽量一个聚合接口返回基本数据，减少移动端请求次数。
字段精简：只返回 UI 展示与操作必需字段。
按角色过滤：菜单、按钮、功能入口按当前用户权限过滤。
强版本兼容：App 已发版接口不能随意删除字段或改变字段类型。
弱网处理：关键操作支持幂等 key、重试、离线缓存或失败补偿。
敏感字段默认不返回：成本价、毛利、内部审批备注等字段要受控。

10.2 手机端 BFF 聚合接口模板

@RestController
@RequestMapping("/api/app/mine")
@RequiredArgsConstructor
public class AppMineController {

private final MineHomeFacade mineHomeFacade;

@GetMapping("/home")
@PreAuthorize("hasAuthority('mine:home:view')")
public Result<MineHomeVO> home(@RequestHeader(value = "X-Terminal", required = false) String terminal) {
return Result.ok(mineHomeFacade.getMineHome(terminal));
}
}

10.3 手机端响应字段建议

|--------------|---------------------------------|
| 字段原则 | 说明 |
| 只返回必要字段 | 列表中不要返回完整 Entity。 |
| 金额字段统一格式 | BigDecimal 原值 + 展示字符串按需返回。 |
| 状态字段双返回 | statusCode + statusName，方便前端展示。 |
| 图片字段返回完整 URL | 避免前端拼接路径。 |
| 操作按钮由后端返回 | 根据权限、状态、终端返回 allowedActions。 |
| 服务端兜底 | 前端隐藏按钮不等于权限校验，后端必须再次校验。 |

11. 公共 API、开放 API、POS/API 的边界

11.1 公共 API

公共 API 是各端都可复用的基础能力，但仍需按业务类型控制权限、文件大小、访问频率。

|---------------------------|----------------------|
| 接口 | 说明 |
| /api/common/dict/list | 数据字典列表。 |
| /api/common/area/tree | 省市区树。 |
| /api/common/file/upload | 文件上传，需传业务类型 bizType。 |
| /api/common/captcha | 验证码。 |
| /api/common/version/check | 版本检查。 |

11.2 开放 API

开放 API 面向第三方系统，需要单独的签名、AppKey、时间戳、防重放、IP 白名单、限流、审计日志。不要直接复用后台 Controller。

/api/open/v1/order/push
/api/open/v1/inventory/query
/api/open/v1/customer/sync

Header:
X-App-Key
X-Timestamp
X-Nonce
X-Signature
X-Tenant-Code

11.3 POS / PDA API

POS 与 PDA 需要考虑设备编号、离线同步、幂等提交、数据增量拉取、价格缓存、库存缓存、打印设备等能力，建议独立路径。

|-------------------------------|---------------------|
| 接口 | 说明 |
| /api/pos/login | POS 设备登录。 |
| /api/pos/sync/pull | 拉取商品、价格、会员、促销等增量数据。 |
| /api/pos/sale/submit | 提交销售订单，必须带幂等号。 |
| /api/pda/wms/pick/task/list | PDA 拣货任务。 |
| /api/pda/wms/stocktake/submit | PDA 盘点提交。 |

12. 核心业务域 API 清单建议

以下清单用于改造整个升鲜宝项目源代码时做接口归类。实际开发时可按模块逐步落地，不要求一次性全部改完。

12.1 系统与权限域 sys

|-------|--------|--------------------------|--------|-------------------|
| 端 | 方法 | 路径 | 说明 | 共用服务 |
| 后台 | GET | /api/admin/sys/user/page | 用户分页查询 | SysUserService |
| 后台 | POST | /api/admin/sys/user/save | 新增用户 | SysUserService |
| 后台 | POST | /api/admin/sys/role/save | 新增角色 | SysRoleService |
| 后台 | POST | /api/admin/sys/menu/save | 新增菜单 | SysMenuService |
| 手机 | GET | /api/app/user/current | 获取当前用户 | UserProfileFacade |
| 公共 | GET | /api/common/dict/list | 字典列表 | DictService |

12.2 商品域 pms

|-------|--------|--------------------------------|---------|------------------|
| 端 | 方法 | 路径 | 说明 | 共用服务 |
| 后台 | GET | /api/admin/pms/goods/page | 商品分页管理 | GoodsService |
| 后台 | POST | /api/admin/pms/goods/save | 新增商品 | GoodsService |
| 后台 | POST | /api/admin/pms/goods/update | 修改商品 | GoodsService |
| 后台 | GET | /api/admin/pms/unit/page | 单位管理 | UnitService |
| 手机 | GET | /api/app/pms/goods/search | 移动端商品搜索 | GoodsQueryFacade |
| 手机 | GET | /api/app/pms/goods/detail/{id} | 移动端商品详情 | GoodsQueryFacade |

12.3 采购与供应商域 pur/sup

|-------|--------|------------------------------|-----------|----------------------|
| 端 | 方法 | 路径 | 说明 | 共用服务 |
| 后台 | GET | /api/admin/pur/order/page | 采购订单分页 | PurchaseOrderService |
| 后台 | POST | /api/admin/pur/order/approve | 采购订单审核 | PurchaseOrderService |
| 后台 | GET | /api/admin/sup/supplier/page | 供应商分页 | SupplierService |
| 手机 | GET | /api/app/pur/order/list | 移动端采购订单列表 | PurchaseOrderFacade |
| 手机 | POST | /api/app/sup/order/confirm | 供应商确认订单 | SupplierOrderService |

12.4 订单域 oms

|-------|--------|--------------------------------|--------|--------------------|
| 端 | 方法 | 路径 | 说明 | 共用服务 |
| 后台 | GET | /api/admin/oms/order/page | 订单分页 | OrderService |
| 后台 | POST | /api/admin/oms/order/approve | 订单审核 | OrderService |
| 后台 | POST | /api/admin/oms/order/cancel | 订单取消 | OrderService |
| 手机 | GET | /api/app/oms/order/list | 我的订单列表 | OrderFacade |
| 手机 | GET | /api/app/oms/order/detail/{id} | 订单详情 | OrderFacade |
| 手机 | POST | /api/app/oms/order/create | 移动端下单 | OrderCreateService |

12.5 公司仓库域 wms

|-------|--------|----------------------------------|----------|------------------|
| 端 | 方法 | 路径 | 说明 | 共用服务 |
| 后台 | GET | /api/admin/wms/stockin/page | 入库单分页 | StockinService |
| 后台 | POST | /api/admin/wms/stockin/approve | 入库审核 | StockinService |
| 后台 | GET | /api/admin/wms/stockout/page | 出库单分页 | StockoutService |
| 后台 | POST | /api/admin/wms/stocktake/approve | 盘点审核 | StocktakeService |
| 手机 | GET | /api/app/wms/task/list | 移动仓库任务列表 | WmsTaskFacade |
| 手机 | POST | /api/app/wms/stockin/receive | 移动收货确认 | StockinService |

12.6 门店仓储与 POS 域 hwms/pos

|-------|--------|--------------------------------|----------|----------------------|
| 端 | 方法 | 路径 | 说明 | 共用服务 |
| 后台 | GET | /api/admin/hwms/inventory/page | 门店库存分页 | HwmsInventoryService |
| 后台 | GET | /api/admin/pos/shift/page | 收银班次分页 | PosShiftService |
| 手机 | GET | /api/app/hwms/stocktake/list | 门店盘点列表 | HwmsStocktakeFacade |
| 手机 | POST | /api/app/hwms/stocktake/submit | 门店盘点提交 | HwmsStocktakeService |
| POS | POST | /api/pos/sale/submit | 收银订单提交 | PosSaleService |
| POS | GET | /api/pos/sync/pull | POS 增量同步 | PosSyncService |

12.7 CRM 与财务域 crm/fin

|-------|--------|--------------------------------|---------|---------------------|
| 端 | 方法 | 路径 | 说明 | 共用服务 |
| 后台 | GET | /api/admin/crm/customer/page | 客户分页 | CustomerService |
| 后台 | POST | /api/admin/crm/customer/save | 新增客户 | CustomerService |
| 手机 | POST | /api/app/crm/lead/create | 手机端新增线索 | CustomerLeadService |
| 后台 | GET | /api/admin/fin/receivable/page | 应收分页 | ReceivableService |
| 后台 | POST | /api/admin/fin/payment/approve | 收付款审核 | PaymentService |
| 手机 | GET | /api/app/fin/bill/list | 移动端账单列表 | BillFacade |

13. 我的中心模块 API 改造示例

我的中心是最适合先改造的模块，因为它天然同时包含手机端展示接口和后台配置接口。

13.1 手机端 API

|--------|---------------------------------|--------------------------|-----------------------------|
| 方法 | 路径 | 说明 | 返回对象 |
| GET | /api/app/mine/home | 我的中心首页聚合：用户信息、授权信息、菜单分组。 | MineHomeVO |
| GET | /api/app/mine/profile | 个人资料。 | MineProfileVO |
| POST | /api/app/mine/profile/update | 修改个人资料。 | Void |
| GET | /api/app/mine/qrcode | 我的二维码/推广码。 | MineQrCodeVO |
| GET | /api/app/mine/support/config | 客服热线、在线客服、CEO 邮箱配置。 | List<MineSupportConfigVO> |
| POST | /api/app/mine/feedback/submit | 提交反馈。 | Void |
| GET | /api/app/mine/print/device/list | 我的打印设备列表。 | List<MinePrintDeviceVO> |
| POST | /api/app/mine/print/device/save | 保存打印设备。 | Void |
| POST | /api/app/mine/print/test | 打印测试。 | MinePrintTestVO |
| GET | /api/app/mine/setting/list | 用户设置项列表。 | List<MineSettingGroupVO> |
| POST | /api/app/mine/setting/save | 保存用户设置。 | Void |

13.2 后台管理 API

|--------|-----------------------------------|-------------|------------------------------------|
| 方法 | 路径 | 说明 | 返回对象 |
| GET | /api/admin/mine/menu/page | 我的中心菜单配置分页。 | PageResult<AdminMineMenuVO> |
| POST | /api/admin/mine/menu/save | 新增菜单配置。 | Void |
| POST | /api/admin/mine/menu/update | 修改菜单配置。 | Void |
| POST | /api/admin/mine/menu/delete | 删除菜单配置。 | Void |
| POST | /api/admin/mine/menu/enable | 启用菜单。 | Void |
| POST | /api/admin/mine/menu/disable | 停用菜单。 | Void |
| GET | /api/admin/mine/support/page | 客服配置分页。 | PageResult<AdminSupportConfigVO> |
| POST | /api/admin/mine/support/save | 保存客服配置。 | Void |
| GET | /api/admin/mine/feedback/page | 用户反馈分页。 | PageResult<AdminFeedbackVO> |
| POST | /api/admin/mine/feedback/reply | 回复用户反馈。 | Void |
| GET | /api/admin/mine/print/device/page | 打印设备分页。 | PageResult<AdminPrintDeviceVO> |

13.3 共用 Service

|--------------------------|---------------------|
| Service | 职责 |
| MineMenuService | 菜单配置、启停、按终端和权限过滤。 |
| MineUserSettingService | 用户个性化设置保存、查询、重置。 |
| MineSupportConfigService | 客服热线、在线客服、CEO 邮箱配置。 |
| MineFeedbackService | 反馈提交、查询、回复、关闭。 |
| MinePrintDeviceService | 打印设备保存、默认设置、删除、测试。 |
| MineHomeFacade | 手机端我的中心首页聚合。 |

14. 代码骨架与标准模板

14.1 Service 接口模板

public interface MineMenuService extends IService<MineMenuEntity> {

PageResult<AdminMineMenuVO> pageAdmin(MineMenuPageQuery query);

List<MineMenuGroupVO> listAppMenuGroups(Long tenantId, Long userId, String terminalType);

void saveMenu(MineMenuSaveDTO dto);

void updateMenu(MineMenuUpdateDTO dto);

void enable(Long id);

void disable(Long id);
}

说明：Service 接口不返回 Result，Result 只出现在 Controller 层。

14.2 Facade 聚合模板

@Service
@RequiredArgsConstructor
public class MineHomeFacade {

private final MineMenuService mineMenuService;
private final MineSupportConfigService supportConfigService;
private final LicenseService licenseService;
private final UserProfileService userProfileService;

public MineHomeVO getMineHome(String terminalType) {
Long tenantId = LoginUserContext.getTenantId();
Long userId = LoginUserContext.getUserId();

MineUserInfoVO userInfo = userProfileService.getMineUserInfo(userId);
MineLicenseInfoVO licenseInfo = licenseService.getMineLicenseInfo(tenantId);
List<MineMenuGroupVO> menuGroups = mineMenuService.listAppMenuGroups(tenantId, userId, terminalType);

MineHomeVO vo = new MineHomeVO();
vo.setUserInfo(userInfo);
vo.setLicenseInfo(licenseInfo);
vo.setMenuGroups(menuGroups);
return vo;
}
}

14.3 Entity 模板

@Data
@TableName("mine_menu")
public class MineMenuEntity {

@TableId(type = IdType.AUTO)
private Long id;

private Long tenantId;

private String menuCode;

private String menuName;

private String groupCode;

private String iconCode;

private String iconUrl;

private String path;

private String permissionCode;

private String terminalType;

private Integer visibleFlag;

private Integer enabledFlag;

private Integer sortNo;

private String remark;

private LocalDateTime createTime;

private LocalDateTime updateTime;

private Integer deleted;
}

14.4 Controller 命名模板

|-------|-------------------------|------------------------|
| 端 | Controller 命名 | 路径 |
| 后台 | AdminMineMenuController | /api/admin/mine/menu |
| 手机 | AppMineController | /api/app/mine |
| POS | PosSaleController | /api/pos/sale |
| PDA | PdaPickTaskController | /api/pda/wms/pick/task |
| 开放 | OpenOrderController | /api/open/v1/order |
| 公共 | CommonDictController | /api/common/dict |

15. 旧项目 API 改造实施路线图

为了降低风险，不建议一次性推倒重来。应按"接口盘点 -> 分类 -> 抽 Service -> 分 Controller -> 建 VO -> 加权限 -> 保持兼容 -> 灰度上线"的方式逐步改造。

15.1 改造步骤

接口盘点：导出所有 Controller 路径，按业务域、终端、权限、是否外部使用进行分类。
识别混用接口：找出 PC 后台和手机端共同调用的接口，标记字段泄露、权限混乱、返回臃肿问题。
抽取共用 Service：把 Controller 中业务逻辑迁移到 Service / Domain。
拆分 Controller：新增 controller/admin、controller/app、controller/pos 等入口。
拆分 DTO/VO：后台 VO 保留管理字段，手机端 VO 做字段精简。
补齐权限：为每个新接口配置权限编码、菜单、按钮、数据权限。
兼容旧接口：旧接口保留一段时间，内部调用新 Service，并标记 deprecated。
联调与回归：按模块进行接口自动化测试、权限测试、字段脱敏测试。
灰度上线：优先改造我的中心、系统设置、商品查询等风险较低模块，再改造订单、库存、财务。

15.2 推荐改造优先级

|---------|-------------------------------------------|------------------------------|
| 优先级 | 模块 | 原因 |
| P0 | 公共 Result、ErrorCode、LoginUserContext、权限注解 | 所有接口的基础能力，先统一。 |
| P1 | 我的中心 / 设置 / 客服 / 打印 | 边界清晰，风险较低，适合做样板。 |
| P1 | 商品查询接口 | 后台管理与手机端选择商品差异明显。 |
| P2 | 订单 OMS | 业务核心，先抽 Service，再拆接口。 |
| P2 | 采购 / 供应商 | 涉及供应商协同端，应区分 admin/app/open。 |
| P3 | WMS / HWMS / POS | 涉及库存和离线设备，需要充分测试。 |
| P3 | 财务 | 权限敏感，字段权限和审计必须完善后再改。 |

15.3 兼容旧接口策略

旧接口不要立即删除，先保留并在代码中标记 @Deprecated。
旧接口内部调用新的 Service，避免维护两套逻辑。
通过网关、日志或埋点统计旧接口调用量。
前端全部迁移完成并运行一个版本周期后，再删除旧接口。
对手机端旧版本接口，必须保留更长兼容期。

16. 测试、审计、日志、缓存与上线检查

16.1 接口测试维度

|----------|------------------------------|
| 测试类型 | 检查内容 |
| 功能测试 | 新增、修改、删除、审核、反审核、查询、导入导出是否正常。 |
| 权限测试 | 无权限用户不能访问，越权数据不能返回。 |
| 字段权限测试 | 成本价、手机号、毛利等敏感字段是否按权限返回。 |
| 租户隔离测试 | A 租户不能访问 B 租户数据。 |
| 幂等测试 | 重复提交不会重复生成单据、重复扣库存、重复付款。 |
| 版本兼容测试 | 手机端旧版本字段仍能正常解析。 |
| 性能测试 | 分页、列表、聚合接口响应时间符合要求。 |

16.2 操作日志与审计

后台新增、修改、删除、审核、反审核必须记录操作日志。
手机端关键动作如收货、发货、签收、盘点、提交反馈也要记录终端来源。
开放 API 必须记录 appKey、请求体摘要、签名结果、响应结果、耗时。
失败日志要能定位 userId、tenantId、接口、参数摘要、错误码。

16.3 缓存建议

|--------|-------------------------------------------------|----------------|
| 数据 | 缓存策略 | 失效方式 |
| 菜单配置 | Redis + Caffeine，可按 tenantId + terminalType 缓存。 | 菜单新增/修改/启停后清理。 |
| 数据字典 | 高频缓存。 | 字典变更后清理。 |
| 用户设置 | 按 tenantId + userId 缓存。 | 用户保存设置后清理。 |
| 客服配置 | 低频变更，高频读取。 | 后台修改后清理。 |
| 商品基础信息 | 可缓存热点商品。 | 商品更新、价格更新后清理。 |
| 库存数量 | 谨慎缓存，关键扣减必须查数据库/库存引擎。 | 库存过账后失效或使用实时表。 |

16.4 错误码规范

建议继续使用升鲜宝分域错误码，Service 抛业务异常，Controller 统一转换为 Result。

|-------|---------|----------------------------|
| 域 | 编码段 | 示例 |
| 系统权限 | 10xxx | 10001 用户未登录，10002 无权限。 |
| 商品 | 20xxx | 20001 商品不存在。 |
| 订单 | 30xxx | 30001 订单状态不允许审核。 |
| 仓库 | 40xxx | 40001 库存不足。 |
| 门店 | 45xxx | 45001 门店库存不存在。 |
| 我的中心 | 58xxx | 58001 菜单不存在，58004 打印设备不存在。 |
| 财务 | 60xxx | 60001 凭证不平。 |

17. 附录：接口评审清单与迁移清单

17.1 新接口评审清单

|--------------------------|----------|-----------------------------------|
| 检查项 | 是否必须 | 说明 |
| 路径是否符合 /api/{端}/{域}/{资源} | 是 | 路径必须清晰表达终端与业务域。 |
| Controller 是否只做入口 | 是 | 不得直接写复杂业务，不得直接调 Mapper。 |
| Service 是否可复用 | 是 | 后台、手机端、POS 能共用的业务能力必须沉淀到 Service。 |
| DTO/VO 是否按端区分 | 是 | 避免字段泄露和返回臃肿。 |
| 是否配置权限编码 | 是 | 接口、按钮、场景权限必须清晰。 |
| 是否支持租户隔离 | 是 | 所有业务表必须受 tenantId 控制。 |
| 是否需要幂等 | 按场景 | 订单、库存、付款、打印重试等必须幂等。 |
| 是否记录操作日志 | 按场景 | 写操作、审核、反审核必须记录。 |
| 是否需要版本兼容 | 手机端必须 | App、小程序接口字段不能随意破坏。 |

17.2 旧接口迁移清单模板

|---------------|-----------------------------------|---------------------------------|------------------------|----------|
| 旧接口 | 新后台接口 | 新手机接口 | 共用 Service | 迁移状态 |
| /goods/list | /api/admin/pms/goods/page | /api/app/pms/goods/search | GoodsService | 待迁移 |
| /order/list | /api/admin/oms/order/page | /api/app/oms/order/list | OrderService | 待迁移 |
| /setting/list | /api/admin/mine/menu/page | /api/app/mine/setting/list | MineUserSettingService | 待迁移 |
| /print/list | /api/admin/mine/print/device/page | /api/app/mine/print/device/list | MinePrintDeviceService | 待迁移 |

17.3 最终落地标准

升鲜宝 API 改造最终标准：

后台管理端 Controller 与手机端 Controller 分开。
Service、Domain、Mapper、Entity 共用。
Service 接口不返回 Result。
Entity 不作为 Controller 入参。
AdminVO 与 AppVO 分开。
所有接口都有权限编码、错误码、日志策略。
手机端接口优先采用页面聚合接口，减少请求次数。
旧接口迁移期间保留兼容层，稳定后再删除。
所有核心写操作具备幂等能力。
租户隔离、数据权限、字段权限必须作为底层能力统一处理。

以上规范可作为升鲜宝后端项目整体改造的 API 开发基准文档。建议先从"我的中心/设置模块"按本规范落地一版，再逐步推广到商品、订单、采购、仓储、门店、POS、CRM、财务等核心业务域。