73 lines
3.5 KiB
Markdown
73 lines
3.5 KiB
Markdown
|
## Context
|
|||
|
|
|
|||
|
|
当前仓库是 Vue 3 + Vite 前端项目，核心业务页面主要集中在 UDP 监控、房态日志、语音助手日志、黑名单和 TFTP 管理等模块。项目已经交付使用，但存在典型老项目特征：
|
|||
|
|
|
|||
|
|
- 文档缺失，页面和接口关系需要靠读代码还原。
|
|||
|
|
- 登录与权限实现带有临时方案痕迹。
|
|||
|
|
- 请求层同时混用 axios、fetch、jQuery.ajax。
|
|||
|
|
- 路由、菜单与页面目录不完全一致，部分页面已经脱离主流程。
|
|||
|
|
|
|||
|
|
本次变更的目标不是重构实现，而是沉淀一份足够支撑后续维护的知识底座，并把文档化工作本身纳入 OpenSpec 变更流程。
|
|||
|
|
|
|||
|
|
## Goals / Non-Goals
|
|||
|
|
|
|||
|
|
**Goals:**
|
|||
|
|
|
|||
|
|
- 建立一个正式的 OpenSpec change，记录本次老项目文档化工作。
|
|||
|
|
- 产出面向维护的 Markdown 文档，帮助后续开发快速定位页面、接口和工具约定。
|
|||
|
|
- 明确当前项目中的高风险历史实现，为未来重构提供入口信息。
|
|||
|
|
|
|||
|
|
**Non-Goals:**
|
|||
|
|
|
|||
|
|
- 不修改任何业务页面逻辑。
|
|||
|
|
- 不修复历史遗留 bug。
|
|||
|
|
- 不统一重构 axios、登录或权限系统。
|
|||
|
|
- 不补充自动化测试或发布流程。
|
|||
|
|
|
|||
|
|
## Decisions
|
|||
|
|
|
|||
|
|
### Decision 1：文档按“总览 / 页面 / 接口 / 工具”四类拆分
|
|||
|
|
|
|||
|
|
理由：老项目维护时，最常见的问题分别是“项目怎么进”“页面做什么”“接口从哪来”“工具为什么这么写”。按这四个维度拆开，检索效率最高。
|
|||
|
|
|
|||
|
|
备选方案：
|
|||
|
|
|
|||
|
|
- 只保留一个总文档。缺点是后续持续扩展时会迅速膨胀，不利于查找。
|
|||
|
|
|
|||
|
|
### Decision 2：将旧规范草稿完全收敛到 `openspec/changes/` 正式资产
|
|||
|
|
|
|||
|
|
理由：项目已经具备正式的 OpenSpec 目录结构，继续保留额外的 `spec/` 目录只会制造双入口和歧义。统一到 `openspec/changes/` 后，后续维护路径更清晰。
|
|||
|
|
|
|||
|
|
备选方案：
|
|||
|
|
|
|||
|
|
- 保留旧 `spec/` 目录做兼容说明。缺点是会持续造成“哪里才是规范源”的认知负担。
|
|||
|
|
|
|||
|
|
### Decision 3：只做静态文档化，不试图在本次变更中修复源码问题
|
|||
|
|
|
|||
|
|
理由：用户明确要求不能修改代码；同时老项目中存在多个潜在问题点，若在同一次变更中混入修复，会扩大范围并提高风险。
|
|||
|
|
|
|||
|
|
备选方案：
|
|||
|
|
|
|||
|
|
- 在文档化时顺手修复明显问题。缺点是违反本次约束，也会让变更边界变得不清晰。
|
|||
|
|
|
|||
|
|
## Risks / Trade-offs
|
|||
|
|
|
|||
|
|
- [风险] 文档来自静态代码阅读，无法覆盖运行期才会暴露的动态行为。 → 缓解：重点记录可确认的页面、接口和工具约定，不对未验证行为做过度推断。
|
|||
|
|
- [风险] 某些页面未接路由或菜单，文档内容可能与当前实际使用范围不完全一致。 → 缓解：在文档中显式区分“已启用”和“代码存在但未接入”。
|
|||
|
|
- [风险] 旧目录删除后，历史使用者可能短期内找不到原来的路径。 → 缓解：将有效内容全部并入 `openspec/changes/`，并确保当前 change 可被 OpenSpec CLI 正常识别。
|
|||
|
|
|
|||
|
|
## Migration Plan
|
|||
|
|
|
|||
|
|
本次变更没有运行时迁移动作，只有文档与规范资产补齐：
|
|||
|
|
|
|||
|
|
1. 通过 OpenSpec CLI 初始化并更新仓库级规范资产。
|
|||
|
|
2. 创建正式 change：`legacy-project-documentation`。
|
|||
|
|
3. 输出文档文件到 `docs/`。
|
|||
|
|
4. 删除旧 `spec/` 目录，确保规范入口唯一。
|
|||
|
|
5. 后续新需求统一转到 `openspec/changes/` 下开展。
|
|||
|
|
|
|||
|
|
## Open Questions
|
|||
|
|
|
|||
|
|
- 登录与权限逻辑是否要单独立项做安全性重构。
|
|||
|
|
- 请求层是否需要拆分为“主平台 / 辅助平台 / RCU”三个显式 SDK。
|