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)

核心依赖包

{
  "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. 日志记录: 重要操作需要记录详细日志

联系信息

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