junhong_cmp_fiber/docs/PACKAGE_DOCS_INDEX.md

# 套餐接口文档索引

本目录包含套餐（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