tupingr
4083fadb2a
- 权限矩阵: RL/R/W/RW 四态替代 ✅/❌，三文件语义对齐 - 目录重构: server/config/types 移入 src/，projects/*/src/ 全覆盖 - 提示词库: 新增 code-style.md / doc-template.md / bug-report.md - 工作流: 8阶段→4阶段，新增 retry 循环 + escalation 升级规则 - 审核报告: reports/quality-reports/framework-review-2026-05-23.md
234 lines
3.8 KiB
Markdown
234 lines
3.8 KiB
Markdown
# 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 src/server
|
||
pnpm install
|
||
cd ../..
|
||
```
|
||
|
||
### 4. 配置环境变量
|
||
|
||
```bash
|
||
# 复制环境变量模板
|
||
cp .env.example .env
|
||
|
||
# 编辑 .env 文件，配置以下变量
|
||
```
|
||
|
||
**前端环境变量 (`.env`)**:
|
||
```bash
|
||
# 项目域名（可选，用于生产环境）
|
||
PROJECT_DOMAIN=
|
||
|
||
# API 基础路径
|
||
API_BASE_URL=/api
|
||
```
|
||
|
||
**后端环境变量 (`src/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 src/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 src/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
|