selfrelease
d79e3baa34
- 面包屑导航组件，集成至TopNav header - 侧边栏菜单分组间距增大，分组间分隔线 - 制度公示员工阅读签收：PolicyReadRecord模型、portal路由、管理端阅读统计 - 修复Policies.tsx民主程序推进bug（字段名/API路径/参数） - 用工文本模板变量名英文转中文显示 - 通知类型TYPE_LABELS补全(RISK_ALERT/SOCIAL_INS/OVERTIME_ALERT/PAYSLIP_READY) - 通知示例数据补充 - h2标题统一为text-sm font-medium - 新增run.md
155 lines
3.6 KiB
Markdown
155 lines
3.6 KiB
Markdown
# 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`。
|