|
|
||
|---|---|---|
| .. | ||
| public | ||
| src | ||
| .dockerignore | ||
| .eslintrc.cjs | ||
| .gitignore | ||
| Dockerfile | ||
| README.md | ||
| index.html | ||
| nginx.conf | ||
| package-lock.json | ||
| package.json | ||
| tsconfig.json | ||
| tsconfig.node.json | ||
| vite.config.ts | ||
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
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)
开发指南
添加新页面
- 在
src/pages/下创建页面组件 - 在
src/App.tsx中用lazy()注册路由 - 如果需要认证,使用
<ProtectedRoute>包裹
添加新 API
- 在
src/api/下创建对应的 API 文件 - 先在
src/types/api.ts补后端返回类型(对照后端 Pydantic schema,不要凭猜测写) - 使用
request工具发起请求,在组件中调用 - 错误提示统一用
@/utils/apiError取后端detail
状态管理
使用 Zustand 进行状态管理,参考 src/stores/userStore.ts
许可证
Copyright © 2023 Mula.liu