团队记账工具项目完整说明文档

以下是基于 Flask 的团队记账 Web 应用完整项目说明，包含：目录结构、主要功能模块、核心代码逻辑、模板文件说明以及部署与使用说明等内容。

🗂 项目结构总览

team_accounting/               # 项目根目录
├── app.py                     # Flask 应用入口
├── config.py                  # 配置文件（如 SECRET_KEY、数据库URI）
├── models.py                  # 数据模型定义（User, Tag, Expense）
├── requirements.txt           # 项目依赖列表
├── auth/                      # 身份认证功能模块
│   ├── __init__.py            # 定义 auth Blueprint
│   └── routes.py              # 注册、登录、登出路由
├── main/                      # 普通用户功能模块
│   ├── __init__.py            # 定义 main Blueprint
│   └── routes.py              # 提交申请、查看自身申请路由
├── admin/                     # 管理员功能模块
│   ├── __init__.py            # 定义 admin Blueprint
│   └── routes.py              # 审核、分类管理、统计导出路由
├── templates/                 # 前端模板
│   ├── base.html              # 基础页面框架模板
│   ├── auth/                  # auth 模块相关模板
│   ├── main/                  # main 模块相关模板
│   └── admin/                 # admin 模块相关模板
└── static/                    # 静态文件目录（保存图表等）

🔧 功能模块简介

  • 用户注册登录：支持用户名密码注册，首个注册用户自动设为管理员
  • 用户权限区分：基于 Flask-Login 权限控制，分为普通用户和管理员
  • 提交报销申请：普通用户填写金额、分类、用途、时间等字段后提交
  • 管理员审核：可批准/拒绝待审核申请，审批后写入正式账本
  • 预算分类系统：管理员可添加、修改各分类的预算金额
  • 预算控制机制：审批前校验是否超出预算，避免超额报销
  • 图表统计：按分类可视化支出情况（柱状图），展示总预算/支出/剩余
  • 数据导出：管理员可导出审批后的账单为 CSV 或 Excel 文件

🧱 核心代码文件说明

app.py

应用初始化入口，包含数据库初始化、蓝图注册与登录状态设置。

config.py

使用 SECRET_KEY 和 SQLALCHEMY_DATABASE_URI 控制配置项，支持从环境变量读取。

models.py

定义了三张核心表：

  • User：用户模型，支持是否为管理员
  • Tag：预算分类，含预算值与相关申请
  • Expense：报销记录，关联用户与分类

🌐 路由模块与模板结构

模块 说明
auth/ 登录、注册、登出，模板在 templates/auth/
main/ 普通用户提交与查看申请，模板在 templates/main/
admin/ 管理员审核、预算管理与数据导出，模板在 templates/admin/

💡 前端设计

  • 使用 Bootstrap 5 快速搭建响应式页面
  • 表单提交通过原生 HTML + Flask 表单处理完成
  • Flash 消息用于反馈提示（成功、错误、信息等）

🐍 项目运行说明

1️⃣ 安装依赖

pip install -r requirements.txt

2️⃣ 启动项目

python app.py

首次运行将自动创建数据库文件 team_accounting.db。

3️⃣ 访问应用

浏览器打开：http://127.0.0.1:5000

第一位注册用户将拥有管理员权限，可直接访问管理员页面。

📊 图表生成与导出

  • admin/stats 页面会使用 Pandas 和 Matplotlib 生成支出对比柱状图
  • 图表保存为 static/stats.png
  • 支持导出 CSV 或 Excel 格式的审批账单数据

✅ 管理流程说明

  • 成员提交申请后默认状态为 pending
  • 管理员登录后点击 Approve/Reject 审核
  • 若预算不足，将禁止审批并提示
  • 成员可查看自己的历史申请记录

🛡 安全与用户体验设计

  • 使用加密存储用户密码（werkzeug.security）
  • 所有操作要求登录认证
  • 管理员功能限定访问权限
  • 所有页面支持 Flash 消息提示

📦 未来可拓展方向

  • 支持多团队账本（多租户支持）
  • 支持图片/票据上传（与申请绑定）
  • 审批历史记录记录管理员操作日志
  • 审批意见字段支持文字备注
  • 添加 API 支持移动端接入
  • 增加异步统计和图表缓存机制

⚙️ 开发环境准备

推荐系统环境：Ubuntu 20.04/22.04、Python 3.8+

1️⃣ 安装 Python 与虚拟环境工具

sudo apt update
sudo apt install python3 python3-venv python3-pip -y

2️⃣ 创建项目目录与虚拟环境

cd ~
git clone https://github.com/yourname/team_accounting.git
cd team_accounting
python3 -m venv venv
source venv/bin/activate

3️⃣ 安装依赖

pip install -r requirements.txt

🚀 本地开发运行

python app.py

默认监听：http://127.0.0.1:5000

数据库文件将自动创建为 team_accounting.db。

☁️ 生产部署（Gunicorn + systemd）

适用于生产服务器，如阿里云、腾讯云、VPS 等。

1️⃣ 安装 Gunicorn

source venv/bin/activate
pip install gunicorn

2️⃣ 创建 Gunicorn 启动服务（Systemd）

sudo nano /etc/systemd/system/team_accounting.service

写入以下内容：

[Unit]
Description=Team Accounting Web App
After=network.target

[Service]
User=www-data
WorkingDirectory=/home/youruser/team_accounting
Environment="PATH=/home/youruser/team_accounting/venv/bin"
ExecStart=/home/youruser/team_accounting/venv/bin/gunicorn -w 4 -b 0.0.0.0:8000 app:app
Restart=always

[Install]
WantedBy=multi-user.target

保存并启动服务：

sudo systemctl daemon-reload
sudo systemctl enable team_accounting
sudo systemctl start team_accounting

查看状态：

sudo systemctl status team_accounting

🌐 配置 Nginx 作为反向代理（可选）

sudo apt install nginx -y
sudo nano /etc/nginx/sites-available/team_accounting

内容如下：

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        include proxy_params;
    }
}

启用配置并重启 Nginx：

sudo ln -s /etc/nginx/sites-available/team_accounting /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

📦 自动化部署脚本（deploy.sh）

在项目根目录创建 deploy.sh：

nano deploy.sh

内容如下：

#!/bin/bash
set -e

echo ">>> 激活虚拟环境"
source venv/bin/activate

echo ">>> 拉取最新代码"
git pull origin main

echo ">>> 安装/更新依赖"
pip install -r requirements.txt

echo ">>> 重启服务"
sudo systemctl restart team_accounting

echo ">>> 部署完成 ✔️"

给予执行权限：

chmod +x deploy.sh

使用方法：

./deploy.sh

⏱ 自动定时任务（crontab）

每日凌晨 3 点自动重启服务：

crontab -e

添加行：

0 3 * * * systemctl restart team_accounting

🔐 安全建议

  • 修改默认 SECRET_KEY
  • 配置 HTTPS（使用 Certbot）
  • 备份数据库文件 team_accounting.db（可写入备份脚本）

📈 数据备份脚本（backup.sh）

#!/bin/bash
backup_dir="/home/youruser/team_accounting/backups"
mkdir -p $backup_dir
cp /home/youruser/team_accounting/team_accounting.db $backup_dir/db_$(date +%F).sqlite

设定定时任务：

crontab -e
# 每天凌晨 2 点备份一次
0 2 * * * /home/youruser/team_accounting/backup.sh

📝 总结

本项目已支持：

  • 用户权限管理（注册/登录）
  • 报销流程：提交、审核、分类预算控制
  • 数据可视化与导出
  • 本地开发/服务器部署/Gunicorn/Nginx/systemd
  • 自动更新脚本与备份计划

下一步可拓展方向：

  • 上传附件/票据
  • 多语言支持
  • 微信小程序前端

开源地址（示例）：https://github.com/Benjaminisgood/Benony.git

目录