ss-visit/PROJECT_DOCUMENTATION.md

# 访客管理系统项目文档

## 项目概述

这是一个基于 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. **日志记录**: 重要操作需要记录详细日志

## 联系信息

如需了解更多项目详情或技术支持，请联系开发团队。