# 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 统一响应格式

```json
// 成功
{ "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 一致）