xiaotutongxue

lovife/xiaotutongxue

Fork 0

Commit Graph

Author	SHA1	Message	Date
lovife	5de9ccc100	feat(fill): 草稿保存（§9.3 / §9.4） POST /mp/submissions 取草稿（幂等）+ PUT /mp/submissions/{id} 保存草稿。学生填了一半能存下来，再打开还在。四条守住的规则： 1) 填报单必须属于调用者 —— 这个条件写进 SQL 的 WHERE（selectMineById），不是"查出来再判断"。后者一旦判断漏写就是越权。 2) 锁定字段服务端再拒一次：前端已经渲染成只读，但请求可以伪造，而「报考工种」被改错的后果是机构直接不受理。两层防护里只有服务端这层是真的。 3) 改动留痕（changed_fields）：老师填的值被学生改过要记下来 —— 审核时看到的是一个数字，无法判断该找谁（老师填错找老师，学生改错直接驳回）。 4) 已提交的填报单不能直接改，要先撤回。本轮修掉的 4 个真问题（全是"不报错但结果错"的类型）： 1) changed_fields 是 jsonb，我当 varchar 用了。存了逗号分隔字符串， PostgreSQL 报 `invalid input syntax for type json`，而错误信息里的 "Token xxx is invalid" 完全指不到是这一列。已改为存 JSON 数组。 ⚠️ 这已经是第三次被"列的真实类型与我的假设不符"咬到（前两次：expected_count NOT NULL、min_long_side NOT NULL）。教训：写列之前查 information_schema 的实际类型，不要只读 DDL 文档。 2) changed_fields 把没动过的字段也标成"改过"。原因是我拿"提交表的列值" 和"名册值"比，而锁定字段的列永远不写初值、姓名/证件号/电话根本没有列 —— 全都读成 null，于是全被判成"改过"。留痕一旦充满噪音，真正的改动就没人看了。已改为：排除锁定字段（按定义不可能被改）与没有列的字段。 3) 学生自己填的"非预填字段"根本没被读回来。我的合并只遍历了"名册有的键"，于是在读学校填了、保存成功、再打开却没了。已改为按表单字段全集遍历，并明确三种情形：动过的预填字段用草稿值（空也算，那是清空）、自己填的用草稿值、其余用名册值。 4) 建草稿时没做初值，导致三种状态无法区分（从没动过 / 改成了别的 / 清空了）—— 列值都是 null。表现是改动判不出、清空会被名册值顶回来。已在建草稿时把名册值写入"可改的预填字段"做初值，状态就自明了。顺带修正一处字段目录与 DDL 的真不一致：表单定义把「联系电话」标为可改（PRD 把它列在「预填可改」里），但 collect_submission 没有 phone 列 —— 学生改了没地方存。一期先设为只读，并在代码里写明要真正开放修改需要加一列。不用"前端允许改、后端悄悄丢掉"糊过去 —— 那会让学生以为改成功了，实际提交的还是老号码。另一处实现选择修正：锁定字段（报考职业/工种/等级）要写进提交单。它们恰恰是最重要的统计维度（按工种统计报名人数），不落列就统计不出来 —— 而架构约束正是"内置字段落列才可统计"。写进去还带来一个好处：它是提交时的快照，老师之后改了名册，这份单子仍记得"他当时报的是四级"。顺带修 E2E 的两条过时期望（回归抓到的）： · 写死了 127.0.0.1，而 H5 应用地址已改成穿透域名 → 改为从配置读期望值； · fragment 改成 hash 路由格式后，token 解析没跟上。验收：e2e-m3-draft 27/27、e2e-m3-gate 29/29、e2e-m3-h5-auth 23/23。	2026-09-29 11:41:40 +08:00
lovife	6e7597531a	feat(mp): M3-02 H5 微信网页授权（公众号 OAuth）方向决定了 H5 优先：资质门槛低得多、且前端可自动化测试。小程序端代码不浪费 —— uni-app 一套代码多端，build:h5 直接出 H5。交付： · GET /mp/h5/authorize —— 生成微信授权地址（公众号 appid，snsapi_base 静默授权） · GET /mp/h5/callback —— code 换 openid → 找/建学生 → 下发会话 → 302 回 H5 · GET /mp/h5/stub-login —— 【仅开发/测试】跳过微信授权的登录，供自动化测试 · fill.mp-h5 配置段（公众号凭据）关键事实：H5 必须用公众号的 appid —— 网页授权与小程序码是两套凭据、两套接口，不能混用。所以配置分成 fill.mini-program（小程序码用）与 fill.mp-h5（网页授权用）。授权流程的三处设计： 1) token 放在 URL 的 fragment（#）里，不放 query。fragment 不发给服务器 —— 不会进 Nginx access log、不会进 Referer、不会进浏览器历史。放 query 等于把 token 写进四五处日志。 2) scene 不裸放在 state 里，而是存 Redis 用一次性随机串指代 —— state 会进 URL、浏览器历史与日志，放业务参数容易被人拿来构造请求。 3) 回调必须"永远重定向回应用"，绝不抛业务错误。那是浏览器直接跳转的地址，抛错用户看到的是一屏 {"code":40001,...} JSON —— 一个学生完全无法理解、也不知道该怎么办的画面。打桩（为了自动化）与四道约束：微信授权那一步必须真人在微信里点，脚本永远做不了，所以要有打桩；而打桩是危险动作 —— 一个"跳过微信授权"的开关漏进生产就是 "任何人可登录任何学生"的后门。约束： ① 配置开关默认 false，只有 dev 打开； ② 代码里再判一次 profile 不含 prod（配置写错也进不来，双保险）； ③ 接口路径独立（/mp/h5/stub-login），不是"真实回调里加个 if"—— 那种写法一旦判断写反就是灾难； ④ 每次调用都 WARN 日志，不留静默通道。本轮修掉 2 个真问题： 1) RoleProvisioner.bindRole 在匿名请求下不可用：它内部走 MP 的 BaseMapper，插入时租户拦截器拿不到 tenantId、直接抛「未登录」。症状是 500 且角色没建上（用户建了却没角色，后面每个接口都会以"无权限"拒绝他，排查毫无头绪）。已改为自己写：@InterceptorIgnore + 显式 tenant_id。 2) 授权回调抛业务错误 → 用户看到一屏 JSON。已改成 try/catch 后重定向回应用，把 e.getMessage() 作为 authError 带上（那句话本来就是写给人看的）。 E2E 实测：用户看到的是「网页授权换 openid失败：code 无效或已使用过（code 只能用一次，且 5 分钟过期）（微信原文：40029 invalid code...）」。 ⚠️ 上线前必须解决：H5 与小程序是两个 openid 同一个人的小程序 openid 与公众号 openid 是不同的（不同 appid 各自签发），只有 union_id 一致 —— 而它需要两个账号都绑到同一个微信开放平台账号。后果：学生先用 H5 填、后来又用小程序填，系统当成两个用户，第二个渠道撞 40072（已被登记）。一期只走 H5 不会碰到，但两条腿都上线前必须解决（按 union_id 认人）。已知缺口： · H5 核验页未做（落地页的「开始填报」仍是"开发中"提示）。 · H5 桌面全宽铺开，该加 max-width 居中。 · 真实微信授权未走通：需要公众号后台填「授权回调页面域名」+ 域名解析到能跑服务的机器（或内网穿透）。打桩跳过的是微信那一步，后面全走真逻辑。 · /mp/login（小程序登录）仍未做，可与 H5 授权共用 resolveUser。顺带确认：frontend-mp 的 build:h5 已能出 H5 产物，已在无头浏览器里跑通「URL 带 scene → 读 scene → 跨域调后端 → 显示学校/任务/状态」， CORS（后端早已配 localhost:*）也通。这条是选 H5 的核心收益：前端交互层可自动化验证。验收：e2e-m3-h5-auth.py 22/22；受影响的四条回归全绿（落地页 31 / 门禁 29 / M0 账号 55 / 二维码 32）。	2026-09-29 11:00:18 +08:00

Author

SHA1

Message

Date

lovife

5de9ccc100

feat(fill): 草稿保存（§9.3 / §9.4）

POST /mp/submissions 取草稿（幂等）+ PUT /mp/submissions/{id} 保存草稿。
学生填了一半能存下来，再打开还在。

四条守住的规则：
1) **填报单必须属于调用者** —— 这个条件写进 SQL 的 WHERE（selectMineById），
   不是"查出来再判断"。后者一旦判断漏写就是越权。
2) **锁定字段服务端再拒一次**：前端已经渲染成只读，但请求可以伪造，
   而「报考工种」被改错的后果是机构直接不受理。两层防护里只有服务端这层是真的。
3) **改动留痕**（changed_fields）：老师填的值被学生改过要记下来 ——
   审核时看到的是一个数字，无法判断该找谁（老师填错找老师，学生改错直接驳回）。
4) 已提交的填报单不能直接改，要先撤回。

本轮修掉的 4 个真问题（全是"不报错但结果错"的类型）：

1) **changed_fields 是 jsonb，我当 varchar 用了**。存了逗号分隔字符串，
   PostgreSQL 报 `invalid input syntax for type json`，而错误信息里的
   "Token xxx is invalid" 完全指不到是这一列。已改为存 JSON 数组。
   ⚠️ 这已经是第三次被"列的真实类型与我的假设不符"咬到
   （前两次：expected_count NOT NULL、min_long_side NOT NULL）。
   教训：**写列之前查 information_schema 的实际类型，不要只读 DDL 文档。**

2) **changed_fields 把没动过的字段也标成"改过"**。原因是我拿"提交表的列值"
   和"名册值"比，而锁定字段的列**永远不写初值**、姓名/证件号/电话**根本没有列** ——
   全都读成 null，于是全被判成"改过"。留痕一旦充满噪音，真正的改动就没人看了。
   已改为：排除锁定字段（按定义不可能被改）与没有列的字段。

3) **学生自己填的"非预填字段"根本没被读回来**。我的合并只遍历了"名册有的键"，
   于是在读学校填了、保存成功、再打开却没了。已改为按**表单字段全集**遍历，
   并明确三种情形：动过的预填字段用草稿值（空也算，那是清空）、
   自己填的用草稿值、其余用名册值。

4) **建草稿时没做初值，导致三种状态无法区分**（从没动过 / 改成了别的 / 清空了）——
   列值都是 null。表现是改动判不出、清空会被名册值顶回来。
   已在建草稿时把名册值写入"可改的预填字段"做初值，状态就自明了。

顺带修正一处**字段目录与 DDL 的真不一致**：
   表单定义把「联系电话」标为可改（PRD 把它列在「预填可改」里），
   但 collect_submission **没有 phone 列** —— 学生改了没地方存。
   一期先设为**只读**，并在代码里写明要真正开放修改需要加一列。
   不用"前端允许改、后端悄悄丢掉"糊过去 —— 那会让学生以为改成功了，
   实际提交的还是老号码。

另一处实现选择修正：锁定字段（报考职业/工种/等级）**要写进提交单**。
   它们恰恰是最重要的统计维度（按工种统计报名人数），不落列就统计不出来 ——
   而架构约束正是"内置字段落列才可统计"。写进去还带来一个好处：
   它是**提交时的快照**，老师之后改了名册，这份单子仍记得"他当时报的是四级"。

顺带修 E2E 的两条过时期望（回归抓到的）：
   · 写死了 127.0.0.1，而 H5 应用地址已改成穿透域名 → 改为从配置读期望值；
   · fragment 改成 hash 路由格式后，token 解析没跟上。

验收：e2e-m3-draft 27/27、e2e-m3-gate 29/29、e2e-m3-h5-auth 23/23。

2026-09-29 11:41:40 +08:00

lovife

6e7597531a

feat(mp): M3-02 H5 微信网页授权（公众号 OAuth）

方向决定了 H5 优先：资质门槛低得多、且前端可自动化测试。
小程序端代码不浪费 —— uni-app 一套代码多端，build:h5 直接出 H5。

交付：
· GET /mp/h5/authorize —— 生成微信授权地址（公众号 appid，snsapi_base 静默授权）
· GET /mp/h5/callback —— code 换 openid → 找/建学生 → 下发会话 → 302 回 H5
· GET /mp/h5/stub-login —— 【仅开发/测试】跳过微信授权的登录，供自动化测试
· fill.mp-h5 配置段（公众号凭据）

关键事实：H5 必须用**公众号**的 appid —— 网页授权与小程序码是两套凭据、两套接口，
不能混用。所以配置分成 fill.mini-program（小程序码用）与 fill.mp-h5（网页授权用）。

授权流程的三处设计：
1) token 放在 URL 的 fragment（#）里，不放 query。fragment 不发给服务器 ——
   不会进 Nginx access log、不会进 Referer、不会进浏览器历史。
   放 query 等于把 token 写进四五处日志。
2) scene 不裸放在 state 里，而是存 Redis 用一次性随机串指代 ——
   state 会进 URL、浏览器历史与日志，放业务参数容易被人拿来构造请求。
3) 回调必须"永远重定向回应用"，绝不抛业务错误。那是浏览器直接跳转的地址，
   抛错用户看到的是一屏 {"code":40001,...} JSON —— 一个学生完全无法理解、
   也不知道该怎么办的画面。

打桩（为了自动化）与四道约束：
   微信授权那一步必须真人在微信里点，脚本永远做不了，所以要有打桩；
   而打桩是危险动作 —— 一个"跳过微信授权"的开关漏进生产就是
   "任何人可登录任何学生"的后门。约束：
   ① 配置开关默认 false，只有 dev 打开；
   ② 代码里再判一次 profile 不含 prod（配置写错也进不来，双保险）；
   ③ 接口路径独立（/mp/h5/stub-login），不是"真实回调里加个 if"——
      那种写法一旦判断写反就是灾难；
   ④ 每次调用都 WARN 日志，不留静默通道。

本轮修掉 2 个真问题：
1) RoleProvisioner.bindRole 在匿名请求下不可用：它内部走 MP 的 BaseMapper，
   插入时租户拦截器拿不到 tenantId、直接抛「未登录」。症状是 500 且角色没建上
   （用户建了却没角色，后面每个接口都会以"无权限"拒绝他，排查毫无头绪）。
   已改为自己写：@InterceptorIgnore + 显式 tenant_id。
2) 授权回调抛业务错误 → 用户看到一屏 JSON。已改成 try/catch 后重定向回应用，
   把 e.getMessage() 作为 authError 带上（那句话本来就是写给人看的）。
   E2E 实测：用户看到的是「网页授权换 openid失败：code 无效或已使用过
   （code 只能用一次，且 5 分钟过期）（微信原文：40029 invalid code...）」。

⚠️ 上线前必须解决：H5 与小程序是**两个 openid**
   同一个人的小程序 openid 与公众号 openid 是不同的（不同 appid 各自签发），
   只有 union_id 一致 —— 而它需要两个账号都绑到同一个微信开放平台账号。
   后果：学生先用 H5 填、后来又用小程序填，系统当成两个用户，
   第二个渠道撞 40072（已被登记）。一期只走 H5 不会碰到，
   但两条腿都上线前必须解决（按 union_id 认人）。

已知缺口：
· H5 核验页未做（落地页的「开始填报」仍是"开发中"提示）。
· H5 桌面全宽铺开，该加 max-width 居中。
· 真实微信授权未走通：需要公众号后台填「授权回调页面域名」+ 域名解析到能跑服务的
  机器（或内网穿透）。打桩跳过的是微信那一步，后面全走真逻辑。
· /mp/login（小程序登录）仍未做，可与 H5 授权共用 resolveUser。

顺带确认：frontend-mp 的 build:h5 已能出 H5 产物，
已在无头浏览器里跑通「URL 带 scene → 读 scene → 跨域调后端 → 显示学校/任务/状态」，
CORS（后端早已配 localhost:*）也通。这条是选 H5 的核心收益：前端交互层可自动化验证。

验收：e2e-m3-h5-auth.py 22/22；受影响的四条回归全绿
（落地页 31 / 门禁 29 / M0 账号 55 / 二维码 32）。

2026-09-29 11:00:18 +08:00

2 Commits