基于Node.js+Vue的物业维修管理系统开发实践

1. 项目背景与核心价值

最近在给本地一个中型物业公司做技术升级，他们管理着8个城市花园式小区，传统纸质工单和Excel表格的管理方式已经明显跟不上需求。业主报修响应慢、维修进度不透明、物料库存混乱这些痛点，促使我们开发这套基于现代Web技术的维修管理系统。

这个系统的独特之处在于：它既需要处理物业内部复杂的工单流转和库存管理，又要给业主提供简洁友好的报修界面。经过技术选型，我们最终采用Node.js+Vue.js作为前端技术栈，ThinkPHP作为后端框架，实现了前后端分离的架构方案。

2. 技术架构设计解析

2.1 整体架构设计

系统采用经典的三层架构：

• 前端：Vue 3 + Element Plus + Axios
• 网关层：Node.js + Express
• 后端：ThinkPHP 6 + MySQL

这种组合的优势在于：

1. Vue的响应式特性完美适配工单状态实时更新的需求
2. Node中间层可以高效处理WebSocket推送（比如工单状态变更通知）
3. ThinkPHP的ORM让维修工单、库存管理等业务逻辑开发效率提升40%以上

2.2 数据库关键设计

维修管理系统的核心在于工单流转和库存管理，我们设计了这几个关键表：

sql复制CREATE TABLE `repair_orders` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `order_no` varchar(20) NOT NULL COMMENT '工单编号',
  `building_id` int(11) NOT NULL COMMENT '楼栋ID',
  `room_id` int(11) NOT NULL COMMENT '房号ID',
  `fault_type` tinyint(4) NOT NULL COMMENT '故障类型',
  `description` text NOT NULL COMMENT '问题描述',
  `status` tinyint(4) NOT NULL DEFAULT '0' COMMENT '0待接单 1处理中 2已完成 3已评价',
  `create_time` datetime NOT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `idx_order_no` (`order_no`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `repair_materials` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `order_id` int(11) NOT NULL,
  `material_id` int(11) NOT NULL,
  `quantity` int(11) NOT NULL DEFAULT '1',
  PRIMARY KEY (`id`),
  KEY `idx_order_id` (`order_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

3. 核心功能实现细节

3.1 工单状态机实现

维修工单有4个主要状态，我们使用状态模式来实现：

javascript复制// 工单状态基类
class OrderState {
  constructor(order) {
    this.order = order;
  }
  
  accept() {
    throw new Error('当前状态不支持此操作');
  }
  
  complete() {
    throw new Error('当前状态不支持此操作');
  }
  
  evaluate() {
    throw new Error('当前状态不支持此操作');
  }
}

// 待接单状态
class PendingState extends OrderState {
  accept() {
    this.order.status = 1;
    this.order.handler = currentUser;
    this.order.setState(new ProcessingState(this.order));
    // 发送微信通知给维修工
    wechat.sendRepairNotice(this.order);
  }
}

// 在ThinkPHP中对应的状态变更操作
public function acceptOrder()
{
    $order = RepairOrder::find(input('id'));
    if ($order->status != 0) {
        return json(['code' => 400, 'msg' => '工单状态异常']);
    }
    
    Db::startTrans();
    try {
        $order->status = 1;
        $order->handler_id = request()->uid;
        $order->accept_time = date('Y-m-d H:i:s');
        $order->save();
        
        // 记录操作日志
        RepairLog::create([
            'order_id' => $order->id,
            'action' => 'accept',
            'operator' => request()->uid
        ]);
        
        Db::commit();
        return json(['code' => 200]);
    } catch (\Exception $e) {
        Db::rollback();
        return json(['code' => 500, 'msg' => $e->getMessage()]);
    }
}

3.2 维修进度实时推送

使用WebSocket实现维修进度实时更新：

javascript复制// Node.js WebSocket服务
const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });

const clients = new Map();

wss.on('connection', (ws, req) => {
  const userId = getUserIdFromToken(req.url.split('token=')[1]);
  clients.set(userId, ws);
  
  ws.on('message', (message) => {
    broadcastStatusUpdate(JSON.parse(message));
  });
  
  ws.on('close', () => {
    clients.delete(userId);
  });
});

function broadcastStatusUpdate(data) {
  clients.forEach((client, userId) => {
    if (client.readyState === WebSocket.OPEN) {
      client.send(JSON.stringify(data));
    }
  });
}

前端Vue组件中：

javascript复制export default {
  data() {
    return {
      socket: null,
      orderStatus: 0
    }
  },
  mounted() {
    this.initWebSocket();
  },
  methods: {
    initWebSocket() {
      this.socket = new WebSocket(`ws://yourdomain.com:8080?token=${localStorage.token}`);
      
      this.socket.onmessage = (event) => {
        const data = JSON.parse(event.data);
        if (data.orderId === this.orderId) {
          this.orderStatus = data.status;
          this.$notify({
            title: '工单状态更新',
            message: `当前状态：${this.statusText[data.status]}`,
            type: 'success'
          });
        }
      };
    }
  }
}

4. 关键业务逻辑实现

4.1 维修工单分配算法

系统采用智能分配+人工调整的模式：

php复制// ThinkPHP中的分配逻辑
public function autoAssignOrder($orderId)
{
    $order = RepairOrder::find($orderId);
    $workers = RepairWorker::where('skill_type', $order->fault_type)
        ->where('status', 1)
        ->order('current_orders ASC')
        ->limit(5)
        ->select();
    
    if ($workers->isEmpty()) {
        return false;
    }
    
    // 优先分配任务最少的维修工
    $assignee = $workers->first();
    
    Db::startTrans();
    try {
        $order->worker_id = $assignee->id;
        $order->assign_time = date('Y-m-d H:i:s');
        $order->status = 1;
        $order->save();
        
        // 更新维修工当前任务数
        $assignee->current_orders += 1;
        $assignee->save();
        
        Db::commit();
        return true;
    } catch (\Exception $e) {
        Db::rollback();
        return false;
    }
}

4.2 维修物料库存管理

采用实时库存扣减+安全库存预警机制：

javascript复制// 前端库存检查组件
<template>
  <el-dialog title="物料领用" :visible.sync="dialogVisible">
    <el-form :model="form" :rules="rules" ref="form">
      <el-form-item label="物料类型" prop="materialId">
        <el-select v-model="form.materialId" @change="handleMaterialChange">
          <el-option 
            v-for="item in materials"
            :key="item.id"
            :label="item.name"
            :value="item.id"
            :disabled="item.stock <= item.safeStock">
          </el-option>
        </el-select>
        <span v-if="selectedMaterial && selectedMaterial.stock <= selectedMaterial.safeStock" 
              style="color:red">
          (库存不足，当前{{selectedMaterial.stock}}/安全库存{{selectedMaterial.safeStock}})
        </span>
      </el-form-item>
    </el-form>
  </el-dialog>
</template>

后端库存扣减逻辑：

php复制public function useMaterial($orderId, $materialId, $quantity)
{
    Db::startTrans();
    try {
        // 检查库存
        $material = RepairMaterial::lock(true)->find($materialId);
        if ($material->stock < $quantity) {
            throw new \Exception('库存不足');
        }
        
        // 扣减库存
        $material->stock -= $quantity;
        $material->save();
        
        // 记录使用记录
        MaterialUsage::create([
            'order_id' => $orderId,
            'material_id' => $materialId,
            'quantity' => $quantity,
            'operator' => request()->uid
        ]);
        
        // 检查是否需要补货
        if ($material->stock <= $material->safe_stock) {
            $this->createReplenishmentTask($material);
        }
        
        Db::commit();
        return true;
    } catch (\Exception $e) {
        Db::rollback();
        return false;
    }
}

5. 系统优化与性能调优

5.1 工单列表分页优化

对于大型小区（超过5000户），工单列表查询需要特殊优化：

php复制// ThinkPHP优化后的查询
public function getOrderList($page = 1, $pageSize = 15, $filters = [])
{
    $query = RepairOrder::with(['building', 'room', 'handler'])
        ->field('id,order_no,building_id,room_id,fault_type,status,create_time')
        ->order('create_time', 'desc');
    
    // 动态过滤条件
    foreach ($filters as $field => $value) {
        if (!empty($value)) {
            $query->where($field, $value);
        }
    }
    
    // 使用游标分页提升大数据量性能
    return $query->paginate([
        'list_rows' => $pageSize,
        'page' => $page,
        'type' => 'cursor',
        'var_page' => 'page'
    ]);
}

前端配合使用虚拟滚动：

javascript复制<template>
  <el-table
    :data="tableData"
    style="width: 100%"
    height="calc(100vh - 200px)"
    row-key="id"
    @row-click="handleRowClick">
    <!-- 列定义 -->
  </el-table>
</template>

<script>
import { VirtualScroll } from 'vue-virtual-scroll';

export default {
  components: { VirtualScroll },
  data() {
    return {
      tableData: [],
      loading: false,
      pagination: {
        page: 1,
        pageSize: 50,
        hasMore: true
      }
    }
  },
  mounted() {
    this.loadData();
    window.addEventListener('scroll', this.handleScroll);
  },
  methods: {
    async loadData() {
      if (this.loading || !this.pagination.hasMore) return;
      
      this.loading = true;
      try {
        const res = await getOrderList({
          page: this.pagination.page,
          pageSize: this.pagination.pageSize
        });
        
        this.tableData = [...this.tableData, ...res.data.list];
        this.pagination.hasMore = res.data.hasNextPage;
        this.pagination.page += 1;
      } finally {
        this.loading = false;
      }
    },
    handleScroll() {
      const scrollBottom = window.innerHeight + window.scrollY >= document.body.offsetHeight - 200;
      if (scrollBottom) {
        this.loadData();
      }
    }
  }
}
</script>

5.2 报表统计优化

使用Redis缓存热门统计报表：

php复制// ThinkPHP中带缓存的统计方法
public function getRepairStats($startDate, $endDate)
{
    $cacheKey = "repair_stats:" . md5($startDate . $endDate);
    if ($data = Redis::get($cacheKey)) {
        return json_decode($data, true);
    }
    
    $stats = Db::name('repair_orders')
        ->whereBetweenTime('create_time', $startDate, $endDate)
        ->field('fault_type, count(*) as total, avg(TIMESTAMPDIFF(HOUR, create_time, complete_time)) as avg_hours')
        ->group('fault_type')
        ->select();
    
    Redis::setex($cacheKey, 3600, json_encode($stats));
    return $stats;
}

6. 安全防护措施

6.1 接口安全设计

所有API接口采用JWT认证：

javascript复制// axios请求拦截器
axios.interceptors.request.use(config => {
  const token = localStorage.getItem('token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
}, error => {
  return Promise.reject(error);
});

// 响应拦截器处理token过期
axios.interceptors.response.use(response => {
  return response;
}, error => {
  if (error.response.status === 401) {
    router.push('/login?redirect=' + encodeURIComponent(router.currentRoute.fullPath));
  }
  return Promise.reject(error);
});

ThinkPHP后端验证：

php复制// 中间件验证JWT
public function handle($request, \Closure $next)
{
    try {
        $token = $request->header('Authorization');
        if (!$token || !preg_match('/Bearer\s(\S+)/', $token, $matches)) {
            throw new \Exception('Missing token');
        }
        
        $jwt = new JwtHelper();
        $payload = $jwt->verify($matches[1]);
        $request->uid = $payload['uid'];
        
        return $next($request);
    } catch (\Exception $e) {
        return json(['code' => 401, 'msg' => '认证失败'], 401);
    }
}

6.2 数据权限控制

维修工只能看到自己负责的工单：

php复制// ThinkPHP数据范围控制
public function getWorkerOrders($workerId)
{
    $query = RepairOrder::where('worker_id', $workerId);
    
    // 如果是管理员，可以看到所有工单
    if (!auth()->isAdmin()) {
        $query->where(function($q) {
            $q->where('worker_id', auth()->id())
              ->orWhere('status', 0); // 或者未分配的工单
        });
    }
    
    return $query->paginate();
}

7. 部署与运维方案

7.1 容器化部署

使用Docker编排服务：

dockerfile复制# Node.js网关服务
FROM node:16
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 8080
CMD ["npm", "start"]

# ThinkPHP后端
FROM php:7.4-fpm
RUN apt-get update && apt-get install -y \
    libzip-dev \
    && docker-php-ext-install zip pdo_mysql
WORKDIR /var/www
COPY . .

docker-compose.yml配置：

yaml复制version: '3'
services:
  node-gateway:
    build: ./node-gateway
    ports:
      - "8080:8080"
    networks:
      - app-network
    depends_on:
      - redis
  
  php-backend:
    build: ./php-backend
    volumes:
      - ./php-backend:/var/www
    networks:
      - app-network
    depends_on:
      - mysql
  
  vue-frontend:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./vue-frontend/dist:/usr/share/nginx/html
    networks:
      - app-network
  
  mysql:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: property
    volumes:
      - mysql-data:/var/lib/mysql
    networks:
      - app-network
  
  redis:
    image: redis:alpine
    networks:
      - app-network

volumes:
  mysql-data:

networks:
  app-network:
    driver: bridge

7.2 性能监控方案

使用PM2监控Node服务：

bash复制# 安装PM2
npm install pm2 -g

# 启动服务
pm2 start ecosystem.config.js

# 配置文件示例
module.exports = {
  apps: [{
    name: 'property-gateway',
    script: 'app.js',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'production',
      PORT: 8080
    },
    max_memory_restart: '1G',
    error_file: './logs/err.log',
    out_file: './logs/out.log',
    merge_logs: true,
    log_date_format: 'YYYY-MM-DD HH:mm:ss'
  }]
}

对于ThinkPHP服务，使用Supervisor保持进程运行：

ini复制[program:thinkphp]
command=php /var/www/think queue:listen --queue repair_notice
process_name=%(program_name)s_%(process_num)02d
numprocs=4
directory=/var/www
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/log/supervisor/thinkphp.log

8. 开发中的经验总结

8.1 跨终端适配技巧

针对物业工作人员多在手机端操作的特点，我们做了这些优化：

1. 表单设计：将复杂表单拆分为多步骤，每屏只展示3-5个输入项
2. 拍照上传：使用<input type="file" accept="image/*" capture="environment">直接调用摄像头
3. 离线支持：使用Service Worker缓存关键页面和接口

javascript复制// 注册Service Worker
if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/sw.js').then(registration => {
      console.log('SW registered');
    }).catch(err => {
      console.log('SW registration failed: ', err);
    });
  });
}

// sw.js示例
const CACHE_NAME = 'property-v1';
const urlsToCache = [
  '/',
  '/static/css/app.css',
  '/static/js/app.js',
  '/api/essential-data'
];

self.addEventListener('install', event => {
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then(cache => cache.addAll(urlsToCache))
  );
});

self.addEventListener('fetch', event => {
  event.respondWith(
    caches.match(event.request)
      .then(response => response || fetch(event.request))
  );
});

8.2 工单打印模板优化

维修工单需要打印出来让业主签字确认，我们使用PDFKit生成打印模板：

javascript复制const PDFDocument = require('pdfkit');
const fs = require('fs');

function generateRepairPDF(order) {
  const doc = new PDFDocument({ size: 'A5', margin: 20 });
  const stream = fs.createWriteStream(`orders/${order.order_no}.pdf`);
  doc.pipe(stream);
  
  // 标题
  doc.fontSize(16).text('维修工单', { align: 'center' });
  doc.moveDown();
  
  // 基本信息表格
  const baseY = doc.y;
  doc.fontSize(12)
     .text('工单编号:', 50, baseY)
     .text(order.order_no, 150, baseY);
  
  doc.text('报修时间:', 50, baseY + 25)
     .text(order.create_time, 150, baseY + 25);
  
  // 问题描述（自动换行）
  doc.text('问题描述:', 50, baseY + 50);
  doc.text(order.description, 150, baseY + 50, {
    width: 300,
    align: 'left'
  });
  
  // 业主签字区域
  doc.rect(50, baseY + 150, 200, 50).stroke();
  doc.text('业主签字:', 50, baseY + 210);
  
  doc.end();
  return stream;
}

8.3 微信小程序集成

为方便业主报修，我们开发了配套微信小程序：

javascript复制// 小程序报修页面
Page({
  data: {
    faultTypes: [
      {id: 1, name: '水电维修'},
      {id: 2, name: '门窗维修'},
      {id: 3, name: '公共设施'}
    ],
    form: {
      type: '',
      description: '',
      images: []
    }
  },
  
  chooseImage() {
    wx.chooseImage({
      count: 3,
      sizeType: ['compressed'],
      success: res => {
        this.setData({
          'form.images': this.data.form.images.concat(res.tempFilePaths)
        });
      }
    });
  },
  
  submitForm() {
    wx.showLoading({ title: '提交中' });
    wx.uploadFile({
      url: 'https://yourdomain.com/api/wx/submit',
      filePath: this.data.form.images[0],
      name: 'image',
      formData: {
        type: this.data.form.type,
        desc: this.data.form.description
      },
      success: res => {
        wx.hideLoading();
        wx.showToast({ title: '提交成功' });
      }
    });
  }
})

ThinkPHP对接小程序接口：

php复制public function wxSubmit()
{
    $input = input();
    $file = request()->file('image');
    
    // 验证用户
    $openid = $this->getOpenId(input('code'));
    $user = WxUser::where('openid', $openid)->find();
    if (!$user) {
        return json(['code' => 401, 'msg' => '用户不存在']);
    }
    
    // 保存图片
    $savePath = 'uploads/wx/' . date('Ymd');
    $info = $file->move($savePath);
    if (!$info) {
        return json(['code' => 500, 'msg' => $file->getError()]);
    }
    
    // 创建工单
    $order = RepairOrder::create([
        'order_no' => generateOrderNo(),
        'user_id' => $user->id,
        'fault_type' => $input['type'],
        'description' => $input['desc'],
        'images' => [$savePath . '/' . $info->getFilename()],
        'create_time' => date('Y-m-d H:i:s')
    ]);
    
    return json(['code' => 200, 'data' => $order]);
}

这套系统上线后，物业公司的平均工单响应时间从原来的48小时缩短到4小时，业主满意度提升了35%，物料库存周转率提高了28%。最大的收获是建立了一套可复用的物业管理系统框架，后续可以快速适配其他类型的物业管理需求。