junhong_cmp_fiber/docs/package-system-upgrade/API文档.md

套餐系统升级 - API 文档

客户端 API

查询我的流量使用情况

获取当前用户绑定的卡/设备的套餐流量使用情况。

请求

GET /api/h5/packages/my-usage
Authorization: Bearer {token}

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "main_package": {
      "package_usage_id": 101,
      "package_id": 1,
      "package_name": "月度套餐 30G",
      "data_limit_mb": 30720,
      "data_usage_mb": 15360,
      "status": 1,
      "priority": 1,
      "activated_at": "2025-02-01T00:00:00Z",
      "expires_at": "2025-02-28T23:59:59Z",
      "data_reset_cycle": "monthly",
      "last_reset_at": "2025-02-01T00:00:00Z",
      "next_reset_at": "2025-03-01T00:00:00Z"
    },
    "addon_packages": [
      {
        "package_usage_id": 102,
        "package_id": 5,
        "package_name": "加油包 5G",
        "data_limit_mb": 5120,
        "data_usage_mb": 2048,
        "status": 1,
        "priority": 2,
        "master_usage_id": 101,
        "activated_at": "2025-02-10T00:00:00Z",
        "expires_at": "2025-02-28T23:59:59Z"
      }
    ],
    "total": {
      "total_mb": 35840,
      "used_mb": 17408,
      "remaining_mb": 18432
    }
  },
  "timestamp": 1707667200
}

响应字段说明

字段	类型	说明
main_package	object	主套餐信息（可能为 null）
addon_packages	array	加油包列表
total.total_mb	int64	总流量（MB）
total.used_mb	int64	已用流量（MB）
total.remaining_mb	int64	剩余流量（MB）

套餐状态 status

值	说明
0	待生效
1	生效中
2	已用完
3	已过期
4	已失效

---

后台管理 API

查询套餐流量详单

查询指定套餐的每日流量使用记录。

请求

GET /api/admin/package-usage/{id}/daily-records
Authorization: Bearer {token}

Query 参数

参数	类型	必填	说明
start_date	string	是	开始日期（YYYY-MM-DD）
end_date	string	是	结束日期（YYYY-MM-DD）

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "package_usage_id": 101,
    "package_name": "月度套餐 30G",
    "records": [
      {
        "date": "2025-02-01",
        "daily_usage_mb": 1024,
        "cumulative_usage_mb": 1024
      },
      {
        "date": "2025-02-02",
        "daily_usage_mb": 512,
        "cumulative_usage_mb": 1536
      },
      {
        "date": "2025-02-03",
        "daily_usage_mb": 2048,
        "cumulative_usage_mb": 3584
      }
    ],
    "total_usage_mb": 15360
  },
  "timestamp": 1707667200
}

错误码

错误码	说明
400	参数错误（日期格式不正确）
403	无权限访问该套餐
404	套餐不存在

---

创建套餐（扩展字段）

创建套餐时支持的新字段。

请求

POST /api/admin/packages
Authorization: Bearer {token}
Content-Type: application/json

请求体

{
  "package_name": "月度套餐 30G",
  "package_type": "main",
  "data_limit_mb": 30720,
  "price": 9900,
  "calendar_type": "natural_month",
  "duration_months": 1,
  "data_reset_cycle": "monthly",
  "enable_realname_activation": false
}

新增字段说明

字段	类型	必填	说明
calendar_type	string	是	有效期类型：natural_month（自然月）、by_day（按天）
duration_months	int	条件必填	自然月套餐的月数（calendar_type=natural_month 时必填）
duration_days	int	条件必填	按天套餐的天数（calendar_type=by_day 时必填）
data_reset_cycle	string	是	流量重置周期：daily、monthly、yearly、none
enable_realname_activation	bool	否	是否需要实名后激活（默认 false）

calendar_type 取值

值	说明	有效期计算
natural_month	自然月	激活月份 + N 个月，月末过期
by_day	按天	激活日期 + N 天

data_reset_cycle 取值

值	说明	重置时间
daily	日重置	每天 00:00:00
monthly	月重置	自然月套餐：每月1号 按天套餐：每30天
yearly	年重置	每年1月1日
none	不重置	不重置

---

更新套餐（扩展字段）

更新套餐时支持的新字段。

请求

PUT /api/admin/packages/{id}
Authorization: Bearer {token}
Content-Type: application/json

请求体

{
  "calendar_type": "by_day",
  "duration_days": 30,
  "data_reset_cycle": "none",
  "enable_realname_activation": true
}

---

查询套餐详情（扩展字段）

获取套餐详情时返回的新字段。

响应

{
  "code": 0,
  "data": {
    "id": 1,
    "package_name": "月度套餐 30G",
    "package_type": "main",
    "data_limit_mb": 30720,
    "price": 9900,
    "calendar_type": "natural_month",
    "duration_months": 1,
    "duration_days": 0,
    "data_reset_cycle": "monthly",
    "enable_realname_activation": false,
    "status": 1,
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-15T00:00:00Z"
  }
}

---

错误码汇总

错误码	HTTP 状态码	说明
CodePackageActivationConflict	409	套餐正在激活中，请稍后重试
CodeNoMainPackage	400	必须有主套餐才能购买加油包
CodeRealnameRequired	403	设备/卡必须先完成实名认证才能购买套餐
CodeMixedOrderForbidden	400	同订单不能同时购买正式套餐和加油包

---

数据权限

客户端 API

• 只能查询当前用户绑定的卡/设备的套餐信息
• 用户身份通过 JWT Token 识别

后台管理 API

• 代理商：只能查询自己店铺及下级店铺的套餐
• 企业用户：只能查询自己企业的套餐
• 平台用户：可查询所有套餐
• 越权访问返回 403 错误