升鲜宝供应链管理系统Spring Boot 4.0 项目源代码结构及数据...

博客园 - 升鲜宝生鲜供应链系统

升鲜宝生鲜供应链系统 · 2026-05-17 · via 博客园 - 升鲜宝生鲜供应链系统

升鲜宝供应链管理系统Spring Boot 4.0 项目源代码结构及数据库字典模块命名与表字段命名开发约束规范(一）---升鲜宝生鲜配送供应链管理系统

V1.0 · 研发参考版

适用：升鲜宝供应链后端 Spring Boot 4.0 升级、新模块开发、数据库建模、代码生成、AI 辅助开发约束

项目	说明
文档目标	统一升鲜宝 Spring Boot 4.0 项目源码结构、业务模块命名、数据库表命名、字段命名、接口命名、菜单路由和代码生成规范。
约束等级	MUST=必须执行；SHOULD=推荐执行；PROHIBITED=禁止使用。
主要技术栈	Spring Boot 4.0、Spring Framework 7、Java 17+、MyBatis-Plus、MySQL 8.0+、Redis、Vue3、Element Plus。
核心原则	领域清晰、命名稳定、少改动兼容现库、销售/库存/采购口径分离、统一审计字段、统一 Req/Resp 命名。

生成日期：2026-05-16

1. 文档范围与技术基线

本文档用于约束升鲜宝供应链管理系统在 Spring Boot 4.0 目标架构下的新模块开发、旧模块重构、数据库字典设计、代码生成和前后端菜单集成。

1.1 适用范围

后端 Java 项目：业务模块源码结构、Controller、Service、Dao、Entity、Req、Resp、XML、枚举、转换器和领域对象。
数据库设计：模块前缀、表命名、字段命名、数据类型、字典注释、索引、唯一键和审计字段。
前端 Vue3 项目：业务模块页面目录、列表页、新增/修改弹窗页、路由和菜单 SQL URL 对应关系。
AI 代码生成：所有自动生成代码必须遵循本文目录与命名规则，避免生成独立项目、错误分层和不可合并结构。

1.2 Spring Boot 4.0 技术基线

项目	约束
Java	MUST 使用 Java 17 或更高版本；生产建议优先 Java 21 LTS 或企业统一版本。
Spring Boot	目标版本为 Spring Boot 4.0.x；新代码不得继续使用 javax.* 包，应迁移到 jakarta.*。
Spring Framework	Spring Boot 4.0 基于 Spring Framework 7.x，项目公共依赖必须统一由父工程管理。
Jakarta EE	MUST 采用 Jakarta EE 11 口径，例如 jakarta.validation、jakarta.servlet、jakarta.persistence。
JSON	Spring Boot 4 以 Jackson 3 为默认方向，序列化兼容需通过统一配置处理。
构建工具	Maven/Gradle 版本由父工程统一，不允许各模块私自指定冲突版本。
ORM	默认使用 MyBatis-Plus；普通查询优先 LambdaWrapper；复杂查询使用 XML，但必须参数化。

说明：Spring Boot 4.0 属于重大版本升级，老项目迁移时应先做依赖清点、javax 到 jakarta 替换、序列化兼容测试和基础框架适配，不建议直接全量替换生产项目。

1.3 约束等级

等级	含义	示例
MUST	必须执行，违反会导致代码不可合并或数据不可维护。	所有新请求对象必须使用 Req 前缀，例如 ReqB2bCouponSave。
SHOULD	推荐执行，除非兼容旧系统有明确理由。	新表建议使用 enabled、del_flag、sort_code、creator、create_date 等公共字段。
PROHIBITED	禁止使用，除非为了兼容旧表只读保留。	新字段禁止以 is_ 开头，布尔字段统一使用 xxx_flag。

2. 总体工程结构规范

升鲜宝 Spring Boot 4.0 后端推荐采用“业务模块内部分层”的源码组织方式。每个业务域是一个一级业务子目录，业务子目录下直接放 controller、service、dao、entity、xml 等目录。

2.1 后端推荐工程结构

sxb-scm-backend
└─ src/main/java/com/loveinway/sxbscm
   ├─ common                # 通用返回、分页、工具、异常、基础枚举
   ├─ config                # Spring、MyBatis-Plus、Redis、Security、Jackson 配置
   ├─ security              # 认证、授权、登录上下文、数据权限拦截
   ├─ sys                   # 系统管理：用户、角色、菜单、字典、日志
   ├─ platform              # 平台云商品库：platform_ 前缀表
   ├─ pms                   # 公司商品中心：pms_ 前缀表
   ├─ b2bmall               # B2B订货商城：b2b_ + 复用客户/商品/价格/Banner/通知
   ├─ oms                   # 订单中心：oms_ 前缀表
   ├─ wms                   # 公司仓库库存与成本：wms_ 前缀表
   ├─ cwms                  # B2B客户轻量进销存：cwms_ 前缀表
   ├─ storeinv              # 门店库存：store_inv_ 前缀表
   ├─ pos                   # 门店收银：pos_ 前缀表
   ├─ ums                   # 会员域：ums_ 前缀表
   ├─ fin                   # 财务域：fin_ 前缀表
   ├─ pur                   # 采购域：pur_ 前缀表
   └─ sup                   # 供应商域：sup_ 前缀表

2.2 前端推荐工程结构

sxb-scm-frontend
└─ src
   ├─ views
   │ ├─ b2bmall
   │ │ ├─ b2bcoupon.vue
   │ │ ├─ b2bcoupon-add-or-update.vue
   │ │ ├─ b2bmallcategory.vue
   │ │ └─ b2bmallcategory-add-or-update.vue
   ├─ api
   │ └─ b2bmall
   │     ├─ b2bcoupon.ts
   │     └─ b2bmallcategory.ts
   ├─ router
   │ └─ modules
   │     └─ b2bmall.ts
   └─ components
      └─ b2bmall

2.3 禁止的工程组织方式

PROHIBITED：禁止为 b2bmall 生成独立后端工程、独立 pom.xml、独立 SpringBootApplication。b2bmall 是现有后端项目中的业务子目录。
PROHIBITED：禁止生成 controller/admin/b2bmall、service/b2bmall、dao/b2bmall 这种全局分层下挂结构。
PROHIBITED：禁止前端每个功能生成新增页、编辑页、详情页多个页面；升鲜宝前端默认一个列表页 + 一个新增/修改弹窗页。
PROHIBITED：禁止把 OMS 正式订单表、WMS 库存成本表复制到 b2bmall 内重复建设。

3. 业务模块命名规范

业务模块命名必须和业务边界、数据库前缀、前端目录、菜单权限编码保持一致。模块名称必须稳定，不因页面名称或临时需求随意改变。

业务模块	Java目录名	表前缀	核心职责	命名约束
平台云商品库	platform	platform_	平台公共商品模板库，不直接参与销售、采购、库存核算。	不得与公司商品中心 pms_ 混用。
公司商品中心	pms	pms_	公司商品、SPU、SKU、单位、销售最小粒度。	销售最小粒度使用 sku_unit_id。
B2B订货商城	b2bmall	b2b_	下单前商城运营、客户可见范围、价格展示、购物车、优惠券、提交OMS前校验。	不得直接写 OMS 订单主从表。
订单中心	oms	oms_	订单主从、审核、发货、退货、多退少补、提交来源承接。	正式客户订单归 OMS。
公司仓库库存	wms	wms_	公司库存、批次、库位、成本、出入库。	库存主口径 product_sku_id + unit_id。
客户轻量库存	cwms	cwms_	B2B客户自己的轻量进销存。	不代表供应链公司的公司库存。
门店库存	storeinv	store_inv_	门店实时库存、盘点、出入库、报损报溢。	表前缀用 store_inv_，Java目录可用 storeinv。
门店收银	pos	pos_	收银交易、支付、退款、班次、设备打印。	POS订单属于门店对会员销售。
会员域	ums	ums_	会员、会员等级、积分、钱包、会员权益。	会员域继续用 ums_，不改 member_。
财务域	fin	fin_	应收应付、收付款、对账、发票、凭证。	金额字段必须 DECIMAL。
采购域	pur	pur_	采购申请、采购单、采购入库、采购退货。	采购商品主口径 product_sku_id + unit_id。
供应商域	sup	sup_	供应商档案、授权、报价、合同。	供应商档案与采购单引用分离。
系统管理	sys	sys_	用户、角色、菜单、字典、租户、日志。	菜单 URL 必须与前端路由 path 对应。

3.1 模块命名基本规则

MUST：Java 目录使用小写英文，不使用中文、空格、横线。
MUST：数据库表使用小写下划线 snake_case，必须带业务前缀。
MUST：前端 views/api 目录与业务模块目录一致，例如 src/views/b2bmall、src/api/b2bmall。
SHOULD：模块名称尽量短，避免 b2b_mall_ordering_management_system 这类过长命名。
PROHIBITED：禁止同一个业务模块出现多个别名，例如 b2b、b2bmall、cusoms 混用。历史模块保留，但新模块必须统一。

4. 后端代码目录结构规范

每个业务模块目录下直接分层，保持升鲜宝现有工程易合并、易定位、易生成代码的特点。以下以 b2bmall 为标准示例。

b2bmall
├─ constant                    # 模块常量
├─ controller                  # 控制器
│ ├─ admin                    # 后台管理端接口
│ └─ b2bmall                  # 客户订货端接口
├─ converter                   # Entity / Req / Resp 转换
├─ dao                         # MyBatis-Plus Mapper 接口
├─ domain                      # 领域对象、内部业务对象、上下文对象
├─ entity                      # 数据库实体
├─ enums                       # 枚举
├─ req                         # 请求对象，统一 Req 前缀
├─ resp                        # 返回对象，统一 Resp 前缀
├─ service                     # Service 接口
│ └─ impl                     # Service 实现类
└─ xml                         # MyBatis XML 映射文件

目录	放置内容	命名示例	约束
constant	模块常量、缓存Key、权限前缀、默认值。	B2bMallConstant	常量类必须 final，构造私有。
controller/admin	后台管理端 Controller。	B2bCouponController	处理后台列表、保存、启停、发布、导出等。
controller/b2bmall	客户订货端 Controller。	B2bMallHomeController	处理首页、商品、购物车、提交OMS等。
converter	Entity、Req、Resp 转换。	B2bCouponConverter	禁止在 Controller 中堆大量字段复制。
dao	Mapper 接口。	B2bCouponDao	继承 BaseMapper，复杂查询在 XML。
domain	内部业务对象、上下文、聚合结果。	B2bPriceContext	不直接映射数据库表。
entity	数据库实体。	B2bCouponEntity	字段与表字段一一对应。
enums	状态、类型、业务枚举。	CouponUseStatusEnum	必须有 code/name，禁止魔法数字散落。
req	请求入参对象。	ReqB2bCouponSave	统一 Req 前缀，不使用 DTO 作为主命名。
resp	返回对象。	RespB2bCoupon	统一 Resp 前缀，不使用 VO 作为主命名。
service	Service 接口。	B2bCouponService	接口不返回前端 Result 包装。
service/impl	Service 实现。	B2bCouponServiceImpl	实现类只放 impl 子目录。
xml	MyBatis XML。	B2bCouponDao.xml	namespace 必须指向 Dao 全限定名。

5. Java 类、接口、方法与包命名规范

5.1 包命名

MUST：包名全部小写，使用业务模块名作为一级业务边界，例如 com.loveinway.sxbscm.b2bmall.service。
MUST：新增模块不得把业务代码放到 common、utils、base 等公共目录。公共目录只放真正跨模块复用能力。
SHOULD：模块内部不要再按功能无限嵌套目录，除非文件数量过多且有清晰子域。

5.2 类命名

类型	命名规则	示例
Controller	业务对象 + Controller	B2bCouponController
Service接口	业务对象 + Service	B2bCouponService
Service实现	业务对象 + ServiceImpl	B2bCouponServiceImpl
Dao	业务对象 + Dao	B2bCouponDao
Entity	业务对象 + Entity	B2bCouponEntity
Req	Req + 业务对象 + 场景	ReqB2bCouponSave / ReqB2bCouponPage
Resp	Resp + 业务对象	RespB2bCoupon
Enum	业务语义 + Enum	CouponUseStatusEnum
Converter	业务对象 + Converter	B2bCouponConverter
Domain	业务语义 + Context/Result/Item	B2bPriceContext / B2bSubmitCheckResult

5.3 方法命名

方法类型	推荐命名	禁止/避免
分页查询	page(req)	listPageData / getListByPageInfo
详情查询	getById(id) / detail(id)	selectOneInfoData
新增或修改	save(req) / update(req) / saveOrUpdate(req)	addData / editData 随意混用
删除	delete(id) / deleteBatch(ids)	removeInfo / delData
启停	updateEnabled(id, enabled)	updateStatus(row) 且无业务语义
发布/下架	publish(id) / offline(id)	changeStatus(1/2)
校验	checkSubmit(req) / validateCoupon(req)	check(req) 但无返回说明
业务计算	calculateCustomerPrice(ctx)	calc(data)

6. Controller、Service、Dao、XML 分层约束

6.1 Controller 约束

MUST：Controller 只做参数接收、基础校验、权限注解、调用 Service、统一返回，不写复杂业务逻辑。
MUST：后台管理端 Controller 放在 controller/admin；客户订货端 Controller 放在 controller/b2bmall。
MUST：后台 URL 与前端菜单 URL 保持一致，例如 /b2bmall/b2bcoupon/page、/b2bmall/b2bcoupon/{id}。
SHOULD：新增、修改可共用 saveOrUpdate，但保存前必须区分主键是否为空。
PROHIBITED：禁止 Controller 直接调用多个 Dao 拼业务，必须经 Service 编排。
MUST：Service 接口文件直接放在模块 service 目录，ServiceImpl 放在 service/impl。
MUST：Service 负责业务编排、跨表校验、状态机、幂等、事务边界。
MUST：Service 接口不返回前端 Result 包装，返回 Resp、Domain、PageResult 或业务对象。
SHOULD：普通 CRUD 可复用公共基类，但业务动作必须显式方法化。
PROHIBITED：禁止在 ServiceImpl 中写硬编码 SQL 字符串拼接 ORDER BY。
MUST：Dao 只放数据库访问方法，复杂 SQL 写在同名 XML 中。
MUST：XML namespace 必须等于 Dao 接口全限定名。
MUST：所有外部入参必须使用 #{param} 参数化，禁止 ${} 拼用户输入。
MUST：排序字段必须经过白名单转换，不允许前端字段直接进入 ORDER BY。
SHOULD：单表查询优先 MyBatis-Plus LambdaQueryWrapper；多表名称回填可写 XML。

6.2 Service 约束

6.3 Dao/XML 约束

6.4 Service 模板

public interface B2bCouponService {
    PageResult<RespB2bCoupon> page(ReqB2bCouponPage req);
    RespB2bCoupon detail(Long id);
    Long save(ReqB2bCouponSave req);
    void update(ReqB2bCouponSave req);
    void delete(Long id);
    void updateEnabled(Long id, Integer enabled);
    void publish(Long id);
    void offline(Long id);
}

7. 前端目录、页面、路由与菜单 SQL 对应规范

升鲜宝前端现有写法是每个功能一个列表页、一个新增/修改弹窗页。b2bmall 必须沿用该风格，不生成过多页面。

7.1 页面文件命名

src/views/b2bmall
├─ b2bcoupon.vue
├─ b2bcoupon-add-or-update.vue
├─ b2bmallcategory.vue
├─ b2bmallcategory-add-or-update.vue
├─ customermallconfig.vue
└─ customermallconfig-add-or-update.vue

页面类型	命名规则	说明
列表页	xxx.vue	负责查询、重置、新增、导出、列表、分页、删除、启停。
新增/修改页	xxx-add-or-update.vue	以 el-dialog 弹窗方式实现，通过 defineExpose({ init }) 打开。
详情页	默认不单独生成	除订单、波次、库存单据等复杂业务外，不生成单独详情页面。
选择器组件	components/b2bmall/xxx-select.vue	客户、价格组、商品、分类、优惠券等字段使用选择器，不直接输入 ID。

7.2 路由与菜单 SQL 对应

MUST：sys_menu.url 必须等于前端列表页 route.path。
MUST：菜单 SQL 只插入列表页作为三级功能菜单，新增/修改路由只在前端静态路由中配置。
MUST：新增/修改页面 meta.activeMenu 必须指回列表路由。
SHOULD：权限编码与 URL 保持同一语义，例如 b2b:mall:coupon:page、b2b:mall:coupon:save。

// 列表路由：插入 sys_menu
{
path: "/b2bmall/b2bcoupon",
component: () => import("@/views/b2bmall/b2bcoupon.vue"),
meta: { title: "优惠券管理", isNavigationMenu: false }
}

// 新增/修改路由：不插入 sys_menu，只放静态路由
{
path: "/b2bmall/b2bcouponadd",
component: () => import("@/views/b2bmall/b2bcoupon-add-or-update.vue"),
meta: { title: "新增优惠券", isNavigationMenu: false, activeMenu: "/b2bmall/b2bcoupon" }
}

7.3 前端列表字段显示约束

MUST：列表页不能只显示 customerId、skuUnitId、categoryId 等 ID 字段，必须显示 customerName、skuUnitName、categoryName 等名称字段。
MUST：新增/修改弹窗中客户、商品、分类、价格组字段使用选择器组件，保存时提交 ID，展示时显示名称。
SHOULD：ID 字段可以作为辅助列或隐藏列，但不能作为主要业务展示字段。

<el-table-column prop="customerName" label="客户名称" min-width="180" show-overflow-tooltip />
<el-table-column prop="customerId" label="客户ID" width="120" show-overflow-tooltip />

8. 数据库表命名规范

8.1 表命名基本规则

MUST：表名全部小写，使用下划线分隔。
MUST：表名必须以业务模块前缀开头，例如 b2b_、pms_、oms_、wms_、fin_。
MUST：表名采用“模块前缀 + 业务对象 + 可选子对象”的形式。
SHOULD：表名不超过 64 个字符，避免过长。
PROHIBITED：禁止使用 t_、tb_、base_ 作为无意义前缀；base_payment 这种历史表可保留，新表不推荐。
PROHIBITED：禁止新表使用复数形式，例如 b2b_coupons。

8.2 表类型命名

表类型	后缀/命名	示例	说明
主表	业务对象名	b2b_coupon	优惠券主信息。
明细表	_item / _info / _detail	oms_order_bill_info	历史系统常用 info 可保留，新表推荐 item/detail 语义明确。
范围表	_scope	b2b_coupon_scope	客户、价格组、商品、分类等可见/适用范围。
日志表	_log	b2b_mall_submit_log	记录提交、操作、核销、缓存刷新等日志。
流水表	_flow	wms_goods_cost_flow	库存、成本、资金等流水。
关系表	_relation	pms_goods_unit_relation	多对多或单位换算关系。
配置表	_config / _setting	b2b_customer_mall_config / b2b_mall_setting	客户级配置与全局设置。
规则表	_rule	b2b_customer_delivery_rule	校验、定价、配送、截单规则。

8.3 好坏示例

推荐表名	不推荐表名	原因
b2b_customer_mall_config	customer_config / b2b_config	缺少业务对象或模块前缀不清晰。
b2b_mall_product_scope	b2b_product_customer	scope 更能表达投放/可见范围。
b2b_coupon_use_log	coupon_log / b2b_coupons_log	必须带模块前缀，且不使用复数。
pms_goods_sku_unit	sku_unit / product_unit	必须归入公司商品中心 pms_。
store_inv_stock	shop_inv_stock	门店库存前缀统一为 store_inv_。

9. 数据库字段命名与数据字典规范

9.1 字段命名基本规则

MUST：字段名全部小写下划线 snake_case。
MUST：字段名必须表达业务含义，不使用 a、b、type1、value1 这类无意义字段。
MUST：所有字段必须写 COMMENT，COMMENT 使用中文业务含义。
MUST：布尔字段使用 xxx_flag，不使用 is_xxx。
MUST：多状态字段使用具体业务前缀，例如 publish_status、audit_status、use_status，不使用泛化 status。
SHOULD：金额、数量、单价、比例字段必须用 DECIMAL，不使用 FLOAT、DOUBLE。
PROHIBITED：禁止把前端展示名称作为主业务关联字段，关联必须用 ID，名称只做冗余展示或 Resp 回填。

9.2 常用字段命名词典

语义	字段名	类型建议	说明
主键	id	BIGINT	全局或雪花ID。
编码	xxx_code	VARCHAR(64)	业务单号、规则编码、页面编码。
名称	xxx_name	VARCHAR(100)	业务名称。
客户ID	customer_id	BIGINT	B2B客户ID，通常关联 mall_shop.id。
客户账号ID	customer_account_id	BIGINT	客户子账号ID。
价格组ID	customer_grade_id	BIGINT	客户价格组。
销售商品最小粒度	sku_unit_id	BIGINT	销售侧使用，关联 pms_goods_sku_unit.id。
库存/采购SKU	product_sku_id	BIGINT	库存采购主口径，关联 pms_goods_sku.id。
单位ID	unit_id	BIGINT	库存采购单位，关联 pms_goods_unit.id。
分类ID	category_id	BIGINT	商品或商城分类。
仓库ID	workhouse_id	BIGINT	沿用现库拼写；新设计可标准化 warehouse_id，但兼容优先。
启用状态	enabled	TINYINT	1启用 0停用。
软删除	del_flag	TINYINT	0正常 1删除。
排序码	sort_code	INT	越小越靠前或按系统约定。
创建人	creator	BIGINT	用户ID。
创建时间	create_date	BIGINT	沿用升鲜宝时间戳。
修改人	updater	BIGINT	用户ID。
修改时间	update_date	BIGINT	沿用升鲜宝时间戳。
备注	remark	VARCHAR(255)	简短备注；长文本用 TEXT。

9.3 字段类型推荐

业务类型	推荐数据库类型	说明
ID	BIGINT	主键和外键统一 BIGINT。
编码/单号	VARCHAR(64) 或 VARCHAR(100)	业务单号建议 64；外部系统单号可 100。
名称	VARCHAR(100)	较长标题可 VARCHAR(200)。
手机号	VARCHAR(32)	不要用数字类型。
金额	DECIMAL(18,4) 或兼容 DECIMAL(12,3)	按升鲜宝小数位组件统一处理；不得 FLOAT/DOUBLE。
单价	DECIMAL(18,6) 或兼容 DECIMAL(12,3)	生鲜行业单价可能小数位较多。
数量	DECIMAL(18,4)	支持重量、件数、换算。
比例/折扣	DECIMAL(10,4)	折扣、毛利率、税率。
状态/类型	TINYINT / SMALLINT	必须配套枚举。
时间戳	BIGINT	沿用 create_date/update_date 口径。
日期	DATE	仅纯日期业务可用。
JSON配置	JSON	MySQL 8.0+ 可用，必须有结构说明。
长文本	TEXT	说明、富文本内容。

10. 主键、编码、状态、审计与软删除字段规范

10.1 标准公共字段顺序

id BIGINT NOT NULL COMMENT '主键ID',
-- 业务字段...
enabled TINYINT NOT NULL DEFAULT 1 COMMENT '启用状态 1启用 0停用',
del_flag TINYINT NOT NULL DEFAULT 0 COMMENT '删除标记 0正常 1删除',
sort_code INT NOT NULL DEFAULT 1 COMMENT '排序码',
creator BIGINT DEFAULT NULL COMMENT '创建人',
create_date BIGINT DEFAULT NULL COMMENT '创建时间',
updater BIGINT DEFAULT NULL COMMENT '修改人',
update_date BIGINT DEFAULT NULL COMMENT '修改时间',
remark VARCHAR(255) DEFAULT NULL COMMENT '备注',
PRIMARY KEY (id)

10.2 状态字段规则

字段	适用场景	枚举建议
enabled	通用启停。	1启用 0停用。
del_flag	软删除。	0正常 1删除。
publish_status	页面、Banner、优惠券、通知等发布状态。	0草稿 1已发布 2已下架。
audit_status	模板、单据、审核流程。	0待审核 1已通过 2已驳回。
use_status	优惠券、卡券、核销状态。	0未使用 1已锁定 2已使用 3已过期 4已作废 5已释放。
submit_status	提交OMS、接口重试。	0处理中 1成功 2失败。
pay_status	支付。	0未支付 1已支付 2支付失败 3已退款。

10.3 布尔字段规则

MUST：布尔业务字段统一使用 xxx_flag，例如 show_price_flag、show_stock_flag、allow_cancel_flag。
PROHIBITED：新字段禁止使用 is_show、is_delete、is_enable。
MUST：COMMENT 写明 1/0 含义，例如是否显示价格 1是 0否。

11. 商品、客户、订单、库存、门店和会员的核心口径约束

升鲜宝系统中很多问题来自“同一个业务词在不同模块含义不同”。本章定义核心口径，代码和数据库必须遵守。

对象	正确口径	禁止/风险点
B2B客户	customer_id 关联 mall_shop.id，表示供应链公司的 B2B 客户。	不要把客户和门店 shop 混淆；历史 shop_id 字段要在代码注释中说明。
门店	门店是用户自己的实体门店，门店会员销售走 POS/商城门店体系。	门店不是 B2B 客户。
会员	会员域使用 ums_，会员订单/POS订单属于门店对消费者销售。	会员订单不属于 B2B 客户订货。
销售商品最小粒度	B2B客户订单、价格、商城展示使用 sku_unit_id = pms_goods_sku_unit.id。	不能拿 sku_unit_id 作为公司库存/成本主核算口径。
采购库存商品	采购、库存、成本主口径为 product_sku_id + unit_id。	不能只用 sku_unit_id 做库存核算。
云商品库	platform_ 是平台公共模板库，不直接参与业务核算。	不能把 platform_ 当公司商品中心。
B2B订单	B2Bmall 只做提交前校验，正式订单由 OMS 生成。	b2bmall 不直接写 oms_order_bill / oms_order_bill_info。
库存显示	商城可展示库存规则，但库存扣减、成本核算仍在 WMS。	商城模块不得自行扣公司库存。

11.1 B2Bmall 边界强约束

MUST：B2Bmall 负责首页装修、Banner、金刚区、分类、商品展示、客户价格、购物车、常购、收藏、模板、优惠券、提交前校验。
MUST：提交订单时调用 OMS 提交服务，由 OMS 生成正式订单主从表。
MUST：优惠券仅在线支付订单可用；提交时锁券，支付成功核销，支付失败释放。
PROHIBITED：B2Bmall 不处理发货、退货、多退少补、对账、成本核算。

12. 索引、唯一键、外键与 SQL 查询规范

12.1 索引命名

索引类型	命名规则	示例
唯一键	uk_表名缩写_字段	uk_b2b_coupon_code
普通索引	idx_表名缩写_字段	idx_b2b_coupon_time
联合索引	idx_表名缩写_字段1_字段2	idx_b2b_product_scope_customer
业务幂等唯一键	uk_表名缩写_biz	uk_b2b_submit_no

12.2 索引设计规则

MUST：所有高频查询条件必须建立索引，例如 customer_id、sku_unit_id、customer_grade_id、enabled、del_flag。
MUST：唯一业务编码必须建立唯一键，例如 coupon_code、page_code、group_code。
MUST：范围表必须围绕主对象 + scope_type + 目标对象建索引。
SHOULD：列表查询默认带 del_flag、enabled 条件，避免扫描无效数据。
PROHIBITED：不建议在 MySQL 层创建强外键，避免影响历史数据迁移；外键关系必须在数据字典和 Service 校验中体现。
MUST：查询必须参数化，禁止拼接用户输入。
MUST：分页查询必须明确排序，禁止无序分页。
MUST：前端排序字段必须通过后端白名单映射。
SHOULD：多表查询只返回页面需要字段，不使用 select *。
SHOULD：名称回填优先在分页 SQL 中完成，例如 customer_name、sku_unit_name、category_name。
MUST：请求对象统一 Req 前缀，例如 ReqB2bMallProductPage。
MUST：返回对象统一 Resp 前缀，例如 RespB2bMallProduct。
MUST：Req 不直接复用 Entity，Resp 不直接返回 Entity。
MUST：Resp 必须包含前端展示名称字段，例如 customerName、skuUnitName、categoryName。
SHOULD：ReqSave 与 ReqPage 分开，避免分页参数污染保存接口。

12.3 SQL 查询规则

13. 请求、返回、分页、导入导出和日志规范

13.1 Req/Resp 约束

13.2 分页接口约束

POST /b2bmall/b2bcoupon/page
Request: ReqB2bCouponPage
Response: PageResult<RespB2bCoupon>

RespB2bCoupon 字段示例：
- id
- couponCode
- couponName
- thresholdAmount
- discountAmount
- publishStatus
- publishStatusName
- enabled
- creatorName
- createDate

13.3 导入导出约束

MUST：导出必须记录任务或导出日志，包含操作人、条件、条数、文件名、导出时间。
MUST：导出字段受权限控制，敏感字段必须脱敏。
SHOULD：大数据导出走异步任务，不在 Controller 同步阻塞。
SHOULD：导入必须提供失败明细，不允许只返回“导入失败”。

13.4 日志约束

日志类型	记录内容	示例表
操作日志	新增、修改、删除、启停、发布、下架、导出等后台操作。	b2b_mall_operate_log 或统一日志表
提交日志	客户购物车提交OMS的请求、响应、失败原因、订单号。	b2b_mall_submit_log
优惠券日志	锁券、释放、核销、使用订单、优惠金额。	b2b_coupon_use_log
缓存刷新日志	刷新模块、缓存Key、结果、耗时、操作人。	b2b_mall_cache_refresh_log

14. B2Bmall 模块示例规范

14.1 b2bmall 后端目录

b2bmall
├─ constant
├─ controller
│ ├─ admin
│ │ ├─ B2bCouponController.java
│ │ └─ B2bCustomerMallConfigController.java
│ └─ b2bmall
│ ├─ B2bMallHomeController.java
│ └─ B2bMallOrderSubmitController.java
├─ converter
├─ dao
├─ domain
├─ entity
├─ enums
├─ req
├─ resp
├─ service
│ ├─ impl
│ ├─ B2bCouponService.java
│ └─ B2bMallSubmitService.java
└─ xml

14.2 b2bmall 表清单约束

表	类型	用途
b2b_customer_mall_config	新增配置表	客户商城访问、下单、价格、库存、起订、截单等配置。
b2b_customer_delivery_rule	新增规则表	客户配送日、截单时间、配送时间段。
b2b_mall_setting	新增设置表	商城全局设置。
b2b_mall_page	新增页面表	首页/专题页版本和发布。
b2b_mall_page_component	新增组件表	Banner、金刚区、分类、商品楼层等组件配置。
b2b_mall_kingkong_group	新增配置表	金刚区分组。
b2b_mall_kingkong_item	新增配置表	金刚区入口。
b2b_mall_kingkong_scope	新增范围表	金刚区客户/价格组范围。
b2b_mall_category	新增展示表	商城展示分类。
b2b_mall_category_scope	新增范围表	商城分类可见范围。
b2b_mall_product_config	新增配置表	销售商品展示、上下架、默认价、起订量。
b2b_mall_product_scope	新增范围表	商品客户/价格组可见范围。
b2b_coupon	新增营销表	B2B满减优惠券。
b2b_customer_coupon	新增营销表	客户优惠券领取、锁定、使用状态。
b2b_coupon_use_log	新增日志表	优惠券核销与订单关联日志。
b2b_mall_submit_log	新增日志表	提交OMS日志。

14.3 b2bmall 复用表口径

复用表	B2B使用口径
mall_shop	B2B客户主档；新增配置抽离到 b2b_customer_mall_config。
mall_shop_account	客户账号、子账号、联系人。
cus_customer_price	客户特殊价，按 customer_id + sku_unit_id 查询。
cus_customer_grade_price	价格组商品价，按 customer_grade_id + sku_unit_id 查询。
mall_banner / mall_banner_info / mall_banner_shop	Banner配置与关联商品；多范围能力由 b2b_mall_banner_scope 补强。
shop_notice / shop_notice_type	客户通知与通知类型；范围由 b2b_mall_notice_scope 补强。
oms_shop_cart	B2B购物车底表；代码可命名为 OmsOrderCart，但不改表。
cus_often_buy	常购商品。
cus_goods_favorite	商品收藏。
cus_order_template / cus_order_template_info	客户订货模板。
base_payment	支付方式，优惠券仅在线支付可用。

15. 建表模板、代码模板与检查清单

15.1 建表模板

CREATE TABLE b2b_demo_config (
id BIGINT NOT NULL COMMENT '主键ID',
demo_code VARCHAR(64) NOT NULL COMMENT '配置编码',
demo_name VARCHAR(100) NOT NULL COMMENT '配置名称',
customer_id BIGINT DEFAULT NULL COMMENT 'B2B客户ID',
customer_grade_id BIGINT DEFAULT NULL COMMENT '客户价格组ID',
config_json JSON DEFAULT NULL COMMENT '配置JSON',
enabled TINYINT NOT NULL DEFAULT 1 COMMENT '启用状态 1启用 0停用',
del_flag TINYINT NOT NULL DEFAULT 0 COMMENT '删除标记 0正常 1删除',
sort_code INT NOT NULL DEFAULT 1 COMMENT '排序码',
creator BIGINT DEFAULT NULL COMMENT '创建人',
create_date BIGINT DEFAULT NULL COMMENT '创建时间',
updater BIGINT DEFAULT NULL COMMENT '修改人',
update_date BIGINT DEFAULT NULL COMMENT '修改时间',
remark VARCHAR(255) DEFAULT NULL COMMENT '备注',
PRIMARY KEY (id),
UNIQUE KEY uk_b2b_demo_config_code (demo_code),
KEY idx_b2b_demo_config_customer (customer_id),
KEY idx_b2b_demo_config_enabled (enabled, del_flag)
) COMMENT='B2B示例配置表';

15.2 Entity 模板

@Data
@TableName("b2b_coupon")
public class B2bCouponEntity {
    @TableId(type = IdType.ASSIGN_ID)
    private Long id;
    private String couponCode;
    private String couponName;
    private BigDecimal thresholdAmount;
    private BigDecimal discountAmount;
    private Integer publishStatus;
    private Integer enabled;
    private Integer delFlag;
    private Integer sortCode;
    private Long creator;
    private Long createDate;
    private Long updater;
    private Long updateDate;
    private String remark;
}

15.3 开发检查清单

检查项	必须达标
目录结构	业务代码是否放在业务模块目录下；b2bmall 是否采用截图确认结构。
Req/Resp	是否使用 Req/Resp 前缀；是否避免直接返回 Entity。
字段名称	是否使用 xxx_flag；是否避免泛化 status；字段是否有 COMMENT。
展示名称	分页 Resp 是否回填 customerName、skuUnitName、categoryName 等名称字段。
接口边界	B2Bmall 是否只调用 OMS 提交服务，不直接写订单主从表。
SQL安全	是否禁止 ${} 拼用户输入；排序是否白名单。
权限菜单	sys_menu.url 是否等于前端 route.path。
导出日志	导出是否有记录；敏感字段是否受权限控制。
枚举	状态字段是否有枚举，不使用魔法数字。
缓存	首页、价格、客户可见范围变更是否刷新缓存。

16. Spring Boot 4.0 升级注意事项

16.1 依赖与兼容

MUST：升级前先确认父工程 Spring Boot、Spring Framework、MyBatis-Plus、Spring Security、Redis、Jackson、Validation、OpenAPI 依赖兼容。
MUST：所有 javax.validation、javax.servlet、javax.persistence 等导入迁移为 jakarta.*。
MUST：统一 Jackson 配置，测试 BigDecimal、Long ID、时间戳、枚举序列化兼容。
SHOULD：先在新模块或旁路分支验证，不直接全量替换生产分支。
MUST：生成代码前先读取数据库表 COMMENT 和字段 COMMENT，生成中文 label。
MUST：生成前端列表时，ID字段必须配套名称字段；名称由后端 Resp 回填。
MUST：生成 b2bmall 时只生成业务子目录，不生成独立项目。
SHOULD：生成代码后执行格式化、编译、单元测试和接口冒烟测试。

16.2 代码生成注意事项

16.3 官方参考

资料	说明
Spring Boot System Requirements	Spring Boot 4.0.x 的 Java、Spring Framework、Maven、Gradle 版本要求。
Spring Boot 4.0 Release Highlights	Jakarta EE 11、JSpecify、Jackson 3、Spring Core Retry 等变化。
Spring Boot 4.0 Migration Guide	Java 17+、Jakarta EE 11、Servlet 6.1、Spring Framework 7.x 等迁移要求。

17. 附录：命名词典与禁止项清单

17.1 常用业务词典

中文	推荐英文	说明
客户	customer	B2B客户。
客户账号	customer_account	B2B客户子账号。
价格组	customer_grade	客户等级/价格组。
商品	goods / product	现有 pms_goods 沿用 goods；商城配置可用 product。
销售规格单位	sku_unit	销售侧最小粒度。
库存SKU	product_sku	库存采购主SKU。
单位	unit	计量单位。
分类	category	商品分类或商城展示分类。
可见范围	scope	客户/价格组/全部客户范围。
优惠券	coupon	B2B满减券。
金刚区	kingkong	首页快捷入口。
通知	notice	客户通知公告。
发布	publish	页面/Banner/通知/优惠券发布。
截单	deadline	每日截单时间。
配送	delivery	配送日期、配送规则。

17.2 禁止项清单

禁止项	正确做法
新字段使用 is_xxx	使用 xxx_flag。
新字段使用 status 表达所有状态	使用 publish_status、audit_status、use_status 等具体状态。
前端只显示 customerId	后端 Resp 回填 customerName，前端主显示客户名称。
B2Bmall 直接写 OMS 订单表	调用 OMS 提交服务。
公司库存按 sku_unit_id 核算	库存成本使用 product_sku_id + unit_id。
把 platform_ 云商品库直接参与核算	先同步到 pms_ 商品中心。
生成独立 b2bmall 项目	生成主项目内 b2bmall 子目录。
ServiceImpl 放独立 serviceImpl 目录	按截图结构放 b2bmall/service/impl。
菜单 SQL 插入 add/edit 页面	只插入列表页，add/edit 为静态路由。
SQL 使用 ${orderBy}	使用排序白名单映射。

17.3 推荐落地步骤

先确定模块前缀、业务边界和数据库表清单。
按本文命名规范输出 DDL，并补全 COMMENT、索引和公共字段。
生成 Entity、Dao、XML、Service、ServiceImpl、Controller、Req、Resp。
生成前端一个列表页 + 一个新增/修改弹窗页。
生成 sys_menu 初始化 SQL，确保 URL 与前端列表路由一致。
补充 Resp 名称回填，避免前端只展示 ID。
补充业务方法、状态机、幂等、缓存刷新和操作日志。
执行编译、接口冒烟、菜单访问、权限按钮、导出日志和数据权限测试。

此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。原文来自 — 版权归原作者所有。

推荐订阅源

博客园 - 升鲜宝生鲜供应链系统