team/ycc-proxy-server

Fork 0

Files

liangzai 08ff223ff8 v1.0

2025-12-02 19:57:10 +08:00

4.4 KiB

Raw Blame History

短链系统实现说明

一、功能说明

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

支持两种类型

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

工作流程

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

二、执行步骤

1. 执行SQL创建表

# 执行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代码：

# 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. 配置推广域名

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

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

三、接口说明

短链重定向接口

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

生成推广链接接口

路径: /api/v1/agent/generating_link
方法: POST

请求参数:

{
  "product_id": 1,
  "set_price": 10.00,
  "target_path": "/agent/promotionInquire/{linkIdentifier}"  // 前端传入目标地址
}

{
  "link_identifier": "加密的链接标识",
  "full_link": "https://推广域名/s/xxxxxx"
}

生成邀请链接接口

路径: /api/v1/agent/invite_link
方法: GET
请求参数:
- invite_code: 邀请码
- target_path: 目标地址（可选，默认：/register?invite_code=xxx）

{
  "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	版本号（乐观锁）

五、注意事项

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

4.4 KiB Raw Blame History Unescape Escape