mp-pilates/docs/lesson-apparatus-feedback.md

按器械填写课后评价

教练从已完成课程详情的「为这次课写评语」进入，评价继续关联该预约与学员。成长档案的「寄语 → 写评价」也可以记录不关联课程的教练笔记。

• 保留整体评价，新增 M、R、TT、Chair、ARC、SC、LB 七项自由文本，每项最多 1000 字。
• 所有字段均选填；整体评价或任意一项器械有非空白内容即可保存。空白器械不入库、不展示。
• 按器械展开填写，收起保留摘要；保存失败保留当前输入，可重试。主动关闭时会提醒放弃未保存内容。
• 继续沿用「分享给学员」开关，默认关闭。学员只可读取已共享笔记。历史笔记无需转换。

部署

新增可空 MySQL JSON 字段 member_notes.apparatus_notes，迁移为 20261018100000_lesson_apparatus_notes。先在目标环境执行 pnpm --filter @mp-pilates/server exec prisma migrate deploy，重新生成 Prisma Client 并部署后端，然后发布小程序。此命令会部署目标库中所有尚未执行的迁移，应按现有发布流程核对。

本次迁移及服务端改动已与月卡周期功能一并部署生产。发布前纠正了原迁移误用 PostgreSQL JSONB 的问题，并在生产数据库的临时表上验证 MySQL SQL。详见 联合发布记录。新版小程序尚未上传或发布。

验收

1. 从一节已完成课程进入，仅填写 M、仅填写整体评价、填写多种器械，分别保存；检查关联课程、换行及各器械内容。
2. 所有输入为空或只有空格时不可保存。填满 1000 字，检查计数和输入上限。
3. 展开、收起、切换器械，检查内容摘要与填写数量；滚动至 LB，检查软键盘、输入框和底部按钮在微信 iOS / Android 的可见性。
4. 保存时连续点击不重复提交；断网保存后内容保留，恢复网络可重试；关闭未保存表单可选择继续填写。
5. 默认私密记录仅馆主可见，开启共享后学员端按器械分段展示；未填写的器械不显示，历史整体评价仍显示。

本地已验证共享包构建、前端类型检查、小程序构建、后端构建，以及完整 Jest 测试。本地浏览器组件预览用于验证展开、切换、填写计数、仅器械保存及分段展示；不替代微信真机验收。

单条评价分享

保存后自动进入评价详情页；档案内每条评价底部的「查看与分享」也可进入。教练页底固定「分享给学员」主按钮，避免长评价滚动后找不到操作。私密记录首次点击会确认开启该学员查看，再次点击调起微信转发；可随时关闭学员查看。

• 分享仅携带评价 ID，跳转 /pages/profile/lesson-feedback?id=...，不带管理员预览参数 userId。
• 分享标题与封面固定，不包含学员姓名、评价正文或页面截图。
• 学员详情接口 GET /user/progress/notes/:id 强制登录，并在同一次数据库查询中限定 JWT 学员 ID、评价 ID 与 shared=true。管理员打开学生分享链接同样没有跨学员读取权限。
• 教练预览和共享设置分别使用现有 ADMIN 权限控制下的 GET /admin/members/:userId/progress/notes/:id 与 PUT .../notes/:id/sharing；二者均限定目标学员与评价归属。共享修改仅接受布尔 shared。
• 详情响应设置 Cache-Control: private, no-store，仅返回展示所需内容。无权限、已删除、未共享统一返回 404，不泄露评价是否存在。
• 未登录先展示登录引导，登录后留在同一条评价；不显示任何姓名或正文预览。退出登录或页面进入后台时清除详情，返回页面重新请求和验证权限。
• 关闭共享后旧链接不再能从接口读取；已经阅读、截图或自行保存的内容不能远程撤回。

本次分享功能不新增表、字段或环境变量，沿用已部署的器械评价字段。

分享功能生产发布（2026-10-18）

• 功能提交：b2a785b（feat: share lesson feedback with owner-only access）。
• shared/server 构建、前端类型检查、微信小程序构建通过；完整 Jest 为 35 个套件、563 项全部通过。浏览器组件预览验证了详情布局、共享开关、无权限状态及登录后保留当前评价入口；微信原生转发仍需在新版小程序中验收。
• 已发布服务端并验证本机与公网健康检查均为 200，PM2 mp-pilates-server 在线且无异常重启。发布产物与运行目录逐文件比较一致。
• prisma migrate deploy 确认没有待执行迁移，15 个迁移均完成；migrate status 确认数据库为最新状态。本次不修改数据库结构。
• 42 项线上及真实 MySQL 检查通过，涵盖未登录、过期身份、学员归属、管理员打开学生链接、私密笔记隔离、共享参数校验、无缓存响应，以及开启、撤销共享后的读取。
• 真实 MySQL 写入验证在隔离事务内完成并主动回滚，未保留测试账号或评价，已有评价数量保持不变。未修改真实评价的共享状态。
• 备份与验证文件位于服务器受限目录 /usr/local/web/releases/combined-feedback-sharing-20261018-b2a785b/，包含已校验的完整数据库备份 database-before.sql.gz、旧运行包 previous-runtime.tgz、verification.json、迁移及启动日志。
• 发布包 SHA-256：e25ec285811883da920dedc720a223aebe1aacebd74ff101eee84bdc200b8832。

本次未上传或发布微信小程序。老师的分享按钮、评价详情页与学生打开分享链接的入口，需要发布当前小程序构建后才能使用。