source: update Base rule Agent

2026-03-09 18:01:01 +07:00
parent 3003a0ff0b
commit fd9f558fa1
22 changed files with 501 additions and 1426 deletions
--- a/Architecture/C4_Code.md
+++ b/Architecture/C4_Code.md
@@ -1,24 +1,24 @@
-# Tài liệu Kiến trúc C4 - Mức 4: Code Documentation (Frontend Store)
+# C4 Architecture Document - Level 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.
+Detailed description of the state management structure on the Frontend to support complex business flows.

 ## 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.
+To ensure customer data is retained when navigating between pages (Selecting Product -> Going back to edit info -> Viewing PDF), a Global Store is utilized.

 ### `useCustomerStore`
 - **State**:
  - `personalInfo`: { name, cccd, dob, gender, ... }
  - `ocrStatus`: 'idle' | 'scanning' | 'success' | 'error'
  - `selectedProduct`: 'UVL-IC' | 'UVL-EL' | null
-  - `illustrationUrl`: string (Link PDF)
+  - `illustrationUrl`: string (PDF Link)

 - **Actions**:
  - `updateInfo(field, value)`
  - `setOCRData(data)`
  - `resetSession()`

-## 2. Sequence Diagram: Luồng OCR & Tạo PDF
+## 2. Sequence Diagram: OCR & PDF Generation Flow

 ```mermaid
 sequenceDiagram
@@ -28,21 +28,21 @@ sequenceDiagram
    participant OCR as OCR Service
    participant PDF as PDF Engine

-    User->>FE: Upload ảnh CCCD
+    User->>FE: Upload ID Card image
    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)
+    FE-->>User: Display Form (pre-filled)

-    User->>FE: Chọn SP & Nhấn "Xem Minh Họa"
+    User->>FE: Select Product & Click "View Illustration"
    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
+    FE-->>User: Display PDF Viewer
 ```

 ---
-*Biên soạn bởi: Agent mbl-landing-page-architecture*
+*Authored by: Agent mbl-landing-page-architecture*
--- a/Architecture/C4_Component.md
+++ b/Architecture/C4_Component.md
@@ -1,31 +1,31 @@
-# Tài liệu Kiến trúc C4 - Mức 3: Component Diagram (Landing Page)
+# C4 Architecture Document - Level 3: Component Diagram (Landing Page)

-Chi tiết hóa các thành phần logic trong **Sales Landing App** và **BFF Service**.
+Detailed breakdown of the logical components within the **Sales Landing App** and **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.
+- **Auth Module**: Login form, Token handling.
+- **Customer Module**: Input form, Camera/Upload Component for OCR.
+- **Product Module**: Product selection interface (Card selection for UVL-IC/UVL-EL).
+- **Illustration Module**: PDF display (PDF Viewer) and download/Submit buttons.

 ### 1.2. Shared
- **UI Kit**: Button, Input, Modal (theo Design System).
- **API Client**: Axios wrapper để gọi BFF.
+- **UI Kit**: Button, Input, Modal (matching the Design System).
+- **API Client**: Axios wrapper for calling the 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.
+- **AuthController**: Authentication via Auth API.
+- **OCRController**: Proxies images to the OCR Service.
+- **IllustrationController**: Aggregates data -> Calls PDF Engine -> Returns URL/File.
+- **SubmissionController**: Submits final data to the Core system.

 ### 2.2. Services
- **ClientService**: Lưu/Lấy thông tin khách hàng từ Database.
+- **ClientService**: Saves/Retrieves customer information from the Database.

-## 3. Sơ đồ Component
+## 3. Component Diagram

 ```mermaid
 C4Component
@@ -58,4 +58,4 @@ C4Component
 ```

 ---
-*Biên soạn bởi: Agent mbl-landing-page-architecture*
+*Authored by: Agent mbl-landing-page-architecture*
--- a/Architecture/C4_Container.md
+++ b/Architecture/C4_Container.md
@@ -1,54 +1,54 @@
-# Tài liệu Kiến trúc C4 - Mức 2: Container Diagram (Landing Page)
+# C4 Architecture Document - Level 2: Container Diagram (Landing Page)

-Mô tả các thành phần triển khai của hệ thống Landing Page.
+Describes the deployable components of the Landing Page system.

-## 1. Danh sách Container
+## 1. Container List

 ### 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.
+- **Technology**: React, Vite, TailwindCSS.
+- **Role**: Provides the interactive interface (Responsive).
+- **Features**: Data input forms, Camera capture (for OCR), PDF Viewer, product navigation.

 ### 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.
+- **Technology**: Node.js / Express (or Serverless Functions).
+- **Role**: Secures intermediary and API coordinator.
+- **Features**:
+    - Hides Tokens/Secrets when making calls to the OCR and PDF APIs.
+    - Manages user sessions.
+    - Sanitizes and normalizes data before dispatching.

 ### 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.
+- **Technology**: PostgreSQL (or Redis/LocalStorage depending on long-term storage needs). *Based on the requirement to save customer data for future visits, PostgreSQL will be used.*
+- **Role**: Stores draft customer information and temporary illustration history.

-## 2. Sơ đồ Container
+## 2. Container Diagram

 ```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.")
+    Person(sales_agent, "Sales Agent", "Using personal device.")

    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.")
+        Container(web_app, "Sales Landing App", "React/Vite", "Mobile-first user interface.")
+        Container(bff_api, "BFF Service", "Node.js", "Intermediary logic and security handler.")
+        ContainerDb(local_db, "Client Cache DB", "PostgreSQL", "Stores draft customer information.")
    }

-    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")
+    System_Ext(auth_api, "Auth API", "Authentication")
+    System_Ext(ocr_service, "OCR Service", "Image processing")
+    System_Ext(pdf_engine, "PDF Engine", "PDF Generation")
+    System_Ext(core_system, "Core System", "Stores contracts")

-    Rel(sales_agent, web_app, "Tương tác", "HTTPS")
+    Rel(sales_agent, web_app, "Interacts", "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")
+    Rel(bff_api, local_db, "Read/Write Customer Data", "SQL")
+    Rel(bff_api, auth_api, "Auth Proxy", "REST")
+    Rel(bff_api, ocr_service, "Calls OCR", "REST")
+    Rel(bff_api, pdf_engine, "Calls PDF Gen", "REST")
+    Rel(bff_api, core_system, "Submits application", "REST")
 ```

 ---
-*Biên soạn bởi: Agent mbl-landing-page-architecture*
+*Authored by: Agent mbl-landing-page-architecture*
--- a/Architecture/C4_Context.md
+++ b/Architecture/C4_Context.md
@@ -1,58 +1,58 @@
-# Tài liệu Kiến trúc C4 - Mức 1: System Context (Landing Page)
+# C4 Architecture Document - Level 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.
+This document describes the system context of the **Sales Landing Page**, focusing on supporting sales agents in presenting and initiating insurance policies.

-## 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ị.
+## 1. System Overview
+The **Landing Page Sales Party** is a web application that helps sales agents log in, manage customer data (OCR), and generate illustration boards (PDFs) for insurance products (UVL-IC, UVL-EL) across multiple devices.

-## 2. Personas (Tác nhân)
+## 2. Personas (Actors)

-### 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ơ.
+### Sales Agent
+- **Type**: Primary User.
+- **Description**: Uses a Laptop or Mobile device to consult directly with customers.
+- **Goal**: Rapid data entry (OCR), instant presentation of illustration boards, and on-the-spot contract closure.
+- **Key Features**: Login, Scan ID Card, Select Product, View/Download PDF, Submit Application.

-## 3. Các hệ thống bên ngoài (External Systems)
+## 3. 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.
+- **Role**: Authenticates the Sales Agent's account.
+- **Protocol**: 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.
+### OCR Service
+- **Role**: Extracts customer information from ID Card images.
+- **Protocol**: 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.
+### Illustration PDF API (PDF Engine)
+- **Role**: Calculates benefits and renders the illustration PDF file.
+- **Protocol**: 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.
+### Core Insurance System (Core System)
+- **Role**: Receives the insurance application (upon Sales submission).
+- **Protocol**: REST/SOAP API.

-## 4. Sơ đồ System Context (C4 Context Diagram)
+## 4. System Context Diagram (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.")
+    Person(sales_agent, "Sales Agent", "Uses the Landing Page to consult and close deals.")

-    System(landing_system, "Landing Page System", "Cho phép nhập liệu KH, xem minh họa và nộp hồ sơ.")
+    System(landing_system, "Landing Page System", "Allows customer data entry, viewing illustrations, and submitting applications.")

-    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.")
+    System_Ext(auth_api, "Auth API", "Sales account authentication system.")
+    System_Ext(ocr_service, "OCR Service", "Extracts ID Card data.")
+    System_Ext(pdf_engine, "PDF Generator API", "Generates the illustration PDF file.")
+    System_Ext(core_system, "Core Insurance System", "Records the contract.")

-    Rel(sales_agent, landing_system, "Truy cập, nhập liệu, xem PDF", "HTTPS")
+    Rel(sales_agent, landing_system, "Accesses, inputs data, views 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")
+    Rel(landing_system, auth_api, "Authenticates user", "REST/JSON")
+    Rel(landing_system, ocr_service, "Sends ID image", "REST/JSON")
+    Rel(landing_system, pdf_engine, "Sends data to fetch PDF", "REST/JSON")
+    Rel(landing_system, core_system, "Submits application", "REST/JSON")
 ```

 ---
-*Biên soạn bởi: Agent mbl-landing-page-architecture*
+*Authored by: Agent mbl-landing-page-architecture*
--- a/Architecture/README.md
+++ b/Architecture/README.md
@@ -1,24 +1,24 @@
-# Hệ thống Tài liệu Kiến trúc C4 - Landing Page Sales Party
+# C4 Architecture Documentation System - 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.
+This repository consolidates the system architecture for the **Landing Page for Sales** project, helping the development team grasp the structure from a broad overview down to intricate details.

-## Mục lục Tài liệu
+## Document Index

 ### [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.
+- **Description**: The big picture of interactions between the Sales Agent, the Landing Page system, and external partners (OCR, Auth, Core).
+- **Focus**: Identifying system boundaries and integration points.

 ### [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.
+- **Description**: Decomposing the system into the Web App (Frontend), BFF (Backend), and Database.
+- **Technologies**: 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.
+- **Description**: The internal structure of the Frontend (Modules) and Backend BFF (Controllers/Services).
+- **Focus**: Processing logic for OCR and illustration generation.

 ### [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.
+- **Description**: Detailed data processing flows (Sequence Diagram) and State management on the Frontend.
+- **Focus**: The data synchronization mechanism between the input form and the PDF Viewer.

 ---
-*Được cập nhật mới nhất bởi: Agent mbl-landing-page-architecture*
+*Last updated by: Agent mbl-landing-page-architecture*