平台架构与技术栈 · 安全生产一体化管理平台展示说明书架构日志
第 06 章

🧱平台架构与技术栈

技术参考

现状口径:信创版 5112,PostgreSQL 专库,Leon-Control 托管。旧源站 5111(SQLite)仅作对照保留。 本文档侧重接口可用性:列出平台全部对外接口、调用条件、权限范围与可用性状态,供二次开发与集成参考。

整体架构

TK-Safe-UpLoad 采用经典的三层架构,所有业务通过 REST API 对外提供服务,接口可用性按角色分级控制。详细数据模型见 数据库表结构,接口规范见 REST API 文档,系统管理见 系统管理。

graph TB
    subgraph Frontend["表现层 · Frontend"]
        M["📱 移动端 /m
Tailwind + Alpine.js"] PC["🖥️ PC后台 /admin
ECharts 统计图表"] SP["📊 数据大屏 /screen
轮播 + 实时刷新"] PT[" unified 门户 /portal
三端聚合入口"] end subgraph Backend["业务层 · Backend (Flask)"] API["REST API 路由
app.py 86 条"] AUTH["认证 · 会话管理
RBAC 5 角色"] MD["Markdown 渲染
Jinja2 模板引擎"] AI["AI 中台数据接口
标准化数据输出"] end subgraph Storage["数据层 · Storage"] DB["PostgreSQL tk_safe_xc
36 张表"] UPL["文件存储 uploads/"] LOG["操作日志 审计留痕"] CACHE["内存缓存 30s/60s"] end subgraph Ext["外部系统"] ENG["工程反馈系统"] SAFE["安全管理平台"] SMART["智慧工地"] AIENG["AI 分析引擎"] end M --> API PC --> API SP --> API PT --> API API --> AUTH AUTH --> MD MD --> DB API --> DB API --> UPL API --> LOG API --> CACHE API --> AI AI --> AIENG ENG --> AI SAFE --> AI SMART --> AI AIENG --> AI

核心路由

graph LR
    A["浏览器
192.168.11.70:5112"] --> B["Flask app.py"] B --> C{路径判断} C -->|/m| D["移动端模板
m/*.html"] C -->|/admin| E["PC后台模板
admin/*.html"] C -->|/screen| F["数据大屏
screen.html"] C -->|/portal| G["统一门户
portal.html"] C -->|/api| H["REST API
返回 JSON"] C -->|/uploads| I["上传附件
登录后可访问"] C -->|/health| J["健康检查
免登录"]

技术栈详情

技术 版本/说明 用途
Python 3.12 后端运行时
Flask 3.1.1 Web 框架(多线程 serving,生产 gunicorn 4 进程)
PostgreSQL 11.22(openGauss 兼容目标) 远端专库 tk_safe_xc,36 张表
psycopg2 2.9.13,连接池 2–32 PG 驱动与连接复用
Jinja2 模板引擎 服务端渲染 HTML(35 个模板)
Tailwind CSS 本地 vendor(无外网依赖) 响应式 UI 样式
Alpine.js 本地 vendor 轻量级前端交互
ECharts 本地 vendor 数据可视化图表
bcrypt 带盐哈希 cost 12 密码存储(旧 SHA-256 登录时自动升级)
fpdf2 PDF 导出 报表 PDF 生成
segno 二维码生成 说明书分享二维码

接口可用性总览

平台提供 86 条路由,其中 REST API 约 60 条。所有接口按角色分级,可用性状态如下:

角色 可用接口范围 说明
company_admin(公司管理员) 全部接口 最高权限,含用户管理、系统配置、考核
sub_admin(子公司管理员) 除用户管理/系统配置外的后台接口 可管理台账、隐患、培训、应急
inspector(巡查员) 移动端全部 + 隐患/巡查/风险/物资只读 + 隐患详情 无写权限,仅查看
merchant(商户) 移动端 + 个人中心 举报、培训、资料查阅
staff(普通员工) 移动端 + 个人中心 随手拍、巡查、任务、培训、资料
匿名(未登录) /health、/api/screen/data、/login、隐患举报(可选匿名) 大屏脱敏数据

认证与会话接口

方法 路径 认证 可用性 说明
POST /login 无 全部 表单/JSON 双兼容,bcrypt 校验,IP 限流(5 次/5 分钟)
GET /logout Session 已登录 清会话并记审计
GET /health 无 全部 托管探活,附带数据库连通性
GET /api/csrf-token 无 全部 返回 CSRF Token(可选)
POST /api/profile/password Session 已登录 校验旧口令后改密
POST /api/profile/update Session 已登录 更新姓名与手机号

移动端接口(/m)

方法 路径 认证 可用性 说明
GET /m Session 已登录 移动端首页(统计卡片 + 待办 + 快捷操作)
GET /m/photo Session 已登录 隐患随手拍页面
POST /api/photo/submit Session 已登录 拍照上报,自动绑定点位,最多 6 张照片,单文件 8MB
GET /m/patrol Session 已登录 巡查打卡页面
POST /api/patrol/checkin Session 已登录 按计划点位签到,最多 4 张照片
GET /m/tasks Session 已登录 我的任务列表
POST /api/task//done Session 本人/管理员 确认完成任务
GET /m/report Session 已登录 隐患举报页面
POST /api/report/submit Session 已登录 实名或匿名举报,最多 6 张照片
GET /m/training Session 已登录 培训课程列表
POST /api/training//sign Session 已登录 课程签到
POST /api/training//progress Session 已登录 课时进度上报(≥90% 视为完成)
GET /api/training//lessons Session 已登录 课时列表
POST /api/training//certificate/generate Session 已登录 生成 12 位证书码(需全部完成)
GET /m/library Session 已登录 资料查阅(预案/风险卡/培训文档)
GET /m/alerts Session 已登录 预警中心(逾期/设备/证件/风险/物资)
GET /m/me Session 已登录 个人中心

PC 后台接口(/admin)

通用 CRUD

方法 路径 认证 可用性 说明
GET /api/admin/
/list
Session 后台角色 分页列表,支持 org 筛选 + kw 服务端搜索
POST /api/admin/
/add
Session 后台角色 新增记录,流程字段被拦截保护
POST /api/admin/
//update
Session 后台角色 更新记录
POST /api/admin/
//delete
Session 后台角色 删除记录

支持的表:organizations, equipment, personnel, related_parties, materials, risk_points, hazards, special_actions, training_courses, training_lessons, training_plans, emergency_plans, drill_records, contacts, message_templates, alert_rules, assessment, risk_reports, violation_reports, work_permits, patrol_plans(21 张)

考核与配置表仅公司管理员可维护;隐患状态类字段禁止通用接口直写,只能走闭环接口。

隐患治理闭环

方法 路径 认证 可用性 说明
POST /api/admin/hazard//assign Session 后台角色 指定整改负责人/单位/期限,自动生成 rectify 任务
POST /api/admin/hazard//rectify Session 负责人/管理员 提交整改说明与佐证照片(8MB 限制)
POST /api/admin/hazard//review Session 后台角色 通过则销号并办结任务,退回则回到整改中,销号须写验收依据
POST /api/admin/hazard//major Session 后台角色 重大隐患挂牌督办与强制停工标记
GET /api/admin/hazard//detail Session 后台/巡查员 基础信息 + 照片 + 流转时间线

作业许可

方法 路径 认证 可用性 说明
POST /api/admin/permit//approve Session 后台角色 多级审批(level 1/2,未过一级直接二级被拒)
POST /api/admin/permit//finish Session 后台角色 工作完工销项

物资管理

方法 路径 认证 可用性 说明
POST /api/admin/material//io Session 后台角色 原子加减库存并写流水,超库存直接拒绝
GET /api/admin/material//io-list Session 后台角色 出入库流水查询

风险管理

方法 路径 认证 可用性 说明
POST /api/admin/risk//review Session 后台角色 风险点复核登记,顺延下次复核日期

用户管理

方法 路径 认证 可用性 说明
POST /api/admin/users/add Session 仅公司管理员 新增用户
POST /api/admin/users//update Session 仅公司管理员 修改角色/停用/启用
POST /api/admin/users//delete Session 仅公司管理员 删除用户(保留至少一个可用管理员)

系统配置

方法 路径 认证 可用性 说明
POST /api/admin/setting/save Session 仅公司管理员 保存系统配置
POST /api/admin/send-test-message Session 仅公司管理员 发送测试消息

培训管理

方法 路径 认证 可用性 说明
GET /api/admin/training//detail Session 后台角色 课程详情
POST /api/admin/training//update Session 后台角色 更新课程
POST /api/admin/training//lessons/add Session 后台角色 添加课时
POST /api/admin/training_courses/upload Session 后台角色 上传课件(视频/PDF/文档)

数据导入导出接口

方法 路径 认证 可用性 说明
GET /admin/import-template/
Session 后台角色 CSV 模板下载(7 类台账)
POST /api/admin/
/import
Session 后台角色 CSV 批量导入(兼容 UTF-8-BOM 与 GBK)
GET /admin/export/
?fmt=excel
Session 后台角色 CSV 导出(UTF-8 BOM)
GET /admin/export/
?fmt=pdf
Session 后台角色 PDF 导出

培训进阶接口

方法 路径 认证 可用性 说明
GET /api/training//lessons Session 已登录 课时列表
GET /api/training//lesson/ Session 已登录 课时详情
POST /api/training//lesson//progress Session 已登录 课时进度上报(≥90% 视为完成)
GET/POST /api/training//lesson//notes Session 已登录 学习笔记
GET /api/training//certificate Session 已登录 是否可领证
POST /api/training//certificate/generate Session 已登录 生成 12 位证书码(需全部完成)

大屏接口

方法 路径 认证 可用性 说明
GET /api/screen/data 无 全部 脱敏态势数据(手机号打码,隐患明细仅白名单字段,30 秒缓存)

AI 中台接口

平台作为 AI 中台的数据底座,提供标准化数据输出供 AI 分析引擎消费:

方法 路径 认证 可用性 说明
GET /api/screen/data 无 全部 脱敏态势数据,AI 中台可直接消费
GET /api/admin/
/list
Session 后台角色 结构化台账数据,支持分页与筛选,供 AI 分析
GET /api/admin/hazard//detail Session 后台/巡查员 隐患全流程数据(含流转记录),供 AI 生成整改建议
GET /health 无 全部 健康检查,附带数据库连通性

AI 中台通过标准化接口汇聚本平台数据 + 工程反馈系统 + 安全管理平台 + 智慧工地等多源数据,进行 AI 分析(报告生成、趋势预测、风险评估、整改建议、培训分析),并将结果回写平台,为领导提供一站式智能分析看板。

项目文件结构

TK-Safe-Xinchuang/   # 信创版代码目录(源站 5111 保持不动)
├── app.py              # Flask 主应用(约 2440 行,86 条路由)
├── blueprints/         # 已抽离蓝图:auth 登录登出、mobile 移动端、admin_pages 后台页面
├── models.py           # 数据层(约 1088 行,PG 兼容层 + 通用 CRUD + 统计预警)
├── config.py           # 项目配置(端口/角色/分级常量/PG 数据源,口令走环境变量)
├── db_init.py          # 数据库初始化与种子数据
├── govern_data.py      # 数据治理(默认预览,--apply 执行)
├── start.sh            # 启动脚本(--install 装依赖)
├── gunicorn.conf.py    # 生产配置(4 进程 4 线程)
├── requirements.txt    # 依赖清单
├── data/               # 运行态:secret_key、pg_dsn.txt(600 权限)、日志
├── uploads/            # 上传文件存储(photo/patrol/report/rectify/training/general)
├── static/             # 静态资源(vendor/ 本地化三件套 + tk-theme.css)
├── templates/          # Jinja2 模板(35 个:base/login/portal/screen + m/10 + admin/21)
├── test_all.py         # 87 项接口冒烟(自清理)
├── test_links.py       # 96 项链接可达性
├── test_ui.py          # 55 项真点击交互(Playwright)
├── test_flows.py       # 85 项多账号业务闭环
├── test_offline.py     # 断网可用性专项
└── venv/               # Python 虚拟环境

部署架构

项目 说明
部署设备 192.168.11.70(x86_64 Ubuntu)
服务端口 5112(源站 5111 保持不动)
公网地址 http://119.145.17.34:5112/(NAT 映射已放行)
内网地址 http://192.168.11.70:5112/
进程管理 Leon-Control 统一管理(服务卡片 id 25,自动重启 + 健康检查)
数据专库 青云 ARM 服务器 172.168.10.17:5432,库 tk_safe_xc,口令走环境变量或受限文件
启动依赖 Python 3.12,Flask 3.1.1,psycopg2-binary 2.9.13,bcrypt,fpdf2

安全机制

  • 密码存储:bcrypt 带盐哈希;旧 SHA-256 无盐哈希登录成功后自动升级,数据库不存储明文密码
  • 会话管理:Flask Session Cookie,HttpOnly + SameSite=Lax,7 天有效期;停用账号会话即时失效
  • 权限控制:基于角色的访问控制(RBAC),5 级角色体系;隐患整改另做负责人归属校验
  • 操作日志:全操作留痕,IP 地址记录,支持按模块/关键词检索
  • 文件安全:扩展名白名单,上传文件重命名,照片路径入库前正则校验
  • CSRF 防护:SameSite Cookie + Origin/Referer 同源校验,可选 CSRF Token
  • 登录防护:连续 5 次失败按 IP 锁定 5 分钟,失败登录记审计可追溯
  • 大屏脱敏:免登录公开接口手机号打码,证件号/整改说明等字段剔除

相关阅读