名称: "增强版 PRP 模板 v3 - 上下文丰富、智能验证与风险评估"
描述: 该模板专为 AI Agent 优化，支持项目技术栈自动识别、依赖版本检查、代码规范验证和风险评估

## 目的
该模板专为 AI 代理优化，使其能够通过充分的上下文和自我验证能力，通过迭代改进实现可工作的代码。新增技术栈识别、风险评估等模块，提升实现成功率。

## 核心原则
1. **上下文为王**: 包含所有必要的文档、示例和注意事项
2. **验证循环**: 提供 AI 可运行和修复的可执行测试/检查
3. **信息密集**: 使用代码库中的关键词和模式
4. **渐进式成功**: 从简单开始，验证后再增强
5. **全局规则**: 确保遵循 CLAUDE.md 中的所有规则
6. **风险前置**: 在实施前识别和规避潜在风险
7. **技术栈对齐**: 确保实现与项目技术栈保持一致

---

## 目标
[需要构建什么 - 明确说明最终状态和期望]

### 成功标准
- [ ] [具体的可衡量结果]
- [ ] 功能测试通过
- [ ] 性能指标达标
- [ ] 代码审查通过

## 项目技术栈识别

### 自动识别清单
在开始实施前，必须识别并确认以下技术栈信息：

```yaml
项目框架:
  语言版本: [如 Java 17/21, Python 3.11+]
  框架类型: [如 Spring Boot 3.x, FastAPI, Django]
  构建工具: [如 Maven, Gradle, pip, uv]
  
数据库与存储:
  数据库类型: [如 MySQL, PostgreSQL, MongoDB]
  缓存方案: [如 Redis, Memcached]
  ORM 框架: [如 MyBatis, JPA/Hibernate, SQLAlchemy]
  
中间件:
  消息队列: [如 Kafka, RabbitMQ]
  RPC 框架: [如 Dubbo, JSF, gRPC]
  配置中心: [如 Nacos, Apollo]
  
工具库:
  工具类库: [如 Hutool, Guava, Apache Commons]
  JSON 处理: [如 Jackson, Gson, FastJSON]
  日志框架: [如 SLF4J + Logback]
```

### 技术栈识别方法
1. 检查 `pom.xml` 或 `build.gradle` 文件
2. 检查 `requirements.txt` 或 `pyproject.toml` 文件
3. 检查项目配置文件（`application.yml`, `application.properties`）
4. 检查现有代码中的导入语句

## 依赖版本检查

### 必须检查的依赖
```yaml
核心依赖:
  - 名称: [依赖名称]
    版本: [当前版本]
    要求: [最低版本要求]
    状态: [✅ 满足 / ❌ 需升级]
    
冲突检测:
  - 是否存在版本冲突: [是/否]
  - 冲突详情: [描述冲突及解决方案]
```

### 版本兼容性矩阵
| 组件 | 当前版本 | 推荐版本 | 兼容性 |
|------|----------|----------|--------|
| [组件名] | [版本] | [版本] | [✅/❌] |

## 所有必需的上下文

### 文档和参考资料（列出实现功能所需的所有上下文）
```yaml
# 必读 - 将这些包含在您的上下文窗口中
- url: [官方 API 文档 URL]
  why: [您需要的具体章节/方法]
  
- file: [path/to/example.java]
  why: [要遵循的模式，要避免的陷阱]
  
- doc: [库文档 URL] 
  section: [关于常见陷阱的具体章节]
  critical: [防止常见错误的关键见解]

- docfile: [PRPs/ai_docs/file.md]
  why: [用户粘贴到项目中的文档]
```

### 当前代码库结构（在项目根目录运行 `tree` 命令）以获取代码库概览
```bash
[项目目录结构]
```

### 期望的代码库结构（包含要添加的文件及文件职责）
```bash
[目标目录结构]
```

### 已知的代码库陷阱和库怪癖  
```java
// 关键: [库名称] 需要 [特定设置/使用约定]
// 示例: Spring Boot 中 @ConfigurationProperties 类必须提供 setter 方法
// 示例: Hibernate 实体类必须提供无参构造函数，字段应使用包装类型（如 Integer 而非 int）
// 示例: 使用 Lombok 时，@Data 与 @Entity 混用可能导致 Hibernate 代理问题，建议改用 @Getter/@Setter
// 示例: Java 命名规范：类名 PascalCase，方法和变量 camelCase，常量 UPPER_SNAKE_CASE
// 示例: Optional 仅用于返回值，不应用于字段或方法参数
```

## 风险评估与规避方案

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

### 风险规避方案
```yaml
风险 R1:
  描述: [详细描述风险]
  触发条件: [什么情况下会触发]
  规避措施:
    - [具体措施1]
    - [具体措施2]
  应急预案: [如果发生如何处理]
  
风险 R2:
  描述: [详细描述风险]
  触发条件: [什么情况下会触发]
  规避措施:
    - [具体措施1]
    - [具体措施2]
  应急预案: [如果发生如何处理]
```

### 技术债务考虑
- 是否引入新的技术债务: [是/否]
- 债务类型: [描述]
- 还债计划: [如何在未来处理]

## 实施蓝图

### 分层架构约束
```yaml
架构分层:
  表现层 (Controller/API):
    - 职责: 接收请求、参数校验、调用业务层、封装响应
    - 禁止: 直接访问数据库、编写业务逻辑
    
  业务层 (Service/Domain):
    - 职责: 业务逻辑编排、事务管理
    - 禁止: 直接操作 HTTP 请求/响应
    
  数据层 (Repository/DAO):
    - 职责: 数据访问、SQL 执行
    - 禁止: 包含业务逻辑
    
  基础设施层 (Infrastructure):
    - 职责: 外部服务集成、工具类
    - 禁止: 包含业务逻辑
```

### 数据模型和结构  

定义清晰、封装良好、类型安全的核心数据模型，确保与序列化和持久化框架兼容。

```java
示例:
 - 使用普通 Java 类（POJO）定义 DTO 和实体，提供 public 无参构造函数
 - 使用 Lombok @Getter/@Setter
 - 使用 enum 定义状态或分类常量，禁止使用字符串字面量
 - 实体类使用 JPA 注解（如 @Entity、@Table、@Id、@Column）
 - DTO 类用于 API 输入/输出，与 JPA 实体分离
 - 使用 Bean Validation 注解（如 @NotNull、@NotBlank、@Email）进行校验
 - 避免在模型中使用 Java 8 之后的语言特性（如 records、sealed classes）
```

### 按顺序完成 PRP 所需完成的任务列表

```yaml
任务 1:
修改 jd.gms.item.site.web/src/main/java/jd/gms/item/site/controller/task/TaskControllerNew.java:
  - 在addTaskV2方法中，submitTaskService.submitTask4File调用成功后
  - 添加缓存记录逻辑：RedisCacheUtil.hIncrBy("task:usage:stat:" + getUserCodeLowerCase(), type, 1L)
  - 添加try-catch块确保缓存失败不影响主流程
  - 添加适当的日志记录
  风险: R1
  预计时间: 30分钟

任务 N:
...
```

### 每个任务所需的伪代码（根据需要添加到每个任务）
```java
// 任务 1 - 修改addTaskV2方法
public SiteResult addTaskV2(...) {
    // ... 现有代码 ...
    
    TaskResult taskResult = submitTaskService.submitTask4File(...);
    
    // 新增：记录任务使用统计
    try {
        if (taskResult.isSuccess()) {
            taskUsageStatService.recordTaskUsage(getUserCodeLowerCase(), type);
        }
    } catch (Exception e) {
        log.warn("记录任务使用统计失败，不影响主流程, erp={}, type={}", getUserCodeLowerCase(), type, e);
    }
    
    // ... 现有代码 ...
}
```

### 集成点
```yaml
缓存配置:
  - 使用现有RedisCacheUtil工具类
  - 缓存过期时间：30天
  - key命名规范：task:usage:stat:{erp}
  
依赖注入:
  - 在TaskControllerNew中添加TaskUsageStatService注入
  - 使用现有@Autowired注解模式
  
接口规范:
  - 查询接口：GET /new/task/getUsageStat?erp={erp}
  - 返回格式：SiteResult<TaskUsageStatDTO>
```

## 验证循环

### 级别 1: 语法和样式
```bash
# 编译检查
mvn compile -pl [本次生成、修改的代码文件]
# 预期: 无编译错误
```

### 级别 2: 单元测试
```bash
# 运行单元测试
mvn test -pl [模块名]
# 预期: 所有测试通过
```

### 级别 3: 集成测试
```bash
# 运行集成测试
mvn verify -pl [模块名]
# 预期: 集成测试通过
```

### 级别 4: 代码规范检查
```bash
# 代码风格检查
mvn checkstyle:check
# 预期: 无风格违规

# 静态代码分析
mvn sonar:sonar
# 预期: 无严重问题
```

## 最终验证清单
- [ ] 无 lint 错误
- [ ] 无类型错误
- [ ] 错误情况得到优雅处理
- [ ] 日志信息丰富但不冗长
- [ ] 文档已更新（如需要）
- [ ] 单元测试覆盖率达标
- [ ] 集成测试通过
- [ ] 性能指标达标
- [ ] 安全检查通过
- [ ] 代码审查通过

## 回滚计划

### 回滚触发条件
- [条件1]: [描述]
- [条件2]: [描述]

### 回滚步骤
1. [步骤1]
2. [步骤2]
3. [步骤3]

### 数据回滚
```sql
-- 数据回滚脚本（如需要）
```

---

## 要避免的反模式
- ❌ 当现有模式有效时不要创建新模式
- ❌ 不要因为"应该可以工作"而跳过验证
- ❌ 不要忽略失败的测试 - 修复它们
- ❌ 不要在异步上下文中使用同步函数
- ❌ 不要硬编码应该是配置的值
- ❌ 不要捕获所有异常 - 要具体
- ❌ 忠实地理解用户所提出的需求，不要自主添加其他功能
- ❌ 不要跳过风险评估环节
- ❌ 不要忽视技术栈兼容性问题
- ❌ 不要引入未经验证的依赖

## 实施检查点

### 开始前检查
- [ ] 技术栈已识别并确认
- [ ] 依赖版本已检查
- [ ] 风险已识别并有规避方案
- [ ] 回滚计划已准备

### 完成后检查
- [ ] 所有验证循环通过
- [ ] 文档已更新
- [ ] 代码已审查
- [ ] 无技术债务遗留