Add earnings adjustments, withdrawal reject, and auth guard

2026-01-12 12:46:42 -05:00
parent d335c577d3
commit 56239450d4
34 changed files with 3117 additions and 22 deletions
--- a/llm/earnings-adjustments-and-withdrawal-reject.md
+++ b/llm/earnings-adjustments-and-withdrawal-reject.md
@@ -0,0 +1,177 @@
+# Earnings Adjustments & Withdrawal Reject — Expected Behavior
+
+This document defines the intended behavior for:
+
+- Admin-created **earnings adjustments** (positive or negative earning lines)
+- Admin **withdrawal reject** (cancel a withdrawal request and release reserved earning lines)
+- **Authorization** rules (permission + group leader scope + cross-tenant isolation)
+
+## Concepts
+
+### Earnings Line
+An `earnings line` is an immutable money movement entry for a clerk. Amount can be positive or negative.
+
+### Adjustment
+An `adjustment` is an admin-originated earnings line, designed to support future extensibility (many “reasons”, auditability, idempotency, async apply).
+
+Key semantics:
+
+- It **creates exactly one** earnings line when applied.
+- The created earnings line uses:
+  - `earningType = ADJUSTMENT`
+  - `sourceType = ADJUSTMENT`
+  - `sourceId = adjustmentId`
+  - `orderId = null`
+  - `amount` can be positive or negative
+  - `unlockTime = effectiveTime` (adjustments are effective at their “unlock” time)
+
+### Withdrawal Reject
+Admin reject is a cancel operation that:
+
+- marks the withdrawal request as canceled/rejected
+- releases reserved `withdrawing` earnings lines back to `available` / `frozen`
+
+## Authorization Model (New Endpoints)
+
+Authorization is **two-layer**:
+
+1) **Action-level permission**: does the user have permission to call the endpoint?
+2) **Object-level scope**: can the user act on the target clerk / request?
+
+### Permission Strings
+
+- Create adjustment: `withdraw:adjustment:create`
+- Read/poll adjustment status: `withdraw:adjustment:read`
+- Reject withdrawal request: `withdraw:request:reject`
+
+### Group Leader Scope
+
+If the current user is **not** `superAdmin`, they can only act on clerks that belong to a group where:
+
+- `clerk.groupId = group.id`
+- `group.sysUserId = currentUserId`
+
+If this scope check fails, the endpoint returns **HTTP 403**.
+
+### Super Admin Bypass
+
+If `superAdmin == true`, the user bypasses permission checks and scope checks for these new endpoints.
+
+### Cross-Tenant Isolation
+
+All operations are tenant-scoped.
+
+- If `X-Tenant` does not match the target entity’s `tenantId`, the API returns **HTTP 404** (do not leak existence across tenants).
+
+## Admin Earnings Adjustments API
+
+### Create Adjustment
+
+`POST /admin/earnings/adjustments`
+
+Headers:
+
+- `Idempotency-Key: <uuid>` (required)
+- `X-Tenant: <tenantId>` (required)
+
+Body:
+
+```json
+{
+  "clerkId": "clerk-id",
+  "amount": "20.00",
+  "reasonType": "MANUAL",
+  "reasonDescription": "text",
+  "effectiveTime": "2026-01-01T12:00:00" // optional
+}
+```
+
+Validation rules:
+
+- `Idempotency-Key` required
+- `tenantId` required
+- `clerkId` required
+- `amount` must be non-zero (positive = reward-like, negative = punishment-like)
+- `reasonType` required (currently hard-coded enum values, extend later)
+- `reasonDescription` required, non-blank
+
+Idempotency behavior:
+
+- Same `tenantId + Idempotency-Key` with the **same request body** returns the **same** `adjustmentId`.
+- Same `tenantId + Idempotency-Key` with a **different request body** returns **HTTP 409**.
+
+Response behavior:
+
+- Always returns **HTTP 202 Accepted** on success (request is “in-progress”).
+- Includes `Location: /admin/earnings/adjustments/idempotency/{Idempotency-Key}` for polling.
+
+Response example:
+
+```json
+{
+  "code": 202,
+  "message": "请求处理中",
+  "data": {
+    "adjustmentId": "adj-uuid",
+    "idempotencyKey": "same-key",
+    "status": "PROCESSING"
+  }
+}
+```
+
+### Poll Adjustment Status
+
+`GET /admin/earnings/adjustments/idempotency/{key}`
+
+Behavior:
+
+- If not found in this tenant: **HTTP 404**
+- If found:
+  - returns **HTTP 200**
+  - `status` is one of:
+    - `PROCESSING`: accepted but not yet applied
+    - `APPLIED`: earnings line has been created
+    - `FAILED`: apply failed (and should be visible for operator debugging)
+
+Stress / eventual consistency note:
+
+- Under load (DB latency / executor backlog), polling may stay in `PROCESSING` longer, but must not create duplicate earnings lines.
+
+## Withdrawal Reject API
+
+### Reject Withdrawal Request
+
+`POST /admin/withdraw/requests/{id}/reject`
+
+Body:
+
+```json
+{ "reason": "text (optional)" }
+```
+
+Behavior:
+
+- If request does not exist in this tenant: **HTTP 404**
+- If request is already canceled/rejected: return **HTTP 200** (idempotent)
+- If request is `success`: return **HTTP 400** (cannot reject a successful payout)
+- Otherwise:
+  - request status transitions to `canceled` (or `rejected` depending on legacy naming)
+  - all earnings lines with:
+    - `withdrawalId = requestId`
+    - `status = withdrawing`
+    are released:
+      - `withdrawalId` set to `null`
+      - if `unlockTime > now` -> `status = frozen`
+      - else -> `status = available`
+
+## Stats: includeAdjustments toggle
+
+The statistics endpoint supports a toggle `includeAdjustments`:
+
+- when `includeAdjustments = false` (default): only order-derived earnings contribute
+- when `includeAdjustments = true`: adjustment earnings lines (`sourceType=ADJUSTMENT`) are included in the revenue sum
+
+Time-window behavior:
+
+- adjustment inclusion is based on `unlockTime` window (equivalent to `effectiveTime`)
+