diff --git a/CORE_FEATURE_GUIDE.md b/CORE_FEATURE_GUIDE.md index a478c34..cd1d507 100644 --- 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,7 +19,7 @@ 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 @@ -27,7 +27,7 @@ React/Swagger request → Repository → Entity/DB → DTO Response - → React + → client ``` Entity chỉ dùng ở tầng service/repository để map DB. Controller chỉ nhận/trả DTO. @@ -92,7 +92,7 @@ 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. @@ -100,7 +100,7 @@ service/ai - 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 index b31dfc6..2949813 100644 --- a/docs/AGENT_BACKEND_GUIDE.md +++ b/docs/AGENT_BACKEND_GUIDE.md @@ -59,7 +59,7 @@ 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 @@ -67,7 +67,7 @@ Frontend / Swagger request -> 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 index 340e093..018f1fc 100644 --- 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 index bd2c449..5938fd9 100644 --- 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?