FaultRecord:基于 FastAPI 的地铁线路问题工单填报系统

可用于地铁线路问题工单的管理与数据统计。支持多线路管理、问题录入、查询、修改、复测,具备用户注册登录、权限控制、数据可视化及响应式设计,适配PC和移动端。【此简介由AI生成】

Branch1Tags0
FilesLast commitLast update
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago

地铁线路问题工单填报系统

基于 FastAPI 的地铁线路问题工单填报系统,支持多线路管理、问题录入、查询、修改、复测和数据统计功能。

功能特性

  • ✅ 用户注册和登录(管理员账号:admin/123)
  • ✅ 多Excel文件和多Sheet(线路)支持
  • ✅ 问题录入、查询、修改、复测
  • ✅ 数据统计可视化
  • ✅ 响应式设计(支持PC和移动端)
  • ✅ 权限控制(管理员可修改和复测)
  • ✅ 双击表格行查看详情
  • ✅ 问题详情卡片分区展示,支持滚动

技术栈

  • 后端: FastAPI
  • 前端: Jinja2模板 + HTML/CSS/JavaScript
  • 数据处理: pandas, openpyxl
  • 环境管理: UV

安装和运行

前置要求

  1. Python 3.13+
  2. UV 包管理器(推荐使用官方安装脚本)

1. 安装 UV

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Linux/Mac:

curl -LsSf https://astral.sh/uv/install.sh | sh

安装后,将 UV 添加到 PATH(Linux/Mac 通常会自动添加,或手动添加到 ~/.bashrc 或 ~/.zshrc):

export PATH="$HOME/.cargo/bin:$PATH"

其他安装方式:

# 使用 pip 安装
pip install uv
# 或
pip3 install uv

# 使用 pipx 安装
pipx install uv

2. 安装项目依赖

cd FaultRecord
uv sync

3. 准备 Excel 文件

将 Excel 文件(.xlsx 格式)放在项目根目录下。每个 Excel 文件的每个 Sheet 代表一条线路。

Excel 文件应包含以下列:

  • 序号
  • 问题分类(平台新需求、平台问题(实施)、平台问题(开发)、平台缺失(开发)、平台缺失(实施))
  • 测试时间
  • 系统
  • 设备名称
  • 问题描述
  • 整改责任人
  • 问题分析
  • 截止处理时间
  • 整改结果
  • 第一次整改时间
  • 第二次整改时间
  • 第三次整改时间
  • 复测结果
  • 第一次复测时间
  • 第一次复测说明
  • 第二次复测时间
  • 第二次复测说明
  • 第三次复测时间
  • 第三次复测说明
  • 备注

4. 运行项目

Windows 开发模式(前台运行)

uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8010

或者直接运行:

uv run python app/main.py

Linux 后台启动

项目提供了多种 Linux 后台启动方式:

方式一:使用启动脚本(推荐,简单快捷)
# 项目目录
cd FaultRecord

# 赋予执行权限
chmod +x start.sh stop.sh restart.sh

# 启动应用
./start.sh

# 停止应用
./stop.sh

# 重启应用
./restart.sh

启动后,应用会在后台运行,日志保存在 logs/app.log,PID 保存在 faultrecord.pid。

方式二:使用 systemd(推荐生产环境)

systemd 是 Linux 系统的服务管理器,适合生产环境使用,支持开机自启、自动重启等功能。

  1. 编辑服务文件:

    nano faultrecord.service
    

    修改以下配置:

    • WorkingDirectory: 设置为项目实际路径(如 /home/user/FaultRecord)
    • User 和 Group: 设置为运行应用的用户和组(如 www-data 或你的用户名)
    • ExecStart: 设置为 start-service.sh 的完整路径
    • Environment: 如果需要,添加用户本地 bin 目录到 PATH(如 /home/USER/.local/bin)

    示例配置:

    WorkingDirectory=/home/user/FaultRecord
    User=user
    Group=user
    Environment="PATH=/usr/local/bin:/usr/bin:/bin:/home/user/.local/bin"
    ExecStart=/home/user/FaultRecord/start-service.sh
    
  2. 赋予启动脚本执行权限:

    chmod +x start-service.sh
    
  3. 安装服务:

    sudo cp faultrecord.service /etc/systemd/system/
    sudo systemctl daemon-reload
    
  4. 启动服务:

    sudo systemctl start faultrecord
    sudo systemctl enable faultrecord  # 设置开机自启
    
  5. 管理服务:

    # 查看状态
    sudo systemctl status faultrecord
    
    # 停止服务
    sudo systemctl stop faultrecord
    
    # 重启服务
    sudo systemctl restart faultrecord
    
    # 查看日志
    sudo journalctl -u faultrecord -f
    
    # 查看最近 100 行日志
    sudo journalctl -u faultrecord -n 100
    
方式三:使用 nohup(临时使用)

适合临时测试或快速启动:

# 创建日志目录
mkdir -p logs

# 后台启动
nohup uv run uvicorn app.main:app --host 0.0.0.0 --port 8010 > logs/app.log 2>&1 &

# 查看进程
ps aux | grep uvicorn

# 查看日志
tail -f logs/app.log

# 停止(需要先找到 PID)
kill <PID>
方式四:使用 screen 或 tmux(开发/调试)

适合需要交互式调试的场景:

使用 screen:

# 创建新的 screen 会话
screen -S faultrecord

# 启动应用
uv run uvicorn app.main:app --host 0.0.0.0 --port 8010

# 退出 screen(应用继续运行):按 Ctrl+A,然后按 D

# 重新连接
screen -r faultrecord

# 列出所有 screen 会话
screen -ls

# 终止 screen 会话
screen -X -S faultrecord quit

使用 tmux:

# 创建新的 tmux 会话
tmux new -s faultrecord

# 启动应用
uv run uvicorn app.main:app --host 0.0.0.0 --port 8010

# 退出 tmux(应用继续运行):按 Ctrl+B,然后按 D

# 重新连接
tmux attach -t faultrecord

# 列出所有 tmux 会话
tmux ls

# 终止 tmux 会话
tmux kill-session -t faultrecord

5. 防火墙配置

如果需要在其他机器访问,需要开放端口:

# Ubuntu/Debian (ufw)
sudo ufw allow 8010/tcp

# CentOS/RHEL (firewalld)
sudo firewall-cmd --permanent --add-port=8010/tcp
sudo firewall-cmd --reload

# 或者使用 iptables
sudo iptables -A INPUT -p tcp --dport 8010 -j ACCEPT

6. 访问系统

启动成功后,在浏览器访问:

默认管理员账号:

  • 用户名:admin
  • 密码:123

故障排查

检查应用是否运行

# 使用启动脚本时
ps aux | grep uvicorn
cat faultrecord.pid

# 使用 systemd 时
sudo systemctl status faultrecord

查看日志

# 启动脚本日志
tail -f logs/app.log

# systemd 日志
sudo journalctl -u faultrecord -f

检查端口占用

netstat -tlnp | grep 8010
# 或
lsof -i :8010

检查 UV 是否正确安装

which uv
uv --version

检查依赖是否正确安装

uv sync

CSS样式未生效问题

如果在Linux(如树莓派)上部署后,发现样式没有更新,通常是浏览器缓存问题。

解决方案

方法一:强制刷新浏览器(推荐)

  • Chrome/Edge浏览器:

    • Windows/Linux: 按 Ctrl + Shift + R 或 Ctrl + F5
    • Mac: 按 Cmd + Shift + R
  • Firefox浏览器:

    • Windows/Linux: 按 Ctrl + Shift + R 或 Ctrl + F5
    • Mac: 按 Cmd + Shift + R
  • Safari浏览器:

    • Mac: 按 Cmd + Option + R

方法二:清除浏览器缓存

  • Chrome/Edge:按 F12 打开开发者工具,右键点击刷新按钮,选择"清空缓存并硬性重新加载"
  • Firefox:按 Ctrl + Shift + Delete,选择"缓存",点击"立即清除"
  • Safari:菜单栏 → 开发 → 清空缓存

方法三:重启服务

如果修改了CSS文件,需要重启服务:

# 使用启动脚本
./restart.sh

# 或使用systemd
sudo systemctl restart faultrecord

方法四:验证CSS是否加载

  1. 打开浏览器开发者工具(F12)
  2. 切换到"网络"(Network)标签
  3. 刷新页面
  4. 查找 style.css 文件
  5. 检查状态码应该是 200,响应头中应该有正确的 Content-Type: text/css

系统已自动添加CSS版本控制功能,每次CSS文件更新后,版本号会自动更新,浏览器会加载最新的CSS文件。

打包(Windows)

项目支持使用PyInstaller打包成Windows可执行文件(带命令行窗口)。

打包步骤

  1. 安装开发依赖(包含PyInstaller):
uv sync --extra dev
  1. 执行打包:

Windows(推荐):

build.bat

或使用Python脚本:

uv run python build.py

或直接使用PyInstaller:

uv run pyinstaller build.spec --clean --noconfirm

打包完成后,可执行文件位于 dist/FaultRecord.exe

打包后的使用

  1. 将 FaultRecord.exe 复制到目标目录
  2. 将Excel文件放在与 FaultRecord.exe 相同的目录下
  3. 双击 FaultRecord.exe 运行程序
  4. 程序会显示命令行窗口,显示运行日志
  5. 浏览器访问:http://localhost:8010

打包配置

  • 打包配置文件:build.spec
  • 打包脚本:build.py 或 build.bat
  • 命令行窗口:已启用(console=True)

打包后的程序会自动处理路径:

  • 资源文件(模板、静态文件):从临时目录加载
  • Excel文件:从可执行文件所在目录加载
  • 用户数据(users.json):保存在可执行文件所在目录

项目结构

FaultRecord/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI应用入口
│   ├── config.py            # 配置文件
│   ├── models.py            # 数据模型
│   ├── auth.py              # 用户认证
│   ├── routers/             # 路由模块
│   │   ├── auth.py          # 认证路由
│   │   ├── issues.py        # 问题管理路由
│   │   └── stats.py         # 统计路由
│   ├── templates/           # Jinja2模板
│   │   ├── base.html
│   │   ├── index.html
│   │   ├── stats.html
│   │   ├── login.html
│   │   └── register.html
│   ├── static/              # 静态资源
│   │   ├── css/
│   │   └── js/
│   └── utils/              # 工具模块
│       ├── excel_loader.py # Excel加载器
│       └── validators.py   # 数据验证
├── *.xlsx                   # Excel数据文件
├── pyproject.toml           # 项目配置
└── uv.lock                  # 依赖锁定文件

使用说明

1. 登录/注册

  • 首次使用需要注册账号(只能注册普通用户)
  • 管理员账号:admin/123(可修改和复测问题)

2. 选择线路

  • 进入首页后,先选择Excel文件和Sheet(线路)
  • 如果只有一个Excel文件,会自动加载第一个Sheet

3. 问题管理

  • 问题录入:点击"问题录入"按钮,填写问题信息
  • 查看详情:点击"查看详情"按钮或双击表格行查看完整问题信息
  • 修改问题:管理员可点击"修改"按钮修改问题(需管理员权限)
  • 复测功能:管理员可点击"复测"按钮录入复测数据(需管理员权限)

4. 查询功能

  • 支持按问题分类、系统、测试时间、整改责任人等条件查询

5. 数据统计

  • 进入"数据统计"页面查看统计数据
  • 统计包括:新增问题数量、复测问题数量、复测闭环数量、处理数量等

代码检测

项目使用 ruff 进行代码检测和格式化:

# 运行代码检测
uv run ruff check app/

# 自动修复可修复的问题
uv run ruff check app/ --fix

# 运行格式化
uv run ruff format app/

# 或使用便捷脚本(Windows)
check.bat

生产环境建议

  1. 使用 systemd:提供更好的进程管理和监控
  2. 配置反向代理:使用 Nginx 作为反向代理,提供 HTTPS 支持
  3. 修改 SECRET_KEY:在 app/config.py 中修改 SECRET_KEY 为随机字符串
  4. 配置日志轮转:使用 logrotate 管理日志文件
  5. 设置资源限制:在 systemd service 文件中配置 LimitNOFILE 等参数
  6. 定期备份:备份 Excel 文件和 users.json 文件

Nginx 反向代理配置示例

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

    location / {
        proxy_pass http://127.0.0.1:8010;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

注意事项

  1. Excel文件修改后会自动保存,请确保文件有写入权限
  2. 建议定期备份Excel文件
  3. 生产环境请修改SECRET_KEY(在app/config.py中)
  4. 用户数据存储在项目根目录的users.json文件中

开发

代码风格

  • 遵循 PEP 8 代码风格指南
  • 使用类型提示
  • 使用 Pydantic 进行数据验证

测试

# 运行开发服务器(自动重载)
uv run uvicorn app.main:app --reload

许可证

MIT License

Introduction

可用于地铁线路问题工单的管理与数据统计。支持多线路管理、问题录入、查询、修改、复测,具备用户注册登录、权限控制、数据可视化及响应式设计,适配PC和移动端。【此简介由AI生成】

Customize your domain