leaudit-platform-backend/docs/superpowers/plans/2026-05-25-chat-temporary-rag-attachments.md

Chat Temporary RAG Attachments Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build conversation-scoped temporary RAG attachments for chat with 7-day TTL, parser/OCR indexing, strict tenant/user/conversation isolation, and dual retrieval with the existing formal knowledge base.

Architecture: Add a focused RagChatAttachmentServiceImpl responsible for attachment lifecycle, parsing, chunking, indexing, retrieval, validation, and cleanup. Extend RagChatServiceImpl so a chat message can include an AttachmentId, retrieve attachment facts first, then formal KB legal context, and generate one answer with source-aware chunks. Add frontend upload/poll/status plumbing inside the existing chat input path without touching unrelated dirty frontend files.

Tech Stack: FastAPI, SQLAlchemy text queries, Chroma, existing RagRetriever, existing OSS client, existing LeAudit OCR bridge, React/Next.js, Ant Design upload controls.

---

Task 1: Backend Attachment Contract And Unit Tests

Files:

• Create: tests/test_rag_chat_attachment_service.py

• Create: fastapi_modules/fastapi_leaudit/domian/vo/ragChatAttachmentVo.py

• Modify: fastapi_modules/fastapi_leaudit/domian/Dto/ragChatDto.py

• Write tests for TTL, collection naming, scope matching, and chunk metadata.

• Run: pytest tests/test_rag_chat_attachment_service.py -q; expected failures mention missing RagChatAttachmentServiceImpl.

• Add attachment DTO and VO classes.

• Re-run the same test and keep remaining failures focused on missing service implementation.

Task 2: Backend Attachment Service

Files:

• Create: fastapi_modules/fastapi_leaudit/services/ragChatAttachmentService.py

• Create: fastapi_modules/fastapi_leaudit/services/impl/ragChatAttachmentServiceImpl.py

• Create: scripts/创建sql/schema_add_rag_chat_attachments.sql

• Implement schema creation for rag_chat_attachment.

• Implement BuildCollectionName, BuildChunks, CreateAttachment, GetAttachment, ValidateAttachmentForChat, RetrieveAttachmentContext, DeleteAttachment, and CleanupExpiredAttachments.

• Implement parsers for txt/md/json/csv/docx/pdf/xlsx/images.

• Implement async indexing with status transitions and best-effort cleanup.

• Run: pytest tests/test_rag_chat_attachment_service.py -q; expected pass.

Task 3: Chat Message Dual Retrieval

Files:

• Modify: fastapi_modules/fastapi_leaudit/services/ragChatService.py

• Modify: fastapi_modules/fastapi_leaudit/services/impl/ragChatServiceImpl.py

• Modify: fastapi_modules/fastapi_leaudit/rag_engine/generator.py

• Modify: tests/test_rag_chat_streaming_sources.py

• Add AttachmentId to chat service and DTO call path.

• Add tests proving _run_message_task merges attachment chunks and formal KB chunks with distinct source scopes.

• Run targeted test and confirm red.

• Implement retrieval merge and grounded legal query construction.

• Update generator prompt to group uploaded file facts separately from formal KB basis.

• Run targeted tests and confirm green.

Task 4: Backend Controller Routes

Files:

• Modify: fastapi_modules/fastapi_leaudit/controllers/ragChatController.py

• Add POST /chat/attachments, GET /chat/attachments/{AttachmentId}, and DELETE /chat/attachments/{AttachmentId}.

• Extend message send route to pass Body.attachmentId.

• Reuse rag:chat:use permission and existing tenant context.

• Run backend attachment and chat streaming tests.

Task 5: Frontend Upload And Send Plumbing

Files:

• Create: legal-platform-frontend/app/api/chat-attachments/route.ts

• Create: legal-platform-frontend/app/api/chat-attachments/[attachmentId]/route.ts

• Create: legal-platform-frontend/lib/api/legacy/dify-chat/attachment.ts

• Modify: legal-platform-frontend/lib/api/legacy/dify-chat/types.ts

• Modify: legal-platform-frontend/lib/api/legacy/dify-chat/client.ts

• Modify: legal-platform-frontend/app/api/chat-messages/route.ts

• Modify: legal-platform-frontend/hooks/use-chat-message.ts

• Modify: legal-platform-frontend/components/dify-chat/index.tsx

• Modify: legal-platform-frontend/components/dify-chat/chat-input.tsx

• Add frontend attachment API client and Next route proxies.

• Update chat input to allow one file, upload immediately, poll status, show completed/error/removable state, and block send while indexing.

• Pass attachmentId through Chat -> useChatMessage -> /api/chat-messages -> FastAPI.

• Keep upload scoped to current conversation id; for new chats, create/send with conversation after backend returns id or require existing conversation before attachment.

Task 6: Verification

Files:

• All touched files

• Run: pytest tests/test_rag_chat_attachment_service.py tests/test_rag_chat_streaming_sources.py -q.

• Run frontend type/test command if available and scoped enough.

• Check git status --short at root and frontend subrepo.

• Report changed files, verification output, and any known gaps.