chore: update project documentation, audit reports, and initialize IDE configuration files

docs/api-error-codes.md

@@ -1,10 +1,10 @@
-# API Error Codes Reference
+# Tài Liệu Tham Khảo Mã Lỗi API
 
-All GoodGo Platform API errors follow a structured JSON format. This document lists every `errorCode` value, its HTTP status, description, and usage examples.
+Tất cả các lỗi của GoodGo Platform API đều tuân theo định dạng JSON có cấu trúc thống nhất. Tài liệu này liệt kê mọi giá trị `errorCode`, mã HTTP tương ứng, mô tả và ví dụ sử dụng.
 
-## Error Response Format
+## Định Dạng Phản Hồi Lỗi
 
-Every error response from the API has this shape:
+Mỗi phản hồi lỗi từ API có dạng như sau:
 
 ```json
 {
@@ -19,42 +19,42 @@ Every error response from the API has this shape:
 
 | Field           | Type     | Description |
 |-----------------|----------|-------------|
-| `statusCode`    | `number` | HTTP status code (e.g. `400`, `401`, `404`). |
-| `errorCode`     | `string` | Machine-readable error identifier (see tables below). |
-| `message`       | `string` | Human-readable explanation (Vietnamese for business rules, English for system errors). |
-| `details`       | `object` | Optional structured metadata (e.g. validation field names, current/target status). |
-| `correlationId` | `string` | Echoed from the `X-Correlation-Id` request header when present. |
-| `timestamp`     | `string` | ISO 8601 timestamp of the error occurrence. |
+| `statusCode`    | `number` | Mã HTTP status (ví dụ: `400`, `401`, `404`). |
+| `errorCode`     | `string` | Mã lỗi dạng máy đọc được (xem các bảng bên dưới). |
+| `message`       | `string` | Giải thích dạng người đọc được (tiếng Việt cho các quy tắc nghiệp vụ, tiếng Anh cho lỗi hệ thống). |
+| `details`       | `object` | Metadata có cấu trúc tùy chọn (ví dụ: tên trường validation, trạng thái hiện tại/mục tiêu). |
+| `correlationId` | `string` | Phản chiếu từ header `X-Correlation-Id` của request khi có. |
+| `timestamp`     | `string` | Dấu thời gian ISO 8601 tại thời điểm xảy ra lỗi. |
 
 ---
 
-## General Error Codes
+## Mã Lỗi Chung
 
-These codes apply across all modules. They are also used as fallback codes when a plain `HttpException` (without a domain error code) is thrown.
+Các mã này áp dụng cho tất cả các module. Chúng cũng được dùng làm mã dự phòng khi một `HttpException` thông thường (không có mã lỗi domain) được ném ra.
 
 | Error Code | HTTP Status | Description | When It Occurs |
 |---|---|---|---|
-| `INTERNAL_ERROR` | `500` | Unexpected server error. | Unhandled exceptions, infrastructure failures. |
-| `VALIDATION_FAILED` | `400` | Request data failed validation. | Invalid input fields, business rule violations (e.g. invalid phone format, bad status transitions). |
-| `NOT_FOUND` | `404` | Requested resource does not exist. | Entity lookup by ID returns no result. |
-| `CONFLICT` | `409` | Resource state conflict. | Duplicate creation, conflicting state transition. |
-| `UNAUTHORIZED` | `401` | Authentication required or failed. | Missing/invalid/expired auth token, bad credentials. |
-| `FORBIDDEN` | `403` | Insufficient permissions. | Role-based access denial, CSRF token failure, resource ownership mismatch. |
-| `BAD_REQUEST` | `400` | Malformed request. | Invalid file upload, unsupported content type, bad query parameters. |
-| `TOO_MANY_REQUESTS` | `429` | Rate limit exceeded. | Too many API requests in a short period. |
+| `INTERNAL_ERROR` | `500` | Lỗi máy chủ không mong đợi. | Ngoại lệ chưa được xử lý, lỗi hạ tầng. |
+| `VALIDATION_FAILED` | `400` | Dữ liệu request không qua xác thực. | Trường dữ liệu không hợp lệ, vi phạm quy tắc nghiệp vụ (ví dụ: định dạng số điện thoại sai, chuyển trạng thái không hợp lệ). |
+| `NOT_FOUND` | `404` | Tài nguyên được yêu cầu không tồn tại. | Tra cứu thực thể theo ID không có kết quả. |
+| `CONFLICT` | `409` | Xung đột trạng thái tài nguyên. | Tạo trùng lặp, chuyển đổi trạng thái xung đột. |
+| `UNAUTHORIZED` | `401` | Yêu cầu xác thực hoặc xác thực thất bại. | Token xác thực thiếu/không hợp lệ/hết hạn, thông tin đăng nhập sai. |
+| `FORBIDDEN` | `403` | Không đủ quyền truy cập. | Từ chối quyền theo vai trò, lỗi CSRF token, không khớp quyền sở hữu tài nguyên. |
+| `BAD_REQUEST` | `400` | Request không đúng định dạng. | Tải lên tệp không hợp lệ, loại nội dung không được hỗ trợ, tham số truy vấn sai. |
+| `TOO_MANY_REQUESTS` | `429` | Vượt quá giới hạn tốc độ. | Gửi quá nhiều request API trong thời gian ngắn. |
 
 ---
 
-## Auth Error Codes
+## Mã Lỗi Xác Thực
 
 | Error Code | HTTP Status | Description | When It Occurs |
 |---|---|---|---|
-| `AUTH_INVALID_CREDENTIALS` | `401` | Login credentials are incorrect. | Phone number or password mismatch during local login. |
-| `AUTH_TOKEN_EXPIRED` | `401` | JWT token has expired. | Access token or refresh token past expiration. |
-| `AUTH_TOKEN_INVALID` | `401` | JWT token is malformed or tampered with. | Token signature verification failure. |
-| `AUTH_INSUFFICIENT_PERMISSIONS` | `403` | Authenticated user lacks required role/permission. | Non-admin accessing admin endpoints, role mismatch. |
+| `AUTH_INVALID_CREDENTIALS` | `401` | Thông tin đăng nhập không chính xác. | Số điện thoại hoặc mật khẩu không khớp khi đăng nhập nội bộ. |
+| `AUTH_TOKEN_EXPIRED` | `401` | JWT token đã hết hạn. | Access token hoặc refresh token đã quá thời gian hết hạn. |
+| `AUTH_TOKEN_INVALID` | `401` | JWT token bị sai định dạng hoặc bị giả mạo. | Xác minh chữ ký token thất bại. |
+| `AUTH_INSUFFICIENT_PERMISSIONS` | `403` | Người dùng đã xác thực không có vai trò/quyền cần thiết. | Người dùng không phải admin truy cập endpoint admin, không khớp vai trò. |
 
-### Auth Module Usage Examples
+### Ví Dụ Sử Dụng Module Xác Thực
 
 ```json
 // POST /auth/login — wrong password
@@ -88,15 +88,15 @@ These codes apply across all modules. They are also used as fallback codes when
 
 ---
 
-## User Error Codes
+## Mã Lỗi Người Dùng
 
 | Error Code | HTTP Status | Description | When It Occurs |
 |---|---|---|---|
-| `USER_NOT_FOUND` | `404` | User does not exist. | Profile lookup, admin user management. |
-| `USER_ALREADY_EXISTS` | `409` | User with given identifier already exists. | Duplicate registration (phone or email). |
-| `USER_INVALID_PHONE` | `400` | Phone number format is invalid. | Registration or profile update with bad phone format. |
+| `USER_NOT_FOUND` | `404` | Người dùng không tồn tại. | Tra cứu hồ sơ, quản lý người dùng qua admin. |
+| `USER_ALREADY_EXISTS` | `409` | Người dùng với định danh đã cho tồn tại. | Đăng ký trùng lặp (số điện thoại hoặc email). |
+| `USER_INVALID_PHONE` | `400` | Định dạng số điện thoại không hợp lệ. | Đăng ký hoặc cập nhật hồ sơ với số điện thoại sai định dạng. |
 
-### User Module Usage Examples
+### Ví Dụ Sử Dụng Module Người Dùng
 
 ```json
 // GET /auth/profile — deleted or nonexistent user
@@ -116,16 +116,16 @@ These codes apply across all modules. They are also used as fallback codes when
 
 ---
 
-## Listing Error Codes
+## Mã Lỗi Tin Đăng
 
 | Error Code | HTTP Status | Description | When It Occurs |
 |---|---|---|---|
-| `LISTING_NOT_FOUND` | `404` | Listing does not exist. | Lookup by ID for viewing, moderation, or status change. |
-| `LISTING_INVALID_STATUS_TRANSITION` | `400` | Status transition is not allowed. | Attempting an invalid workflow step (e.g. `EXPIRED` → `ACTIVE`). |
-| `LISTING_ALREADY_ACTIVE` | `409` | Listing is already in active state. | Re-activating a listing that is already published. |
-| `LISTING_EXPIRED` | `400` | Listing has expired. | Attempting operations on an expired listing. |
+| `LISTING_NOT_FOUND` | `404` | Tin đăng không tồn tại. | Tra cứu theo ID để xem, kiểm duyệt, hoặc thay đổi trạng thái. |
+| `LISTING_INVALID_STATUS_TRANSITION` | `400` | Chuyển đổi trạng thái không được phép. | Thực hiện bước quy trình không hợp lệ (ví dụ: `EXPIRED` → `ACTIVE`). |
+| `LISTING_ALREADY_ACTIVE` | `409` | Tin đăng đã ở trạng thái hoạt động. | Kích hoạt lại tin đăng đã được xuất bản. |
+| `LISTING_EXPIRED` | `400` | Tin đăng đã hết hạn. | Thực hiện các thao tác trên tin đăng đã hết hạn. |
 
-### Listing Module Usage Examples
+### Ví Dụ Sử Dụng Module Tin Đăng
 
 ```json
 // PATCH /listings/:id/status — invalid transition
@@ -156,13 +156,13 @@ These codes apply across all modules. They are also used as fallback codes when
 
 ---
 
-## Property Error Codes
+## Mã Lỗi Bất Động Sản
 
 | Error Code | HTTP Status | Description | When It Occurs |
 |---|---|---|---|
-| `PROPERTY_NOT_FOUND` | `404` | Property does not exist. | Property lookup for media upload or listing creation. |
+| `PROPERTY_NOT_FOUND` | `404` | Bất động sản không tồn tại. | Tra cứu bất động sản để tải media hoặc tạo tin đăng. |
 
-### Property Module Usage Examples
+### Ví Dụ Sử Dụng Module Bất Động Sản
 
 ```json
 // POST /properties/:id/media — property not found
@@ -182,24 +182,24 @@ These codes apply across all modules. They are also used as fallback codes when
 
 ---
 
-## Media Error Codes
+## Mã Lỗi Media
 
 | Error Code | HTTP Status | Description | When It Occurs |
 |---|---|---|---|
-| `MEDIA_UPLOAD_FAILED` | `500` | File upload to storage provider failed. | S3/cloud storage write failure. |
-| `MEDIA_LIMIT_EXCEEDED` | `400` | Maximum number of media files reached. | Exceeding per-property media limit. |
+| `MEDIA_UPLOAD_FAILED` | `500` | Tải tệp lên nhà cung cấp lưu trữ thất bại. | Lỗi ghi vào S3/cloud storage. |
+| `MEDIA_LIMIT_EXCEEDED` | `400` | Đã đạt số lượng tệp media tối đa. | Vượt quá giới hạn media cho mỗi bất động sản. |
 
 ---
 
-## Payment Error Codes
+## Mã Lỗi Thanh Toán
 
 | Error Code | HTTP Status | Description | When It Occurs |
 |---|---|---|---|
-| `PAYMENT_FAILED` | `500` | Payment processing failed. | Gateway error, provider timeout, payment link creation failure. |
-| `PAYMENT_ALREADY_PROCESSED` | `409` | Payment has already been completed, failed, or refunded. | Duplicate callback, retry on non-pending payment, refunding a non-completed payment. |
-| `PAYMENT_INVALID_AMOUNT` | `400` | Payment amount is invalid. | Zero/negative amount, amount below minimum threshold. |
+| `PAYMENT_FAILED` | `500` | Xử lý thanh toán thất bại. | Lỗi cổng thanh toán, hết thời gian chờ nhà cung cấp, lỗi tạo liên kết thanh toán. |
+| `PAYMENT_ALREADY_PROCESSED` | `409` | Thanh toán đã được hoàn tất, thất bại, hoặc hoàn tiền. | Callback trùng lặp, thử lại trên thanh toán không ở trạng thái chờ, hoàn tiền thanh toán chưa hoàn tất. |
+| `PAYMENT_INVALID_AMOUNT` | `400` | Số tiền thanh toán không hợp lệ. | Số tiền bằng 0/âm, số tiền dưới ngưỡng tối thiểu. |
 
-### Payment Module Usage Examples
+### Ví Dụ Sử Dụng Module Thanh Toán
 
 ```json
 // POST /payments — duplicate idempotency key
@@ -233,17 +233,17 @@ These codes apply across all modules. They are also used as fallback codes when
 
 ---
 
-## Subscription Error Codes
+## Mã Lỗi Gói Dịch Vụ
 
 | Error Code | HTTP Status | Description | When It Occurs |
 |---|---|---|---|
-| `SUBSCRIPTION_NOT_FOUND` | `404` | Subscription does not exist. | Lookup for cancellation, upgrade, or usage metering. |
-| `SUBSCRIPTION_ALREADY_ACTIVE` | `409` | User already has an active subscription. | Attempting to create a second active subscription. |
-| `SUBSCRIPTION_ALREADY_CANCELLED` | `409` | Subscription has already been cancelled. | Re-cancelling a subscription. |
-| `SUBSCRIPTION_INACTIVE` | `409` | Subscription is not in an active state. | Upgrading, expiring, or marking past-due on a non-active subscription. |
-| `QUOTA_EXCEEDED` | `403` | Usage quota for the current plan has been exceeded. | Exceeding listing, lead, or search quota limits. |
+| `SUBSCRIPTION_NOT_FOUND` | `404` | Gói dịch vụ không tồn tại. | Tra cứu để hủy, nâng cấp, hoặc đo lường sử dụng. |
+| `SUBSCRIPTION_ALREADY_ACTIVE` | `409` | Người dùng đã có gói dịch vụ đang hoạt động. | Cố tạo gói dịch vụ hoạt động thứ hai. |
+| `SUBSCRIPTION_ALREADY_CANCELLED` | `409` | Gói dịch vụ đã bị hủy trước đó. | Hủy lại gói dịch vụ đã hủy. |
+| `SUBSCRIPTION_INACTIVE` | `409` | Gói dịch vụ không ở trạng thái hoạt động. | Nâng cấp, hết hạn, hoặc đánh dấu quá hạn trên gói không hoạt động. |
+| `QUOTA_EXCEEDED` | `403` | Đã vượt quá hạn mức sử dụng của gói hiện tại. | Vượt quá giới hạn tin đăng, khách hàng tiềm năng, hoặc tìm kiếm. |
 
-### Subscription Module Usage Examples
+### Ví Dụ Sử Dụng Module Gói Dịch Vụ
 
 ```json
 // POST /subscriptions — already has active subscription
@@ -284,17 +284,17 @@ These codes apply across all modules. They are also used as fallback codes when
 
 ---
 
-## Course Error Codes
+## Mã Lỗi Khóa Học
 
 | Error Code | HTTP Status | Description | When It Occurs |
 |---|---|---|---|
-| `COURSE_NOT_FOUND` | `404` | Course does not exist. | Course lookup by ID. |
-| `COURSE_ALREADY_PUBLISHED` | `409` | Course is already in published state. | Re-publishing an active course. |
-| `COURSE_ENROLLMENT_CLOSED` | `400` | Course enrollment period has ended. | Attempting to enroll after the cutoff date. |
+| `COURSE_NOT_FOUND` | `404` | Khóa học không tồn tại. | Tra cứu khóa học theo ID. |
+| `COURSE_ALREADY_PUBLISHED` | `409` | Khóa học đã ở trạng thái xuất bản. | Xuất bản lại khóa học đang hoạt động. |
+| `COURSE_ENROLLMENT_CLOSED` | `400` | Thời hạn đăng ký khóa học đã kết thúc. | Cố đăng ký sau ngày chốt danh sách. |
 
 ---
 
-## Error Code Quick-Reference (Sorted Alphabetically)
+## Tra Cứu Nhanh Mã Lỗi (Sắp Xếp Theo Bảng Chữ Cái)
 
 | Error Code | HTTP Status | Module |
 |---|---|---|
@@ -333,9 +333,9 @@ These codes apply across all modules. They are also used as fallback codes when
 
 ---
 
-## Frontend Integration Guide
+## Hướng Dẫn Tích Hợp Frontend
 
-### TypeScript Error Type
+### Kiểu Lỗi TypeScript
 
 ```typescript
 interface ApiError {
@@ -348,7 +348,7 @@ interface ApiError {
 }
 ```
 
-### Handling Errors by Code
+### Xử Lý Lỗi Theo Mã
 
 ```typescript
 import axios, { AxiosError } from 'axios';
@@ -391,9 +391,9 @@ async function handleApiCall() {
 }
 ```
 
-### Error Code Constants (Optional)
+### Hằng Số Mã Lỗi (Tùy Chọn)
 
-For type safety, maintain error codes as a union type on the frontend:
+Để đảm bảo an toàn kiểu, hãy duy trì các mã lỗi dưới dạng union type ở phía frontend:
 
 ```typescript
 type ErrorCode =
@@ -434,8 +434,8 @@ type ErrorCode =
 
 ---
 
-## Source Files
+## Tệp Nguồn
 
-- **Error code enum**: `apps/api/src/modules/shared/domain/error-codes.ts`
+- **Enum mã lỗi**: `apps/api/src/modules/shared/domain/error-codes.ts`
 - **Domain exceptions**: `apps/api/src/modules/shared/domain/domain-exception.ts`
 - **Global exception filter**: `apps/api/src/modules/shared/infrastructure/filters/global-exception.filter.ts`