CyyNote/README.md

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

{
	"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 config set registry https://registry.npmmirror.com/

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。