Tài liệu bàn giao dự án ERP Frontend (Vue 3)

1) Tổng quan

Mục tiêu: Ứng dụng ERP Frontend kết nối Odoo (backend) để phục vụ các nghiệp vụ: task/project, expenses, overtime, HR, dashboard, marketing report...

Điểm nổi bật UI: Dự án dùng UI mới theo hướng hiện đại, dễ dùng hơn:

PrimeVue v4 + PrimeVue Theme (Aura) làm nền tảng component UI.

TailwindCSS (kèm tailwindcss-primeui) để tuỳ biến layout/spacing nhanh, đồng nhất.

Các icon dùng primeicons và lucide-vue-next.

2) Tech stack

Framework: Vue 3 + TypeScript

Build tool: Vite

State: Pinia

Data fetching/cache: @tanstack/vue-query

UI: PrimeVue + TailwindCSS + Headless UI

HTTP: Axios

i18n: vue-i18n

Test: Vitest

Các file/cấu hình chính:

package.json: scripts + dependencies

vite.config.ts: base path + proxy dev

src/main.ts: khởi tạo app, PrimeVue theme, Pinia, Router, Vue Query

3) Kết nối Odoo (core integration)

3.1 Cơ chế gọi API

Hầu hết các request tới Odoo dùng JSON-RPC 2.0.

Axios client: src/http/axios/index.ts

baseURL = env.BASE_API_URL

withCredentials: true để mang theo cookie session (quan trọng cho Odoo)

interceptor tự chèn jsonrpc: "2.0" vào body khi POST

Hàm gọi Odoo chuẩn: src/services/api.ts

queryOdoo<T>(url, body, userContext?):

Tự thêm id random và jsonrpc/method

Merge context, ép lang: "vi_VN"

Nếu response.data.error thì throw Error(error.data.message)

3.2 Luồng đăng nhập / session

Login: src/modules/auth/authenticationService.ts

Gọi POST /web/session/login với params { db, login, password }

Nếu thành công, lưu token/session vào local storage (xem src/services/localStorage.ts)

Logout:

POST /web/session/destroy

chuyển hướng window.location.href = "/web/session/logout"

Refresh token (tuỳ môi trường):

Gọi POST /api/v1/oauth2/refresh-token nếu có refresh token + session id

Dùng CLIENT_ID/CLIENT_SECRET từ env

3.3 Upload/Download & avatar

Trong src/services/api.ts:

Avatar: getOdooAvatar({ id, size, model }) → /web/image?...

Upload file: uploadOdooFile(file, threadId, threadModel)

gọi thẳng env.BASE_API_URL + "/api/attachment/upload"

withCredentials: true (cần cookie session)

Download export xlsx: downloadFile(...)

gọi env.BASE_API_URL + "web/export/xlsx" và download blob

3.4 Proxy dev (tránh CORS)

Trong vite.config.ts:

base = APP_BASE_PATH

proxy dev route:

BASE_PATH + "/api" → target: BASE_API_URL

rewrite remove BASE_PATH

Điều này giúp local dev gọi /<APP_BASE_PATH>/api/... nhưng thực tế đi tới Odoo.

4) Cấu hình môi trường (.env)

4.1 File mẫu

Dùng .env.example làm chuẩn:

APP_BASE_PATH: base path khi deploy (ví dụ "/vue")

BASE_API_URL: base URL Odoo (ví dụ http://localhost:8069/)

DB_NAME: tên database Odoo

Ngoài ra có thể có các biến dùng cho oauth/encrypt (tuỳ môi trường):

CLIENT_ID, CLIENT_SECRET

AES_IV, AES_SECRET_KEY

PUBLIC_KEY

Lưu ý:

Không commit secret lên repo.

Nếu rotate secret (client secret/aes keys) cần phối hợp backend/Odoo tương ứng.

4.2 Cách tạo .env

Sau đó chỉnh các biến cho đúng môi trường.

5) Chạy dự án local

5.1 Chạy bằng Node (nhanh nhất)

App chạy theo Vite (mặc định port 5173). Nếu APP_BASE_PATH="/vue" thì URL thường là:

http://localhost:5173/vue/

5.2 Chạy bằng Docker (khuyến nghị theo repo)

Repo hiện có hướng dẫn trong README.md + docker/docker-compose-dev.yml:

Yêu cầu:

Docker network external phải tồn tại (ví dụ winads_erp_external_network).

Odoo phải reachable theo BASE_API_URL trong .env.

6) Build/Deploy

6.1 Scripts

Các script chính trong package.json:

npm run build: typecheck + build

npm run lint, npm run format

npm run test:unit

Repo có thêm các script shell tiện dụng:

run-dev.sh, run-prod.sh, run-139.sh, run-format.sh

6.2 GitLab CI/CD

Xem .gitlab-ci.yml:

Develop (deploy):

Job erp-fe-139-develop chạy khi branch develop

SSH vào server, git pull origin develop, chạy sh run-139.sh

Production (build & deploy):

Build images (multi-arch) và push lên AWS ECR

Deploy trên 2 môi trường: ERP_FE_D1 và ERP_FE_D2

Thông tin quan trọng khi vận hành:

Pipeline dựa vào các CI variables (SSH key, user, host, ECR credentials, …).

Khi production deploy, server sẽ docker pull ...:latest và docker compose up -d.

7) Cấu trúc source (gợi ý đọc nhanh)

src/modules/*: các module nghiệp vụ theo domain (expenses, overtime, projects, dashboard, human-resources, marketing, ...)

src/services/api.ts: wrapper gọi Odoo (JSON-RPC), upload/download

src/http/axios/index.ts: axios instance + interceptor JSON-RPC

src/modules/auth/*: login/refresh/logout + type

src/router/*: public/private routes + guard requiresAuth

src/constants/*, src/types/odoo/*: hằng số & typings liên quan Odoo

8) Troubleshooting nhanh

Sai base path (404 route / asset):

kiểm tra APP_BASE_PATH (ví dụ /vue) và cấu hình reverse proxy/nginx tương ứng.

router dùng createWebHistory(env.APP_BASE_PATH).

Không giữ session / gọi API bị 401/redirect:

đảm bảo BASE_API_URL đúng domain/protocol

cookie của Odoo cần withCredentials: true (đã bật trong axios client)

nếu khác domain, cần cấu hình CORS/cookie trên backend/nginx phù hợp.

Upload file lỗi:

endpoint dùng env.BASE_API_URL + "/api/attachment/upload" (không qua proxy dev).

kiểm tra quyền Odoo + session cookie.

9) Checklist bàn giao (handover)

Có file .env theo từng môi trường (dev/staging/prod) và được lưu an toàn (Vault/Secret Manager).

Xác nhận BASE_API_URL trỏ đúng Odoo + truy cập được từ nơi deploy.

Xác nhận DB_NAME đúng database.

Xác nhận cơ chế auth (login/refresh) phù hợp với backend đang chạy.

Xác nhận APP_BASE_PATH khớp với cấu hình nginx/reverse proxy.

Xác nhận CI variables trên GitLab đủ cho pipeline (SSH keys, AWS ECR, hosts).

ERP Frontend

Tài liệu bàn giao dự án ERP Frontend (Vue 3)#

1) Tổng quan#

2) Tech stack#

3) Kết nối Odoo (core integration)#

3.1 Cơ chế gọi API#

3.2 Luồng đăng nhập / session#

3.3 Upload/Download & avatar#

3.4 Proxy dev (tránh CORS)#

4) Cấu hình môi trường (.env)#

4.1 File mẫu#

4.2 Cách tạo .env#

5) Chạy dự án local#

5.1 Chạy bằng Node (nhanh nhất)#

5.2 Chạy bằng Docker (khuyến nghị theo repo)#

6) Build/Deploy#

6.1 Scripts#

6.2 GitLab CI/CD#

7) Cấu trúc source (gợi ý đọc nhanh)#

8) Troubleshooting nhanh#

9) Checklist bàn giao (handover)#