178 lines
5.2 KiB
Markdown
178 lines
5.2 KiB
Markdown
# Handoff: Phase 1 OpenSpec 格式修正
|
||
|
||
**交接时间**: 2026-06-23
|
||
**项目**: SuperBizAgent-java
|
||
**分支**: emdash/mvp-waq54
|
||
**任务**: 将 Phase 1 OpenSpec 重构为标准格式
|
||
|
||
---
|
||
|
||
## 背景
|
||
|
||
当前正在执行 Phase 1（基础设施搭建）实施，已通过 sm-flow 完整流程生成 OpenSpec，但**格式不符合 OpenSpec 标准规范**。
|
||
|
||
---
|
||
|
||
## 已完成工作
|
||
|
||
### 1. Phase 1 代码实施（部分完成）
|
||
|
||
**已提交 3 个 commit**：
|
||
- `5ddb7a6`: Phase 1 基础设施代码
|
||
- 添加 JPA/Flyway/Redis 依赖到 pom.xml
|
||
- 创建 3 个 Flyway 迁移脚本（V001/V002/V003）
|
||
- 创建 3 个枚举类（FaultCategory/DiagnosisStatus/SourceType）
|
||
- 配置 MySQL + Redis 连接
|
||
- `3f15778`: Phase 1 文档和 OpenSpec（**格式错误，需要修正**）
|
||
- `a3d806e`: .gitignore 更新
|
||
|
||
**已推送到远程**：`origin/emdash/mvp-waq54`
|
||
|
||
**配置信息**（已完成）：
|
||
- **MySQL**: 119.29.78.52:33306/superbiz_agent
|
||
- 用户: root
|
||
- 密码: 已从仓库移除，使用环境变量注入
|
||
- driver: com.mysql.cj.jdbc.Driver
|
||
- URL参数: useUnicode=true&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
|
||
- **Redis**: 119.29.78.52:6379
|
||
- 无密码
|
||
- database: 0
|
||
- timeout: 3000ms
|
||
- 连接池: max-active=8, max-idle=8, min-idle=0
|
||
- **JPA**:
|
||
- ddl-auto: validate（Flyway 管理表结构）
|
||
- show-sql: true
|
||
- format_sql: true
|
||
- dialect: org.hibernate.dialect.MySQL8Dialect
|
||
- **Flyway**:
|
||
- enabled: true
|
||
- baseline-on-migrate: true
|
||
- locations: classpath:db/migration
|
||
- application.yml 配置完整（保留原有 Milvus、DashScope、MCP、文档分片、RAG、Prometheus、CLS 等配置）
|
||
|
||
**待完成任务**（Phase 1 剩余）：
|
||
- Task 1.6-1.11: JPA 实体类、Repository、Redis 会话管理
|
||
- Task 3.1-3.3: 包名重构（org.example → com.superbiz.agent）
|
||
- Task 4.1-4.7: 文档管理 CRUD + 混合检索
|
||
|
||
### 2. OpenSpec 生成（sm-flow 完整流程）
|
||
|
||
通过 sm-flow 完整流程（clarify → context → propose → grill → specify → audit → commit）生成了 Phase 1 OpenSpec，但**格式不符合标准**。
|
||
|
||
**当前目录结构**（错误）：
|
||
```
|
||
openspec/changes/phase-1-infrastructure/
|
||
├── proposal.md # ❌ 应合并到 change.md
|
||
├── design.md # ❌ 应合并到 change.md
|
||
├── specs/
|
||
│ └── functional-specs.md # ❌ 应为 specs.md
|
||
├── tasks.md # ❌ 格式错误（详细文档而非任务列表）
|
||
├── decisions.md # ✅ 格式可能正确
|
||
└── .commit # ❌ 非标准文件
|
||
```
|
||
|
||
---
|
||
|
||
## 问题诊断
|
||
|
||
### 格式问题清单
|
||
|
||
1. **文件结构错误**
|
||
- proposal.md 和 design.md 应合并为 change.md
|
||
- specs/functional-specs.md 应改为 specs.md
|
||
- .commit 文件非标准
|
||
|
||
2. **tasks.md 格式错误**（用户明确指出）
|
||
- 当前：详细的 Markdown 文档（标题、粗体、嵌套、描述、验收标准）
|
||
- 应该：纯任务列表格式（checkbox 列表）
|
||
- 示例：`- [ ] Task 1.1: 添加依赖到 pom.xml`
|
||
|
||
3. **缺少标准格式规范**
|
||
- 不清楚 change.md 应包含哪些部分
|
||
- 不清楚 specs.md 的标准结构
|
||
- 需要参考 OpenSpec 标准示例
|
||
|
||
---
|
||
|
||
## 下一步行动
|
||
|
||
### 主要任务：修正 OpenSpec 格式
|
||
|
||
**目标**：将 `openspec/changes/phase-1-infrastructure/` 重构为标准 OpenSpec 格式
|
||
|
||
**步骤**：
|
||
1. **了解标准格式**
|
||
- 阅读 OpenSpec 规范文档或示例
|
||
- 明确 change.md、specs.md、tasks.md 的标准结构
|
||
|
||
2. **重构文件结构**
|
||
- 合并 proposal.md + design.md → change.md
|
||
- 重构 specs/functional-specs.md → specs.md
|
||
- 重写 tasks.md 为简单的 checkbox 列表
|
||
- 检查 decisions.md 是否符合标准
|
||
- 删除 .commit 或确认其用途
|
||
|
||
3. **验证格式**
|
||
- 确认符合 OpenSpec 标准
|
||
- 提交修正后的 OpenSpec
|
||
|
||
**约束**：
|
||
- 保留所有内容价值，只调整格式
|
||
- 不修改已实施的代码
|
||
- 不影响 application.yml 中的现有配置
|
||
|
||
---
|
||
|
||
## 建议技能
|
||
|
||
1. **openspec-propose** 或 **openspec-apply-change**
|
||
查看这些技能生成的 OpenSpec 格式，作为标准参考
|
||
|
||
2. **Read**
|
||
读取现有 OpenSpec 文件内容，理解需要重构的部分
|
||
|
||
3. **Write** / **Edit**
|
||
重构 OpenSpec 文件为标准格式
|
||
|
||
---
|
||
|
||
## 关键文件路径
|
||
|
||
**OpenSpec 目录**：
|
||
- `openspec/changes/phase-1-infrastructure/`（需要重构）
|
||
|
||
**参考文档**：
|
||
- `docs/architecture/implementation-detail.md`（实施计划）
|
||
- `docs/tables/*.md`（数据库表设计）
|
||
|
||
**代码文件**（已完成）：
|
||
- `pom.xml`
|
||
- `src/main/resources/application.yml`
|
||
- `src/main/resources/db/migration/V00*.sql`
|
||
- `src/main/java/com/superbiz/agent/domain/enums/*.java`
|
||
|
||
---
|
||
|
||
## 环境信息
|
||
|
||
- **工作目录**: D:\zhu\worktree\SuperBizAgent-java\emdash\mvp-waq54
|
||
- **Git 分支**: emdash/mvp-waq54
|
||
- **平台**: Windows (bash shell)
|
||
- **Maven**: 可用
|
||
- **数据库**: MySQL 已配置，数据库 `superbiz_agent` 需要用户创建
|
||
|
||
---
|
||
|
||
## 敏感信息（已编辑）
|
||
|
||
- MySQL 密码：已从仓库移除，使用环境变量注入
|
||
- Redis：无密码
|
||
|
||
---
|
||
|
||
## 备注
|
||
|
||
- 用户已解决分支合并冲突，当前在新分支 `emdash/mvp-waq54`
|
||
- Phase 1 实施暂停在 OpenSpec 格式修正任务
|
||
- 修正完成后可继续执行 Task 1.6 及后续任务
|