Tích hợp Hub (bsd_hub)

Realty Project ship sẵn API layer cho phép tích hợp với hệ thống bên ngoài qua hub bsd_hub — Next.js BFF (Backend-for-Frontend) chạy độc lập, reuse Odoo session cho auth, expose RESTful API + Webhook.

11.1 Tổng quan kiến trúc

Hệ thống bên ngoài (Mobile app / Power BI / Custom dashboard)
       ↓ HTTPS REST
   bsd_hub (Next.js BFF)
       ↓ Odoo XML-RPC / JSON-RPC
   Realty Project (Odoo 19)
       ↓ ORM
   PostgreSQL 16

Vai trò bsd_hub

Layer	Trách nhiệm
bsd_hub	Session reuse + caching + rate-limit + multi-tenant routing + type-safe API
Odoo	Business logic + DB + ACL gốc

bsd_hub KHÔNG store data — chỉ proxy + cache + format. Single source of truth vẫn ở Odoo DB.

11.2 Auth flow

bsd_hub reuse Odoo session cookie — user login Odoo 1 lần, mọi API call từ hệ thống bên ngoài đi qua bsd_hub đều inherit session đó.

Flow chuẩn

1. User login Odoo: POST /web/session/authenticate
   → response: session_id cookie

2. App gọi bsd_hub: GET /api/projects
   Headers: Cookie: session_id=xxx

3. bsd_hub verify session via Odoo /web/session/get_session_info
   → user_id, company_id, group_ids

4. bsd_hub call Odoo XML-RPC với context user_id
   → ACL của user áp dụng đầy đủ
   → return filtered data theo user role

5. bsd_hub format response (camelCase JSON cho FE convenience)

Multi-tenant

Hub support multiple Odoo instances (multi-company hoặc multi-customer):

{
  "tenants": {
    "customer-a.bsdinsight.com": {
      "odoo_url": "https://customer-a-odoo.internal:8069",
      "default_db": "prod"
    },
    "customer-b.bsdinsight.com": {
      "odoo_url": "https://customer-b-odoo.internal:8069",
      "default_db": "prod"
    }
  }
}

Hub route theo subdomain → đúng Odoo instance.

11.3 API endpoints (Realty Project)

Projects

Endpoint	Method	Return
/api/projects	GET	List projects user có quyền access (filter theo ACL)
/api/projects/{id}	GET	Detail 1 project + nested data (subzones, structures)
/api/projects/{id}/progress	GET	Weighted progress + KPI tiles
/api/projects/{id}/cashflow	GET	Forecast cash flow 12 tháng

Contracts

Endpoint	Method	Return
/api/contracts	GET	List HĐ nhà thầu với filters (project, state, NT)
/api/contracts/{id}	GET	Detail HĐ + BOQ + milestones + amendments
/api/contracts/{id}/bbn	GET	List BBN nghiệm thu
/api/contracts/{id}/invoices	GET	List hóa đơn từ milestones

Loans (re_loan)

Endpoint	Method	Return
/api/loans/notes	GET	List KW outstanding
/api/loans/notes/{id}/interest-schedule	GET	Lịch lãi chi tiết
/api/loans/bank-advice/preview	POST	Upload Excel → preview before allocate
/api/loans/bank-advice/allocate	POST	Confirm allocate giấy báo có

Guarantees (re_guarantee)

Endpoint	Method	Return
/api/guarantees/outstanding	GET	BL NH outstanding theo NH × loại
/api/guarantees/{id}/lifecycle	GET	Full lifecycle 1 BL

11.4 Webhook

Realty Project trigger webhook khi state thay đổi quan trọng — hub forward sang hệ thống đăng ký.

Events list

Event	Trigger
contract.signed	rp.contract.state → executing
bbn.approved	rp.progress.acceptance.state → approved
invoice.paid	account.move.payment_state → paid
loan.note.activated	re.loan.note.state → active
bank.advice.imported	re.loan.bank.advice tạo mới
guarantee.issued	re.bank.guarantee.state → issued
guarantee.forfeited	re.bank.guarantee.state → forfeited (risk alert)

Subscription

Trong bsd_hub:

POST /api/webhooks/subscribe
{
  "url": "https://my-app.example.com/webhook/realty",
  "events": ["contract.signed", "bbn.approved"],
  "secret": "xxx"
}

Hub gửi POST với HMAC-SHA256 signature trong header X-BSD-Signature.

11.5 Use cases mẫu

Use case 1: Mobile app cho PTDA

PTDA dùng app mobile khi field check:

• Xem tiến độ hạng mục đang thi công (API /projects/{id}/progress)
• Chụp ảnh thực tế upload làm evidence cho BBN
• Approve BBN ngay tại site (state proposed → approved)

Use case 2: Dashboard executive Power BI

CFO/CEO không login Odoo trực tiếp:

• Power BI connect bsd_hub via REST API
• Query cross-project KPI hourly (cron sync)
• Render dashboard quen thuộc cho BLĐ

Use case 3: Webhook → Slack/Discord

DevOps/PM team nhận alert real-time:

• Webhook guarantee.forfeited → Slack channel #risk
• Webhook loan.note.activated (giá trị lớn) → Discord channel #treasury

11.6 Deploy bsd_hub

Stack

• Next.js 14 (App Router) + TypeScript
• Postgres for cache + rate-limit (shared với Odoo DB hoặc riêng)
• Redis optional cho session cache (giảm tải Odoo)
• Cloudflare Tunnel hoặc nginx reverse proxy

Compose

services:
  bsd-hub:
    image: bsdinsight/bsd-hub:latest
    environment:
      - ODOO_URL=http://odoo:8069
      - REDIS_URL=redis://redis:6379
      - JWT_SECRET=xxx
    ports:
      - 3000:3000
  redis:
    image: redis:7-alpine

Detail config tham khảo repo bsd-hub (private — liên hệ partner@bsdinsight.com).

---

Tiếp: Troubleshooting →