update
This commit is contained in:
@@ -0,0 +1,272 @@
|
||||
# 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
|
||||
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 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。
|
||||
|
||||
Reference in New Issue
Block a user