Đây là điểm rất quan trọng: LLM không được quyền tự khẳng định giá, trạng thái thanh toán, lịch trống hoặc kết quả booking. Những dữ liệu đó phải đến từ backend/domain authoritative.

Xét về tính khả thi, dự án có tính khả thi kỹ thuật cao cho MVP/sandbox vì phần lớn nền tảng đã tồn tại và đã có bằng chứng test/runtime. Tuy nhiên, để trở thành sản phẩm production thực sự, độ khó lớn nhất không còn là “viết thêm API” mà là bốn vấn đề:

1. Độ chính xác và khả năng giữ ngữ cảnh của AI trong hội thoại dài, mơ hồ, nhiều dịch vụ và có chỉnh sửa giữa chừng.
2. Độ hoàn thiện của trải nghiệm giao dịch: bản đồ, ETA, loading, pagination, context rail, form chỉnh sửa, trạng thái đang diễn ra.
3. Tích hợp dữ liệu/provider thực: bản đồ/routing, nhà hàng, vận tải, lịch khám, thanh toán.
4. Độ tin cậy production: observability, security, rate limit, recovery, SLA, privacy, compliance và vận hành.

Hướng phát triển hợp lý nhất là không tiếp tục thêm nhiều tầng AI phức tạp, mà tập trung vào: eval → phân nhóm failure → sửa understanding/context/planning → đồng bộ Gateway/domain contract → cải thiện UI → kiểm thử end-to-end. X-One sẽ mạnh hơn nhờ sự chính xác và tính nhất quán của toàn pipeline, không phải nhờ biến hệ thống thành một “multi-agent swarm”.

2. Bài toán cần giải quyết

2.1. Bối cảnh

Trong một hành trình đời sống thông thường, người dùng thường phải tương tác với nhiều dịch vụ độc lập. Ví dụ:

“Tối mai tìm giúp tôi một nhà hàng Nhật gần Hồ Tây cho 4 người, khoảng dưới 2 triệu. Nếu còn bàn thì đặt lúc 19:00. Sau đó gọi xe từ nhà, ghé Cầu Giấy đón Minh rồi đi tới nhà hàng. Nếu giá xe trên 300.000 đồng thì hỏi lại tôi.”

Để hoàn thành yêu cầu này theo cách truyền thống, người dùng có thể phải:

1. mở ứng dụng tìm nhà hàng;
2. lọc theo vị trí, món ăn, rating và ngân sách;
3. kiểm tra giờ mở cửa;
4. gọi/đặt bàn;
5. mở ứng dụng bản đồ;
6. tính thời gian di chuyển;
7. mở ứng dụng gọi xe;
8. nhập nhiều điểm dừng;
9. kiểm tra giá;
10. theo dõi trạng thái từng dịch vụ.

Vấn đề không phải là thiếu ứng dụng. Vấn đề là mỗi ứng dụng chỉ hiểu một phần của mục tiêu tổng thể.

X-One giải quyết sự phân mảnh này bằng một lớp orchestration hội thoại nằm phía trên các dịch vụ.

2.2. Pain point của người dùng

2.2.1. Phân mảnh dịch vụ

Người dùng phải ghi nhớ và truyền lại cùng một context giữa nhiều ứng dụng: địa chỉ nhà, điểm đến, số người, thời gian, ngân sách, yêu cầu đặc biệt.

2.2.2. Lặp lại thông tin

Một assistant kém sẽ hỏi lại dữ liệu đã có. Feedback thực tế của dự án cho thấy các trường hợp:

• người dùng đã chia sẻ vị trí nhưng chatbot vẫn hỏi lại điểm đón;
• người dùng đã nói số người/khu vực nhưng bot tiếp tục hỏi lại;
• sau khi người dùng sửa thời gian hoặc địa điểm, state cũ và state mới không được reconcile đúng;
• user chọn một resource trên UI nhưng assistant không hiểu “cái này”, “quán đó”, “đến đó”.

Đây là lỗi context/state, không chỉ là lỗi prompt.

2.2.3. Yêu cầu tự nhiên thường không sạch

Người dùng không nói theo schema. Họ có thể viết:

• “tối nay ăn gì chill chill cho 2 người dưới 500k”;
• “đặt xe qua đón thằng bạn ở Cầu Giấy rồi qua Hồ Tây”;
• “đổi lại đi”;
• “thôi cái thứ hai”;
• “nhà tôi”;
• “đặt lịch khám trên sao Hỏa”;
• “bạn là ai?”;
• hoặc chuyển chủ đề giữa chừng.

Hệ thống phải xử lý được:

• intent;
• entity;
• constraint;
• reference;
• correction;
• ambiguity;
• out-of-scope;
• interaction signal;
• dependency giữa nhiều task.

2.2.4. Người dùng cần hành động, không chỉ câu trả lời

Một chatbot thông thường có thể trả lời một danh sách. X-One phải hỗ trợ một chuỗi:

Hiểu nhu cầu
    ↓
Tìm resource phù hợp
    ↓
Đề xuất lựa chọn
    ↓
Cho phép chỉnh sửa
    ↓
Xác nhận điều khoản
    ↓
Thực thi backend
    ↓
Theo dõi trạng thái
    ↓
Hủy / sửa / khôi phục nếu cần

Do đó, đây là bài toán transactional AI agent, không phải chatbot FAQ.

2.3. Bài toán tin cậy

AI có thể hiểu sai. Trong các tác vụ chỉ đọc thông tin, một sai sót đôi khi chỉ gây khó chịu. Nhưng trong các tác vụ như:

• đặt xe;
• đặt bàn;
• đặt lịch khám;
• đặt món;
• thanh toán;
• hủy dịch vụ;

một sai sót có thể tạo ra giao dịch thật.

Vì vậy X-One phải giải bài toán kép:

Làm cho AI đủ linh hoạt để hiểu ngôn ngữ tự nhiên nhưng không trao cho AI quyền tự quyết các giao dịch quan trọng.

Đây là lý do kiến trúc hiện tại đặt confirmation, authority, idempotency và domain validation bên ngoài LLM.

2.4. Bài toán multi-service

Điểm khác biệt tiềm năng của X-One là khả năng hiểu một yêu cầu gồm nhiều dịch vụ.

Có ba loại workflow chính.

A. Nhiều dịch vụ độc lập

Ví dụ:

“Đặt đồ ăn cho tôi và tìm lịch khám thần kinh sáng mai.”

Hai task có thể chạy tương đối độc lập.

B. Workflow có dependency

Ví dụ:

“Đặt bàn nhà hàng rồi gọi xe tới đó.”

Ride phụ thuộc vào nhà hàng được chọn.

C. Workflow có điều kiện

Ví dụ:

“Nếu chuyến xe dưới 200.000 thì đặt, nếu cao hơn thì hỏi lại tôi.”

Hệ thống cần hiểu điều kiện nhưng không được biến ngôn ngữ của user thành mã tùy ý để thực thi.

3. Mục tiêu sản phẩm

3.1. Mục tiêu ngắn hạn

Xây dựng một Web application có thể demo ổn định các workflow chính:

• hội thoại tiếng Việt tự nhiên;
• Food;
• Ride;
• Restaurant;
• Healthcare;
• multi-turn correction;
• confirmation;
• payment sandbox;
• history;
• tracking;
• cancellation;
• multi-service cơ bản.

3.2. Mục tiêu trung hạn

Biến X-One từ demo thành một service orchestration platform có thể tích hợp provider thật.

3.3. Mục tiêu dài hạn

X-One có thể trở thành một “personal service layer” nơi người dùng không cần biết mỗi nhu cầu được thực hiện bởi ứng dụng/provider nào. Người dùng mô tả mục tiêu; hệ thống lập kế hoạch, đề xuất phương án và thực hiện các bước sau khi được xác nhận.

4. Phạm vi sản phẩm hiện tại

4.1. Food

Các năng lực codebase hướng tới/đã có gồm:

• tìm món/nhà hàng;
• xem menu;
• chọn item;
• tạo và cập nhật giỏ hàng;
• quantity/options/notes;
• voucher;
• địa chỉ giao hàng;
• delivery quote;
• preview order;
• confirmation;
• place order;
• theo dõi đơn;
• hủy;
• reorder/history.

Các vấn đề UX từng được ghi nhận gồm danh sách món bị cắt hoặc quá dài, pagination chưa rõ, map detail không ổn định, phí giao hàng hiển thị không nhất quán và việc chọn địa chỉ/current location chưa thuận tiện.

4.2. Ride

Năng lực chính:

• pickup/dropoff;
• loại xe;
• quote;
• ETA;
• booking;
• tracking lifecycle;
• cancel;
• persisted state;
• confirmation và idempotency.

Các vấn đề thực tế tập trung ở:

• hủy chuyến;
• ETA;
• map loading/rendering;
• chuyển động marker;
• autocomplete địa chỉ;
• map bị cắt hoặc layout overlap;
• trạng thái tài xế chưa tự nhiên;
• nhu cầu multi-stop phức tạp.

4.3. Restaurant

Năng lực chính:

• discovery;
• filter theo khu vực/ẩm thực/budget;
• xem chi tiết;
• availability snapshot;
• hold;
• booking;
• modify/cancel;
• history/book again.

UX cần ưu tiên:

• danh sách ngắn gọn, có pagination/progressive disclosure;
• ảnh/fallback hợp lý;
• opening hours dễ đọc;
• từ chối ngay các thời điểm không hợp lệ;
• khi đổi quán/thời gian phải chuyển workflow đúng thay vì lặp lại search list.

4.4. Healthcare

Năng lực chính:

• cơ sở y tế;
• chuyên khoa;
• bác sĩ;
• lịch trống;
• patient context;
• hold appointment;
• confirmation;
• cancel;
• history.

Healthcare có boundary đặc biệt: X-One hỗ trợ discovery, thông tin dịch vụ và booking, không phải hệ thống chẩn đoán hay kê đơn.

Các lỗi behavior từng xuất hiện gồm chọn sai chuyên khoa khi câu hỏi mơ hồ và xử lý các yêu cầu vô lý/out-of-scope chưa tự nhiên.

5. Giải pháp kỹ thuật tổng thể

5.1. Kiến trúc lớp

flowchart TB
    U[Người dùng] --> W[Next.js Web]
    W --> G[NestJS API Gateway]

    G --> A[Agent Service\nFastAPI + LangGraph + Gemini]
    G --> F[Food Service]
    G --> R[Ride Service]
    G --> RS[Restaurant Service]
    G --> H[Healthcare Service]

    G --> CDB[(Core DB)]
    A --> ADB[(Agent metadata DB / workflow state)]
    F --> FDB[(Food DB)]
    R --> RDB[(Ride DB)]
    RS --> RSDB[(Restaurant DB)]
    H --> HDB[(Healthcare DB)]

Nguyên tắc kiến trúc:

• client chỉ gọi Gateway;
• Agent không gọi database/domain trực tiếp;
• Gateway orchestration nhưng không sở hữu domain invariant;
• domain service là source of truth;
• contract nội bộ sử dụng REST/JSON/OpenAPI;
• side effect phải có idempotency;
• transaction quan trọng phải có confirmation.

5.2. Frontend — Next.js

Web frontend đóng vai trò presentation layer, không phải business authority.

Các trách nhiệm chính:

• authentication UI;
• chat workspace;
• rich cards;
• service hub;
• history;
• profile/addresses/patients;
• maps;
• active-service ContextRail;
• confirmation UI;
• loading/error/empty/recovery state.

Một nguyên tắc quan trọng là UI không được tự suy ra trạng thái booking từ dữ liệu local. Ví dụ, nút “Đã đặt thành công” chỉ được hiển thị sau khi backend authoritative trả về trạng thái tương ứng.

Hướng UX phù hợp

Authenticated app nên tiến gần mô hình:

┌───────────┬──────────────────────────────┬───────────────────┐
│ Navigation│        Conversation          │ Current activity  │
│           │                              │ / Context rail    │
│           │                              │                   │
│           │                              │                   │
├───────────┴──────────────────────────────┴───────────────────┤
│                 Sticky composer                              │
└───────────────────────────────────────────────────────────────┘

Ở màn hình nhỏ, context rail chuyển thành drawer/collapsible section.

5.3. API Gateway — NestJS

Gateway là trung tâm của hệ thống giao dịch.

Gateway đảm nhiệm:

• authentication/authorization;
• request validation;
• correlation ID;
• rate limit;
• conversation persistence;
• typed client tới các domain;
• tool registry;
• confirmation;
• idempotency orchestration;
• payment sandbox;
• audit;
• multi-service workflow;
• response shaping;
• resource resolution;
• retry/recovery policy.

Vì sao Gateway cần đứng giữa Agent và Domain?

Nếu LLM gọi thẳng domain service:

• model có thể chọn sai tool;
• model có thể gửi authoritative ID không đáng tin;
• risk/confirmation dễ bị bypass;
• khó chống duplicate side effect;
• rất khó audit/recovery.

Gateway biến proposal từ AI thành một request đã được kiểm soát.

6. Kiến trúc AI Agent

6.1. Nguyên tắc cốt lõi

X-One không nên dùng LLM như “bộ não toàn quyền”. LLM phù hợp nhất với:

• hiểu câu nói;
• trích xuất semantic information;
• nhận diện ambiguity;
• paraphrase câu trả lời;
• xử lý ngôn ngữ tự nhiên.

LLM không nên sở hữu:

• giá authoritative;
• availability authoritative;
• booking ID;
• payment result;
• final transaction state;
• permission;
• confirmation authority.

6.2. Pipeline AI hiện đại của X-One

Kiến trúc hiện tại đã tiến tới mô hình typed understanding + deterministic planning.

flowchart TB
    M[User message] --> CN[Context Normalizer]
    UI[UI context / selected resource] --> CN
    CS[Conversation state] --> CN
    LOC[Current / saved location] --> CN

    CN --> UB[Understanding Layer\nGemini structured output / deterministic fallback]
    UB --> ST[Typed Semantic Delta / SemanticTurn]
    ST --> SV[Semantic validation]
    SV --> PA[Core-A deterministic planner]
    PA --> PV[Plan / capability validation]
    PV --> GW[Gateway Orchestrator]
    GW --> DS[Domain services]
    DS --> RN[Authoritative result normalization]
    RN --> RC[Grounded response composer]
    RC --> OUT[Text + Cards + Actions]

Ý nghĩa của thiết kế này

AI không cần quyết định toàn bộ workflow bằng text. Nó chỉ cần chuyển câu nói thành một representation có cấu trúc.

Ví dụ:

“tìm quán Nhật gần Hồ Tây cho 4 người tối mai, dưới 2 triệu”

có thể được hiểu thành:

intent: restaurant_search
party_size: 4
location:
  text: Hồ Tây
cuisine:
  value: Japanese
  strength: HARD
budget:
  comparator: MAX
  max: 2000000
  basis: TOTAL
time:
  date: tomorrow
  daypart: evening

Sau đó planner deterministic quyết định thiếu gì, tool nào hợp lệ và bước nào cần confirmation.

6.3. Context và semantic delta

Một hội thoại không nên được xử lý như chuỗi message độc lập.

Ví dụ:

User: Đặt bàn 2 người lúc 7 giờ tối mai.
AI: ...
User: Không, 4 người cơ.

Turn thứ hai không phải một booking mới. Nó là amendment cho task hiện tại.

Representation nên thể hiện delta:

party_size: SET 4
restaurant: KEEP
location: KEEP
time: KEEP

Nếu user nói:

“Bỏ địa điểm cũ đi.”

thì đó là CLEAR, không phải KEEP.

Cơ chế SET/CLEAR/KEEP giúp tránh lỗi phổ biến khi slot mới ghi đè hoặc làm mất context cũ.

6.4. Reference resolution

X-One cần hiểu các reference như:

• “cái thứ hai”;
• “quán đó”;
• “đến đó”;
• “nhà tôi”;
• “đơn vừa rồi”;
• “chuyến hiện tại”;
• resource user vừa chọn trên UI.

Reference chỉ hợp lệ nếu có authoritative candidate/resource context.

Ví dụ, trong conversation mới, nếu user nói:

“Chọn cái thứ hai.”

system phải hỏi lại, không được tự bịa candidate.

6.5. Constraint engine

Ngôn ngữ người dùng có hard và soft constraint.

“phải là quán Nhật”  → HARD
“ưu tiên quán Nhật” → SOFT

Nếu hệ thống không phân biệt hai loại này, ranking sẽ dễ vi phạm ý user.

Các constraint quan trọng:

• budget;
• location;
• time;
• party size;
• vehicle type;
• cuisine;
• doctor/department;
• route preference;
• maximum fare;
• special requests.

6.6. Money reasoning

Feedback người dùng cho thấy ngân sách là một thông tin rất quan trọng.

Một câu như:

“500k cho 2 người”

khác với:

“500k mỗi người”.

Do đó semantic money object cần có basis:

• TOTAL;
• PER_PERSON;
• PER_ITEM;
• SERVICE_FARE.

AI chỉ hiểu budget constraint. Giá thực tế vẫn phải đến từ domain.

6.7. Out-of-scope và graceful refusal

Chatbot không nên trả lời cứng nhắc hoặc lặp một câu hardcode khi user hỏi ngoài luồng.

Ví dụ:

“Đặt lịch khám trên sao Hỏa.”

Một phản hồi tốt có thể là:

“Hiện X-One chỉ hỗ trợ các cơ sở y tế có trong hệ thống. Nếu bạn cho mình khu vực thực tế muốn khám, mình có thể tìm chuyên khoa và lịch phù hợp.”

Mẫu chung:

1. Acknowledge ngắn gọn.
2. Nêu giới hạn thật.
3. Không bịa dữ liệu.
4. Đưa người dùng trở lại capability phù hợp.

Đây nên là behavior policy, không phải một chuỗi hardcode cho từng câu test.

7. Tool Registry và capability boundary

Tool Registry giúp Agent biết hệ thống thực sự có khả năng làm gì.

Mỗi capability cần xác định:

• tên;
• domain owner;
• input schema;
• output schema;
• risk level;
• có cần confirmation hay không;
• version;
• availability.

Ví dụ:

name: healthcare.confirm_appointment
owner: healthcare
risk: FINANCIAL_OR_FINAL
requires_confirmation: true

Điều này tốt hơn việc mô tả capability hoàn toàn bằng prompt vì:

• có thể validate bằng code;
• Agent/Gateway có thể kiểm tra parity;
• thay đổi contract có version;
• model không thể tự hạ risk level.

8. Transaction safety

8.1. Hai bước xác nhận

Các giao dịch quan trọng nên sử dụng mô hình:

Proposal
   ↓
User xem chi tiết
   ↓
Confirmation #1
   ↓
Domain hold / prepare
   ↓
Payment / final terms
   ↓
Confirmation #2
   ↓
Final write

Không phải domain nào cũng cần thanh toán thật, nhưng nguyên tắc là user phải thấy điều khoản authoritative cuối cùng trước side effect quan trọng.

8.2. Stale confirmation

Nếu user đổi:

• thời gian;
• số người;
• địa điểm;
• loại xe;
• giá;
• resource;

thì confirmation cũ phải bị invalidated.

Nếu không, người dùng có thể xác nhận một card cũ và tạo giao dịch với điều khoản không còn đúng.

8.3. Idempotency

Network có thể retry. User có thể double-click. Gateway có thể restart sau khi domain đã ghi thành công.

Do đó side effect cần idempotency.

Mục tiêu:

same actor
+ same operation
+ same key
+ same payload
→ same logical result

nhưng:

same key
+ changed payload
→ conflict

8.4. Recovery

Đây là một điểm mạnh của kiến trúc hiện tại.

Một tình huống nguy hiểm:

Gateway gọi domain
Domain ghi thành công
Gateway chết trước khi lưu response
Client retry

Nếu không có idempotency/reconciliation, một booking có thể bị tạo hai lần.

X-One đã xây dựng migration/state cho confirmation execution, workflow reconciliation và recovery claims để xử lý lớp lỗi này.

9. Multi-service orchestration

9.1. Dependency graph

Ví dụ:

flowchart LR
    A[Search Restaurant] --> B[Select + Confirm Restaurant]
    B --> C[Resolve Restaurant Location]
    C --> D[Ride Quote]
    D --> E{Fare <= limit?}
    E -->|Yes| F[Prepare Ride]
    E -->|No| G[Ask User]

Dependency phải dùng output authoritative của task trước. Không được lấy địa chỉ mà model tự nghĩ ra.

9.2. Partial success

Một workflow nhiều dịch vụ không luôn có kết quả all-or-nothing.

Ví dụ:

Restaurant: CONFIRMED
Ride: NO_DRIVER

Kết quả hợp lý là:

PARTIAL_SUCCESS

Không nên tự động hủy bàn chỉ vì không có xe, trừ khi một compensation policy rõ ràng cho phép.

9.3. Compensation

Nên giới hạn ba nhóm:

• NONE;
• USER_CONFIRM_REQUIRED;
• AUTOMATIC_SAFE_COMPENSATION.

Không cho LLM tự quyết một hành động rollback có side effect.

10. Data architecture

10.1. Logical database ownership

Codebase hiện sử dụng một PostgreSQL instance cho local development nhưng tách logical database/owner:

• xone_core;
• xone_agent;
• xone_food;
• xone_ride;
• xone_restaurant;
• xone_healthcare.

Đây là lựa chọn thực dụng cho MVP:

• chi phí vận hành thấp;
• dễ chạy local;
• vẫn giữ service boundary;
• sau này có thể tách physical instance khi cần.

10.2. Không cross-domain SQL

Gateway không được query trực tiếp database của Food để quyết định Restaurant hoặc Ride.

Mọi domain phải giao tiếp qua typed API.

Lợi ích:

• giảm coupling;
• dễ test;
• dễ tách deployment;
• ownership rõ;
• giảm khả năng business rule bị nhân bản.

10.3. Dữ liệu sandbox

Hiện sản phẩm là MVP/local sandbox. Catalog và seed data cho phép demo flow nhưng chưa tương đương provider production.

Do đó cần phân biệt:

“hệ thống có thể thực thi workflow”

với:

“hệ thống đang kết nối với thị trường thật”

Hai vấn đề khác nhau.

11. Bản đồ, geocoding và routing

Map là một trong các nguồn bug UX lớn nhất vì nó liên quan đồng thời tới:

• geocoding;
• tile provider;
• route geometry;
• container size;
• async loading;
• marker state;
• tracking update;
• ETA;
• fallback.

11.1. Nguyên tắc hiển thị

• loading phải có skeleton/spinner;
• không render map trước khi container có kích thước ổn định;
• sau khi modal mở, map cần invalidateSize/equivalent nếu library yêu cầu;
• map chỉ render coordinate được xác thực;
• nếu provider lỗi, UI hiển thị route facts thay vì vẽ dữ liệu giả;
• marker animation không được tạo cảm giác xe “teleport”.

11.2. ETA

ETA phải tách:

Pickup ETA
Travel duration
Total estimated journey

Không nên dùng một con số hardcode cho mọi route.

Production cần provider routing/traffic phù hợp. Trong sandbox, ETA phải được ghi rõ là estimate và thuật toán fallback phải deterministic.

12. UI/UX solution

12.1. Chat-first, không chat-only

X-One nên là giao diện hội thoại kết hợp rich UI.

LLM thích hợp để hiểu ý. Nhưng user không nên phải gõ text cho mọi bước.

Ví dụ:

• chọn nhà hàng bằng card;
• chỉnh số người trực tiếp trên form;
• chọn giờ bằng time control;
• chọn address bằng autocomplete;
• xác nhận bằng button;
• theo dõi route bằng map.

12.2. Form phải editable

Khi Assistant render một proposal:

Điểm đi: VinUni
Điểm đến: Hồ Gươm
Xe: 4 chỗ
Giá: 140.000đ

user nên có thể bấm Chỉnh sửa và thay trực tiếp những field được phép thay đổi.

Sau mỗi material change:

1. invalidate quote/confirmation cũ;
2. revalidate domain;
3. lấy authoritative quote mới;
4. render lại proposal.

12.3. Progressive disclosure

Một danh sách 20 nhà hàng không nên đẩy chat dài hàng nghìn pixel.

Nên dùng:

• 3–5 recommendation đầu;
• “Xem thêm”;
• pagination/cursor;
• modal/drawer cho detail;
• filter chips;
• ranking giải thích ngắn.

12.4. Loading state là first-class state

Bug document nhắc nhiều lần việc thiếu spinner.

Các trạng thái bắt buộc thiết kế riêng:

• initial loading;
• loading next page;
• autocomplete loading;
• map loading;
• submitting;
• waiting for driver;
• payment processing;
• retrying;
• partial failure;
• empty result.

Không nên chỉ disable button mà không cho user biết hệ thống đang làm gì.

13. Bảo mật và privacy

13.1. Authentication

Gateway hiện có các thành phần cho:

• register/login;
• Argon2 password hashing;
• JWT access token;
• rotating refresh session;
• session revocation;
• change/reset password;
• admin guard.

13.2. LLM trust boundary

Các input sau đều phải coi là untrusted:

• user text;
• model output;
• provider output;
• retrieved text;
• tool text.

Không chuỗi text nào được tự biến thành permission.

13.3. Healthcare

Không gửi dữ liệu y tế không cần thiết vào model.

X-One không nên mở rộng sang:

• chẩn đoán;
• kê thuốc;
• thay thế bác sĩ.

Nếu tương lai xử lý dữ liệu sức khỏe thật, yêu cầu privacy/compliance sẽ tăng mạnh.

13.4. Payment

Hiện tại là sandbox. Production payment cần:

• provider tokenization;
• PCI scope review;
• webhook signature validation;
• reconciliation;
• dispute/refund flow;
• ledger/audit chặt chẽ.

Không nên tự lưu full card number/CVV.

14. Reliability và observability

X-One là hệ thống phân tán. Một request assistant có thể đi qua:

Browser
→ Gateway
→ Agent
→ Gateway
→ Domain
→ Database
→ Gateway
→ Agent composer
→ Browser

Do đó cần correlation ID xuyên suốt.

Các metric quan trọng:

API

• latency p50/p95/p99;
• 4xx/5xx rate;
• timeout;
• retry count.

AI

• model latency;
• token usage;
• provider fallback;
• semantic validation failure;
• clarification rate;
• unsupported rate.

Product

• search → selection conversion;
• selection → confirmation;
• confirmation → success;
• cancellation rate;
• partial-success rate;
• average turns per completed task.

Quality

• intent accuracy;
• slot/constraint accuracy;
• reference resolution accuracy;
• context retention;
• tool exactness;
• unsafe action rate;
• hallucinated fact rate.

15. Kiểm thử và Evaluation

15.1. Vì sao unit test chưa đủ

Một function có thể pass unit test nhưng sản phẩm vẫn lỗi khi user thực sự thao tác trên browser.

Vì vậy cần pyramid:

Unit
  ↓
Contract
  ↓
Integration
  ↓
Gateway/domain E2E
  ↓
Browser E2E
  ↓
AI behavioral evaluation

15.2. AI eval nên test theo behavior class

Không nên chỉ tạo test cho từng câu feedback.

Ví dụ feedback:

“đã gửi vị trí nhưng bot vẫn hỏi lại.”

Không chỉ thêm đúng một test câu đó. Nên tạo một cluster:

location from UI
location from device
saved address
explicit text location
conflicting locations
stale previous location
relative “ở đây”
location changed mid-flow

Tương tự với:

• budget;
• time correction;
• candidate reference;
• multi-intent;
• interrupt/resume;
• out-of-scope;
• stale confirmation;
• duplicate actions.

15.3. Browser E2E

Playwright là lựa chọn phù hợp cho X-One vì có thể kiểm tra:

• mọi route;
• button/control;
• responsive viewport;
• network errors;
• console errors;
• race conditions;
• refresh/back/forward;
• screenshots/traces;
• map/modal behavior.

Các flow transaction có state nên chạy live E2E với worker thấp, tránh parallel tạo race giả.

16. Hiện trạng và bằng chứng tính khả thi

Phần này mô tả bằng chứng có trong repository/current-state, không phải tuyên bố rằng hệ thống đã production-ready.

Codebase hiện đã có:

• Web Next.js hoàn chỉnh hơn mức skeleton;
• API Gateway NestJS;
• Agent FastAPI/LangGraph;
• bốn domain FastAPI;
• PostgreSQL migrations theo ownership;
• authentication;
• confirmation;
• payment sandbox;
• audit/recovery;
• Tool Registry;
• multi-service persistence;
• admin/product-ops;
• Jest/pytest/Playwright suites;
• Docker Compose/local bootstrap.

Các checkpoint gần đây trong tài liệu current-state ghi nhận các đợt test lớn với hàng trăm test Agent/Gateway/domain, mock Playwright và isolated Compose runtime. Một checkpoint 21/08 ghi nhận toàn bộ stack 8 container healthy và browser transaction harness chạy qua nhiều domain. Đây là bằng chứng mạnh rằng kiến trúc không chỉ tồn tại trên giấy.

Tuy nhiên, repository cũng chủ động ghi nhận các gate chưa hoàn toàn khép kín, đặc biệt ở:

• provider live/external evidence;
• một số behavior AI phức tạp;
• multi-service/GUI handoff coverage;
• exact live Ride ETA/interpolation;
• pagination/map timing ở một số surface;
• các scenario recovery nâng cao.

Tập hợp bug/feedback người dùng cũng cho thấy product quality vẫn là bottleneck quan trọng. Các lỗi này chủ yếu nằm trong ba cluster:

1. AI behavior/context;
2. map/realtime/ETA;
3. UI state/list/form/loading.

Điều đó cho thấy dự án đã qua giai đoạn “có chạy hay không” và bước vào giai đoạn khó hơn: làm cho toàn bộ trải nghiệm đủ chính xác, nhất quán và dễ tin cậy.

17. Đánh giá tính khả thi

17.1. Tính khả thi kỹ thuật — Cao cho MVP, Trung bình–Cao cho production

Điểm thuận lợi

• stack phổ biến, dễ tuyển người và triển khai;
• architecture boundary tương đối rõ;
• domain decomposition phù hợp;
• có typed contracts;
• đã có migrations và persistence;
• có deterministic fallback khi LLM lỗi;
• có confirmation/idempotency/recovery;
• có automated tests;
• có local containerized runtime.

Thách thức

• integration với provider thật;
• distributed consistency;
• realtime;
• map/routing accuracy;
• semantic ambiguity;
• cost/latency LLM;
• production observability.

Kết luận

Không có yếu tố kỹ thuật nào khiến ý tưởng X-One “không thể làm được”. Phần khó nằm ở chất lượng triển khai và tích hợp, không phải tính khả thi nền tảng.

17.2. Tính khả thi của AI — Trung bình–Cao

LLM hiện nay đủ khả năng hỗ trợ semantic understanding cho bài toán này, nhưng không đủ đáng tin để tự làm transaction controller.

Kiến trúc hybrid của X-One là hợp lý:

LLM → semantic understanding
Code → policy/planning validation
Backend → transaction authority

Độ chính xác sẽ phụ thuộc chủ yếu vào:

• schema chất lượng;
• context assembly;
• reference resolution;
• constraint modeling;
• eval coverage;
• provider/model choice;
• fallback behavior.

Không cần một model cực lớn cho mọi turn. Có thể dùng routing:

simple/high-confidence
→ model nhanh/rẻ

complex/multi-intent/low-confidence
→ model mạnh hơn

still ambiguous
→ hỏi user

Điều này giúp tối ưu cả cost và accuracy.

17.3. Tính khả thi dữ liệu — Trung bình

Trong sandbox, seed/import data đủ để chứng minh workflow.

Production khó hơn vì cần:

• dữ liệu cập nhật;
• availability realtime;
• menu/price freshness;
• driver supply;
• location accuracy;
• provider SLA;
• API terms/licensing.

Nếu không có provider thật, X-One chỉ là orchestration demo, chưa phải marketplace/service platform thực tế.

17.4. Tính khả thi vận hành — Trung bình–Cao

Docker Compose phù hợp local/MVP.

Để production cần chuyển dần tới:

• container registry;
• managed runtime hoặc VM/container orchestration;
• managed PostgreSQL;
• secret manager;
• HTTPS/domain;
• logging/metrics;
• backup/restore;
• alerting;
• rollout/rollback.

Không nhất thiết phải dùng Kubernetes sớm. Với traffic ban đầu, một nền tảng container managed hoặc VPS chuẩn hóa có thể đủ.

17.5. Tính khả thi kinh doanh — Có tiềm năng nhưng phụ thuộc integration

Value proposition dễ hiểu:

“Một nơi để hoàn thành nhiều việc đời sống bằng một yêu cầu tự nhiên.”

Lợi ích:

• giảm app switching;
• giảm thời gian tìm kiếm;
• giảm thao tác nhập lại;
• hỗ trợ người dùng khi workflow phức tạp;
• tạo cơ hội cross-service.

Nhưng moat không nằm ở chatbot UI. Lợi thế bền vững sẽ đến từ:

• provider ecosystem;
• orchestration reliability;
• context/memory chính xác;
• dữ liệu tốt;
• trust;
• conversion rate;
• cost efficiency.

18. Phân tích rủi ro

19. Hướng phát triển ưu tiên

Giai đoạn 1 — Product stabilization

Mục tiêu

Đưa Web app tới trạng thái demo ổn định, không có lỗi UX rõ ràng.

Ưu tiên

1. hoàn thiện Ride cancel;
2. chuẩn hóa ETA/tracking;
3. map loading và resize;
4. autocomplete address;
5. pagination/“xem thêm” Food và Restaurant;
6. spinner/skeleton tất cả async state;
7. sửa delivery fee/address selection;
8. editable form trong chat;
9. full-screen chat + sticky composer + toggle ContextRail;
10. loại bỏ technical copy khỏi UI.

Exit criteria

• không có console error không giải thích;
• không có overlap/clipping ở viewport chính;
• tất cả loading state có feedback;
• tất cả critical button có happy/error path;
• browser E2E pass các flow demo.

Giai đoạn 2 — AI behavior hardening

Mục tiêu

Assistant hiểu đúng hơn, hỏi ít hơn và không mất context.

Tập trung vào

• location precedence;
• budget semantics;
• time/date correction;
• current resource;
• ordinal/deictic reference;
• interrupt/resume;
• multi-intent;
• graceful refusal;
• clarification policy;
• confidence routing;
• contradiction detection.

Nguyên tắc

Không hardcode theo từng câu feedback.

Mỗi lỗi phải được biến thành failure family + regression set.

Giai đoạn 3 — Domain completeness

Ride

• authoritative route provider;
• multi-stop waypoint support;
• realistic driver simulation/live feed;
• pickup ETA vs trip ETA;
• cancellation policy;
• fare threshold condition.

Restaurant

• robust availability;
• opening hours normalization;
• budget/ranking;
• modify reservation;
• fallback tương tự;
• media quality.

Healthcare

• better specialty/department mapping;
• reschedule;
• patient context;
• alternate slot suggestion;
• safety refusal.

Food

• complete catalog pagination;
• current-location delivery;
• fee consistency;
• option/customization;
• tracking/reorder.

Giai đoạn 4 — Multi-service orchestration V2

Hỗ trợ tốt:

Restaurant → Ride
Healthcare → Ride
Food + Healthcare độc lập
multi-stop Ride phụ thuộc resource trước
condition theo budget/fare
partial success

Không cần generic arbitrary workflow language. Chỉ hỗ trợ các condition class được review.

Giai đoạn 5 — Provider integration

Từng domain nên có adapter interface.

Domain interface
     ↓
Sandbox adapter
     ↓
Provider A
     ↓
Provider B

Không để provider-specific schema lan vào Agent.

Ưu tiên integration:

1. geocoding/routing;
2. payment sandbox → payment provider test environment;
3. restaurant availability/provider;
4. ride provider/simulation nâng cao;
5. healthcare scheduling partner.

Giai đoạn 6 — Production hardening

• deployment pipeline;
• TLS/domain;
• secret manager;
• managed DB;
• backups;
• migration rollback plan;
• structured logs;
• metrics/dashboard;
• alerting;
• rate limiting;
• abuse prevention;
• privacy retention policy;
• support/operator runbook;
• load test;
• chaos/recovery test.

Giai đoạn 7 — Personalization và memory có kiểm soát

Chỉ nên làm sau khi transaction core ổn định.

Có thể ghi nhớ khi user cho phép:

• nhà/công ty;
• loại xe thường dùng;
• sở thích ẩm thực;
• dietary preference;
• preferred clinic/facility.

Cần UI để:

• xem;
• sửa;
• xóa;
• tắt memory.

Không nên dùng vector DB chỉ vì “AI app cần vector DB”. Với preference structured, relational storage thường đủ.

Giai đoạn 8 — Mobile và channel expansion

Mobile hiện không nên là ưu tiên trước Web quality.

Sau khi Web ổn định có thể:

• hoàn thiện Expo app;
• push notification;
• deep link;
• background tracking phù hợp permission;
• channel adapters khác.

Voice có thể là roadmap xa hơn nhưng không cần để chứng minh core value.

20. Những công nghệ không cần thêm ở giai đoạn hiện tại

X-One không tự động tốt hơn chỉ vì thêm nhiều thành phần “AI”.

Chưa có lý do mạnh để thêm:

• multi-agent swarm;
• vector database cho conversation state;
• knowledge graph;
• agent tự query SQL;
• LLM critic chạy mọi turn;
• event sourcing toàn hệ thống;
• Kubernetes sớm;
• một workflow engine mới chỉ để thay orchestration hiện có.

Các thành phần này chỉ nên xuất hiện khi có một bottleneck cụ thể được đo lường.

21. KPI đề xuất

21.1. AI Quality

21.2. Product

21.3. System

Các ngưỡng production phải được điều chỉnh bằng dữ liệu thực thay vì giữ cứng theo tài liệu MVP.

22. Chiến lược mở rộng domain

Một domain mới không nên yêu cầu sửa toàn bộ Agent.

Quy trình:

1. Define domain ownership
2. Define OpenAPI contract
3. Implement domain service
4. Add capability to Tool Registry
5. Generate/update typed client
6. Add Agent semantic capability mapping
7. Add Gateway orchestration policy
8. Add confirmation/risk classification
9. Add UI card/form
10. Add tests/eval

Ví dụ domain tương lai:

• khách sạn;
• vé tàu/xe;
• salon;
• dịch vụ tại nhà;
• sự kiện;
• grocery;
• logistics cá nhân.

Điểm mạnh của X-One khi đó là một orchestration framework dùng chung, không phải một prompt khổng lồ chứa logic của tất cả dịch vụ.

23. Định vị sản phẩm

X-One không nên định vị là:

“ChatGPT nhưng có nút đặt xe.”

Định vị mạnh hơn là:

Một lớp điều phối dịch vụ cá nhân bằng ngôn ngữ tự nhiên, kết nối nhiều quy trình và luôn giữ người dùng trong vòng kiểm soát giao dịch.

Ba thuộc tính cần giữ:

1. Contextual

Không hỏi lại thông tin đã biết và hiểu các reference giữa UI + conversation.

2. Transaction-safe

Không tự ý thực hiện side effect. Luôn dựa trên backend authority.

3. Cross-service

Có thể lập kế hoạch xuyên nhiều dịch vụ và quản lý partial failure.

24. Điểm khác biệt kỹ thuật có thể trình bày khi demo/bảo vệ

Nếu cần giải thích dự án trong buổi demo, không nên chỉ nói “dùng Gemini + LangGraph”. Các điểm đáng nhấn mạnh hơn là:

1. AI không trực tiếp sở hữu giao dịch.
2. Typed semantic understanding thay vì parse text tùy ý xuyên hệ thống.
3. Deterministic planner/policy khóa risk và confirmation.
4. Gateway orchestration boundary tách AI khỏi domain.
5. Domain ownership cho Food/Ride/Restaurant/Healthcare.
6. Idempotency + recovery chống duplicate khi network/process lỗi.
7. Stale confirmation invalidation khi user đổi điều khoản.
8. Reference resolution cho “cái thứ hai”, “đến đó”, resource từ UI.
9. Partial success cho workflow đa dịch vụ.
10. Browser + AI behavioral evaluation, không chỉ unit tests.

Đây là các đặc điểm khiến X-One gần một transactional agent platform hơn một chatbot demo.

25. Kiến trúc mục tiêu nên dừng ở đâu?

Một kiến trúc hợp lý cho X-One trong vài vòng phát triển tới là:

Context Normalizer
        ↓
Typed Understanding
        ↓
Semantic Validator
        ↓
Deterministic Planner / Policy
        ↓
Gateway Orchestrator
        ↓
Domain Authority
        ↓
Grounded Result
        ↓
Natural Response + Structured UI

Kèm theo:

• structured conversation state;
• hard/soft constraints;
• money reasoning;
• time/location normalization;
• active-resource resolution;
• bounded conditional planning;
• confirmation;
• idempotency;
• recovery;
• confidence-aware model routing.

Đây đã là một kiến trúc đủ mạnh để tiếp tục mở rộng mà chưa bị overengineering.

Nếu accuracy vẫn thấp sau khi đạt cấu trúc này, bước tiếp theo không nên là thêm một “agent” mới. Bước đúng hơn là:

Eval
→ tìm failure cluster
→ xác định layer gây lỗi
→ sửa schema/context/prompt/model/contract
→ regression test

26. Kế hoạch phát triển đề xuất theo ưu tiên

P0 — Không được sai

• confirmation;
• stale-action invalidation;
• idempotency;
• authoritative price/availability;
• cancellation;
• actor isolation;
• safe healthcare boundary;
• context không làm sai resource.

P1 — Trải nghiệm người dùng trực tiếp

• chatbot behavior;
• location/context;
• budget;
• map;
• ETA;
• loading;
• pagination;
• editable forms;
• active service state;
• error recovery.

P2 — Differentiator

• dependent multi-service;
• conditional workflows;
• multi-stop ride;
• intelligent ranking;
• GUI → AI context handoff;
• memory có consent.

P3 — Production

• provider thật;
• payment thật;
• monitoring;
• operator workflow;
• deployment hardening;
• privacy/compliance;
• scaling.

P4 — Expansion

• mobile parity;
• domain mới;
• personalization nâng cao;
• voice/channel mới nếu có nhu cầu thật.

27. Kết luận

X-One giải một bài toán thực tế và có giá trị: biến các dịch vụ rời rạc thành một hành trình thống nhất có thể điều khiển bằng ngôn ngữ tự nhiên.

Codebase hiện tại cho thấy dự án đã có nền tảng kỹ thuật đáng kể: Web, Gateway, AI Agent, bốn domain service, persistence, typed contracts, transaction safeguards, test suite và local runtime. Vì vậy, tính khả thi của MVP đã được chứng minh ở mức kỹ thuật.

Thách thức lớn nhất từ đây không phải “xây thêm nhiều module” mà là hoàn thiện ba lớp chất lượng:

1. AI hiểu đúng và giữ đúng context;
2. backend luôn bảo toàn authority và transaction safety;
3. frontend phản ánh state rõ ràng, nhanh, dễ chỉnh sửa và không tạo cảm giác hệ thống bị lỗi.

Nếu giải quyết tốt ba lớp này, X-One có thể chuyển từ một dự án AI demo sang một nền tảng service orchestration có khả năng phát triển thực tế.

Định hướng tối ưu là tiếp tục đào sâu chất lượng trên kiến trúc hiện có, mở rộng theo contract và bằng evidence, thay vì tăng độ phức tạp kiến trúc một cách không cần thiết.

28. Phụ lục A — Ma trận thành phần và trách nhiệm

29. Phụ lục B — Ví dụ end-to-end target

Yêu cầu

“Tối mai tìm nhà hàng Nhật gần Hồ Tây cho 4 người, tổng khoảng 2 triệu. Nếu còn bàn lúc 7h thì đặt. Sau đó gọi xe từ nhà, ghé Cầu Giấy đón Minh rồi tới quán. Nếu xe quá 300k thì hỏi lại tôi.”

Semantic interpretation

tasks:
  - type: restaurant
    operation: search_and_reserve
    constraints:
      cuisine: Japanese
      location: Hồ Tây
      party_size: 4
      budget:
        comparator: MAX
        max: 2000000
        basis: TOTAL
      time: tomorrow 19:00

  - type: ride
    operation: quote_and_book
    depends_on: restaurant.selected_resource
    route:
      pickup: saved_address.home
      waypoints:
        - Cầu Giấy / Minh
      destination: restaurant.selected_resource
    constraints:
      max_fare: 300000

Execution

Search restaurant
→ authoritative candidates
→ user selects
→ check availability
→ show reservation confirmation
→ user confirms
→ reserve
→ resolve selected restaurant location
→ route quote with ordered waypoint
→ if fare > 300k: ask user
→ otherwise show ride confirmation
→ user confirms
→ book ride
→ track both resources

Safety rules

• không tự chọn nhà hàng nếu ambiguity cao;
• không đổi giờ 19:00 thành slot khác mà không nói;
• không bịa tọa độ;
• không dùng confirmation cũ sau khi user đổi nhà hàng;
• không rollback reservation tự động nếu Ride NO_DRIVER trừ khi policy cho phép;
• không vượt 300k nếu user chưa xác nhận.

Đây là loại workflow thể hiện rõ nhất giá trị dài hạn của X-One.