# NexusGate 客户流量按月自动重置 — 实施报告

日期：2026-10-20 ｜ 基线：`f4ef3d9` ｜ 范围：独立功能，不含任何数据迁移代码。

## 0. 开工前工作区处理

`git status` 检查结果：工作区与 HEAD (`f4ef3d9`) 一致，无已修改文件；上一条被中止的
迁移工作流未留下任何残件。唯一未跟踪文件 `LINK-MIGRATION.md` 是更早的链接迁移说明
文档（本功能之前就未入仓），与本功能无关 — 原样保留，未纳入本次提交。

## 1. 用量模型摸底（设计前提）

- 客户用量记在客户记录的三个字段：`usedBytes` / `usedUplinkBytes` / `usedDownlinkBytes`，
  由 orchestrator 按 agent 上报的 epoch 累计计数做增量累加（面板侧累计制）。
- 额度判定全部读 `usedBytes`：`CustomerBlockReason`、housekeeping 的额度暂停、
  客户状态变更守卫、订阅发放前检查，四处同一口径。
- 订阅输出（`Subscription-Userinfo` 头与订阅信息页）读同三字段，其中
  `historical = usedBytes - up - down`（≥0）是给"只灌总数"的导入数据兜底的派生量。
- 模型没有独立的终身累计字段：三字段既是周期计数也是展示口径。已有手动
  `POST /api/customers/:id/reset-usage` 把三字段同时清零并在拦截消除后恢复客户 —
  本功能与其保持完全一致的清零语义。
- **绝不能动**的是各 server/nodeClient 上的 epoch 基线计数器
  （`serverUsage[].usageCounters` 等）：那是增量记账的基准，清了会重复计费。
  本功能只动客户三字段。

## 2. 设计

### 字段（客户级，共享 JSON schema，全部 omitempty）

| 字段 | 类型 | 含义 |
|---|---|---|
| `trafficResetDay` | int | 每月重置日 1–31；0/缺省 = 不重置 |
| `trafficResetPeriod` | string | 幂等标记：上次已应用重置所属周期键 `YYYY-MM` |
| `trafficResetAt` | string(ISO) | 上次实际重置时间（展示用） |

Node 版面板无副作用已核实：Node 的客户 PATCH 是逐字段改已加载对象、整对象落盘，
未知字段原样保留；Node 只是不执行重置逻辑（生产主控是 Go 版）。

### 周期键与触发判定（纯函数，无内存状态）

- 某月的重置时刻 = `min(重置日, 当月天数)` 号 00:00（面板本地时间）— 31 号遇
  2 月在 28 号触发，闰年 29 号正常存在。
- 周期键 = `now` 时刻"最近一个已到来的重置时刻"所在月份（`YYYY-MM`）。
  跨过重置时刻键才翻页。
- 判定（housekeeping 每轮）：`marker != 当前周期键` 且 marker 非空 ⇒ 到期，执行一次
  清零并把 marker 写为当前键。**面板停机跨过多个周期也只清一次**（落到当前周期），
  这就是重启补判：不依赖 ticker 记忆，第一轮 housekeeping（启动后 ≤60 秒，
  与 Node 版同节律，未额外加启动调用以保持差分行为对齐）即补触发。

### 布防（arm）语义 — 防误清

- marker 为空（老数据、或外部写入只写了 `trafficResetDay`）时，第一轮检查只写
  marker、**不清零**：本周期已累计用量保留，下个重置日正常触发。
- API 创建客户带重置日、或 PATCH **改动**重置日时，当场布防（新排期从下个重置
  时刻生效，绝不在设置瞬间清零）。PATCH 回显**未改动**的值不重布防 — 否则管理员
  在"到期未触发"的窗口里编辑客户会把待触发的重置吞掉。

### 到期动作（镜像手动清零）

1. 三计数清零；marker ← 当前周期键；`trafficResetAt` / `updatedAt` ← 现在；
2. 写审计 `reset_customer_usage_monthly`（actor `system:monthly_reset`，
  detail 含清零前用量、重置日、周期键）；
3. 若客户是 `traffic_limit` 暂停且清零后无其它拦截（未过期等），自动恢复
  active 并 `ResumeCustomerResources`（与手动清零同路径）。
   手动暂停、到期暂停的客户只清零、不恢复。

### 挂载点

`main.go` 的 60 秒 housekeeping 事务内、额度暂停评估**之前**调用
`ApplyMonthlyTrafficResets`（`panel-go/reset.go`）— 同事务原子生效：清零后本轮
额度判定即按新周期口径走。不新起 goroutine，内存零增量（几个时间计算/客户）。

### API / UI 配套（最小）

- `POST /api/customers` 与 `PATCH /api/customers/:id` 接受 `trafficResetDay`
  （0–31 整数，null = 清除；32 / 小数 / 负数 → 400）。
- 前端客户表单新增"每月流量重置日"输入（0 不重置 + 说明），编辑时回显
  "上次重置 时间"；提交 payload 带该字段。`public/app.js` 与
  `panel-go/embed_public/app.js`（构建期副本）已同步。

## 3. 改动清单

| 文件 | 改动 |
|---|---|
| `panel-go/types.go` | Customer 加 3 字段（+3 行） |
| `panel-go/reset.go` | 新增：周期键/时刻计算、布防、到期应用、入参校验 |
| `panel-go/main.go` | housekeeping 事务内挂载（+9 行） |
| `panel-go/handlers.go` | 创建/PATCH 接受并布防 `trafficResetDay`（+22 行） |
| `public/app.js` | 表单字段 + payload（+3/−1 行） |
| `panel-go/reset_test.go` | 新增测试（14 个测试函数） |
| `MONTHLY-RESET-REPORT.md` | 本报告 |

## 4. 测试清单与结果

**基线（改动前）**：panel-go `go test ./...` 全过；Node `node --test` 52/52。

**新增用例**（`panel-go/reset_test.go`，全部通过）：

| 用例 | 覆盖点 |
|---|---|
| `TestTrafficResetPeriodKey` | 16 个历法断言：跨月、时刻整点边界、同日、年翻转（1/1→上年 12 月）、31→2/28 夹逼、30→2 月、29 闰/非闰年 |
| `TestApplyMonthlyResetDueAndIdempotent` | 正常跨月触发清零 + marker/resetAt/审计落位；同周期二次检查不清零（新流量保留） |
| `TestApplyMonthlyResetNotYetDue` | 本周期已重置者不动 |
| `TestApplyMonthlyResetArmsOnFirstSight` | marker 空只布防不清零；布防后下个周期正常触发 |
| `TestApplyMonthlyResetCatchUpMissedPeriods` | 停机跨 4 个周期（重启补判）：只清一次、落当前周期、审计恰 1 条 |
| `TestApplyMonthlyResetShortMonthClamp` | 31 号：2/27 不触发、2/28 00:01 触发且周期为 2 月 |
| `TestApplyMonthlyResetIndependentDays` | 多客户不同重置日互不干扰（1 号已清、25 号未动） |
| `TestApplyMonthlyResetUnsetOrInvalidUntouched` | 未设置 / 45 / −3 的客户完全不受影响 |
| `TestApplyMonthlyResetResumesTrafficSuspended` | 流量暂停客户清零后自动恢复、拦截原因消除 |
| `TestApplyMonthlyResetKeepsOtherSuspensions` | 手动暂停 / 到期暂停：只清零不恢复 |
| `TestParseResetDay` | nil/0/1/31/json.Number 合法；32/2.5/−1 拒绝 |
| `TestResetFieldsPersistAndOmitWhenUnset` | 落盘原文含三字段、重载不丢；未设置客户 JSON 不出现新键（Node 互通前提） |
| `TestHousekeepingAppliesMonthlyReset` | 走真实 housekeeping 全链：到期清零、周期落位；第二轮不重复清 |
| `TestCustomerAPIResetDayLifecycle` | 登录后 API 全程：创建带日（布防、无 resetAt）→ PATCH 32 被拒 → 改日重布防 → 清 0 后记录中字段消失 |

**改动后全套**：

- panel-go `go test ./...` 全过（另 `-count=1` 全量复跑过）；`gofmt` / `go vet` 干净。
- agent-go `go test ./...` 全过（未改动，回归确认）。
- Node `node --test` 52/52；`npm run check`（server.js / agent / app.js 语法）通过。
- **差分 E2E（difftest）正式模式 50/50 PASS**（Node vs Go 同种子同剧本，
  含客户 PATCH 与客户列表比对）— 新增字段未扰动任何既有响应形状。

## 5. 代码自审清单（边界专项）

| # | 发现 | 处置 |
|---|---|---|
| 1 | `TrafficResetPeriodKey` 初版混用时区：年月取 `now` 的 Location、时刻构造写死 `time.Local`，两者不一致必算错 | **已修**：全程 `now.Location()`；`daysInMonth` 改纯历法（UTC）计算；历法测试全程显式构造本地时间 |
| 2 | epoch 基线计数器（serverUsage / nodeClient usageCounters）若被清会重复计费 | 已确认设计只动客户三字段，基线零接触（见 §1） |
| 3 | 事务原子性：重置在 housekeeping 事务内，若 `ResumeCustomerResources` 出错整轮回滚 — marker 与计数同生同灭，下轮重试，不会出现"清了零但 marker 没落"或重复清 | 核实 `Store.Transaction` 为 clone-草稿语义后**接受**；代价：单个客户恢复出错会阻塞整轮 housekeeping，与既有 ip_limit 恢复同构 |
| 4 | 跨界流量归属：重置时刻前后一个上报周期（≤60 秒）的增量整笔计入新周期 | 清零式重置的固有近似（3x-ui 同样），量级 ≤1 分钟流量，**接受并记录** |
| 5 | PATCH 回显吞重置：前端每次编辑都回显该字段，若"提交即布防"会在到期窗口内吞掉待触发重置 | **已防**：仅值变化才重布防（§2），API 测试覆盖 |
| 6 | PATCH 传 `trafficResetDay: null` 的语义 | 定为清除，与 `expiresAt` 的 null 清除口径一致 |
| 7 | marker 被写成垃圾字符串（仅可能来自手工改库） | 按"到期"处理：清一次后写入合法键自愈收敛；前提是重置日本身合法，**接受** |
| 8 | DST：00:00 在个别时区不存在（春跳日） | Go `time.Date` 自动顺延，周期键不受影响；生产时区 Asia/Shanghai 无 DST，**记录** |
| 9 | 多名流量暂停客户同轮恢复 → 每人可能触发节点重建下发 | 与手动清零恢复同路径同量级，路由器客户规模小，**接受** |
| 10 | 临时回滚到 Node 版当主控时重置停摆 | Node 不执行但不破坏字段；切回 Go 后按 marker 补判、不会重复清（幂等），**记录为运维须知** |
| 11 | 补判延迟：启动后第一轮 housekeeping 在 ≤60 秒 | 满足"启动/下个检查点补触发"；未加启动即时调用是为与 Node 节律保持差分对齐，**接受** |

自审未发现其它未处置的边界问题。

## 6. 与迁移的衔接点

- 转换器对 13 名按月重置客户**只需写 `trafficResetDay`（1–31）**，
  `trafficResetPeriod` 可不写：面板首轮自动布防、绝不误清迁移带入的期初用量，
  到下个重置日正常触发。若转换器想显式写 marker，写"转换时刻的当前周期键"即可
  （`TrafficResetPeriodKey(转换时刻, 重置日)`）。
- 期初用量落位不变：`usedBytes = client_traffics 上+下`、方向两字段按原值 —
  其中属于重置客户的部分将在其首个重置日按新周期清零，符合 3x-ui 现行语义。

## 7. 未做 / 边界

- Node 版面板未实现重置执行逻辑（定版生产主控为 Go 版；Node 仅需字段无副作用，
  已满足）。如未来 Node 回主，需在 `server.js` housekeeping 补同语义实现。
- 客户列表页未加"重置日"列（按最小配套要求只做了表单入口 + 上次重置显示）。
- 本报告不含生产部署动作：新二进制构建/换装按既有流程另行执行。