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

6 Commits

Author SHA1 Message Date
lovife 7df078e0ea docs: 同步交接摘要 / PRD / 原型，并记录品牌改名「深学在线」 
- 交接摘要补 §一·三十五~§一·三十八：角色与授权、需求收敛（4 角色 / 10 菜单 / 取消二期）、
  PC 端重搭后的 UI 修复与卡片式基线、品牌改名与新标识
- PRD 与功能逻辑卷只改标题行与产品代号线；**文件名不动** —— verify-docs.py 按路径读，
  全库还有 20+ 处按文件名引用，改名会连带炸脚本
- 原型 index / admin-web / teacher-app / student-app 的品牌区改「深学在线」，
  admin-web 的 .mark（10 处）换成内嵌的新标 data URI，保持原型"单文件自包含"的约定
- 根 AGENTS.md 与 frontend-pc 的规范同步：接线检查补第 ⑨ 项（SVG 资产是不是合法 XML ——
  SVG 注释里出现连续两个减号就 not well-formed，图标裂开而控制台一句话都不报）、
  「最容易写错的约定」6 -> 7 条（新增品牌标）
- deploy/docker-compose.yml 只改头注释里的项目名（compose 的 name 与七牛对象前缀都没动）
 2026-10-10 16:49:04 +08:00
lovife d32969d766 feat(material): M1-04 材料项定义与内置模板 
发布前置校验里最后缺的一项（40018「未配置必传材料项」）终于能配了。
按计划表这一项是后端（4 人日），材料规则的界面属 M1-09。

交付：
· 材料项 CRUD（《03-接口设计》§7.10）：GET/POST /tasks/{id}/materials、
  PUT/DELETE /materials/{id}
· 三个内置模板（TPL_SCHOOL_ROLL / TPL_SOCIAL / TPL_ZHUANXIANG），幂等应用
· GET /material-catalog：材料码/档位/格式白名单/模板的静态清单，
  供界面下拉使用（接口是契约外的，理由见 Controller 注释：把这份常量在前端
  再抄一份会造成两份真相，而别名正是识别历史文件名用的）

落在代码里的三件事：
1) 默认值按两个维度分别取（MaterialCatalog）：
   · 按材料码定 名字/别名/默认压缩档/份数/是否合并
   · 按压缩档定 固定尺寸(P1)/长边下限(P2)/目标DPI(P3)/输出格式
   把份数塞进档位默认里是很容易犯的错 —— 那样所有 P2 材料都会变成"要传 2 份"，
   而"身份证要正反面"是这件材料的事实，不是档位的规则。
2) WORK_PROOF 的名字就是「工作证明」。机构模板里「职业技能等级个人申报表」
   的规范文件名就是「工作证明」，这是机构既有习惯，不要"修正" —— 改了会让
   导出包与该机构一直以来的归档口径对不上，带教老师只认这个名字。
3) 关联键是 (task_id, material_code)，不是 material_def_id（表里没有那个外键）。
   所以 40027「已有文件不可删」必须按码查 —— 用 id 查会永远返回 0，
   这道校验形同虚设，后果是"删了材料定义，文件成了孤儿"。

本轮修掉的 2 个真问题：
1) NOT NULL DEFAULT 与"档位不适用就置空"打架（同一类 bug 的第二次）：
   min_long_side（NOT NULL DEFAULT 1400）与 output_format（NOT NULL DEFAULT 'jpg'）
   在切档位时被写成 null，PostgreSQL 直接 500。而更根本的是：契约 §3.4 明确写着
   outputFormat 的 null = 保持原格式 —— 这一列本就不该是 NOT NULL。
   已由 V5__material_profile_params_nullable.sql 把四个档位参数统一成
   "不适用时为空"（另两个本来就可空），并同步更正两份 DDL 文档。
   ⚠️ 这与上一轮的 expected_count 是同一类问题：NOT NULL DEFAULT x 看起来无害，
   但它让"未设置/不适用"无法表达，而契约往往又要求能表达。
   动"可选数字/字符串"字段前，先查 information_schema.columns 的 is_nullable。
2) 我的两条 E2E 断言本身是坏的：
   · 把 lower_case 断言成"应被拒" —— 实际服务端把它规范化成 LOWER_CASE 后
     接受了，这是对输入友好的正确行为，错的是断言；
   · "改档位后参数跟着变"用了 P3，而 OTHER_PROOF 的默认档本来就是 P3，
     于是无论改没改都会通过（假通过）。
   教训：断言要能真的失败。

顺带整理：
· 抽出 support/NamingTemplate：任务级 naming_template 与材料级 name_pattern
  必须共用同一套校验规则。两处各写一套会出现"任务级认的变量材料级不认"，
  而这类不一致的表现是"发布时通过、导出时文件名叫错"，最难在测试里撞上。
  TaskService 已改为委托。
· materialTemplateId（契约里是 int64）不再空转：§7.10 的三个模板在文档与代码里
  都是具名常量，库里也没有"材料模板表"，拿 id 指代常量就得先造一张表放它们。
  新增 materialTemplateCode（字符串）承接内置模板，materialTemplateId 留给
  M1-05 的 collect_rule_template（那是真正的一行一条，id 才有意义）。

已知缺口（写进了代码注释与交接摘要）：
· minSizeKb 恒为 null：契约 §3.4 给了字段但"对应列"是 —，而《04》又用到
  materialDef.minSizeKb，两侧口径没对齐；且具体阈值属待办 D5「一寸照片阈值标定」，
  没有实测数据。编一个数会让它看起来"已实现"，卡住真材料时没人说得清为什么。
· 条件显示只做存取与形状校验，求值在填报引擎 M3-10。
· 40030（审核中不可删材料）属 M5，当前删除只查 40027。

验收：e2e-m1-materials.py 68/68；五条 E2E 合计 278 项断言全通过；
Flyway 迁移 1~5 全部 success。
 2026-09-29 09:42:08 +08:00
lovife 7523ebe789 feat(task): M1-02 覆盖班级与班主任配置 
补上发布前置校验的最后一环（40019），同时确立任务的数据隔离边界 ——
班主任能看到哪些任务、能审哪些单子，全由 collect_task_org 决定。

后端 GET/PUT /tasks/{id}/orgs（整体替换语义 + 软移除 + 历史行复用）；
前端「配置班级」抽屉：组织树只允许勾选班级，主班主任留空时显式提示
「将由该班负责人初审」而非留白。发布被拦时给出「去哪里补」的指引
（BLOCKING_HINTS），而不是只说"未设置覆盖班级"。

三条守住的规则：
1) 班级与初审人都必须在本租户内。跨租户的 id 一律当作"不存在或已删除"，
   不透露"它存在但不属于你" —— 漏了的后果是 A 校能把 B 校的班挂到自己
   的任务上，B 校的班主任就出现在 A 校的审批流里。
2) 初审人必须持有班主任/副班主任角色。指定初审人本质上是一次授权，
   那个人将能看到该班学生的身份证号与学籍材料；不校验角色就等于把
   "谁能看学生隐私"变成任意授权。报错要给出下一步，不能只说"校验失败"。
3) 移除是软移除（status=0），且「移除再加回」必须复用原行。
   后者不是优化而是必须：uk_task_org UNIQUE (task_id, org_id) 不带 status
   条件，一个班在同一任务下只能有一行，直接 insert 会违反唯一约束。

本轮修掉的 3 个真问题：
1) 我此前误判 uk_task_org 不存在 —— grep 只匹配含表名的行，而
   CONSTRAINT uk_task_org UNIQUE (task_id, org_id) 那行没有表名。
   基于这个错误前提，我写了一个多余的部分唯一索引 uk_task_org_active
   和一段基于错误前提的代码，已全部撤掉并更正注释。
   教训：查约束要看 CREATE TABLE 整块，不能只 grep 表名。
2) collect_task_org.expected_count 是 NOT NULL DEFAULT 0，与接口契约矛盾：
   DDL 注释说它是"由名册汇总"（系统算的），但《03-接口设计》§7.6 把它放在
   PUT 请求体里、说"用于与名册实际人数比对" —— 只有"管理员填的期望值 vs
   名册实际值"才需要比对。而 0 是有意义的业务值（"预期 0 人"），拿它兼职
   表示"没填"会让每个没填的班都触发"应填 0 人、实际 31 人"的假告警；告警
   变噪音就没人看了，真正"应填 28、名册却有 31"（名册导错）反而被漏掉，
   而这条告警的全部价值就在那一次。已由 V4 迁移改为可空 + 去掉默认值，
   并同步更正 docs/db/schema-postgresql.sql 与 PRD 里的内联 DDL。
3) 删掉迁移文件后必须 mvn clean，否则它会"复活"：我只跑 mvn package，
   target/classes 里的旧副本被打进 jar，Flyway 发现历史里没有 v4 就又执行
   了一遍 —— 索引回来了、历史行填回去了。之后又建了同名版本号的新 V4，
   于是"两个 v4"→"checksum 冲突"，排查绕了好几圈。

顺带修掉：
· 任务列表操作列从 3 个链接涨到 4 个，160px 会挤成竖排 —— 把「进度」并进
  「状态」列腾出 40px，操作列给到 200px，合计 820px（可用约 824px）。
· defineEmits 必须用函数调用签名（frontend-pc/.agents/skills/code-vue）。
  我此前写的 5 个组件都是被禁的 tuple 形式，一并改正：
  OrgFormModal / TaskFormModal / TaskOrgDrawer / UserFormModal / UserImportModal。
· e2e-m1-orgs.py 的清理抽成幂等的 cleanup_all()，并在 __main__ 的 finally
  里兜一次 —— 该脚本首次运行时崩在准备阶段、清理段没执行，把两个测试账号
  留在了库里（是在浏览器里看到下拉框里有个「E2E班主任」才发现的）。
  其余三条 E2E 脚本仍是老样子，下一轮一并改。

验收：e2e-m1-orgs.py 48/48（含跨租户隔离）；e2e-m1-task.py 71/71、
e2e-m0-user.py 55/55、e2e-m0.py 36/36 回归通过，共 210 项断言；
前端 typecheck / eslint / lint:style 0 错、build 通过；
浏览器实测抽屉的开合、树的勾选规则与保存落库。
 2026-09-29 09:32:48 +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 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
lovife 63aec55329 docs: 产品文档与交互原型（P1-P7 交付物） 
一期范围：学校收集 + 自主认定（4 类材料全部有实测样本）
- 主 PRD 190KB：125 条 FR / 21 条 VAL / 20 张表 DDL / 121 个接口
- 功能逻辑卷 88KB：不含代码模块
- 接口设计 116KB：58 个错误码 / 12 个 VO
- 核心模块设计：M1 命名 / M2 压缩 / M3 识别 / M4 门禁 / M5 校验 / M6 导出
- 开发任务拆解：100 任务 / 387 人日 / 15 周
- 验收测试清单：36 条 Golden 断言 / 111 条功能验收
- PostgreSQL DDL：已在 PG 16.15 实测零错误
- 交互原型 31 屏：学生端 11 / 班主任端 9 / 管理端 11
 2026-09-28 16:19:19 +08:00