# 按器械填写课后评价

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

- 保留整体评价，新增 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。详见 [联合发布记录](combined-release-2026-10-18.md)。新版小程序尚未上传或发布。

## 验收

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`。

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