XuJiacheng
5239411ec7
- 新增 openspec-propose 技能，支持快速提案生成变更及相关文档。 - 新增接口汇总文档，整理后端接口及其用途。 - 新增页面功能说明文档，描述各页面的功能及路由。 - 新增项目总览文档，概述项目结构、技术栈及运行方式。 - 新增工具与非标准实现说明文档，记录项目中的特殊实现及约定。 - 创建 legacy-project-documentation 变更，整合现有文档并迁移至正式 OpenSpec 目录。 - 记录项目中的高风险历史实现特征，明确页面启用状态及接口调用关系。
124 lines
5.4 KiB
Markdown
124 lines
5.4 KiB
Markdown
# BLS Web Vue 项目总览
|
||
|
||
## 文档目标
|
||
|
||
本文档用于给后续维护人员快速建立认知，重点覆盖以下内容：
|
||
|
||
- 项目入口与运行方式
|
||
- 路由、菜单和页面结构
|
||
- 后端接口域名与调用分层
|
||
- 当前项目中值得注意的非标准实现
|
||
- 关联文档索引
|
||
|
||
## 技术栈
|
||
|
||
- 前端框架：Vue 3 + Vite
|
||
- UI 组件：Element Plus
|
||
- 路由：Vue Router 4
|
||
- 国际化：vue-i18n
|
||
- 数据请求：axios、fetch、jQuery.ajax 混用
|
||
- 数据处理：dayjs、qs、xlsx
|
||
|
||
## 项目入口
|
||
|
||
- 页面入口：`src/main.js`
|
||
- 根组件：`src/App.vue`
|
||
- 路由定义：`src/router/index.js`
|
||
- 请求封装：`src/axios.js`
|
||
- 运行配置：`public/config.js`
|
||
|
||
## 运行说明
|
||
|
||
`package.json` 中当前可见脚本：
|
||
|
||
- `npm run dev`：启动本地开发环境
|
||
- `npm run build`：构建生产包
|
||
- `npm run preview`：本地预览构建结果
|
||
- `npm run lint`：执行 eslint，并带 `--fix`
|
||
|
||
当前仓库没有现成的测试脚本，属于典型的“已交付老项目，缺少自动化回归”的状态。
|
||
|
||
## 认证与访问控制
|
||
|
||
项目的访问控制依赖浏览器存储，不是标准的后端 token 鉴权流：
|
||
|
||
- 路由守卫依据 `localStorage.TokenT` 判断是否已登录。
|
||
- 登录页当前使用前端硬编码账号密码校验，而不是正式后端登录接口。
|
||
- `TokenT` 实际保存的是一个时间字符串，用于计算“3 天内免密登录”。
|
||
- `localStorage.login` 被用来控制布局切换与页面状态。
|
||
- 菜单权限目前被写死为 `全选`，没有接入真实权限接口。
|
||
|
||
这意味着：后续如果要补安全能力，登录、权限、会话续期都需要整体重构，不能把当前实现视为最终鉴权方案。
|
||
|
||
## 路由与菜单概览
|
||
|
||
路由层当前启用的页面：
|
||
|
||
| 路由 | 页面名称 | 状态 |
|
||
| ------------------ | ------------ | ------------------------------ |
|
||
| `/login` | 登录 | 启用 |
|
||
| `/home` | 主页 | 启用，进入后立即跳转 `/udplog` |
|
||
| `/udplog` | UDP 监控 | 启用 |
|
||
| `/tasktimelog` | 线程耗时记录 | 启用 |
|
||
| `/blacklist` | 黑名单管理 | 启用 |
|
||
| `/tftpwhitelist` | TFTP 管理 | 启用 |
|
||
| `/voicelog` | 语音助手日志 | 启用 |
|
||
| `/statuslog` | 房态日志 | 启用 |
|
||
| `/powerlog` | 功率记录 | 路由启用，但菜单默认隐藏 |
|
||
| `/:pathMatch(.*)*` | 404 | 启用 |
|
||
|
||
代码存在但默认未接入主流程的页面：
|
||
|
||
- `src/pages/dicmanage/index.vue`：路由被注释，属于后台字典管理页。
|
||
- `src/pages/logsetup/index.vue`：未在路由中注册，属于个人资料维护页。
|
||
- `src/pages/udpconn/index.vue`：目录存在，但当前未接入路由或菜单。
|
||
|
||
## 后端域名与调用层次
|
||
|
||
`public/config.js` 中定义了三套主要地址：
|
||
|
||
- `ApiList[0]`：`http://blv-rd.tech:19088/api/`，主日志平台接口。
|
||
- `ApiList[1]`：`http://blv-rd.tech:19055/api/`，酒店/黑名单/主机相关接口。
|
||
- `ApiList[2]`：`http://www.boonlive-rcu.com:7000/api/`，RCU/TFTP 相关接口。
|
||
|
||
请求层分为四种：
|
||
|
||
- 默认 `$http`：来自 `src/axios.js` 默认实例。
|
||
- `createAxiosInstance(1)`：显式切到 `ApiList[1]`。
|
||
- `createAxiosInstance(2)`：显式切到 `ApiList[2]`。
|
||
- `fetch` / `$.ajax`：在 `App.vue` 中作为补充能力直接注入。
|
||
|
||
## 请求封装摘要
|
||
|
||
`src/axios.js` 的行为需要重点注意：
|
||
|
||
- `createAxiosInstance` 参数不是任意 `baseURL`，而是 `ApiList` 下标。
|
||
- 请求拦截器会在 `config.data` 为对象时自动执行 `JSON.stringify`。
|
||
- 项目内部大量页面又手动对参数做了一次 `JSON.stringify`，形成“调用方自己转 JSON，拦截器有时也会转”的混合风格。
|
||
- 某些接口使用 `qs.stringify` 发 `application/x-www-form-urlencoded`，通过第三个参数传 headers。
|
||
- 响应拦截器几乎不做统一错误处理，只是 `console.log` 后抛出异常。
|
||
|
||
## App.vue 提供的全局能力
|
||
|
||
根组件除了渲染菜单和布局，还承担了一些基础设施职责：
|
||
|
||
- 通过 provide 注入 `$http`、`config`、`checkLoginStatus`、`isMobile`、`fullScreen`。
|
||
- 提供 `ajaxfile(form)`，以 `fetch + FormData` 上传文件到 `FileUpload/UploadFile`。
|
||
- 提供 `ajax(api, form)`，使用 `jQuery.ajax` 发送 JSON POST 请求。
|
||
- 管理深浅色主题、菜单切换、浏览器尺寸监听和基础登录状态刷新。
|
||
|
||
## 开发风险与维护建议
|
||
|
||
- 登录逻辑是前端硬编码，不能作为正式生产安全实现继续扩展。
|
||
- 路由、菜单和页面目录存在不一致，新增功能前要先确认是否接入菜单、路由、缓存和权限。
|
||
- 页面对后端接口依赖很分散，且经常跨三个基础域名切换，排查接口问题时必须先确认 axios 实例来源。
|
||
- 代码中存在多套请求方式并存的情况，后续统一封装前应先做接口盘点。
|
||
- 项目当前没有系统化的 API 文档，维护时应优先参考本次新增的接口汇总文档。
|
||
|
||
## 文档索引
|
||
|
||
- `docs/project-overview.md`：项目总览
|
||
- `docs/page-functions.md`：页面功能说明
|
||
- `docs/api-summary.md`：接口汇总
|
||
- `docs/tooling-notes.md`：工具与非标准实现说明
|