Answer Template — Danh sách API

Sequence diagram

sequenceDiagram
    actor Dev as Dev/PO (Studio)
    participant Web as web-bff (public /v1)
    participant PS as project-svc (owner + authz)
    Dev->>Web: GET /v1/projects/{pid}/answer-templates?q=&status=&cursor= (JWT)
    Web->>PS: forward (verified JWT, X-Project-Id)
    Note over PS: verify project-member + quyền viewer<br/>SET LOCAL app.project_id (RLS)
    Note over PS: SELECT project.answer_templates WHERE deleted_at IS NULL (filter + cursor)
    PS-->>Web: 200 {data, next_cursor}
    Web-->>Dev: Render danh sách + trạng thái published

Mô tả luồng nghiệp vụ

Mô tả API

API Request

Header: Authorization Bearer JWT (Y).

Query: q (search ILIKE), status (published/draft_only), cursor, limit (≤100).

API Response

200 — {data[], next_cursor}; mỗi item: id, name, description, current_version, updated_by, updated_at.

Bảng mã lỗi

Sequence diagram

sequenceDiagram
    actor Dev as Dev/PO
    participant Web as web-bff
    participant PS as project-svc
    participant VS as version-svc
    Dev->>Web: GET /v1/projects/{pid}/answer-templates/{id} (JWT)
    Web->>PS: forward
    Note over PS: SELECT metadata entity (id, name, description, RLS project)
    alt không có / đã xóa mềm
        PS-->>Web: 404 NOT_FOUND
    else tồn tại
        PS->>VS: S2S GET /v1/internal/components/{ws}/resolve (lấy DSL v0)
        VS-->>PS: DSL v0 + version history (version_no≥1)
        PS-->>Web: 200 {metadata + dsl + versions[]}
    end
    Web-->>Dev: Mở Visual Builder với DSL v0

Mô tả luồng nghiệp vụ

Mô tả API

API Response

200 — {id, name, description, dsl, current_version_id, versions[]}. 404 NOT_FOUND nếu không thuộc project.

Bảng mã lỗi

Sequence diagram

sequenceDiagram
    actor Dev as Dev/PO
    participant Web as web-bff
    participant PS as project-svc
    Dev->>Web: POST /v1/projects/{pid}/answer-templates (JWT + Idempotency-Key)
    Web->>PS: forward
    Note over PS: verify quyền editor + validate (name 3-100, description ≤ 500)
    Note over PS: INSERT project.answer_templates
    alt tên chưa dùng
        PS-->>Web: 201 template (draft)
    else trùng (project_id, name)
        PS-->>Web: 409 NAME_CONFLICT
    end

Mô tả luồng nghiệp vụ

Mô tả API

API Request

Header: Authorization (Y), Idempotency-Key (Y). Body: {name, description?}.

API Response

201 — {id, name, description, current_version_id: null, created_at}.

Bảng mã lỗi

Sequence diagram

sequenceDiagram
    actor Dev as Dev/PO
    participant Web as web-bff
    participant PS as project-svc
    Dev->>Web: POST /v1/projects/{pid}/answer-templates/{id}/update (JWT + Idempotency-Key)
    Web->>PS: forward
    Note over PS: load template (404 nếu không có)
    Note over PS: validate field đổi (name/description/layout/variables)
    Note over PS: UPDATE bản draft
    PS-->>Web: 200 template đã cập nhật

Mô tả luồng nghiệp vụ

Mô tả API

API Request

Header: Authorization (Y), Idempotency-Key (Y). Body: {name?, description?, layout?, variables?} (full-replace phần gửi).

API Response

200 — template đã cập nhật. 404 nếu không thuộc project.

Bảng mã lỗi

Sequence diagram

sequenceDiagram
    actor Dev as Dev/PO
    participant Web as web-bff
    participant PS as project-svc
    participant VS as version-svc
    Dev->>Web: POST /v1/projects/{pid}/answer-templates/{id}/delete (JWT + Idempotency-Key)
    Web->>PS: forward
    PS->>VS: S2S GET /v1/internal/answer-templates/{id}/references
    alt còn Workspace Version tham chiếu
        VS-->>PS: references[...]
        PS-->>Web: 409 TEMPLATE_IN_USE + details.referenced_by[]
    else không còn ref
    Note over PS: UPDATE deleted_at = now() (xóa mềm)
        PS-->>Web: 200 {deleted: true}
    end

Mô tả luồng nghiệp vụ

Mô tả API

API Request

Header: Authorization (Y), Idempotency-Key (Y).

API Response

200 — {deleted: true} (idempotent). 409 TEMPLATE_IN_USE + details.referenced_by[].

Bảng mã lỗi

Sequence diagram

sequenceDiagram
    actor Dev as Dev/PO
    participant Web as web-bff (public /v1)
    participant PS as project-svc (authz)
    participant VS as version-svc (S2S)
    Dev->>Web: POST /v1/projects/{pid}/answer-templates/{id}/draft (JWT + Idempotency-Key)
    Web->>PS: forward (verified JWT, X-Project-Id)
    Note over PS: verify quyền editor
    PS->>VS: S2S POST /v1/internal/components/{ws}/upsert {kind:'answer_template', component_id, dsl}
    Note over VS: content_hash JCS RFC 8785
    Note over VS: UPSERT components version_no=0 (v0, mutable) — KHÔNG mint
    alt expected_content_hash lệch
        VS-->>PS: 409 DRAFT_CONFLICT
    else ok
        VS-->>PS: 200 {content_hash, updated_at}
    end
    PS-->>Web: 200
    Web-->>Dev: Đã lưu nháp

Mô tả luồng nghiệp vụ

Mô tả API

API Request

Header: Authorization (Y), Idempotency-Key (Y). Body: {dsl, expected_content_hash?}.

API Response

200 — {content_hash, updated_at}. 409 DRAFT_CONFLICT khi hash lệch.

Sequence diagram

sequenceDiagram
    actor Dev as Dev/PO
    participant Web as web-bff (public /v1)
    participant PS as project-svc (authz)
    participant VS as version-svc (S2S)
    participant OB as OpenBao Transit
    Dev->>Web: POST /v1/projects/{pid}/versions/publish (JWT + Idempotency-Key)
    Web->>PS: forward
    PS->>VS: S2S POST /v1/internal/versions/publish {workspace_id}
    Note over VS: [1 tx] lock ws → đọc v0 → diff TỪNG component (gồm answer_template)
    loop mỗi answer_template đổi hash
        VS->>OB: sign Ed25519 (content_hash)
        OB-->>VS: signature
    Note over VS: INSERT components version_no=next (freeze DSL, immutable)
    end
    Note over VS: INSERT workspace_versions header trỏ các version_no chốt
    VS-->>PS: 201 {workspace_version_id, version_no, minted[]}
    PS-->>Web: 201
    Web-->>Dev: Version mới + badge published

Mô tả luồng nghiệp vụ

Mô tả API

API Request

Header: Authorization (Y), Idempotency-Key (Y). Body: {workspace_id}.

API Response

201 — {workspace_version_id, version_no, minted[]}.

Sequence diagram

sequenceDiagram
    participant PS as project-svc
    participant VS as version-svc
    PS->>VS: GET /v1/internal/answer-templates/{id}/references (S2S Ed25519, aud=version-svc)
    Note over VS: query index (project_id, component_id)<br/>trên components (kind=answer_template, version_no≥1)
    alt còn version tham chiếu
        VS-->>PS: 200 references[...]
    else không còn ref
        VS-->>PS: 200 references []
    end

Mô tả luồng nghiệp vụ

Mô tả API

API Request

Header: S2S bearer Ed25519, aud=version-svc; tenant từ claim.

API Response

200 — {template_id, references[]}; mỗi ref: workspace_version_id, version_no. Rỗng → [] (không 404).

Bảng mã lỗi

Bảng ghi nhận thay đổi tài liệu

_Loại thay đổi: A – Tạo mới, M – Sửa đổi, D – Xóa bỏ_

1. Tên service

agent-runtime (:50056) — render card từ resolved_dsl.json (Jinja sandbox, JCS hash verify) trên run path = ĐÃ BUILD (Seam 1 producer, T-CONV-08); web-bff (:4001) — MAPPER thuần forward message_end.metadata.card (engine-parity) = ĐÃ BUILD (Seam 3, T-CONV-10), no-op output filter (card đã strip ở producer/persist — §N2 point 3); conversation-svc (:50067) — vật mang SSE (message_end.metadata.card) + persistence (card_payload) = ĐÃ BUILD (Seam 2, T-CONV-09); studio-svc (:3000) — FE Answer Card renderer (answer/answer-card.tsx) render 8 catalog type + dispatch postback/open_url = ĐÃ BUILD (Seam 4, T-CONV-11).

2. Mô tả chung

Khi agent trả lời dạng có cấu trúc (form, danh sách lựa chọn, nút CTA, carousel...), answer không phải text thuần mà là một Answer Card — layout + field binding + action định nghĩa trong agent DSL, dựng bằng Visual Builder (TKCT 3.9). Runtime flow: agent-runtime load card definition từ resolved_dsl.json (verify JCS hash trước khi nạp), render qua Jinja sandbox (block __import__, missing variable defaults) + filter action URL allowlist (render-time), conversation-svc filter lại + persist bản POST-FILTER, web-bff forward metadata.card nguyên trạng (mapper — Seam 3), Chat UI render component tương ứng.

Khâu vận chuyển — card đã render đi trong SSE stream (message_end.metadata.card) và lưu vào message (card_payload) ra sao để xem lại transcript — đã land (T-CONV-08..11). Trang này đặc tả phần mở rộng đó.

3. Tính năng

End-user thấy answer dạng card tương tác trong chat (thay vì text); xem lại transcript vẫn render đúng card (từ card_payload đã persist); action trên card (button/selector) gửi turn chat mới hoặc mở URL trong allowlist.

4. Mô tả luồng xử lý

4.1. Hiển thị Card Template

4.1.1. Luồng tổng quan

sequenceDiagram
    autonumber
    actor U as End User
    participant FE as Chat UI
    participant CV as conversation-svc (:50067)
    participant AR as agent-runtime (:50056)
    participant B as web-bff (:4001)
    participant PG as PostgreSQL (schema conv)

    U->>FE: Gửi câu hỏi (turn chat thường)
    FE->>B: POST /v1/chat-messages (SSE)
    B->>CV: proxy request
    Note over CV: Crisis check in-process trước (p99 < 5ms)<br/>— crisis bypass KHÔNG render card
    CV->>AR: invoke (non-crisis)
    Note over AR: Agent quyết định trả lời bằng card<br/>card/card_payload_renderer.py: Jinja sandbox render<br/>resolved_dsl.json (JCS hash verify)
    AR-->>CV: SSE chunk* + done.payload.card (producer-native)
    Note over CV: Apply allowlist filter Answer Card<br/>(schema + length cap + action URL —<br/>CÙNG cấu hình với web-bff) trước khi proxy
    CV-->>B: proxy SSE 1:1 (card đã filter)
    Note over B: Output filter (OPTIMAL §13 filter 5):<br/>validate lại schema + allowlist —<br/>defense-in-depth, no-op khi CV đã strip
    B-->>FE: message_end.metadata.card
    CV->>PG: INSERT assistant msg + card_payload POST-FILTER<br/>+ outbox conv.message.appended.v1 (1 transaction, sau done)
    FE-->>U: Render card component (form/list/button/carousel)

4.1.2. Danh sách API và tiến trình

4.1.3. Mô tả API

API 1: Field card trên message_end.metadata của stream chat

API Request

Không đổi so với 3.12.3.1 — card là quyết định phía agent, client không gửi gì thêm.

_Permission yêu cầu:_ như 3.12.3.1.

API Response

_Body — field card trong message_end.metadata (always-present nullable):_

_Example response 200 (trích frame message_end — field card):_

{
  "conversation_id": "b3f1c2ae-8d4f-4c2a-9b7e-5a6d3e8f1c2b",
  "message_id": "a8d4f7c2-3e6b-4f9d-8b2a-1c5e9d7f3a48",
  "answer": "Anh/chị tham khảo 2 gói cước phù hợp dưới đây.",
  "metadata": {
    "is_crisis": false,
    "served_by": "agent_runtime",
    "tokens_in": 410,
    "tokens_out": 188,
    "ttft_ms": 580,
    "latency_ms": 2310,
    "card": {
      "template_id": "goi-cuoc-compare",
      "template_version": "1.2.0",
      "layout": {
        "type": "list",
        "children": [
          { "type": "text", "children": [], "props": { "value": "C90 — 4GB/ngày, 90.000đ/tháng" } },
          { "type": "text", "children": [], "props": { "value": "SD135 — 5GB/ngày, 135.000đ/tháng" } }
        ]
      },
      "actions": [
        { "id": "act-1", "kind": "open_url", "label": "Đăng ký 5G Gia Đình", "payload": "viettelmoney://pay?order=5G-GIADINH&ctx={conversation_id}" },
        { "id": "act-2", "kind": "postback", "label": "So sánh thêm gói", "payload": "So sánh các gói 5G khác" }
      ]
    }
  }
}

_Link swagger:_ /openapi.json → POST /v1/chat-messages (field card = ChatMessageMetadata.card + x-sse-event-message-end.metadata.card, OpenAPI 04 v1.5.0).

4.1.4. Mô tả luồng nghiệp vụ

4.2. Xử lý FE Answer Card (studio-svc — Seam 4, T-CONV-11)

Tầng FE cuối của chuỗi delivery: render card trong bubble trả lời và điều phối action. Reuse hạ tầng chat của engine (useChatContext().onSend, IChatItem, parse SSE message_end ở service/base.ts) — chỉ thêm một component mới + một dòng đọc metadata, KHÔNG đụng pipeline SSE/persist (đã do Seam 1-3 lo).

Render 8 type: form (fields + submit_label), text (variant heading/body/caption), image_media (image/video/audio), list (items), selector (single/multi options), button_cta (label + action), carousel (cards), confirmation (prompt + yes/no label). Action điều phối qua useChatContext():

- postback → onSend(payload) (gửi turn mới, reuse cơ chế SuggestedQuestions); no-op khi readonly. - open_url → window.open(url, '_blank', 'noopener,noreferrer') CHỈ khi url qua scheme-guard FE (https/http); scheme lạ (vd javascript:) → console.warn, KHÔNG mở. FE chỉ guard scheme cuối — KHÔNG dựng allowlist riêng (server đã strip action ngoài allowlist ở Seam 1+2). - confirmation → yes: onSend(yes_payload), no: onSend(no_payload).

Degrade: card_schema_version != "1.0" → render fallback text (chat.card.unsupportedVersion), KHÔNG throw — bubble vẫn sống. FE render plain/escaped text (KHÔNG dangerouslySetInnerHTML), KHÔNG re-validate schema (server validate trước wire).

4.3. Ràng buộc control-level Answer Template Card (KBNV §2.2.10.3)

Trên màn Chat end-user, Answer Template Card render dưới dạng control tổng hợp (control #14, 3.12.3.3) gồm các thành phần con #15–20. Ràng buộc hiển thị theo KBNV:

Các ràng buộc trên là tầng render FE — không đổi contract wire card ở §4.1.3; label nút map field card.actions[].label, độ dài cắt/ellipsis do FE xử lý. Use case tham chiếu: card so sánh gói với Title "5G Gia Đình", Primary "Đăng ký 5G Gia Đình", Secondary "Kiểm tra vùng phủ 5G".

Bảng mã lỗi

Không có mã lỗi riêng — card đi trên stream chat, mã lỗi dùng chung 3.12.3.1 → Bảng mã lỗi. Lỗi render card phía agent-runtime degrade về text thuần (không fail turn); action URL ngoài allowlist bị strip + log ở agent-runtime (render-time) + conversation-svc (pre-persist), answer text vẫn về client. web-bff (Seam 3, T-CONV-10) chỉ forward metadata.card — không phát mã lỗi card.