permix

Permix

当工作涉及 Permix 权限时使用此技能：包括定义、setup/check、SSR 水合、UI 适配器、服务器中间件、NestJS 守卫或 v3→v4 迁移。

快照：[email protected]（已于 2026-10-01 验证）。如果安装的版本不同，请根据 source-map.md 更新。

工作流

1. 检查本地 Permix 接口：
   • 软件包版本（优先使用 [email protected]；当前稳定快照为 4.3.0）。
   • 导入路径：permix（核心）还是子路径（permix/react、permix/next、permix/nest、permix/tanstack-start 等）。
   • 定义形式：操作元组 / { name, type, required? }，还是旧版 v3 { action, dataType }。
   • 权限检查运行的位置（服务器中间件 / Nest @Check 还是客户端 UX），以及是否使用 SSR 反序列化/水合。
2. 日常使用方法请先参考 usage-guide.md。
3. 如果版本不一致，或任务涉及迁移 / SSR / 集成特定事项，请更新文档。请从 source-map.md 开始。
4. 按需查阅更深入的细节：
   • 核心 API、规则、检查、模板、ReBAC、错误：core-api.md。
   • React/Vue/Solid/Svelte、Next、TanStack Start、水合：frameworks-ssr.md。
   • Express/Hono/Elysia/Fastify/Node/服务器/tRPC/oRPC/Nest/Drizzle/Effect：server-integrations.md。
   • v3→v4 破坏性变更：migration-v4.md。
5. 优先使用 Permix v4 API（点号路径、操作元组）。客户端检查仅用于 UX，必须在服务器端强制执行权限。
6. 通过类型检查以及针对性的 setup/check 测试进行验证（服务器集成时，还需测试中间件的 403 / Nest ForbiddenException 路径）。

核心判断

• 流程：createPermix<Definition>() → setup(rules) → check('entity.action'[, data])。
• 定义是操作列表（字符串或 { name, type?, required? }），也可以是嵌套树。
• 规则是布尔值或 (data?) => boolean 闭包（在 setup 时捕获操作者）。
• check 返回 boolean。使用回调实现 AND/OR；使用 '~all' / '~any'（或 'post.~all'）进行聚合检查。
• v4 中已移除 checkAsync —— 先 await isReadyAsync()，再调用 check()。
• 尚未设置任何规则时，check / dehydrate 会抛出 PermixNotReadyError（而不是 false）。
• 无效路径会抛出 PermixRuleNotDefinedError。
• template(...) 返回一个函数 —— 需要调用它：permix.setup(admin())。
• SSR：dehydrate() → JSON 布尔值（函数会变为 false）→ 客户端 hydrate → 函数规则必须再次调用 setup()；仅调用 hydrate 不会设置 isReady。
• 服务器：优先通过集成中间件 / Nest guard / Next cache() 使用每个请求各自的实例；不要在并发请求之间共享可变的核心单例。
• TanStack Start：使用 setupMiddleware（如果回调导入仅限服务器端的代码，则在 createMiddleware().server(...) 内使用 createSetupHandler）。Router 的 beforeLoad/loader 在 router context 上使用单独的核心实例，仅用于 UX。
• NestJS：permix/nest —— guard() 会为每个请求附加规则；@Check 负责强制执行（默认拒绝）。仅限 HTTP（Express/Fastify 适配器）。
• 安全性：必须在服务器端强制执行权限；仅使用客户端检查来隐藏 UI。
• 引擎：软件包声明 node: >=22。仅在导入相应适配器时才需要可选的 peer 依赖。

验证

优先使用仓库自带的命令。对于有实际意义的 Permix 工作，覆盖相关部分：

• 类型检查路径（$inferPath）、required: true 数据参数，以及共享的 ValidateDefinition / Rules。
• 单元测试：允许/拒绝、带数据和不带数据的实体数据规则、~all / ~any、回调组合、未就绪 / 缺少路径错误。
• SSR：反序列化快照形状；客户端水合 + 重新执行 setup；UI 中的 isReady 门控。
• 服务端：先执行 setupMiddleware，再执行 checkMiddleware——断言 200 与 403 / onForbidden。Nest：APP_GUARD + @Check → 201 与 403；缺少守卫 → PermixNotFoundError。
• TanStack Start：使用服务器函数中的 checkMiddleware / getOrThrow(context) 实施强制校验；仅靠 beforeLoad 检查还不够。
• 迁移：不再残留 check('entity', 'action')、checkAsync、Better Auth 插件，或同时包含 entity 和 action 的 UI 属性。

报告运行了哪些检查、哪些未运行，以及仍存在的任何版本假设。