Skip to content

Các quyết định công nghệ ​

Trang này ghi lại vì sao dự án chọn các công nghệ hiện tại, trong chừng mực có bằng chứng. Hầu hết các lựa chọn không có ghi chép lý do được lưu cùng repo, nên trang này tách bạch ba thứ: lựa chọn đang thấy trong code, ý định mà chính code có ghi chú, và các hệ quả quan sát được. Mục đích là để không ai nhầm một suy đoán với một quyết định đã được đưa ra.

Cách đọc ​

  • Dấu hiệu trong code: bằng chứng cho thấy lựa chọn đó đang được dùng.
  • Lý do có ghi chép: chỉ điền khi có lời giải thích được lưu trong repo (chú thích code hoặc README). Nếu không có thì ghi "Chưa có ghi chép về lý do".
  • Quan sát: hệ quả có thể thấy từ code. Đây không phải lý do mà người viết code đã nêu.

Bảng 1: các lựa chọn công nghệ ​

Lựa chọnDấu hiệu trong codeLý do có ghi chép
Next.js App RouterCây src/app/[locale]/, generateMetadata, sitemap.tsChưa có ghi chép về lý do
Tách page.tsx (server) và *-page-client.tsxCác trang công khai trong (main)Chưa có ghi chép về lý do
Redux Toolkit và RTK Querysrc/lib/redux/store.ts, *.api.tsChưa có ghi chép về lý do
Axios bên dưới RTK Queryaxios-base-query.tsREADME chỉ mô tả: interceptor tự động làm mới token
Redux Persist cho auth và chatBotstore.tsChú thích trong code: chỉ lưu user và trạng thái đăng nhập
Tailwind CSS và shadcn/uicomponents.json, src/components/ui/Chưa có ghi chép về lý do
React Hook Form và Zodlogin-form.tsx, *.schema.tsChưa có ghi chép về lý do
CASL cho phân quyền giao diệnsrc/lib/casl/ability.tsREADME chỉ mô tả: ẩn, hiện hoặc vô hiệu hóa phần tử giao diện theo quyền
next-intl với as-neededsrc/i18n/routing.ts, middleware.tsChưa có ghi chép về lý do
Socket.IO cho thông báosocket-provider.tsxChưa có ghi chép về lý do
fetch đọc luồng thay cho EventSourceuse-stream-chat.tsChưa có ghi chép về lý do
@react-pdf/renderer cho xuất CVsrc/features/cv-builder/components/pdf/README chỉ mô tả: "template-driven CV generation"
Jest và React Testing Libraryjest.config.jsChưa có ghi chép về lý do

Bảng 2: ý định được ghi ngay trong code ​

Các chú thích sau là phần hiếm hoi nêu rõ mục đích:

NơiChú thíchÝ nghĩa
src/app/api/proxy-image/route.ts"Solves CORS issues when fetching images from backend"Route tồn tại để dựng PDF không bị chặn CORS
src/app/api/proxy-image/route.ts"Validate URL to prevent SSRF attacks"Chỉ cho phép một danh sách máy chủ ảnh
src/lib/axios/axios-instance.ts"Custom header to avoid infinite retries"Header x-no-retry chặn vòng lặp làm mới token
src/components/auth-initializer.tsx"prevent infinite 401 loop"Không gọi getMe khi không có token
src/app/[locale]/(main)/jobs/external/[id]/page.tsx"Aggregated third-party content stays out of search indexes."Lý do của noindex cho việc làm bên ngoài
src/lib/redux/store.ts"Only persist user and auth status"Giới hạn phần được lưu của slice auth

Bảng 3: hệ quả quan sát được ​

Đây là những điều có thể kết luận từ code. Chúng là đánh đổi đang tồn tại, không phải quyết định đã được thảo luận.

Quan sátHệ quả
Access token nằm trong localStorageMọi script chạy trên trang đều đọc được token. Xem Xác thực
API_BASE_URL viết cứng localhost:8081Không đổi được backend theo môi trường nếu không sửa code. Xem Bối cảnh hệ thống
eslint.ignoreDuringBuilds: truenext build không chạy lint; lỗi lint chỉ lộ khi gọi npm run lint
eslint-config-next bản 13 trên Next.js 15Quy tắc lint có thể không theo kịp Next.js 15
Bảng quyền CASL viết riêng ở frontendKhi quyền ở backend đổi, phải cập nhật thủ công cả hai nơi. Xem Phân quyền
Bốn slice được đăng ký nhưng không dùngState thừa trong store. Xem Quản lý state
Không có E2E, độ phủ hay CIHồi quy ở các luồng đầy đủ không được phát hiện tự động. Xem Kiểm thử

Cách bổ sung lý do ​

Khi một lựa chọn quan trọng cần có lời giải thích, nên ghi lại dưới dạng Architecture Decision Record: bối cảnh, các phương án đã cân nhắc, quyết định và đánh đổi. Thư mục ADR nằm trong kế hoạch của Giai đoạn 3 và chưa được tạo. Trước đó, hãy cập nhật cột "Lý do có ghi chép" của trang này khi chủ dự án xác nhận một lý do.

Source code liên quan ​

Tài liệu kỹ thuật xây dựng theo chuẩn Documentation as Code