# 架构概览（Overview）

## 系统定位

NEX Docus 是**单机可部署**的团队文档平台，后端 FastAPI 单体 + 前端 React SPA + MySQL + Redis + 本地文件系统 + 本地检索/向量引擎，全部由 docker-compose 编排为同网段容器。

## 逻辑架构

```mermaid
graph TD
  Client[React SPA] -->|JSON/HTTP| API[FastAPI Backend :8000]
  Agent[External Agent] -->|MCP streamableHttp| API
  API --> DB[(MySQL)]
  API --> RD[(Redis)]
  API --> FS[文件系统 STORAGE_ROOT/projects/<uuid>]
  API --> WH[Whoosh 全文索引 search_index]
  API --> ZV[ZVec 向量库 vector_index/<project_id>]
  API --> LLM[LLM Provider: chat/embedding]
  FS -->|变更同步| SVC[FileVectorSyncService → ZVec / SearchService]
```

## 三层结构（物理/逻辑/应用映射）

| 层 | 载体 | 说明 |
| --- | --- | --- |
| 应用层 | FastAPI（/api/v1 + /mcp）+ React SPA | 业务 API 与前端 |
| 数据层 | MySQL（元数据/权限/状态）、Redis（Token/会话）、文件系统（内容）、Whoosh/ZVec（索引） | 结构化 vs 非结构化分离 |
| 基础设施 | docker-compose（backend/frontend/mysql/redis）、nginx（frontend 内） | 容器化部署 |

## 关键子系统
1. **认证**：JWT Bearer + Redis Token 缓存双校验（见 DV-0001）。
2. **权限**：RBAC（roles/system_menus/role_menus）+ 项目级角色（admin/editor/viewer）双维度（DV-0002/0004）。
3. **文件系统**：`StorageService` 统一封装，含路径安全校验（DV-0002）。
4. **检索**：Whoosh 全文（DV-0005）+ ZVec 语义（DV-0006）双引擎，写路径后台同步（ADR-08）。
5. **知识库**：RAG 检索 + LLM 生成 + 引用支撑句对齐（DV-0007）。
6. **开放**：MCP Streamable HTTP（/mcp），bot 凭据映射到用户（DV-0011）。

## 系统边界
- 进程内单后端：REST 与 MCP 同挂一个 service。
- 存储边界：内容永不进 DB BLOB；DB 只存元数据。
- 网络边界：前端经 nginx 反代 /api，可同域免跨域；/mcp 不可 301/302 重定向（MCP 客户端要求）。