气田异常管理系统 (Exception Management System)

气田生产异常全流程闭环管理系统，支持异常上报、接收、处置、审核、销项等完整业务流程，集成钉钉通知推送。

📋 目录

技术栈
项目结构
功能特性
快速开始
环境变量配置
API文档
数据库模型
业务流程
用户角色与权限

技术栈

后端

技术	版本	说明
Python	3.11+	运行环境
Flask	3.0.0	Web框架
Flask-SQLAlchemy	3.1.1	ORM
Flask-JWT-Extended	4.6.0	JWT认证
Flask-CORS	4.0.0	跨域支持
APScheduler	3.10.4	定时任务调度
Gunicorn	21.2.0	生产WSGI服务器
requests	2.31.0	HTTP客户端(钉钉API)

前端

技术	版本	说明
Vue	3.4+	前端框架
Vite	5.0	构建工具
Element Plus	2.4+	UI组件库
Vue Router	4.2+	路由管理
Pinia	2.1+	状态管理
Axios	1.6+	HTTP请求
ECharts	5.4+	数据可视化
Sass	1.69+	CSS预处理器

项目结构

exception-system/
├── app/                          # Flask后端应用
│   ├── __init__.py               # 应用工厂
│   ├── api/                      # API蓝图
│   │   ├── auth.py               # 认证接口(登录/登出/Token刷新)
│   │   ├── users.py              # 用户管理接口
│   │   ├── exceptions.py         # 异常管理接口(CRUD+流程操作)
│   │   ├── statistics.py         # 统计分析接口
│   │   ├── dict.py               # 数据字典接口
│   │   ├── upload.py             # 文件上传接口
│   │   ├── health.py             # 健康检查接口
│   │   ├── logs.py               # 操作日志接口
│   │   └── export.py             # 数据导出接口
│   ├── models/                   # 数据库模型
│   │   └── __init__.py           # User, ExceptionRecord, DisposalHistory等
│   ├── services/                 # 业务逻辑层
│   │   ├── exception_service.py  # 异常业务服务
│   │   ├── dingtalk_service.py   # 钉钉集成服务
│   │   └── scheduler_service.py  # 定时任务服务
│   └── utils/                    # 工具模块
│       ├── auth_utils.py         # 认证工具(角色校验等)
│       ├── jwt_callbacks.py      # JWT回调处理
│       └── error_handlers.py     # 全局错误处理
├── config/                       # 配置文件
│   └── config.py                 # 多环境配置(开发/生产/测试)
├── frontend/                     # Vue前端应用
│   ├── src/
│   │   ├── api/                  # API请求封装
│   │   │   ├── auth.js           # 认证API
│   │   │   ├── exception.js      # 异常API
│   │   │   ├── statistics.js     # 统计API
│   │   │   └── dingtalk.js       # 钉钉API
│   │   ├── router/               # 路由配置
│   │   ├── store/                # Pinia状态管理
│   │   ├── utils/                # 工具函数
│   │   │   ├── request.js        # Axios封装(拦截器/Token刷新)
│   │   │   └── dingtalk.js       # 钉钉JS工具
│   │   └── views/                # 页面视图
│   │       ├── Dashboard.vue     # 仪表盘
│   │       ├── ExceptionList.vue # 异常列表
│   │       ├── ExceptionForm.vue # 异常表单(上报/编辑)
│   │       ├── ExceptionDetail.vue # 异常详情
│   │       ├── Statistics.vue    # 统计分析
│   │       ├── UserList.vue      # 用户管理
│   │       ├── DictList.vue      # 数据字典管理
│   │       ├── Login.vue         # 登录页
│   │       ├── Layout.vue        # PC端布局
│   │       └── mobile/           # 移动端适配页面
│   ├── package.json
│   └── vite.config.js
├── migrations/                   # 数据库迁移脚本
│   └── 001_init_schema.sql       # 初始数据SQL
├── data/                         # SQLite数据库文件(开发)
├── uploads/                      # 上传文件目录
├── logs/                         # 日志目录
├── docker-compose.yml            # Docker编排配置
├── Dockerfile                    # 后端镜像构建
├── .env.docker                   # Docker环境变量模板
├── gunicorn.conf.py              # Gunicorn生产配置
├── requirements.txt              # Python依赖
├── run.py                        # 应用入口
└── README.md                     # 项目说明文档

功能特性

核心业务功能

异常上报 - 支持多级分类、图片附件、自动编号
流程管理 - 上报→接收→处置→审核→销项全流程闭环
退回与重报 - 接收人可退回，上报人可修改后重新提交
撤回机制 - 上报人可在接收前撤回异常
延期管理 - 处置人可申请延期，接收人审批
取消功能 - 接收人/管理员可取消异常
多轮处置 - 支持处置不通过重新处置

管理功能

用户管理 - 多角色支持，数据权限隔离
数据字典 - 异常类型三级分类配置
统计分析 - 多维度数据统计，ECharts可视化
操作日志 - 全流程审计日志
数据导出 - Excel格式导出

集成功能

钉钉通知 - 异常状态变更实时推送
钉钉免登 - 通过钉钉授权码登录(待完善)
文件上传 - 图片上传，支持压缩和预览

技术特性

JWT认证 - Access Token + Refresh Token 双令牌
乐观锁 - 并发操作版本控制，防止冲突
CORS - 灵活的跨域配置
健康检查 - API健康检查端点
响应式 - PC端与移动端自适应布局

快速开始

环境要求

Python 3.11+
Node.js 18+ (前端开发)
npm 或 pnpm

本地开发

1. 克隆项目

git clone <repository-url>
cd exception-system

2. 后端启动

# 创建Python虚拟环境
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

# 安装依赖
pip install -r requirements.txt

# 初始化数据库
flask init-db

# 创建管理员账号
flask create-admin
# 输出: 用户名: admin  密码: admin123

# 启动开发服务器
python run.py
# 后端运行在 http://localhost:5000

3. 前端启动

cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
# 前端运行在 http://localhost:5173

Docker部署

1. 配置环境变量

# 复制环境变量模板
cp .env.docker .env

# 编辑 .env 文件，设置必要配置
# 至少修改 SECRET_KEY 和 JWT_SECRET_KEY

2. 启动服务

# 构建并启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f backend

3. 访问应用

前端: http://localhost:80
后端API: http://localhost:5000/api/v1/

环境变量配置

变量名	必填	说明	示例
`SECRET_KEY`	生产必须	Flask应用密钥	`your-random-secret-key`
`JWT_SECRET_KEY`	生产必须	JWT签名密钥	`your-jwt-secret-key`
`DATABASE_URL`	生产必须	数据库连接URL	`sqlite:///data/exception.db`
`FLASK_ENV`	否	运行环境	`development` / `production`
`DINGTALK_APP_KEY`	否	钉钉应用AppKey	-
`DINGTALK_APP_SECRET`	否	钉钉应用AppSecret	-
`DINGTALK_AGENT_ID`	否	钉钉微应用AgentId	-
`DINGTALK_CHAT_ID`	否	钉钉群会话ID	-
`CORS_ORIGINS`	否	允许的跨域来源(逗号分隔)	`http://localhost:5173`

API文档

所有API前缀: /api/v1/

认证接口 `/api/v1/auth`

方法	路径	说明	权限
POST	`/login`	用户登录	公开
POST	`/refresh`	刷新Token	Refresh Token
POST	`/logout`	用户登出	需登录
POST	`/dingtalk-login`	钉钉免登	公开

异常管理 `/api/v1/exceptions`

方法	路径	说明	权限
POST	`/`	异常上报	上报人/接收人/管理员
GET	`/`	获取异常列表	需登录(数据隔离)
GET	`/{id}`	获取异常详情	需登录
POST	`/{id}/accept`	接收确认	接收人
POST	`/{id}/reject`	退回上报人	接收人
POST	`/{id}/resubmit`	重新提交	上报人
POST	`/{id}/dispose`	提交处置结果	处置人
POST	`/{id}/approve`	销项审核	接收人
POST	`/{id}/delay/approve`	延期审批	接收人
POST	`/{id}/cancel`	取消异常	接收人/系统管理员
POST	`/{id}/withdraw`	撤回异常	上报人

用户管理 `/api/v1/users`

方法	路径	说明	权限
GET	`/`	用户列表	管理员
POST	`/`	创建用户	管理员
PUT	`/{id}`	更新用户	管理员
DELETE	`/{id}`	删除用户	系统管理员

其他接口

路径前缀	说明
`/api/v1/statistics`	统计分析
`/api/v1/dict`	数据字典管理
`/api/v1/upload`	文件上传
`/api/v1/operation-logs`	操作日志
`/api/v1/export`	数据导出
`/api/v1/health`	健康检查

响应格式

{
  "code": 200,
  "data": { ... },
  "message": "操作成功"
}

错误码

错误码	说明
200	成功
400	请求参数错误
401	未认证/Token过期
403	无权限
404	资源不存在
409	状态冲突(并发操作)
500	服务器内部错误

数据库模型

核心表

users - 用户表

字段	类型	说明
id	INTEGER	主键
username	VARCHAR(50)	登录用户名(唯一)
display_name	VARCHAR(100)	显示名称
role	VARCHAR(20)	角色
site	VARCHAR(50)	所属站点
phone	VARCHAR(20)	手机号
dingtalk_user_id	VARCHAR(100)	钉钉用户ID
password_hash	VARCHAR(128)	密码哈希
is_active	INTEGER	是否启用

exception_records - 异常记录表

字段	类型	说明
id	INTEGER	主键
exception_no	VARCHAR(20)	异常编号(唯一)
site	VARCHAR(50)	所属站点
level	VARCHAR(20)	异常级别(站级/公司级)
category_1/2/3	VARCHAR(50)	三级分类
occur_date	DATE	发生日期
occur_time	TIME	发生时间
description	TEXT	异常描述
photo_urls	TEXT	照片URL(JSON)
reporter	VARCHAR(50)	上报人
receiver	VARCHAR(50)	接收人
handler	VARCHAR(50)	处置人
status	VARCHAR(20)	当前状态
version	INTEGER	乐观锁版本号

disposal_history - 处置历史表

记录每次处置操作的详细信息，支持多轮处置。

operation_logs - 操作审计日志

记录所有状态变更操作，包含操作人、角色、IP地址等。

exception_dict - 异常类型字典

配置三级异常分类的可选值。

业务流程

                    ┌─────────────────────────────────────────────┐
                    │            异常生命周期流程图                 │
                    └─────────────────────────────────────────────┘

    上报人                    接收人                    处置人
      │                        │                        │
      ▼                        │                        │
 ┌─────────┐                   │                        │
 │  上 报   │                   │                        │
 └────┬────┘                   │                        │
      │                        │                        │
      ▼                        │                        │
 ┌─────────┐     接收确认      │                        │
 │ 待接收   │──────────────────▶│                        │
 └────┬────┘                   │                        │
      │                        │                        │
      │◀─── 退回 ──────────────┤                        │
      │                        │                        │
 ┌─────────┐                   │                        │
 │ 已退回   │                   │                        │
 └────┬────┘                   │                        │
      │                        │                        │
      │ 重新提交                │                        │
      │───▶ 待接收              │                        │
      │                        │                        │
      │              ┌─────────▼─────────┐              │
      │              │      处置中        │──────────────▶│
      │              └───────────────────┘              │
      │                        │                        │
      │                        │    提交处置结果         │
      │                        │◀───────────────────────┤
      │                        │                        │
      │                        ▼                        │
      │              ┌───────────────────┐              │
      │              │      待审核        │              │
      │              └─────────┬─────────┘              │
      │                        │                        │
      │                        │ 审核                    │
      │                        ▼                        │
      │              ┌───────────────────┐              │
      │              │    ┌─────────┐    │              │
      │              │    │  审核   │    │              │
      │              │    └────┬────┘    │              │
      │              │         │         │              │
      │              │    ┌────┴────┐    │              │
      │              │    ▼         ▼    │              │
      │              │  通过     不通过   │              │
      │              │    │         │    │              │
      │              │    ▼         ▼    │              │
      │              │ 已销项    处置中   │──────────────▶│
      │              └───────────────────┘              │
      │                                                 │
      │           ┌───────────────────┐                 │
      │           │    已取消          │                 │
      │           └───────────────────┘                 │
      │                                                 │
      │           ┌───────────────────┐                 │
      │           │  延期待审批        │                 │
      │           └───────────────────┘                 │
      │                                                 │

状态说明

状态	说明	可执行操作
待接收	已上报，等待接收人确认	接收/退回/撤回(上报人)/取消
已退回	被接收人退回	重新提交/取消
处置中	已接收，等待处置	提交处置/申请延期/取消
延期待审批	处置人申请延期	延期审批(通过/拒绝)
待审核	处置完成，等待审核	审核(通过/不通过)/取消
已销项	审核通过，异常关闭	-
已取消	异常被取消	-

用户角色与权限

角色列表

角色	数据权限	主要操作
系统管理员	全部数据	用户管理、系统配置、取消异常
管理员	全部数据	用户管理、查看统计
上报人	仅自己上报的	上报异常、撤回、重新提交
接收人	本站点数据	接收/退回/审核/取消、指派处置人
处置人	指派给自己的	提交处置结果、申请延期

数据隔离规则

上报人: 只能查看和操作自己上报的异常
接收人: 只能查看和操作本站点的异常
处置人: 只能查看被指派处置的异常
管理员/系统管理员: 可查看所有异常

生产部署建议

安全配置

必须修改 SECRET_KEY 和 JWT_SECRET_KEY 为强随机字符串
生产环境使用 MySQL/PostgreSQL 替代 SQLite
配置 HTTPS
限制 CORS_ORIGINS 为实际前端域名

Gunicorn配置

生产环境使用Gunicorn运行:

gunicorn -c gunicorn.conf.py run:app

配置文件 gunicorn.conf.py 默认配置:

绑定: 0.0.0.0:5000
工作进程: 4
超时: 120秒
日志: /app/logs/

反向代理(Nginx)

server {
    listen 80;
    server_name your-domain.com;

    location / {
        root /path/to/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

常见问题

Q: 忘记管理员密码怎么办?

# 直接修改数据库
sqlite3 data/exception_dev.db
UPDATE users SET password_hash='<new-hash>' WHERE username='admin';

Q: 如何添加新的异常分类?

通过数据字典管理界面(/dict)添加，或直接操作 exception_dict 表。

Q: 钉钉通知不工作?

检查以下配置:

.env 中钉钉相关变量是否正确
钉钉应用是否已发布
网络是否能访问钉钉API

许可证

本项目为内部使用系统，请勿外传。

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
app		app
config		config
docs		docs
frontend		frontend
migrations		migrations
nginx		nginx
scripts		scripts
tests		tests
uploads		uploads
.dockerignore		.dockerignore
.env.docker		.env.docker
.env.example		.env.example
.env.tencent		.env.tencent
.gitignore		.gitignore
API接口文档.md		API接口文档.md
DINGTALK_APP.md		DINGTALK_APP.md
DOCKER.md		DOCKER.md
Dockerfile		Dockerfile
README.md		README.md
deploy-tencent.sh		deploy-tencent.sh
deploy.bat		deploy.bat
deploy.sh		deploy.sh
docker-compose.tencent.yml		docker-compose.tencent.yml
docker-compose.yml		docker-compose.yml
exception_system_schema.sql		exception_system_schema.sql
gunicorn.conf.py		gunicorn.conf.py
init-server.sh		init-server.sh
package-lock.json		package-lock.json
package.json		package.json
requirements.txt		requirements.txt
run.py		run.py
开发任务清单.md		开发任务清单.md
气田异常管理系统设计说明.md		气田异常管理系统设计说明.md

Folders and files

Latest commit

History

Repository files navigation

气田异常管理系统 (Exception Management System)

📋 目录

技术栈

后端

前端

项目结构

功能特性

核心业务功能

管理功能

集成功能

技术特性

快速开始

环境要求

本地开发

1. 克隆项目

2. 后端启动

3. 前端启动

Docker部署

1. 配置环境变量

2. 启动服务

3. 访问应用

环境变量配置

API文档

认证接口 /api/v1/auth

异常管理 /api/v1/exceptions

用户管理 /api/v1/users

其他接口

响应格式

错误码

数据库模型

核心表

users - 用户表

exception_records - 异常记录表

disposal_history - 处置历史表

operation_logs - 操作审计日志

exception_dict - 异常类型字典

业务流程

状态说明

用户角色与权限

角色列表

数据隔离规则

生产部署建议

安全配置

Gunicorn配置

反向代理(Nginx)

常见问题

Q: 忘记管理员密码怎么办?

Q: 如何添加新的异常分类?

Q: 钉钉通知不工作?

许可证

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

认证接口 `/api/v1/auth`

异常管理 `/api/v1/exceptions`

用户管理 `/api/v1/users`