v1.0

邀请码使用历史功能说明.md

@@ -0,0 +1,107 @@
+# 邀请码使用历史功能说明
+
+## 问题描述
+
+当前系统中，`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;
+```
+