北京中考诊断站

给北京初三家长的"模拟考诊断书架"。学生考完模考、老师批改后，上传已判卷的答题纸或学校发的得分表，3 分钟内得到知识点掌握度报告。

当前版本：v1.0（2026-04-25）— 完全免费，无需登录

v1.0 核心约束

• 只支持北京中考体系
• 只支持管理员预录入的试卷
• 只支持已批改、写有每题得分的答题纸（未批改的拒绝服务）
• 学科：数学 / 物理 / 语文 / 英语 / 道法
• 阶段：零模 / 一模 / 二模 / 中考真题
• 全程零 LLM（用户路径与管理员路径都不调用大模型）

技术栈

• 前端: Next.js 15 (App Router) + TypeScript + Tailwind CSS
• UI 组件: 自建 shadcn/ui 子集
• 数据库: PostgreSQL (via Supabase) + Prisma 5
• 存储: Cloudflare R2 (S3 兼容)
• 认证: Supabase Auth (手机号 OTP, 可选)
• OCR:
  • 阿里云教育文档 OCR（模式 A：识别答题卡学生作答）
  • 阿里云通用 / 表格 OCR（模式 B：识别学校得分表截图）
  • 红笔检测：HSV 色域 + 数字/勾叉识别
• 部署: Vercel
• 测试: Vitest（单测）

双输入模式

模式	输入	处理流程
A	已判卷答题纸 PDF/照片	教育文档 OCR 学生作答 + 红笔检测老师判分
B	学校得分表截图	表格 OCR 直接抽出每题得分

两条链路最终产出同一份知识点掌握度报告。

开发指南

初始化项目

# 安装依赖
npm install

# 配置环境变量
cp .env.local.example .env.local
# 编辑 .env.local 填入实际值（Supabase / R2 / 阿里云 OCR）

# 应用数据库迁移
npx prisma migrate dev --name v1_init

# 生成 Prisma Client
npx prisma generate

# 导入 5 学科 234 个知识点
npx prisma db seed

# 启动开发服务器
npm run dev

访问 http://localhost:3000

测试

npm run test           # 单测（grading 不变量、OCR 列名解析）
npm run test:watch     # 单测 watch 模式

数据库操作

npm run db:studio      # 可视化数据库
npm run db:migrate     # 创建新迁移
npm run db:seed        # 重新导入知识点

项目结构

src/
├── app/
│   ├── (app)/                # 用户端
│   │   ├── papers/           # 试卷库
│   │   ├── diagnoses/        # 我的诊断历史
│   │   └── membership/       # v1.0 占位（已免费）
│   ├── (admin)/              # 管理后台（受 middleware 保护）
│   │   ├── wizard/new/       # 试卷资产录入向导（5 步）
│   │   └── papers/           # 试卷库 + 行内编辑
│   ├── api/
│   │   ├── diagnose/         # 上传 + 校对 + 状态轮询
│   │   ├── papers/[id]/download/  # 下载试卷+标答 PDF
│   │   ├── auth/sync/        # 登录后同步 User 表 + 迁移匿名诊断
│   │   └── admin/papers/     # 管理后台 API
│   ├── diagnose/[id]/        # 诊断页（按 status 分流）
│   ├── login/                # 手机号 OTP 登录
│   └── reports/[id]/         # 诊断报告
├── components/
│   ├── diagnose/             # 上传 / 校对 / 处理中
│   ├── reports/              # 知识地图 / 题目作答情况表 / 总分
│   ├── admin/                # 试卷向导 / 编辑表
│   └── ui/                   # shadcn 子集
├── lib/
│   ├── ocr.ts                # 阿里云双链路（A/B）+ 列名同义词
│   ├── grading.ts            # excluded 跳过聚合
│   ├── anon-session.ts       # 匿名 cookie 标识
│   ├── rate-limit.ts         # 软速率限制（防滥用）
│   ├── auth.ts / supabase/   # 认证
│   └── storage.ts            # R2 + 预签名 GET URL
├── types/
│   ├── ocr.ts                # OcrPerQuestion / OcrResult
│   ├── paper-import.ts       # PaperImportJsonSchema (Zod)
│   └── diagnosis.ts
└── data/
    ├── bj-chuzhong-knowledge-tree.json          # 数学 65 个
    ├── bj-chuzhong-chinese-knowledge-tree.json  # 33
    ├── bj-chuzhong-english-knowledge-tree.json  # 38
    ├── bj-chuzhong-physics-knowledge-tree.json  # 60
    └── bj-chuzhong-politics-knowledge-tree.json # 38

详细文档

• plan/dev-spec.md：完整开发规格 v1.1（3300+ 行）
• docs/superpowers/plans/2026-04-25-launch-readiness.md：上线就绪 plan
• plan/README.md：给 AI 编程工具的项目导览

环境变量

必需变量（见 .env.local.example）：

• DATABASE_URL：PostgreSQL 连接串
• NEXT_PUBLIC_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_ANON_KEY / SUPABASE_SERVICE_ROLE_KEY
• R2_ACCOUNT_ID / R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY / R2_BUCKET_NAME / R2_PUBLIC_URL
• ALIYUN_OCR_ACCESS_KEY_ID / ALIYUN_OCR_ACCESS_KEY_SECRET / ALIYUN_OCR_ENDPOINT
• NEXT_PUBLIC_APP_URL

v1.0 完全免费，不需要任何支付商户号。

v1.0 核心功能

用户端

• 试卷库浏览（按学科 / 阶段分类）
• 双模式上传：答题纸（A） / 学校得分表（B）
• 异步 OCR + 状态轮询
• 用户校对低置信度题（可标"未批改/不计入"）
• 知识点掌握度报告（顶部 4 计数器 + 题目作答情况表 + 知识地图）
• 试卷 PDF + 标答 PDF 下载

管理后台

• 试卷资产录入向导：元数据 → 上传 PDF → 上传题目 JSON → 校验 → 发布
• 试卷库管理（按学科分组、状态徽章、行内编辑）
• 自动校验：题号连续 / 总分一致 / 知识点白名单

v1.2 待上线

• 微信支付 + 月度套餐（trigger：内测验证 ≥ 3 家长付费意愿 + 复用率 ≥ 30%）
• PDF 报告导出
• 历史诊断对比

部署

# Vercel CLI
vercel
# 自动读取 vercel.json，buildCommand 含 prisma migrate deploy

# 配置生产环境变量（与 .env.local 对应）

License

MIT