Chuyển tới nội dung chính

Docs Update Plan

Tài liệu này tổng hợp kế hoạch cập nhật docs-site dựa trên:

  • OpenAPI spec mới (internal /openapi.json, external /external-openapi.json).
  • Tài liệu backend chi tiết trong thư mục docs/.
  • Tài liệu frontend trong cohost-fe/docs/.

Mục tiêu:

  • Đảm bảo docs-site luôn khớp với behavior thật của API và FE.
  • Giảm lệch giữa OpenAPI, backend code và guides/architecture docs.

1. Sync OpenAPI → API Docs (Internal & External)​

1.1. Bước vận hành​

  1. Export OpenAPI từ backend:
    • Chạy script export (ví dụ như hướng dẫn trong docs-site/docs/api/internal.md / external.md):
      • python scripts/export_openapi.py
    • Kỳ vọng tạo:
      • openapi.json (internal).
      • external-openapi.json (external).
  2. Copy spec vào docs-site:
    • Từ project root:
      • cp openapi.json external-openapi.json docs-site/
  3. Generate API docs từ OpenAPI:
    • Vào thư mục docs-site/:
      • Cài deps (lần đầu): npm ci
      • Sinh docs: npm run gen-api-docs
        • Sử dụng cấu hình trong docusaurus.config.js với plugin docusaurus-plugin-openapi-docs.
  4. Build & deploy:
    • Build local: npm run build
    • Hoặc rely vào pipeline .github/workflows/staging_deploy-docs.yml:
      • Dockerfile đã có bước build Docusaurus.
      • Có thể cân nhắc bật lại RUN npm run gen-api-docs trong Dockerfile khi spec đã ổn định.

1.2. Checklist sau khi generate​

  • docs/api/internal/* hiển thị đủ nhóm endpoint chính (auth, teams, listings, bookings, payments, webhooks, availability, financial, …).
  • docs/api/external/* hiển thị đầy đủ các endpoint external (listings, bookings, webhooks external nếu có).
  • Các tag / group trong sidebar hợp lý (mapping tốt với guides: Listings, Bookings, Payments, External API).
  • Xem qua một số endpoint quan trọng, đảm bảo mô tả/field name khớp với guides mới viết.

2. Cross-check Architecture Docs​

Kiểm tra các file trong docs-site/docs/architecture so với:

  • OpenAPI mới (internal/external).
  • Tài liệu backend trong docs/ (Phân tích BE, DB, Third-party, Listing Management, v.v.).
  • Tài liệu FE trong cohost-fe/docs/ (Team Management, Booking Integration, Pricing, …).

2.1. Danh sách file cần cross-check​

  • overview.md
  • backend.md
  • booking-flow.md
  • catalog-design.md
  • database.md
  • implementation-summary.md
  • listing-management.md
  • listing-parent-child.md
  • third-party-api.md
  • x-team-id-guide.md

2.2. Những điểm cần lưu ý khi cross-check​

  • Đường dẫn API & team context:
    • Các path cũ có {team_id} trong URL → đã/đang được migrate sang endpoint “current team” dùng X-Team-ID.
    • Đảm bảo docs:
      • Mô tả đúng các endpoint mới (không lẫn giữa path cũ và mới).
      • Luôn nhấn mạnh việc dùng X-Team-ID cho team-scoped endpoints.
  • Booking flow & pricing:
    • booking-flow.md vs:
      • OpenAPI (/checkout/preview, /checkout/confirm, /bookings/*).
      • cohost-fe/docs/Host_Booking_Integration_Guide.md.
      • cohost-fe/docs/cohost-dayladau-pricing-compatibility.md.
    • Kiểm tra:
      • Đã nhắc tới hourly/overnight/combo pricing chưa?
      • Mô tả Soft-Lock, All-or-Nothing có khớp với implement hiện tại?
  • Listing management:
    • listing-management.md vs:
      • docs/Listing_Management_Guide.md.
      • cohost-fe/docs/Listing_Management_Guide.md.
      • OpenAPI nhóm listings (CRUD, pricing rules, availability, images, policies).
    • Đảm bảo:
      • Các bước tạo listing (step 1–4) được mô tả đúng và không bỏ sót các field mới (pricing/hourly/extra guest/combo).
  • Third-party / External API:
    • third-party-api.md vs:
      • docs/04_PhanTich_ThirdParty_API.md.
      • Dayladau integration docs trong docs/ và cohost-fe/docs/.
    • Đảm bảo:
      • Nhóm endpoint external hiện tại (listings, bookings, webhooks, pricing) khớp với OpenAPI external.
  • X-Team-ID:
    • x-team-id-guide.md vs:
      • docs/X_TEAM_ID_HEADER_GUIDE.md.
      • docs/X_TEAM_ID_API_PATH_REVIEW.md.
      • cohost-fe/docs/X_TEAM_ID_HEADER_GUIDE.md.
    • Kiểm tra:
      • Naming header (X-Team-ID) thống nhất.
      • Bảng endpoint cần/không cần X-Team-ID khớp với spec mới.

2.3. Cách ghi lại kết quả cross-check​

Đề xuất ghi lại trong một bảng (có thể ở file này hoặc docs/BE_Implementation_TODO.md).

Bảng khởi tạo gợi ý (có thể bổ sung/điều chỉnh thêm khi review chi tiết):

FileMục / SectionVấn đềĐề xuất updateƯu tiên
booking-flow.mdPricingMô tả pricing tổng quan, chưa nhắc rõ hourly/overnight/combo, checkout/previewThêm section Pricing chi tiết (hourly, overnight, extra guest, combo) và nhắc rõ các API /checkout/preview, /listing-availability/.../calendars (link tới guides/bookings)High
booking-flow.mdSoft-LockĐã mô tả Soft-Lock nhưng chưa liên kết tới error codes / overbookingThêm link tới guides/error-handling và error codes liên quan (booking/overbooking)Medium
listing-management.mdFlow tạo listingFlow step-based đã đúng, chưa nhấn mạnh preview/validation endpointNhấn mạnh vai trò POST /api/v1/listings/preview trong bước cuối trước khi publish listing (link tới guides/listings)Medium
listing-management.mdPricing rulesMô tả pricing rules chung, chưa nêu rõ mapping với Dayladau pricing modelThêm tiểu mục “Compatibility with Dayladau pricing” và link tới docs phân tích pricing (backend + FE)Medium
third-party-api.mdExternal API overviewNội dung tổng quan, chưa cụ thể theo spec external mớiĐồng bộ lại theo OpenAPI external (nhóm endpoints listings, bookings, webhooks, iCal nếu có) và link tới guides/external-api, guides/bookingsHigh
x-team-id-guide.mdHeader & pathĐã update X-Team-ID, cần đảm bảo danh sách endpoints bắt buộc/không bắt buộc khớp spec mớiSau khi OpenAPI cập nhật, so lại bảng endpoints và chỉnh mô tả cho khớp (ưu tiên team management, financial, bookings theo team)High
……………

3. Plan chỉnh sửa docs theo nhóm​

Sau khi cross-check, thực hiện update theo ba nhóm lớn:

3.1. Nhóm API Docs (OpenAPI-generated)​

  • Không chỉnh tay file generated (trong docs/api/internal, docs/api/external).
  • Khi cần đổi:
    • Cập nhật OpenAPI spec trong backend.
    • Re-export → npm run gen-api-docs.
  • Checklist:
    • Đảm bảo description/summary của endpoint đủ rõ (FE/3rd party dễ hiểu).
    • Thêm examples quan trọng trong OpenAPI (request/response).

3.2. Nhóm Guides (Đã cập nhật)​

Các guides chính đã có skeleton + nội dung:

  • guides/getting-started
  • guides/authentication
  • guides/listings
  • guides/bookings
  • guides/payments
  • guides/error-handling
  • guides/rate-limiting
  • guides/roles-permissions
  • guides/webhooks
  • guides/ical-sync
  • guides/external-api

Việc còn lại chủ yếu là:

  • Tinh chỉnh wording sau khi spec ổn định (tên field, enum, error codes).
  • Thêm ví dụ nâng cao (multi-listing booking, complex pricing, advanced search).

3.3. Nhóm Architecture​

Sau cross-check (mục 2), update:

  • overview.md:
    • Cập nhật high-level feature nếu có module mới.
  • booking-flow.md:
    • Đồng bộ với guides/bookings + spec mới.
  • listing-management.md:
    • Đồng bộ với guides/listings + spec mới.
  • third-party-api.md:
    • Đồng bộ với guides/external-api + integration docs.
  • x-team-id-guide.md:
    • Đảm bảo là single source of truth về team context.

4. Trạng thái TODO (high-level)​

Liên kết với TODO hiện tại trong repo:

  • openapi-sync-internal-external:
    • Thực thi các bước tại mục 1.1–1.2.
  • architecture-docs-crosscheck:
    • Thực hiện checklist tại mục 2, ghi lại bảng chênh lệch.
  • define-update-plan:
    • File này (docs-update-plan.md) chính là hiện thân của plan tổng quát; có thể mở rộng thêm khi phát hiện chênh lệch mới.