文档提交

docs/PACKAGE_DOCS_INDEX.md

@@ -0,0 +1,244 @@
+# 套餐接口文档索引
+
+本目录包含套餐（Package/PackageSeries）相关接口的完整代码结构分析文档。
+
+## 📚 文档清单
+
+### 1. 📋 [完整结构分析](./package_structure_summary.md)
+**用途**：全面了解套餐接口的代码结构
+
+**包含内容**：
+- Model 层文件位置和结构
+- DTO 层请求/响应定义
+- Handler 层方法列表
+- Service 层业务逻辑
+- Store 层数据访问
+- API 路由注册
+- 关键字段详解（duration_days）
+- 业务逻辑关键点
+- 数据库表结构
+- 完整请求/响应示例
+
+**适合场景**：
+- 需要全面了解套餐接口架构
+- 查看具体的代码位置和行号
+- 理解业务逻辑和校验规则
+
+---
+
+### 2. 🎯 [快速导航指南](./package_quick_navigation.md)
+**用途**：快速定位需要的代码
+
+**包含内容**：
+- 按功能快速查找表
+- 按字段快速查找表
+- 按 API 端点快速查找表
+- 关键代码片段
+- 数据流向图
+- 常见操作指南
+- 相关模块链接
+
+**适合场景**：
+- 需要快速找到某个字段或方法
+- 想了解数据流向
+- 需要修改或扩展功能
+
+---
+
+### 3. 🏗️ [架构详细图](./package_architecture_diagram.md)
+**用途**：可视化理解系统架构
+
+**包含内容**：
+- 整体架构流程图
+- 分层详细结构（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. **首次了解**：先读 [架构详细图](./package_architecture_diagram.md)，理解整体流程
+2. **深入学习**：再读 [完整结构分析](./package_structure_summary.md)，了解具体实现
+3. **快速查找**：使用 [快速导航指南](./package_quick_navigation.md)，定位具体代码
+4. **修改代码**：参考 [快速导航指南](./package_quick_navigation.md) 的常见操作部分
+
+---
+
+**最后更新**：2025-04-10
+**文档版本**：1.0