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 3b8f607..0000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,44 +0,0 @@ -# Project Guidelines - -## Code Style -- Backend này là Python-first (FastAPI). Ưu tiên sửa/chạy bằng `uv` và toolchain trong `pyproject.toml`. -- Tuân thủ format/lint với Ruff: line-length 100, import order rõ ràng. -- Viết async đúng chuẩn FastAPI/SQLAlchemy async; tránh trộn sync blocking call trong request path. -- Khi thêm endpoint, luôn trả lỗi có chủ đích bằng `HTTPException` và message rõ nghĩa. - -## Architecture -- `app/main.py`: khởi tạo FastAPI app, middleware/CORS, health và endpoint user-facing. -- `app/auth.py`: xác thực JWT/session cookie và kiểm tra role (`USER`/`MOD`/`ADMIN`). -- `app/database.py`: kết nối PostgreSQL (SQLAlchemy async) + MongoDB (motor). -- `app/routers/mod.py`: nhóm route cho MOD/ADMIN. -- `prisma/schema.prisma`: schema dữ liệu quan hệ chia sẻ với web. -- Dữ liệu chia 2 lớp: PostgreSQL cho metadata quan hệ, MongoDB cho chapter content/recommendation content. - -## Build and Test -- Cài dependencies: `uv sync` -- Chạy dev server: `uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000` -- Health check nhanh: `curl http://localhost:8000/api/health` -- Lint: `uv run ruff check .` -- Format: `uv run ruff format .` -- Docker stack: xem `docker-compose.yml` (`api`, `api-local`, `postgres`, `mongo`, `web`) - -## Conventions -- Ưu tiên dependency injection qua `Depends(...)` cho auth/db session. -- Kiểm tra ownership/role trước thao tác ghi dữ liệu, đặc biệt ở mod routes. -- Với nghiệp vụ ghi đồng thời nhiều nguồn (PostgreSQL + MongoDB), xử lý lỗi từng bước rõ ràng để tránh trạng thái nửa thành công. -- Repository này có `package.json` không phản ánh backend Python hiện tại; dùng lệnh trong `README.md` và `pyproject.toml` làm chuẩn. - -## Pitfalls -- `DATABASE_URL` từ Prisma có query params; cần normalize đúng cho asyncpg (đã xử lý trong `app/database.py`). -- Thiếu `.env` hoặc secret (`NEXTAUTH_SECRET`, `MOBILE_JWT_SECRET`, `GOOGLE_CLIENT_ID`) sẽ làm auth flow lỗi. -- Sai CORS origin sẽ gây lỗi cross-origin cho web/mobile local. -- Khi chạy local stack bằng Docker profile, lưu ý khác biệt cổng giữa `api` (8000) và `api-local` (8001). - -## Key References -- Setup, env, endpoint matrix: `README.md` -- Debug chapter save: `CHAPTER_SAVE_DEBUG.md` -- Các bản vá quan trọng: `FIXES_APPLIED.md` -- App bootstrap: `app/main.py` -- Auth/session logic: `app/auth.py` -- DB wiring: `app/database.py` -- Mod routes: `app/routers/mod.py` 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/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml deleted file mode 100644 index 77e0c74..0000000 --- a/.github/workflows/docker-publish.yml +++ /dev/null @@ -1,43 +0,0 @@ -name: Build and Push Docker Image - -on: - push: - -jobs: - docker: - runs-on: ubuntu-latest - permissions: - contents: read - packages: write - - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - - name: Log in to Docker Hub - uses: docker/login-action@v3 - with: - username: ${{ secrets.DOCKERHUB_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - name: Log in to GitHub Container Registry - uses: docker/login-action@v3 - with: - registry: ghcr.io - username: ${{ github.actor }} - password: ${{ secrets.GITHUB_TOKEN }} - - - name: Build and push image - uses: docker/build-push-action@v6 - with: - context: . - file: ./Dockerfile - push: true - tags: | - fevirtus/reader-api:latest - ghcr.io/fevirtus/reader-api:latest - cache-from: type=gha - cache-to: type=gha,mode=max diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..5243dfb --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,46 @@ +# Reader Suite Architecture (API Backend) + +Tai lieu nay mo ta `reader-api` la backend dung chung cho Web (`reader`) va Android (`reader-app`). + +## Vai tro trung tam + +- `reader-api` la single source of truth cho: + - API contract + - domain rule + - auth mapping web/mobile + - data orchestration PostgreSQL + MongoDB +- Moi thay doi contract phai uu tien backward-compatible cho 2 client. + +## Domain ownership + +- User domain: profile, settings, bookmarks, reading progress, recommendations. +- Content domain: genres, novels, chapter list, chapter content. +- Interaction domain: comments, ratings. + +## Data strategy + +- PostgreSQL: + - user, novel metadata, genres, comments, ratings, bookmarks, progress. +- MongoDB: + - chapter text content lon. + - recommendation document payload (neu can rich document). + +## Auth and identity + +- Web auth: session cookie (NextAuth token va secure variants). +- Mobile auth: JWT tu `/api/auth/mobile-login`. +- Backend map ca 2 co che vao cung identity va permission model. + +## API compatibility policy + +- Khong xoa field dang duoc client dung khi chua co migration plan. +- Them field moi theo huong optional tru khi co versioning. +- Error response phai on dinh theo format chung (code, message, details). +- Versioning uu tien uri prefix hoac contract evolution, tranh breaking ngay. + +## Definition of Done (API) + +- Endpoint moi co docs request/response + auth requirement. +- Da verify voi web + mobile happy path va auth edge cases. +- Healthcheck va monitoring khong bi anh huong. +- Docker/local dev van chay voi huong dan README. 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..4abca39 --- /dev/null +++ b/FEATURES.md @@ -0,0 +1,28 @@ +# Features - Reader API + +Tinh nang backend cho web + mobile. + +## Public/User-Facing API + +| Domain | Endpoint Group | Status | Notes | +|---|---|---|---| +| Health | `/api/health` | done | Healthcheck | +| Auth | `/api/auth/mobile-login` | done | Mobile JWT login | +| User | `/api/user/*` | done | profile, bookmarks, progress, settings, recommendations | +| Catalog | `/api/genres`, `/api/novels/*` | done | browse/detail | +| Reading | `/api/truyen/*`, `/api/chapters/*` | done | toc, comments, rate, chapter detail | +| Search | `/api/truyen/suggest` | done | web dang dung, mobile con gap | + +## MOD/ADMIN API + +| Domain | Endpoint Group | Status | Notes | +|---|---|---|---| +| Content management | `/api/mod/*` | partial | da co nhieu route, tiep tuc bo sung nhu cau | + +## Contract + Parity Responsibility + +- Canonical contract owner cho ca 2 clients. +- Moi endpoint moi phai update: + - `README.md` + - `CONTRACT.md` + - `CROSS_REPO_ENDPOINT_MATRIX.md` diff --git a/FLOWS.md b/FLOWS.md new file mode 100644 index 0000000..c5c0cad --- /dev/null +++ b/FLOWS.md @@ -0,0 +1,38 @@ +# Flows - Reader API + +Backend flow theo domain, de web/mobile follow giong nhau. + +## Flow A: Auth Identity Unification + +- Input: + - Web session cookie (NextAuth) + - Mobile bearer JWT +- Behavior: + 1. Resolve current user identity. + 2. Validate role/permission. + 3. Return consistent auth errors (`401/403`). + +## Flow B: Discovery and Reading + +- Discovery: + - `/api/genres` + - `/api/novels/browse` + - `/api/novels/{idOrSlug}` +- Reading: + - `/api/truyen/{id}/chapters` + - `/api/chapters/{chapterId}` or chapter-by-number variant +- Rule: response shape on dinh de client render. + +## Flow C: User Personalization + +- Bookmark: `/api/user/bookmarks`. +- Progress: `/api/user/reading-progress`. +- Settings: `/api/user/settings`. +- Recommendations: `/api/user/recommendations`. +- Rule: idempotent where possible, clear conflict semantics. + +## Flow D: Social Interaction + +- Comments: `/api/truyen/{id}/comments`. +- Rating: `/api/truyen/{id}/rate`. +- Rule: enforce auth + anti-invalid payload + stable error format. 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.