182 lines
8.9 KiB
Markdown
182 lines
8.9 KiB
Markdown
---
|
||
title: 后端架构
|
||
description: g3soft-erp 后端的实际结构：技术栈、包组织、多机构数据源路由、通用数据接口、权限与工作流
|
||
---
|
||
|
||
# 后端架构
|
||
|
||
本文描述 `g3soft-erp/server` **当前的实现**（不是规划稿）。所有内容以代码为准，涉及取舍的地方都写明原因。
|
||
|
||
## 1. 技术栈
|
||
|
||
| 项 | 选型 |
|
||
|---|---|
|
||
| 框架 | Spring Boot 4.1.0 / Java 21 |
|
||
| 数据访问 | `spring-boot-starter-jdbc` + **纯手写 SQL**，**无 ORM** |
|
||
| 连接池 | Druid |
|
||
| 数据库 | SQL Server（2022） |
|
||
| 鉴权 | JJWT |
|
||
| 导出 | Apache Fesod + POI |
|
||
| 参数校验 | 自研 `ParamUtils` / `RequestParams` |
|
||
|
||
**为什么不用 ORM**：业务查询大量依赖视图、动态条件、聚合与按机构分库，ORM 的映射层在这些场景反而成为阻碍。查询与写入都直接落到 SQL。
|
||
|
||
## 2. 包组织
|
||
|
||
```
|
||
cn.g3soft.erp
|
||
├── common/ 通用设施
|
||
│ ├── ApiResponse 统一响应包体
|
||
│ ├── exception/ 业务异常 + 全局异常处理
|
||
│ └── util/ 参数、SQL 文本、时间、UUIDv7、雪花 ID
|
||
├── config/ 过滤器与配置属性
|
||
│ ├── JwtAuthFilter JWT 鉴权
|
||
│ ├── RequestLoggingFilter 访问日志（MDC）
|
||
│ └── *Properties 按功能分组的配置绑定
|
||
├── controller/ 接口层（6 个控制器）
|
||
├── database/ 数据访问基础设施
|
||
│ ├── MetadataReader 表结构内省
|
||
│ ├── RowReader 查询
|
||
│ ├── RowWriter 写入
|
||
│ ├── model/ 元数据模型
|
||
│ └── org/ 多机构数据源路由
|
||
└── service/ 业务服务
|
||
├── auth/ 登录、JWT、会话、登录日志
|
||
├── data/ 通用数据查询 / 保存 / 删除
|
||
├── export/ 导出
|
||
├── file/ 附件
|
||
├── formula/ 公式引擎
|
||
├── permission/ 权限判定
|
||
└── workflow/ 工作流引擎
|
||
```
|
||
|
||
分层约定：**controller 只做参数接收与响应包装**，业务逻辑一律在 service；SQL 相关的底层能力集中在 `database/`，由各 service 复用。
|
||
|
||
## 3. 多机构数据源路由
|
||
|
||
一套部署服务多个机构，每个机构一个独立数据库。
|
||
|
||
```text
|
||
请求 → JwtAuthFilter 解析 JWT，写入 OrgContext（ThreadLocal: orgId / userId）
|
||
→ 业务代码注入 @Primary 的 OrgRoutingDataSource
|
||
→ 按 OrgContext.requireOrgId() 路由到该机构的连接池
|
||
```
|
||
|
||
| 组件 | 职责 |
|
||
|---|---|
|
||
| `OrgContext` | `ThreadLocal` 保存当前请求的机构码与用户编码 |
|
||
| `OrgRoutingDataSource` | `@Primary` 数据源，每次取连接时按机构路由 |
|
||
| `OrgDataSourceManager` | 按机构懒加载并缓存连接池 |
|
||
| `OrgDatabaseConfigLoader` | 读取 `config/dbconfigs/{机构码}.properties` |
|
||
| `OrgDatabaseConfigWatcher` | 监听配置目录，改动后热切换连接池 |
|
||
|
||
**几个刻意的做法**：
|
||
|
||
- **不依赖 Spring 的事务抽象**：全项目不使用 `@Transactional`，事务边界由 service 手动控制（`setAutoCommit(false)` → `commit` / `rollback`）。
|
||
- **连接池配置热更新**：配置文件变更后重建连接池，旧池延迟关闭，保证在途请求有时间归还连接。
|
||
- **建池即验活**：`initial-size: 1`，配置指向不可达的库时快速失败并保留旧池，不会把整个机构打挂。
|
||
- **后台任务要自己设上下文**：无请求上下文的定时任务必须逐个机构设置 `OrgContext` 再取连接，用完清理。
|
||
|
||
## 4. 通用数据接口
|
||
|
||
除工作流外，业务数据的读写统一走 `/data/**`，不为每个模块写专用 CRUD。
|
||
|
||
| 接口 | 作用 |
|
||
|---|---|
|
||
| `POST /data/describe` | 探测表/视图的列结构 |
|
||
| `POST /data/loaddata` | 按视图 + 条件查询列表 |
|
||
| `POST /data/loaddatabysql` | 执行只读 SQL |
|
||
| `POST /data/page` | 分页查询（返回 `rows` / `total` / `page_no` / `page_size`） |
|
||
| `POST /data/saveobjt` | 通用保存（批量，主子表一次提交） |
|
||
| `POST /data/delete` | 通用删除 |
|
||
| `POST /data/nextid` | 取雪花 ID |
|
||
| `POST /data/nextcode` | 取自动编码 |
|
||
|
||
**共同约定**：
|
||
|
||
- 表名、视图名、列名**先过标识符校验**（只允许 `[A-Za-z_][A-Za-z0-9_]*`，可带 `dbo.` 限定），不做字符串拼接。
|
||
- `search_condition` 是**原样拼进 `WHERE` 的布尔表达式片段**，整条 SQL 之后过只读校验（禁分号、禁注释、禁写关键字）。
|
||
- 返回的行是普通 Map，键是**库里的原始列名**。
|
||
- **审计列由服务端统一填**，前端不能指定：`b_created_by` / `b_created_at` / `b_updated_by` / `b_updated_at` 由保存层写入，不建触发器。
|
||
|
||
**保存的并发保护**：`b_row_version` 参与乐观锁；影响行数为 0 时区分「记录不存在」与「版本冲突」，分别返回可识别的错误，前端据此提示刷新。
|
||
|
||
## 5. 权限模型
|
||
|
||
前端隐藏菜单只是体验，**真正生效的过滤必须在后端拼进 SQL**。`SqlPermissionService` 是这一层的唯一实现，分三层：
|
||
|
||
| 层 | 数据来源 | 语义 |
|
||
|---|---|---|
|
||
| 动作权限 | `s_power` + `s_user_power` | **白名单**：没有对应权限点、或未授权、或任一侧停用即拒绝 |
|
||
| 字段权限 | `s_user_field_power` | `b_view` / `b_export`，无记录按模块默认（可看可导出） |
|
||
| 数据范围 | `s_user_data_power` | 按操作精确匹配优先，多条规则 OR，整体再与其它条件 AND |
|
||
|
||
动作权限编码为 `action.{模块}.{动作}`；数据范围的判定字段取自**模块配置** `s_module.b_scope_field`（记录归属人字段），而不是授权行——同一个模块的所有用户必须用同一字段判范围。
|
||
|
||
## 6. 工作流
|
||
|
||
工作流是独立子系统，不与通用数据接口混用：**业务单据的状态只能由流程服务推进**，业务表的状态列由流程投影写入。
|
||
|
||
```text
|
||
业务模块 → 流程绑定 → 已发布版本 → 节点与连线 / 审批人规则
|
||
业务提交 → 流程实例 → 节点运行 → 待办任务 → 动作 / 审计 / 通知
|
||
```
|
||
|
||
| 接口组 | 前缀 | 职责 |
|
||
|---|---|---|
|
||
| 配置 | `/workflow/**` | 定义、版本（草稿/发布/停用/复制）、绑定 |
|
||
| 运行 | `/workflow/runtime/**` | 送审、审批动作、抢占、转派、加签、催办、撤回、取消、待办/已办/进度/抄送 |
|
||
|
||
实现上的关键口径：
|
||
|
||
- 一次动作的全部副作用在**同一事务**内完成：锁定 → 校验 → 写动作 → 更新任务/节点 → 推进或结束 → 投影业务状态 → 写 outbox → 提交。
|
||
- **锁序统一为「实例优先」**，避免实例与任务互锁造成的死锁。
|
||
- **幂等**：送审按 `b_idempotency_key`，审批按 `wf_action.b_request_id`，各由一条筛选唯一索引兜底。
|
||
- 审批人解析为空时实例进入 `error` 而非跳过节点。
|
||
- **超时只标记任务、不改流程**：到期任务置 `expired` 并从待办移除，实例保持运行，由管理员加签/转派处理。
|
||
|
||
## 7. 鉴权与会话
|
||
|
||
```text
|
||
POST /auth/login → 校验账号 → 签发 JWT（含机构码、用户编码）→ 登记活动会话
|
||
后续请求 → JwtAuthFilter 校验签名与会话有效性 → 写入 OrgContext 与日志 MDC
|
||
```
|
||
|
||
- 过滤器只放行 `OPTIONS` 与 `/auth/login`，其余请求一律校验。
|
||
- **会话登记**：`ActiveSessionRegistry` 记录活动会话，可在登录时判定是否顶掉旧会话。
|
||
- 登录日志独立记录（含客户端信息与 IP 归属地），便于审计。
|
||
|
||
## 8. 公式引擎
|
||
|
||
`service/formula` 是一套独立的表达式引擎：词法 → 语法 → AST → 求值，配合依赖图与配置服务。
|
||
|
||
- **依赖分析**：`FormulaDeps` / `FormulaGraph` 解析字段间依赖，支持检测循环引用。
|
||
- **校验与配置分离**：`FormulaValidator` 负责保存期校验，`FormulaConfigService` 负责读取与缓存。
|
||
- 求值结果与错误都走统一类型，便于前端展示。
|
||
|
||
## 9. 附件
|
||
|
||
`POST /file/**` 提供两类存储模式，由 `erp.file.storage-type` 配置：
|
||
|
||
| 模式 | 流程 |
|
||
|---|---|
|
||
| `local` | 后端写盘 + 落库，静态资源走 `/file/static/**` |
|
||
| `aliyun-oss` | 前后端取号 → 凭证直传 OSS → 回调落库 |
|
||
|
||
配置前缀为 `erp.file.*`（`storage-dir` / `url-prefix` / `g3oss-url`）。文件记录表使用 `bf_` 业务域前缀。
|
||
|
||
## 10. 配置
|
||
|
||
配置按功能分组，统一挂在 `erp.*` 下：
|
||
|
||
```yaml
|
||
erp:
|
||
auth: jwt-secret / jwt-expiration
|
||
database: config-dir / refresh-check-interval / pool.*
|
||
file: storage-type / local.* / oss.*
|
||
log: slow-request-ms / max-param-bytes / exclude-param-paths
|
||
workflow: expire-sweep-interval
|
||
```
|
||
|
||
**机构数据库配置独立存放**：`server/config/dbconfigs/{机构码}.properties`，含连接串、账号与驱动。该目录已 gitignore，不入版本库。
|