04-技术规范

零、技术栈总览

分层模块	技术	版本要求	说明
前端基础框架	React	18.x	构建前端应用
前端 UI 组件	Ant Design	5.x	页面组件与交互控件
前端状态管理	Redux Toolkit	最新稳定版	管理全局状态
前端路由管理	React Router	v6	页面路由与导航
前端工程化构建	Vite	最新稳定版	前端开发与打包构建
前端接口通信	Axios	最新稳定版	调用后端 API
后端基础框架	Spring Boot	3.x	构建后端服务
后端数据访问	MyBatis-Plus	最新稳定版	数据库访问与 ORM 增强
工作流引擎	Activiti	6.x	审批流、流程流转
缓存服务	Redis	最新稳定版	缓存、会话、分布式能力
报表打印	JXLS	2.8.1	基于 Excel 模板生成报表
Excel 导入导出	EasyExcel	4.0.3	Excel 数据导入导出
关系型数据库	MySQL	8.x	核心业务数据存储
数据库 schema 迁移	Flyway (flyway-core + flyway-mysql)	10.x / 最新稳定版	sql/migrations/V_n__*.sql 顺序 apply；Spring Boot 启动时自动应用
接口风格	RESTful API	统一规范	前后端接口设计规范
权限认证	Spring Security / JWT	最新稳定版	登录认证、权限控制
API 文档	OpenAPI / Swagger	最新稳定版	接口文档与调试
项目构建管理	Maven	3.9.x	Java 项目依赖与构建
JDK 运行环境	Java	17 / 21	Spring Boot 3 推荐版本
部署容器	Docker	最新稳定版	容器化部署
Web 服务器 / 反向代理	Nginx	最新稳定版	前端托管、反向代理、负载分发
日志管理	Logback	默认集成 / 最新稳定版	应用日志输出
对象映射工具	MapStruct	最新稳定版	DTO / VO / Entity 转换
工具类库	Hutool / Apache Commons	最新稳定版	常用工具方法支持

本表由 scope-lock 锁定。后续所有规范基于此表推导。

一、后端规范

1.1 分层结构

基于 Spring Boot 3.x + MyBatis-Plus 的标准三层架构：

层	包路径	职责
Controller	module/<mod>/controller/	接收 HTTP 请求，校验入参，调 Service，返回统一响应体
Service	module/<mod>/service/	核心业务逻辑，事务边界，编排 Mapper 和跨域调用
Mapper	module/<mod>/mapper/	MyBatis-Plus 数据访问，简单 CRUD 继承 BaseMapper，复杂 SQL 写 XML
Entity	module/<mod>/entity/	与数据库表一一对应，不含业务方法
DTO / VO	module/<mod>/dto/ module/<mod>/vo/	解耦接口层与实体层；DTO 为入参，VO 为出参
Config	config/	Spring Bean 配置、Security 规则、Swagger、MyBatis 拦截器等全局配置
Common	common/	统一响应体、全局异常处理器、枚举、常量、工具类

1.2 命名约定

• 根包名：com.example.erp
• 类名：UpperCamelCase；示例：UserController、UserServiceImpl
• 方法名：lowerCamelCase；示例：createUser()、getUserById()
• 常量：UPPER_SNAKE_CASE，统一放 common/constants/；示例：MAX_LOGIN_RETRY
• 数据库表：lower_snake_case；示例：sys_user、usr_role

1.3 统一响应格式

// 成功
{ "code": 0, "message": "success", "data": { ... } }

// 失败
{ "code": 10001, "message": "用户名已存在", "data": null }

错误码段位：

• 0：成功
• 10xxx：通用业务错误（参数校验、权限等）
• 20xxx：用户管理模块（USR）
• 99xxx：系统内部错误

1.4 异常处理

• 使用 @RestControllerAdvice 全局捕获异常，统一返回规范响应体
• 业务异常继承 BizException(code, message)，在 Service 层抛出
• RuntimeException / 未知异常统一映射为 code=99000，返回用户友好文案
• 接口响应禁止回显后端异常堆栈；堆栈信息只写 Logback 日志，不出现在 HTTP 响应体

1.5 事务

• 事务边界在 Service 层，使用 @Transactional
• 只读查询加 @Transactional(readOnly = true)
• 禁止在 Controller 层加事务注解
• 跨模块数据操作通过 Service 接口调用，不直接跨 Mapper 调用其他模块

1.6 认证

基于 Spring Security + JWT：

• Token 生命周期：Access Token 有效期 24 小时，Refresh Token 有效期 7 天
• 刷新机制：前端检测到 401 时，用 Refresh Token 换新 Access Token；Refresh Token 过期则强制重新登录
• 密钥管理：JWT 签名密钥从 .env.local 注入，生产环境通过 Docker 环境变量覆盖，禁止硬编码

二、前端规范

2.1 目录约定

目录	职责
api/	Axios 实例封装 + 各模块接口定义；前端禁止直接写 SQL 或操作 DB，所有数据访问经此层
components/	通用业务组件（PermButton、PageContainer 等）
pages/	页面组件，按模块子目录组织（pages/usr/）
store/slices/	Redux Toolkit Slice，每模块一个文件
hooks/	自定义 React Hooks（useTable、usePermission 等）
utils/	纯函数工具（日期格式化、金额格式化等）

2.2 状态管理

• 全局状态（认证信息、用户权限）：Redux Toolkit Store
• 模块级 UI 状态（列表筛选条件、表单开关）：组件本地 useState / useReducer
• 服务端数据：通过 RTK Query 或自定义 Hook 管理远程数据缓存与加载状态，不建议直接放 Redux

2.3 请求封装

api/request.ts 封装 Axios 实例：

• 认证注入：请求拦截器从内存/Cookie 读取 Access Token，注入 Authorization: Bearer <token>
• 超时：默认 10s
• 错误重试：网络超时自动重试 1 次，业务错误不重试
• 401 处理：响应拦截器捕获 401，触发 Refresh Token 流程；再次失败则清除登录态并跳转登录页

2.4 错误处理

层级	处理方式
网络错误 / 超时	message.error("网络异常，请检查连接")
业务错误（HTTP 200 + code ≠ 0）	读取 message 字段，message.error(接口文案)
页面级错误（路由 / 权限）	React Router ErrorBoundary，展示 Result 组件

2.5 样式与主题

• CSS 变量命名格式：--color-<scope>-<role>-<state>（如 --color-form-bg-edit、--color-table-row-bg-hover）
• 文件位置：src/styles/tokens.css，由 skeleton-gen 生成骨架，色值在 docs/06 § 四锁定后填入
• 组件样式中只用 var(--color-xxx)，禁止硬编码 hex / rgba
• 与 Ant Design 对接：在 App.tsx 的 ConfigProvider.theme.token 中将 Ant Design 主题 token 映射到 CSS 变量（如 colorPrimary: 'var(--color-primary)'）
• 具体 token 表见 docs/06 § 四

三、共同约定

3.1 Git 提交

<type>(<scope>): <subject> REQ-XXX-NNN

示例：feat(usr): 增加用户创建接口 REQ-USR-001

type 取值：feat / fix / refactor / test / docs / chore

3.2 分页查询

• 入参：pageNum（从 1 起）、pageSize（默认 20，最大 100）
• 出参：{ list: [], total: N, pageNum: N, pageSize: N }
• 后端使用 MyBatis-Plus Page<T> 对象；前端使用 Ant Design Table 的 pagination 属性

3.3 日期与金额

• 后端日期类型：LocalDateTime，JSON 序列化为 yyyy-MM-dd HH:mm:ss
• 后端金额类型：BigDecimal，精度 2 位小数，不在接口层做四舍五入
• 前端日期展示：使用 dayjs 格式化
• 前端金额展示：保留 2 位小数并加千分位，使用封装的 formatAmount(val) 工具函数

3.4 数据访问规约

• SELECT 字段显式列举，禁止 SELECT *
• 循环中禁止执行 DB 查询（N+1 反模式），改用批量查 / IN 子句 / JOIN
• Mapper XML 里字段与表名使用 MyBatis-Plus 的常量引用，避免拼字符串

3.5 配置与安全

• DB 连接 / 端口 / 密钥 / 第三方 URL 一律放 application.yml（占位符）+ .env.local（真实值），代码里禁止硬编码
• 前端：localStorage 不存储敏感信息（token / 身份 / 个人数据），推荐 HttpOnly Cookie 或内存 + Refresh Token 模式
• 接口响应禁止回显后端异常堆栈（与 § 1.4 一致）