docs(academic): AC-14 收尾——权限码清单导出 + divide 注释更正 + 种子注释

internal/academic/handler/divide_handler.go

@@ -19,7 +19,14 @@
 //
 // 两张表都是**全局推广体系**（推广关系不归属某个机构），数据层无法按机构过滤 ⇒ 防线只有两条：
 //  1. `scope.FromFiber` 必须存在（取不到 → 1001，避免匿名读全平台分账数据）；
-//  2. 端点角色白名单（AC-14 落 RBAC）：预期 `super_admin / finance / market`。
+//  2. 端点角色白名单（AC-14 落 RBAC，**以契约 §2.3 为唯一权威**）：
+//     端点 38~42 → `super_admin, academic`；端点 43（分账流水列表）→ `super_admin, academic, finance`。
+//
+// ⚠ **曾经写错的一处**：本文件原写"预期 `super_admin / finance / market`"，与契约 §2.3 冲突。
+// `market` 是**旧系统角色残留**（`t_role` 字典里的历史角色码，新系统 6 个角色码见契约 §1.7，
+// 不含 `market`）；按旧写法落种子会得到一条**没有任何角色命中**的白名单 + 一条多余策略，
+// 症状是"分账树对 academic 报 1003"（看起来像 RBAC 没配，实际是这里写错）。
+// 已按契约改正；`RoleMarket` 常量仍保留（路由表角色拼写校验用），但**不得**再出现在本域白名单里。
 //
 // 这也是它与其他端点的本质差异：**分账树是跨机构的，不存在"本机构分账树"**。
 package handler

internal/academic/handler/seed.go

@@ -1,5 +1,16 @@
 // RBAC 种子生成器（AC-14）——**从路由表生成，不手写清单**。
 //
+// ⚠ 两条已验证的结论，改这里之前先读：
+//
+//  1. casbin 路径必须用 Fiber 的 `:param`，不能用 `*`。
+//     keyMatch2 里 `*` 会展开成 `.*`（**跨 `/` 匹配**），`/admin/activities/*`
+//     会把 `POST /admin/activities/1/sign` 也放行 = **提权**。
+//     反证见 TestRBACSeedEnforcedByCasbin：`teacher POST /admin/activities/9/sign` 必须为 false。
+//     ⚠ 既有 /org 种子用的是 `*`，是否存在同样的跨段放行**尚未核实**，已登记待 S3 核。
+//
+//  2. 种子从路由表生成、不要手写清单。
+//     本批 40 端点，第二批还有 20 个；手写必漏，症状是"接口从 404 变成 403"，比 404 更难查。
+//
 // 依据：unified/03-migration/academic-domain-design.md AC-14 行（"种子幂等 + 与路由表 1:1 对齐"）/
 // `01-architecture/casbin-rbac-design.md` §6（casbin p 规则种子写法：`dom=*`、`keyMatch2` 路径、
 // `regexMatch` 方法、`INSERT IGNORE` 幂等）/ `02-data-model/core-model-ddl.sql`（三张表的既有种子格式）。