Gọi API của Phillip: trường nào bắt buộc, trường nào im lặng làm sai giá.

Bản đồNăm cổng, hai cổng ghi được

https://casa-escondida-03-staging-web-37790335.dev.odoo.com/estimate-api

Bốn cổng đầu đã gọi thật nhiều lần. Cổng thứ năm chưa gọi lần nào, vì nó tạo hồ sơ thật trong staging của Phillip. Trước khi thử, báo Phillip một câu.

Câu hỏi chínhTrường nào bắt buộc

Câu trả lời có hai tầng, và tầng thứ hai mới là tầng nguy hiểm.

Tầng 1: thiếu thì lỗi 422, thấy ngay

Hết. Mọi trường khác trong Trip đều tùy chọn theo spec.

Tầng 2: thiếu thì giá sai, không ai báo

// A — thiếu diveFrom/diveTo          // B — có diveFrom/diveTo
{"checkIn":"2026-12-01",              {"checkIn":"2026-12-01",
 "checkOut":"2026-12-03",              "checkOut":"2026-12-03",
                                       "diveFrom":"2026-12-02",
                                       "diveTo":"2026-12-02",
 "guests":[{"diver":true,              "guests":[{"diver":true,
   "days":{"2026-12-02":                 "days":{"2026-12-02":
     {"dive":true}}}]}                      {"dive":true}}}]}

→ HTTP 200                            → HTTP 200
→ diveDates: ["2026-10-06",           → diveDates: ["2026-12-02"]
              "2026-10-07",           → lines: room 11,000
              "2026-10-08"]                    dive 10,000
→ lines: room 11,000                  → catRev.dive: 10,000
→ catRev.dive: 0                      → warnings: ["no boat picked yet"]
→ warnings: []

Luật cho BFF: luôn gửi đủ Trip, mọi trường, kể cả trường rỗng. Không bao giờ gửi PATCH một phần lên compute.

HìnhHình dạng của một Trip

Tra cứuTừng trường một

Trip

Guest

Room · DayPlanEntry · CustomItem · VanMeta

Dễ nhầmHai chữ "vai" khác nhau

Ba dòng trên lấy từ spec. Chỉ dòng guest đã kiểm chứng thật, vì chưa có khóa truy cập cho hai vai kia. Đó là mục số một trong danh sách gửi Phillip.

POST /v1/estimate/computeVí dụ chạy được, sao chép là dùng

Hai khách, hai đêm phòng Standard, một người lặn một ngày, ăn cả ngày. Đây là request nhỏ nhất mà vẫn đúng giá.

curl -X POST https://casa-escondida-03-staging-web-37790335.dev.odoo.com/estimate-api/v1/estimate/compute \
  -H "content-type: application/json" -d '{
  "trip": {
    "label": "Retail couple",
    "guestType": "retail",
    "transportType": "none",
    "checkIn": "2026-11-20", "checkOut": "2026-11-22",
    "diveFrom": "2026-11-21", "diveTo": "2026-11-21",
    "bookedDaysAhead": 30,
    "rooms": [ { "id": "r1", "type": "standard" } ],
    "guests": [
      { "id": "g1", "name": "Ana", "diver": true,  "meals": true, "transport": false,
        "foc": false, "roomId": "r1", "courses": [],
        "days": { "2026-11-21": { "dive": true, "third": false, "night": false } } },
      { "id": "g2", "name": "Ben", "diver": false, "meals": true, "transport": false,
        "foc": false, "roomId": "r1", "courses": [], "days": {} }
    ],
    "items": []
  }
}'

Trả về, đã rút gọn:

{
  "ok": true,
  "role": "guest",
  "retail_model": null,          // chỉ staff và agent mới có
  "assumptions": null,           // chỉ staff mới có
  "model": {
    "N": 2,                                        // số đêm
    "stayDates": ["2026-11-20", "2026-11-21"],
    "diveDates": ["2026-11-21"],
    "quotes": [
      { "g": { "id": "g1", "name": "Ana", ... },   // cả đối tượng khách, lặp lại
        "isFoc": false,
        "lines": [
          { "cat": "room",  "label": "Standard A — 2 nights",
            "sub": "nightly rate ÷ that night's roommates, summed over your stay",
            "gross": 7600, "discs": [], "net": 7600 },
          { "cat": "meals", "label": "Full board — 2 days",  "gross": 3000, ... },
          { "cat": "dive",  "label": "Boat dives — Sat, Nov 21",
            "sub": "2-dive boat trip · 1 diver out", "gross": 10000, ... }
        ],
        "gross": 20600, "total": 20600, "discountTotal": 0 },
      { "g": { "id": "g2", "name": "Ben", ... }, "total": 10600, ... }
    ],
    "catRev":  { "room": 15200, "meals": 6000, "dive": 10000, "course": 0,
                 "transport": 0, "gear": 0, "extras": 0 },
    "kpis":    { "revenue": 31200, "cost": null, "profit": null, "margin": null,
                 "rpgn": 7800, "discounts": 0, "guests": 2, "nights": 2 },
    "foc":     { "ok": true, "per": 5, "bracket": 0, "entitled": 0, "marked": 0,
                 "stay": {...}, "dive": {...} },
    "warnings": [ { "level": "warn", "text": "Sat, Nov 21: no boat picked yet for Ana." } ],
    "dayPlans": [...], "vanRuns": [...], "presence": {...}, "covers": {...},
    "roomNames": {...}, "roomAvailability": {...}
  }
}

Đọc phần trả về

LỗiBốn dạng, tất cả đều 422

// thiếu trường bắt buộc
{"detail":[{"type":"missing","loc":["body","trip"],"msg":"Field required","input":{}}]}

// sai enum
{"detail":[{"type":"enum","loc":["body","trip","guestType"],
            "msg":"Input should be 'retail', 'agent' or 'instructor'","input":"vip",
            "ctx":{"expected":"'retail', 'agent' or 'instructor'"}}]}

// sai kiểu  ← đây là bẫy vanA
{"detail":[{"type":"string_type","loc":["body","trip","guests",0,"vanA"],
            "msg":"Input should be a valid string","input":0}]}

// vượt giới hạn
{"detail":[{"type":"too_long","loc":["body","trip","guests"],
            "msg":"List should have at most 40 items after validation, not 80",
            "input":[ ...toàn bộ payload được trả lại... ]}]}

Bốn dạng đều theo chuẩn Pydantic: detail là mảng, mỗi phần tử có loc chỉ thẳng tới trường sai. BFF nên dịch loc thành đường dẫn trường trong form để tô đỏ đúng ô. Lưu ý dạng cuối trả lại nguyên payload trong input, nên đừng ghi thẳng lỗi vào log.

Timeout và thử lại

POST /v1/booking/submitCổng duy nhất ghi vào Odoo

{
  "contact": { "name": "Ana Cruz", "email": "ana@example.com", "phone": "+63..." },
  "trip":    { ...đúng Trip đã gửi cho compute... }
}

→ { "success": true, "folio_id": 162, "order_ids": [418, 419] }

Hai cổng đọcrates và rooms

GET /v1/estimate/rates

{
  "roomRates": { "standard": {"1pax":5500,"2pax":7600},
                 "deluxe":   {"1-2pax":11200,"3-4pax":16400.010000000002},
                 "suite":    {"1-2pax":14200,"3-4pax":18400} },
  "diveTiers": { "1":10000, "2":5500, "3":4500, "4":3600 },
  "mealRate":  1500,
  "courseRates": { "dsd":5500, "ow":22000, "aow":18000 },   // thiếu refresher, rescue
  "transport": { "roundtrip":13000, "oneway":6500 },
  "terms":     { "depositPct":50 },
  "roomNames": { "standard":[16 phòng], "deluxe":[4], "suite":[4] }
}

• diveTiers đọc theo số thợ lặn xuống nước trong ngày đó, không phải tổng số khách.
• courseRates thiếu hai loại: refresher và rescue. Nhưng engine vẫn tính đúng 5.500 và 20.000 khi gửi lên. Không dựng bảng chọn khóa học từ đây.
• Deluxe 3-4 người trả về 16400,010000000002. Làm tròn ở phía BFF trước khi hiển thị.

GET /v1/estimate/rooms?check_in=2026-11-20&check_out=2026-11-22

{ "ok": true,
  "rooms":     { "standard":["Standard A"..."Standard P"], "deluxe":[...], "suite":[...] },
  "available": { "standard":[...], "deluxe":[...], "suite":[...] },   // null nếu không truyền ngày
  "check_in": "2026-11-20", "check_out": "2026-11-22" }

Casa có đúng 24 phòng: 16 standard, 4 deluxe, 4 suite. Con số này khớp tuyệt đối với công cụ của Sky. Cùng dữ liệu này cũng nằm trong response của compute ở roomNames và roomAvailability, nên trong luồng tính giá thì không cần gọi riêng.

Ánh xạForm của Sky sang Trip của Odoo

Gửi PhillipMười mục, ba mục đầu là chặn đường

Trong repo tn-casa-quotation-estimator đã có ba bài test khẳng định các mục 1, 2 và 4 vẫn còn thiếu. Chúng sẽ chuyển sang đỏ đúng ngày Phillip làm xong, và đó là cách mình biết.

Hết chặn đườngDựng mock trả số thật

Spec không có ví dụ nên Prism sinh ra chuỗi vô nghĩa. Cách sửa không cần chờ Phillip: lưu chính những response thật ở trên thành tệp ví dụ.

contracts/odoo/
  estimate-api.v1.json          # spec đã ghim, md5 14c078e9
  examples/
    compute.retail-couple.json  # 2 khách, 2 đêm, 1 ngày lặn   →  4 KB
    compute.agent-group.json    # 7 khách, 4 đêm, FOC, khóa học → 39 KB
    compute.course.json         # refresher + open water
    rates.json                  # bảng giá thật
    rooms.json                  # 24 phòng thật
    errors.422-*.json           # bốn dạng lỗi

npm run mock -w contracts       # Prism, cổng 4010, trả ví dụ thật
npm run spec:check -w contracts  # so spec staging với bản đã ghim, lệch là thoát 1