# 教育机构打卡小程序 · 设计文档（v0.2 通用多班级版）

> 定位：通用「班级作业 + 打卡」平台——任何老师（数学 / 物理 / 语文…）都能建班发作业，学生加入多个班级后按学科聚合查看
> 版本：v0.2（2026-10-23，相对 v0.1 重构为多老师 / 多班级 / 多学科）
> 状态：设计方向与品牌色待确认，未接后端

---

## 0. 变更说明（v0.1 → v0.2）

| v0.1 | v0.2 |
|---|---|
| 单一机构视角 | **通用平台**：任意老师可入驻 |
| 机构统一任务 | 老师按**学科**建**班级**，发作业/打卡 |
| 学员被动接收 | 学生**邀请码加入班级**，自主管理多班 |
| 无学科维度 | 首页按**学科**聚合各科待办 |

---

## 1. 产品定位

一句话：**一个 App，服务所有老师与学生——数学老师、物理老师…各自建班，学生加入后在一个首页看到各科作业与打卡。**

两条主线保留并打散到班级维度：
- **作业闭环**：老师发作业 → 学生提交 → 老师点评。
- **坚持打卡**：习惯类每日打卡（错题整理、每日一题、阅读…），按学科攒连续天数。

---

## 2. 角色与场景

| 角色 | 核心诉求 | 高频场景 |
|---|---|---|
| 老师（数学/物理/…） | 建班级、发作业/打卡、点评激励 | 创建「初三数学冲刺班」、发每日练习、圈里点评 |
| 学生 | 加入班级、按学科看作业、3 步打卡 | 加入数学/物理班、今日做完各科作业 |
| 家长 | 看孩子各科出勤与作业 | 接收提醒、查看周报 |

---

## 3. 核心功能架构（4 Tab）

1. **首页 / 今日** — 顶部「连续天数环 ↔ 考试倒计时」可切换（倒计时支持高考 / 月考 / 期中 / 期末 / 自定义，自动算剩余天数）+ 学科筛选 chips + 今日待办（**按学科分组**，行内带班级名）。**不重复列班级**——班级统一在「班级」Tab 看
2. **班级** — 我加入的班级（学科色条 / 老师 / 成员 / 待办数）+ 加入班级（邀请码）；点开详情可查看**班级老师**并**退出班级**。学生端**不提供创建班级**（建班属老师端能力）
3. **打卡圈** — 班级内动态，带学科标签，点赞 / 发布（选班级）/ 评论区（可看老师点评并回复）
4. **我的** — 资料、加入的班级、学科勋章墙、身份切换（学生 / 老师）

**信息不重复原则**：同一份信息只在一个地方出现 —— 班级列表只在「班级」Tab，首页只管待办；老师归属只在班级详情里看。

**关键流程**：老师建班 → 学生输邀请码加入 → 首页看到多学科作业 → 打卡/提交 → 流入打卡圈 → 老师点评 → 攒学科勋章。

---

## 4. Design Pillars

- **坚持感**：连续天数、进度环、勋章三重强化。
- **学科辨识度**：用颜色区分学科（数学橙 / 物理青 / 语文粉…），一眼分清归属。
- **轻量**：任何打卡 ≤ 3 步，默认带快捷打卡。
- **鼓励**：正向动画、社区点赞、老师点评。

---

## 5. 视觉规范

| 角色 | 色值 | 用途 |
|---|---|---|
| 主色 成长橙 | `#FF7A45` | 主按钮、强调 |
| 深橙 | `#F2541B` | 渐变终点、按压态 |
| 奶油底 | `#FFF9F2` | 页面背景 |
| 墨 / 次文本 | `#2B2B2B` / `#8A8A8A` | 文字 |
| 卡片白 / 描边 | `#FFFFFF` / `#F0EAE2` | 卡片 |

**学科色（核心新增）**

| 学科 | key | 色值 | 图标 |
|---|---|---|---|
| 数学 | math | `#FF7A45` | 📐 |
| 物理 | physics | `#2BB6A8` | 🔭 |
| 语文 | chinese | `#E26D9C` | 📖 |
| 英语 | english | `#7C6CF0` | 🔤 |
| 综合 | general | `#8A8A8A` | ⭐ |

学科色用于：筛选 chip 选中态、班级卡左侧条、任务卡学科标签、打卡圈学科角标。

---

## 6. 关键页面与交互（见 `教育机构打卡-原型.html`）

- **首页**：顶部通栏区默认显示个人连续天数环（SVG 进度环），可一键切换为「考试倒计时」（高考 / 月考 / 期中 / 期末 / 自定义，点 ⏱ 设置目标日期，自动算剩余天数）；其下为学科 chips 筛选 + 今日待办按学科分组（含班级名 + 学科标签 + 打卡按钮）。
  - **不重复展示班级列表**：底部导航已有「班级」Tab，首页不再放「我加入的班级」条目块，避免同一信息出现两处；班级详情统一从班级页点「详情」进入。
  - 待办行保留**班级名**前缀（如「高一数学冲刺 · 今日 21:00 前 · 王老师」），保证同科多班时仍能区分任务来源。
  - **作业查看 / 下载**：「作业」型任务**点击整行**可打开详情，查看并下载老师发布的作业文件（PDF / Word / PPT 等，点文件行即下载）。
  - **打卡即提交作业**：点「作业」型任务的「打卡」按钮 → 弹出「提交作业」窗口（可**拍照 / 从相册上传图片**做作业凭证 + 选填留言给老师），提交后标记完成并触发连续天数 +1 与撒花动画；「打卡」型（习惯类）任务仍一键直接打卡。
- **班级**：班级卡列表（学科色条 + 老师 + 成员数 + 待办数）。学生端**只有「＋ 加入班级」**（输邀请码），**没有创建班级入口**——建班是老师的能力。点班级卡进入**班级详情**，详情内含：
  - **班级老师**区块：老师头像（姓名首字）+ 姓名 + 「XX老师 · 负责本班教学与作业」+ 学科标签；
  - **班级作业**列表（该班全部作业 + 完成状态）；
  - 底部**「退出班级」**（红色描边警示态，二次确认弹窗说明「退出后不再接收该班作业与提醒」；确认后移出 `joinedClassIds`、班级成员数 −1、详情自动关闭并刷新列表）。
- **打卡圈**：动态带学科角标与班级名；「写打卡」可选班级发布；点赞 / 发布；**评论区**（点「💬 评论」展开，可看老师点评并回复）。
- **我的**：统计（加入班级数 / 连续天数 / 勋章）；我加入的班级列表；学科勋章墙；身份切换（学生 ↔ 老师）。

---

## 7. 数据模型（演示用，后续云开发）

```js
subject = { key, name, color, icon }
teacher = { id, name, subjectKey, title }
class   = { id, name, subjectKey, teacherName, inviteCode, memberCount }
task    = { id, classId, subjectKey, title, desc, dueTime, type:'作业'|'打卡'|'到课', needProof:bool, file:{name,size,type}|null, done }
checkin = { id, taskId, studentId, date, status, note, images:[], fileId:null, likes }
student = { id, name, joinedClassIds:[], streak, totalDays, medals:[] }
checkin = { id, taskId, studentId, date, status, note, images:[], likes }
feed    = { id, classId, studentId, name, body, images:[], time, likes, comments:[{ id, name, role:'teacher'|'student', text, time, replyTo }] }
```

- 演示数据存本地 `storage`；接云开发后 `classes / tasks / checkins / users / members` 入云数据库。
- 学生加入班级 = 在 `members` 集合写 (classId, studentId)；邀请码校验在后端的 `joinClass` 云函数。
- 连续天数与学科进度**服务端重算**，防前端作弊。

---

## 8. 技术约定

- 原生小程序（与巷口集市 / 慢咖啡一致），4 Tab。
- 演示模式：`utils/demoData.js` + `storage`，无后端跑通主流程（含加入/创建班级交互）。
- 后续：微信云开发（`joinClass` / `createClass` / `publishTask` / `submit` / `comment` 云函数 + 订阅消息：作业提醒 / 点评通知 / 连续中断）。
- 角色：同一 App 内 `role` 字段切换（学生 / 老师），**切换后底部 Tab 整体替换**——学生 4 Tab：首页 / 班级 / 打卡圈 / 我的；老师 5 Tab：工作台 / 班级 / 作业 / 打卡圈 / 我的（详见 §13，老师端以"管理"为核心，与学生端差异大）。

---

## 9. 待确认

1. 产品名与品牌色（含学科色方案是否采用）。
2. 老师是否需要**独立端**，还是同一 App 内角色切换？（文档默认角色切换）
3. 一个班级是否支持**多老师**协同？学生加入班级上限？
4. 作业提交是否需**图片 / 文件**（needProof）？→ **已确认**：支持老师发作业文件 + 学生上传作业（合规见 §11）。
5. 是否需要**积分 / 排行榜 / 家长独立端**？
6. 接云开发还是先纯演示？AppID 待定。

---

## 10. 上架合规要求（2026-10-23 补充）

> 结论：**不能走个人主体**（教育类目个人禁入 + 无支付）；要走**个体工商户 / 企业主体**。当前「打卡 + 作业工具」形态**一般无需《办学许可证》**，但要过备案、认证、内容安全、未成年人保护四关。具体类目以审核时实机判定为准。

1. **主体**：必须个体工商户或企业（个人主体无法选教育类目、不能开微信支付）。个体户成本最低（无需对公账户，资金结算至法人银行卡）。
2. **小程序备案（ICP 备案）**：自 2023-09 起**强制**，未备案不能提交审核发布。免费，3–20 工作日，主体须与微信注册主体 100% 一致；request 域名须 HTTPS 且已 ICP 备案。
3. **微信认证**：企业 / 个体户 300 元 / 年。
4. **类目与资质（关键分水岭）**：
   - 只做打卡 / 作业管理、**不卖课、不直播上课** → 选「工具-实用工具」或「教育-其他（教育信息服务）」，**仅需营业执照，无需办学许可证**。
   - 含在线课程 / 直播 / 卖课 → 需《民办学校办学许可证》或《非学科类校外培训机构培训许可证》等，门槛高。
   - 做多机构入驻的**课程销售平台** → 需《增值电信业务经营许可证》（EDI）。本设计是「老师自建班」工具，通常不涉及。
5. **内容安全（打卡圈 UGC）**：用户发动态 / 图 / 评论，必须接**微信内容安全 API**（msgSecCheck / imgSecCheck）做先审后发，否则 UGC 功能审核不过；配套用户协议 + 隐私政策 + 举报机制。
6. **未成年人保护**：用户含学生（未成年人）→ 收集儿童个人信息需监护人同意、建议青少年模式 / 时长管理，是教育类重点合规项。
7. **微信支付 / 虚拟支付**：暂不收款可跳过；未来收会员 / 使用费见 §12（2026 起走「微信虚拟支付」专用通道，iOS 12% / 安卓 1%，非普通支付 0.6%）。
8. **上线时间线**：备齐材料 → 小程序备案（3–20 天）→ 开发 + 选类目 → 提交审核（1–7 天）→ 发布。
9. **成本估算**：个体户执照（低 / 基本免费）+ 微信认证 300/年 + 云开发基础版约 19.9/月（参考巷口集市）+（未来支付 0.6%）。

**建议起步方案**：用个体工商户主体注册 → 类目选「工具 / 教育-其他」规避办学许可证 → 先把打卡 / 作业工具跑通 → 打卡圈接内容安全 API → 学生信息做未成年人合规。

---

## 11. 作业文件收发专项合规（2026-10-23 补充）

> **结论先行**：老师发作业文件 + 学生上传作业，**不需要《办学许可证》**，属「学习管理 / 家校沟通工具」而非「校外培训经营」，符合上架要求。但「学生上传」= 用户生成内容（UGC），会**新增内容安全强义务**，且**企业 / 个体户主体 + 微信认证是前置硬条件**（个人主体调不了内容安全接口）。

### 11.1 为什么不需要办学许可证

- 双减政策下，《办学许可证》仅针对**开展学科类 / 校外培训经营的机构**（面向中小学生收费授课）。
- 本产品定位是「学校 / 老师布置、收集作业的**辅助工具**」，不提供培训服务、不收费授课、不撮合卖课 → 不满足"培训经营"要件。
- ⚠️ **红线**：若实质变成「老师通过它有偿辅导 / 变相授课收费」「为无证个人提供培训平台」，会被认定为校外培训，需办学许可。保持"纯作业收发 + 打卡"工具定位最安全。
- 类目仍选「工具-实用工具」或「教育-其他」，仅营业执照，不要选「教育-在线视频课程」（那个才要办学许可）。

### 11.2 文件上传触发的内容安全义务（核心新增）

学生上传作业 = UGC，平台**必须**在发布 / 存储前做内容审核：

| 上传内容 | 检测接口 | 说明 |
|---|---|---|
| 作业**图片**（拍照 / 截图） | `imgSecCheck` | 同步检测，免费（20 万次 / 天 / appId），硬性要求 |
| 作业**文字说明 / 评论** | `msgSecCheck` | 同步文本检测，硬性要求 |
| 作业**语音 / 视频** | `mediaCheckAsync` | 异步，需配 HTTPS 回调域名 |
| 作业**文档（PDF / Word / PPT）** | ⚠️ **官方接口不直接覆盖** | 微信内容安全只覆盖文本 / 图片 / 音视频，**文档类无原生检测** |

- **前置硬条件**：内容安全接口**仅企业 / 组织主体 + 已完成微信认证**可调（个人主体不行，且个人也不能有 UGC）。
- **禁止用"本地关键词过滤 / 纯人工初审"替代官方接口**——平台明确规定人工只能补充，不能替代。
- **报备审核**：含 UGC 的小程序发布前要走**网信部门报备**（约 7 个自然日），代码审核环节会敏感词检测，**未接入官方内容安全接口将直接审核不通过**。
- **文档类的实操兜底**：学生作业多为 PDF / Word，官方接口检测不到。建议：① 优先引导"拍照 / 截图上传"（走 imgSecCheck）；② 若必须支持文档，在用户协议明确禁止违规内容 + 提供举报入口 + 建人工复核兜底；③ 对文档生成预览图再检测预览图（折中方案）。

### 11.3 文件存储与传输

- 云存储（微信云开发 / 对象存储 / 自有服务器）均可；`wx.uploadFile` / `wx.downloadFile` 的域名**必须 HTTPS + 已 ICP 备案**并加入小程序 request 合法域名白名单。
- 学生提交的作业文件涉及**未成年人个人信息**，需：加密存储、最小必要收集、监护人同意授权、不对外公开（仅老师可见）。

### 11.4 对设计的影响

- `submit` 云函数流程改为：**接收文件 → 文件落地前先做内容安全检测（图片 / 文字）→ 通过才入库并通知老师**，失败则拦截 + 提示。
- 学生端交互落地为：点作业整行 → 查看 / 下载老师文件；点「打卡」（作业型）→ 弹「提交作业」窗口上传图片凭证（优先图片走 `imgSecCheck`，文档类按 §11.2 兜底）。
- 待确认第 4 项（needProof）**已确认**：支持老师发作业文件 + 学生上传作业；默认以"图片 / 截图"为主，文档类作为可选。
- 隐私政策需单列「未成年人信息」与「作业文件处理」条款。

---

## 12. 商业化：向老师收使用费（会员 / 订阅）合规（2026-10-23 补充）

> **结论先行**：可以收。一年几百的「老师使用费」属于会员 / 订阅 / 服务费，是合规的**虚拟支付**场景；**不触发《办学许可证》**（这是收工具使用费，不是卖课 / 培训），**也不触发 EDI**（自营 SaaS，不是平台撮合）。但 2026 年起必须用「微信虚拟支付」专用通道（禁普通支付 / 外链跳转），费率 iOS 12% / 安卓 1%。

### 12.1 为什么能收、且不算办学许可 / EDI

- 收的是"使用工具的会员 / 订阅费"，不是"卖课 / 培训费" → 仍是工具经营，不触发《办学许可证》。
- 不是"为其他老师撮合卖课抽成"的平台 → 不触发《增值电信业务经营许可证》(EDI)。EDI 只在做**多机构课程销售平台**时才需要（见 §10.4）。
- 本质 = 自营 SaaS 年费，属虚拟支付中的"会员与特权服务 / 工具付费功能"形态（微信官方虚拟支付运营指南明确覆盖）。

### 12.2 2026 虚拟支付新规（关键）

- **2026-04-01 起，全终端（iOS / Android / 鸿蒙 / Windows）虚拟交易必须走「微信虚拟支付」**，禁止用普通微信支付、禁止引导跳转公众号 / H5 / 外部网站完成支付（此前 iOS 长期禁虚拟支付，2025-11 已破冰接入）。
- 需**单独开通虚拟支付专用商户号**（与普通微信支付隔离），签署《虚拟支付服务协议》《订阅付费运营规范》。
- **费率（2026）**：iOS **12%**（苹果佣金，腾讯技术服务费当年暂免）；安卓 / 鸿蒙 / Windows **1%**（原 10% 优惠）。
- iOS 必须开启苹果 IAP 开关 + 配置小程序简称；iOS 结算由 Apple 走，周期约 45–60 天。

### 12.3 主体与类目

- **主体**：企业 / 个体户（本产品教育类目本就要求企业 / 个体户；个人主体虽 2026 可开虚拟支付但仅限「工具」类目、月限 10 万、不适合含未成年人的教育收费，不推荐）。
- **类目**：保持「工具-实用工具」或「教育-其他」即可开通虚拟支付，**无需改为电商类目、无需 EDI**（微信开放社区官方口径：工具类销售虚拟商品无需 EDI）。

### 12.4 对产品 / 设计的影响

- 做**免费版 + 会员版**分层：免费（如 1 个班 / 基础功能），会员（如 ¥299/年：不限班级数、不限学生数、作业 AI 批改、数据导出、去广告等清晰权益）。
- 计费走虚拟支付"订阅"能力（年卡对应月卡 / 季卡 / 年卡道具），生成 OfferId。
- 会员权益须清晰可落地、无诱导续费、无虚假特权（微信严查类目）。
- **成本测算要把费率算进去**：定价 ¥299 → 安卓到手 ≈ ¥296、iOS 到手 ≈ ¥263。

### 12.5 风险提示

- ❌ 不能用普通微信支付商户号收会员费（会被判违规、限制功能）。
- ❌ 不能引导老师去公众号 / H5 / 官网付款（2026 新规严禁外链跳转完成虚拟支付）。
- ❌ 不能把"会员"包装成"卖课"，否则回到办学许可 / 教育类目强监管。

---

## 13. 老师端设计（2026-10-23 补充）

> 老师端与学生端**差异巨大**：学生端是"参与 / 接收"，老师端是"管理 / 发布"。同一 App 内通过 `role` 切换，切换后**底部 Tab 整体替换**（学生 4 Tab：首页 / 班级 / 打卡圈 / 我的；老师 5 Tab：工作台 / 班级 / 作业 / 打卡圈 / 我的），而非在原页面上堆功能。

### 13.1 老师端 5 Tab 与核心能力

| Tab | 名称 | 核心页面 / 能力 |
|---|---|---|
| 工作台 | 🧑‍🏫 | 教学概览四宫格（我的班级 / 学生总数 / 待批改 / 今日打卡率）+ 快捷「发布作业 / 创建班级」+ 待批改 / 提交跟踪列表（按学科标签 + 提交进度 %） |
| 班级 | 🏫 | **「＋ 创建班级」**（选学科 + 班名，自动生成邀请码）+ 我创建的班级列表（学科色条 + 学生数 + **待审批角标**）；班级详情 = **成员管理**（学生 + 近 30 天打卡率 + 移除）+ **待审批加入**（同意 / 拒绝）+ **邀请码**（点击复制）+ 群发打卡提醒 + 发布作业入口 |
| 作业 | 📋 | 作业管理列表（已发布作业 + 提交进度 %）；**发布作业**表单（选班级 / 标题 / 要求 / 截止 / 上传附件 / 是否需提交图片）；点作业 → **提交详情**（已提交学生 + 批改按钮 / 未提交学生 + 提醒按钮，附老师原附件下载） |
| 打卡圈 | 🌈 | **学生打卡动态流**（仅自己班级的学生动态）+ 按班级筛选 chips + **点评 / 回复**（老师评论带橙色「老师」标识）+ 点赞鼓励 + **删除动态 / 删除评论**（内容安全管理） |
| 我的 | 👤 | 老师资料（姓名 / 科目 / 教龄 / 认证）+ 我教授的学科 + 班级管理 / 消息提醒 / 内容安全须知 / 通用设置 + 切回学生端 |

### 13.2 老师端关键流程

1. **发作业闭环**：工作台/班级/作业页 → 发布作业（选班 + 传附件 + 设截止）→ 学生端出现该作业 → 学生上传图片提交 → 老师端作业进度 % 上升 → 点进查看提交 → 批改 / 提醒未交。
2. **学生管理闭环**：学生输邀请码申请加入 → 老师端班级详情「待审批」出现红点 → 同意 → 进入班级学生列表（可移除）。
3. **数据洞察**：工作台聚合各班级打卡率与待批改量，老师一眼掌握全局。
4. **打卡点评闭环**（2026-10-23 补充）：学生打卡 / 交作业 → 动态流入打卡圈 → 老师端打卡圈看到 → **点评 / 回复**（带「老师」标识）→ 学生端打卡圈收到点评 → 学生回复老师 → 老师端即时看到。闭环中老师可**删除动态 / 删除评论**（UGC 内容安全管理）。

### 13.2.2 打卡圈点评闭环（老师 ↔ 学生）

| 环节 | 老师端 | 学生端 |
|---|---|---|
| 查看 | 打卡圈 Tab 只显示**自己班级**学生的动态（数据隔离），顶部可按班级筛选 | 只看自己加入班级的动态 |
| 互动 | 点「💬 评论」展开评论区 → 输入点评；可**回复**某条学生评论；点赞鼓励 | 看到老师点评（橙色「老师」标签）→ 可**回复**老师 |
| 管理 | 每条动态「删除」、每条评论「删除」（`wx.showModal` 二次确认） | ❌ 无删除入口 |
| 身份标识 | 评论 `role='teacher'` → 橙色名字 + 「老师」小标签 | 同上，视觉区分 |

> 数据模型：`feed[].comments[] = { id, name, role: 'teacher'|'student', text, time, replyTo }`。

### 13.2.1 角色边界（学生 / 老师能力分离）

同一 App 内角色切换，但**两端数据可见性严格隔离**，不允许互相污染：

| 能力 | 学生端 | 老师端 |
|---|---|---|
| 创建班级 | ❌ 无入口 | ✅ 班级页「＋ 创建班级」 |
| 加入班级 | ✅ 输邀请码 | —（老师不需要加自己的班） |
| 退出班级 | ✅ 详情底部「退出班级」 | —（老师解散班级为另一功能，v1 未做） |
| 可见班级集合 | `joinedClassIds`（我加入的） | `teacherClassIds` + 自建班（我教的） |
| 班级详情 | 班级老师 + 作业列表 + 退出 | 成员管理 + 待审批 + 邀请码 + 群发提醒 |

> ⚠️ 实现要点：`createClass` **不得**把新班级写入 `joinedClassIds`，否则老师自建的班会出现在学生端「我的班级」里（角色混淆 bug）。演示层用 `teacherClasses()` 过滤 `owner` 字段实现隔离。

### 13.3 数据模型补充（老师端）

```
student   = { id, name, classId, joinStatus:'in'|'pending', last30Rate }
assignment= { id, classId, subjectKey, title, desc, dueTime, file:{name,size,type}|null, needProof:bool, submitted:[studentId], total }
```
- 老师发布作业 = 写 `assignment` 集合；学生提交 = 在 `submitted` 追加 + 写 `checkin.images`。
- 学生加入审批 = `joinClass` 云函数写 `members`（in）或 `pending`（pending），老师端 `approve` 云函数转正。
- 进度 %、打卡率**服务端重算**；老师端接口需校验 `openid` 为该班级 `teacherOpenid`，防越权。

### 13.4 原型落地位置

老师端页面与交互已实现于 `教育机构打卡-原型-列表风.html`：在「我的」点身份切换（或右上角色药丸）切到老师端，底部 Tab 即变为工作台 / 班级 / 作业 / 我的。