# 邀请码使用历史功能说明

## 问题描述

当前系统中，`agent_invite_code` 表只记录了最后一次使用情况（`used_user_id`, `used_agent_id`, `used_time`）。对于普通邀请码（可以无限使用），每次使用都会覆盖之前的记录，导致：

1. **无法统计**：无法统计每个邀请码总共邀请了多少代理
2. **无法查询**：无法查询某个代理是通过哪个邀请码成为代理的
3. **历史丢失**：无法保留完整的使用历史记录

## 解决方案

### 1. 创建使用历史表

创建 `agent_invite_code_usage` 表，记录每次邀请码使用的详细信息。

### 2. 在 agent 表中添加字段

在 `agent` 表中添加 `invite_code_id` 字段，便于直接查询代理是通过哪个邀请码成为的。

## 实施步骤

### 第一步：执行 SQL 迁移

```bash
# 执行 SQL 文件
mysql -u root -p your_database < deploy/sql/add_invite_code_usage_table.sql
```

### 第二步：生成 Model

```bash
# 生成 AgentInviteCodeUsage Model
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" \
  -table="agent_invite_code_usage" \
  -dir="app/main/model" \
  -cache=true \
  --style=goZero \
  --home="./deploy/template"
```

### 第三步：更新 ServiceContext

在 `app/main/api/internal/svc/servicecontext.go` 中添加：

```go
AgentInviteCodeUsageModel model.AgentInviteCodeUsageModel
```

并在 `NewServiceContext` 中初始化：

```go
AgentInviteCodeUsageModel: model.NewAgentInviteCodeUsageModel(db, cacheConf),
```

### 第四步：更新逻辑代码

更新以下文件，在使用邀请码时记录使用历史：

1. `app/main/api/internal/logic/agent/registerbyinvitecodelogic.go`
2. `app/main/api/internal/logic/agent/applyforagentlogic.go`

### 第五步：更新 Agent Model（可选）

如果 agent 表添加了 `invite_code_id` 字段，需要重新生成 Agent Model 或手动更新。

## 功能说明

### 统计功能

- **统计邀请码邀请数量**：通过 `agent_invite_code_usage` 表，可以统计每个邀请码邀请了多少代理
- **查询代理来源**：可以通过 `agent.invite_code_id` 或 `agent_invite_code_usage.agent_id` 查询代理是通过哪个邀请码成为的

### 数据完整性

- **保留完整历史**：每次使用邀请码都会记录一条使用历史，不会丢失
- **支持多次使用**：普通邀请码可以多次使用，每次使用都会记录

## API 查询示例

### 查询某个邀请码邀请了多少代理

```sql
SELECT COUNT(*) FROM agent_invite_code_usage 
WHERE invite_code_id = ? AND del_state = 0;
```

### 查询某个代理是通过哪个邀请码成为的

```sql
-- 方式1：通过 agent 表（如果添加了 invite_code_id 字段）
SELECT invite_code_id FROM agent WHERE id = ?;

-- 方式2：通过使用历史表
SELECT invite_code_id, code FROM agent_invite_code_usage 
WHERE agent_id = ? AND del_state = 0 
ORDER BY used_time DESC LIMIT 1;
```

### 查询某个邀请码的所有使用记录

```sql
SELECT * FROM agent_invite_code_usage 
WHERE invite_code_id = ? AND del_state = 0 
ORDER BY used_time DESC;
```