From 19cca5b5d01c9479acb316beb719c4aab1557d65 Mon Sep 17 00:00:00 2001 From: virtus Date: Wed, 29 Apr 2026 23:24:53 +0700 Subject: [PATCH] Remove deprecated agent files and add new architecture, contract, and feature documentation for the Reader Suite --- .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 | 44 ------------ .../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 ++++++++++++ .github/workflows/docker-publish.yml | 43 ------------ ARCHITECTURE.md | 44 ++++++++++++ CONTRACT.md | 70 +++++++++++++++++++ CROSS_REPO_ENDPOINT_MATRIX.md | 34 +++++++++ FEATURES.md | 35 ++++++++++ FLOWS.md | 40 +++++++++++ SKILLS.md | 23 ++++++ 21 files changed, 311 insertions(+), 404 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 delete mode 100644 .github/workflows/docker-publish.yml 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 a0d5909..0000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,44 +0,0 @@ -# Project Guidelines - -## Code Style -- Dùng TypeScript strict, ưu tiên typing tường minh cho props, API payload và server helpers. -- Tách rõ Server Component và Client Component. Chỉ thêm `"use client"` khi cần state/effect/event handler. -- Giữ naming theo dự án: route tiếng Việt dạng kebab-case (`dang-nhap`, `the-loai`, `tim-kiem`, `tu-sach`), component file dạng kebab-case. -- Dùng TailwindCSS utility + component trong `components/ui`; không tự ý đổi pattern UI nếu chưa cần. - -## Architecture -- `app/`: Next.js App Router pages + route handlers. -- `components/`: UI/domain components tái sử dụng. -- `lib/`: tầng truy cập dữ liệu, auth, context, helper dùng chung. -- `prisma/`: schema PostgreSQL; MongoDB model nằm trong `lib/models/`. -- App dùng kiến trúc hybrid DB: PostgreSQL (dữ liệu cấu trúc) + MongoDB (nội dung chương). -- API user-facing thường đi qua proxy routes trong `app/api/**` và `READER_API_ORIGIN`. - -## Build and Test -- Cài đặt: `pnpm install` -- Dev server: `pnpm dev` -- Lint: `pnpm lint` -- Build production: `pnpm build` -- Chạy production: `pnpm start` -- Prisma: `npx prisma db push` (hoặc `npx prisma migrate dev`) và `npx prisma generate` -- Kiểm tra kết nối DB/AI nếu cần: `node test-db.js`, `node test-ai.js` - -## Conventions -- Ưu tiên dùng helper sẵn có trong `lib/server-api.ts` cho gọi backend ở server side. -- Luồng auth đi qua NextAuth config trong `lib/auth.ts`; không tạo cơ chế xác thực song song trừ khi có yêu cầu rõ ràng. -- Khi sửa API route proxy (`app/api/**`), luôn giữ nguyên behavior forward headers/token nếu route đang bảo vệ quyền. -- Không mở rộng phạm vi thay đổi sang backend Python trong repo khác nếu yêu cầu chỉ thuộc web repo. - -## Pitfalls -- Thiếu biến môi trường (`DATABASE_URL`, `MONGODB_URI`, `NEXTAUTH_SECRET`, `READER_API_ORIGIN`) sẽ gây lỗi khó chẩn đoán. -- Nếu Prisma Client chưa generate, import từ `@prisma/client` có thể fail. -- Nếu `reader-api` chưa chạy đúng origin, các route `/api/*` proxy sẽ lỗi upstream. -- `next.config.mjs` đang cho phép bỏ qua lỗi type ở build; vẫn cần giữ chất lượng type khi sửa code. - -## Key References -- Tổng quan setup và môi trường: `README.md` -- Auth + session callbacks: `lib/auth.ts` -- App shell và providers: `app/layout.tsx` -- API helper và error model: `lib/server-api.ts` -- Proxy mod route pattern: `app/api/mod/[...path]/route.ts` -- Data model quan hệ: `prisma/schema.prisma` 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 fcc8aaa..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:latest - ghcr.io/fevirtus/reader: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..2627bfa --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,44 @@ +# Reader Suite Architecture (Web) + +Tai lieu nay mo ta vai tro cua `reader` (web app) trong bo 3 he thong: Web + Android + API. + +## Vai tro trong he thong + +- `reader` la frontend web cho end-user va mot phan workflow cho MOD/ADMIN. +- `reader` KHONG duoc tro thanh noi xu ly business logic chinh. +- `reader-api` la API trung tam, la nguon su that cho contract va domain behavior. + +## Nguyen tac thong nhat voi mobile + backend + +- API-first: moi tinh nang user-facing moi phai co endpoint ro rang trong `reader-api`. +- Contract-first: web va mobile dung chung schema response, error code, pagination. +- Auth parity: + - Web: NextAuth session cookies. + - Mobile: Bearer JWT. + - Ca hai deu map vao cung user identity trong backend. +- Data ownership: + - PostgreSQL: metadata co cau truc (user, novel, genre, comment, bookmark...). + - MongoDB: chapter content, recommendation payload lon. + +## Kien truc module web + +- App layer (`app/*`): route, rendering, page composition. +- UI layer (`components/*`): reusable components, khong chua business rule quan trong. +- Data access layer: goi REST API qua `READER_API_ORIGIN` cho endpoint da migrate. +- Auth adapter: dong bo session NextAuth va profile API. + +## Quy uoc tich hop API + +- Base URL local: `http://localhost:8000` (qua `READER_API_ORIGIN`). +- Khong hard-code endpoint trong component; gom theo domain (novels, chapters, user...). +- Luon xu ly 3 nhom loi: + - validation/business (`4xx`) + - auth (`401/403`) + - he thong (`5xx`) + +## Definition of Done (Web) + +- Tinh nang moi co endpoint tai `reader-api` hoac da duoc architect chap thuan. +- Khong duplicate business logic voi mobile. +- Da test luong auth va state dong bo profile/bookmark/progress. +- README va contract docs duoc cap nhat neu co thay doi API. diff --git a/CONTRACT.md b/CONTRACT.md new file mode 100644 index 0000000..1d09d06 --- /dev/null +++ b/CONTRACT.md @@ -0,0 +1,70 @@ +# 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": {} +} +``` + +- `code`: machine-friendly identifier (vd: `UNAUTHORIZED`, `VALIDATION_ERROR`, `NOT_FOUND`). +- `message`: thong diep nguoi dung/dev doc duoc. +- `details`: optional object cho field-level context. + +## 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` (1-based) + - `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..53de40a --- /dev/null +++ b/FEATURES.md @@ -0,0 +1,35 @@ +# Features - Reader Web + +Trang thai tinh nang cho web app `reader`. + +## Guest + +| Feature | Status | Notes | +|---|---|---| +| Home boards / browse | done | Goi API browse, hot/recommendation sections | +| Genre listing/detail | done | `/api/genres`, `/api/novels/browse` | +| Search + suggest | partial | Suggest da co web, can tiep tuc canh edge cases | +| Novel detail + chapter list | done | Chi tiet + comment/thread load | + +## User + +| Feature | Status | Notes | +|---|---|---| +| Google login (NextAuth) | done | Session cookie auth | +| Bookmark CRUD | done | Qua `/api/user/bookmarks` | +| Reading progress sync | partial | Co call API, can them parity checks | +| Reading settings | done | `/api/user/settings` | +| Comment on novel/chapter | done | `/api/truyen/{id}/comments` | +| Rating | done | `/api/truyen/{id}/rate` | +| Recommendations | done | `/api/user/recommendations` | + +## MOD/ADMIN + +| Feature | Status | Notes | +|---|---|---| +| MOD dashboard/workflows | partial | Mot phan route mod da co, tiep tuc bo sung | + +## Dependencies + +- Contract: `reader/CONTRACT.md` +- Mapping: `reader/CROSS_REPO_ENDPOINT_MATRIX.md` diff --git a/FLOWS.md b/FLOWS.md new file mode 100644 index 0000000..4cf7f06 --- /dev/null +++ b/FLOWS.md @@ -0,0 +1,40 @@ +# Flows - Reader Web + +Luon xem `reader-api` la canonical behavior. + +## Flow 1: Web Login and Session + +- Trigger: user bam dang nhap Google. +- Preconditions: env OAuth hop le. +- Steps: + 1. User xac thuc Google qua NextAuth. + 2. Web co session cookie. + 3. Web goi endpoint user de hydrate profile/state. +- Success: user vao trang co tinh nang ca nhan hoa. + +## Flow 2: Browse -> Novel Detail -> Read Chapter + +- Trigger: user click tu home/search/genre. +- Steps: + 1. Goi `/api/novels/browse` hoac `/api/novels/{idOrSlug}`. + 2. Goi `/api/truyen/{id}/chapters` lay muc luc. + 3. Doc chapter qua luong chapter hien co cua web. +- Failure handling: + - 404: thong bao khong tim thay truyen/chuong. + - 5xx: retry UI + fallback message. + +## Flow 3: Bookmark and Progress Sync + +- Trigger: user bookmark hoac chuyen chuong. +- Steps: + 1. Bookmark: `GET/POST/DELETE /api/user/bookmarks`. + 2. Progress: `POST /api/user/reading-progress`. + 3. UI cap nhat trang thai optimistic + reconcile API. +- Expected parity: cung nghia status voi mobile. + +## Flow 4: Comment / Rating / Recommendation + +- Comment: `GET/POST /api/truyen/{id}/comments`. +- Rating: `POST /api/truyen/{id}/rate`. +- Recommendation: `/api/user/recommendations`. +- Error rules: follow `CONTRACT.md`. 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.