# 优一科技员工月度绩效考核系统 — 部署文档

## 一、系统概述

| 项目 | 说明 |
|------|------|
| 系统名称 | 员工月度绩效考核系统 |
| 前端技术 | React 18 + TypeScript + Ant Design 5 + Vite |
| 后端技术 | Node.js + Express + TypeScript |
| 数据库 | MySQL 8.0+ |
| AI 服务 | FastGPT（云端 API） |

---

## 二、环境要求

| 软件 | 版本要求 |
|------|----------|
| Node.js | >= 18.x |
| npm | >= 9.x |
| MySQL | >= 8.0 |
| 操作系统 | Linux（推荐 Ubuntu 22.04）/ Windows Server |
| Nginx | >= 1.20（用于前端静态文件托管及反向代理） |

---

## 三、数据库初始化

### 3.1 创建数据库

```sql
CREATE DATABASE employee_performance
  DEFAULT CHARACTER SET utf8mb4
  DEFAULT COLLATE utf8mb4_unicode_ci;
```

### 3.2 创建数据库用户（可选，建议生产环境不使用 root）

```sql
CREATE USER 'perf_user'@'localhost' IDENTIFIED BY '你的密码';
GRANT ALL PRIVILEGES ON employee_performance.* TO 'perf_user'@'localhost';
FLUSH PRIVILEGES;
```

### 3.3 初始化表结构

将 `backend/src/db/init.sql` 导入数据库：

```bash
mysql -u root -p employee_performance < backend/src/db/init.sql
```

### 3.4 初始化配置规则数据

```bash
cd backend
npx ts-node init-config-rules.ts
```

---

## 四、后端部署

### 4.1 安装依赖

```bash
cd backend
npm install
```

### 4.2 配置环境变量

复制示例文件并修改：

```bash
cp .env.example .env
```

编辑 `.env`，填写以下配置：

```env
# 数据库配置
DB_HOST=localhost
DB_PORT=33306  # Docker Compose 部署时使用 33306，传统部署请根据实际情况调整
DB_USER=perf_user
DB_PASSWORD=你的数据库密码
DB_NAME=employee_performance

# JWT 配置（生产环境请使用随机长字符串）
JWT_SECRET=请替换为随机长字符串_至少32位

# FastGPT API 配置
FASTGPT_API_KEY=你的FastGPT密钥
FASTGPT_API_URL=https://cloud.fastgpt.cn/api/v1/chat/completions
FASTGPT_MODEL=gpt-4

# 代理配置（如服务器需要代理才能访问 FastGPT，填写代理地址；否则删除此行）
HTTPS_PROXY=http://127.0.0.1:7890

# 服务器配置
PORT=3001
NODE_ENV=production
```

### 4.3 编译 TypeScript

```bash
npm run build
```

编译产物在 `backend/dist/` 目录。

### 4.4 启动服务

**方式一：直接启动（测试用）**

```bash
npm start
```

**方式二：使用 PM2 守护进程（推荐生产环境）**

```bash
# 安装 PM2
npm install -g pm2

# 启动
pm2 start dist/index.js --name "perf-backend"

# 设置开机自启
pm2 startup
pm2 save
```

**常用 PM2 命令：**

```bash
pm2 status          # 查看状态
pm2 logs perf-backend   # 查看日志
pm2 restart perf-backend  # 重启
pm2 stop perf-backend     # 停止
```

---

## 五、前端部署

### 5.1 安装依赖

```bash
cd frontend
npm install
```

### 5.2 配置 API 地址

如果后端不在同一台服务器，需要修改 `frontend/src/api/http.ts` 中的 `baseURL`：

```typescript
const http = axios.create({
  baseURL: 'http://47.238.126.111:33001',  # Docker Compose 部署时使用 33001，传统部署使用 3001
  timeout: 15000,
});
```

或者通过环境变量配置，在 `frontend/` 目录创建 `.env.production`：

```env
VITE_API_BASE_URL=http://47.238.126.111:33001  # Docker Compose 部署时使用 33001，传统部署使用 3001
```

### 5.3 构建静态文件

```bash
npm run build
```

构建产物在 `frontend/dist/` 目录。

### 5.4 Nginx 配置

将 `frontend/dist/` 目录内容部署到 Nginx，参考配置：

```nginx
server {
    listen 80;
    server_name 47.238.126.111;

    # 前端静态文件
    root /var/www/perf-system/dist;
    index index.html;

    # React Router 支持（所有路由返回 index.html）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 反向代理后端 API
    location /api/ {
        proxy_pass http://127.0.0.1:33001;  # Docker Compose 部署时使用 33001，传统部署使用 3001
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 120s;
    }

    # 静态资源缓存
    location /assets/ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}
```

重载 Nginx：

```bash
nginx -t && nginx -s reload
```

---

## 六、初始账号

| 用户名 | 密码 | 角色 |
|--------|------|------|
| lister | lister123 | 总经理 |
| xinxin | sxx980623 | 管理层 |

> 员工账号由管理层在系统内「员工管理」页面创建。

---

## 七、目录结构说明

```
项目根目录/
├── backend/          # 后端源码
│   ├── src/
│   │   ├── routes/   # API 路由
│   │   ├── services/ # 业务逻辑
│   │   ├── dao/      # 数据访问层
│   │   ├── db/       # SQL 初始化脚本
│   │   └── index.ts  # 入口文件
│   ├── dist/         # 编译产物（npm run build 后生成）
│   └── .env          # 环境变量（不提交 Git）
└── frontend/         # 前端源码
    ├── src/
    └── dist/         # 构建产物（npm run build 后生成）
```

---

## 八、常见问题

**Q: 后端启动报数据库连接失败**
- 检查 `.env` 中 `DB_HOST`、`DB_PORT`、`DB_USER`、`DB_PASSWORD` 是否正确
- 确认 MySQL 服务已启动：`systemctl status mysql`

**Q: AI 评分不工作**
- 检查 `FASTGPT_API_KEY` 和 `FASTGPT_API_URL` 是否正确
- 如服务器无法直接访问 FastGPT，配置 `HTTPS_PROXY`
- 查看后端日志中 `[AI]` 开头的日志排查问题

**Q: 前端页面空白或 404**
- 确认 Nginx 配置了 `try_files $uri /index.html`
- 确认 `frontend/dist/` 已正确部署到 Nginx root 目录

**Q: 登录后 401 错误**
- 检查 `JWT_SECRET` 是否与生成 token 时一致
- 清除浏览器 localStorage 后重新登录

---

## 九、更新部署流程

```bash
# 1. 拉取最新代码
git pull

# 2. 重新构建后端
cd backend && npm run build

# 3. 重启后端服务
pm2 restart perf-backend

# 4. 重新构建前端
cd ../frontend && npm run build

# 5. 将 dist/ 同步到 Nginx 目录
cp -r dist/* /var/www/perf-system/dist/
```