junhong_cmp_fiber/docs/PACKAGE_DOCS_INDEX.md

套餐接口文档索引

本目录包含套餐（Package/PackageSeries）相关接口的完整代码结构分析文档。

📚 文档清单

1. 📋 完整结构分析

用途：全面了解套餐接口的代码结构

包含内容：

• Model 层文件位置和结构
• DTO 层请求/响应定义
• Handler 层方法列表
• Service 层业务逻辑
• Store 层数据访问
• API 路由注册
• 关键字段详解（duration_days）
• 业务逻辑关键点
• 数据库表结构
• 完整请求/响应示例

适合场景：

• 需要全面了解套餐接口架构
• 查看具体的代码位置和行号
• 理解业务逻辑和校验规则

---

2. 🎯 快速导航指南

用途：快速定位需要的代码

包含内容：

• 按功能快速查找表
• 按字段快速查找表
• 按 API 端点快速查找表
• 关键代码片段
• 数据流向图
• 常见操作指南
• 相关模块链接

适合场景：

• 需要快速找到某个字段或方法
• 想了解数据流向
• 需要修改或扩展功能

---

3. 🏗️ 架构详细图

用途：可视化理解系统架构

包含内容：

• 整体架构流程图
• 分层详细结构（Handler/Service/Store）
• 数据模型关系图
• 请求流程示例
• 代理用户查询流程
• 字段验证流程

适合场景：

• 需要理解系统整体架构
• 想了解数据流向和处理过程
• 需要设计新功能时参考

---

🔍 快速查找

按需求查找

需求	文档	位置
查看套餐数据模型	完整结构分析	第 1 节
查看 API 请求/响应结构	完整结构分析	第 2 节
查看 HTTP 处理器	完整结构分析	第 3 节
查看业务逻辑	完整结构分析	第 4 节
查看数据访问	完整结构分析	第 5 节
快速定位代码	快速导航指南	第 1-2 节
理解数据流向	快速导航指南	第 3 节
了解系统架构	架构详细图	第 1-2 节
查看请求流程	架构详细图	第 4-5 节

按文件查找

文件	说明	文档
internal/model/package.go	数据模型	完整结构分析 1.1
internal/model/dto/package_dto.go	DTO 定义	完整结构分析 1.2
internal/handler/admin/package.go	HTTP 处理	完整结构分析 1.3
internal/service/package/service.go	业务逻辑	完整结构分析 1.4
internal/store/postgres/package_store.go	数据访问	完整结构分析 1.5
internal/routes/package.go	路由注册	完整结构分析 2.2
internal/routes/admin.go	路由入口	完整结构分析 2.1

按字段查找

字段	Model 位置	DTO 位置	文档
duration_days	package.go:46	package_dto.go:96	完整结构分析 3.1
calendar_type	package.go:45	package_dto.go:95	完整结构分析 3.1
duration_months	package.go:37	package_dto.go:79	完整结构分析 3.1
real_data_mb	package.go:38	package_dto.go:80	完整结构分析 3.1
virtual_data_mb	package.go:39	package_dto.go:81	完整结构分析 3.1

---

🔑 关键信息速查

duration_days 字段

定义位置：

• Model: internal/model/package.go:46
• DTO: internal/model/dto/package_dto.go:96

用途：

• 当 calendar_type = "by_day" 时必填
• 用于按天计算套餐有效期

验证规则：

• 范围：1-3650 天
• 当 calendar_type = "by_day" 时必须提供

相关校验：

• Service 层校验：internal/service/package/service.go:65-80

---

API 端点总览

方法	路径	处理器	说明
GET	/packages	List()	套餐列表
POST	/packages	Create()	创建套餐
GET	/packages/:id	Get()	获取详情
PUT	/packages/:id	Update()	更新套餐
DELETE	/packages/:id	Delete()	删除套餐
PATCH	/packages/:id/status	UpdateStatus()	更新状态
PATCH	/packages/:id/shelf	UpdateShelfStatus()	更新上架状态
PATCH	/packages/:id/retail-price	UpdateRetailPrice()	更新零售价

路由注册：

• 文件：internal/routes/package.go:11-78
• 入口：internal/routes/admin.go:71-78

---

关键业务逻辑

1. 虚流量配置校验

位置：internal/service/package/service.go:51-63

规则：

• 启用虚流量时，虚流量额度必须 > 0
• 虚流量额度不能大于真流量额度

2. 套餐周期类型校验

位置：internal/service/package/service.go:65-80

规则：

• natural_month：必须提供 duration_months
• by_day：必须提供 duration_days

3. 代理用户套餐过滤

位置：internal/store/postgres/package_store.go:57-66

规则：

• 代理用户只能看到已分配的套餐
• 通过 INNER JOIN tb_shop_package_allocation 实现

---

📊 数据库表

主要表

表名	说明	文档
tb_package	套餐表	完整结构分析 6.1
tb_package_series	套餐系列表	完整结构分析 6.2
tb_package_usage	套餐使用表	架构详细图 3
tb_package_usage_daily_record	日记录表	架构详细图 3
tb_shop_package_allocation	套餐分配表	架构详细图 3

---

🛠️ 常见操作

添加新的套餐字段

1. Model 层：修改 internal/model/package.go 的 Package 结构体
2. DTO 层：修改 internal/model/dto/package_dto.go 的相关 Request/Response
3. Service 层：修改 internal/service/package/service.go 的业务逻辑
4. Store 层：修改 internal/store/postgres/package_store.go 的查询条件
5. 数据库：添加数据库迁移

详见：快速导航指南 第 4 节

修改套餐 API 响应

1. 修改 PackageResponse 结构体（package_dto.go:71-99）
2. 修改 Service 的转换逻辑
3. 测试 API 端点

详见：快速导航指南 第 4 节

添加新的套餐 API 端点

1. 在 PackageHandler 中添加方法
2. 在 PackageService 中添加业务逻辑
3. 在 registerPackageRoutes() 中注册路由

详见：快速导航指南 第 4 节

---

📝 相关文档

• 套餐系统升级：docs/package-system-upgrade/
• 套餐与佣金业务模型：docs/commission-package-model.md
• API 文档生成规范：docs/api-documentation-guide.md

---

🔗 相关模块

模块	说明	文件
PackageSeries	套餐系列管理	internal/routes/package_series.go
PackageUsage	套餐使用记录	internal/routes/package_usage.go
ShopPackageAllocation	套餐分配给代理	internal/store/postgres/shop_package_allocation_store.go
ShopSeriesAllocation	系列分配给代理	internal/store/postgres/shop_series_allocation_store.go

---

💡 使用建议

1. 首次了解：先读 架构详细图，理解整体流程
2. 深入学习：再读 完整结构分析，了解具体实现
3. 快速查找：使用 快速导航指南，定位具体代码
4. 修改代码：参考 快速导航指南 的常见操作部分

---

最后更新：2025-04-10 文档版本：1.0