skycurtain/ndm-web-platform

Fork 0

Files

T

yangsy 1e2ad96e56 docs(AGENTS.md): 新增AGENTS.md项目说明文档

2026-05-25 10:14:54 +08:00

9.7 KiB

Raw Blame History

网络设备管理平台

项目概述

这是网络设备管理平台的前端项目，用于在地铁线路运管中心检测和查看各车站网络设备的详细数据、运行情况、异常告警，并提供分析、统计、日志和权限管理能力。

主要设备类型：

摄像机
网络录像机
交换机
解码器
智能安防箱
媒体服务器
视频服务器
网络键盘
报警主机

技术栈

包管理：pnpm
构建工具：Vite
前端框架：Vue 3
语言：TypeScript
路由：Vue Router
组件库：Naive UI
状态管理：Pinia + pinia-plugin-persistedstate
服务端状态/轮询：TanStack Vue Query
本地持久化：localStorage、sessionStorage、IndexedDB/localforage
网络请求：axios
实时消息：STOMP/WebSocket（@stomp/stompjs）
图表：ECharts
图标：lucide-vue-next
样式：Sass

环境与脚本

运行环境

Node.js：^20.19.0 || >=22.12.0
pnpm：以 package.json 中 packageManager 为准

常用命令

pnpm install      # 安装依赖
pnpm dev          # 启动开发服务，默认端口 9763
pnpm build        # 类型检查 + Vite 构建 + 构建产物压缩
pnpm preview      # 预览构建产物
pnpm build-only   # 仅执行 Vite 构建
pnpm type-check   # 执行 vue-tsc 类型检查
pnpm lint         # 执行 ESLint，并带 --fix
pnpm format       # 使用 Prettier 格式化 src/

当前项目未配置测试脚本，也未发现测试文件；不要声称已运行单元测试。需要验证改动时，优先运行 pnpm type-check、pnpm lint、pnpm build 中与改动相关的命令。

构建流程

pnpm build 的实际流程为：

tsx build/pre-build.ts：根据 package.json 的版本和构建时间写入 public/manifest.json。
vue-tsc --build：类型检查。
vite build：生成 dist/。
tsx build/post-build.ts：基于 dist/ 生成 .zip、.tar、.tar.gz 压缩包。

压缩包命名格式为：ndm-web-platform_v<version>_<YYMMDD-HHmmss>。

目录结构

项目源码集中在 src/：

src/
  apis/                    # 接口客户端、接口模型、业务请求封装
  components/              # 业务组件与全局组件
    device/
    global/
    permission/
    station/
  composables/             # 组合式函数
    alarm/
    common/
    device/
    permission/
    query/                 # TanStack Query 轮询与请求编排
    station/
    stomp/                 # STOMP/WebSocket 客户端
  constants/               # 常量
  enums/                   # 枚举
  helpers/                 # 辅助逻辑
  layouts/
    app-layout.vue         # 登录后主布局
  pages/                   # 页面
  plugins/                 # Pinia 持久化等插件
  router/
    index.ts               # 路由配置与守卫
  stores/                  # Pinia stores
  styles/                  # 全局样式
  types/                   # 全局/工具类型
  utils/                   # 通用工具函数

路径别名：@/* 指向 src/*。

页面与路由

路由配置在 src/router/index.ts。登录页独立于主布局；除 /login 外，其余页面都作为 src/layouts/app-layout.vue 的子路由。

src/
  router/
    index.ts
  layouts/
    app-layout.vue
  pages/
    login/
      login-page.vue                 # 登录页，对应 /login
    station/
      station-page.vue               # 车站状态页/首页，对应 /station
    device/
      device-page.vue                # 设备诊断页，对应 /device
    alarm/
      alarm-log-page.vue             # 设备告警记录，对应 /alarm/alarm-log
      alarm-ignore-page.vue          # 告警忽略管理，对应 /alarm/alarm-ignore
    log/
      vimp-log-page.vue              # 视频平台日志，对应 /log/vimp-log
      call-log-page.vue              # 上级调用日志，对应 /log/call-log
    permission/
      permission-page.vue            # 权限管理，对应 /permission
    system/
      changelog/
        changelog-page.vue           # 更新记录，对应 /changelog
      error/
        not-found-page.vue           # 404 页面，对应 catch-all

路由守卫规则：

未登录访问非 /login 页面会跳转到 /login。
已登录访问 /login 会跳转到 /。
/ 默认重定向到 /station。
/permission 需要 useUserStore().isLamp 为真，否则跳转到 404。

数据轮询与状态管理

由于后端服务按车站分布，前端需要向各车站服务依次请求数据。项目采用“单点驱动 + 变更监听 + 级联触发”的轮询模式。

核心文件位于 src/composables/query/：

use-line-stations-query.ts：查询所有车站，是业务轮询入口。
use-user-permission-query.ts：查询并计算当前用户在各车站的权限，负责调度后续设备/告警查询。
use-line-devices-query.ts：查询设备数据。
use-line-alarms-query.ts：查询告警数据。
use-verify-user-query.ts：用户登录/校验相关请求。
use-version-check-query.ts：版本检查，依赖构建阶段生成的 /manifest.json。

关键 Pinia stores 位于 src/stores/：

user.ts：用户登录态、Token、用户类型等。
station.ts：车站数据。
device.ts：设备数据。
alarm.ts：告警数据。
permission.ts：权限数据。
setting.ts：系统设置、调试开关、网络开关等。
polling.ts：轮询状态控制。
unread.ts：未读状态。

持久化注意事项：

大体量业务数据会使用 IndexedDB/localforage。
普通设置类状态会使用 localStorage/sessionStorage。
src/main.ts 会比较 VITE_STORAGE_VERSION 与本地 ndm-storage-version，不一致时清空 localStorage 并清空 localforage。

接口与代理

接口相关代码位于 src/apis/：

client/：HTTP 客户端基础封装。
domain/：领域相关类型/逻辑。
model/：接口模型。
request/：按业务拆分的请求函数。

开发代理配置在 vite.config.ts：

开发服务端口：9763。
已配置多个线路/站点前缀代理，包括 01、02、04、10、21 相关站点。
当前配置包含 /api、/minio、/ws 等代理项。
ProxyItem.rewrite 用于将本地请求前缀改写为后端真实路径，例如将 /1001/api 改写为 /api。

修改代理时，应同步检查 key、target、rewrite、ws 是否匹配实际环境。

环境变量

项目使用 Vite 环境变量，当前变量集中在 .env。文档或回答中只列变量名和用途，不要复述真实密钥、密码或授权值。

常见变量：

VITE_APP_TITLE：页面标题。
VITE_REQUEST_INTERVAL：轮询间隔，单位秒。
VITE_NDM_APP_KEY：网管 appKey。
VITE_LAMP_CLIENT_ID：LAMP clientId。
VITE_LAMP_CLIENT_SECRET：LAMP clientSecret。
VITE_LAMP_USERNAME：LAMP 登录用户名。
VITE_LAMP_PASSWORD：LAMP 登录密码。
VITE_LAMP_AUTHORIZATION：已有 Authorization 时直接使用，否则由 clientId/clientSecret 生成。
VITE_STORAGE_VERSION：本地缓存版本，用于触发缓存清理。
VITE_DEBUG_CODE：调试模式授权码。

调试模式与离线开发

调试模式默认隐藏，用于开发、联调和故障排查。

开启方式：

使用快捷键 Ctrl + Alt + D 唤起验证弹窗。
输入 VITE_DEBUG_CODE 对应授权码。
验证通过后，“系统设置”中会显示调试分组。

调试相关能力：

显示设备原始数据。
控制是否轮询车站。
控制是否主动请求。
控制是否订阅 STOMP/WebSocket 消息。
启用模拟用户。
允许在特定场景下直接操作本地 IndexedDB。

离线开发：

如果浏览器已有现场缓存，可在调试模式中关闭轮询、主动请求和消息订阅，直接查看本地缓存。
全新环境可在登录页控制台设置 window.$mockUser.value = true 进入模拟登录，再通过调试面板导入 docs/data/ 下的数据：
- ndm-station-store.json
- ndm-device-store.json
- ndm-alarm-store.json

代码风格与约定

遵循现有 Vue SFC、TypeScript、组合式函数和 Pinia 写法。
新增业务请求时优先放入 src/apis/request/ 对应业务分类。
新增页面时同步更新 src/router/index.ts，并保持 src/pages/ 目录与路由语义一致。
新增共享逻辑优先放入 src/composables/、src/helpers/ 或 src/utils/，不要在页面中堆积重复逻辑。
新增全局/业务组件时优先放入 src/components/ 对应分类。
使用 @/ 引用 src/ 下模块。
不要在代码、文档或回复中泄露真实密码、Token、Authorization 或现场地址以外的敏感信息。

格式化配置来自 .prettierrc.json：

LF 换行
2 空格缩进
单引号
使用分号
trailingComma: all
printWidth: 200

ESLint 重点规则：

@typescript-eslint/no-unused-vars 为 warn。
@typescript-eslint/no-explicit-any 当前关闭，但新增代码仍应尽量保持类型清晰。
vue/multi-word-component-names 当前关闭。

协作规则

默认不要直接修改项目代码；当用户明确授权修改时，只修改授权范围内的文件。
修改前先阅读相关文件和既有实现，避免凭空猜测目录、接口或状态结构。
修改后说明改了哪些文件、为什么改、如何验证。
文档类修改至少重新读取目标文件确认内容正确。
代码类修改应按影响范围运行 pnpm type-check、pnpm lint、pnpm build 或更小范围的可用验证命令。
不要提交 Git commit，除非用户明确要求。
不要删除失败测试或通过压制类型错误来规避问题。
不要在最终说明中声称执行了未实际执行的命令。

9.7 KiB Raw Blame History Unescape Escape