lovife/xiaotutongxue
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
72 Commits 1 Branch 0 Tags
b516a7c47b6daf3a24d4326e3d85df115897b6d9
Commit Graph

7 Commits

Author SHA1 Message Date
lovife 1f3c485ceb feat(role,scope)!: 角色与授权可配 + 需求收敛（4 角色 / 10 菜单 / 删两模块） 
角色与授权（交接摘要 §一·三十五）：
- 权限判定合并两个来源：内置角色按代码（BuiltinRole）、自定义角色按库
  （sys_role_permission）。实现放 module 层的 DbRoleGrantSource，security 只依赖
  接口 RoleGrantSource —— 否则角色服务要调 permissionChecker，两个包迟早成环
- 权限判定必须加缓存：此前是零 IO，而压测基线是"SQL 条数恒定"。缓存放 Redis，
  空结果也缓存（否则已删角色的 token 会把库打穿）、Redis 挂了退化成直读库、TTL 只兜底
- V18 建 sys_role.user_type（账号的 user_type 一直从角色反推，自定义角色不在代码映射里）
  与 sys_role_menu；8 个接口 + 错误码 40045；契约 119 -> 129
- 内置角色只读（权限码是前后端契约，做成可改 = 一次误操作就能把管理员锁在系统外）；
  平台级能力两道防线（界面禁用 + 服务端 40301）；防自锁；改完立即生效（写授权清缓存）
- RoleProvisioner 从"已存在就 continue"改成幂等回填 + 每日 03:20 定时任务 ——
  修的是"代码改了权限、已开通租户永远停在发放那一刻"，这种漂移不报错也没测试会红
- scripts/e2e-m10-role.py 77/77

需求收敛（交接摘要 §一·三十六，本节的数字为准）：
- 删副班主任 / 审核员两个内置角色（6 -> 4）、历史整理器（module/cleanup）、
  加入申请（module/join + 学生端 pages/join）、collect_task_org.deputy_user_ids 整列；
  审核范围三级回退 -> 两级，连带 6 个 mapper 的 LIKE '%,id,%' 分支
- V19 迁移处理存量：先解 sys_user_role 绑定再软删角色；账号只在"除这两个角色外没有
  别的角色"时才软删。必须迁而不能只删代码 —— 角色码删掉后 mergePermissions 返回空集，
  存量账号会"能登录、处处 40301"，不抛异常不打日志
- 契约 129 -> 119、错误码 59 -> 54、权限码 30 -> 28、PC 菜单 12 -> 10、
  小程序页 10 -> 9、原型 32 -> 29 屏、E2E 39 -> 37 个（断言 1695 条）
- UserService.list 对不认识的角色码由"静默丢掉过滤条件"改成失败关闭
  （之前传个不存在的 roleCode 会返回全校账号，且看起来完全正常）
- 品牌元信息同步改名「深学在线」：pom 名称、/doc.html 标题、配置与启动类注释、
  存储自检探针内容；学生端 app 名与全局导航栏标题
 2026-10-10 16:48:54 +08:00
lovife 0bbac7d228 feat(pc,platform): 验收走查修复（平台按学校代管 + 菜单/403/日志范围/分页） 
客户在验收里点出来的问题，一次改完。两段改动：

一、平台运营与租户范围（后端为主）
- 新增请求头 X-Tenant-Id：平台运营是唯一跨租户身份，租户拦截器对它整体关掉了过滤，
  于是「组织架构 / 账号管理 / 工作台」拿到的是所有租户混在一起的数据 —— 而只有一所
  学校有数据时，它和学校管理员看到的完全一样，看不出错（这是最危险的一点）。
  现在这些页面必须先选定学校，服务端再把本次请求的租户上下文换成目标租户：
  只认平台身份（其它身份带头一律忽略）、目标租户必须存在且启用。
- OrgService.tree / UserService.list 补显式 tenant_id 条件（原来只靠拦截器，而拦截器对
  平台不生效）；TaskService.seesWholeTenant 改用新的 LoginUser.isPlatformStaff() ——
  isPlatformAdmin 回答"当前租户是不是平台租户"，代管时它为 false，会让平台退化成普通
  用户（任务列表掉进"班主任只看自己带的班"分支，得到空列表）；PLATFORM_ADMIN 补
  TASK_VIEW（PRD §3.2「查看填报进度看板：平台运营 ✅」）。
- 操作日志对平台永远是空的：SQL 写死 tenant_id = 当前租户，而平台的 tenantId 是 0。
  按契约 §13.4 补 tenantId 参数与 log:viewAll：平台默认看全量、可指定某所学校；
  学校管理员恒为本租户，传别家返回 40301（不静默忽略，否则会让人以为"筛过了"）。
- 开放接口"推送重试"从未生效（F-112）：定时扫描缺 @InterceptorIgnore，异常被 log.warn
  吞掉；同一方法里"接入方已停用"那条 update 也没有租户上下文，会每 10 秒重试到永远。
  E2E 补了"真的重试了"的断言（原来只断言"安排了下次重试"）。

二、PC 端走查体验
- 去掉 3 条无用菜单（名单管理 / 表单设计器 / 材料规则）：功能都在「收集任务」行内入口，
  菜单里那一条点进去只有指路；后端菜单键同步删除，entryAt 那套机制一并删掉。
- 班主任点工作台必弹 403：工作台无条件调了要 org:view / progress:viewAll 的两个接口。
  403 走 HTTP 状态码，try/catch 拦不住它的弹窗 —— 改成按权限决定发不发请求。
- 操作日志：分页器被裁在可视区外（新增 .g-list-card 让表体自己滚、表头钉住、分页器留在
  卡片底部）+ 去掉页面上那段免责声明；收集任务的状态切换改成单独一行 tab；去掉顶栏假数据
  铃铛；配色按客户要求还原。

顺带修两处"检查器自己不严"：check-wiring 新增第 ⑦ 项（PC 端引用的权限码必须存在于
PermissionDef —— 本轮我自己把 progress:viewAll 写成 progress:view:all，判断恒为 false，
而编译 / typecheck / lint / E2E 全都不红）；verify-docs 的表格列数检查不再把 GFM 转义
竖线当成列分隔符。两个检查器都拿"故意写错的样例"试过，确认真的会红。

验证：typecheck / mvn package / check-wiring（未接线声明 0 条）/ verify-docs（22 项）全过；
e2e-m0 36、e2e-m1-orgs 48、e2e-m0-user 55、e2e-m5-logs 44、e2e-m5-notify-wiring 43、
e2e-m1-tenant-domain 6、e2e-m8-open 61 全绿；浏览器按角色逐个真点复验。
详见 docs/交接摘要.md §一·三十三 与 §一·三十四。
 2026-10-09 17:29:20 +08:00
lovife 9911ff01f1 feat(submit): 提交 + 红黄绿校验（PRD §5.7 的 VAL 系列） 
一次给全，不"改一条再拒一次"：学生一次可能同时缺 3 项材料、2 个字段没填，
逐条拒绝会让他改 5 次提交 5 次。所以 validate 收全部问题后一次性返回
{ruleCode, severity, title, detail}，ruleCode 用 PRD 的 VAL-xx 编号。

两段式提交：只有黄色警告时先返回 submitted=false 让学生确认，
再带 confirmWarnings=true 才真的提交。为什么不前端自己判断 ——
只有服务端的校验结果算数，两次请求之间学生可能又改坏了什么。

实现的规则：VAL-01 证件号 / VAL-05 材料完整性 / VAL-06 格式 /
VAL-07 体积 / VAL-08 清晰度 / VAL-09 重复文件 / VAL-13 报考三项 /
VAL-15 补考科目数按等级 / VAL-16 在校生三项 / VAL-17 工作年限 /
VAL-18 未规范化 / VAL-20 体积下限 / VAL-22 表单必填（**新增**：
PRD 的 VAL-01~21 是具体业务规则，没覆盖动态表单的必填字段，按系列顺延补的）。

═══ 本轮抓到的四个真问题（都记在代码注释里了）═══

① **校验器不能用列名当字段 key**。字段 key 是 snake_case
   （work_unit / job_level / enroll_date），不是列名；而且报考三项
   存在 ext_json 里、**不是独立列**（契约 §2.4）。写 camelCase 的表现是
   "明明填了却说没填"。更糟的是 VAL-16 读列、VAL-22 读表单装配值 ——
   **两条规则对同一份数据给出相反结论**，学生不知道该信哪一条。
   现在统一用 FillService.getForm 装配出来的那一份作为唯一取值口径。

② **VAL-22 没判可见性**。不判可见就会要求一个在校生填「补考理论」——
   而那个字段在他页面上根本不存在。求值口径已与前端 fill.vue 的 visible()
   逐字对齐（norm 归一 true/false↔1/0、未知 op 一律可见）。

③ **VAL-01 读错了列**：collect_roster.id_card_no 是 **AES 密文**
   （列注释写明的），明文只在导入与门禁时短暂存在。一开始拿它算校验位，
   于是每一份填报单都被判"身份证号未通过校验" —— 100% 阻断。
   这种"规则很对但读错列"的错，反而容易被当成"校验太严"而不是 bug。
   现在只确认名册里有证件号（用脱敏列），校验位交给导入与门禁。

④ **静态资源没有 Cache-Control/ETag**（新增 StaticCacheHeaderFilter）。
   没有它浏览器会走启发式缓存：旧 index.html → 旧 chunk →
   **学生发版后看到的是上个月的页面**，而开发机硬刷新一次就没了，
   极容易被当成"偶发"。现在 /assets/** 一年 immutable（文件名带内容哈希）、
   *.html no-cache（每次校验）、/api/** no-store。

排查过程里还确认了一件事：材料上传那轮的"浏览器加载旧 chunk"
不是构建问题 —— 从 8080 下载的 chunk 与磁盘文件 SHA-256 一致、里面确实有新代码，
是缓存头缺失导致的浏览器行为。

验收：e2e-m3-submit.py **30/30**（含"该拦的确实拦了"和"修好后确实放过"）。
回归：草稿 27 / 门禁 29 / 材料上传 29 / 材料目录 68 全绿。
 2026-09-29 12:39:16 +08:00
lovife 15b819746b feat(mp): M3-01 门禁核验（名单是闸门） 
M3 的第一块：学生必须先过名单核验，才能开始填报任何东西。

交付：
· POST /api/v1/mp/roster/match（§5.4）—— 姓名+证件号与名册匹配，命中才放行并绑定
· common/util/IdCardUtil —— 身份证校验位（三态裁决）
· support/ClientIp —— 取真实调用方 IP（限流用，X-Forwarded-For 第一段）
· module/roster/entity/CollectRoster —— 名册实体（M2 会继续用）

四条守住的规则：
1) 失败提示必须统一（40007），不区分"姓名错"还是"号码错"。
   分开提示等于交付了一个身份证号枚举器：用任意姓名+目标号码试，
   若提示"姓名不对"就说明号码在名单里，一个个试就能把全校号码试出来。
   这不是体验取舍，是安全底线。E2E 专门断言两种失败的 msg 字符串完全一致。
2) 绑定并发安全：UPDATE ... WHERE bind_user_id IS NULL + 看影响行数。
   不要改成"先 SELECT 判空再 UPDATE"——中间有窗口，两人会同时通过检查，
   后绑的人静默覆盖先绑的人，而先绑的学生之后再也进不去。
   E2E 用两个线程同时冲同一行，断言"恰好一个成功、一个 40072"（实测 [0, 40072]）。
3) 证件号明文只在 match() 里出现一次，失败日志只记 HMAC 与 uid（日志被翻出来
   同样是泄露）；响应里永远只有 idCardMask，E2E 断言整个响应 JSON 不含明文。
4) 已绑定自己的人重复核验是幂等的 —— 学生刷新页面不该看到"该信息已被登记"。

IdCardUtil 的价值在三态而不在对错：
   真实数据集实测：名册 28 人校验位全通过（可信基准）；某两个学生的文件名证件号
   校验位失败（确定是号码错，可自动改正）；另一学生的两个号码都通过（是两个真人，
   串档实锤，必须人工介入）。后两种看起来都是"号码对不上"，处理策略却完全相反——
   一个能放心自动修，另一个自动修就是把两个真人的材料合并。区分它们的唯一办法
   就是校验位。所以对外暴露 Verdict{VALID,CHECKSUM_FAILED,MALFORMED} 而非 boolean。

   1900 年下界是业务判断，不是国标要求：网上流传的"示例有效身份证号"里有一批
   出生年份在 1800 年代（如常被引用的 440524188001010014 → 1880 年），它们校验位
   合法但不可能是认定考生。只算校验位会把它们判成 VALID。这个坑写 E2E 时真踩到了。

E2E 怎么拿 token：门禁要求已登录的学生，而登录（/mp/login）需要真实的 wx.login
code，脚本拿不到。所以用 dev 配置里的 JWT 密钥自己签一个 MP token（HS512，
claims 与 JwtService.issue 同构）—— 与 e2e-m0 用 dev RSA 公钥加密登录密码是同一类
做法：用开发配置里的凭据手搓测试夹具，不是绕过认证逻辑。prod 密钥不在仓库里，
这个手法自然失效。顺带：读配置要读两个文件，issuer 在主 application.yml 里，
只读 dev 会漏掉它，而症状是 401，完全指不到"配置没读到"。

回归抓到我一条脆断言：
   e2e-m1-qrcode.py 的"token TTL 是 7000 秒"在连续第二次运行时失败（TTL=4633，
   正好是两次运行的时间差）——它假设 token 是刚取的，实际沿用了缓存。
   已改成"先清缓存强制重取，再断言 TTL∈[6900,7000]"，连跑两次都稳定通过。
   教训与前面几次同类：断言要确定性地反映被测行为，而不是碰巧在某种顺序下通过。

已知缺口（写进交接摘要）：
· /mp/login 未做：它需要真实 wx.login code，脚本测不了，只能在小程序里测，
  下一轮连同小程序核验页一起做。
· 形近字候选（FR-504c）未实现，needConfirmName 恒为 false。
· 名册导入未做（M2），E2E 用 SQL 直接造名册行。
· 小程序端还没有核验页（落地页的「开始填报」目前是明确的"开发中"提示）。

验收：e2e-m3-gate.py 29/29（含并发绑定与限流）；
九条 E2E 合计 418 项断言全通过。
 2026-09-29 10:46:21 +08:00
lovife 8480f431ba feat(user): 账号管理（CRUD、Excel 导入、改密）并修掉 5 处缺陷 
后端补齐 /users 全套（列表/新增/修改/软删/启停/重置密码/批量导入）与
PUT /auth/password；前端加「组织与账号 → 账号管理」一屏（左组织树 + 右列表、
新增编辑弹窗、导入体检报告、初始密码只显示一次的强确认）。

验收：e2e-m0-user.py 55/55；e2e-m0.py 回归 36/36；typecheck 0 错、build 通过。
账号管理页已在浏览器肉眼确认（首屏与切页均可见、数据与分页正确）。

本轮修掉的 5 个真问题 —— 都不是功能没做完，而是做完了但错的：

1) 学校租户也发放 PLATFORM_ADMIN 角色行
   学校管理员在新增账号时传 roleCodes=[PLATFORM_ADMIN] 就能造出带
   tenant:manage 的账号，而 /tenants 只校验权限码、不校验是否真在平台租户下
   → 任何学校管理员都能开通租户、拉全平台租户列表（租户级越权到平台级）。
   RoleProvisioner 不再给非平台租户发该角色行 + 服务端按租户白名单校验。

2) UserUpsertReq.username 的 @NotBlank 对修改也生效
   PUT /users/{id} 永远返回 40001，且明细只说存在阻断性校验问题，
   看不出是登录名 —— 改账号功能整体不可用。去掉该注解，
   必填性改由 UserService.create 判定。

3) Main.vue 的 <transition appear>
   首次渲染被当成一次过渡，元素被加上 zoom-fade-enter-from（opacity:0）后
   永不清理 → DOM 内容齐全、接口数据正常、文字可选中，但整块内容区肉眼不可见。
   极易误判成页面没渲染而往路由/接口方向排查。去掉 appear。

4) assertAnotherAdminExists 在停用/删除路径上不可达
   能调这两个接口的人自己必然是活跃管理员，所以除目标外还有管理员恒成立；
   而真正会锁死租户的路径 —— 把管理员改成普通角色（目标可以是操作者自己）——
   当时没有拦。补 losingAdminRole() + UserMapper.countAdminRoles()，
   并在方法注释里写明哪条路径真生效、哪条只是防御性的。

5) sys_user.user_type 有两套互相冲突的枚举
   DDL/实体注释写「1教师/管理员 2填报人(学生) 3社会人员」，而权威契约
   （03-接口设计 §2.7）与 BuiltinRole.UserType 是
   「1平台运营 2学校管理员 3班主任 4学生」—— 2 和 3 完全错位。
   后果：userType=3（班主任，最高频的账号）被当成社会人员（二期）直接拒掉，
   建班主任账号会失败；前端还把学校管理员显示成填报人（学生）。
   改法：后端从角色反推用户类型再比对；新增 V3 迁移更正库注释
   （V1 已应用不能改，Flyway 会校验 checksum）；更正 PRD 与 schema DDL 的同一行；
   前端「用户类型」从手选改为由角色推导，从根上消除矛盾组合；
   E2E 加 3 条回归断言锁住这个语义。

顺带修掉：
  · components/index.ts 里 6 个指向已删组件的悬空导出（构建不报错、用到才炸）
  · tsconfig 的 lib 停在 ES2020 而代码用了 Array.prototype.at
  · 两处 .at() 的空值风险（useBreakpoint / useTabsStore）
  · dashboard 的 userStore.menus 拼错，导致平台判断恒为 false
  · http.ts 里两个永不命中的错误码常量
  · 账号列表的 fixed 列缺 :scroll 配置，会浮在其它列上面
  · .gitignore 补 __pycache__

新增脚本：
  · scripts/e2e-m0-user.py            账号管理 55 项验收（含越权与自锁的负向断言）
  · scripts/dev-clean-test-users.py   清理 E2E 残留的测试账号
 2026-09-28 22:25:01 +08:00
lovife 87ece5a971 feat(frontend): 管理端改用 Gi Admin Pro 框架 + 腾讯云主题 
前端此前只有本地实现、从未入库，本次首次纳入版本管理。

框架切换
  · 以 Gi Admin Pro（Vue3 + Vite + TS + Arco Design Vue + Pinia）为底
  · 剥离 14 个演示页面目录 / 121 个文件（demo 28、file 20、form 19、system 18…）
  · 依赖 dependencies 35 → 19，devDependencies 31 → 27
  · 保留框架核心：layout、Gi* 组件库、hooks、权限指令、错误页、登录页

主题：腾讯云 / TDesign 官方色板
  · 主色 #0052D9（腾讯蓝）、成功 #00A870、警告 #ED7B2F、危险 #E34D59
  · 页面底色 #f3f3f3、文字 rgba(0,0,0,90/60/40/26%)
  · 覆盖 Arco 底层色板 + 显式语义别名（primary/success/warning/danger/link/neutral）
  · 三个改了不生效也不报错的坑已记入注释：
      1) Arco 色值是逗号分隔 RGB 三元组，不是 #RRGGBB
      2) Arco 把色板定义在 body 而非 :root，必须写 `:root, body`
      3) setting.json 的 themeColor 会以内联样式写进 body，优先级高于样式表

对接后端（三处契约差异在 @/utils/http 统一适配）
  · 响应信封 {code,msg,data} → {code,success,message,data}
  · Token 头 token → Authorization: Bearer
  · 分页 {list,total} → 补一份 records，list 原样保留
  · 40101 → 登录页；登录密码 RSA 加密（公钥走 /auth/public-key，轮换无需重建前端）
  · 路由：后端只下发菜单键，前端在本地路由表上过滤（有哪些页面归代码，谁能看归后端）

已实现页面（浏览器实测通过）
  · 登录：RSA 加密 + 自适应验证码/租户码 + 账号锁定提示
  · 工作台：真实数据（组织 6 个 / 角色 1 个 / 权限 25 项）
  · 组织架构：三级树 + CRUD + 占用校验
  · 租户管理：开通租户 + 初始密码只显示一次的强确认
  · 待建页：未实现菜单显示所属里程碑
  · 权限菜单：学校管理员看不到「租户管理」

视觉资产按腾讯云主题重做
  · logo.svg（渐变圆角方 + 填）、favicon.svg（小尺寸做减法）、login-hero.svg（材料归集）
  · 登录页点阵纹理走主题变量，换主色自动跟随
  · 文案改为产品实际能力：自动改名 / 强制压缩 / 隐私保护

清理模板遗留（约 17MB + 三处外部依赖）
  · 百度统计脚本（上报到 gi-demo 作者的统计账号）
  · 用户菜单「项目地址」（跳转模板作者的 Gitee 仓库）
  · 两份 8.8MB mp3、388KB favicon.ico、57KB 模板插画、未引用字体与 loading.gif
  · 「个人中心」指向已删除的 /system/account（点了 404）
  · 头部头像在无 avatarUrl 时渲染成裂图 → 改为姓名首字兜底

后端修复
  · 新增 GET /auth/public-key（前端加密登录密码用）
  · DataSeeder.ancestor_path 生成错误：子节点本该是 /16/17/ 却写成 /17/
    该字段是「按院系统计」的索引，错了会漏人/多人且不报错 —— 改为从库里读父节点路径
  · seedDemoOrgs 曾放在租户作用域外 + admin 早退分支之后，导致启动失败 / 永不执行
  · 示范租户补一套三级组织树（1 学校 / 2 院系 / 3 班级），供界面演示
 2026-09-28 20:49:55 +08:00
lovife 9d7a8ca845 feat(m0): 后端骨架 + 账号体系（M0 验收 36/36 通过） 
技术栈（已在 4.1.1 上实测跑通，非纸面选型）
  Java 21 + Spring Boot 4.1.1 + MyBatis-Plus 3.5.17(boot4) + PostgreSQL 16.15
  + Redis 7 + Flyway 12.4 + springdoc 3.1.1；前端定 Vue 3 + Element Plus + uni-app

交付内容
  M0-01 基础设施     deploy/docker-compose.yml（PG + Redis + MinIO，容器名与端口避让本机既有项目）
  M0-02 后端骨架     xt-common + xt-server；统一响应 / 全局异常 / 58 个错误码 /
                     多租户拦截 / 软删除 / 字段自动填充 / AES-GCM / HMAC 索引 / RSA / JWT
  M0-05 租户        开通租户（一次完成建租户 + 发 6 个内置角色 + 建首个管理员）、列表、详情
  M0-06 组织        CRUD + 组织树 + ancestor_path 自动维护 + 占用校验
  M0-07 PC 登录     RSA 解密 + 图形验证码 + 失败锁定 + 等时比较防账号枚举 + 审计日志
  M0-08 登出/当前用户  Token 黑名单（存 SHA-256，TTL 到自然过期）
  M0-01 数据库      Flyway 2 个迁移 → 26 张表（20 业务 + 5 标准 + 1 迁移记录）

安全姿态
  · 租户拦截器【默认拒绝】：匿名请求触及租户表直接抛 40101，不做「不加条件放行」
  · 权限码定义在代码里（PermissionDef / BuiltinRole），不建 sys_permission 表，杜绝前后端漂移
  · 匿名接口只靠 @PublicApi 放行，不做路径白名单，避免两套机制各说各话
  · 账号不存在时也跑一次 BCrypt（假哈希），拉平响应时间防枚举
  · 登录密码 RSA 传输，防止网关/APM 把明文密码记进日志

脚本
  scripts/sync-ddl.py          文档 DDL → Flyway 迁移，带 --check 防漂移
  scripts/e2e-m0.py            M0 验收 36 项，可进 CI
  scripts/verify-docs.py       文档一致性（接口数【逐节】核对、错误码、跨文档数字、表格列数）
  scripts/dev-login.py         RSA 加密登录助手
  scripts/dev-clean-e2e.py     清理 E2E 测试数据

文档修正（实测暴露，非人工审查）
  · DDL 缺陷：sys_tenant.contact_phone / sys_user.phone / collect_roster.phone
    原 varchar(20) 按明文长度建，装不下 AES-GCM 密文（约 52 字符），改 varchar(128)（PRD V2.4）
  · 错误码 40007b/40007c 带字母后缀与「code 为数字」的约定冲突，规范化为 40071/40072
  · 07-开发实施计划 新增 §9 版本兼容踩坑记录（10 条实录）与 §10 M0 完成情况
 2026-09-28 17:28:21 +08:00