现状口径:信创版 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 分钟,失败登录记审计可追溯
- 大屏脱敏:免登录公开接口手机号打码,证件号/整改说明等字段剔除
相关阅读
| | | | | | | | |