v1.0

短链系统实现说明.md

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