Remove deprecated agent files and add new architecture, contract, and feature documentation for the Reader Suite

2026-04-29 23:24:53 +07:00
parent 9b1f7bb060
commit 19cca5b5d0
21 changed files with 311 additions and 404 deletions
@@ -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
@@ -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
@@ -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.
@@ -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
@@ -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
@@ -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)
@@ -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
@@ -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
@@ -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`
@@ -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).
@@ -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.
@@ -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.
@@ -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.
@@ -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:
@@ -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
@@ -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.
@@ -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.
@@ -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`.
@@ -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`
@@ -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`.
@@ -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.