Ida Dittrich 8970761bb8 extended PEK routes and included swisstopo connector

2025-12-15 07:21:17 +01:00

22 KiB

Raw Blame History

Prompt Page Requirements

This document contains the complete frontend requirements for all prompt management pages and components. All UI components are dynamically generated from backend metadata—no hardcoding required.

Overview
Page Structure and Layout
User Interactions and Functionality
Backend Routes and API Integration
Field and Attribute Reference
Dynamic Rendering Guidelines

Overview

The prompt management page enables users to manage prompts within their mandate. The frontend consists of a single page (/prompts) with different views/states:

List View - Browse, search, filter, and sort prompts
Edit View - Edit prompt properties
Create View - Create new prompts

All views use backend-driven UI generation, meaning field definitions, labels, validation rules, and UI structure come entirely from backend metadata through the /api/attributes/Prompt endpoint. Views are managed through component state and routing within the same page, not as separate routes.

Page Structure and Layout

Prompt Management Page (`/prompts`)

The prompt management page uses different views/states to handle different user interactions. Views are managed through component state and routing within the same page component.

List View

State: view === 'list' or selectedPromptId === null

What the user sees:

Main Content Area:
- Table or card grid displaying all prompts in the mandate
- Each prompt row/card shows: name, content preview, mandate ID
- Action buttons column in table (rendered on first load):
  - "Start Prompt" button - navigates to /chat-playground and starts workflow with prompt content
  - "Edit" button - switches to Edit View
  - "Delete" button - shows confirmation dialog and deletes prompt
- Clickable rows/cards that switch to Detail View (set selectedPromptId and view state)
Search and Filter Controls:
- General search input box (searches across all text fields)
- Field-specific filter controls (one filter per visible field)
- Active filter indicators (chips/badges showing applied filters)
- "Clear all filters" button when filters are active
Sorting Controls:
- Clickable column headers with sort indicators (up/down arrows)
- Visual indication of current sort field and direction
- Support for multi-level sorting
Pagination Controls:
- Page information display ("Page X of Y", "Showing 1-20 of 45 prompts")
- Previous/Next page buttons
- Page number buttons
- Page size selector (10, 20, 50, 100 items per page)
Action Buttons:
- "Create Prompt" button - switches to Create View

Detail View

State: view === 'detail' and selectedPromptId !== null

What the user sees:

Prompt Header Section:
- Prompt name (editable indicator if user has permission)
- Mandate ID (read-only)
Prompt Information Section:
- All prompt properties displayed as formatted fields
- Read-only fields shown as formatted text
- Editable fields shown with edit indicators (if user has permission)
- Special formatting:
  - Content → Display as formatted textarea or code block (if applicable)
  - Name → Display as heading
Action Buttons:
- Start Prompt button - navigates to /chat-playground and starts workflow with prompt content
- Edit button (if user has permission and editable fields exist) - switches to Edit View
- Delete button (if user has permission)

Edit View

State: view === 'edit' and selectedPromptId !== null

What the user sees:

Form Section:
- Dynamic form with editable prompt fields only
- Field labels with required indicators (asterisk for required fields)
- Help text/tooltips from field descriptions
- Input validation errors displayed inline
Action Buttons:
- Save button (submits form)
- Cancel button (switches back to Detail View)

Create View

State: view === 'create'

What the user sees:

Form Section:
- Dynamic form with all editable prompt fields
- Field labels with required indicators
- Help text/tooltips from field descriptions
- Input validation errors displayed inline
Action Buttons:
- Create button (submits form)
- Cancel button (switches back to List View)
Confirmation Dialogs:
- Delete confirmation dialog (on prompt detail page)

User Interactions and Functionality

Browsing and Discovery

Search Functionality:

User types in general search box
Frontend debounces input (300-500ms delay)
Search applies across all text fields in prompt objects
Results update automatically
Page resets to page 1 when search changes

Field Filtering:

User selects field to filter by
Frontend shows appropriate filter UI based on field type:
- Text fields → Text input with operator selection (contains, equals, startsWith, endsWith)
- Textarea fields → Text input filter
- Select fields → Dropdown with options from backend metadata
- Email fields → Email input filter
- Checkbox fields → Boolean toggle (true/false/any)
User applies filter → Filter appears as active chip/badge
User can remove individual filters
Multiple filters work together (AND logic)
Page resets to page 1 when filters change

Sorting:

User clicks column header
Sort direction toggles (asc → desc → remove)
Multiple columns can be sorted (multi-level sorting)
Sort indicators show on column headers
All filters and search preserved when sorting

Pagination:

User clicks page number or navigation button
Page updates and data refetches
All filters, search, and sort preserved
User changes page size → Page resets to 1, data refetches

View Switching:

User clicks prompt row/card → Switches to Detail View (set selectedPromptId and view state)
User clicks prompt name → Switches to Detail View (set selectedPromptId and view state)

Viewing Prompt Details

Information Display:

All prompt fields displayed using dynamic rendering
Read-only fields shown as formatted text
Editable fields shown with edit indicators
Special fields formatted appropriately (content as formatted text)

Action Availability:

Edit button shown if editable fields exist and user has permission
Delete button shown if user has permission

Creating Prompts

Form Interaction:

User clicks "Create Prompt" button → Switches to Create View (set view: 'create')
Form shows all editable fields
User fills in fields
Client-side validation shows errors immediately
User clicks Create → Form validates and submits
User clicks Cancel → Switches back to List View (set view: 'list', selectedPromptId: null)

Form Validation:

Required field validation (shows error if empty)
Type validation (e.g., textarea fields must be valid text)
Validation errors displayed inline below fields

Form Submission:

Prompt data sent as Prompt object
Success → Switch to Detail View for created prompt (set selectedPromptId to new prompt ID, view: 'detail')
Error handling:
- 403 (permission denied) → Show permission error
- 400 (validation errors) → Display backend validation errors
- Other errors → Show generic error message

Editing Prompts

Form Interaction:

User clicks "Edit" button → Switches to Edit View (set view: 'edit')
Form pre-populated with current prompt values
User modifies fields
Client-side validation shows errors immediately
User clicks Save → Form validates and submits
User clicks Cancel → Switches back to Detail View (set view: 'detail')

Form Validation:

Required field validation (shows error if empty)
Type validation (e.g., textarea fields must be valid text)
Validation errors displayed inline below fields

Form Submission:

Only changed fields sent (or all form data)
Success → Switch back to Detail View (set view: 'detail') and show success message
Error handling:
- 403 (permission denied) → Show permission error
- 400 (validation errors) → Display backend validation errors
- Other errors → Show generic error message

Starting Prompts

Start Prompt Action:

User clicks "Start Prompt" button in table row or detail page
Frontend fetches prompt data to get prompt content
Frontend navigates to /chat-playground page
Frontend pre-fills the chat input with the prompt's content
Frontend displays prompt name as context (optional)
User can optionally modify the prompt or add files before starting
User clicks "Start" or "Send" button in chat playground
Frontend calls POST /api/chat/playground/start with:
- workflowMode query parameter: "Dynamic" (default) or user-selected mode
- userInput body: {prompt: promptContent, listFileId: [...], userLanguage: "en"}

Start Prompt Submission:

Success → Workflow starts, chat playground updates with workflow data, messages/logs appear
Error handling:
- 403 (permission denied) → Show permission error
- 400 (validation errors) → Display backend validation errors
- Other errors → Show generic error message

Implementation Notes:

Action buttons (Start Prompt, Edit, Delete) are rendered in the table on first load
Buttons should be visible in each table row
Start Prompt button should be clearly distinguished (e.g., primary button style)
Navigation to chat playground should preserve prompt context

Deleting Prompts

Delete Action:

User clicks delete button (on detail page or list)
Confirmation dialog appears with prompt name
Warning about permanent deletion
User confirms → Prompt deleted
User cancels → Dialog closes, no action

Delete Success Handling:

Success message displayed
If in Detail View → Switch back to List View (set view: 'list', selectedPromptId: null)
If in List View → Remove prompt from list or refresh

Backend Routes and API Integration

Complete Route Reference

All backend routes used by prompt pages:

Route	Method	Purpose	When Used	Access Control
`/api/prompts/`	GET	Get all prompts (with pagination)	Initial page load, pagination changes, sort changes, filter changes, search changes	All authenticated users (filtered by mandate)
`/api/prompts/{promptId}`	GET	Get prompt details	Detail page load, edit page load	All authenticated users
`/api/prompts/{promptId}`	PUT	Update prompt	Edit form submission	All authenticated users
`/api/prompts/{promptId}`	DELETE	Delete prompt	User confirms deletion	All authenticated users
`/api/prompts`	POST	Create prompt	Create form submission	All authenticated users
`/api/attributes/Prompt`	GET	Get field definitions	Page load (once per page) - used to generate all UI components	All authenticated users
`/api/chat/playground/start`	POST	Start workflow with prompt	User clicks "Start Prompt" button	All authenticated users

API Request Patterns

Pagination Request:

GET /api/prompts/?pagination={"page":1,"pageSize":20,"sort":[],"filters":null}

pagination parameter is JSON-encoded string
If user wants all prompts: omit pagination parameter entirely
Filters structure: {"search":"query","fieldName":"value",...}
Optional mandateId query parameter to filter by mandate

Create Request:

POST /api/prompts
Content-Type: application/json
Body: {
  "name": "Invoice Processing",
  "content": "Process the following invoice..."
}

All Prompt model fields sent as Prompt object
Handle 403 (permission denied) and 400 (validation errors)

Update Request:

PUT /api/prompts/{promptId}
Content-Type: application/json
Body: {fieldName: value, ...}

Send only changed fields or all form data
Handle 403 (permission denied) and 400 (validation errors)

Start Prompt Request:

POST /api/chat/playground/start?workflowMode=Dynamic
Content-Type: application/json
Body: {
  "prompt": "Prompt content here...",
  "listFileId": ["file1", "file2"],
  "userLanguage": "en"
}

workflowMode query parameter is required: "Actionplan", "Dynamic", or "Template" (default: "Dynamic")
prompt field contains the prompt's content
listFileId is optional array of file IDs to attach
userLanguage should match user's preferred language
Handle 403 (permission denied) and 400 (validation errors)

Delete Requests:

DELETE /api/prompts/{promptId}

Delete operation requires user confirmation
Handle 403 (permission denied) and 404 (not found) gracefully

Response Handling

Paginated Response:

{
  "items": [...],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 45,
    "totalPages": 3,
    "sort": [...],
    "filters": {...}
  }
}

Error Responses:

403 Forbidden → Show permission error message
404 Not Found → Show "not found" error message
400 Bad Request → Display validation errors from response
500 Internal Server Error → Show generic error message

Field and Attribute Reference

Complete Field List

The following is a comprehensive list of all parameters, attributes, and fields that will be displayed for prompts. All of these are provided by the backend through the /api/attributes/Prompt endpoint and should never be hardcoded in the frontend.

Core Prompt Fields

Identification Fields:

id - Unique prompt identifier (text, readonly, not required, visible)
mandateId - ID of the mandate this prompt belongs to (text, readonly, not required, visible)

Content Fields:

name - Name of the prompt (text, editable, required, visible)
content - Content of the prompt (textarea, editable, required, visible)

Pagination Parameters

Request Parameters (PaginationParams):

page - Current page number (1-based, minimum 1)
pageSize - Number of items per page (minimum 1, maximum 1000)
sort - Array of sort field configurations
- Each sort field contains:
  - field - Field name to sort by (must match a prompt field name)
  - direction - Sort direction: "asc" or "desc"
filters - Filter criteria dictionary
- search - General search term (searches across all text fields, case-insensitive)
- Field-specific filters: {fieldName: value} or {fieldName: {operator: "operator", value: value}}
- Supported operators: "equals", "contains", "startsWith", "endsWith", "in", "notIn"

Response Metadata (PaginationMetadata):

currentPage - Current page number (1-based)
pageSize - Number of items per page
totalItems - Total number of items across all pages (after filters applied)
totalPages - Total number of pages (calculated from totalItems / pageSize)
sort - Current sort configuration applied (array of SortField objects)
filters - Current filters applied (mirrors request filters)

Attribute Definition Structure

Each field returned from /api/attributes/Prompt contains:

name - Field name (e.g., "name", "content", "id")
type - Field data type (e.g., "text", "textarea", "select", "checkbox")
label - Localized field label (object with language keys: {"en": "English Label", "fr": "French Label"})
description - Field description text
required - Boolean indicating if field is required
readonly - Boolean indicating if field is read-only
editable - Boolean indicating if field can be edited (inverse of readonly)
visible - Boolean indicating if field should be displayed in UI
options - Array of options for select fields (each option has value and localized label)

Dynamic Rendering Guidelines

The frontend must render all UI components dynamically based on backend metadata. No field definitions, labels, validation rules, or UI structure should be hardcoded.

Table Column Generation

When rendering the prompt list table:

Fetch attribute definitions from /api/attributes/Prompt
Filter attributes where visible: true to determine which columns to display
Use label property for column headers (select appropriate language based on user preference)
Use type property to determine how to format cell values:
- text fields → Display as plain text
- textarea fields → Display as truncated text with "..." or expandable preview
- select fields → Display value using label from options array (match value to option.value, then display option.label)
- checkbox fields → Display as checkmark icon or "Yes"/"No" text
Use readonly property to determine if column should be sortable (readonly fields may still be sortable, but editable fields definitely are)
Generate click handlers for column headers to update sort parameters and refetch data
Add Actions Column:
- Render action buttons in each table row on first load
- Include "Start Prompt" button (primary style) - navigates to /chat-playground with prompt content
- Include "Edit" button - switches to Edit View
- Include "Delete" button - shows confirmation dialog
- Buttons should be visible and accessible in each row

Filter Control Generation

When rendering filter controls:

Fetch attribute definitions from /api/attributes/Prompt
Filter attributes where visible: true to determine which filters to show
For each visible field, generate appropriate filter UI based on type:
- text fields → Text input filter (supports "contains", "equals", "startsWith", "endsWith" operators)
- textarea fields → Text input filter (supports "contains", "equals", "startsWith", "endsWith" operators)
- email fields → Email input filter
- select fields → Dropdown filter with options from options array (use localized labels)
- checkbox fields → Boolean toggle filter (true/false/any)
Use label property for filter labels (localized)
When user applies filter, update filters object in pagination parameters and refetch data
Display active filters as chips/badges showing field label and value
Allow removing individual filters by removing them from filters object

Search Implementation

For general search functionality:

Display a single search input box (not field-specific)
When user types, update filters.search in pagination parameters
Debounce search input (wait 300-500ms after user stops typing before sending request)
Search applies across all text fields in the prompt object
Reset to page 1 when search query changes
Combine search with field-specific filters (both are in the filters object)

Form Field Generation

When rendering edit forms:

Fetch attribute definitions from /api/attributes/Prompt
Filter attributes where visible: true AND editable: true to determine which fields to show
For each editable field, generate appropriate form input based on type:
- text fields → Text input
- textarea fields → Textarea input (with appropriate rows/height)
- email fields → Email input
- select fields → Dropdown/select input with options from options array (use localized labels)
- checkbox fields → Checkbox input
Use label property for field labels (localized)
Use required property to show required indicators (asterisk, etc.)
Use description property to show help text or tooltips
Validate form before submission:
- Check all required: true fields have values
- Validate types (e.g., textarea fields must be valid text)
- Validate select fields (value must be in options array)
On submit, send only changed fields or all form data to update endpoint

Create Form Field Generation

When rendering create forms:

Follow same pattern as edit forms for Prompt model fields
On submit, send Prompt object fields in request body

Display Formatting

When displaying field values:

Use type property to determine formatting:
- text → Display as-is (may need HTML escaping)
- textarea → Display as formatted text (preserve line breaks, may truncate with "Read more" link)
- select → Look up value in options array and display localized label
- checkbox → Display as checkmark icon or "Yes"/"No" text
Handle null or undefined values gracefully (show "-" or "Not set")
Use readonly property to determine if field should show edit indicators
For content field (textarea), consider:
- Truncating long content in list view with "Show more" link
- Showing full content in detail view
- Preserving formatting (line breaks, whitespace)

Localization

All labels and options support multiple languages:

Use user's preferred language (from user settings or browser locale)
Access localized labels from label object: label[userLanguage] or label.en as fallback
For select options, use option.label[userLanguage] or option.label.en as fallback
If label for current language is missing, fall back to English

Key Principles

Never hardcode field names, labels, types, or validation rules
Always fetch attribute definitions from backend before rendering UI
Use attribute metadata to determine what to display and how to display it
Support all field types dynamically - if backend adds new types, frontend should handle them
Respect visible, editable, readonly, and required flags from backend
Use localized labels from backend metadata
Generate filters, forms, and tables entirely from attribute definitions
When backend adds new fields, frontend should automatically display them without code changes
Handle all error cases gracefully (403, 404, 400, 500)
Provide user feedback for all actions (loading states, success messages, error messages)

Summary

This document provides complete frontend requirements for all prompt management pages and components. All requirements follow the principle of backend-driven UI generation—no hardcoding of field definitions, labels, or validation rules. The frontend should dynamically generate all UI components from backend metadata provided through the /api/attributes/Prompt endpoint.

Key Architecture Pattern: The prompt management interface is a single page (/prompts) with different views managed through component state. All interactions happen within the same page component without separate routes.

For generic patterns that apply across all entity types (not just prompts), see the Dynamic Forms and Pagination documentation.

22 KiB Raw Blame History

Prompt Page Requirements

Table of Contents

Overview

Page Structure and Layout

Prompt Management Page (/prompts)

List View

Detail View

Edit View

Create View

User Interactions and Functionality

Browsing and Discovery

Viewing Prompt Details

Creating Prompts

Editing Prompts

Starting Prompts

Deleting Prompts

Backend Routes and API Integration

Complete Route Reference

API Request Patterns

Response Handling

Field and Attribute Reference

Complete Field List

Core Prompt Fields

Pagination Parameters

Attribute Definition Structure

Dynamic Rendering Guidelines

Table Column Generation

Filter Control Generation

Search Implementation

Form Field Generation

Create Form Field Generation

Display Formatting

Localization

Key Principles

Summary

22 KiB

Raw Blame History

Prompt Management Page (`/prompts`)