lab/docs/plans/2026-09-18-casbin-v3-notes.md

Casbin v3 笔记更新方案

范围

• 仅更新 note/随手记/casbin学习笔记.md，不修改项目 Go 依赖。
• 本文件记录方案；笔记实施前等待用户确认。

已核实依据

• GitHub 最新正式 release 为 v3.11.0（2026-08-20）。
• v3.11.0 的 module 仍为 github.com/casbin/casbin/v3，尽管源码仓库已迁移至 apache/casbin。
• 本次查询 Go proxy 的旧模块路径 @latest 返回 v3.10.0；不能将 GitHub 最新发布与代理解析结果混为一谈。
• 来源：https://github.com/apache/casbin/releases/tag/v3.11.0
• 来源：https://raw.githubusercontent.com/apache/casbin/v3.11.0/go.mod

实施顺序

1. 保留原有学习笔记结构，新增版本基线、v2 到 v3 的迁移注意事项与官方来源。
2. 修改示例 import；纠正 CSV 加载错误处理、上下文生命周期、Watcher/自动重载、延迟加载、ABAC 能力边界等过时或绝对化描述。不要把既有能力或新增示例误写成 v3 新能力。
3. 完善最小 RBAC 示例错误处理；检查差异、代码块和引用，条件允许时在临时目录验证示例，不修改仓库依赖。

职责与验收

• librarian：只读核实官方事实（已完成）。
• fixer：用户确认后仅实施目标笔记，编辑前确认编码和换行，保持原有中文笔记风格。
• 主会话：核对最终 diff 和关键事实，说明实际验证情况及外部依赖限制。

完成状态

• 已更新 note/随手记/casbin学习笔记.md（2026-09-18）：头部版本基线（v3.11.0、module path、官方来源、release 与 proxy @latest 区别）、三元组只是典型模型、g 的角色继承表述、SyncedEnforcer 并发与 matcher 编译缓存、adapter 表结构非核心标准、LoadPolicyArray/Line 校验责任、只读 adapter、ctx 生命周期与 ContextAdapter/ContextEnforcer、Watcher/Dispatcher/StartAutoLoadPolicy、快照时序保护与去性能硬承诺、最小示例改 /v3 并完整处理 error、ABAC 能力边界、govaluate 来源与 GetPolicy 签名、延迟加载顺序。
• 示例已抽取到 /tmp/opencode/casbin-v3-verify 独立 module（github.com/casbin/casbin/v3 v3.11.0）验证：go run . 输出 true false false；NewSyncedEnforcer(m) → SetAdapter(a) → LoadPolicy() 顺序 go run ./delayed 输出 delayed-load: true。
• 未改动仓库 Go 依赖，未提交 git；最终 diff 与事实由主会话复核。

精简方案（2026-09-18 二次修订）

• 目标：从 213 行压到约 60–85 行（原长度约 1/3），定位为中文概念速记，不是教程；不写/少写具体 API 使用方法。
• 保留：简短版本基线与 import 路径；“授权而非认证”一句话；PERM 四段简洁解释 + role_definition 扩展；核心组件 Model/Policy/Enforcer/Adapter/RoleManager/Watcher 职责表；一条判定链与 alice/admin/report/read 极短策略示意（无完整 Go 代码）；关键提醒（deny/error 均 fail-closed、并发优先 SyncedEnforcer、内存策略不自动跨实例同步、ABAC 不自动 SQL 过滤、迁移核对 adapter /v3 依赖）；2–3 条官方来源。
• 删除：加载入口对比、SQL 表结构、接口签名、CSV/context 细节、完整程序、只读消费与快照架构、MaxStale/性能讨论、proxy @latest 偏差等非核心展开及其历史修订细节。
• 约束：避免过度简化造成事实错误；不改代码与依赖；不提交；改动仅限本方案与目标笔记。