如何开发车辆管理系统中的加油管理板块（附架构图+流程图+代码参考）

+-------------------------+      +------------------+
|   前端（Web / 手机）    | <--> |   API 网关 / Nginx |
+-------------------------+      +------------------+
           |                                |
           v                                v
+----------------------+         +----------------------+
|   后端服务 (Node.js)  | <-----> |  消息队列 (RabbitMQ) |
|  - Auth / 权限        |         +----------------------+
|  - FuelService        |
|  - CardService        |
+----------------------+
           |
           v
+----------------------+    +-------------------+
| 关系型数据库 (MySQL)   |    | Cache / Redis     |
| - oil_cards           |    +-------------------+
| - fuel_records        |
| - card_recharges      |
+----------------------+
           |
           v
+----------------------+
| 外部集成（可选）     |
| - OCR 服务           |
| - 油站 API / 充值接口 |
| - 财务系统导出/对接   |
+----------------------+

CREATE TABLE oil_cards (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  card_number VARCHAR(64) NOT NULL UNIQUE,
  provider VARCHAR(100),
  holder VARCHAR(100),
  balance DECIMAL(12,2) DEFAULT 0,
  status ENUM('active','frozen','lost','closed') DEFAULT 'active',
  created_by BIGINT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

CREATE TABLE fuel_records (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  vehicle_id BIGINT NOT NULL,
  driver_id BIGINT,
  card_id BIGINT,          -- 使用的油卡，若现金则为 NULL
  station VARCHAR(200),
  fill_datetime DATETIME,
  liters DECIMAL(10,2),
  amount DECIMAL(12,2),
  odometer BIGINT,
  invoice_no VARCHAR(100),
  invoice_image VARCHAR(255),
  status ENUM('pending','approved','rejected') DEFAULT 'pending',
  created_by BIGINT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY uniq_invoice (invoice_no, card_id)
);

CREATE TABLE card_recharges (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  card_id BIGINT NOT NULL,
  amount DECIMAL(12,2) NOT NULL,
  recharge_datetime DATETIME,
  operator_id BIGINT,
  voucher_image VARCHAR(255),
  source ENUM('bank','cash','third_party'),
  status ENUM('pending','completed','failed') DEFAULT 'pending',
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE audit_logs (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  entity VARCHAR(50),
  entity_id BIGINT,
  action VARCHAR(50),
  before_data JSON,
  after_data JSON,
  operator_id BIGINT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

flowchart TD
  A[维护油卡信息] --> B[油卡充值登记]
  B --> C{充值是否成功?}
  C -- 是 --> D[余额更新 & 写审计]
  C -- 否 --> E[记录失败原因]
  D --> F[司机去加油]
  F --> G[车辆加油登记(上传发票)]
  G --> H[系统校验(发票重复/里程异常/余额)]
  H -- 通过 --> I[审批流程] --> J[扣减余额/入账]
  H -- 异常 --> K[人工复核/拒绝]
  J --> L[对账任务（异步）] --> M[生成报表/告警]

// fuel.controller.ts (Express + Sequelize 简化示例)
import express from 'express';
import { sequelize } from './models'; // Sequelize 实例
const router = express.Router();
router.post('/fuel', async (req, res) => {
  const t = await sequelize.transaction();
  try {
    const { vehicleId, driverId, cardId, station, liters, amount, odometer, invoiceNo, invoiceImage } = req.body;
    if (!vehicleId || !amount || !odometer) {
      return res.status(400).json({ message: '必填字段缺失' });
    }
    // 防重复：invoice_no + card_id
    const exists = await sequelize.models.fuel_records.findOne({
      where: { invoice_no: invoiceNo, card_id: cardId }
    });
    if (exists) {
      return res.status(409).json({ message: '发票已存在，可能重复提交' });
    }
    // 保存登记（初始 pending）
    const fuel = await sequelize.models.fuel_records.create({
      vehicle_id: vehicleId,
      driver_id: driverId,
      card_id: cardId || null,
      station, liters, amount, odometer,
      invoice_no: invoiceNo, invoice_image: invoiceImage,
      status: 'pending', created_by: req.user.id
    }, { transaction: t });
    // 里程异常检测（若低于历史读数则写审计，但不阻断）
    const vehicle = await sequelize.models.vehicles.findByPk(vehicleId);
    if (vehicle && odometer < vehicle.current_odometer) {
      await sequelize.models.audit_logs.create({
        entity: 'vehicle',
        entity_id: vehicleId,
        action: 'odometer_decrease',
        before_data: JSON.stringify({ last: vehicle.current_odometer }),
        after_data: JSON.stringify({ odometer }),
        operator_id: req.user.id
      }, { transaction: t });
    }
    await t.commit();
    res.json({ id: fuel.id, message: '登记成功，待审批' });
  } catch (err) {
    await t.rollback();
    console.error(err);
    res.status(500).json({ message: '服务器错误' });
  }
});
export default router;

router.post('/cards/:id/recharge', async (req, res) => {
  const cardId = req.params.id;
  const { amount, rechargeDatetime, source, externalOrderId } = req.body;
  const t = await sequelize.transaction();
  try {
    // 幂等：外部订单号唯一约束（若有）
    if (externalOrderId) {
      const prev = await sequelize.models.card_recharges.findOne({ where: { external_order_id: externalOrderId }});
      if (prev) return res.json({ id: prev.id, message: '已处理' });
    }
    const card = await sequelize.models.oil_cards.findByPk(cardId, { transaction: t, lock: t.LOCK.UPDATE });
    if (!card) {
      await t.rollback();
      return res.status(404).json({ message: '油卡不存在' });
    }
    // 创建充值记录
    const rec = await sequelize.models.card_recharges.create({
      card_id: cardId, amount, recharge_datetime: rechargeDatetime || new Date(),
      operator_id: req.user.id, source, status: 'completed', external_order_id: externalOrderId || null
    }, { transaction: t });
    // 更新余额（同一事务内）
    const newBalance = parseFloat(card.balance) + parseFloat(amount);
    await card.update({ balance: newBalance }, { transaction: t });
    // 写审计
    await sequelize.models.audit_logs.create({
      entity: 'oil_card',
      entity_id: cardId,
      action: 'recharge',
      before_data: JSON.stringify({ balance: card.balance }),
      after_data: JSON.stringify({ balance: newBalance }),
      operator_id: req.user.id
    }, { transaction: t });
    await t.commit();
    res.json({ id: rec.id, newBalance });
  } catch (err) {
    await t.rollback();
    console.error(err);
    res.status(500).json({ message: '充值失败' });
  }
});