XuJiacheng
5239411ec7
- 新增 openspec-propose 技能，支持快速提案生成变更及相关文档。 - 新增接口汇总文档，整理后端接口及其用途。 - 新增页面功能说明文档，描述各页面的功能及路由。 - 新增项目总览文档，概述项目结构、技术栈及运行方式。 - 新增工具与非标准实现说明文档，记录项目中的特殊实现及约定。 - 创建 legacy-project-documentation 变更，整合现有文档并迁移至正式 OpenSpec 目录。 - 记录项目中的高风险历史实现特征，明确页面启用状态及接口调用关系。
3.5 KiB
3.5 KiB
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
本次变更没有运行时迁移动作，只有文档与规范资产补齐：
- 通过 OpenSpec CLI 初始化并更新仓库级规范资产。
- 创建正式 change：
legacy-project-documentation。 - 输出文档文件到
docs/。 - 删除旧
spec/目录，确保规范入口唯一。 - 后续新需求统一转到
openspec/changes/下开展。
Open Questions
- 登录与权限逻辑是否要单独立项做安全性重构。
- 请求层是否需要拆分为“主平台 / 辅助平台 / RCU”三个显式 SDK。