HI-VPN/hi-server
4
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

新功能: 还原 v1/public/user/invite_sales 接口 + promo schema 修复迁移
Build docker and publish / build (20.15.1) (push) Failing after 13m47s
Details
Build docker and publish / build (20.15.1) (pull_request) Failing after 15m7s
Details

Browse Source 
- 还原 /v1/public/user/invite_sales 接口及 /invite/sales 别名（与 invite_records 并存）
  逻辑/handler/types 与 197fed7d 删除前版本完全一致，按 fefbd4f5 新 routes 结构注册
- 新增迁移 02155_promo_schema_fix: 幂等修复 subscribe_promo / order 列类型与索引偏差
- 同步 etc/ppanel.yaml 数据库连接配置
- 补齐相关需求与设计文档
This commit is contained in:
shanshanzhong
2026-05-28 20:46:37 -07:00
parent fefbd4f56a
commit 3e265bd837
12 changed files with 2418 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apis/public/user.api
+20
View File
@@ -218,6 +218,22 @@ type (
Total int64 `json:"total"`
List []InviteRecord `json:"list"`
}
GetInviteSalesRequest {
Page int `form:"page"`
Size int `form:"size"`
StartTime int64 `form:"start_time"`
EndTime int64 `form:"end_time"`
}
InvitedUserSale {
Amount float64 `json:"amount"`
UpdatedAt int64 `json:"updated_at"`
UserHash string `json:"user_hash"`
ProductName string `json:"product_name"`
}
GetInviteSalesResponse {
Total int64 `json:"total"`
List []InvitedUserSale `json:"list"`
}
GetSubscribeStatusRequest {
Email string `form:"email" json:"email" validate:"omitempty,email"`
}
@@ -402,6 +418,10 @@ service ppanel {
@handler GetInviteRecords
get /invite_records (GetInviteRecordsRequest) returns (GetInviteRecordsResponse)
@doc "Get Invite Sales"
@handler GetInviteSales
get /invite_sales (GetInviteSalesRequest) returns (GetInviteSalesResponse)
@doc "Get Subscribe Status"
@handler GetSubscribeStatus
post /subscribe_status (GetSubscribeStatusRequest) returns (GetSubscribeStatusResponse)
doc/app-invite-and-subscribe-discount-requirements-zh.md
+559
View File
@@ -0,0 +1,559 @@
# App 邀请列表与商品套餐折扣需求梳理
本文基于当前 `ppanel-server` 代码现状，对以下两个需求做整理：
1. App 需要一个“邀请列表/邀请记录”接口。
2. 商品套餐需要补充“折扣信息”，当存在折扣时，App 需要做样式展示，并支持用户继续下单购买。
目标是帮助产品、前端、后端快速统一口径，明确：
- 现在已有哪些接口可以复用
- 哪些地方确实需要新增
- “接口增加三个字段”更适合加在哪一层
---
## 1. 需求结论
### 1.1 邀请列表
当前公开侧已经有一部分邀请能力，但**没有一个完全匹配“App 邀请记录列表”语义的公开接口**。
现状：
- 已有 `GET /v1/public/user/affiliate/list`
- 能返回“我邀请了哪些用户”
- 但字段较少，只包含基础信息
- 已有 `GET /v1/public/user/invite_sales`
- 返回的是“被邀请用户的成交订单记录”
- 不是“邀请用户记录列表”
- 已有 `GET /v1/public/user/invite_stats`
- 返回邀请统计
- 不是列表
结论：
- 如果 App 只是要展示“我邀请了哪些人”，`/affiliate/list` 可以复用。
- 如果 App 需要展示“邀请时间、是否购买、购买次数、带来的佣金/赠送天数”等完整邀请记录，则**建议新增一个公开接口**。
### 1.2 商品套餐折扣
当前公开侧套餐列表接口 `GET /v1/public/subscribe/list` **已经返回 `discount` 字段**，下单预览接口 `POST /v1/public/order/pre` 也已经支持折扣计算。
现状：
- 套餐列表已有折扣规则数组 `discount`
- 预下单接口已有：
- 原价 `price`
- 实付 `amount`
- 折扣金额 `discount`
- 活动优惠 `promo_discount`
- 优惠券减免 `coupon_discount`
- 手续费 `fee_amount`
结论：
- 后端**不是完全没有折扣能力**，而是“已经有计算能力，但 App 展示层使用起来不够直接”。
- 如果需求明确要求“接口增加三个字段”，**更推荐补在套餐列表返回的 `discount[]` 子项里**，而不是直接加在下单接口里。
---
## 2. 当前代码现状
## 2.1 邀请相关
### 2.1.1 已有公开接口
#### A. 邀请基础列表
接口：
- `GET /v1/public/user/affiliate/list`
请求：
- `page`
- `size`
返回结构：
- `total`
- `list[]`
- `identifier`
- `avatar`
- `registered_at`
- `enable`
特点：
- 能表达“我邀请了谁”
- 不能表达“是否购买 / 购买次数 / 给我带来多少收益”
对应代码：
- `apis/public/user.api`
- `internal/logic/public/user/queryUserAffiliateListLogic.go`
#### B. 邀请成交记录
接口：
- `GET /v1/public/user/invite_sales`
返回结构：
- `total`
- `list[]`
- `amount`
- `updated_at`
- `user_hash`
- `product_name`
特点：
- 更像“邀请带来的订单流水”
- 不是邀请用户列表
对应代码：
- `internal/logic/public/user/getInviteSalesLogic.go`
#### C. 邀请统计
接口：
- `GET /v1/public/user/invite_stats`
返回结构：
- `friendly_count`
- `history_count`
特点：
- 只适合头部统计卡片
- 不适合列表页
对应代码：
- `internal/logic/public/user/getUserInviteStatsLogic.go`
### 2.1.2 已有后台接口
后台已经有更完整的邀请记录能力，可以直接参考：
- `GetAdminUserInviteList`
- `GetInviteManageList`
这些接口已经能返回：
- 邀请时间
- 是否购买
- 购买次数
- 邀请人佣金
- 邀请人赠送天数
- 被邀请人赠送天数
对应代码：
- `internal/logic/admin/user/getAdminUserInviteListLogic.go`
- `internal/logic/admin/invite/getInviteManageListLogic.go`
结论：
- 邀请记录的统计逻辑后端已经有现成实现思路。
- 新增 App 公开接口时，建议复用这部分逻辑，不要从零再写一套。
---
## 2.2 套餐折扣相关
### 2.2.1 套餐列表接口已有折扣规则
接口：
- `GET /v1/public/subscribe/list`
当前返回的套餐结构 `Subscribe` 中已包含：
- `unit_price`
- `discount []SubscribeDiscount`
其中 `SubscribeDiscount` 当前字段为：
- `quantity`
- `discount`
- `new_user_only`
- `map_apple`
- `promo`
对应代码：
- `apis/public/subscribe.api`
- `internal/logic/public/subscribe/querySubscribeListLogic.go`
- `internal/types/types.go`
说明：
- `discount` 是按购买数量 `quantity` 生效的阶梯折扣
- 不是单个套餐固定只有一个折扣值
### 2.2.2 预下单接口已有价格计算结果
接口：
- `POST /v1/public/order/pre`
当前已返回：
- `price`：原价
- `amount`：最终应付
- `discount`：折扣减免金额
- `promo_discount`：活动优惠金额
- `gift_amount`：礼品余额抵扣
- `coupon_discount`：优惠券减免
- `fee_amount`：手续费
对应代码：
- `apis/public/order.api`
- `internal/logic/public/order/preCreateOrderLogic.go`
说明：
- 只要 App 知道 `subscribe_id + quantity [+ coupon] [+ payment]`，就已经能拿到准确的下单金额
- 所以“下单购买”这件事本身，后端主链路已经具备
---
## 3. 差距分析
## 3.1 邀请列表的真实缺口
如果产品要的是“邀请记录页”，通常至少会关心以下内容：
- 被邀请用户
- 邀请时间
- 是否已购买
- 购买次数
- 给邀请人带来的佣金
- 双方赠送天数
而当前：
- `/affiliate/list` 只有基础用户列表
- `/invite_sales` 是订单成交记录
- `/invite_stats` 是统计值
所以当前公开侧缺一个“**邀请关系维度的邀请记录列表**”。
## 3.2 套餐折扣的真实缺口
后端目前的主要问题不是“不会算折扣”，而是：
- `discount[]` 更偏规则定义
- App 如果只想直接展示“折后价 / 优惠金额 / 折扣标签”，还需要自己再算一层
- 这会增加前端理解成本，也容易和后端口径不一致
所以当前更合理的改法是：
- 保留现有折扣规则
- 再额外补充几个**面向展示的字段**
---
## 4. 推荐方案
## 4.1 邀请记录接口
### 方案建议
新增一个公开接口，例如：
- `GET /v1/public/user/invite_records`
说明：
- 从登录态中取当前用户 ID
- 不从前端传 `user_id`
- 只查“当前用户邀请的记录”
### 请求参数建议
```json
{
"page": 1,
"size": 10
}
```
### 返回字段建议
```json
{
"total": 2,
"list": [
{
"invitee_id": 1001,
"invitee_identifier": "138****8888",
"invitee_avatar": "https://...",
"invitee_enable": true,
"invited_at": 1716800000,
"order_count": 3,
"has_purchased": true,
"inviter_commission": 1200,
"inviter_gift_days": 30,
"invitee_gift_days": 7
}
]
}
```
### 字段说明
- `invitee_id`：被邀请用户 ID
- `invitee_identifier`：被邀请用户展示账号
- `invitee_avatar`：头像
- `invitee_enable`：是否启用
- `invited_at`：邀请时间
- `order_count`：该被邀请用户产生的有效订单数
- `has_purchased`：是否已购买
- `inviter_commission`：给邀请人带来的佣金，单位建议继续沿用分
- `inviter_gift_days`：邀请人获赠天数
- `invitee_gift_days`：被邀请人获赠天数
### 实现建议
优先复用现有后台逻辑思路：
- 参考 `internal/logic/admin/user/getAdminUserInviteListLogic.go`
- 或参考 `internal/logic/admin/invite/getInviteManageListLogic.go`
公开接口与后台接口的主要差异只有两点：
- 公开接口不允许前端指定 `user_id`
- 公开接口按当前登录用户本人维度返回
### 是否可以不新增接口
可以，但前提是 App 接受以下拆分：
- 列表页用 `/affiliate/list`
- 顶部统计用 `/invite_stats`
- 订单流水页用 `/invite_sales`
如果产品要的是一个完整“邀请记录页”，不建议这样拆三次请求，前端维护成本偏高。
---
## 4.2 套餐折扣字段建议
### 核心建议
“接口增加三个字段”建议**加在 `SubscribeDiscount` 子项里**，不要直接加在 `Subscribe` 顶层。
原因：
- 折扣是按 `quantity` 生效的
- 一个套餐可能有多个折扣档位
- 如果加在套餐顶层，很难表达“买 1 个月”和“买 12 个月”对应不同折扣
### 推荐新增字段
建议在 `SubscribeDiscount` 中增加以下三个展示字段：
- `discount_price`
- `discount_amount`
- `discount_desc`
推荐结构如下：
```json
{
"quantity": 12,
"discount": 80,
"new_user_only": false,
"map_apple": "",
"promo": null,
"discount_price": 9600,
"discount_amount": 2400,
"discount_desc": "年付8折"
}
```
### 三个字段的含义
#### 1. `discount_price`
- 含义：该档位折后总价
- 计算建议：`unit_price * quantity * discount / 100`
- 单位：分
作用：
- App 可直接展示“折后价”
- 下单时直接把该项的 `quantity` 带入 `/order/pre` 或 `/order/purchase`
#### 2. `discount_amount`
- 含义：该档位比原价便宜多少钱
- 计算建议：`unit_price * quantity - discount_price`
- 单位：分
作用：
- App 可直接展示“立省 xx”
#### 3. `discount_desc`
- 含义：折扣展示文案
- 示例：
- `年付8折`
- `季付9折`
- `新用户首单8折`
作用：
- App 可直接做角标、标签、促销文案展示
### 为什么不推荐这三个字段加在下单接口
因为下单接口本来就是“结果型接口”，它已经能返回：
- 原价
- 折扣金额
- 实付金额
如果只是为了 App 卡片展示，再去每个套餐都调一次 `/order/pre`，成本会比较高：
- 请求次数多
- 页面首屏会更慢
- 前端链路更复杂
更合适的做法是：
- 套餐列表接口负责“展示友好”
- 预下单接口负责“结算准确”
---
## 5. 推荐改动清单
## 5.1 邀请列表
建议新增：
- 新接口：`GET /v1/public/user/invite_records`
建议新增类型：
- `GetUserInviteRecordsRequest`
- `UserInviteRecord`
- `GetUserInviteRecordsResponse`
建议实现位置：
- `apis/public/user.api`
- `internal/types/types.go`
- `internal/handler/public/user/`
- `internal/logic/public/user/`
## 5.2 套餐折扣
建议调整：
- `SubscribeDiscount` 增加 3 个字段：
- `discount_price`
- `discount_amount`
- `discount_desc`
建议实现位置：
- `apis/types.api`
- `internal/types/types.go`
- `internal/logic/public/subscribe/querySubscribeListLogic.go`
---
## 6. 前后端协作建议
## 6.1 App 侧调用建议
邀请页建议：
- 头部统计：`/v1/public/user/invite_stats`
- 邀请记录列表：`/v1/public/user/invite_records`
- 如果还要看成交流水：`/v1/public/user/invite_sales`
套餐页建议：
- 先调 `/v1/public/subscribe/list` 渲染套餐和折扣标签
- 用户点某个折扣档位时，带 `subscribe_id + quantity` 调 `/v1/public/order/pre`
- 用户确认后再调 `/v1/public/order/purchase`
## 6.2 单位口径建议
建议继续保持后端金额统一为“分”：
- `unit_price`
- `discount_price`
- `discount_amount`
- `amount`
- `coupon_discount`
这样可以避免前后端出现小数精度问题。
---
## 7. 最终建议
### 建议一
如果你们只是要“邀请用户名单”，可直接复用：
- `GET /v1/public/user/affiliate/list`
### 建议二
如果你们要的是完整“邀请记录”，建议新增：
- `GET /v1/public/user/invite_records`
这是本次需求里更合理的新增接口。
### 建议三
商品套餐“折扣信息”不建议重新设计一整套下单逻辑。
当前后端已经具备：
- 套餐折扣规则
- 预下单价格计算
- 正式下单购买
更推荐做法是：
- 在 `SubscribeDiscount` 里补 3 个展示字段：
- `discount_price`
- `discount_amount`
- `discount_desc`
这样改动最小，也最贴近 App 展示场景。
---
## 8. 相关代码位置
- `internal/logic/public/user/queryUserAffiliateListLogic.go`
- `internal/logic/public/user/getInviteSalesLogic.go`
- `internal/logic/public/user/getUserInviteStatsLogic.go`
- `internal/logic/admin/user/getAdminUserInviteListLogic.go`
- `internal/logic/admin/invite/getInviteManageListLogic.go`
- `internal/logic/public/subscribe/querySubscribeListLogic.go`
- `internal/logic/public/order/preCreateOrderLogic.go`
- `internal/logic/public/order/purchaseLogic.go`
- `internal/types/types.go`
- `apis/public/user.api`
- `apis/public/subscribe.api`
- `apis/public/order.api`
doc/app-three-apis-zh.md
+435
View File
@@ -0,0 +1,435 @@
# App 端三个接口对接文档
> 适用：移动端 / 桌面端 App
> 维护：基于当前 `internal/handler` + `internal/logic` 代码反向梳理
> 时间：2026-05-27
涉及接口：
1. [文件上传](#1-文件上传) — `POST /v1/public/file/upload`
2. [订阅列表（含促销 promo）](#2-订阅列表含促销-promo) — `GET /v1/public/subscribe/list`
3. [邀请赠送记录](#3-邀请赠送记录) — `GET /v1/public/user/invite_records`
公共说明：
- BaseURL 示例：`https://tapi.hifast.biz`
- 鉴权头：`Authorization: <JWT>`（注意：**不要**写 `Bearer ` 前缀，本项目 `AuthMiddleware` 直接取 token 值）
- 业务码包在 `{ code, msg, data }` 信封中，`code = 200` 为成功
- 默认 `Accept: application/json`，可选 `lang: zh_CN`
- 经过 `AuthMiddleware` + `DeviceMiddleware` 的接口都需要登录态 + 设备绑定校验
---
## 1. 文件上传
### 1.1 Endpoint
```
POST /v1/public/file/upload
Content-Type: multipart/form-data
```
- Handler: `internal/handler/public/file/fileUploadHandler.go`
- Logic: `internal/logic/public/file/fileuploadlogic.go:33`
- 路由: `internal/handler/routes.go:934`
- 中间件: `AuthMiddleware` + `DeviceMiddleware`（必须登录）
### 1.2 请求
#### Form 参数
| 字段 | 位置 | 必填 | 说明 |
|---|---|---|---|
| `biz_type` | form | 是 | 业务分类标签，会作为对象 key 的一部分（如 `app-package`、`avatar`） |
| `file` | form file | 是 | 待上传文件二进制 |
#### 文件约束（来自 `etc/ppanel.yaml` → `S3`，可调整）
| 项 | 默认值 |
|---|---|
| 单文件最大 | **104857600 字节（100 MiB）** |
| 允许的 Content-Type | `application/zip, application/x-zip-compressed, application/gzip, application/x-gzip, application/octet-stream, text/plain, application/json, image/jpeg, image/jpg, image/png, image/webp, image/gif, image/heic, image/heif, image/bmp` |
> Content-Type 判定优先级：multipart 文件头里的 `Content-Type` → 文件嗅探（前 512 字节）→ 兜底 `application/octet-stream`。
> **前端 form 上传时尽量带上 `Content-Type`**，否则被嗅探成 `application/octet-stream` 可能不在白名单里。
### 1.3 请求示例
```bash
curl -X POST 'https://tapi.hifast.biz/v1/public/file/upload' \
-H 'Authorization: <JWT>' \
-H 'Accept: application/json' \
-F 'biz_type=app-package' \
-F 'file=@"/Users/Apple/Documents/avatar.jpg";type=image/jpeg'
```
### 1.4 响应
| 字段 | 类型 | 说明 |
|---|---|---|
| `data.url` | string | 上传完成后的可访问 URL，规则：`{S3.PublicBaseURL or S3.Endpoint}/{bucket}/{prefix}/{YYYY}/{MM}/{DD}/{userId}/{safeFileName}__{fileId}` |
成功示例：
```json
{
"code": 200,
"msg": "success",
"data": {
"url": "http://107.173.50.22:5016/hifastvpn/app-upload/2026/05/28/510/2026-05-27_20.03.55.jpg__226ad097c2ee4e3546e729c5"
}
}
```
### 1.5 错误码
| 业务码 | 触发场景 |
|---|---|
| `InvalidAccess` | 未登录 / JWT 无效 |
| `ParamError` | 缺少 `biz_type` 或 `file` |
| `InvalidParams` | `biz_type` 为空、文件名为空、size <= 0、超过 `MaxUploadSize`、`Content-Type` 不在白名单 |
| `ERROR` | S3 未启用（`S3.Enable=false`） / S3 写入失败 |
### 1.6 前端易踩坑
1. `file` 字段名必须是 `file`，写 `image` / `upload` 都不行。
2. `biz_type` 走 form 字段（`form:"biz_type"`），不要塞 query 里。
3. 上传成功只返回 `url`，不返回 `file_id` / 大小等元数据；如需附加元数据，请走分片协议 `POST /upload/init` + `POST /upload/complete`。
4. 想上传 PDF / DOC 不会成功——白名单里没有，需要后端调 `S3.AllowedContentTypes`。
---
## 2. 订阅列表（含促销 promo）
### 2.1 Endpoint
```
GET /v1/public/subscribe/list
```
- Handler: `internal/handler/public/subscribe/querySubscribeListHandler.go`
- Logic: `internal/logic/public/subscribe/querySubscribeListLogic.go:32`
- Promo 合并逻辑: `internal/logic/public/subscribe/promo.go`
- 路由: `internal/handler/routes.go:1026`
- 中间件: **`OptionalAuthMiddleware` + `DeviceMiddleware`**（**未登录也能请求**，但未登录时只能拿到 `rule_type = campaign` 的促销）
### 2.2 请求
#### Query 参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `language` | string | 否 | 语言筛选，传值后返回该语言版本；不传则按系统默认语言返回 |
#### 头部说明（影响返回内容）
| Header | 影响 |
|---|---|
| `Authorization` | 传则识别为登录态，能拿到 `new_user` / `inactive_user` 类型的个性化促销；不传只返回 `campaign` 类型 |
| `X-App-Id` | **不传**会被识别为"老版本客户端"，每个套餐的 `discount` 列表会被**截掉最后一个元素**。新版 App 必须带 `X-App-Id` |
### 2.3 请求示例
```bash
curl -X GET 'https://tapi.hifast.biz/v1/public/subscribe/list?language=zh-CN' \
-H 'Authorization: <JWT>' \
-H 'X-App-Id: hifast-ios' \
-H 'Accept: application/json'
```
### 2.4 响应
#### 顶层
| 字段 | 类型 | 说明 |
|---|---|---|
| `data.total` | int64 | 返回的套餐数量（= `len(list)`，不是数据库总数） |
| `data.list` | Subscribe[] | 套餐列表 |
#### `Subscribe` 关键字段
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | int64 | 套餐 ID |
| `name` | string | 套餐名 |
| `language` | string | 当前返回的语言版本 |
| `description` | string | 套餐描述（可能是富文本/Markdown） |
| `unit_price` | int64 | 单时间单位**原价**，单位：**分** |
| `unit_time` | string | 时间单位，枚举：`Day` / `Month` / `Year`（注意首字母大写） |
| `discount` | SubscribeDiscount[] | 量级折扣 + 促销，按 `quantity` 升序 |
| `node_count` | int64 | 节点数 |
| `traffic` | int64 | 套餐总流量，单位：字节 |
| `speed_limit` | int64 | 限速，单位见后端约定 |
| `device_limit` | int64 | 同时在线设备数限制 |
| `quota` | int64 | 总配额 |
| `show` | bool | 是否在前端展示 |
| `sell` | bool | 是否可售卖（本接口只返回 `sell=true`） |
| `show_original_price` | bool | 是否展示划线原价 |
| `reset_cycle` | int64 | 流量重置周期 |
| `renewal_reset` | bool | 续费时是否重置流量 |
| `created_at` / `updated_at` | int64 | 秒级 Unix 时间戳 |
#### `SubscribeDiscount` 字段
| 字段 | 类型 | 说明 |
|---|---|---|
| `quantity` | int64 | 购买的时间单位数量（如 1 = 1 个月，3 = 3 个月） |
| `discount` | float64 | 量级折扣比例，0 表示无折扣，0.05 表示再优惠 5% |
| `map_apple` | string | 对应 Apple IAP 商品 ID |
| `promo` | SubscribePromo \| null | **#77 新增的促销对象**，命中促销规则时下发，否则为 `null` |
#### `SubscribePromo` 字段
| 字段 | 类型 | 说明 |
|---|---|---|
| `rule_name` | string | 促销规则名（运营在后台填写，可直接给用户展示，如"新人首单 8 折"） |
| `rule_type` | string | 规则类型枚举（见下表） |
| `promo_price` | int64 | **促销价**，单位：**分**。优先级高于 `unit_price * discount`，前端命中促销时按此价显示 |
| `expires_at` | int64 | 该促销对当前用户的失效时间（**秒级 Unix**），`0` 表示无明确截止 |
#### `rule_type` 枚举
| 值 | 含义 | 资格判定 |
|---|---|---|
| `campaign` | 全员/限时活动 | 仅看 `start_time` / `end_time` 是否在窗口内；**未登录也会下发** |
| `new_user` | 新用户首单 | 登录用户，且 `now < user.created_at + params.window_hours`；`expires_at = user.created_at + window_hours` |
| `inactive_user` | 老用户唤回 | 登录用户，且距离最近一个订阅过期已超过 `params.inactive_months` 个月；`expires_at = 规则 end_time` |
> 多条促销规则命中同一 `(subscribe_id, quantity)` 时，按 `priority DESC, id ASC` 取**首条**，不是合并。
### 2.5 响应示例
```json
{
"code": 200,
"msg": "success",
"data": {
"total": 1,
"list": [
{
"id": 1,
"name": "月付套餐",
"language": "zh-CN",
"description": "...",
"unit_price": 1000,
"unit_time": "Month",
"show_original_price": true,
"node_count": 30,
"traffic": 107374182400,
"device_limit": 3,
"discount": [
{
"quantity": 1,
"discount": 0,
"map_apple": "ios.month1",
"promo": {
"rule_name": "新人首单 8 折",
"rule_type": "new_user",
"promo_price": 800,
"expires_at": 1780500000
}
},
{
"quantity": 3,
"discount": 0.05,
"map_apple": "ios.month3",
"promo": null
}
],
"show": true,
"sell": true,
"created_at": 1764547200,
"updated_at": 1779934580
}
]
}
}
```
### 2.6 价格计算建议（前端）
对每个 `discount` 元素：
```
原价 = unit_price * quantity
量级折后价 = round(原价 * (1 - discount))
if promo != null:
实付 = promo.promo_price * quantity // 注意：promo_price 是「单价」，乘以 quantity
划线价 = 原价 // 用于展示「省 XX」
else:
实付 = 量级折后价
划线价 = 原价（show_original_price=true 时展示）
```
> 注意：`promo_price` 设计为**单价**（与 `unit_price` 同级），不是总价。
> 命中促销时建议同时显示 `rule_name`（"新人首单 8 折"）和倒计时（基于 `expires_at`）。
### 2.7 前端易踩坑
1. **必带 `X-App-Id`**——否则 `discount` 数组最后一个会被砍掉。
2. **促销分登录态**：未登录时只能拿到 `campaign`；未拿到 `new_user`/`inactive_user` 时先检查是否传了 `Authorization`。
3. **`unit_time` 是 PascalCase**：`Day` / `Month` / `Year`，别小写匹配。
4. **金额单位都是分**（`unit_price`、`promo_price`），展示时除以 100。
5. **`expires_at = 0`** 表示无截止，不要展示成 1970 年。
6. `total` 是当前返回的条数，不是数据库总数（接口在 logic 里强制 `Size: 9999`，相当于不分页）。
---
## 3. 邀请赠送记录
> 当前用户的"邀请赠送天数"流水。包含两类：
> - 当前用户作为**邀请人**，被邀请的朋友下单触发的赠送；
> - 当前用户作为**被邀请人**，自己下单触发的对应赠送（双向赠送）。
>
> 数据源：`system_logs` 表，`type = 33 (TypeGift)` 且 `content.remark = "邀请赠送"`。
> 这里**只是赠送天数**，不包含邀请佣金（请走 affiliate 系列接口）。
### 3.1 Endpoint
```
GET /v1/public/user/invite_records
```
- Handler: `internal/handler/public/user/getInviteRecordsHandler.go`
- Logic: `internal/logic/public/user/getInviteRecordsLogic.go:61`
- 路由: `internal/handler/routes.go:1122`
- 中间件: `AuthMiddleware` + `DeviceMiddleware`（必须登录）
### 3.2 请求
#### Query 参数
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `page` | int | 否 | `1` | 页码，<1 自动归一为 1 |
| `size` | int | 否 | `10` | 每页条数，<1 归一为 10，**>100 截断为 100** |
| `start_time` | int64 | 否 | `0` | 起始时间（**秒级 Unix**），`0` 表示不过滤下界 |
| `end_time` | int64 | 否 | `0` | 截止时间（**秒级 Unix**），`0` 表示不过滤上界 |
> ⚠️ `start_time` / `end_time` 单位是**秒**（后端用 `FROM_UNIXTIME(?)`）。传毫秒会过滤掉所有记录。
#### 请求示例
```bash
# 不带时间过滤
curl -X GET 'https://tapi.hifast.biz/v1/public/user/invite_records?page=1&size=20' \
-H 'Authorization: <JWT>' \
-H 'Accept: application/json'
# 带时间过滤
curl -X GET 'https://tapi.hifast.biz/v1/public/user/invite_records?page=1&size=20&start_time=1764547200&end_time=1780099200' \
-H 'Authorization: <JWT>'
```
> 旧 curl 模板里的 `--data-urlencode 'page=1'` 等对 GET 是 form body，不会被读取，请用 query string。
### 3.3 响应
#### 顶层
| 字段 | 类型 | 说明 |
|---|---|---|
| `data.total` | int64 | 当前过滤条件下的**记录总数**（用于分页） |
| `data.list` | InviteRecord[] | 当前页列表，可能为空数组 `[]` |
#### `InviteRecord` 字段
| 字段 | 类型 | 说明 |
|---|---|---|
| `role` | string | 当前用户在该条记录中的角色：`inviter` 或 `invitee`（详见下表） |
| `peer_hash` | string | 对端用户的脱敏哈希（10 位定长数字字符串），用于"匿名展示朋友"。订单已删 / 对端 id 缺失时为 `""` |
| `gift_days` | int64 | 本次赠送天数（来源 `system_logs.content.amount`） |
| `order_no` | string | 触发本次赠送的订单号 |
| `created_at` | int64 | 赠送时间，**毫秒级 Unix**（SQL 端 `UNIX_TIMESTAMP(created_at) * 1000`） |
> ⚠️ **时间戳单位不一致**：请求里的 `start_time/end_time` 是**秒**，响应里的 `created_at` 是**毫秒**。前端请区分对待。
> （与项目其它接口"统一秒级"约定不同，是该接口的当前实现。）
#### `role` 取值
| 值 | 含义 | `peer_hash` 来源 |
|---|---|---|
| `inviter` | 当前用户是**邀请人**，朋友下单触发的赠送 | 被邀请人（即订单的 `user_id`）的脱敏 hash |
| `invitee` | 当前用户是**被邀请人**，自己下单触发的赠送 | 邀请人（`user.referer_id`）的脱敏 hash |
判定规则：默认 `inviter`；若 `order.user_id == 当前用户 id`，切换为 `invitee` 并改用 `referer_id` 计算 hash。
#### 排序与分页
- 排序：`created_at DESC, id DESC`（最近一条在最前）
- 分页：`LIMIT size OFFSET (page-1)*size`
- `total` **不**受 `LIMIT/OFFSET` 影响
### 3.4 响应示例
非空：
```json
{
"code": 200,
"msg": "success",
"data": {
"total": 2,
"list": [
{
"role": "inviter",
"peer_hash": "0382716459",
"gift_days": 30,
"order_no": "20260527123456789",
"created_at": 1779934580000
},
{
"role": "invitee",
"peer_hash": "1745920031",
"gift_days": 30,
"order_no": "20260520112233445",
"created_at": 1779329780000
}
]
}
}
```
空：
```json
{
"code": 200,
"msg": "success",
"data": {
"total": 0,
"list": []
}
}
```
### 3.5 错误码
| 业务码 | 触发场景 |
|---|---|
| `InvalidAccess` | 未登录 / JWT 无效 |
| `ParamError` | 参数绑定失败 |
| `DatabaseQueryError` | DB 查询失败（count / 日志 / 订单任一） |
### 3.6 前端易踩坑
1. 传**毫秒**给 `start_time/end_time` → 永远拿到空集。请传**秒**。
2. 拿到的 `created_at` 是**毫秒**，**不要再 `*1000`**，直接 `new Date(created_at)` 即可。
3. 空列表是 `[]` 不是 `null`，可直接 `.map`。
4. `peer_hash` 可能为 `""`，UI 兜底展示"未知朋友"。
5. `size` 上限 100，传 1000 会被截断。
6. 本接口**只含赠送天数**，不含邀请佣金（佣金 → affiliate 接口）。
---
## 附录：业务码常量速查
| 名称 | HTTP 含义 | 出现场景 |
|---|---|---|
| `200` | 成功 | `{"code":200,"msg":"success",...}` |
| `InvalidAccess` | 未授权 | 未登录 / JWT 无效 / 设备未绑定 |
| `ParamError` | 参数错误 | 请求绑定失败、缺必填项 |
| `InvalidParams` | 参数校验不通过 | 业务规则校验失败（文件超限、Content-Type 不合法等） |
| `DatabaseQueryError` | DB 错 | SQL 查询失败 |
| `ERROR` | 通用错 | 第三方/中间件失败（S3 未启用、S3 写入失败等） |
doc/promo-pricing-design-zh.md
+796
View File
@@ -0,0 +1,796 @@
# 促销优惠价系统设计文档
## 1. 背景与目标
### 1.1 业务需求
为套餐规格提供可配置的优惠价格能力，支持多种促销场景：
- **新客优惠**：注册 N 天内的用户享受优惠价
- **回归用户**：N 个月未活跃的用户享受优惠价
- **活动促销**：指定时间段内所有用户享受优惠价
- **未来可扩展**：首充优惠、邀请用户专属价、指定地区优惠等
### 1.2 设计原则
1. **纯新增，不改老代码**：现有的 `new_user_only` + `discount.NewUserOnly` + 24h 窗口逻辑全部保留不动
2. **固定价格，非百分比**：运营直接设定优惠价（如 $5.99），不再需要反算折扣百分比
3. **后台可配置**：规则类型、参数、时间窗口、优先级均可在管理后台配置
4. **促销价不叠加批量折扣**：促销价命中时即为最终基础单价，跳过 `getDiscount()` 的百分比折扣
### 1.3 与现有体系的关系
```
现有体系（保留不动）：
subscribe.NewUserOnly → 套餐级新客限制
discount[].NewUserOnly → 折扣档位级新客限制
newUserEligibility.go → 24h 窗口 + 家庭组判定
newUserDiscountEligibility.go → 新客折扣资格组装
getDiscount() → 百分比折扣选择
order.IsNew → 订单首购标记（统计/佣金用）
新增体系（本次设计）：
promo_rule 表 → 可配置的促销规则
subscribe_promo 表 → 规格×规则 的优惠价
promo_usage 表 → 使用记录（运营分析用）
EvaluatePromo() → 促销资格判定
```
**互斥规则**：促销价命中时，跳过老的百分比折扣逻辑（`getDiscount()`）。
两套体系不叠加 — 用户要么走促销价，要么走原价+百分比折扣，不会同时生效。
---
## 2. 数据模型
### 2.1 新增表：`promo_rule`（促销规则）
```sql
CREATE TABLE `promo_rule` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
`name` VARCHAR(100) NOT NULL DEFAULT '' COMMENT '规则名称，如"新客7天优惠"',
`type` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '规则类型：new_user / inactive_user / campaign',
`params` JSON NOT NULL COMMENT '类型专属参数',
`priority` INT NOT NULL DEFAULT 0 COMMENT '优先级，数值越大越优先匹配',
`enabled` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否启用',
`start_time` DATETIME DEFAULT NULL COMMENT '生效开始时间，NULL=立即生效',
`end_time` DATETIME DEFAULT NULL COMMENT '生效结束时间，NULL=永不过期',
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
`deleted_at` DATETIME DEFAULT NULL COMMENT '软删除时间',
PRIMARY KEY (`id`),
KEY `idx_enabled_priority` (`enabled`, `priority` DESC)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='促销规则表';
```
### 2.2 新增表：`subscribe_promo`（规格优惠价）
```sql
CREATE TABLE `subscribe_promo` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
`subscribe_id` BIGINT UNSIGNED NOT NULL COMMENT '套餐规格 ID',
`promo_rule_id` BIGINT UNSIGNED NOT NULL COMMENT '促销规则 ID',
`promo_price` BIGINT NOT NULL DEFAULT 0 COMMENT '该规格在此规则下的优惠价（分）',
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
UNIQUE KEY `uk_subscribe_rule` (`subscribe_id`, `promo_rule_id`),
KEY `idx_promo_rule_id` (`promo_rule_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='规格促销价表';
```
### 2.3 新增表：`promo_usage`（促销使用记录）
用于运营分析，不做强制去重约束。
```sql
CREATE TABLE `promo_usage` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
`user_id` BIGINT UNSIGNED NOT NULL COMMENT '用户 ID',
`promo_rule_id` BIGINT UNSIGNED NOT NULL COMMENT '使用的规则 ID',
`subscribe_id` BIGINT UNSIGNED NOT NULL COMMENT '购买的规格 ID',
`order_no` VARCHAR(255) NOT NULL DEFAULT '' COMMENT '关联订单号',
`promo_price` BIGINT NOT NULL DEFAULT 0 COMMENT '使用时的促销单价（分）',
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
KEY `idx_user_rule` (`user_id`, `promo_rule_id`),
KEY `idx_order_no` (`order_no`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='促销使用记录表';
```
### 2.4 `order` 表新增字段
```sql
ALTER TABLE `order`
ADD COLUMN `promo_rule_id` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '促销规则ID, 0=未使用促销',
ADD COLUMN `promo_discount` BIGINT NOT NULL DEFAULT 0 COMMENT '促销优惠金额(分)';
```
**字段说明**：
| 订单字段 | 含义 | 促销命中时 | 未命中时 |
|---------|------|-----------|---------|
| `Price` | 原始总价 = `UnitPrice × Quantity` | 不变，始终记录原价 | 不变 |
| `promo_rule_id` | 使用的促销规则 | 规则 ID | 0 |
| `promo_discount` | 促销优惠金额 | `(UnitPrice - PromoPrice) × Quantity` | 0 |
| `Discount` | 百分比折扣金额 | **0**（不叠加） | 正常计算 |
| `Amount` | 最终支付金额 | 基于促销价计算 | 基于原价+折扣计算 |
**订单自证**：任何一笔订单都能独立还原其价格构成，不需要回查促销规则表：
```
Amount = Price - promo_discount - Discount - CouponDiscount + FeeAmount - GiftAmount
```
### 2.5 ER 关系
```
subscribe (1) ──── (*) subscribe_promo (*) ──── (1) promo_rule
│
│
user (1) ──────── (*) promo_usage (*) ─────────── (1) promo_rule
│
(*) order ← 新增 promo_rule_id, promo_discount
```
---
## 3. 规则类型定义
### 3.1 `new_user` — 新客优惠
**含义**：用户注册后 N 小时内可享受优惠价
**params 结构**：
```json
{
"window_hours": 168
}
```
**判定逻辑**：
```
eligible = (当前时间 - 用户注册时间) < window_hours
expires_at = 用户注册时间 + window_hours
```
**与老逻辑的区别**：
| | 老逻辑 | 新逻辑 |
|--|--------|--------|
| 窗口期 | 硬编码 24h | 配置化，后台可改 |
| 判定基准 | 首台设备注册时间 + 家庭组 | 用户注册时间（`user.created_at`） |
| 价格方式 | 百分比折扣 | 固定价格 |
| 与折扣叠加 | 是（百分比折扣本身） | 否（替代原价，跳过折扣） |
### 3.2 `inactive_user` — 回归用户优惠
**含义**：最近 N 个月没有活跃订阅的用户可享受优惠价
**params 结构**：
```json
{
"inactive_months": 3
}
```
**判定逻辑**：
```
last_active = 用户最后一个订阅的 expire_time
eligible = last_active 为空（从未购买过）
OR (当前时间 - last_active) >= inactive_months 个月
expires_at = 规则的 end_time（如有），否则无过期
```
**查询依据**：`user_subscribe` 表中该用户最近一条记录的 `expire_time`
**注意**：「从未购买过」的用户同时满足 `new_user` 和 `inactive_user`，靠 `priority` 排序选择高优先级的那条。
### 3.3 `campaign` — 活动促销
**含义**：在指定时间段内，所有用户均可享受优惠价
**params 结构**：
```json
{}
```
活动促销不需要额外参数，完全靠 `promo_rule.start_time` 和 `end_time` 控制。
**判定逻辑**：
```
eligible = start_time <= 当前时间 <= end_time
expires_at = end_time
```
### 3.4 扩展预留
未来新增规则类型只需：
1. 定义新的 `type` 字符串（如 `first_purchase`、`referral`、`region`）
2. 定义对应的 `params` 结构
3. 在判定逻辑中增加一个 `case` 分支
不需要改表结构，不需要改 API 格式。
---
## 4. 核心逻辑
### 4.1 促销资格判定
新增文件：`internal/logic/common/promoEligibility.go`
```go
type PromoResult struct {
Eligible bool
RuleID int64
RuleName string
RuleType string
PromoPrice int64 // 促销单价（分）
ExpiresAt time.Time
}
func EvaluatePromo(ctx context.Context, svcCtx *svc.ServiceContext, userID int64, subscribeID int64) (*PromoResult, error) {
// 1. 查询该规格关联的所有已启用规则，按 priority DESC
// 2. 遍历规则，按类型判定
// 3. 首条命中即返回
}
```
### 4.2 各类型判定函数
```go
func evaluateNewUser(user *User, params RuleParams) (bool, time.Time) {
windowHours := params.WindowHours
if windowHours <= 0 {
return false, time.Time{}
}
expiresAt := user.CreatedAt.Add(time.Duration(windowHours) * time.Hour)
eligible := time.Now().Before(expiresAt)
return eligible, expiresAt
}
func evaluateInactiveUser(ctx context.Context, userID int64, rule PromoRule) (bool, time.Time) {
inactiveMonths := rule.Params.InactiveMonths
if inactiveMonths <= 0 {
return false, time.Time{}
}
lastExpire := getLastSubscriptionExpireTime(ctx, userID)
if lastExpire.IsZero() {
return true, rule.GetExpiresAt()
}
threshold := time.Now().AddDate(0, -inactiveMonths, 0)
eligible := lastExpire.Before(threshold)
return eligible, rule.GetExpiresAt()
}
```
### 4.3 下单流程集成（不叠加方案）
在 `purchaseLogic.go` 中 `sub.UnitPrice * req.Quantity` 之前，插入促销价判定：
```go
// === 新增：促销价判定 ===
promoResult, promoErr := commonLogic.EvaluatePromo(l.ctx, l.svcCtx, u.Id, targetSubscribeID)
if promoErr != nil {
return nil, promoErr
}
var promoDiscount int64
var promoRuleID int64
if promoResult.Eligible {
// 促销命中 → 用促销价，跳过百分比折扣
price = promoResult.PromoPrice * req.Quantity
promoDiscount = (sub.UnitPrice * req.Quantity) - price
promoRuleID = promoResult.RuleID
discount = 1 // 不叠加批量折扣
discountAmount = 0
} else {
// 未命中 → 走原有逻辑（不动）
price = sub.UnitPrice * req.Quantity
discount = getDiscount(newUserDiscount.Discounts, req.Quantity, newUserDiscount.EligibleForDiscount)
discountAmount = price - int64(math.Round(float64(price)*discount))
}
// === 新增结束 ===
// 后续 coupon / fee / gift 逻辑完全不动
```
**订单创建时记录**：
```go
orderInfo := &order.Order{
// ... 原有字段不动 ...
Price: sub.UnitPrice * req.Quantity, // 始终记录原价
PromoRuleID: promoRuleID, // 新增
PromoDiscount: promoDiscount, // 新增
Discount: discountAmount, // 促销命中时为 0
Amount: amount,
}
```
**激活时写 usage**（`activateOrderLogic.go` 追加）：
```go
if orderInfo.PromoRuleID > 0 {
insertPromoUsage(ctx, orderInfo.UserId, orderInfo.PromoRuleID, orderInfo.SubscribeId, orderInfo.OrderNo, promoPrice)
}
```
### 4.4 价格计算完整流程
```
┌───────────────────────────────────────────────────┐
│ 1. 判定促销 │
│ EvaluatePromo(userId, subscribeId) │
├──────────────┬────────────────────────────────────┤
│ 促销命中 │ 促销未命中 │
├──────────────┼────────────────────────────────────┤
│ basePrice │ basePrice │
│ = promoPrice│ = unitPrice │
│ │ │
│ discount = 0 │ discount = getDiscount(...) │
│ （跳过折扣） │ （百分比折扣正常生效） │
├──────────────┴────────────────────────────────────┤
│ 2. price = basePrice × quantity │
│ amount = price - discountAmount │
├───────────────────────────────────────────────────┤
│ 3. 优惠券（原有逻辑，不动） │
│ amount -= couponDiscount │
├───────────────────────────────────────────────────┤
│ 4. 手续费（原有逻辑，不动） │
│ amount += feeAmount │
├───────────────────────────────────────────────────┤
│ 5. 余额抵扣（原有逻辑，不动） │
│ amount -= giftAmount │
└───────────────────────────────────────────────────┘
```
---
## 5. 退款影响分析
### 5.1 结论：退款逻辑无需改动
当前退款流程（`refundOrderLogic.go`）基于**订单上已存储的字段**运作，不回查价格体系：
| 退款动作 | 数据来源 | 是否受促销影响 |
|---------|---------|--------------|
| 退款金额 | `order.Amount`（支付时已锁定） | 否 — Amount 已反映促销价 |
| 佣金回退 | `system_log` 表中的 commission 记录 | 否 — 佣金是基于 Amount 计算的 |
| 订阅终止 | `user_subscribe.status → 3` | 否 — 和价格无关 |
| 审计日志 | `buildRefundAuditLog()` 读订单快照 | 否 — 记录的就是实际值 |
**原因**：订单创建时所有金额字段（Price、Amount、Discount、PromoDiscount、FeeAmount 等）都已写入 `order` 表。退款只读这些已存储的值，不会重新计算价格。
### 5.2 退款后的促销资格
退款后用户的订阅被终止（`expire_time = now - 1s`）。如果用户再次购买：
| 场景 | 促销资格 | 说明 |
|------|---------|------|
| 新客退款后重新购买 | 如仍在窗口期内 → 仍然可以享受促销价 | 正常行为，`promo_usage` 只是记录不做去重 |
| 回归用户退款后重新购买 | 需重新判定 `inactive_months` | 退款后订阅 expire_time 被设为过去时间 |
| 活动促销退款后重新购买 | 如活动仍在进行 → 可以继续购买 | 活动促销不限次数 |
这些都是合理的业务行为，不需要额外处理。
### 5.3 佣金影响
佣金计算公式（`activateOrderLogic.go:1104`）：
```go
amount := l.calculateCommission(orderInfo.Amount - orderInfo.FeeAmount, referralPercentage)
```
- `Amount` 在促销命中时已反映促销价（更低的金额）
- 所以佣金会相应减少 — **这是正确的行为**
- 退款时佣金回退金额从 `system_log` 读取，回退的也是减少后的佣金
**无需任何改动**。
---
## 6. Apple IAP 影响分析
### 6.1 现状
- Apple IAP 价格在 App Store Connect 中配置，不支持后端动态定价
- 当前通过 `discount[].MapApple` 字段映射 Apple Product ID
- IAP 订单在 `appleIAPNotifyLogic.go` 中处理，走独立的价格逻辑
### 6.2 设计决策
**促销价不适用于 IAP 订单**。原因：
- IAP 价格由 Apple 控制，后端无法干预
- IAP 通知回调（`appleIAPNotifyLogic.go`）有独立的价格处理流程
- IAP 审计订单设 `IsNew: false`，不走常规购买逻辑
**实现方式**：`EvaluatePromo()` 不需要特殊处理 — IAP 订单根本不经过 `purchaseLogic.go`，自然不会触发促销判定。
---
## 7. 各购买场景适配
### 7.1 需要集成促销的场景
| 文件 | 场景 | 集成方式 |
|------|------|---------|
| `purchaseLogic.go` | 新购 | 完整促销判定 + 不叠加逻辑 |
| `preCreateOrderLogic.go` | 价格预览 | 同上（返回 promo_discount 字段） |
### 7.2 不需要改动的场景
| 文件 | 场景 | 原因 |
|------|------|------|
| `renewalLogic.go` | 续费 | 促销价仅限首购，续费走原价+折扣 |
| `rechargeLogic.go` | 余额充值 | 充值不涉及套餐价格 |
| `redeemCodeLogic.go` | 兑换码 | 兑换码有自己的固定逻辑 |
| `recoverOrderLogic.go` | 历史导入 | 导入的是已完成订单 |
| `appleIAPNotifyLogic.go` | IAP 续订 | Apple 控制价格 |
| `portal/purchaseLogic.go` | 游客购买 | 游客无 user_id，无法判定促销资格 |
| `refundOrderLogic.go` | 退款 | 读取订单已存储的金额，不重新计算 |
| `activateOrderLogic.go` | 订单激活 | 只追加 promo_usage 写入，价格不重算 |
### 7.3 统计报表
现有统计 SQL（`order/model.go` 中 8 处）按 `is_new` 拆分收入，**不需要改动**。
未来如需促销维度报表，可通过 `order.promo_rule_id` 字段扩展：
```sql
SUM(CASE WHEN promo_rule_id > 0 THEN amount ELSE 0 END) AS promo_order_amount,
SUM(CASE WHEN promo_rule_id = 0 THEN amount ELSE 0 END) AS normal_order_amount
```
---
## 8. API 设计
### 8.1 套餐列表 API（改造）
**接口**：`GET /v1/public/subscribe/list`
**响应变更**：在原有 `Subscribe` 结构体中追加 `promo` 字段。
```json
{
"list": [
{
"id": 1,
"name": "基础套餐",
"unit_price": 288,
"discount": [...],
"promo": {
"rule_name": "新客7天优惠",
"rule_type": "new_user",
"promo_price": 279,
"expires_at": 1748870400
}
},
{
"id": 2,
"name": "标准套餐",
"unit_price": 688,
"promo": null
}
]
}
```
**`promo` 字段说明**：
| 字段 | 类型 | 说明 |
|------|------|------|
| `rule_name` | string | 规则名称，前端展示用 |
| `rule_type` | string | 规则类型，前端可据此展示不同样式 |
| `promo_price` | int64 | 优惠单价（分），注意是单价不是总价 |
| `expires_at` | int64 | 优惠过期时间戳（秒），0 = 无过期 |
- 用户未登录时：仅展示 `campaign` 类型促销（不需要用户信息）
- 用户已登录：展示所有命中的促销
- 未命中任何规则时，`promo` 为 `null`
### 8.2 预算订单 API（改造）
**接口**：`POST /v1/public/order/pre`
**响应追加字段**：
```json
{
"price": 688,
"amount": 499,
"discount": 0,
"promo_discount": 189,
"coupon_discount": 0,
"fee_amount": 0,
"gift_amount": 0
}
```
| 字段 | 含义 |
|------|------|
| `price` | 原始总价 = `UnitPrice × Quantity` |
| `promo_discount` | 促销优惠 = `(UnitPrice - PromoPrice) × Quantity` |
| `discount` | 百分比折扣优惠（促销命中时为 0） |
| `amount` | 最终支付金额 |
前端可展示：~~原价 ¥6.88~~ → 促销价 ¥4.99
### 8.3 管理后台 API（新增）
#### 8.3.1 促销规则 CRUD
```
POST /v1/admin/promo/rule 创建规则
GET /v1/admin/promo/rule/list 规则列表
GET /v1/admin/promo/rule/:id 规则详情
PUT /v1/admin/promo/rule/:id 更新规则
DELETE /v1/admin/promo/rule/:id 删除规则（软删除）
```
**创建/更新请求体**：
```json
{
"name": "新客7天优惠",
"type": "new_user",
"params": {
"window_hours": 168
},
"priority": 10,
"enabled": true,
"start_time": null,
"end_time": null
}
```
**校验规则**：
- `type` 必须是已支持的类型
- `params` 按 `type` 做结构校验（如 `new_user` 必须有 `window_hours > 0`）
- `priority` >= 0
- `start_time` < `end_time`（如果两者都提供）
#### 8.3.2 规格优惠价配置
```
POST /v1/admin/promo/price 批量设置优惠价
GET /v1/admin/promo/price/list 查询某规则下的所有优惠价
DELETE /v1/admin/promo/price/:id 删除某条优惠价
```
**批量设置请求体**：
```json
{
"promo_rule_id": 1,
"items": [
{"subscribe_id": 1, "promo_price": 279},
{"subscribe_id": 2, "promo_price": 599}
]
}
```
**校验**：`promo_price` 必须 < 对应规格的 `unit_price`（防止配置错误）。
#### 8.3.3 使用记录查询
```
GET /v1/admin/promo/usage/list?rule_id=1&page=1&size=20
```
---
## 9. 缓存策略
### 9.1 规则缓存
```
Key: promo:rules:enabled
Value: JSON 数组（所有启用的规则，按 priority DESC）
TTL: 300 秒（5 分钟）
清除: 管理后台修改规则时主动删除
```
### 9.2 规格优惠价缓存
```
Key: promo:subscribe:{subscribe_id}
Value: JSON 数组（该规格关联的所有 rule_id → promo_price）
TTL: 300 秒
清除: 管理后台修改优惠价时主动删除
```
### 9.3 注意事项
- 缓存 TTL 300 秒意味着活动 `end_time` 到期后最多 5 分钟延迟，可接受
- 管理后台操作后主动 DEL 缓存 key，确保配置变更及时生效
- `EvaluatePromo()` 缓存未命中时回查 DB
---
## 10. 确定的决策项
| 编号 | 问题 | 结论 | 原因 |
|------|------|------|------|
| D-01 | 促销价与批量折扣叠加 | **不叠加** | 促销价即最终单价，跳过 `getDiscount()` |
| D-02 | 未登录用户展示促销价 | 仅展示 `campaign` 类型 | `new_user`/`inactive_user` 需要用户信息 |
| D-03 | 续费订单适用促销价 | **仅首购** | 促销价用于拉新/回归，续费走原价 |
| D-04 | 回归用户判定方式 | 订阅过期时间 | `user_subscribe.expire_time`，数据最可靠 |
| D-05 | 多规则命中 | 按 `priority` DESC 取第一条 | 运营可控 |
| D-07 | Portal（游客）购买走促销 | **不走** | 游客无 user_id，无法判定资格 |
---
## 11. 新增文件清单
| 层级 | 新增文件 | 说明 |
|------|----------|------|
| **Model** | `internal/model/promo_rule/promo_rule.go` | 促销规则模型 |
| **Model** | `internal/model/subscribe_promo/subscribe_promo.go` | 规格优惠价模型 |
| **Model** | `internal/model/promo_usage/promo_usage.go` | 使用记录模型 |
| **Logic** | `internal/logic/common/promoEligibility.go` | 促销资格判定核心逻辑 |
| **Logic** | `internal/logic/admin/promo/` 目录（CRUD） | 管理后台逻辑 |
| **Handler** | `internal/handler/admin/promo/` 目录 | 管理后台 Handler |
| **Types** | `internal/types/types.go` 追加 | 新增结构体 |
| **Migration** | `initialize/migrate/database/02153_promo_rule.up.sql` | 建表 + order 加字段 |
| **Migration** | `initialize/migrate/database/02153_promo_rule.down.sql` | 回滚 |
### 需改动的已有文件（仅追加）
| 文件 | 改动方式 |
|------|----------|
| `internal/logic/public/subscribe/querySubscribeListLogic.go` | 追加：查促销信息，填充 `promo` |
| `internal/logic/public/order/purchaseLogic.go` | 追加：促销判定 + 不叠加分支 |
| `internal/logic/public/order/preCreateOrderLogic.go` | 追加：预算时考虑促销价 |
| `queue/logic/order/activateOrderLogic.go` | 追加：激活后写 `promo_usage` |
| `internal/model/order/order.go` | 追加：`PromoRuleID`、`PromoDiscount` 字段 |
| `internal/model/order/model.go` | 追加：`Details` 同步字段 |
| `internal/types/types.go` | 追加：新增结构体、响应字段 |
| `internal/svc/serviceContext.go` | 追加：注入新 Model |
| 路由配置 | 追加：管理后台路由 |
---
## 12. 运营配置示例
### 场景 1：新客 7 天优惠
```
promo_rule:
name = "新客7天优惠"
type = "new_user"
params = {"window_hours": 168}
priority = 10
enabled = true
start_time = NULL（永久生效）
end_time = NULL
subscribe_promo:
规格"7天" → promo_price = 279
规格"30天" → promo_price = 599
规格"90天" → promo_price = 1299
规格"365天" → promo_price = 4499
```
### 场景 2：回归用户优惠
```
promo_rule:
name = "回归用户专属价"
type = "inactive_user"
params = {"inactive_months": 3}
priority = 5
enabled = true
subscribe_promo:
规格"30天" → promo_price = 499
规格"90天" → promo_price = 999
```
### 场景 3：双十一全站活动
```
promo_rule:
name = "双十一特惠"
type = "campaign"
params = {}
priority = 20（优先级高于新客和回归）
enabled = true
start_time = "2026-11-01 00:00:00"
end_time = "2026-11-12 00:00:00"
subscribe_promo:
规格"90天" → promo_price = 999
规格"365天" → promo_price = 3999
```
**优先级效果**：双十一期间（priority=20），即使用户是新客（priority=10），也走双十一价格。双十一结束后，新客仍可享受新客优惠。
---
## 13. 迁移脚本
### 02153_promo_system.up.sql
```sql
-- 促销规则表
CREATE TABLE IF NOT EXISTS `promo_rule` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
`name` VARCHAR(100) NOT NULL DEFAULT '',
`type` VARCHAR(32) NOT NULL DEFAULT '',
`params` JSON NOT NULL,
`priority` INT NOT NULL DEFAULT 0,
`enabled` TINYINT(1) NOT NULL DEFAULT 1,
`start_time` DATETIME DEFAULT NULL,
`end_time` DATETIME DEFAULT NULL,
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
`deleted_at` DATETIME DEFAULT NULL,
PRIMARY KEY (`id`),
KEY `idx_enabled_priority` (`enabled`, `priority` DESC)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='促销规则表';
-- 规格促销价表
CREATE TABLE IF NOT EXISTS `subscribe_promo` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
`subscribe_id` BIGINT UNSIGNED NOT NULL,
`promo_rule_id` BIGINT UNSIGNED NOT NULL,
`promo_price` BIGINT NOT NULL DEFAULT 0,
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
UNIQUE KEY `uk_subscribe_rule` (`subscribe_id`, `promo_rule_id`),
KEY `idx_promo_rule_id` (`promo_rule_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='规格促销价表';
-- 促销使用记录表
CREATE TABLE IF NOT EXISTS `promo_usage` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
`user_id` BIGINT UNSIGNED NOT NULL,
`promo_rule_id` BIGINT UNSIGNED NOT NULL,
`subscribe_id` BIGINT UNSIGNED NOT NULL,
`order_no` VARCHAR(255) NOT NULL DEFAULT '',
`promo_price` BIGINT NOT NULL DEFAULT 0,
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
KEY `idx_user_rule` (`user_id`, `promo_rule_id`),
KEY `idx_order_no` (`order_no`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='促销使用记录表';
-- order 表新增促销字段
ALTER TABLE `order`
ADD COLUMN `promo_rule_id` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '促销规则ID, 0=未使用促销',
ADD COLUMN `promo_discount` BIGINT NOT NULL DEFAULT 0 COMMENT '促销优惠金额(分)';
```
### 02153_promo_system.down.sql
```sql
ALTER TABLE `order`
DROP COLUMN IF EXISTS `promo_discount`,
DROP COLUMN IF EXISTS `promo_rule_id`;
DROP TABLE IF EXISTS `promo_usage`;
DROP TABLE IF EXISTS `subscribe_promo`;
DROP TABLE IF EXISTS `promo_rule`;
```
---
## 14. 风险与注意事项
| 风险 | 应对 |
|------|------|
| 促销价 > 原价（配置错误） | 管理后台校验：`promo_price` 必须 < `unit_price` |
| 规则删除后已有订单受影响 | 软删除（`deleted_at`），订单上已存储 `promo_rule_id` 和 `promo_discount`，不依赖规则表 |
| 缓存与数据库不一致 | 管理后台修改时主动清缓存，判定逻辑以 DB 为准 |
| 新促销和老 NewUserOnly 折扣共存 | **互斥**：促销命中时跳过 `getDiscount()` 的百分比折扣 |
| 活动到期后 5 分钟内仍可下单 | 缓存 TTL=300s 的延迟，可接受；下单时可选择实时查 DB 校验 |
| 退款后重新购买仍享促销 | 正常行为 — `promo_usage` 只做记录不做去重 |
doc/withdrawal-list-subscribe-fields-zh.md
+153
View File
@@ -0,0 +1,153 @@
# 用户端提现列表 API — 订阅字段现状调研
> 调研日期：2026-05-27
> 调研范围：用户端「提现记录列表」接口当前返回字段，重点关注是否包含订阅相关信息
## 一、接口信息
| 项目 | 值 |
|------|-----|
| 方法 | `GET` |
| 路径 | `/v1/public/user/withdrawal_log` |
| 认证 | JWT Token（`AuthMiddleware` + `DeviceMiddleware`） |
| 分组 | `apis/public/user.api` |
## 二、文件定位
| 层 | 路径 |
|----|------|
| API DSL | `apis/public/user.api:118` (`WithdrawalLog`) / `apis/public/user.api:368` (路由) |
| Handler | `internal/handler/public/user/queryWithdrawalLogHandler.go` |
| Logic | `internal/logic/public/user/queryWithdrawalLogLogic.go:30` |
| 类型生成 | `internal/types/types.go`（`WithdrawalLog`、`QueryWithdrawalLogListRequest`、`QueryWithdrawalLogListResponse`） |
| 数据模型 | `internal/model/user/user.go:167` (`Withdrawal`，表名 `withdrawals`） |
## 三、请求参数
```go
QueryWithdrawalLogListRequest {
Page int `form:"page"`
Size int `form:"size"`
}
```
- 默认值：`page=1`、`size=10`（在 logic 内兜底）
## 四、响应结构
### 4.1 顶层响应
```go
QueryWithdrawalLogListResponse {
List []WithdrawalLog `json:"list"`
Total int64 `json:"total"`
}
```
### 4.2 列表项 `WithdrawalLog`
```go
WithdrawalLog {
Id int64 `json:"id"`
UserId int64 `json:"user_id"`
Amount int64 `json:"amount"` // 单位：分
Content string `json:"content"` // 收款附加信息
Status uint8 `json:"status"` // 0:Pending 1:Approved 2:Rejected 3:Cancelled
Reason string `json:"reason,omitempty"` // 拒绝原因
Method uint8 `json:"method"` // 0:其他 1:支付宝 2:微信 3:USDT
Account string `json:"account"` // 收款账号
QrCodeUrl string `json:"qr_code_url"` // 收款码图片 URL
CreatedAt int64 `json:"created_at"`
UpdatedAt int64 `json:"updated_at"`
}
```
## 五、底层数据模型 `Withdrawal`
```go
type Withdrawal struct {
Id int64
UserId int64 // index:idx_user_id
Amount int64
Content string // type:text
Status uint8 // 0:Pending 1:Approved 2:Rejected 3:Cancelled
Reason string // varchar(500)
Method uint8 // 0:其他 1:支付宝 2:微信 3:USDT
Account string // varchar(255)
QrCodeUrl string // varchar(500)
CreatedAt time.Time
UpdatedAt time.Time
}
```
> 表名：`withdrawals`，与用户关联仅靠 `user_id` 外键，**无任何订阅 ID / 订阅快照字段**。
## 六、订阅字段现状（核心结论）
### 6.1 当前结论
| 维度 | 是否包含订阅信息 |
|------|------------------|
| API 响应（`WithdrawalLog`） | ❌ 无 |
| 数据库表（`withdrawals`） | ❌ 无 |
| Logic 查询逻辑 | ❌ 无 JOIN、无附加查询 `user_subscribe` |
提现记录与订阅之间**完全没有关联**。原因：佣金来源于多次订单累计，提现是从「佣金余额（`user.commission`）」整体扣减，不绑定到任何具体订阅。
### 6.2 Logic 当前实现要点
```go
// internal/logic/public/user/queryWithdrawalLogLogic.go:46-72
query := l.svcCtx.DB.WithContext(l.ctx).
Model(&user.Withdrawal{}).
Where("user_id = ?", u.Id)
// 仅按 user_id 过滤 + 分页 + 倒序，无任何 Preload / Join
```
## 七、已发现的隐患（与本次需求关联）
### 7.1 时间戳违反项目约定 ⚠️
`queryWithdrawalLogLogic.go:70-71`：
```go
CreatedAt: row.CreatedAt.UnixMilli(),
UpdatedAt: row.UpdatedAt.UnixMilli(),
```
- 项目约定：**后端统一返回秒级 Unix 时间戳**（前端 `formatDate` 已按 `数字 × 1000` 处理）
- 当前实现返回毫秒级，前端会解析为约公元 +55000 年的日期，**展示必然异常**
- 修复方式：改为 `.Unix()`
> 该问题独立于「订阅字段」需求，但属于同一接口，建议同批修复。
## 八、可选扩展方向（待业务确认）
若产品希望在提现列表中展示订阅相关信息，可选方案如下：
| 方案 | 字段示意 | 实现成本 | 适用场景 |
|------|----------|----------|----------|
| A. 当前生效订阅摘要 | `current_subscribe: { id, name, expire_at }` | 中（每行额外查 `user_subscribe`） | 想让用户看到「我提的是哪个订阅产生的佣金对应的余额」 |
| B. 用户全部订阅列表 | `subscribes: [{ id, name, expire_at }]` | 高（N+1 风险） | 极少场景，需评估必要性 |
| C. 仅订阅 ID 数组 | `subscribe_ids: [int64]` | 低 | 仅前端跳详情用 |
| D. 不加，保持现状 | — | 0 | 若业务上提现与订阅本就无关 |
> **推荐先与产品确认动机**：提现是佣金余额提现，与订阅本身没有直接业务关系，加字段前需明确「让用户看到订阅信息要解决什么问题」。
## 九、相关接口（一并列出，便于对照）
| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 提交提现 | POST | `/v1/public/user/commission_withdraw` | 入参 `CommissionWithdrawRequest`，返回 `WithdrawalLog` |
| 取消提现 | POST | `/v1/public/user/withdrawal_cancel` | 入参 `CancelWithdrawalRequest`，返回 `WithdrawalLog` |
| 提现记录列表 | GET | `/v1/public/user/withdrawal_log` | 本文主角 |
> 三个接口共用 `WithdrawalLog` 类型，**任何字段变更需统一同步**，否则前端类型会错位。
## 十、后续动作建议
1. **产品确认**：是否真的需要在提现列表里返回订阅字段？目的是什么？
2. **若需新增**：在 `apis/public/user.api` 修改 `WithdrawalLog`，运行 goctl 重新生成，再补 Logic 查询。
3. **顺手修复**：将 `UnixMilli()` 改为 `Unix()`（独立小 PR 即可）。
4. **如新增订阅字段**：注意三个接口（list / cancel / withdraw）的返回结构同步，避免前端类型联动断裂。
etc/ppanel.yaml
+2 -2
View File
@@ -15,10 +15,10 @@ Logger: # 日志配置
Level: debug # 日志级别: debug, info, warn, error, panic, fatal
MySQL:
Addr: 45.43.29.127:3306 # host 网络模式; bridge 模式改为 mysql:3306
Addr: 154.12.35.103:3306 # host 网络模式; bridge 模式改为 mysql:3306
Username: root # MySQL用户名
Password: jpcV41ppanel # MySQL密码，与 .env MYSQL_ROOT_PASSWORD 一致
Dbname: hifast # MySQL数据库名
Dbname: ppanel # MySQL数据库名
Config: charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai
MaxIdleConns: 10
MaxOpenConns: 100
initialize/migrate/database/02155_promo_schema_fix.down.sql
+6
View File
@@ -0,0 +1,6 @@
-- 02155 down
--
-- 本迁移只是把 02154 的偏差修正回它应有的目标定义，没有引入新的列/表。
-- 回滚 02155 并不应该把列重新改坏成 varchar/INT NULL 的旧偏差，因此 down
-- 为空操作。若需彻底删除 promo 系统，请回滚到 02154 的 down。
SELECT '02155 has no destructive forward step; down is a no-op.';
initialize/migrate/database/02155_promo_schema_fix.up.sql
+241
View File
@@ -0,0 +1,241 @@
-- 02155 Promo Schema Fix
--
-- 修复历史环境中 02154 未正确执行（或部分 GORM AutoMigrate 推断）导致的
-- promo 系统列类型 / 索引偏差。完全幂等：可重复执行。
--
-- 覆盖偏差：
-- 1) subscribe_promo.quantity 实际 int/NULL -> BIGINT NOT NULL DEFAULT 1
-- 2) subscribe_promo 唯一索引 实际 (subscribe_id, promo_rule_id) -> (subscribe_id, quantity, promo_rule_id)
-- 3) order.promo_rule_id 实际 int/NULL -> BIGINT UNSIGNED NOT NULL DEFAULT 0
-- 4) order.promo_discount 实际 varchar(255)/NULL -> BIGINT NOT NULL DEFAULT 0
--
-- 设计原则：
-- - 所有 ALTER 前先做 NULL/空串兜底，避免 NOT NULL 转换失败。
-- - 类型已经正确的环境（02154 正常跑过）不会被改动，所有 IF 判断都基于
-- INFORMATION_SCHEMA 当前真实状态。
-- - 索引差异处理 4 个分支：仅当索引确实是错的旧形态时才替换，已经是新形态则不动。
-- ============================================================================
-- 1) subscribe_promo.quantity
-- ============================================================================
-- 1.1 列不存在则补建（极端历史环境兜底）
SET @col_exists = (
SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'subscribe_promo'
AND COLUMN_NAME = 'quantity'
);
SET @sql = IF(
@col_exists = 0,
'ALTER TABLE `subscribe_promo` ADD COLUMN `quantity` BIGINT NOT NULL DEFAULT 1 COMMENT ''购买数量'' AFTER `subscribe_id`',
'SELECT ''subscribe_promo.quantity exists, skip ADD'''
);
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
-- 1.2 NULL 兜底为 1（旧 AutoMigrate 推断列允许 NULL，必须先回填再 NOT NULL）
UPDATE `subscribe_promo` SET `quantity` = 1 WHERE `quantity` IS NULL;
-- 1.3 类型 / 可空 / 默认值修正：只在与目标定义不一致时改
SET @col_def_wrong = (
SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'subscribe_promo'
AND COLUMN_NAME = 'quantity'
AND (
LOWER(DATA_TYPE) <> 'bigint'
OR IS_NULLABLE = 'YES'
OR COLUMN_DEFAULT IS NULL
OR COLUMN_DEFAULT <> '1'
)
);
SET @sql = IF(
@col_def_wrong = 1,
'ALTER TABLE `subscribe_promo` MODIFY COLUMN `quantity` BIGINT NOT NULL DEFAULT 1 COMMENT ''购买数量''',
'SELECT ''subscribe_promo.quantity already matches target definition'''
);
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
-- ============================================================================
-- 2) subscribe_promo 唯一索引：旧形态 -> (subscribe_id, quantity, promo_rule_id)
-- ============================================================================
-- 2.1 删除已知的所有旧形态唯一索引（如果存在）
SET @idx_exists = (
SELECT COUNT(*) FROM INFORMATION_SCHEMA.STATISTICS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'subscribe_promo'
AND INDEX_NAME = 'idx_subscribe_rule'
);
SET @sql = IF(
@idx_exists = 1,
'ALTER TABLE `subscribe_promo` DROP INDEX `idx_subscribe_rule`',
'SELECT ''subscribe_promo.idx_subscribe_rule absent'''
);
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
SET @idx_exists = (
SELECT COUNT(*) FROM INFORMATION_SCHEMA.STATISTICS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'subscribe_promo'
AND INDEX_NAME = 'uk_subscribe_rule'
);
SET @sql = IF(
@idx_exists = 1,
'ALTER TABLE `subscribe_promo` DROP INDEX `uk_subscribe_rule`',
'SELECT ''subscribe_promo.uk_subscribe_rule absent'''
);
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
SET @idx_exists = (
SELECT COUNT(*) FROM INFORMATION_SCHEMA.STATISTICS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'subscribe_promo'
AND INDEX_NAME = 'uk_subscribe_qty_rule'
);
SET @sql = IF(
@idx_exists = 1,
'ALTER TABLE `subscribe_promo` DROP INDEX `uk_subscribe_qty_rule`',
'SELECT ''subscribe_promo.uk_subscribe_qty_rule absent'''
);
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
-- 2.2 新建目标唯一索引（缺失时才建）
SET @idx_exists = (
SELECT COUNT(*) FROM INFORMATION_SCHEMA.STATISTICS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'subscribe_promo'
AND INDEX_NAME = 'uk_subscribe_quantity_rule'
);
SET @sql = IF(
@idx_exists = 0,
'ALTER TABLE `subscribe_promo` ADD UNIQUE KEY `uk_subscribe_quantity_rule` (`subscribe_id`, `quantity`, `promo_rule_id`)',
'SELECT ''subscribe_promo.uk_subscribe_quantity_rule exists'''
);
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
-- ============================================================================
-- 3) order.promo_rule_id -> BIGINT UNSIGNED NOT NULL DEFAULT 0
-- ============================================================================
SET @col_exists = (
SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'order'
AND COLUMN_NAME = 'promo_rule_id'
);
SET @sql = IF(
@col_exists = 0,
'ALTER TABLE `order` ADD COLUMN `promo_rule_id` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT ''促销规则ID, 0=未使用促销'' AFTER `discount`',
'SELECT ''order.promo_rule_id exists, skip ADD'''
);
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
UPDATE `order` SET `promo_rule_id` = 0 WHERE `promo_rule_id` IS NULL;
SET @col_def_wrong = (
SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'order'
AND COLUMN_NAME = 'promo_rule_id'
AND (
LOWER(DATA_TYPE) <> 'bigint'
OR INSTR(LOWER(COLUMN_TYPE), 'unsigned') = 0
OR IS_NULLABLE = 'YES'
OR COLUMN_DEFAULT IS NULL
OR COLUMN_DEFAULT <> '0'
)
);
SET @sql = IF(
@col_def_wrong = 1,
'ALTER TABLE `order` MODIFY COLUMN `promo_rule_id` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT ''促销规则ID, 0=未使用促销''',
'SELECT ''order.promo_rule_id already matches target definition'''
);
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
-- ============================================================================
-- 4) order.promo_discount -> BIGINT NOT NULL DEFAULT 0
-- 历史 AutoMigrate 推断为 varchar(255)/NULL，金额字段错存为字符串。
-- 必须先把空串/NULL 兜底为 '0'，再 MODIFY，否则 MySQL 转 BIGINT 会写 0
-- （这里我们仍兜底显式化，避免触发 strict mode 报错）。
-- ============================================================================
SET @col_exists = (
SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'order'
AND COLUMN_NAME = 'promo_discount'
);
SET @sql = IF(
@col_exists = 0,
'ALTER TABLE `order` ADD COLUMN `promo_discount` BIGINT NOT NULL DEFAULT 0 COMMENT ''促销优惠金额(分)'' AFTER `promo_rule_id`',
'SELECT ''order.promo_discount exists, skip ADD'''
);
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
-- 当且仅当当前是字符串型时做兜底（避免对已经是 BIGINT 的环境跑无谓 UPDATE）
SET @col_is_string = (
SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'order'
AND COLUMN_NAME = 'promo_discount'
AND LOWER(DATA_TYPE) IN ('varchar', 'char', 'text')
);
SET @sql = IF(
@col_is_string = 1,
'UPDATE `order` SET `promo_discount` = ''0'' WHERE `promo_discount` IS NULL OR `promo_discount` = ''''',
'SELECT ''order.promo_discount not string type, skip backfill'''
);
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
SET @col_def_wrong = (
SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'order'
AND COLUMN_NAME = 'promo_discount'
AND (
LOWER(DATA_TYPE) <> 'bigint'
OR IS_NULLABLE = 'YES'
OR COLUMN_DEFAULT IS NULL
OR COLUMN_DEFAULT <> '0'
)
);
SET @sql = IF(
@col_def_wrong = 1,
'ALTER TABLE `order` MODIFY COLUMN `promo_discount` BIGINT NOT NULL DEFAULT 0 COMMENT ''促销优惠金额(分)''',
'SELECT ''order.promo_discount already matches target definition'''
);
PREPARE stmt FROM @sql;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
internal/handler/public/user/getInviteSalesHandler.go
+30
View File
@@ -0,0 +1,30 @@
package user
import (
"github.com/gin-gonic/gin"
"github.com/perfect-panel/server/internal/logic/public/user"
"github.com/perfect-panel/server/internal/svc"
"github.com/perfect-panel/server/internal/types"
"github.com/perfect-panel/server/pkg/result"
)
// Get invite sales data
func GetInviteSalesHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
return func(c *gin.Context) {
var req types.GetInviteSalesRequest
if err := c.ShouldBind(&req); err != nil {
result.ParamErrorResult(c, err)
return
}
validateErr := svcCtx.Validate(&req)
if validateErr != nil {
result.ParamErrorResult(c, validateErr)
return
}
l := user.NewGetInviteSalesLogic(c.Request.Context(), svcCtx)
resp, err := l.GetInviteSales(&req)
result.HttpResult(c, resp, err)
}
}
internal/handler/routes.go
+12
View File
@@ -2200,6 +2200,18 @@ func RegisterHandlers(server *rest.Server, serverCtx *svc.ServiceContext) {
Path: "/invite_records",
Handler: publicuser.GetInviteRecordsHandler(serverCtx),
},
{
// Get Invite Sales
Method: http.MethodGet,
Path: "/invite_sales",
Handler: publicuser.GetInviteSalesHandler(serverCtx),
},
{
// Get Invite Sales (backward-compat alias)
Method: http.MethodGet,
Path: "/invite/sales",
Handler: publicuser.GetInviteSalesHandler(serverCtx),
},
{
// Get User Invite Stats
Method: http.MethodGet,
internal/logic/public/user/getInviteSalesLogic.go
+145
View File
@@ -0,0 +1,145 @@
package user
import (
"context"
"fmt"
"hash/fnv"
"strconv"
"github.com/perfect-panel/server/internal/model/user"
"github.com/perfect-panel/server/internal/svc"
"github.com/perfect-panel/server/internal/types"
"github.com/perfect-panel/server/pkg/constant"
"github.com/perfect-panel/server/pkg/logger"
"github.com/perfect-panel/server/pkg/xerr"
"github.com/pkg/errors"
)
type GetInviteSalesLogic struct {
logger.Logger
ctx context.Context
svcCtx *svc.ServiceContext
}
func NewGetInviteSalesLogic(ctx context.Context, svcCtx *svc.ServiceContext) *GetInviteSalesLogic {
return &GetInviteSalesLogic{
Logger: logger.WithContext(ctx),
ctx: ctx,
svcCtx: svcCtx,
}
}
func (l *GetInviteSalesLogic) GetInviteSales(req *types.GetInviteSalesRequest) (resp *types.GetInviteSalesResponse, err error) {
// 1. Get current user
u, ok := l.ctx.Value(constant.CtxKeyUser).(*user.User)
if !ok {
l.Errorw("[GetInviteSales] user not found in context")
return nil, errors.Wrapf(xerr.NewErrCode(xerr.InvalidAccess), "Invalid Access")
}
userId := u.Id
// 2. Count total sales
var totalSales int64
db := l.svcCtx.DB.WithContext(l.ctx).
Table("`order` o").
Joins("JOIN user u ON o.user_id = u.id").
Where("u.referer_id = ? AND o.status IN ?", userId, []int{2, 5})
if req.StartTime > 0 {
db = db.Where("o.updated_at >= FROM_UNIXTIME(?)", req.StartTime)
}
if req.EndTime > 0 {
db = db.Where("o.updated_at <= FROM_UNIXTIME(?)", req.EndTime)
}
err = db.Count(&totalSales).Error
if err != nil {
l.Errorw("[GetInviteSales] count sales failed",
logger.Field("error", err.Error()),
logger.Field("user_id", userId))
return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError),
"count sales failed: %v", err.Error())
}
// 3. Pagination
if req.Page < 1 {
req.Page = 1
}
if req.Size < 1 {
req.Size = 10
}
if req.Size > 100 {
req.Size = 100
}
offset := (req.Page - 1) * req.Size
// 4. Get sales data
type OrderWithUser struct {
Amount int64 `gorm:"column:amount"`
UpdatedAt int64 `gorm:"column:updated_at"`
UserId int64 `gorm:"column:user_id"`
ProductName string `gorm:"column:product_name"`
Quantity int64 `gorm:"column:quantity"`
}
var orderData []OrderWithUser
query := l.svcCtx.DB.WithContext(l.ctx).
Table("`order` o").
Select("o.amount, CAST(UNIX_TIMESTAMP(o.updated_at) * 1000 AS SIGNED) as updated_at, u.id as user_id, s.name as product_name, o.quantity").
Joins("JOIN user u ON o.user_id = u.id").
Joins("LEFT JOIN subscribe s ON o.subscribe_id = s.id").
Where("u.referer_id = ? AND o.status IN ?", userId, []int{2, 5}) // status 2: Active, 5: Finished
if req.StartTime > 0 {
query = query.Where("o.updated_at >= FROM_UNIXTIME(?)", req.StartTime)
}
if req.EndTime > 0 {
query = query.Where("o.updated_at <= FROM_UNIXTIME(?)", req.EndTime)
}
err = query.Order("o.updated_at DESC").
Limit(req.Size).
Offset(offset).
Scan(&orderData).Error
if err != nil {
l.Errorw("[GetInviteSales] query sales failed",
logger.Field("error", err.Error()),
logger.Field("user_id", userId))
return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError),
"query sales failed: %v", err.Error())
}
// 5. Get sales list
const HashSalt = "ppanel_invite_sales_v1" // Fixed Key
var list []types.InvitedUserSale
for _, order := range orderData {
// Calculate unique numeric hash (FNV-64a)
h := fnv.New64a()
h.Write([]byte(HashSalt))
h.Write([]byte(strconv.FormatInt(order.UserId, 10)))
// Truncate to 10 digits using modulo 10^10
hashVal := h.Sum64() % 10000000000
userHashStr := fmt.Sprintf("%010d", hashVal)
// Format product name: prefer subscribe name, fallback to quantity-based label
productName := order.ProductName
if productName == "" {
productName = fmt.Sprintf("%d天VPN服务", order.Quantity)
if order.Quantity <= 0 {
productName = "VPN服务"
}
}
list = append(list, types.InvitedUserSale{
Amount: float64(order.Amount) / 100.0, // Convert cents to dollars
UpdatedAt: order.UpdatedAt,
UserHash: userHashStr,
ProductName: productName,
})
}
return &types.GetInviteSalesResponse{
Total: totalSales,
List: list,
}, nil
}
internal/types/types.go
+19
View File
@@ -1319,6 +1319,18 @@ type GetInviteRecordsResponse struct {
List []InviteRecord `json:"list"`
}
type GetInviteSalesRequest struct {
Page int `form:"page"`
Size int `form:"size"`
StartTime int64 `form:"start_time"`
EndTime int64 `form:"end_time"`
}
type GetInviteSalesResponse struct {
Total int64 `json:"total"`
List []InvitedUserSale `json:"list"`
}
type GetLogMessageRawRequest struct {
Id int64 `form:"id" validate:"required"`
}
@@ -1852,6 +1864,13 @@ type InviteRecord struct {
CreatedAt int64 `json:"created_at"`
}
type InvitedUserSale struct {
Amount float64 `json:"amount"`
UpdatedAt int64 `json:"updated_at"`
UserHash string `json:"user_hash"`
ProductName string `json:"product_name"`
}
type KickOfflineRequest struct {
Id int64 `json:"id"`
}