XuJiacheng
5239411ec7
- 新增 openspec-propose 技能，支持快速提案生成变更及相关文档。 - 新增接口汇总文档，整理后端接口及其用途。 - 新增页面功能说明文档，描述各页面的功能及路由。 - 新增项目总览文档，概述项目结构、技术栈及运行方式。 - 新增工具与非标准实现说明文档，记录项目中的特殊实现及约定。 - 创建 legacy-project-documentation 变更，整合现有文档并迁移至正式 OpenSpec 目录。 - 记录项目中的高风险历史实现特征，明确页面启用状态及接口调用关系。
97 lines
3.6 KiB
Markdown
97 lines
3.6 KiB
Markdown
# 工具与非标准实现说明
|
||
|
||
## axios 封装
|
||
|
||
文件：`src/axios.js`
|
||
|
||
当前项目的 axios 封装与常规写法有几个明显差异：
|
||
|
||
1. `createAxiosInstance(urlnum)` 参数语义是“配置下标”，不是完整 URL。
|
||
2. `baseURL` 固定取自 `config.ApiList[urlnum || 0]`。
|
||
3. 请求拦截器会把对象类型的 `config.data` 自动转成 JSON 字符串。
|
||
4. 如果页面已经手工 `JSON.stringify`，拦截器不会再重复转换，但代码阅读成本会升高。
|
||
5. 响应拦截器没有统一消息提示，也没有 token 失效处理。
|
||
|
||
建议：如果后续要统一网络层，先做接口分组和参数样式清查，不要直接全局替换。
|
||
|
||
## 全局注入能力
|
||
|
||
文件：`src/main.js`、`src/App.vue`
|
||
|
||
项目通过 provide/inject 暴露了多项全局能力：
|
||
|
||
- `$http`：默认 axios 实例
|
||
- `config`：运行配置
|
||
- `checkLoginStatus`：登录状态检查
|
||
- `calculateTimeDiff`：时间差辅助方法
|
||
- `isMobile`：移动端状态
|
||
- `fullScreen`：页面全屏状态
|
||
- `ajaxfile`：`fetch + FormData` 文件上传
|
||
- `ajax`：`jQuery.ajax` JSON 请求
|
||
|
||
这意味着很多页面不是从模块 import 工具函数，而是依赖根组件注入。迁移或拆分页面时需要同步处理这些依赖。
|
||
|
||
## 本地存储约定
|
||
|
||
项目大量依赖浏览器存储保存运行态：
|
||
|
||
- `TokenT`：保存时间字符串，用于免密登录窗口判断
|
||
- `login`：字符串形式的登录标记
|
||
- `username`：当前用户名
|
||
- `url`：上次停留的页面路由
|
||
- `rememberedUsername` / `rememberedPassword`：登录页记住我
|
||
- `loginErrorAttempts` / `loginLockUntil`：登录错误计数和锁定信息
|
||
- `currentRoute`：路由守卫中记录当前访问路径
|
||
|
||
这套约定分散在多个页面和根组件中，没有中心化状态管理。
|
||
|
||
## 非标准登录实现
|
||
|
||
登录页当前是演示型或临时型实现：
|
||
|
||
- 用户名和密码写在页面常量 `validUsers` 中。
|
||
- 注释中保留了旧接口调用痕迹，但并未启用。
|
||
- 路由守卫依赖 `TokenT` 时间串，而不是标准 JWT 或 session token。
|
||
|
||
如果未来要正式上线鉴权，应整体替换，而不是局部打补丁。
|
||
|
||
## jQuery.ajax 与 fetch 仍在使用
|
||
|
||
文件：`src/App.vue`
|
||
|
||
虽然项目主体已经使用 Vue 3，但根组件仍保留了旧式辅助方法：
|
||
|
||
- `ajaxfile`：手写 `fetch` 上传，额外拼接了 `Authorization` 请求头。
|
||
- `ajax`：使用 `$.ajax` 发送 JSON 请求。
|
||
|
||
说明项目经历过多轮演化，存在旧工具与新工具并存的历史包袱。
|
||
|
||
## MinuteIndex 工具类
|
||
|
||
文件：`src/utils/index.js`
|
||
|
||
`MinuteIndex` 用于把日志对象按“分钟 + commandType”索引到 `Map` 中，便于高频查询：
|
||
|
||
- 适合按分钟级时间快速定位同一命令类型的数据。
|
||
- 用 `WeakMap` 追踪对象位置，支持更新和移除。
|
||
- 对时间字符串做了局部格式标准化处理。
|
||
|
||
该工具体现出页面中存在一定的前端侧数据索引需求，不完全依赖后端聚合。
|
||
|
||
## 页面状态与菜单控制
|
||
|
||
文件：`src/App.vue`
|
||
|
||
菜单、缓存、主题切换等逻辑都集中在根组件：
|
||
|
||
- 菜单项写死在 `menuValue`。
|
||
- 页面权限目前默认全部开放。
|
||
- 主题切换同时操作 Element Plus 深浅模式和自定义 CSS 变量。
|
||
- `home` 实际只是跳转页，不是业务主页。
|
||
|
||
## 建议的维护策略
|
||
|
||
- 新增接口前，先决定接入哪一套 baseURL，再确定用默认 `$http` 还是 `createAxiosInstance`。
|
||
- 新增页面前，先同时检查目录、路由、菜单、权限过滤和缓存策略。
|
||
- 若要做重构，优先从登录、请求层、全局注入三块入手，因为它们是当前项目最明显的历史耦合点。
|