# IPMS

**Repository Path**: fengshaqingqing/ipms

## Basic Information

- **Project Name**: IPMS
- **Description**: 积分系统
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IPMS积分系统

IPMS (Integral Point Management System) 是一个高性能、可扩展的积分管理系统,采用伪Monorepo架构,支持管理后台、实时交易和批量任务三大链路。

## 技术栈

### 后端
- **语言**: Go 1.24.8
- **Web框架**: Hertz
- **ORM**: GORM v2
- **数据库**: MySQL 8.0 (分表+分区)
- **缓存**: Redis 7.0
- **规则引擎**: expr-lang/expr
- **依赖注入**: Uber Fx
- **日志**: Zap

### 前端
- **框架**: Vue 3
- **UI库**: Element Plus
- **状态管理**: Pinia
- **路由**: Vue Router 4
- **HTTP客户端**: Axios
- **图表**: ECharts 5
- **构建工具**: Vite 5

## 项目结构

```
ipms/
├── cmd/                      # 服务入口
│   ├── admin/               # Admin服务(端口8081)
│   ├── realtime/            # Realtime服务(端口8082)
│   └── batch/               # Batch服务(端口8083)
├── internal/                # 内部代码
│   ├── admin/              # Admin服务实现
│   │   └── handler/        # Handler层
│   ├── realtime/           # Realtime服务实现
│   │   └── handler/        # Handler层
│   ├── batch/              # Batch服务实现
│   │   └── service/        # 批量任务服务
│   └── core/               # 核心共享层
│       ├── model/          # 数据模型
│       ├── dto/            # 数据传输对象
│       ├── repository/     # 数据访问层
│       └── service/        # 业务逻辑层
├── pkg/                    # 公共工具包
│   ├── sharding/           # 分表路由
│   └── utils/              # 工具函数
├── web/                    # 前端代码
│   └── admin-ui/           # 管理后台前端
│       ├── src/
│       │   ├── api/        # API定义
│       │   ├── router/     # 路由配置
│       │   ├── views/      # 页面组件
│       │   └── utils/      # 工具函数
│       ├── package.json
│       └── vite.config.js
├── scripts/
│   └── sql/init/           # 数据库初始化脚本
│       └── init-database.sql
└── go.mod                  # Go模块定义
```

## 快速开始

### 方式一: Docker部署(推荐) 🐳

```bash
# 1. 克隆项目
git clone <repository-url>
cd ipms

# 2. 配置环境变量
cp .env.example .env
# 编辑.env文件,修改数据库密码等配置

# 3. 启动所有服务
docker-compose up -d

# 4. 初始化数据库
docker exec -i ipms-mysql mysql -uroot -p${MYSQL_ROOT_PASSWORD} ipms < scripts/sql/init/init-database.sql

# 5. 访问系统
# 管理后台: http://localhost
# Admin API: http://localhost:8081
# Realtime API: http://localhost:8082
```

详细部署文档请参考: [docs/deployment/积分系统-Docker部署指南.md](./docs/deployment/积分系统-Docker部署指南.md)

---

### 方式二: 本地开发环境

### 前置要求
1. MySQL 8.0已安装并运行
2. Redis 7.0已安装并运行
3. Go 1.24.8已安装
4. Node.js 18+已安装

### 1. 数据库初始化

```bash
mysql -u root -p < scripts/sql/init/init-database.sql
```

### 2. 修改配置文件

编辑 `configs/admin.yaml` 和 `configs/realtime.yaml`:
```yaml
database:
  password: your-mysql-password
  
redis:
  password: your-redis-password  # 如果有密码
```

### 3. 启动后端服务

#### Admin服务(管理后台)
```bash
cd cmd/admin
go run main.go
# 输出: Config loaded: server.port=8081, mode=debug
# 输出: MySQL连接成功
# 输出: Admin服务启动在端口 8081
```

#### Realtime服务(实时交易)
```bash
cd cmd/realtime
go run main.go
# 输出: Config loaded: server.port=8082, mode=debug
# 输出: MySQL连接成功
# 输出: Redis连接成功
# 输出: Realtime服务启动在端口 8082
```

#### Batch服务(批量任务)
```bash
cd cmd/batch
go run main.go
# 后台运行定时任务
```

### 4. 启动前端服务

```bash
cd web/admin-ui
npm install
npm run dev
# 前端运行在 http://localhost:3000
```

## 核心功能

### 1. 业务场景管理 ✅
- 创建/编辑/删除业务场景
- 配置场景类型、消耗优先级、混合使用策略
- 设置过期处理和退款策略
- **完整CRUD实现,支持多条件过滤和分页查询**

### 2. 规则配置中心 ✅
- **完整CRUD功能**(新增/编辑/删除/查询)
- **多条件搜索**(编码/名称/类型/状态)
- **实时状态切换**(Switch开关启用/禁用)
- 基于expr-lang的表达式计算
- 支持多种规则类型(订单消费、签到、活动等)
- 可视化规则树编辑器(开发中)

### 3. 积分交易 ✅
- **积分发放**: 自动创建分桶,支持自定义有效期
- **积分消耗**: FIFO先进先出扣减,支持事务锁定
- **幂等性控制**: Redis SETNX防止重复提交(TTL=5分钟)
- **签名验证**: HMAC-SHA256防篡改+防重放攻击(5分钟窗口)
- 退货处理: 支持负数余额(开发中)

### 4. 账户管理 ✅
- 主子账户架构
- 多场景账户隔离
- **客户搜索**(按ID/手机号)
- **账户详情展示**(余额/冻结金额/有效期)
- **分桶列表查询**(初始积分/剩余积分/过期时间)
- **变动流水查询**(最近10条记录)
- **数据脱敏**(手机号/身份证自动脱敏)

### 5. 数据分片 ✅
- 按customer_id % 10分10张表
- 按月自动分区
- 透明路由,对业务无感知

### 6. 配置管理 ✅
- Viper配置文件管理(YAML格式)
- 环境隔离(admin.yaml/realtime.yaml)
- 类型安全的配置结构
- 便捷的辅助方法(GetDSN/GetAddr)

### 7. Redis缓存层 ✅
- Cache-Aside模式封装
- 自动JSON序列化/反序列化
- 统一Key命名规范
- 灵活TTL设置

### 8. Batch批量任务 ✅
- **过期积分清理**(每日执行,遍历分片表)
- **每日增量对账**(账户余额vs分桶总额)
- **对账异常记录**(自动插入异常表)
- **分区维护SQL**(每月25日自动添加/删除分区)
- 仪表盘统计(凌晨2:00-4:00,待完善)

## API文档

### Admin服务API (http://localhost:8081)

#### 场景管理
- `POST /api/v1/scenes` - 创建场景
- `PUT /api/v1/scenes` - 更新场景
- `DELETE /api/v1/scenes/:id` - 删除场景
- `GET /api/v1/scenes/:id` - 查询场景详情
- `GET /api/v1/scenes` - 分页查询场景列表

**示例: 创建场景**
```bash
curl -X POST http://localhost:8081/api/v1/scenes \
  -H "Content-Type: application/json" \
  -d '{
    "scene_code": "TEST_SCENE",
    "scene_name": "测试场景",
    "scene_type": 0,
    "consumption_priority": 99,
    "allow_mix_use": 0,
    "expiry_action": 1,
    "refund_policy": 1,
    "description": "用于测试的场景"
  }'
```

### Realtime服务API (http://localhost:8082)

#### 积分交易
- `POST /api/v1/points/earn` - 积分发放(需签名验证)
- `POST /api/v1/points/spend` - 积分消耗(需签名验证)

**签名算法**: HMAC-SHA256(method + path + timestamp + appID + body, secretKey)

**示例: 积分发放(需签名)**
```bash
# 1. 生成时间戳
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

# 2. 计算签名(Linux/Mac)
SIGNATURE=$(echo -n "POST/api/v1/points/earn${TIMESTAMP}test-app-id{\"customer_id\":123,...}" | \
  openssl dgst -sha256 -hmac 'your-secret-key' -hex | awk '{print $2}')

# 3. 发送请求
curl -X POST http://localhost:8082/api/v1/points/earn \
  -H "Content-Type: application/json" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-App-ID: test-app-id" \
  -H "X-Signature: ${SIGNATURE}" \
  -d '{
    "customer_id": 123,
    "biz_no": "ORDER_20240115_001",
    "biz_scene_code": "TEST_SCENE",
    "amount": 100,
    "expire_time": "2025-01-15T00:00:00Z",
    "idempotent_key": "ORDER_20240115_001"
  }'
```

**注意**: 
- 签名验证失败返回401
- 重复请求(idempotent_key相同)返回409
- 时间戳过期(>5分钟)返回401

## 开发规范

### 后端规范
- 遵循三层架构: Handler → Service → Repository
- 所有业务表和配置表必须包含审计字段(create_time, create_user, update_time, update_user, version)
- 分表操作通过pkg/sharding路由,禁止硬编码表名
- 使用乐观锁(version字段)处理并发更新

### 前端规范
- 使用Composition API (script setup)
- API调用统一通过src/api目录
- 组件命名采用PascalCase
- 样式使用scoped避免污染

## CI/CD

### Gitee Go 配置 (已就绪,待启用)

本项目已配置Gitee Go持续集成,但目前**以本地测试为主**。

**配置文件**: `.gitee/workflows/test.yml`

**何时启用**:
- 团队协同时需要自动化测试
- 需要PR合并前自动验证
- 希望减少人工测试工作量

**启用步骤** (将来需要时):
1. 登录码云,进入项目
2. 点击 **"服务" → "Gitee Go"**
3. 点击 **"启用Gitee Go"**
4. 流水线会自动触发

**详细文档**: `.gitee/GITEE_GO_GUIDE.md`

---

## 本地测试 (当前主要方式)

### 分层测试策略

本项目采用**单元测试 + 集成测试**的分层测试策略:

- **单元测试**: 使用SQLite内存数据库,快速隔离,适合日常开发
- **集成测试**: 使用MySQL真实环境,验证SQL兼容性和数据一致性

**详细文档**: [LOCAL_TEST_GUIDE.md](LOCAL_TEST_GUIDE.md)

### 运行测试

#### Windows PowerShell (推荐)
```powershell
# 查看帮助
.\test.ps1 help

# 运行单元测试(快速)
.\test.ps1 unit

# 运行集成测试(需要MySQL)
.\test.ps1 integration

# 运行所有测试
.\test.ps1 all
```

#### Linux/Mac (Makefile)
```bash
# 查看帮助
make help

# 运行单元测试
make test-unit

# 运行集成测试
make test-integration

# 运行所有测试
make test-all
```

#### 直接运行Go命令
```bash
# 单元测试
CGO_ENABLED=1 go test ./internal/admin/service -v

# 集成测试
CGO_ENABLED=1 TEST_DB_DSN="root:root@tcp(localhost:3306)/ipms?..." \
  go test -tags=integration ./internal/admin/service -v
```

### 测试覆盖

#### 后端单元测试 ✅
- ✅ AuthService登录/Token验证/用户信息查询
- ✅ AdminUserRepository数据访问
- ✅ PointService积分发放边界值测试
- ✅ PointService FIFO扣减逻辑测试
- ✅ RuleEngineService表达式计算测试

#### 后端集成测试 ✅
- ✅ AuthService MySQL环境测试
- ✅ AdminUserRepository MySQL数据持久化

### 前端单元测试 ✅
```bash
# 运行所有测试
go test ./internal/core/service/... -v

# 运行PointService测试
go test ./internal/core/service/point_service_test.go -v

# 运行RuleEngineService测试
go test ./internal/core/service/rule_engine_service_test.go -v
```

**测试覆盖**:
- ✅ PointService积分发放边界值测试
- ✅ PointService FIFO扣减逻辑测试
- ✅ PointService并发扣减测试
- ✅ RuleEngineService表达式计算测试

### 前端单元测试 ✅
```bash
cd web/admin-ui

# 运行所有测试
npm test

# 图形化界面运行
npm run test:ui

# 生成覆盖率报告
npm run test:coverage
```

**测试文件**:
- ✅ `src/api/scene.spec.js` - 场景管理API测试(15+用例)
- ✅ `src/api/rule.spec.js` - 规则配置API测试(12+用例)
- ✅ `src/api/account.spec.js` - 账户管理API测试(14+用例)
- ✅ `src/utils/request.spec.js` - HTTP请求封装测试(16+用例)
- ✅ `src/views/scene/List.spec.js` - 场景列表组件测试(18+用例)

**总计**: 75+ 个测试用例

详细测试文档: [web/admin-ui/TESTING.md](./web/admin-ui/TESTING.md)

## 部署

### Docker部署(推荐) 🐳

**快速启动(3步)**:
```bash
# 1. 配置环境变量
cp .env.example .env
# 编辑.env文件,修改数据库密码等配置

# 2. 启动所有服务
docker-compose up -d

# 3. 初始化数据库
docker exec -i ipms-mysql mysql -uroot -p${MYSQL_ROOT_PASSWORD} ipms < scripts/sql/init/init-database.sql
```

**访问地址**:
- 管理后台: http://localhost
- Admin API: http://localhost:8081
- Realtime API: http://localhost:8082

详细部署文档: [docs/deployment/积分系统-Docker部署指南.md](./docs/deployment/积分系统-Docker部署指南.md)

### 本地开发环境

## 注意事项

1. **数据库连接**: 修改 `configs/*.yaml` 中的database配置
2. **Redis连接**: 修改 `configs/realtime.yaml` 中的redis配置
3. **签名密钥**: 生产环境务必修改 `signature.secret_key`
4. **Casbin鉴权**: Admin服务需要集成Casbin权限控制(待实现)
5. **配置文件**: 已使用Viper从YAML文件读取参数,不再硬编码
6. **Docker部署**: 推荐使用docker-compose一键部署所有服务
7. **数据备份**: 每日自动备份脚本见docs/deployment/积分系统-Docker部署指南.md

## 后续优化方向

1. ✅ **单元测试**: PointService/RuleEngineService测试已完成
2. ✅ **Docker部署**: docker-compose + Dockerfile已实现
3. ✅ **分区维护**: SQL存储过程已实现
4. 🚧 **Casbin权限**: Admin服务需要集成Casbin鉴权中间件
5. 🚧 **规则编辑器**: 前端可视化规则树编辑器(开发中)
6. 🚧 **账户管理页面**: 变动流水查询页面(待完善)
7. ⏳ **Prometheus监控**: 添加性能指标采集
8. ⏳ **分布式追踪**: Jaeger/Zipkin集成
9. ⏳ **API文档**: Swagger自动生成

## License

MIT