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 分层结构

层	职责
controller	REST 入口，参数绑定 / 校验 / 调用 service，不写业务逻辑
service	业务编排，事务边界，跨模块调用通过 service 接口完成
mapper	MyBatis-Plus 接口 + XML，仅做 CRUD，不写业务规则
entity	与表 1:1 的 PO，仅作 ORM 映射
dto / vo	入参 DTO（Controller ↔ Service） / 出参 VO（Service → 前端）
common	统一响应 / 全局异常 / 工具方法
config	Spring 配置类（Security / Redis / Swagger / Web）

1.2 命名约定

• 包名：全小写，根包 com.xly.erp，业务模块下按 module.<mod>.<layer> 划分。
• 类名：大驼峰，如 UserController / UserServiceImpl / UserMapper。
• 方法名：小驼峰动宾式，如 createUser / pageUsers。
• 常量：全大写下划线，如 MAX_PAGE_SIZE / JWT_TOKEN_HEADER。
• 示例：
  • <root>.module.usr.controller.UserController#createUser
  • <root>.module.mod.service.ModuleService#pageModules

1.3 统一响应格式

{
  "code": "0",
  "message": "ok",
  "data": { /* 业务数据 */ }
}

• 成功 code=0；失败按段位划分：
  • 1xxx 通用错误（参数 / 鉴权 / 权限）
  • 2xxx USR 模块业务错误
  • 3xxx MOD 模块业务错误
  • 后续模块按段位顺延，由 downstream-gen 在 docs/05 中登记。

1.4 异常处理

• 使用 @RestControllerAdvice 注册全局异常处理器，统一捕获 BizException / BindException / Exception。
• 业务异常抛 BizException(code, message)；参数校验由 Spring @Valid 触发。
• 接口响应禁止回显后端异常堆栈——堆栈只入 Logback 日志，响应只返回友好错误码 + 文案。

1.5 事务

• 事务边界统一在 service 层，使用 @Transactional(rollbackFor = Exception.class)。
• 禁止跨服务远程调用包在事务内；本项目暂无远程依赖，跨模块调用通过本地 service 接口同步完成。
• 长耗时操作（导入导出、批处理）拆分为多个短事务，必要时入异步任务。

1.6 认证

• 基于 Spring Security + JWT 无状态认证：
  • 登录返回 accessToken（HS256，过期 2 小时）+ refreshToken（过期 7 天）。
  • accessToken 通过 Authorization: Bearer <token> 请求头携带。
  • refreshToken 仅用于换新 accessToken，存于 Redis 用于黑名单 / 撤销。
• JWT 密钥放 .env.local，启动期注入，禁止硬编码。

二、前端规范

2.1 目录约定

目录	职责
src/api/	Axios 封装 + 模块接口；前端禁止直接写 SQL / 操作 DB，所有数据访问走 api/ 层
src/components/	通用组件（UI 组合、无业务）
src/pages/	业务页面（按模块代码 usr / mod 分子目录）
src/store/	Redux Toolkit slices
src/hooks/	通用 hooks
src/utils/	纯函数工具（日期 / 金额 / 校验）
src/router/	React Router 配置
src/styles/	全局样式 + Design Token

2.2 状态管理

• 使用 Redux Toolkit + RTK Query（按需）管理服务端数据缓存。
• 全局状态：登录用户信息、菜单树、权限码集合、全局加载态。
• 局部 / 短生命周期状态：放组件 useState / useReducer，不进 store。
• 服务端数据：列表 / 详情等"远程状态"放 store/api（RTK Query slice）或 React Query 替代。

2.3 请求封装

• src/api/request.ts 单例 Axios，注册：
  • 请求拦截器：注入 Authorization 头；请求超时默认 15 s。
  • 响应拦截器：剥离 data 字段；遇 401 触发 token 刷新或跳登录；业务错误码统一抛出。
• 不在业务代码里直接 import axios，统一走 request.get/post。

2.4 错误处理

• 网络错误（无 response）：message.error("网络异常，请检查连接")，不重试。
• 业务错误（response.code !== 0）：message.error(response.message)；权限类错误（401 / 403）跳登录或 403 页。
• 页面级错误（路由级 ErrorBoundary）：渲染 Result 组件，提供"返回首页"链接。

2.5 样式与主题

• CSS 变量命名：--color-<scope>-<role>-<state>
  • scope ∈ {form, table-row, button, panel, ...}
  • role ∈ {bg, fg, border}
  • state ∈ {edit, readonly, hover, selected, disabled}
• 文件位置：src/styles/tokens.css，由 skeleton-gen 生成空骨架，色值由 docs/06 § 四锁定后填入。
• 组件样式中只用 var(--color-xxx)，禁止硬编码 hex / rgba。
• 与 Ant Design ConfigProvider 对接：在 App 根读取 tokens.css 变量映射到 theme.token（如 colorPrimary 取自 getComputedStyle(document.documentElement).getPropertyValue('--color-primary')）。
• 具体 token 表见 docs/06 § 四。

三、共同约定

3.1 Git 提交

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

3.2 分页查询

• 后端入参：PageRequest { pageNum: int (≥1), pageSize: int (1-100), keyword?: string, sort?: string }
• 后端出参：PageResult<T> { total: long, list: List<T>, pageNum, pageSize }
• 前端：使用 Ant Design Table 受控分页，current / pageSize 与后端 pageNum / pageSize 对齐。

3.3 日期与金额

• 后端日期：LocalDateTime（数据库 DATETIME），统一序列化为 ISO 8601（yyyy-MM-dd'T'HH:mm:ss）。
• 后端金额：BigDecimal，数据库 DECIMAL(18,4)，业务展示精度由前端统一 utils/money.ts 处理。
• 前端展示：日期使用 dayjs 格式化；金额使用 toFixed(2) + 千分位分隔。

3.4 数据访问规约

• SELECT 字段显式列举，禁止 SELECT *。
• 循环中不得执行 DB 查询（N+1 反模式），改用批量查 / IN 子句 / JOIN。
• Mapper XML 字段名 / 表名使用 <sql id="Base_Column_List"> 复用，避免散落字符串拼接。
• 使用 MyBatis-Plus 的 LambdaQueryWrapper 时，字段引用通过方法引用（如 User::getId），不允许直接传字符串字段名。

3.5 配置与安全

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