# P01_errlens_app - 环境准备指南

## 项目信息

- **项目名称**: ErrLens 小程序应用
- **技术栈**: Taro 4 + React 18 + NestJS
- **支持平台**: 微信小程序、抖音小程序、H5

---

## 环境要求

### 基础环境

| 依赖项 | 版本要求 | 说明 |
|--------|---------|------|
| Node.js | >= 20.x | 推荐使用 nvm 管理 |
| pnpm | >= 9.0.0 | 包管理器 |
| Git | 最新版 | 代码版本控制 |

### 数据库（后端服务）

| 依赖项 | 版本要求 | 说明 |
|--------|---------|------|
| PostgreSQL | 15+ | 主数据库 |
| Supabase | 可选 | 云端数据库替代方案 |

### 开发工具（可选）

| 工具 | 说明 |
|------|------|
| VSCode | 推荐编辑器 |
| 微信开发者工具 | 微信小程序调试 |
| 抖音开发者工具 | 抖音小程序调试 |

---

## 安装步骤

### 1. 克隆项目

```bash
git clone <repository-url>
cd errlens-project/projects/P01_errlens_app
```

### 2. 安装前端依赖

```bash
# 使用 pnpm（推荐）
pnpm install

# 或使用 npm
npm install
```

### 3. 安装后端依赖

```bash
cd server
pnpm install
cd ..
```

### 4. 配置环境变量

```bash
# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，配置以下变量
```

**前端环境变量 (`.env`)**:
```bash
# 项目域名（可选，用于生产环境）
PROJECT_DOMAIN=

# API 基础路径
API_BASE_URL=/api
```

**后端环境变量 (`server/.env`)**:
```bash
# 服务端口
PORT=3000

# 数据库连接
DATABASE_URL=postgresql://user:password@localhost:5432/errlens

# Supabase（可选）
SUPABASE_URL=
SUPABASE_KEY=

# JWT 密钥
JWT_SECRET=your-secret-key
```

---

## 开发命令

### 前端开发

```bash
# 启动前端开发服务器（H5）
pnpm dev:web

# 启动微信小程序开发模式
pnpm dev:weapp

# 启动抖音小程序开发模式
pnpm dev:tt
```

### 后端开发

```bash
# 启动后端开发服务器
pnpm dev:server

# 或
cd server
pnpm dev
```

### 完整开发模式

```bash
# 同时启动前端和后端
pnpm dev
```

### 构建命令

```bash
# 构建所有平台
pnpm build

# 仅构建前端
pnpm build:web
pnpm build:weapp
pnpm build:tt

# 仅构建后端
pnpm build:server
```

### 代码检查

```bash
# 运行 ESLint
pnpm lint

# 运行 TypeScript 检查
pnpm tsc

# 运行完整验证
pnpm validate
```

---

## 数据库迁移

### 开发环境

```bash
cd server

# 运行迁移
pnpm drizzle-kit migrate

# 或生成 SQL
pnpm drizzle-kit generate
```

---

## 项目结构

```
P01_errlens_app/
├── src/                    # 前端源码
│   ├── components/        # UI 组件
│   ├── pages/             # 页面
│   ├── lib/               # 工具库
│   └── network.ts         # API 封装
│
├── server/                 # 后端源码 (NestJS)
│   └── src/
│
├── tests/                  # 测试代码
│   ├── unit/             # 单元测试
│   ├── integration/      # 集成测试
│   └── e2e/              # E2E 测试
│
├── docs/                  # 项目文档
│   ├── 01_需求概要.md
│   ├── 02_架构设计.md
│   └── 03_接口定义.md
│
└── config/                # 构建配置
```

---

## 常见问题

### Q: pnpm install 失败？
A: 确保 Node.js >= 20.x，pnpm >= 9.0.0

### Q: H5 开发正常，但小程序报错？
A: 检查是否使用了不支持的 API 或组件，参考跨端兼容性文档

### Q: 后端服务启动失败？
A: 检查 PostgreSQL 是否运行，环境变量是否正确配置

---

## 端口说明

| 服务 | 端口 | 说明 |
|------|------|------|
| 前端 H5 | 5000 | 开发服务器 |
| 后端 API | 3000 | NestJS 服务 |
| 微信开发者工具 | - | 自动加载 |
| 抖音开发者工具 | - | 自动加载 |

---

**文档版本**：v1.0.0
**最后更新**：2026-05-22