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

```json
{
  "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 一致）。