# 代码结构审计与优化记录（2026-04-08）

本文依据 [`docs/code-structure-standards.md`](./code-structure-standards.md) 对当前仓库进行前后端结构审计，并记录本轮已落地的优化项。

## 1. 审计范围

- 后端：`backend/app/api/v1`、`backend/app/services`
- 前端：`frontend/src/pages`、`frontend/src/utils`、`frontend/src/components`

## 2. 主要结构问题

### 2.1 后端 Router 过厚

以下问题在多个 router 中重复出现：

- 项目存在性校验
- 读权限/写权限/成员角色判断
- 项目文档数量统计
- 公开项目与私密项目访问分支

受影响较明显的文件：

- `backend/app/api/v1/projects.py`
- `backend/app/api/v1/files.py`
- `backend/app/api/v1/preview.py`
- `backend/app/api/v1/search.py`
- `backend/app/api/v1/git_repos.py`

这类问题违反了“Router 只做协议转换”和“副作用与规则应收口”的要求，导致：

- 权限规则难以统一演进
- 同一类修改影响多个入口
- 新增接口时容易复制旧逻辑继续膨胀

### 2.2 前端文档页承担过多页面级编排

`frontend/src/pages/Document/DocumentPage.jsx` 在审计前同时承担了：

- 文件树加载
- URL deep link 同步
- 搜索与节点展开
- Markdown 文件加载
- PDF URL 组装
- Markdown 内链解析
- TOC 生成
- 页面展示渲染

这已经明显超过“页面入口必须薄”的建议范围，属于页面入口和页面编排层混杂。

### 2.3 前端认证存储边界分散

`access_token` 与登录态清理逻辑分散在：

- `request.js`
- `ProtectedRoute.jsx`
- `userStore.js`
- 多个页面文件

这违背了“前端基础设施应收口”的要求，也增加了未来切换 token 策略时的修改面。

## 3. 本轮已落地优化

### 3.1 后端新增项目域服务

新增：

- `backend/app/services/project_service.py`

收口能力：

- 项目存在性查询
- 项目成员查询
- 项目角色解析
- 项目读权限校验
- 项目角色权限校验
- 项目写权限校验
- 项目文档数量统计
- 项目序列化补充 `doc_count`

### 3.2 后端 Router 瘦身

已切换到项目域服务的文件：

- `backend/app/api/v1/projects.py`
- `backend/app/api/v1/files.py`
- `backend/app/api/v1/preview.py`
- `backend/app/api/v1/search.py`
- `backend/app/api/v1/git_repos.py`

效果：

- 权限判断不再散落在每个 handler 内
- `projects.py` 的列表序列化不再自己统计文档数
- `preview.py` 的公开/私密访问逻辑集中复用
- `files.py` 的读写权限边界更明确

### 3.3 前端抽离文档页编排层

新增：

- `frontend/src/pages/Document/useDocumentBrowser.js`
- `frontend/src/pages/Document/documentBrowserUtils.jsx`

抽离后的职责：

- 文件树加载与状态维护
- URL 参数驱动的文档打开
- Markdown/PDF 切换
- 搜索与节点展开
- TOC 生成
- Markdown 内链解析

`frontend/src/pages/Document/DocumentPage.jsx` 现在主要保留：

- 页面布局
- Git 操作 UI
- 分享设置 UI
- Markdown 渲染输出

### 3.4 前端认证存储收口

新增：

- `frontend/src/utils/authStorage.js`

已接入：

- `frontend/src/utils/request.js`
- `frontend/src/components/ProtectedRoute.jsx`
- `frontend/src/stores/userStore.js`
- `frontend/src/pages/Preview/PreviewPage.jsx`
- `frontend/src/pages/Document/DocumentPage.jsx`

### 3.5 继续下沉编辑页与浏览器副作用

新增：

- `frontend/src/pages/Document/useDocumentEditorWorkspace.js`
- `frontend/src/utils/browserIO.js`
- `frontend/src/pages/ProjectList/useProjectExport.js`
- `frontend/src/pages/ProjectList/useProjectShare.js`
- `frontend/src/pages/ProjectList/useProjectCollaboration.js`
- `frontend/src/pages/ProjectList/useProjectGitRepos.js`

本轮继续优化后：

- `DocumentEditor.jsx` 中的树加载、URL 同步、文件打开、刷新流程已下沉到工作区 hook
- 项目导出、文件名解析、复制链接等浏览器能力已从页面中抽出为通用工具
- `ProjectList.jsx` 与 `DocumentPage.jsx` 不再自己维护复制降级实现
- `ProjectList.jsx` 中的导出轮询、分享设置、成员协作、Git 仓库管理已各自收口为稳定子流程

### 3.6 补齐后端文件用例与预览页编排层

新增：

- `backend/app/services/project_export_service.py`
- `backend/app/services/project_file_service.py`
- `frontend/src/pages/Preview/usePreviewBrowser.js`
- `frontend/src/pages/Preview/previewBrowserUtils.js`

本轮继续优化后：

- `projects.py` 中的导出任务状态管理、过期清理与 ZIP 打包流程已下沉到独立导出服务
- `files.py` 的保存、创建、删除、重命名、移动流程已通过项目文件服务统一编排
- `backend/app/mcp/server.py` 不再复制文件写入后的索引、日志、通知逻辑，改为复用同一文件用例服务
- `PreviewPage.jsx` 中的密码校验、目录树加载、文档切换、搜索、TOC 与 PDF/Markdown 模式切换已下沉到页面级 hook

## 4. 验证结果

已执行：

1. `python3 -m py_compile backend/app/services/project_service.py backend/app/api/v1/projects.py backend/app/api/v1/files.py backend/app/api/v1/preview.py backend/app/api/v1/search.py backend/app/api/v1/git_repos.py`
2. `npm run build`（在 `frontend/` 下）

结果：

- 后端语法校验通过
- 前端生产构建通过
- 仍存在 Vite 默认的大包告警，属于性能优化项，不影响本轮结构改造正确性

## 5. 剩余建议

以下问题已在审计中确认，但未在本轮一并处理，以控制风险：

### 5.1 前端仍有超大页面待继续下沉

重点文件：

- `frontend/src/pages/Document/DocumentEditor.jsx`
- `frontend/src/pages/ProjectList/ProjectList.jsx`
- `frontend/src/pages/Preview/PreviewPage.jsx` 已完成一轮下沉，但页面内仍保留部分响应式布局与渲染分支，可后续继续压薄

建议方向：

- 将上传/导出/重命名/移动等流程拆为页面级 controller 或 hook
- 将下载、文件名解析、Blob 导出等浏览器副作用进一步沉到可复用基础模块

### 5.2 前端构建产物体积偏大

构建结果中仍存在明显的大 chunk 警告，建议后续评估：

- 文档页与编辑页按路由拆包
- PDF/Markdown 编辑器相关库延迟加载
- 搜索与预览相关能力按场景拆分

### 5.3 后端入口层仍有剩余热点

虽然项目导出和文件编排已下沉，但以下热点仍值得继续优化：

- `backend/app/api/v1/projects.py` 仍包含较多成员管理与分享配置流程，可继续按主题拆出更明确的 use case
- `backend/app/api/v1/files.py` 仍承载上传、导入、导出等多类文件主题，后续可继续按“编辑文件 / 传输文件 / 读取文档”拆分

## 6. 结论

本轮优化重点完成了两件事：

1. 后端将重复的项目访问规则从 router 中收口到项目域服务
2. 前端将文档浏览页的页面级编排从页面入口中拆出，并统一认证存储边界

这两项改动都直接对应结构规范中的高优先级问题，属于低风险、可验证、后续可继续扩展的结构优化。