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 + MyBatis-Plus 惯例分四层，每层职责单一：

层	职责
controller	HTTP 入口；参数校验（@Valid）；调用 service；返回统一响应；不写业务逻辑
service + service/impl	业务编排；事务边界；调用一个或多个 mapper；DTO ↔ Entity 转换走 converter
mapper + resources/mapper/*.xml	单表 CRUD 走 MyBatis-Plus；复杂 SQL 写 XML；不写业务逻辑
entity / dto / vo / converter	数据传输层；converter 用 MapStruct 自动生成实现

1.2 命名约定

• Java 包：全小写。根包：com.xly.erp。业务模块：module.<module_code_lower>（与 docs/01 模块代码对齐）。
• 类名：大驼峰；后缀清晰标识层（UserController / UserServiceImpl / UserMapper / UserEntity / CreateUserReq / UserVo / UserConverter）。
• 方法 / 字段：小驼峰（createUser / userName）。
• 常量：全大写下划线（MAX_LOGIN_ATTEMPTS）。
• 数据库表名：小写下划线（sys_user）；字段名同样小写下划线（created_at）。

示例：

package com.xly.erp.module.usr.controller;

@RestController
@RequestMapping("/api/v1/users")
public class UserController {
    public Result<UserVo> createUser(@RequestBody @Valid CreateUserReq req) { ... }
}

1.3 统一响应格式

所有 HTTP 接口返回 Result<T> / PageResult<T>：

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

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

错误码段位：

• 0：成功
• 10xxx：参数 / 校验类错误
• 20xxx：业务规则错误
• 30xxx：权限类错误
• 40xxx：资源类错误（找不到、冲突）
• 50xxx：服务器内部错误
• 60xxx：第三方依赖错误

1.4 异常处理

• 全局异常处理器 GlobalExceptionHandler（@RestControllerAdvice）统一捕获并转 Result.fail(...)。
• 业务异常用 BizException(int code, String message)，service 层抛出，全局处理器捕获后转响应。
• 禁止在 controller / service 里 catch (Exception e) { e.printStackTrace(); } 后吞掉。
• 接口响应禁止回显后端异常堆栈：仅返回 code + 用户友好 message；堆栈写日志（含 traceId）。

1.5 事务

• 事务边界统一在 service 实现层，使用 @Transactional(rollbackFor = Exception.class)。
• controller / mapper 层禁止写 @Transactional。
• 跨服务（跨进程）调用禁止使用本地事务跨边界；改用最终一致性（消息队列 / 补偿任务），本项目当前无跨服务场景。

1.6 认证

• 使用 Spring Security + JWT。
• Access Token：HS256，TTL 2 小时；签发后写 Redis（key=auth:token:<userId>:<jti>，value=用户摘要）。
• Refresh Token：TTL 7 天，单独签发；刷新时旋转 token 并使旧 token 失效。
• 密钥（HMAC secret）放 .env.local 的 JWT_SECRET，禁止写入 application.yml 或代码。
• 登出 / 改密 / 停用：把对应 jti 加入 Redis 黑名单直至原 TTL 过期。

二、前端规范

2.1 目录约定

按 Vite + React 18 + Redux Toolkit 惯例分层（详见 docs/09 § 三）：

目录	职责
src/api/	Axios 实例 + 各模块接口调用函数；所有数据访问唯一入口
src/store/	Redux Toolkit slices；全局态（认证 / 用户信息 / 字典）
src/router/	React Router 配置 + 路由守卫
src/pages/<module>/	业务页面（按模块分目录）
src/components/	跨页面通用组件（含 Permission 等）
src/layouts/	框架布局
src/hooks/	自定义 hook
src/utils/	工具方法（日期 / 金额 / 校验等）
src/styles/	全局样式 + Design Tokens
src/types/	全局 TypeScript 类型

前端禁止直接写 SQL / 操作 DB；所有数据访问走 api/ 层封装的 HTTP 调用。

2.2 状态管理

• 全局态（用户身份 / 权限 / 全局字典 / 主题）：Redux Toolkit。
• 页面级态（表单值 / 列表参数）：组件本地 useState / useReducer。
• 服务端数据（列表 / 详情）：直接调 api/ 函数，配合 useEffect + 本地 state；不放全局 store，避免缓存一致性问题。
• 跨页面共享但非全局的态用 React Context（如 Modal Provider）。

2.3 请求封装

src/api/client.ts 统一 Axios 实例：

• baseURL 从 import.meta.env.VITE_API_BASE_URL 读取。
• 请求拦截：自动注入 Authorization: Bearer <accessToken>；附带 X-Request-Id 用于链路追踪。
• 响应拦截：
  • HTTP 200 + code === 0 → 返回 data。
  • HTTP 200 + code !== 0 → 抛业务错误（含 message 和 code）。
  • HTTP 401 → 触发 refresh token；refresh 失败 → 清登录态 + 跳登录页。
  • HTTP 5xx → 抛网络错误。
• 超时：默认 10s；上传 / 导出接口 60s。
• 不做自动重试（重试由业务调用处显式控制）。

2.4 错误处理

错误类型	处理方式
网络错误（断网 / 5xx）	顶层 message.error('网络异常，请重试')，业务调用处可自定义重试按钮
业务错误（code !== 0）	默认 message.error(err.message)，业务调用处可拦截做特殊提示
表单校验失败	字段下方红字（Ant Design Form 自带）
路由级未授权	RequireAuth 守卫重定向到 /login
页面级崩溃	顶层 ErrorBoundary 显示 Result status="500" + 重新加载按钮

2.5 样式与主题

• CSS 变量命名：--color-<scope>-<role>-<state>
  • scope：form / table-row / tag / btn 等；通用全局色无 scope（如 --color-primary）
  • role：bg / fg / border
  • state：edit / readonly / hover / selected / disabled；常态省略
• 文件位置：frontend/src/styles/tokens.css（由 skeleton-gen 生成骨架，色值由 docs/06 § 二锁定）。
• 组件样式中只用 var(--color-xxx)，禁止硬编码 hex / rgba。
• 与 Ant Design 主题对接：App.tsx 顶层包 <ConfigProvider theme={{ token: { colorPrimary: 'var(--color-primary)', ... } }}>；Ant Design 5 接受 token 对象映射，确保组件库色值与 tokens.css 单一来源。
• 具体 token 表见 docs/06 § 二。

三、共同约定

3.1 Git 提交

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

• type：见 CLAUDE.md § 🗂️ Git 提交规范。
• scope：模块代码小写（usr / pur / sal）或 infra / docs。
• subject：祈使句，中文，<= 50 字。
• REQ tag：业务类提交（feat / fix / test）必带。

示例：feat(usr): 实现用户登录接口 REQ-USR-001

3.2 分页查询

• 后端：请求入参 PageReq { page=1, size=20 }（兜底默认值；size 上限 100）；返回 PageResult<T> { records: List<T>, total: long, page: int, size: int }。
• 前端：使用 Ant Design Table + Pagination；统一组件包装在 components/PagedTable，对接 PageResult。
• 排序参数走 sortField / sortOrder，白名单字段，禁止任意字段排序。

3.3 日期与金额

• 后端类型：日期用 LocalDateTime / LocalDate；金额用 BigDecimal（精度 2 位）。
• 后端 → 前端：日期统一序列化为 YYYY-MM-DD HH:mm:ss 字符串；金额序列化为 string（避免精度丢失）。
• 前端展示：日期使用 dayjs 格式化（YYYY-MM-DD HH:mm）；金额使用 utils/money.ts 格式化为千分位。
• 金额精度：内部全部 BigDecimal，4 舍 6 入 5 成双（HALF_EVEN）；展示截断到 2 位。

3.4 数据访问规约

• SELECT 字段显式列举：禁止 SELECT *；MyBatis-Plus 用 select(User::getId, User::getUsername) 或 XML 显式列名。
• 禁止 N+1 反模式：循环中不得执行 DB 查询；改用 selectBatchIds / IN 子句 / JOIN。
• Mapper XML：表名 / 字段名用常量或引用，禁止字符串拼接 SQL（防注入）。
• 复杂查询走 XML，简单 CRUD 走 LambdaQueryWrapper。
• 写操作：单表批量写用 saveBatch / updateBatchById；超大批量（>1000）分批 commit。

3.5 配置与安全

• 后端配置：DB 连接 / 端口 / 密钥 / 第三方 URL 等一律放 application.yml + .env.local。代码中禁止硬编码（用 @Value / @ConfigurationProperties 注入）。
• 多环境：application-dev.yml / application-test.yml / application-prod.yml，通过 SPRING_PROFILES_ACTIVE 切换。
• 前端安全：
  • localStorage 禁止存敏感信息（token / 身份 / 个人数据）。
  • Token 推荐内存 + HttpOnly Cookie（refresh）或纯内存（access），Redux store 持有 access；刷新页面通过 refresh cookie 重新换取。
  • 接口响应禁止回显后端异常堆栈（与 § 1.4 一致）。
• 密钥来源：所有密钥（JWT / DB 密码 / 第三方 API key）从 .env.local 加载；.env.local 在 .gitignore，永不入库。