@xmobitea/gn-typescript-client 2.6.13 → 2.6.14

package/docs/guides/CONTENT.md

@@ -0,0 +1,291 @@
+# ContentApi
+
+Tài liệu này dành cho AI code assistant và AI agent nội bộ. Mục tiêu là chọn đúng namespace `client/server/admin`, truyền đúng payload cho `GNNetwork.content*`, và không sinh sai sequence ở flow upload/download file.
+
+## 1. Scope
+
+- Áp dụng cho:
+  - `GNNetwork.content`
+  - `GNNetwork.content.server`
+  - `GNNetwork.content.admin`
+- Toàn bộ method hiện tại của `ContentApi` đều gửi qua HTTP.
+- `ContentApi` có đủ 3 role thật:
+  - `GNNetwork.content` -> `RequestRole.Client`
+  - `GNNetwork.content.server` -> `RequestRole.Server`
+  - `GNNetwork.content.admin` -> `RequestRole.Admin`
+- Nếu không truyền `overrideSecretKey`, SDK sẽ tự lấy secret key theo role tương ứng.
+- Chỉ dùng namespace `.server` khi bạn đã cấu hình `secretKey` với `permission rules` `server` hợp lệ trong `GNServerSettings`, hoặc chủ động truyền `overrideSecretKey`.
+- Chỉ dùng namespace `.admin` khi bạn đã cấu hình `secretKey` với `permission rules` `admin` hợp lệ trong `GNServerSettings`, hoặc chủ động truyền `overrideSecretKey`.
+- Rule chuẩn để chọn `client/server/admin` và hiểu semantics permission xem [RULES](../RULES.md#3-route--trust-boundary-của-caller). Với nhóm này, không tự suy diễn route chỉ từ target ownership.
+- Payload shape giữa `client`, `server`, `admin` của cùng một operation là giống nhau; khác biệt chính là role.
+- `ContentApi` không upload byte trực tiếp. Nó chỉ quản lý metadata và token cho flow file; phần upload byte thật đi qua `GNNetwork.uploadFileAsync(...)`.
+
+## 2. Hard Rules
+
+- Luôn ưu tiên `async/await`. Mặc định dùng `*Async()`.
+- Bắt buộc đã `GNNetwork.init(settings)` trước khi gọi.
+- Không dùng socket cho `ContentApi`.
+- Chọn namespace theo đúng role của actor hiện tại. Không gọi nhầm `client` khi bạn đang sinh code cho server job hoặc admin tool.
+- Flow upload file đúng là:
+  1. `createNewFileUploadInfoAsync(...)`
+  2. lấy `fileId` từ response
+  3. `GNNetwork.uploadFileAsync(fileId, bytes, filename, mimetype)`
+- Flow download file đúng là:
+  1. `requestDownloadFileUploadInfoAsync(...)`
+  2. lấy `downloadToken` từ response
+  3. `GNNetwork.getDownloadFileUrl(downloadToken)`
+- `setContentDataAsync(...)` bắt buộc có `configs`.
+- `removeFileUploadInfoAsync(...)` là thao tác mutate/xóa metadata file. Chỉ gọi khi có chủ đích rõ ràng.
+
+## 3. Chọn Namespace
+
+| Namespace | Role thật | Dùng khi nào |
+| --- | --- | --- |
+| `GNNetwork.content` | `Client` | | flow từ client/player app |
+| `GNNetwork.content.server` | `Server` | | server worker, backend integration, trusted service |
+| `GNNetwork.content.admin` | `Admin` | | dashboard, backoffice, tooling quản trị |
+
+Rule nhanh:
+
+- Nếu code chạy trong game client: ưu tiên `GNNetwork.content`.
+- Nếu code chạy ở trusted backend hoặc worker: ưu tiên `GNNetwork.content.server`.
+- Nếu code chạy ở dashboard/tool vận hành: ưu tiên `GNNetwork.content.admin`.
+- Chỉ dùng `overrideSecretKey` khi bạn cố ý override hành vi mặc định theo role.
+
+## 4. Chọn Method
+
+| Method | Dùng khi nào | Cần truyền gì | Nhận được gì | Ghi chú | ErrorCode
+| --- | --- | --- | --- | --- | --- |
+| `getContentDataAsync` | Đọc content config theo key hoặc label | `keys?`, `label?` | `GetContentDataResponseData` | Dùng cho config/content data, không phải file binary | `Ok`, `GameNotFound` |
+| `setContentDataAsync` | Tạo hoặc cập nhật content config | `configs`, `label?` | `EmptyResponseData` | Mỗi config cần `key` và `data` | `Ok`, `GameNotFound` |
+| `createNewFileUploadInfoAsync` | Xin cấp `fileId` cho một file sẽ upload | `fileName` | `FileIdUploadResponseData` | Không upload byte ở bước này | `Ok` |
+| `getFileUploadInfoListAsync` | Liệt kê metadata file upload | `skip?`, `limit?` | `GetFileUploadInfoListResponseData` | Phân trang mềm | `Ok` |
+| `getFileUploadInfoAsync` | Xem chi tiết metadata của một file | `fileId` | `GetFileUploadInfoResponseData` | Trả cả `removeStatus`, `tsUploadExpire`, `fileUpload?` | `Ok`, `FileNotFound` |
+| `removeFileUploadInfoAsync` | Gỡ metadata hoặc đánh dấu remove cho file | `fileId`, `reason?` | `EmptyResponseData` | Không phải API upload delete byte trực tiếp | `Ok`, `FileNotFound` |
+| `requestDownloadFileUploadInfoAsync` | Xin download token cho file | `fileId` | `RequestDownloadFileUploadInfoResponseData` | Dùng tiếp với `GNNetwork.getDownloadFileUrl(...)` | `Ok`, `FileNotFound`, `FileNotUpload` |
+
+## 5. Decision Rules
+
+- Cần config dạng key/value structured: dùng `getContentDataAsync` hoặc `setContentDataAsync`.
+- Cần upload file mới: dùng `createNewFileUploadInfoAsync` trước, sau đó `GNNetwork.uploadFileAsync`.
+- Cần liệt kê file đã có: dùng `getFileUploadInfoListAsync`.
+- Cần inspect một file cụ thể: dùng `getFileUploadInfoAsync`.
+- Cần cấp link download: dùng `requestDownloadFileUploadInfoAsync`, không tự ghép URL thủ công từ `fileId`.
+- Cần bỏ metadata file: dùng `removeFileUploadInfoAsync`.
+- Cần thao tác cùng operation nhưng khác quyền: giữ nguyên tên method, đổi namespace cho đúng role.
+
+## 6. Request Rules và Reference
+
+- DTO fields: [reference/dto/CONTENT.md](../reference/dto/CONTENT.md). Method table: [reference/API_CONTENT.md](../reference/API_CONTENT.md).
+- Fallback `dist` chỉ khi reference docs chưa đủ: `dist/runtime/entity/models/Content*.d.ts`.
+- `GetContentDataRequestData.keys` là optional.
+  - Suy luận từ model: nếu bỏ `keys`, backend có thể trả tập content rộng hơn theo `label` hoặc default scope.
+  - Nếu backend spec không chốt rõ hành vi này, AI không được tự mặc định lấy toàn bộ content.
+- `GetContentDataRequestData.label` là optional và có `defaultValue: ""`.
+- `SetContentDataRequestData.configs` là mảng bắt buộc.
+- `ContentDataParam.key` là bắt buộc.
+- `GetFileUploadInfoListRequestData.limit` mặc định `10`, min `1`, max `100`.
+- `GetFileUploadInfoRequestData.fileId`, `RemoveFileUploadInfoRequestData.fileId`, `RequestDownloadFileUploadInfoRequestData.fileId` đều yêu cầu đúng độ dài `15`.
+- `CreateNewFileUploadInfoRequestData.fileName` là bắt buộc, min `5`, max `50`.
+
+## 7. Upload và Download Sequence
+
+### Upload
+
+1. Gọi `createNewFileUploadInfoAsync` để xin `fileId`.
+2. Gọi `GNNetwork.uploadFileAsync(fileId, bytes, filename, mimetype)` để upload nội dung thật.
+3. Nếu cần kiểm tra lại metadata sau upload, gọi `getFileUploadInfoAsync`.
+
+### Download
+
+1. Gọi `requestDownloadFileUploadInfoAsync` với `fileId`.
+2. Lấy `downloadToken` từ response.
+3. Gọi `GNNetwork.getDownloadFileUrl(downloadToken)` để tạo URL download.
+
+Rule cứng:
+
+- Không gọi `GNNetwork.uploadFileAsync` trước khi có `fileId`.
+- Không tự tạo download URL từ `fileId`.
+- Không nhầm `getContentDataAsync` với file download; đây là 2 loại dữ liệu khác nhau.
+
+## 8. Response Rules
+
+Tất cả typed response của `ContentApi` đều có:
+
+- `returnCode`
+- `debugMessage`
+- `invalidMembers`
+- `errorCode`
+- `responseData`
+
+Rule kiểm tra response:
+
+```ts
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+```
+
+Những response chính AI cần nhớ:
+
+- `createNewFileUploadInfoAsync` trả `responseData.fileId`.
+- `getContentDataAsync` trả `responseData.configs`.
+- `getFileUploadInfoListAsync` trả `responseData.results`.
+- `getFileUploadInfoAsync` trả `fileName`, `tsCreate`, `removeStatus`, `tsUploadExpire?`, `fileUpload?`.
+- `requestDownloadFileUploadInfoAsync` trả `responseData.downloadToken`.
+- `setContentDataAsync` và `removeFileUploadInfoAsync` trả `EmptyResponseData`.
+
+## 9. Best Practices
+
+- Chọn đúng namespace ngay từ đầu để SDK tự chọn đúng secret key.
+- Với `getContentDataAsync`, truyền `keys` cụ thể nếu bạn biết mình cần gì.
+- Với `setContentDataAsync`, chỉ gửi những config thật sự muốn cập nhật.
+- Sau `createNewFileUploadInfoAsync`, dùng luôn `fileId` vừa nhận để upload; không cache lỏng lẻo qua nhiều bước nếu không cần.
+- Với `getFileUploadInfoListAsync`, giữ `limit` nhỏ và phân trang dần.
+- Với `removeFileUploadInfoAsync`, truyền `reason` nếu workflow của bạn cần audit rõ lý do.
+
+## 10. Ví dụ Khuyến Nghị
+
+### Client đọc content theo key
+
+```ts
+import {
+    GNNetwork,
+    ContentModels,
+    ErrorCode,
+} from "@xmobitea/gn-typescript-client";
+
+const request = new ContentModels.GetContentDataRequestData();
+request.keys = ["homepage", "shop"];
+request.label = "public";
+
+const response = await GNNetwork.content.getContentDataAsync(request);
+
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+
+const configs = response.responseData.configs;
+```
+
+### Server set content data
+
+```ts
+import {
+    GNHashtable,
+    GNNetwork,
+    ContentModels,
+    ErrorCode,
+} from "@xmobitea/gn-typescript-client";
+
+const config = new ContentModels.ContentDataParam();
+config.key = "maintenance";
+config.data = GNHashtable.builder()
+    .add("enabled", true)
+    .add("message", "Server maintenance at 22:00")
+    .build();
+
+const request = new ContentModels.ServerSetContentDataRequestData();
+request.configs = [config];
+request.label = "ops";
+
+const response = await GNNetwork.content.server.setContentDataAsync(request);
+
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+```
+
+### Upload file đúng sequence
+
+```ts
+import {
+    GNNetwork,
+    ContentModels,
+    ErrorCode,
+} from "@xmobitea/gn-typescript-client";
+
+const createRequest = new ContentModels.CreateNewFileUploadInfoRequestData();
+createRequest.fileName = "banner.png";
+
+const createResponse = await GNNetwork.content.createNewFileUploadInfoAsync(createRequest);
+
+if (createResponse.hasReturnCodeError()) {
+    throw new Error(createResponse.debugMessage);
+}
+
+if (createResponse.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${createResponse.errorCode}`);
+}
+
+const fileId = createResponse.responseData.fileId;
+const bytes = new Uint8Array([1, 2, 3]);
+
+const uploadResponse = await GNNetwork.uploadFileAsync(
+    fileId,
+    bytes,
+    "banner.png",
+    "image/png",
+);
+
+if (uploadResponse.error) {
+    throw new Error(uploadResponse.error);
+}
+```
+
+### Xin download URL từ fileId
+
+```ts
+import {
+    GNNetwork,
+    ContentModels,
+    ErrorCode,
+} from "@xmobitea/gn-typescript-client";
+
+const request = new ContentModels.RequestDownloadFileUploadInfoRequestData();
+request.fileId = "123456789012345";
+
+const response = await GNNetwork.content.requestDownloadFileUploadInfoAsync(request);
+
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+
+const url = GNNetwork.getDownloadFileUrl(response.responseData.downloadToken);
+```
+
+## 11. Anti-Patterns
+
+- Không gọi `GNNetwork.uploadFileAsync` trước khi có `fileId`.
+- Không dùng `getContentDataAsync` để đọc file binary.
+- Không tự ghép URL download từ `fileId`.
+- Không gọi nhầm namespace role.
+- Không request `getContentDataAsync` không giới hạn nếu bạn chưa chắc backend sẽ trả bao nhiêu dữ liệu.
+- Không bỏ qua kiểm tra `returnCode` và `errorCode`.
+- Không dùng callback style mặc định khi codebase đã support `async/await`.
+
+## 12. AI Checklist
+
+- Đã `GNNetwork.init(settings)` chưa.
+- Có chọn đúng namespace `content` / `content.server` / `content.admin` chưa.
+- Có nhớ rằng `ContentApi` chỉ đi qua HTTP không.
+- Nếu đang upload file, đã gọi `createNewFileUploadInfoAsync` trước chưa.
+- Nếu đang download file, có dùng `requestDownloadFileUploadInfoAsync` rồi `getDownloadFileUrl(...)` chưa.
+- Nếu đang set content, `configs` đã có đầy đủ `key` và `data` chưa.
+- Có kiểm tra `hasReturnCodeError()` trước `errorCode` chưa.

package/docs/guides/DASHBOARD.md

@@ -0,0 +1,262 @@
+# DashboardApi
+
+Tài liệu này dành cho AI code assistant và AI agent nội bộ. Mục tiêu là chọn đúng method của `GNNetwork.dashboard`, truyền đúng input, hiểu đúng scope quản trị của nhóm này và không sinh code sai secret key.
+
+## 1. Scope
+
+- Chỉ áp dụng cho `GNNetwork.dashboard`.
+- Không áp dụng cho `GNNetwork.dashboard.server` và `GNNetwork.dashboard.admin` vì hiện tại 2 namespace này rỗng, không có method public.
+- Toàn bộ method hiện tại của `DashboardApi` đều gửi qua HTTP.
+- Toàn bộ request wrapper hiện tại của `DashboardApi` đều dùng `RequestType.Dashboard` với `RequestRole.Client`.
+- Hệ quả rất quan trọng ở tầng SDK: nếu không truyền `overrideSecretKey`, request sẽ mặc định gắn `secretKey`
+- Rule chuẩn để chọn `client/server/admin` và hiểu semantics permission xem [RULES](../RULES.md#3-route--trust-boundary-của-caller), nhưng `DashboardApi` là ngoại lệ vì public SDK wrapper này vẫn đi qua `RequestRole.Client`.
+- Trong triển khai GearN Server hiện tại, sau `loginByAdminAccountAsync` thành công backend middleware sẽ resolve secret context và quyền riêng của admin từ `authToken` cho các request dashboard tiếp theo.
+- Đây là nhóm API dành cho dashboard, backoffice, provisioning, analytics và maintenance. Không dùng thay cho gameplay API của player.
+- Nếu cần login player, dùng `AuthenticateApi`. Nếu cần data/player runtime, dùng group tương ứng khác.
+
+## 2. Hard Rules
+
+- Luôn ưu tiên `async/await`. Mặc định dùng `GNNetwork.dashboard.*Async()`.
+- Bắt buộc đã `GNNetwork.init(settings)` trước khi gọi.
+- Không dùng `GNNetwork.dashboard.server.*` hoặc `GNNetwork.dashboard.admin.*` vì hiện chưa có method nào để gọi.
+- Với triển khai GearN Server hiện tại, quyền admin riêng của account sau login được backend middleware resolve từ `authToken`, không phải do SDK tự đổi sang admin secret key local.
+- Chỉ truyền `overrideSecretKey` khi bạn cố ý bypass flow mặc định ở trên.
+- `DashboardApi` không có flow socket. Không dùng `connectSocket()` hay `sendRequestAuthSocket()` cho nhóm này.
+- `loginByAdminAccountAsync` là entrypoint hợp lý để lấy admin auth token trước khi gọi các operation quản trị khác.
+- `loginByAdminAccountAsync` chỉ trả `authToken`. Không giả định response có `userId`.
+- `deleteInDatabaseAsync` và `resetStatisticsLeaderboardAsync` là operation phá hủy hoặc reset dữ liệu. Chỉ dùng khi có chủ đích vận hành rõ ràng.
+
+## 3. Chọn Method
+
+### Auth và quản trị admin account
+
+| Method | Dùng khi nào | Cần truyền gì | Nhận được gì | Ghi chú | ErrorCode
+| --- | --- | --- | --- | --- | --- |
+| `loginByAdminAccountAsync` | Login dashboard/admin tool | `username`, `password` | `LoginByAdminAccountResponseData` | Response chỉ có `authToken` | `Ok`, `AccountNotFound` |
+| `changePasswordAdminAccountAsync` | Admin hiện tại tự đổi mật khẩu của chính mình | `currentPassword`, `password` | `EmptyResponseData` | Nên dùng sau khi đã login | `Ok`, `AccountNotFound` |
+| `getAdminAccountListAsync` | Liệt kê admin account | request rỗng | `GetAdminAccountListResponseData` | Dùng cho màn hình quản trị account | `Ok` |
+| `createAdminAccountAsync` | Tạo admin account mới | `username`, `password`, `secretKey` | `CreateAdminAccountResponseData` | Response trả danh sách `userId` tạo ra | `Ok`, `AccountUsernameExists` |
+| `getUsernameAdminAccountAsync` | Tìm username từ `userId` admin | `userId` | `GetUsernameAdminAccountResponseData` | Dùng khi chỉ có `userId` | `Ok`, `AccountNotFound` |
+| `setPasswordAdminAccountAsync` | Đặt lại mật khẩu cho admin khác | `userId`, `password` | `EmptyResponseData` | Không dùng cho self-service đổi mật khẩu | `Ok`, `AccountNotFound` |
+| `setSecretKeyAdminAccountAsync` | Gán hoặc đổi secret key của admin account | `userId`, `secretKey` | `EmptyResponseData` | Thao tác nhạy cảm | `Ok`, `AccountNotFound`, `SecretInfoNotFound` |
+| `removeAdminAccountAsync` | Xóa admin account | `userId` | `EmptyResponseData` | Destructive | `Ok`, `AccountNotFound` |
+
+### Quản lý game và cấu hình
+
+| Method | Dùng khi nào | Cần truyền gì | Nhận được gì | Ghi chú | ErrorCode
+| --- | --- | --- | --- | --- | --- |
+| `getGameListAsync` | Liệt kê game id hiện có | request rỗng | `GetGameListResponseData` | Dùng trước khi chọn `gameId` | `Ok` |
+| `createGameAsync` | Tạo game mới | `gameId` | `GameWithGameIdResponseData` | Chỉ tạo identity cơ bản của game | `Ok`, `GameExists` |
+| `getGameInformationAsync` | Đọc metadata và settings của một game | `gameId` | `GetGameInformationResponseData` | Trả `gameName`, `gameDescription`, `gameSettings`, `matchmakingQueueSettings` | `Ok`, `GameNotFound` |
+| `setGameInformationAsync` | Cập nhật metadata/settings của game | `gameId` và field cần đổi | `EmptyResponseData` | Chỉ set field thật sự cần đổi | `Ok`, `GameNotFound` |
+| `getMasterGameSettingsAsync` | Đọc global settings của server/game platform | request rỗng | `GetMasterGameSettingsResponseData` | Trả `thirtPartySettings`, `masterPlayerSettings`, `emailSettings`, `pushNotificationSettings` | `Ok` |
+| `setMasterGameSettingsAsync` | Cập nhật global settings | hashtable settings cần đổi | `EmptyResponseData` | Không nên gửi full object nếu không cần | `Ok` |
+| `getServerGameDataAsync` | Lấy snapshot số lượng entity và version của một game | `gameId` và các boolean flag cần lấy | `GetServerGameDataResponseData` | Chỉ bật các flag cần thiết để giảm payload | `Ok` |
+
+### Secret key và permission
+
+| Method | Dùng khi nào | Cần truyền gì | Nhận được gì | Ghi chú | ErrorCode
+| --- | --- | --- | --- | --- | --- |
+| `getSecretInfoListAsync` | Liệt kê secret key theo role | request rỗng | `GetSecretInfoListResponseData` | Trả `secretKeys` | `Ok` |
+| `getSecretInfoInformationAsync` | Xem chi tiết một secret key | `secretKey` | `GetSecretInfoInformationResponseData` | Trả `gameId`, `permissionParam`, `tsExpire`, `remove` | `Ok`, `SecretInfoNotFound` |
+| `createSecretInfoAsync` | Tạo secret key mới và tùy chọn `secretKey`, `gameId`, `permissionParam` | `SecretInfoWithSecretKeyResponseData` | `secretKey` đang optional trong model; AI có thể bỏ qua nếu muốn backend sinh key | `Ok`, `SecretInfoExists` |
+| `setSecretInfoInformationAsync` | Cập nhật expire, description, permission hoặc remove flag của secret key | `secretKey` và field cần đổi | `EmptyResponseData` | Dùng để revoke hoặc thay permission | `Ok`, `SecretInfoNotFound` |
+
+### Analytics, logs và callback
+
+| Method | Dùng khi nào | Cần truyền gì | Nhận được gì | Ghi chú | ErrorCode
+| --- | --- | --- | --- | --- | --- |
+| `getAnalyticsAsync` | Lấy analytics tổng hợp | các boolean flag cần lấy, `timestamp?` | `GetAnalyticsResponseData` | Không bật tất cả flag một cách mù quáng | `Ok`, `ItemNotFound` |
+| `getServerLogAsync` | Lấy log server dạng phân trang | `skip?`, `limit?` | `GetServerLogResponseData` | Model mặc định `skip = 0`, `limit = 50` | `Ok` |
+| `getEventCallbackCloudScriptAsync` | Liệt kê callback CloudScript theo event | request rỗng | `GetEventCallbackCloudScriptResponseData` | Dùng để inspect cấu hình hiện tại | `Ok` |
+| `setEventCallbackCloudScriptAsync` | Tạo hoặc sửa callback CloudScript theo event | `eventName`, `script` | `SetEventCallbackCloudScriptResponseData` | Response có `errorMessage` | `Ok`, `ExecuteError` |
+| `getBackupStatisticsLeaderboardVersionAsync` | Liệt kê version backup của leaderboard | `gameId`, `type`, `key` | `GetBackupStatisticsLeaderboardVersionResponseData` | `type` phải lấy từ `OwnerType` | `Ok`, `OwnerNotFound` |
+
+### Maintenance và thao tác phá hủy
+
+| Method | Dùng khi nào | Cần truyền gì | Nhận được gì | Ghi chú | ErrorCode
+| --- | --- | --- | --- | --- | --- |
+| `resetStatisticsLeaderboardAsync` | Reset một version leaderboard | `type`, `key`, `version`, `gameId`, `log?`, `catalogId?` | `EmptyResponseData` | Destructive; chỉ dùng khi operator đã chốt loại leaderboard | `Ok`, `KeyNotFound`, `OwnerTypeNotSupport`, `VersionInvalid` |
+| `deleteInDatabaseAsync` | Xóa dữ liệu trực tiếp theo loại và id | `type`, `id`, `gameId`, `log?` | `EmptyResponseData` | `type` phải lấy từ `OwnerType` | `Ok`, `ItemNotFound` |
+
+## 4. Decision Rules
+
+- Cần login admin: dùng `loginByAdminAccountAsync` trước.
+- Cần đổi mật khẩu của chính admin hiện tại: dùng `changePasswordAdminAccountAsync`.
+- Cần quản lý admin account khác: dùng bộ `getAdminAccountListAsync`, `createAdminAccountAsync`, `getUsernameAdminAccountAsync`, `setPasswordAdminAccountAsync`, `setSecretKeyAdminAccountAsync`, `removeAdminAccountAsync`.
+- Cần tạo game mới: dùng `createGameAsync`, sau đó `setGameInformationAsync` nếu cần metadata/settings.
+- Cần đọc hoặc cập nhật cấu hình global: dùng `getMasterGameSettingsAsync` hoặc `setMasterGameSettingsAsync`.
+- Cần quản lý secret key: bắt đầu từ `getSecretInfoListAsync` hoặc `getSecretInfoInformationAsync`, sau đó mới `createSecretInfoAsync` hoặc `setSecretInfoInformationAsync`.
+- Cần analytics hoặc log: dùng `getAnalyticsAsync`, `getServerLogAsync`, `getServerGameDataAsync` với payload tối giản.
+- Cần callback CloudScript theo event: dùng `getEventCallbackCloudScriptAsync` để inspect trước, rồi `setEventCallbackCloudScriptAsync`.
+- Cần reset leaderboard hoặc xóa dữ liệu: chỉ dùng khi operator đã xác nhận chính xác `type`, `key`, `version`, `id`, `gameId` và hậu quả.
+
+## 5. Request Rules và Reference
+
+- DTO fields: [reference/dto/DASHBOARD.md](../reference/dto/DASHBOARD.md). Method table: [reference/API_DASHBOARD.md](../reference/API_DASHBOARD.md).
+- Enums: [OwnerType](../reference/ENUMS.md#ownertype).
+- Fallback `dist` chỉ khi reference docs chưa đủ: `dist/runtime/entity/models/Dashboard*.d.ts`.
+- `DashboardApi` hiện `type` phải lấy từ `OwnerType` trong `resetStatisticsLeaderboard` hoặc `deleteInDatabase`.
+- Nếu codebase hiện tại không có constant nghiệp vụ cho các numeric field đó, AI không được tự bịa giá trị.
+- `GetServerLogRequestData` có phân trang mềm bằng `skip` và `limit`; không request log vô hạn.
+- `GetAnalyticsRequestData` và `GetServerGameDataRequestData` đều dùng nhiều boolean flag để điều khiển payload; chỉ bật field thật sự cần.
+
+## 6. Response Rules
+
+Tất cả typed response của `DashboardApi` đều có các field low-level giống các nhóm API khác:
+
+- `returnCode`
+- `debugMessage`
+- `invalidMembers`
+- `errorCode`
+- `responseData`
+
+Rule kiểm tra response:
+
+```ts
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+```
+
+Những response quan trọng AI cần nhớ:
+
+- `loginByAdminAccountAsync` trả `LoginByAdminAccountResponseData` với `authToken`.
+- `createAdminAccountAsync` trả `CreateAdminAccountResponseData` chứa danh sách `userId`.
+- `getGameInformationAsync` trả metadata/settings đầy đủ của game.
+- `getMasterGameSettingsAsync` trả các hashtable settings cấp hệ thống.
+- `getSecretInfoListAsync` trả danh sách secret key theo từng role.
+- `setEventCallbackCloudScriptAsync` trả `errorMessage` trong `responseData`; cần kiểm tra nếu backend trả message lỗi nghiệp vụ.
+- Nhiều operation mutate chỉ trả `EmptyResponseData`. Đừng mong đợi payload chi tiết sau khi set/remove/reset/delete.
+
+Ghi chú quan trọng:
+
+- `loginByAdminAccountAsync` có thể giúp SDK cache `authToken`.
+- Trong triển khai GearN Server hiện tại, chính `authToken` này là thứ backend middleware dùng để resolve secret context và quyền riêng của admin cho các request dashboard tiếp theo.
+- Không có bằng chứng từ response model rằng flow này cũng trả `userId`, nên AI không được giả định `GNNetwork.getAuthenticateStatus().getUserId()` sẽ có giá trị mới sau login admin.
+
+## 7. Best Practices
+
+- Với admin/dashboard flow, mặc định login trước rồi mới gọi các operation còn lại.
+- Sau khi login admin thành công, ưu tiên để các request dashboard tiếp theo đi theo `authToken` đã cache thay vì cố tự override secret key.
+- Chỉ truyền `overrideSecretKey` khi bạn cố ý bypass flow middleware mặc định đó.
+- Với analytics và snapshot data, chỉ bật các flag thật sự cần để giảm payload.
+- Với game provisioning, tách `createGameAsync` và `setGameInformationAsync` thành 2 bước rõ ràng.
+- Với secret management, inspect trước bằng `getSecretInfoListAsync` hoặc `getSecretInfoInformationAsync` rồi mới mutate.
+- Với `createSecretInfoAsync`, có thể bỏ qua `secretKey` nếu backend của bạn cho phép sinh tự động; đây là suy luận hợp lý từ model vì field đang optional và response trả lại `secretKey`.
+- Với operation phá hủy dữ liệu, luôn ghi `log` nếu backend/workflow của bạn dùng trường này để audit.
+
+## 8. Ví dụ Khuyến Nghị
+
+### Login admin
+
+```ts
+import {
+    GNNetwork,
+    DashboardModels,
+    ErrorCode,
+} from "@xmobitea/gn-typescript-client";
+
+const request = new DashboardModels.LoginByAdminAccountRequestData();
+request.username = "gnadmin";
+request.password = "123456";
+
+const response = await GNNetwork.dashboard.loginByAdminAccountAsync(request);
+
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+
+const adminAuthToken = GNNetwork.getAuthenticateStatus().getAuthToken();
+```
+
+### Tạo game rồi cập nhật metadata
+
+```ts
+import {
+    GNNetwork,
+    DashboardModels,
+    ErrorCode,
+} from "@xmobitea/gn-typescript-client";
+
+const createRequest = new DashboardModels.CreateGameRequestData();
+createRequest.gameId = "demo-game";
+
+const createResponse = await GNNetwork.dashboard.createGameAsync(createRequest);
+
+if (createResponse.hasReturnCodeError()) {
+    throw new Error(createResponse.debugMessage);
+}
+
+if (createResponse.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${createResponse.errorCode}`);
+}
+
+const updateRequest = new DashboardModels.SetGameInformationRequestData();
+updateRequest.gameId = "demo-game";
+updateRequest.gameName = "Demo Game";
+updateRequest.gameDescription = "Internal demo project";
+
+const updateResponse = await GNNetwork.dashboard.setGameInformationAsync(updateRequest);
+
+if (updateResponse.hasReturnCodeError()) {
+    throw new Error(updateResponse.debugMessage);
+}
+
+if (updateResponse.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${updateResponse.errorCode}`);
+}
+```
+
+### Tạo secret key cho server role
+
+```ts
+import {
+    GNNetwork,
+    DashboardModels,
+    RequestRole,
+    ErrorCode,
+} from "@xmobitea/gn-typescript-client";
+
+const request = new DashboardModels.CreateSecretInfoRequestData();
+request.gameId = "demo-game";
+
+const response = await GNNetwork.dashboard.createSecretInfoAsync(request);
+
+if (response.hasReturnCodeError()) {
+    throw new Error(response.debugMessage);
+}
+
+if (response.errorCode !== ErrorCode.Ok) {
+    throw new Error(`Business error: ${response.errorCode}`);
+}
+
+const generatedSecretKey = response.responseData.secretKey;
+```
+
+## 9. Anti-Patterns
+
+- Không gọi `GNNetwork.dashboard.server` hoặc `GNNetwork.dashboard.admin`.
+- Không bỏ qua bước `loginByAdminAccountAsync` rồi vẫn mong backend tự hiểu request dashboard là admin request.
+- Không dùng `DashboardApi` như gameplay API cho client/player thường.
+- Không gọi `deleteInDatabaseAsync` hoặc `resetStatisticsLeaderboardAsync` nếu chưa có xác nhận vận hành rõ ràng.
+- Không request full analytics/full snapshot nếu chỉ cần một vài metric.
+- Không giả định `loginByAdminAccountAsync` trả `userId`.
+- Không dùng callback style mặc định khi codebase đã support `async/await`.
+
+## 10. AI Checklist
+
+- Đã `GNNetwork.init(settings)` chưa.
+- Có đang dùng đúng `GNNetwork.dashboard.*Async()` không.
+- Có nhớ rằng toàn bộ `DashboardApi` hiện dùng `RequestRole.Client` và HTTP không.
+- Có cần login admin trước khi gọi operation hiện tại không.
+- Nếu operation là destructive, đã có xác nhận rõ về hậu quả chưa.
+- Có kiểm tra `hasReturnCodeError()` trước `errorCode` chưa.