283 lines
7.7 KiB
Markdown
283 lines
7.7 KiB
Markdown
# CyyNote
|
||
|
||
CyyNote 是一个前后端分离的在线笔记系统，后端基于 Solon + Wood + SQLite 提供鉴权、笔记树、笔记编辑、回收站和浏览历史接口；前端基于 React + Vite + Semi UI + Lexical 提供笔记管理与富文本编辑体验。
|
||
|
||
## 技术栈
|
||
|
||
### 前端
|
||
|
||
- React 18
|
||
- TypeScript 5.8
|
||
- Vite 6
|
||
- React Router 7
|
||
- Zustand 5：客户端状态管理
|
||
- Axios：统一 HTTP 客户端与鉴权拦截器
|
||
- Semi UI 2.96：页面组件库
|
||
- Lexical 0.44：富文本编辑器
|
||
- Yjs + y-websocket：协作编辑基础能力
|
||
- pnpm 9：包管理器
|
||
- ESLint 9 Flat Config
|
||
|
||
### 后端
|
||
|
||
- JDK 17
|
||
- Solon 3.0.5
|
||
- Wood ORM / wood-solon-plugin
|
||
- SQLite JDBC 3.46
|
||
- HikariCP
|
||
- solon-sessionstate-jwt：JWT Session
|
||
- Fastjson2
|
||
- Hutool
|
||
- Maven
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
CyyNote/
|
||
├── cyynote-backend/ # Solon 后端工程
|
||
│ ├── pom.xml
|
||
│ └── src/main/
|
||
│ ├── java/com/cyynote/
|
||
│ │ ├── controller/ # Auth / Note / Test 控制器
|
||
│ │ ├── dso/ # DB 初始化、Wood Mapper
|
||
│ │ ├── model/ # 数据模型
|
||
│ │ ├── payload/ # 请求/响应 DTO
|
||
│ │ └── util/ # 笔记树构建工具
|
||
│ └── resources/
|
||
│ ├── app.yml # 通用配置
|
||
│ ├── app-dev.yml # 开发环境配置
|
||
│ ├── app-pro.yml # 生产环境配置
|
||
│ └── db/schema.sql # SQLite 初始化脚本
|
||
└── cyynote-frontend/ # React 前端工程
|
||
├── package.json
|
||
├── vite.config.ts
|
||
└── src/
|
||
├── components/ # 页面组件、Lexical 编辑器、弹窗、侧栏
|
||
├── pages/ # 路由页面
|
||
├── services/ # API Service
|
||
├── stores/ # Zustand Store
|
||
├── lib/axios.ts # Axios 实例与拦截器
|
||
└── types/ # 前端类型定义
|
||
```
|
||
|
||
## 环境要求
|
||
|
||
| 项目 | 要求 |
|
||
| --- | --- |
|
||
| JDK | 17+ |
|
||
| Maven | 3.8+ |
|
||
| Node.js | 20+ |
|
||
| pnpm | 9+ |
|
||
|
||
后端 Maven 编译目标已设置为 Java 17；前端 `package.json` 中声明了 Node 20 与 pnpm 9。
|
||
|
||
## 后端配置与运行
|
||
|
||
### 数据库配置
|
||
|
||
开发环境默认使用当前运行目录下的 SQLite 文件：
|
||
|
||
```yaml
|
||
test.db1:
|
||
jdbcUrl: "jdbc:sqlite:./cyynote.db"
|
||
driverClassName: "org.sqlite.JDBC"
|
||
```
|
||
|
||
首次启动时，如果数据库中不存在 `appx` 表，后端会执行 `src/main/resources/db/schema.sql` 初始化基础表结构和示例数据。
|
||
|
||
默认账号：
|
||
|
||
| 用户名 | 密码 | 角色 |
|
||
| --- | --- | --- |
|
||
| admin | cyy123 | ROLE_ADMIN |
|
||
| test | test | ROLE_USER |
|
||
|
||
### 启动后端
|
||
|
||
```bash
|
||
cd cyynote-backend
|
||
mvn clean package
|
||
mvn clean package -DskipTests
|
||
mvn solon:run
|
||
|
||
|
||
java -jar demo.jar
|
||
|
||
java -jar target/cyynote.jar
|
||
```
|
||
|
||
默认服务端口：`8080`。
|
||
|
||
### 后端关键接口
|
||
|
||
接口统一以 `/api` 为前缀。
|
||
|
||
#### 鉴权接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| POST | `/api/auth/signin` | 登录，返回 `accessToken`、`tokenType` 和 `user` |
|
||
| GET | `/api/auth/logout` | 清理服务端 Session |
|
||
| POST | `/api/auth/signup` | 注册普通用户 |
|
||
| POST | `/api/auth/updatePassword` | 修改密码 |
|
||
|
||
登录成功响应中的 `data` 结构：
|
||
|
||
```json
|
||
{
|
||
"accessToken": "...",
|
||
"tokenType": "Bearer",
|
||
"user": {
|
||
"id": 1,
|
||
"username": "admin",
|
||
"email": "aaaaaaaaa",
|
||
"roles": ["ROLE_ADMIN"]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 笔记接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| GET | `/api/note/all` | 获取笔记树 |
|
||
| GET | `/api/note/home?type=1&search=0` | 首页列表、搜索、回收站列表 |
|
||
| GET | `/api/note/get?id=1` | 获取笔记详情，同时更新浏览时间 |
|
||
| GET | `/api/note/add?pid=0` | 新增笔记 |
|
||
| POST | `/api/note/update` | 更新笔记标题和内容 |
|
||
| POST | `/api/note/delete` | 软删除笔记 |
|
||
| GET | `/api/note/deleteBack?id=1` | 从回收站恢复笔记 |
|
||
| GET | `/api/note/historyQueryOrDelete?flag=0` | 查询或清理历史记录 |
|
||
|
||
`/api/note/home` 的 `type` 参数含义：
|
||
|
||
| type | 说明 |
|
||
| --- | --- |
|
||
| 0 | 搜索 |
|
||
| 1 | 最近更新 |
|
||
| 2 | 最新添加 |
|
||
| 3 | 最近浏览 |
|
||
| 4 | 回收站 |
|
||
|
||
## 前端配置与运行
|
||
|
||
### 环境变量
|
||
|
||
复制示例配置：
|
||
|
||
```bash
|
||
cd cyynote-frontend
|
||
cp .env.example .env
|
||
```
|
||
|
||
常用配置：
|
||
|
||
```env
|
||
VITE_API_BASE_URL=/api
|
||
VITE_WS_URL=ws://localhost:1234
|
||
```
|
||
|
||
开发模式下，Vite 已配置 `/api` 代理到 `http://localhost:8080`。
|
||
|
||
### 安装与启动
|
||
|
||
```bash
|
||
cd cyynote-frontend
|
||
若网络不好
|
||
pnpm config set registry https://registry.npmmirror.com/
|
||
|
||
pnpm install
|
||
|
||
pnpm dev
|
||
```
|
||
|
||
### 构建与检查
|
||
|
||
```bash
|
||
pnpm typecheck
|
||
pnpm lint
|
||
pnpm build
|
||
```
|
||
|
||
## 前端架构说明
|
||
|
||
### 路由
|
||
|
||
前端入口使用 `BrowserRouter`。主要路由：
|
||
|
||
| 路径 | 页面 | 说明 |
|
||
| --- | --- | --- |
|
||
| `/login` | SignIn | 登录页 |
|
||
| `/register` | Register | 注册页 |
|
||
| `/home` | NotePage | 笔记主界面 |
|
||
| `/profile` | Profile | 用户信息 |
|
||
| `/user` | BoardUser | 用户权限测试页 |
|
||
| `/mod` | BoardModerator | Moderator 权限测试页 |
|
||
| `/admin` | BoardAdmin | Admin 权限测试页 |
|
||
|
||
除登录和注册外，其他路由由 `ProtectedRoute` 保护；未登录用户会跳转到 `/login`。
|
||
|
||
### 状态管理
|
||
|
||
Zustand Store 分为三类：
|
||
|
||
- `useAuthStore`：用户信息、JWT Token、登录状态持久化到 `sessionStorage`
|
||
- `useNoteStore`：当前笔记、笔记树、首页列表、最近浏览列表
|
||
- `useUIStore`：当前视图、侧栏状态、搜索条件、弹窗显隐状态
|
||
|
||
### HTTP 客户端
|
||
|
||
`src/lib/axios.ts` 创建统一 Axios 实例：
|
||
|
||
- `baseURL` 读取 `VITE_API_BASE_URL`，默认 `/api`
|
||
- 请求拦截器自动添加 `Authorization: Bearer <token>`
|
||
- 响应拦截器在 HTTP 401 时自动登出并跳转登录页
|
||
|
||
### 编辑器
|
||
|
||
笔记编辑器基于 Lexical。`NoteEditor` 负责标题输入与编辑器挂载，`LexicalApp` 负责富文本编辑能力。协作相关配置位于 `components/lexical/collaboration.ts`，WebSocket 地址由 `VITE_WS_URL` 控制。
|
||
|
||
## 本次升级与修复说明
|
||
|
||
本次修复覆盖前端、后端和 JDK 17 运行兼容性：
|
||
|
||
- 后端 Maven 编译目标升级为 Java 17
|
||
- 修复后端登录返回结构，使其与前端 `IAuthResponse` 匹配
|
||
- 修复登录失败时空指针问题，并返回 HTTP 401
|
||
- 修复注册接口只返回空对象的问题，改为实际创建普通用户
|
||
- 修复修改密码接口用户不存在时空指针问题
|
||
- 修复 JWT 拦截器在 401 后仍继续执行 Controller 的问题
|
||
- 修复软删除接口把标题更新成 `null` 的问题
|
||
- 修复历史表缺失 `flag` 字段的问题
|
||
- 修复开发环境 SQLite 路径在 Linux 下不可用的问题
|
||
- 修复前端 Profile 页面访问不存在 `accessToken` 字段导致崩溃的问题
|
||
- 修复首页点击“查看”后未切换到笔记视图的问题
|
||
- 修复 Board 页面仍使用旧 service 返回结构的问题
|
||
- 修复回收站和密码弹窗状态字段 `Model` / `Modal` 拼写不一致问题
|
||
- 修复前端笔记树 `key` 类型与后端返回值不一致的问题
|
||
- 清理未使用的 `@tanstack/react-query` 依赖声明
|
||
|
||
## 验证建议
|
||
|
||
网络正常后建议执行：
|
||
|
||
```bash
|
||
cd cyynote-backend
|
||
mvn clean package
|
||
|
||
cd ../cyynote-frontend
|
||
pnpm install
|
||
pnpm typecheck
|
||
pnpm lint
|
||
pnpm build
|
||
```
|
||
|
||
如果 CI 使用 `pnpm install --frozen-lockfile`，需要提交 `pnpm-lock.yaml`。
|
||
|
||
## 注意事项
|
||
|
||
- 当前密码仍为明文存储，生产环境应改为 BCrypt/Argon2 等不可逆哈希。
|
||
- Lexical 从旧版本升级到 0.44 跨度较大，建议重点回归测试自定义 Node、Plugin、序列化/反序列化和保存逻辑。
|
||
- y-websocket 3.x 与旧版存在差异，协作编辑功能需要单独联调。
|
||
- SQLite 适合单机和轻量部署；多人协作、高并发或云部署建议迁移到 MySQL/PostgreSQL。
|