# TurboHR 运行手册

## 技术栈

| 层 | 技术 | 版本 |
|---|------|------|
| 前端 | React + Vite + TypeScript + TailwindCSS | React 18, Vite 5 |
| 后端 | Express + TypeScript + Prisma | Node 18+, Express 4 |
| 数据库 | PostgreSQL | 14+ |
| 缓存 | Redis（可选，降级内存 Map） | 6+ |
| AI | OpenAI / 通义千问（SSE 流式） | — |

## 首次准备

```bash
# 1. 安装后端依赖
cd backend
npm install

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 填写 DATABASE_URL、JWT_SECRET、AI_API_KEY 等

# 3. 同步数据库
npx prisma db push
npx prisma generate

# 4. 安装前端依赖
cd ../frontend
npm install
```

## 应用启停

### 启动后端

```bash
cd backend
npx tsx watch src/index.ts
```

- 默认端口：**3000**
- 启动成功输出：`Server running on http://[::]:3000`
- 入口文件：`src/index.ts`（不是 `src/app.ts`，`app.ts` 仅 export app 实例）

### 启动前端

```bash
cd frontend
npx vite --port 5173
```

- 默认端口：**5173**
- 启动成功输出：`VITE v5.x ready`
- 访问地址：`http://localhost:5173`

### 停止服务

```bash
# 查找占用端口的进程
lsof -i :3000 -i :5173

# 杀掉进程
lsof -ti :3000 -ti :5173 | xargs kill -9
```

## DB 命令

```bash
cd backend

# 同步 schema 到数据库（增量，不丢数据）
npx prisma db push

# 生成 Prisma Client
npx prisma generate

# 创建迁移文件并应用
npx prisma migrate dev --name <migration_name>

# 重置数据库（危险！会清空数据）
npx prisma migrate reset

# 打开 Prisma Studio 可视化管理
npx prisma studio

# 验证 schema
npx prisma validate
```

## 排错

| 问题 | 解决方案 |
|------|---------|
| 端口被占用 | `lsof -ti :3000 \| xargs kill -9` |
| Prisma Client 找不到新 model | `npx prisma generate` 后重启 TS Server |
| IDE 报模块找不到但 tsc 通过 | `Cmd+Shift+P` → `TypeScript: Restart TS Server` |
| 后端启动无输出 | 确认入口是 `src/index.ts` 不是 `src/app.ts` |
| Redis 连接失败 | 自动降级内存 Map，不影响功能；设置 `REDIS_URL` 启用 |
| 前端 API 404 | 确认后端已启动在 3000 端口，Vite 代理配置在 `vite.config.ts` |

## 端口表

| 服务 | 端口 | 说明 |
|------|------|------|
| 后端 API | 3000 | Express + Prisma |
| 前端 Dev | 5173 | Vite dev server |
| PostgreSQL | 5432 | 数据库 |
| Redis | 6379 | 验证码缓存（可选） |

## 环境变量（.env）

```env
# 后端 backend/.env
DATABASE_URL="postgresql://user:pass@localhost:5432/hr_compliance"
JWT_SECRET="your-secret-key"
AI_API_KEY="your-ai-api-key"
AI_BASE_URL="https://api.openai.com/v1"
AI_MODEL="gpt-4o-mini"
REDIS_URL="redis://localhost:6379"  # 可选
PORT=3000

# 前端 frontend/.env
VITE_API_BASE_URL="http://localhost:3000/api/v1"
```

## 部署备份

```bash
# 前端构建
cd frontend && npm run build
# 产物在 frontend/dist/

# 后端编译
cd backend && npx tsc
# 产物在 backend/dist/

# 数据库备份
pg_dump -U user hr_compliance > backup_$(date +%Y%m%d).sql

# 数据库恢复
psql -U user hr_compliance < backup_20260726.sql
```

## FAQ

**Q: 为什么后端启动用 `src/index.ts` 而不是 `src/app.ts`？**
A: `app.ts` 只创建并 export Express app 实例（供测试使用），`index.ts` 才是启动入口，包含 `app.listen()`。

**Q: `prisma migrate dev` 和 `prisma db push` 的区别？**
A: `migrate dev` 创建迁移文件并应用，适合生产环境；`db push` 直接同步 schema 不生成迁移文件，适合开发环境快速迭代。

**Q: 新增 Prisma model 后 IDE 报类型不存在？**
A: 执行 `npx prisma generate`，然后 `Cmd+Shift+P` → `TypeScript: Restart TS Server`。