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

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

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

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

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

 

文档目录

1. 文档目标与总体结论

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

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

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

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

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

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

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

9. 管理后台 API 开发规范

10. 手机端 API 开发规范

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

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

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

14. 代码骨架与标准模板

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

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

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

 

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

4.3 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 改造步骤

1. 接口盘点：导出所有 Controller 路径，按业务域、终端、权限、是否外部使用进行分类。

2. 识别混用接口：找出 PC 后台和手机端共同调用的接口，标记字段泄露、权限混乱、返回臃肿问题。

3. 抽取共用 Service：把 Controller 中业务逻辑迁移到 Service / Domain。

4. 拆分 Controller：新增 controller/admin、controller/app、controller/pos 等入口。

5. 拆分 DTO/VO：后台 VO 保留管理字段，手机端 VO 做字段精简。

6. 补齐权限：为每个新接口配置权限编码、菜单、按钮、数据权限。

7. 兼容旧接口：旧接口保留一段时间，内部调用新 Service，并标记 deprecated。

8. 联调与回归：按模块进行接口自动化测试、权限测试、字段脱敏测试。

9. 灰度上线：优先改造我的中心、系统设置、商品查询等风险较低模块，再改造订单、库存、财务。

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 改造最终标准：

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

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