221 lines
6.9 KiB
Markdown
221 lines
6.9 KiB
Markdown
# 代码结构审计与优化记录（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. 前端将文档浏览页的页面级编排从页面入口中拆出，并统一认证存储边界
|
||
|
||
这两项改动都直接对应结构规范中的高优先级问题，属于低风险、可验证、后续可继续扩展的结构优化。
|