feat: 完成老项目文档化工作
- 新增 openspec-propose 技能,支持快速提案生成变更及相关文档。 - 新增接口汇总文档,整理后端接口及其用途。 - 新增页面功能说明文档,描述各页面的功能及路由。 - 新增项目总览文档,概述项目结构、技术栈及运行方式。 - 新增工具与非标准实现说明文档,记录项目中的特殊实现及约定。 - 创建 legacy-project-documentation 变更,整合现有文档并迁移至正式 OpenSpec 目录。 - 记录项目中的高风险历史实现特征,明确页面启用状态及接口调用关系。
This commit is contained in:
96
docs/tooling-notes.md
Normal file
96
docs/tooling-notes.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# 工具与非标准实现说明
|
||||
|
||||
## 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`。
|
||||
- 新增页面前,先同时检查目录、路由、菜单、权限过滤和缓存策略。
|
||||
- 若要做重构,优先从登录、请求层、全局注入三块入手,因为它们是当前项目最明显的历史耦合点。
|
||||
Reference in New Issue
Block a user