Developer
0a9588abb7
- Add pagination support to findAll (page, limit query params) - Add findByTemplateId method to service - Add GET /by-template/:templateId endpoint to controller - Service already includes CRUD for QuestionBank and QuestionBankItem
118 lines
6.8 KiB
Markdown
118 lines
6.8 KiB
Markdown
# Implementation Plan - AuraK External API Service (v2.0)
|
|
|
|
Provide an API service for external systems to access the KnowledgeBase functionalities, including chat, search, and document management.
|
|
|
|
## User Review Required
|
|
|
|
> [!IMPORTANT]
|
|
> **Multi-Tenancy & Resource Sharing**:
|
|
> - **Tenant Entity**: We will introduce a `Tenant` (Organization) entity.
|
|
> - **Resource Scoping**: `User`, `KnowledgeBase`, `KnowledgeGroup`, `SearchHistory`, `Note`, and `ImportTask` will be scoped by `tenantId`.
|
|
> - **Configuration Hierarchy**:
|
|
> - **ModelConfig**: Inherited hierarchy: `System Models (Global)` -> `Tenant Models (Shared in Org)` -> `User Models (Private)`.
|
|
> - **TenantSettings**: New entity to define organization-wide defaults (Language, Default Models, Search thresholds). `UserSetting` can still override these for personalization.
|
|
> - **Data Migration**: Existing data will be migrated to a "Default Tenant" during the first run.
|
|
> - **Elasticsearch Isolation**: The `tenantId` field will be added to the ES mapping and enforced in all search/delete queries.
|
|
> - **Storage Partitioning**: Uploaded files will be stored in `uploads/{tenantId}/{fileId}` to isolate files at the filesystem level.
|
|
> - **API Key**: Tied to `User`, and all operations will be automatically scoped to the user's and tenant's data range.
|
|
|
|
> [!IMPORTANT]
|
|
> **RBAC & Interface Separation**:
|
|
> - **Roles**:
|
|
> - `SUPER_ADMIN`: Manage Tenants and global system settings.
|
|
> - `TENANT_ADMIN`: Manage Users and Knowledge Bases within their Tenant.
|
|
> - `USER`: Access Chat, Search, and Knowledge Base within their Tenant.
|
|
> - **API Separation**: Administrative endpoints will be separated into `/api/v1/super-admin/*` and `/api/v1/admin/*`.
|
|
> - **UI Separation**: Recommend separating the "Admin Portal" from the "User Workspace" to ensure a cleaner user experience and better security boundaries.
|
|
|
|
> [!IMPORTANT]
|
|
> **Frontend Modernization & Boundary Separation (Google Workspace Style)**:
|
|
> - **Design Aesthetic**: Adopt a clean, modern, and professional style inspired by Google Workspace (Gmail, Drive, Gemini), following Material Design 3 specifications.
|
|
> - **Frontend Boundary Separation**:
|
|
> - **User Workspace**: Focused purely on end-user tools (Chat, Notebooks, Personal Settings).
|
|
> - **Admin Dashboard**: Dedicated area for management (Knowledge Base files, System/Tenant Settings, Global Models).
|
|
> - **Implementation**: We will introduce `react-router-dom` to provide clear URL boundaries (e.g., `/` for workspace and `/admin` for management) OR use a strict state-based layout split (`WorkspaceLayout` vs `AdminLayout`) with an app switcher.
|
|
> - **Core Elements**:
|
|
> - **Sleek Navigation Rail**: A minimal, collapsible sidebar with rounded active states, scoped to the current boundary (Admin vs Workspace).
|
|
> - **Top Global Search**: A prominent, rounded search bar for quick access.
|
|
> - **Airy Layout**: Increased white space and soft shadows to improve readability.
|
|
> - **Gemini-like Chat**: A modern AI chat interface with clean message bubbles and a refined input area.
|
|
> - **Mockup**:
|
|
> 
|
|
|
|
## Proposed Changes
|
|
|
|
### [Component] Database Schema
|
|
#### [NEW] [tenant.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/tenant/tenant.entity.ts)
|
|
- Define `Tenant` entity with `id` and `name`.
|
|
|
|
#### [MODIFY] [user.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/user/user.entity.ts)
|
|
- Add `tenantId` column (ManyToOne relationship with `Tenant`).
|
|
- Add `role` column (Enum: `SUPER_ADMIN`, `TENANT_ADMIN`, `USER`).
|
|
- Add `apiKey` column for API authentication.
|
|
|
|
#### [NEW] [tenant-setting.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/tenant/tenant-setting.entity.ts)
|
|
- Store organization-wide defaults (similar fields to `UserSetting`).
|
|
|
|
#### [MODIFY] [model-config.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/model-config/model-config.entity.ts)
|
|
- Add `tenantId` column (nullable for global models).
|
|
- Update lookup logic to include system-level and tenant-level models.
|
|
|
|
#### [MODIFY] [knowledge-base.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/knowledge-base/knowledge-base.entity.ts)
|
|
- Add `tenantId` column.
|
|
|
|
#### [MODIFY] [knowledge-group.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/knowledge-group/knowledge-group.entity.ts)
|
|
- Add `tenantId` column.
|
|
|
|
#### [MODIFY] [search-history.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/search-history/search-history.entity.ts)
|
|
- Add `tenantId` column.
|
|
|
|
#### [MODIFY] [note.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/note/note.entity.ts)
|
|
- Add `tenantId` column.
|
|
|
|
### [Component] Infrastructure & Storage
|
|
#### [MODIFY] [elasticsearch.service.ts](file:///d:/tmp/KnowledgeBase/server/src/elasticsearch/elasticsearch.service.ts)
|
|
- Update `createIndex` mapping to include `tenantId` as a `keyword` field.
|
|
- Modify `searchSimilar`, `searchFullText`, and `hybridSearch` to include `term: { tenantId }` filter.
|
|
|
|
#### [MODIFY] [knowledge-base.service.ts](file:///d:/tmp/KnowledgeBase/server/src/knowledge-base/knowledge-base.service.ts)
|
|
- Update file storage logic to use `uploads/{tenantId}/{fileId}` path.
|
|
|
|
#### [NEW] [migrations]
|
|
- Create a migration script to:
|
|
1. Create the `Tenant` table.
|
|
2. Create a "Default" tenant.
|
|
3. Update all existing records to link to the "Default" tenant.
|
|
|
|
### [Component] User & Auth
|
|
#### [NEW] [super-admin.guard.ts](file:///d:/tmp/KnowledgeBase/server/src/auth/super-admin.guard.ts)
|
|
- Guard that checks for `SUPER_ADMIN` role.
|
|
|
|
#### [NEW] [tenant-admin.guard.ts](file:///d:/tmp/KnowledgeBase/server/src/auth/tenant-admin.guard.ts)
|
|
- Guard that checks for `TENANT_ADMIN` role or higher within the same tenant.
|
|
|
|
### [Component] Frontend Separation
|
|
#### [MODIFY] [App.tsx](file:///d:/workspace/AuraK/web/App.tsx)
|
|
- Introduce a clear layout abstraction: `WorkspaceLayout` and `AdminLayout`.
|
|
- Add an "App Switcher" for Admin users to toggle between User Workspace and Admin Dashboard.
|
|
|
|
#### [NEW] [WorkspaceLayout.tsx](file:///d:/workspace/AuraK/web/components/layouts/WorkspaceLayout.tsx)
|
|
- Contains a customized `WorkspaceSidebarRail` showing only user-centric views (`chat`, `notebooks`).
|
|
|
|
#### [NEW] [AdminLayout.tsx](file:///d:/workspace/AuraK/web/components/layouts/AdminLayout.tsx)
|
|
- Contains an `AdminSidebarRail` showing management views (`knowledge`, `settings`).
|
|
|
|
---
|
|
|
|
## Verification Plan
|
|
|
|
### Automated Tests
|
|
- `curl -X GET http://localhost:3001/api/v1/knowledge-bases -H "x-api-key: YOUR_KEY"`
|
|
- `curl -X POST http://localhost:3001/api/v1/chat -H "x-api-key: YOUR_KEY" -d '{"message": "Hello"}'`
|
|
|
|
### Manual Verification
|
|
1. **Retrieve API Key**: Login to the system, then call `/api/user/api-key` to get the key.
|
|
2. **Test External Request**: Use the retrieved key to call the new `/api/v1/*` endpoints.
|
|
3. **Check Swagger**: Visit `http://localhost:3001/api/docs`.
|
|
4. **Verify Streaming**: Ensure `POST /api/v1/chat` with `stream: true` returns SSE chunks.
|