# commision-demo

**Repository Path**: ChenLonggitee/commision-demo

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-17
- **Last Updated**: 2025-11-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 用户提成自动化管理系统 - 配置表模块

## 📋 项目说明

本模块实现了用户提成自动化管理系统中的三张核心配置表的增删改查功能和业务逻辑。

## 🗂️ 三张配置表说明

### 1. channel_field_dictionary (字段字典表)
**用途**: 规则要素字段释义,用于字段映射配置

**核心功能**:
- 将业务系统的字段映射到规则表的field1-15字段
- 支持按表名、渠道代码、机构编码查询
- 支持字段启用/禁用控制
- 使用Caffeine缓存提高查询性能

**使用场景**: 业务数据采集时,根据字段映射将业务数据写入中间表

### 2. channel_salary_field_config (工资字段配置表)
**用途**: 控制工资表单字段的显示名称和行为

**核心功能**:
- 配置工资字段的显示名称、是否启用、是否必填、是否只读等
- 支持扩展字段(extend_item1-10)的自定义配置
- 支持字段排序、默认值、最小值、最大值配置
- 支持初始化标准字段配置

**使用场景**: HR录入工资时,前端根据配置动态渲染表单,实现"extend_item1"显示为"高温补贴"等友好名称

### 3. channel_commission_salary_config (工资模板配置表)
**用途**: 定义工资计算公式,支持版本管理

**核心功能**:
- 配置应发提成和实发提成的计算公式
- 支持多版本管理,每次修改创建新版本
- 支持按日期范围控制模板生效时间
- 集成Aviator公式引擎,支持复杂计算
- 提供公式语法校验和测试功能

**使用场景**: 工资计算时,根据日期获取对应的模板配置,使用Aviator引擎执行公式计算

## 📁 项目结构

```
src/main/java/com/demo/
├── common/                          # 通用类
│   ├── Result.java                 # 统一返回结果类
│   ├── BusinessException.java      # 业务异常类
│   └── GlobalExceptionHandler.java # 全局异常处理器
├── config/                          # 配置类
│   ├── MyBatisPlusConfig.java      # MyBatis-Plus配置
│   └── MetaObjectHandlerConfig.java # 字段自动填充配置
├── pojo/
│   └── entity/                      # 实体类
│       ├── ChannelFieldDictionary.java
│       ├── ChannelSalaryFieldConfig.java
│       └── ChannelCommissionSalaryConfig.java
├── mapper/                          # Mapper接口
│   ├── ChannelFieldDictionaryMapper.java
│   ├── ChannelSalaryFieldConfigMapper.java
│   └── ChannelCommissionSalaryConfigMapper.java
├── service/                         # 服务接口
│   ├── ChannelFieldDictionaryService.java
│   ├── ChannelSalaryFieldConfigService.java
│   └── ChannelCommissionSalaryConfigService.java
├── service/impl/                    # 服务实现
│   ├── ChannelFieldDictionaryServiceImpl.java
│   ├── ChannelSalaryFieldConfigServiceImpl.java
│   └── ChannelCommissionSalaryConfigServiceImpl.java
└── controller/                      # 控制器
    ├── ChannelFieldDictionaryController.java
    ├── ChannelSalaryFieldConfigController.java
    └── ChannelCommissionSalaryConfigController.java
```

## 🚀 快速开始

### 1. 环境要求
- JDK 17+
- MySQL 8.0+
- Maven 3.6+
- Redis (可选,用于分布式缓存)

### 2. 配置数据库
修改 `application.properties` 中的数据库连接配置:
```properties
spring.datasource.url=jdbc:mysql://localhost:3306/demo2?characterEncoding=UTF-8
spring.datasource.username=root
spring.datasource.password=your_password
```

### 3. 启动项目
```bash
mvn clean install
mvn spring-boot:run
```

### 4. 访问接口
- 字段字典API: `http://localhost:8002/api/field-dictionary/*`
- 工资字段配置API: `http://localhost:8002/api/salary-field-config/*`
- 工资模板配置API: `http://localhost:8002/api/salary-config/*`

## 🎯 核心功能特性

### 1. 统一异常处理
- 全局异常处理器自动捕获并处理异常
- 业务异常返回友好的错误信息
- 参数校验异常自动提取错误信息

### 2. 缓存优化
- 使用Caffeine本地缓存提高查询性能
- 字段字典缓存: 1小时过期
- 字段配置缓存: 1小时过期
- 工资模板缓存: 1小时过期
- 公式编译缓存: 2小时过期,最多缓存10000条

### 3. 字段自动填充
- 创建时自动填充createTime和updateTime
- 更新时自动填充updateTime
- 使用MyBatis-Plus的MetaObjectHandler实现

### 4. 逻辑删除
- 所有表都支持逻辑删除
- 删除操作不会真正删除数据,只是标记is_deleted=1
- 查询时自动过滤已删除数据

### 5. 分页查询
- 使用MyBatis-Plus的Page插件
- 单页最大1000条记录
- 支持多条件组合查询

### 6. 公式引擎
- 集成Aviator表达式引擎
- 支持算术运算、比较运算、逻辑运算
- 支持MAX、MIN、IF等函数
- 提供公式校验和测试接口

## 📊 数据库设计亮点

### 1. 字段字典表
- 支持按表名、渠道、机构的多维度映射
- 灵活的字段映射机制
- 支持字段释义和注释

### 2. 工资字段配置表
- 灵活的字段配置机制
- 支持扩展字段自定义
- 支持字段校验规则配置
- 支持字段显示控制

### 3. 工资模板配置表
- 版本化管理
- 支持时间段控制
- 公式快照保存,确保可追溯
- 支持审批流程集成

## 🔧 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Spring Boot | 3.2.4 | 基础框架 |
| MyBatis-Plus | 3.5.5 | ORM框架 |
| Aviator | 5.3.3 | 表达式引擎 |
| Caffeine | 3.1.8 | 本地缓存 |
| Druid | 1.2.20 | 数据库连接池 |
| Lombok | 1.18.30 | 简化代码 |
| Hutool | 5.8.24 | 工具类库 |
| FastJSON2 | 2.0.43 | JSON处理 |

## 📝 API接口文档

详细的API接口文档请查看: [API接口文档.md](./API接口文档.md)

### 接口总览

**字段字典表** (10个接口):
- 分页查询、根据ID查询、根据表名和渠道查询、获取映射Map
- 新增、更新、批量更新、删除
- 启用/禁用、刷新缓存

**工资字段配置表** (13个接口):
- 分页查询、根据ID查询、根据机构ID查询、获取启用的字段、获取录入字段、获取字段Map
- 新增、更新、更新扩展字段、批量更新排序、删除
- 启用/禁用、初始化标准字段、刷新缓存

**工资模板配置表** (13个接口):
- 分页查询、根据ID查询、获取生效模板、根据日期获取模板、根据机构ID查询、根据编码和版本查询
- 创建新版本、更新、激活、失效、删除
- 校验公式、测试公式、复制模板、刷新缓存

## 💡 使用示例

### 1. 初始化机构配置

```bash
# 1. 初始化字段配置
POST http://localhost:8002/api/salary-field-config/init?agencyId=1001&agencyCode=SZ001

# 2. 自定义扩展字段
PUT http://localhost:8002/api/salary-field-config/extend-field
?agencyId=1001&extendFieldCode=extend_item1&fieldName=高温补贴&helpText=夏季6-9月发放

# 3. 创建工资模板
POST http://localhost:8002/api/salary-config
Content-Type: application/json

{
  "configCode": "SZ_SALARY_001",
  "configName": "深圳分公司工资模板",
  "agencyId": 1001,
  "agencyCode": "SZ001",
  "totalCommissionFormula": "auto_total_commission + fixed_salary + extend_item1",
  "finalCommissionFormula": "MAX(total_commission, 0)",
  "status": 2
}

# 4. 激活模板
PUT http://localhost:8002/api/salary-config/1/activate?effectiveDate=2024-01-01
```

### 2. 工资录入流程

```bash
# 1. 获取需要录入的字段
GET http://localhost:8002/api/salary-field-config/agency/1001/input-fields

# 2. 前端根据返回的字段配置动态渲染表单

# 3. HR填写数据并提交到工资表
```

### 3. 公式测试

```bash
# 校验公式语法
POST http://localhost:8002/api/salary-config/validate-formula
?formula=auto_total_commission + fixed_salary

# 测试公式计算
POST http://localhost:8002/api/salary-config/test-formula
?formula=auto_total_commission + fixed_salary
Content-Type: application/json

{
  "auto_total_commission": 15000,
  "fixed_salary": 8000
}
```

## ⚠️ 注意事项

1. **缓存刷新**: 配置变更后需要调用刷新缓存接口,或等待缓存自动过期
2. **公式测试**: 上线前务必使用测试接口验证公式的正确性
3. **版本管理**: 修改工资模板时建议创建新版本,而不是直接修改现有版本
4. **数据校验**: 所有金额字段建议设置min_value和max_value进行范围校验
5. **权限控制**: 实际使用时需要添加权限校验,防止越权操作
6. **事务控制**: 批量操作已添加事务控制,确保数据一致性

## 🐛 常见问题

### Q1: 缓存什么时候刷新?
A: 配置变更后会自动清除相关缓存,也可以手动调用刷新缓存接口。如果不手动刷新,缓存会在1-2小时后自动过期。

### Q2: 如何自定义扩展字段?
A: 调用 `/api/salary-field-config/extend-field` 接口更新扩展字段的名称和帮助文本。

### Q3: 公式支持哪些运算?
A: 支持加减乘除、比较运算、逻辑运算、三元表达式、MAX/MIN/IF等函数。详见Aviator文档。

### Q4: 如何处理不同时间段使用不同公式?
A: 为不同时间段创建不同的模板,设置不同的生效日期和失效日期。

### Q5: 扩展字段最多支持多少个?
A: 工资表支持10个扩展字段(extend_item1-extend_item10)。

## 📞 技术支持

如有问题,请联系开发团队。

---

**版本**: v1.0.0
**更新日期**: 2024-11-17
**维护团队**: 提成自动化管理系统开发组