# SV API Platform

基于 Workerman webman 开发的高性能 HR 员工管理 API 服务。

## 技术栈

- **框架**: Workerman webman (PHP >= 8.1)
- **数据库**: MySQL (三库: 主库、安全库、设备库)
- **ORM**: webman/database (基于 Illuminate Database)
- **迁移工具**: Phinx

## 完整 API 文档

📚 **[点击查看完整 API 文档](./docs/README.md)** 📚

文档涵盖所有 9 个 Controller 的详细接口说明、请求参数、响应示例和数据库结构。

---

## 功能模块与接口列表

### 员工管理 (EmployeeController)
路由前缀: `/employee`

| 方法 | 路由 | 说明 |
|------|------|------|
| GET | `/employee/index` | 员工列表查询 (支持姓名/部门/岗位筛选) |
| GET | `/employee/deps` | 获取所有部门列表 |
| GET | `/employee/getDetail` | 获取员工详细信息 |
| POST | `/employee/addLicense` | 为员工添加资质证书 |
| GET | `/employee/getEmpLicense` | 获取员工的资质证书列表 |

**数据表**: `dbf_data`, `employee_license`, `license`

---

### 资质证书管理 (LicenseController)
路由前缀: `/license`

| 方法 | 路由 | 说明 |
|------|------|------|
| GET | `/license/index` | 证件类型列表 |
| POST | `/license/save` | 保存证件类型 |
| POST | `/license/batch` | 批量导入证件 |

**数据表**: `license`

---

### 证件申请管理 (ApplyController)
路由前缀: `/apply`

| 方法 | 路由 | 说明 |
|------|------|------|
| GET | `/apply/index` | 待处理申请列表 (支持按部门筛选) |
| POST | `/apply/addApply` | 提交证件申请 |
| POST | `/apply/doneApply` | 完成申请 (标记 is_done=1) |

**数据表**: `application_form`

---

### 安全管理 (Safety DataController)
路由前缀: `/safety`

安全事故、成本、进度管理 (独立数据库 `safety` 连接)。

| 方法 | 路由 | 说明 |
|------|------|------|
| GET | `/safety/events` | 安全事故列表 |
| POST | `/safety/save_event` | 保存/更新事故 (触发 TPM/飞书通知) |
| POST | `/safety/add_cost` | 添加安全成本 |
| POST | `/safety/del_cost` | 删除成本 |
| GET | `/safety/get_costs` | 获取事故成本列表 |
| POST | `/safety/add_progress` | 添加处理进度 |
| POST | `/safety/del_progress` | 删除进度 |
| GET | `/safety/get_progress` | 获取进度列表 |
| POST | `/safety/saveBatch` | 批量更新事故 |
| GET | `/safety/statisticsData` | 事故统计数据 |

**数据表**: `events`, `costs`, `progress`

**外部集成**: TPM 系统 (`TPM_URL`)、飞书机器人 (`FEISHU_HOOK_URL`)

---

### 设备查询 (DeviceController)
路由前缀: `/device`

设备详情查询、历史记录、Excel 导出 (主要返回 HTML 页面)。

| 方法 | 路由 | 说明 |
|------|------|------|
| GET | `/device/{code}` | 设备详情 (智能模板选择) |
| GET | `/device/mylist` | 我的设备列表页面 |
| GET | `/device/history/{code}` | 设备历史记录页面 |
| GET | `/device/export?key=` | 导出设备清单 (Excel) |
| POST | `/device/prepare_export` | 准备导出数据 (生成缓存 key) |
| GET | `/device/export_by_dep` | 按部门导出设备清单 |
| GET | `/device/sevents/{txmno}` | 设备关联安全事故页面 |

**智能模板**: 根据 `txmno` 前缀选择
- `MHQ` → `showMhqInfo`
- `XFS` → `showXfsInfo`
- 其他 → `showInfo`

---

### 设备文档 (DocController)
路由前缀: `/doc`

设备文档关联、查看、下载。

| 方法 | 路由 | 说明 |
|------|------|------|
| GET | `/doc/view/{type}/{filename}` | PDF 文档查看页面 |
| GET | `/doc/data/{type}/{filename}` | PDF 文件流 (inline) |
| POST | `/doc/relate` | 关联文档与设备 |
| GET | `/doc/getDocs?type=` | 获取文档列表 (默认 type=SOP) |

**文件存储**: `SAFE_PDF/` 目录 (项目根目录)

**数据表**: `docs`, `doc_machine`

---

### 设备点检 (InspectionController)
路由前缀: `/inspection`

设备点检任务、资质验证、无资格人员管理。

| 方法 | 路由 | 说明 |
|------|------|------|
| GET | `/inspection` | 点检首页 |
| GET | `/inspection/search` | 按关键词查询设备资质 |
| POST | `/inspection/check` | 执行点检并验证人员资格 |
| GET | `/inspection/unqualified` | 无资格操作人员列表 |
| GET | `/inspection/export` | 导出无资格名单 (Excel) |
| GET | `/inspection/employee` | 查询员工部门信息 |
| GET | `/inspection/search_employee` | 搜索员工 (最多 20 条) |
| GET/POST | `/inspection/import` | 导入点检数据 (CSV) |

**数据表**: `dm_qualification` (设备库), `inspection_logs`

**外部依赖**: 员工服务 `http://127.0.0.1:45670/employee/index`

---

### TPM 到场验证 (TPMController)
路由前缀: `/tpm`

TPM 设备到场验证 (支持中繁双语)。

| 方法 | 路由 | 说明 |
|------|------|------|
| GET/POST | `/tpm/reach/{code}` | 设备到场验证 (中文) |
| GET/POST | `/tpm/reach_tw/{code}` | 设备到场验证 (繁体) |

**业务逻辑**: `DeviceService::checkReach($code, $phone, $tw)`

---

## 快速开始

### 安装依赖

```bash
composer install
```

### 配置环境

创建 `.env` 文件：

```env
DBADDR=localhost
DBPORT=3306
DBNAME=your_database
DBUSER=your_username
DBPASS=your_password
```

### 运行服务

```bash
php start.php start        # 前台运行
php start.php start -d     # 后台运行
php start.php stop         # 停止服务
php start.php restart      # 重启服务
```

### 数据库迁移

```bash
./vendor/bin/phinx migrate      # 执行迁移
./vendor/bin/phinx rollback     # 回滚迁移
```

## 目录结构

```
app/
├── controller/      # 控制器
│   ├── EmployeeController.php
│   ├── LicenseController.php
│   └── ApplyController.php
├── model/          # 数据模型
├── middleware/     # 中间件
└── service/        # 业务逻辑服务
config/             # 配置文件
database/
└── migrations/     # 数据库迁移
public/             # Web 根目录
support/            # 框架辅助类
```

## 代码规范

- 遵循 PSR-12 标准
- 使用严格类型声明 `declare(strict_types=1);`
- 数据库字段使用 snake_case
- 类名使用 PascalCase，方法名使用 camelCase

## API 响应格式

所有接口返回 JSON 格式数据：

```json
{
  "status": "ok"
}
```

错误响应：

```json
{
  "error": "错误描述"
}
```

## License

MIT