# Legacy Reuse Evaluation

Date: 2026-07-06

## Conclusion

The existing project can provide useful engineering references, but it should not be directly extended as-is for the new requirement.

The old project is a **大本营答疑资产后台系统 MVP**. Its core flow is:

`Feishu session/transcript -> AI cleaning -> raw QA -> manual review -> standard QA -> manually marked callable QA`

The new project is an **AI 企业知识库问答系统**. Its core flow is:

`User login -> authorized knowledge bases -> real-time Feishu retrieval -> Prompt assembly -> model streaming answer -> chat/history/log persistence`

These two systems both touch "QA" and "Feishu", but their domain models, permissions, APIs, database tables, and user workflows are different. For long-term maintainability, V2 should use a new domain model and only reuse selected implementation patterns or small infrastructure pieces.

## New Requirement Snapshot

Source documents define the V2 target as:

- Feishu knowledge base is the only phase-one knowledge source.
- Phase one does not build an independent local knowledge base, does not manually sync content, and does not maintain a vector database sync.
- User login uses phone number + SMS verification code.
- Admin login uses username + password.
- AI chat supports sessions, history, streaming output, stop generation, Markdown rendering, auto title, and daily chat quota.
- AI can only answer from the user's authorized knowledge bases and retrieved snippets.
- No-hit answer must be: `当前知识库中未检索到相关内容，请联系管理员补充相关知识。`
- Feishu/model failures need unified fallback messages and logs.
- Admin backend includes dashboard, user management, admin management, knowledge base management, Prompt management, model management, chat records, system config, and operation logs.
- Core database tables include `sys_user`, `sys_admin`, `sys_role`, `sys_knowledge`, `sys_user_kb`, `sys_chat_session`, `sys_chat_message`, `sys_prompt`, `sys_model`, `sys_system_config`, `sys_ai_request_log`, and `sys_operation_log`.

## Existing Code Overview

The old project currently uses:

- Backend: FastAPI, SQLAlchemy, Pydantic, APScheduler, HTTPX.
- Frontend: Next.js, React, TypeScript, TailwindCSS.
- Database: PostgreSQL preferred, SQLite fallback.
- AI: OpenAI-compatible chat completions with mock fallback.
- Feishu: Bitable/document adapter with mock fallback.
- Existing H5 page: mobile-first chat surface connected to `/api/standard-qa/callable`.

The old database model centers on:

- `users`
- `feishu_sessions`
- `raw_qa_items`
- `standard_qa_items`
- `task_runs`
- `audit_logs`
- `system_settings`

## Reuse Assessment

| Area | Reuse Level | Recommendation |
| --- | --- | --- |
| FastAPI application skeleton | High | Reuse routing style, settings pattern, CORS setup, dependency injection, and service layering ideas. |
| SQLAlchemy/Pydantic conventions | Medium | Reuse coding style, but rebuild models for `sys_*` tables required by V2. |
| Next.js/Tailwind frontend setup | Medium | Reuse project setup and visual implementation experience; rebuild pages around V2 user/admin flows. |
| H5 chat UI interaction | Medium | Reuse mobile-first interaction ideas such as compact header, chat bubbles, input ergonomics, and local loading states. Replace old callable-QA matching with real `/chat/completions` SSE. |
| Feishu service adapter | Medium | Reuse token acquisition, HTTP wrapper, document text extraction ideas, and mock-mode pattern. V2 still needs a new Feishu knowledge retrieval service matching SpaceID/NodeID and real-time search. |
| AI API wrapper | Medium | Reuse OpenAI-compatible request pattern. V2 needs streaming, cancellation, Prompt assembly, token logging, and model config from database. |
| Operation/task logs | Low to Medium | Reuse audit/logging ideas. V2 needs `sys_operation_log` and `sys_ai_request_log`, not old QA audit semantics. |
| Scheduler/task runner | Low | V2 phase one says no manual sync or vector DB sync, so scheduled QA processing is not core. Keep only if later needed for maintenance jobs. |
| Old QA review domain | Low | Do not reuse as V2 core. Raw/standard QA review, risk/desensitization, and callable status are old-domain concepts. |
| Existing `/standard-qa/callable` H5 API | Low | Replace with V2 chat/session/history APIs. It can stay as old system behavior but should not drive V2. |
| Docker Compose | Medium | Reuse containerization pattern, but V2 should switch DB target to MySQL 8.x per documents or explicitly record a deviation if PostgreSQL remains. |

## Gap Analysis

Must build or redesign for V2:

- User SMS login, token/session invalidation, account expiry, and daily quota.
- Admin username/password login and role/permission control.
- Knowledge base management using `SpaceID` and `NodeID`.
- User-to-knowledge permission table with effective/expired dates.
- Chat session and message persistence.
- SSE streaming endpoint `POST /chat/completions`.
- Stop-generation endpoint `POST /chat/stop`.
- Prompt management and active Prompt loading.
- Model management with API URL/API key/model settings.
- System config for login expiry, daily chat count, AI timeout, Feishu retries, context length, source display, and disabled web search.
- Real-time Feishu retrieval with permission filtering.
- AI request log with prompt, retrieval knowledge IDs, token usage, latency, status, and error.
- Admin chat query/detail/export APIs.
- UAT/test coverage around permission isolation and no-hallucination fallback.

## Recommended Technical Direction

1. Keep `ai_knowledge_base_v2/` as the new context and planning workspace.
2. Create a new V2 application folder after architecture confirmation, rather than mutating old V1 files in place.
3. Keep backend modular from day one:
   - `auth`
   - `users`
   - `admins`
   - `knowledge`
   - `chat`
   - `rag`
   - `prompts`
   - `models`
   - `config`
   - `logs`
4. Keep services separated:
   - `SmsCodeService`
   - `TokenService`
   - `FeishuKnowledgeService`
   - `RagService`
   - `ModelClient`
   - `ChatService`
   - `AuditLogService`
5. Make mock providers explicit for local development:
   - mock SMS code
   - mock model response
   - mock Feishu retrieval
6. Do not store production model API keys in plain text unless a security decision is documented. Prefer environment secret references or encrypted storage.

## Risk Notes

- The new documents specify MySQL 8.x, while the existing project uses PostgreSQL/SQLite. This is a deployment and migration decision, not a small code change.
- The documents say "Feishu updates immediately effective" and "real-time retrieval"; this depends on actual Feishu APIs and tenant permissions. A technical spike should validate retrieval behavior early.
- Streaming and stop-generation affect backend request lifecycle, frontend rendering, and persistence semantics. This should be implemented as a first-class chat capability, not as an afterthought.
- Permissions are central to the product. Every chat retrieval path must filter knowledge bases before retrieval and log what was used.

## Immediate Next Steps

1. Confirm whether V2 should be implemented in this repository under a new app folder, or whether this repository should become the V2 repository.
2. Draft V2 architecture and module plan in `development_records/`.
3. Scaffold V2 backend with the `sys_*` domain model and auth boundary.
4. Scaffold V2 H5/user frontend around the documented chat APIs and SSE.
5. Add admin frontend pages according to the prototype document.
6. Keep old V1 code untouched until a deliberate migration or replacement decision is made.