HCI Ambiguity-Aware NL2SQL Frontend

A React frontend for an HCI-powered, interactive ambiguity-aware NL2SQL workflow. Phase 4 integrates the one-question-at-a-time clarification controls into a progressively revealed indented intention tree.

The real tree API is not finalized. The current implementation therefore uses a deterministic pancreas waiting-list mock behind the stable Nl2SqlService and intention-tree adapter boundaries; it does not invent browser endpoints or backend fields.

Phase 4 Demo

Use the Transplant Allocation PostgreSQL database and submit:

I need the pancreas waiting list, sorted correctly for all the pending matches. Show me the patient's ID, region, urgency status, the HLA mismatch number, and their rank.

This is a fixed mock, not a branching inference demo. Any structurally valid answer advances through the same 16 questions, tree snapshots, GT SQL, and five-row result fixture. Submitted answers still appear in expandable history nodes, and either escape option marks that answered node as an issue.

The exact presentation selections are documented in ../3rd iteration/demo happy path.txt.

Current Flow

1. Select a database and SQL dialect.
2. Enter the pancreas waiting-list query.
3. Answer one clarification question at a time.
4. Answer directly inside the green Answering node as each successful response replaces the full tree snapshot.
5. Expand non-active intentions and gray Answered nodes to inspect the original options, submitted answer, and an available source-backed SQL snippet.
6. Follow the recursively promoted active path using normal page scrolling; no canvas navigation is required.
7. After question 16, inspect the final read-only SQL and five-row result preview above the completed tree.

The initial snapshot contains all nine top-level intentions and question 1, but does not reveal the later 8.x or 9.x details. The viewer uses semantic nested lists, active-first ordering, disclosure controls, and capped mobile indentation. Grouping questions place each full option label above its group selector and stack their two main sections when the component becomes narrow.

Tech Stack

• React 19, Vite, and TypeScript
• Local shadcn-compatible UI components under src/components/ui
• Semantic recursive DOM and CSS for the integrated indented tree
• Lucide React icons
• useReducer workflow state
• Vitest, React Testing Library, and Oxlint

Key Boundaries

src/
├── App.tsx
├── app/query-reducer.ts
├── components/intention-tree/
│   ├── intention-tree-panel.tsx
│   ├── intention-tree-item.tsx
│   ├── build-indented-tree.ts
│   ├── answered-question-details.tsx
│   └── answer-state.ts
├── mocks/
│   ├── catalog.ts
│   └── pancreas-intention-tree.ts
└── services/nl2sql/
    ├── intention-tree-adapter.ts
    ├── mock-service.ts
    └── types.ts

• query-reducer.ts owns session transitions, pending submissions, history, and the latest complete tree snapshot.
• intention-tree-adapter.ts validates snapshot references and status invariants while dropping raw agent or trace fields.
• pancreas-intention-tree.ts holds the stable 16-question catalog and builds each complete snapshot from per-step visibility.
• build-indented-tree.ts derives the active path and stable display order without mutating snapshots.
• App.tsx composes the Query result and Integrated Tree sibling regions; recursive ordering and disclosure stay inside components/intention-tree.

Data Boundaries

• Only successful analyze or resolve responses update the tree.
• A submitted answer stays pending until resolve succeeds; failed responses do not advance history or the tree.
• Snapshots with duplicate IDs, broken references, an invalid answering node, or an invalid status are rejected.
• Revisions must increase before a snapshot can replace the current tree.
• SQL snippets are optional. The mock includes only the seven snippets explicitly provided by the motivating example and does not infer 8.x or 9.x snippets from the final SQL.
• The result has the five GT SQL projection columns and a fixed five-row fixture sampled and correlated from organ_transplant_large.sql. The browser neither reads that dump nor runs a database at demo time.
• Agent names, schema, KB context, SQL diffs, and diagnostic traces do not enter the rendered domain model.

Commands

npm install
npm run dev
npm test
npm run lint
npm run build

Backend Integration

The frontend continues to depend on:

interface Nl2SqlService {
  listDatabases(): Promise<DatabaseOption[]>
  importDatabase(input: ImportDatabaseInput): Promise<ImportDatabaseJob>
  getImportJob(input: DatabaseJobInput): Promise<ImportDatabaseJob>
  connectDatabase(input: ConnectDatabaseInput): Promise<ConnectionDatabaseJob>
  getConnectionJob(input: DatabaseJobInput): Promise<ConnectionDatabaseJob>
  removeDatabase(input: RemoveDatabaseInput): Promise<void>
  analyze(input: AnalyzeInput): Promise<SessionTurnResponse>
  speculate(input: SpeculateInput): Promise<SpeculateResponse>
  getResultPage(input: ResultPageInput): Promise<ResultPage>
  resolve(input: ResolveInput): Promise<SessionTurnResponse>
  undoLast(input: UndoInput): Promise<SessionTurnResponse>
  executeReadonly(input: ExecuteInput): Promise<QueryExecution>
}

http-service.ts maps these operations to deployment-provided VITE_API_* paths and validates the returned catalog, database jobs, session views, projections, charts and result pages. The complete request/response and security contract is in 所需后端接口.md. Database onboarding transport is reserved, but the Add database management UI is not part of the current Phase 5 screen.

Not Implemented

• real HTTP tree endpoints or incremental tree merging;
• branching mock behavior;
• editing, moving, deleting, or reconnecting individual tree nodes;
• MiniMap, tree search, cross-query tree history, or HCI telemetry;
• modifying submitted answers, rationale collection, or retry UX;
• inferred SQL snippets or fabricated patient rows.