# CRS

**Repository Path**: bynick_admin/crs

## Basic Information

- **Project Name**: CRS
- **Description**: 1. 项目摘要
1.1 背景与目标
为验证企业间碳配额交易的核心业务流程，开发一个极简Demo系统。系统仅支持碳配额挂牌交易，实现从“发布出售单”到“购买成交”的闭环，不包含复杂的履约管理、价格指数、多角色审批等功能。

1.2 核心价值
轻量验证：快速验证交易匹配逻辑。

流程闭环：展示碳配额从出售方转移到购买方的全流程。

极简操作：仅需3个页面（挂牌市场、我的持仓、交易记录）即可完成演示。
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-02
- **Last Updated**: 2026-04-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 碳配额交易系统

## 项目简介

这是一个基于 .NET Core 9.0 和 Vue 3 的碳配额交易系统，实现了碳配额的挂牌交易功能，包括发布出售单、购买成交、撤单等核心功能。

## 技术栈

### 后端
- .NET Core 9.0
- SqlSugarCore
- MySQL
- Redis (分布式锁)
- Swagger
- 三主三从，基于nginx负载均衡

### 前端
- Vue 3
- Element Plus
- Vue Router
- Axios

## 项目结构

```
crs/
├── src/
│   ├── backend/  # 后端代码
│   └── web/      # 前端代码
```

## 后端实现

### 核心功能
1. 挂牌出售：企业可以发布碳配额出售单
2. 购买功能：企业可以购买其他企业发布的出售单
3. 撤单功能：卖方可以在成交前撤销自己的挂单
4. 交易记录：记录所有已成交的交易
5. 持仓查询：查询企业的碳配额持有量和资金余额
6. 自动化交易：支持三种智能匹配算法的自动交易撮合
7. 价格预测：基于历史交易数据预测碳配额价格趋势

### 数据库设计
- user 表：存储企业信息，包括资金余额和碳配额持有量
- sell_order 表：存储卖单信息
- buy_order 表：存储买单信息
- trade_log 表：存储交易记录

## 前端实现

### 页面
1. 挂牌市场：展示未成交卖单，支持创建卖单和购买操作
2. 我的持仓：展示企业的碳配额持有量和资金余额
3. 交易记录：展示所有已成交的交易
4. 交易详情：展示单个交易的详细信息
5. 价格预测：展示碳配额价格预测趋势

## 运行指南

### 后端运行
1. 确保安装了 .NET Core 9.0 SDK
2. 确保 MySQL 数据库服务已启动
3. 确保 Redis 服务已启动
4. 修改 `backend/Config/DatabaseConfig.cs` 中的数据库连接字符串
5. 进入 `backend` 目录，运行 `dotnet run` 命令启动后端服务

### 前端运行
1. 确保安装了 Node.js
2. 进入 `web` 目录，运行 `npm install` 安装依赖
3. 运行 `npm run dev` 启动前端开发服务器
4. 在浏览器中访问 `http://localhost:3000` 查看前端页面

## 初始数据

系统启动时会自动创建以下初始数据：
- 控排企业A：资金余额 100000 元，碳配额持有量 100 吨
- 控排企业B：资金余额 100000 元，碳配额持有量 0 吨

## 业务与技术背景

### 业务场景
在碳交易市场中，控排企业需要根据自身的碳排放情况和配额持有量，在市场上进行碳配额的买卖交易。传统的碳交易方式存在以下痛点：

1. **交易效率低下**：人工撮合交易耗时长，市场流动性差
2. **价格发现困难**：缺乏有效的价格形成机制，买卖双方难以达成一致
3. **交易风险高**：资金与配额交割不同步，存在违约风险
4. **对账复杂**：交易记录与资金、配额变动难以实时核对

### 核心痛点解决方案
本系统针对上述痛点，提供了以下核心功能：

1. **自动化交易撮合**：支持三种智能匹配算法，提高交易效率
   - 稳定匹配算法（Gale-Shapley）：优先考虑"价差×交易量"的综合效用
   - 双向拍卖博弈模型：寻找贝叶斯纳什均衡价格
   - 图论优化模型：在多重约束下枚举可行交易路径

2. **实时价格发现**：通过买卖订单簿自动形成市场价格

3. **价格预测**：基于历史交易数据，使用时间序列分析预测碳配额价格趋势，帮助企业做出更明智的交易决策

4. **原子性交易保障**：使用分布式锁 + 数据库事务 + 乐观锁三重保障机制

5. **自动对账功能**：实时验证资金和配额的一致性

## 架构决策

### 技术选型

#### 后端技术栈
- **.NET Core 9.0**：选择最新的 LTS 版本，提供更好的性能和开发体验
- **SqlSugarCore**：轻量级 ORM，相比 Entity Framework Core 更灵活，适合快速开发
- **MySQL**：成熟的关系型数据库，支持事务和行级锁
- **Redis**：用于分布式锁实现，确保并发交易的安全性

#### 前端技术栈
- **Vue 3**：现代化的前端框架，组合式 API 提供更好的代码组织
- **Element Plus**：成熟的企业级 UI 组件库
- **Vite**：快速的开发服务器和构建工具

### 核心架构设计

#### 1. 并发控制方案
**选择**：Redis 分布式锁 + 数据库事务 + 乐观锁（RowVersion）

**权衡（Trade-offs）**：
- ✅ **优势**：
  - 三重保障机制确保交易的原子性和一致性
  - 乐观锁避免了长时间持有数据库锁
  - Redis 分布式锁支持水平扩展
- ❌ **劣势**：
  - 增加了系统复杂度
  - Redis 故障会影响交易系统可用性
  - 需要处理锁超时等边界情况

**替代方案考虑**：
- 纯数据库锁：性能较差，容易成为瓶颈
- 消息队列：增加系统复杂度，需要引入消息中间件

#### 2. 交易匹配算法
**选择**：提供三种可选算法

**权衡（Trade-offs）**：
- ✅ **优势**：
  - 稳定匹配算法：确保交易双方满意度，平抑碳价波动
  - 双向拍卖算法：快速发现均衡价格，适合高流动性市场
  - 图论优化算法：考虑多重约束（预算、风险），更贴近实际场景
- ❌ **劣势**：
  - 算法复杂度较高，需要根据市场情况选择
  - 图论算法在大数据量下性能可能下降

#### 3. 价格预测模型
**选择**：基于历史交易数据的时间序列分析

**权衡（Trade-offs）**：
- ✅ **优势**：
  - 为企业提供价格参考，辅助决策
  - 基于实际交易数据，预测结果更可靠
  - 实现简单，计算开销小
- ❌ **劣势**：
  - 仅基于历史数据，无法预测突发因素影响
  - 预测精度受数据量和质量影响
  - 长期预测准确性有限

#### 4. 数据一致性保障
**选择**：数据库事务 + 对账服务

**权衡（Trade-offs）**：
- ✅ **优势**：
  - ACID 特性确保数据一致性
  - 对账服务提供事后验证机制
  - 支持问题追溯和修复
- ❌ **劣势**：
  - 对账服务需要额外计算资源
  - 发现问题时需要人工干预

### 系统架构图
```
┌─────────────────────────────────────────────────┐
│                   前端层 (Vue 3)                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │ 挂牌市场  │  │ 我的持仓  │  │ 交易记录  │      │
│  └──────────┘  └──────────┘  └──────────┘      │
└─────────────────────────────────────────────────┘
                      ↓ HTTP/REST API
┌─────────────────────────────────────────────────┐
│                 后端层 (.NET Core)                │
│  ┌──────────────────────────────────────────┐  │
│  │           Controllers (API 层)            │  │
│  └──────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────┐  │
│  │          Services (业务逻辑层)             │  │
│  │  ┌─────────────┐  ┌──────────────────┐   │  │
│  │  │ TradeService│  │ AutoTradingService│   │  │
│  │  └─────────────┘  └──────────────────┘   │  │
│  │  ┌──────────────────────────────────┐    │  │
│  │  │ TradingAlgorithmService (算法层)  │    │  │
│  │  └──────────────────────────────────┘    │  │
│  │  ┌───────────────────────┐              │  │
│  │  │ PricePredictionService│              │  │
│  │  └───────────────────────┘              │  │
│  └──────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────┐  │
│  │              DAL (数据访问层)              │  │
│  └──────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘
         ↓                              ↓
┌──────────────────┐          ┌──────────────────┐
│   MySQL 数据库    │          │   Redis 缓存     │
│  - 用户数据       │          │  - 分布式锁      │
│  - 订单数据       │          │                  │
│  - 交易记录       │          │                  │
└──────────────────┘          └──────────────────┘
```

## AI 协作说明

本系统开发过程中使用了 AI 工具（trae） 进行辅助开发，具体如下：

### AI 辅助的部分

1. **交易算法实现**
   - AI 辅助实现了三种交易匹配算法的核心逻辑
   - 提供了 Gale-Shapley 算法的初始实现思路
   - **关键调整**：根据碳交易市场的实际特点，调整了效用计算公式，加入了"价差×交易量"的综合考量

2. **价格预测模型**
   - AI 辅助实现了基于历史交易数据的价格预测算法
   - 提供了时间序列分析的基础实现
   - **关键调整**：根据碳交易市场的特点，优化了预测模型参数，提高了短期预测的准确性

3. **代码注释和文档**
   - AI 辅助生成了部分代码注释
   - **关键调整**：补充了业务背景说明，使注释更贴近实际业务场景

4. **前端页面布局**
   - AI 辅助生成了 Vue 组件的基础结构
   - **关键调整**：优化了用户体验，增加了加载状态和错误提示

### 人工开发的部分

1. **业务逻辑设计**：根据碳交易市场的实际需求，设计了交易流程和规则
2. **数据库设计**：设计了用户、订单、交易记录等核心表结构
3. **API 接口设计**：定义了 RESTful API 的接口规范
4. **分布式锁和乐观锁**：设计了并发控制机制，确保交易的原子性和一致性

### AI 生成内容的验证

所有 AI 生成的代码都经过以下验证：
1. ✅ 代码逻辑审查：确保符合业务需求
2. ✅ 性能测试：验证并发场景下的正确性
3. ✅ 边界条件测试：验证异常情况的处理

## 验证指南

### 环境准备

#### 必备软件
- .NET Core 9.0 SDK
- Node.js (v16 或更高版本)
- MySQL 8.0
- Redis 6.0

#### 数据库配置
1. 创建 MySQL 数据库：
```sql
CREATE DATABASE carbon_trading_system;
```

2. 修改后端配置文件 `src/backend/appsettings.json`：
```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=carbon_trading_system;User=root;Password=your_password;"
  },
  "Redis": {
    "ConnectionString": "localhost:6379"
  }
}
```

### 启动步骤

#### 1. 启动后端服务
```bash
cd src/backend
dotnet restore
dotnet run
```

后端服务将在 `http://localhost:5000` 启动，Swagger 文档地址：`http://localhost:5000/swagger`

#### 2. 启动前端服务
```bash
cd src/web
npm install
npm run dev
```

前端服务将在 `http://localhost:3000` 启动

### 功能验证

#### 场景一：基础交易流程验证

**步骤**：
1. 使用初始账号登录系统：
   - 控排企业A：用户名 `company_a`，密码 `123456`
   - 控排企业B：用户名 `company_b`，密码 `123456`

2. 企业A 发布卖单：
   - 进入"挂牌市场"页面
   - 点击"发布卖单"
   - 输入数量：10 吨，价格：50 元/吨
   - 提交卖单

3. 企业B 购买：
   - 切换到企业B 账号登录
   - 在"挂牌市场"找到企业A 的卖单
   - 点击"购买"，输入购买数量：10 吨
   - 确认购买

**预期结果**：
- ✅ 交易成功，生成交易记录
- ✅ 企业A 资金增加 500 元，配额减少 10 吨
- ✅ 企业B 资金减少 500 元，配额增加 10 吨
- ✅ 卖单状态变为"已成交"

#### 场景二：并发交易验证

**步骤**：
1. 企业A 发布卖单：数量 10 吨，价格 50 元/吨
2. 同时使用两个浏览器窗口，分别以企业B 和企业C 的账号登录
3. 两个窗口同时尝试购买同一卖单（数量均为 10 吨）

**预期结果**：
- ✅ 只有一个购买请求成功
- ✅ 另一个购买请求失败，提示"卖单已成交或数量不足"
- ✅ 数据一致性：资金和配额变动正确

#### 场景三：自动交易匹配验证

**步骤**：
1. 企业A 发布卖单：数量 20 吨，价格 45 元/吨
2. 企业B 发布买单：数量 15 吨，价格 50 元/吨
3. 调用自动交易 API：
```bash
curl -X POST http://localhost:5000/api/auto-trading/execute?algorithm=stable
```

**预期结果**：
- ✅ 系统自动匹配买卖订单
- ✅ 成交价格在买卖价格之间
- ✅ 生成交易记录

#### 场景四：对账功能验证

**步骤**：
1. 执行多笔交易
2. 调用对账 API：
```bash
curl http://localhost:5000/api/reconciliation/reconcile
```

**预期结果**：
- ✅ 返回对账结果：`"isBalanced": true`
- ✅ 无资金或配额差异

#### 场景五：价格预测功能验证

**步骤**：
1. 执行多笔交易，产生足够的历史交易数据
2. 调用价格预测 API：
```bash
curl http://localhost:5000/api/auto-trading/predict-price
```

**预期结果**：
- ✅ 返回预测的碳配额价格
- ✅ 预测价格基于历史交易数据，具有合理性
- ✅ 前端"价格预测"页面显示价格趋势图

### 性能验证

#### 并发压力测试

使用 Apache Bench 或 JMeter 进行压力测试：

```bash
# 安装 Apache Bench
# Ubuntu: sudo apt-get install apache2-utils
# Windows: 下载 Apache 二进制包

# 并发 100 个请求，测试购买接口
ab -n 1000 -c 100 -p purchase.json -T application/json \
   http://localhost:5000/api/trade/purchase
```

**预期结果**：
- ✅ 所有请求成功或失败都有明确的响应
- ✅ 数据库中资金和配额数据一致
- ✅ 无死锁或超时错误


<<<<<<< HEAD
=======
1. 本系统为演示版本，仅实现了核心功能，未包含复杂的业务逻辑
2. 系统使用 Redis 实现分布式锁、乐观锁，确保交易的原子性
3. 系统使用数据库事务确保数据的一致性
4. 前端页面为后台管理风格，适配 PC 端
>>>>>>> aa87fe3466572407202ae5be35ce466b790317ee