Chatbot to Business API

Business outcome

The chatbot's main conversation path streams a request through the UI to Dify. A product-question answer may then be cached through a protected backend route when the request has a matching cache context and Dify completed successfully. A separate backend SAV API accepts authenticated case-creation requests and forwards them to Logidav. A chat response does not imply that a business API ran, and a SAV case is not itself a payment refund.

Conversation and optional answer-cache path

View diagram source

sequenceDiagram
  participant User as Customer
  participant UI as Chatbot UI
  participant D as Configured Dify profile
  participant B as Chatbot backend

  User->>UI: Send chat input
  UI->>D: POST /chat-messages
  D-->>UI: Response stream
  UI-->>User: Preserve and stream Dify response
  opt Matching product-question context and completed non-error answer
    UI->>UI: Match SKU, normalized question, store, and language
    UI->>B: POST /api/v2/products/general-product-question-answers/store
    B->>B: Sanctum ability and route throttle
    B-->>UI: Cache result
  end
  Note over UI,B: Cache write is best-effort, but failure is non-fatal to the answer

Diagram

app/api/chat-messages/route.ts is the UI-to-Dify request path. The backend cache is an optional side path, not a request made for every chat turn.

SAV business API path

View diagram source

sequenceDiagram
  participant Caller as Request caller (UI caller not established here)
  participant B as Chatbot backend
  participant S as SavController
  participant L as LogidavService
  participant API as Logidav /api/sav
  participant DB as Logidav SAV records

  Caller->>B: POST /api/v2/sav/requests with Sanctum token
  B->>S: Require order-read and sav-create abilities
  S->>S: Validate request and delegate ticket creation
  S->>L: createSavTicket()
  L->>API: POST configured base URL + /sav
  API->>DB: Resolve sale, then route special request types or ordinary SAV creation
  API-->>L: Structured validation / HTTP result
  L-->>S: Result
  S-->>Caller: Backend response

Diagram

The backend base URL prefix and the UI caller for POST /api/v2/sav/requests were not established by the source review. The matching Logidav controller declares POST /api/sav; deployment configuration determines whether the backend's configured base URL includes the required /api prefix.

Numbered handoffs

Dify conversation and answer cache

1. The UI's POST() forwards chat input to the configured Dify profile's /chat-messages endpoint and preserves the upstream response/stream.
2. A separate cache context must match the request SKU, normalized question, store, and language.
3. Only a completed, non-error Dify stream with an answer schedules the cache write.
4. The UI posts to /api/v2/products/general-product-question-answers/store using the Menzzo auth token. The route is inside Sanctum auth, requires general-product-question-cache-write, and has a cache-store throttle.
5. A 401 clears and retries the token once. Cache failure is non-fatal to the already returned answer.

SAV request creation

1. The backend declares POST /api/v2/sav/requests inside Sanctum middleware requiring order-read,sav-create abilities. This route declaration does not establish which screen or workflow calls it.
2. SavController::createSavV2 validates the v2 request and delegates ordinary ticket creation to handleSavCreation.
3. LogidavService::createSavTicket() normalizes files, custom fields, and allowed propositions, then posts to the configured Logidav base URL plus /sav. It returns structured validation and HTTP failures.
4. Logidav's MenzzoChatbotWrapperApiController::createSavAction() receives POST /api/sav, requires increment_id and sav_type, resolves the sale, and routes cancellation, forgotten-coupon, and delivery-info-update cases through separate workflows.
5. SaleSavService::addSav() / addSavFromApi() persists the SAV record and filters products for API-created cases. communicationType=ai_chatbot marks a case as chatbot-created; reminder types use a separate reminder path.
6. Logidav's /api/customer/sav-status path can return SAV status, product, planning, and refund details for a query filtered by email or order. Its actual UI caller is not established here.

Data ownership and contracts

Data or action	Owner/path	Evidence limit
Conversation stream	UI → configured Dify profile.	Source-backed request path; active profile and environment configuration were not checked.
Product-question answer cache	UI → protected backend store route.	Exact match conditions, auth ability, one 401 retry, and non-fatal result are source-backed. This is not the source of a product's business truth.
SAV case	Chatbot backend request handling → Logidav SAV API/service and records.	The backend and Logidav code paths are source-backed. Base URL prefix and request caller remain unknown.
SAV status	Logidav /api/customer/sav-status.	Controller path returns the named case/order details; a consumer and runtime configuration were not verified.
Order and product facts	Backend has configured Logidav and Magento service integrations.	LogidavService verifies increment ID and persists normalized order detail; MagentoApiService provides configured REST calls. These service paths do not prove which chatbot screen calls each endpoint.
Refund payment	Provider and Logidav refund paths.	See Support and refunds; SAV creation is not proof that money was refunded.

Failures, retries, and duplicates

• Dify error or incomplete stream: the answer-cache branch is not scheduled. The review does not establish a general Dify retry policy.
• Cache auth: the cache helper clears/retries once on 401; other retry behavior is not established. A failed cache write does not fail the answer.
• SAV validation/HTTP errors: the backend/Logidav client returns structured failures. The exact configured URL prefix is unknown, so verify configuration with the owning team before diagnosing path mismatch.
• Forgotten-coupon case: this SAV type has a specific safeguard. The backend checks Logidav history before reserving the local request, fails closed with 503 if history is unavailable, and records the Logidav result. This does not prove general idempotency for other SAV types.
• Other case duplicates: source review did not establish a shared duplicate guard across every SAV type. Do not blindly replay a create request after an uncertain response.
• Other backend routes: route declarations for order, refund-validation, delivery, coupon, and payment APIs do not prove that the chatbot UI calls them or that a complete support workflow exists.

Diagnosis

1. For a missing answer, separate the UI request, Dify stream, and optional cache write. Do not expect a backend cache request on every chat turn.
2. For a cache issue, verify the four context-match fields and whether the Dify stream completed without an error before inspecting backend auth or throttling.
3. For a SAV issue, compare the authenticated backend route result, the Logidav service response, and the persisted Logidav case/status. Preserve a correlation or request identifier only if the owning application exposes one; its exact field is not established here.
4. Before replaying a SAV create request, determine whether the specific SAV type has an idempotency safeguard. The forgotten-coupon check must not be generalized to every case type.
5. For a payment-refund question, continue to the separate refund evidence. A SAV case status may report refund details without proving a provider reversal succeeded.

The Chatbot project overview retains the cross-system links. The exact /workflow-failures bounded-query behavior and logs API implementation were not re-read in this source review.

Evidence and open questions

Source-verified at pinned commits: UI-to-Dify streaming and conditional answer caching at axelites/menzzo-chatbot-ui@43c6f73518a7a8dda18c9c47fce9e4bf50ae1260; cache-store route authorization and backend SAV request path at axelites/menzzo-chatbot-backend@98f8bab4770d9e7d8e26d815171645f2895bb524; Logidav SAV endpoints and record handling at axelites/logidav@e0b7a25c1912039c1520eb04c1b4c242d74b6d1e.

Still unknown: the UI caller for the SAV request and status routes; active Dify profile, backend base URL and /api prefix; deployment configuration; caller coverage for other protected backend APIs; behavior of logs queries; and end-to-end owner acceptance.

Source references: UI Dify chat route and cache helper; backend API route declarations, SAV validation/controller, forgotten-coupon idempotency path, Logidav client; and Logidav chatbot SAV API, SAV status API, and SAV persistence.