# TT01 — Quy tắc tích hợp cho Dev Tool (C# Executable) **Version:** 1.0 · **Updated:** 2026-06-10 · **Audience:** C# developer maintaining the executable test runner --- ## 1. Tổng quan hệ thống ``` ┌─────────────┐ 1. Login + lấy app token ┌──────────────────────────┐ │ CMS Web │ ────────────────────────────▶│ tt01.goseedup.com │ │ (User) │ │ (Workflow Builder + CMS)│ └─────────────┘ └────────────┬─────────────┘ │ 2. Save .jtt01 ▼ ┌─────────────┐ 3. Read .jtt01 file ┌──────────────────────────┐ │ C# App │ ◀───────────────────────────│ Local file system │ │ (Runner) │ └──────────────────────────┘ └──────┬──────┘ │ 4. POST /api/commands + Bearer token ▼ ┌──────────────────────────┐ 5. ADB commands ┌──────────────────────────┐ │ api-tt01.goseedup.com │ ─────────────────▶│ C# parse + execute │ │ (Backend API) │ │ via ADB shell │ └──────────────────────────┘ └────────┬─────────────────┘ │ 6. Log result ▼ ┌──────────────────────────┐ │ POST /api/runs/finish │ │ (CMS API endpoint) │ └──────────────────────────┘ ``` **3 service C# cần biết:** | Service | Base URL | Purpose | |---------|----------|---------| | **CMS API** | `https://tt01.goseedup.com/api` | Test cases, test runs CRUD | | **Backend API** | `https://api-tt01.goseedup.com/api` | `.jtt01` → ADB commands | | **Web CMS** | `https://tt01.goseedup.com` | User UI (không phải concern của C#) | --- ## 2. Authentication ### 2.1 Phase 0 (hiện tại) — Bearer Secret C# cấu hình **1 secret duy nhất** trong app.config / appsettings.json: ```json { "TT01": { "ApiBaseUrl": "https://tt01.goseedup.com", "BackendBaseUrl": "https://api-tt01.goseedup.com", "ApiKey": "" } } ``` > ⚠️ **API key được phát hành riêng cho team C# qua kênh nội bộ** (Slack/email mã hoá, KHÔNG public). > Liên hệ admin: `hello@goseedup.com` để nhận key. > KHÔNG commit key vào git. Phase 1 sẽ self-service generate trong CMS Settings → API Tokens. **Mọi request** gắn header: ``` Authorization: Bearer ``` ### 2.2 Phase 1 (tương lai, ~Q3) — Per-user Tokens Khi SaaS launch, mỗi user sẽ generate token riêng từ CMS: ``` CMS → Settings → API Tokens → "+ Token mới" Tên: "Production runner" Scope: ☑ read:testcases ☑ write:runs Token: tt01_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (chỉ hiện 1 lần) ``` C# app **không hardcode** — sẽ: - Hiện UI input cho user paste token lần đầu - Lưu vào Windows Credential Manager (an toàn) - Token có scope → giới hạn quyền (vd: chỉ đọc testcase, không xoá) → Khi migrate, format token bắt đầu bằng prefix `tt01_` để C# có thể detect và parse khác. ### 2.3 Quy tắc bảo mật | Quy tắc | Lý do | |---------|-------| | **KHÔNG hardcode key trong source code commit lên git** | Token leak → server bị abuse | | **KHÔNG log token vào file/console** | Đọc log = chiếm session | | **KHÔNG gắn token vào URL query string** | Browser history + access log leak | | **HTTPS bắt buộc** — block HTTP | Plaintext token trên mạng | | **Catch 401/403 → re-prompt user nhập token mới** | Token có thể bị revoke | | **Timeout request 30s** | Tránh treo app khi server chậm | --- ## 3. Endpoints — Backend API (`api-tt01.goseedup.com`) ### 3.1 `POST /api/commands` — Chuyển `.jtt01` → ADB commands **Use case:** User chọn run test → C# đọc `.jtt01` → POST lên API → nhận về list ADB command → execute lần lượt. **Request:** ```http POST /api/commands Authorization: Bearer Content-Type: application/json Accept: application/json { "json_config": { ... toàn bộ nội dung .jtt01 ... } } ``` `json_config` là object thật, không phải string. Parse `.jtt01` thành JSON rồi paste vào. **Response 200 OK:** ```json { "status": "success", "body": [ { "code": "5760d6abad0c4a61fa562d8c73e288e4", "command": "am start -n com.example/.MainActivity", "name": "Start Application", "_node_id": "node1" }, { "code": "7243f8be75253afbadf7477867021f8b", "command": "sleep 2", "name": "Delay", "_node_id": "node2" }, ... ], "category": "data" } ``` C# execute lần lượt theo thứ tự trong array. Mỗi item: - `code` — action code gốc (32-char hex) - `command` — ADB command string thuần text, paste vào `adb shell ...` - `name` — label hiển thị (không phải logic) - `_node_id` — ID để link với log run **Response 401 Unauthorized:** ```json {"success": false, "message": "Invalid token"} ``` **Response 422 Validation:** ```json { "status": "failed", "message": "INPUT_DATA_MISSING", "category": "validate" } ``` **Response 500:** Cache chưa warm → ping `/api/cache/refresh/*` (admin) hoặc báo lỗi. ### 3.2 `POST /api/commands/dry-run` — Validate trước khi chạy **Use case:** Trước khi execute thật, check xem tất cả action trong .jtt01 có ADB command tương ứng không. **Request:** giống `/api/commands`. **Response:** ```json { "status": "success", "body": { "ready": true, "total": 8, "missing": [], "warnings": [] } } ``` `ready: false` + `missing: [...]` → có action thiếu command → STOP, hiện dialog cho user. C# **bắt buộc** call `dry-run` trước `commands` mỗi lần. Tránh fail giữa chừng. ### 3.3 `GET /api/cache/status` — Healthcheck ```json { "status": "success", "body": { "action": {"exists": true, "count": 20}, "command": {"exists": true, "count": 35}, "version": {"exists": true, "count": 7}, "ttl_seconds": 300, "ready": true } } ``` `ready: false` → backend chưa load data, retry sau 30s. --- ## 4. Endpoints — CMS API (`tt01.goseedup.com/api`) ### 4.1 `POST /api/runs/start` — Bắt đầu run Gọi TRƯỚC khi execute để tạo record trong DB. **Request:** ```http POST /api/runs/start Authorization: Bearer Content-Type: application/json { "testcase_code": "abc123def456", "device": "Samsung_SM-A515F_R58M123", "package_name": "com.example.app", "version_code": "1.2.3" } ``` **Response 200:** ```json { "run_id": 1234, "status": "running" } ``` **Lưu `run_id` vào local memory** — cần để gọi `/finish`. ### 4.2 `POST /api/runs/{run_id}/finish` — Kết thúc run ```http POST /api/runs/1234/finish Authorization: Bearer Content-Type: application/json { "status": "passed", // passed | failed | skipped "result_log": "[2026-06-10 10:00:01] node1 OK\n[2026-06-10 10:00:03] node2 OK\n...", "duration_ms": 12500 } ``` **Quy tắc QUAN TRỌNG:** - `finish` **luôn phải gọi**, kể cả khi test fail/crash → `status: failed` - Nếu C# crash giữa chừng và không kịp finish → server có cron quét runs > 1h ở status=running → auto mark failed (server-side safety net) - `result_log` tối đa 1 MB. Truncate phần đầu nếu vượt. ### 4.3 `GET /api/runs/{run_id}` — Xem detail run Optional, chỉ dùng nếu C# muốn verify đã ghi nhận đúng. --- ## 5. Quy trình chuẩn (Reference Implementation) ```csharp public async Task ExecuteTestCase(string jtt01Path, string device, string packageName, string versionCode) { var jtt01Content = await File.ReadAllTextAsync(jtt01Path); var jtt01Json = JsonNode.Parse(jtt01Content); // 1. Dry-run check var dryRun = await _api.PostAsync( $"{_config.BackendBaseUrl}/api/commands/dry-run", new { json_config = jtt01Json }); if (!dryRun.Ready) throw new TestCaseInvalidException(dryRun.Missing); // 2. Lấy ADB commands var commandsRes = await _api.PostAsync( $"{_config.BackendBaseUrl}/api/commands", new { json_config = jtt01Json }); // 3. Báo CMS: bắt đầu run var startRes = await _api.PostAsync( $"{_config.ApiBaseUrl}/api/runs/start", new { testcase_code = jtt01Json["testcase_code"]!.ToString(), device, package_name = packageName, version_code = versionCode }); int runId = startRes.RunId; // 4. Execute từng command, đảm bảo finish luôn được gọi var log = new StringBuilder(); var stopwatch = Stopwatch.StartNew(); string status = "passed"; try { foreach (var cmd in commandsRes.Body) { log.AppendLine($"[{DateTime.Now:HH:mm:ss}] {cmd.Name}: {cmd.Command}"); var (ok, output) = await RunAdbCommand(cmd.Command); if (!ok) { status = "failed"; log.AppendLine($" ✗ FAILED: {output}"); break; } } } catch (Exception ex) { status = "failed"; log.AppendLine($"EXCEPTION: {ex.Message}"); } finally { // 5. LUÔN gọi finish — kể cả khi crash stopwatch.Stop(); try { await _api.PostAsync($"{_config.ApiBaseUrl}/api/runs/{runId}/finish", new { status, result_log = Truncate(log.ToString(), 1_000_000), duration_ms = stopwatch.ElapsedMilliseconds }); } catch { /* server-side cron sẽ mark failed nếu finish miss */ } } return new TestRunResult { RunId = runId, Status = status }; } ``` --- ## 6. Error Handling ### 6.1 HTTP status codes | Code | Meaning | C# action | |------|---------|-----------| | 200 | OK | Parse body | | 401 | Token sai/hết hạn | Re-prompt user nhập token | | 403 | Permission denied (Phase 1 - vượt quota) | Hiện dialog "Vượt quota, upgrade plan" | | 404 | Resource không tồn tại | Hiện "Test case/run không tìm thấy" | | 422 | Validation failed | Đọc `errors` object, hiện cho user | | 429 | Rate limit (Phase 1) | Wait + retry với exponential backoff | | 500 | Server error | Retry 3 lần delay 1s, 3s, 9s | | 503 | Service unavailable | Maintenance — báo user retry sau | ### 6.2 Retry policy ```csharp async Task WithRetry(Func> action) { for (int attempt = 1; attempt <= 3; attempt++) { try { return await action(); } catch (HttpRequestException ex) when (ex.StatusCode is HttpStatusCode.InternalServerError or HttpStatusCode.BadGateway or HttpStatusCode.ServiceUnavailable) { if (attempt == 3) throw; await Task.Delay(TimeSpan.FromSeconds(Math.Pow(3, attempt))); // 3s, 9s } } throw new Exception("Unreachable"); } ``` **KHÔNG retry** 4xx — đó là lỗi từ phía client, retry vô nghĩa. ### 6.3 Network/offline C# **phải handle gracefully:** - Network mất → hiện banner "Mất kết nối, đang retry..." - API down → fallback offline mode? Hoặc block UI với spinner - Timeout 30s → cancel + báo user --- ## 7. Versioning & Backward Compatibility ### 7.1 API version Hiện tại: **v1** (implicit, không có `/v1/` prefix). Phase 1 sẽ thêm prefix → `https://api-tt01.goseedup.com/api/v2/commands`. C# nên config version qua appsettings để switch dễ: ```json "BackendBaseUrl": "https://api-tt01.goseedup.com/api" ``` ### 7.2 `.jtt01` format version File `.jtt01` có field `version.id` (UUID của Version). Server check version còn được support không. - Nếu deprecated → 422 với message hướng dẫn re-export từ CMS - C# **không tự parse logic** của `.jtt01` — gửi nguyên về server, server làm sạch ### 7.3 Action code Mỗi action có `code` 32-char hex bất biến. **Không bao giờ thay đổi** kể cả khi rename action. Đây là cam kết của server. C# có thể cache action `code` → friendly name mapping locally để hiện UI đẹp. --- ## 8. Roadmap C# integration ### Phase 0 (giờ — chạy ngay được) - ✅ Bearer secret cho auth - ✅ Endpoints `/api/commands`, `/api/commands/dry-run`, `/api/cache/status` - ✅ Endpoints `/api/runs/start`, `/api/runs/{id}/finish` - ⚠️ Chưa có rate limit - ⚠️ Chưa có quota per user ### Phase 1 (Q3 — SaaS launch) - 🔜 Per-user Sanctum tokens (token bắt đầu `tt01_`) - 🔜 Rate limit: 100 req/min/token - 🔜 Quota: theo plan (Free 50 runs/month, Solo 2000, ...) - 🔜 API version prefix `/v2/` - 🔜 Webhook notification (optional — server push results về C#) ### Phase 2 (Q4 — Enterprise) - 🔜 mTLS cho enterprise - 🔜 SAML SSO → token issued via SAML assertion - 🔜 Audit log API — C# có thể query "ai gọi lúc nào" --- ## 9. Liên hệ & report bug - **Bug API:** Tạo issue trong repo `be-tt01` hoặc message Thanh - **Slack:** #tt01-integration - **Hotline kỹ thuật:** xem trong CMS Settings **Khi report bug, đính kèm:** 1. `run_id` (nếu liên quan run) 2. Request body (xoá token trước) 3. Response body 4. Timestamp UTC 5. C# version + Windows version --- ## Appendix A — Postman/Insomnia collection File `tt01-api.postman_collection.json` (sẽ release riêng) chứa tất cả endpoint với example. ## Appendix B — Changelog | Version | Date | Changes | |---------|------|---------| | 1.0 | 2026-06-10 | Initial spec — Phase 0 bearer auth |