需求文档设计

这个项目90%以上的代码都是由 cursor 完成，我在新建了项目以后，使用 DeepSeek-R1 帮我写项目的需求文档，这是我对 DeepSeek-R1 的要求：

使用golang作为后端，使用golang 的 echo 框架来编写API，使用gorm作为 orm，支持 sqlite和postgre 数据库。
使用react来写前端，使用 radix ui 库。
请注意，无论是前端还是后端，使用较新的库来开发，同时要确保各个组件都兼容。
这是一个文件快递柜项目，它允许用户通过简单的方式分享文件。这个网站的主要功能是可以上传文件或者分享文本，然后生成一个取件码，另外一个人访问这个网站，输入取件码就可以获取别人分享的文件。
还需要增加一个管理后台，路径为 admin，提供默认的管理员用户和密码。需要支持注册登陆，注册登陆以后可以查看自己的发件记录和取件记录。同时也支持匿名发送文件。
一般情况下，用户分享文件时，取件码是随机生成的，但是也需要支持自定义取件码，用户在分享文件时，可以自定义取件码。
前端和后端代码都放在同一个仓库里，使用 github action 作为 ci，要支持 docker 部署，因此需要提供 dockerfile 文件。

接下来是 DeepSeek-R1 给我的需求文档：

以下是根据您的需求整理的专业生产级Prompt，可用于指导AI生成符合要求的代码：

项目架构Prompt（文件快递柜系统）
<MARKDOWN>
# 项目需求规范

## 1. 项目类型
- 全栈Web应用（前后端分离架构）

## 2. 核心功能需求

### 后端模块
**2.1 文件管理模块**
- 行为描述：支持多格式文件上传（最大100MB）、加密存储、生成下载链接
- 输入：Multipart/form-data文件流
- 输出：JSON响应包含文件ID、大小、哈希值
- 规则：匿名用户最大文件50MB，注册用户100MB

**2.2 分享管理模块**
- 生成策略：随机6位字母数字取件码（可自定义）
- 有效期：默认7天（可配置）
- 访问限制：下载次数限制（默认5次）

**2.3 用户系统模块**
- JWT认证流程（访问/刷新令牌）
- 注册/登录（邮箱+密码）
- 历史记录查询：发送/接收记录分页展示

**2.4 管理后台模块**
- 功能：文件审计、用户管理、系统监控
- 访问路径：/admin
- 初始凭证：admin@example.com / admin123（强制首次修改）

### 前端模块
**3.1 文件上传组件**
- 拖拽上传支持
- 实时进度显示
- 取件码生成面板（随机/自定义切换）

**3.2 文件下载组件**
- 取件码验证表单
- 文件预览支持（文本/图片）
- 下载次数展示

## 3. 技术栈规范

### 后端（Go）
- Runtime: Go 1.21+
- Web框架: Echo v4
- ORM: Gorm v1.25+
- 数据库: PostgreSQL 15 / SQLite3（开发环境）
- 依赖管理: Go Modules

### 前端（React）
- React 18+（TypeScript）
- 状态管理: Zustand
- UI组件库: Radix UI + Tailwind CSS
- 构建工具: Vite 4+

### 基础设施
- 容器化: Docker 23.0+（多阶段构建）
- CI/CD: GitHub Actions（包含测试/构建/部署流程）
- 部署配置: docker-compose.prod.yml

## 4. 架构要求

### 后端架构
- 分层结构：
├── api         // 路由层
├── service     // 业务逻辑
├── model       // 数据模型
├── storage     // 文件存储抽象
└── middleware  // 认证/限流等中间件

- 数据库设计：
```sql
CREATE TABLE files (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  storage_path VARCHAR(255) NOT NULL,
  hash VARCHAR(64) NOT NULL,
  expires_at TIMESTAMPTZ
);
前端架构
功能模块化：
src/
 ├── features/
 │    ├── file-upload
 │    └── file-download
 ├── lib/
 │    └── api-client  // 类型安全的API客户端
 └── admin/
5. 非功能性需求
性能要求：

API响应时间 < 500ms（P99）
并发上传支持：50+（通过连接池实现）
安全性：

文件存储加密（AES-256）
密码哈希（bcrypt cost=12）
JWT签名算法：ES256
可靠性：

数据库事务处理文件操作
文件完整性校验（SHA-256）
6. 接口规范
REST API 设计
<TYPESCRIPT>
// 文件上传响应
interface FileResponse {
  id: string;
  code: string; // 取件码
  expiresAt: string;
  downloadCount: number;
}

// 错误响应
interface ErrorResponse {
  code: "INVALID_CODE" | "FILE_EXPIRED";
  message: string;
}
7. 开发规范
代码质量
Go测试覆盖率 > 80%
ESLint严格模式
提交信息遵循Conventional Commits
容器化配置
<DOCKERFILE>
# 后端Dockerfile示例
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.mod ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /server

FROM alpine:latest
COPY --from=builder /server /server
EXPOSE 8080
CMD ["/server"]
8. 特别注意事项
数据库兼容性：

使用Gorm的方言配置实现SQLite/PostgreSQL切换
通过环境变量注入连接字符串
文件存储策略：

开发环境：本地文件系统
生产环境：配置S3兼容存储（预留接口）
管理员面板保护：

会话校验双重验证（JWT + IP白名单）
敏感操作审计日志
版本兼容性保障：

Go版本通过go.mod固定
前端依赖使用精确版本锁定

请将以上prompt提供给Cursor，配合以下建议使用效果更佳：

1. 分模块生成代码时使用上下文记忆功能
2. 数据库迁移文件建议使用gorm的AutoMigrate结合手动调整
3. 前端API客户端推荐使用Zod进行响应验证
4. 文件上传建议分片处理（超过50MB时）
5. 安全加固建议添加速率限制中间件

开发调试

在我的使用中，我发现使用AI，在它能获取到比较准确的反馈时，它的修改效果就会比较好，比如代码生成。但是在它不能获取准确反馈时，它的使用效果就很差，比如项目部署。 我将上述需求文档扔给 cursor，使用 agent 模式开始开发，cursor 自己一个人在那里自问自答开发了大概一个多小时。在代码生成完成以后，cursor 自己会尝试去调试，但是目前cursor在部署项目的时候问题还是比较多，因此当它尝试部署后端服务时，陷入了死胡同。 一开始的时候我都没注意，我在刷抖音，让它自己写代码，后来发现它一直在尝试重复部署，原本我是想尝试全程由AI来开发这个项目，但是这时候它陷入困境了，于是我就接手过来处理后端服务部署的问题。 实际上部署后端服务陷入死胡同的问题非常非常简单，我的项目前后端放在同一个仓库下，使用 backend 和 frontend 文件夹来进行区分，cursor默认在根目录，它一直找不到 main.go 文件入口，紧接着它就尝试在根目录生成 main.go，我一看这要坏事，就赶紧把它叫停，手动把服务启动起来。当然我手动尝试启动的时候，代码本身也出现了报错，但是基本都是小问题，把错误信息交给 cursor，它很快就能定位到错误并解决问题。 部署前端服务也是一样，AI 生成代码速度很快，功能开发的很快，但是它被困在前端服务启动这一步，cursor不停的尝试使用 npm run dev ,很多时候都是路径不对，又或者端口已经被占用（它自己会重复启动很多次，端口被占用就会换端口继续尝试），这导致我电脑启动了一堆的 node 进程。于是这里也由我接管过来，将前端开发环境也部署好，再让 cursor 继续。 前后端都部署完成后，首页还是白屏，这时候把浏览器 console 中的报错交给 cursor，它很快就能把问题解决，功能也基本能正常使用。 最后在本地调试好，需要打包成为镜像，放在云上部署，这时候cursor的效果又开始变的比较差了，它靠自己的知识生成了流水线，生成了 Dockerfile，生成了 docker-compose.yml，但是它自己没有办法去获得反馈，它不知道生成出来的东西实际效果是怎样的。这中间的过程还是挺曲折的，折腾到最后，CI/CD这一块基本都是我接手过来，一步一步指导它要怎么做，这时候它才能比较好的完成任务。

总结

cursor辅助开发确实非常强，在代码生成方面，给它明确的需求，它能非常快的完成你的要求，但是它擅长的场景需要它能够获得准确反馈才行，比如代码生成，文字生成，在生成完成以后，它可以准确的知道自己生成的效果，这样它才能知道怎么修改。在它不能获得准确反馈时，AI生成的效果就会大打折扣，它不知道是什么情况，只能靠真人给它描述现状，但是沟通的过程中，AI很容易理解有偏差，导致它给出的解决方案也不尽人意。

---

原文链接 (opens new window)