平台架构与技术栈
现状口径:信创版 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 分钟,失败登录记审计可追溯
大屏脱敏 :免登录公开接口手机号打码,证件号/整改说明等字段剔除
相关阅读
⬆️
安全生产一体化管理平台 · TK-Safe-Upload · 说明书 · Leyon WorkStation