docs: update lite deployment and feature docs

docs/API.md

@@ -1,6 +1,6 @@
-# J-Board API 与 Server Actions
+# J-Board Lite API 与 Server Actions
 
-本文整理 J-Board 当前有效的 HTTP Route Handlers 和内部 Server Actions。HTTP 对外结构化描述见 `docs/openapi.yaml`；本文更偏向工程阅读和排障。
+本文整理 J-Board Lite 当前有效的 HTTP Route Handlers 和内部 Server Actions。HTTP 对外结构化描述见 `docs/openapi.yaml`；本文更偏向工程阅读和排障。
 
 ## 通用约定
 
@@ -33,7 +33,8 @@
 行为：
 
 - 校验邮箱、密码、邀请码和 Turnstile。
-- 当注册邮箱验证开启时，用户会进入 `PENDING_EMAIL` 状态并收到验证邮件。
+- 当注册邮箱验证开启时，先写入 `PendingRegistration` 并发送验证邮件，用户不会立即创建。
+- 只有邮箱验证链接通过后，系统才创建 `User` 并激活。
 - 当注册邮箱验证关闭时，用户直接成为可登录用户。
 
 ### `GET|POST /api/auth/[...nextauth]`
@@ -66,7 +67,7 @@ NextAuth 内置登录、登出、会话接口。
 
 ### `GET /api/payment/providers`
 
-返回当前启用的支付方式。普通用户创建订单或切换支付方式时使用。
+返回当前启用的支付方式。普通用户创建订单或切换支付方式时使用。`?target=wallet` 会排除余额支付，避免用户用余额给余额充值。
 
 ### `POST /api/payment/create`
 
@@ -109,6 +110,41 @@ NextAuth 内置登录、登出、会话接口。
 - 标记订单已支付。
 - 调用 `src/services/provision.ts` 创建或续费订阅。
 - 代理订阅会同步 3x-ui client。
+- 充值订单回调会进入钱包入账流程，成功后写入 `WalletTransaction`。
+
+## 钱包接口
+
+### `GET /api/wallet/recharge/{id}`
+
+查询当前用户自己的余额充值订单。充值支付页会读取金额、状态、支付方式和流水号。
+
+### `POST /api/wallet/recharge/payment/create`
+
+为余额充值订单创建外部支付参数。
+
+请求体：
+
+```json
+{
+  "rechargeId": "wallet-recharge-order-id",
+  "provider": "epay",
+  "channel": "alipay"
+}
+```
+
+行为：
+
+- 要求登录用户拥有该充值订单，且订单仍为 `PENDING`。
+- 不允许 `provider=balance`。
+- 调用对应支付适配器生成支付链接、二维码或链上收款信息。
+
+### `GET /api/wallet/recharge/query/{tradeNo}`
+
+按充值流水号主动查询支付状态。用于充值页轮询或回调异常时兜底。
+
+### `POST /api/wallet/redeem-card`
+
+兑换充值卡。余额卡立即入账余额；套餐卡立即激活对应套餐。已使用、过期或不存在的卡密会返回可展示错误。
 
 ## 订阅与用户资源
 
@@ -320,6 +356,10 @@ Server Actions 是后台和用户端写操作的主要入口。它们不是公
 
 自动清理由 `src/services/log-cleanup-scheduler.ts` 启动，默认每天最多执行一次，读取 `AppConfig.logCleanupEnabled` 和 `AppConfig.logRetentionDays`。自动清理和手动过期清理都会保留仍处于用户端限制中的风控事件。
 
+#### 套餐 Push：`src/actions/admin/subscription-transfers.ts`
+
+- `deleteAdminSubscriptionTransfer(id)`：删除管理端 Push 历史记录。待接收记录会先取消转让、恢复套餐、退回已扣手续费，再删除记录；已完成记录只删除历史。
+
 #### 订单：`src/actions/admin/orders.ts`
 
 - `confirmOrder(orderId)`：手动确认订单并触发开通。
@@ -341,6 +381,7 @@ Server Actions 是后台和用户端写操作的主要入口。它们不是公
 - 任务重试：`src/actions/admin/tasks.ts`
 - 流量视图刷新：`src/actions/admin/traffic.ts`
 - 优惠券与促销：`src/actions/admin/commerce.ts`
+- 充值卡：`src/actions/admin/recharge-cards.ts`，生成余额卡/套餐卡、删除卡密并在需要时释放套餐库存。
 
 ### 用户端 Actions
 
@@ -351,6 +392,8 @@ Server Actions 是后台和用户端写操作的主要入口。它们不是公
 - `src/actions/user/notifications.ts`：已读、删除、清空。
 - `src/actions/user/support.ts`：创建、回复、关闭、删除工单。创建工单会受后台工单上限控制。
 - `src/actions/user/orders.ts`：取消待支付订单、重新选择支付方式。
+- `src/actions/user/wallet.ts`：创建余额充值订单、兑换充值卡、取消待支付充值订单。
+- `src/actions/user/subscription-transfer.ts`：发起套餐 Push、接收、拒收、取消。发起时会暂停套餐并禁用 3x-ui client，接收成功后会为接收方生成新的 client。
 
 ## 风控数据模型要点
 
@@ -359,6 +402,9 @@ Server Actions 是后台和用户端写操作的主要入口。它们不是公
 - `SubscriptionRiskReason`：包含城市、省/地区、国家变化，以及节点高频、目标分散等原因。
 - `AppConfig`：保存订阅风控总控、自动暂停开关、阈值、节点日志风控阈值，以及日志清理开关、保留天数和上次清理时间。
 - `NodeClient.email`：用于匹配 Xray access log 中的 `email:`。它可能形如 `user@example.com-cmojtnp3`，不要手动在 3x-ui 修改。
+- `WalletAccount` / `WalletTransaction` / `WalletRechargeOrder`：保存用户余额、余额流水和充值订单。
+- `RechargeCard`：保存余额卡和套餐卡，套餐卡会参与套餐库存占用计算。
+- `SubscriptionTransfer`：保存套餐 Push 全流程状态、费用承担方、扣费/退款时间、周期起点和 24 小时过期时间。
 
 ## 错误处理约定
 

docs/openapi.yaml

@@ -1,8 +1,8 @@
 openapi: 3.1.0
 info:
-  title: J-Board API
-  version: 0.2.0
-  description: Current J-Board Route Handlers. Node provisioning uses 3x-ui; probe API only accepts latency and trace uploads.
+  title: J-Board Lite API
+  version: 0.3.0
+  description: Current J-Board Lite Route Handlers. Node provisioning uses 3x-ui; the Agent API accepts latency, route trace, and Xray access log uploads.
 servers:
   - url: https://your-domain.com
 security: []
@@ -11,8 +11,10 @@ tags:
   - name: Public
   - name: Payment
   - name: Admin
-  - name: Probe
+  - name: Agent
   - name: Subscription
+  - name: Wallet
+  - name: Support
 paths:
   /api/auth/register:
     post:
@@ -82,6 +84,14 @@ paths:
     get:
       tags: [Payment]
       summary: List enabled payment providers
+      parameters:
+        - name: target
+          in: query
+          required: false
+          schema:
+            type: string
+            enum: [order, wallet]
+          description: Use wallet to exclude balance payment from recharge flows.
       responses:
         '200':
           description: Providers
@@ -200,10 +210,10 @@ paths:
           description: SQL file
   /api/agent/latency:
     post:
-      tags: [Probe]
-      summary: Upload carrier latency probe results
+      tags: [Agent]
+      summary: Upload carrier latency results
       security:
-        - probeToken: []
+        - agentToken: []
       requestBody:
         required: true
         content:
@@ -218,13 +228,13 @@ paths:
               schema:
                 $ref: '#/components/schemas/OkResponse'
         '401':
-          description: Invalid probe token
+          description: Invalid agent token
   /api/agent/trace:
     post:
-      tags: [Probe]
+      tags: [Agent]
       summary: Upload carrier route trace results
       security:
-        - probeToken: []
+        - agentToken: []
       requestBody:
         required: true
         content:
@@ -239,7 +249,24 @@ paths:
               schema:
                 $ref: '#/components/schemas/OkResponse'
         '401':
-          description: Invalid probe token
+          description: Invalid agent token
+  /api/agent/node-access:
+    post:
+      tags: [Agent]
+      summary: Upload aggregated Xray access log events
+      security:
+        - agentToken: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NodeAccessUpload'
+      responses:
+        '200':
+          description: Accepted
+        '401':
+          description: Invalid agent token
   /api/subscription/{id}:
     get:
       tags: [Subscription]
@@ -264,7 +291,7 @@ paths:
                 type: string
   /api/support/attachments/{id}:
     get:
-      tags: [Subscription]
+      tags: [Support]
       summary: Download or preview support attachment
       security:
         - cookieAuth: []
@@ -282,13 +309,99 @@ paths:
       responses:
         '200':
           description: Attachment file
+  /api/subscription/all:
+    get:
+      tags: [Subscription]
+      summary: Download aggregate subscription content
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          description: Subscription text
+          content:
+            text/plain:
+              schema:
+                type: string
+  /api/notifications:
+    get:
+      tags: [Subscription]
+      summary: List current user notifications
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          description: Notifications
+  /api/wallet/recharge/{id}:
+    get:
+      tags: [Wallet]
+      summary: Get current user's wallet recharge order
+      security:
+        - cookieAuth: []
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Recharge order
+  /api/wallet/recharge/payment/create:
+    post:
+      tags: [Wallet]
+      summary: Create external payment parameters for a wallet recharge order
+      security:
+        - cookieAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateWalletRechargePaymentRequest'
+      responses:
+        '200':
+          description: Payment created
+        '400':
+          description: Invalid recharge or payment provider
+  /api/wallet/recharge/query/{tradeNo}:
+    get:
+      tags: [Wallet]
+      summary: Query wallet recharge payment by trade number
+      security:
+        - cookieAuth: []
+      parameters:
+        - name: tradeNo
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Recharge payment state
+  /api/wallet/redeem-card:
+    post:
+      tags: [Wallet]
+      summary: Redeem a balance or subscription recharge card
+      security:
+        - cookieAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RedeemRechargeCardRequest'
+      responses:
+        '200':
+          description: Redeemed
+        '400':
+          description: Invalid, used, or expired card
 components:
   securitySchemes:
     cookieAuth:
       type: apiKey
       in: cookie
       name: next-auth.session-token
-    probeToken:
+    agentToken:
       type: http
       scheme: bearer
   parameters:
@@ -336,7 +449,25 @@ components:
           type: string
         provider:
           type: string
+        channel:
+          type: string
       required: [orderId, provider]
+    CreateWalletRechargePaymentRequest:
+      type: object
+      properties:
+        rechargeId:
+          type: string
+        provider:
+          type: string
+        channel:
+          type: string
+      required: [rechargeId, provider]
+    RedeemRechargeCardRequest:
+      type: object
+      properties:
+        code:
+          type: string
+      required: [code]
     LatencyUpload:
       type: object
       properties:
@@ -383,3 +514,38 @@ components:
                 type: integer
             required: [carrier, hops]
       required: [traces]
+    NodeAccessUpload:
+      type: object
+      properties:
+        events:
+          type: array
+          items:
+            type: object
+            properties:
+              clientEmail:
+                type: string
+              sourceIp:
+                type: string
+              inboundTag:
+                type: string
+              network:
+                type: string
+                enum: [tcp, udp]
+              targetHost:
+                type: string
+              targetPort:
+                type: integer
+              action:
+                type: string
+              connectionCount:
+                type: integer
+              uniqueTargetCount:
+                type: integer
+              firstSeenAt:
+                type: string
+                format: date-time
+              lastSeenAt:
+                type: string
+                format: date-time
+            required: [clientEmail, sourceIp, inboundTag, network, action, connectionCount, uniqueTargetCount]
+      required: [events]