# integrix

**Repository Path**: kongfq/integrix

## Basic Information

- **Project Name**: integrix
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-05-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Integrix ERP 业务开发基座

基于 Spring Boot 3 + JDK 21（虚拟线程）+ COLA 架构 + Kong 网关 + 改造版 Supabase Studio 的企业级 ERP 开发基座。

## 项目结构

```
integrix/
├── backend/                          # 后端 Spring Boot 应用
│   ├── integrix-common-core/         # 公共基石
│   │   └── src/main/java/com/integrix/common/core/
│   │       ├── result/               #   统一响应 Result<T>
│   │       └── exception/            #   异常处理（BusinessException、ErrorCode、GlobalExceptionHandler）
│   │
│   ├── integrix-commons/             # 通用工具配置
│   │   └── src/main/java/com/integrix/commons/
│   │       └── mybatis/              #   MyBatis-Plus 配置
│   │
│   ├── integrix-common-starters/     # 可插拔 Starter 组件集合（父 POM）
│   │   ├── common-auth/              #   认证授权 Starter
│   │   │   └── src/main/java/com/integrix/common/starter/auth/
│   │   │       ├── configuration/    #     SaTokenConfigure、AuthProperties、PasswordEncoderConfig
│   │   │       ├── authentication/   #     AbstractAuthentication、UserInfoStatusCheck
│   │   │       ├── entity/           #     UserDetail、AuthInfoResult、LoginAuthContext
│   │   │       ├── handler/          #     SaRouteHandler
│   │   │       ├── util/             #     SecurityUtil
│   │   │       └── exception/        #     LoginFailureException、UserNotFoundException
│   │   │
│   │   └── common-redis/             #   Redis 操作 Starter
│   │       └── src/main/java/com/integrix/common/starter/redis/
│   │           ├── RedisConfig.java  #     Redis 序列化配置
│   │           └── RedisService.java #     Redis 操作封装
│   │
│   ├── integrix-services/            # 业务服务模块
│   │   └── service-iam/              # 身份与访问管理服务（COLA 包级分层）
│   │       └── src/main/java/com/integrix/service/iam/
│   │           ├── domain/           #   领域层（纯净，无 Spring 依赖）
│   │           │   ├── constant/     #     IamConstants
│   │           │   ├── model/        #     User 领域模型
│   │           │   └── gateway/      #     UserGateway 接口
│   │           ├── app/              #   应用层（用例编排）
│   │           │   ├── dto/          #     LoginCmd、RegisterCmd、LoginResult（Record）
│   │           │   └── service/      #     IamAppService
│   │           ├── adapter/          #   适配层（外部接口）
│   │           │   └── controller/   #     AuthController
│   │           └── infrastructure/   #   基础设施层
│   │               └── persistence/  #     持久化实现
│   │                   ├── dataobject/  #   UserDO
│   │                   ├── mapper/      #   UserMapper
│   │                   ├── converter/   #   UserConverter
│   │                   └── gateway/     #   UserGatewayImpl
│   │
│   └── integrix-start/               # 启动模块
│       └── src/main/
│           ├── java/                 #   IntegrixApplication 入口
│           └── resources/
│               ├── application.yml   #   应用配置
│               └── db/migration/     #   Flyway 数据库迁移
│
├── frontend/                         # 前端应用
│   └── studio/                       # 改造版 Supabase Studio
│       └── src/
│           ├── components/           #   UI 组件（Layout、CommandBar 等）
│           ├── contexts/             #   ThemeContext 主题切换
│           ├── providers/            #   数据提供者（Mock、API）
│           └── stores/               #   Zustand 状态管理
│
├── shared/                           # 共享资源
│   └── types/                        # 前后端共享类型定义
│
├── gateway/                          # Kong Gateway 配置
├── docker/                           # Docker 配置
└── docs/                             # 文档
```

## 技术栈

### 后端
- **核心框架**: Spring Boot 3.2+
- **JDK 版本**: JDK 21 (LTS) - 启用虚拟线程 (`spring.threads.virtual.enabled=true`)
- **架构模式**: COLA 四层架构（Adapter → App → Domain → Infrastructure）- 包级分层
- **数据访问**: MyBatis-Plus 3.5+
- **数据库**: PostgreSQL 15+
- **缓存**: Redis + Lettuce + Redisson
- **API 文档**: SpringDoc OpenAPI 3
- **安全**: Sa-Token + Redis（参考 bootx-platform）
- **数据库迁移**: Flyway

### 前端
- **框架**: React 18+ (TypeScript)
- **状态管理**: Zustand
- **UI 组件**: Tailwind CSS + Headless UI
- **构建工具**: Vite 5

### 基础设施
- **API 网关**: Kong Gateway
- **容器化**: Docker + Docker Compose
- **监控**: Prometheus + Grafana
- **日志**: ELK Stack / Loki

## COLA 架构说明

### 分层职责（包级分层）

| 层级 | 包路径 | 职责 | 依赖 |
|------|--------|------|------|
| **Adapter** | `*.adapter.controller` | 接收外部请求，参数校验，调用 App 层 | → App |
| **App** | `*.app.service` / `*.app.dto` | 用例编排，事务控制，DTO 转换 | → Domain |
| **Domain** | `*.domain.model` / `*.domain.gateway` | 领域模型，业务规则，Gateway 接口定义 | → Common Core |
| **Infrastructure** | `*.infrastructure.persistence` | 数据持久化，外部服务调用，Gateway 实现 | → Domain |

### 模块依赖关系

```
integrix-start
  ├── common-auth          → integrix-common-core
  ├── common-redis         → integrix-common-core
  ├── integrix-commons     → integrix-common-core
  └── service-iam
        ├── domain/        → integrix-common-core
        ├── app/           → domain/
        ├── adapter/       → app/
        └── infrastructure/→ domain/, integrix-commons
```

### 可插拔 Starter 组件

| Starter | 说明 | 自动配置 |
|---------|------|----------|
| **common-auth** | Sa-Token + Redis 认证，支持多登录方式（密码/三方登录） | AuthAutoConfiguration |
| **common-redis** | Redis 操作封装（Lettuce + Redisson） | RedisConfig |

按需引入，不需要的 Starter 不添加依赖即可。

### 认证架构（参考 bootx-platform）

```
common-auth/
  ├── AbstractAuthentication      # 抽象认证器接口（策略模式）
  ├── UserInfoStatusCheck         # 用户状态检查接口
  ├── SaRouteHandler              # 路由鉴权处理器
  ├── SaTokenConfigure            # Sa-Token 拦截器配置
  └── SecurityUtil                # 安全工具类（获取当前用户、登录、登出）

service-iam/
  ├── auth/login/                 # 登录方式实现
  │   └── PasswordLoginHandler    # 密码登录（实现 AbstractAuthentication）
  └── auth/handler/               # 认证相关处理器
      ├── UserInfoStatusCheckImpl # 用户状态检查实现
      └── SaRouteHandlerImpl      # 路由鉴权实现
```

**登录流程：**
1. 前端调用 `/api/v1/auth/login`，传入 `loginType`（默认 `password`）
2. `IamAppService` 根据 `loginType` 找到对应的 `AbstractAuthentication` 实现
3. 执行认证流程：`authenticationBefore` → `attemptAuthentication` → `check` → `authenticationAfter`
4. 认证成功后通过 `StpUtil.login()` 创建 Sa-Token 会话
5. 后续请求通过 `SaTokenConfigure` 拦截器进行路由鉴权

### 开发规范

1. **DTO 使用 Record 类**：Adapter 层的请求/响应对象使用 Java Record
2. **领域层保持纯净**：Domain 层不引入 Spring 或基础设施注解
3. **Gateway 模式**：Domain 层定义接口，Infrastructure 层实现
4. **审计字段**：所有数据表包含 `created_at`、`updated_at`、`created_by`、`updated_by`
5. **虚拟线程**：`spring.threads.virtual.enabled=true`
6. **逻辑删除**：使用 `deleted` 字段，MyBatis-Plus 全局配置
7. **主键策略**：UUID (`assign_uuid`)

## 快速开始

### 环境要求
- JDK 21+
- Node.js 18+
- PostgreSQL 15+
- Redis 7+
- Docker & Docker Compose

### 安装依赖
```bash
npm run setup
```

### 开发模式
```bash
# 同时启动前后端
npm run dev

# 单独启动前端
npm run dev:frontend

# 单独启动后端
npm run dev:backend
```

### 构建
```bash
# 构建前端
npm run build:frontend

# 构建后端
cd backend && mvn clean package -DskipTests
```

## 新增业务模块

按 COLA 架构创建新业务模块（以 `service-xxx` 为例）：

```bash
# 1. 在 integrix-services 下创建 service-xxx 模块
integrix-services/
  └── service-xxx/
      └── src/main/java/com/integrix/service/xxx/
          ├── domain/           # 领域模型、Gateway接口、常量
          ├── app/              # 用例编排、DTO（Record）
          ├── adapter/          # Controller
          └── infrastructure/   # 持久化实现（DO、Mapper、Converter、GatewayImpl）

# 2. 创建 pom.xml，继承 integrix-services
# 3. 在 integrix-services/pom.xml 中添加模块引用
# 4. 在 integrix-start/pom.xml 中添加依赖
```

## 新增 Starter 组件

在 `integrix-common-starters/` 下创建新 Starter 模块（以 `common-xxx` 为例）：

```bash
integrix-common-starters/
  └── common-xxx/
      └── src/main/java/com/integrix/common/starter/xxx/
          └── XxxAutoConfiguration.java

# 1. 创建 pom.xml，继承 integrix-common-starters
# 2. 在 integrix-common-starters/pom.xml 中添加模块引用
# 3. 在 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 中注册自动配置类
```

## 架构设计

详见 [架构设计文档](./架构设计.md)

## 开发规范

详见 [.trae/rules/allconstarct.md](./.trae/rules/allconstarct.md)

## 许可证

内部项目，未经授权不得外传。