Files

T

Chuyaoyuan c764603dbd update

2026-04-30 18:53:50 +08:00

7.6 KiB

Raw Blame History

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

目录结构

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 文件：

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

启动后端

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 结构：

{
	"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	回收站

前端配置与运行

环境变量

复制示例配置：

cd cyynote-frontend
cp .env.example .env

常用配置：

VITE_API_BASE_URL=/api
VITE_WS_URL=ws://localhost:1234

开发模式下，Vite 已配置 /api 代理到 http://localhost:8080。

安装与启动

cd cyynote-frontend
pnpm install
pnpm dev

构建与检查

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 依赖声明

验证建议

网络正常后建议执行：

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。

7.6 KiB Raw Blame History Unescape Escape