feat(clients): add calendar weekly renewal and schedule previews (#6524)

* feat(clients): add calendar weekly renewal and schedule previews

Expose fixed-day, calendar-weekly, calendar-monthly, and disabled renewal
through one shared selector in individual and bulk client forms. Store the
weekly weekday separately (Monday 1 through Sunday 7) and use panel-local
calendar dates rather than a fixed 168-hour duration. Resolve skipped or
repeated midnights to the first valid instant of the selected date, and skip
an entirely nonexistent calendar date rather than changing the weekday.

Reuse the existing renewal writer and share its boundary alignment and
per-period catch-up calculation with an authenticated, read-only preview.
Keep monthly precedence for legacy records, fixed-day interval semantics,
maximum renewal allowances, first-use durations, and operator-disabled
settings unchanged. Selecting a mode does not rewrite an existing cutoff;
an unset calendar cutoff requires an explicit action to choose the first.
The last-valid-second preview uses the stored exclusive expiry, even when
the billing calculation aligns a legacy last-second cutoff up to midnight.

Carry weekly schedules through client persistence, paging, enable toggles,
inbound settings, and node traffic reconciliation. Migrate missing or nullable
weekday columns to disabled by default without altering existing limits, and
include the new isolated-schema PostgreSQL regression in the live CI gate.

Regenerate API contracts and reference documentation, add lifecycle and form
regressions, and document timezone, quota-reset, and upgrade considerations.
All participating nodes must be upgraded before weekly mode is enabled;
older binaries ignore the new field. Independent periodic traffic resets and
the optional month-end subscription-header display are not changed.

* fix(clients): validate renewal schedules across inbound write paths

Reject conflicting weekly/interval/monthly schedules and out-of-range
weekdays on inbound creation and edits, legacy one-client apply paths,
record/link synchronization, and traffic metadata writes. Validate imported
traffic snapshots as well, before any inbound or client is persisted, so
an inbound API cannot create a client that the clients page cannot toggle.

Merge a weekly-related schedule as one timestamp-selected tuple rather
than filling its zero fields from another renewal mode. Preserve empty
migration snapshots and the existing non-weekly monthly/interval merge
semantics. Renewal caps, counters, credentials, and deadlines are unchanged.

Add regressions for nine write paths, unchanged records and runtime calls
after rejection, valid inbound clients remaining editable, and duplicate
record merges between individually valid renewal modes.

* docs(clients): clarify depleted-client deletion risks on downgrade

Explain in English and Chinese that older versions not only stop weekly
renewal: their depleted-client cleanup can delete a weekly-only client once
its expiry or quota is exhausted. This is conditional on cleanup, not an
automatic deletion caused by downgrade itself.

Recommend backing up and converting weekly schedules to a mode supported
by every participating version before rollback, and avoiding cleanup while
mixed versions or unconverted clients remain. Merely disabling weekly
renewal does not restore the old binary's missing purge protection.

* fix(clients): bound weekly renewal date searches

Limit the search for a valid weekly calendar date to eight candidates so
an unusual timezone cannot monopolize the single traffic writer. Exhaustion
returns the original instant, allowing the existing catch-up forward-progress
guard to stop without advancing expiry, consuming an allowance, resetting
traffic, or falling back to a fixed-duration schedule that can drift.

Reject a non-future calendar suggestion in the read-only preview instead of
offering an immediately expired initial cutoff. Also report failed weekly
catch-up as a search error when allowances remain, not as cap exhaustion.
Existing preview errors use the form's current warning; no API schema or
locale changes are needed.

Exercise exhaustion with a synthetic valid TZif containing twelve skipped
Sundays. This fault-injection case was red without the bound; it is not a
claim that a production IANA timezone was observed hanging. Keep the Havana
and Apia regressions for real skipped/repeated midnights and absent dates.

* fix(tests): isolate weekly renewal preview timezone

Stop the weekly search regression from replacing process-global time.Local.
CI caught that assignment and its cleanup racing with background timer reads
through time.Now, even though the top-level tests do not use t.Parallel.

Pass the timezone and current instant into the unchanged preview calculation.
The public service still validates the request and resolves the panel timezone;
API responses, renewal accounting, and persisted client data are unchanged.

Use fixed dates for both suggestion and catch-up exhaustion, removing the
test's dependency on today's date and its unnecessary database setup. Keep a
bounded-lifetime background clock reader to expose future global-timezone
mutations under the existing race gate rather than disabling that check.

* ci: retrigger PR checks

Create an empty commit to request a fresh pull-request CI run after release dependency downloads failed with network errors.

No source, dependency, or workflow changes are included. Retry the existing checks without bypassing them.

* ci: retry PR checks and record deferred download hardening

Request another CI run after the amd64 release job compiled successfully but failed during dependency fetching with exit code 4 (network failure).

Record possible follow-up improvements for the Linux release fetch helper:
- Print each download URL and destination, and preserve error details.
- Reuse the existing curl configuration with up to five retries; add connection and per-attempt timeouts and a bounded retry window.
- Download to a temporary file and promote it to the final filename only after a successful, non-empty transfer. Keep the job failing if downloads ultimately fail.
- Validate successful downloads, recovery after a temporary failure, and correct failure after persistent errors before shipping such a change.

These improvements are intentionally deferred, not implemented or tested by this commit. This commit is empty: renewal logic, dependencies, workflow configuration, check requirements, and TLS verification remain unchanged.

---------

Co-authored-by: JacktheRanger <219502738+JacktheRanger@users.noreply.github.com>

.github/workflows/ci.yml

@@ -83,12 +83,12 @@ jobs:
       - name: PostgreSQL schema and migration tests
         run: |
           set -o pipefail
-          go test ./internal/database -run '^(TestHostAutoMigrateCreatesColumns_Postgres|TestMigrate_Postgres)$' -count=1 -v | tee /tmp/postgres-schema.log
-          # Both must pass. Counting, not SKIP-matching: renaming either test would
+          go test ./internal/database -run '^(TestHostAutoMigrateCreatesColumns_Postgres|TestMigrate_Postgres|TestClientWeeklyRenewMigration_Postgres)$' -count=1 -v | tee /tmp/postgres-schema.log
+          # All must pass. Counting, not SKIP-matching: renaming a test would
           # otherwise leave this step green while testing nothing.
-          passed=$(grep -c -- '--- PASS' /tmp/postgres-schema.log || true)
-          if [ "$passed" -lt 2 ]; then
-            echo "expected 2 passing PostgreSQL schema tests, got $passed" >&2
+          passed=$(grep -c -- '^--- PASS' /tmp/postgres-schema.log || true)
+          if [ "$passed" -lt 3 ]; then
+            echo "expected at least 3 passing PostgreSQL schema tests, got $passed" >&2
             exit 1
           fi
 

docs/content/docs/en/config/clients.mdx

@@ -20,7 +20,7 @@ inbounds** at once, with per-client traffic accounting.
 | **Limit IP**   | all (except TUIC)     | Max simultaneous source IPs (enforced via Fail2ban).               |
 | **Total (GB)** | all (except TUIC)     | Traffic quota; the client is disabled when exhausted (for TUIC, limits are set at the inbound level). |
 | **Expiry**     | all                   | Date after which the client stops working.                        |
-| **Reset**      | all                   | Auto-renew period in **days** (rolls the quota over).              |
+| **Auto renewal** | all                 | Disabled, fixed interval in days, calendar weekly, or calendar monthly. |
 | **Telegram ID**| all                   | Links the client to a Telegram user for self-service/notifications.|
 | **Sub ID**     | all                   | Subscription identifier grouping this client's links.             |
 | **Group**      | all                   | Optional client group for organization and bulk filtering.        |
@@ -42,6 +42,68 @@ inbounds** at once, with per-client traffic accounting.
 - **Online status** and **last-online** times are tracked per client (and per
   node in multi-node setups).
 
+## Automatic renewal
+
+The individual and bulk-create forms offer one renewal mode at a time:
+
+| Mode | API fields | Schedule |
+| --- | --- | --- |
+| Disabled | `reset=0`, `resetDay=0`, `resetWeekday=0` | The expiry is not renewed. |
+| Fixed interval | `reset=N`, other two fields `0` | Add exactly N × 24 hours to the previous cutoff. |
+| Calendar weekly | `resetWeekday=1..7`, other two fields `0` | Renew at panel-local midnight on Monday (1) through Sunday (7). |
+| Calendar monthly | `resetDay=1..31`, `resetWeekday=0` | Renew at panel-local midnight on that day; missing dates clamp to the month's last day without losing the configured day. |
+
+Calendar weeks stay on the selected weekday across daylight-saving changes;
+they are not equivalent to a fixed seven-day interval. A skipped midnight uses
+the first valid instant of that date; a repeated midnight uses the first one.
+If a timezone skips the entire selected date, the next matching week is used.
+Existing monthly clients
+that also have `reset` set retain monthly precedence. The API rejects weekly
+renewal combined with a positive `reset` or `resetDay`.
+
+For a full calendar month, select **monthly, day 1** and set the initial cutoff
+to the next month's first midnight. For example, `2030-09-01 00:00:00` is valid
+through `2030-08-31 23:59:59`. Day 31 renews at the **start** of the 31st and is
+not the same schedule. The existing optional month-end subscription-header
+display remains a separate setting and is not enabled by this form.
+
+The preview uses the panel's timezone and the same calendar/catch-up calculation
+as automatic renewal. It shows the cutoff, last valid second, next expiry, and
+allowances needed. It is informational: it does not save, activate, reserve, or
+guarantee a future renewal. When no expiry is set, auto-renewal cannot run; an
+explicit button can set the first calendar cutoff. Selecting a mode alone never
+rewrites an existing expiry. First-use clients keep their initial duration, and
+their calendar dates are available after activation.
+
+For legacy last-second calendar cutoffs, the renewal boundary includes the
+existing free alignment to the following midnight. The last-valid-second
+preview still uses the **stored expiry**, not that alignment: an exclusive
+`23:59:59` cutoff is valid through `23:59:58`. Use a next-midnight cutoff for
+full-day validity; the preview itself does not repair the initial expiry.
+
+`resetMax=0` means unlimited renewals. A positive limit counts **each elapsed
+period**, including offline catch-up, not each scheduler tick or attached inbound.
+If the remaining allowances cannot reach a future cutoff, the client stays
+expired and its traffic is not reset. Operator-disabled clients stay disabled.
+
+Renewal already resets client traffic. The separate **periodic traffic reset**
+does not move the expiry and is unchanged; keep it disabled unless you intend an
+additional reset. Quarterly, yearly, and every-N-week/month schedules are not
+part of these modes.
+
+<Callout type="warn">
+  Upgrade the main panel and every participating node before enabling weekly
+  renewal. Older versions ignore `resetWeekday`; a weekly-only client would not
+  auto-renew and, after its expiry or quota is exhausted, can be deleted by
+  **delete depleted clients** because older versions lack the weekly protection.
+  Back up the database and convert weekly schedules to a renewal mode supported
+  by every participating version before downgrading. Merely disabling weekly
+  renewal does not protect a depleted client from deletion. Avoid depleted-client
+  cleanup while a mixed-version fleet or unconverted weekly clients remain.
+  Database upgrades default this new field to `0` and preserve existing limits
+  and dates.
+</Callout>
+
 ## Share links and external links
 
 Every client has share links and a QR code for its inbounds, plus a combined

docs/content/docs/en/reference/api/clients.mdx

@@ -37,6 +37,9 @@ _openapi:
         call. Body is JSON. Per-protocol secrets are generated server-side when
         omitted, so callers can send only the universal fields.
       url: '#create-a-new-client-and-attach-it-to-one-or-more-inbounds-in-a-single-call-body-is-json-per-protocol-secrets-are-generated-server-side-when-omitted-so-callers-can-send-only-the-universal-fields'
+    - depth: 2
+      title: Preview client auto-renewal dates without saving or resetting anything.
+      url: '#preview-client-auto-renewal-dates-without-saving-or-resetting-anything'
     - depth: 2
       title: Update an existing client by email. Changes propagate to every attached
         inbound. Body is the JSON client payload — supply the full set of fields
@@ -317,6 +320,8 @@ _openapi:
           call. Body is JSON. Per-protocol secrets are generated server-side
           when omitted, so callers can send only the universal fields.
         id: create-a-new-client-and-attach-it-to-one-or-more-inbounds-in-a-single-call-body-is-json-per-protocol-secrets-are-generated-server-side-when-omitted-so-callers-can-send-only-the-universal-fields
+      - content: Preview client auto-renewal dates without saving or resetting anything.
+        id: preview-client-auto-renewal-dates-without-saving-or-resetting-anything
       - content: Update an existing client by email. Changes propagate to every attached
           inbound. Body is the JSON client payload — supply the full set of
           fields you want to keep (the server replaces the row, it does not
@@ -592,6 +597,16 @@ _openapi:
           one per line. `limitHwid` is applied only when every inbound
           succeeded, so re-run the call after fixing the failure.
         heading: create-a-new-client-and-attach-it-to-one-or-more-inbounds-in-a-single-call-body-is-json-per-protocol-secrets-are-generated-server-side-when-omitted-so-callers-can-send-only-the-universal-fields
+      - content: Uses the same calendar and catch-up calculation as auto-renew in the
+          panel timezone. resetWeekday is 1 (Monday) to 7 (Sunday), 0 disables
+          weekly mode; it cannot be combined with positive reset or resetDay.
+          Existing resetDay takes precedence over reset. With expiryTime=0,
+          calendar modes suggest a first cutoff but do not activate renewal.
+          Negative expiryTime waits for first-use activation. resetMax and
+          resetCount simulate the existing per-period allowance limit; the
+          preview is informational and does not reserve an allowance or
+          guarantee node availability.
+        heading: preview-client-auto-renewal-dates-without-saving-or-resetting-anything
       - content: 'The inbounds are applied concurrently and independently: one that
           fails no longer stops the others. Every inbound error names the
           inbound it came from (`inbound 7: <message>`), and several failures
@@ -638,7 +653,7 @@ export default function Layout(props) {
   return (
     <>
       {props.children}
-      <Comp document="./public/openapi.json" webhooks={[]} operations={[{"path":"/panel/api/clients/list","method":"get"},{"path":"/panel/api/clients/list/paged","method":"get"},{"path":"/panel/api/clients/get/{email}","method":"get"},{"path":"/panel/api/clients/get/tgId/{tgId}","method":"get"},{"path":"/panel/api/clients/add","method":"post"},{"path":"/panel/api/clients/update/{email}","method":"post"},{"path":"/panel/api/clients/del/{email}","method":"post"},{"path":"/panel/api/clients/{email}/attach","method":"post"},{"path":"/panel/api/clients/{email}/detach","method":"post"},{"path":"/panel/api/clients/{email}/externalLinks","method":"post"},{"path":"/panel/api/clients/resetAllTraffics","method":"post"},{"path":"/panel/api/clients/delDepleted","method":"post"},{"path":"/panel/api/clients/delOrphans","method":"post"},{"path":"/panel/api/clients/export","method":"get"},{"path":"/panel/api/clients/import","method":"post"},{"path":"/panel/api/clients/bulkAdjust","method":"post"},{"path":"/panel/api/clients/bulkEnable","method":"post"},{"path":"/panel/api/clients/bulkDisable","method":"post"},{"path":"/panel/api/clients/bulkDel","method":"post"},{"path":"/panel/api/clients/bulkCreate","method":"post"},{"path":"/panel/api/clients/groups/bulkAdd","method":"post"},{"path":"/panel/api/clients/groups/bulkRemove","method":"post"},{"path":"/panel/api/clients/bulkAttach","method":"post"},{"path":"/panel/api/clients/bulkDetach","method":"post"},{"path":"/panel/api/clients/bulkResetTraffic","method":"post"},{"path":"/panel/api/clients/groups","method":"get"},{"path":"/panel/api/clients/groups/{name}/emails","method":"get"},{"path":"/panel/api/clients/groups/create","method":"post"},{"path":"/panel/api/clients/groups/rename","method":"post"},{"path":"/panel/api/clients/groups/delete","method":"post"},{"path":"/panel/api/clients/groups/resetTraffic","method":"post"},{"path":"/panel/api/clients/resetTraffic/{email}","method":"post"},{"path":"/panel/api/clients/updateTraffic/{email}","method":"post"},{"path":"/panel/api/clients/ips/{email}","method":"post"},{"path":"/panel/api/clients/clearIps/{email}","method":"post"},{"path":"/panel/api/clients/hwids/{email}","method":"post"},{"path":"/panel/api/clients/hwids/{email}","method":"delete"},{"path":"/panel/api/clients/hwids/{email}/{id}","method":"delete"},{"path":"/panel/api/clients/onlines","method":"post"},{"path":"/panel/api/clients/onlinesByGuid","method":"post"},{"path":"/panel/api/clients/clientIpsByGuid","method":"post"},{"path":"/panel/api/clients/activeInbounds","method":"post"},{"path":"/panel/api/clients/lastOnline","method":"post"},{"path":"/panel/api/clients/traffic/{email}","method":"get"},{"path":"/panel/api/clients/subLinks/{subId}","method":"get"},{"path":"/panel/api/clients/happLink/{id}","method":"post"},{"path":"/panel/api/clients/links/{email}","method":"get"}]} showTitle />
+      <Comp document="./public/openapi.json" webhooks={[]} operations={[{"path":"/panel/api/clients/list","method":"get"},{"path":"/panel/api/clients/list/paged","method":"get"},{"path":"/panel/api/clients/get/{email}","method":"get"},{"path":"/panel/api/clients/get/tgId/{tgId}","method":"get"},{"path":"/panel/api/clients/add","method":"post"},{"path":"/panel/api/clients/renewalPreview","method":"post"},{"path":"/panel/api/clients/update/{email}","method":"post"},{"path":"/panel/api/clients/del/{email}","method":"post"},{"path":"/panel/api/clients/{email}/attach","method":"post"},{"path":"/panel/api/clients/{email}/detach","method":"post"},{"path":"/panel/api/clients/{email}/externalLinks","method":"post"},{"path":"/panel/api/clients/resetAllTraffics","method":"post"},{"path":"/panel/api/clients/delDepleted","method":"post"},{"path":"/panel/api/clients/delOrphans","method":"post"},{"path":"/panel/api/clients/export","method":"get"},{"path":"/panel/api/clients/import","method":"post"},{"path":"/panel/api/clients/bulkAdjust","method":"post"},{"path":"/panel/api/clients/bulkEnable","method":"post"},{"path":"/panel/api/clients/bulkDisable","method":"post"},{"path":"/panel/api/clients/bulkDel","method":"post"},{"path":"/panel/api/clients/bulkCreate","method":"post"},{"path":"/panel/api/clients/groups/bulkAdd","method":"post"},{"path":"/panel/api/clients/groups/bulkRemove","method":"post"},{"path":"/panel/api/clients/bulkAttach","method":"post"},{"path":"/panel/api/clients/bulkDetach","method":"post"},{"path":"/panel/api/clients/bulkResetTraffic","method":"post"},{"path":"/panel/api/clients/groups","method":"get"},{"path":"/panel/api/clients/groups/{name}/emails","method":"get"},{"path":"/panel/api/clients/groups/create","method":"post"},{"path":"/panel/api/clients/groups/rename","method":"post"},{"path":"/panel/api/clients/groups/delete","method":"post"},{"path":"/panel/api/clients/groups/resetTraffic","method":"post"},{"path":"/panel/api/clients/resetTraffic/{email}","method":"post"},{"path":"/panel/api/clients/updateTraffic/{email}","method":"post"},{"path":"/panel/api/clients/ips/{email}","method":"post"},{"path":"/panel/api/clients/clearIps/{email}","method":"post"},{"path":"/panel/api/clients/hwids/{email}","method":"post"},{"path":"/panel/api/clients/hwids/{email}","method":"delete"},{"path":"/panel/api/clients/hwids/{email}/{id}","method":"delete"},{"path":"/panel/api/clients/onlines","method":"post"},{"path":"/panel/api/clients/onlinesByGuid","method":"post"},{"path":"/panel/api/clients/clientIpsByGuid","method":"post"},{"path":"/panel/api/clients/activeInbounds","method":"post"},{"path":"/panel/api/clients/lastOnline","method":"post"},{"path":"/panel/api/clients/traffic/{email}","method":"get"},{"path":"/panel/api/clients/subLinks/{subId}","method":"get"},{"path":"/panel/api/clients/happLink/{id}","method":"post"},{"path":"/panel/api/clients/links/{email}","method":"get"}]} showTitle />
     </>
   );
 }

docs/content/docs/zh/config/clients.mdx

@@ -19,7 +19,7 @@ icon: Users
 | **Limit IP**   | 全部（TUIC 除外）      | 最大同时连接的源 IP 数量（通过 Fail2ban 强制执行）。             |
 | **Total (GB)** | 全部（TUIC 除外）      | 流量配额；用尽后客户端将被禁用（对于 TUIC，限制在入站级别设置）。 |
 | **Expiry**     | 全部                  | 该日期之后客户端停止工作。                                       |
-| **Reset**      | 全部                  | 以**天**为单位的自动续期周期（滚动重置配额）。                   |
+| **自动续期**   | 全部                  | 关闭、固定天数、日历每周或日历每月。                             |
 | **Telegram ID**| 全部                  | 将客户端关联到 Telegram 用户，用于自助服务/通知。               |
 | **Sub ID**     | 全部                  | 用于对该客户端链接分组的订阅标识符。                             |
 | **Group**      | 全部                  | 可选的客户端分组，便于组织管理和批量筛选。                       |
@@ -39,6 +39,58 @@ icon: Users
   并从该客户端的操作中清除它们。
 - 系统会按客户端（在多节点部署中还会按节点）跟踪**在线状态**和**最后在线**时间。
 
+## 自动续期
+
+单个客户端和批量创建表单使用统一的续期模式选择：
+
+| 模式 | API 字段 | 续期规则 |
+| --- | --- | --- |
+| 关闭 | `reset=0`、`resetDay=0`、`resetWeekday=0` | 不自动延长到期时间。 |
+| 固定天数 | `reset=N`，另两个字段为 `0` | 从上次截止时间增加 N × 24 小时。 |
+| 日历每周 | `resetWeekday=1..7`，另两个字段为 `0` | 在面板时区每周一（1）至周日（7）的零点续期。 |
+| 日历每月 | `resetDay=1..31`、`resetWeekday=0` | 在面板时区指定日的零点续期；短月取月末，之后仍按原配置日续期。 |
+
+日历每周跨夏令时仍保持指定星期，不等于固定 7 天。若零点不存在，使用
+该日期第一个有效时刻；零点重复时取第一次。若时区跳过整天，则使用
+下一周的同一星期。旧配置同时填写
+`reset` 和 `resetDay` 时继续以每月续期为准。API 不允许每周续期与正数
+`reset` 或 `resetDay` 同时启用。
+
+整自然月应选**每月、1 日**，首次截止时间设置为下月 1 日零点。例如
+`2030-09-01 00:00:00` 表示有效至 `2030-08-31 23:59:59`。
+31 日表示在 31 日**开始时**续期，并不是同一边界。订阅头原有的可选
+月末显示设置仍独立存在，本表单不会自动开启它。
+
+日期预览使用面板时区和后端实际续期的同一套计算，显示截止时间、最后
+有效秒、下次到期时间及需要消耗的续期次数。预览不会保存、激活或预留
+续期，也不保证未来一定续期。未设到期时间时自动续期无法运行，可以
+明确点击按钮设置首次日历截止时间；仅选择模式不会修改已有到期时间。
+“首次使用后开始”保留原来的初始天数，激活后才能确定日历日期。
+
+旧配置以最后一秒为日历截止时间时，续期边界包含原有的不计次数向下个
+零点对齐规则。但最后有效秒仍按**已存储的到期时间**计算，不会假装
+初始时间已被修改：排他截止时间 `23:59:59` 实际有效至 `23:59:58`。
+整天有效应使用下一个零点，预览本身不会修复首次截止时间。
+
+最大续期次数 `resetMax=0` 表示不限次数。正数上限按**每个经过的周期**
+计数，包括离线补续，不按定时任务执行次数或关联入站数量计数。剩余
+次数不足以续到未来时，客户端继续过期且不会重置流量；手动禁用的
+客户端保持禁用。
+
+自动续期本身会重置客户端流量。独立的**定期流量重置**不延长到期时间，
+这次未改变其规则；除非需要额外重置，否则保持关闭。本次不包含季度、
+年度和每 N 周/月的续期。
+
+<Callout type="warn">
+  启用每周续期前，需要升级主面板及所有参与节点。旧版本会忽略
+  `resetWeekday`，仅配置每周的客户端将无法自动续期，且在到期或流量
+  耗尽后，可能被**删除已耗尽客户端**操作删除，因为旧版没有每周续期
+  的清理保护。降级前应备份数据库，并将每周配置转换为所有参与版本
+  都支持的续期模式；仅关闭每周续期并不能防止耗尽后的删除。存在
+  混合版本或尚未转换的每周客户端时，应避免执行耗尽客户端清理。
+  数据库升级默认将新字段设为 `0`，保留已有日期和限制。
+</Callout>
+
 ## 分享链接与外部链接
 
 每个客户端都有针对其各入站的分享链接和二维码，外加一个合并的

docs/public/openapi.json

@@ -1531,13 +1531,17 @@
             "type": "integer"
           },
           "resetDay": {
-            "description": "Calendar renewal day 1-31, 0 = interval mode",
+            "description": "Calendar renewal day 1-31, 0 disables monthly renewal",
             "type": "integer"
           },
           "resetMax": {
             "description": "Max auto-renew count, 0 = unlimited",
             "type": "integer"
           },
+          "resetWeekday": {
+            "description": "Calendar weekday 1-7 (Mon-Sun), 0 disables weekly renewal",
+            "type": "integer"
+          },
           "reverse": {
             "allOf": [
               {
@@ -1600,6 +1604,7 @@
           "reset",
           "resetDay",
           "resetMax",
+          "resetWeekday",
           "security",
           "subId",
           "tgId",
@@ -1751,6 +1756,9 @@
           "resetMax": {
             "type": "integer"
           },
+          "resetWeekday": {
+            "type": "integer"
+          },
           "reverse": {},
           "secret": {
             "type": "string"
@@ -1806,6 +1814,7 @@
           "reset",
           "resetDay",
           "resetMax",
+          "resetWeekday",
           "reverse",
           "secret",
           "security",
@@ -1819,6 +1828,97 @@
         ],
         "type": "object"
       },
+      "ClientRenewalPreview": {
+        "properties": {
+          "canRenew": {
+            "example": true,
+            "type": "boolean"
+          },
+          "delayedStart": {
+            "example": false,
+            "type": "boolean"
+          },
+          "nextExpiry": {
+            "example": "2030-02-01T00:00:00Z",
+            "type": "string"
+          },
+          "renewAt": {
+            "example": "2030-01-01T00:00:00Z",
+            "type": "string"
+          },
+          "renewals": {
+            "example": 1,
+            "type": "integer"
+          },
+          "suggestedExpiry": {
+            "example": "2030-01-01T00:00:00Z",
+            "type": "string"
+          },
+          "suggestedExpiryTime": {
+            "example": 1893456000000,
+            "format": "int64",
+            "type": "integer"
+          },
+          "timeZone": {
+            "example": "UTC",
+            "type": "string"
+          },
+          "validThrough": {
+            "example": "2029-12-31T23:59:59Z",
+            "type": "string"
+          }
+        },
+        "required": [
+          "canRenew",
+          "delayedStart",
+          "nextExpiry",
+          "renewAt",
+          "renewals",
+          "suggestedExpiry",
+          "suggestedExpiryTime",
+          "timeZone",
+          "validThrough"
+        ],
+        "type": "object"
+      },
+      "ClientRenewalPreviewRequest": {
+        "properties": {
+          "expiryTime": {
+            "example": 1893456000000,
+            "format": "int64",
+            "type": "integer"
+          },
+          "reset": {
+            "example": 0,
+            "type": "integer"
+          },
+          "resetCount": {
+            "example": 0,
+            "type": "integer"
+          },
+          "resetDay": {
+            "example": 1,
+            "type": "integer"
+          },
+          "resetMax": {
+            "example": 0,
+            "type": "integer"
+          },
+          "resetWeekday": {
+            "example": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "expiryTime",
+          "reset",
+          "resetCount",
+          "resetDay",
+          "resetMax",
+          "resetWeekday"
+        ],
+        "type": "object"
+      },
       "ClientReverse": {
         "properties": {
           "tag": {
@@ -1889,6 +1989,10 @@
             "example": 0,
             "type": "integer"
           },
+          "resetWeekday": {
+            "example": 0,
+            "type": "integer"
+          },
           "subId": {
             "example": "abcd1234",
             "type": "string"
@@ -1923,6 +2027,7 @@
           "reset",
           "resetDay",
           "resetMax",
+          "resetWeekday",
           "subId",
           "totalGB",
           "updatedAt"
@@ -1978,7 +2083,7 @@
             "type": "integer"
           },
           "resetDay": {
-            "description": "ResetDay renews on that day of each calendar month instead of every\nReset days; 0 keeps the interval behaviour.",
+            "description": "ResetDay renews on that day of each calendar month instead of every\nReset days; 0 disables monthly renewal.",
             "example": 0,
             "type": "integer"
           },
@@ -1987,6 +2092,11 @@
             "example": 0,
             "type": "integer"
           },
+          "resetWeekday": {
+            "description": "ResetWeekday renews weekly at panel-local midnight: 1 Monday through 7 Sunday.",
+            "example": 0,
+            "type": "integer"
+          },
           "subId": {
             "example": "i7tvdpeffi0hvvf1",
             "type": "string"
@@ -2019,6 +2129,7 @@
           "resetCount",
           "resetDay",
           "resetMax",
+          "resetWeekday",
           "subId",
           "total",
           "up",
@@ -4807,6 +4918,7 @@
                           "resetCount": 0,
                           "resetDay": 0,
                           "resetMax": 0,
+                          "resetWeekday": 0,
                           "subId": "i7tvdpeffi0hvvf1",
                           "total": 10737418240,
                           "up": 1048576,
@@ -8041,6 +8153,7 @@
                         "reset": 0,
                         "resetDay": 0,
                         "resetMax": 0,
+                        "resetWeekday": 0,
                         "subId": "abcd1234",
                         "totalGB": 53687091200,
                         "traffic": null,
@@ -8233,6 +8346,97 @@
         }
       }
     },
+    "/panel/api/clients/renewalPreview": {
+      "post": {
+        "tags": [
+          "Clients"
+        ],
+        "summary": "Preview client auto-renewal dates without saving or resetting anything.",
+        "operationId": "post_panel_api_clients_renewalPreview",
+        "description": "Uses the same calendar and catch-up calculation as auto-renew in the panel timezone. resetWeekday is 1 (Monday) to 7 (Sunday), 0 disables weekly mode; it cannot be combined with positive reset or resetDay. Existing resetDay takes precedence over reset. With expiryTime=0, calendar modes suggest a first cutoff but do not activate renewal. Negative expiryTime waits for first-use activation. resetMax and resetCount simulate the existing per-period allowance limit; the preview is informational and does not reserve an allowance or guarantee node availability.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "expiryTime": {
+                    "type": "integer",
+                    "description": "Current cutoff in Unix milliseconds; 0 unlimited, negative first-use duration."
+                  },
+                  "reset": {
+                    "type": "integer",
+                    "description": "Fixed interval in days; 0 disabled."
+                  },
+                  "resetDay": {
+                    "type": "integer",
+                    "description": "Monthly calendar day 1-31; 0 disabled."
+                  },
+                  "resetWeekday": {
+                    "type": "integer",
+                    "description": "Weekly calendar day 1-7 (Monday-Sunday); 0 disabled."
+                  },
+                  "resetMax": {
+                    "type": "integer",
+                    "description": "Maximum renewals; 0 unlimited."
+                  },
+                  "resetCount": {
+                    "type": "integer",
+                    "description": "Renewals already consumed; defaults to 0."
+                  }
+                },
+                "required": [
+                  "expiryTime",
+                  "reset",
+                  "resetDay",
+                  "resetWeekday",
+                  "resetMax",
+                  "resetCount"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "msg": {
+                      "type": "string"
+                    },
+                    "obj": {
+                      "$ref": "#/components/schemas/ClientRenewalPreview"
+                    }
+                  }
+                },
+                "example": {
+                  "success": true,
+                  "obj": {
+                    "canRenew": true,
+                    "delayedStart": false,
+                    "nextExpiry": "2030-02-01T00:00:00Z",
+                    "renewAt": "2030-01-01T00:00:00Z",
+                    "renewals": 1,
+                    "suggestedExpiry": "2030-01-01T00:00:00Z",
+                    "suggestedExpiryTime": 1893456000000,
+                    "timeZone": "UTC",
+                    "validThrough": "2029-12-31T23:59:59Z"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/panel/api/clients/update/{email}": {
       "post": {
         "tags": [
@@ -10292,6 +10496,7 @@
                     "resetCount": 0,
                     "resetDay": 0,
                     "resetMax": 0,
+                    "resetWeekday": 0,
                     "subId": "i7tvdpeffi0hvvf1",
                     "total": 10737418240,
                     "up": 1048576,
@@ -15665,6 +15870,7 @@
                     "resetCount": 0,
                     "resetDay": 0,
                     "resetMax": 0,
+                    "resetWeekday": 0,
                     "subId": "i7tvdpeffi0hvvf1",
                     "total": 10737418240,
                     "up": 1048576,
@@ -15747,6 +15953,7 @@
                     "resetCount": 0,
                     "resetDay": 0,
                     "resetMax": 0,
+                    "resetWeekday": 0,
                     "subId": "i7tvdpeffi0hvvf1",
                     "total": 10737418240,
                     "up": 1048576,
@@ -15793,6 +16000,7 @@
                       "resetCount": 0,
                       "resetDay": 0,
                       "resetMax": 0,
+                      "resetWeekday": 0,
                       "subId": "i7tvdpeffi0hvvf1",
                       "total": 10737418240,
                       "up": 1048576,

frontend/public/openapi.json

@@ -1531,13 +1531,17 @@
             "type": "integer"
           },
           "resetDay": {
-            "description": "Calendar renewal day 1-31, 0 = interval mode",
+            "description": "Calendar renewal day 1-31, 0 disables monthly renewal",
             "type": "integer"
           },
           "resetMax": {
             "description": "Max auto-renew count, 0 = unlimited",
             "type": "integer"
           },
+          "resetWeekday": {
+            "description": "Calendar weekday 1-7 (Mon-Sun), 0 disables weekly renewal",
+            "type": "integer"
+          },
           "reverse": {
             "allOf": [
               {
@@ -1600,6 +1604,7 @@
           "reset",
           "resetDay",
           "resetMax",
+          "resetWeekday",
           "security",
           "subId",
           "tgId",
@@ -1751,6 +1756,9 @@
           "resetMax": {
             "type": "integer"
           },
+          "resetWeekday": {
+            "type": "integer"
+          },
           "reverse": {},
           "secret": {
             "type": "string"
@@ -1806,6 +1814,7 @@
           "reset",
           "resetDay",
           "resetMax",
+          "resetWeekday",
           "reverse",
           "secret",
           "security",
@@ -1819,6 +1828,97 @@
         ],
         "type": "object"
       },
+      "ClientRenewalPreview": {
+        "properties": {
+          "canRenew": {
+            "example": true,
+            "type": "boolean"
+          },
+          "delayedStart": {
+            "example": false,
+            "type": "boolean"
+          },
+          "nextExpiry": {
+            "example": "2030-02-01T00:00:00Z",
+            "type": "string"
+          },
+          "renewAt": {
+            "example": "2030-01-01T00:00:00Z",
+            "type": "string"
+          },
+          "renewals": {
+            "example": 1,
+            "type": "integer"
+          },
+          "suggestedExpiry": {
+            "example": "2030-01-01T00:00:00Z",
+            "type": "string"
+          },
+          "suggestedExpiryTime": {
+            "example": 1893456000000,
+            "format": "int64",
+            "type": "integer"
+          },
+          "timeZone": {
+            "example": "UTC",
+            "type": "string"
+          },
+          "validThrough": {
+            "example": "2029-12-31T23:59:59Z",
+            "type": "string"
+          }
+        },
+        "required": [
+          "canRenew",
+          "delayedStart",
+          "nextExpiry",
+          "renewAt",
+          "renewals",
+          "suggestedExpiry",
+          "suggestedExpiryTime",
+          "timeZone",
+          "validThrough"
+        ],
+        "type": "object"
+      },
+      "ClientRenewalPreviewRequest": {
+        "properties": {
+          "expiryTime": {
+            "example": 1893456000000,
+            "format": "int64",
+            "type": "integer"
+          },
+          "reset": {
+            "example": 0,
+            "type": "integer"
+          },
+          "resetCount": {
+            "example": 0,
+            "type": "integer"
+          },
+          "resetDay": {
+            "example": 1,
+            "type": "integer"
+          },
+          "resetMax": {
+            "example": 0,
+            "type": "integer"
+          },
+          "resetWeekday": {
+            "example": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "expiryTime",
+          "reset",
+          "resetCount",
+          "resetDay",
+          "resetMax",
+          "resetWeekday"
+        ],
+        "type": "object"
+      },
       "ClientReverse": {
         "properties": {
           "tag": {
@@ -1889,6 +1989,10 @@
             "example": 0,
             "type": "integer"
           },
+          "resetWeekday": {
+            "example": 0,
+            "type": "integer"
+          },
           "subId": {
             "example": "abcd1234",
             "type": "string"
@@ -1923,6 +2027,7 @@
           "reset",
           "resetDay",
           "resetMax",
+          "resetWeekday",
           "subId",
           "totalGB",
           "updatedAt"
@@ -1978,7 +2083,7 @@
             "type": "integer"
           },
           "resetDay": {
-            "description": "ResetDay renews on that day of each calendar month instead of every\nReset days; 0 keeps the interval behaviour.",
+            "description": "ResetDay renews on that day of each calendar month instead of every\nReset days; 0 disables monthly renewal.",
             "example": 0,
             "type": "integer"
           },
@@ -1987,6 +2092,11 @@
             "example": 0,
             "type": "integer"
           },
+          "resetWeekday": {
+            "description": "ResetWeekday renews weekly at panel-local midnight: 1 Monday through 7 Sunday.",
+            "example": 0,
+            "type": "integer"
+          },
           "subId": {
             "example": "i7tvdpeffi0hvvf1",
             "type": "string"
@@ -2019,6 +2129,7 @@
           "resetCount",
           "resetDay",
           "resetMax",
+          "resetWeekday",
           "subId",
           "total",
           "up",
@@ -4807,6 +4918,7 @@
                           "resetCount": 0,
                           "resetDay": 0,
                           "resetMax": 0,
+                          "resetWeekday": 0,
                           "subId": "i7tvdpeffi0hvvf1",
                           "total": 10737418240,
                           "up": 1048576,
@@ -8041,6 +8153,7 @@
                         "reset": 0,
                         "resetDay": 0,
                         "resetMax": 0,
+                        "resetWeekday": 0,
                         "subId": "abcd1234",
                         "totalGB": 53687091200,
                         "traffic": null,
@@ -8233,6 +8346,97 @@
         }
       }
     },
+    "/panel/api/clients/renewalPreview": {
+      "post": {
+        "tags": [
+          "Clients"
+        ],
+        "summary": "Preview client auto-renewal dates without saving or resetting anything.",
+        "operationId": "post_panel_api_clients_renewalPreview",
+        "description": "Uses the same calendar and catch-up calculation as auto-renew in the panel timezone. resetWeekday is 1 (Monday) to 7 (Sunday), 0 disables weekly mode; it cannot be combined with positive reset or resetDay. Existing resetDay takes precedence over reset. With expiryTime=0, calendar modes suggest a first cutoff but do not activate renewal. Negative expiryTime waits for first-use activation. resetMax and resetCount simulate the existing per-period allowance limit; the preview is informational and does not reserve an allowance or guarantee node availability.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "expiryTime": {
+                    "type": "integer",
+                    "description": "Current cutoff in Unix milliseconds; 0 unlimited, negative first-use duration."
+                  },
+                  "reset": {
+                    "type": "integer",
+                    "description": "Fixed interval in days; 0 disabled."
+                  },
+                  "resetDay": {
+                    "type": "integer",
+                    "description": "Monthly calendar day 1-31; 0 disabled."
+                  },
+                  "resetWeekday": {
+                    "type": "integer",
+                    "description": "Weekly calendar day 1-7 (Monday-Sunday); 0 disabled."
+                  },
+                  "resetMax": {
+                    "type": "integer",
+                    "description": "Maximum renewals; 0 unlimited."
+                  },
+                  "resetCount": {
+                    "type": "integer",
+                    "description": "Renewals already consumed; defaults to 0."
+                  }
+                },
+                "required": [
+                  "expiryTime",
+                  "reset",
+                  "resetDay",
+                  "resetWeekday",
+                  "resetMax",
+                  "resetCount"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "msg": {
+                      "type": "string"
+                    },
+                    "obj": {
+                      "$ref": "#/components/schemas/ClientRenewalPreview"
+                    }
+                  }
+                },
+                "example": {
+                  "success": true,
+                  "obj": {
+                    "canRenew": true,
+                    "delayedStart": false,
+                    "nextExpiry": "2030-02-01T00:00:00Z",
+                    "renewAt": "2030-01-01T00:00:00Z",
+                    "renewals": 1,
+                    "suggestedExpiry": "2030-01-01T00:00:00Z",
+                    "suggestedExpiryTime": 1893456000000,
+                    "timeZone": "UTC",
+                    "validThrough": "2029-12-31T23:59:59Z"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/panel/api/clients/update/{email}": {
       "post": {
         "tags": [
@@ -10292,6 +10496,7 @@
                     "resetCount": 0,
                     "resetDay": 0,
                     "resetMax": 0,
+                    "resetWeekday": 0,
                     "subId": "i7tvdpeffi0hvvf1",
                     "total": 10737418240,
                     "up": 1048576,
@@ -15665,6 +15870,7 @@
                     "resetCount": 0,
                     "resetDay": 0,
                     "resetMax": 0,
+                    "resetWeekday": 0,
                     "subId": "i7tvdpeffi0hvvf1",
                     "total": 10737418240,
                     "up": 1048576,
@@ -15747,6 +15953,7 @@
                     "resetCount": 0,
                     "resetDay": 0,
                     "resetMax": 0,
+                    "resetWeekday": 0,
                     "subId": "i7tvdpeffi0hvvf1",
                     "total": 10737418240,
                     "up": 1048576,
@@ -15793,6 +16000,7 @@
                       "resetCount": 0,
                       "resetDay": 0,
                       "resetMax": 0,
+                      "resetWeekday": 0,
                       "subId": "i7tvdpeffi0hvvf1",
                       "total": 10737418240,
                       "up": 1048576,

frontend/src/generated/examples.ts

@@ -371,6 +371,7 @@ export const EXAMPLES: Record<string, unknown> = {
     "reset": 0,
     "resetDay": 0,
     "resetMax": 0,
+    "resetWeekday": 0,
     "reverse": null,
     "secret": "ee1234567890abcdef1234567890abcd7777772e636c6f7564666c6172652e636f6d",
     "security": "",
@@ -410,6 +411,7 @@ export const EXAMPLES: Record<string, unknown> = {
         "reset": 0,
         "resetDay": 0,
         "resetMax": 0,
+        "resetWeekday": 0,
         "subId": "abcd1234",
         "totalGB": 53687091200,
         "traffic": null,
@@ -459,6 +461,7 @@ export const EXAMPLES: Record<string, unknown> = {
     "reset": 0,
     "resetDay": 0,
     "resetMax": 0,
+    "resetWeekday": 0,
     "reverse": null,
     "secret": "",
     "security": "",
@@ -470,6 +473,25 @@ export const EXAMPLES: Record<string, unknown> = {
     "updatedAt": 0,
     "uuid": ""
   },
+  "ClientRenewalPreview": {
+    "canRenew": true,
+    "delayedStart": false,
+    "nextExpiry": "2030-02-01T00:00:00Z",
+    "renewAt": "2030-01-01T00:00:00Z",
+    "renewals": 1,
+    "suggestedExpiry": "2030-01-01T00:00:00Z",
+    "suggestedExpiryTime": 1893456000000,
+    "timeZone": "UTC",
+    "validThrough": "2029-12-31T23:59:59Z"
+  },
+  "ClientRenewalPreviewRequest": {
+    "expiryTime": 1893456000000,
+    "reset": 0,
+    "resetCount": 0,
+    "resetDay": 1,
+    "resetMax": 0,
+    "resetWeekday": 0
+  },
   "ClientReverse": {
     "tag": ""
   },
@@ -489,6 +511,7 @@ export const EXAMPLES: Record<string, unknown> = {
     "reset": 0,
     "resetDay": 0,
     "resetMax": 0,
+    "resetWeekday": 0,
     "subId": "abcd1234",
     "totalGB": 53687091200,
     "traffic": null,
@@ -507,6 +530,7 @@ export const EXAMPLES: Record<string, unknown> = {
     "resetCount": 0,
     "resetDay": 0,
     "resetMax": 0,
+    "resetWeekday": 0,
     "subId": "i7tvdpeffi0hvvf1",
     "total": 10737418240,
     "up": 1048576,
@@ -704,6 +728,7 @@ export const EXAMPLES: Record<string, unknown> = {
         "resetCount": 0,
         "resetDay": 0,
         "resetMax": 0,
+        "resetWeekday": 0,
         "subId": "i7tvdpeffi0hvvf1",
         "total": 10737418240,
         "up": 1048576,

frontend/src/generated/schemas.ts

@@ -1505,13 +1505,17 @@ export const SCHEMAS: Record<string, unknown> = {
         "type": "integer"
       },
       "resetDay": {
-        "description": "Calendar renewal day 1-31, 0 = interval mode",
+        "description": "Calendar renewal day 1-31, 0 disables monthly renewal",
         "type": "integer"
       },
       "resetMax": {
         "description": "Max auto-renew count, 0 = unlimited",
         "type": "integer"
       },
+      "resetWeekday": {
+        "description": "Calendar weekday 1-7 (Mon-Sun), 0 disables weekly renewal",
+        "type": "integer"
+      },
       "reverse": {
         "allOf": [
           {
@@ -1574,6 +1578,7 @@ export const SCHEMAS: Record<string, unknown> = {
       "reset",
       "resetDay",
       "resetMax",
+      "resetWeekday",
       "security",
       "subId",
       "tgId",
@@ -1725,6 +1730,9 @@ export const SCHEMAS: Record<string, unknown> = {
       "resetMax": {
         "type": "integer"
       },
+      "resetWeekday": {
+        "type": "integer"
+      },
       "reverse": {},
       "secret": {
         "type": "string"
@@ -1780,6 +1788,7 @@ export const SCHEMAS: Record<string, unknown> = {
       "reset",
       "resetDay",
       "resetMax",
+      "resetWeekday",
       "reverse",
       "secret",
       "security",
@@ -1793,6 +1802,97 @@ export const SCHEMAS: Record<string, unknown> = {
     ],
     "type": "object"
   },
+  "ClientRenewalPreview": {
+    "properties": {
+      "canRenew": {
+        "example": true,
+        "type": "boolean"
+      },
+      "delayedStart": {
+        "example": false,
+        "type": "boolean"
+      },
+      "nextExpiry": {
+        "example": "2030-02-01T00:00:00Z",
+        "type": "string"
+      },
+      "renewAt": {
+        "example": "2030-01-01T00:00:00Z",
+        "type": "string"
+      },
+      "renewals": {
+        "example": 1,
+        "type": "integer"
+      },
+      "suggestedExpiry": {
+        "example": "2030-01-01T00:00:00Z",
+        "type": "string"
+      },
+      "suggestedExpiryTime": {
+        "example": 1893456000000,
+        "format": "int64",
+        "type": "integer"
+      },
+      "timeZone": {
+        "example": "UTC",
+        "type": "string"
+      },
+      "validThrough": {
+        "example": "2029-12-31T23:59:59Z",
+        "type": "string"
+      }
+    },
+    "required": [
+      "canRenew",
+      "delayedStart",
+      "nextExpiry",
+      "renewAt",
+      "renewals",
+      "suggestedExpiry",
+      "suggestedExpiryTime",
+      "timeZone",
+      "validThrough"
+    ],
+    "type": "object"
+  },
+  "ClientRenewalPreviewRequest": {
+    "properties": {
+      "expiryTime": {
+        "example": 1893456000000,
+        "format": "int64",
+        "type": "integer"
+      },
+      "reset": {
+        "example": 0,
+        "type": "integer"
+      },
+      "resetCount": {
+        "example": 0,
+        "type": "integer"
+      },
+      "resetDay": {
+        "example": 1,
+        "type": "integer"
+      },
+      "resetMax": {
+        "example": 0,
+        "type": "integer"
+      },
+      "resetWeekday": {
+        "example": 0,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "expiryTime",
+      "reset",
+      "resetCount",
+      "resetDay",
+      "resetMax",
+      "resetWeekday"
+    ],
+    "type": "object"
+  },
   "ClientReverse": {
     "properties": {
       "tag": {
@@ -1863,6 +1963,10 @@ export const SCHEMAS: Record<string, unknown> = {
         "example": 0,
         "type": "integer"
       },
+      "resetWeekday": {
+        "example": 0,
+        "type": "integer"
+      },
       "subId": {
         "example": "abcd1234",
         "type": "string"
@@ -1897,6 +2001,7 @@ export const SCHEMAS: Record<string, unknown> = {
       "reset",
       "resetDay",
       "resetMax",
+      "resetWeekday",
       "subId",
       "totalGB",
       "updatedAt"
@@ -1952,7 +2057,7 @@ export const SCHEMAS: Record<string, unknown> = {
         "type": "integer"
       },
       "resetDay": {
-        "description": "ResetDay renews on that day of each calendar month instead of every\nReset days; 0 keeps the interval behaviour.",
+        "description": "ResetDay renews on that day of each calendar month instead of every\nReset days; 0 disables monthly renewal.",
         "example": 0,
         "type": "integer"
       },
@@ -1961,6 +2066,11 @@ export const SCHEMAS: Record<string, unknown> = {
         "example": 0,
         "type": "integer"
       },
+      "resetWeekday": {
+        "description": "ResetWeekday renews weekly at panel-local midnight: 1 Monday through 7 Sunday.",
+        "example": 0,
+        "type": "integer"
+      },
       "subId": {
         "example": "i7tvdpeffi0hvvf1",
         "type": "string"
@@ -1993,6 +2103,7 @@ export const SCHEMAS: Record<string, unknown> = {
       "resetCount",
       "resetDay",
       "resetMax",
+      "resetWeekday",
       "subId",
       "total",
       "up",

frontend/src/generated/types.ts

@@ -367,6 +367,7 @@ export interface Client {
   reset: number;
   resetDay: number;
   resetMax: number;
+  resetWeekday: number;
   reverse?: ClientReverse | null;
   secret?: string;
   security: string;
@@ -418,6 +419,7 @@ export interface ClientRecord {
   reset: number;
   resetDay: number;
   resetMax: number;
+  resetWeekday: number;
   reverse: unknown;
   secret: string;
   security: string;
@@ -430,6 +432,27 @@ export interface ClientRecord {
   uuid: string;
 }
 
+export interface ClientRenewalPreview {
+  canRenew: boolean;
+  delayedStart: boolean;
+  nextExpiry: string;
+  renewAt: string;
+  renewals: number;
+  suggestedExpiry: string;
+  suggestedExpiryTime: number;
+  timeZone: string;
+  validThrough: string;
+}
+
+export interface ClientRenewalPreviewRequest {
+  expiryTime: number;
+  reset: number;
+  resetCount: number;
+  resetDay: number;
+  resetMax: number;
+  resetWeekday: number;
+}
+
 export interface ClientReverse {
   tag: string;
 }
@@ -447,6 +470,7 @@ export interface ClientSlim {
   reset: number;
   resetDay: number;
   resetMax: number;
+  resetWeekday: number;
   subId: string;
   totalGB: number;
   traffic?: ClientTraffic | null;
@@ -466,6 +490,7 @@ export interface ClientTraffic {
   resetCount: number;
   resetDay: number;
   resetMax: number;
+  resetWeekday: number;
   subId: string;
   total: number;
   up: number;

frontend/src/generated/zod.ts

@@ -388,6 +388,7 @@ export const ClientSchema = z.object({
   reset: z.number().int(),
   resetDay: z.number().int(),
   resetMax: z.number().int(),
+  resetWeekday: z.number().int(),
   reverse: z.lazy(() => ClientReverseSchema).nullable().optional(),
   secret: z.string().optional(),
   security: z.string(),
@@ -442,6 +443,7 @@ export const ClientRecordSchema = z.object({
   reset: z.number().int(),
   resetDay: z.number().int(),
   resetMax: z.number().int(),
+  resetWeekday: z.number().int(),
   reverse: z.unknown(),
   secret: z.string(),
   security: z.string(),
@@ -455,6 +457,29 @@ export const ClientRecordSchema = z.object({
 });
 export type ClientRecord = z.infer<typeof ClientRecordSchema>;
 
+export const ClientRenewalPreviewSchema = z.object({
+  canRenew: z.boolean(),
+  delayedStart: z.boolean(),
+  nextExpiry: z.string(),
+  renewAt: z.string(),
+  renewals: z.number().int(),
+  suggestedExpiry: z.string(),
+  suggestedExpiryTime: z.number().int(),
+  timeZone: z.string(),
+  validThrough: z.string(),
+});
+export type ClientRenewalPreview = z.infer<typeof ClientRenewalPreviewSchema>;
+
+export const ClientRenewalPreviewRequestSchema = z.object({
+  expiryTime: z.number().int(),
+  reset: z.number().int(),
+  resetCount: z.number().int(),
+  resetDay: z.number().int(),
+  resetMax: z.number().int(),
+  resetWeekday: z.number().int(),
+});
+export type ClientRenewalPreviewRequest = z.infer<typeof ClientRenewalPreviewRequestSchema>;
+
 export const ClientReverseSchema = z.object({
   tag: z.string(),
 });
@@ -473,6 +498,7 @@ export const ClientSlimSchema = z.object({
   reset: z.number().int(),
   resetDay: z.number().int(),
   resetMax: z.number().int(),
+  resetWeekday: z.number().int(),
   subId: z.string(),
   totalGB: z.number().int(),
   traffic: z.lazy(() => ClientTrafficSchema).nullable().optional(),
@@ -493,6 +519,7 @@ export const ClientTrafficSchema = z.object({
   resetCount: z.number().int(),
   resetDay: z.number().int(),
   resetMax: z.number().int(),
+  resetWeekday: z.number().int(),
   subId: z.string(),
   total: z.number().int(),
   up: z.number().int(),

frontend/src/hooks/useClients.ts

@@ -696,6 +696,7 @@ export function useClients(options: UseClientsOptions = {}) {
         tgId: Number(base.tgId) || 0,
         reset: Number(base.reset) || 0,
         resetDay: Number(base.resetDay) || 0,
+        resetWeekday: Number(base.resetWeekday) || 0,
         resetMax: Number(base.resetMax) || 0,
         trafficReset: base.trafficReset || 'never',
         trafficResetDay: Number(base.trafficResetDay) || 1,

frontend/src/pages/api-docs/endpoints.ts

@@ -1169,6 +1169,52 @@ export const sections: readonly Section[] = [
         body: '{\n  "client": {\n    "email": "alice@example.com",\n    "totalGB": 53687091200,\n    "expiryTime": 1735689600000,\n    "tgId": 0,\n    "limitIp": 0,\n    "limitHwid": 0,\n    "enable": true\n  },\n  "inboundIds": [3, 5]\n}',
         response: '{\n  "success": true,\n  "msg": "Client added"\n}',
       },
+      {
+        method: 'POST',
+        path: '/panel/api/clients/renewalPreview',
+        summary: 'Preview client auto-renewal dates without saving or resetting anything.',
+        description:
+          'Uses the same calendar and catch-up calculation as auto-renew in the panel timezone. resetWeekday is 1 (Monday) to 7 (Sunday), 0 disables weekly mode; it cannot be combined with positive reset or resetDay. Existing resetDay takes precedence over reset. With expiryTime=0, calendar modes suggest a first cutoff but do not activate renewal. Negative expiryTime waits for first-use activation. resetMax and resetCount simulate the existing per-period allowance limit; the preview is informational and does not reserve an allowance or guarantee node availability.',
+        params: [
+          {
+            name: 'expiryTime',
+            in: 'body (json)',
+            type: 'integer',
+            desc: 'Current cutoff in Unix milliseconds; 0 unlimited, negative first-use duration.',
+          },
+          {
+            name: 'reset',
+            in: 'body (json)',
+            type: 'integer',
+            desc: 'Fixed interval in days; 0 disabled.',
+          },
+          {
+            name: 'resetDay',
+            in: 'body (json)',
+            type: 'integer',
+            desc: 'Monthly calendar day 1-31; 0 disabled.',
+          },
+          {
+            name: 'resetWeekday',
+            in: 'body (json)',
+            type: 'integer',
+            desc: 'Weekly calendar day 1-7 (Monday-Sunday); 0 disabled.',
+          },
+          {
+            name: 'resetMax',
+            in: 'body (json)',
+            type: 'integer',
+            desc: 'Maximum renewals; 0 unlimited.',
+          },
+          {
+            name: 'resetCount',
+            in: 'body (json)',
+            type: 'integer',
+            desc: 'Renewals already consumed; defaults to 0.',
+          },
+        ],
+        responseSchema: 'ClientRenewalPreview',
+      },
       {
         method: 'POST',
         path: '/panel/api/clients/update/:email',

frontend/src/pages/clients/ClientBulkAddModal.tsx

@@ -25,6 +25,7 @@ import { DateTimePicker, SelectAllClearButtons } from '@/components/form';
 import { FormField } from '@/components/form/rhf';
 import { useClients, type InboundOption } from '@/hooks/useClients';
 import { useFail2banStatusQuery, getLimitIpNotice } from '@/api/queries/useFail2banStatusQuery';
+import ClientRenewalFields from './ClientRenewalFields';
 import { ClientBulkAddFormSchema, type ClientBulkAddFormValues } from '@/schemas/client';
 
 const FLOW_OPTIONS = Object.values(TLS_FLOW_CONTROL);
@@ -57,6 +58,7 @@ const EMPTY: ClientBulkAddFormValues = {
   expiryTime: 0,
   reset: 0,
   resetDay: 0,
+  resetWeekday: 0,
   resetMax: 0,
   trafficReset: 'never' as const,
   trafficResetDay: 1,
@@ -215,6 +217,7 @@ export default function ClientBulkAddModal({
           expiryTime: current.expiryTime,
           reset: Number(current.reset) || 0,
           resetDay: Number(current.resetDay) || 0,
+          resetWeekday: Number(current.resetWeekday) || 0,
           resetMax: Number(current.resetMax) || 0,
           trafficReset: current.trafficReset || 'never',
           trafficResetDay: Number(current.trafficResetDay) || 1,
@@ -437,32 +440,13 @@ export default function ClientBulkAddModal({
               </Form.Item>
             )}
 
-            <FormField
-              name="reset"
-              label={t('pages.clients.renew')}
-              tooltip={t('pages.clients.renewDesc')}
-              transform={{ output: (v) => Number(v) || 0 }}
-            >
-              <InputNumber min={0} />
-            </FormField>
-
-            <FormField
-              name="resetDay"
-              label={t('pages.clients.renewOnDay')}
-              tooltip={t('pages.clients.renewOnDayDesc')}
-              transform={{ output: (v) => Number(v) || 0 }}
-            >
-              <InputNumber min={0} max={31} />
-            </FormField>
-
-            <FormField
-              name="resetMax"
-              label={t('pages.clients.renewMax')}
-              tooltip={t('pages.clients.renewMaxDesc')}
-              transform={{ output: (v) => Number(v) || 0 }}
-            >
-              <InputNumber min={0} />
-            </FormField>
+            <ClientRenewalFields
+              active={open}
+              delayedStart={delayedStart}
+              expiryTime={expiryTime}
+              bulk
+              setExpiry={(expiry) => methods.setValue('expiryTime', expiry)}
+            />
 
             <FormField name="trafficReset" label={t('pages.inbounds.periodicTrafficResetTitle')}>
               <Select

frontend/src/pages/clients/ClientFormModal.tsx

@@ -48,6 +48,7 @@ import type {
   ExternalLinkInput,
 } from '@/hooks/useClients';
 import { useFail2banStatusQuery, getLimitIpNotice } from '@/api/queries/useFail2banStatusQuery';
+import ClientRenewalFields from './ClientRenewalFields';
 import { ClientFormSchema, ClientCreateFormSchema, type ClientFormValues } from '@/schemas/client';
 import './ClientFormModal.css';
 
@@ -155,6 +156,7 @@ const EMPTY: Values = {
   delayedDays: 0,
   reset: 0,
   resetDay: 0,
+  resetWeekday: 0,
   resetMax: 0,
   trafficReset: 'never' as const,
   trafficResetDay: 1,
@@ -259,6 +261,7 @@ export default function ClientFormModal({
   const methods = useForm<Values>({ defaultValues: EMPTY });
   const inboundIds = useWatch({ control: methods.control, name: 'inboundIds' });
   const delayedStart = useWatch({ control: methods.control, name: 'delayedStart' });
+  const delayedDays = useWatch({ control: methods.control, name: 'delayedDays' });
   const expiryDate = useWatch({ control: methods.control, name: 'expiryDate' });
   const enable = useWatch({ control: methods.control, name: 'enable' });
   const flow = useWatch({ control: methods.control, name: 'flow' });
@@ -366,6 +369,7 @@ export default function ClientFormModal({
         totalGB: bytesToGB(client.totalGB || 0),
         reset: Number(client.reset) || 0,
         resetDay: Number(client.resetDay) || 0,
+        resetWeekday: Number(client.resetWeekday) || 0,
         resetMax: Number(client.resetMax) || 0,
         trafficReset: (client.trafficReset as ClientFormValues['trafficReset']) || 'never',
         trafficResetDay: Number(client.trafficResetDay) || 1,
@@ -663,6 +667,7 @@ export default function ClientFormModal({
       delayedDays: values.delayedDays,
       reset: values.reset,
       resetDay: values.resetDay,
+      resetWeekday: values.resetWeekday,
       resetMax: values.resetMax,
       trafficReset: values.trafficReset,
       trafficResetDay: values.trafficResetDay,
@@ -696,6 +701,7 @@ export default function ClientFormModal({
       expiryTime,
       reset: Number(values.reset) || 0,
       resetDay: Number(values.resetDay) || 0,
+      resetWeekday: Number(values.resetWeekday) || 0,
       resetMax: Number(values.resetMax) || 0,
       trafficReset: values.trafficReset || 'never',
       trafficResetDay: Number(values.trafficResetDay) || 1,
@@ -985,35 +991,16 @@ export default function ClientFormModal({
                             />
                           </Form.Item>
                         </Col>
-                        <Col xs={12} md={6}>
-                          <FormField
-                            name="reset"
-                            label={t('pages.clients.renewDays')}
-                            tooltip={t('pages.clients.renewDesc')}
-                            transform={{ output: (v) => Number(v) || 0 }}
-                          >
-                            <InputNumber min={0} style={{ width: '100%' }} />
-                          </FormField>
-                        </Col>
-                        <Col xs={12} md={6}>
-                          <FormField
-                            name="resetDay"
-                            label={t('pages.clients.renewOnDay')}
-                            tooltip={t('pages.clients.renewOnDayDesc')}
-                            transform={{ output: (v) => Number(v) || 0 }}
-                          >
-                            <InputNumber min={0} max={31} style={{ width: '100%' }} />
-                          </FormField>
-                        </Col>
-                        <Col xs={12} md={6}>
-                          <FormField
-                            name="resetMax"
-                            label={t('pages.clients.renewMax')}
-                            tooltip={t('pages.clients.renewMaxDesc')}
-                            transform={{ output: (v) => Number(v) || 0 }}
-                          >
-                            <InputNumber min={0} style={{ width: '100%' }} />
-                          </FormField>
+                        <Col xs={24}>
+                          <ClientRenewalFields
+                            active={open}
+                            delayedStart={delayedStart}
+                            expiryTime={
+                              delayedStart ? -86400000 * (delayedDays || 0) : expiryDate || 0
+                            }
+                            resetCount={client?.traffic?.resetCount || 0}
+                            setExpiry={(expiry) => methods.setValue('expiryDate', expiry)}
+                          />
                         </Col>
                         <Col xs={12} md={6}>
                           <FormField

frontend/src/pages/clients/ClientRenewalFields.tsx

@@ -0,0 +1,197 @@
+import { useEffect, useId, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { useFormContext, useWatch } from 'react-hook-form';
+import { useQuery } from '@tanstack/react-query';
+import { Button, Form, InputNumber, Select, Space, Typography } from 'antd';
+
+import { FormField } from '@/components/form/rhf';
+import { ClientRenewalPreviewSchema } from '@/generated/zod';
+import { HttpUtil } from '@/utils';
+import type { ClientFormValues } from '@/schemas/client';
+
+type RenewalFields = Pick<ClientFormValues, 'reset' | 'resetDay' | 'resetWeekday' | 'resetMax'>;
+type RenewalMode = 'none' | 'interval' | 'weekly' | 'monthly';
+
+export default function ClientRenewalFields({
+  active,
+  expiryTime,
+  resetCount = 0,
+  bulk = false,
+  delayedStart = false,
+  setExpiry,
+}: {
+  active: boolean;
+  expiryTime: number;
+  resetCount?: number;
+  bulk?: boolean;
+  delayedStart?: boolean;
+  setExpiry: (expiry: number) => void;
+}) {
+  const { t, i18n } = useTranslation();
+  const formId = useId();
+  const modeId = 'client-renewal-mode-' + formId;
+  const { control, setValue } = useFormContext<RenewalFields>();
+  const [reset, resetDay, resetWeekday, resetMax] = useWatch({
+    control,
+    name: ['reset', 'resetDay', 'resetWeekday', 'resetMax'],
+  });
+  const mode: RenewalMode =
+    resetDay > 0 ? 'monthly' : resetWeekday > 0 ? 'weekly' : reset > 0 ? 'interval' : 'none';
+  const request = useMemo(
+    () => ({
+      expiryTime,
+      reset: reset || 0,
+      resetDay: resetDay || 0,
+      resetWeekday: resetWeekday || 0,
+      resetMax: resetMax || 0,
+      resetCount,
+    }),
+    [expiryTime, reset, resetDay, resetWeekday, resetMax, resetCount],
+  );
+  const [debounced, setDebounced] = useState(request);
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(request), 250);
+    return () => clearTimeout(timer);
+  }, [request]);
+  const query = useQuery({
+    queryKey: ['clients', 'renewalPreview', debounced],
+    enabled: active && mode !== 'none' && request === debounced,
+    retry: false,
+    queryFn: async () => {
+      const msg = await HttpUtil.post('/panel/api/clients/renewalPreview', debounced, {
+        headers: { 'Content-Type': 'application/json' },
+        silent: true,
+      });
+      if (!msg?.success) throw new Error(msg?.msg || 'Renewal preview failed');
+      return ClientRenewalPreviewSchema.parse(msg.obj);
+    },
+  });
+  const preview = request === debounced ? query.data : undefined;
+  const weekdayFormatter = new Intl.DateTimeFormat(i18n.language, {
+    weekday: 'long',
+    timeZone: 'UTC',
+  });
+  function changeMode(next: RenewalMode) {
+    setValue('reset', next === 'interval' ? Math.max(1, reset || 0) : 0);
+    setValue('resetDay', next === 'monthly' ? Math.max(1, resetDay || 0) : 0);
+    setValue('resetWeekday', next === 'weekly' ? Math.max(1, resetWeekday || 0) : 0);
+  }
+  return (
+    <>
+      <Form.Item label={t('pages.clients.renewMode')} htmlFor={modeId}>
+        <Select
+          id={modeId}
+          value={mode}
+          onChange={changeMode}
+          options={[
+            { value: 'none', label: t('pages.clients.renewModeNone') },
+            { value: 'interval', label: t('pages.clients.renewModeInterval') },
+            { value: 'weekly', label: t('pages.clients.renewModeWeekly') },
+            { value: 'monthly', label: t('pages.clients.renewModeMonthly') },
+          ]}
+        />
+      </Form.Item>
+      {mode === 'interval' && (
+        <FormField
+          name="reset"
+          label={bulk ? t('pages.clients.renew') : t('pages.clients.renewDays')}
+          tooltip={t('pages.clients.renewDesc')}
+          transform={{ output: (v) => Number(v) || 1 }}
+        >
+          <InputNumber id={'client-renewal-interval-' + formId} min={1} style={{ width: '100%' }} />
+        </FormField>
+      )}
+      {mode === 'monthly' && (
+        <FormField
+          name="resetDay"
+          label={t('pages.clients.renewOnDay')}
+          tooltip={t('pages.clients.renewOnDayDesc')}
+          transform={{ output: (v) => Number(v) || 1 }}
+        >
+          <InputNumber
+            id={'client-renewal-day-' + formId}
+            min={1}
+            max={31}
+            style={{ width: '100%' }}
+          />
+        </FormField>
+      )}
+      {mode === 'weekly' && (
+        <FormField name="resetWeekday" label={t('pages.clients.renewWeekday')}>
+          <Select
+            id={'client-renewal-weekday-' + formId}
+            options={Array.from({ length: 7 }, (_, i) => ({
+              value: i + 1,
+              label: weekdayFormatter.format(new Date(Date.UTC(2026, 0, i + 5))),
+            }))}
+          />
+        </FormField>
+      )}
+      {mode !== 'none' && (
+        <>
+          <FormField
+            name="resetMax"
+            label={t('pages.clients.renewMax')}
+            tooltip={t('pages.clients.renewMaxDesc')}
+            transform={{ output: (v) => Number(v) || 0 }}
+          >
+            <InputNumber min={0} style={{ width: '100%' }} />
+          </FormField>
+          <Typography.Paragraph type="secondary">
+            {t('pages.clients.renewScheduleDesc')}
+          </Typography.Paragraph>
+          {query.isError && request === debounced && (
+            <Typography.Paragraph type="warning">
+              {t('pages.clients.renewPreviewError')}
+            </Typography.Paragraph>
+          )}
+          {preview && (
+            <Space orientation="vertical" size={4} style={{ marginBottom: 16 }}>
+              <Typography.Text>
+                {t('pages.clients.renewPreview', { zone: preview.timeZone })}
+              </Typography.Text>
+              {delayedStart || preview.delayedStart ? (
+                <Typography.Text type="secondary">
+                  {t('pages.clients.renewFirstUse')}
+                </Typography.Text>
+              ) : expiryTime === 0 ? (
+                <>
+                  <Typography.Text type="warning">
+                    {t('pages.clients.renewNeedsExpiry')}
+                  </Typography.Text>
+                  {preview.suggestedExpiryTime > 0 && (
+                    <Button onClick={() => setExpiry(preview.suggestedExpiryTime)}>
+                      {t('pages.clients.renewSetExpiry')}: {preview.suggestedExpiry}
+                    </Button>
+                  )}
+                </>
+              ) : (
+                <>
+                  <Typography.Text>
+                    {t('pages.clients.renewAt')}: {preview.renewAt}
+                  </Typography.Text>
+                  <Typography.Text>
+                    {t('pages.clients.renewValidThrough')}: {preview.validThrough}
+                  </Typography.Text>
+                  {preview.nextExpiry && (
+                    <Typography.Text>
+                      {t('pages.clients.renewNextExpiry')}: {preview.nextExpiry}
+                    </Typography.Text>
+                  )}
+                  <Typography.Text>
+                    {t('pages.clients.renewPeriods', { count: preview.renewals })}
+                  </Typography.Text>
+                  {!preview.canRenew && (
+                    <Typography.Text type="warning">
+                      {t('pages.clients.renewUnavailable')}
+                    </Typography.Text>
+                  )}
+                </>
+              )}
+            </Space>
+          )}
+        </>
+      )}
+    </>
+  );
+}

frontend/src/schemas/client.ts

@@ -41,6 +41,7 @@ export const ClientRecordSchema = z
     enable: z.boolean().optional(),
     reset: z.number().optional(),
     resetDay: z.number().optional(),
+    resetWeekday: z.number().optional(),
     resetMax: z.number().optional(),
     trafficReset: z.string().optional(),
     trafficResetDay: z.number().optional(),
@@ -328,6 +329,7 @@ export const ClientFormSchema = z.object({
   delayedDays: z.number().int().min(0),
   reset: z.number().int().min(0),
   resetDay: z.number().int().min(0).max(31),
+  resetWeekday: z.number().int().min(0).max(7),
   resetMax: z.number().int().min(0),
   trafficReset: z.enum(['never', 'hourly', 'daily', 'weekly', 'monthly']),
   trafficResetDay: z.number().int().min(1).max(31),
@@ -392,6 +394,7 @@ export const ClientBulkAddFormSchema = z.object({
   expiryTime: z.number(),
   reset: z.number().int().min(0),
   resetDay: z.number().int().min(0).max(31),
+  resetWeekday: z.number().int().min(0).max(7),
   resetMax: z.number().int().min(0),
   trafficReset: z.enum(['never', 'hourly', 'daily', 'weekly', 'monthly']).optional(),
   trafficResetDay: z.number().int().min(1).max(31).optional(),

frontend/src/test/client-bulk-calendar-renewal.test.tsx

@@ -0,0 +1,113 @@
+import { expect, it, vi } from 'vitest';
+import { fireEvent, screen, waitFor } from '@testing-library/react';
+
+import ClientBulkAddModal from '@/pages/clients/ClientBulkAddModal';
+import { HttpUtil, Msg } from '@/utils';
+import { chooseSelectOption, renderWithProviders } from './test-utils';
+
+const { bulkCreate } = vi.hoisted(() => ({ bulkCreate: vi.fn() }));
+vi.mock('@/hooks/useClients', () => ({ useClients: () => ({ bulkCreate }) }));
+
+it('keeps bulk renewal disabled by default and requires explicit cutoff selection without changing first-use duration', async () => {
+  bulkCreate.mockResolvedValue(new Msg(true, '', { created: 1, skipped: [] }));
+  const post = vi.spyOn(HttpUtil, 'post').mockImplementation(async (url, body) => {
+    if (url !== '/panel/api/clients/renewalPreview')
+      return new Msg(true, '', { datepicker: 'gregorian' });
+    const request = body as { expiryTime: number };
+    return new Msg(true, '', {
+      timeZone: 'Asia/Taipei',
+      renewAt: '',
+      validThrough: '',
+      nextExpiry: '',
+      suggestedExpiryTime: 1893427200000,
+      suggestedExpiry: '2030-01-01T00:00:00+08:00',
+      renewals: 0,
+      canRenew: false,
+      delayedStart: request.expiryTime < 0,
+    });
+  });
+  async function submit() {
+    const button = document.querySelector('.ant-modal-footer .ant-btn-primary');
+    if (!button) throw new Error('Create button missing');
+    await waitFor(() => expect(button.classList.contains('ant-btn-loading')).toBe(false));
+    fireEvent.click(button);
+  }
+  try {
+    renderWithProviders(
+      <ClientBulkAddModal
+        open
+        inbounds={[{ id: 1, protocol: 'vless', tag: 'calendar' }]}
+        onOpenChange={() => {}}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Select all' }));
+    const mode = screen.getByLabelText('Auto renewal');
+    expect(mode.closest('.ant-select')?.textContent).toContain('Disabled');
+    expect(post.mock.calls.some(([url]) => url === '/panel/api/clients/renewalPreview')).toBe(
+      false,
+    );
+    await submit();
+    await waitFor(() =>
+      expect(bulkCreate).toHaveBeenCalledWith([
+        expect.objectContaining({
+          client: expect.objectContaining({
+            reset: 0,
+            resetDay: 0,
+            resetWeekday: 0,
+            expiryTime: 0,
+          }),
+        }),
+      ]),
+    );
+    chooseSelectOption(mode.id, 'Calendar weekly');
+    await waitFor(() => expect(document.body.textContent).toContain('An expiry must be set'));
+    await submit();
+    await waitFor(() =>
+      expect(bulkCreate).toHaveBeenLastCalledWith([
+        expect.objectContaining({
+          client: expect.objectContaining({
+            reset: 0,
+            resetDay: 0,
+            resetWeekday: 1,
+            expiryTime: 0,
+          }),
+        }),
+      ]),
+    );
+    fireEvent.click(screen.getByRole('button', { name: /Set first cycle cutoff/ }));
+    await submit();
+    await waitFor(() =>
+      expect(bulkCreate).toHaveBeenLastCalledWith([
+        expect.objectContaining({
+          client: expect.objectContaining({ resetWeekday: 1, expiryTime: 1893427200000 }),
+        }),
+      ]),
+    );
+    const label = Array.from(document.querySelectorAll('.ant-form-item-label label')).find(
+      (el) => el.textContent === 'Start After First Use',
+    );
+    const toggle = label?.closest('.ant-form-item')?.querySelector('[role="switch"]');
+    if (!toggle) throw new Error('First-use switch missing');
+    fireEvent.click(toggle);
+    const daysLabel = Array.from(document.querySelectorAll('.ant-form-item-label label')).find(
+      (el) => el.textContent === 'Duration (days)',
+    );
+    const daysInput = daysLabel?.closest('.ant-form-item')?.querySelector('input');
+    if (!daysInput) throw new Error('First-use days input missing');
+    fireEvent.change(daysInput, { target: { value: '7' } });
+    await waitFor(() =>
+      expect(document.body.textContent).toContain('Dates are available after first-use activation'),
+    );
+    expect(screen.queryByRole('button', { name: /Set first cycle cutoff/ })).toBeNull();
+    await submit();
+    await waitFor(() =>
+      expect(bulkCreate).toHaveBeenLastCalledWith([
+        expect.objectContaining({
+          client: expect.objectContaining({ resetWeekday: 1, expiryTime: -604800000 }),
+        }),
+      ]),
+    );
+  } finally {
+    post.mockRestore();
+  }
+});

frontend/src/test/client-calendar-renewal.test.tsx

@@ -0,0 +1,109 @@
+import { expect, it, vi } from 'vitest';
+import { fireEvent, screen, waitFor } from '@testing-library/react';
+
+import ClientFormModal from '@/pages/clients/ClientFormModal';
+import { HttpUtil, Msg } from '@/utils';
+import { chooseSelectOption, renderWithProviders } from './test-utils';
+
+it('preserves monthly clients, previews backend dates, and saves exclusive weekly or disabled modes', async () => {
+  const post = vi.spyOn(HttpUtil, 'post').mockResolvedValue(
+    new Msg(true, '', {
+      timeZone: 'Asia/Taipei',
+      renewAt: '2030-01-01T00:00:00+08:00',
+      validThrough: '2029-12-31T23:59:59+08:00',
+      nextExpiry: '2030-02-01T00:00:00+08:00',
+      suggestedExpiryTime: 1893427200000,
+      suggestedExpiry: '2030-01-01T00:00:00+08:00',
+      renewals: 1,
+      canRenew: true,
+      delayedStart: false,
+    }),
+  );
+  const save = vi.fn().mockResolvedValue(new Msg(true, '', null));
+  async function submit() {
+    const button = document.querySelector('.ant-modal-footer .ant-btn-primary');
+    if (!button) throw new Error('Save button missing');
+    await waitFor(() => expect(button.classList.contains('ant-btn-loading')).toBe(false));
+    fireEvent.click(button);
+  }
+  try {
+    renderWithProviders(
+      <ClientFormModal
+        open
+        mode="edit"
+        client={{
+          email: 'monthly@example.com',
+          uuid: '11111111-1111-1111-1111-111111111111',
+          subId: 'calendar-sub',
+          enable: true,
+          expiryTime: 1893427200000,
+          resetDay: 1,
+          reset: 7,
+          resetMax: 3,
+          traffic: { resetCount: 2 },
+        }}
+        attachedIds={[1]}
+        inbounds={[{ id: 1, protocol: 'vless', tag: 'calendar' }]}
+        save={save}
+        onOpenChange={() => {}}
+      />,
+    );
+    const mode = screen.getByLabelText('Auto renewal');
+    expect(mode.closest('.ant-select')?.textContent).toContain('Calendar monthly');
+    await waitFor(() => expect(document.body.textContent).toContain('2029-12-31T23:59:59+08:00'));
+    expect(post).toHaveBeenCalledWith(
+      '/panel/api/clients/renewalPreview',
+      expect.objectContaining({ resetMax: 3, resetCount: 2 }),
+      expect.anything(),
+    );
+    await submit();
+    await waitFor(() =>
+      expect(save).toHaveBeenCalledWith(
+        expect.objectContaining({
+          reset: 7,
+          resetDay: 1,
+          resetWeekday: 0,
+          expiryTime: 1893427200000,
+        }),
+        expect.anything(),
+      ),
+    );
+    chooseSelectOption(mode.id, 'Calendar weekly');
+    const weekday = screen.getByLabelText('Renew on weekday');
+    chooseSelectOption(weekday.id, 'Sunday');
+    await waitFor(() =>
+      expect(post).toHaveBeenCalledWith(
+        '/panel/api/clients/renewalPreview',
+        expect.objectContaining({ reset: 0, resetDay: 0, resetWeekday: 7 }),
+        expect.anything(),
+      ),
+    );
+    await submit();
+    await waitFor(() =>
+      expect(save).toHaveBeenCalledWith(
+        expect.objectContaining({
+          reset: 0,
+          resetDay: 0,
+          resetWeekday: 7,
+          expiryTime: 1893427200000,
+        }),
+        expect.anything(),
+      ),
+    );
+    chooseSelectOption(mode.id, 'Disabled');
+    await submit();
+    await waitFor(() =>
+      expect(save).toHaveBeenCalledWith(
+        expect.objectContaining({
+          reset: 0,
+          resetDay: 0,
+          resetWeekday: 0,
+          expiryTime: 1893427200000,
+        }),
+        expect.anything(),
+      ),
+    );
+  } finally {
+    post.mockRestore();
+  }
+});

frontend/src/test/client-toggle-traffic-reset.test.tsx

@@ -18,7 +18,16 @@ describe('client enable toggle', () => {
       const email = 'scheduled@example.com';
       vi.spyOn(HttpUtil, 'get').mockResolvedValue(
         new Msg(true, '', {
-          client: { email, enable: !enable, trafficReset: 'monthly', trafficResetDay: 15 },
+          client: {
+            email,
+            enable: !enable,
+            trafficReset: 'monthly',
+            trafficResetDay: 15,
+            reset: 0,
+            resetDay: 0,
+            resetWeekday: 7,
+            resetMax: 3,
+          },
           inboundIds: [],
         }),
       );
@@ -44,7 +53,16 @@ describe('client enable toggle', () => {
       expect(HttpUtil.get).toHaveBeenCalledWith('/panel/api/clients/get/scheduled%40example.com');
       expect(post).toHaveBeenCalledWith(
         '/panel/api/clients/update/scheduled%40example.com',
-        expect.objectContaining({ email, enable, trafficReset: 'monthly', trafficResetDay: 15 }),
+        expect.objectContaining({
+          email,
+          enable,
+          trafficReset: 'monthly',
+          trafficResetDay: 15,
+          reset: 0,
+          resetDay: 0,
+          resetWeekday: 7,
+          resetMax: 3,
+        }),
         { headers: { 'Content-Type': 'application/json' } },
       );
     },

internal/database/client_weekly_renew_migration_test.go

@@ -0,0 +1,90 @@
+package database
+
+import (
+	"path/filepath"
+	"testing"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/xray"
+)
+
+func TestClientWeeklyRenewMigration(t *testing.T) {
+	for _, nullable := range []bool{false, true} {
+		name := "missing columns"
+		if nullable {
+			name = "nullable columns and configured weekday"
+		}
+		t.Run(name, func(t *testing.T) {
+			path := filepath.Join(t.TempDir(), "x-ui.db")
+			legacy, err := gorm.Open(sqlite.Open(path), &gorm.Config{})
+			if err != nil {
+				t.Fatal(err)
+			}
+			column := ""
+			if nullable {
+				column = ", reset_weekday INTEGER"
+			}
+			for _, ddl := range []string{
+				"CREATE TABLE clients (id INTEGER PRIMARY KEY, email TEXT, reset INTEGER, reset_day INTEGER, reset_max INTEGER, expiry_time BIGINT" + column + ")",
+				"CREATE TABLE client_traffics (id INTEGER PRIMARY KEY, email TEXT, reset INTEGER, reset_day INTEGER, reset_max INTEGER, reset_count INTEGER, expiry_time BIGINT, up BIGINT, down BIGINT" + column + ")",
+				"INSERT INTO clients (id,email,reset,reset_day,reset_max,expiry_time) VALUES (1,'legacy',30,15,3,1893456000000)",
+				"INSERT INTO client_traffics (id,email,reset,reset_day,reset_max,reset_count,expiry_time,up,down) VALUES (1,'legacy',30,15,3,2,1893456000000,111,222)",
+			} {
+				if err := legacy.Exec(ddl).Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+			if nullable {
+				if err := legacy.Exec("INSERT INTO clients (id,email,reset_weekday) VALUES (2,'weekly',2)").Error; err != nil {
+					t.Fatal(err)
+				}
+				if err := legacy.Exec("INSERT INTO client_traffics (id,email,reset_weekday) VALUES (2,'weekly',2)").Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+			handle, err := legacy.DB()
+			if err != nil {
+				t.Fatal(err)
+			}
+			if err := handle.Close(); err != nil {
+				t.Fatal(err)
+			}
+			if err := InitDB(path); err != nil {
+				t.Fatal(err)
+			}
+			t.Cleanup(func() { _ = CloseDB() })
+			for _, table := range []string{"clients", "client_traffics"} {
+				var nulls int64
+				if err := GetDB().Table(table).Where("reset_weekday IS NULL").Count(&nulls).Error; err != nil || nulls != 0 {
+					t.Fatalf("%s NULL weekdays/error = %d/%v", table, nulls, err)
+				}
+				if nullable {
+					var weekday int
+					if err := GetDB().Table(table).Where("email = ?", "weekly").Pluck("reset_weekday", &weekday).Error; err != nil || weekday != 2 {
+						t.Fatalf("%s configured weekday/error = %d/%v", table, weekday, err)
+					}
+				}
+			}
+			var client model.ClientRecord
+			if err := GetDB().Where("email = ?", "legacy").First(&client).Error; err != nil {
+				t.Fatal(err)
+			}
+			var traffic xray.ClientTraffic
+			if err := GetDB().Where("email = ?", "legacy").First(&traffic).Error; err != nil {
+				t.Fatal(err)
+			}
+			if client.Reset != 30 || client.ResetDay != 15 || client.ResetMax != 3 || client.ResetWeekday != 0 || client.ExpiryTime != 1893456000000 {
+				t.Fatalf("legacy client changed: %+v", client)
+			}
+			if traffic.Reset != 30 || traffic.ResetDay != 15 || traffic.ResetMax != 3 || traffic.ResetCount != 2 || traffic.ResetWeekday != 0 || traffic.ExpiryTime != 1893456000000 || traffic.Up != 111 || traffic.Down != 222 {
+				t.Fatalf("legacy traffic changed: %+v", traffic)
+			}
+			if err := migrateClientResetWeekdayColumns(); err != nil {
+				t.Fatal(err)
+			}
+		})
+	}
+}

internal/database/client_weekly_renew_postgres_test.go

@@ -0,0 +1,118 @@
+package database
+
+import (
+	"fmt"
+	"net/url"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/xray"
+)
+
+func TestClientWeeklyRenewMigration_Postgres(t *testing.T) {
+	dsn := strings.TrimSpace(os.Getenv("XUI_DB_DSN"))
+	if dsn == "" || os.Getenv("XUI_DB_TYPE") != "postgres" {
+		t.Skip("set XUI_DB_TYPE=postgres and XUI_DB_DSN to run the weekly migration test")
+	}
+	admin, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	handle, err := admin.DB()
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = handle.Close() })
+	for _, nullable := range []bool{false, true} {
+		t.Run(fmt.Sprintf("nullable_%t", nullable), func(t *testing.T) {
+			schema := fmt.Sprintf("weekly_renew_%d", time.Now().UnixNano())
+			if err := admin.Exec("CREATE SCHEMA " + schema).Error; err != nil {
+				t.Fatal(err)
+			}
+			t.Cleanup(func() {
+				_ = CloseDB()
+				if err := admin.Exec("DROP SCHEMA " + schema + " CASCADE").Error; err != nil {
+					t.Error(err)
+				}
+			})
+			scoped := dsn + " search_path=" + schema
+			if strings.HasPrefix(dsn, "postgres://") || strings.HasPrefix(dsn, "postgresql://") {
+				u, err := url.Parse(dsn)
+				if err != nil {
+					t.Fatal(err)
+				}
+				query := u.Query()
+				query.Set("search_path", schema)
+				u.RawQuery = query.Encode()
+				scoped = u.String()
+			}
+			t.Setenv("XUI_DB_DSN", scoped)
+			legacy, err := gorm.Open(postgres.Open(scoped), &gorm.Config{})
+			if err != nil {
+				t.Fatal(err)
+			}
+			legacyHandle, err := legacy.DB()
+			if err != nil {
+				t.Fatal(err)
+			}
+			t.Cleanup(func() { _ = legacyHandle.Close() })
+			column := ""
+			if nullable {
+				column = ", reset_weekday INTEGER"
+			}
+			for _, ddl := range []string{
+				"CREATE TABLE clients (id BIGSERIAL PRIMARY KEY, email TEXT, reset INTEGER, reset_day INTEGER, reset_max INTEGER, expiry_time BIGINT" + column + ")",
+				"CREATE TABLE client_traffics (id BIGSERIAL PRIMARY KEY, email TEXT, reset INTEGER, reset_day INTEGER, reset_max INTEGER, reset_count INTEGER, expiry_time BIGINT, up BIGINT, down BIGINT" + column + ")",
+				"INSERT INTO clients (email,reset,reset_day,reset_max,expiry_time) VALUES ('legacy',30,15,3,1893456000000)",
+				"INSERT INTO client_traffics (email,reset,reset_day,reset_max,reset_count,expiry_time,up,down) VALUES ('legacy',30,15,3,2,1893456000000,111,222)",
+			} {
+				if err := legacy.Exec(ddl).Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+			if nullable {
+				if err := legacy.Exec("INSERT INTO clients (email,reset_weekday) VALUES ('weekly',2)").Error; err != nil {
+					t.Fatal(err)
+				}
+				if err := legacy.Exec("INSERT INTO client_traffics (email,reset_weekday) VALUES ('weekly',2)").Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+			if err := InitDB(""); err != nil {
+				t.Fatal(err)
+			}
+			for _, table := range []string{"clients", "client_traffics"} {
+				var nulls int64
+				if err := GetDB().Table(table).Where("reset_weekday IS NULL").Count(&nulls).Error; err != nil || nulls != 0 {
+					t.Fatalf("%s NULL weekdays/error = %d/%v", table, nulls, err)
+				}
+				if nullable {
+					var weekday int
+					if err := GetDB().Table(table).Where("email = ?", "weekly").Pluck("reset_weekday", &weekday).Error; err != nil || weekday != 2 {
+						t.Fatalf("%s weekday/error = %d/%v, want 2/nil", table, weekday, err)
+					}
+				}
+			}
+			var client model.ClientRecord
+			if err := GetDB().Where("email = ?", "legacy").First(&client).Error; err != nil {
+				t.Fatal(err)
+			}
+			var traffic xray.ClientTraffic
+			if err := GetDB().Where("email = ?", "legacy").First(&traffic).Error; err != nil {
+				t.Fatal(err)
+			}
+			if client.ResetWeekday != 0 || client.Reset != 30 || client.ResetDay != 15 || client.ResetMax != 3 || client.ExpiryTime != 1893456000000 || traffic.ResetWeekday != 0 || traffic.Reset != 30 || traffic.ResetDay != 15 || traffic.ResetMax != 3 || traffic.ResetCount != 2 || traffic.Up != 111 || traffic.Down != 222 || traffic.ExpiryTime != client.ExpiryTime {
+				t.Fatalf("legacy PostgreSQL limits changed: client=%+v traffic=%+v", client, traffic)
+			}
+			if err := migrateClientResetWeekdayColumns(); err != nil {
+				t.Fatal(err)
+			}
+		})
+	}
+}

internal/database/db.go

@@ -176,6 +176,9 @@ func initModels() error {
 	if err := migrateClientTrafficResetColumns(); err != nil {
 		return err
 	}
+	if err := migrateClientResetWeekdayColumns(); err != nil {
+		return err
+	}
 	if err := migrateSyncOrphanColumns(); err != nil {
 		return err
 	}
@@ -355,6 +358,17 @@ func migrateClientTrafficResetColumns() error {
 	return nil
 }
 
+// Existing clients keep weekly renewal disabled, including nullable columns
+// left by an earlier ALTER TABLE; configured nonzero weekdays are preserved.
+func migrateClientResetWeekdayColumns() error {
+	for _, table := range []string{"clients", "client_traffics"} {
+		if err := db.Table(table).Where("reset_weekday IS NULL").UpdateColumn("reset_weekday", 0).Error; err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
 // AutoMigrate adds the column; this only backfills the NULLs an older SQLite
 // ALTER TABLE leaves behind, so the reaper's predicate never compares to NULL.
 func migrateSyncOrphanColumns() error {

internal/database/model/client_renewal_merge_test.go

@@ -0,0 +1,30 @@
+package model
+
+import "testing"
+
+func TestMergeClientRecordRenewalModes(t *testing.T) {
+	for _, tt := range []struct {
+		name                string
+		existing, incoming  ClientRecord
+		reset, day, weekday int
+	}{
+		{"newer weekly replaces interval", ClientRecord{Reset: 7, UpdatedAt: 1}, ClientRecord{ResetWeekday: 3, UpdatedAt: 2}, 0, 0, 3},
+		{"newer weekly replaces legacy monthly", ClientRecord{Reset: 7, ResetDay: 1, UpdatedAt: 1}, ClientRecord{ResetWeekday: 3, UpdatedAt: 2}, 0, 0, 3},
+		{"newer interval replaces weekly", ClientRecord{ResetWeekday: 3, UpdatedAt: 1}, ClientRecord{Reset: 7, UpdatedAt: 2}, 7, 0, 0},
+		{"newer monthly replaces weekly", ClientRecord{ResetWeekday: 3, UpdatedAt: 1}, ClientRecord{Reset: 7, ResetDay: 1, UpdatedAt: 2}, 7, 1, 0},
+		{"older weekly cannot fill interval zeros", ClientRecord{Reset: 7, UpdatedAt: 2}, ClientRecord{ResetWeekday: 3, UpdatedAt: 1}, 7, 0, 0},
+		{"older interval cannot fill weekly zeros", ClientRecord{ResetWeekday: 3, UpdatedAt: 2}, ClientRecord{Reset: 7, UpdatedAt: 1}, 0, 0, 3},
+		{"older monthly cannot fill weekly zeros", ClientRecord{ResetWeekday: 3, UpdatedAt: 2}, ClientRecord{ResetDay: 1, UpdatedAt: 1}, 0, 0, 3},
+		{"empty newer snapshot preserves weekly", ClientRecord{ResetWeekday: 3, UpdatedAt: 1}, ClientRecord{UpdatedAt: 2}, 0, 0, 3},
+		{"unset existing accepts weekly", ClientRecord{UpdatedAt: 2}, ClientRecord{ResetWeekday: 3, UpdatedAt: 1}, 0, 0, 3},
+		{"legacy monthly merging is unchanged", ClientRecord{Reset: 7, UpdatedAt: 1}, ClientRecord{ResetDay: 1, UpdatedAt: 2}, 7, 1, 0},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			tt.existing.ResetMax = 4
+			MergeClientRecord(&tt.existing, &tt.incoming)
+			if tt.existing.Reset != tt.reset || tt.existing.ResetDay != tt.day || tt.existing.ResetWeekday != tt.weekday || tt.existing.ResetMax != 4 {
+				t.Fatalf("merged schedule/cap = %d/%d/%d/%d, want %d/%d/%d/4", tt.existing.Reset, tt.existing.ResetDay, tt.existing.ResetWeekday, tt.existing.ResetMax, tt.reset, tt.day, tt.weekday)
+			}
+		})
+	}
+}

internal/database/model/model.go

@@ -895,18 +895,19 @@ type Client struct {
 	ForwardedPorts      string           `json:"forwardedPorts,omitempty"` // AmneziaWG per-client port-forwarding spec, e.g. "80,443,8000-8100"
 	Secret              string           `json:"secret,omitempty" example:"ee1234567890abcdef1234567890abcd7777772e636c6f7564666c6172652e636f6d"`
 	AdTag               string           `json:"adTag,omitempty" example:"0123456789abcdef0123456789abcdef"`
-	Email               string           `json:"email"`                        // Client email identifier
-	LimitIP             int              `json:"limitIp"`                      // IP limit for this client
-	TotalGB             int64            `json:"totalGB" form:"totalGB"`       // Total traffic limit in GB
-	ExpiryTime          int64            `json:"expiryTime" form:"expiryTime"` // Expiration timestamp
-	Enable              bool             `json:"enable" form:"enable"`         // Whether the client is enabled
-	TgID                int64            `json:"tgId" form:"tgId"`             // Telegram user ID for notifications
-	SubID               string           `json:"subId" form:"subId"`           // Subscription identifier
-	Group               string           `json:"group,omitempty" form:"group"` // Logical grouping label
-	Comment             string           `json:"comment" form:"comment"`       // Client comment
-	Reset               int              `json:"reset" form:"reset"`           // Reset period in days
-	ResetDay            int              `json:"resetDay" form:"resetDay"`     // Calendar renewal day 1-31, 0 = interval mode
-	ResetMax            int              `json:"resetMax" form:"resetMax"`     // Max auto-renew count, 0 = unlimited
+	Email               string           `json:"email"`                            // Client email identifier
+	LimitIP             int              `json:"limitIp"`                          // IP limit for this client
+	TotalGB             int64            `json:"totalGB" form:"totalGB"`           // Total traffic limit in GB
+	ExpiryTime          int64            `json:"expiryTime" form:"expiryTime"`     // Expiration timestamp
+	Enable              bool             `json:"enable" form:"enable"`             // Whether the client is enabled
+	TgID                int64            `json:"tgId" form:"tgId"`                 // Telegram user ID for notifications
+	SubID               string           `json:"subId" form:"subId"`               // Subscription identifier
+	Group               string           `json:"group,omitempty" form:"group"`     // Logical grouping label
+	Comment             string           `json:"comment" form:"comment"`           // Client comment
+	Reset               int              `json:"reset" form:"reset"`               // Reset period in days
+	ResetDay            int              `json:"resetDay" form:"resetDay"`         // Calendar renewal day 1-31, 0 disables monthly renewal
+	ResetWeekday        int              `json:"resetWeekday" form:"resetWeekday"` // Calendar weekday 1-7 (Mon-Sun), 0 disables weekly renewal
+	ResetMax            int              `json:"resetMax" form:"resetMax"`         // Max auto-renew count, 0 = unlimited
 	// Per-client traffic reset cycle, independent of the inbound's own (#5497).
 	TrafficReset    string `json:"trafficReset,omitempty" form:"trafficReset" validate:"omitempty,oneof=never hourly daily weekly monthly"`
 	TrafficResetDay int    `json:"trafficResetDay,omitempty" form:"trafficResetDay" validate:"omitempty,gte=1,lte=31"`
@@ -942,6 +943,7 @@ type ClientRecord struct {
 	Comment         string `json:"comment"`
 	Reset           int    `json:"reset" gorm:"default:0"`
 	ResetDay        int    `json:"resetDay" gorm:"column:reset_day;default:0"`
+	ResetWeekday    int    `json:"resetWeekday" gorm:"column:reset_weekday;default:0"`
 	ResetMax        int    `json:"resetMax" gorm:"column:reset_max;default:0"`
 	TrafficReset    string `json:"trafficReset" gorm:"column:traffic_reset;default:never;index:idx_clients_traffic_reset"`
 	TrafficResetDay int    `json:"trafficResetDay" gorm:"column:traffic_reset_day;default:1"`
@@ -1154,6 +1156,7 @@ func (c *Client) ToRecord() *ClientRecord {
 		Comment:         c.Comment,
 		Reset:           c.Reset,
 		ResetDay:        c.ResetDay,
+		ResetWeekday:    c.ResetWeekday,
 		ResetMax:        c.ResetMax,
 		TrafficReset:    c.TrafficReset,
 		TrafficResetDay: c.TrafficResetDay,
@@ -1212,6 +1215,7 @@ func (r *ClientRecord) ToClient() *Client {
 		Comment:         r.Comment,
 		Reset:           r.Reset,
 		ResetDay:        r.ResetDay,
+		ResetWeekday:    r.ResetWeekday,
 		ResetMax:        r.ResetMax,
 		TrafficReset:    r.TrafficReset,
 		TrafficResetDay: r.TrafficResetDay,
@@ -1377,16 +1381,39 @@ func MergeClientRecord(existing *ClientRecord, incoming *ClientRecord) []ClientM
 			existing.TgID = incoming.TgID
 		}
 	}
-	if existing.Reset != incoming.Reset && incoming.Reset != 0 {
-		if incomingNewer || existing.Reset == 0 {
-			keep("reset", existing.Reset, incoming.Reset, incoming.Reset)
-			existing.Reset = incoming.Reset
+	if existing.ResetWeekday != 0 || incoming.ResetWeekday != 0 {
+		// A mode switch must carry its zeroes, not fill them from another mode.
+		// Empty snapshots still preserve the existing schedule during migration.
+		incomingSet := incoming.Reset != 0 || incoming.ResetDay != 0 || incoming.ResetWeekday != 0
+		existingSet := existing.Reset != 0 || existing.ResetDay != 0 || existing.ResetWeekday != 0
+		if incomingSet && (incomingNewer || !existingSet) {
+			for _, field := range []struct {
+				name    string
+				current *int
+				value   int
+			}{
+				{"reset", &existing.Reset, incoming.Reset},
+				{"resetDay", &existing.ResetDay, incoming.ResetDay},
+				{"resetWeekday", &existing.ResetWeekday, incoming.ResetWeekday},
+			} {
+				if *field.current != field.value {
+					keep(field.name, *field.current, field.value, field.value)
+					*field.current = field.value
+				}
+			}
 		}
-	}
-	if existing.ResetDay != incoming.ResetDay && incoming.ResetDay != 0 {
-		if incomingNewer || existing.ResetDay == 0 {
-			keep("resetDay", existing.ResetDay, incoming.ResetDay, incoming.ResetDay)
-			existing.ResetDay = incoming.ResetDay
+	} else {
+		if existing.Reset != incoming.Reset && incoming.Reset != 0 {
+			if incomingNewer || existing.Reset == 0 {
+				keep("reset", existing.Reset, incoming.Reset, incoming.Reset)
+				existing.Reset = incoming.Reset
+			}
+		}
+		if existing.ResetDay != incoming.ResetDay && incoming.ResetDay != 0 {
+			if incomingNewer || existing.ResetDay == 0 {
+				keep("resetDay", existing.ResetDay, incoming.ResetDay, incoming.ResetDay)
+				existing.ResetDay = incoming.ResetDay
+			}
 		}
 	}
 	if existing.ResetMax != incoming.ResetMax && incoming.ResetMax != 0 {

internal/web/controller/client.go

@@ -60,6 +60,7 @@ func (a *ClientController) initRouter(g *gin.RouterGroup) {
 	g.POST("/happLink/:id", a.generateHappLink)
 
 	g.POST("/add", a.create)
+	g.POST("/renewalPreview", a.renewalPreview)
 	g.POST("/update/:email", a.update)
 	g.POST("/del/:email", a.delete)
 	g.POST("/:email/attach", a.attach)
@@ -101,6 +102,16 @@ func (a *ClientController) list(c *gin.Context) {
 	jsonObj(c, rows, nil)
 }
 
+func (a *ClientController) renewalPreview(c *gin.Context) {
+	var request service.ClientRenewalPreviewRequest
+	if err := c.ShouldBindJSON(&request); err != nil {
+		jsonObj(c, nil, err)
+		return
+	}
+	preview, err := a.clientService.PreviewRenewal(request, &a.settingService)
+	jsonObj(c, preview, err)
+}
+
 func (a *ClientController) listPaged(c *gin.Context) {
 	var params service.ClientPageParams
 	if err := c.ShouldBindQuery(&params); err != nil {

internal/web/controller/client_renewal_preview_test.go

@@ -0,0 +1,124 @@
+package controller
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database"
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/web/service"
+	"github.com/mhsanaei/3x-ui/v3/internal/xray"
+)
+
+func TestClientRenewalPreviewHTTP(t *testing.T) {
+	for _, tt := range []struct {
+		name, zone, expiry, renewAt, validThrough, next string
+		wantError                                       string
+		reset, day, weekday, max, count                 int
+		periods                                         int
+		canRenew, delayed, invalid                      bool
+	}{
+		{name: "monthly uses Taipei and preserves legacy precedence", zone: "Asia/Taipei", expiry: "2030-01-01T00:00:00+08:00", renewAt: "2030-01-01T00:00:00+08:00", validThrough: "2029-12-31T23:59:59+08:00", next: "2030-02-01T00:00:00+08:00", reset: 7, day: 1, canRenew: true},
+		{name: "31st clamps in February", zone: "UTC", expiry: "2030-01-31T00:00:00Z", renewAt: "2030-01-31T00:00:00Z", validThrough: "2030-01-30T23:59:59Z", next: "2030-02-28T00:00:00Z", day: 31, canRenew: true},
+		{name: "31st returns after February", zone: "UTC", expiry: "2030-02-28T00:00:00Z", renewAt: "2030-02-28T00:00:00Z", validThrough: "2030-02-27T23:59:59Z", next: "2030-03-31T00:00:00Z", day: 31, canRenew: true},
+		{name: "leap February", zone: "UTC", expiry: "2028-01-31T00:00:00Z", renewAt: "2028-01-31T00:00:00Z", validThrough: "2028-01-30T23:59:59Z", next: "2028-02-29T00:00:00Z", day: 31, canRenew: true},
+		{name: "weekly crosses New York daylight saving", zone: "America/New_York", expiry: "2030-03-10T00:00:00-05:00", renewAt: "2030-03-10T00:00:00-05:00", validThrough: "2030-03-09T23:59:59-05:00", next: "2030-03-17T00:00:00-04:00", weekday: 7, canRenew: true},
+		{name: "interval preserves 168 hours", zone: "America/New_York", expiry: "2030-03-10T00:00:00-05:00", renewAt: "2030-03-10T00:00:00-05:00", validThrough: "2030-03-09T23:59:59-05:00", next: "2030-03-17T01:00:00-04:00", reset: 7, canRenew: true},
+		{name: "inclusive month end charges full month", zone: "UTC", expiry: "2030-01-31T23:59:59Z", renewAt: "2030-02-01T00:00:00Z", validThrough: "2030-01-31T23:59:58Z", next: "2030-03-01T00:00:00Z", day: 1, max: 1, canRenew: true},
+		{name: "inclusive week end charges full week", zone: "UTC", expiry: "2030-01-06T23:59:59Z", renewAt: "2030-01-07T00:00:00Z", validThrough: "2030-01-06T23:59:58Z", next: "2030-01-14T00:00:00Z", weekday: 1, max: 1, canRenew: true},
+		{name: "partial offline catch-up remains expired", zone: "UTC", expiry: "2026-03-01T00:00:00Z", renewAt: "2026-03-01T00:00:00Z", validThrough: "2026-02-28T23:59:59Z", next: "2026-03-08T00:00:00Z", weekday: 7, max: 3, count: 2, periods: 1},
+		{name: "arbitrary initial cutoff is not silently realigned", zone: "UTC", expiry: "2030-01-08T12:00:00Z", renewAt: "2030-01-08T12:00:00Z", validThrough: "2030-01-08T11:59:59Z", next: "2030-01-14T00:00:00Z", weekday: 1, canRenew: true},
+		{name: "cap exhausted", zone: "UTC", expiry: "2030-01-01T00:00:00Z", renewAt: "2030-01-01T00:00:00Z", validThrough: "2029-12-31T23:59:59Z", day: 1, max: 3, count: 3},
+		{name: "unset cutoff only suggests a boundary", zone: "UTC", weekday: 1},
+		{name: "first-use waits for activation", zone: "UTC", expiry: "first-use", weekday: 1, delayed: true},
+		{name: "disabled ignores absolute expiry", zone: "UTC", expiry: "2030-01-01T00:00:00Z"},
+		{name: "invalid weekday", zone: "UTC", weekday: 8, invalid: true, wantError: "client resetWeekday must be between 0 and 7, got: 8\n"},
+		{name: "conflicting weekly and monthly", zone: "UTC", day: 1, weekday: 1, invalid: true, wantError: "client weekly renewal cannot be combined with reset or resetDay\n"},
+		{name: "conflicting weekly and interval", zone: "UTC", reset: 7, weekday: 1, invalid: true, wantError: "client weekly renewal cannot be combined with reset or resetDay\n"},
+		{name: "negative count", zone: "UTC", count: -1, invalid: true, wantError: "renewal preview reset and resetCount must not be negative\n"},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			if err := database.InitDB(filepath.Join(t.TempDir(), "x-ui.db")); err != nil {
+				t.Fatal(err)
+			}
+			t.Cleanup(func() { _ = database.CloseDB() })
+			db := database.GetDB()
+			if err := db.Create(&model.Setting{Key: "timeLocation", Value: tt.zone}).Error; err != nil {
+				t.Fatal(err)
+			}
+			snapshot := xray.ClientTraffic{Email: "preview-sentinel", ExpiryTime: 1893456000000, ResetCount: 7, Up: 111, Down: 222, Enable: true}
+			if err := db.Create(&snapshot).Error; err != nil {
+				t.Fatal(err)
+			}
+			request := service.ClientRenewalPreviewRequest{Reset: tt.reset, ResetDay: tt.day, ResetWeekday: tt.weekday, ResetMax: tt.max, ResetCount: tt.count}
+			if tt.expiry == "first-use" {
+				request.ExpiryTime = -7 * 86400000
+			} else if tt.expiry != "" {
+				at, err := time.Parse(time.RFC3339, tt.expiry)
+				if err != nil {
+					t.Fatal(err)
+				}
+				request.ExpiryTime = at.UnixMilli()
+			}
+			payload, err := json.Marshal(request)
+			if err != nil {
+				t.Fatal(err)
+			}
+			router := gin.New()
+			NewClientController(router.Group("/panel/api/clients"))
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest(http.MethodPost, "/panel/api/clients/renewalPreview", bytes.NewReader(payload))
+			r.Header.Set("Content-Type", "application/json")
+			router.ServeHTTP(w, r)
+			var msg struct {
+				Success bool                         `json:"success"`
+				Msg     string                       `json:"msg"`
+				Obj     service.ClientRenewalPreview `json:"obj"`
+			}
+			if err := json.Unmarshal(w.Body.Bytes(), &msg); err != nil {
+				t.Fatal(err)
+			}
+			if w.Code != http.StatusOK || msg.Success == tt.invalid {
+				t.Fatalf("status/body = %d/%s", w.Code, w.Body.String())
+			}
+			if tt.invalid && msg.Msg != " ("+tt.wantError+")" {
+				t.Fatalf("validation error = %q, want wrapped error %q", msg.Msg, tt.wantError)
+			}
+			if !tt.invalid {
+				got := msg.Obj
+				if got.TimeZone != tt.zone || got.RenewAt != tt.renewAt || got.ValidThrough != tt.validThrough || got.NextExpiry != tt.next || got.CanRenew != tt.canRenew || got.DelayedStart != tt.delayed {
+					t.Fatalf("preview = %+v, want boundary/valid/next %q/%q/%q", got, tt.renewAt, tt.validThrough, tt.next)
+				}
+				wantRenewals := 0
+				if tt.canRenew {
+					wantRenewals = 1
+				}
+				if tt.periods > 0 {
+					wantRenewals = tt.periods
+				}
+				if got.Renewals != wantRenewals {
+					t.Fatalf("periods = %d, want %d", got.Renewals, wantRenewals)
+				}
+				if tt.weekday > 0 || tt.day > 0 {
+					if got.SuggestedExpiryTime <= time.Now().UnixMilli() || got.SuggestedExpiry == "" {
+						t.Fatalf("missing future suggestion: %+v", got)
+					}
+				}
+			}
+			var after xray.ClientTraffic
+			if err := db.Where("email = ?", snapshot.Email).First(&after).Error; err != nil {
+				t.Fatal(err)
+			}
+			if after != snapshot {
+				t.Fatalf("read-only preview mutated traffic: %+v", after)
+			}
+		})
+	}
+}

internal/web/service/calendar_renew.go

@@ -1,6 +1,10 @@
 package service
 
-import "time"
+import (
+	"time"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/xray"
+)
 
 // nextCalendarRenewal returns the next renewal strictly after from, at midnight
 // in loc; a missing day clamps to the month's last, so the 31st comes back (#6106).
@@ -40,3 +44,94 @@ func calendarDay(year int, month time.Month, day int, loc *time.Location) time.T
 func daysInMonth(year int, month time.Month) int {
 	return time.Date(year, month+1, 0, 0, 0, 0, 0, time.UTC).Day()
 }
+
+// Advance by calendar dates, not 168 hours; a repeated midnight must not spend
+// another weekly allowance on the same local date.
+func nextWeeklyRenewal(from time.Time, weekday int, loc *time.Location) time.Time {
+	if loc == nil {
+		loc = time.UTC
+	}
+	local := from.In(loc)
+	days := (min(7, max(1, weekday))%7 - int(local.Weekday()) + 7) % 7
+	if days == 0 {
+		days = 7
+	}
+	date := time.Date(local.Year(), local.Month(), local.Day()+days, 0, 0, 0, 0, time.UTC)
+	// A corrupt or unusual zone must not stall the single traffic writer.
+	// Returning from lets the catch-up forward-progress guard fail closed.
+	for range 8 {
+		candidate, exists := localCalendarDateStart(date, loc)
+		if exists && candidate.After(local) {
+			return candidate
+		}
+		date = date.AddDate(0, 0, 7)
+	}
+	return from
+}
+
+// Find the first valid instant of a local date: Date can pick a repeated
+// midnight or normalize a nonexistent midnight into the preceding day.
+func localCalendarDateStart(date time.Time, loc *time.Location) (time.Time, bool) {
+	localDate := func(at time.Time) time.Time {
+		local := at.In(loc)
+		return time.Date(local.Year(), local.Month(), local.Day(), 0, 0, 0, 0, time.UTC)
+	}
+	candidate := time.Date(date.Year(), date.Month(), date.Day(), 0, 0, 0, 0, loc)
+	if localDate(candidate).Equal(date) && localDate(candidate.Add(-time.Second)).Before(date) {
+		return candidate, true
+	}
+	low, high := candidate.Unix()-86400, candidate.Unix()+86400
+	for low < high {
+		mid := low + (high-low)/2
+		if localDate(time.Unix(mid, 0)).Before(date) {
+			low = mid + 1
+		} else {
+			high = mid
+		}
+	}
+	start := time.Unix(low, 0).In(loc)
+	return start, localDate(start).Equal(date)
+}
+
+func nextClientRenewal(expiry int64, reset, day, weekday int, loc *time.Location) int64 {
+	if day > 0 {
+		return nextCalendarRenewal(time.UnixMilli(expiry), day, loc).UnixMilli()
+	}
+	if weekday > 0 {
+		return nextWeeklyRenewal(time.UnixMilli(expiry), weekday, loc).UnixMilli()
+	}
+	return expiry + int64(reset)*86400000
+}
+
+func canonicalRenewalExpiry(expiry int64, reset, day, weekday int, loc *time.Location) int64 {
+	if day > 0 || weekday > 0 {
+		boundary := nextClientRenewal(expiry, reset, day, weekday, loc)
+		if expiry >= boundary-1000 && expiry < boundary {
+			return boundary
+		}
+	}
+	return expiry
+}
+
+func catchUpClientRenewal(traffic *xray.ClientTraffic, now int64, loc *time.Location) (int64, int) {
+	if traffic.ResetDay <= 0 && traffic.ResetWeekday <= 0 && traffic.Reset <= 0 {
+		return traffic.ExpiryTime, 0
+	}
+	expiry := canonicalRenewalExpiry(traffic.ExpiryTime, traffic.Reset, traffic.ResetDay, traffic.ResetWeekday, loc)
+	renewals := 0
+	for expiry < now {
+		if traffic.ResetMax > 0 && traffic.ResetCount+renewals >= traffic.ResetMax {
+			break
+		}
+		next := nextClientRenewal(expiry, traffic.Reset, traffic.ResetDay, traffic.ResetWeekday, loc)
+		if next <= expiry {
+			return traffic.ExpiryTime, 0
+		}
+		expiry = next
+		renewals++
+	}
+	if renewals == 0 {
+		return traffic.ExpiryTime, 0
+	}
+	return expiry, renewals
+}

internal/web/service/calendar_weekly_bound_test.go

@@ -0,0 +1,78 @@
+package service
+
+import (
+	"encoding/binary"
+	"testing"
+	"time"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/xray"
+)
+
+func TestWeeklyRenewalSearchFailsClosed(t *testing.T) {
+	// Keep a background clock reader so -race catches global timezone writes.
+	started, stop, done := make(chan struct{}), make(chan struct{}), make(chan struct{})
+	go func() {
+		defer close(done)
+		_ = time.Now()
+		close(started)
+		for {
+			select {
+			case <-stop:
+				return
+			default:
+				_ = time.Now()
+			}
+		}
+	}()
+	<-started
+	t.Cleanup(func() { close(stop); <-done })
+
+	// Fault injection: a valid TZif with twelve absent Sundays, not a claim
+	// about real IANA zones. Each following Monday repeats, so no Sunday returns.
+	const transitions = 24
+	data := make([]byte, 44+transitions*5+2*6+2)
+	copy(data, "TZif")
+	binary.BigEndian.PutUint32(data[32:36], transitions)
+	binary.BigEndian.PutUint32(data[36:40], 2)
+	binary.BigEndian.PutUint32(data[40:44], 2)
+	from := time.Date(2026, time.March, 1, 0, 0, 0, 0, time.UTC)
+	for week := range 12 {
+		at := from.AddDate(0, 0, (week+1)*7).Unix()
+		for day := range 2 {
+			index := week*2 + day
+			binary.BigEndian.PutUint32(data[44+index*4:48+index*4], uint32(at+int64(day)*86400))
+			data[44+transitions*4+index] = byte(1 - day)
+		}
+	}
+	binary.BigEndian.PutUint32(data[44+transitions*5+6:48+transitions*5+6], 86400)
+	data[len(data)-2] = 'X'
+	loc, err := time.LoadLocationFromTZData("Test/SkippedSundays", data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := nextWeeklyRenewal(from, 7, loc); !got.Equal(from) {
+		t.Fatalf("exhausted weekly search advanced to %s, want unchanged %s", got.Format(time.RFC3339), from.Format(time.RFC3339))
+	}
+	traffic := &xray.ClientTraffic{ExpiryTime: from.UnixMilli(), ResetWeekday: 7, ResetMax: 4, ResetCount: 2, Enable: false, Up: 111, Down: 222}
+	before := *traffic
+	expiry, renewals := catchUpClientRenewal(traffic, from.AddDate(0, 0, 28).UnixMilli(), loc)
+	if expiry != before.ExpiryTime || renewals != 0 || *traffic != before {
+		t.Fatalf("exhausted search changed billing/traffic: expiry=%d renewals=%d traffic=%+v", expiry, renewals, traffic)
+	}
+	for _, tt := range []struct {
+		name string
+		now  int64
+	}{
+		{"initial suggestion exhausted", from.UnixMilli()},
+		{"catch-up exhausted with allowances left", from.AddDate(0, 3, 0).UnixMilli()},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			preview, err := previewClientRenewal(ClientRenewalPreviewRequest{
+				ExpiryTime: before.ExpiryTime, ResetWeekday: 7, ResetMax: 4, ResetCount: 2,
+			}, tt.now, loc)
+			if err == nil || err.Error() != "calendar renewal could not find a future expiry\n" || preview != nil {
+				t.Fatalf("failed search preview/error = %+v/%v, want nil/calendar search error", preview, err)
+			}
+		})
+	}
+}

internal/web/service/calendar_weekly_renew_test.go

@@ -0,0 +1,52 @@
+package service
+
+import (
+	"testing"
+	"time"
+)
+
+func TestNextWeeklyRenewal_RepeatedMidnight(t *testing.T) {
+	loc, err := time.LoadLocation("America/Havana")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, tt := range []struct{ expiry, want string }{
+		{"2026-10-25T00:00:00-04:00", "2026-11-01T00:00:00-04:00"},
+		{"2026-11-01T00:00:00-04:00", "2026-11-08T00:00:00-05:00"},
+		{"2026-11-01T00:00:00-05:00", "2026-11-08T00:00:00-05:00"},
+	} {
+		from, err := time.Parse(time.RFC3339, tt.expiry)
+		if err != nil {
+			t.Fatal(err)
+		}
+		got := nextWeeklyRenewal(from, 7, loc).Format(time.RFC3339)
+		if got != tt.want {
+			t.Fatalf("next Sunday after %s = %s, want %s", tt.expiry, got, tt.want)
+		}
+	}
+}
+
+func TestNextWeeklyRenewal_SkippedDates(t *testing.T) {
+	for _, tt := range []struct {
+		zone, from, want string
+		weekday          int
+	}{
+		{"America/Havana", "2026-03-01T00:00:00-05:00", "2026-03-08T01:00:00-04:00", 7},
+		{"Pacific/Apia", "2011-12-23T00:00:00-10:00", "2012-01-06T00:00:00+14:00", 5},
+	} {
+		t.Run(tt.zone, func(t *testing.T) {
+			loc, err := time.LoadLocation(tt.zone)
+			if err != nil {
+				t.Fatal(err)
+			}
+			from, err := time.Parse(time.RFC3339, tt.from)
+			if err != nil {
+				t.Fatal(err)
+			}
+			got := nextWeeklyRenewal(from, tt.weekday, loc).Format(time.RFC3339)
+			if got != tt.want {
+				t.Fatalf("next weekly cutoff = %s, want %s", got, tt.want)
+			}
+		})
+	}
+}

internal/web/service/client_bulk.go

@@ -1303,7 +1303,7 @@ func (s *ClientService) BulkCreate(inboundSvc *InboundService, payloads []Client
 			skip(email, verr.Error())
 			continue
 		}
-		if verr := validateClientResetDay(client.ResetDay); verr != nil {
+		if verr := validateClientRenewal(client); verr != nil {
 			skip(email, verr.Error())
 			continue
 		}

internal/web/service/client_crud.go

@@ -81,6 +81,28 @@ func validateClientResetMax(resetMax int) error {
 	return nil
 }
 
+func validateClientRenewal(client model.Client) error {
+	if err := validateClientResetDay(client.ResetDay); err != nil {
+		return err
+	}
+	if client.ResetWeekday < 0 || client.ResetWeekday > 7 {
+		return common.NewError("client resetWeekday must be between 0 and 7, got:", client.ResetWeekday)
+	}
+	if client.ResetWeekday > 0 && (client.Reset > 0 || client.ResetDay > 0) {
+		return common.NewError("client weekly renewal cannot be combined with reset or resetDay")
+	}
+	return nil
+}
+
+func validateClientsRenewal(clients []model.Client) error {
+	for _, client := range clients {
+		if err := validateClientRenewal(client); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
 // normalizeClientTrafficReset stores what the inbound path would store, so the
 // day never reaches the DB as a 0 that three layers downstream each clamp to 1.
 func normalizeClientTrafficReset(c *model.Client) {
@@ -137,7 +159,7 @@ func (s *ClientService) Create(inboundSvc *InboundService, payload *ClientCreate
 	if err := validateClientSubID(client.SubID); err != nil {
 		return false, err
 	}
-	if err := validateClientResetDay(client.ResetDay); err != nil {
+	if err := validateClientRenewal(client); err != nil {
 		return false, err
 	}
 	if err := validateClientResetMax(client.ResetMax); err != nil {
@@ -591,7 +613,7 @@ func (s *ClientService) Update(inboundSvc *InboundService, id int, updated model
 	if err := validateClientSubID(updated.SubID); err != nil {
 		return false, err
 	}
-	if err := validateClientResetDay(updated.ResetDay); err != nil {
+	if err := validateClientRenewal(updated); err != nil {
 		return false, err
 	}
 	if err := validateClientResetMax(updated.ResetMax); err != nil {
@@ -756,6 +778,7 @@ func (s *ClientService) Update(inboundSvc *InboundService, id int, updated model
 				"comment":           merged.Comment,
 				"reset":             merged.Reset,
 				"reset_day":         merged.ResetDay,
+				"reset_weekday":     merged.ResetWeekday,
 				"reset_max":         merged.ResetMax,
 				"traffic_reset":     merged.TrafficReset,
 				"traffic_reset_day": merged.TrafficResetDay,

internal/web/service/client_inbound_apply.go

@@ -329,6 +329,9 @@ func (s *ClientService) AddInboundClient(inboundSvc *InboundService, data *model
 	if err != nil {
 		return false, err
 	}
+	if err := validateClientsRenewal(clients); err != nil {
+		return false, err
+	}
 
 	var settings map[string]any
 	err = json.Unmarshal([]byte(data.Settings), &settings)
@@ -659,6 +662,9 @@ func (s *ClientService) UpdateInboundClient(inboundSvc *InboundService, data *mo
 	if err != nil {
 		return false, err
 	}
+	if err := validateClientsRenewal(clients); err != nil {
+		return false, err
+	}
 
 	var settings map[string]any
 	err = json.Unmarshal([]byte(data.Settings), &settings)

internal/web/service/client_link.go

@@ -65,6 +65,7 @@ func applyClientRecordMerge(row *model.ClientRecord, incoming *model.ClientRecor
 	row.Comment = incoming.Comment
 	row.Reset = incoming.Reset
 	row.ResetDay = incoming.ResetDay
+	row.ResetWeekday = incoming.ResetWeekday
 	row.ResetMax = incoming.ResetMax
 	// Guarded like Group and AdTag: a node snapshot rebuilt from settings that
 	// predate the cycle would otherwise silently erase it.
@@ -94,6 +95,9 @@ func (s *ClientService) ApplyInboundClientDelta(tx *gorm.DB, inboundId int, chan
 }
 
 func (s *ClientService) syncInboundClients(tx *gorm.DB, inboundId int, clients []model.Client, detachEmails []string, prune bool) error {
+	if err := validateClientsRenewal(clients); err != nil {
+		return err
+	}
 	if tx == nil {
 		tx = database.GetDB()
 	}

internal/web/service/client_paging.go

@@ -18,22 +18,23 @@ import (
 // so the list payload stays compact even when the panel manages thousands
 // of clients. Modals that need the full record still call /get/:email.
 type ClientSlim struct {
-	Email      string              `json:"email" example:"alice@example.com"`
-	SubID      string              `json:"subId" example:"abcd1234"`
-	Enable     bool                `json:"enable" example:"true"`
-	TotalGB    int64               `json:"totalGB" example:"53687091200"`
-	ExpiryTime int64               `json:"expiryTime" example:"1735689600000"`
-	LimitIP    int                 `json:"limitIp" example:"0"`
-	LimitHwid  int                 `json:"limitHwid" example:"0"`
-	Reset      int                 `json:"reset" example:"0"`
-	ResetDay   int                 `json:"resetDay" example:"0"`
-	ResetMax   int                 `json:"resetMax" example:"0"`
-	Group      string              `json:"group,omitempty" example:"staff"`
-	Comment    string              `json:"comment,omitempty" example:"Primary device"`
-	InboundIds []int               `json:"inboundIds" example:"[3,5]"`
-	Traffic    *xray.ClientTraffic `json:"traffic,omitempty"`
-	CreatedAt  int64               `json:"createdAt" example:"1735000000000"`
-	UpdatedAt  int64               `json:"updatedAt" example:"1735100000000"`
+	Email        string              `json:"email" example:"alice@example.com"`
+	SubID        string              `json:"subId" example:"abcd1234"`
+	Enable       bool                `json:"enable" example:"true"`
+	TotalGB      int64               `json:"totalGB" example:"53687091200"`
+	ExpiryTime   int64               `json:"expiryTime" example:"1735689600000"`
+	LimitIP      int                 `json:"limitIp" example:"0"`
+	LimitHwid    int                 `json:"limitHwid" example:"0"`
+	Reset        int                 `json:"reset" example:"0"`
+	ResetDay     int                 `json:"resetDay" example:"0"`
+	ResetWeekday int                 `json:"resetWeekday" example:"0"`
+	ResetMax     int                 `json:"resetMax" example:"0"`
+	Group        string              `json:"group,omitempty" example:"staff"`
+	Comment      string              `json:"comment,omitempty" example:"Primary device"`
+	InboundIds   []int               `json:"inboundIds" example:"[3,5]"`
+	Traffic      *xray.ClientTraffic `json:"traffic,omitempty"`
+	CreatedAt    int64               `json:"createdAt" example:"1735000000000"`
+	UpdatedAt    int64               `json:"updatedAt" example:"1735100000000"`
 }
 
 // ClientPageParams are the query params accepted by /panel/api/clients/list/paged.
@@ -246,9 +247,9 @@ func (q clientQuery) applyParams(tx *gorm.DB, params ClientPageParams, onlines [
 	}
 	switch strings.ToLower(strings.TrimSpace(params.AutoRenew)) {
 	case "on":
-		where("(COALESCE(c.reset, 0) > 0 OR COALESCE(c.reset_day, 0) > 0)")
+		where("(COALESCE(c.reset, 0) > 0 OR COALESCE(c.reset_day, 0) > 0 OR COALESCE(c.reset_weekday, 0) > 0)")
 	case "off":
-		where("(COALESCE(c.reset, 0) <= 0 AND COALESCE(c.reset_day, 0) <= 0)")
+		where("(COALESCE(c.reset, 0) <= 0 AND COALESCE(c.reset_day, 0) <= 0 AND COALESCE(c.reset_weekday, 0) <= 0)")
 	}
 	switch strings.ToLower(strings.TrimSpace(params.HasTgID)) {
 	case "yes":
@@ -598,22 +599,23 @@ func sqlInt(v int64) string {
 
 func toClientSlim(c ClientWithAttachments) ClientSlim {
 	return ClientSlim{
-		Email:      c.Email,
-		SubID:      c.SubID,
-		Enable:     c.Enable,
-		TotalGB:    c.TotalGB,
-		ExpiryTime: c.ExpiryTime,
-		LimitIP:    c.LimitIP,
-		LimitHwid:  c.LimitHwid,
-		Reset:      c.Reset,
-		ResetDay:   c.ResetDay,
-		ResetMax:   c.ResetMax,
-		Group:      c.Group,
-		Comment:    c.Comment,
-		InboundIds: c.InboundIds,
-		Traffic:    c.Traffic,
-		CreatedAt:  c.CreatedAt,
-		UpdatedAt:  c.UpdatedAt,
+		Email:        c.Email,
+		SubID:        c.SubID,
+		Enable:       c.Enable,
+		TotalGB:      c.TotalGB,
+		ExpiryTime:   c.ExpiryTime,
+		LimitIP:      c.LimitIP,
+		LimitHwid:    c.LimitHwid,
+		Reset:        c.Reset,
+		ResetDay:     c.ResetDay,
+		ResetWeekday: c.ResetWeekday,
+		ResetMax:     c.ResetMax,
+		Group:        c.Group,
+		Comment:      c.Comment,
+		InboundIds:   c.InboundIds,
+		Traffic:      c.Traffic,
+		CreatedAt:    c.CreatedAt,
+		UpdatedAt:    c.UpdatedAt,
 	}
 }
 

internal/web/service/client_portable.go

@@ -115,7 +115,7 @@ func (s *ClientService) ImportClients(inboundSvc *InboundService, items []Client
 			skip(email, verr.Error())
 			continue
 		}
-		if verr := validateClientResetDay(client.ResetDay); verr != nil {
+		if verr := validateClientRenewal(client); verr != nil {
 			skip(email, verr.Error())
 			continue
 		}

internal/web/service/client_renewal_preview.go

@@ -0,0 +1,81 @@
+package service
+
+import (
+	"time"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/util/common"
+	"github.com/mhsanaei/3x-ui/v3/internal/xray"
+)
+
+type ClientRenewalPreviewRequest struct {
+	ExpiryTime   int64 `json:"expiryTime" example:"1893456000000"`
+	Reset        int   `json:"reset" example:"0"`
+	ResetDay     int   `json:"resetDay" example:"1"`
+	ResetWeekday int   `json:"resetWeekday" example:"0"`
+	ResetMax     int   `json:"resetMax" example:"0"`
+	ResetCount   int   `json:"resetCount" example:"0"`
+}
+
+type ClientRenewalPreview struct {
+	TimeZone            string `json:"timeZone" example:"UTC"`
+	RenewAt             string `json:"renewAt" example:"2030-01-01T00:00:00Z"`
+	ValidThrough        string `json:"validThrough" example:"2029-12-31T23:59:59Z"`
+	NextExpiry          string `json:"nextExpiry" example:"2030-02-01T00:00:00Z"`
+	SuggestedExpiryTime int64  `json:"suggestedExpiryTime" example:"1893456000000"`
+	SuggestedExpiry     string `json:"suggestedExpiry" example:"2030-01-01T00:00:00Z"`
+	Renewals            int    `json:"renewals" example:"1"`
+	CanRenew            bool   `json:"canRenew" example:"true"`
+	DelayedStart        bool   `json:"delayedStart" example:"false"`
+}
+
+func (s *ClientService) PreviewRenewal(request ClientRenewalPreviewRequest, settings *SettingService) (*ClientRenewalPreview, error) {
+	client := model.Client{Reset: request.Reset, ResetDay: request.ResetDay, ResetWeekday: request.ResetWeekday}
+	if err := validateClientRenewal(client); err != nil {
+		return nil, err
+	}
+	if err := validateClientResetMax(request.ResetMax); err != nil {
+		return nil, err
+	}
+	if request.ResetCount < 0 || request.Reset < 0 {
+		return nil, common.NewError("renewal preview reset and resetCount must not be negative")
+	}
+	loc, err := settings.GetTimeLocation()
+	if err != nil {
+		return nil, err
+	}
+	return previewClientRenewal(request, time.Now().UnixMilli(), loc)
+}
+
+func previewClientRenewal(request ClientRenewalPreviewRequest, now int64, loc *time.Location) (*ClientRenewalPreview, error) {
+	preview := &ClientRenewalPreview{TimeZone: loc.String(), DelayedStart: request.ExpiryTime < 0}
+	if request.ResetDay > 0 || request.ResetWeekday > 0 {
+		preview.SuggestedExpiryTime = nextClientRenewal(now, request.Reset, request.ResetDay, request.ResetWeekday, loc)
+		if preview.SuggestedExpiryTime <= now {
+			return nil, common.NewError("calendar renewal could not find a future expiry")
+		}
+		preview.SuggestedExpiry = time.UnixMilli(preview.SuggestedExpiryTime).In(loc).Format(time.RFC3339)
+	}
+	if request.ExpiryTime <= 0 || (request.Reset <= 0 && request.ResetDay <= 0 && request.ResetWeekday <= 0) {
+		return preview, nil
+	}
+	at := canonicalRenewalExpiry(request.ExpiryTime, request.Reset, request.ResetDay, request.ResetWeekday, loc)
+	preview.RenewAt = time.UnixMilli(at).In(loc).Format(time.RFC3339Nano)
+	// Billing alignment does not rewrite the stored exclusive deadline; the
+	// preview must not promise an extra second before the first renewal.
+	preview.ValidThrough = time.UnixMilli(request.ExpiryTime - 1).In(loc).Format(time.RFC3339)
+	traffic := &xray.ClientTraffic{
+		ExpiryTime: request.ExpiryTime, Reset: request.Reset, ResetDay: request.ResetDay,
+		ResetWeekday: request.ResetWeekday, ResetMax: request.ResetMax, ResetCount: request.ResetCount,
+	}
+	expiry, renewals := catchUpClientRenewal(traffic, max(now, at+1), loc)
+	if renewals == 0 && request.ResetWeekday > 0 && (request.ResetMax == 0 || request.ResetCount < request.ResetMax) {
+		return nil, common.NewError("calendar renewal could not find a future expiry")
+	}
+	preview.Renewals = renewals
+	preview.CanRenew = renewals > 0 && expiry > max(now, at)
+	if renewals > 0 {
+		preview.NextExpiry = time.UnixMilli(expiry).In(loc).Format(time.RFC3339Nano)
+	}
+	return preview, nil
+}

internal/web/service/client_renewal_write_validation_test.go

@@ -0,0 +1,131 @@
+package service
+
+import (
+	"testing"
+	"time"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database"
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/xray"
+)
+
+func TestClientRenewalWriteValidation(t *testing.T) {
+	for _, operation := range []string{"add inbound", "update inbound", "add inbound client", "update inbound client", "sync inbound", "client delta", "add stat", "update stat", "import stat"} {
+		for _, schedule := range []struct {
+			name                string
+			reset, day, weekday int
+			errorMessage        string
+		}{
+			{"weekly and interval", 7, 0, 3, "client weekly renewal cannot be combined with reset or resetDay"},
+			{"weekly and monthly", 0, 1, 3, "client weekly renewal cannot be combined with reset or resetDay"},
+			{"invalid weekday", 0, 0, 8, "client resetWeekday must be between 0 and 7, got: 8"},
+		} {
+			t.Run(operation+"/"+schedule.name, func(t *testing.T) {
+				setupConflictDB(t)
+				nodeID, fake := setupNodeRuntime(t)
+				svc, inboundSvc := &ClientService{}, &InboundService{}
+				client := model.Client{Email: "renewal-boundary", ID: "11111111-1111-1111-1111-111111111111", SubID: "renewal-boundary-sub", Enable: true, ResetWeekday: 3, ResetMax: 4, ExpiryTime: time.Now().Add(time.Hour).UnixMilli()}
+				inbound := nodeInbound(t, nodeID, 41759, []model.Client{client})
+				if err := inboundSvc.AddClientStat(database.GetDB(), inbound.Id, &client); err != nil {
+					t.Fatal(err)
+				}
+				record, err := svc.GetRecordByEmail(nil, client.Email)
+				if err != nil {
+					t.Fatal(err)
+				}
+				beforeRecord := *record
+				beforeTraffic := readTraffic(t, database.GetDB(), client.Email)
+				beforeSettings := inbound.Settings
+				client.Reset, client.ResetDay, client.ResetWeekday = schedule.reset, schedule.day, schedule.weekday
+				update := *inbound
+				update.Settings = clientsSettings(t, []model.Client{client})
+				switch operation {
+				case "add inbound", "import stat":
+					update.Id, update.Port, update.Tag = 0, 41760, "renewal-boundary-new"
+					if operation == "import stat" {
+						update.Settings = beforeSettings
+						update.ClientStats = []xray.ClientTraffic{{Email: "invalid-import-stat", Reset: schedule.reset, ResetDay: schedule.day, ResetWeekday: schedule.weekday}}
+					}
+					_, _, err = inboundSvc.AddInbound(&update)
+				case "update inbound":
+					_, _, err = inboundSvc.UpdateInbound(&update)
+				case "add inbound client":
+					client.Email = "invalid-new-client"
+					update.Settings = clientsSettings(t, []model.Client{client})
+					_, err = svc.AddInboundClient(inboundSvc, &update)
+				case "update inbound client":
+					_, err = svc.UpdateInboundClient(inboundSvc, &update, client.Email)
+				case "sync inbound":
+					err = svc.SyncInbound(nil, inbound.Id, []model.Client{client})
+				case "client delta":
+					err = svc.ApplyInboundClientDelta(nil, inbound.Id, []model.Client{client}, nil)
+				case "add stat":
+					err = inboundSvc.AddClientStat(database.GetDB(), inbound.Id, &client)
+				case "update stat":
+					err = inboundSvc.UpdateClientStat(database.GetDB(), client.Email, &client)
+				}
+				if err == nil || err.Error() != schedule.errorMessage+"\n" {
+					t.Fatalf("write error = %v, want %q", err, schedule.errorMessage)
+				}
+				var persisted model.Inbound
+				if err := database.GetDB().First(&persisted, inbound.Id).Error; err != nil {
+					t.Fatal(err)
+				}
+				if persisted.Settings != beforeSettings {
+					t.Fatal("rejected write changed inbound settings")
+				}
+				record, err = svc.GetRecordByEmail(nil, beforeRecord.Email)
+				if err != nil || *record != beforeRecord || readTraffic(t, database.GetDB(), beforeRecord.Email) != beforeTraffic {
+					t.Fatalf("rejected write changed client/traffic: record=%+v error=%v", record, err)
+				}
+				for _, table := range []string{"inbounds", "clients", "client_traffics"} {
+					var count int64
+					if err := database.GetDB().Table(table).Count(&count).Error; err != nil || count != 1 {
+						t.Fatalf("%s count/error = %d/%v, want 1/nil", table, count, err)
+					}
+				}
+				if fake.addInbound.Load() != 0 || fake.updateInbound.Load() != 0 || fake.delInbound.Load() != 0 || fake.addClient.Load() != 0 || fake.updateUser.Load() != 0 {
+					t.Fatal("rejected write dispatched to the runtime")
+				}
+			})
+		}
+	}
+}
+
+func TestInboundRenewalModesRemainEditable(t *testing.T) {
+	for _, weekly := range []bool{false, true} {
+		name := "legacy monthly with interval"
+		if weekly {
+			name = "weekly"
+		}
+		t.Run(name, func(t *testing.T) {
+			setupConflictDB(t)
+			nodeID, _ := setupNodeRuntime(t)
+			svc, inboundSvc := &ClientService{}, &InboundService{}
+			client := model.Client{Email: "renewal-editable", ID: "11111111-1111-1111-1111-111111111111", Enable: true, Reset: 7, ResetDay: 1, ResetMax: 4, ExpiryTime: time.Now().Add(time.Hour).UnixMilli()}
+			if weekly {
+				client.Reset, client.ResetDay, client.ResetWeekday = 0, 0, 3
+			}
+			inbound := &model.Inbound{Tag: "renewal-editable", NodeID: &nodeID, Port: 41761, Protocol: model.VLESS, Enable: true, Settings: clientsSettings(t, []model.Client{client})}
+			if _, _, err := inboundSvc.AddInbound(inbound); err != nil {
+				t.Fatal(err)
+			}
+			if _, _, err := inboundSvc.UpdateInbound(inbound); err != nil {
+				t.Fatal(err)
+			}
+			record, err := svc.GetRecordByEmail(nil, client.Email)
+			if err != nil {
+				t.Fatal(err)
+			}
+			toggle := *record.ToClient()
+			toggle.Enable = false
+			if _, err := svc.Update(inboundSvc, record.Id, toggle, 0); err != nil {
+				t.Fatalf("valid inbound client could not be toggled: %v", err)
+			}
+			record, err = svc.GetRecordByEmail(nil, client.Email)
+			if err != nil || record.Enable || record.Reset != client.Reset || record.ResetDay != client.ResetDay || record.ResetWeekday != client.ResetWeekday || record.ResetMax != 4 {
+				t.Fatalf("valid schedule/toggle not preserved: %+v/%v", record, err)
+			}
+		})
+	}
+}

internal/web/service/client_weekly_renew_crud_test.go

@@ -0,0 +1,71 @@
+package service
+
+import (
+	"testing"
+	"time"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database"
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+)
+
+func TestClientWeeklyRenewCRUD(t *testing.T) {
+	setupBulkDB(t)
+	svc, inboundSvc := &ClientService{}, &InboundService{}
+	first := mkInbound(t, 41701, model.VLESS, `{"clients":[]}`)
+	second := mkInbound(t, 41702, model.VLESS, `{"clients":[]}`)
+	client := model.Client{
+		Email: "weekly-crud", ID: "11111111-1111-1111-1111-111111111111", Enable: true,
+		ResetWeekday: 7, ResetMax: 3, ExpiryTime: time.Now().Add(-time.Hour).UnixMilli(),
+	}
+	if _, err := svc.Create(inboundSvc, &ClientCreatePayload{Client: client, InboundIds: []int{first.Id, second.Id}}); err != nil {
+		t.Fatal(err)
+	}
+	record, err := svc.GetRecordByEmail(nil, client.Email)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertSchedule := func(want int) {
+		t.Helper()
+		got, err := svc.GetRecordByEmail(nil, client.Email)
+		if err != nil || got.ResetWeekday != want || got.ToClient().ResetWeekday != want {
+			t.Fatalf("record schedule/error = %+v/%v, want %d", got, err, want)
+		}
+		traffic := readTraffic(t, database.GetDB(), client.Email)
+		if traffic.ResetWeekday != want || traffic.ResetMax != 3 {
+			t.Fatalf("traffic policy = %+v, want weekday %d and cap 3", traffic, want)
+		}
+		for _, id := range []int{first.Id, second.Id} {
+			var inbound model.Inbound
+			if err := database.GetDB().First(&inbound, id).Error; err != nil {
+				t.Fatal(err)
+			}
+			clients, err := inboundSvc.GetClients(&inbound)
+			if err != nil || len(clients) != 1 || clients[0].ResetWeekday != want {
+				t.Fatalf("inbound %d schedule/error = %+v/%v, want %d", id, clients, err, want)
+			}
+		}
+		filter := "on"
+		if want == 0 {
+			filter = "off"
+		}
+		page, err := svc.ListPaged(inboundSvc, nil, ClientPageParams{AutoRenew: filter})
+		if err != nil || len(page.Items) != 1 || page.Items[0].ResetWeekday != want {
+			t.Fatalf("renewal filter/projection = %+v/%v, want weekday %d", page, err, want)
+		}
+	}
+	assertSchedule(7)
+	if deleted, _, err := svc.DelDepleted(inboundSvc); err != nil || deleted != 0 {
+		t.Fatalf("expired weekly client was purged: deleted/error = %d/%v", deleted, err)
+	}
+	for _, weekday := range []int{2, 0} {
+		updated := *record.ToClient()
+		updated.ResetWeekday = weekday
+		if _, err := svc.Update(inboundSvc, record.Id, updated, 0); err != nil {
+			t.Fatal(err)
+		}
+		assertSchedule(weekday)
+	}
+	if deleted, _, err := svc.DelDepleted(inboundSvc); err != nil || deleted != 1 {
+		t.Fatalf("non-renewing expired client was not purged: deleted/error = %d/%v", deleted, err)
+	}
+}

internal/web/service/inbound.go

@@ -1133,6 +1133,14 @@ func (s *InboundService) AddInbound(inbound *model.Inbound) (*model.Inbound, boo
 	if err != nil {
 		return inbound, false, err
 	}
+	if err := validateClientsRenewal(clients); err != nil {
+		return inbound, false, err
+	}
+	for _, traffic := range inbound.ClientStats {
+		if err := validateClientRenewal(model.Client{Reset: traffic.Reset, ResetDay: traffic.ResetDay, ResetWeekday: traffic.ResetWeekday}); err != nil {
+			return inbound, false, err
+		}
+	}
 	existEmail, err := s.clientService.checkEmailsExistForClients(s, clients)
 	if err != nil {
 		return inbound, false, err
@@ -1702,6 +1710,9 @@ func (s *InboundService) UpdateInbound(inbound *model.Inbound) (*model.Inbound,
 	if err != nil {
 		return inbound, false, err
 	}
+	if err := validateClientsRenewal(clients); err != nil {
+		return inbound, false, err
+	}
 	if inbound.Protocol == model.Hysteria {
 		for _, client := range clients {
 			if client.Auth == "" {

internal/web/service/inbound_autorenew_weekly_test.go

@@ -0,0 +1,95 @@
+package service
+
+import (
+	"testing"
+	"time"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database"
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/xray"
+)
+
+func TestAutoRenewClients_WeeklyMode(t *testing.T) {
+	for _, tt := range []struct {
+		name, zone          string
+		weekday, max, count int
+		inclusive, manual   bool
+	}{
+		{name: "UTC Monday catch-up across shared inbounds", zone: "UTC", weekday: 1},
+		{name: "New York Sunday across daylight saving", zone: "America/New_York", weekday: 7},
+		{name: "capped catch-up stays expired", zone: "UTC", weekday: 3, max: 3, count: 2},
+		{name: "inclusive last second spends one allowance", zone: "Asia/Taipei", weekday: 1, max: 1, inclusive: true},
+		{name: "operator-disabled settings stay disabled", zone: "UTC", weekday: 5, manual: true},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			setupBulkDB(t)
+			db := database.GetDB()
+			zone := pinPanelZone(t, tt.zone)
+			now := time.Now().In(zone)
+			boundary := time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, zone)
+			for int(boundary.Weekday()+6)%7+1 != tt.weekday || !boundary.Before(now) {
+				boundary = boundary.AddDate(0, 0, -1)
+			}
+			past := boundary.AddDate(0, 0, -21)
+			if tt.zone == "America/New_York" {
+				past = time.Date(2026, time.March, 1, 0, 0, 0, 0, zone)
+			}
+			if tt.inclusive {
+				past = boundary.Add(-time.Second)
+			}
+			client := model.Client{
+				Email: "weekly@x", ID: "11111111-1111-1111-1111-111111111111",
+				ResetWeekday: tt.weekday, ResetMax: tt.max, ExpiryTime: past.UnixMilli(),
+			}
+			svc := &InboundService{}
+			for _, port := range []int{30241, 30242} {
+				ib := mkInbound(t, port, model.VLESS, clientsSettings(t, []model.Client{client}))
+				if err := svc.clientService.SyncInbound(nil, ib.Id, []model.Client{client}); err != nil {
+					t.Fatal(err)
+				}
+			}
+			traffic := xray.ClientTraffic{
+				Email: client.Email, ResetWeekday: tt.weekday, ResetMax: tt.max, ResetCount: tt.count,
+				ExpiryTime: past.UnixMilli(), Up: 111, Down: 222, Enable: tt.manual,
+			}
+			if err := db.Create(&traffic).Error; err != nil {
+				t.Fatal(err)
+			}
+			want, steps := past, 0
+			if tt.inclusive {
+				want = boundary
+			}
+			for !want.After(now) && (tt.max == 0 || tt.count+steps < tt.max) {
+				want = want.AddDate(0, 0, 7)
+				steps++
+			}
+			if _, _, err := svc.autoRenewClients(db, newTrafficMutationBatch()); err != nil {
+				t.Fatal(err)
+			}
+			var got xray.ClientTraffic
+			if err := db.Where("email = ?", client.Email).First(&got).Error; err != nil {
+				t.Fatal(err)
+			}
+			if got.ExpiryTime != want.UnixMilli() || got.ResetCount != tt.count+steps || got.ResetWeekday != tt.weekday {
+				t.Fatalf("expiry/count/weekday = %d/%d/%d, want %d/%d/%d", got.ExpiryTime, got.ResetCount, got.ResetWeekday, want.UnixMilli(), tt.count+steps, tt.weekday)
+			}
+			if want.After(now) {
+				if !got.Enable || got.Up != 0 || got.Down != 0 {
+					t.Fatalf("renewed enable/up/down = %v/%d/%d, want true/0/0", got.Enable, got.Up, got.Down)
+				}
+			} else if got.Enable || got.Up != 111 || got.Down != 222 {
+				t.Fatalf("capped enable/up/down = %v/%d/%d, want false/111/222", got.Enable, got.Up, got.Down)
+			}
+			var record model.ClientRecord
+			if err := db.Where("email = ?", client.Email).First(&record).Error; err != nil {
+				t.Fatal(err)
+			}
+			if record.ResetWeekday != tt.weekday || record.ExpiryTime != got.ExpiryTime || record.Enable != (want.After(now) && !tt.manual) {
+				t.Fatalf("client record lost weekly schedule or operator enable state: %+v", record)
+			}
+			if _, count, err := svc.autoRenewClients(db, newTrafficMutationBatch()); err != nil || count != 0 {
+				t.Fatalf("repeat tick count/error = %d/%v, want 0/nil", count, err)
+			}
+		})
+	}
+}

internal/web/service/inbound_node.go

@@ -290,7 +290,7 @@ func applyMasterClientLifecycle(c *model.Client, master *xray.ClientTraffic, cs
 // nodeClientRenewed reports a node-side auto-renew: an absolute deadline moved
 // forward, evidenced by a renewal-count bump or a drop below the stored baseline.
 func nodeClientRenewed(existing *xray.ClientTraffic, cs xray.ClientTraffic, canon, base nodeTrafficCounter) bool {
-	if (cs.Reset <= 0 && cs.ResetDay <= 0) || cs.ExpiryTime <= 0 || existing.ExpiryTime <= 0 {
+	if (cs.Reset <= 0 && cs.ResetDay <= 0 && cs.ResetWeekday <= 0) || cs.ExpiryTime <= 0 || existing.ExpiryTime <= 0 {
 		return false
 	}
 	if cs.ExpiryTime <= existing.ExpiryTime {
@@ -952,16 +952,19 @@ func (s *InboundService) setRemoteTrafficLocked(nodeID int, snap *runtime.Traffi
 					seedUp, seedDown = canon.Up, canon.Down
 				}
 				row := &xray.ClientTraffic{
-					InboundId:  c.Id,
-					Email:      cs.Email,
-					Enable:     cs.Enable,
-					Total:      cs.Total,
-					ExpiryTime: cs.ExpiryTime,
-					Reset:      cs.Reset,
-					ResetDay:   cs.ResetDay,
-					Up:         seedUp,
-					Down:       seedDown,
-					LastOnline: cs.LastOnline,
+					InboundId:    c.Id,
+					Email:        cs.Email,
+					Enable:       cs.Enable,
+					Total:        cs.Total,
+					ExpiryTime:   cs.ExpiryTime,
+					Reset:        cs.Reset,
+					ResetDay:     cs.ResetDay,
+					ResetWeekday: cs.ResetWeekday,
+					ResetMax:     cs.ResetMax,
+					ResetCount:   cs.ResetCount,
+					Up:           seedUp,
+					Down:         seedDown,
+					LastOnline:   cs.LastOnline,
 				}
 				if err := tx.Clauses(clause.OnConflict{Columns: []clause.Column{{Name: "email"}}, DoNothing: true}).
 					Create(row).Error; err != nil {
@@ -985,7 +988,7 @@ func (s *InboundService) setRemoteTrafficLocked(nodeID int, snap *runtime.Traffi
 				// re-enables from the node.
 				enableChanged := !lifecycleFrozen && existing.Enable && !cs.Enable &&
 					!nodeDisableIsStale(existing, cs, now, deltaUp, deltaDown)
-				metaChanged := !lifecycleFrozen && (existing.Total != cs.Total || existing.Reset != cs.Reset)
+				metaChanged := !lifecycleFrozen && (existing.Total != cs.Total || existing.Reset != cs.Reset || existing.ResetWeekday != cs.ResetWeekday)
 				if enableChanged || metaChanged || expiryChanged {
 					structuralChange = true
 				}
@@ -1009,12 +1012,12 @@ func (s *InboundService) setRemoteTrafficLocked(nodeID int, snap *runtime.Traffi
 					fmt.Sprintf(
 						`UPDATE client_traffics
 						 SET up = ?, down = ?, enable = ?, total = ?,
-						     expiry_time = ?, reset = ?, reset_day = ?, reset_count = ?, last_online = %s
+						     expiry_time = ?, reset = ?, reset_day = ?, reset_weekday = ?, reset_count = ?, last_online = %s
 						 WHERE email = ?`,
 						database.GreatestExpr("last_online", "?"),
 					),
 					canon.Up, canon.Down, cs.Enable, cs.Total,
-					cs.ExpiryTime, cs.Reset, cs.ResetDay, cs.ResetCount,
+					cs.ExpiryTime, cs.Reset, cs.ResetDay, cs.ResetWeekday, cs.ResetCount,
 					cs.LastOnline, cs.Email,
 				).Error; err != nil {
 					return false, err
@@ -1028,6 +1031,7 @@ func (s *InboundService) setRemoteTrafficLocked(nodeID int, snap *runtime.Traffi
 				existing.Total = cs.Total
 				existing.ExpiryTime = cs.ExpiryTime
 				existing.Reset = cs.Reset
+				existing.ResetWeekday = cs.ResetWeekday
 				existing.ResetCount = cs.ResetCount
 				structuralChange = true
 			} else if lifecycleFrozen {
@@ -1058,7 +1062,7 @@ func (s *InboundService) setRemoteTrafficLocked(nodeID int, snap *runtime.Traffi
 						`UPDATE client_traffics
 						 SET up = %s, down = %s, enable = %s, total = ?,
 						     expiry_time = %s,
-						     reset = ?, reset_day = ?, last_online = %s
+						     reset = ?, reset_day = ?, reset_weekday = ?, last_online = %s
 						 WHERE email = ?`,
 						database.ClampedAddExpr("up"),
 						database.ClampedAddExpr("down"),
@@ -1069,7 +1073,7 @@ func (s *InboundService) setRemoteTrafficLocked(nodeID int, snap *runtime.Traffi
 					deltaUp, deltaDown,
 					cs.Enable, cs.ExpiryTime, cs.Total, now, deltaUp, deltaDown,
 					cs.Total,
-					cs.ExpiryTime, cs.Reset, cs.ResetDay,
+					cs.ExpiryTime, cs.Reset, cs.ResetDay, cs.ResetWeekday,
 					cs.LastOnline, cs.Email,
 				).Error; err != nil {
 					return false, err
@@ -1084,6 +1088,7 @@ func (s *InboundService) setRemoteTrafficLocked(nodeID int, snap *runtime.Traffi
 					existing.Down = clampTrafficCounter(existing.Down + deltaDown)
 					existing.Total = cs.Total
 					existing.Reset = cs.Reset
+					existing.ResetWeekday = cs.ResetWeekday
 				}
 			}
 			// A dip plus a lagging longer expiry mimics nodeClientRenewed and would

internal/web/service/inbound_traffic.go

@@ -23,7 +23,7 @@ import (
 
 // A client with a renewal day set auto-renews too, so it must not read as
 // depleted — otherwise the operator's purge deletes it between cycles (#6239).
-const depletedClientsClause = "reset = 0 and reset_day = 0 and ((total > 0 and up + down >= total) or (expiry_time > 0 and expiry_time <= ?))"
+const depletedClientsClause = "reset = 0 and reset_day = 0 and reset_weekday = 0 and ((total > 0 and up + down >= total) or (expiry_time > 0 and expiry_time <= ?))"
 
 func (s *InboundService) AddTraffic(inboundTraffics []*xray.Traffic, clientTraffics []*xray.ClientTraffic) (needRestart bool, clientsDisabled bool, err error) {
 	var disabledNodeIDs []int
@@ -345,7 +345,7 @@ func (s *InboundService) autoRenewClients(tx *gorm.DB, mutationBatch *trafficMut
 	// attached to, so it could be a node inbound even when the client also has
 	// local inbounds. The email-based join through client_inbounds is authoritative.
 	err = tx.Model(xray.ClientTraffic{}).
-		Where("(reset > 0 or reset_day > 0) and expiry_time > 0 and expiry_time <= ?", now).
+		Where("(reset > 0 or reset_day > 0 or reset_weekday > 0) and expiry_time > 0 and expiry_time <= ?", now).
 		// A prepaid plan stops itself: once as many renewals have fired as the
 		// operator allowed, the client is left to expire like any other.
 		Where("reset_max <= 0 or reset_count < reset_max").
@@ -447,37 +447,7 @@ func (s *InboundService) autoRenewClients(tx *gorm.DB, mutationBatch *trafficMut
 			}
 			// One allowance per period, not per tick: a client away for three
 			// cycles must not catch up three of them against a prepaid cap.
-			newExpiryTime := traffic.ExpiryTime
-			if traffic.ResetDay <= 0 && traffic.Reset <= 0 {
-				// Unreachable while the selection filter holds: a zero step below
-				// would spin forever on the single traffic writer and hang the panel.
-				continue
-			}
-			at := time.UnixMilli(newExpiryTime)
-			// Inclusive end-of-day expiries share the next billing midnight; snap without
-			// spending an allowance so the first charged step is a full month (#6300).
-			if traffic.ResetDay > 0 {
-				boundary := nextCalendarRenewal(at, traffic.ResetDay, renewLocation)
-				if !at.Before(boundary.Add(-time.Second)) && at.Before(boundary) {
-					at = boundary
-					newExpiryTime = at.UnixMilli()
-				}
-			}
-			renewals := 0
-			for newExpiryTime < now {
-				if traffic.ResetMax > 0 && traffic.ResetCount+renewals >= traffic.ResetMax {
-					break
-				}
-				if traffic.ResetDay > 0 {
-					// Calendar mode: step whole months in the panel's zone, so the
-					// renewal date does not drift the way a fixed 30-day step does.
-					at = nextCalendarRenewal(at, traffic.ResetDay, renewLocation)
-					newExpiryTime = at.UnixMilli()
-				} else {
-					newExpiryTime += (int64(traffic.Reset) * 86400000)
-				}
-				renewals++
-			}
+			newExpiryTime, renewals := catchUpClientRenewal(traffic, now, renewLocation)
 			if renewals > 0 {
 				traffic.ExpiryTime = newExpiryTime
 				traffic.ResetCount += renewals
@@ -580,33 +550,41 @@ func (s *InboundService) autoRenewClients(tx *gorm.DB, mutationBatch *trafficMut
 // happens to reuse an orphaned email still inherits that row's leftover
 // up/down, since nothing at this call site can tell the two cases apart.
 func (s *InboundService) AddClientStat(tx *gorm.DB, inboundId int, client *model.Client) error {
+	if err := validateClientRenewal(*client); err != nil {
+		return err
+	}
 	clientTraffic := xray.ClientTraffic{
-		InboundId:  inboundId,
-		Email:      client.Email,
-		Total:      client.TotalGB,
-		ExpiryTime: client.ExpiryTime,
-		Enable:     client.Enable,
-		Reset:      client.Reset,
-		ResetDay:   client.ResetDay,
-		ResetMax:   client.ResetMax,
+		InboundId:    inboundId,
+		Email:        client.Email,
+		Total:        client.TotalGB,
+		ExpiryTime:   client.ExpiryTime,
+		Enable:       client.Enable,
+		Reset:        client.Reset,
+		ResetDay:     client.ResetDay,
+		ResetWeekday: client.ResetWeekday,
+		ResetMax:     client.ResetMax,
 	}
 	return tx.Clauses(clause.OnConflict{
 		Columns:   []clause.Column{{Name: "email"}},
-		DoUpdates: clause.AssignmentColumns([]string{"inbound_id", "total", "expiry_time", "enable", "reset", "reset_day", "reset_max"}),
+		DoUpdates: clause.AssignmentColumns([]string{"inbound_id", "total", "expiry_time", "enable", "reset", "reset_day", "reset_weekday", "reset_max"}),
 	}).Create(&clientTraffic).Error
 }
 
 func (s *InboundService) UpdateClientStat(tx *gorm.DB, email string, client *model.Client) error {
+	if err := validateClientRenewal(*client); err != nil {
+		return err
+	}
 	result := tx.Model(xray.ClientTraffic{}).
 		Where("email = ?", email).
 		Updates(map[string]any{
-			"enable":      client.Enable,
-			"email":       client.Email,
-			"total":       client.TotalGB,
-			"expiry_time": client.ExpiryTime,
-			"reset":       client.Reset,
-			"reset_day":   client.ResetDay,
-			"reset_max":   client.ResetMax,
+			"enable":        client.Enable,
+			"email":         client.Email,
+			"total":         client.TotalGB,
+			"expiry_time":   client.ExpiryTime,
+			"reset":         client.Reset,
+			"reset_day":     client.ResetDay,
+			"reset_weekday": client.ResetWeekday,
+			"reset_max":     client.ResetMax,
 		})
 	err := result.Error
 	return err

internal/web/service/node_client_weekly_renew_test.go

@@ -0,0 +1,53 @@
+package service
+
+import (
+	"testing"
+	"time"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/xray"
+)
+
+func TestNodeWeeklyRenew_AdoptsNewPeriod(t *testing.T) {
+	db := initTrafficTestDB(t)
+	createNodeInbound(t, db, 1, "n1-weekly", 41011)
+	svc := &InboundService{}
+	first := time.Date(2030, time.January, 7, 0, 0, 0, 0, time.UTC).UnixMilli()
+	second := first + 7*86400000
+	client := model.Client{Email: "node-weekly", ID: "11111111-1111-1111-1111-111111111111", Enable: true, ResetWeekday: 1, ResetMax: 4, ExpiryTime: first}
+	stats := xray.ClientTraffic{Email: client.Email, Enable: true, ResetWeekday: 1, ResetMax: 4, ResetCount: 2, ExpiryTime: first}
+	syncNodeWithSettings(t, svc, 1, "n1-weekly", clientsSettings(t, []model.Client{client}), stats)
+	seeded := readTraffic(t, db, client.Email)
+	if seeded.ResetMax != 4 || seeded.ResetCount != 2 || seeded.ResetWeekday != 1 {
+		t.Fatalf("node adoption lost renewal policy: %+v", seeded)
+	}
+	stats.Up, stats.Down = 500, 100
+	syncNodeWithSettings(t, svc, 1, "n1-weekly", clientsSettings(t, []model.Client{client}), stats)
+	if err := db.Model(&xray.ClientTraffic{}).Where("email = ?", client.Email).Update("enable", false).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Create(&model.ClientGlobalTraffic{MasterGuid: "other", Email: client.Email, Up: 90}).Error; err != nil {
+		t.Fatal(err)
+	}
+	client.ExpiryTime, stats.ExpiryTime = second, second
+	stats.Up, stats.Down, stats.ResetCount = 0, 0, 3
+	syncNodeWithSettings(t, svc, 1, "n1-weekly", clientsSettings(t, []model.Client{client}), stats)
+	got := readTraffic(t, db, client.Email)
+	if got.ExpiryTime != second || got.ResetCount != 3 || got.ResetMax != 4 || got.ResetWeekday != 1 || !got.Enable || got.Up != 0 || got.Down != 0 {
+		t.Fatalf("node weekly renewal was not adopted: %+v", got)
+	}
+	var count int64
+	if err := db.Model(&model.ClientGlobalTraffic{}).Where("email = ?", client.Email).Count(&count).Error; err != nil || count != 0 {
+		t.Fatalf("stale global traffic count/error = %d/%v, want 0/nil", count, err)
+	}
+	var record model.ClientRecord
+	if err := db.Where("email = ?", client.Email).First(&record).Error; err != nil {
+		t.Fatal(err)
+	}
+	if record.ResetWeekday != 1 || record.ExpiryTime != second {
+		t.Fatalf("node weekly client record lost schedule: %+v", record)
+	}
+	stats.Up, stats.Down = 20, 8
+	syncNodeWithSettings(t, svc, 1, "n1-weekly", clientsSettings(t, []model.Client{client}), stats)
+	assertUpDown(t, readTraffic(t, db, client.Email), 20, 8, "new weekly period")
+}

internal/web/translation/ar-EG.json

@@ -943,6 +943,23 @@
       },
       "renewMax": "الحد الأقصى للتجديدات",
       "renewMaxDesc": "عدد المرات التي يمكن أن يعمل فيها التجديد التلقائي قبل ترك العميل ينتهي. القيمة 0 تعني بلا حد. تعويض عدة فترات فائتة يستهلك تجديدًا واحدًا لكل فترة.",
+      "renewMode": "Auto renewal",
+      "renewModeNone": "Disabled",
+      "renewModeInterval": "Fixed interval (days)",
+      "renewModeWeekly": "Calendar weekly",
+      "renewModeMonthly": "Calendar monthly",
+      "renewWeekday": "Renew on weekday",
+      "renewScheduleDesc": "Calendar renewal uses midnight in the panel timezone and also resets the client's traffic. Keep independent traffic resets disabled unless an additional reset is intended. Monthly day 1 means valid through the preceding month; day 31 is not the same boundary.",
+      "renewPreview": "Renewal preview ({zone})",
+      "renewAt": "Renewal boundary",
+      "renewValidThrough": "Valid through",
+      "renewNextExpiry": "Cutoff after renewal",
+      "renewPeriods": "Periods charged: {count}",
+      "renewUnavailable": "The remaining renewal allowances cannot provide a future cutoff.",
+      "renewFirstUse": "Dates are available after first-use activation. The initial duration is unchanged.",
+      "renewSetExpiry": "Set first cycle cutoff",
+      "renewNeedsExpiry": "An expiry must be set before auto-renewal can run.",
+      "renewPreviewError": "Could not preview renewal dates.",
       "renewOnDay": "يوم التجديد",
       "renewOnDayDesc": "يتم التجديد في هذا اليوم من كل شهر ميلادي، عند منتصف الليل بتوقيت اللوحة، بدلاً من كل N يوم. إذا كان الشهر أقصر من اليوم المختار، يتم التجديد في آخر يوم منه. القيمة 0 تُبقي وضع الفاصل اليومي.",
       "renewsUsed": "التجديدات المستخدمة",

internal/web/translation/en-US.json

@@ -943,6 +943,23 @@
       },
       "renewMax": "Max renewals",
       "renewMaxDesc": "How many times auto-renew may fire before the client is left to expire. 0 means no limit. Catching up several missed periods spends one renewal per period.",
+      "renewMode": "Auto renewal",
+      "renewModeNone": "Disabled",
+      "renewModeInterval": "Fixed interval (days)",
+      "renewModeWeekly": "Calendar weekly",
+      "renewModeMonthly": "Calendar monthly",
+      "renewWeekday": "Renew on weekday",
+      "renewScheduleDesc": "Calendar renewal uses midnight in the panel timezone and also resets the client's traffic. Keep independent traffic resets disabled unless an additional reset is intended. Monthly day 1 means valid through the preceding month; day 31 is not the same boundary.",
+      "renewPreview": "Renewal preview ({zone})",
+      "renewAt": "Renewal boundary",
+      "renewValidThrough": "Valid through",
+      "renewNextExpiry": "Cutoff after renewal",
+      "renewPeriods": "Periods charged: {count}",
+      "renewUnavailable": "The remaining renewal allowances cannot provide a future cutoff.",
+      "renewFirstUse": "Dates are available after first-use activation. The initial duration is unchanged.",
+      "renewSetExpiry": "Set first cycle cutoff",
+      "renewNeedsExpiry": "An expiry must be set before auto-renewal can run.",
+      "renewPreviewError": "Could not preview renewal dates.",
       "renewOnDay": "Renew on day",
       "renewOnDayDesc": "Renew on this day of every calendar month, at midnight in the panel's time zone, instead of every N days. A month too short for the chosen day renews on its last day. 0 keeps the day-interval mode.",
       "renewsUsed": "Renewals used",

internal/web/translation/es-ES.json

@@ -943,6 +943,23 @@
       },
       "renewMax": "Renovaciones máximas",
       "renewMaxDesc": "Cuántas veces puede activarse la renovación automática antes de dejar que el cliente caduque. 0 significa sin límite. Recuperar varios periodos perdidos consume una renovación por periodo.",
+      "renewMode": "Auto renewal",
+      "renewModeNone": "Disabled",
+      "renewModeInterval": "Fixed interval (days)",
+      "renewModeWeekly": "Calendar weekly",
+      "renewModeMonthly": "Calendar monthly",
+      "renewWeekday": "Renew on weekday",
+      "renewScheduleDesc": "Calendar renewal uses midnight in the panel timezone and also resets the client's traffic. Keep independent traffic resets disabled unless an additional reset is intended. Monthly day 1 means valid through the preceding month; day 31 is not the same boundary.",
+      "renewPreview": "Renewal preview ({zone})",
+      "renewAt": "Renewal boundary",
+      "renewValidThrough": "Valid through",
+      "renewNextExpiry": "Cutoff after renewal",
+      "renewPeriods": "Periods charged: {count}",
+      "renewUnavailable": "The remaining renewal allowances cannot provide a future cutoff.",
+      "renewFirstUse": "Dates are available after first-use activation. The initial duration is unchanged.",
+      "renewSetExpiry": "Set first cycle cutoff",
+      "renewNeedsExpiry": "An expiry must be set before auto-renewal can run.",
+      "renewPreviewError": "Could not preview renewal dates.",
       "renewOnDay": "Renovar el día",
       "renewOnDayDesc": "Renueva este día de cada mes natural, a medianoche en la zona horaria del panel, en lugar de cada N días. Si el mes es demasiado corto para el día elegido, renueva su último día. 0 mantiene el modo de intervalo en días.",
       "renewsUsed": "Renovaciones usadas",

internal/web/translation/fa-IR.json

@@ -943,6 +943,23 @@
       },
       "renewMax": "حداکثر تعداد تمدید",
       "renewMaxDesc": "تمدید خودکار حداکثر چند بار اجرا شود پیش از آنکه کلاینت منقضی بماند. مقدار ۰ یعنی بدون محدودیت. جبران چند دورهٔ ازدست‌رفته، برای هر دوره یک تمدید مصرف می‌کند.",
+      "renewMode": "Auto renewal",
+      "renewModeNone": "Disabled",
+      "renewModeInterval": "Fixed interval (days)",
+      "renewModeWeekly": "Calendar weekly",
+      "renewModeMonthly": "Calendar monthly",
+      "renewWeekday": "Renew on weekday",
+      "renewScheduleDesc": "Calendar renewal uses midnight in the panel timezone and also resets the client's traffic. Keep independent traffic resets disabled unless an additional reset is intended. Monthly day 1 means valid through the preceding month; day 31 is not the same boundary.",
+      "renewPreview": "Renewal preview ({zone})",
+      "renewAt": "Renewal boundary",
+      "renewValidThrough": "Valid through",
+      "renewNextExpiry": "Cutoff after renewal",
+      "renewPeriods": "Periods charged: {count}",
+      "renewUnavailable": "The remaining renewal allowances cannot provide a future cutoff.",
+      "renewFirstUse": "Dates are available after first-use activation. The initial duration is unchanged.",
+      "renewSetExpiry": "Set first cycle cutoff",
+      "renewNeedsExpiry": "An expiry must be set before auto-renewal can run.",
+      "renewPreviewError": "Could not preview renewal dates.",
       "renewOnDay": "روز تمدید",
       "renewOnDayDesc": "در این روز از هر ماه تقویمی، در نیمه‌شب به وقت پنل تمدید می‌شود، به جای هر N روز. اگر ماه کوتاه‌تر از روز انتخابی باشد، در آخرین روز آن ماه تمدید می‌شود. مقدار ۰ حالت بازهٔ روزانه را حفظ می‌کند.",
       "renewsUsed": "تمدیدهای استفاده‌شده",

internal/web/translation/id-ID.json

@@ -943,6 +943,23 @@
       },
       "renewMax": "Maksimum perpanjangan",
       "renewMaxDesc": "Berapa kali perpanjangan otomatis boleh berjalan sebelum klien dibiarkan kedaluwarsa. 0 berarti tanpa batas. Mengejar beberapa periode yang terlewat menghabiskan satu perpanjangan per periode.",
+      "renewMode": "Auto renewal",
+      "renewModeNone": "Disabled",
+      "renewModeInterval": "Fixed interval (days)",
+      "renewModeWeekly": "Calendar weekly",
+      "renewModeMonthly": "Calendar monthly",
+      "renewWeekday": "Renew on weekday",
+      "renewScheduleDesc": "Calendar renewal uses midnight in the panel timezone and also resets the client's traffic. Keep independent traffic resets disabled unless an additional reset is intended. Monthly day 1 means valid through the preceding month; day 31 is not the same boundary.",
+      "renewPreview": "Renewal preview ({zone})",
+      "renewAt": "Renewal boundary",
+      "renewValidThrough": "Valid through",
+      "renewNextExpiry": "Cutoff after renewal",
+      "renewPeriods": "Periods charged: {count}",
+      "renewUnavailable": "The remaining renewal allowances cannot provide a future cutoff.",
+      "renewFirstUse": "Dates are available after first-use activation. The initial duration is unchanged.",
+      "renewSetExpiry": "Set first cycle cutoff",
+      "renewNeedsExpiry": "An expiry must be set before auto-renewal can run.",
+      "renewPreviewError": "Could not preview renewal dates.",
       "renewOnDay": "Perpanjang pada tanggal",
       "renewOnDayDesc": "Perpanjang pada tanggal ini setiap bulan kalender, pada tengah malam menurut zona waktu panel, alih-alih setiap N hari. Bulan yang terlalu pendek untuk tanggal yang dipilih diperpanjang pada hari terakhirnya. 0 mempertahankan mode interval hari.",
       "renewsUsed": "Perpanjangan terpakai",

internal/web/translation/ja-JP.json

@@ -943,6 +943,23 @@
       },
       "renewMax": "最大更新回数",
       "renewMaxDesc": "自動更新が実行される最大回数です。これを超えるとクライアントはそのまま失効します。0 は無制限。複数の未処理期間をまとめて処理する場合、1 期間につき 1 回消費します。",
+      "renewMode": "Auto renewal",
+      "renewModeNone": "Disabled",
+      "renewModeInterval": "Fixed interval (days)",
+      "renewModeWeekly": "Calendar weekly",
+      "renewModeMonthly": "Calendar monthly",
+      "renewWeekday": "Renew on weekday",
+      "renewScheduleDesc": "Calendar renewal uses midnight in the panel timezone and also resets the client's traffic. Keep independent traffic resets disabled unless an additional reset is intended. Monthly day 1 means valid through the preceding month; day 31 is not the same boundary.",
+      "renewPreview": "Renewal preview ({zone})",
+      "renewAt": "Renewal boundary",
+      "renewValidThrough": "Valid through",
+      "renewNextExpiry": "Cutoff after renewal",
+      "renewPeriods": "Periods charged: {count}",
+      "renewUnavailable": "The remaining renewal allowances cannot provide a future cutoff.",
+      "renewFirstUse": "Dates are available after first-use activation. The initial duration is unchanged.",
+      "renewSetExpiry": "Set first cycle cutoff",
+      "renewNeedsExpiry": "An expiry must be set before auto-renewal can run.",
+      "renewPreviewError": "Could not preview renewal dates.",
       "renewOnDay": "更新する日",
       "renewOnDayDesc": "毎月この日の深夜（パネルのタイムゾーン基準）に更新します。N 日ごとの更新の代わりになります。その日が存在しない月は月末に更新されます。0 で日数間隔モードのままになります。",
       "renewsUsed": "使用済み更新回数",

internal/web/translation/pt-BR.json

@@ -943,6 +943,23 @@
       },
       "renewMax": "Renovações máximas",
       "renewMaxDesc": "Quantas vezes a renovação automática pode ocorrer antes de o cliente ser deixado a expirar. 0 significa sem limite. Recuperar vários períodos perdidos consome uma renovação por período.",
+      "renewMode": "Auto renewal",
+      "renewModeNone": "Disabled",
+      "renewModeInterval": "Fixed interval (days)",
+      "renewModeWeekly": "Calendar weekly",
+      "renewModeMonthly": "Calendar monthly",
+      "renewWeekday": "Renew on weekday",
+      "renewScheduleDesc": "Calendar renewal uses midnight in the panel timezone and also resets the client's traffic. Keep independent traffic resets disabled unless an additional reset is intended. Monthly day 1 means valid through the preceding month; day 31 is not the same boundary.",
+      "renewPreview": "Renewal preview ({zone})",
+      "renewAt": "Renewal boundary",
+      "renewValidThrough": "Valid through",
+      "renewNextExpiry": "Cutoff after renewal",
+      "renewPeriods": "Periods charged: {count}",
+      "renewUnavailable": "The remaining renewal allowances cannot provide a future cutoff.",
+      "renewFirstUse": "Dates are available after first-use activation. The initial duration is unchanged.",
+      "renewSetExpiry": "Set first cycle cutoff",
+      "renewNeedsExpiry": "An expiry must be set before auto-renewal can run.",
+      "renewPreviewError": "Could not preview renewal dates.",
       "renewOnDay": "Renovar no dia",
       "renewOnDayDesc": "Renova neste dia de cada mês do calendário, à meia-noite no fuso horário do painel, em vez de a cada N dias. Se o mês for curto demais para o dia escolhido, renova no último dia dele. 0 mantém o modo de intervalo em dias.",
       "renewsUsed": "Renovações usadas",

internal/web/translation/ru-RU.json

@@ -943,6 +943,23 @@
       },
       "renewMax": "Лимит продлений",
       "renewMaxDesc": "Сколько раз автопродление может сработать, прежде чем клиент будет оставлен истекать. 0 — без ограничения. Догон нескольких пропущенных периодов расходует по одному продлению на период.",
+      "renewMode": "Auto renewal",
+      "renewModeNone": "Disabled",
+      "renewModeInterval": "Fixed interval (days)",
+      "renewModeWeekly": "Calendar weekly",
+      "renewModeMonthly": "Calendar monthly",
+      "renewWeekday": "Renew on weekday",
+      "renewScheduleDesc": "Calendar renewal uses midnight in the panel timezone and also resets the client's traffic. Keep independent traffic resets disabled unless an additional reset is intended. Monthly day 1 means valid through the preceding month; day 31 is not the same boundary.",
+      "renewPreview": "Renewal preview ({zone})",
+      "renewAt": "Renewal boundary",
+      "renewValidThrough": "Valid through",
+      "renewNextExpiry": "Cutoff after renewal",
+      "renewPeriods": "Periods charged: {count}",
+      "renewUnavailable": "The remaining renewal allowances cannot provide a future cutoff.",
+      "renewFirstUse": "Dates are available after first-use activation. The initial duration is unchanged.",
+      "renewSetExpiry": "Set first cycle cutoff",
+      "renewNeedsExpiry": "An expiry must be set before auto-renewal can run.",
+      "renewPreviewError": "Could not preview renewal dates.",
       "renewOnDay": "Продлевать числа",
       "renewOnDayDesc": "Продлевать этого числа каждого месяца, в полночь по часовому поясу панели, вместо интервала в днях. Если в месяце такого числа нет, продление придётся на последний день. 0 — оставить режим интервала.",
       "renewsUsed": "Продлений израсходовано",

internal/web/translation/tr-TR.json

@@ -943,6 +943,23 @@
       },
       "renewMax": "En fazla yenileme",
       "renewMaxDesc": "İstemcinin süresi dolmaya bırakılmadan önce otomatik yenilemenin kaç kez çalışabileceği. 0 sınırsız demektir. Kaçırılan birden fazla dönemi telafi etmek, dönem başına bir yenileme harcar.",
+      "renewMode": "Auto renewal",
+      "renewModeNone": "Disabled",
+      "renewModeInterval": "Fixed interval (days)",
+      "renewModeWeekly": "Calendar weekly",
+      "renewModeMonthly": "Calendar monthly",
+      "renewWeekday": "Renew on weekday",
+      "renewScheduleDesc": "Calendar renewal uses midnight in the panel timezone and also resets the client's traffic. Keep independent traffic resets disabled unless an additional reset is intended. Monthly day 1 means valid through the preceding month; day 31 is not the same boundary.",
+      "renewPreview": "Renewal preview ({zone})",
+      "renewAt": "Renewal boundary",
+      "renewValidThrough": "Valid through",
+      "renewNextExpiry": "Cutoff after renewal",
+      "renewPeriods": "Periods charged: {count}",
+      "renewUnavailable": "The remaining renewal allowances cannot provide a future cutoff.",
+      "renewFirstUse": "Dates are available after first-use activation. The initial duration is unchanged.",
+      "renewSetExpiry": "Set first cycle cutoff",
+      "renewNeedsExpiry": "An expiry must be set before auto-renewal can run.",
+      "renewPreviewError": "Could not preview renewal dates.",
       "renewOnDay": "Yenileme günü",
       "renewOnDayDesc": "Her N günde bir yerine, her takvim ayının bu gününde, panel saat diliminde gece yarısı yeniler. Seçilen gün için kısa olan aylarda ayın son gününde yeniler. 0 gün aralığı modunu korur.",
       "renewsUsed": "Kullanılan yenileme",

internal/web/translation/uk-UA.json

@@ -943,6 +943,23 @@
       },
       "renewMax": "Ліміт подовжень",
       "renewMaxDesc": "Скільки разів автоподовження може спрацювати, перш ніж клієнта буде залишено спливати. 0 — без обмеження. Надолуження кількох пропущених періодів витрачає по одному подовженню на період.",
+      "renewMode": "Auto renewal",
+      "renewModeNone": "Disabled",
+      "renewModeInterval": "Fixed interval (days)",
+      "renewModeWeekly": "Calendar weekly",
+      "renewModeMonthly": "Calendar monthly",
+      "renewWeekday": "Renew on weekday",
+      "renewScheduleDesc": "Calendar renewal uses midnight in the panel timezone and also resets the client's traffic. Keep independent traffic resets disabled unless an additional reset is intended. Monthly day 1 means valid through the preceding month; day 31 is not the same boundary.",
+      "renewPreview": "Renewal preview ({zone})",
+      "renewAt": "Renewal boundary",
+      "renewValidThrough": "Valid through",
+      "renewNextExpiry": "Cutoff after renewal",
+      "renewPeriods": "Periods charged: {count}",
+      "renewUnavailable": "The remaining renewal allowances cannot provide a future cutoff.",
+      "renewFirstUse": "Dates are available after first-use activation. The initial duration is unchanged.",
+      "renewSetExpiry": "Set first cycle cutoff",
+      "renewNeedsExpiry": "An expiry must be set before auto-renewal can run.",
+      "renewPreviewError": "Could not preview renewal dates.",
       "renewOnDay": "Подовжувати числа",
       "renewOnDayDesc": "Подовжувати цього числа кожного місяця, опівночі за часовим поясом панелі, замість інтервалу в днях. Якщо в місяці такого числа немає, подовження припаде на останній день. 0 — залишити режим інтервалу.",
       "renewsUsed": "Подовжень витрачено",

internal/web/translation/vi-VN.json

@@ -943,6 +943,23 @@
       },
       "renewMax": "Số lần gia hạn tối đa",
       "renewMaxDesc": "Gia hạn tự động được phép chạy bao nhiêu lần trước khi để khách hàng hết hạn. 0 nghĩa là không giới hạn. Bù lại nhiều kỳ đã bỏ lỡ sẽ tiêu tốn một lần gia hạn cho mỗi kỳ.",
+      "renewMode": "Auto renewal",
+      "renewModeNone": "Disabled",
+      "renewModeInterval": "Fixed interval (days)",
+      "renewModeWeekly": "Calendar weekly",
+      "renewModeMonthly": "Calendar monthly",
+      "renewWeekday": "Renew on weekday",
+      "renewScheduleDesc": "Calendar renewal uses midnight in the panel timezone and also resets the client's traffic. Keep independent traffic resets disabled unless an additional reset is intended. Monthly day 1 means valid through the preceding month; day 31 is not the same boundary.",
+      "renewPreview": "Renewal preview ({zone})",
+      "renewAt": "Renewal boundary",
+      "renewValidThrough": "Valid through",
+      "renewNextExpiry": "Cutoff after renewal",
+      "renewPeriods": "Periods charged: {count}",
+      "renewUnavailable": "The remaining renewal allowances cannot provide a future cutoff.",
+      "renewFirstUse": "Dates are available after first-use activation. The initial duration is unchanged.",
+      "renewSetExpiry": "Set first cycle cutoff",
+      "renewNeedsExpiry": "An expiry must be set before auto-renewal can run.",
+      "renewPreviewError": "Could not preview renewal dates.",
       "renewOnDay": "Gia hạn vào ngày",
       "renewOnDayDesc": "Gia hạn vào ngày này của mỗi tháng dương lịch, lúc nửa đêm theo múi giờ của bảng điều khiển, thay vì mỗi N ngày. Tháng không có ngày đã chọn sẽ gia hạn vào ngày cuối cùng của tháng. 0 giữ nguyên chế độ khoảng cách theo ngày.",
       "renewsUsed": "Số lần gia hạn đã dùng",

internal/web/translation/zh-CN.json

@@ -943,6 +943,23 @@
       },
       "renewMax": "最大续期次数",
       "renewMaxDesc": "自动续期最多可触发的次数，达到后客户端将自然到期。填 0 表示不限制。补齐多个错过的周期时，每个周期消耗一次续期。",
+      "renewMode": "自动续期模式",
+      "renewModeNone": "不续期",
+      "renewModeInterval": "固定间隔（天）",
+      "renewModeWeekly": "日历周",
+      "renewModeMonthly": "日历月",
+      "renewWeekday": "每周续期日",
+      "renewScheduleDesc": "日历续期按面板时区的午夜执行，并重置客户端流量。若不需要额外重置，请关闭独立的流量重置。每月 1 日续期表示有效至上个月末；每月 31 日不是同一边界。",
+      "renewPreview": "续期预览（{zone}）",
+      "renewAt": "续期边界",
+      "renewValidThrough": "本期有效至",
+      "renewNextExpiry": "续期后的截止时间",
+      "renewPeriods": "计入续期次数：{count}",
+      "renewUnavailable": "剩余续期次数不足以提供未来的截止时间。",
+      "renewFirstUse": "首次使用激活后才能确定日期，首次使用后的初始时长保持不变。",
+      "renewSetExpiry": "设置首个周期截止时间",
+      "renewNeedsExpiry": "需要先设置到期时间，自动续期才会执行。",
+      "renewPreviewError": "无法预览续期日期。",
       "renewOnDay": "按日期续期",
       "renewOnDayDesc": "每个自然月的这一天午夜（按面板时区）续期，而不是每 N 天续期一次。若当月没有该日期，则在当月最后一天续期。填 0 保持按天间隔模式。",
       "renewsUsed": "已用续期次数",

internal/web/translation/zh-TW.json

@@ -943,6 +943,23 @@
       },
       "renewMax": "最大續期次數",
       "renewMaxDesc": "自動續期最多可觸發的次數，達到後用戶端將自然到期。填 0 表示不限制。補齊多個錯過的週期時，每個週期消耗一次續期。",
+      "renewMode": "自動續期模式",
+      "renewModeNone": "不續期",
+      "renewModeInterval": "固定間隔（天）",
+      "renewModeWeekly": "日曆週",
+      "renewModeMonthly": "日曆月",
+      "renewWeekday": "每週續期日",
+      "renewScheduleDesc": "日曆續期按面板時區的午夜執行，並重置客戶端流量。若不需要額外重置，請關閉獨立的流量重置。每月 1 日續期表示有效至上個月末；每月 31 日不是同一邊界。",
+      "renewPreview": "續期預覽（{zone}）",
+      "renewAt": "續期邊界",
+      "renewValidThrough": "本期有效至",
+      "renewNextExpiry": "續期後的截止時間",
+      "renewPeriods": "計入續期次數：{count}",
+      "renewUnavailable": "剩餘續期次數不足以提供未來的截止時間。",
+      "renewFirstUse": "首次使用啟用後才能確定日期，首次使用後的初始時長保持不變。",
+      "renewSetExpiry": "設定首個週期截止時間",
+      "renewNeedsExpiry": "需要先設定到期時間，自動續期才會執行。",
+      "renewPreviewError": "無法預覽續期日期。",
       "renewOnDay": "按日期續期",
       "renewOnDayDesc": "每個自然月的這一天午夜（依面板時區）續期，而不是每 N 天續期一次。若當月沒有該日期，則在當月最後一天續期。填 0 保持按天間隔模式。",
       "renewsUsed": "已用續期次數",

internal/xray/client_traffic.go

@@ -15,8 +15,10 @@ type ClientTraffic struct {
 	Total      int64  `json:"total" form:"total" example:"10737418240"`
 	Reset      int    `json:"reset" form:"reset" gorm:"default:0;index:idx_client_traffics_renew,priority:2" example:"0"`
 	// ResetDay renews on that day of each calendar month instead of every
-	// Reset days; 0 keeps the interval behaviour.
+	// Reset days; 0 disables monthly renewal.
 	ResetDay int `json:"resetDay" form:"resetDay" gorm:"default:0" example:"0"`
+	// ResetWeekday renews weekly at panel-local midnight: 1 Monday through 7 Sunday.
+	ResetWeekday int `json:"resetWeekday" form:"resetWeekday" gorm:"default:0" example:"0"`
 	// ResetMax caps how many times auto-renew may fire; 0 means no cap.
 	ResetMax int `json:"resetMax" form:"resetMax" gorm:"default:0" example:"0"`
 	// ResetCount is how many have fired, so a prepaid plan stops on its own.

tools/openapigen/main.go

@@ -93,6 +93,8 @@ func run(root, outDir string) error {
 				"InboundOption",
 				"HappLinkResult",
 				"ClientSlim",
+				"ClientRenewalPreviewRequest",
+				"ClientRenewalPreview",
 				"ClientPageResponse",
 				"ClientsSummary",
 				"InboundTrafficSummary",