# master-study-notes

**Repository Path**: suzhidong/master-study-notes

## Basic Information

- **Project Name**: master-study-notes
- **Description**: 学习笔记项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 学迹 · 错题与学习笔记

一个 Vue 3 + NestJS 的前后端分离学习档案系统。支持注册登录、主题、分类、标签、错题/练习/笔记、多附件上传以及多条复盘评论。

## 技术栈

- Web：Vue 3、Vite、TypeScript、Ant Design Vue、Pinia、Vue Router
- API：NestJS、TypeORM、MySQL、JWT、Swagger
- 安全：bcrypt 12 轮、短期 Access Token、HttpOnly Refresh Cookie、令牌轮换、接口限流、Helmet、DTO 白名单、资源归属校验和文件头校验

## 快速开始

要求 Node.js 20+ 与 MySQL 8。项目附带 `docker-compose.yml`，已安装 Docker 时可直接启动独立开发数据库：

```powershell
docker compose up -d mysql
Copy-Item .env.example .env.local
npm install
npm run db:bootstrap
npm run dev
```

打开 <http://localhost:5173>。API 默认位于 <http://localhost:3100/api>，Swagger 位于 <http://localhost:3100/api/docs>。

## 复用现有服务器的连接信息，但使用新数据库

本项目不会复用 `cpa-test-system` 的业务库。可以让服务读取原项目的主机、端口和账号，再用当前进程覆盖数据库名：

```powershell
$env:ENV_FILE='D:\cpa-test-system\.env.development.local'
$env:DB_NAME='master_study_notes_dev'
$env:APP_ORIGIN='http://localhost:5173'
$env:JWT_ACCESS_SECRET='替换为至少32位的开发密钥'
$env:JWT_REFRESH_SECRET='替换为另一个至少32位的开发密钥'
npm run db:bootstrap
npm run dev
```

生产环境同理使用 `.env.production.local` 或密钥管理服务，并将 `DB_NAME` 设为 `master_study_notes`。首版部署前执行一次 `npm run db:bootstrap`，日常运行时保持 `DB_SYNCHRONIZE=false`。

## 环境变量

开发模板见 `.env.example`，生产模板见 `.env.production.example`。至少配置：

- `DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME`
- `JWT_ACCESS_SECRET/JWT_REFRESH_SECRET`，两者必须不同且至少 32 字符
- `APP_ORIGIN`，多个来源用英文逗号分隔
- `UPLOAD_DIR`，生产环境应挂载持久卷并定期备份

`.env.local`、`.env.*.local` 和上传文件均已被 Git 忽略。

## 常用命令

```powershell
npm run dev          # 同时启动前后端
npm run build        # 生产构建
npm run test         # 两端测试
npm run typecheck    # 两端类型检查
npm run db:bootstrap # 创建独立数据库并初始化表
```

## 生产建议

- 使用 HTTPS；当前服务器通过 Nginx 在 `/study-notes/` 发布 Vue 静态文件，并反向代理 `/study-notes/api/`。
- 为应用建立仅拥有 `master_study_notes` 权限的 MySQL 用户，不使用 root。
- 当前附件落本地文件系统；多实例部署前应替换为 OSS/S3 兼容存储。
- 同时备份 MySQL 与 `UPLOAD_DIR`，两者必须来自同一恢复时间点。
- 生产环境不要启用 `DB_SYNCHRONIZE`；后续版本应把结构变更固化为 TypeORM migration。

## 文档

- 系统设计：`docs/plans/2026-07-15-study-notes-design.md`
- 实施计划：`docs/plans/2026-07-15-study-notes-implementation.md`
- 生产部署：`docs/deployment.md`
- 架构决策：`docs/adr/0001-modular-monolith-mysql.md`
- Docker 网络决策：`docs/adr/0002-isolated-production-network.md`