math.miniapp

知了数学 · 小程序

math.client-pc 的教师工作台小程序，使用 Taro 4、React 18、TypeScript、Vite 和 SCSS。此目录为独立 Git 仓库，使用 pnpm 管理依赖。

已按工作区「上传错题小程序.html」原型实现前端流程，所有环境使用本地模拟数据，不调用后端接口。可选择本地照片和 Word/PDF 文件，文件仅保存在当前设备；本地讲解视频可播放。退出/重新进入演示账号仅改变本地展示状态，不代表真实鉴权。

原型功能

• 上传错题：跨班级多选学生、连续拍摄/相册多选、Word/PDF 导入、照片预览与删除、按页识别、题号/划动切换、标记错题、修改题干/选择题选项/答案/解析/年级/知识点/难度，提交所选错题。
• 上传试卷：必填名称、年份、类型、省份；多页采集与逐题编辑；提交后显示待审核，约 20 秒后本地模拟审核通过并产生通知。
• 上传答题卡：拍摄规范、相册多选、连续拍摄、逐张预览/删除/重拍、批量提交。成功后提示到 PC 客户端「批量解析」查看结果，当前版本不执行真实解析。
• 失败重试：确认页提供「体验上传失败与重试」入口；错题/试卷保留编辑结果，答题卡展示失败图片并支持仅重拍失败项，已成功图片不重复处理。
• 题目讲解：待查看/处理中筛选、关联学生与请求/预计/生成时间、完成通知、包内无声讲解示范、观看进度与已读状态。初始示例包含 3 条就绪讲解、1 条约 12 秒后完成的讲解。
• 消息：按视频讲解/试卷/题目/答题卡筛选、全部已读、上传与审核详情、试卷题目和原图分页查看。
• 题库与统计：保留题库页面，支持按年级、知识点、题干或学生筛选，展示本地题量、错题、关联学生和近 7 天趋势；包含 3 份多页示例卷。首页不显示题库管理和上传记录入口，消息仍可通过右上角铃铛查看。
• 我的：编辑姓名/手机号/邮箱并保存到本地、密码表单校验、关于与退出演示账号；不会保存或验证真实密码。

识别结果固定使用数学样例，每张照片/每个文档模拟 3 道题。Word/PDF 仅演示文件选择和识别流程，不解析实际文档内容或实际页数，也不提供文档原图预览。真实拍照需要微信相机权限，H5 拍照行为由浏览器与设备支持决定。

题库、通知、资料和观看进度使用 Taro 本地存储 zhiliao-miniapp-workbench-v1。微信端提交时将临时照片保存为本地文件；H5 保存为数据 URL，刷新后仍可查看。设备存储不足时显示失败并保留当前编辑供重试，未提交草稿不跨刷新保留。清除此项本地存储可恢复示例数据；不要使用真实敏感资料体验。

照片参考图及 4 段讲解视频由 scripts/create-demo-media.mjs 离线生成，拍摄示例页的试卷参考图由 scripts/create-capture-reference.mjs 绘制，已随源码提供。需要重新生成时运行对应的 node scripts/…mjs（使用本机 Chrome），普通构建无需运行。媒体资源输出为独立文件，避免微信端不支持的视频数据 URL。

上传错题页使用学生关联条、拍照区域和相册/文件双列入口；添加照片后显示数量与「识别全部照片」。「查看示例」页仅展示拍摄规范、完整试卷参考、三项拍摄提示和多页说明；拍照或导入照片请返回上传页操作。

上传试卷页使用浅紫色信息卡：名称独占一行、年份与类型并排、省份独占一行。下方为拍照区域、已添加照片入口和「识别全部照片」按钮；相册和 Word/PDF 导入入口位于后方，表单和已添加文件在查看示例或照片后保留。

上传答题卡页展示拍摄规范、浅紫色 A4 答题卡参考卡、三项提示，以及「从相册多选」「拍摄答题卡」双按钮。参考图片由 scripts/create-answer-reference.mjs 离线生成，包含姓名、班级、示意二维码和作答区域；首次选择照片后进入确认页。

关联学生使用居中弹窗，未关联学生时班级显示「请选择班级」，不默认选中班级；已有选择时重新打开弹窗，回显首位已选学生的班级及该班已选学生。先选择班级，再通过学生下拉多选。跨班级保留名单，已选学生以可删除标签展示。取消会丢弃本次选择，确认后才更新上传页名单。

关联名单仅用于本次上传，不保存为下次默认选择；重新进入、刷新页面或成功后「继续上传」均清空。查看照片和拍摄示例后返回，仍保留本次选择；已提交记录中的关联学生继续保留。

拍照、从相册选择和导入 Word/PDF 均不校验关联学生；点击「识别全部照片」时才校验，未关联学生则弹出选择框，取消后保留已添加的文件。

「已添加照片」按顺序展示照片缩略图、文件名、查看与删除入口；Word/PDF 使用文件图标。顶部可继续拍照，底部「完成」返回上传页，再统一识别。图片预览只包含照片，不包含文档。

安装与预览

要求 Node.js 22.18+、pnpm 10.34.9（已在 packageManager 中固定）。React 18 为当前 Taro 官方插件支持的版本，未沿用 PC 端的 React 19。

pnpm install --frozen-lockfile
pnpm dev

如果本机全局 pnpm 不是 10.34.9，可将命令前缀换成 npx --yes pnpm@10.34.9，例如 npx --yes pnpm@10.34.9 dev，无需改动全局安装。

先执行 pnpm dev 完成首次编译，再在微信开发者工具中直接导入 math.miniapp 根目录。根目录的 project.config.json 已将 miniprogramRoot 设为 dist/，修改源码后会自动重新编译。pnpm build:dev 可生成一次性的开发环境产物。

默认 touristappid 用于本地预览；需要真机或正式上传时，在微信开发者工具中使用自己的公开 AppID，不在本项目填写 AppSecret。也支持单独导入 dist/，该目录的工程配置可用进程环境变量覆盖 AppID：

$env:TARO_APP_ID = '你的小程序AppID'
pnpm build:test

浏览器辅助预览：pnpm dev:h5，访问 http://127.0.0.1:10086。H5 用于快速查看布局与交互，微信端效果仍需在开发者工具及真机上确认。构建命令只编译本地文件，不会上传或发布小程序。

三套打包环境

环境	打包命令	产物目录
开发	pnpm build:dev	dist/
测试	pnpm build:test	dist/
正式	pnpm build:production（或 pnpm build）	dist/

pnpm build:all 依次构建开发、测试、正式环境，最终 dist/ 保留正式环境产物。测试环境监听构建使用 pnpm dev:test。切换环境前请先停止正在运行的监听构建，避免不同命令同时写入 dist/。需要恢复开发环境时运行 pnpm dev 或 pnpm build:dev。

H5 开发环境静态打包使用 pnpm build:h5，产物单独保存到 dist-h5/，避免覆盖小程序产物。

业务环境由构建命令选择，脚本显式传递 --mode development/test/production，由 Taro 加载对应的 .env.* 文件，并设置 APP_ENV。所有一次性打包均使用 NODE_ENV=production 优化，避免将 React 的构建模式和业务测试环境混用。三个环境共用 dist/，后一次构建覆盖前一次，微信开发者工具运行的是最近一次构建的环境。

dist/build-info.json 包含当前产物的环境、平台、版本、数据来源和构建时间；单独导入 dist/ 时微信工程名称也带环境后缀。所有环境的页面顶部均不显示环境标记；「关于」页可以查看环境和版本。三套环境目前都不含 API 地址，未来接接口时再分别添加公开配置，不能把密钥编译进前端。

根目录 project.config.json 用于直接导入仓库，同时作为产物工程配置的模板；构建生成的 dist/project.config.json 将 miniprogramRoot 设为 ./，也可直接导入。TARO_APP_ID 仅覆盖产物工程配置，不改写根目录配置。不同 AppID 不是区分环境的必要条件，微信体验版/正式版发布状态与业务环境是两个概念。

环境变量

文件	用途	提交 Git
.env.development	开发环境的公开值	是
.env.test	测试环境的公开值	是
.env.production	正式环境的公开值	是
.env / .env.local	可选的公共默认值 / 个人默认值	否
.env.<mode>.local	某个环境的个人覆盖值	否

同名变量的优先级从高到低：进程环境变量 → .env.<mode>.local → .env.<mode> → .env.local → .env。每个模式在独立构建进程中加载，build:all 不会沿用上一个环境文件的值。修改环境文件后需重启监听构建。

.env 文件格式本身不限制变量名前缀，但本项目使用 Taro 默认加载规则，自动加载并注入前端的自定义变量必须以完整的 TARO_APP_ 开头，单独的 TARO_ 前缀不够。任意名称的变量不会自动加载到业务代码；系统进程变量和框架内置变量另有用途。

例如，在本地 .env 中定义所有环境共用的公开变量（此文件不提交 Git）：

TARO_APP_APP_NAME=知了数学

在业务代码中可直接读取：

const appName = process.env.TARO_APP_APP_NAME

请使用完整的 process.env.TARO_APP_XXX 表达式，避免解构或动态键读取。同名值若存在于 .env.development 等优先级更高的文件中，将覆盖 .env，空字符串也会覆盖；需要使用公共默认值时，移除环境文件中的同名项。

三个环境文件已包含：

TARO_APP_ENV_LABEL=开发环境
TARO_APP_API_BASE_URL=
TARO_APP_ENABLE_DEBUG=true
TARO_APP_ID=touristappid

环境名称和调试开关分别按环境填写；接口地址目前留空，仍然只运行本地演示，不发请求。TARO_APP_ENABLE_DEBUG 必须为 true 或 false，不会自动打开调试工具。TARO_APP_ID 默认为游客 AppID；需要个人覆盖时在 .env.development.local 等文件中填写。

业务代码统一读取经过类型转换的配置：

import { appConfig } from '@/config/environment'

const apiBaseUrl = appConfig.apiBaseUrl
const enableDebug = appConfig.enableDebug // boolean

新增变量时，共用默认值放在本地 .env，不同环境的值放在对应 .env.*，并同步维护本节变量说明。需要统一暴露给业务代码的变量，更新 types/global.d.ts 的类型声明及 src/config/environment.ts 的读取/转换。需要构建时校验的变量同步维护 config/environments.ts 中的 readPublicConfig。不要在 TypeScript 中再硬编码三套环境值。Taro 以字符串注入环境变量，数字、布尔值需显式转换。

src/config/environment.ts 仍作为统一的类型化读取入口，「关于」页面正在使用它；它还负责将 TARO_APP_ENABLE_DEBUG 转换为布尔值。环境值来自 .env.*，这个文件不再维护三套配置。项目不保留额外的环境示例模板，变量说明直接维护在 README 和三套公开环境文件中。

TARO_APP_ 变量会打进前端包，只存放公开配置，不包含密钥。APP_ENV、NODE_ENV 由脚本控制，不在环境文件中设置。

验证

pnpm typecheck
pnpm lint
pnpm test
pnpm build:all
pnpm test
pnpm build:h5
pnpm test:e2e

单元测试覆盖环境校验、模式文件加载、覆盖优先级、统一输出目录、产物配置，以及追加/删除照片时保留编辑、跨班级同名学生、表单校验、重复提交、审核回传和消息已读；可通过 EXPECTED_APP_ENV 指定产物应有的环境。E2E 使用本机 Chrome，覆盖 390px/320px 两种视口、错题编辑与重试、答题卡部分失败与重拍、试卷元信息/本地图片/PDF 选择/审核回传、刷新保留原图、视频播放、题库、个人页与无业务 API 请求。未安装 Chrome 时需先安装，或修改 Playwright 的浏览器配置。相机权限、微信文件选择器和原生视频播放仍需微信开发者工具及真机验证。

目录约定

各页面保留自己的 index.scss 样式入口，确保微信端生成对应的 index.wxss。产物测试逐页检查 JS、JSON、WXML、WXSS，避免微信开发者工具因缺失页面样式而编译失败。

• src/pages：首页、个人页、上传、消息、讲解和题库；src/components：公共表单、题目卡片、学生选择、安全区与弹层。
• src/data：本地领域类型、模拟识别/回传、持久化状态、媒体适配及演示登录态；后续接接口可替换数据层。
• config、scripts：环境与跨平台构建入口。
• tests：环境回归与浏览器交互验证。

品牌 Logo 复用工作区 math.client-pc/public/logo.png 的副本；底部导航和通知铃铛 PNG 图标由本项目绘制，通知图标可运行 scripts/create-notification-icon.ps1 重新生成。未引入 PC 端的 Electron、Ant Design 或 API 依赖。