6.9 KiB

Raw Blame History

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

本文依据 docs/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. 验证结果

已执行：

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
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. 结论

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

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

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

6.9 KiB Raw Blame History Unescape Escape