# 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。