ycc-proxy-server/deploy/sql/generate_agent_models.md

# 生成新代理系统Model说明

## 一、执行数据库迁移

### 1.1 备份数据库（重要！）

```bash
# 备份整个数据库
mysqldump -u root -p your_database > backup_before_migration.sql

# 或者只备份agent相关表
mysqldump -u root -p your_database agent agent_audit agent_closure agent_commission agent_wallet agent_link agent_order agent_rewards agent_membership_config agent_product_config agent_real_name agent_withdrawal agent_withdrawal_tax agent_withdrawal_tax_exemption agent_active_stat agent_platform_deduction agent_commission_deduction agent_membership_recharge_order agent_membership_user_config > agent_tables_backup.sql
```

### 1.2 执行迁移SQL

```bash
# 方式1：使用mysql命令行
mysql -u root -p your_database < deploy/sql/agent_system_migration.sql

# 方式2：使用数据库客户端工具（如Navicat、DBeaver等）
# 直接执行 deploy/sql/agent_system_migration.sql 文件
```

## 二、生成Model代码

### 2.1 方式一：使用脚本批量生成（推荐）

**Windows (PowerShell):**

```powershell
# 修改脚本中的数据库配置
# 然后执行（需要安装goctl工具）
cd deploy/sql
bash generate_agent_models.sh
```

**Linux/Mac:**

```bash
# 修改脚本中的数据库配置
chmod +x deploy/sql/generate_agent_models.sh
cd deploy/sql
./generate_agent_models.sh
```

### 2.2 方式二：使用goctl命令逐个生成

```bash
# 1. agent表
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" -table="agent" -dir="app/main/model" -cache=true --style=goZero --home="./deploy/template"

# 2. agent_audit表
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" -table="agent_audit" -dir="app/main/model" -cache=true --style=goZero --home="./deploy/template"

# 3. agent_wallet表
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" -table="agent_wallet" -dir="app/main/model" -cache=true --style=goZero --home="./deploy/template"

# 4. agent_relation表（新表，替代agent_closure）
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" -table="agent_relation" -dir="app/main/model" -cache=true --style=goZero --home="./deploy/template"

# 5. agent_link表
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" -table="agent_link" -dir="app/main/model" -cache=true --style=goZero --home="./deploy/template"

# 6. agent_order表
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" -table="agent_order" -dir="app/main/model" -cache=true --style=goZero --home="./deploy/template"

# 7. agent_commission表
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" -table="agent_commission" -dir="app/main/model" -cache=true --style=goZero --home="./deploy/template"

# 8. agent_rebate表（新表）
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" -table="agent_rebate" -dir="app/main/model" -cache=true --style=goZero --home="./deploy/template"

# 9. agent_upgrade表（新表）
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" -table="agent_upgrade" -dir="app/main/model" -cache=true --style=goZero --home="./deploy/template"

# 10. agent_withdrawal表
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" -table="agent_withdrawal" -dir="app/main/model" -cache=true --style=goZero --home="./deploy/template"

# 11. agent_config表（新表）
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" -table="agent_config" -dir="app/main/model" -cache=true --style=goZero --home="./deploy/template"

# 12. agent_product_config表
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" -table="agent_product_config" -dir="app/main/model" -cache=true --style=goZero --home="./deploy/template"

# 13. agent_real_name表
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" -table="agent_real_name" -dir="app/main/model" -cache=true --style=goZero --home="./deploy/template"

# 14. agent_withdrawal_tax表
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" -table="agent_withdrawal_tax" -dir="app/main/model" -cache=true --style=goZero --home="./deploy/template"
```

### 2.3 方式三：使用goctl一次性生成所有表

```bash
# 生成所有agent相关表的Model
goctl model mysql datasource -url="root:password@tcp(localhost:3306)/database" -table="agent,agent_audit,agent_wallet,agent_relation,agent_link,agent_order,agent_commission,agent_rebate,agent_upgrade,agent_withdrawal,agent_config,agent_product_config,agent_real_name,agent_withdrawal_tax" -dir="app/main/model" -cache=true --style=goZero --home="./deploy/template"
```

## 三、表结构变化说明

### 3.1 删除的旧表

以下表在新系统中已删除，不再需要：

- `agent_closure` → 被 `agent_relation` 替代
- `agent_commission_deduction` → 新系统不需要
- `agent_rewards` → 新系统不需要
- `agent_membership_config` → 新系统不需要
- `agent_membership_recharge_order` → 新系统不需要
- `agent_membership_user_config` → 新系统不需要
- `agent_platform_deduction` → 新系统不需要
- `agent_active_stat` → 新系统不需要
- `agent_withdrawal_tax_exemption` → 新系统不需要

### 3.2 新增的表

- `agent_relation` - 替代 `agent_closure`，支持关系脱离
- `agent_rebate` - 等级加成返佣记录表
- `agent_upgrade` - 代理升级记录表
- `agent_config` - 代理系统配置表

### 3.3 结构变化的表

以下表结构有变化，需要重新生成Model：

- `agent` - 等级字段改为数值型，新增 `team_leader_id`
- `agent_audit` - 新增 `ancestor_mobile`、`audit_user_id` 字段
- `agent_wallet` - 字段保持不变
- `agent_link` - 新增唯一约束
- `agent_order` - 新增 `order_amount`、`process_status` 等字段
- `agent_commission` - 字段保持不变
- `agent_product_config` - 字段保持不变
- `agent_real_name` - 新增 `audit_user_id` 字段
- `agent_withdrawal` - 字段保持不变
- `agent_withdrawal_tax` - 字段保持不变

## 四、生成后的文件结构

生成后，会在 `app/main/model` 目录下创建以下文件：

```
app/main/model/
├── agentModel.go              # agent表Model（自定义方法）
├── agentModel_gen.go          # agent表Model（自动生成）
├── agentAuditModel.go         # agent_audit表Model（自定义方法）
├── agentAuditModel_gen.go     # agent_audit表Model（自动生成）
├── agentWalletModel.go         # agent_wallet表Model（自定义方法）
├── agentWalletModel_gen.go    # agent_wallet表Model（自动生成）
├── agentRelationModel.go      # agent_relation表Model（自定义方法，新）
├── agentRelationModel_gen.go  # agent_relation表Model（自动生成，新）
├── agentLinkModel.go          # agent_link表Model（自定义方法）
├── agentLinkModel_gen.go      # agent_link表Model（自动生成）
├── agentOrderModel.go         # agent_order表Model（自定义方法）
├── agentOrderModel_gen.go     # agent_order表Model（自动生成）
├── agentCommissionModel.go    # agent_commission表Model（自定义方法）
├── agentCommissionModel_gen.go # agent_commission表Model（自动生成）
├── agentRebateModel.go        # agent_rebate表Model（自定义方法，新）
├── agentRebateModel_gen.go    # agent_rebate表Model（自动生成，新）
├── agentUpgradeModel.go       # agent_upgrade表Model（自定义方法，新）
├── agentUpgradeModel_gen.go   # agent_upgrade表Model（自动生成，新）
├── agentWithdrawalModel.go    # agent_withdrawal表Model（自定义方法）
├── agentWithdrawalModel_gen.go # agent_withdrawal表Model（自动生成）
├── agentConfigModel.go        # agent_config表Model（自定义方法，新）
├── agentConfigModel_gen.go    # agent_config表Model（自动生成，新）
├── agentProductConfigModel.go # agent_product_config表Model（自定义方法）
├── agentProductConfigModel_gen.go # agent_product_config表Model（自动生成）
├── agentRealNameModel.go      # agent_real_name表Model（自定义方法）
├── agentRealNameModel_gen.go  # agent_real_name表Model（自动生成）
├── agentWithdrawalTaxModel.go # agent_withdrawal_tax表Model（自定义方法）
└── agentWithdrawalTaxModel_gen.go # agent_withdrawal_tax表Model（自动生成）
```

## 五、注意事项

1. **备份数据**：执行迁移前务必备份数据库
2. **测试环境**：建议先在测试环境执行，验证无误后再在生产环境执行
3. **代码兼容**：生成新Model后，需要更新相关业务代码以适配新的表结构
4. **删除旧Model**：生成新Model后，需要删除旧的Model文件（如 `agentClosureModel.go`）
5. **更新ServiceContext**：需要在 `svc/servicecontext.go` 中更新Model初始化代码

## 六、验证

生成Model后，请验证：

1. 所有新表都有对应的Model文件
2. Model文件可以正常编译
3. 数据库连接正常
4. 基本的CRUD操作可以正常执行