master
cody
11 months ago
parent
e61dee61ef
commit
491dd67bc7
@ -1,124 +0,0 @@
|
||||
# 门岗端控制器统一响应格式更新总结
|
||||
|
||||
## 更新内容
|
||||
|
||||
根据要求，已将门岗端控制器的响应方法统一为系统标准的 `success` 和 `fail` 方法，移除了自定义的响应方法。
|
||||
|
||||
## 修改详情
|
||||
|
||||
### 1. 移除自定义方法
|
||||
- 删除了 `GateController` 中自定义的 `success()` 和 `error()` 方法
|
||||
- 使用系统统一的 `ApiResponse` trait 中的方法
|
||||
|
||||
### 2. 更新错误响应
|
||||
将所有 `$this->error()` 调用更新为 `$this->fail()` 调用：
|
||||
|
||||
```php
|
||||
// 修改前
|
||||
return $this->error(__('gate.visit_not_found'));
|
||||
|
||||
// 修改后
|
||||
return $this->fail([ResponseCode::ERROR_BUSINESS, __('gate.visit_not_found')]);
|
||||
```
|
||||
|
||||
### 3. 统一响应格式
|
||||
- **成功响应**: 使用 `$this->success($data)` 直接返回数据
|
||||
- **失败响应**: 使用 `$this->fail([$errcode, $errmsg])` 返回错误码和消息
|
||||
|
||||
## 响应格式
|
||||
|
||||
### 成功响应格式
|
||||
```json
|
||||
{
|
||||
"current_page": 1,
|
||||
"data": [...],
|
||||
"total": 10
|
||||
}
|
||||
```
|
||||
|
||||
### 失败响应格式
|
||||
```json
|
||||
{
|
||||
"errcode": 10002,
|
||||
"errmsg": "错误消息"
|
||||
}
|
||||
```
|
||||
|
||||
## 更新的错误类型
|
||||
|
||||
1. **拜访记录不存在**
|
||||
```php
|
||||
return $this->fail([ResponseCode::ERROR_BUSINESS, __('gate.visit_not_found')]);
|
||||
```
|
||||
|
||||
2. **只有已审核通过的拜访才能进厂**
|
||||
```php
|
||||
return $this->fail([ResponseCode::ERROR_BUSINESS, __('gate.only_approved_visits_can_enter')]);
|
||||
```
|
||||
|
||||
3. **只有已进厂的访客才能离厂**
|
||||
```php
|
||||
return $this->fail([ResponseCode::ERROR_BUSINESS, __('gate.only_entered_visitors_can_leave')]);
|
||||
```
|
||||
|
||||
4. **只有物流车辆才能上传货车图片**
|
||||
```php
|
||||
return $this->fail([ResponseCode::ERROR_BUSINESS, __('gate.only_logistics_cars_can_upload_images')]);
|
||||
```
|
||||
|
||||
5. **货车图片不能为空**
|
||||
```php
|
||||
return $this->fail([ResponseCode::ERROR_BUSINESS, __('gate.vehicle_images_required')]);
|
||||
```
|
||||
|
||||
6. **货车图片ID无效**
|
||||
```php
|
||||
return $this->fail([ResponseCode::ERROR_BUSINESS, __('gate.invalid_vehicle_images')]);
|
||||
```
|
||||
|
||||
7. **无效的操作类型**
|
||||
```php
|
||||
return $this->fail([ResponseCode::ERROR_BUSINESS, __('gate.invalid_action_type')]);
|
||||
```
|
||||
|
||||
## 测试结果
|
||||
|
||||
### ✅ 通过的测试
|
||||
- ✅ 门岗端拜访列表接口
|
||||
- ✅ 门岗端拜访详情接口
|
||||
- ✅ 门岗端拜访更新接口
|
||||
- ✅ 多语言支持
|
||||
- ✅ API响应格式
|
||||
- ✅ 路由验证
|
||||
|
||||
### ⚠️ 需要关注的问题
|
||||
- ⚠️ 后台管理接口认证测试失败（可能是中间件配置问题）
|
||||
|
||||
## 代码变更
|
||||
|
||||
### 添加的引用
|
||||
```php
|
||||
use App\Helpers\ResponseCode;
|
||||
```
|
||||
|
||||
### 移除的方法
|
||||
```php
|
||||
// 删除了这些自定义方法
|
||||
public function success($data = null, $message = 'success') { ... }
|
||||
public function error($message = 'error', $code = 400, $data = null) { ... }
|
||||
```
|
||||
|
||||
### 更新的调用
|
||||
- 所有 `$this->error()` → `$this->fail([ResponseCode::ERROR_BUSINESS, $message])`
|
||||
- 保持 `$this->success($data)` 不变
|
||||
|
||||
## 优势
|
||||
|
||||
1. **统一性**: 与系统其他控制器使用相同的响应格式
|
||||
2. **一致性**: 错误码和消息格式统一
|
||||
3. **可维护性**: 减少了重复代码
|
||||
4. **标准化**: 符合系统架构规范
|
||||
|
||||
## 总结
|
||||
|
||||
门岗端控制器已成功更新为使用系统统一的响应方法，所有接口都能正常工作，响应格式与系统其他部分保持一致。测试显示主要功能正常，只有认证相关的测试需要进一步检查。
|
||||
@ -0,0 +1,195 @@
|
||||
# 访客管理系统项目文档
|
||||
|
||||
## 项目概述
|
||||
|
||||
这是一个基于 Laravel 9 框架开发的企业访客管理系统，主要用于管理企业的访客预约、门岗登记、审核流程等功能。系统采用前后端分离架构，提供了完整的 API 接口。
|
||||
|
||||
## 主要功能模块
|
||||
|
||||
### 1. 访客预约管理
|
||||
- **功能描述**: 支持访客在线预约访问，填写访问信息、时间、区域等
|
||||
- **核心文件**: `app/Models/Visit.php`, `app/Http/Controllers/Mobile/VisitController.php`
|
||||
- **访问类型**:
|
||||
- 访客 (TYPE_VISITOR = 1)
|
||||
- 访客车辆 (TYPE_VISITOR_CAR = 2)
|
||||
- 物流车辆 (TYPE_LOGISTICS_CAR = 3)
|
||||
|
||||
### 2. 审核流程管理
|
||||
- **功能描述**: 多级审核流程，支持审核状态跟踪
|
||||
- **核心文件**: `app/Models/VisitAudit.php`, `app/Http/Controllers/Admin/VisitAuditController.php`
|
||||
- **审核状态**:
|
||||
- 待学习 (AUDIT_STATUS_PENDING_STUDY = -1)
|
||||
- 待审核 (AUDIT_STATUS_PENDING = 0)
|
||||
- 通过/待进厂 (AUDIT_STATUS_APPROVED = 1)
|
||||
- 驳回 (AUDIT_STATUS_REJECTED = 2)
|
||||
- 已进厂 (AUDIT_STATUS_ENTERED = 3)
|
||||
- 已离厂 (AUDIT_STATUS_LEFT = 4)
|
||||
|
||||
### 3. 门岗管理系统
|
||||
- **功能描述**: 门岗端进行访客登记、ID卡绑定、进出厂记录等
|
||||
- **核心文件**: `app/Http/Controllers/GateController.php`, `app/Models/GateLog.php`
|
||||
- **主要功能**:
|
||||
- 访客列表查询和筛选
|
||||
- ID卡绑定 (bind_card)
|
||||
- 进厂登记 (enter)
|
||||
- 离厂登记 (leave)
|
||||
- 货车图片上传 (upload_vehicle)
|
||||
|
||||
### 4. 学习培训模块
|
||||
- **功能描述**: 访客进厂前的安全学习和考试
|
||||
- **核心文件**: `app/Models/Study.php`, `app/Models/StudyAsk.php`, `app/Models/StudyLog.php`
|
||||
- **相关控制器**: `app/Http/Controllers/Admin/StudyController.php`, `StudyAskController.php`
|
||||
|
||||
### 5. 系统配置管理
|
||||
- **功能描述**: 系统参数配置、访问区域管理、时间段管理等
|
||||
- **核心文件**:
|
||||
- `app/Models/Config.php` - 系统配置
|
||||
- `app/Models/VisitArea.php` - 访问区域
|
||||
- `app/Models/VisitTime.php` - 访问时间段
|
||||
- `app/Models/Blacklist.php` - 黑名单管理
|
||||
|
||||
### 6. 用户权限管理
|
||||
- **功能描述**: 基于角色的权限控制系统
|
||||
- **核心文件**: `app/Models/Admin.php`, `app/Models/Role.php`, `app/Models/Permission.php`
|
||||
- **技术实现**: 使用 Spatie Laravel Permission 包
|
||||
|
||||
### 7. 多语言支持
|
||||
- **功能描述**: 支持多语言国际化
|
||||
- **实现方式**: 通过 `set.locale` 中间件实现
|
||||
- **语言文件**: `lang/` 目录下的语言包
|
||||
|
||||
## 技术架构
|
||||
|
||||
### 后端技术栈
|
||||
- **框架**: Laravel 9.x
|
||||
- **PHP版本**: ^8.0.2
|
||||
- **数据库**: MySQL
|
||||
- **认证**: Laravel Sanctum (JWT)
|
||||
- **权限管理**: Spatie Laravel Permission
|
||||
- **API文档**: Swagger (darkaonline/l5-swagger)
|
||||
|
||||
### 核心依赖包
|
||||
```json
|
||||
{
|
||||
"darkaonline/l5-swagger": "^8.6", // API文档生成
|
||||
"spatie/laravel-permission": "^5.5", // 权限管理
|
||||
"owen-it/laravel-auditing": "^13.6", // 操作审计
|
||||
"maatwebsite/excel": "^3.1", // Excel导入导出
|
||||
"overtrue/wechat": "~5.0", // 微信SDK
|
||||
"lpilp/guomi": "^2.0", // 国密加密
|
||||
"overtrue/pinyin": "^5.0" // 拼音转换
|
||||
}
|
||||
```
|
||||
|
||||
### API 路由结构
|
||||
|
||||
#### 门岗端接口 (`/api/gate/`)
|
||||
- `GET /visits` - 获取访客列表
|
||||
- `POST /visits/detail` - 获取访客详情
|
||||
- `POST /visits/update` - 更新访客状态
|
||||
- `GET /visits/use-code` - 核销访客
|
||||
|
||||
#### 管理后台接口 (`/api/admin/`)
|
||||
- `/visits/*` - 访客管理
|
||||
- `/studies/*` - 学习内容管理
|
||||
- `/study-asks/*` - 学习题目管理
|
||||
- `/visit-times/*` - 访问时间管理
|
||||
- `/configs/*` - 系统配置
|
||||
- `/blacklists/*` - 黑名单管理
|
||||
- `/visit-areas/*` - 访问区域管理
|
||||
|
||||
#### 移动端接口 (`/api/mobile/`)
|
||||
- `/user/*` - 用户相关
|
||||
- `/visit/*` - 访客预约相关
|
||||
|
||||
## 数据库设计
|
||||
|
||||
### 核心数据表
|
||||
- `visits` - 访客预约记录表
|
||||
- `visit_audits` - 审核记录表
|
||||
- `visit_logs` - 访客操作日志表
|
||||
- `gate_logs` - 门岗操作日志表
|
||||
- `admins` - 管理员表
|
||||
- `visit_areas` - 访问区域表
|
||||
- `visit_times` - 访问时间段表
|
||||
- `studies` - 学习内容表
|
||||
- `study_asks` - 学习题目表
|
||||
|
||||
## 安全特性
|
||||
|
||||
### 认证与授权
|
||||
- 使用 Laravel Sanctum 进行 API 认证
|
||||
- 基于角色的权限控制 (RBAC)
|
||||
- 支持多端认证 (admin/mobile)
|
||||
|
||||
### 数据安全
|
||||
- 支持国密加密算法 (SM2)
|
||||
- 操作审计日志记录
|
||||
- 软删除保护重要数据
|
||||
|
||||
### 加密命令
|
||||
项目提供了 SM2 加密/解密命令:
|
||||
- `php artisan sm2:encrypt` - 加密数据
|
||||
- `php artisan sm2:decrypt` - 解密数据
|
||||
|
||||
## 部署要求
|
||||
|
||||
### 环境要求
|
||||
- PHP >= 8.0.2
|
||||
- MySQL >= 5.7
|
||||
- Composer
|
||||
- Node.js (用于前端资源编译)
|
||||
|
||||
### 安装步骤
|
||||
1. 克隆项目代码
|
||||
2. 运行 `composer install` 安装依赖
|
||||
3. 复制 `.env.example` 为 `.env` 并配置数据库
|
||||
4. 运行 `php artisan key:generate` 生成应用密钥
|
||||
5. 运行 `php artisan migrate` 执行数据库迁移
|
||||
6. 运行 `php artisan db:seed` 填充初始数据
|
||||
7. 配置 Web 服务器指向 `public` 目录
|
||||
|
||||
## API 文档
|
||||
|
||||
系统集成了 Swagger API 文档，可通过以下方式访问:
|
||||
- 开发环境: `http://domain/api/documentation`
|
||||
- 控制器: `app/Http/Controllers/SwaggerController.php`
|
||||
|
||||
## 日志系统
|
||||
|
||||
### 访客操作日志
|
||||
- **表**: `visit_logs`
|
||||
- **类型**: 进厂、离厂、审核等操作记录
|
||||
|
||||
### 门岗操作日志
|
||||
- **表**: `gate_logs`
|
||||
- **功能**: 记录门岗的所有操作行为
|
||||
|
||||
### 系统审计日志
|
||||
- **实现**: Laravel Auditing 包
|
||||
- **功能**: 自动记录模型的增删改操作
|
||||
|
||||
## 国际化支持
|
||||
|
||||
系统支持多语言，通过中间件 `set.locale` 实现:
|
||||
- 语言包位置: `lang/` 目录
|
||||
- 支持动态语言切换
|
||||
- API 接口均支持多语言响应
|
||||
|
||||
## 文件上传管理
|
||||
|
||||
- **控制器**: `app/Http/Controllers/Admin/UploadController.php`
|
||||
- **模型**: `app/Models/Upload.php`
|
||||
- **功能**: 支持图片、文档等文件上传和管理
|
||||
|
||||
## 开发建议
|
||||
|
||||
1. **代码规范**: 遵循 PSR-4 自动加载标准
|
||||
2. **API 设计**: 遵循 RESTful 设计规范
|
||||
3. **错误处理**: 使用统一的 API 响应格式
|
||||
4. **数据验证**: 使用 Laravel Validator 进行数据验证
|
||||
5. **日志记录**: 重要操作需要记录详细日志
|
||||
|
||||
## 联系信息
|
||||
|
||||
如需了解更多项目详情或技术支持，请联系开发团队。
|
||||
@ -1,87 +0,0 @@
|
||||
<?php
|
||||
|
||||
// API接口测试脚本
|
||||
echo "=== 访客系统API接口测试 ===\n\n";
|
||||
|
||||
// 测试门岗端接口
|
||||
echo "1. 测试门岗端接口:\n";
|
||||
|
||||
// 测试拜访列表接口
|
||||
$url = 'http://localhost:8000/api/gate/visits';
|
||||
$response = @file_get_contents($url);
|
||||
if ($response !== false) {
|
||||
$data = json_decode($response, true);
|
||||
if (isset($data['code']) && isset($data['message']) && isset($data['data'])) {
|
||||
echo "✅ GET /api/gate/visits - 拜访列表接口正常\n";
|
||||
echo " 响应格式: code={$data['code']}, message={$data['message']}\n";
|
||||
} else {
|
||||
echo "❌ GET /api/gate/visits - 响应格式不正确\n";
|
||||
}
|
||||
} else {
|
||||
echo "❌ GET /api/gate/visits - 接口无法访问\n";
|
||||
}
|
||||
|
||||
// 测试拜访详情接口
|
||||
$url = 'http://localhost:8000/api/gate/visits/1';
|
||||
$response = @file_get_contents($url);
|
||||
if ($response !== false) {
|
||||
$data = json_decode($response, true);
|
||||
if (isset($data['code']) && isset($data['message'])) {
|
||||
echo "✅ GET /api/gate/visits/{id} - 拜访详情接口正常\n";
|
||||
echo " 响应格式: code={$data['code']}, message={$data['message']}\n";
|
||||
} else {
|
||||
echo "❌ GET /api/gate/visits/{id} - 响应格式不正确\n";
|
||||
}
|
||||
} else {
|
||||
echo "❌ GET /api/gate/visits/{id} - 接口无法访问\n";
|
||||
}
|
||||
|
||||
// 测试多语言支持
|
||||
echo "\n2. 测试多语言支持:\n";
|
||||
|
||||
// 测试中文响应
|
||||
$context = stream_context_create([
|
||||
'http' => [
|
||||
'header' => 'Accept-Language: zh-CN'
|
||||
]
|
||||
]);
|
||||
$url = 'http://localhost:8000/api/gate/visits';
|
||||
$response = @file_get_contents($url, false, $context);
|
||||
if ($response !== false) {
|
||||
echo "✅ 中文语言支持正常\n";
|
||||
} else {
|
||||
echo "❌ 中文语言支持异常\n";
|
||||
}
|
||||
|
||||
// 测试英文响应
|
||||
$context = stream_context_create([
|
||||
'http' => [
|
||||
'header' => 'Accept-Language: en'
|
||||
]
|
||||
]);
|
||||
$response = @file_get_contents($url, false, $context);
|
||||
if ($response !== false) {
|
||||
echo "✅ 英文语言支持正常\n";
|
||||
} else {
|
||||
echo "❌ 英文语言支持异常\n";
|
||||
}
|
||||
|
||||
// 测试后台管理接口
|
||||
echo "\n3. 测试后台管理接口:\n";
|
||||
|
||||
$url = 'http://localhost:8000/api/admin/visits/index';
|
||||
$response = @file_get_contents($url);
|
||||
if ($response !== false) {
|
||||
$data = json_decode($response, true);
|
||||
if (isset($data['code']) && $data['code'] == 401) {
|
||||
echo "✅ GET /api/admin/visits/index - 认证保护正常\n";
|
||||
} else {
|
||||
echo "⚠️ GET /api/admin/visits/index - 认证保护可能有问题\n";
|
||||
}
|
||||
} else {
|
||||
echo "❌ GET /api/admin/visits/index - 接口无法访问\n";
|
||||
}
|
||||
|
||||
echo "\n=== 测试完成 ===\n";
|
||||
echo "注意: 此测试需要Laravel开发服务器运行在 localhost:8000\n";
|
||||
echo "启动命令: php artisan serve\n";
|
||||
Loading…
Reference in new issue