10 KiB
10 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 10-agent-capabilities | 03 | execute | 2 |
|
|
false |
|
|
Purpose: Completes CAP-03 by providing the user-facing interface for document management. Operators need to see what's in their KB, upload new content, and monitor ingestion status.
Output: Fully functional /knowledge-base portal page with file upload, URL/YouTube ingestion, document list with status polling, delete, and re-index.
<execution_context> @/home/adelorenzo/.claude/get-shit-done/workflows/execute-plan.md @/home/adelorenzo/.claude/get-shit-done/templates/summary.md </execution_context>
@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/phases/10-agent-capabilities/10-CONTEXT.md @.planning/phases/10-agent-capabilities/10-01-SUMMARY.md POST /api/portal/kb/{tenant_id}/documents — multipart file upload, returns 201 {id, filename, status} POST /api/portal/kb/{tenant_id}/documents/url — JSON {url, source_type}, returns 201 {id, source_url, status} GET /api/portal/kb/{tenant_id}/documents — returns [{id, filename, source_url, content_type, status, error_message, chunk_count, created_at}] DELETE /api/portal/kb/{tenant_id}/documents/{document_id} — returns 204 POST /api/portal/kb/{tenant_id}/documents/{document_id}/reindex — returns 200- TanStack Query for data fetching (useQuery, useMutation)
- shadcn/ui components (Button, Dialog, Badge, Table, etc.)
- Tailwind CSS for styling
- next-intl useTranslations() for i18n
- RBAC: session.user.role determines admin vs operator capabilities
2. **KB page** (`packages/portal/app/(dashboard)/knowledge-base/page.tsx`):
- Server Component wrapper that renders the client KB content
- Page title: "Knowledge Base" with subtitle showing tenant context
- Two action buttons for admins: "Upload Files" (opens upload dialog), "Add URL" (opens URL dialog)
- Document list component below actions
- Use tenant_id from session/route context (same pattern as other dashboard pages)
3. **Document list** (`packages/portal/components/kb/document-list.tsx`):
- Client component using useQuery to fetch GET /api/portal/kb/{tenant_id}/documents
- Poll every 5 seconds while any document has status='processing' (refetchInterval: 5000 conditional)
- Table with columns: Name (filename or source_url), Type (file/url/youtube), Status (badge), Chunks, Date, Actions
- Status badges: "Processing" (amber/spinning), "Ready" (green), "Error" (red with tooltip showing error_message)
- Actions per row (admin only): Delete button, Re-index button
- Empty state: "No documents in knowledge base yet. Upload files or add URLs to get started."
- Delete: useMutation calling DELETE endpoint, invalidate query on success, confirm dialog before delete
- Re-index: useMutation calling POST reindex endpoint, invalidate query on success
4. **Upload dialog** (`packages/portal/components/kb/upload-dialog.tsx`):
- shadcn/ui Dialog component
- Drag-and-drop zone (onDragOver, onDrop handlers) with visual feedback
- File picker button (input type="file" with accept for supported extensions: .pdf,.docx,.pptx,.xlsx,.csv,.txt,.md)
- Support multiple file selection
- Show selected files list before upload
- Upload button: for each file, POST FormData to /api/portal/kb/{tenant_id}/documents
- Show upload progress (file-by-file)
- Close dialog and invalidate document list query on success
- Error handling: show toast on failure
5. **URL ingest dialog** (`packages/portal/components/kb/url-ingest-dialog.tsx`):
- shadcn/ui Dialog component
- Input field for URL
- Radio or select for source type: "Web Page" or "YouTube Video"
- Auto-detect: if URL contains youtube.com or youtu.be, default to YouTube
- Submit: POST to /api/portal/kb/{tenant_id}/documents/url
- Close dialog and invalidate document list query on success
6. **API client updates** (`packages/portal/lib/api.ts`):
- Add KB API functions: fetchKbDocuments, uploadKbDocument, addKbUrl, deleteKbDocument, reindexKbDocument
- Use the same fetch wrapper pattern as existing API calls
7. **i18n**: Add English, Spanish, and Portuguese translations for KB page strings (following existing i18n pattern with next-intl message files). Add keys like: kb.title, kb.upload, kb.addUrl, kb.empty, kb.status.processing, kb.status.ready, kb.status.error, kb.delete.confirm, etc.
Steps:
1. Navigate to the portal and confirm "Knowledge Base" appears in the sidebar navigation
2. Click Knowledge Base — verify the page loads with empty state message
3. Click "Upload Files" — verify drag-and-drop zone and file picker appear
4. Upload a small PDF or TXT file — verify it appears in the document list with "Processing" status
5. Wait for processing to complete — verify status changes to "Ready" with chunk count
6. Click "Add URL" — verify URL input dialog with web/YouTube type selector
7. Add a URL — verify it appears in the list and processes
8. Click delete on a document — verify confirmation dialog, then document removed
9. If logged in as customer_operator — verify upload/delete buttons are hidden but document list is visible
<success_criteria>
- Knowledge Base page accessible in portal navigation
- File upload works with drag-and-drop and file picker
- URL and YouTube ingestion works
- Document list shows live processing status with polling
- Delete and re-index work
- RBAC enforced (admin: full access, operator: view only)
- All three languages have KB translations
- Human verification approved </success_criteria>