第 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}(托管探活,免登录)