feat: 完成老项目文档化工作

- 新增 openspec-propose 技能,支持快速提案生成变更及相关文档。
- 新增接口汇总文档,整理后端接口及其用途。
- 新增页面功能说明文档,描述各页面的功能及路由。
- 新增项目总览文档,概述项目结构、技术栈及运行方式。
- 新增工具与非标准实现说明文档,记录项目中的特殊实现及约定。
- 创建 legacy-project-documentation 变更,整合现有文档并迁移至正式 OpenSpec 目录。
- 记录项目中的高风险历史实现特征,明确页面启用状态及接口调用关系。
This commit is contained in:
2026-03-06 09:32:21 +08:00
parent da68cef1c1
commit 5239411ec7
17 changed files with 1913 additions and 0 deletions

123
docs/project-overview.md Normal file
View File

@@ -0,0 +1,123 @@
# 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`:工具与非标准实现说明