toc家庭学习工作台-MaoDou Studio

1、立项背景和目标：
面向家庭教育场景，解决家长布置/批改作业依赖微信群、纸质记录零散、孩子学习安排不直观的问题。目标是打造一个家长与学生深
度绑定的学习工作台，覆盖作业流转、课程表、待办、消息通知的全链路。

2、软件功能与核心模块：
（1）家庭绑定：家长生成6位家庭码，学生输入即绑定，支持多子女管理；
（2）作业流转：语文/数学/英语/其它四类模板，支持草稿-发布-提交-通过/打回订正的完整状态机，语文英语支持Excel批量导入；
（3）互动学习：英语单词卡3D翻面+挖空默写、语文生字卡默写、数学答题自动校对+解析讲解+大题拍照上传；
（4）消息中心：家长学生私信互发、系统通知、消息撤回与软删除；
（5）日程管理：月历视图统一展示课程与待办，支持课程有效期设置。

3、业务流程与功能路径：
家长生成家庭码→学生绑定→家长布置作业（手动/Excel导入）→学生端实时收到→学生互动作答并提交（图片/音频/录音附件）→家长端
实时出现待批改提醒→批改通过或打回→学生收到消息订正重交。全程基于Supabase
Realtime实现多端秒级同步，数据由PostgreSQL行级安全（RLS）保障家庭隐私隔离。

1、整体架构与设计思路：
前端采用 Next.js 14（App Router）+ TypeScript + Tailwind CSS + shadcn/ui，分层架构（components通用组件 /
features业务模块 / hooks / lib / types），按家长端、学生端、消息、导入等领域拆分features；后端采用 Supabase
全家桶（Auth认证、PostgreSQL、Storage对象存储、Realtime实时推送），全部数据访问由数据库层 RLS
行级安全策略约束，前端零自建服务端。

2、我负责的模块和结果：
独立完成从架构设计、数据库建模（9张表、13个迁移）、前后端开发到部署上线的全部工作：实现作业状态机、家庭码原子绑定（sec
urity definer函数）、英语单词卡/语文生字卡/数学自动校对三套互动学习器、消息软删除与撤回机制、附件存储90天pg_cron自动清
理；通过28项端到端冒烟测试（覆盖注册触发器、RLS越权边界、作业全流转），最终部署于Netlify并完成线上全链路验收。

3、遇到的难点、坑和解决方案：
（1）Supabase联表查询依赖自动生成的外键提示名不稳定，导致关联字段返回null——改为两步查询（先取ID再批量查档案）彻底规避
；
（2）React Query跨账号缓存污染导致换账号串数据——在登录/登出环节强制清空内存与localStorage持久化缓存；
（3）Realtime同名channel冲突导致页面崩溃——为每个订阅实例生成唯一topic；
（4）存储桶upsert覆盖触发RLS拦截——改为时间戳唯一文件名纯插入方案；
（5）列表查询等待用户资料造成两轮串行请求瀑布——去掉门控、改用本地session解析，首屏请求数减半，配合预取与骨架屏优化首开
体验。