"""
initRequirementsDoc prompt 生成器
initRequirementsDoc prompt generator
负责将模板和参数组合成最终的 prompt
Responsible for combining templates and parameters into the final prompt
"""

from typing import Optional, Dict, Any
from dataclasses import dataclass
import asyncio
from ofc_ai.utils.loader import load_prompt


@dataclass
class InitRequirementsDocPromptParams:
    """
    initRequirementsDoc prompt 参数类
    initRequirementsDoc prompt parameters class
    """
    # 目前没有额外参数，未来可按需扩展
    # Currently no additional parameters, can be expanded as needed in the future
    pass


async def get_init_requirements_doc_prompt(
    params: Optional[InitRequirementsDocPromptParams] = None
) -> str:
    """
    获取 initRequirementsDoc 的完整 prompt
    Get the complete prompt for initRequirementsDoc
    
    Args:
        params: prompt 参数（可选）/ prompt parameters (optional)
        
    Returns:
        str: 生成的 prompt / generated prompt
    """
    
    index_template = """
# 需求描述文档

## 目的

**此文件专为 AI Agent 设计，非一般开发者文档。**
**必须生成一个专属于 AI Agent 使用的需求描述文档([根据本次需求命名].md)。**

**必须专注于以下关键目标：**

- 准确识别和描述产品的核心功能特性
- 识别并规避潜在风险和注意事项
- 输出结构清晰、功能完整的需求文档

**强制规定：**

- 完成的规范必须使 AI Agent 能立即理解哪些文件必须参考或修改
- 避免使用模糊不清的需求描述语言
- 使用命令式语言定义规则，避免解释性内容
- 注意事项必须包含具体的风险规避方案
- 参考示例必须来自「examples」文件夹中的产品
- 识别描述中外部依赖，统一调用MCP工具阅读JAR包中源代码

**严重禁止：**

- 禁止包含通用开发知识
- 禁止包含 LLM 已知的通用开发知识
- 进行项目功能解释
- 禁止开始写代码

---

## 建议结构

请使用以下结构建立需求描述文档文件：

```markdown
# 需求描述文档 - [需求名称]

## 功能特性

### 1. 核心功能
- **功能点1**: [详细描述]
- **功能点2**: [详细描述]
- **功能点3**: [详细描述]

### 2. 功能优先级
| 优先级 | 功能名称 | 描述 | 预计工作量 |
|--------|----------|------|------------|
| P0 | [核心功能] | [描述] | [工时] |
| P1 | [重要功能] | [描述] | [工时] |
| P2 | [一般功能] | [描述] | [工时] |

### 3. 功能依赖关系
```yaml
依赖关系:
  - 功能A -> 功能B: [依赖说明]
  - 功能B -> 功能C: [依赖说明]
```

## 参考示例

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

### 1. 相关代码示例
**文件**: `[文件路径]`
- **功能**: [描述主要功能]
- **参考点**: [需要参考的具体实现]

### 2. 配置示例
**文件**: `[配置文件路径]`
- **配置项**: [描述配置项]

## 参考文档

### 1. 项目规范文件
- `[文件路径]` - [文件用途]

### 2. 外部文档
- [文档名称](URL) - [文档用途]

### 3. API 文档
- [API名称](URL) - [API用途]

## 技术方案建议

### 1. 推荐技术栈
```yaml
语言: [推荐语言及版本]
框架: [推荐框架及版本]
数据库: [推荐数据库]
缓存: [推荐缓存方案]
其他: [其他推荐]
```

### 2. 架构建议
- **分层架构**: [描述分层方案]
- **设计模式**: [推荐使用的设计模式]
- **性能优化**: [性能优化建议]

### 3. 关键技术决策
| 决策点 | 选择 | 理由 |
|--------|------|------|
| [决策点1] | [选择] | [理由] |
| [决策点2] | [选择] | [理由] |

## 验收标准

### 1. 功能验收
- [ ] [验收标准1]
- [ ] [验收标准2]
- [ ] [验收标准3]

### 2. 性能验收
- [ ] [性能指标1]: [目标值]
- [ ] [性能指标2]: [目标值]

### 3. 安全验收
- [ ] [安全要求1]
- [ ] [安全要求2]

### 4. 兼容性验收
- [ ] [兼容性要求1]
- [ ] [兼容性要求2]

## 风险评估与规避方案

### 1. 风险识别
| 风险ID | 风险描述 | 可能性 | 影响程度 | 优先级 |
|--------|----------|--------|----------|--------|
| R1 | [风险描述] | [高/中/低] | [高/中/低] | [P0/P1/P2] |

### 2. 风险规避方案
```yaml
风险 R1:
  描述: [详细描述]
  触发条件: [触发条件]
  规避措施:
    - [措施1]
    - [措施2]
  应急预案: [应急预案]
```

## 注意事项

### 1. 开发规范
**强制规定**:
- [规范1]
- [规范2]
- [规范3]

**严重禁止**:
- [禁止1]
- [禁止2]

### 2. 代码规范
- **命名规范**: [命名规则]
- **注释规范**: [注释要求]
- **日志规范**: [日志要求]

### 3. 测试要求
- **单元测试**: [单元测试要求]
- **集成测试**: [集成测试要求]
- **测试覆盖率**: [覆盖率要求]

---

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

## 内容指南

需求描述文档应包含但不限于以下内容：

1. **功能特性** - 简要描述项目功能点描述，包含优先级和依赖关系
2. **参考示例** - 描述主要功能和使用场景，提供代码参考
3. **参考文档** - 开发过程中需要参考的任何文档
4. **技术方案建议** - 推荐的技术栈和架构建议
5. **验收标准** - 明确的功能、性能、安全验收标准
6. **风险评估与规避方案** - 风险识别和规避方案
7. **注意事项** - 任何其他注意事项或特定要求

## 文档质量要求

1. **面向 AI 优化** - 文档将作为 prompt 提供给 Coding Agent AI，应对 prompt 最佳化
2. **使用命令式语言** - 必须使用直接指令而非描述性语言，减少解释内容
3. **结构化呈现** - 所有内容必须以列表、表格等结构化形式呈现，便于 AI 解析
4. **突出重点标记** - 使用粗体、警告标记等突出关键规则和禁忌
5. **移除通用知识** - 禁止包含 LLM 已知的通用开发知识，仅包含项目特定规则
6. **优先级明确** - 必须标注功能优先级，便于分阶段实施
7. **验收标准量化** - 验收标准必须可量化、可测试

请根据以上指南，创建一个名为 [根据本次需求命名(使用下划线命名风格)].md 的文件并存放于根目录下「.joycode/docs」目录

## 完成上面的步骤后
**[AI Agent Action]**请呼叫「log_report」工具进行本次工具使用记录上报
    """

    # 加载可能的自定义 prompt (通过环境变量覆盖或追加)
    # Load possible custom prompt (override or append via environment variables)
    return load_prompt(index_template, "INIT_REQUIREMENTS_DOC")