docs: 同步契约 §6.5~6.9 / §13.4、问题清单 F-112~F-124、交接摘要 §一·三十九
1) docs/03-接口设计.md：
- §6.5 补 expireBefore **含当天**的语义与"格式不对返回 40001，不静默忽略筛选"；补
"列表 contactPhone 恒为 null"与"packageName 与内嵌 usage{} 不实现（200 行内嵌用量会变成
N+1 统计）"。
- §6.6 的 tenantType 由 3 值改回真实的 **4 值**（1 学校 / 2 认定机构 / 3 报名点 / 4 企业）、
packageId 由 ✅ 必填改为可选（DTO 里本来就是可选），并补副作用（发放 6 个内置角色 + 建管理员
+ 写 CREATE_TENANT 日志）。
- §6.7 的响应示例原来写着 ocrCount=3105 / smsCount=420，**与实现恒 0 矛盾** —— 改成 0 并补齐
契约没写的 notes 与 alerts.used/limit，再加三条口径：实时值 vs 周期、恒 0 的原因（编数字会让
运营拿假数据去谈续费）、**只算这一个租户**（含"库里只有一所学校时看不出"这一点）。
- **新增 §6.8 / §6.9**（PUT /tenants/{id} 与 GET /tenants/{id}）：PUT 此前只在 §4.2 的总览表里
出现过一次、全文**没有详情节**；GET 更是只登记在 §17.1 的"清单漏列"组里。§6.8 含字段表、
"不传的字段不修改"、"tenantCode 不可修改"的理由，以及留痕对照表（status→0 是 DISABLE_TENANT，
不是 UPDATE_TENANT）+ "这些日志行的 tenant_id 是 0，要用 target_type/target_id 查"的警告。
- §13.4 的 Query 补 targetType（并说明为什么 targetType+targetId 才是最重要的查询方式：
关键字全文匹配会把"改了它"和"顺带提到它"混在一起，而合规结论不能建立在这种匹配上）；
响应补 request_method / request_uri / extraJson；动作表由 9 行扩到**全集 27 个**并按来源分组
（任务 / 名册 / 导出 / 角色 / 租户）；写明 request_param / duration_ms 刻意不采集；
并记下"一期只做查询、不做日志导出"这条**此前只写在 LogController 类注释里**的口径
（导出等于把"谁在什么时候看了谁的身份证"这份名单落到本地磁盘，而导出行为本身也要留痕）。
- 登录日志响应补 tenantId，并写明 userType 的权威枚举与 location 恒为 null。
2) docs/08-完成度盘点与问题清单.md：新增 **F-112~F-124** —— 用量越界（含"为什么本地完全看不出来"）、
PUT 明文写入加密列、两个枚举能建不能改、租户零留痕、expireBefore 差一天、AUTO_CLOSE 字面量、
模块下拉里有死项、LogController 描述与事实相反、request_param/duration_ms 有列无写入点、
schema-postgresql.sql 缺三张表、**"平台专属权限码 + 查带 tenant_id 的表"这个风险面**、
登录日志缺租户列、userType 注释错位。F-112 标注为本轮最严重的一条。
3) docs/10-用户手册与客服话术.md：「三种角色，三个入口」→ **四种角色**（补平台运营，并写明它是
唯一跨单位的角色、用"组织与账号/收集管理"这类单位内页面之前要先选"当前学校"）；
§4 速查表的菜单名与路径同步（平台运维 → 日志，含两个页签；新增租户管理一行）；
附录的排查话术补 traceId（"日志详情里能拿到，那是后端排查时最有用的一个线索"）。
4) docs/交接摘要.md：新增 **§一·三十九**，九节 —— 一、口径变更（旧注释原文 + 推翻理由）；
二、用量越界那个 bug 的完整来龙去脉（权限码 → ignoreTable → 实测数据分布 → 修法与夹具）；
三、另外四条后端缺陷表；四、日志详情为什么不新增接口（轻字段 vs 全库 0 行有值的重字段）；
五、AUTO_CLOSE 与检查 ⑩ 的关系（**"这一族检查的价值取决于被检查的那一侧有没有被规范化"**）；
六、顺带修掉的五处；七、前端刻意用分段按钮而不是 NTabs 的两条原因；八、验证表 +
"改了后端必须重新打包重启、判据是看返回体里有没有新字段"的提醒；九、约定同步。
另把 E2E 断言总数 1595 → **1617**（四处）。
5) 根 AGENTS.md：接线检查说明补第 ⑩ 项，并写明做这一项时才发现 AUTO_CLOSE 是字符串字面量写的
—— "提成常量"是让这个检查真正生效的前提。
验证：python scripts/verify-docs.py **22/22**；python scripts/check-wiring.py 未接线 **0 条**
（⑦ 11 个权限码 / ⑧ 0 处漏 import / ⑨ 3 个 SVG 全合法 / ⑩ 27 个动作码两端逐字一致）；
python scripts/check-api-parity.py 契约 **119** / 已实现 118 / 缺口 1 —— **没变**，符合本轮
"不新增后端接口"的决定。
This commit is contained in:
+10
-3
@@ -8,17 +8,21 @@
|
||||
|
||||
---
|
||||
|
||||
## §1 三种角色，三个入口
|
||||
## §1 四种角色，四个入口
|
||||
|
||||
| 角色 | 入口 | 设备 | 主要做什么 |
|
||||
|---|---|---|---|
|
||||
| **学生** | 扫学校/班主任发的**二维码** | 手机（微信小程序 / H5） | 核对身份 → 填表 → 上传材料 → 提交 |
|
||||
| **班主任** | 微信小程序（同一套码，登录后进教师端） | 手机 | 看本班进度、审本班材料、代传、催报 |
|
||||
| **学校管理员** | 电脑浏览器打开管理端 | PC | 建任务、配表单与材料、导名册、终审、导出交付包 |
|
||||
| **平台运营** | 电脑浏览器打开管理端（账号**不用填单位编码**） | PC | 开通学校、改到期与联系人、停用学校、查全平台日志 |
|
||||
|
||||
**⚠️ 学生与老师的小程序是同一个**，靠账号角色区分。学生第一次要"核验身份"（填姓名+证件号），
|
||||
这一步就是**门禁**：名册里没有的人进不去（这是产品铁律，见 §5.1）。
|
||||
|
||||
**⚠️ 平台运营是唯一跨单位的角色**：它看的是**所有学校**的数据，所以在"组织与账号""收集管理"
|
||||
这类本来就是单位内的页面上，它必须先选"**当前学校**"（顶栏那个切换），选之前看到的是混在一起的。
|
||||
|
||||
---
|
||||
|
||||
## §2 学生操作手册
|
||||
@@ -199,7 +203,9 @@
|
||||
| 改学校/院系/班级结构 | 组织与账号 → 组织架构（也支持 Excel 导入） |
|
||||
| 加一个下拉选项（如多了种学历写法） | 配置 → 字典管理（**内置项不可改名**，要加就追加自定义项） |
|
||||
| 给某类人配一套能力范围 | 组织与账号 → 角色与授权（见 §4.5） |
|
||||
| 查"谁在什么时候看了证件号/导出了什么" | 平台运维 → 操作日志 |
|
||||
| 查"谁在什么时候看了证件号/导出了什么" | 平台运维 → 日志（「操作日志」页签，点某一行看详情） |
|
||||
| 查"某个账号什么时候登进来的、从哪登的" | 平台运维 → 日志 → 「登录日志」页签 |
|
||||
| 开通一所新学校 / 改到期日 / 停用学校 | 平台运维 → 租户管理（**仅平台运营可见**；停用前会二次确认） |
|
||||
| 查"通知到底发出去没有" | 收集管理 → 通知记录 |
|
||||
| 看某个任务的分班进度 | 工作台 → 数据看板（选一个任务） |
|
||||
|
||||
@@ -261,7 +267,8 @@ A：系统上限是 3 次（防反复折腾）。到上限后由班主任/管理
|
||||
3. **屏幕上的完整提示文字**（照抄，不要转述 —— 提示文案与错误码是一一对应的）；
|
||||
4. **发生时间**（精确到分钟）。
|
||||
|
||||
有了这四样，技术同学可以直接去「操作日志」与「通知记录」里定位。
|
||||
有了这四样，技术同学可以直接去「日志」（平台运维菜单，含操作日志与登录日志两个页签）
|
||||
与「通知记录」里定位 —— 日志详情里能拿到 `traceId`，那是后端排查时最有用的一个线索。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user