# AI智能学习笔记管理系统

**Repository Path**: stephon_curry/ai-notes

## Basic Information

- **Project Name**: AI智能学习笔记管理系统
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-15
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI智能学习笔记管理系统

基于FastAPI + SQLAlchemy + 原生HTML/CSS/JavaScript构建的AI智能学习笔记管理系统，支持笔记CRUD、AI摘要生成、AI对话交互等功能。

***

## 目录

1. [技术栈](#技术栈)
2. [功能特性](#功能特性)
3. [项目结构](#项目结构)
4. [数据库表设计](#数据库表设计)
5. [业务流程设计](#业务流程设计)
6. [快速开始](#快速开始)
7. [API接口](#api接口)
8. [响应格式](#响应格式)
9. [注意事项](#注意事项)

***

## 技术栈

### 后端

- **FastAPI** - 高性能Python Web框架
- **SQLAlchemy 2.0** - ORM数据库操作
- **Pydantic** - 数据校验
- **JWT** - 身份认证
- **requests** - HTTP请求
- **MySQL** - 数据库

### 前端

- **原生HTML/CSS/JavaScript** - 无框架依赖
- **Axios** - HTTP客户端（CDN引入）

### AI服务

- **Dify API** - AI对话和生成服务

***

## 功能特性

### 1. 用户管理模块

- 用户注册（用户名唯一、密码bcrypt加密）
- 用户登录（JWT令牌生成、前端localStorage存储）
- 全局JWT身份鉴权
- 退出登录功能

### 2. 笔记CRUD模块

- 新增笔记（标题必填、正文可选）
- 笔记列表分页查询（默认每页10条、按创建时间倒序）
- 笔记详情查询
- 笔记编辑（更新时间自动刷新）
- 笔记软删除（is\_deleted标记）
- 笔记模糊搜索（标题/正文/标签）

### 3. 基础AI生成模块（Dify单向调用）

- AI智能摘要生成（30-50字）
- AI自动标签推荐（3-5个，逗号分隔）
- AI文本纠错优化

### 4. AI对话交互模块（Dify多轮对话）

- 单笔记专属会话自动创建
- 对话消息发送与AI响应
- 历史对话消息自动加载
- 会话清空重置功能
- 4个预设快捷指令：拆解知识点、生成练习题、梳理背诵提纲、解释专业术语

***

## 项目结构

```
ai-note-system/
├── backend/                    # 后端代码
│   ├── app/                    # 应用核心代码
│   │   ├── config/             # 配置文件
│   │   │   └── settings.py     # 环境变量配置
│   │   ├── core/               # 核心模块
│   │   │   ├── database.py     # 数据库连接
│   │   │   ├── security.py     # JWT安全认证
│   │   │   ├── exceptions.py   # 异常处理
│   │   │   └── dependencies.py # 依赖注入
│   │   ├── models/             # SQLAlchemy模型
│   │   ├── schemas/            # Pydantic数据模型
│   │   ├── services/           # 业务逻辑层
│   │   ├── api/                # API路由
│   │   │   └── v1/             # API版本控制
│   │   └── utils/              # 工具类
│   │       └── dify_client.py  # Dify API客户端
│   ├── .env.example           # 环境变量示例
│   └── requirements.txt        # Python依赖
├── frontend/                   # 前端代码
│   ├── static/                 # 静态资源
│   │   ├── css/               # 样式文件
│   │   └── js/                # JavaScript文件
│   └── templates/             # HTML模板
└── README.md                   # 项目说明文档
```

***

## 数据库表设计

### 实体关系图（ER图）

```
┌──────────────┐       ┌──────────────┐
│    users     │       │    notes     │
│──────────────│       │──────────────│
│ id (PK)      │<──────│ user_id (FK) │
│ username     │       │ title        │
│ password_hash│       │ content      │
│ email        │       │ summary      │
│ created_at   │       │ tags         │
│ updated_at   │       │ created_at   │
│ is_deleted   │       │ updated_at   │
└──────────────┘       │ is_deleted   │
                       └──────┬───────┘
                              │
                              │ note_id (FK)
                              ▼
                       ┌───────────────┐
                       │chat_sessions  │
                       │───────────────│
                       │ id (PK)       │
                       │ user_id (FK)  │
                       │ note_id (UK)  │
                       │ session_id    │
                       │ created_at    │
                       │ updated_at    │
                       │ is_deleted    │
                       └──────┬────────┘
                              │ chat_session_id (FK)
                              ▼
                       ┌───────────────┐
                       │chat_messages  │
                       │───────────────│
                       │ id (PK)       │
                       │ chat_session_id│
                       │ role          │
                       │ content       │
                       │ created_at    │
                       │ is_deleted    │
                       └───────────────┘
```

### 表详细设计

#### 1. users 表（用户表）

| 字段名            | 类型           | 约束                                   | 说明                |
| -------------- | ------------ | ------------------------------------ | ----------------- |
| id             | INT          | PRIMARY KEY, AUTO\_INCREMENT         | 用户唯一标识            |
| username       | VARCHAR(50)  | NOT NULL, UNIQUE, INDEX              | 用户名，唯一            |
| password\_hash | VARCHAR(255) | NOT NULL                             | 密码哈希值（bcrypt加密）   |
| email          | VARCHAR(100) | UNIQUE, INDEX                        | 邮箱地址，可选           |
| created\_at    | DATETIME     | DEFAULT CURRENT\_TIMESTAMP           | 创建时间              |
| updated\_at    | DATETIME     | DEFAULT CURRENT\_TIMESTAMP ON UPDATE | 更新时间              |
| is\_deleted    | TINYINT(1)   | DEFAULT 0                            | 软删除标记（0=正常，1=已删除） |

#### 2. notes 表（笔记表）

| 字段名         | 类型           | 约束                                   | 说明              |
| ----------- | ------------ | ------------------------------------ | --------------- |
| id          | INT          | PRIMARY KEY, AUTO\_INCREMENT         | 笔记唯一标识          |
| user\_id    | INT          | NOT NULL, INDEX, FOREIGN KEY         | 所属用户ID          |
| title       | VARCHAR(200) | NOT NULL, INDEX                      | 笔记标题            |
| content     | TEXT         | NULL                                 | 笔记正文内容          |
| summary     | VARCHAR(200) | NULL                                 | AI生成的摘要（30-50字） |
| tags        | VARCHAR(200) | NULL                                 | 标签，逗号分隔         |
| created\_at | DATETIME     | DEFAULT CURRENT\_TIMESTAMP           | 创建时间            |
| updated\_at | DATETIME     | DEFAULT CURRENT\_TIMESTAMP ON UPDATE | 更新时间            |
| is\_deleted | TINYINT(1)   | DEFAULT 0                            | 软删除标记           |

**外键约束**: `user_id` REFERENCES `users(id)` ON DELETE CASCADE

#### 3. chat\_sessions 表（对话会话表）

| 字段名         | 类型          | 约束                                   | 说明               |
| ----------- | ----------- | ------------------------------------ | ---------------- |
| id          | INT         | PRIMARY KEY, AUTO\_INCREMENT         | 会话唯一标识           |
| user\_id    | INT         | NOT NULL, INDEX, FOREIGN KEY         | 所属用户ID           |
| note\_id    | INT         | NOT NULL, UNIQUE, INDEX, FOREIGN KEY | 关联笔记ID（一篇笔记一个会话） |
| session\_id | VARCHAR(50) | NOT NULL                             | Dify平台的会话ID      |
| created\_at | DATETIME    | DEFAULT CURRENT\_TIMESTAMP           | 创建时间             |
| updated\_at | DATETIME    | DEFAULT CURRENT\_TIMESTAMP ON UPDATE | 更新时间             |
| is\_deleted | TINYINT(1)  | DEFAULT 0                            | 软删除标记            |

**外键约束**:

- `user_id` REFERENCES `users(id)` ON DELETE CASCADE
- `note_id` REFERENCES `notes(id)` ON DELETE CASCADE

#### 4. chat\_messages 表（对话消息表）

| 字段名               | 类型          | 约束                           | 说明                 |
| ----------------- | ----------- | ---------------------------- | ------------------ |
| id                | INT         | PRIMARY KEY, AUTO\_INCREMENT | 消息唯一标识             |
| chat\_session\_id | INT         | NOT NULL, INDEX, FOREIGN KEY | 所属会话ID             |
| role              | VARCHAR(20) | NOT NULL                     | 角色（user/assistant） |
| content           | TEXT        | NOT NULL                     | 消息内容               |
| created\_at       | DATETIME    | DEFAULT CURRENT\_TIMESTAMP   | 创建时间               |
| is\_deleted       | TINYINT(1)  | DEFAULT 0                    | 软删除标记              |

**外键约束**: `chat_session_id` REFERENCES `chat_sessions(id)` ON DELETE CASCADE

### 数据库建表SQL

```sql
CREATE DATABASE IF NOT EXISTS ai_note_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

USE ai_note_db;

-- 用户表
CREATE TABLE IF NOT EXISTS users (
    id INT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    password_hash VARCHAR(255) NOT NULL,
    email VARCHAR(100) UNIQUE,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    is_deleted TINYINT(1) DEFAULT 0,
    INDEX idx_users_username (username),
    INDEX idx_users_email (email)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 笔记表
CREATE TABLE IF NOT EXISTS notes (
    id INT AUTO_INCREMENT PRIMARY KEY,
    user_id INT NOT NULL,
    title VARCHAR(200) NOT NULL,
    content TEXT,
    summary VARCHAR(200),
    tags VARCHAR(200),
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    is_deleted TINYINT(1) DEFAULT 0,
    INDEX idx_notes_user_id (user_id),
    INDEX idx_notes_title (title),
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 对话会话表
CREATE TABLE IF NOT EXISTS chat_sessions (
    id INT AUTO_INCREMENT PRIMARY KEY,
    user_id INT NOT NULL,
    note_id INT NOT NULL UNIQUE,
    session_id VARCHAR(50) NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    is_deleted TINYINT(1) DEFAULT 0,
    INDEX idx_chat_sessions_user_id (user_id),
    INDEX idx_chat_sessions_note_id (note_id),
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
    FOREIGN KEY (note_id) REFERENCES notes(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 对话消息表
CREATE TABLE IF NOT EXISTS chat_messages (
    id INT AUTO_INCREMENT PRIMARY KEY,
    chat_session_id INT NOT NULL,
    role VARCHAR(20) NOT NULL,
    content TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    is_deleted TINYINT(1) DEFAULT 0,
    INDEX idx_chat_messages_chat_session_id (chat_session_id),
    FOREIGN KEY (chat_session_id) REFERENCES chat_sessions(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

***

## 业务流程设计

### 1. 用户注册流程

```mermaid
flowchart TD
    A[用户访问登录页] --> B{是否已有账号?}
    B -->|否| C[点击注册链接]
    B -->|是| D[直接登录]
    C --> E[填写注册表单]
    E --> F[前端表单验证]
    F -->|验证失败| G[显示错误提示]
    F -->|验证成功| H[调用注册API]
    H --> I[后端校验用户名唯一性]
    I -->|用户名已存在| J[返回错误]
    I -->|用户名可用| K[密码bcrypt加密]
    K --> L[插入用户记录]
    L --> M[返回成功]
    M --> N[自动跳转到登录页]
```

### 2. 用户登录流程

```mermaid
flowchart TD
    A[用户填写登录表单] --> B[前端表单验证]
    B -->|验证失败| C[显示错误提示]
    B -->|验证成功| D[调用登录API]
    D --> E[后端验证用户名]
    E -->|用户不存在| F[返回错误]
    E -->|用户存在| G[验证密码]
    G -->|密码错误| H[返回错误]
    G -->|密码正确| I[生成JWT令牌]
    I --> J[返回令牌和用户信息]
    J --> K[前端保存到localStorage]
    K --> L[跳转到笔记列表页]
```

### 3. 笔记CRUD流程

#### 创建笔记

```mermaid
flowchart TD
    A[用户点击新建笔记] --> B[进入编辑页面]
    B --> C[填写笔记标题]
    C --> D{是否使用AI工具?}
    D -->|是| E[调用AI生成摘要/标签]
    E --> F[结果回填到表单]
    D -->|否| F
    F --> G[点击保存]
    G --> H[前端验证]
    H -->|失败| I[显示错误]
    H -->|成功| J[调用创建API]
    J --> K[后端验证权限]
    K --> L[插入笔记记录]
    L --> M[返回成功]
    M --> N[跳转到笔记列表]
```

#### 笔记列表与搜索

```mermaid
flowchart TD
    A[进入笔记列表页] --> B[调用列表API]
    B --> C[后端查询用户笔记]
    C --> D{是否有搜索关键词?}
    D -->|是| E[模糊搜索标题/内容/标签]
    D -->|否| E[查询全部]
    E --> F[分页处理]
    F --> G[返回结果]
    G --> H[前端渲染列表]
    H --> I[用户翻页/搜索]
    I --> B
```

#### 笔记编辑与删除

```mermaid
flowchart TD
    A[点击编辑/删除] --> B{操作类型}
    B -->|编辑| C[进入编辑页]
    B -->|删除| D[确认删除]
    D -->|取消| E[返回列表]
    D -->|确认| F[调用删除API]
    F --> G[软删除标记]
    G --> H[返回成功]
    H --> I[刷新列表]
    C --> J[加载笔记数据]
    J --> K[修改内容]
    K --> L[调用更新API]
    L --> M[更新记录]
    M --> I
```

### 4. AI生成流程

```mermaid
flowchart TD
    A[用户点击AI工具按钮] --> B{工具类型}
    B -->|生成摘要| C[获取笔记内容]
    B -->|推荐标签| D[获取标题+内容]
    B -->|文本纠错| E[获取内容]
    C --> F[调用Dify生成型API]
    D --> F
    E --> F
    F --> G[构造prompt]
    G --> H[发送请求]
    H --> I[接收响应]
    I --> J[解析结果]
    J --> K[回填到表单]
```

### 5. AI对话流程

```mermaid
flowchart TD
    A[进入对话页面] --> B[调用历史消息API]
    B --> C[查询会话是否存在]
    C -->|存在| D[加载历史消息]
    C -->|不存在| E[创建新会话]
    E --> F[调用Dify创建会话]
    F --> G[保存会话记录]
    G --> D
    D --> H[渲染消息列表]
    H --> I[用户输入消息]
    I --> J[点击发送]
    J --> K[调用发送消息API]
    K --> L[保存用户消息]
    L --> M[调用Dify对话API]
    M --> N[接收AI响应]
    N --> O[保存AI消息]
    O --> P[返回结果]
    P --> Q[渲染新消息]
    Q --> I
```

### 6. 预设快捷指令流程

```mermaid
flowchart TD
    A[用户点击预设按钮] --> B[获取笔记内容]
    B --> C[填充指令模板]
    C --> D[设置到输入框]
    D --> E[用户点击发送]
    E --> F[按正常对话流程处理]
```

***

## 快速开始

### 1. 环境要求

- Python 3.10+
- MySQL 5.7+

### 2. 数据库创建

执行上述**数据库建表SQL**创建数据库和表结构。

### 3. 环境变量配置

复制 `.env.example` 为 `.env` 并配置：

```env
APP_ENV=development
APP_HOST=0.0.0.0
APP_PORT=8000

DATABASE_URL=mysql+pymysql://username:password@localhost:3306/ai_note_db

JWT_SECRET_KEY=your-secret-key-here-must-be-at-least-32-characters
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=30

DIFY_API_KEY=your-dify-api-key-here
DIFY_API_BASE_URL=https://api.dify.ai/v1
```

### 4. Dify应用搭建

1. 登录 [Dify](https://dify.ai) 创建账号
2. 创建一个"对话应用"
3. 在应用设置中获取API Key
4. 将API Key填入 `.env` 文件的 `DIFY_API_KEY`

### 5. 安装依赖

```bash
cd backend
pip install -r requirements.txt
```

### 6. 启动项目

```bash
cd backend
python -m uvicorn app.main:app --reload
```

### 7. 访问地址

- **后端API**: <http://localhost:8000>
- **前端页面**: 通过HTTP服务器访问 `frontend/templates/login.html`

***

## API接口

### 用户管理

| 接口                       | 方法   | 描述       | 需要认证 |
| ------------------------ | ---- | -------- | ---- |
| `/api/v1/users/register` | POST | 用户注册     | 否    |
| `/api/v1/users/login`    | POST | 用户登录     | 否    |
| `/api/v1/users/me`       | GET  | 获取当前用户信息 | 是    |
| `/api/v1/users/logout`   | POST | 退出登录     | 是    |

### 笔记管理

| 接口                        | 方法     | 描述            | 需要认证 |
| ------------------------- | ------ | ------------- | ---- |
| `/api/v1/notes`           | GET    | 获取笔记列表（分页+搜索） | 是    |
| `/api/v1/notes`           | POST   | 创建笔记          | 是    |
| `/api/v1/notes/{note_id}` | GET    | 获取笔记详情        | 是    |
| `/api/v1/notes/{note_id}` | PUT    | 更新笔记          | 是    |
| `/api/v1/notes/{note_id}` | DELETE | 删除笔记（软删除）     | 是    |

### AI生成

| 接口                     | 方法   | 描述   | 需要认证 |
| ---------------------- | ---- | ---- | ---- |
| `/api/v1/ai/summary`   | POST | 生成摘要 | 是    |
| `/api/v1/ai/tags`      | POST | 生成标签 | 是    |
| `/api/v1/ai/proofread` | POST | 文本纠错 | 是    |

### AI对话

| 接口                               | 方法   | 描述     | 需要认证 |
| -------------------------------- | ---- | ------ | ---- |
| `/api/v1/chat/message`           | POST | 发送消息   | 是    |
| `/api/v1/chat/history/{note_id}` | GET  | 获取对话历史 | 是    |
| `/api/v1/chat/clear`             | POST | 清空对话   | 是    |
| `/api/v1/chat/preset-commands`   | GET  | 获取预设指令 | 是    |

***

## 响应格式

所有接口统一返回格式：

```json
{
    "code": 200,
    "message": "success",
    "data": {}
}
```

**状态码说明**:

- `200` - 成功
- `201` - 创建成功
- `400` - 请求参数错误
- `401` - 未授权（需要登录）
- `403` - 禁止访问（权限不足）
- `404` - 资源不存在
- `500` - 服务器内部错误

***

## 注意事项

1. 请确保MySQL服务正常运行，并正确配置数据库连接信息
2. Dify API Key需要正确配置才能使用AI功能，否则AI相关接口将返回失败提示
3. 前端页面需要通过HTTP服务器访问（如Python http.server或Live Server），不能直接双击打开
4. JWT\_SECRET\_KEY需要设置至少32个字符的密钥，建议使用随机生成的安全密钥
5. 所有数据库查询都会自动过滤 `is_deleted=0` 的记录，实现软删除逻辑
6. 用户只能操作自己的数据，后端会自动校验用户权限