ycc-proxy-server/邀请码使用历史功能说明.md

邀请码使用历史功能说明

问题描述

当前系统中，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 迁移

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

第二步：生成 Model

# 生成 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 中添加：

AgentInviteCodeUsageModel model.AgentInviteCodeUsageModel

并在 NewServiceContext 中初始化：

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 查询示例

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

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

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

-- 方式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;

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

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