附录 · 访客门禁管理系统展示说明书架构日志
第 03 章

📄附录

页面

项目信息

项目 内容
项目名称 QR-Code-Gate(访客门禁二维码管理系统)
应用类型 Web 应用(Flask)
服务端口 5102(公网与内网同端口)
公网访问 http://119.145.17.34:5102(已验证在线)
部署设备 管理服务器(内网)
本地路径 ~/Desktop/Leon-TK-Station/QR-Code-Gate
Git 仓库 Gitea · LZ-TK-Station · TK-QR-Gate(main 分支)
当前基线 9690cd4(2026-10-25,见下方变更记录)

现状快照(2026-10-25)

  • 服务状态:运行中(公网 5102 与本机 5102 均返回 HTTP 200)。
  • 数据规模:门禁点位 404 个(启用 387 个,同步于 2026-10-22);人脸设备 60 台(同步于 2026-09-26);访客预约累计 34 条。
  • 已验证:test_ux_round2.py 10/10 通过;test_ux_round3.py 5/5 通过(含建号合规、过期撤人脸、data 出 git 三项回归)。
  • 代码规模:app.py 2699 行(57 路由)+ blueprints/settings.py 7 路由,共 64 路由;models.py 942 行;api_client.py 670 行;另有 auth.py、constants.py。
  • 已知事项:test_all.py(87 项旧冒烟脚本)硬编码 5002 端口,与现行 5102 不一致,待更新后才能作为回归门禁。

变更记录(倒序)

2026-10-25 | 蓝图拆分与封装(9bf7320)

  • 改动:新增 auth.py(鉴权装饰器集中管理);新增 blueprints/settings.py(首页卡片/公告/站点设置 7 路由迁入蓝图并注册);models.py 新增公开 save_allocation_records(),app.py 内 3 处直调内部 _write 全部替换;constants.py 状态枚举接入 models.py(预约/账户状态不再散落字面量)。
  • 验证:test_ux_round2.py 10/10、test_ux_round3.py 5/5;公网 5102 HTTP 200;/api/announcement 与 /api/home-card(未登录 302)行为符合预期。
  • 影响面:设置类接口保持路径不变,调用方无感。

2026-10-25 | 稳定性优化批次 1(466cc18)

  • 改动:api_client.py 的 C3 会话增加幂等 GET 有限重试(2 次、退避 0.5s,仅 5xx);开发/批量开门后台任务完成即落盘 data/tasks.json(保留最近 50 条);_safe_format_time 增加严格格式校验,非法输入返回空串不再透传脏数据;recycle_expired_accounts 对无分时记录的已分配账户改为保留(防误回收);get_site_settings 路径统一走 DATA_DIR;get_face_dev_names 语义化别名;C3 签名密钥支持环境变量覆盖(默认值仍在服务端配置中,不对外公开)。
  • 验证:同上 R2/R3 全绿;服务经 Leon-Control 重启后 5102 正常。
  • 取舍:授权类写操作保持单次不重试(避免重复下发权限),只对幂等查询重试。

2026-10-25 | 基线快照(64ced0a)

  • 改动:撤销误入 Git 的自动备份提交(含 data/ 运行时敏感数据),以干净代码树建立「可正常使用的版本」基线并推送 Gitea。
  • 决策:data/ 仅留工作区,永不入库;历史 Git 中的旧 data(含密码哈希)后续再做 filter-repo 清理。

2026-10-24 | 短板修复(1c514ce,已部署)

  • 改动:data/ 移出 Git 跟踪;访客建号合规(V + 15 位,满足 C3 16 位上限);授权精确到填写值(_format_exact_time,查询类仍用扩展版 _safe_format_time);过期账户撤人脸(定时 + 手动共用)。
  • 验证:test_ux_round3.py 5/5;生产 PID 切换后公网 200。

2026-10-24 | 人性化优化第二轮(4bee34a)

  • 改动:时间归一化与脱敏展示、预约页设备指引与一键人脸、成功页复制预约号、查询页找卡回填与自助取消、凭证页门禁折叠与倒计时状态、首页站内卡片同标签页等 12 项。
  • 验证:新增 test_ux_round2.py 10 项全过,旧回归 49 项全过。

技术栈

层级 技术
后端框架 Python 3.12 / Flask 3(单应用 + settings 蓝图)
数据存储 JSON 文件(data/,原子写入:临时文件 + fsync + rename),无数据库、无 ORM
门禁对接 达实 C3 双通道 API(公网映射 19002 无签名通道 + 19001 签名通道),requests.Session 复用连接
二维码 按账户实时向 C3 获取 qr_data,服务端不自造码
安全 PBKDF2-SHA256(200k 迭代,旧明文登录即自动升级哈希);会话密钥随机生成持久化(data/.secret_key);查询接口防枚举限流;手机号归一化与脱敏展示;data/ 已移出 Git
部署 venv + start.sh,Leon-Control 托管(走 restart 接口重启,不手动 kill)

文件结构

QR-Code-Gate/
├── app.py                 # Flask 主应用(2699 行,57 路由;页面/预约/审批/授权/记录/开门/管理/dev)
├── blueprints/
│   └── settings.py        # 设置蓝图(95 行:首页卡片/公告/站点设置 7 路由)
├── auth.py                # 鉴权装饰器(27 行:login_required / super_admin_required)
├── constants.py           # 状态枚举(24 行:预约/账户/授权类型)
├── models.py              # 数据层(942 行:预约/账户池分时分配/回收/门禁与人脸缓存/管理员/站点设置)
├── api_client.py          # C3 双通道客户端(670 行:签名/重试/并发拉取/授权/二维码)
├── config.py              # 配置(43 行:双通道地址/账户池/部门/密钥环境变量覆盖)
├── templates/             # Jinja2 模板(9 个:base/index/login/visitor/approve/qr/dev/remote/admin/emp_pass)
├── static/                # 本地静态资源(无外部 CDN)
├── data/                  # 运行态(工作区保留,不入库):accounts/admins/reservations/allocation_records/
│                          # qr_records/doors/face_devs/visibility/site_settings/announcement/home_cards/tasks
└── test_*.py              # 回归脚本(test_ux_round2/round3 为现行门禁,test_all 为旧冒烟待更新端口)

核心业务流程

flowchart LR
    A[访客提交预约] --> B[员工审批通过]
    B --> C[分时分配账户]
    C --> D[门禁分时授权 + 人脸授权]
    D --> E[生成二维码与访问令牌]
    E --> F[访客扫码通行]
    F --> G[记录归因查询]
    G --> H[到期回收账户并撤权]
  • 分时分配:同一账户可服务多访客的非重叠时段(time_allocations 冲突检测),池不足时自动创建 V + 15 位新账户。
  • 授权:门禁按填写值精确分时(到期自动失效);人脸永久下发,无卡号账户自动转人脸兜底。
  • 归因查询:刷卡/刷脸记录按分配时段二次校验,只归属到当前访客。
  • 回收:手动、过期自动(仅全窗口结束才回收,无分时记录的保留防误伤)、一键收回授权。

URL 路由

页面(12)

路径 功能
/ 首页
/login 登录页
/logout 退出
/visitor 访客预约页
/track 预约进度查询页
/approve 审批列表页
/visit/<id>/<token> 访客通行凭证页
/reservation/done/<id> 预约成功页
/qr/<rid> 二维码页(需登录)
/pass/<emp_no> 账户通行证页(需登录)
/admin 管理后台
/dev 开发者模式(仅超管)

核心 API

路径 方法 功能
/api/reservation POST 创建预约
/api/reservation/status /api/my-reservations /api/reservation/cancel POST 进度查询 / 我的预约 / 自助取消
/api/approve/<rid> /api/approve/batch POST 审批通过或拒绝 / 批量审批
/api/qr/<rid> /api/visitor-link/<rid> /api/emp-pass GET 二维码数据 / 访客链接 / 账户通行证
/api/door-record /api/face-record GET 刷卡 / 刷脸记录查询
/api/visitor-door-swipe/<rid> /api/visitor-swipe-query /api/emp-access-record GET 单条归因 / 按访客归因 / 按账号归因
/api/search-visitor GET 按姓名或手机搜索访客记录
/api/open-door /api/open-all-doors /api/open-all-task/<id> POST/GET 单门远开 / 批量远开(后台任务)/ 进度
/api/sync-doors /api/doors GET 同步门禁缓存 / 门禁列表
/api/sync-face-devs /api/face-devs /api/face-authorize POST/GET 同步人脸设备 / 列表 / 授权
/api/create-emp /api/authorize-emp /api/unified-authorize /api/quit-emp /api/emp-info /api/emp-permissions/<no> POST/GET 建号 / 授权 / 离职 / 查询
/api/add-account POST 账户池加号(先验 C3 真实存在)
/api/recycle/<rid> /api/recycle-all /api/recycle-expired POST 回收 / 全回收 / 过期回收
/api/door-visitor-visibility /api/face-devs-visibility GET/POST 访客页可见性配置
/api/dev/batch-create /api/dev/batch-approve /api/dev/task/<id> /api/dev/tasks /api/dev/reservations /api/dev/revoke POST/GET 开发者批量能力
/api/admin/create /api/admin/toggle/<u> /api/admin/toggle-approve/<u> POST 管理员管理(仅超管)
/api/home-card /api/announcement /api/site-settings GET/POST/PUT/DELETE 首页卡片 / 公告 / 站点设置(settings 蓝图)

测试脚本

脚本 用途 状态
test_ux_round2.py 人性化优化 10 项回归 10/10 通过(2026-10-25 实测)
test_ux_round3.py 短板修复 5 项回归 5/5 通过(2026-10-25 实测)
test_ux_regression.py 旧回归 49 项 历史全过
test_all.py 旧接口冒烟 87 项 待更新(硬编码 5002 端口)
test_api.py test_api_response.py test_ui_e2e.py 旧探针与端到端 按需运行

安全机制

机制 说明
密码存储 PBKDF2-SHA256(200k 迭代 + 随机盐),旧明文登录成功即自动升级,库中无明文
会话密钥 首次启动随机生成并持久化到 data/.secret_key,cookie 独立命名防串站
查询防护 查询类接口防枚举限流;手机号归一化后脱敏展示
授权安全 分时授权严格按填写值(结束不扩到 23:59);无卡号自动转人脸,不留永久刷卡权限
数据安全 data/ 被 .gitignore 排除,历史残留后续做 filter-repo 清理
公开面纪律 说明书与展示站不出现明文口令、密钥、内网地址与个人账号(本页已按此清理)

审批状态机

pending(待审批) ──通过──▶ approved(已通过) ──回收──▶ recycled(已回收)
       └──────拒绝──▶ rejected(已拒绝,终态,不可逆)
  • 只有 pending 能进审批动作;approved 的单只能走回收链(手动/过期/一键收回),不能二次审批。
  • 拒绝必须填原因,原因回显给访客;空原因拒绝会被接口直接打回。
  • 访客自助取消只允许 pending 单;已通过的单访客侧不可动。

授权矩阵

授权对象 方式 有效期 说明
门禁(刷卡) 永久授权 长期有效 后台手动下发,需账户有正常卡号
门禁(刷卡) 分时授权 严格按填写值 审批链路默认;到期平台自动失效
人脸设备 永久下发 长期有效 无需卡号;到期靠回收时统一撤销
无卡号账户 自动转人脸 同人脸规则 刷卡授权报缺卡时自动兜底,不让访客白等
  • 分时开始时间必须晚于当前一定分钟数,否则平台直接拒绝;预约提交时即提前拦截,不合法的单建不出来。
  • 授权结果逐项回显(门禁逐门、人脸逐台),失败项单独标出,不影响成功的项。

建号与回收规则

  • 建号:固定前缀 V + 15 位(纳秒时间戳尾数加随机后缀),满足 C3 16 位硬上限;入库前做唯一性重试,冲突即换号。
  • 分配:同一账户可服务多访客的非重叠时段,冲突判定精确到分钟,边界相接不算冲突。
  • 回收三档:手动回收(按单)/ 一键全回收(仅超管)/ 过期自动回收(仅全窗口结束,无分时记录的保留防误伤)。
  • 撤权:回收时按授权原路撤销,人脸走取消授权,无卡号转全量的账户一并撤回。

排障速查

现象 先查哪里
审批通过但没收到二维码 分配记录的授权结果:门禁是否报缺卡(已转人脸兜底)、C3 通道是否超时
门禁刷卡无反应 账户授权窗口是否已生效或已过期;门禁是否在本次授权门内
人脸识别不到人 设备是否在授权清单内;同名设备是否按物理地址消歧到正确那台
记录查不到某次通行 通行时间是否落在分配窗口内;窗口外记录归属到其他单
同步后数量对不上 先看同步时间是否新鲜,再看缓存与平台的启用态口径
接口返回签名错误 检查参与签名的参数是否含空值(空值不参签但保留在请求体)

联系方式

角色 联系方式
管理员账号 不对外公开(后台 /login 登录)
技术支持电话 195****3095
技术支持微信 见管理员
服务地址 http://119.145.17.34:5102
Git 仓库 Gitea · LZ-TK-Station · TK-QR-Gate

← 常见问题 返回首页