Document V2 plan in Chinese

ai_knowledge_base_v2/reports/legacy_reuse_evaluation.md

@@ -1,48 +1,48 @@
-# Legacy Reuse Evaluation
+# 旧代码复用评估报告
 
-Date: 2026-07-06
+日期：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:
+旧项目是 **大本营答疑资产后台系统 MVP**，核心流程是：
 
-`Feishu session/transcript -> AI cleaning -> raw QA -> manual review -> standard QA -> manually marked callable QA`
+`飞书场次/转写稿 -> AI 清洗 -> 原始问答 -> 人工审核 -> 标准问答 -> 人工标记可调用`
 
-The new project is an **AI 企业知识库问答系统**. Its core flow is:
+新项目是 **AI 企业知识库问答系统**，核心流程是：
 
-`User login -> authorized knowledge bases -> real-time Feishu retrieval -> Prompt assembly -> model streaming answer -> chat/history/log persistence`
+`用户登录 -> 获取授权知识库 -> 实时检索飞书知识库 -> 组装 Prompt -> 大模型流式回答 -> 保存聊天、引用和日志`
 
-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.
+两个系统都涉及“问答”和“飞书”，但领域模型、权限逻辑、接口、数据库表和用户流程都不一样。为了后期维护和交接，V2 应该重新建立自己的领域模型，只选择性复用旧项目里的工程模式、小工具或局部服务代码。
 
-## New Requirement Snapshot
+## 新需求概要
 
-Source documents define the V2 target as:
+根据这次上传的需求资料，V2 的目标包括：
 
-- 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`.
+- 飞书知识库是一阶段唯一知识来源。
+- 一期不建立独立本地知识库，不做人工同步，不做向量数据库同步。
+- 用户端使用手机号 + 短信验证码登录。
+- 管理后台使用用户名 + 密码登录。
+- AI 聊天支持多会话、历史聊天、流式输出、停止生成、Markdown 渲染、自动标题和每日聊天额度。
+- AI 只能基于用户有权限访问的知识库和检索片段回答。
+- 没有命中知识时，统一回答：`当前知识库中未检索到相关内容，请联系管理员补充相关知识。`
+- 飞书或模型异常时，需要统一提示并记录日志。
+- 后台包含首页统计、用户管理、管理员管理、知识库管理、Prompt 管理、模型管理、聊天记录、系统配置和操作日志。
+- 核心表包括 `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`、`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`.
+- 后端：FastAPI、SQLAlchemy、Pydantic、APScheduler、HTTPX。
+- 前端：Next.js、React、TypeScript、TailwindCSS。
+- 数据库：优先 PostgreSQL，未配置时使用 SQLite。
+- AI：OpenAI 兼容 Chat Completions，支持 mock。
+- 飞书：已有多维表格和文档读取适配器，支持 mock。
+- H5：已有手机优先的聊天界面，但目前连接的是 `/api/standard-qa/callable`。
 
-The old database model centers on:
+旧项目核心数据模型：
 
 - `users`
 - `feishu_sessions`
@@ -52,46 +52,46 @@ The old database model centers on:
 - `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. |
+| FastAPI 应用骨架 | 高 | 可参考路由拆分、配置读取、CORS、依赖注入和 service 分层方式。 |
+| SQLAlchemy / Pydantic 写法 | 中 | 可参考编码风格，但模型需要按 V2 的 `sys_*` 表重建。 |
+| Next.js / Tailwind 前端工程 | 中 | 可参考工程搭建方式和页面实现经验，但页面要按 V2 用户端和后台流程重建。 |
+| H5 聊天交互 | 中 | 可复用手机优先、聊天气泡、输入框、加载状态等交互思路；需要替换为真实会话接口和 SSE 流式问答。 |
+| 飞书服务适配 | 中 | 可参考 token 获取、HTTP 封装、文档文本提取和 mock 模式；V2 仍需新增基于 SpaceID/NodeID 的实时知识库检索服务。 |
+| AI 调用封装 | 中 | 可参考 OpenAI 兼容请求方式；V2 需要新增流式输出、停止生成、Prompt 组装、Token 记录和从数据库读取模型配置。 |
+| 日志/审计思路 | 低到中 | 可参考日志意识；V2 需要实现 `sys_operation_log` 和 `sys_ai_request_log`，不能直接沿用旧审核日志语义。 |
+| 定时任务 | 低 | V2 一期不做同步任务和向量库同步，定时任务不是核心。后续如有维护任务再引入。 |
+| 旧问答审核领域 | 低 | 不建议作为 V2 核心。原始问答、标准问答、风险、脱敏、可调用状态属于旧系统领域。 |
+| `/standard-qa/callable` 接口 | 低 | V2 应替换为聊天、会话、历史和 SSE 接口。这个接口可以作为旧系统能力保留，但不应驱动 V2。 |
+| Docker Compose | 中 | 可复用容器化思路，但 V2 文档指定 MySQL 8.x。如果继续用 PostgreSQL，需要单独记录偏离原因。 |
 
-## Gap Analysis
+## 缺口分析
 
-Must build or redesign for V2:
+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.
+- 用户短信登录、Token、退出失效、账号有效期和每日额度。
+- 管理员用户名密码登录、角色和权限控制。
+- 知识库管理，字段包括知识库名称、SpaceID、NodeID、状态和备注。
+- 用户知识库授权关系，支持生效时间和到期时间。
+- 聊天会话和聊天消息持久化。
+- SSE 流式接口 `POST /chat/completions`。
+- 停止生成接口 `POST /chat/stop`。
+- Prompt 管理和当前 Prompt 加载。
+- 模型管理，包括 API URL、API Key、模型名称、温度、最大 Token 和超时。
+- 系统配置，包括登录有效期、每日聊天次数、AI 超时、飞书重试次数、上下文长度、是否展示引用来源、是否允许联网。
+- 按权限过滤后的飞书实时检索。
+- AI 请求日志，记录 Prompt、检索知识库、Token、耗时、状态和错误信息。
+- 后台聊天记录查询、详情和导出。
+- 围绕权限隔离、无命中兜底、不编造答案的测试和验收。
 
-## 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:
+1. 继续把 `ai_knowledge_base_v2/` 作为新需求上下文和规划工作区。
+2. 架构确认后，新建 V2 应用目录，而不是直接大面积修改旧 V1 文件。
+3. 后端从第一天开始按模块拆分：
    - `auth`
    - `users`
    - `admins`
@@ -102,7 +102,7 @@ Must build or redesign for V2:
    - `models`
    - `config`
    - `logs`
-4. Keep services separated:
+4. service 层保持边界清楚：
    - `SmsCodeService`
    - `TokenService`
    - `FeishuKnowledgeService`
@@ -110,24 +110,24 @@ Must build or redesign for V2:
    - `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.
+5. 本地开发阶段需要明确 mock provider：
+   - mock 短信验证码
+   - mock 大模型回答
+   - mock 飞书知识库检索
+6. 生产环境的模型 API Key 不建议明文存储。需要优先考虑环境变量引用、密文存储或其他安全方案，并形成决策记录。
 
-## 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.
+- 新文档指定 MySQL 8.x，而旧项目使用 PostgreSQL/SQLite。这不是一个小改动，需要作为架构和部署决策处理。
+- 文档要求“飞书更新后立即生效”和“每次提问实时检索”，这强依赖飞书实际 API 能力和租户权限，必须尽早做技术验证。
+- 流式输出和停止生成会影响后端请求生命周期、前端渲染和消息落库语义，应作为核心能力设计。
+- 权限是产品底线。每一次聊天检索都必须先过滤用户知识库权限，并记录实际使用的知识库和片段。
 
-## 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.
+1. 确认 V2 是放在当前仓库的新应用目录，还是后续拆成独立仓库。
+2. 先写 V2 架构和开发流程计划。
+3. 搭建 V2 后端基础工程和 `sys_*` 领域模型。
+4. 搭建 V2 用户端 H5，先跑通登录 mock、会话、SSE mock 问答。
+5. 搭建后台基础框架和用户/知识库/Prompt/模型管理页面。
+6. 尽早验证飞书实时检索和模型流式调用，避免后期被关键外部接口卡住。