Files

T

selfrelease d79e3baa34 feat: 系统优化Phase2 - 面包屑导航/侧边栏间距/制度公示阅读签收/模板变量中文化/通知类型补全

- 面包屑导航组件，集成至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

2026-07-26 20:32:38 +08:00

3.6 KiB

Raw Blame History

TurboHR 运行手册

技术栈

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

首次准备

# 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

应用启停

启动后端

cd backend
npx tsx watch src/index.ts

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

启动前端

cd frontend
npx vite --port 5173

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

停止服务

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

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

DB 命令

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）

# 后端 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"

部署备份

# 前端构建
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。

3.6 KiB Raw Blame History Unescape Escape