# 手搓HR system-codebuddy

**Repository Path**: georgechen0212/hr-system-codebuddy

## Basic Information

- **Project Name**: 手搓HR system-codebuddy
- **Description**: 人资小型系统，首次提交。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-07
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HR system-codebuddy 企业福利与招聘管理系统

基于 React + Vite 的前端单页应用,配合 `server/` 下的 **Express REST API + MySQL** 后端,实现数据的持久化存储与全量双向同步。

> 数据库唯一数据源:内网 MySQL(`192.168.2.233:3306`,库名 `hrcodebuddy`)。连接信息只从环境变量读取,真实密码不落入仓库,详见「安全约定」。

## 目录结构

```
├── src/                  # 前端(React + TS,Vite)
│   ├── lib/api.ts        # 后端 REST 客户端(默认 http://127.0.0.1:5174)
│   ├── pages/            # 各业务页面(福利 / 招聘 / 薪酬绩效 / 组织人事…)
│   └── store/            # 前端状态与全量同步逻辑
├── server/               # 后端(独立 node 工程)
│   ├── index.js          # Express REST API(端口 5174)
│   ├── config.js         # 环境变量读取与校验(密码仅允许来自 .env)
│   ├── db.js             # MySQL 连接池 + 集合↔表映射 + 读写转换
│   ├── migrate.js        # 幂等建库建表/补列
│   ├── schema.sql        # 表结构定义(hr_* 系列表)
│   ├── .env.example      # 环境变量模板(入仓库)
│   └── .env              # 本机真实配置(被 .gitignore 忽略,勿提交)
├── scripts/dev.js        # 一键启动前后端(npm run dev:all)
├── .env.example          # 前端环境变量模板(VITE_API_BASE)
└── package.json          # 根工程:web 与启动脚本
```

## 快速开始

环境要求:Node.js ≥ 18、可访问内网 MySQL(账号具备 `hrcodebuddy` 库读写权限)。

```bash
# 1) 安装依赖(前端 + 后端各一份)
npm install
npm run db:install

# 2) 配置后端环境变量
cd server
Copy-Item .env.example .env   # PowerShell;随后在 .env 中填写真实 DB_PASSWORD
cd ..

# 3) 建库建表(幂等,可重复执行)
npm run db:migrate

# 4) 启动(方式一:一键同时启动前端 + 后端)
npm run dev:all

#    方式二:两个终端分别启动
#    终端 A: npm run dev:web        # 前端 http://localhost:5173
#    终端 B: npm run dev:api        # 后端 http://localhost:5174/api/health
```

验证:浏览器打开 `http://localhost:5173`,登录后任一动作用户,数据会经后端写入 MySQL;`http://localhost:5174/api/health` 返回 `{ok:true, db:"mysql"}` 即后端健康。

## 环境变量

### 后端(`server/.env`,模板见 `server/.env.example`)

| 变量 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `DB_HOST` | 否 | `192.168.2.233` | MySQL 主机 |
| `DB_PORT` | 否 | `3306` | MySQL 端口 |
| `DB_NAME` | 否 | `hrcodebuddy` | 数据库名 |
| `DB_USER` | 否 | `hrcodebuddy` | 数据库账号 |
| `DB_PASSWORD` | **是** | 无 | 数据库密码(缺省时后端拒绝启动) |
| `API_PORT` | 否 | `5174` | 后端监听端口 |
| `CORS_ORIGIN` | 否 | 空(放行所有) | 允许的前端来源,逗号分隔,如 `http://localhost:5173,http://127.0.0.1:5173` |

> 优先级:进程真实环境变量 > `server/.env` > 仓库内默认值。

### 前端(`.env` / `.env.local`,模板见 `.env.example`)

| 变量 | 默认 | 说明 |
|------|------|------|
| `VITE_API_BASE` | `http://127.0.0.1:5174` | 后端 API 基地址;前后端分离部署时按需修改 |

## 数据与同步模型

- **存储**:福利模块(福利项目、申请单、发放记录)落库为结构化列(`hr_benefit`、`hr_application`、`hr_grant_record`);招聘模块及各业务集合落库为 `id + data(JSON)` 文档表(`hr_recruit_*`、`hr_candidate` 等)。
- **同步**:前端启动时从后端拉取整包快照(`GET /api/state`);写操作后由前端将涉及的集合整包推送(`PUT /api/state`),后端在**单个事务**内整体替换目标表,保证原子性。
- **元数据**:`hr_meta` 记录数据版本标记,用于避免旧快照覆盖新数据。

## API 一览

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/health` | 健康检查(含 DB 连通性) |
| GET / PUT | `/api/state` | 业务集合全量快照 读 / 写 |
| GET / PUT | `/api/meta` | 元数据(kv)读 / 写 |
| GET | `/api/collections` | 各集合行数统计 |
| GET / PUT | `/api/collections/:name` | 指定集合 读 / 整体替换 |
| DELETE | `/api/collections/:name/:id` | 删除指定行 |

## 安全约定与建议

- **凭据管理**:真实 `DB_PASSWORD` 只放在本地 `server/.env`(已被 `.gitignore` 忽略)。`config.js` 无密码兜底默认值,缺密码时直接拒绝启动;`.env.example` 仅作模板,不含真实密码。
- **本仓库过往提交中曾包含内网 IP/默认密码**。若仓库对外可见,建议轮换该数据库账号密码,并清理/重写历史(仓库不可见且为内部试用场景时可忽略)。
- 已启用:隐藏 `x-powered-by`、请求体上限、畸形 JSON 统一 400、连接池超时与保活、优雅退出(SIGINT/SIGTERM)。
- 建议:正式环境收紧 `CORS_ORIGIN` 白名单;为 DB 账号最小化授权;对 HR 敏感数据增加登录鉴权(当前演示版前端本地鉴权);定期备份 `hrcodebuddy` 库。

## 常用脚本(根目录)

| 命令 | 作用 |
|------|------|
| `npm run dev` / `dev:web` | 仅启动前端(Vite 5173) |
| `npm run dev:api` | 仅启动后端(5174) |
| `npm run dev:all` | 一键启动前后端 |
| `npm run api` | 生产方式运行后端 |
| `npm run db:install` | 安装后端依赖 |
| `npm run db:migrate` | 幂等执行建库建表迁移 |
| `npm run build` | 构建前端产物到 `dist/` |


## 服务器部署(正式机 192.168.0.75:8085)

架构:`nginx :8085` 托管 `dist/` 静态产物 + 反代 `/api/*` → 本机 `127.0.0.1:5174`(Express)。

| 项 | 值 |
|---|---|
| 访问地址 | `http://192.168.0.75:8085` |
| 前端静态 | `/data/hr-system-codebuddy/dist`(nginx root) |
| 后端代码 | `/data/hr-system-codebuddy/server`(node `index.js`,监听 5174) |
| nginx 配置 | `/etc/nginx/sites-available/property-manage`(8085 server 块) |
| systemd | `hr-system.service`(开机自启,崩溃自动拉起) |
| 数据库 | `192.168.2.233:3306/hrcodebuddy`(与开发共用) |

### 重新部署步骤(本机 Windows)

```bash
# 1) 构建最新前端
cd F:/111renzi/hr-system-codebuddy
npm run build          # 产物 dist/

# 2) 打包并上传(排除 node_modules/.git)
tar -czf /tmp/hr-deploy.tar.gz --exclude=server/node_modules --exclude=.git dist server .env package.json

# 3) 服务器(192.168.0.75, root):停服务→备份→解压→装依赖→migrate→启动
ssh -p 55555 root@192.168.0.75
systemctl stop hr-system || true
cd /data && mv hr-system-codebuddy hr-system-codebuddy.bak.$(date +%Y%m%d%H%M%S)
mkdir -p /data/hr-system-codebuddy && tar -xzf /tmp/hr-deploy.tar.gz -C /data/hr-system-codebuddy
cd /data/hr-system-codebuddy/server && npm install --omit=dev && npm run migrate
systemctl start hr-system
```

### 部署要点/坑

1. 构建若报 `TS18048: 'b.legalIds' is possibly 'undefined'`,将 `src/store/actions.ts` 判空 `!== null` 改为 `!= null`(同时排除 undefined)。
2. 后端 5174 与 nginx 8085 已就绪;改端口需同步改 `server/.env` 的 `API_PORT` 与 nginx `proxy_pass`。
3. ufw 需放行 8085(已执行 `ufw allow 8085/tcp`)。
4. 数据在共享库 `hrcodebuddy`,服务器部署前请执行 `npm run migrate` 同步最新表结构。