fix(permission): clean dangling resource permissions

[FinleyGe]

变更内容

• 删除知识库及其子知识库时，在同一 MongoDB transaction 中同步删除对应资源权限
• 新增管理员权限清理接口，检查 team、成员、成员组、组织及 app、dataset、agentSkill 的悬垂或跨团队引用
• 清理接口默认 dry-run，支持 batchSize、maxScan、sampleLimit 和 cursor 断点续跑
• apply 模式删除前重新校验，并通过权限记录快照条件避免并发更新误删
• 将请求与响应 contract 统一为 global Zod schema

验证

• pnpm test:app：通过
• pnpm test:service：298 files passed，2 skipped；3636 tests passed，22 skipped
• 新增定向测试：6 passed
• ESLint、Prettier、git diff --check：通过
• app TypeScript 检查仅保留既有 sdk/storage/src/adapters/oss.adapter.ts 的 OSS.signatureUrlV4 类型错误

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	19.95%	1765 / 8847
🔵	Statements	19.94%	1855 / 9301
🔵	Functions	17.54%	372 / 2120
🔵	Branches	16.57%	833 / 5027

File Coverage

No changed files found.

Generated in workflow #1929 for commit c386160 by the Vitest Coverage Report Action

[github-actions]

✅ Admin Preview Image Ready!

ghcr.io/labring/fastgpt-pr:admin_c386160b551eff0100a5be6ee889995eaa30361f

🕒 Time: 2026-08-04 14:16:50 (UTC+8)

[github-actions]

✅ Build Successful - Preview fastgpt Image for this PR:

ghcr.io/labring/fastgpt-pr:fastgpt_c386160b551eff0100a5be6ee889995eaa30361f

🕒 Time: 2026-08-04 14:20:09 (UTC+8)

[c121914yu]

PR Review: fix(permission): clean dangling resource permissions\n\n## 需求理解\n本 PR 在知识库删除事务中同步删除 dataset 权限，并新增仅 root 可调用、默认 dry-run、支持批量扫描与 cursor 续跑的悬垂资源权限清理接口。主要涉及 dataset deletion、permission data-clean service、global Zod contract 和 admin API。\n\n## 逻辑验证\n- 正常删除：root dataset、子 dataset 的 dataset 权限被删除，其他资源类型、其他团队和未删除 dataset 的权限保留；定向测试通过。\n- dry-run：扫描、原因计数和 samples 返回正确且不删除；定向测试通过。\n- apply：仅删除悬垂权限，sampleLimit 生效；定向测试通过。\n- 并发修改：权限快照变化时不会误删；定向测试通过。\n- maxScan/cursor：多次调用可覆盖全部记录；定向测试通过。\n- API 默认 dry-run：定向 app 测试通过。\n\n## 问题汇总\n### 🔴 严重问题（0）\n未发现阻塞合并的功能或安全问题。\n\n### 🟡 建议改进（1）\n新增 API 的 contract 放置和 OpenAPI 注册不符合仓库 API 规范，详见行级评论。该问题不会影响当前运行时路由，但会导致 admin OpenAPI 文档遗漏接口。\n\n### 🟢 可选优化（0）\n无。\n\n## 做得好的地方\n- apply 模式在删除前重新校验，并用权限记录快照构造删除条件，降低并发更新误删风险。\n- 扫描有 batchSize/maxScan 上限，且使用 _id 游标续跑，避免一次性加载全表。\n- 资源引用按 ID + teamId 校验，能识别跨团队引用。\n- 默认 dry-run 和 root 鉴权符合高风险数据清理接口的安全边界。\n\n## 审查结论\n通过（有一项非阻塞规范建议）。GitHub CI 全部通过；本地新增 service 定向测试 5/5、app API 定向测试 1/1 通过。

[c121914yu]

🟡 API contract 未进入 OpenAPI 文档：仓库 API 规范要求对外路由的 request/response schema 放在 packages/global/openapi/**，并在 adminOpenAPIPaths 的 index 链路中注册。当前 schema 定义在 packages/global/support/permission/dataClean/controller.schema.ts，且 PR 没有新增对应的 admin path，因此生成的 Admin API 文档不会包含这个 root-only 清理接口。请将接口 contract（业务共用结构可保留在当前目录）迁移/包装到 OpenAPI 目录，并补充 path 注册；如果该路由有意不进入文档，也请在代码或设计中明确这是例外。