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

P01_errlens_app — 架构设计

整体架构

┌──────────────────────────────────────────────────────────────┐
│                     小程序客户端 (Taro + React)                │
│                                                              │
│  ┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │  首页  │ │ 拍照录入  │ │ 错题列表  │ │  我的    │          │
│  └───┬────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘          │
│      │           │            │            │                │
│  ┌───┴───────────┴────────────┴────────────┴─────┐          │
│  │            组件库 (shadcn/ui Taro 适配)         │          │
│  └──────────────────────┬───────────────────────┘          │
│                         │                                   │
│  ┌──────────────────────┴───────────────────────┐          │
│  │           状态管理 (Zustand)                   │          │
│  │   auth / error-item / capture / ai-analysis   │          │
│  └──────────────────────┬───────────────────────┘          │
│                         │                                   │
│  ┌──────────────────────┴───────────────────────┐          │
│  │           Network 层 (API 封装 + JWT)         │          │
│  └──────────────────────┬───────────────────────┘          │
└─────────────────────────┼──────────────────────────────────┘
                          │ HTTPS
                          ▼
┌──────────────────────────────────────────────────────────────┐
│                   后端服务 (NestJS)                           │
│                                                              │
│  ┌────────┐ ┌────────┐ ┌──────────┐ ┌────────┐              │
│  │ 用户模块│ │ 错题模块│ │ AI 分析   │ │ 上传    │              │
│  └───┬────┘ └───┬────┘ └────┬─────┘ └───┬────┘              │
│      │          │           │            │                   │
│  ┌───┴──────────┴───────────┴────────────┴─────┐            │
│  │              Service 层                      │            │
│  └──────────────────────┬───────────────────────┘           │
│                         │                                   │
│  ┌──────────────────────┴───────────────────────┐          │
│  │          数据层 (Drizzle ORM + PostgreSQL)     │          │
│  └──────────────────────┬───────────────────────┘          │
└─────────────────────────┼──────────────────────────────────┘
                          │
              ┌───────────┴───────────┐
              ▼                       ▼
    ┌─────────────────┐    ┌─────────────────┐
    │   PostgreSQL     │    │   S3 兼容存储    │
    │   (Supabase)     │    │   (错题图片)     │
    └─────────────────┘    └─────────────────┘

目录结构

P01_errlens_app/
├── src/                          # 前端源码 (Taro)
│   ├── app.config.ts             # Taro 应用配置
│   ├── app.tsx                   # 根组件
│   ├── app.css                   # 全局样式 (Tailwind)
│   ├── index.html                # H5 入口
│   │
│   ├── components/               # 组件
│   │   ├── ui/                   # shadcn/ui 组件库 (~50 个)
│   │   └── business/             # 业务组件
│   │       ├── error-card/       # 错题卡片
│   │       ├── knowledge-tag/    # 知识点标签
│   │       └── analysis-chart/   # 分析图表
│   │
│   ├── pages/                    # 页面
│   │   ├── index/                # 首页
│   │   ├── auth/login/           # 登录
│   │   ├── capture/              # 拍照录入
│   │   │   ├── index/            # 拍照页
│   │   │   └── review/           # 识别确认页
│   │   ├── error-list/           # 错题列表
│   │   ├── error-detail/         # 错题详情
│   │   ├── weak-points/          # 薄弱点
│   │   └── profile/              # 个人中心
│   │
│   ├── stores/                   # Zustand 状态
│   │   ├── auth.store.ts
│   │   ├── error-item.store.ts
│   │   ├── capture.store.ts      # 拍照流程状态机
│   │   └── ai-analysis.store.ts
│   │
│   ├── lib/                      # 工具库
│   │   ├── utils.ts
│   │   ├── platform.ts
│   │   ├── measure.ts
│   │   └── hooks/
│   │
│   ├── presets/                  # 预设配置
│   │   ├── index.tsx
│   │   ├── env.ts
│   │   └── h5-*.tsx
│   │
│   └── network.ts                # API 请求封装
│
├── server/                       # 后端源码 (NestJS)
│   └── src/
│       ├── main.ts               # 启动入口
│       ├── app.module.ts         # 根模块
│       ├── app.controller.ts     # 根控制器
│       ├── db/
│       │   └── schema.ts         # Drizzle Schema
│       ├── modules/
│       │   ├── auth/             # 鉴权模块
│       │   ├── user/             # 用户模块
│       │   ├── error-item/       # 错题模块
│       │   ├── ai/               # AI 分析模块
│       │   ├── subject/          # 学科模块
│       │   └── upload/           # 文件上传
│       └── common/
│           ├── guards/           # JWT Guard
│           ├── interceptors/     # HTTP 状态拦截器
│           └── filters/          # 异常过滤器
│
├── tests/                        # 测试
│   ├── unit/                     # 单元测试
│   │   ├── components/
│   │   └── lib/
│   ├── integration/              # 集成测试
│   └── e2e/                      # E2E 测试
│
├── docs/                         # 项目文档
├── package.json
├── tsconfig.json
├── babel.config.js
├── eslint.config.mjs
├── stylelint.config.mjs
├── project.config.json           # 微信小程序配置
└── ENVIRONMENT.md

核心流程

拍照录入流程

[拍照页] → 拍照/选图
    → [预览页] 确认图片
    → [Upload] 上传 → S3 返回 URL
    → [AI Service] Coze SDK OCR + 知识点分类
    → [确认页] 展示识别结果，允许修正
    → [保存] 写入 ErrorItem → 跳转详情页

状态机 (capture.store)

IDLE → CAMERA → PREVIEW → UPLOADING → ANALYZING → REVIEW → SAVING → DONE
                      ↓              ↓           ↓         ↓
                    ERROR          ERROR       ERROR     ERROR
                                     └── 重试 ──┘

多端适配策略

场景	方案
拍照	微信: wx.chooseMedia, H5: input[type=file]
图片预览	微信: wx.previewImage, H5: dialog
登录	微信: wx.login → code2session, H5: 扫码
原生组件	平台检测 + 条件渲染

部署架构

开发环境

• 前端 H5: port 5000 (Vite dev server)
• 后端: port 3000 (NestJS)
• 数据库: Supabase 开发实例

生产环境

• 微信小程序: taro build --type weapp → 上传代码包
• 后端: Node.js 单实例 (Phase 3 容器化)
• 图片: S3/MinIO + CDN

---

文档版本: v0.1.0 | 基于: 系统架构 | 最后更新: 2026-05-26