# 需求描述文档 - OFC-AI 项目重构

## 功能特性

### 1. 项目重构与重命名

- **创建新项目 ofc-ai**：基于现有 aicoding_backend 项目进行重构
- **Skill 重命名**：根据功能重新命名所有 skill，使其命名更加直观和语义化
- **清理无用文件**：删除项目中未被使用的文件，精简项目结构
- **文档格式优化**：完善 PRP 和需求文档模板，提升对项目需求的理解能力

### 2. Skill 名称重命名计划

| 当前名称 | 新名称 | 功能描述 |
|---------|--------|----------|
| java-controller-generator | java-rest-api-generator | Java REST API 生成器（Controller 层） |
| java-dto-generator | java-data-model-generator | Java 数据模型生成器（DTO/VO/Entity） |
| java-rpc-generator | java-rpc-service-generator | Java RPC 服务生成器（JSF 接口实现） |
| java-service-generator | java-business-service-generator | Java 业务服务生成器（Service 层） |

### 3. 项目结构优化

**保留的核心模块**：
- `ofc_ai/main.py` - MCP 服务器入口
- `ofc_ai/tools/` - 工具实现模块
- `ofc_ai/prompts/` - 提示词模板
- `ofc_ai/utils/` - 通用工具函数

**需要清理的文件**：
- `tools/generate_test.py` - 空文件，无实际内容
- `notebooks/` - 开发调试文件，非生产必需

**需要删除的文件**（确认未使用后）：
- 未被任何模块导入的文件
- 测试遗留文件
- 废弃的模板文件

### 4. PRP 文档格式优化

**现有问题**：
- 模板结构较为通用，缺乏针对特定场景的定制
- 缺少项目上下文自动注入机制
- 验证清单不够具体

**优化方向**：
- 增加项目技术栈自动识别
- 添加依赖版本检查
- 强化代码规范验证
- 明确分层架构约束

### 5. 需求文档模板优化

**现有问题**：
- 模板结构简单，缺少必要字段
- 未明确区分功能需求和非功能需求
- 缺少风险评估模块

**优化方向**：
- 增加需求优先级字段
- 添加验收标准模板
- 补充技术方案建议模块
- 增加风险识别与规避方案

---

## 参考示例

以下为项目中现有的核心实现，重构时需保持其功能完整性：

### 1. MCP 工具实现示例

**文件**：`aicoding_backend/main.py`
- `generate_prp` - PRP 文档生成工具
- `execute_prp` - PRP 执行工具
- `java_fast_coding` - Java 快速编码工具
- `init_project_rules` - 项目规则初始化
- `init_requirements_doc` - 需求文档模板初始化
- `log_report` - 使用记录上报
- `skills_expert` - 智能 Skills 专家

### 2. Skills 实现示例

**目录**：`.joycode/skills/`
- `java-controller-generator/SKILL.md` - Controller 生成规范
- `java-service-generator/SKILL.md` - Service 层生成规范
- `java-dto-generator/SKILL.md` - DTO 生成规范
- `java-rpc-generator/SKILL.md` - RPC 服务生成规范

### 3. 提示词模板示例

**目录**：`aicoding_backend/prompts/`
- `prp_base.md` - PRP 基础模板
- `java_design_doc_template.md` - Java 设计文档模板
- `java_implementation_template.md` - Java 实现模板

---

## 参考文档

### 1. 项目规范文件

- `.joycode/rules/ProjectInfo.mdc` - 项目开发守则
- `pyproject.toml` - 项目配置和依赖

### 2. MCP 协议文档

- FastMCP 官方文档 - MCP 服务器框架
- Pydantic 文档 - 参数验证

### 3. 编码规范参考

- Java 命名规范
- Spring Boot 最佳实践
- RESTful API 设计规范

---

## 注意事项

### 1. 重构安全要求

**风险规避**：
- ⚠️ **必须**：先创建新项目，确认功能完整后再删除旧项目
- ⚠️ **必须**：保留所有现有工具的核心功能，不得遗漏
- ⚠️ **必须**：Skill 重命名后需同步更新 SKILL.md 汇总文件
- ⚠️ **禁止**：删除任何正在被引用的模块或函数

### 2. 代码迁移规范

**强制规定**：
- 所有工具函数必须保持异步特性
- 参数模型必须使用 Pydantic BaseModel
- 错误处理必须返回以 `❌` 开头的友好错误信息
- 成功响应必须使用 `generate_prompt()` 函数格式化

### 3. 文档更新要求

**强制规定**：
- PRP 模板优化后必须保持向后兼容
- 需求文档模板必须包含 `[AI Agent Action]` 指令
- 所有工具必须调用 `log_report` 工具上报使用记录

### 4. 测试验证清单

**必须验证**：
- [ ] 新项目所有 MCP 工具可正常调用
- [ ] Skills 索引和匹配功能正常
- [ ] PRP 生成和执行流程完整
- [ ] 文档模板格式正确

### 5. 项目命名规范

**新项目命名**：
- 项目名称：`ofc-ai`
- Python 包名：`ofc_ai`（使用下划线）
- 入口文件：`ofc_ai/main.py`

### 6. 文件清理原则

**删除判断标准**：
1. 文件未被任何其他文件 import
2. 文件不在 `pyproject.toml` 配置中被引用
3. 文件不是 MCP 工具的核心实现
4. 文件不是提示词模板或技能文件

### 7. Skill 重命名注意事项

**必须执行**：
- 更新 `.joycode/skills/SKILL.md` 汇总文件
- 更新每个 Skill 目录名称
- 保持 Skill 描述和功能不变
- 更新 `skills_expert.py` 中的相关注释（如有）

---

## 实施步骤建议

### 阶段一：项目创建与文件迁移

1. 创建新项目目录 `ofc-ai/`
2. 复制核心模块到新项目
3. 重命名包名和模块引用
4. 更新 `pyproject.toml` 配置

### 阶段二：Skill 重命名

1. 重命名 `.joycode/skills/` 下的目录
2. 更新每个 SKILL.md 中的 name 字段
3. 重新生成 SKILL.md 汇总文件

### 阶段三：文件清理

1. 使用静态分析工具识别未使用文件
2. 逐个确认后删除
3. 运行测试确保功能完整

### 阶段四：文档优化

1. 优化 PRP 模板结构
2. 完善需求文档模板
3. 更新项目规范文件

### 阶段五：验证与发布

1. 完整功能测试
2. 文档审查
3. 版本发布

---

## 验收标准

### 功能完整性

- [ ] 所有 MCP 工具功能正常
- [ ] Skills 匹配和执行正常
- [ ] 文档生成功能正常

### 代码质量

- [ ] 无未使用的导入和文件
- [ ] 代码符合 Python 规范
- [ ] 类型注解完整

### 文档质量

- [ ] PRP 模板结构清晰
- [ ] 需求文档模板完整
- [ ] 所有文档可被 AI Agent 正确解析

### 项目规范

- [ ] 目录结构符合规范
- [ ] 命名统一规范
- [ ] 配置文件正确

---

**[AI Agent Action]**完成文档创建后请呼叫「log_report」工具进行本次工具使用记录上报，本次记录使用的工具为 init_requirements_doc