DatabreezeService · BeforeLights · Jul 2, 2026 · Jul 2, 2026
diff --git a/CORE_FEATURE_GUIDE.md b/CORE_FEATURE_GUIDE.md
@@ -4,9 +4,9 @@ Bản này giữ đúng cấu trúc project hiện tại:
 
 ```txt
 src/main/java/databreeze
-├── api              # Controller/API layer nhận request từ React/Swagger
+├── api              # Controller/API layer nhận request từ client/Swagger
 ├── config           # Env, Swagger/OpenAPI, CORS/JWT sau này
-├── dto              # Request/Response DTO, không dùng Entity để trả ra FE
+├── dto              # Request/Response DTO, không dùng Entity để trả ra client
 ├── entity           # JPA Entity map trực tiếp bảng DB
 ├── enums            # Enum dùng chung
 ├── repository       # Lớp giao tiếp DB, extends JpaRepository
@@ -19,15 +19,15 @@ src/main/java/databreeze
 Không transfer dữ liệu thuần qua Entity.
 
 ```txt
-React/Swagger request
+Client/Swagger request
     → DTO Request
     → Controller
     → Service interface
     → Service implementation
     → Repository
     → Entity/DB
     → DTO Response
-    → React
+    → client
 ```
 
 Entity chỉ dùng ở tầng service/repository để map DB. Controller chỉ nhận/trả DTO.
@@ -92,15 +92,15 @@ service/ai
 ### EtlImportService
 
 #### uploadAndAnalyze(...)
-- Nhận file Excel/CSV từ FE.
+- Nhận file Excel/CSV từ client.
 - Chỉ cho phép `SHOPEE + MARKETPLACE_ORDER` trong MVP.
 - Gọi `TargetSchemaService.getActiveSchema()` để lấy schema Shopee VN.
 - Gọi `FileParsingService.parse()` để đọc header + rows.
 - Lưu file vào local storage.
 - Lưu metadata vào `uploads`.
 - Tạo `import_jobs`.
 - Gọi `RawRowService.saveRawRows()` để lưu dữ liệu gốc vào `raw_import_rows`.
-- Trả `UploadFileResponse` cho FE gồm `uploadId`, `importJobId`, `headers`, `sampleRows`.
+- Trả `UploadFileResponse` cho client gồm `uploadId`, `importJobId`, `headers`, `sampleRows`.
 
 #### suggestMapping(importJobId, request)
 - Load lại file đã upload từ `raw_import_rows`.
@@ -109,13 +109,13 @@ service/ai
 - Rule Shopee VN chạy trước.
 - AI chỉ được gọi nếu `request.useAi=true` và `APP_AI_ENABLED=true`.
 - Lưu mapping vào `import_column_mappings` với `userConfirmed=false`.
-- Trả `SuggestMappingResponse` để FE hiển thị Schema Change Report.
+- Trả `SuggestMappingResponse` để client xử lý mapping.
 
 #### confirmMapping(importJobId, request)
-- FE gửi mapping user đã xác nhận/chỉnh sửa.
+- Client gửi mapping user đã xác nhận/chỉnh sửa.
 - Service kiểm tra field bắt buộc như `external_order_id`, `sku`.
 - Lưu mapping với `userConfirmed=true`.
-- Nếu thiếu field bắt buộc thì trả `missingRequiredFields` để FE chặn import.
+- Nếu thiếu field bắt buộc thì trả `missingRequiredFields`.
 
 #### runImport(importJobId, request)
 - Kiểm tra mapping đã confirmed.
@@ -125,7 +125,7 @@ service/ai
 - Cập nhật `import_jobs` thành `COMPLETED` hoặc `FAILED`.
 
 #### getStatus(importJobId)
-- Trả trạng thái job cho FE polling.
+- Trả trạng thái job cho client polling.
 
 ### FileParsingService
 
@@ -156,7 +156,7 @@ service/ai
 #### persistMappings(...)
 - Xóa mapping cũ của job.
 - Lưu mapping mới vào `import_column_mappings`.
-- Cho phép FE chỉnh mapping nhiều lần trước khi import.
+- Cho phép client gửi lại mapping nhiều lần trước khi import.
 
 ### ShopeeOrderImportService
 
@@ -234,7 +234,7 @@ Flow đúng:
 ```txt
 Rule Shopee VN
     → AI bổ sung cột khó nếu bật
-    → FE hiển thị mapping
+    → client xử lý mapping
     → User xác nhận
     → BE mới import
 ```

diff --git a/docs/AGENT_BACKEND_GUIDE.md b/docs/AGENT_BACKEND_GUIDE.md
@@ -59,15 +59,15 @@ The project contains both `dto/shopee` and `dto/shoppee`. The correctly spelled
 ## High-Level Data Flow
 
 ```text
-Frontend / Swagger request
+Client / Swagger request
   -> DTO request
   -> Controller
   -> Service interface
   -> Service implementation
   -> Repository
   -> Entity / PostgreSQL
   -> DTO response
-  -> Frontend
+  -> Client
 ```
 
 Controllers should not expose JPA entities directly.
@@ -395,7 +395,7 @@ When adding billing limits:
 1. Store durable counters in PostgreSQL.
 2. Use Redis only for short-lived throttles or locks.
 3. Make limit errors user-readable.
-4. Keep plan catalog and UI plan display in sync.
+4. Keep plan catalog and client-facing plan responses in sync.
 
 When changing auth:
 

diff --git a/docs/DataBreeze_User_Flow_APIs_VN.md b/docs/DataBreeze_User_Flow_APIs_VN.md
@@ -1,6 +1,6 @@
 # DataBreeze BE - User Flow APIs
 
-File nay note cac API user-flow moi bo sung de FE co the dung app end-to-end sau khi import Shopee.
+File nay note cac API user-flow moi bo sung sau khi import Shopee.
 
 ## ETL history
 
@@ -81,15 +81,3 @@ Body tao chi phi:
   "allocationMethod": "MANUAL"
 }
 ```
-
-## FE flow goi y
-
-1. Tao/list store: `GET/POST /stores`.
-2. Upload Shopee voi `storeId`.
-3. Suggest mapping, confirm mapping, run import.
-4. Lay `dashboardUrl`, `minBusinessDate`, `maxBusinessDate` tu response run import.
-5. Goi dashboard Shopee de hien KPI/chart/top products.
-6. Goi missing-skus de nhap gia von SKU con thieu.
-7. Tao product-costs, sau do goi apply COGS.
-8. Goi generate insights voi cung `storeId/fromDate/toDate`.
-9. Goi list insights co filter `storeId/fromDate/toDate` de tranh hien insight cu.
diff --git a/docs/PRODUCT_REQUIREMENTS.md b/docs/PRODUCT_REQUIREMENTS.md
@@ -4,7 +4,7 @@ This document preserves the product meaning behind DataBreeze so backend agents
 
 ## Product Vision
 
-DataBreeze is an AI-assisted Vietnamese-first data pipeline and business insight workspace. It helps SMEs, online sellers, and technical teams turn messy files into clean dashboards without writing code or hiring a data team.
+DataBreeze is an AI-assisted Vietnamese-first data pipeline and business insight workspace. It helps SMEs, online sellers, and technical teams turn messy files into clean business data without writing code or hiring a data team.
 
 The product should become a trusted workflow layer between raw business exports and decision-making.
 
@@ -14,7 +14,7 @@ The product should become a trusted workflow layer between raw business exports
 Upload messy files.
 Map columns safely.
 Clean and validate data.
-See profit dashboards and business warnings.
+See profit data and business warnings.
 Reuse the workflow next time.
 ```
 
@@ -38,12 +38,9 @@ The first product experience should work for a single seller with one to three s
 
 Needs:
 
-- Simple onboarding.
 - Store setup.
 - Shopee/TikTok/Ads file upload.
-- Clear dashboard.
 - Missing cost warnings.
-- "What should I fix?" guidance.
 
 ### Multi-Shop Seller
 
@@ -52,7 +49,6 @@ This user operates several shops or channels and needs comparison.
 Needs:
 
 - Store filters.
-- All-store dashboard.
 - Per-store profit.
 - Repeatable mapping templates.
 - Upload history.
@@ -71,7 +67,7 @@ Needs:
 
 ### Developer / Agency
 
-This user repeatedly builds imports, scripts, and dashboards for clients.
+This user repeatedly builds imports, scripts, and reports for clients.
 
 Needs:
 
@@ -111,9 +107,9 @@ The processing run for an upload.
 
 Reusable mapping between source file columns and DataBreeze fields.
 
-### Dashboard
+### Dashboard Data
 
-The business view of imported and calculated data.
+Imported and calculated metrics exposed by the backend.
 
 ## MVP Scope
 
@@ -154,9 +150,7 @@ Do not add all sources at once. Each source should have a clear import flow, map
 
 ### First-Time Setup
 
-The user signs up, receives a personal workspace, and can add the first store.
-
-The empty dashboard should point to one action: upload the first file.
+The backend should support sign-up, personal workspace creation, and first store creation.
 
 ### Upload and Mapping
 
@@ -168,16 +162,14 @@ Requirements:
 - User uploads CSV/XLSX.
 - Backend parses headers and sample rows.
 - System suggests mappings.
-- Required fields are clearly shown.
+- Required fields are returned in API responses.
 - User confirms or edits mappings.
 - Mapping can later become reusable as a template.
 - Import cannot run without confirmed mappings.
 
 ### Validation and Error Handling
 
-Validation should be useful, not scary.
-
-The product should show:
+Validation responses should include:
 
 - Total rows.
 - Successful rows.
@@ -190,9 +182,9 @@ The product should show:
 
 Users should be able to download error reports when rows fail or warn.
 
-### Dashboard
+### Dashboard Data
 
-The dashboard should answer:
+Dashboard APIs should provide enough data to answer:
 
 - How much revenue did I make?
 - How much did I lose to discounts, refunds, fees, shipping, ads, expenses, and COGS?
@@ -217,35 +209,6 @@ Early rule-based insights:
 
 Future AI insights should explain business context but must not hide calculation logic.
 
-## UX Principles
-
-### Vietnamese-First
-
-Use familiar business language. Prefer terms like shop, doanh thu, chi phi, loi nhuan, gia von, don hang, SKU, phi san, hoan tien.
-
-### Guided, Not Technical
-
-The user should feel they are following a clear path:
-
-```text
-Upload -> Map columns -> Check data -> Update dashboard
-```
-
-Avoid exposing internal ETL terms in primary UI unless needed for debugging.
-
-### Errors Should Be Actionable
-
-Bad data should produce practical next steps:
-
-- Add missing SKU cost.
-- Fix invalid date.
-- Confirm required mapping.
-- Download error file.
-
-### Solo-First, Team-Ready
-
-The MVP should feel comfortable for a solo seller. The information architecture should still support teams later through workspace switching, member roles, and organization billing.
-
 ## Pricing and Limits
 
 The backend currently seeds these plan concepts:
@@ -287,4 +250,4 @@ For every feature, ask:
 - Does this make profit clearer?
 - Does this handle Vietnamese file mess better?
 - Does this preserve trust and auditability?
-- Can a non-technical seller understand what happened?
+- Are API responses clear enough to explain what happened?