# SubjStudio

**Repository Path**: codekpy/subj-studio

## Basic Information

- **Project Name**: SubjStudio
- **Description**: 人人都是学科创作者
SubjStudio 是一个基于 AI 辅助的学科交互式内容共创平台，让高中生、教师与开发者无需深厚代码基础，也能轻松创作、分享与协作开发物理、化学、数学等学科的可视化模拟演示。
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-16
- **Last Updated**: 2026-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SubjStudio

> **人人都是学科创作者**
> *Empowering Everyone to Create Interactive Learning*

SubjStudio 是一个基于 AI 辅助的学科交互式内容共创平台，让高中生、教师与开发者无需深厚代码基础，也能轻松创作、分享与协作开发物理、化学、数学等学科的可视化模拟演示。

**核心闭环**: 用户聊天 → AI 生成单文件 HTML → 预览/编辑 → 一键推送至 SubjEngine 仓库

***

## 目录

- [项目定位](#-项目定位)
- [核心功能](#-核心功能)
- [技术架构](#-技术架构)
- [快速开始](#-快速开始)
- [API 参考](#-api-参考)
- [数据库设计](#-数据库设计)
- [部署指南](#-部署指南)
- [参与贡献](#-参与贡献)

***

## 📌 项目定位

让抽象知识「看得见、摸得着、玩得转」，让每一个有创意的学习者，都能成为知识的「创作者」而非「消费者」。

### 目标用户

| 用户类型    | 使用场景                                       |
| ------- | ------------------------------------------ |
| **高中生** | 通过可视化模拟理解抽象概念（如电场、化学反应、函数图像）               |
| **教师**  | 快速创建课堂演示素材，辅助教学讲解                          |
| **开发者** | 利用 AI 辅助快速交付学科演示 HTML 页面，推送至 SubjEngine 仓库 |

***

## 🌟 核心功能

### 🤖 AI 智能创作

- **自然语言生成模拟**：输入学科需求，AI 自动生成可视化演示代码（自包含单文件 HTML）
- **Function Call 工具链**：7 个 tool 实现文件写入、模板读取、问题确认、TODO 管理、项目信息获取等
- **内容审查机制**：前端请求实时过滤（检测恶意脚本/外链）+ 后端 AI 异步审核
- **流式输出**：支持实时 AI 响应（含 reasoning\_content 思维链），前端 Socket.IO 转发

### 🧩 用户前台

- **首页瀑布流**：公开项目展示，综合排序算法（点赞×0.3 + 浏览×0.2 + 时间衰减×0.5）
- **项目管理**：个人项目列表，支持新建/编辑/学科/年级标签筛选，按时间降序排列
- **Studio 创作空间**：左右布局（左侧 iframe 实时预览 + 右侧 AI 聊天面板）
- **收藏系统**：收藏喜欢的项目，个人收藏页管理
- **用户主页**：公开项目展示 + AI 编辑热力图

### 🛡️ 管理后台

- **多级权限体系**：三级角色（user / partial\_admin / super\_admin）+ adminList 动态权限
- **项目管理**：编辑简介 / AI 重审 / Git 推送 / 取消发布
- **用户管理**：修改信息 / 冻结 / 权限分配（权限感知，只读时邮箱脱敏）
- **AI & SMTP 动态配置**：运行时通过 system\_config 表管理，修改即生效（无需重启）
- **实时通知**：WebSocket 推送推送完成/审核结果通知

### 🔗 Git 集成

- **自动推送**：项目文件复制到学科目录（按学科映射英文目录名），追加 list.json
- **中文文件名自动转译**：内置中→英映射表（50+ 学科关键词），剩余中文 fallback 为 charCode
- **版本管理**：git pull → 复制 → commit → push 自动化流程，自动切 development 分支

***

## ⚙️ 技术架构

| 层级         | 技术选型                               | 说明                                 |
| ---------- | ---------------------------------- | ---------------------------------- |
| **前端**     | Vue 3 + TypeScript + Vite          | Composition API, 单文件组件             |
| **前端样式**   | Tailwind CSS 3                     | 液态玻璃顶栏 + 蓝色左侧菜单                    |
| **前端通信**   | Socket.IO 客户端                      | 命名空间（/chat, /admin）+ 事件驱动 + 自动重连   |
| **后端**     | Node.js 18+ + Express + TypeScript | ES Module, strict 模式               |
| **后端通信**   | Socket.IO + RESTful API            | 聊天流式用 Socket.IO, CRUD 用 HTTP       |
| **AI 接入**  | DeepSeek / OpenAI 兼容协议             | 统一中间件调用，支持 stream + function\_call |
| **数据库**    | MySQL 8 + mysql2                    | 参数化查询 (mysql2/promise.execute)，防 SQL 注入，utf8mb4 |
| **文件存储**   | 本地文件系统 + per-project Git           | 演示文件存 `files/{hash}/{hash}.html`，每个项目独立 Git 仓库 |
| **Git 集成** | nodegit + child_process             | per-project 版本管理 + 推送至 SubjEngine |
| **包管理**    | npm workspaces                     | monorepo 前后端+共享类型                  |

### 安全架构

| 维度 | 方案 |
|------|------|
| **SQL 注入防护** | 全部使用 `mysql2/promise.execute()` 参数化查询，零字符串拼接 |
| **认证** | JWT (jsonwebtoken) + Bearer Token，支持过期时间配置 |
| **密码存储** | bcryptjs 哈希加盐 |
| **授权** | 三层架构：全局 `permissionGuard` → 用户组属地管理 → 细粒度权限名 |
| **防越权** | `checkNoPrivilegeEscalation()` 确保不能授予自己没有的权限 |
| **WebAuthn** | 可选无密码登录，基于 @simplewebauthn/server |
| **内容审查** | 实时中间件过滤 + AI 异步审核队列 |

### 核心数据流

```
用户输入需求 → Studio 聊天面板
  → Socket.IO /chat 命名空间
  → 后端 ai-proxy 中间件 (流式调用 DeepSeek API)
    → function_call 工具链 (读模板 / 写文件 / 更新TODO / update_project_info)
    → AI 流式响应 → Socket.IO 推回前端
  → 用户预览 → 满意 → 管理员审核
    → 审核通过 → Git 推送至 SubjEngine 仓库
```

***

## 🚀 快速开始

### 1. 克隆与安装

```bash
git clone <repository-url>
cd subj-studio
npm install
```

### 2. 配置环境变量

```bash
# Windows
copy .env.example .env
```

编辑 `.env` 文件，配置以下必需项：

| 配置项                          | 说明     | 示例                             |
| ---------------------------- | ------ | ------------------------------ |
| `PORT`                       | 后端端口   | `3001`                         |
| `DB_HOST/PORT/USER/PASSWORD` | 数据库配置  | `localhost/3306/root/password` |
| `DB_NAME`                    | 数据库名称  | `subj_studio`                  |
| `JWT_SECRET`                 | JWT 密钥 | 随机字符串                          |
| `FRONTEND_URL`               | 前端地址   | `http://localhost:5173`        |

### 3. 初始化数据库

使用安装向导：启动后访问 `http://localhost:3001/api/install`

### 4. 启动服务

**快速启动（推荐）**：

```bash
npm run build
npm start
```

启动后访问 `http://localhost:3001`

**开发模式**：

```bash
npm run dev  # 同时启动前后端
npm run dev:frontend  # 仅前端 (http://localhost:5173)
npm run dev:backend   # 仅后端 (http://localhost:3001)
```

### 5. 完成配置

注册第一个用户（自动成为 super\_admin），进入管理后台配置 AI 密钥、SMTP 邮箱、Git 仓库。

***

## 📡 API 参考

### 核心 API

| 端点 | 方法 | 认证 | 说明 |
|------|------|------|------|
| `GET /api/health` | GET | 公开 | 健康检查 |
| `POST /api/auth/register` | POST | 公开 | 注册 |
| `POST /api/auth/login` | POST | 公开 | 密码/验证码登录 |
| `GET /api/projects/public` | GET | 公开 | 公开项目列表 (分页/搜索/排序) |
| `GET /api/projects/my` | GET | 需认证 | 我的项目 |
| `POST /api/projects` | POST | 需认证 | 创建项目 |
| `GET /api/projects/:id` | GET | optionalAuth | 项目详情 |
| `PUT /api/projects/:id` | PUT | 需认证 | 更新项目 (仅作者) |
| `DELETE /api/projects/:id` | DELETE | 需认证 | 删除项目 (仅作者) |
| `POST /api/projects/:id/like` | POST | authMiddleware | 点赞/取消 |
| `POST /api/projects/:id/collect` | POST | 需认证 | 收藏/取消 |
| `POST /api/projects/:id/fork` | POST | 需认证 | Fork 项目 |
| `POST /api/projects/:id/publish` | POST | authMiddleware | 发布项目 (加入AI审核) |
| `GET /api/projects/:projectId/versions` | GET | 需认证 | 版本历史 |
| `GET /api/user/:id` | GET | 公开 | 用户公开信息 |
| `GET /api/announcements` | GET | 公开 | 公开公告列表 |
| `POST /api/tickets` | POST | 需认证 | 创建工单 |
| `GET /api/tickets/my` | GET | 需认证 | 我的工单 |
| `GET /api/permissions/me` | GET | admin | 我的权限 |
| `GET /api/admin/users` | GET | admin | 用户列表 (权限感知) |
| `PUT /api/admin/projects/:id/push` | PUT | admin | 推送至 SubjEngine |
| `POST /api/knowledge-base` | POST | authMiddleware | 知识库操作 |

> **认证级别说明**:
> - **公开** — 无需任何认证
> - **需认证** — 通过全局 `permissionGuard` 中间件自动鉴权
> - **authMiddleware** — 显式使用 `authMiddleware` 中间件
> - **optionalAuth** — 有 token 则鉴权，无 token 也可访问
> - **admin** — 需 `admin_access` 权限 (管理员及以上)

### Socket.IO 事件

#### `/chat` 命名空间

| 事件 | 方向 | 说明 |
|------|------|------|
| `chat:send` | C→S | 发送聊天消息 (触发 AI 流式响应) |
| `chat:receive` | S→C | AI 流式响应 fragment |
| `chat:history` | S→C | 会话历史记录 |
| `chat:error` | S→C | 聊天错误通知 |
| `todo_list_updated` | S→C | TODO 列表更新通知 |
| `ask_problem` | S→C | AI 向用户提问 |
| `ask_problem_answer` | C→S | 用户回答提问 |
| `function_call_executed` | S→C | Function Call 通知 |
| `project:join` | C→S | 加入项目房间 |
| `project:leave` | C→S | 离开项目房间 |
| `join_session` | C→S | 加入聊天会话 |

#### `/admin` 命名空间

| 事件 | 方向 | 说明 |
|------|------|------|
| `admin_join` | C→S | 管理员加入后台频道 |
| `push:result` | S→C | Git 推送结果通知 |
| `review_completed` | S→C | AI 内容审核完成通知 |
| `new_pending_project` | S→C | 有待推送项目 (小红点) |

连接地址：`ws://localhost:3001/chat`（用户）或 `ws://localhost:3001/admin`（管理员），需在 query 中传入 `token` 参数

***

## 🗄️ 数据库设计

### 核心表

| 表名 | 说明 | 主要字段 |
|------|------|----------|
| **users** | 用户表 | id, username, email, password_hash(bcrypt), display_name, avatar_base64, is_frozen |
| **user_groups** | 用户组树 (邻接表) | id, name, parent_id, created_at |
| **user_group_membership** | 用户-用户组映射 | id, user_id, group_id (唯一约束) |
| **permissions** | 分层权限表 | id, user_id(NULL=组级), group_id, permission_name, granted, granted_by |
| **projects** | 项目表 | id, name, summary, user_id, subject, grade, is_public, file_path, git_path, like_count, view_count, collect_count, publish_commit_hash, review_status, deleted_at |
| **project_likes** | 项目点赞 | id, user_id, project_id |
| **project_forks** | Fork 关系 | id, parent_id, child_id, depth |
| **commit_reviews** | 提交审核 | id, project_id, commit_hash, source, review_status(compliant/violation/pending), ai_feedback |
| **chat_sessions** | 聊天会话 | id, user_id, project_id, todo_list(JSON) |
| **chat_records** | 聊天记录 | id, session_id, role, content, attachments(JSON), function_call(JSON) |
| **collections** | 收藏 | id, user_id, project_id (唯一约束) |
| **system_config** | 系统配置 | id, config_key(唯一), config_value, config_group(smtp/ai/git/general) |
| **review_queue** | AI 审核队列 | id, project_id, status |
| **announcements** | 公告 | id, title, content, is_published, created_by |
| **tickets** | 工单 | id, title, content, status(open/in_progress/resolved/closed), created_by |
| **ticket_messages** | 工单消息 | id, ticket_id, sender_type, sender_id, content |
| **banners** | 横幅 | id, title, image_url, link_url, is_active |
| **inbox_messages** | 站内信 | id, user_id, title, content, is_read |
| **issues** | Issue | id, project_id, title, content, status, created_by |
| **recommend_lists** | 推荐列表 | id, name, description, created_by |
| **recommend_items** | 推荐项 | id, list_id, project_id, sort_order |
| **knowledge_entries** | 知识条目 | id, title, content, source, status |
| **access_stats** | 访问统计 | id, path, method, user_id, ip, response_time |
| **webauthn_credentials** | WebAuthn 凭证 | id, user_id, credential_id, credential_public_key, counter |

### 学科与年级

- **学科**: 语文、数学、英语、物理、化学、生物、历史、政治、地理
- **年级**: 初中(J1-J3)、高中(B1-B3)、选科(XB1-XB3)、小学(X1-X6)

***

## 📦 项目结构

```
subj-studio/
├── backend/                     # 后端 (Express + TS)
│   ├── src/
│   │   ├── controllers/         # REST API 控制器 (16个)
│   │   ├── middleware/          # 中间件 (auth, permission-guard, ai-proxy, content-audit, access-stats)
│   │   ├── services/            # 服务 (email, git, permission, review-queue, webauthn, cache, etc.)
│   │   ├── socket/              # Socket.IO 命名空间 (/chat, /admin)
│   │   ├── function-calls/      # AI Function Call 实现 (10个工具)
│   │   ├── routes/              # 路由模块 (admin, permission, knowledge, stats)
│   │   └── db/                  # 数据库初始化与迁移 (含5个增量迁移)
│   └── package.json
│
├── frontend/                    # 前端 (Vue 3 + Vite)
│   ├── src/
│   │   ├── views/               # 页面 (Home, Studio, Project, Admin)
│   │   ├── components/          # 组件 (GlassNav, ChatPanel, PreviewFrame)
│   │   ├── router/              # 路由配置
│   │   ├── socket/              # Socket.IO 客户端
│   │   └── store/               # 状态管理
│   └── package.json
│
├── shared/                      # 共享类型定义 (types.ts)
├── static/                      # 静态资源 (CSS/JS/fonts/img)
└── files/                       # 项目 HTML 文件存储
```

## 🚢 部署指南

### 生产部署

1. **构建**：`npm install && npm run build`
2. **启动**：`npm start`
3. **进程管理**：使用 PM2 (`pm2 start npm -- start`)
4. **反向代理**：配置 Nginx 代理 `/` 和 `/socket.io/` 到 `http://127.0.0.1:3001`

### 生产环境注意事项

| 项目          | 建议                        |
| ----------- | ------------------------- |
| JWT\_SECRET | 使用强随机密钥                   |
| HTTPS       | 必须配置 SSL，WebSocket 需要 WSS |
| 数据库         | 定期备份，限制用户权限               |
| 防火墙         | 仅开放 80/443 端口             |

### 常见问题

| 问题             | 解决方法                           |
| -------------- | ------------------------------ |
| 数据库连接失败        | 检查 DB\_HOST/PORT/USER/PASSWORD |
| 收不到验证码         | 检查 SMTP 配置，确认邮箱已开启 SMTP 服务     |
| AI 不响应         | 检查 AI 配置，确认 API Key 正确         |
| Git 推送失败       | 确认 SSH Key 已添加                 |
| WebSocket 连接失败 | Nginx 需配置 Upgrade/Connection 头 |

## 🧪 开发指南

### 常用命令

```bash
npm run typecheck    # 类型检查
npm run dev          # 开发模式
npm run build        # 生产构建
```

### 代码规范

- TypeScript strict 模式
- Vue 3 Composition API (`<script setup lang="ts">`)
- ES Module 规范
- Tailwind CSS 工具类
- Conventional Commits 格式

### 添加新功能

1. **新 API**：在 `controllers/` 创建控制器，在路由中注册
2. **新 Function Call**：在 `function-calls/` 创建文件，在 `ai-proxy.ts` 中注册
3. **新页面**：在 `views/` 创建组件，在 `router/` 中注册

***

## 🤝 参与贡献

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'feat: add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 提交 Pull Request

### 代码规范

- 代码使用 TypeScript，strict 模式
- 前端遵循 Vue 3 Composition API 风格（`<script setup lang="ts">`）
- 后端遵循 ES Module 规范（import/export）
- 提交信息使用 Conventional Commits 格式（feat/fix/chore/docs 等前缀）
- 样式优先使用 Tailwind CSS 工具类

### 分支策略

- `main` 分支：稳定发布版本
- `development` 分支：日常开发集成
- `feature/*` 分支：新功能开发
- `fix/*` 分支：Bug 修复

***

## 📄 开源协议

本项目基于 Apache 2.0 协议开源。详见 [LICENSE](./LICENSE) 文件。

***

## 📬 联系方式

- **邮箱**: <codekpy@foxmail.com>
- **父项目**: [SubjEngine](https://gitee.com/codekpy/subj-engine)
- **问题反馈**: 提交 Issue 或通过邮箱联系

***

<p align="center">
  <strong>SubjStudio · 让知识可视化，让创造更简单</strong><br>
  <em>Build Knowledge, Together.</em>
</p>