朱子纯 / test6

04-技术规范.md 11.3 KB

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 锁定。后续所有规范基于此表推导。

命令清单

由 scope-lock(A1) 锁定。Coding 阶段 coding.mjs 的 tdd / test-gate 按 stack 读取以下命令。无 表示该栈不提供此类命令。

后端（Spring Boot 3 / Maven / Java 17）

类别 命令
build mvn -q -B -DskipTests package
lint mvn -q -B checkstyle:check
unit mvn -q -B test
e2e 无

前端（React / Vite / npm）

类别 命令
build npm run build
lint npm run lint
unit npm run test:unit
e2e npm run test:e2e

一、后端规范

技术栈：Spring Boot 3 + MyBatis-Plus + MySQL 8 + Flyway + Spring Security/JWT，根包 com.xly.erp，构建工具 Maven。

1.1 规则

  • 所有后端代码位于仓库根 backend/ 子项目；根包统一为 com.xly.erp，禁止散落到其他包名。
  • 业务代码按模块组织在 com.xly.erp.modules.<模块小写代码> 下（如 modules.usr），通用能力在 com.xly.erp.common 下，不得跨模块直接引用对方的 mapper/entity。
  • 每个对外接口必须先在 docs/05-API接口契约.md 定义，再编码实现；Controller 只做参数校验 + 调 Service，不写业务逻辑。
  • 业务 schema 变更一律走 sql/migrations/V_n__*.sql（Flyway），禁止在代码或会话里手跑业务 DDL。
  • 密码等敏感值只从 config-vars.yaml / 环境读取，禁止硬编码进源码或日志。

1.2 分层结构

后端为仓库根下的 backend/ Maven 子项目，目录布局：

backend/
├── pom.xml                              # 声明 spring-boot / mybatis-plus / flyway-core / flyway-mysql / spring-security / jjwt / mapstruct / hutool 等依赖
├── src/main/java/com/xly/erp/
│   ├── ErpApplication.java              # Spring Boot 启动类
│   ├── common/                          # 跨模块通用能力（不属于任何业务模块）
│   │   ├── response/                    # Result<T> 统一响应体、ResultCode 枚举、PageResult<T>
│   │   ├── exception/                   # BusinessException、GlobalExceptionHandler（@RestControllerAdvice）
│   │   ├── config/                      # MybatisPlusConfig / SecurityConfig / SwaggerConfig / CorsConfig
│   │   ├── security/                    # JWT 工具、JwtAuthenticationFilter、UserDetails 适配
│   │   └── base/                        # BaseEntity（id/创建时间/制单人/逻辑删除等公共字段）
│   └── modules/
│       └── usr/                         # USR 用户管理（每个业务模块一个子包）
│           ├── controller/              # UsrUserController —— 仅校验 + 委派
│           ├── service/                 # UsrUserService 接口
│           │   └── impl/                # UsrUserServiceImpl 业务实现
│           ├── mapper/                  # UsrUserMapper（继承 MyBatis-Plus BaseMapper）
│           ├── entity/                  # UsrUser 实体（映射数据库表）
│           ├── dto/                     # 入参对象（CreateUserDTO / UpdateUserDTO / UserQueryDTO / LoginDTO）
│           └── vo/                      # 出参对象（UserVO / LoginVO）
├── src/main/resources/
│   ├── application.yml                  # 端口、数据源、MyBatis-Plus、Flyway locations、JWT 等配置
│   └── mapper/                          # 复杂 SQL 的 MyBatis XML（简单 CRUD 用注解/MP 内置）
└── src/test/java/com/xly/erp/           # 单元测试 + 集成测试，包结构镜像主代码
  • 跨模块判定：路径 backend/src/main/java/com/xly/erp/modules/<mod>/** 归属模块 <mod>；common/** 为公共区，改动需在《模块完成报告》留痕。
  • Flyway：迁移脚本在仓库根 sql/migrations/，application.yml 配置 spring.flyway.locations=filesystem:../sql/migrations（相对 backend/ 工作目录），Spring Boot 启动时自动 apply。

1.3 命名约定

  • 类：大驼峰，模块前缀 + 业务名 + 层后缀，如 UsrUserController / UsrUserServiceImpl / UsrUserMapper。
  • 方法：小驼峰动词起头，如 createUser / updateUser / pageUsers / login。
  • 表名：snake_case 单数或业务习惯命名（详见 docs/03）；实体类名大驼峰对应表名。
  • 常量：全大写下划线；DTO/VO 字段小驼峰。
  • REST 路径：/api/<模块>/<资源>，小写中划线，如 /api/usr/users。

1.4 统一响应格式

所有接口返回统一包装 Result<T>：

{ "code": 0, "message": "success", "data": { } }
  • code：0 成功；非 0 为业务/系统错误码（由 ResultCode 枚举集中定义）。
  • 分页返回 Result<PageResult<T>>，PageResult 含 records / total / pageNum / pageSize。
  • 失败响应不抛栈到前端，message 给可读提示。

1.5 异常处理

  • 业务错误统一抛 BusinessException(ResultCode, msg)，由 GlobalExceptionHandler 捕获转 Result。
  • 参数校验用 jakarta.validation（@Valid + 注解），校验失败由全局处理器转统一错误。
  • 系统异常（未捕获）记录 ERROR 日志并返回通用错误码，不泄露内部细节。

1.6 事务

  • 写操作（增/改/删，含多表）在 Service 实现方法上加 @Transactional(rollbackFor = Exception.class)。
  • 只读查询不开事务；避免在事务方法内做远程调用 / 长耗时操作。

1.7 认证

  • 采用 Spring Security + JWT 无状态认证。登录成功签发 JWT（密钥取自 config-vars.yaml secrets.jwt_secret，有过期时间）。
  • 受保护接口经 JwtAuthenticationFilter 校验 Authorization: Bearer <token>；登录接口 /api/usr/login 放行。
  • 密码用 BCryptPasswordEncoder 哈希存储与比对，禁止明文。

二、前端规范

技术栈：React 18 + Ant Design 5 + Redux Toolkit + React Router v6 + Vite + Axios，包名 xly-erp-web。

2.1 目录约定

前端为仓库根下的 frontend/ 子项目，目录布局：

frontend/
├── package.json                 # name=xly-erp-web；scripts: dev/build/lint/test:unit/test:e2e
├── vite.config.ts
├── index.html
├── src/
│   ├── main.tsx                 # 入口：挂载 App + Redux Provider + Router + AntD ConfigProvider
│   ├── App.tsx
│   ├── router/                  # React Router v6 路由表 + 路由守卫（未登录跳登录页）
│   ├── store/                   # Redux Toolkit：store.ts + slices/（authSlice 等）
│   ├── api/                     # Axios 实例封装（request.ts）+ 各模块 api（usrApi.ts）
│   ├── pages/
│   │   └── usr/                 # 用户管理页面（用户列表 / 新增 / 编辑 / 登录）
│   ├── components/              # 跨页面通用组件
│   ├── styles/                  # 引用 Design Tokens（见下）
│   └── utils/                   # 通用工具
└── tests/                       # 单元测试（Vitest）+ e2e（Playwright）
  • Design Tokens SSoT：色值单一来源在仓库根 src/styles/tokens.css（由 skeleton-gen 生成），前端在 main.tsx / 全局样式中引入；组件只用 var(--color-xxx)，禁止硬编码 hex/rgba。色值冲突时 tokens.css 优先于 prototype/。
  • UI/交互/布局权威：项目根 prototype/（完整 demo）为前端页面布局与交互的权威参照，A5 据其推导 FE 清单。

2.2 状态管理

  • 全局状态（登录态、当前用户、token）用 Redux Toolkit createSlice 管理；按域拆 slice。
  • 服务端数据优先就近在页面用 hooks 拉取，跨页面共享的才进 store；避免把所有响应塞进全局。

2.3 请求封装

  • 统一 Axios 实例（api/request.ts）：baseURL 指向后端 /api，请求拦截器注入 Authorization 头，响应拦截器拆 Result、对非 0 code 统一提示。
  • 各模块 API 集中在 api/<模块>Api.ts，页面只调封装后的方法，不直接散用 axios。

2.4 错误处理

  • 响应拦截器统一处理：401 跳登录、业务错误码弹 message.error、网络异常兜底提示。
  • 表单提交错误就近在表单展示；列表加载失败展示空态/重试。

三、共同约定

3.1 Git 提交

<type>(<scope>): <subject> REQ-XXX-NNN（详见 CLAUDE.md § 🗂️ Git 提交规范）。

3.2 分页查询

  • 入参统一 pageNum（从 1 起）+ pageSize（有上限，默认 10/20，最大 100）+ 业务过滤条件。
  • 返回 PageResult<T>：records / total / pageNum / pageSize。
  • 文本条件模糊匹配，枚举/外键条件精确匹配；空条件返回全量分页。

3.3 日期与金额

  • 日期时间统一 ISO-8601 字符串传输（yyyy-MM-dd'T'HH:mm:ss），后端用 LocalDateTime。
  • 金额用整数分或 BigDecimal，禁止用 float/double 表示金额。

3.4 数据访问规约

  • 数据访问只走 Mapper（MyBatis-Plus）；简单 CRUD 用 MP 内置/LambdaQueryWrapper，复杂 SQL 写 XML。
  • 禁止在 Controller 直接操作 Mapper；逻辑删除/审计字段（创建时间、制单人）由 BaseEntity + MP 自动填充统一处理。
  • 业务 schema 变更走 Flyway migration，并反向同步更新 docs/03-数据库设计文档.md 对应表小节（SSoT 一致）。