source: Add rules for AI Coding

2026-03-09 16:51:44 +07:00
parent 4b7236493f
commit 3003a0ff0b
27 changed files with 2103 additions and 70 deletions
--- a/Architecture/C4_Code.md
+++ b/Architecture/C4_Code.md
@@ -0,0 +1,48 @@
+# Tài liệu Kiến trúc C4 - Mức 4: Code Documentation (Frontend Store)
+
+Mô tả chi tiết cấu trúc quản lý dữ liệu (State Management) tại Frontend để phục vụ luồng nghiệp vụ phức tạp.
+
+## 1. Global State (Zustand/Context)
+
+Để đảm bảo dữ liệu khách hàng được lưu giữ khi chuyển giữa các trang (Chọn sản phẩm -> Quay lại sửa thông tin -> Xem PDF), sử dụng Global Store.
+
+### `useCustomerStore`
+- **State**:
+  - `personalInfo`: { name, cccd, dob, gender, ... }
+  - `ocrStatus`: 'idle' | 'scanning' | 'success' | 'error'
+  - `selectedProduct`: 'UVL-IC' | 'UVL-EL' | null
+  - `illustrationUrl`: string (Link PDF)
+
+- **Actions**:
+  - `updateInfo(field, value)`
+  - `setOCRData(data)`
+  - `resetSession()`
+
+## 2. Sequence Diagram: Luồng OCR & Tạo PDF
+
+```mermaid
+sequenceDiagram
+    participant User as Sales Agent
+    participant FE as Frontend (Store)
+    participant BFF as Backend BFF
+    participant OCR as OCR Service
+    participant PDF as PDF Engine
+
+    User->>FE: Upload ảnh CCCD
+    FE->>BFF: POST /api/ocr (image)
+    BFF->>OCR: Extract Info
+    OCR-->>BFF: {name, cccd, dob...}
+    BFF-->>FE: Return JSON
+    FE->>FE: Update Store (personalInfo)
+    FE-->>User: Hiển thị Form (đã điền sẵn)
+
+    User->>FE: Chọn SP & Nhấn "Xem Minh Họa"
+    FE->>BFF: POST /api/illustration {info, product}
+    BFF->>PDF: Generate Request
+    PDF-->>BFF: PDF Stream/URL
+    BFF-->>FE: Return URL
+    FE-->>User: Hiển thị PDF Viewer
+```
+
+---
+*Biên soạn bởi: Agent mbl-landing-page-architecture*
--- a/Architecture/C4_Component.md
+++ b/Architecture/C4_Component.md
@@ -0,0 +1,61 @@
+# Tài liệu Kiến trúc C4 - Mức 3: Component Diagram (Landing Page)
+
+Chi tiết hóa các thành phần logic trong **Sales Landing App** và **BFF Service**.
+
+## 1. Frontend Components (Sales Landing App)
+
+### 1.1. Modules
+- **Auth Module**: Form đăng nhập, xử lý Token.
+- **Customer Module**: Form nhập liệu, Component Camera/Upload cho OCR.
+- **Product Module**: Giao diện chọn sản phẩm (Card chọn UVL-IC/UVL-EL).
+- **Illustration Module**: Hiển thị PDF (PDF Viewer) và nút tải về/Submit.
+
+### 1.2. Shared
+- **UI Kit**: Button, Input, Modal (theo Design System).
+- **API Client**: Axios wrapper để gọi BFF.
+
+## 2. Backend Components (BFF Service)
+
+### 2.1. Controllers
+- **AuthController**: Xác thực với Auth API.
+- **OCRController**: Proxy ảnh sang OCR Service.
+- **IllustrationController**: Tổng hợp dữ liệu -> Gọi PDF Engine -> Trả về URL/File.
+- **SubmissionController**: Gửi dữ liệu cuối cùng về Core.
+
+### 2.2. Services
+- **ClientService**: Lưu/Lấy thông tin khách hàng từ Database.
+
+## 3. Sơ đồ Component
+
+```mermaid
+C4Component
+    title Component Diagram - Landing Page System
+
+    Container_Boundary(frontend, "Sales Landing App") {
+        Component(c_auth, "Auth Module", "React", "Login Screen")
+        Component(c_cust, "Customer Module", "React", "Form & OCR Upload")
+        Component(c_pdf, "Illustration Module", "React", "PDF View & Submit")
+    }
+
+    Container_Boundary(backend, "BFF Service") {
+        Component(ctl_ocr, "OCR Controller", "Node.js", "Handle Upload & Proxy")
+        Component(ctl_ill, "Illustration Controller", "Node.js", "Coordinate PDF Gen")
+        Component(svc_client, "Client Service", "Node.js", "Manage Client Data DB")
+    }
+
+    ContainerDb(db, "PostgreSQL", "Database", "Store Drafts")
+    System_Ext(ocr_ext, "External OCR", "Service")
+    System_Ext(pdf_ext, "External PDF Gen", "Service")
+
+    Rel(c_auth, ctl_ocr, "Authenticated Req")
+    Rel(c_cust, ctl_ocr, "Upload Image")
+    Rel(c_cust, ctl_ill, "Request PDF")
+    
+    Rel(ctl_ocr, ocr_ext, "Proxy")
+    Rel(ctl_ill, pdf_ext, "Proxy")
+    Rel(ctl_ill, svc_client, "Save Info")
+    Rel(svc_client, db, "Persist")
+```
+
+---
+*Biên soạn bởi: Agent mbl-landing-page-architecture*
--- a/Architecture/C4_Container.md
+++ b/Architecture/C4_Container.md
@@ -0,0 +1,54 @@
+# Tài liệu Kiến trúc C4 - Mức 2: Container Diagram (Landing Page)
+
+Mô tả các thành phần triển khai của hệ thống Landing Page.
+
+## 1. Danh sách Container
+
+### 1.1. Sales Landing App (Frontend)
+- **Công nghệ**: React, Vite, TailwindCSS.
+- **Vai trò**: Cung cấp giao diện tương tác (Responsive).
+- **Chức năng**: Form nhập liệu, Camera capture (cho OCR), PDF Viewer, điều hướng sản phẩm.
+
+### 1.2. Backend For Frontend (BFF)
+- **Công nghệ**: Node.js / Express (hoặc Serverless Functions).
+- **Vai trò**: Trung gian bảo mật và điều phối API.
+- **Chức năng**:
+    - Ẩn các Token/Secret khi gọi OCR và PDF API.
+    - Quản lý session người dùng.
+    - Chuẩn hóa dữ liệu trước khi gửi đi.
+
+### 1.3. Local Storage / Caching DB
+- **Công nghệ**: PostgreSQL (hoặc Redis/LocalStorage tùy yêu cầu lưu lâu dài). *Dựa trên yêu cầu lưu lại khách hàng lần sau, sẽ dùng PostgreSQL.*
+- **Vai trò**: Lưu nháp thông tin khách hàng và lịch sử minh họa tạm thời.
+
+## 2. Sơ đồ Container
+
+```mermaid
+C4Container
+    title Container Diagram - Landing Page Sales Party
+
+    Person(sales_agent, "Nhân viên kinh doanh", "Sử dụng thiết bị cá nhân.")
+
+    System_Boundary(landing_zone, "Landing Page System") {
+        Container(web_app, "Sales Landing App", "React/Vite", "Giao diện người dùng Mobile-first.")
+        Container(bff_api, "BFF Service", "Node.js", "Xử lý logic trung gian và bảo mật.")
+        ContainerDb(local_db, "Client Cache DB", "PostgreSQL", "Lưu thông tin khách hàng nháp.")
+    }
+
+    System_Ext(auth_api, "Auth API", "Xác thực")
+    System_Ext(ocr_service, "OCR Service", "Xử lý ảnh")
+    System_Ext(pdf_engine, "PDF Engine", "Tạo PDF")
+    System_Ext(core_system, "Core System", "Lưu hợp đồng")
+
+    Rel(sales_agent, web_app, "Tương tác", "HTTPS")
+    Rel(web_app, bff_api, "API Call", "JSON/HTTPS")
+    
+    Rel(bff_api, local_db, "Đọc/Ghi dữ liệu KH", "SQL")
+    Rel(bff_api, auth_api, "Proxy xác thực", "REST")
+    Rel(bff_api, ocr_service, "Gọi OCR", "REST")
+    Rel(bff_api, pdf_engine, "Gọi tạo PDF", "REST")
+    Rel(bff_api, core_system, "Submit hồ sơ", "REST")
+```
+
+---
+*Biên soạn bởi: Agent mbl-landing-page-architecture*
--- a/Architecture/C4_Context.md
+++ b/Architecture/C4_Context.md
@@ -0,0 +1,58 @@
+# Tài liệu Kiến trúc C4 - Mức 1: System Context (Landing Page)
+
+Tài liệu này mô tả bối cảnh hệ thống của **Landing Page dành cho Sales**, tập trung vào việc hỗ trợ nhân viên kinh doanh trình diễn và khởi tạo bảo hiểm.
+
+## 1. Tổng quan hệ thống
+**Landing Page Sales Party** là ứng dụng web giúp nhân viên kinh doanh đăng nhập, quản lý khách hàng (OCR), và tạo bảng minh họa (PDF) cho các sản phẩm bảo hiểm (UVL-IC, UVL-EL) trên đa thiết bị.
+
+## 2. Personas (Tác nhân)
+
+### Nhân viên kinh doanh (Sales Agent)
+- **Loại**: Người dùng duy nhất.
+- **Mô tả**: Sử dụng Laptop hoặc Mobile để tư vấn trực tiếp cho khách hàng.
+- **Mục tiêu**: Nhập liệu nhanh (OCR), cho xem bảng minh họa tức thì, chốt hợp đồng tại chỗ.
+- **Tính năng chính**: Login, Scan CCCD, Chọn sản phẩm, Xem/Tải PDF, Submit hồ sơ.
+
+## 3. Các hệ thống bên ngoài (External Systems)
+
+### API Authentication (Existing)
+- **Vai trò**: Xác thực tài khoản của Sales Agent.
+- **Giao thức**: REST API / OIDC.
+
+### Dịch vụ OCR (OCR Service)
+- **Vai trò**: Trích xuất thông tin khách hàng từ ảnh CCCD.
+- **Giao thức**: REST API.
+
+### API Illustration PDF (PDF Engine)
+- **Vai trò**: Tính toán quyền lợi và kết xuất file PDF minh họa.
+- **Giao thức**: REST API.
+
+### Hệ thống Core Bảo hiểm (Core System)
+- **Vai trò**: Tiếp nhận hồ sơ yêu cầu bảo hiểm (khi Sales submit).
+- **Giao thức**: REST/SOAP API.
+
+## 4. Sơ đồ System Context (C4 Context Diagram)
+
+```mermaid
+C4Context
+    title System Context Diagram - Landing Page Sales Party
+
+    Person(sales_agent, "Nhân viên kinh doanh", "Sử dụng Landing Page để tư vấn và chốt đơn.")
+
+    System(landing_system, "Landing Page System", "Cho phép nhập liệu KH, xem minh họa và nộp hồ sơ.")
+
+    System_Ext(auth_api, "Auth API", "Hệ thống xác thực tài khoản Sales.")
+    System_Ext(ocr_service, "OCR Service", "Trích xuất dữ liệu CCCD.")
+    System_Ext(pdf_engine, "PDF Generator API", "Tạo file PDF bản minh họa.")
+    System_Ext(core_system, "Core Insurance System", "Ghi nhận hợp đồng.")
+
+    Rel(sales_agent, landing_system, "Truy cập, nhập liệu, xem PDF", "HTTPS")
+
+    Rel(landing_system, auth_api, "Xác thực người dùng", "REST/JSON")
+    Rel(landing_system, ocr_service, "Gửi ảnh CCCD", "REST/JSON")
+    Rel(landing_system, pdf_engine, "Gửi data để lấy PDF", "REST/JSON")
+    Rel(landing_system, core_system, "Submit hồ sơ", "REST/JSON")
+```
+
+---
+*Biên soạn bởi: Agent mbl-landing-page-architecture*
--- a/Architecture/README.md
+++ b/Architecture/README.md
@@ -0,0 +1,24 @@
+# Hệ thống Tài liệu Kiến trúc C4 - Landing Page Sales Party
+
+Tài liệu này tổng hợp kiến trúc hệ thống cho dự án **Landing Page dành cho Sales**, giúp đội ngũ phát triển nắm bắt cấu trúc từ tổng quan đến chi tiết.
+
+## Mục lục Tài liệu
+
+### [Level 1: System Context](./C4_Context.md)
+- **Mô tả**: Bức tranh tổng thể về tương tác giữa Sales Agent và hệ thống Landing Page cùng các đối tác (OCR, Auth, Core).
+- **Trọng tâm**: Xác định ranh giới hệ thống và các điểm tích hợp.
+
+### [Level 2: Container Diagram](./C4_Container.md)
+- **Mô tả**: Phân rã hệ thống thành Web App (Frontend), BFF (Backend), và Database.
+- **Công nghệ**: React, Node.js, PostgreSQL.
+
+### [Level 3: Component Diagram](./C4_Component.md)
+- **Mô tả**: Cấu trúc nội bộ của Frontend (Modules) và Backend BFF (Controllers/Services).
+- **Trọng tâm**: Logic xử lý OCR và tạo bảng minh họa.
+
+### [Level 4: Code Documentation](./C4_Code.md)
+- **Mô tả**: Chi tiết luồng xử lý dữ liệu (Sequence Diagram) và quản lý State tại Frontend.
+- **Trọng tâm**: Cơ chế đồng bộ dữ liệu giữa Form nhập liệu và PDF Viewer.
+
+---
+*Được cập nhật mới nhất bởi: Agent mbl-landing-page-architecture*