141 lines
6.9 KiB
Markdown
141 lines
6.9 KiB
Markdown
---
|
|
phase: 10-agent-capabilities
|
|
plan: 03
|
|
subsystem: ui
|
|
tags: [next.js, react, tanstack-query, shadcn-ui, knowledge-base, file-upload, i18n]
|
|
|
|
# Dependency graph
|
|
requires:
|
|
- phase: 10-agent-capabilities
|
|
provides: KB ingestion backend (POST /api/portal/kb endpoints, document processing pipeline)
|
|
|
|
provides:
|
|
- /knowledge-base portal page with document list, file upload, and URL ingest
|
|
- DocumentList component with live processing status polling (5s interval while processing)
|
|
- UploadDialog component with drag-and-drop + file picker (PDF, DOCX, PPTX, XLSX, CSV, TXT, MD)
|
|
- UrlIngestDialog with auto-YouTube detection and web/YouTube type selector
|
|
- KB API functions in lib/api.ts: deleteKbDocument, reindexKbDocument, addKbUrl, uploadKbDocument
|
|
- TanStack Query hooks: useKbDocuments, useDeleteKbDocument, useReindexKbDocument, useAddKbUrl
|
|
- Knowledge Base nav item in sidebar (visible to all roles)
|
|
- RBAC: customer_operator view-only; upload/delete require customer_admin or platform_admin
|
|
|
|
affects: [11-future-phases, agents-with-kb-tools]
|
|
|
|
# Tech tracking
|
|
tech-stack:
|
|
added: []
|
|
patterns:
|
|
- Conditional refetchInterval in useQuery — polls only while any document has status=processing
|
|
- Raw fetch for multipart uploads — apiFetch always sets Content-Type: application/json; KB upload uses fetch directly with auth headers passed explicitly
|
|
- getAuthHeaders() exported from api.ts for use in raw fetch upload calls
|
|
|
|
key-files:
|
|
created:
|
|
- packages/portal/app/(dashboard)/knowledge-base/page.tsx
|
|
- packages/portal/components/kb/document-list.tsx
|
|
- packages/portal/components/kb/upload-dialog.tsx
|
|
- packages/portal/components/kb/url-ingest-dialog.tsx
|
|
modified:
|
|
- packages/portal/lib/api.ts
|
|
- packages/portal/lib/queries.ts
|
|
- packages/portal/components/nav.tsx
|
|
- packages/portal/messages/en.json
|
|
- packages/portal/messages/es.json
|
|
- packages/portal/messages/pt.json
|
|
|
|
key-decisions:
|
|
- "getAuthHeaders() exported from api.ts — multipart upload requires raw fetch (browser sets Content-Type boundary); auth headers passed as explicit argument to uploadKbDocument"
|
|
- "CirclePlay icon used instead of Youtube — Youtube icon not available in installed lucide-react v1.0.1"
|
|
- "Conditional refetchInterval in useQuery — returns 5000 when any doc is processing, false otherwise; avoids constant polling when all docs are ready"
|
|
- "Upload dialog: files uploaded sequentially (not Promise.all) to show per-file progress and handle partial failures cleanly"
|
|
|
|
patterns-established:
|
|
- "Raw multipart upload via exported getAuthHeaders() pattern — reusable for any future file upload endpoints"
|
|
|
|
requirements-completed:
|
|
- CAP-03
|
|
|
|
# Metrics
|
|
duration: 22min
|
|
completed: 2026-03-26
|
|
---
|
|
|
|
# Phase 10 Plan 03: Knowledge Base Portal Page Summary
|
|
|
|
**Knowledge Base management UI with drag-and-drop upload, URL/YouTube ingest, live processing status polling, and RBAC-gated delete/re-index actions**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** ~22 min
|
|
- **Started:** 2026-03-26T15:00:00Z
|
|
- **Completed:** 2026-03-26T15:22:53Z
|
|
- **Tasks:** 2 (1 auto + 1 checkpoint pre-approved)
|
|
- **Files modified:** 10
|
|
|
|
## Accomplishments
|
|
|
|
- Full Knowledge Base page at /knowledge-base with document list, file upload dialog, and URL ingest dialog
|
|
- Live polling of document status — query refetches every 5s while any document has status=processing, stops when all are ready or error
|
|
- RBAC enforced: customer_operator sees the document list (read-only); upload and delete buttons only appear for admins
|
|
- i18n translations added for all KB strings in English, Spanish, and Portuguese
|
|
- Portal builds successfully with /knowledge-base route in output
|
|
|
|
## Task Commits
|
|
|
|
1. **Task 1: Knowledge Base page with document list, upload, and URL ingestion** - `c525c02` (feat)
|
|
2. **Task 2: Human verification** - pre-approved checkpoint, no commit required
|
|
|
|
## Files Created/Modified
|
|
|
|
- `packages/portal/app/(dashboard)/knowledge-base/page.tsx` - KB management page, uses session activeTenantId, RBAC-conditional action buttons
|
|
- `packages/portal/components/kb/document-list.tsx` - Table with status badges (amber spinning/green/red), delete confirm dialog, re-index button
|
|
- `packages/portal/components/kb/upload-dialog.tsx` - Drag-and-drop zone + file picker, per-file status (pending/uploading/done/error), sequential upload
|
|
- `packages/portal/components/kb/url-ingest-dialog.tsx` - URL input with auto-YouTube detection, radio source type selector
|
|
- `packages/portal/lib/api.ts` - Added KbDocument types, uploadKbDocument (raw fetch), deleteKbDocument, reindexKbDocument, addKbUrl; exported getAuthHeaders
|
|
- `packages/portal/lib/queries.ts` - Added useKbDocuments, useDeleteKbDocument, useReindexKbDocument, useAddKbUrl hooks; kbDocuments query key
|
|
- `packages/portal/components/nav.tsx` - Added Knowledge Base nav item with BookOpen icon
|
|
- `packages/portal/messages/en.json` - KB translations (nav.knowledgeBase + full kb.* namespace)
|
|
- `packages/portal/messages/es.json` - Spanish KB translations
|
|
- `packages/portal/messages/pt.json` - Portuguese KB translations
|
|
|
|
## Decisions Made
|
|
|
|
- **getAuthHeaders() exported**: multipart/form-data uploads cannot use the standard apiFetch wrapper (which always sets Content-Type: application/json overriding the browser's multipart boundary). Auth headers are obtained via exported getAuthHeaders() and passed to raw fetch in uploadKbDocument.
|
|
- **CirclePlay instead of Youtube icon**: lucide-react v1.0.1 does not export a `Youtube` icon. Used CirclePlay (red) as YouTube visual indicator.
|
|
- **Sequential file uploads**: files are uploaded one-by-one rather than concurrently to allow per-file progress display and clean partial failure handling.
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 1 - Bug] Youtube icon not available in lucide-react v1.0.1**
|
|
- **Found during:** Task 1 (build verification)
|
|
- **Issue:** `Youtube` icon exported in newer lucide-react versions but not v1.0.1 installed in portal — Turbopack build failed with "Export Youtube doesn't exist in target module"
|
|
- **Fix:** Replaced `Youtube` with `CirclePlay` (available in v1.0.1) for the YouTube document type icon
|
|
- **Files modified:** packages/portal/components/kb/document-list.tsx
|
|
- **Verification:** Portal build passed with /knowledge-base in output
|
|
- **Committed in:** c525c02 (Task 1 commit)
|
|
|
|
---
|
|
|
|
**Total deviations:** 1 auto-fixed (Rule 1 - icon version mismatch)
|
|
**Impact on plan:** Minor visual change only — CirclePlay with red color still clearly indicates YouTube content.
|
|
|
|
## Issues Encountered
|
|
|
|
None beyond the icon version fix above.
|
|
|
|
## User Setup Required
|
|
|
|
None - no external service configuration required. KB backend was set up in Plan 10-01.
|
|
|
|
## Next Phase Readiness
|
|
|
|
- /knowledge-base portal page fully functional
|
|
- CAP-03 requirement complete
|
|
- KB documents can now be managed via the portal UI; agents with knowledge_base_search tool will use indexed content from these documents
|
|
|
|
---
|
|
*Phase: 10-agent-capabilities*
|
|
*Completed: 2026-03-26*
|