ai_soc_sw/projects/P01_errlens_app/docs/02_架构设计.md

# P01_errlens_app - 架构设计

## 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                        小程序客户端                          │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
│  │  首页   │  │  分析   │  │  历史   │  │  我的   │        │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
│       │            │            │            │             │
│  ┌────┴────────────┴────────────┴────────────┴────┐        │
│  │              组件库 (shadcn/ui)                  │        │
│  └────────────────────┬─────────────────────────┘        │
│                        │                                  │
│  ┌────────────────────┴─────────────────────────┐        │
│  │              状态管理 (Zustand)                 │        │
│  └────────────────────┬─────────────────────────┘        │
│                        │                                  │
│  ┌────────────────────┴─────────────────────────┐        │
│  │           Network 层 (API 封装)               │        │
│  └────────────────────┬─────────────────────────┘        │
└───────────────────────┼───────────────────────────────────┘
                        │ HTTP
                        ▼
┌───────────────────────────────────────────────────────────┐
│                      后端服务 (NestJS)                     │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
│  │ 用户模块 │  │ 分析模块 │  │ 历史模块 │  │ 系统模块 │        │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
│       │            │            │            │             │
│  ┌────┴────────────┴────────────┴────────────┴────┐        │
│  │              Service 层                         │        │
│  └────────────────────┬─────────────────────────┘        │
│                        │                                  │
│  ┌────────────────────┴─────────────────────────┐        │
│  │              数据层 (Drizzle ORM)             │        │
│  └────────────────────┬─────────────────────────┘        │
└───────────────────────┼───────────────────────────────────┘
                        │
                        ▼
              ┌─────────────────┐
              │   PostgreSQL    │
              │   Supabase      │
              └─────────────────┘
```

## 目录结构

```
P01_errlens_app/
├── src/                          # 前端源码
│   ├── app.config.ts             # Taro 应用配置
│   ├── app.tsx                   # 根组件
│   ├── app.css                   # 全局样式
│   ├── index.html                # H5 入口
│   │
│   ├── components/               # 组件
│   │   └── ui/                   # shadcn/ui 组件库
│   │       ├── button.tsx
│   │       ├── card.tsx
│   │       ├── dialog.tsx
│   │       └── ... (50+ 组件)
│   │
│   ├── pages/                    # 页面
│   │   └── index/                # 首页
│   │       ├── index.tsx
│   │       ├── index.config.ts
│   │       └── index.css
│   │
│   ├── lib/                      # 工具库
│   │   ├── utils.ts              # 通用工具
│   │   ├── platform.ts           # 平台检测
│   │   ├── measure.ts            # 尺寸测量
│   │   └── hooks/                # 自定义 Hooks
│   │
│   ├── presets/                  # 预设配置
│   │   ├── index.tsx
│   │   ├── env.ts
│   │   ├── h5-container.tsx
│   │   └── ...
│   │
│   └── network.ts                # API 请求封装
│
│   ├── server/                   # 后端源码 (NestJS)
│   │   ├── src/
│   │   │   ├── app.module.ts    # 根模块
│   │   │   ├── app.controller.ts# 根控制器
│   │   │   ├── app.service.ts   # 根服务
│   │   │   └── main.ts          # 入口文件
│   │   │
│   │   ├── nest-cli.json
│   │   ├── tsconfig.json
│   │   └── package.json
│   │
│   ├── config/                   # 构建配置
│   │   ├── index.ts             # 通用配置
│   │   ├── dev.ts               # 开发环境配置
│   │   └── prod.ts              # 生产环境配置
│   │
│   ├── types/                    # 类型定义
│   │   ├── global.d.ts
│   │   └── lucide.d.ts
│
├── tests/                        # 测试代码
│   ├── unit/                    # 单元测试
│   ├── integration/             # 集成测试
│   └── e2e/                    # E2E 测试
│
├── docs/                        # 项目文档
│   ├── 01_需求概要.md
│   ├── 02_架构设计.md
│   └── 03_接口定义.md
│
├── package.json                 # 前端依赖
├── tsconfig.json                # TypeScript 配置
├── babel.config.js              # Babel 配置
├── eslint.config.mjs           # ESLint 配置
├── stylelint.config.mjs        # Stylelint 配置
├── project.config.json         # 微信小程序配置
└── ENVIRONMENT.md               # 环境准备指南
```

## 核心模块设计

### 1. Network 层

```typescript
// src/network.ts
// API 请求封装，自动添加项目域名前缀
// 支持 request / uploadFile / downloadFile
```

**职责**：
- 统一处理 API 请求
- 自动添加域名和路径前缀
- 请求/响应日志打印
- 错误处理

### 2. 组件库

**位置**：`src/components/ui/`

**组件分类**：
- 基础组件：Button, Input, Badge, Avatar
- 布局组件：Card, Dialog, Drawer, Sheet
- 数据展示：Table, Progress, Skeleton
- 导航组件：Tabs, Breadcrumb
- 反馈组件：Toast, Alert, Tooltip

### 3. 状态管理

**方案**：Zustand

**特点**：
- 轻量级
- 无 Provider 嵌套
- TypeScript 友好

### 4. 后端模块

```
src/server/src/
├── controllers/     # 控制器
├── services/        # 业务逻辑
├── modules/         # NestJS 模块
├── entities/        # 数据实体
├── dto/             # 数据传输对象
└── interceptors/    # 拦截器
```

## 多端适配策略

### 平台检测

```typescript
import { Taro, ENV_TYPE } from '@tarojs/taro'

const isWeapp = Taro.getEnv() === ENV_TYPE.WEAPP    // 微信小程序
const isTT = Taro.getEnv() === ENV_TYPE.TT           // 抖音小程序
const isH5 = Taro.getEnv() === ENV_TYPE.WEB          // H5
```

### 跨端规则

| 场景 | 适配方案 |
|------|---------|
| Text 换行 | 添加 `block` 类 |
| Input 样式 | View 包裹，样式放 View |
| Fixed + Flex | 使用 inline style |
| 原生组件 | 平台检测 + 降级方案 |

## 部署架构

### 开发环境
- 前端：H5 端口 5000
- 后端：Node 端口 3000

### 生产环境
- 微信小程序：构建 weapp 包
- 抖音小程序：构建 tt 包
- H5：构建 web 静态资源

---

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