nex_docus/frontend
mula.liu c6117e1c49 优化前端规范 2026-11-14 14:25:53 +08:00
..
public 0.9.5 2025-12-31 13:44:03 +08:00
src 优化前端规范 2026-11-14 14:25:53 +08:00
.dockerignore 0.9.3 2025-12-25 12:22:35 +08:00
.eslintrc.cjs v 1.0.1 2026-11-09 16:18:25 +08:00
.gitignore 0.9.3 2025-12-25 12:22:35 +08:00
Dockerfile 优化大pdf加载 2026-01-01 23:05:43 +08:00
README.md v 1.0.1 2026-11-09 16:18:25 +08:00
index.html v 1.0.1 2026-11-09 16:18:25 +08:00
nginx.conf v0.9.9 2026-08-04 16:40:13 +08:00
package-lock.json v 1.0.1 2026-11-09 16:18:25 +08:00
package.json v 1.0.1 2026-11-09 16:18:25 +08:00
tsconfig.json v 1.0.1 2026-11-09 16:18:25 +08:00
tsconfig.node.json v 1.0.1 2026-11-09 16:18:25 +08:00
vite.config.ts v 1.0.1 2026-11-09 16:18:25 +08:00

README.md

NexDocus Frontend

NexDocus 前端项目 - 基于 React + TypeScript + Vite + Ant Design 构建。

技术栈

  • 框架: React 18+(TypeScript,strict 模式)
  • 构建工具: Vite 5+
  • UI 组件: Ant Design 5+
  • 路由: React Router v6
  • HTTP 客户端: Axios
  • 状态管理: Zustand
  • Markdown 编辑器: ByteMD(@bytemd/react + gfm / highlight / frontmatter / breaks / gemoji)
  • Markdown 渲染: react-markdown(+ remark-gfm / rehype-highlight / rehype-raw / rehype-slug)
  • 样式: CSS Variables + 手写 CSS(无 Tailwind、无 CSS Modules); 令牌见 src/styles/design-tokens.css,antd 主题映射见 src/theme/antdTheme.ts

项目结构

frontend/
├── public/              # 静态资源
├── src/
│   ├── api/            # API 请求封装
│   │   ├── auth.ts         # 用户认证
│   │   ├── project.ts      # 项目管理
│   │   └── file.ts         # 文件系统
│   ├── components/      # 通用组件
│   │   ├── MainLayout/     # 主布局
│   │   └── ProtectedRoute.tsx  # 路由守卫
│   ├── pages/           # 页面组件
│   │   ├── Login/          # 登录页
│   │   ├── ProjectList/    # 项目列表页
│   │   └── DocumentEditor/ # 文档编辑页
│   ├── types/           # 后端接口契约(api.ts)
│   ├── stores/          # 状态管理
│   │   └── userStore.ts    # 用户状态
│   ├── utils/           # 工具函数
│   │   ├── request.ts      # HTTP 请求封装
│   │   └── apiError.ts     # 接口错误信息统一取值
│   ├── App.tsx          # 路由与应用入口
│   ├── main.tsx         # 渲染入口
│   └── index.css        # 全局样式
├── index.html           # HTML 模板
├── package.json         # 项目配置
├── tsconfig.json        # TypeScript 配置(strict + noUnusedLocals)
├── tsconfig.node.json   # vite.config.ts 的类型检查配置
└── vite.config.ts       # Vite 配置

快速开始

1. 安装依赖

npm install

2. 后端地址

前端固定请求同源相对路径 /api/v1(见 src/utils/request.ts), 开发环境由 vite.config.ts 的 server.proxy 转发到 http://localhost:8000, 生产环境由容器内 nginx 反向代理。无需配置环境变量。

3. 启动开发服务器

npm run dev

访问:http://localhost:5173

4. 构建生产版本

npm run build

构建产物在 dist/ 目录。

5. 质量检查

npm run typecheck     # tsc 严格检查(Vite 构建不做类型检查,必须单独跑)
npm run lint          # ESLint(基线:0 error / 25 warning)
npm run lint:strict   # 警告也视为失败

主要功能

用户认证

  • 用户注册
  • 用户登录
  • 退出登录

项目管理

  • 创建项目
  • 项目列表(我创建的 / 我参与的)
  • 成员与角色管理、所有权转移
  • 删除项目(要求目录已清空,随后删除物理目录与记录)

文档编辑

  • 目录树浏览
  • Markdown 实时预览
  • 文件保存
  • 创建文件/文件夹
  • 删除文件
  • 图片上传
  • PDF 预览(pdfjs-dist / react-pdf)

默认账号

  • 用户名: admin
  • 密码: admin@123(由 backend/scripts/init_db.py 首次创建时读取 ADMIN_PASSWORD,详见 docs/quickstart.md)

开发指南

添加新页面

  1. 在 src/pages/ 下创建页面组件
  2. 在 src/App.tsx 中用 lazy() 注册路由
  3. 如果需要认证,使用 <ProtectedRoute> 包裹

添加新 API

  1. 在 src/api/ 下创建对应的 API 文件
  2. 先在 src/types/api.ts 补后端返回类型(对照后端 Pydantic schema,不要凭猜测写)
  3. 使用 request 工具发起请求,在组件中调用
  4. 错误提示统一用 @/utils/apiError 取后端 detail

状态管理

使用 Zustand 进行状态管理,参考 src/stores/userStore.ts

许可证

Copyright © 2023 Mula.liu