hwd32/ai_soc_sw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(phase): Phase 1 收尾 — 一鸡多吃 + Dev工作台初始化 + Phase 2启动

Browse Source 
- Phase 1 标记 100% 完成，Phase 2 标记 ACTIVE
- Dev AI 工作台重写：8个任务入队 + 依赖关系图
- 一鸡多吃：6篇对外分享文章（项目缘起/框架思路/阶段复盘/3篇决策故事）
- 新增 share-context Skill（内部文档→对外分享自动化）
- P01 文档同步更新（需求/架构/接口定义）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
tupingr
2026-05-26 12:01:04 +08:00
parent e3f4af9c0c
commit 5b428d0810
18 changed files with 1344 additions and 485 deletions
Download Patch File Download Diff File Expand all files Collapse all files
projects/P01_errlens_app/docs/01_需求概要.md
+54 -56
View File
@@ -1,21 +1,21 @@
# P01_errlens_app - 需求概要
# P01_errlens_app — 需求概要
## 项目概述
ErrLens 小程序应用是一个基于 **Taro 4 框架**开发的多端小程序项目，支持微信小程序、抖音小程序和 H5 平台。
ErrLens 小程序是一款面向中小学生的 **AI 错题本**，帮助学生拍照录入错题、自动归类分析、获得针对性练习推荐。
## 项目定位
- **产品类型**：AI 辅助编程工具的移动端入口
- **目标用户**：开发者、编程学习者、代码审查人员
- **核心价值**：随时随地访问 ErrLens 的代码错误检测和修复建议功能
- **产品类型**: AI 错题本（教育类微信小程序）
- **目标用户**: 中小学生（10-18 岁），以初中生为典型交互设计
- **核心价值**: 拍照录入 → AI 分析错误原因 → 识别薄弱知识点 → 推荐同类练习
## 技术栈
### 前端框架
| 技术 | 版本 | 说明 |
|------|------|------|
| Taro | 4.1.9 | 跨端开发框架 |
| Taro | 4.1.x | 跨端开发框架 |
| React | 18.x | UI 框架 |
| TypeScript | 5.x | 类型安全 |
| Tailwind CSS | 4.x | 原子化样式 |
@@ -25,84 +25,82 @@ ErrLens 小程序应用是一个基于 **Taro 4 框架**开发的多端小程序
| 技术 | 版本 | 说明 |
|------|------|------|
| NestJS | 10.x | Node.js 服务端框架 |
| Express | 5.x | HTTP 服务器 |
| PostgreSQL | 15+ | 关系数据库 |
| Drizzle ORM | 0.45.x | ORM 工具 |
### 集成服务
| 服务 | 说明 |
|------|------|
| Supabase | 数据库连接 |
| S3 兼容存储 | 文件存储 |
| Coze SDK | AI 能力集成 |
| Supabase | 数据库托管 |
| S3 兼容存储 | 错题图片存储 |
| Coze SDK | AI OCR + 知识点分类 + 错误诊断 |
| 微信开放平台 | 微信登录 + 小程序能力 |
## 核心功能模块
### 1. 首页模块
- [ ] 欢迎页面展示
- [ ] 功能快捷入口
- [ ] 最新动态/公告
### 1. 拍照录入模块
- [ ] 拍照/选图 → AI 识别题目文字、学科、知识点
- [ ] 识别结果展示 + 用户修正
- [ ] 正确答案录入（可选）
### 2. 代码分析模块
- [ ] 代码上传/粘贴
- [ ] 错误检测结果展示
- [ ] 修复建议生成
### 2. 错题管理模块
- [ ] 错题列表（按时间/学科/知识点/错误类型筛选）
- [ ] 错题详情（题目 + AI 分析 + 知识点标注）
- [ ] 错题编辑（修正 AI 识别结果）
### 3. 用户模块
- [ ] 用户登录/注册
### 3. AI 分析模块
- [ ] 单题错误诊断（知识点欠缺/粗心/审题偏差/概念混淆）
- [ ] 薄弱知识点汇总与排序
- [ ] 学习报告（周/月度趋势）
### 4. 用户模块
- [ ] 微信授权登录
- [ ] 年级和学科设置
- [ ] 个人中心
- [ ] 历史记录
### 4. 设置模块
- [ ] 主题切换
- [ ] 通知设置
- [ ] 关于我们
### 5. 练习推荐模块（P1）
- [ ] 基于薄弱点推荐同类题
- [ ] 自定义组题练习
## 页面结构
```
pages/
├── index/ # 首页
├── analyze/ # 代码分析
├── history/ # 历史记录
├── profile/ # 个人中心
└── settings/ # 设置页面
├── index/ # 首页（错题概览 + 快捷入口）
├── auth/
│ └── login/ # 微信授权登录
├── capture/ # 拍照录入
│ ├── index/ # 拍照页
│ └── review/ # 识别结果确认页
├── error-list/ # 错题列表
├── error-detail/ # 错题详情 + AI 分析
├── weak-points/ # 薄弱点分析
├── practice/ # 练习推荐 (P1)
└── profile/ # 个人中心
```
## 组件库
项目使用 **Taro 版 shadcn/ui** 组件库，位于 `src/components/ui/`：
| 组件类型 | 示例组件 |
|---------|---------|
| 基础组件 | Button, Input, Textarea |
| 布局组件 | Card, Dialog, Drawer, Sheet |
| 数据展示 | Table, Badge, Avatar |
| 导航组件 | Tabs, Breadcrumb |
| 反馈组件 | Toast, Alert, Progress |
## 多端支持
| 平台 | 状态 | 说明 |
|------|------|------|
| 微信小程序 | ✅ 支持 | 主流平台 |
| 抖音小程序 | ✅ 支持 | 字节系平台 |
| H5 | ✅ 支持 | Web 端预览 |
| 平台 | 状态 | 优先级 |
|------|------|--------|
| 微信小程序 | MVP 唯一平台 | P0 |
| 抖音小程序 | 按需适配 | P3 |
| H5 | 兜底+开发调试 | P2 |
## 用户体验目标
- **加载速度**：首屏加载 < 2s
- **交互流畅**：帧率 >= 60fps
- **跨端一致**：各端 UI 表现一致
- **离线可用**：支持本地缓存
- **录入效率**: 拍照到保存 < 30s（含 AI 识别 3-5s）
- **首屏加载**: < 2s
- **交互流畅**: 60fps，长列表使用虚拟列表
- **离线可用**: 图片本地缓存，网络恢复后上传
## 安全要求
- 用户数据加密存储
- API 请求鉴权
- 敏感信息脱敏
- 微信 OAuth 登录，不存储密码
- 用户数据严格隔离（API 鉴权）
- 图片上传使用签名 URL
- 敏感信息传输加密
---
**文档版本**：v1.0.0
**最后更新**：2026-05-22
**文档版本**: v0.1.0 | **基于**: [PRD.md](../../../docs/01_产品需求/PRD.md) | **最后更新**: 2026-05-26
projects/P01_errlens_app/docs/02_架构设计.md
+134 -161
View File
@@ -1,207 +1,180 @@
# P01_errlens_app - 架构设计
# P01_errlens_app — 架构设计
## 整体架构
```
┌─────────────────────────────────────────────────────────────┐
│ 小程序客户端 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 首页 │ │ 分析 │ │ 历史 │ │ 我的 │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ ┌────┴────────────┴────────────┴────────────┴────┐ │
│ │ 组件库 (shadcn/ui) │ │
│ └────────────────────┬─────────────────────────┘ │
│ │ │
│ ┌────────────────────┴─────────────────────────┐ │
│ │ 状态管理 (Zustand) │ │
│ └────────────────────┬─────────────────────────┘ │
│ │ │
│ ┌────────────────────┴─────────────────────────┐ │
│ │ Network 层 (API 封装) │ │
│ └────────────────────┬─────────────────────────┘ │
└───────────────────────┼───────────────────────────────────┘
│ HTTP
▼
┌───────────────────────────────────────────────────────────┐
│ 后端服务 (NestJS) │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 用户模块 │ │ 分析模块 │ │ 历史模块 │ │ 系统模块 │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ ┌────┴────────────┴────────────┴────────────┴────┐ │
│ │ Service 层 │ │
│ └────────────────────┬─────────────────────────┘ │
│ │ │
│ ┌────────────────────┴─────────────────────────┐ │
│ │ 数据层 (Drizzle ORM) │ │
│ └────────────────────┬─────────────────────────┘ │
└───────────────────────┼───────────────────────────────────┘
│
▼
┌─────────────────┐
│ PostgreSQL │
│ Supabase │
└─────────────────┘
┌──────────────────────────────────────────────────────────────┐
│ 小程序客户端 (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/ # 前端源码
├── src/ # 前端源码 (Taro)
│ ├── app.config.ts # Taro 应用配置
│ ├── app.tsx # 根组件
│ ├── app.css # 全局样式
│ ├── app.css # 全局样式 (Tailwind)
│ ├── index.html # H5 入口
│ │
│ ├── components/ # 组件
│ │ └── ui/ # shadcn/ui 组件库
│ │ ├── button.tsx
│ │ ├── card.tsx
│ │ ├── dialog.tsx
│ │ └── ... (50+ 组件)
│ │ ├── ui/ # shadcn/ui 组件库 (~50 个)
│ │ └── business/ # 业务组件
│ │ ├── error-card/ # 错题卡片
│ │ ├── knowledge-tag/ # 知识点标签
│ │ └── analysis-chart/ # 分析图表
│ │
│ ├── pages/ # 页面
│ │ └── index/ # 首页
│ │ ├── index.tsx
│ │ ├── index.config.ts
│ │ └── index.css
│ │ ├── 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/ # 自定义 Hooks
│ │ ├── utils.ts
│ │ ├── platform.ts
│ │ ├── measure.ts
│ │ └── hooks/
│ │
│ ├── presets/ # 预设配置
│ │ ├── index.tsx
│ │ ├── env.ts
│ │ ├── h5-container.tsx
│ │ └── ...
│ │ └── h5-*.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
├── 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/ # 单元测试
│ ├── integration/ # 集成测试
│ └── e2e/ # E2E 测试
├── tests/ # 测试
│ ├── unit/ # 单元测试
│ │ ├── components/
│ │ └── lib/
│ ├── 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 # 环境准备指南
├── docs/ # 项目文档
├── package.json
├── tsconfig.json
├── babel.config.js
├── eslint.config.mjs
├── stylelint.config.mjs
├── 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/ # 拦截器
[拍照页] → 拍照/选图
→ [预览页] 确认图片
→ [Upload] 上传 → S3 返回 URL
→ [AI Service] Coze SDK OCR + 知识点分类
→ [确认页] 展示识别结果，允许修正
→ [保存] 写入 ErrorItem → 跳转详情页
```
### 状态机 (capture.store)
```
IDLE → CAMERA → PREVIEW → UPLOADING → ANALYZING → REVIEW → SAVING → DONE
↓ ↓ ↓ ↓
ERROR ERROR ERROR ERROR
└── 重试 ──┘
```
## 多端适配策略
### 平台检测
```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 |
| 原生组件 | 平台检测 + 降级方案 |
| 场景 | 方案 |
|------|------|
| 拍照 | 微信: wx.chooseMedia, H5: input[type=file] |
| 图片预览 | 微信: wx.previewImage, H5: dialog |
| 登录 | 微信: wx.login → code2session, H5: 扫码 |
| 原生组件 | 平台检测 + 条件渲染 |
## 部署架构
### 开发环境
- 前端：H5 端口 5000
- 后端：Node 端口 3000
- 前端 H5: port 5000 (Vite dev server)
- 后端: port 3000 (NestJS)
- 数据库: Supabase 开发实例
### 生产环境
- 微信小程序：构建 weapp 包
- 抖音小程序：构建 tt 包
- H5：构建 web 静态资源
- 微信小程序: `taro build --type weapp` → 上传代码包
- 后端: Node.js 单实例 (Phase 3 容器化)
- 图片: S3/MinIO + CDN
---
**文档版本**：v1.0.0
**最后更新**：2026-05-22
**文档版本**: v0.1.0 | **基于**: [系统架构](../../../docs/02_系统架构/) | **最后更新**: 2026-05-26
projects/P01_errlens_app/docs/03_接口定义.md
+341 -177
View File
@@ -1,202 +1,170 @@
# P01_errlens_app - 接口定义
# P01_errlens_app — 接口定义
## 接口规范
### 基础信息
- **Base URL**: `/api`（开发环境通过 Vite Proxy 代理到 `http://localhost:3000/api`）
- **请求格式**: JSON
- **响应格式**: Envelope Pattern `{ code, msg, data }`
- **Base URL**: `/api`（开发环境通过 Vite Proxy 到 `http://localhost:3000/api`）
- **请求格式**: JSON（文件上传使用 multipart/form-data）
- **响应格式**: `{ code: number, msg: string, data: T | null }`
### 通用响应结构
```typescript
// 成功响应
{
code: 200,
msg: "success",
data: { ... }
}
// 成功
{ code: 200, msg: "success", data: { ... } }
// 错误响应
{
code: 400 | 401 | 403 | 404 | 500,
msg: "错误信息",
data: null
}
// 客户端错误
{ code: 400 | 401 | 403 | 404, msg: "错误描述", data: null }
// 服务端错误
{ code: 500, msg: "服务器内部错误", data: null }
```
### 鉴权
除登录接口外，所有 API 需在 Header 携带 JWT Token：
```
Authorization: Bearer <token>
```
---
## 用户模块
## 1. 鉴权模块
### 1. 用户登录
### 1.1 微信登录
```
POST /api/auth/login
```
**请求参数**：
**请求**:
```json
{
"email": "string",
"password": "string"
"code": "wx.login() 返回的 code"
}
```
**响应示例**：
**响应**:
```json
{
"code": 200,
"msg": "success",
"data": {
"token": "jwt_token_here",
"token": "jwt_token",
"user": {
"id": "uuid",
"email": "user@example.com",
"nickname": "用户名"
"nickname": "微信昵称",
"avatarUrl": "https://..."
}
}
}
```
### 1.2 刷新 Token
```
POST /api/auth/refresh
```
---
### 2. 用户注册
## 2. 用户模块
### 2.1 获取个人信息
```
POST /api/auth/register
GET /api/user/profile
```
**请求参数**：
```json
{
"email": "string",
"password": "string",
"nickname": "string"
}
```
**响应示例**：
**响应**:
```json
{
"code": 200,
"msg": "success",
"data": {
"id": "uuid",
"email": "user@example.com",
"nickname": "用户名"
"nickname": "微信昵称",
"avatarUrl": "https://...",
"grade": "初中二年级",
"subjects": ["数学", "英语"],
"createdAt": "2026-05-26T00:00:00Z"
}
}
```
### 2.2 更新个人信息
```
PATCH /api/user/profile
```
**请求**:
```json
{
"grade": "初中三年级",
"subjects": ["数学", "英语", "物理"]
}
```
---
### 3. 获取用户信息
## 3. 错题模块（核心）
### 3.1 创建错题
```
GET /api/users/profile
POST /api/error-items
```
**请求头**：
```
Authorization: Bearer <token>
**请求**:
```json
{
"imageUrl": "https://storage.example.com/errors/abc.png",
"thumbnailUrl": "https://storage.example.com/errors/abc_thumb.png",
"questionText": "已知二次函数 y = x² - 4x + 3，求顶点坐标...",
"wrongAnswer": "顶点坐标 (2, 1)",
"correctAnswer": "顶点坐标 (2, -1)",
"subjectId": 1,
"knowledgePointIds": [1021],
"errorType": "knowledge_gap",
"difficulty": "medium",
"note": ""
}
```
**响应示例**：
**响应**:
```json
{
"code": 200,
"msg": "success",
"data": {
"id": "uuid",
"email": "user@example.com",
"nickname": "用户名",
"avatar": "https://...",
"createdAt": "2026-05-22T00:00:00Z"
"createdAt": "2026-05-26T10:00:00Z"
}
}
```
---
## 代码分析模块
### 1. 上传代码分析
### 3.2 查询错题列表
```
POST /api/analyze
GET /api/error-items?page=1&pageSize=20&subjectId=1&errorType=knowledge_gap&keyword=二次函数&sort=createdAt&order=desc
```
**请求头**：
```
Authorization: Bearer <token>
```
**查询参数**:
**请求参数**：
```json
{
"code": "string",
"language": "javascript | python | typescript | ..."
}
```
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认 1 |
| pageSize | int | 否 | 每页条数，默认 20，最大 50 |
| subjectId | int | 否 | 学科筛选 |
| errorType | string | 否 | 错误类型筛选 |
| knowledgePointId | int | 否 | 知识点筛选 |
| keyword | string | 否 | 题目文本搜索 |
| sort | string | 否 | 排序字段: createdAt/updatedAt |
| order | string | 否 | asc/desc，默认 desc |
**响应示例**：
```json
{
"code": 200,
"msg": "success",
"data": {
"taskId": "uuid",
"status": "completed",
"results": [
{
"line": 10,
"column": 5,
"severity": "error",
"message": "缺少分号",
"suggestion": "在行末添加分号"
}
]
}
}
```
---
### 2. 获取分析结果
```
GET /api/analyze/:taskId
```
**响应示例**：
```json
{
"code": 200,
"msg": "success",
"data": {
"taskId": "uuid",
"status": "completed",
"results": [...]
}
}
```
---
### 3. 获取历史记录
```
GET /api/analyze/history
```
**查询参数**：
```
page: number (default: 1)
pageSize: number (default: 20)
```
**响应示例**：
**响应**:
```json
{
"code": 200,
@@ -205,90 +173,286 @@ pageSize: number (default: 20)
"list": [
{
"id": "uuid",
"codeSnippet": "function hello() {...}",
"language": "javascript",
"resultCount": 3,
"createdAt": "2026-05-22T00:00:00Z"
"thumbnailUrl": "https://...",
"questionText": "已知二次函数...",
"subject": { "id": 1, "name": "数学" },
"knowledgePoints": [
{ "id": 1021, "name": "顶点坐标" }
],
"errorType": "knowledge_gap",
"difficulty": "medium",
"createdAt": "2026-05-26T10:00:00Z"
}
],
"total": 100,
"total": 42,
"page": 1,
"pageSize": 20
}
}
```
---
## 文件上传模块
### 1. 上传文件
### 3.3 获取错题详情
```
POST /api/upload
GET /api/error-items/:id
```
**请求头**：
```
Authorization: Bearer <token>
Content-Type: multipart/form-data
```
**请求参数**：
```
file: binary
```
**响应示例**：
**响应**:
```json
{
"code": 200,
"msg": "success",
"data": {
"url": "https://storage.example.com/files/xxx.png",
"filename": "xxx.png",
"size": 1024
"id": "uuid",
"imageUrl": "https://...",
"thumbnailUrl": "https://...",
"questionText": "已知二次函数 y = x² - 4x + 3，求顶点坐标...",
"wrongAnswer": "顶点坐标 (2, 1)",
"correctAnswer": "顶点坐标 (2, -1)",
"subject": { "id": 1, "name": "数学" },
"knowledgePoints": [
{ "id": 1021, "name": "顶点坐标", "relevance": 100 }
],
"errorType": "knowledge_gap",
"difficulty": "medium",
"note": "符号搞反了",
"aiAnalysis": {
"diagnosis": "将 x=2 代入时，常数项符号计算错误，应为 3-4=-1 而非 3-4=1。建议回顾二次函数配方法求顶点坐标的完整步骤。",
"errorType": "knowledge_gap",
"confidence": 0.92
},
"createdAt": "2026-05-26T10:00:00Z",
"updatedAt": "2026-05-26T10:00:00Z"
}
}
```
### 3.4 更新错题
```
PATCH /api/error-items/:id
```
**请求**: 同创建参数，所有字段可选。
### 3.5 删除错题
```
DELETE /api/error-items/:id
```
**响应**: `{ code: 200, msg: "success", data: null }`
---
## 4. AI 分析模块
### 4.1 分析错题图片
```
POST /api/ai/analyze
```
**请求**:
```json
{
"imageUrl": "https://storage.example.com/errors/abc.png"
}
```
**响应**:
```json
{
"code": 200,
"msg": "success",
"data": {
"taskId": "uuid",
"status": "completed",
"result": {
"questionText": "已知二次函数 y = x² - 4x + 3...",
"subjectId": 1,
"subjectName": "数学",
"knowledgePoints": [
{ "id": 1021, "name": "顶点坐标", "confidence": 0.95 }
],
"errorType": "knowledge_gap",
"errorTypeConfidence": 0.88,
"difficulty": "medium",
"diagnosis": "顶点坐标计算错误，符号混淆..."
}
}
}
```
### 4.2 获取薄弱点报告
```
GET /api/ai/report?period=week
```
**查询参数**: `period`: week | month
**响应**:
```json
{
"code": 200,
"msg": "success",
"data": {
"periodStart": "2026-05-19",
"periodEnd": "2026-05-26",
"totalErrors": 15,
"trend": "down",
"weakPoints": [
{
"knowledgePointId": 1021,
"name": "二次函数顶点坐标",
"errorCount": 5,
"weight": 0.85,
"trend": "up"
}
],
"errorTypeDistribution": {
"knowledge_gap": 8,
"careless": 3,
"misread": 2,
"concept_confusion": 2
}
}
}
```
---
## 错误码定义
## 5. 学科模块
| 错误码 | 说明 |
|-------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 / Token 过期 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
### 5.1 获取学科列表
---
```
GET /api/subjects
```
## API 测试命令
**响应**:
```json
{
"code": 200,
"msg": "success",
"data": [
{ "id": 1, "name": "数学", "icon": "math" },
{ "id": 2, "name": "英语", "icon": "english" }
]
}
```
### 开发环境测试
### 5.2 获取学科知识点树
```bash
# 登录接口
curl -X POST http://localhost:3000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com","password":"123456"}'
```
GET /api/subjects/:id/knowledge-points
```
# 获取用户信息
curl -X GET http://localhost:3000/api/users/profile \
-H "Authorization: Bearer <token>"
# 代码分析
curl -X POST http://localhost:3000/api/analyze \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"code":"console.log(1)","language":"javascript"}'
**响应**:
```json
{
"code": 200,
"msg": "success",
"data": [
{
"id": 10,
"name": "代数",
"children": [
{
"id": 102,
"name": "二次函数",
"children": [
{ "id": 1021, "name": "顶点坐标", "children": [] }
]
}
]
}
]
}
```
---
**文档版本**：v1.0.0
**最后更新**：2026-05-22
## 6. 文件上传模块
### 6.1 上传图片
```
POST /api/upload/image
Content-Type: multipart/form-data
```
**请求**: `file: binary`
**响应**:
```json
{
"code": 200,
"msg": "success",
"data": {
"url": "https://storage.example.com/errors/abc.png",
"thumbnailUrl": "https://storage.example.com/errors/abc_thumb.png",
"size": 204800
}
}
```
**约束**:
- 最大 10MB
- 格式: jpg/png/webp
- 自动生成缩略图 (200x200)
---
## 7. 错误码
| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 / Token 过期 |
| 403 | 无权访问该资源 |
| 404 | 资源不存在 |
| 413 | 文件过大 |
| 429 | 请求频率超限 |
| 500 | 服务器内部错误 |
| 502 | AI 服务不可用 |
---
## 8. API 测试
```bash
# 微信登录
curl -X POST http://localhost:3000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"code":"wx_test_code"}'
# 获取错题列表
curl -X GET "http://localhost:3000/api/error-items?page=1&pageSize=20" \
-H "Authorization: Bearer <token>"
# 创建错题
curl -X POST http://localhost:3000/api/error-items \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "https://storage.example.com/errors/test.png",
"questionText": "已知二次函数 y = x² - 4x + 3，求顶点坐标",
"wrongAnswer": "(2, 1)",
"subjectId": 1,
"knowledgePointIds": [1021],
"errorType": "knowledge_gap",
"difficulty": "medium"
}'
# 上传图片
curl -X POST http://localhost:3000/api/upload/image \
-H "Authorization: Bearer <token>" \
-F "file=@/path/to/photo.jpg"
```
---
**文档版本**: v0.1.0 | **基于**: [模块设计](../../../docs/02_系统架构/模块设计.md) | **最后更新**: 2026-05-26