EAIminiapp/README.md

EAI 英语课堂辅助小程序（uni-app）

面向高校英语课堂教学的微信小程序前端，基于 uni-app + Vue 3 实现，提供课堂签到（教师/学生两端）、签到记录、个人中心等能力，支持数字码签到方式，并通过 Pinia 实现会话与配置持久化。

项目简介（Overview）

本项目用于辅助高校英语课堂教学场景，面向教师与学生两类用户：

• 教师：发起课堂签到、选择班级与签到方式（数字码）、查看签到进度并结束签到；
• 学生：进入课堂后快速完成签到，并可查看个人签到记录；
• 管理：统一的登录与用户资料管理，自动持久化登录态。

核心功能（Key Features）

• 欢迎/引导页：pages/welcome/index
• 登录认证：pages/login/index
• 首页：pages/index/index
• 个人中心：pages/profile/index
  • 用户资料查看与更新（头像、英文名、性别、生日、联系邮箱等）
  • 默认头像生成与自定义头像设置
• 课堂签到：pages/checkin/*
  • 教师端：teacher/index、select-method（选择二维码/数字码）、number-setup（设置数字签到码）、qr-active（展示实时二维码）、select-class（选择班级）
  • 学生端：index（进入签到页，输入数字码或扫码）
  • 实时状态：倒计时、已签到人数变化、活跃签到任务轮询与自动恢复
• 签到记录：pages/record/*
  • 总览：record/index
  • 教师端：record/teacher、record/teacher-class-details
  • 学生端：record/student
• 网络与状态：
  • 统一请求封装（utils/request.ts），自动附加 Authorization 头、统一 Toast 提示、白名单接口免认证
  • Pinia + 持久化插件（登录态 user-store、签到会话 activeCheckinSession、签到配置 checkin-config-store）
• 二维码支持：内置组件 components/tki-qrcode 与库 uqrcodejs

技术栈（Tech Stack）

• Vue 3（manifest.json 指定 vueVersion: 3）
• uni-app（小程序多端框架）
• Pinia 3（状态管理） + pinia-plugin-persistedstate 4（状态持久化）
• TypeScript（业务模块多为 .ts）
• SCSS（全局样式 uni.scss）
• 微信小程序平台
• 第三方与内置：uqrcodejs、本地组件 tki-qrcode
• DCloud 模块：uni-config-center、uni-id-common

依赖来源请参考 package.json：

{
  "dependencies": {
    "pinia": "^3.0.3",
    "pinia-plugin-persistedstate": "^4.3.0",
    "uqrcodejs": "^4.0.7"
  }
}

项目结构（Project Structure）

EAIminiapp/
  api/                    # 与后端交互的 API 封装（如用户、签到）
  components/             # 业务组件（含二维码组件 tki-qrcode）
  config/
    index.ts              # 运行时配置（baseUrl/timeout/debug）
  pages/                  # 小程序页面目录（uni-app 约定式路由）
    checkin/              # 签到模块（教师/学生）
    record/               # 签到记录（教师/学生）
    profile/              # 个人中心
    login/                # 登录
    index/                # 首页
    welcome/              # 欢迎页
  services/               # 业务服务封装（如用户领域）
  static/                 # 静态资源（图片等）
  store/                  # Pinia 状态（用户、签到、签到配置）
  utils/
    request.ts            # 请求封装（Base URL、鉴权、错误处理）
  App.vue                 # 根组件
  main.js                 # 入口文件（创建应用、注册 Pinia 与持久化插件）
  manifest.json           # 应用清单（平台配置、appid、编译器版本等）
  pages.json              # 路由与页面样式配置（小程序页面清单）
  uni.scss                # 全局样式/变量

• pages：uni-app 的页面根目录，页面路由由 pages.json 管理；
• static：放置静态资源（不会被编译器处理的文件，如图片）；
• components：本地通用/业务组件；
• main.js：应用入口，Vue 3 下通过 createSSRApp 创建应用并 app.use(pinia)；
• manifest.json：多端平台配置（mp-weixin、app-plus 等），其中微信 appid 使用占位符；
• pages.json：页面路由、导航栏、全局样式等配置；
• store：Pinia Store，内置持久化，管理用户/签到/配置等状态；
• utils/request.ts：封装统一请求、鉴权与错误提示；
• config/index.ts：后端地址与超时等运行时配置（可迁移为环境变量）。

安装与启动（Getting Started）

先决条件

• Node.js ≥ 16（推荐 18 LTS）
• HBuilderX 最新版（推荐 Vue3+Vite 编译器）
• 微信开发者工具（基础库建议 ≥ 2.30）
• npm 或 pnpm（项目已附带 package-lock.json，示例使用 npm）

安装依赖

npm install

本地运行 / 编译到微信小程序

1) 使用 HBuilderX（推荐）

• File → Open 选择本项目；
• 运行 → 运行到小程序模拟器 → 微信开发者工具；
• 或 发行 → 小程序-微信（生成产物目录）；
• 首次需要在 manifest.json 中正确配置 mp-weixin.appid（详见下方“环境变量”）。

构建产物目录：

• 开发模式：dist/dev/mp-weixin
• 生产模式：dist/build/mp-weixin

3) 用微信开发者工具导入调试

• 打开微信开发者工具 → 导入项目；
• 选择上述生成的目录（如 dist/dev/mp-weixin）；
• 设置 AppID（需与 manifest.json/环境变量一致），即可运行与预览。

备注与约定

• 接口鉴权：utils/request.ts 会根据白名单 noAuthUrls 控制是否自动附加 Authorization 头；
• 状态持久化：pinia-plugin-persistedstate 已启用，重要键包括 user-store、activeCheckinSession、checkin-config-store；
• 路由与页面：请在 pages.json 中维护新页面及其导航配置；
• 路径别名：代码中使用 @/ 指向项目根（由 uni-app/Vite 预设）。

许可（License）

暂无。