# wkstudy

**Repository Path**: qinyongcheng/wkstudy

## Basic Information

- **Project Name**: wkstudy
- **Description**: Java基础框架
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 24
- **Forks**: 37
- **Created**: 2025-09-01
- **Last Updated**: 2026-09-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Wkstudy 悟空学习平台 —— 项目使用说明

Wkstudy（悟空学习平台）是一套**前后端分离**的教学级全栈项目：

- **[后端 wkstudy-backend](./wkstudy-backend/README.md)**：基于 Spring Boot 4 的 Maven 多模块工程，提供用户/角色/权限管理（RBAC）、Sa-Token + JWT 认证、MyBatis-Plus 数据访问、AI 智能体对话（AgentScope + DeepSeek，已独立为 `agent` 模块）、**知识图谱服务（`kg` 模块，Spring Data Neo4j + 原生 Cypher）**、后端代码生成器等能力；
- **[前端 wkstudy-frontend](./wkstudy-frontend/admin/README.md)**：由两个子工程组成——
  - **admin**（[教程](./wkstudy-frontend/admin/README.md)）：基于 Vue 3 + TypeScript + Vite + Element Plus 的后台管理系统，内置动态权限路由、国际化、图表看板，以及**基于 OpenAPI 协议的前端代码生成器**；
  - **agent**（[模板说明](./wkstudy-frontend/agent/README.md)）：基于 Vue 3.5 + Element-Plus-X + hook-fetch 的 **AI 对话前端**（仿豆包/通义聊天界面），对接后端智能体流式接口，支持会话管理、打字机效果、思考过程与工具调用展示。

前后端的代码生成器是配套关系：后端生成器根据数据库表生成后端 CRUD 模块，前端生成器读取后端 OpenAPI 接口文档生成前端页面与 API 调用代码，组合使用可实现"建表 → 后端接口 → 前端页面"的快速开发闭环。

---

## 一、仓库结构

```
wkstudy/                       # 项目根目录
├── wkstudy-backend/           # 后端工程（Spring Boot 4 多模块）
│   ├── common/                #   通用基础：Result 统一响应、错误码、业务异常、分页 DTO
│   ├── contract/              #   契约模块：跨模块共享 DTO（登录/注册/AI 请求等）
│   ├── core/                  #   核心模块：全局配置、通用 CRUD 基类、全局异常/响应处理
│   ├── sys/                   #   系统业务：用户/角色/权限/字典/日志、Sa-Token 认证、微信登录
│   ├── agent/                #   AI 智能体模块：AgentScope 会话/对话/模型管理（独立模块）
│   ├── kg/                    #   知识图谱模块：Neo4j 图数据库读写、动态 Schema、图谱元数据管理
│   ├── generator/             #   代码生成器：基于数据库表生成完整 CRUD 模块（FreeMarker 模板）
│   ├── testu/                 #   教学示例模块：TestUser 单表 CRUD 完整示例（生成器产物）
│   ├── application/           #   启动模块：WkstudyApplication + 全部配置文件（唯一可执行 jar）
│   └── wkstudy.sql            #   数据库建表脚本（含 sys_* 核心 RBAC 表与示例表 test_user）
├── wkstudy-frontend/
│   ├── admin/                 # 前端后台管理工程（Vue3 + Vite + Element Plus + 代码生成器）
│   │   └── README.md          #   前端完整使用教程
│   └── agent/                 # 前端 AI 对话工程（Vue3.5 + Element-Plus-X + hook-fetch）
├── README.md                  # 本文件（项目总使用说明）
├── README.en.md               # 英文版说明
└── LICENSE                    # MIT 开源协议
```

---

## 二、端口与地址约定

| 服务 | 地址 | 说明 |
|------|------|------|
| 后端 API | `http://127.0.0.1:8080` | Spring Boot，dev 环境默认 |
| 后端接口文档 | `http://127.0.0.1:8080/doc.html` | Knife4j（另有 Swagger UI） |
| 后端 OpenAPI 文档 | `http://127.0.0.1:8080/v3/api-docs` | 供前端代码生成器读取 |
| 前端管理后台 | `http://localhost:3000` | admin 工程 Vite 开发服务器 |
| 前端 AI 对话 | `http://localhost:5173` | agent 工程 Vite 开发服务器（默认端口） |
| MySQL | `localhost:3306` | 业务库名 `wkstudy` |
| Redis | `localhost:6379` | Sa-Token 会话、AI 会话、图谱 Schema 缓存 |
| Neo4j Bolt | `neo4j://localhost:7687` | 知识图谱图数据库（配置于 `application-dev.yml`） |
| Neo4j 浏览器 | `http://localhost:7474` | Neo4j Browser，可视化查看图谱 |

---

## 三、环境准备（总清单）

| 软件 | 版本要求 | 用途 |
|------|----------|------|
| JDK | 24（必须） | 后端编译运行 |
| Maven | 3.9+ | 后端构建 |
| MySQL | 8.x / 9.x | 业务数据库（图谱标签/关系元数据亦存于此） |
| Redis | 任意稳定版 | 会话与缓存 |
| Neo4j | 5.x（社区版即可） | 知识图谱图数据库（不用图谱功能可不装，但启动会告警） |
| Node.js | 20.19+ 或 22.12+ | 前端构建（Vite 7 要求） |
| IDE | IntelliJ IDEA（后端）+ HBuilder X / VS Code（前端，装 Volar 插件） | 开发工具 |
| 大模型 API Key | DeepSeek 等 OpenAI 兼容服务 | AI 对话功能（可选） |

软件百度网盘下载地址链接: https://pan.baidu.com/s/1mSNDTumgqJpbBt2UXKeTZA?pwd=8hd8 提取码: 8hd8 --来自百度网盘超级会员v7的分享

---

## 四、首次运行完整步骤

### 第 1 步：初始化数据库

1. 启动本机 MySQL，创建业务库：

```sql
CREATE DATABASE wkstudy DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
```

2. 导入建表脚本：可参考 `wkstudy-backend/wkstudy.sql`（含 `sys_user`、`sys_role`、`sys_permission`、`sys_user_role`、`sys_role_permission`、`test_user` 及 `kg_graph_nodelabel`、`kg_graph_rellabel` 等核心表），或按后端 README 第三节的表清单自行建表；

3. 执行权限初始化脚本（可选，基础系统已经导入了权限数据）（如 `wkstudy-backend/testu/src/main/java/com/wkstudy/testu/permissions_init.sql`（已经有部分权限））并完成"权限 → 角色 → 用户"的授权。
### 第 2 步：安装redis缓存数据库

### 第 3 步：启动图数据库（使用知识图谱功能时）（如果暂时用不到图数据库跳过）

1. 安装并启动 Neo4j（推荐 5.x 社区版），首次启动设置密码；
2. 浏览器访问 <http://localhost:7474> 验证服务可用。

### 第 4 步：启动并配置后端

详细步骤见 **`wkstudy-backend/README.md`**，要点：

1. 修改 `wkstudy-backend/application/src/main/resources/application-dev.yml` 中的 MySQL 账号密码、Redis 地址、Neo4j 连接（`spring.neo4j.uri` / `username` / `password`）、AI API Key、Sa-Token 密钥；
2. IDEA 运行 `WkstudyApplication`，或命令行：

```bash
cd wkstudy-backend
mvn clean package -DskipTests
java -jar application/target/application-0.0.2.jar
```

3. 验证：访问 <http://127.0.0.1:8080/doc.html> 能打开 Knife4j 接口文档即成功。

### 第 5 步：启动前端

**管理后台（admin）**——详细步骤见 **`wkstudy-frontend/admin/README.md`**，要点：
**首先要安装nodejs**。然后用开发工具或下面命令打开项目并安装依赖。
```bash
cd wkstudy-frontend/admin
npm install          # 首次安装依赖
npm run dev          # 启动开发服务器（默认 3000 端口）
```

安装前确认 `wkstudy-frontend/admin/.env.development` 中 `VITE_APP_BASE_API` 指向后端地址（默认 `http://127.0.0.1:8080`）。

**AI 对话（agent）**——若需要体验聊天界面：

```bash
cd wkstudy-frontend/agent
pnpm install         # 或 npm install（项目自带 pnpm-lock.yaml）
npm run dev          # 启动开发服务器（默认 5173 端口）
```

`agent` 工程通过 `.env.development` 中的 `VITE_API_URL`（默认 `http://127.0.0.1:8080`）指向后端，`VITE_WEB_BASE_API`（默认 `/dev-api`）为请求前缀。

### 第 5 步：登录使用

1. 浏览器访问 <http://localhost:3000>，进入登录页；
2. 使用后端注册的账号登录（登录框默认填充 `admin / admin123`，请以数据库实际账号为准），输入验证码提交；
3. 登录成功进入控制台（Dashboard），左侧菜单按你的角色动态渲染；
4. 后端尚未就绪时，可在登录页右上角切换为「游客」模式（仅开发环境显示），本地模拟 `dev` 角色全权限，用于页面开发与代码生成器调试；
5. AI 对话页面（<http://localhost:5173>）登录后即可创建会话，与智能体流式对话。

---

## 五、典型使用场景

### 5.1 日常开发联调

1. 启动 MySQL、Redis、（可选 Neo4j）→ 启动后端（8080）→ 启动前端（3000 / 5173）；
2. 前端所有接口请求经 `src/utils/request.ts`（admin）/ hook-fetch 封装（agent）统一携带 `Authorization: Bearer <token>` 访问后端；
3. 后端接口变更后，可在 Knife4j（`/doc.html`）在线调试确认，再到前端对接。

### 5.2 新增一个业务模块（前后端代码生成器配合，推荐流程）

完整链路：**建表（按规范写注释）→ 后端生成 → 微调实体/DTO → 前端生成**。两份生成器的详细 step-by-step 教程见 [后端 README 5.4 节](./wkstudy-backend/README.md#54-代码生成器--从建表到后端模块一键生成重点教程) 与 [前端 admin README 第六节](./wkstudy-frontend/admin/README.md#六代码生成器使用教程重点特色)，此处为速览：

1. **设计数据库表**并在 `wkstudy` 库中创建，注意五条规范：
   - 表和字段的注释统一写成「**名称：说明**」格式（如 `course_name varchar(100) COMMENT '课程名称：课程的显示名称'`），生成器据此产出接口文档与前端页面上的字段显示名与描述；
   - 每张表包含 `WkBaseEntity` 的 6 个通用字段（`id`、`create_time`、`update_time`、`is_enabled`、`sort_order`、`is_deleted`）；
   - 表名按**业务前缀**区分（如 `cms_*`），一个前缀生成一个 Maven 模块；
   - 布尔语义字段以 `is` 开头（前端自动生成开关控件）；状态/字典字段在注释中写明取值（如 `状态：0=草稿，1=已发布，2=已下架`，前端自动生成下拉框）；  
   - 需要上传图片/文件的字段，在注释说明中追加 `@upload=image`（图片）或 `@upload=file`（文件）指令（如 `封面：文章封面图 @upload=image`），后端自动生成模块上传策略、前端自动生成上传控件，详见 [后端 README 5.4.1 规范 7](./wkstudy-backend/README.md)；

   下面义cms内容管理系统模块的文章表为例：
```sql
CREATE TABLE `cms_article` (
  `id`          bigint       NOT NULL AUTO_INCREMENT COMMENT '编号：主键ID',
  `title`       varchar(255) NOT NULL COMMENT '标题：文章标题',
  `content`     text         NULL COMMENT '内容：文章内容',
  `create_time` datetime     NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '添加时间',
  `update_time` datetime     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改日期',
  `is_enabled`  tinyint      NULL DEFAULT 1 COMMENT '是否启用：0=禁用，1=启用',
  `sort_order`  int          NULL DEFAULT 0 COMMENT '排序',
  `is_deleted`  tinyint      NULL DEFAULT 0 COMMENT '逻辑删除：0=否，1=是',
  PRIMARY KEY (`id`),
  KEY `idx_title` (`title`) COMMENT '标题索引（加速标题查询）',
  KEY `idx_enabled_sort` (`is_enabled`, `sort_order`) COMMENT '启用状态+排序复合索引（加速按状态和排序的列表查询）'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='文章：存储文章内容的表';
```
2. **后端生成**：调用后端代码生成器接口 `/api/v1/codegen/gen`（或前端「代码生成 → 后端生成」页面），按前缀生成整个 Maven 业务模块（entity/dao/service/controller/DTO/VO/converter/权限脚本，并自动注册进父 pom）；刷新 Maven、执行生成的 `permissions_init.sql`、给角色授权；
3. **微调实体/DTO**：按需调整 `@Schema` 元数据；状态类字段可改为 Java 枚举（接口文档输出枚举值，前端生成器按枚举生成下拉框，优先级最高）；
4. **重启后端**，maven清理生成的模块，并重新构建项目确认没问题，然后重启后端，并确认新模块已出现在 `/v3/api-docs` 文档中；
5. **前端生成**：以开发者身份登录前端 admin（认证或游客模式），进入「代码生成 → 页面生成」，按三步向导（设置参数 → 勾选新模块标签组 → 生成页面）一键生成 API 调用、TS 类型、增删改查页面与路由；
6. 按 F5 刷新浏览器，左侧出现新菜单，即可直接对新表进行增删改查操作。

> **业务表存在外键（指向其它业务表的 ID）怎么办？** 完全无需手工编写联表 SQL 与下拉组件，按下面的链路全自动生成：
> - **建表阶段**：在字段注释里写 `@ref 目标表.关联列 @label 显示字段`（或建物理外键约束，或使用 `parent_id` 自关联），详见 [后端 README 5.4.1 规范 6](./wkstudy-backend/README.md)；
> - **后端阶段**：生成器会自动产出 `xxxId + xxxName` 双字段、`Mapper.selectPageWithJoin`（LEFT JOIN 联表）、`@SelectOptions` 注解，详见 [后端 README 5.4.2「含外键字段时」](./wkstudy-backend/README.md) 与 [5.4.3「⑤」](./wkstudy-backend/README.md)；
> - **前端阶段**：表单自动渲染为「远程下拉 / 树形下拉」，列表自动追加 `xxxName` 显示列，详见 [前端 admin README 6.2.2 / 6.2.3](./wkstudy-frontend/admin/README.md)；常见下拉异常见 [6.5 外键下拉框常见问题排查](./wkstudy-frontend/admin/README.md)。

> **字段需要上传图片/文件怎么办？** 在字段注释的说明部分追加指令即可全自动生成：`@upload=image`（图片）或 `@upload=file`（普通文件），如 `COMMENT '封面：文章封面图 @upload=image'`。后端会为模块自动生成上传策略类（`POST /file/upload/<模块名>` 直接可用，文件存 `uploads/<模块名>/日期/`），前端表单自动渲染上传控件（图片带预览）。注意指令**不含连字符**。详见 [后端 README 5.4.1 规范 7](./wkstudy-backend/README.md)。

### 5.3 AI 智能体对话（agent 模块）

后端 `agent` 模块（独立于 sys）提供以下接口（均需登录）：

| 接口 | 说明 |
|------|------|
| `POST /api/v1/agent/chat` | 同步对话（阻塞式，优先使用流式） |
| `POST /api/v1/agent/chat/stream` | SSE 流式对话（OpenAI 标准格式） |
| `POST /api/v1/agent/session/create` | 为当前用户创建全新会话 |
| `GET /api/v1/agent/session/list` | 分页获取会话列表（不含聊天记录） |
| `GET /api/v1/agent/session/{id}` | 获取会话完整记录（含思考过程、工具调用） |
| `DELETE /api/v1/agent/session/{id}` | 删除指定会话 |
| `GET /api/v1/agent/model/list` | 获取全部模型配置列表 |

智能体基于 AgentScope-Java 构建全局单例 `HarnessAgent`：会话历史持久化到 Redis（多实例共享）、记忆自动压缩（累计 30 条触发）、内置 `get_today_time` 与 `db_select_query`（仅 SELECT）两个演示工具。需要有效的 DeepSeek（或 OpenAI 兼容）API Key，配置在后端 `application-dev.yml` 的 `me.ai.deepseek` 节点。前端 agent 工程即为该能力的完整 UI 实现。

### 5.4 知识图谱（kg 模块）

`kg` 模块基于 **Spring Data Neo4j（Neo4jClient + 原生 Cypher）** 提供图谱读写能力，核心接口（路由前缀 `/api/v1/kg-graph-writer`）：

- **节点**：`create-node` / `save-node` / `batch-save-nodes` / `update-node-by-id` / `delete-node-by-id` / `list-nodes` / `list-nodes-page` / `search-nodes-page` / `node/detail` / `count-nodes` / `node/add-label` 等；
- **关系**：`create-relation` / `save-relation` / `batch-save-relations` / `update-relation-by-id` / `delete-relation-by-id` / `delete-all-relations-of-reltype` 等；
- **元数据**：`/api/v1/kg-graph-nodelabel` 与 `/api/v1/kg-graph-rellabel` 维护节点标签、关系类型清单；`/api/v1/kg-graph-schema/refresh` 强制刷新 Schema 缓存，`/clear-cache` 清空缓存；
- **教学示例**：`/kg/movie` 电影-演员-角色图谱示例（创建电影自动建演员关系）。

技术要点：图谱 Schema（合法节点标签与关系类型）存放于 MySQL 的 `kg_graph_nodelabel` / `kg_graph_rellabel` 表，运行时经 **Redis 缓存 + 动态 Cypher 白名单**校验，防止 Cypher 注入；Redis 不可用时自动降级为本地内存缓存。启动前需在 `application-dev.yml` 的 `spring.neo4j` 节点配置连接信息。

---

## 六、打包部署

| 端 | 命令 | 产物 |
|----|------|------|
| 后端 | `mvn clean package -DskipTests`（在 `wkstudy-backend` 下） | `application/target/application-0.0.2.jar`，用 `java -jar` 运行（生产加 `--spring.profiles.active=prod`） |
| 前端 admin | `npm run build:prod`（在 `wkstudy-frontend/admin` 下） | `dist/` 静态文件，部署到 Nginx/CDN（Hash 路由，无需特殊服务器配置） |
| 前端 agent | `npm run build`（在 `wkstudy-frontend/agent` 下） | `dist/` 静态文件，`vue-tsc` 类型检查 + Vite 构建 |

部署检查清单：

- [ ] MySQL、Redis（、Neo4j）可达且生产配置正确（建议用环境变量覆盖密码类信息）；
- [ ] 后端 `sa-token.jwt-secret-key` 已改为随机强密钥；
- [ ] AI `api-key` 已替换为生产 Key；
- [ ] 前端 `.env.production` 中 `VITE_APP_BASE_API` 指向线上后端地址；
- [ ] 服务器防火墙放行 8080（后端）与 80/443（前端站点）端口。

---

## 七、常见问题（FAQ）

**Q1：必须先启动哪个服务？**
先 MySQL → Redis → Neo4j（如用图谱）→ 后端 → 前端。前端本身可独立启动（游客模式），但真实登录与业务数据依赖后端。

**Q2：前后端跨域怎么办？**
开发期直连后端地址（后端已支持跨域）；如有特殊限制，可在前端 `vite.config.ts` 的 `server.proxy` 配置反向代理；生产环境建议前后端同域部署或由 Nginx 统一转发。

**Q3：登录后提示无权限（401/403）？**
本项目鉴权设计为「URL 自动转权限码」（见后端 README 5.2 节），新接口必须在 `sys_permission` 表登记权限码并分配给角色；改完授权可调用 `/auth/refresh-rolepermission` 刷新缓存。前端菜单不显示则检查账号角色与路由 `meta.roles` 是否匹配。

**Q4：`wkstudy.sql` 导入后库名对不上？**
该脚本导出自 `wkstudy` 库，请将表导入到 `wkstudy` 库（或修改后端数据源 URL 指向你的库名）。

**Q5：Neo4j 连接失败 / 图谱接口报错？**
检查 `application-dev.yml` 中 `spring.neo4j.uri`（默认 `neo4j://localhost:7687`）与账号密码；社区版默认使用 `neo4` 数据库，不能动态切换库。不使用图谱功能时该报错不影响其他模块运行。

**Q6：AI 对话报 401 / 模型调用失败？**
检查 `me.ai.deepseek.api-key` 是否有效；DeepSeek 兼容 OpenAI 协议，也可换成智谱 GLM 等服务，只需改 `base-url` 与 `model-name`。

**Q7：想学习项目源码从哪里入手？**
- 后端：`Result`（common）→ `WkBaseController`（core）→ `TestUserController`（testu）的继承链，再读 `SaTokenConfigure`（sys，RBAC）→ `ChatController`（agent，AI 流式）→ `KgGraphWriterController`（kg，图谱读写）；
- 前端 admin：`main.ts` → `permission.ts`（路由守卫）→ `store/modules/user.ts`（登录态）→ `utils/request.ts`（请求层）→ `codegen/`（代码生成器）；
- 前端 agent：`src/main.ts` → `src/api/chat`（SSE 流式解析）→ `src/stores`（会话状态）。

---

## 八、更多文档（参考各自模块）

| 文档 | 位置 |
|------|------|
| 后端完整使用教程（技术栈、快速开始、接口说明、代码生成器、AI 对话、FAQ） | `wkstudy-backend/README.md` |
| 后端智能体模块说明（AgentScope 架构与配置） | `wkstudy-backend/agent/README.md` |
| 前端管理后台完整使用教程（技术栈、目录结构、登录与权限、前端代码生成器、打包部署、FAQ） | `wkstudy-frontend/admin/README.md` |
| 前端 AI 对话工程模板说明（ruoyi-element-ai） | `wkstudy-frontend/agent/README.md` |
| 前端依赖逐项说明 | `wkstudy-frontend/admin/package-comment.md` |
| 数据库建表脚本 | `wkstudy.sql` |