136 lines
4.4 KiB
Markdown
136 lines
4.4 KiB
Markdown
# 短链系统实现说明
|
||
|
||
## 一、功能说明
|
||
|
||
短链系统用于生成推广链接和邀请链接的短链，格式为：`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`（如果不传则使用默认值）
|
||
|