# 短链系统实现说明

## 一、功能说明

短链系统用于生成推广链接和邀请链接的短链，格式为：`https://推广域名/s/{shortCode}`

### 支持两种类型
1. **推广报告（promotion）**：类型值为1
   - 用于推广产品查询服务
   - 前端传入目标地址，如：`/agent/promotionInquire/{linkIdentifier}`
   
2. **邀请好友（invite）**：类型值为2
   - 用于邀请用户成为代理
   - 前端传入目标地址，如：`/register?invite_code=XXXXX`

### 工作流程
1. 前端调用接口时传入 `target_path`（目标地址）
2. 后端生成6位随机短链标识
3. 短链存储在 `agent_short_link` 表中，包含类型和目标地址
4. 返回短链URL：`https://推广域名/s/{shortCode}`
5. 用户访问短链时，根据 `target_path` 重定向到对应页面

## 二、执行步骤

### 1. 执行SQL创建表

```bash
# 执行SQL文件创建短链表
mysql -u root -p your_database < deploy/sql/add_agent_short_link_table.sql
```

或者直接在数据库客户端执行 `deploy/sql/add_agent_short_link_table.sql` 文件。

### 2. 生成Model

使用goctl工具生成Model代码：

```bash
# Windows PowerShell
cd ycc-proxy-server
goctl model mysql datasource -url="ycc:5vg67b3UNHu8@tcp(127.0.0.1:21001)/ycc" -table="agent_short_link" -dir="./app/main/model" --home="./deploy/template" -cache=true --style=goZero

# Linux/Mac
cd ycc-proxy-server
goctl model mysql datasource -url="ycc:5vg67b3UNHu8@tcp(127.0.0.1:21001)/ycc" -table="agent_short_link" -dir="./app/main/model" --home="./deploy/template" -cache=true --style=goZero
```

### 3. 代码已实现

代码已经实现完成，生成Model后即可使用。

### 4. 配置推广域名

在配置文件中设置推广域名：

```yaml
# main.yaml 或 main.dev.yaml
Promotion:
    PromotionDomain: "https://promo.example.com"  # 推广域名
```

## 三、接口说明

### 短链重定向接口

- **路径**: `/s/{shortCode}`
- **方法**: `GET`
- **说明**: 不需要 `/api/v1` 前缀，直接放在根路径
- **功能**: 根据短链标识查询对应的推广链接，重定向到推广页面

### 生成推广链接接口

- **路径**: `/api/v1/agent/generating_link`
- **方法**: `POST`
- **请求参数**:
  ```json
  {
    "product_id": 1,
    "set_price": 10.00,
    "target_path": "/agent/promotionInquire/{linkIdentifier}"  // 前端传入目标地址
  }
  ```
- **返回**: 
  ```json
  {
    "link_identifier": "加密的链接标识",
    "full_link": "https://推广域名/s/xxxxxx"
  }
  ```

### 生成邀请链接接口

- **路径**: `/api/v1/agent/invite_link`
- **方法**: `GET`
- **请求参数**:
  - `invite_code`: 邀请码
  - `target_path`: 目标地址（可选，默认：`/register?invite_code=xxx`）
- **返回**: 
  ```json
  {
    "invite_link": "https://推广域名/s/xxxxxx"
  }
  ```

## 四、数据库表结构

### agent_short_link 表

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键ID |
| type | tinyint | 类型：1=推广报告，2=邀请好友 |
| link_id | bigint | 推广链接ID（关联agent_link表，仅推广报告使用） |
| invite_code_id | bigint | 邀请码ID（关联agent_invite_code表，仅邀请好友使用） |
| link_identifier | varchar(200) | 推广链接标识（加密，仅推广报告使用） |
| invite_code | varchar(50) | 邀请码（仅邀请好友使用） |
| short_code | varchar(20) | 短链标识（6位随机字符串） |
| target_path | varchar(500) | 目标地址（前端传入，如：/agent/promotionInquire/xxx） |
| promotion_domain | varchar(200) | 推广域名 |
| create_time | datetime | 创建时间 |
| update_time | datetime | 更新时间 |
| delete_time | datetime | 删除时间 |
| del_state | tinyint | 删除状态：0=未删除，1=已删除 |
| version | bigint | 版本号（乐观锁） |

## 五、注意事项

1. 短链标识是6位随机字符串（大小写字母+数字）
2. 同一推广链接或邀请码同一类型只会生成一个短链（通过唯一索引保证）
3. 短链重定向使用 `target_path`（相对路径），域名切换由服务器配置处理
4. 如果推广域名未配置，生成短链时会返回空字符串
5. **前端必须传入 `target_path` 参数**，后端只负责确定推广域名并生成短链
6. 推广报告类型：前端传入 `/agent/promotionInquire/{linkIdentifier}`
7. 邀请好友类型：前端传入 `/register?invite_code=XXXXX`（如果不传则使用默认值）