Planning-with-files 教程 8：实战开发型任务

教程概述

本教程将通过一个完整的功能开发案例，演示如何使用 Planning-with-files 管理开发型任务。

任务背景

你需要为博客系统实现一个评论功能。这是一个典型的开发型任务，需要：

数据库设计
API 实现
前端组件
测试验证

你将学到

✅ 开发型任务的阶段划分
✅ 错误追踪与解决
✅ 测试结果记录
✅ 任务完成验证

任务启动

Step 1：创建规划文件

/plan 为博客添加评论功能，支持用户登录后发表评论，评论需要审核后才能显示

AI 创建三个文件：

task_plan.md（初始版）：

# Task Plan: 博客评论功能

## Goal
为博客添加评论功能，支持登录用户发表评论，评论需要管理员审核后才能显示。

## Context
- 博客已有用户系统（GitHub OAuth）
- 文章模型已存在
- 需要后台管理界面审核评论

## Phases

### Phase 1: 需求分析与设计
- [ ] 确认评论数据模型
- [ ] 设计评论 API
- [ ] 确定审核流程
- **Status:** in_progress
- **Started:** 2026-03-26 09:00

### Phase 2: 数据库实现
- [ ] 创建评论表
- [ ] 设置外键约束
- [ ] 编写迁移脚本
- **Status:** pending

### Phase 3: 后端 API
- [ ] 评论 CRUD 接口
- [ ] 审核接口
- [ ] 权限验证
- **Status:** pending

### Phase 4: 前端实现
- [ ] 评论列表组件
- [ ] 评论表单组件
- [ ] 审核管理界面
- **Status:** pending

### Phase 5: 测试与部署
- [ ] 单元测试
- [ ] 集成测试
- [ ] 部署上线
- **Status:** pending

## Decisions
| Decision | Rationale | Date |
|----------|-----------|------|
| - | - | - |

## Errors Encountered
| Error | Attempt | Resolution | Date |
|-------|---------|------------|------|
| - | - | - | - |

Phase 1：需求分析与设计

需求确认

AI 询问细节：

在设计评论系统之前，需要确认一些细节：

1. 评论层级：支持嵌套回复吗？
2. 评论内容：支持 Markdown 吗？
3. 审核方式：人工审核还是自动过滤？
4. 通知机制：评论后需要通知作者吗？

你回答：

1. 支持一层回复（评论 -> 回复）
2. 支持 Markdown
3. 人工审核
4. 暂不需要通知

更新 findings.md

# Findings: 博客评论功能

## Research Findings

### 需求确认

**评论结构**:
- 支持一层嵌套回复
- 支持 Markdown 格式
- 需要人工审核

**评论状态流转**:

待审核 → 已通过 / 已拒绝


**权限要求**:
- 登录用户可发表评论
- 管理员可审核评论
- 作者可删除自己文章的评论

### 数据模型设计

```mermaid
erDiagram
    ARTICLE ||--o{ COMMENT : has
    USER ||--o{ COMMENT : writes
    COMMENT ||--o{ REPLY : has

    ARTICLE {
        bigint id PK
        string title
        string content
    }

    USER {
        bigint id PK
        string email
        string name
    }

    COMMENT {
        bigint id PK
        bigint article_id FK
        bigint user_id FK
        bigint parent_id FK
        text content
        string status
        timestamp created_at
    }

API 设计

接口	方法	权限	描述
/api/articles/:id/comments	GET	公开	获取文章评论
/api/articles/:id/comments	POST	登录	发表评论
/api/comments/:id	DELETE	作者/管理员	删除评论
/api/admin/comments	GET	管理员	获取待审核列表
/api/admin/comments/:id/approve	POST	管理员	通过审核
/api/admin/comments/:id/reject	POST	管理员	拒绝评论


### 完成 Phase 1

```markdown
### Phase 1: 需求分析与设计
- [x] 确认评论数据模型
- [x] 设计评论 API
- [x] 确定审核流程
- **Status:** complete
- **Started:** 2026-03-26 09:00
- **Completed:** 2026-03-26 09:45

Phase 2：数据库实现

创建迁移脚本

AI 开始实现：

让我创建评论表的迁移脚本...

[Write migrations/20260326_add_comments.sql]

第一次错误

执行迁移失败！

错误: ERROR: relation "users" does not exist

错误追踪

更新 task_plan.md：

## Errors Encountered
| Error | Attempt | Resolution | Date |
|-------|---------|------------|------|
| 迁移失败: users 表不存在 | 1 | 检查表名，发现是 `user` 而非 `users` | 2026-03-26 |

更新 progress.md：

## Error Log
| Time | Error | Resolution | Status |
|------|-------|------------|--------|
| 10:15 | 迁移失败: users 表不存在 | 修正外键引用为 `user` | ✅ 已解决 |

修复并重试

-- 修正后
CREATE TABLE comment (
    id BIGSERIAL PRIMARY KEY,
    article_id BIGINT NOT NULL REFERENCES article(id),
    user_id BIGINT NOT NULL REFERENCES "user"(id),  -- 修正
    parent_id BIGINT REFERENCES comment(id),
    content TEXT NOT NULL,
    status VARCHAR(20) DEFAULT 'pending',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

第二次错误

执行迁移再次失败！

错误: ERROR: syntax error at or near "comment"

错误追踪

## Errors Encountered
| Error | Attempt | Resolution | Date |
|-------|---------|------------|------|
| 迁移失败: users 表不存在 | 1 | 修正外键引用为 `user` | 2026-03-26 |
| 迁移失败: comment 是保留字 | 1 | 使用双引号 `"comment"` | 2026-03-26 |

最终修复

CREATE TABLE "comment" (
    -- 使用双引号包裹保留字
);

完成 Phase 2

### Phase 2: 数据库实现
- [x] 创建评论表
- [x] 设置外键约束
- [x] 编写迁移脚本
- **Status:** complete
- **Started:** 2026-03-26 09:45
- **Completed:** 2026-03-26 10:30

Phase 3：后端 API

实现评论接口

[Write src/app/api/articles/[id]/comments/route.ts]
[Write src/app/api/comments/[id]/route.ts]

更新 findings.md

### API 实现细节

#### 获取评论列表
```typescript
// GET /api/articles/:id/comments
export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  const comments = await prisma.comment.findMany({
    where: {
      articleId: parseInt(params.id),
      status: 'approved',
      parentId: null,
    },
    include: {
      user: { select: { name: true, avatar: true } },
      replies: {
        include: {
          user: { select: { name: true, avatar: true } },
        },
      },
    },
    orderBy: { createdAt: 'desc' },
  });
  return Response.json(comments);
}

发表评论

// POST /api/articles/:id/comments
export async function POST(
  request: Request,
  { params }: { params: { id: string } }
) {
  const session = await getServerSession(authOptions);
  if (!session) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const { content, parentId } = await request.json();

  const comment = await prisma.comment.create({
    data: {
      articleId: parseInt(params.id),
      userId: session.user.id,
      parentId,
      content,
      status: 'pending',
    },
  });

  return Response.json(comment);
}


### 权限验证实现

[Write src/lib/auth-utils.ts]


### 完成 Phase 3

```markdown
### Phase 3: 后端 API
- [x] 评论 CRUD 接口
- [x] 审核接口
- [x] 权限验证
- **Status:** complete
- **Started:** 2026-03-26 10:30
- **Completed:** 2026-03-26 12:00

Phase 4：前端实现

评论组件

[Write src/components/CommentList.tsx]
[Write src/components/CommentForm.tsx]

更新 progress.md

## Session Log
| Time | Action | Files Modified |
|------|--------|----------------|
| 14:00 | 创建评论列表组件 | src/components/CommentList.tsx |
| 14:30 | 创建评论表单组件 | src/components/CommentForm.tsx |
| 15:00 | 实现审核管理界面 | src/app/admin/comments/page.tsx |
| 15:30 | 集成到文章详情页 | src/app/articles/[id]/page.tsx |

第三次错误

前端构建失败！

Error: 'useSession' is not exported from 'next-auth/react'

错误追踪

## Errors Encountered
| Error | Attempt | Resolution | Date |
|-------|---------|------------|------|
| 迁移失败: users 表不存在 | 1 | 修正外键引用为 `user` | 2026-03-26 |
| 迁移失败: comment 是保留字 | 1 | 使用双引号 | 2026-03-26 |
| useSession 导入错误 | 1 | next-auth v5 使用 `useSession` from 'next-auth' | 2026-03-26 |

修复

// 修正导入
import { useSession } from 'next-auth';  // 而非 'next-auth/react'

完成 Phase 4

### Phase 4: 前端实现
- [x] 评论列表组件
- [x] 评论表单组件
- [x] 审核管理界面
- **Status:** complete
- **Started:** 2026-03-26 13:00
- **Completed:** 2026-03-26 16:00

Phase 5：测试与部署

单元测试

[Write tests/comment.test.ts]

更新 progress.md：

## Test Results

### Unit Tests (2026-03-26 16:30)
| Suite | Tests | Passed | Failed | Coverage |
|-------|-------|--------|--------|----------|
| comment.test.ts | 15 | 15 | 0 | 88% |
| auth.test.ts | 8 | 8 | 0 | 92% |

### Integration Tests (2026-03-26 17:00)
| Endpoint | Status | Response Time |
|----------|--------|---------------|
| GET /api/articles/1/comments | ✅ Pass | 45ms |
| POST /api/articles/1/comments | ✅ Pass | 120ms |
| DELETE /api/comments/1 | ✅ Pass | 35ms |
| POST /api/admin/comments/1/approve | ✅ Pass | 50ms |

部署

[Deploy to Vercel]

完成 Phase 5

### Phase 5: 测试与部署
- [x] 单元测试
- [x] 集成测试
- [x] 部署上线
- **Status:** complete
- **Started:** 2026-03-26 16:00
- **Completed:** 2026-03-26 17:30

最终文件状态

task_plan.md

# Task Plan: 博客评论功能

## Goal
为博客添加评论功能，支持登录用户发表评论，评论需要管理员审核后才能显示。

## Phases

### Phase 1: 需求分析与设计
- [x] 确认评论数据模型
- [x] 设计评论 API
- [x] 确定审核流程
- **Status:** complete
- **Started:** 2026-03-26 09:00
- **Completed:** 2026-03-26 09:45

### Phase 2: 数据库实现
- [x] 创建评论表
- [x] 设置外键约束
- [x] 编写迁移脚本
- **Status:** complete
- **Started:** 2026-03-26 09:45
- **Completed:** 2026-03-26 10:30

### Phase 3: 后端 API
- [x] 评论 CRUD 接口
- [x] 审核接口
- [x] 权限验证
- **Status:** complete
- **Started:** 2026-03-26 10:30
- **Completed:** 2026-03-26 12:00

### Phase 4: 前端实现
- [x] 评论列表组件
- [x] 评论表单组件
- [x] 审核管理界面
- **Status:** complete
- **Started:** 2026-03-26 13:00
- **Completed:** 2026-03-26 16:00

### Phase 5: 测试与部署
- [x] 单元测试
- [x] 集成测试
- [x] 部署上线
- **Status:** complete
- **Started:** 2026-03-26 16:00
- **Completed:** 2026-03-26 17:30

## Decisions
| Decision | Rationale | Date |
|----------|-----------|------|
| 支持一层嵌套回复 | 简单实用，复杂度可控 | 2026-03-26 |
| 使用人工审核 | 避免垃圾评论，成本可接受 | 2026-03-26 |
| 评论表名使用双引号 | comment 是 SQL 保留字 | 2026-03-26 |

## Errors Encountered
| Error | Attempt | Resolution | Date |
|-------|---------|------------|------|
| 迁移失败: users 表不存在 | 1 | 修正外键引用为 `user` | 2026-03-26 |
| 迁移失败: comment 是保留字 | 1 | 使用双引号 `"comment"` | 2026-03-26 |
| useSession 导入错误 | 1 | next-auth v5 导入路径变化 | 2026-03-26 |

progress.md

# Progress: 博客评论功能

## Session Log
| Time | Action | Files Modified |
|------|--------|----------------|
| 09:00 | 创建规划文件 | task_plan.md, findings.md, progress.md |
| 09:30 | 设计数据模型 | findings.md |
| 09:45 | 完成 Phase 1 | task_plan.md |
| 10:00 | 创建迁移脚本 | migrations/20260326_add_comments.sql |
| 10:15 | 修复表名错误 | migrations/20260326_add_comments.sql |
| 10:30 | 完成 Phase 2 | task_plan.md |
| 11:00 | 实现评论 API | src/app/api/articles/[id]/comments/route.ts |
| 11:30 | 实现审核 API | src/app/api/admin/comments/route.ts |
| 12:00 | 完成 Phase 3 | task_plan.md |
| 14:00 | 评论列表组件 | src/components/CommentList.tsx |
| 14:30 | 评论表单组件 | src/components/CommentForm.tsx |
| 15:00 | 审核管理界面 | src/app/admin/comments/page.tsx |
| 15:30 | 修复 useSession 导入 | src/components/*.tsx |
| 16:00 | 完成 Phase 4 | task_plan.md |
| 16:30 | 单元测试 | tests/comment.test.ts |
| 17:00 | 集成测试 | - |
| 17:30 | 完成 Phase 5，部署上线 | task_plan.md |

## Test Results

### Unit Tests
| Suite | Tests | Passed | Failed | Coverage |
|-------|-------|--------|--------|----------|
| comment.test.ts | 15 | 15 | 0 | 88% |
| auth.test.ts | 8 | 8 | 0 | 92% |

### Integration Tests
| Endpoint | Status | Response Time |
|----------|--------|---------------|
| GET /api/articles/1/comments | ✅ | 45ms |
| POST /api/articles/1/comments | ✅ | 120ms |
| DELETE /api/comments/1 | ✅ | 35ms |
| POST /api/admin/comments/1/approve | ✅ | 50ms |

## Error Log
| Time | Error | Resolution | Status |
|------|-------|------------|--------|
| 10:15 | 迁移失败: users 表不存在 | 修正外键引用为 `user` | ✅ 已解决 |
| 10:20 | 迁移失败: comment 是保留字 | 使用双引号 `"comment"` | ✅ 已解决 |
| 15:30 | useSession 导入错误 | 修正为 `from 'next-auth'` | ✅ 已解决 |

## 5-Question Reboot Test
| Question | Answer |
|----------|--------|
| Where am I? | Phase 5，已完成 |
| Where am I going? | 所有阶段已完成 |
| What's the goal? | 博客评论功能，支持审核 |
| What have I learned? | SQL 保留字问题，next-auth v5 导入变化 |
| What have I done? | 数据库、API、前端、测试、部署 |

开发型任务最佳实践

1. 错误追踪闭环

每个错误都要：

记录到 task_plan.md（摘要）
记录到 progress.md（详情）
记录解决方案
更新状态为"已解决"

2. 测试驱动

在 Phase 5 运行测试后，更新 Test Results 表格。失败的测试要追踪修复。

3. 文件修改追踪

每次文件创建/修改都记录到 Session Log，便于回溯。

4. 阶段完成立即更新

完成阶段后立即更新 task_plan.md 状态，不要延迟。

5. 5-Question 验证

在声称完成前，验证能回答 5-Question Reboot Test。

系列导航：

教程概述

任务背景

你将学到

任务启动

Step 1：创建规划文件

Phase 1：需求分析与设计

需求确认

更新 findings.md

API 设计

Phase 2：数据库实现

创建迁移脚本

第一次错误

错误追踪

修复并重试

第二次错误

错误追踪

最终修复

完成 Phase 2

Phase 3：后端 API

实现评论接口

更新 findings.md

发表评论

Phase 4：前端实现

评论组件

更新 progress.md

第三次错误

错误追踪

修复

完成 Phase 4

Phase 5：测试与部署

单元测试

部署

完成 Phase 5

最终文件状态

task_plan.md

progress.md

开发型任务最佳实践

1. 错误追踪闭环

2. 测试驱动

3. 文件修改追踪

4. 阶段完成立即更新

5. 5-Question 验证

🍪 Cookie 使用通知

Cookie 偏好设置

必要 Cookie

分析 Cookie

广告 Cookie