Skip to Content
技术文档开发指南开发指南

开发指南

本指南帮助开发者快速上手智能采购意图平台的开发工作，包括环境搭建、技术栈介绍、开发流程和最佳实践。

技术栈

前端

  • 框架：Next.js 15 (React 19)
  • 语言：TypeScript
  • 样式：TailwindCSS
  • 组件库：shadcn/ui
  • 状态管理：React Context / Server Components
  • 表单：React Hook Form + Zod
  • 路由：Next.js App Router

后端

  • 框架：NestJS
  • 语言：TypeScript
  • 数据库：PostgreSQL 14+
  • ORM：Prisma
  • 认证：JWT + HMAC-SHA256
  • API 风格：RESTful

基础设施

  • monorepo 管理：Turborepo
  • 包管理器：pnpm
  • 代码质量：Ultracite (Biome)
  • 容器化：Docker + Docker Compose
  • CI/CD：GitHub Actions

AI 与自动化

  • AI 模型：阿里通义千问-VL Plus
  • 浏览器自动化：Browser-Use + Playwright
  • 任务调度：BullMQ + Redis

项目结构

procure/
├── apps/
│   ├── admin/          # 管理后台（Next.js）
│   ├── api/            # API 服务（NestJS）
│   └── doc/            # 文档站点（Nextra）
├── packages/
│   ├── db/             # 数据库层（Prisma）
│   ├── services/       # 共享业务逻辑
│   ├── ui/             # UI 组件库
│   └── typescript-config/  # TS 配置
└── scripts/            # 工具脚本

快速开始

前置要求

  • Node.js：22+
  • pnpm：10.4+
  • PostgreSQL：14+
  • Docker：最新版（可选）

初始化项目

# 1. 克隆仓库
git clone <repository-url>
cd procure
 
# 2. 安装依赖
pnpm install
 
# 3. 配置环境变量
cp packages/db/.env.example packages/db/.env
cp apps/admin/.env.example apps/admin/.env
cp apps/api/.env.example apps/api/.env
 
# 编辑 .env 文件，填入实际配置

数据库设置

# 生成 Prisma Client
pnpm db:generate
 
# 推送数据库 schema（开发环境）
pnpm db:push
 
# 查看数据库（可选）
pnpm db:studio

启动开发服务器

# 启动所有服务
pnpm dev
 
# 或单独启动
pnpm --filter @procure/admin dev    # 管理后台
pnpm --filter @procure/api dev      # API 服务
pnpm --filter @procure/doc dev      # 文档站点

访问：

开发流程

1. 创建功能分支

# 基于 develop 创建功能分支
git checkout develop
git pull origin develop
git checkout -b feature/new-feature

2. 开发与测试

# 启动开发服务器
pnpm dev
 
# 监听文件变化，自动重启
# Next.js 和 NestJS 都支持 HMR

3. 代码质量检查

# 自动修复代码格式和问题
pnpm fix
 
# 检查代码质量（不修改文件）
pnpm check
 
# 诊断配置
pnpm dlx ultracite doctor

4. 提交代码

遵循 Conventional Commits  规范：

git add .
git commit -m "feat: add new feature"
git commit -m "fix: resolve issue with..."
git commit -m "docs: update README"

Commit 类型：

  • feat: - 新功能
  • fix: - Bug 修复
  • docs: - 文档更新
  • style: - 代码格式（不影响功能）
  • refactor: - 重构
  • test: - 测试相关
  • chore: - 构建/工具相关

5. 推送并创建 PR

# 推送到远程
git push origin feature/new-feature
 
# 在 GitHub 创建 Pull Request
# 目标分支：develop

开发工具

VS Code 扩展推荐

{
  "recommendations": [
    "biomejs.biome",          // 代码格式化和检查
    "prisma.prisma",          // Prisma 支持
    "bradlc.vscode-tailwindcss",  // TailwindCSS 智能提示
    "dbaeumer.vscode-eslint", // ESLint
    "eamodio.gitlens"         // Git 增强
  ]
}

浏览器扩展

  • React Developer Tools - React 组件调试
  • Redux DevTools - 状态调试（如需要）

核心模块开发

数据库开发

使用 Prisma 进行数据库开发：

  • Schema 设计和迁移
  • 查询优化
  • 种子数据管理

服务开发

开发后端服务和 API：

  • NestJS 服务架构
  • RESTful API 设计
  • JWT 认证实现

前端开发

前端应用开发：

  • Next.js 页面开发
  • shadcn/ui 组件使用
  • 表单处理和验证

测试

编写和运行测试：

  • 单元测试
  • 集成测试
  • API 测试

部署与运维

Docker 开发

使用 Docker 进行本地开发和部署：

  • 多容器编排
  • 环境隔离
  • 镜像构建

CI/CD

持续集成和部署：

  • GitHub Actions 配置
  • 自动化测试
  • 自动部署

部署指南

生产环境部署：

  • 构建优化
  • 环境变量管理
  • 数据库迁移

最佳实践

代码规范

  1. 类型安全优先 - 充分利用 TypeScript 的类型系统
  2. 组件化开发 - 保持组件小而专注
  3. 避免过度抽象 - 在需要的时候才抽象
  4. 错误处理 - 使用 try-catch 捕获异步错误
  5. 日志记录 - 关键操作记录详细日志

性能优化

  1. 数据库查询优化 - 使用索引，避免 N+1 查询
  2. React 性能 - 使用 useMemo, useCallback, React.memo
  3. Next.js 优化 - Server Components, 图片优化, 代码分割
  4. API 优化 - 缓存、分页、字段过滤

查看详细的性能优化指南。

安全实践

  1. 环境变量管理 - 敏感信息不提交到代码库
  2. 输入验证 - 使用 Zod 验证所有用户输入
  3. SQL 注入防护 - 使用 Prisma 参数化查询
  4. XSS 防护 - 避免使用 dangerouslySetInnerHTML
  5. CSRF 防护 - API 使用 token 验证

常见问题

环境变量未定义

错误：Invalid environment variables

解决方案：

  1. 检查对应应用的 .env 文件是否存在
  2. 确保变量名拼写正确
  3. 重启开发服务器

数据库连接失败

错误：Can't reach database server

解决方案：

  1. 确保 PostgreSQL 服务运行
  2. 检查 DATABASE_URL 配置
  3. 验证数据库用户权限

端口被占用

错误：Port 3000 is already in use

解决方案：

# 查找占用端口的进程
lsof -i :3000
 
# 杀死进程
kill -9 <PID>
 
# 或使用其他端口
pnpm dev -- --port 3003

Prisma Client 不同步

错误：Type 'xxx' does not exist

解决方案：

# 重新生成 Prisma Client
pnpm db:generate
 
# 如果还不行，清除缓存
rm -rf node_modules/.pnpm
pnpm install

相关资源

框架文档

工具文档

学习资源

准备好了吗？ 从快速开始开始您的开发之旅！

技术细节快速开始