From 2bd7056dde5481c07b09dfe1cc7cb02099412ef0 Mon Sep 17 00:00:00 2001 From: virtus Date: Wed, 29 Apr 2026 23:25:31 +0700 Subject: [PATCH] feat: Add architecture and contract documentation for reader-app, including API standards and cross-repo mapping --- .github/agents/api-contract.agent.md | 33 ---------- .github/agents/backend-security.agent.md | 33 ---------- .../agents/cross-platform-delivery.agent.md | 20 ++++++ .github/agents/mobile-app.agent.md | 32 ---------- .github/agents/sdet-qa.agent.md | 35 ---------- .github/agents/sleuth-debugger.agent.md | 32 ---------- .github/agents/system-architect.agent.md | 33 ---------- .github/agents/web-frontend-nextjs.agent.md | 32 ---------- .github/copilot-instructions.md | 42 ------------ .../prompts/debug-triage-checklist.prompt.md | 22 ------- .../flutter-integration-test-flow.prompt.md | 19 ------ .../prompts/multi-agent-workflow.prompt.md | 27 -------- .../prompts/regression-api-newman.prompt.md | 19 ------ .github/pull_request_template.md | 45 +++++++++++++ ARCHITECTURE.md | 38 +++++++++++ CONTRACT.md | 64 +++++++++++++++++++ CROSS_REPO_ENDPOINT_MATRIX.md | 34 ++++++++++ FEATURES.md | 30 +++++++++ FLOWS.md | 48 ++++++++++++++ SKILLS.md | 23 +++++++ 20 files changed, 302 insertions(+), 359 deletions(-) delete mode 100644 .github/agents/api-contract.agent.md delete mode 100644 .github/agents/backend-security.agent.md create mode 100644 .github/agents/cross-platform-delivery.agent.md delete mode 100644 .github/agents/mobile-app.agent.md delete mode 100644 .github/agents/sdet-qa.agent.md delete mode 100644 .github/agents/sleuth-debugger.agent.md delete mode 100644 .github/agents/system-architect.agent.md delete mode 100644 .github/agents/web-frontend-nextjs.agent.md delete mode 100644 .github/copilot-instructions.md delete mode 100644 .github/prompts/debug-triage-checklist.prompt.md delete mode 100644 .github/prompts/flutter-integration-test-flow.prompt.md delete mode 100644 .github/prompts/multi-agent-workflow.prompt.md delete mode 100644 .github/prompts/regression-api-newman.prompt.md create mode 100644 .github/pull_request_template.md create mode 100644 ARCHITECTURE.md create mode 100644 CONTRACT.md create mode 100644 CROSS_REPO_ENDPOINT_MATRIX.md create mode 100644 FEATURES.md create mode 100644 FLOWS.md create mode 100644 SKILLS.md diff --git a/.github/agents/api-contract.agent.md b/.github/agents/api-contract.agent.md deleted file mode 100644 index 72470ba..0000000 --- a/.github/agents/api-contract.agent.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -name: "API Contract Agent" -description: "Use when: định nghĩa hoặc cập nhật API contract (Swagger/OpenAPI), kiểm soát breaking changes và đồng bộ cập nhật cho web/mobile khi backend thay đổi. Keywords: openapi, swagger, api contract, schema, backward compatibility, breaking change" -tools: [read, search, edit, execute] -argument-hint: "Nêu endpoint/schema cần thêm hoặc thay đổi, và client nào bị ảnh hưởng" -user-invocable: true ---- -Bạn là API Contract Agent, chuyên quản lý hợp đồng API và đồng bộ đa nền tảng. - -## Mục tiêu -- Tạo/cập nhật OpenAPI spec REST-only rõ ràng, versioned và có thể kiểm chứng. -- Cảnh báo sớm breaking changes để web/mobile cập nhật kịp thời. -- Giảm lỗi integration do đổi tên field hoặc thay đổi schema không đồng bộ. - -## Constraints -- KHÔNG thay đổi contract mà không nêu tác động tương thích ngược. -- LUÔN dùng một nguồn spec chuẩn tại reader-api/docs/openapi.yaml. -- KHÔNG bỏ qua phần error model, auth requirements và example payloads. -- LUÔN liệt kê ảnh hưởng tới reader (web) và reader-app (mobile). - -## Approach -1. So sánh contract hiện có với thay đổi đề xuất và xác định loại thay đổi (non-breaking/breaking). -2. Cập nhật spec OpenAPI nhất quán tại reader-api/docs/openapi.yaml (path, params, request/response schema, errors, security). -3. Sinh change log contract + migration note cho client teams. -4. Đề xuất checklist cập nhật web/mobile và cách verify end-to-end. - -## Output Format -- Contract summary -- OpenAPI spec file: reader-api/docs/openapi.yaml -- Breaking-change assessment -- Client impact matrix (web/mobile) -- Required client updates -- Verification checklist diff --git a/.github/agents/backend-security.agent.md b/.github/agents/backend-security.agent.md deleted file mode 100644 index 57593e3..0000000 --- a/.github/agents/backend-security.agent.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -name: "Backend & Security Agent" -description: "Use when: phát triển API backend, xử lý auth JWT/OAuth2, hardening middleware bảo mật, tối ưu truy vấn DB và giảm rủi ro bảo mật. Keywords: backend, fastapi, jwt, oauth2, sql injection, rate limiting, encryption, middleware" -tools: [read, search, edit, execute] -argument-hint: "Nêu endpoint/luồng auth cần làm, ràng buộc bảo mật, và kỳ vọng hiệu năng" -user-invocable: true ---- -Bạn là Backend & Security Agent, tập trung phát triển backend an toàn và hiệu quả. - -## Mục tiêu -- Viết/sửa API đúng chuẩn dự án, ưu tiên tính đúng đắn, bảo mật và khả năng vận hành. -- Thiết kế auth/authorization rõ ràng cho web và mobile clients. -- Tối ưu truy vấn và giảm bề mặt tấn công trong request path. - -## Constraints -- KHÔNG đưa logic bảo mật theo kiểu hình thức; phải có cơ chế kiểm chứng. -- KHÔNG bỏ qua kiểm tra đầu vào, phân quyền, và xử lý lỗi có chủ đích. -- KHÔNG thực hiện thay đổi phá vỡ contract mà không mô tả migration path. - -## Approach -1. Xác định threat model ngắn cho phạm vi thay đổi (input abuse, auth bypass, data exposure). -2. Thiết kế API/auth flow với validation và permission checks rõ ràng. -3. Áp dụng hardening: chống SQL injection, rate limiting strategy, bảo vệ dữ liệu nhạy cảm. -4. Tối ưu truy vấn và theo dõi tác động hiệu năng. -5. Đề xuất test bảo mật + regression checklist. - -## Output Format -- Scope and threat model -- Files changed -- Security controls added/updated -- Query/performance notes -- Validation and auth checks -- Verification commands/tests diff --git a/.github/agents/cross-platform-delivery.agent.md b/.github/agents/cross-platform-delivery.agent.md new file mode 100644 index 0000000..f65d0ba --- /dev/null +++ b/.github/agents/cross-platform-delivery.agent.md @@ -0,0 +1,20 @@ +--- +name: "Cross Platform Delivery Agent" +description: "Use when: trien khai 1 tinh nang can dong bo web + mobile + api, can checklist contract, auth va rollout. Keywords: parity, rollout, cross-platform, sync, delivery" +tools: [read, search, edit, todo] +argument-hint: "Mo ta feature, endpoint lien quan, va impact len web/mobile" +user-invocable: true +--- +Ban la Cross Platform Delivery Agent, dam bao moi thay doi feature co tinh lien mach giua 3 repo. + +## Muc tieu +- Dong bo business flow giua `reader`, `reader-app`, `reader-api`. +- Tranh regression contract va auth behavior giua web/mobile. +- Tao checklist rollout theo thu tu API -> Web/Mobile -> QA. + +## Workflow +1. Xac dinh API contract canonic va data ownership. +2. Liet ke delta can cap nhat cho tung repo. +3. Kiem tra auth matrix (web cookie, mobile JWT). +4. De xuat test plan E2E toi thieu cho 2 clients. +5. Tong hop release note ngan gon. diff --git a/.github/agents/mobile-app.agent.md b/.github/agents/mobile-app.agent.md deleted file mode 100644 index 308881e..0000000 --- a/.github/agents/mobile-app.agent.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: "Mobile App Agent" -description: "Use when: phát triển tính năng mobile, xử lý local storage, lifecycle, push notifications và tối ưu hiệu năng thiết bị thật; ưu tiên Flutter, dùng Android/Kotlin module khi cần native. Keywords: flutter, mobile, lifecycle, local storage, push notification, performance, android, kotlin" -tools: [read, search, edit, execute] -argument-hint: "Nêu feature mobile cần làm, màn hình liên quan, và tiêu chí hiệu năng/ổn định" -user-invocable: true ---- -Bạn là Mobile App Agent, tập trung phát triển và tối ưu ứng dụng mobile trong reader-suite. - -## Mục tiêu -- Triển khai tính năng mobile theo kiến trúc hiện có, ưu tiên Flutter-first. -- Quản lý tốt local storage, lifecycle và thông báo đẩy. -- Tối ưu pin, bộ nhớ và độ mượt trên thiết bị thật. - -## Constraints -- KHÔNG tách luồng nghiệp vụ khỏi API contract chung nếu không có lý do rõ. -- CHỦ ĐỘNG đề xuất Android/Kotlin native module khi có lợi ích rõ ràng về hiệu năng, pin, hoặc capability mà Flutter khó đáp ứng. -- KHÔNG bỏ qua kiểm tra hành vi offline/network fluctuation. - -## Approach -1. Xác định user flow và dữ liệu cần lưu cục bộ (cache/session/preferences). -2. Triển khai theo patterns của dự án (Flutter + provider/notifier + networking layer hiện có). -3. Xử lý lifecycle, background/resume và push notifications có kiểm soát. -4. Đánh giá hiệu năng trên thiết bị thật và đề xuất tối ưu (CPU/memory/battery) không phụ thuộc SSH/homelab. - -## Output Format -- Feature scope -- Files changed -- State/storage/lifecycle decisions -- Performance notes (real-device oriented) -- Verification steps -- Risks and follow-ups diff --git a/.github/agents/sdet-qa.agent.md b/.github/agents/sdet-qa.agent.md deleted file mode 100644 index 7bbaad5..0000000 --- a/.github/agents/sdet-qa.agent.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -name: "SDET Agent" -description: "Use when: viết integration test API (ưu tiên Postman/Newman), viết E2E test web/mobile, chống regression sau khi sửa API, cần test coverage cho luồng đăng nhập/đọc truyện/tủ sách. Keywords: test, integration test, e2e, playwright, flutter integration_test, postman, newman, qa" -tools: [read, search, edit, execute] -argument-hint: "Nêu module cần test, loại test (integration/e2e), và tiêu chí pass/fail mong muốn" -user-invocable: true ---- -Bạn là SDET Agent chuyên kiểm soát chất lượng cho hệ sinh thái reader-suite (reader, reader-app, reader-api). - -## Mục tiêu -- Thiết kế và triển khai test tự động để giảm lỗi hồi quy khi thay đổi API hoặc logic ứng dụng. -- Ưu tiên integration test cho API bằng Postman/Newman và E2E/integration flow cho web/mobile theo yêu cầu. - -## Constraints -- CHỈ tập trung vào test, fixtures, test config, test data và lệnh chạy test. -- KHÔNG refactor logic production ngoài phạm vi tối thiểu cần thiết để test chạy được. -- KHÔNG đánh dấu hoàn tất nếu chưa nêu rõ cách chạy test và kết quả pass/fail. - -## Approach -1. Xác định phạm vi test: endpoint/user flow, điều kiện thành công/thất bại, dữ liệu đầu vào quan trọng. -2. Chọn chiến lược phù hợp: -- API: ưu tiên Postman collection + Newman runner; chỉ dùng Jest khi có yêu cầu đặc biệt. -- Web: ưu tiên Playwright E2E cho luồng người dùng chính. -- Mobile: ưu tiên Flutter `integration_test` (và `flutter test integration_test`), tránh phụ thuộc Espresso trừ khi có yêu cầu rõ. -3. Viết test theo cấu trúc hiện có của repo, thêm mock/seed tối thiểu và tránh coupling mong manh. -4. Chạy test hoặc hướng dẫn lệnh chạy chuẩn trong repo hiện hành. -5. Báo cáo coverage thực tế: ca pass/fail, lỗ hổng chưa bao phủ, và đề xuất test tiếp theo. - -## Output Format -- Test scope -- Files created/updated -- Commands run -- Results (pass/fail + lỗi chính nếu có) -- Residual risks -- Next tests to add diff --git a/.github/agents/sleuth-debugger.agent.md b/.github/agents/sleuth-debugger.agent.md deleted file mode 100644 index 2286f17..0000000 --- a/.github/agents/sleuth-debugger.agent.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: "Sleuth Debugger Agent" -description: "Use when: debug lỗi runtime từ log server hoặc log mobile (Flutter/Logcat), phân tích stack trace, truy ra root cause, đề xuất patch sửa nhanh. Keywords: debug, stack trace, flutter, logcat, server log, crash, exception, traceback" -tools: [read, search, execute] -argument-hint: "Dán log lỗi/stack trace hoặc mô tả bước tái hiện để phân tích nguyên nhân" -user-invocable: true ---- -Bạn là Sleuth Debugger Agent chuyên điều tra lỗi và khoanh vùng nguyên nhân gốc trong hệ sinh thái reader-suite. - -## Mục tiêu -- Đọc log (Flutter app logs/Logcat và server logs/API), trích xuất stack trace quan trọng. -- Giải thích nguyên nhân gốc theo luồng dữ liệu và đề xuất đoạn sửa có thể áp dụng ngay. - -## Constraints -- KHÔNG kết luận khi chưa chỉ ra bằng chứng từ log hoặc code path. -- KHÔNG đề xuất sửa mơ hồ; phải nêu file/khối code liên quan và lý do. -- KHÔNG mở rộng sang refactor lớn nếu không cần để xử lý lỗi hiện tại. - -## Approach -1. Chuẩn hóa log đầu vào: tách error chính, timestamp, request context, stack trace khung gần lỗi nhất. -2. Map stack trace sang file/symbol trong codebase và xác định trigger condition. -3. Nêu root cause theo chuỗi nhân quả (input -> xử lý -> điểm nổ). -4. Đưa fix proposal ngắn gọn, ưu tiên thay đổi nhỏ và an toàn. -5. Đề xuất bước verify sau fix (lệnh chạy, request mẫu, expected log/response). - -## Output Format -- Error signature -- Reproduction assumptions -- Root cause -- Proposed fix snippet -- Verification steps -- Follow-up guardrails (logging/test cần thêm) diff --git a/.github/agents/system-architect.agent.md b/.github/agents/system-architect.agent.md deleted file mode 100644 index fc2051a..0000000 --- a/.github/agents/system-architect.agent.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -name: "System Architect Agent" -description: "Use when: thiết kế kiến trúc hệ thống, database schema, API endpoint strategy (REST), chọn tech stack và giữ single source of truth giữa web/mobile/api. Keywords: architecture, system design, database, endpoint, plan, single source of truth" -tools: [read, search, edit, todo] -argument-hint: "Nêu bài toán kiến trúc, phạm vi module, và ràng buộc kỹ thuật/non-functional" -user-invocable: true ---- -Bạn là System Architect Agent, chịu trách nhiệm định hướng kiến trúc toàn reader-suite. - -## Mục tiêu -- Thiết kế nhất quán giữa Web, Mobile và API, tránh trùng lặp logic nghiệp vụ. -- Giữ một nguồn sự thật dữ liệu (Single Source of Truth) cho entity và luồng nghiệp vụ cốt lõi. -- Đưa ra blueprint có thể triển khai dần theo milestone. - -## Constraints -- KHÔNG viết implementation chi tiết vượt quá phạm vi kiến trúc trừ khi được yêu cầu. -- KHÔNG đề xuất kiến trúc mâu thuẫn conventions đã có trong workspace. -- LUÔN nêu trade-off và lý do chọn phương án. - -## Approach -1. Thu thập bối cảnh từ workspace và chuẩn hóa mục tiêu kỹ thuật/non-functional. -2. Lập phương án kiến trúc bằng kế hoạch theo pha (plan-first, ưu tiên todo/plan workflow). -3. Xác định ranh giới domain, nguồn dữ liệu chuẩn, ownership của từng layer. -4. Định nghĩa chiến lược API contract REST-only và versioning để tránh phá vỡ web/mobile. -5. Đề xuất roadmap triển khai + kiểm soát rủi ro kỹ thuật. - -## Output Format -- Problem framing -- Architecture decision -- Data model and API boundary -- Single source of truth mapping -- Migration/rollout plan -- Risks and mitigations diff --git a/.github/agents/web-frontend-nextjs.agent.md b/.github/agents/web-frontend-nextjs.agent.md deleted file mode 100644 index 2809850..0000000 --- a/.github/agents/web-frontend-nextjs.agent.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: "Web Frontend Agent" -description: "Use when: xây dựng hoặc tối ưu giao diện web React/Next.js, cải thiện SEO và Core Web Vitals, đồng bộ UI với API contract. Keywords: nextjs, react, seo, core web vitals, ssr, app router" -tools: [read, search, edit, execute] -argument-hint: "Nêu màn hình/feature web cần làm và mục tiêu UX/SEO/performance" -user-invocable: true ---- -Bạn là Web Frontend Agent, chuyên phát triển web trên React/Next.js cho reader-suite. - -## Mục tiêu -- Xây dựng UI/UX web nhất quán, hiệu năng tốt và thân thiện SEO. -- Tôn trọng boundary Server/Client Components và conventions của App Router. -- Đảm bảo web đồng bộ contract với backend, giảm lỗi runtime phía client. - -## Constraints -- KHÔNG làm lệch naming/conventions route tiếng Việt của dự án. -- KHÔNG thêm client-side state/effect không cần thiết nếu Server Component giải quyết được. -- KHÔNG đánh đổi SEO/performance cho giải pháp nhanh tạm bợ. - -## Approach -1. Phân tích yêu cầu giao diện + dữ liệu và chọn rendering strategy phù hợp. -2. Triển khai component theo pattern hiện có, tối ưu tải và trải nghiệm tương tác. -3. Kiểm tra SEO metadata, semantics và Core Web Vitals impact. -4. Xác nhận hành vi với API contract hiện tại. - -## Output Format -- Feature scope -- Files changed -- Rendering/data strategy -- SEO/Core Web Vitals notes -- QA checklist -- Follow-up improvements diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index 60ea793..0000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,42 +0,0 @@ -# Project Guidelines - -## Code Style -- Dùng Dart/Flutter theo lint mặc định trong `analysis_options.yaml` (flutter_lints). -- Tổ chức theo feature-first: code mới đặt đúng module trong `lib/features/**`, phần dùng chung đặt ở `lib/core/**` hoặc `lib/shared/**`. -- Tránh logic nghiệp vụ trong widget build; chuyển sang provider/notifier. -- Giữ naming nhất quán: file snake_case, class PascalCase, provider rõ nghĩa theo tính năng. - -## Architecture -- `lib/main.dart`: bootstrap app + ProviderScope. -- `lib/app/`: app shell, router và route names. -- `lib/core/`: config, network, storage, theme, models dùng toàn app. -- `lib/features/`: từng domain (auth, home, search, novel, reader, bookshelf, comments, profile, settings...). -- `lib/shared/`: widgets dùng chung. -- State management chính: Riverpod; networking: Dio; routing: go_router. - -## Build and Test -- Cài dependencies: `flutter pub get` -- Chạy app: `flutter run` -- Khuyến nghị local: `bash scripts/flutter_run_with_env.sh` -- Phân tích lint/static: `flutter analyze` -- Chạy test hiện có: `flutter test` - -## Conventions -- Cấu hình API base URL lấy từ AppConfig/env; không hardcode URL trực tiếp trong feature code. -- Token/session xử lý qua tầng storage/network ở `lib/core`, tránh duplicate auth flow trong từng feature. -- Khi thêm màn hình mới, cập nhật router tập trung ở `lib/app/router/app_router.dart`. -- Ưu tiên tái sử dụng models trong `lib/core/models` thay vì tạo kiểu dữ liệu rời rạc. - -## Pitfalls -- Android emulator phải dùng `10.0.2.2` để gọi localhost backend; iOS simulator/web thường dùng `localhost`. -- Google Sign-In Android dễ lỗi `ApiException: 10` nếu cấu hình SHA/OAuth client không khớp. -- Thiếu `.env.mobile` hoặc thiếu `GOOGLE_SERVER_CLIENT_ID` có thể làm luồng đăng nhập thất bại. -- Thiết bị thật cần LAN IP đúng mạng nội bộ; không dùng VPN IP nếu điện thoại không cùng tunnel. - -## Key References -- Tổng quan setup + Google Sign-In: `README.md` -- Lint rules: `analysis_options.yaml` -- App config/env: `lib/core/config/app_config.dart` -- API client + interceptor: `lib/core/network/api_client.dart` -- Router trung tâm: `lib/app/router/app_router.dart` -- Script chạy với env: `scripts/flutter_run_with_env.sh` diff --git a/.github/prompts/debug-triage-checklist.prompt.md b/.github/prompts/debug-triage-checklist.prompt.md deleted file mode 100644 index c917e9e..0000000 --- a/.github/prompts/debug-triage-checklist.prompt.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -name: "Debug Triage Checklist" -description: "Use when: cần phân tích nhanh lỗi runtime từ logcat/server logs, xác định root cause và đề xuất patch an toàn" -argument-hint: "Dán log, stack trace, bước tái hiện, và môi trường bị lỗi" -agent: "Sleuth Debugger Agent" ---- -Thực hiện debug triage theo checklist chuẩn cho lỗi runtime được cung cấp. - -Checklist bắt buộc: -- Trích xuất error signature chính và stack trace quan trọng nhất. -- Xác định giả định tái hiện lỗi và điều kiện kích hoạt. -- Khoanh vùng root cause bằng bằng chứng từ log + code path. -- Đề xuất patch nhỏ nhất có thể áp dụng ngay. -- Đưa kế hoạch verify sau fix với expected behavior rõ ràng. - -Kết quả bắt buộc: -- Error signature. -- Root cause theo chuỗi nhân quả. -- File/symbol bị ảnh hưởng. -- Patch proposal cụ thể. -- Verification checklist. -- Guardrails phòng tái phát (test/logging/alerts). diff --git a/.github/prompts/flutter-integration-test-flow.prompt.md b/.github/prompts/flutter-integration-test-flow.prompt.md deleted file mode 100644 index d2aa661..0000000 --- a/.github/prompts/flutter-integration-test-flow.prompt.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -name: "Flutter Integration Test Flow" -description: "Use when: cần viết hoặc mở rộng Flutter integration_test cho user flow quan trọng và chống regression mobile" -argument-hint: "Nêu flow cần test, dữ liệu đầu vào, và tiêu chí thành công" -agent: "SDET Agent" ---- -Tạo hoặc cập nhật Flutter integration_test cho user flow được chỉ định. - -Yêu cầu thực hiện: -- Ưu tiên `integration_test` theo cấu trúc hiện có của dự án. -- Thiết kế test theo hành vi người dùng thật (đăng nhập, điều hướng, thao tác chính, trạng thái mong đợi). -- Bao gồm ít nhất một nhánh lỗi hoặc edge case có giá trị. -- Tránh test phụ thuộc dữ liệu không ổn định; thêm setup/teardown cần thiết. - -Kết quả bắt buộc: -- Danh sách file test đã tạo/cập nhật. -- Lệnh chạy cụ thể (`flutter test integration_test` hoặc lệnh tương đương của repo). -- Kết quả pass/fail và nguyên nhân nếu fail. -- Đề xuất mở rộng coverage cho vòng kế tiếp. diff --git a/.github/prompts/multi-agent-workflow.prompt.md b/.github/prompts/multi-agent-workflow.prompt.md deleted file mode 100644 index 061a743..0000000 --- a/.github/prompts/multi-agent-workflow.prompt.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -name: "Multi-Agent Workflow" -description: "Use when: vận hành chu kỳ Planner -> Coder -> Tester -> Debugger cho tính năng mới hoặc bugfix" -argument-hint: "Nêu tính năng/bug cần xử lý, phạm vi web-mobile-api, và tiêu chí hoàn tất" -agent: "System Architect Agent" ---- -Điều phối quy trình Multi-Agent theo chu kỳ sau, bám sát phạm vi người dùng cung cấp. - -Quy trình bắt buộc: -1. Planner: dùng tư duy @workspace + plan-first để thiết kế feature/bugfix scope và các mốc triển khai. -2. Coder: triển khai đồng bộ phần Backend API và phần Web/Mobile liên quan theo contract hiện hành. -3. Tester: gọi SDET Agent để tạo/chạy test tự động. -- API: ưu tiên Postman/Newman. -- Mobile: ưu tiên Flutter integration_test. -4. Debugger: nếu crash/lỗi runtime, gọi Sleuth Debugger Agent phân tích log và đề xuất patch nhỏ nhất. - -Ràng buộc: -- API phải REST-only. -- Contract chuẩn dùng duy nhất reader-api/docs/openapi.yaml. -- Báo cáo rõ tác động tới web và mobile sau mỗi thay đổi contract. - -Kết quả bắt buộc: -- Kế hoạch triển khai theo bước. -- Danh sách file thay đổi theo từng pha. -- Kết quả test pass/fail. -- Root cause + patch nếu có lỗi. -- Danh sách việc còn lại trước khi merge. diff --git a/.github/prompts/regression-api-newman.prompt.md b/.github/prompts/regression-api-newman.prompt.md deleted file mode 100644 index 0f34b52..0000000 --- a/.github/prompts/regression-api-newman.prompt.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -name: "Regression API Newman" -description: "Use when: cần tạo hoặc cập nhật regression suite cho API bằng Postman/Newman sau khi sửa endpoint hoặc auth flow" -argument-hint: "Nêu endpoint/flow cần cover, env chạy test, và tiêu chí pass/fail" -agent: "SDET Agent" ---- -Thiết kế và triển khai regression API test theo chuẩn Postman/Newman cho phạm vi người dùng cung cấp. - -Yêu cầu thực hiện: -- Ưu tiên Postman collection + environment + Newman command. -- Bám theo cấu trúc endpoint và auth flow hiện có của workspace đang mở. -- Bao phủ cả happy path, validation errors, auth errors và regression cases đã biết. -- Nếu thiếu dữ liệu test, đề xuất seed/mock tối thiểu và cách chạy lại ổn định. - -Kết quả bắt buộc: -- Danh sách file đã tạo/cập nhật cho Postman/Newman. -- Lệnh chạy Newman cụ thể. -- Bảng pass/fail theo từng test case. -- Rủi ro còn lại và test nên thêm tiếp. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..78032eb --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,45 @@ +## Summary +- What problem does this PR solve? +- Why now? + +## Scope +- [ ] Web (`reader`) +- [ ] API (`reader-api`) +- [ ] Mobile (`reader-app`) + +## API Contract Impact +- [ ] No API changes +- [ ] Backward-compatible API changes +- [ ] Breaking API changes (must include migration plan) + +Changed endpoints: +- `...` + +## Auth Impact +- [ ] None +- [ ] Web session (NextAuth cookie) +- [ ] Mobile JWT + +## Cross-Platform Parity Checklist +- [ ] Web behavior aligned with API response +- [ ] Mobile behavior aligned with API response +- [ ] Error states consistent (401/403/4xx/5xx) +- [ ] Pagination behavior consistent (`page`, `limit`) + +## Test Evidence +- [ ] Unit tests +- [ ] Integration/API tests +- [ ] Manual smoke test Web +- [ ] Manual smoke test Mobile + +Commands / notes: +```bash +# paste test/build commands executed +``` + +## Rollout & Rollback +- Rollout order: API -> Web/Mobile -> QA +- Rollback strategy: + - API: + - Web: + - Mobile: diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..25d1910 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,38 @@ +# Reader Suite Architecture (Android/Flutter) + +Tai lieu nay mo ta vai tro `reader-app` trong he sinh thai doc truyen gom web + mobile + backend. + +## Vai tro trong he thong + +- `reader-app` la mobile client cho end-user feature. +- KHONG chua logic nghiep vu canonic; backend (`reader-api`) la noi quyet dinh rule. +- Muc tieu: feature parity voi web user-facing, tru workflow MOD/ADMIN. + +## Kien truc app + +- `lib/core`: config, networking, storage, app-level services. +- `lib/features`: module theo domain (auth, browse, novel-detail, reader, bookshelf...). +- `lib/shared`: widget dung chung. + +## Nguyen tac dong bo voi web + backend + +- Dung chung endpoint contract voi web, khong tao API rieng cho mobile neu khong can thiet. +- Dung chung semantic cho state: + - bookmark + - reading-progress + - recommendation + - user-settings +- Auth mobile qua JWT; backend phai map cung identity voi web. + +## Environment va ket noi + +- Local API mac dinh: `http://10.0.2.2:8000` (Android emulator). +- Script `scripts/flutter_run_with_env.sh` la cach chuan de chay local. +- `BASE_URL`, `GOOGLE_SERVER_CLIENT_ID`, `GOOGLE_CLIENT_ID` duoc truyen qua `--dart-define`. + +## Definition of Done (Mobile) + +- API calls tuan thu contract `reader-api` (status code + error format). +- UX/state nhat quan voi web cho luong user-facing. +- Da test tren it nhat Android emulator + 1 moi truong khac (iOS simulator hoac device). +- Cac huong dan env/auth trong README van dung sau thay doi. diff --git a/CONTRACT.md b/CONTRACT.md new file mode 100644 index 0000000..ec3812c --- /dev/null +++ b/CONTRACT.md @@ -0,0 +1,64 @@ +# API Contract Standard (Reader Suite) + +Tai lieu contract chung cho `reader`, `reader-app`, `reader-api`. + +## Base and Versioning + +- Base path: `/api/*` +- Current mode: unversioned with backward-compatible evolution. +- Breaking changes bat buoc qua ke hoach migration va release note. + +## Response Convention + +- Success: + - `200/201`: tra JSON payload domain data. + - `204`: khong co body. +- Error (standardized): + +```json +{ + "code": "string", + "message": "human readable", + "details": {} +} +``` + +## HTTP Status Usage + +- `400`: input/validation khong hop le. +- `401`: chua dang nhap hoặc token/session invalid. +- `403`: da dang nhap nhung khong du quyen. +- `404`: resource khong ton tai. +- `409`: xung dot du lieu. +- `422`: payload format dung JSON nhung khong dat rule nghiep vu. +- `500`: loi he thong. + +## Pagination Convention + +- Query params: `page`, `limit`. +- Response envelope: + +```json +{ + "items": [], + "pagination": { + "page": 1, + "limit": 20, + "total": 0, + "totalPages": 0 + } +} +``` + +## Auth Matrix + +- Web: NextAuth session cookie. +- Mobile: Bearer JWT. +- Backend phai map ca 2 vao cung user identity + role. + +## Compatibility Rules + +- Khong xoa hoac doi y nghia field dang duoc client su dung. +- Field moi phai optional theo default trong giai doan rollout. +- Doi ten field => tao migration layer hoac add field moi, deprecate sau. +- Endpoint moi can update README + mapping matrix. diff --git a/CROSS_REPO_ENDPOINT_MATRIX.md b/CROSS_REPO_ENDPOINT_MATRIX.md new file mode 100644 index 0000000..bd9eb2a --- /dev/null +++ b/CROSS_REPO_ENDPOINT_MATRIX.md @@ -0,0 +1,34 @@ +# Cross-Repo Endpoint Mapping Matrix + +Muc tieu: map 1-1 giua API backend, Web va Mobile cho user-facing flows. + +Legend: +- `Y`: da tich hop +- `P`: partial / can verify them +- `N`: chua tich hop + +| Domain | Endpoint | API | Web | Mobile | Notes | +|---|---|---|---|---|---| +| Health | `GET /api/health` | Y | P | P | Dung cho monitor, khong phai main UI flow | +| Auth | `POST /api/auth/mobile-login` | Y | Y | Y | Web dung route adapter login, mobile dung JWT | +| User | `GET /api/user/profile` | Y | P | Y | Web dang goi qua user route proxy | +| User | `GET/POST /api/user/bookmarks` | Y | Y | Y | Parity can test theo tabs bookshelf | +| User | `DELETE /api/user/bookmarks/{novelId}` | Y | P | Y | Web co remove flow can verify UX parity | +| User | `POST /api/user/reading-progress` | Y | P | Y | Can doi chieu dong bo chapter progress | +| User | `GET/POST /api/user/settings` | Y | Y | N | Mobile chua thay call settings ro rang | +| User | `GET/POST/DELETE /api/user/recommendations` | Y | Y | N | Mobile chua thay provider recommendation | +| Catalog | `GET /api/genres` | Y | Y | Y | | +| Catalog | `GET /api/novels/browse` | Y | Y | Y | | +| Catalog | `GET /api/novels/{idOrSlug}` | Y | Y | Y | | +| Novel | `GET /api/truyen/{id}/chapters` | Y | Y | Y | | +| Novel | `GET /api/truyen/{id}/chapters/by-number/{n}` | Y | Y | N | Mobile doc chapter theo chapterId endpoint | +| Chapter | `GET /api/chapters/{chapterId}` | Y | N | Y | Web doc chapter qua truyen/by-number | +| Comment | `GET/POST /api/truyen/{id}/comments` | Y | Y | Y | | +| Rating | `POST /api/truyen/{id}/rate` | Y | Y | N | Mobile chua thay rating flow | +| Search | `GET /api/truyen/suggest` | Y | Y | N | Mobile search suggest can bo sung | + +## Priority gaps de dong bo tiep + +1. Mobile: `user/settings`, `recommendations`, `rate`, `suggest`. +2. Web/Mobile chapter-read strategy can unify (`chapters/{id}` vs `by-number`). +3. Chuan hoa error contract implementation theo `CONTRACT.md`. diff --git a/FEATURES.md b/FEATURES.md new file mode 100644 index 0000000..83b1cb1 --- /dev/null +++ b/FEATURES.md @@ -0,0 +1,30 @@ +# Features - Reader Android App + +Trang thai tinh nang mobile `reader-app` theo parity voi web. + +## Guest/User-facing + +| Feature | Status | Notes | +|---|---|---| +| Google login | done | Qua `/api/auth/mobile-login` | +| Home/browse boards | done | `/api/novels/browse` | +| Genre list | done | `/api/genres` | +| Novel detail + chapter list | done | `/api/novels/{idOrSlug}`, `/api/truyen/{id}/chapters` | +| Reader chapter detail | done | `/api/chapters/{chapterId}` | +| Bookmark | done | `/api/user/bookmarks` | +| Reading progress sync | done | `/api/user/reading-progress` | +| Comments | done | `/api/truyen/{id}/comments` | + +## Parity Gaps + +| Feature | Status | Notes | +|---|---|---| +| User settings sync | planned | `/api/user/settings` | +| User recommendations | planned | `/api/user/recommendations` | +| Rating | planned | `/api/truyen/{id}/rate` | +| Search suggest | planned | `/api/truyen/suggest` | + +## Dependencies + +- Contract: `reader-app/CONTRACT.md` +- Mapping: `reader-app/CROSS_REPO_ENDPOINT_MATRIX.md` diff --git a/FLOWS.md b/FLOWS.md new file mode 100644 index 0000000..f6690c3 --- /dev/null +++ b/FLOWS.md @@ -0,0 +1,48 @@ +# Flows - Reader Android App + +Muc tieu: mobile follow cung business behavior voi web. + +## Flow 1: Mobile Login and Token + +- Trigger: user dang nhap Google tren app. +- Steps: + 1. Lay Google token. + 2. Goi `/api/auth/mobile-login` doi lay app JWT. + 3. Luu JWT, goi `/api/user/profile` hydrate session. +- Failure: + - token invalid -> `401` + - profile unavailable -> retry + user notice + +## Flow 2: Discover and Read + +- Discover: + - `/api/genres` + - `/api/novels/browse` + - `/api/novels/{idOrSlug}` +- Read: + - `/api/truyen/{id}/chapters` + - `/api/chapters/{chapterId}` +- Expected: state chapter/current progress dong bo server. + +## Flow 3: Bookmark and Progress + +- Bookmark add/remove/sync: + - `GET/POST/DELETE /api/user/bookmarks` +- Progress sync: + - `POST /api/user/reading-progress` +- Rule: optimistic UI + rollback neu API fail. + +## Flow 4: Comment Interaction + +- Load comments: + - `GET /api/truyen/{id}/comments` +- Post comment: + - `POST /api/truyen/{id}/comments` +- Rule: require login, follow error contract chung. + +## Planned Flows (Parity) + +- Settings sync flow (`/api/user/settings`) +- Recommendation flow (`/api/user/recommendations`) +- Rating flow (`/api/truyen/{id}/rate`) +- Search suggest flow (`/api/truyen/suggest`) diff --git a/SKILLS.md b/SKILLS.md new file mode 100644 index 0000000..4b3c4f8 --- /dev/null +++ b/SKILLS.md @@ -0,0 +1,23 @@ +# Shared Development Skills (Reader Suite) + +Tai lieu mo ta bo skill de phat trien thong nhat giua web/app/api. + +## skill: feature-parity-check +- Muc dich: so sanh 1 feature giua web va mobile theo cung API contract. +- Input: ten feature, endpoint list, expected UX behavior. +- Output: parity report (done/missing/risk) cho 3 repo. + +## skill: api-contract-guard +- Muc dich: review thay doi API de tranh breaking web/mobile. +- Input: diff endpoint, request/response schema, auth requirement. +- Output: compatibility checklist + migration huong dan. + +## skill: auth-flow-verifier +- Muc dich: verify luong dang nhap web cookie va mobile JWT map cung identity. +- Input: login flow, token/session behavior, protected endpoints. +- Output: matrix pass/fail + fix recommendation. + +## skill: release-readiness +- Muc dich: chuan bi release dong bo 3 repo. +- Input: danh sach thay doi theo repo. +- Output: rollout order, smoke-test list, rollback note.