108 lines
3.1 KiB
Markdown
108 lines
3.1 KiB
Markdown
# 邀请码使用历史功能说明
|
||
|
||
## 问题描述
|
||
|
||
当前系统中，`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;
|
||
```
|
||
|