项目工程全景（代码级地图）#

面试中回答”项目规模多大""代码结构是什么""数据库怎么设计的”时的参考。 所有数据来自源码实际统计，非估算。

一、仓库统计#

二、后端包结构（com.jake.DocMind）#

agent/ — Agent 核心（22 文件，含 supervisor/worker/state/emit 子包）#

注：SelfReflection.java（自反思）已于四刀改造整类删除；文档直读改由 service/rag/DocumentDirectReader.java 承接（原 SelectedDocumentScopeDecider 已下线）。

agent/supervisor/ (3 文件)

注：自研拆解 / 串行多跳 / CRAG-web 回溯三条分支与 SelfReflection 已于四刀改造统一收敛为 AgenticSearchOrchestrator；更早的 PlanGenerator / PlanExecutor / ExecutionPlan（Plan-and-Execute）已在链路精简中删除。见 04-优化迭代记录 #21/#22。

agent/worker/ (7 文件)

agent/state/ (2 文件)

agent/emit/ (1 文件)

service/rag/ — RAG 检索管线（26 文件）#

service/knowledge/ — 文档处理（4 文件）#

注：原 MinioService.java（MinIO S3 原件存储）已删除——原始文件与头像改为直接落本地磁盘（uploads/），不再使用对象存储。

mcp/ — MCP 工具（6 工具类，双路径；另含 MemoryStore/MemoryRecord/MemoryType 三个记忆支撑类）#

外部暴露 6 端点（doc_search / keyword_search / web_search / recall_memory / store_memory / kb_meta）；executeCode 内部专用。同一套 @Tool 注解代码既被内部 ChatClient 调用，也通过 spring-ai-starter-mcp-server-webmvc 对外暴露。工具执行结果通过 AgentToolContext ThreadLocal 写入，Agent 读取后清理。

MCP 安全边界（MVP → 生产）：内部调用由 AgentToolContext + 用户会话上下文保证 kbIds 隔离和 userId 注入。外部调用 4 个加固点中①已落地——McpApiKeyAuthFilter 校验 X-API-Key（配置键 docmind.mcp.api-key），/mcp/**、/sse 匿名访问被 401（见 21-权限系统对齐报告）；剩余：②kbIds 需校验用户归属（外部持 API-Key 仍可传任意 kbIds）；③Memory userId 需从 auth context 注入、禁止外部指定；④Web Search 需接入 rate-limiter 防配额滥用。

config/ — 配置（24 文件）#

controller/ — REST API（9 文件）#

support/ — 工具类（4 文件）#

entity/ — 数据模型（20 文件）#

实体 + DTO + VO，对应 13 张数据库表（含 RBAC 4 表 + sys_dept + user_memory）。

mapper/ — MyBatis Plus#

每个实体一个 Mapper 接口。XML 配置在 src/main/resources/mapper/。

security/ — 安全（3 文件）#

三、前端结构（DocMind-frontend/src/）#

2026-06 前端从 Vue 3 + Element Plus 彻底重构为 React 18 + TS + Vite + TailwindCSS + shadcn/ui(Radix) + TanStack Query + Zustand + React Router v7 + ECharts。旧 Vue 实现保留在 DocMind-frontend-backup/。后端 REST + SSE 契约不变。采用 feature-sliced 结构（页面按 features/<domain>/ 切分，各自 default-export 页面组件）。

features/ — 业务域页面（8 域）#

api/ — 类型化 HTTP 封装（6 TS 文件）#

aiConfig.ts / chat.ts / knowledge.ts / mcp.ts / stats.ts / user.ts

lib/ — 基础设施#

• http.ts — Axios 实例 + 拦截器（注入 Bearer、code===200 解包、401→登录）
• sse.ts — openChatStream() EventSource 封装（token 走 URL query，类型化 handler）
• token.ts — token 读写
• utils.ts — 通用工具（cn 等）

stores/ — Zustand 状态#

• authStore.ts — token + userInfo + isAdmin
• uiStore.ts — 侧边栏等 UI 状态

其他#

• types/ — 后端契约类型（单一事实来源，含 13 个 SSE 事件载荷）
• components/ui/（shadcn 风 Radix 原语）+ components/shared/（StatCard / ConfidenceBadge / EChart…）
• layout/MainLayout（Sidebar + Topbar）+ router/（createBrowserRouter + RequireAuth / RequireAdmin 守卫）

四、数据库表设计（13 张表）#

kb_chunk — 文档切片表（核心表，8 个设计决策）#

索引：idx_kb_id + idx_kb_id_content_hash（增量索引）+ idx_parent_chunk_id + FULLTEXT ft_kb_chunk_content_ngram

kb_knowledge_base — 知识库文档表#

qa_message — 对话消息表（4 类 JSON 结构化存储）#

额外字段：confidence_score (FLOAT) + confidence_band (VARCHAR) 直接存储置信度。

qa_conversation — 对话会话表#

kb_ids (JSON) 存储关联知识库 ID 列表，message_count 计数，last_active 排序。

sys_ai_config — 动态配置表（详见下节）#

sys_user — 用户表#

role (admin/user) RBAC，password BCrypt 加密，preference (JSON) 用户偏好。

mcp_tool_registry — MCP 工具注册表#

call_count + avg_latency_ms 统计，mode (embedded/remote)。

user_memory — 长期记忆 SoR（系统事实来源）#

按 (user_id, memory_id) 唯一；软删 invalidated_at（审计）、superseded_by 审计链、access_count/last_accessed 支撑 recency×frequency 淘汰；无 TTL（记忆不能随空闲蒸发）。Redis 仅作读缓存、Milvus docmind_memory 仅作向量索引。详见 长期记忆三层存储。

sys_dept / sys_role / sys_permission / sys_role_permission / sys_user_role — RBAC#

部门 + 角色 + 权限 + 两张关联表，支撑 admin/user 角色与细粒度权限。

五、动态配置参数全景（sys_ai_config）#

RAG 组（19 个）#

LLM 组（7 个）#

Memory 组（1 个）#

Cache 组（5 个）#

Safety 组（4 个）#

功能开关（3 个）#

Agent 组（1 个）#

六、Prompt 模板清单#

注：knowledge_qa_decomposed.txt / query_decompose.txt / hop_answer_extract.txt 已随拆解·多跳链路于四刀改造删除（当前 6 个模板）。

PromptAssembler 提供 3 种组装模式：

• assemble() — 标准 QA，带 context + history + memory
• assembleLowConfidence() — 低置信度（CRAG LOW 但有证据）：仍注入 KB/Web chunk 据实作答并 [n] 引用（#28 主通路，不丢弃证据）
• assembleFallback() — 真·无证据兜底（compressed 空，0 chunk）：声明”知识库与联网检索均未返回相关内容” + 防陈旧幻觉护栏（严禁断言实体”不存在/未发布”，#28 P1-A） （assembleDecomposed() 已随拆解链路删除）

七、部署架构#

两套 compose：docker-compose.dev.yml 只起基础设施（本地 npm run dev + mvn spring-boot:run 开发用）；docker-compose.yml 是生产/演示全栈，一条 docker compose up -d --build 起全部 13 个服务。Milvus 用本地盘（COMMON_STORAGETYPE=local），MinIO 仅作 Langfuse v3 的 S3 后端，不再做应用对象存储。MySQL 已纳入全栈 compose（dev 版仍需独立运行）。

docker-compose.dev.yml（仅基础设施，4 服务）
┌──────────────────────────────────────────────┐
│ Redis 7        :6379   语义缓存 + 记忆读缓存  │
│ etcd           :2379   Milvus 元数据存储      │
│ Milvus 2.4     :19530  向量数据库（本地盘）   │
│ OpenSandbox    :8090   代码执行沙箱控制面     │
└──────────────────────────────────────────────┘
（MySQL 8 :3306 需独立运行，dev 不纳入 compose）

docker-compose.yml（生产全栈，13 服务，一键起）
┌──────────────────────────────────────────────┐
│ 业务核心：mysql / redis / etcd / milvus       │
│           backend(:8080) / frontend(:80)      │
│ 代码沙箱：opensandbox(:8090)                  │
│ 可观测  ：Langfuse v3 自托管栈                │
│   langfuse-web(:3000) / langfuse-worker       │
│   + ClickHouse + Postgres + MinIO(:9001 控制台)│
│   （MinIO 仅作 Langfuse S3 事件/媒体存储）     │
└──────────────────────────────────────────────┘
         ↑ 外部 API
┌──────────────────────────────────────────────┐
│ DashScope API     — LLM (qwen-plus/max)      │
│ DashScope API     — Embedding (text-emb-v3)  │
│ DashScope API     — Rerank (gte-rerank)      │
│ MinerU API        — 文档解析（可选）          │
│ Tavily API        — 联网搜索（可选）          │
│ Langfuse          — LLM 可观测（自托管/可选） │
└──────────────────────────────────────────────┘

八、面试 Q&A#

Q: 项目代码规模多大？

A: 后端 153 个 Java 文件（~18,500 行），核心 RAG 组件 26 个文件（service/rag/）。前端 81 个 React/TypeScript 文件（~5,600 行，2026-06 从 Vue 3 彻底重构为 React 18 + shadcn/ui）。13 张数据库表，50+ 动态配置参数，6 个 Prompt 模板。全栈独立开发，经历 6 个 Phase + 对标主流四刀改造、评测驱动迭代。

Q: 最复杂的文件是哪个？

A: 核心编排原来是 DocMindAgent.java（曾 ~1349 行的上帝类），#31 已按职责拆开：入口 DocMindAgent 收缩到 ~135 行薄壳（会话装配 + 根 span + 顶层分流），析出 ScopeRouter（范畴路由）、ShortCircuitResponder（紧急/闲聊/越界等短路）、SemanticCacheReplayer（缓存回放）、以及最复杂的 RagPipeline（~600 行，知识问答主流水线：QU→路径决策三模式 SELECTED_DOC / RULE_PLANNER / AGENTIC→记忆→检索→CRAG→Prompt→流式生成 + 结构化引用，生成即终态、自反思已删）。检索核心仍拆两块：AGENTIC 走 AgenticSearchOrchestrator（真·LLM 工具调用循环），其余走 SupervisorAgent.oneShotRetrieval（四刀改造后从 ~1683 行瘦身到 ~595 行）。

Q: 数据库设计有什么亮点？

A: 三个设计值得讲：第一是 kb_chunk.content_hash（SHA-256），支撑增量索引——100 页 PDF 改 1 字只重新 embedding ~1 次。第二是 kb_chunk.parent_chunk_id，支撑 Parent Document Retrieval 双层切块。第三是 qa_message 的 JSON 字段（sources / agent_trace / mcp_calls），把推理过程结构化存储，前端可回放展示（reflection_log 列在自反思移除后保留兼容、不再写入；引用改由结构化 citations 随 done 下发）。