junhong_cmp_fiber/openspec/changes/archive/2026-02-12-package-system-upgrade/specs/package-data-reset/spec.md

Spec: 套餐流量重置周期管理

业务背景

为什么需要流量重置周期管理

现状问题：

• 运营商套餐的流量重置规则多样：按日、按月、按年、不重置
• 套餐有效期与流量重置周期是两个独立维度（如12个月套餐可按月重置流量）
• 不同运营商有特殊规则（如联通按27号重置，而非1号）
• 用户需要清晰知道流量何时重置，避免超额使用

业务目标：

• 支持灵活配置流量重置周期（daily/monthly/yearly/none）
• 流量重置周期独立于套餐有效期类型
• 自动调度流量重置任务（定时任务）
• 保留历史流量使用记录，仅重置当前累计值

---

业务规则

1. 重置周期类型

data_reset_cycle	说明	重置时间点	适用场景
daily	按日重置	每天 00:00:00	日租卡、按日计费套餐
monthly	按月重置	每月1号 00:00:00（联通27号）	月租套餐、年套餐按月清零
yearly	按年重置	每年1月1日 00:00:00	年度套餐
none	不重置	永不重置	一次性流量包

2. 重置时间点规则

通用规则：

每日重置：
- 触发时间：每天 00:00:00
- 重置对象：data_reset_cycle=daily AND status=1（生效中）

每月重置：
- 通用触发时间：每月1号 00:00:00
- 联通特殊规则：每月27号 00:00:00
- 重置对象：data_reset_cycle=monthly AND status=1（生效中）

每年重置：
- 触发时间：每年1月1日 00:00:00
- 重置对象：data_reset_cycle=yearly AND status=1（生效中）

联通特殊规则：

• 如果套餐的 isp=unicom（联通），data_reset_cycle=monthly → 每月27号00:00:00重置
• 其他运营商按1号重置

3. 重置逻辑

重置流量时的操作：

重置流程：
1. 查询需要重置的套餐（根据 data_reset_cycle 和 status=1）
2. 批量更新：
   - data_usage_mb = 0
   - last_reset_at = 当前时间
3. 不删除 PackageUsageDailyRecord 历史记录
4. 记录重置日志

不重置的内容：

• ❌ PackageUsageDailyRecord 历史记录（保留）
• ❌ 套餐有效期（expires_at 不变）
• ❌ 套餐状态（status 不变）
• ✅ 仅重置 data_usage_mb = 0

4. 重置条件

仅对以下套餐执行重置：

• status=1（生效中）
• data_reset_cycle != none
• expires_at > 当前时间（未过期）

不重置的套餐：

• status=0（待生效）
• status=2（已用完）
• status=3（已过期）
• status=4（已失效）
• data_reset_cycle=none（不重置）

5. 流量重置与套餐有效期独立

流量重置周期与套餐有效期类型独立：

套餐配置	流量重置行为	举例
12个月套餐 + monthly	每月1号重置流量，共重置12次	年套餐按月清零
12个月套餐 + yearly	激活时清零，12个月内不重置	年度总量套餐
30天套餐 + daily	每天0点重置流量，共重置30次	日租卡
30天套餐 + none	30天内累计使用，不重置	一次性流量包

---

ADDED Requirements

Requirement: 支持流量重置周期配置

系统 SHALL 支持为套餐配置流量重置周期（data_reset_cycle），可选值为 daily、monthly、yearly、none。

Scenario: 创建按日重置的套餐

• WHEN 管理员创建套餐时指定 data_reset_cycle=daily
• THEN 系统创建成功，套餐的 data_reset_cycle=daily

Scenario: 创建按月重置的套餐

• WHEN 管理员创建套餐时指定 data_reset_cycle=monthly
• THEN 系统创建成功，套餐的 data_reset_cycle=monthly

Scenario: 创建按年重置的套餐

• WHEN 管理员创建套餐时指定 data_reset_cycle=yearly
• THEN 系统创建成功，套餐的 data_reset_cycle=yearly

Scenario: 创建不重置流量的套餐

• WHEN 管理员创建套餐时指定 data_reset_cycle=none
• THEN 系统创建成功，套餐的 data_reset_cycle=none

Scenario: 更新套餐的重置周期配置

• GIVEN 套餐 ID=123，data_reset_cycle=monthly
• WHEN 管理员更新套餐配置为 data_reset_cycle=daily
• THEN 系统更新成功，该套餐后续流量重置遵循新配置
• AND 已有的 PackageUsage 不受影响（仍按原配置重置）

Requirement: 流量重置周期独立于套餐有效期

系统 SHALL 允许套餐的流量重置周期与套餐有效期类型独立配置。

Scenario: 12个月套餐按月重置流量

• GIVEN 套餐配置为 duration_months=12, data_reset_cycle=monthly
• WHEN 套餐在 2026-02-01 激活
• THEN 套餐有效期到 2027-01-31，流量在每月1号重置（共12次）

Scenario: 12个月套餐按年重置流量

• GIVEN 套餐配置为 duration_months=12, data_reset_cycle=yearly
• WHEN 套餐在 2026-02-01 激活
• THEN 套餐有效期到 2027-01-31，流量仅在激活时清零，12个月内不重置

Scenario: 30天套餐按日重置流量

• GIVEN 套餐配置为 duration_days=30, data_reset_cycle=daily
• WHEN 套餐在 2026-02-01 激活
• THEN 套餐有效期到 2026-03-02，流量每天0点重置（共30次）

Scenario: 自然月套餐按月重置

• GIVEN 套餐配置为 calendar_type=natural_month, duration_months=1, data_reset_cycle=monthly
• WHEN 套餐在 2026-02-15 激活
• THEN 套餐有效期到 2026-02-28，流量在3月1日不重置（因为套餐已过期）

Requirement: 每日流量重置调度

系统 SHALL 每天 00:00:00 自动重置所有 data_reset_cycle=daily 的生效中套餐的 data_usage_mb 为 0。

Scenario: 每日流量重置成功

• GIVEN 系统时间到达 2026-02-11 00:00:00
• AND 存在3个 data_reset_cycle=daily 且 status=1 的套餐
• WHEN 定时任务执行
• THEN 系统批量更新这3个套餐：
  • data_usage_mb = 0
  • last_reset_at = 2026-02-11 00:00:00

Scenario: 非每日重置套餐不受影响

• GIVEN 系统时间到达 2026-02-11 00:00:00
• AND 存在 data_reset_cycle=monthly 的套餐
• WHEN 定时任务执行
• THEN 这些套餐的 data_usage_mb 不变

Scenario: 待生效和已过期套餐不重置

• GIVEN 系统时间到达 2026-02-11 00:00:00
• AND 存在 data_reset_cycle=daily 但 status=0（待生效）的套餐
• AND 存在 data_reset_cycle=daily 但 status=3（已过期）的套餐
• WHEN 定时任务执行
• THEN 这些套餐不被重置

Scenario: 每日重置记录到日志

• GIVEN 系统时间到达 2026-02-11 00:00:00
• AND 重置了5个套餐
• WHEN 定时任务执行完成
• THEN 系统记录 Info 日志：
  • "每日流量重置完成，重置套餐数量：5"

Requirement: 每月流量重置调度

系统 SHALL 每月1号 00:00:00 自动重置所有 data_reset_cycle=monthly 的生效中套餐的 data_usage_mb 为 0。

Scenario: 每月流量重置成功

• GIVEN 系统时间到达 2026-03-01 00:00:00
• AND 存在5个 data_reset_cycle=monthly 且 status=1 的套餐（非联通）
• WHEN 定时任务执行
• THEN 系统批量更新这5个套餐：
  • data_usage_mb = 0
  • last_reset_at = 2026-03-01 00:00:00

Scenario: 联通运营商特殊重置周期

• GIVEN 系统时间到达 2026-02-27 00:00:00
• AND 存在3个 data_reset_cycle=monthly 且 isp=unicom 且 status=1 的套餐
• WHEN 定时任务执行
• THEN 系统批量更新这3个套餐：
  • data_usage_mb = 0
  • last_reset_at = 2026-02-27 00:00:00

Scenario: 跨月边界流量统计

• GIVEN 套餐在 2026-01-31 23:50:00 使用了 5GB 流量
• AND data_usage_mb = 5GB
• WHEN 系统时间到达 2026-02-01 00:00:00，触发重置
• THEN 套餐的 data_usage_mb 重置为 0
• AND 1月31日的 PackageUsageDailyRecord 仍存在（data_usage_mb=5GB）

Scenario: 跨年边界流量重置

• GIVEN 套餐在 2026-12-31 使用了 10GB 流量
• WHEN 系统时间到达 2027-01-01 00:00:00，触发重置
• THEN 套餐的 data_usage_mb 重置为 0
• AND 2026年12月的日记录仍存在

Requirement: 每年流量重置调度

系统 SHALL 每年1月1日 00:00:00 自动重置所有 data_reset_cycle=yearly 的生效中套餐的 data_usage_mb 为 0。

Scenario: 每年流量重置成功

• GIVEN 系统时间到达 2027-01-01 00:00:00
• AND 存在2个 data_reset_cycle=yearly 且 status=1 的套餐
• WHEN 定时任务执行
• THEN 系统批量更新这2个套餐：
  • data_usage_mb = 0
  • last_reset_at = 2027-01-01 00:00:00

Scenario: 12个月套餐按年重置

• GIVEN 套餐在 2026-06-15 激活，duration_months=12，data_reset_cycle=yearly
• AND expires_at=2027-06-15
• WHEN 系统时间到达 2027-01-01 00:00:00
• THEN 套餐流量重置（因为仍在有效期内）

Scenario: 已过期的年套餐不重置

• GIVEN 套餐在 2025-06-15 激活，duration_months=12，data_reset_cycle=yearly
• AND expires_at=2026-06-15（已过期）
• WHEN 系统时间到达 2027-01-01 00:00:00
• THEN 套餐不被重置（status=3）

Requirement: 不重置流量的套餐

系统 SHALL 对 data_reset_cycle=none 的套餐，在整个有效期内不重置 data_usage_mb。

Scenario: 套餐有效期内流量不重置

• GIVEN 套餐 data_reset_cycle=none，duration_days=30
• AND 套餐在 2026-02-01 激活
• WHEN 套餐在30天内使用了 80GB 流量
• THEN data_usage_mb 累计为 80GB，期间从未重置

Scenario: 新激活时流量清零

• GIVEN 套餐 data_reset_cycle=none
• WHEN 套餐首次激活
• THEN data_usage_mb 初始化为 0

Scenario: 不重置套餐不被定时任务影响

• GIVEN 系统时间到达每日/每月/每年重置时刻
• AND 存在 data_reset_cycle=none 的套餐
• WHEN 定时任务执行
• THEN 这些套餐不被查询，不执行任何操作

Requirement: 流量重置周期信息可查询

系统 SHALL 在套餐详情和使用记录 API 中返回 data_reset_cycle 和 last_reset_at。

Scenario: 查询套餐流量重置配置

• WHEN 用户通过 GET /api/admin/packages/:id 查询套餐
• THEN 响应包含：

  {
    "data_reset_cycle": "monthly",
    "isp": "unicom"
  }
  

Scenario: 查询套餐使用记录的重置信息

• WHEN 用户通过 GET /api/admin/package-usage/:id 查询套餐使用记录
• THEN 响应包含：

  {
    "data_reset_cycle": "monthly",
    "last_reset_at": "2026-02-27T00:00:00Z",
    "data_usage_mb": 1024
  }
  

Scenario: 客户端查询流量重置信息

• WHEN 客户通过 GET /api/customer/package-usage 查询自己的套餐
• THEN 响应包含 data_reset_cycle 和 last_reset_at，方便用户知道下次重置时间

Requirement: 流量重置不影响日记录

系统 SHALL 在流量重置时保留历史日记录（PackageUsageDailyRecord），仅重置当前 data_usage_mb。

Scenario: 重置后历史记录可查

• GIVEN 套餐在 2026-02-28 使用了 10GB 流量
• AND PackageUsageDailyRecord 记录了 2026-02-28 的 10GB 使用量
• WHEN 系统时间到达 2026-03-01 00:00:00，触发重置
• THEN 套餐的 data_usage_mb 重置为 0
• AND 2026-02-28 的 PackageUsageDailyRecord 记录仍存在且可查询

Scenario: 重置后新的流量使用

• GIVEN 套餐在 2026-03-01 00:00:00 重置后，data_usage_mb=0
• WHEN 2026-03-01 10:00:00 使用了 2GB 流量
• THEN 套餐的 data_usage_mb=2GB
• AND 写入新的 PackageUsageDailyRecord（date=2026-03-01, data_usage_mb=2GB）

---

边界条件

1. 跨月边界

• 场景：套餐在月末23:59:59使用流量，次月0:00:00触发重置
• 处理：
  • 重置任务在 00:00:00 执行
  • 月末最后一笔流量扣减已提交（日记录已写入）
  • 重置时仅清零 data_usage_mb，不影响日记录

2. 跨年边界

• 场景：套餐在12月31日使用流量，1月1日触发年度重置
• 处理：
  • 与跨月边界相同
  • 年度重置只重置 data_reset_cycle=yearly 的套餐
  • 月度重置套餐不受年度重置影响

3. 并发流量扣减和重置

• 场景：重置任务执行的同时，有流量扣减请求
• 处理：
  • 使用行锁：SELECT * FROM package_usage WHERE id=? FOR UPDATE
  • 先完成的操作生效，后完成的操作基于新值执行
  • 如果重置先完成 → 流量扣减从0开始累加
  • 如果扣减先完成 → 重置清零后续扣减继续

4. 定时任务执行延迟

• 场景：定时任务因系统负载延迟到 00:05:00 才执行
• 处理：
  • 仍按计划重置所有符合条件的套餐
  • last_reset_at 记录实际重置时间（00:05:00）
  • 不影响下次重置周期（仍按 00:00:00 计算）

5. 套餐过期与重置时间重合

• 场景：套餐在 2026-03-01 00:00:00 过期，同时触发月度重置
• 处理：
  • 过期任务将套餐 status=3
  • 重置任务查询时排除 status=3 的套餐
  • 不执行重置操作

---

并发场景

Scenario: 并发流量扣减和重置

• GIVEN 套餐 ID=123，data_usage_mb=5GB
• WHEN 同时发生：
  • 请求1：流量扣减 1GB
  • 请求2：定时任务重置流量
• THEN 使用行锁：

  SELECT * FROM package_usage WHERE id=123 FOR UPDATE
  

• AND 如果请求1先完成：
  • data_usage_mb = 6GB
  • 请求2重置 → data_usage_mb = 0
• AND 如果请求2先完成：
  • data_usage_mb = 0
  • 请求1扣减 → data_usage_mb = 1GB

Scenario: 并发多套餐重置

• GIVEN 有1000个 data_reset_cycle=daily 的套餐
• WHEN 定时任务批量重置
• THEN 系统：
  • 分批处理（每批100个）
  • 每批使用单独事务
  • 失败批次记录日志，不影响其他批次

---

异常处理

1. 重置任务失败

• 错误场景：定时任务执行时数据库连接失败
• 处理流程：
  1. 捕获错误，记录 Error 日志（包含失败原因、影响套餐数量）
  2. 使用 Asynq 重试机制（最多3次，间隔 10s/30s/60s）
  3. 重试前检查套餐 last_reset_at（避免重复重置）
  4. 3次失败后写入死信队列，发送告警
• 返回错误：不返回给用户（定时任务），仅记录日志

2. 批量重置部分失败

• 错误场景：批量重置1000个套餐，第500个套餐更新失败
• 处理流程：
  1. 分批处理（每批100个），每批独立事务
  2. 失败批次回滚，其他批次正常提交
  3. 记录失败批次的套餐ID列表
  4. Asynq 重试失败批次
• 返回错误：不返回给用户（定时任务），仅记录日志

3. last_reset_at 更新失败

• 错误场景：data_usage_mb 重置成功，但 last_reset_at 更新失败
• 处理流程：
  1. 使用事务包裹两个更新操作
  2. 任何一个失败 → 事务回滚，全部不更新
  3. 记录 Error 日志
  4. Asynq 重试
• 返回错误：不返回给用户（定时任务），仅记录日志

---

数据一致性保证

1. 事务边界

• 批量重置套餐：每批使用单独事务，确保原子性
• 流量扣减 + 重置并发：使用行锁，确保顺序执行

2. 行锁机制

• 重置套餐时加锁：SELECT * FROM package_usage WHERE id IN (...) FOR UPDATE
• 流量扣减时加锁：SELECT * FROM package_usage WHERE id=? FOR UPDATE

3. 幂等性保证

• 重置任务幂等：重试前检查 last_reset_at，如果已是今日则跳过
• 示例：

  UPDATE package_usage
  SET data_usage_mb = 0, last_reset_at = NOW()
  WHERE data_reset_cycle = 'daily'
    AND status = 1
    AND (last_reset_at IS NULL OR DATE(last_reset_at) < CURDATE());
  

4. 数据校验

• 重置前：校验套餐 status=1（生效中）
• 重置前：校验套餐 expires_at > 当前时间（未过期）
• 重置后：校验 data_usage_mb=0 且 last_reset_at 已更新

---

性能指标

操作	目标响应时间	并发要求	数据量
每日流量重置（单批）	< 500ms	定时任务	批量更新（100个套餐/批）
每月流量重置（单批）	< 500ms	定时任务	批量更新（100个套餐/批）
每年流量重置（单批）	< 500ms	定时任务	批量更新（100个套餐/批）
查询重置周期配置	< 50ms	100 QPS	单套餐查询

---

错误码定义

错误码	HTTP 状态码	错误消息	场景
RESET_TASK_FAILED	500	流量重置任务失败，请联系管理员	定时任务执行失败
INVALID_RESET_CYCLE	400	无效的重置周期配置	data_reset_cycle 值不合法
LAST_RESET_AT_UPDATE_FAILED	500	更新重置时间失败	last_reset_at 更新失败

---

数据迁移策略

激进策略（开发阶段，保证干净性）：

1. ❌ 要删除的字段

目前 package 表中可能存在的冗余字段（需确认后删除）：

• 如果有 reset_interval 字段（旧的重置间隔） → 删除
• 如果有 reset_day 字段（旧的重置日期） → 删除

目前 package_usage 表中可能存在的冗余字段（需确认后删除）：

• 如果有 last_reset_date 字段（旧的重置日期，非时间戳） → 删除

2. ✅ 新增的字段

在 package 表中新增：

ALTER TABLE package
ADD COLUMN data_reset_cycle VARCHAR(10) DEFAULT 'none' COMMENT '流量重置周期（daily/monthly/yearly/none）',
ADD COLUMN isp VARCHAR(20) DEFAULT NULL COMMENT '运营商（unicom/mobile/telecom，用于特殊重置规则）';

CREATE INDEX idx_data_reset_cycle ON package(data_reset_cycle);

在 package_usage 表中新增：

ALTER TABLE package_usage
ADD COLUMN last_reset_at DATETIME DEFAULT NULL COMMENT '最后一次流量重置时间';

CREATE INDEX idx_last_reset_at ON package_usage(last_reset_at);

3. ❌ 要废弃的逻辑

• 废弃旧的重置逻辑：如果代码中存在通过 reset_interval 或 reset_day 字段计算重置的逻辑，全部删除
• 废弃旧的定时任务：如果存在旧的流量重置定时任务，全部删除
• 废弃旧的重置时间字段：统一使用 last_reset_at（DATETIME），删除其他相关字段

4. ✅ 历史数据强制转换

-- Step 1: 历史套餐的重置周期初始化
-- 假设历史套餐默认为按月重置（需根据实际业务规则调整）
UPDATE package
SET data_reset_cycle = 'monthly'
WHERE data_reset_cycle IS NULL;

-- 如果历史有特殊类型，可以根据 duration 或其他字段推断：
-- 例如：duration_days=1 → data_reset_cycle='daily'
UPDATE package
SET data_reset_cycle = 'daily'
WHERE duration_days = 1
  AND data_reset_cycle IS NULL;

-- Step 2: 历史套餐的运营商初始化
-- 假设历史套餐默认为移动（需根据实际业务规则调整）
UPDATE package
SET isp = 'mobile'
WHERE isp IS NULL;

-- Step 3: 历史 PackageUsage 的 last_reset_at 初始化
-- 如果有旧的 last_reset_date 字段，转换为 last_reset_at
-- UPDATE package_usage
-- SET last_reset_at = STR_TO_DATE(last_reset_date, '%Y-%m-%d')
-- WHERE last_reset_date IS NOT NULL;

-- 如果没有旧字段，根据 activated_at 推断：
-- 按月重置：last_reset_at = 当前月的1号
-- 按日重置：last_reset_at = 今天0点
-- 按年重置：last_reset_at = 今年1月1日
-- 不重置：last_reset_at = NULL

UPDATE package_usage pu
JOIN package p ON pu.package_id = p.id
SET pu.last_reset_at = DATE_FORMAT(CURDATE(), '%Y-%m-01 00:00:00')
WHERE p.data_reset_cycle = 'monthly'
  AND pu.status = 1
  AND pu.last_reset_at IS NULL;

UPDATE package_usage pu
JOIN package p ON pu.package_id = p.id
SET pu.last_reset_at = DATE_FORMAT(CURDATE(), '%Y-%m-%d 00:00:00')
WHERE p.data_reset_cycle = 'daily'
  AND pu.status = 1
  AND pu.last_reset_at IS NULL;

UPDATE package_usage pu
JOIN package p ON pu.package_id = p.id
SET pu.last_reset_at = DATE_FORMAT(CURDATE(), '%Y-01-01 00:00:00')
WHERE p.data_reset_cycle = 'yearly'
  AND pu.status = 1
  AND pu.last_reset_at IS NULL;

-- Step 4: data_reset_cycle=none 的套餐不设置 last_reset_at
-- （保持 NULL）

5. ❌ 删除遗留表/字段（确认后执行）

-- 如果存在旧的重置相关字段，删除
-- ALTER TABLE package DROP COLUMN IF EXISTS reset_interval;
-- ALTER TABLE package DROP COLUMN IF EXISTS reset_day;
-- ALTER TABLE package_usage DROP COLUMN IF EXISTS last_reset_date;

6. 验证步骤

-- 验证1：所有套餐都有 data_reset_cycle
SELECT COUNT(*)
FROM package
WHERE data_reset_cycle IS NULL;
-- 预期结果：0

-- 验证2：data_reset_cycle 值合法
SELECT COUNT(*)
FROM package
WHERE data_reset_cycle NOT IN ('daily', 'monthly', 'yearly', 'none');
-- 预期结果：0

-- 验证3：生效中套餐的 last_reset_at 不为空（除了 data_reset_cycle=none）
SELECT COUNT(*)
FROM package_usage pu
JOIN package p ON pu.package_id = p.id
WHERE pu.status = 1
  AND p.data_reset_cycle != 'none'
  AND pu.last_reset_at IS NULL;
-- 预期结果：0

-- 验证4：检查是否还有遗留字段（需根据实际情况调整）
-- SELECT column_name FROM information_schema.columns
-- WHERE table_name = 'package'
--   AND column_name IN ('reset_interval', 'reset_day');
-- 预期结果：0 rows

---

测试场景矩阵

场景分类	测试用例	预期结果
配置重置周期	创建按日重置套餐	data_reset_cycle=daily
	创建按月重置套餐	data_reset_cycle=monthly
	创建按年重置套餐	data_reset_cycle=yearly
	创建不重置套餐	data_reset_cycle=none
每日重置	每日0点重置	data_usage_mb=0, last_reset_at=今日0点
	非每日重置套餐不受影响	data_usage_mb 不变
	待生效/已过期套餐不重置	data_usage_mb 不变
每月重置	每月1号重置	data_usage_mb=0, last_reset_at=本月1号0点
	联通特殊规则（27号重置）	data_usage_mb=0, last_reset_at=本月27号0点
	跨月边界流量统计	日记录保留，data_usage_mb 重置
每年重置	每年1月1日重置	data_usage_mb=0, last_reset_at=今年1月1日0点
	已过期年套餐不重置	data_usage_mb 不变
不重置	有效期内流量累计	data_usage_mb 持续累加
	定时任务不影响	data_usage_mb 不变
历史记录	重置后历史记录可查	PackageUsageDailyRecord 存在
	重置后新流量使用	新日记录写入
并发	并发流量扣减和重置	使用行锁，顺序执行
	并发多套餐重置	分批处理，失败批次不影响其他
异常	重置任务失败	Asynq 重试，记录日志
	批量重置部分失败	失败批次回滚，其他批次正常

---

实现参考

每日流量重置定时任务

// Handler: HandleDailyReset
func (h *DataResetHandler) HandleDailyReset(ctx context.Context, task *asynq.Task) error {
    const batchSize = 100

    // 1. 查询需要重置的套餐ID列表
    usageIDs, err := h.packageUsageStore.ListDailyResetUsageIDs(ctx)
    if err != nil {
        return fmt.Errorf("list daily reset usage ids failed: %w", err)
    }

    if len(usageIDs) == 0 {
        h.logger.Info("无需要每日重置的套餐")
        return nil
    }

    // 2. 分批重置
    totalCount := 0
    failedCount := 0

    for i := 0; i < len(usageIDs); i += batchSize {
        end := i + batchSize
        if end > len(usageIDs) {
            end = len(usageIDs)
        }

        batchIDs := usageIDs[i:end]

        // 使用独立事务
        tx := h.db.Begin()
        err := h.resetUsageBatch(ctx, tx, batchIDs)
        if err != nil {
            tx.Rollback()
            failedCount += len(batchIDs)
            h.logger.Error("批量重置失败", zap.Error(err), zap.Ints("batch_ids", batchIDs))
            continue
        }

        if err := tx.Commit().Error; err != nil {
            failedCount += len(batchIDs)
            h.logger.Error("提交事务失败", zap.Error(err))
            continue
        }

        totalCount += len(batchIDs)
    }

    h.logger.Info("每日流量重置完成",
        zap.Int("total_count", totalCount),
        zap.Int("failed_count", failedCount))

    if failedCount > 0 {
        return fmt.Errorf("部分套餐重置失败，失败数量：%d", failedCount)
    }

    return nil
}

// Store 层：ListDailyResetUsageIDs
func (s *Store) ListDailyResetUsageIDs(ctx context.Context) ([]int, error) {
    var ids []int
    err := s.db.WithContext(ctx).
        Table("package_usage pu").
        Select("pu.id").
        Joins("JOIN package p ON pu.package_id = p.id").
        Where("p.data_reset_cycle = ?", constants.DataResetCycleDaily).
        Where("pu.status = ?", constants.PackageStatusActive).
        Where("pu.expires_at > ?", time.Now()).
        Where("(pu.last_reset_at IS NULL OR DATE(pu.last_reset_at) < CURDATE())").  // 幂等性
        Pluck("pu.id", &ids).Error
    return ids, err
}

// Store 层：resetUsageBatch
func (h *DataResetHandler) resetUsageBatch(ctx context.Context, tx *gorm.DB, ids []int) error {
    return tx.WithContext(ctx).
        Model(&model.PackageUsage{}).
        Where("id IN (?)", ids).
        Updates(map[string]interface{}{
            "data_usage_mb": 0,
            "last_reset_at": time.Now(),
        }).Error
}

每月流量重置定时任务（含联通特殊规则）

// Handler: HandleMonthlyReset
func (h *DataResetHandler) HandleMonthlyReset(ctx context.Context, task *asynq.Task) error {
    // 判断今天是几号
    today := time.Now().Day()

    // 1. 重置非联通套餐（每月1号）
    if today == 1 {
        if err := h.resetMonthlyUsages(ctx, ""); err != nil {
            h.logger.Error("非联通套餐每月重置失败", zap.Error(err))
            return err
        }
    }

    // 2. 重置联通套餐（每月27号）
    if today == 27 {
        if err := h.resetMonthlyUsages(ctx, constants.ISPUnicom); err != nil {
            h.logger.Error("联通套餐每月重置失败", zap.Error(err))
            return err
        }
    }

    return nil
}

// resetMonthlyUsages: 重置按月重置的套餐
func (h *DataResetHandler) resetMonthlyUsages(ctx context.Context, isp string) error {
    const batchSize = 100

    // 查询需要重置的套餐ID列表
    usageIDs, err := h.packageUsageStore.ListMonthlyResetUsageIDs(ctx, isp)
    if err != nil {
        return fmt.Errorf("list monthly reset usage ids failed: %w", err)
    }

    if len(usageIDs) == 0 {
        h.logger.Info("无需要每月重置的套餐", zap.String("isp", isp))
        return nil
    }

    // 分批重置（逻辑与每日重置相同）
    // ...
    return nil
}

// Store 层：ListMonthlyResetUsageIDs
func (s *Store) ListMonthlyResetUsageIDs(ctx context.Context, isp string) ([]int, error) {
    query := s.db.WithContext(ctx).
        Table("package_usage pu").
        Select("pu.id").
        Joins("JOIN package p ON pu.package_id = p.id").
        Where("p.data_reset_cycle = ?", constants.DataResetCycleMonthly).
        Where("pu.status = ?", constants.PackageStatusActive).
        Where("pu.expires_at > ?", time.Now())

    if isp != "" {
        // 联通特殊规则
        query = query.Where("p.isp = ?", isp)
    } else {
        // 非联通套餐
        query = query.Where("p.isp != ?", constants.ISPUnicom)
    }

    // 幂等性：避免重复重置
    query = query.Where("(pu.last_reset_at IS NULL OR DATE(pu.last_reset_at) < CURDATE())")

    var ids []int
    err := query.Pluck("pu.id", &ids).Error
    return ids, err
}

---

本 Spec 完成，包含：

• ✅ 业务背景和业务规则
• ✅ 详细场景（每日/每月/每年重置、不重置、联通特殊规则）
• ✅ 边界条件和并发场景
• ✅ 异常处理和数据一致性保证
• ✅ 性能指标和错误码定义
• ✅ 激进的数据迁移策略（明确删除字段、废弃逻辑、强制转换）
• ✅ 测试场景矩阵和实现参考