690514:2019 204-rfa-approval-refactor #01

2026-05-14 20:19:21 +07:00
parent 07cc6d47b1
commit 0240d80da5
183 changed files with 20050 additions and 1017 deletions
@@ -0,0 +1,72 @@
+# Implementation Plan: Unified AI Architecture
+
+**Branch**: `301-unified-ai-arch` | **Date**: 2026-05-14 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `specs/300-others/301-unified-ai-arch/spec.md`
+
+## Summary
+
+Implement a Master AI Architecture enforcing strict physical isolation of AI workloads on a dedicated Admin Desktop (Desk-5439). The system supports secure legacy document migration via a staging queue, context-aware conversational RAG queries, and detailed AI audit logging, all orchestrated through robust backend queues (BullMQ) and multi-tenant security filters.
+
+## Technical Context
+
+**Language/Version**: TypeScript (Node.js v24.15.0) for Backend/Frontend
+**Primary Dependencies**: NestJS 11, Next.js 16, BullMQ, Qdrant Node Client, n8n
+**Storage**: MariaDB 11.8 (Relational), Qdrant (Vector), Redis (Queue/Cache)
+**Testing**: Jest (Backend), Vitest (Frontend), E2E with Playwright
+**Target Platform**: QNAP Container Station (Production), Desk-5439 (AI Host)
+**Project Type**: Monorepo Web Application (Backend + Frontend)
+**Performance Goals**: RAG Response < 10s (p95), Migration throughput 1000 pages/hour
+**Constraints**: AI host has limited VRAM (8GB), necessitating concurrency limit of 1 for LLM generation. 
+**Scale/Scope**: 20,000+ legacy documents, project-wide deployment.
+
+## Constitution Check
+
+_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design._
+
+- **ADR-019 UUID**: `publicId` used exclusively. No INT primary keys exposed.
+- **ADR-009 Database**: Schema changes via raw SQL deltas.
+- **ADR-016 Security**: CASL RBAC strictly enforced (`@UseGuards(CaslAbilityGuard)`). Idempotency-Key headers required.
+- **ADR-008 BullMQ**: Heavy AI orchestration and RAG queuing managed via BullMQ.
+- **ADR-018/023 AI Boundary**: AI host connects via DMS API. No direct database access.
+- **TypeScript Strict**: Explicit types, no `any`, proper error handling via `BusinessException`.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/300-others/301-unified-ai-arch/
+├── spec.md
+├── plan.md              # This file
+├── research.md          
+├── data-model.md        
+├── quickstart.md        
+├── contracts/           
+└── tasks.md             # (To be created)
+```
+
+### Source Code (repository root)
+
+```text
+backend/
+├── src/
+│   ├── ai/
+│   │   ├── ai.module.ts
+│   │   ├── ai.controller.ts
+│   │   ├── ai.service.ts
+│   │   ├── qdrant.service.ts
+│   │   ├── rag.processor.ts
+│   │   └── dto/
+│   └── database/
+│       └── sql/
+
+frontend/
+├── src/
+│   ├── app/(dashboard)/ai-staging/
+│   ├── components/ai/
+│   │   ├── AiStatusBanner.tsx
+│   │   └── RagChatWidget.tsx
+│   └── lib/api/ai.ts
+```
+
+**Structure Decision**: Integrated into the existing Next.js / NestJS monorepo architecture, utilizing a dedicated `AiModule` in the backend to centralize all external AI API calls and queue management.