可爱小羊 - 开发指南

技术栈：Vue 3 + TypeScript + Fastify + PostgreSQL + PM2

---

🏗️ 架构概览

┌─────────────────────────────────────────────────────────┐
│                     开发环境 (本地)                        │
├─────────────────────────────────────────────────────────┤
│  ┌─────────┐    ┌─────────┐    ┌─────────┐              │
│  │ Frontend │───▶│ Backend  │───▶│   DB    │              │
│  │  Vue 3   │    │ Fastify │    │PostgreSQL│              │
│  └─────────┘    └─────────┘    └─────────┘              │
│   localhost:5173  localhost:3000  localhost:5432            │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│                     生产环境 (腾讯云)                      │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   用户 ──▶ Vercel (前端+CDN) ──▶ 腾讯云 API ──▶ 腾讯云 PG │
│                                                         │
└─────────────────────────────────────────────────────────┘

---

🚀 快速开始

1. 安装依赖

# 前端依赖
npm install

# 后端依赖
cd backend
npm install
cd ..

2. 配置环境变量

# 复制环境变量模板
cp backend/.env.example backend/.env

# 编辑 backend/.env 配置数据库连接
DATABASE_URL=postgres://username:password@localhost:5432/xiaoyang
JWT_SECRET=your-secret-key
PORT=3000

3. 启动开发服务器

终端 1 - 启动后端：

cd backend
npm run dev

终端 2 - 启动前端：

npm run dev

4. 访问应用

服务	地址
前端	http://localhost:5173
后端 API	http://localhost:3000
API 文档	http://localhost:3000/docs

---

📁 项目结构

xiaoyang/
├── src/                    # Vue 3 前端源代码
│   ├── components/         # 组件
│   ├── views/              # 页面
│   ├── stores/             # Pinia 状态
│   ├── lib/                # 工具库 (API 客户端)
│   └── utils/              # 工具函数
├── backend/                # Fastify 后端
│   ├── src/
│   │   ├── routes/         # API 路由
│   │   ├── db/             # 数据库操作
│   │   ├── middleware/     # 中间件
│   │   └── server.ts       # 入口文件
│   ├── sql/                # SQL 脚本
│   └── package.json
├── supabase/               # 数据库 schema
│   └── schema.sql
└── package.json

---

🔧 常用命令

开发命令

# 启动前端开发服务器
npm run dev

# 启动后端开发服务器
cd backend && npm run dev

# 构建前端生产版本
npm run build

# 代码检查
npm run lint

后端命令

cd backend

npm run dev           # 开发模式
npm run build         # 构建
npm run start         # 生产模式
npm run db:migrate    # 执行数据库迁移
npm run db:mock       # 生成测试数据
npm run db:reset      # 重置数据库

---

🚀 部署

前端部署 (Vercel)

# 1. 构建
npm run build

# 2. 部署到 Vercel
vercel --prod

后端部署 (腾讯云)

# 1. 上传代码到服务器
scp -r backend ubuntu@134.175.189.58:/opt/xiaoyang-api/

# 2. SSH 到服务器
ssh ubuntu@134.175.189.58

# 3. 安装依赖并启动
cd /opt/xiaoyang-api/backend
npm install
npm run build

# 4. 使用 PM2 启动
sudo pm2 start dist/server.js --name xiaoyang-api
sudo pm2 save
sudo pm2 startup

---

📊 测试账号

• 邮箱: teacher@test.com
• 密码: test123456

---

📝 开发规范

1. 提交前: 确保代码通过 lint 检查
2. 数据库变更: 同步更新 supabase/schema.sql
3. API 变更: 更新 Swagger 文档注释
4. 环境切换: 本地开发用 localhost，线上用腾讯云 IP

---

🔗 相关链接

• 线上前端: https://keaixiaoyang.cn (Vercel)
• 线上 API: http://134.175.189.58:3000
• GitHub: https://github.com/lvBingo/xiaoyang

---

文档更新时间: 2026-04-12