API 接口文档 · 安全生产一体化管理平台展示说明书架构日志
第 15 章

🔌API 接口文档

技术参考

通用说明

  • 认证:Session Cookie(tk_safe_session,7 天有效)
  • 响应:{"success": true, "data": ...} 或 {"success": false, "msg": "..."}
  • 未认证返回 401,权限不足返回 403,登录触发限流返回 429
  • 说明书站内另有 CSRF Token 接口:GET /api/csrf-token(表单提交时带 X-CSRF-Token 或 _csrf 字段)

认证流程

sequenceDiagram
    participant U as 用户浏览器
    participant F as Flask app.py
    participant DB as PostgreSQL
    U->>F: POST /login (username, password)
    F->>F: bcrypt 校验(旧 SHA-256 自动升级)
    F->>DB: SELECT users WHERE username=?
    DB-->>F: 用户记录
    F->>F: 验证密码 + 角色
    F-->>U: Set-Cookie tk_safe_session
302 → /portal U->>F: GET /admin/dashboard
(Cookie: tk_safe_session) F->>F: 验证 Session(停用账号即时失效) F->>DB: 参数化查询 DB-->>F: 数据 F-->>U: HTML 页面

认证接口

登录

POST /login
Content-Type: application/x-www-form-urlencoded
username=Leon&password=
→ {"success": true, "role": "company_admin"}

管理员账号 admin 已于 2026-10-09 改名为 Leon;连续 5 次失败按 IP 锁定 5 分钟(429)。

退出

GET /logout → 302 重定向

移动端接口

隐患随手拍

POST /api/photo/submit (multipart/form-data)
file_0~file_5: 照片(最多6张)
title, description, level, org_id, point_id, point_name
→ {"success": true, "data": {"id": 123}}

巡查打卡

POST /api/patrol/checkin (multipart/form-data)
file_0~file_3: 照片(最多4张)
plan_id, point_name, org_id, record, status
→ {"success": true, "data": {"id": 456}}

隐患举报

POST /api/report/submit (multipart/form-data)
file_0~file_5: 照片
title, description, level, org_id, point_name, anonymous(0/1)
→ {"success": true, "data": {"id": 789}}

完成任务

POST /api/task/<id>/done → {"success": true}

培训签到

POST /api/training/<id>/sign → {"success": true}

修改密码

POST /api/profile/password (JSON)
{"old_password": "旧密码", "new_password": "新密码(≥6位)"}

PC 后台接口

通用 CRUD

GET  /api/admin/<table>/list
POST /api/admin/<table>/add
POST /api/admin/<table>/<id>/update
POST /api/admin/<table>/<id>/delete

支持的表: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

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

隐患管理

POST /api/admin/hazard/<id>/assign   {assignee, assignee_org, days}
POST /api/admin/hazard/<id>/rectify  (multipart: note + file_0~file_5)
POST /api/admin/hazard/<id>/review   {pass:"1"/"0", note}
POST /api/admin/hazard/<id>/major    {major_flag, stop_work}
GET  /api/admin/hazard/<id>/detail

作业许可

POST /api/admin/permit/<id>/approve  {level: 1/2}
POST /api/admin/permit/<id>/finish   {note}

物资出入库

POST /api/admin/material/<id>/io  {io_type:"in"/"out", quantity, note}

风险复核

POST /api/admin/risk/<id>/review  {result:"ok", note}

用户管理

POST /api/admin/users/add
POST /api/admin/users/<id>/update
POST /api/admin/users/<id>/delete

系统配置

POST /api/admin/setting/save  {key, value}
POST /api/admin/send-test-message  channel, target, title

数据导入导出

GET  /admin/import-template/<table>  → CSV 模板下载
POST /api/admin/<table>/import       → CSV 批量导入
GET  /admin/export/<table>?fmt=excel → CSV 导出
GET  /admin/export/<table>?fmt=pdf   → PDF 导出

培训进阶接口

课时与进度

GET  /api/training/<id>/lessons
GET  /api/training/<id>/lesson/<lid>
POST /api/training/<id>/lesson/<lid>/progress  {progress, watch_time_sec}  → 90 分视为完成
GET/POST /api/training/<id>/lesson/<lid>/notes  → 学习笔记
GET  /api/training/<id>/certificate             → 是否可领证
POST /api/training/<id>/certificate/generate    → 生成 12 位证书码

课程管理(后台)

GET  /api/admin/training/<id>/detail
POST /api/admin/training/<id>/update
POST /api/admin/training/<id>/lessons/add
POST /api/admin/training_courses/upload  (multipart: 课件文件)

个人资料

POST /api/profile/update  {name, phone}  → 本人更新姓名与手机号

大屏接口

GET /api/screen/data → 脱敏后的态势数据(手机号打码,隐患明细仅白名单字段,30 秒缓存)

健康检查

GET /health → {"status": "ok", "db": true}(托管探活,免登录)

相关阅读