智慧空间设备监控与 AI 工单助手

基于 React 19 + TypeScript + Ant Design 6 的智慧楼宇设备管理与 AI 对话系统

项目简介

本项目是一个智慧楼宇设备监控与 AI 工单管理的前端应用，提供设备状态看板、工单管理、AI 助手对话三大核心功能，帮助运维人员快速掌握设备运行状态、高效处理工单，并通过 AI 助手实现自然语言查询。

技术栈

类别	技术
前端框架	React 19 + TypeScript
UI 组件库	Ant Design 6
状态管理	Zustand 5
路由	React Router 7
构建工具	Vite 8
测试框架	Vitest 4 + React Testing Library
包管理器	pnpm

功能模块

模块 A：设备状态看板

• 楼栋选择与切换（B1-B5）
• 设备列表展示与多条件筛选（状态、类型）
• 设备详情抽屉（含关联告警记录）
• 顶部统计概览（各类型/状态设备数量）

模块 B：工单管理

• 工单列表展示与状态筛选
• 创建工单（表单校验）
• 工单状态流转（待派单 → 已派单 → 处理中 → 已完成）
• 非法状态流转拦截

模块 C：AI 助手对话

• 可折叠侧栏聊天界面
• Tool Calling 自动循环（查询设备、查询告警、创建工单）
• 工具调用中间状态展示
• 错误降级处理

模块 D：Bug 修复

• 修复 useCallback 依赖缺失导致的数据不更新
• 修复 setInterval 未清理导致的内存泄漏
• 修复直接修改 state 导致的 UI 不渲染

快速开始

环境要求

• Node.js >= 18
• pnpm >= 8

安装与运行

# 1. 安装依赖
pnpm install

# 2. 启动开发服务器（默认端口 5173）
pnpm dev

# 3. 浏览器访问 http://localhost:5173

启动 Mock Server（可选）

项目依赖 Mock Server 提供模拟 API 数据。如需完整功能演示：

# 进入 mock server 目录
cd ../interview-dev-package/attachments/mock-server

# 安装依赖并启动
npm install
npm start
# Mock Server 运行在 http://localhost:3012

开发服务器已配置代理，/api 请求会自动转发到 Mock Server。

构建生产版本

pnpm build
# 输出到 dist/ 目录

运行测试

# 运行所有测试
pnpm test

# 监听模式（开发时推荐）
pnpm test:watch

项目结构

smart-building-app/
├── src/
│   ├── api/                    # API 层（client + 各模块 API）
│   ├── stores/                 # Zustand 状态管理
│   ├── components/             # 通用组件（Layout、StatusTag、Bug修复）
│   ├── pages/                  # 页面组件（Dashboard、WorkOrders、Chat）
│   ├── types/                  # TypeScript 类型定义
│   ├── utils/                  # 工具函数
│   ├── App.tsx                 # 应用入口（路由配置）
│   └── main.tsx                # React 挂载点
├── __tests__/                  # 测试文件
├── public/                     # 静态资源
├── vite.config.ts              # Vite 配置（含 API 代理）
├── vitest.config.ts            # Vitest 配置
└── package.json

架构说明

状态管理

采用 Zustand 按业务域拆分为 4 个独立 Store：

• useBuildingStore — 楼栋选择与筛选状态
• useDeviceStore — 设备列表、详情、告警
• useWorkOrderStore — 工单列表与 CRUD
• useChatStore — AI 对话历史与 Tool Calling

API 层

所有请求通过 api/client.ts 统一封装，提供：

• 统一 baseURL 和错误处理
• ApiError 自定义错误类
• 各业务模块独立 API 文件

AI Tool Calling 流程

用户发送消息
  → LLM 返回 tool_calls
    → 前端分发执行（query_devices / query_alerts / create_work_order）
      → 展示中间状态卡片
        → 结果回传 LLM
          → 获取最终回复

开发指南

# 代码检查
pnpm lint

# 预览生产构建
pnpm preview

已知限制

• 当前使用 Mock Server 模拟数据，无真实后端
• Zustand 未启用持久化，页面刷新后状态重置
• AI 对话依赖 LLM API，需配置有效端点

License

MIT