@xmobitea/gn-typescript-client 2.6.13 → 2.6.14

package/docs/RULES.md

@@ -0,0 +1,307 @@
+# RULES — Single Source of Truth
+
+File này là canonical source cho mọi rule cross-cutting: route/permission, self/other-self, auth/socket, error handling, override params, anti-patterns. Các file khác (`README.MD`, `AGENTS.md`, guides) đều link tới đây thay vì lặp lại.
+
+> Nếu phát hiện mâu thuẫn giữa RULES.md và file khác, RULES.md thắng.
+
+---
+
+## 1. Init
+
+- Public entrypoint duy nhất là static class `GNNetwork` (import từ `@xmobitea/gn-typescript-client`).
+- Bắt buộc tạo `GNServerSettings`, gọi `settings.config({...})`, rồi `GNNetwork.init(settings)` **1 lần** ở bootstrap của mỗi app session.
+- `init()` idempotent — lần thứ 2 bị ignore. Muốn đổi snapshot config toàn cục nên restart process. Mutate cùng `settings` object sau init chỉ ảnh hưởng một số request mới và không tự reconnect socket.
+- Gọi API trước khi init → namespace `undefined` / `TypeError`.
+- Config field: xem [reference/CONFIG.md](reference/CONFIG.md).
+
+---
+
+## 2. Response checking (2-tier)
+
+Typed response (mọi `*Async()` và callback form) expose **PUBLIC FIELDS** — không phải getter:
+
+```ts
+res.returnCode       // transport/gateway layer
+res.errorCode        // business/domain layer
+res.invalidMembers   // chỉ set khi returnCode === InvalidRequestParameters
+res.debugMessage     // backend debug string
+res.responseData     // typed payload, chỉ set khi returnCode === Ok
+```
+
+Pattern bắt buộc, đúng thứ tự:
+
+```ts
+if (res.returnCode !== ReturnCode.Ok) return; // transport/permission fail
+if (res.errorCode  !== ErrorCode.Ok)  return; // business fail
+useResult(res.responseData);                  // happy path
+```
+
+Rule cứng:
+
+- `Ok === 1` ở **cả** `ReturnCode` và `ErrorCode`. Không giả định `Ok === 0`.
+- Không skip tầng 1 để đọc thẳng `errorCode`; khi `returnCode !== Ok`, `errorCode` và `responseData` **không đáng tin**.
+- Không hardcode số (`if (res.returnCode === 1)`). So sánh bằng enum symbol.
+- `*Async()` **không throw** business/transport error — reject Promise chỉ khi transport layer thật sự fail (network exception, serialization fail).
+- Low-level raw `OperationResponse` (không dùng typed wrapper) có getter `getReturnCode()` etc. — chỉ dùng khi tự viết custom op.
+
+Full table ReturnCode/ErrorCode + recommended action: [reference/ERROR_HANDLING.md](reference/ERROR_HANDLING.md). Phân biệt `SecretInvalid` / `OperationInvalid` / `OperationNotAllow` → § 5.
+
+---
+
+## 3. Route = trust boundary của caller
+
+Route `client / server / admin` mô tả **bên gọi** thực sự ở đâu, không phải target của mình hay của người khác.
+
+| Route | Dùng khi code chạy ở |
+|---|---|
+| `client` (`GNNetwork.<group>`) | App / browser / mobile của player |
+| `server` (`GNNetwork.<group>.server`) | Trusted backend: game server, internal service, worker, cron, webhook |
+| `admin` (`GNNetwork.<group>.admin`) | Backoffice, dashboard, GM tool, migration tool, ops |
+
+Rule cứng:
+
+- Không chọn `server`/`admin` chỉ vì target không thuộc user hiện tại.
+- Không dùng `.server` / `.admin` từ app client chỉ để vượt permission — bị coi là trust boundary leak, secret sẽ bị expose.
+- Không suy diễn route chỉ từ việc request có hay không có `userId`.
+- Route `server`/`admin` yêu cầu `secretKey` có flag `serverSelfEnable` / `adminSelfEnable` tương ứng (hoặc truyền `overrideSecretKey`).
+
+### Ngoại lệ: `DashboardApi`
+
+- Sau `loginByAdminAccountAsync` thành công, backend resolve admin context từ `authToken` — caller **không** cần cấu hình `secretKey` admin riêng.
+- Public wrapper `GNNetwork.dashboard.*` vẫn đi `RequestRole.Client`.
+- `GNNetwork.dashboard.server` và `GNNetwork.dashboard.admin` hiện **rỗng** (không có operation public).
+
+---
+
+## 4. `self` vs `other-self` (chỉ áp dụng trên route `client`)
+
+Backend suy ra thêm target context `self / other-self` cho route `client`:
+
+| Domain | `self` = |
+|---|---|
+| `MasterPlayerApi`, `GamePlayerApi` | `userId` trong request trùng `userId` đã authenticate (hoặc request không truyền `userId`) |
+| `CharacterPlayerApi`, `InventoryApi`, `GroupApi` | Entity target thuộc ownership của `GamePlayer` có `userId` trùng user đang authenticate |
+| `ContentApi`, `StoreInventoryApi`, `MultiplayerApi`, `CloudScriptApi` | **Không có ownership rõ ràng** — không ép self/other-self; chọn route theo trust boundary + để backend áp permission theo contract operation |
+
+Rule cứng:
+
+- `self / other-self` **không** phải `server / admin`. `server / admin` là route đặc quyền riêng.
+- Không vì muốn thao tác lên data user khác mà tự động chuyển sang `.server` / `.admin`.
+- Ví dụ đúng:
+  - App player gọi `masterPlayer.getPlayerInformationAsync()` cho user đang login → `client + self`.
+  - App player gọi `masterPlayer.getPlayerInformationAsync(otherUserId)` → `client + other-self`.
+  - Game server gọi `gamePlayer.server.changePlayerCurrencyAsync(...)` → `server` (không phải `client + other-self`).
+  - GM tool gọi `inventory.admin.setRemoveStatusAsync(...)` → `admin`.
+
+---
+
+## 5. Phân biệt 3 ReturnCode dễ nhầm
+
+| Code | Nghĩa | Fix |
+|---|---|---|
+| `SecretInvalid` | Secret key sai, thiếu, hoặc không khớp game context | Fix `GNServerSettings.secretKey`. **KHÔNG retry**. |
+| `OperationInvalid` | Operation code không tồn tại, hoặc không hợp lệ với `RequestType` + `RequestRole` hiện tại | Check namespace đang gọi + đúng method trong `API_<GROUP>.md`. |
+| `OperationNotAllow` | Secret hợp lệ **và** operation tồn tại, NHƯNG permission rule của secret không cho phép trong target context | Check route + flag `selfEnable`/`otherSelfEnable`/`serverSelfEnable`/`adminSelfEnable`. **KHÔNG retry**. |
+
+Cùng gia đình nhưng ý nghĩa khác hẳn — đừng confuse "secret sai" với "secret đúng nhưng không đủ quyền".
+
+---
+
+## 6. Permission flags
+
+GearN Server map quyền theo từng domain + operation (ví dụ `masterPlayer.getPlayerInformation`, `group.sendGroupMessage`). Mỗi secret key có 4 flag chính:
+
+| Flag | Nghĩa |
+|---|---|
+| `selfEnable` | Cho phép thao tác trên tài nguyên thuộc user đã authenticate |
+| `otherSelfEnable` | Cho phép thao tác trên tài nguyên không thuộc user đã authenticate |
+| `serverSelfEnable` | Cho phép thực thi qua route `server` |
+| `adminSelfEnable` | Cho phép thực thi qua route `admin` |
+
+Danh sách operation/flag offline: [reference/PERMISSION_RULES.md](reference/PERMISSION_RULES.md) + `docs/reference/API_<GROUP>.md`. Backend GearN Server / dashboard vẫn là runtime source-of-truth cho secret key nào đang có flag nào.
+
+### 6.1 Mapping (route, target) → required flag
+
+Đây là quy tắc **uniform** cho mọi operation. Kết hợp với [§ 4 self / other-self](#4-self-vs-other-self-chỉ-áp-dụng-trên-route-client) để xác định target.
+
+| Caller gọi | Target | Flag cần trên secret key |
+|---|---|---|
+| `GNNetwork.<group>.<method>()` — bỏ userId hoặc userId trùng auth | Self | `selfEnable` của operation |
+| `GNNetwork.<group>.<method>(otherUserId)` | Other-self | `otherSelfEnable` của operation |
+| `GNNetwork.<group>.server.<method>(...)` | Bất kỳ | `serverSelfEnable` của operation |
+| `GNNetwork.<group>.admin.<method>(...)` | Bất kỳ | `adminSelfEnable` của operation |
+
+Ngoại lệ: domain không có ownership (`ContentApi`, `StoreInventoryApi`, `MultiplayerApi`, `CloudScriptApi`) — `self` / `other-self` không áp dụng trên route `client`; backend áp rule theo contract operation.
+
+### 6.2 Ai config flag, client có đổi được không?
+
+- Permission rule được **backend admin** config trên dashboard GearN Server theo **từng `secretKey` × từng operation × từng flag**.
+- Client **không** tự đổi được flag. Chỉ có 3 option khi thiếu quyền:
+  1. Dùng `secretKey` khác trong `GNServerSettings` (cấu hình từ bootstrap).
+  2. Truyền `overrideSecretKey` per-request.
+  3. Yêu cầu backend admin bật flag cho secret hiện tại.
+- Danh sách operation theo domain: ưu tiên [reference/PERMISSION_RULES.md](reference/PERMISSION_RULES.md) và `docs/reference/API_<GROUP>.md` trong repo; chỉ dùng external permission mirror khi cần đối chiếu online.
+
+### 6.3 Scenario điển hình trigger `OperationNotAllow`
+
+| # | Code thực tế | Root cause | Fix |
+|---|---|---|---|
+| 1 | App player: `masterPlayer.getPlayerInformationAsync(otherUserId)` | Secret client không có `otherSelfEnable` cho `masterPlayer.getPlayerInformation` | Backend admin bật `otherSelfEnable` trong GearN Dashboard, hoặc chuyển flow sang server-side |
+| 2 | Script dev: `inventory.admin.setAmountAsync(...)` với secret client thường | Secret không có `adminSelfEnable` cho `inventory.setAmount` | Dùng secret admin qua `overrideSecretKey`, hoặc cấu hình `GNServerSettings.secretKey` = secret admin |
+| 3 | Game server: `GNNetwork.gamePlayer.joinGroupAsync(...)` (route client) | Secret server không có `selfEnable` cho `gamePlayer.joinGroup` | Chuyển sang `GNNetwork.gamePlayer.server.joinGroupAsync(...)` — dùng `serverSelfEnable` |
+| 4 | Backend worker: `gamePlayer.server.changePlayerCurrencyAsync(...)` bỏ `userId` | Route `server`/`admin` yêu cầu `userId` rõ ràng (xem [§ 4](#4-self-vs-other-self-chỉ-áp-dụng-trên-route-client)) | Truyền `userId` target |
+| 5 | Admin tool: `masterPlayer.admin.setPlayerBanAsync(...)` | Secret admin bị backend giới hạn operation đó | Hỏi backend admin bật `adminSelfEnable` cho `masterPlayer.setPlayerBan` trong GearN Dashboard |
+
+### 6.4 Checklist nhanh khi gặp `ReturnCode.OperationNotAllow`
+
+Theo đúng thứ tự:
+
+1. Xác định route đang gọi (`client` / `.server` / `.admin`).
+2. Xác định target là `self` hay `other-self` (xem [§ 4](#4-self-vs-other-self-chỉ-áp-dụng-trên-route-client)).
+3. Tra bảng § 6.1 → ra flag cần (ví dụ `otherSelfEnable`).
+4. Check secret key active có flag đó cho operation đang gọi không? → xem backend dashboard hoặc hỏi admin.
+5. Nếu không → 3 option ở § 6.2.
+
+**Không retry** — đây là config fix, không phải transient error.
+
+Diagnose end-to-end với code: [COOKBOOK Scenario 16](COOKBOOK.md#scenario-16-diagnose-operationnotallow).
+
+---
+
+## 7. Auth & Socket flow
+
+Flow chuẩn:
+
+```
+1. Login HTTP (GNNetwork.authenticate.loginByXxxAsync) → SDK cache authToken + userId vào StorageService
+2. Nếu app cần realtime: GNNetwork.connectSocket()
+3. Khi socket connect, SDK tự gửi authToken hiện tại cho backend
+4. (Chỉ khi cần) GNNetwork.sendRequestAuthSocket() — re-auth thủ công, không reconnect
+```
+
+Rule cứng:
+
+- **Không gộp** auth socket với auth HTTP. Socket auth là bước riêng sau HTTP.
+- Không bắt buộc gọi `sendRequestAuthSocket()` sau mỗi `connectSocket()`. SDK auto-auth nếu token đã có.
+- Gọi `sendRequestAuthSocket()` chỉ khi:
+  - Socket connect **trước** khi có `authToken` (login xảy ra sau socket up).
+  - Token vừa đổi và muốn re-auth ngay mà không reconnect socket.
+- Không giả định realtime event tự chạy chỉ vì đã gọi method HTTP friend/group. Phải subscribe handler trong [reference/EVENTS.md](reference/EVENTS.md).
+- Subscribe event handler **trước** `connectSocket()` để không miss event ngay sau handshake.
+
+Helper state:
+
+- `GNNetwork.isSocketConnected()` — check socket session id hiện tại.
+- `GNNetwork.getPing()` — ping trung bình từ active transport.
+- `GNNetwork.syncTs()` — sync local estimate của server timestamp.
+- `GNNetwork.getAuthenticateStatus().getAuthToken() / .getUserId()` — đọc auth cache.
+
+---
+
+## 8. Method signature & override params
+
+Đa số method có 2 form:
+
+```ts
+// Callback
+GNNetwork.<group>.<method>(requestData, onResponse?, overrideAuthToken?, overrideSecretKey?, customTags?, timeout?);
+
+// Async (preferred)
+const res = await GNNetwork.<group>.<method>Async(requestData, overrideAuthToken?, overrideSecretKey?, customTags?, timeout?);
+```
+
+### 8.1 Build request DTO trong code copy-paste
+
+- Code tích hợp cuối cùng nên tạo instance DTO public: `const request = new <Group>Models.<Method>RequestData();`.
+- Set field trên instance đó rồi truyền vào `*Async(request)`.
+- Không dùng object literal rồi cast sang `RequestData`; pattern đó bỏ qua constructor/decorator và dễ làm AI sinh payload thiếu shape.
+- API reference có thể dùng tên biến `requestData` để rút gọn bảng method, nhưng guide/cookbook copy-paste phải dùng DTO instance cụ thể.
+
+| Param | Khi nào cần |
+|---|---|
+| `overrideAuthToken: string` | Impersonate / multi-session / admin thao tác trên user khác mà không dùng auth cache hiện tại |
+| `overrideSecretKey: string` | Override secret cho 1 request, ví dụ migration tool gọi `.admin` từ script ngoài |
+| `customTags: GNHashtable` | Tag trace id, build version, A/B bucket — backend có thể log/route |
+| `timeout: number` | Override `defaultTimeoutInSeconds` per-request (giây) |
+
+Ví dụ `customTags`:
+
+```ts
+const tags = GNHashtable.builder()
+  .add("traceId", "trace-001")
+  .add("build", "qa")
+  .build();
+```
+
+---
+
+## 9. Platform & transport
+
+- Node ≥ 20. Custom DTO có decorator cần bật `experimentalDecorators` + `emitDecoratorMetadata`.
+- `MessageType.MsgPack` + HTTP trên browser → SDK tự fallback JSON. Không cần override toàn SDK sang `MessageType.Json`.
+- Cocos Creator: giữ 2 flag TS decorator nêu trên khi có custom DTO.
+- Detect platform runtime: `GNSupport.getPlatformType()`.
+
+---
+
+## 10. Anti-patterns & pitfalls
+
+Bảng hợp nhất — cột "Triệu chứng" mô tả lỗi runtime thường thấy, cột "Fix" là hành động đúng.
+
+| # | Anti-pattern | Triệu chứng | Fix |
+|---|---|---|---|
+| 1 | Giả định success là `0` | So sánh `=== 0` luôn false, code tưởng fail | `Ok === 1` cả `ReturnCode` và `ErrorCode`. So sánh bằng enum symbol. |
+| 2 | Skip tầng 1, đọc thẳng `errorCode` | Business code branching nhầm vì `errorCode` chưa valid | Check `returnCode !== Ok` **trước**, return sớm. |
+| 3 | Dùng getter `res.getReturnCode()` | `undefined is not a function` trên typed response | Typed response dùng PUBLIC FIELDS. Getter chỉ trên raw `OperationResponse`. |
+| 4 | Gọi API trước `GNNetwork.init()` | `TypeError`, namespace `undefined` | Init 1 lần ở bootstrap. Idempotent — không re-init để đổi config. |
+| 5 | Re-init để đổi config | Config cũ vẫn active | `init()` idempotent; restart process mới đổi được. |
+| 6 | Dùng `.server` / `.admin` từ frontend để vượt permission | Trust boundary leak, secret expose | Route là trust boundary của **caller**, không phải target ownership. |
+| 7 | Tự gọi `sendRequestAuthSocket()` sau mọi `connectSocket()` | Redundant call, có thể gây re-auth loop | SDK auto-auth nếu token có. Chỉ gọi tay khi token đến sau socket up hoặc token vừa đổi. |
+| 8 | Subscribe event SAU `connectSocket()` | Miss event ngay sau handshake | Subscribe handler trước, rồi mới connect. |
+| 9 | `editFunctionAsync` (CloudScript) để sửa source code | Source không đổi, chỉ flag thay | Đổi source = `addFunctionAsync` tạo version mới. |
+| 10 | `MultiplayerApi` gửi qua socket | Không reach backend | Multiplayer dùng HTTP. Flow: create ticket → poll `getMatchmakingTicket` → `getMatch`. |
+| 11 | `infoRequestParam = null` trong login | Backend không hydrate gì cả | Truyền instance dù chỉ bật ít field. |
+| 12 | Bulk-set mọi field của `infoRequestParam` | Payload bự, slow | Chỉ bật field thật sự render. |
+| 13 | Browser + `MessageType.MsgPack` → override toàn SDK sang JSON | Over-engineering | HTTP transport auto-fallback JSON; giữ MsgPack là ok. |
+| 14 | `OperationNotAllow` = thiếu secret | Fix sai hướng, thay secret vô nghĩa | Xem § 5: secret hợp lệ nhưng permission rule cấm. |
+| 15 | Bịa method / field không có trong `dist/*.d.ts` | Compile fail hoặc runtime `undefined` | Tra `API_<GROUP>.md` / `dto/<DOMAIN>.md` / `dist/*.d.ts`. Không suy diễn. |
+| 16 | Giả định realtime tự chạy sau HTTP call | Không nhận event | Phải subscribe handler trong [reference/EVENTS.md](reference/EVENTS.md). |
+| 17 | Bỏ qua `overrideAuthToken` / `overrideSecretKey` / `customTags` / `timeout` khi cần | Impersonate fail, timeout mặc định không đủ | Xem § 8. |
+| 18 | Dùng `src/` làm nguồn public contract | Phụ thuộc internal, rot nhanh | `src/` chỉ khi sửa SDK / debug nội bộ. |
+
+---
+
+## 11. Canonical sources (thứ tự ưu tiên)
+
+Khi có conflict, tách theo loại thông tin:
+
+- Rule cross-cutting (route, permission, socket, error): **RULES.md thắng**.
+- Method signature, DTO, enum: **API reference / DTO reference / ENUMS.md thắng**, fallback cuối là `dist/*.d.ts`.
+- Bundle generated như `llms-full.txt` không bao giờ thắng source docs.
+
+Khi sinh code:
+
+1. **API reference theo domain** (`docs/reference/API_<GROUP>.md`) — method signature, request DTO, async form, response class.
+2. **Guide theo domain** (`docs/guides/<GROUP>.md`) — decision rules, gotchas domain-specific.
+3. **RULES.md** (file này) + [ai-manifest.json](ai-manifest.json) — rule cross-cutting.
+4. **DTO field table** (`docs/reference/dto/<DOMAIN>.md` hoặc grep `DTO_INDEX.md`) — field-level schema.
+5. **ENUMS.md** — giá trị numeric.
+6. **`dist/*.d.ts`** — fallback nếu docs chưa cover.
+
+Chỉ đọc `src/` khi:
+- Sửa chính SDK.
+- Debug behavior nội bộ.
+- Verify public contract mà docs + `dist` chưa đủ.
+
+---
+
+## Liên kết
+
+- [AI_CHEATSHEET.md](AI_CHEATSHEET.md) — one-page reference
+- [COOKBOOK.md](COOKBOOK.md) — 16 scenario end-to-end
+- [reference/API_INDEX.md](reference/API_INDEX.md) — bảng method mọi group
+- [reference/ERROR_HANDLING.md](reference/ERROR_HANDLING.md) — full return/error code table
+- [reference/EVENTS.md](reference/EVENTS.md) — realtime event handler
+- [reference/CONFIG.md](reference/CONFIG.md) — `GNServerSettings` schema
+- [reference/ENUMS.md](reference/ENUMS.md) — enum numeric value
+- [ai-manifest.json](ai-manifest.json) — machine-readable manifest