feat(knowledge): 支持普通成员按授权访问知识库并维护文档

[774098632]

变更说明

普通成员即使命中知识库的共享管理范围，仍受管理员菜单、路由和 API 依赖限制，无法进入知识库维护文档。本 PR 复用现有 version 2 共享范围，让成员按授权访问知识库，并把文档编辑与整库管理分开。

• 任务类型：feature。
• 目标：普通成员可读取获授权知识库；命中 manage 范围后可上传、导入自己的工作区文件、解析、索引和维护该库文档与文件夹。
• 非目标：新角色或权限迁移、整库所有者转移、任务授权体系，以及 Agent、测试设计、提示词和 Skills 改造。
• substantial：改变用户权限、公开读取入口和文件副作用，需要后端授权、对象隔离、真实集成及前端上下文回归。

工程主张与 Owner

• resource_permission.py 拥有用户/部门/全局范围判断，knowledge_permissions.py 与 HTTP 路由拥有操作授权。响应分别返回 can_edit_documents 和 can_manage；前端按能力展示操作，后端最终裁决。
• 普通编辑授权作用于该库全部文档，包括他人上传的文档。整库创建、配置、共享授权、删除、连接凭据、图谱/导图管理、评估写入、URL 导入和全局任务管理仍受管理员边界保护。
• 读取授权覆盖文档、检索、下载、既有图谱/导图，以及该库评估数据和结果的读取接口。普通成员的页面隐藏评估管理 Tab；隐藏 UI 不作为 API 授权依据。
• Manager、响应序列化与图谱状态投影拥有凭据脱敏。非整库管理者的响应移除嵌套凭据和模型认证请求头，保留分块参数与模型预算；可访问摘要对所有角色脱敏。管理员且具有该库 manage 权限时，详情和图谱状态保留可编辑配置。持久配置与实际模型运行参数不变。
• 文档 executor 拥有目标库对象引用和删除归属校验；KnowledgeFileRepository.upsert() 拒绝跨库 ID 碰撞。HTTP、PostgreSQL、MinIO 原件/派生对象及 worker 最终状态是观察边界。
• database.js 与文件表格、上传、搜索组件拥有当前身份/库的界面投影；切库、会话或授权失效后清理旧载荷，迟到响应不能覆盖新上下文。
• 决策记录：知识库普通成员的授权访问与内容维护。本功能从已实现的独立变更适配至上游 main，记录实际方案、替代项、代价与当前验证，直接提供 implemented 决定供评审。

验证情况

本地验证使用基于上游 main 的独立工作树、全新 Compose 状态和合成数据，直接回读 schema 为 business 9 / knowledge 2。Embedding 使用本地确定性 HTTP stub；HTTP、JWT、PostgreSQL、MinIO、Milvus、解析和索引 worker 均为真实链路。

成员文档编辑与管理员操作边界

• 失败面：角色上限、单库授权和读/写依赖。
• 语义 Owner：资源权限解析、知识库权限依赖、知识库和评估路由。
• 直接证据 / 命令：最终权限、响应与图谱 unit 集合 170 passed；pytest test/integration/api/test_knowledge_router.py::test_delegated_knowledge_content_permissions -q，3 passed。编辑流程回读上传原件字节、parsed/indexed、正文、文件夹改名、移动及删除后列表。
• 负向案例：未授权拒绝读取、只读拒绝写入；普通编辑拒绝整库配置、整库删除、图谱管理、评估写入及 URL 导入。
• 结果：Passed。

凭据投影保持隔离，持久配置与运行参数不变

• 失败面：详情、可访问摘要及图谱状态暴露嵌套模型认证信息。
• 语义 Owner：knowledge/utils/security.py、响应序列化与 MilvusGraphService。
• 直接证据 / 命令：上述最终 170 项集合包含 test_knowledge_content_delegation.py 的 read_projections_remove_nested_credentials 参数化案例，12 passed，覆盖三出口和四身份；额外真实 HTTP 探针验证编辑者、读取者和管理者的九种出口，PG 配置读取前后保持不变。
• 负向案例：仅将上游旧脱敏实现绑定回隔离测试容器时，10 项因嵌套凭据保留失败；管理员管理详情和图谱状态 2 项仍成功。覆盖任意网关请求头、嵌套数组、accessToken，并保留模型 token 预算及 chunk_token_num。
• 结果：Passed。

文档操作不能破坏外库原件或覆盖外库记录

• 失败面：上传对象引用、单删/批删及全局文件 ID 主键碰撞。
• 语义 Owner：知识库文档 executor、KnowledgeFileRepository。
• 直接证据 / 命令：pytest test/integration/api/test_knowledge_document_storage_isolation.py -q，4 passed；pytest test/integration/repositories/test_knowledge_file_upsert.py -q，2 passed。最终修复后的三组集成共 9 passed、0 skipped。
• 负向案例：编辑者和管理员单删、批删外库引用后，HTTP 下载与 MinIO 回读保留外库原件；本库记录、原件及派生物按归属清理。跨库 ID 碰撞被拒绝，PG 原行及更新时间不变；同库更新成功。
• 结果：Passed。

前端能力展示与旧上下文隔离

• 失败面：切库、身份变化、权限失效、上传队列和迟到写响应。
• 语义 Owner：Store、文件表格、上传和搜索组件。
• 直接证据 / 命令：pnpm run test:unit，445 passed，无失败/取消/跳过；Web lint/build 通过。真实浏览器验证普通编辑者与只读账号、同一成员切至只读库、文件夹上传模式、浅/深色及 900px 视口。
• 负向案例：实际组件和 Store 回归验证上下文失效后旧参数、队列、工作区导入及迟到响应不能继续原操作；只读页面无上传或删除操作，普通成员无 URL 模式与整库配置入口。
• 结果：Passed。

通用回归、格式和工程契约

• 失败面：其他后端 unit、格式、文档链接及构建。
• 语义 Owner：pytest、Ruff、ESLint、Vite/VitePress 与工程信任检查。
• 直接证据 / 命令：Linux 容器 pytest test/unit -m 'not slow' --timeout=90 -q -p no:cacheprovider，2,551 passed；此集合执行在补充嵌套凭据案例前，最终受影响集合另为上述 170 passed，两者不相加。python scripts/verify_engineering_contracts.py、python -m unittest scripts.test_verify_engineering_contracts（63 tests）、21 个受影响 Python 文件 Ruff lint/format、Web lint/build、docs build、git diff --check 全部通过。
• 负向案例：SSR 按钮替身转发上游 a-button 属性，保持整库配置入口的权限断言；其他负向边界见各验收组。
• 结果：Passed。

简化 / 删除验收

不涉及。

独立语义 Review

不继承开发上下文的全新 Reviewer 审查完整需求、上游完整 diff、权限/持久化/对象副作用、前端实际组件、公开文档与最终证据。发现并修复嵌套模型凭据投影问题，补充三出口负向案例及真实 HTTP/PG 回读。最终完整暂存树与合成截图审查后无未解决的 P1/P2。Review 结论不代替测试证据。

未验证范围与风险

• Not run：真实模型质量、Dify/RAGFlow 等第三方知识库端到端、真实外部 OAuth 和生产部署。本地确定性 Embedding 验证权限/协议/索引链路，不能证明检索质量。
• Inspected：现有 CI 会覆盖 backend/Web unit 等 gate，但当前 system-tests 工作流没有选择上述三组知识库集成文件；本 PR 的 9 项集成证据来自独立本地真实拓扑。
• Not run：本 PR 的 GitHub CI 结果在创建后产生。
• Windows 本地解释器无法收集依赖 POSIX os.O_DIRECTORY 的后端测试；后端结果来自 Linux 容器。
• 已有 manage 范围会立即授予其中普通成员该库全部文档的编辑和删除能力，包括全局/部门范围。管理员需检查当前授权是否符合编辑意图。

事故反馈

本 PR 处理成员文档维护功能缺口，未确认达到高影响生产事故门槛。评审发现的嵌套凭据边界以直接反例、响应 guard 和回归测试闭合。

界面变更

真实页面截图仅使用隔离环境中的合成账号、知识库与文档，不含客户数据或凭据。

普通编辑者可维护文档，整库配置/评估管理入口隐藏：

同一共享库对普通只读账号隐藏写操作：

普通成员的上传模式包含文件、文件夹、个人空间：

编辑成员切到只读库，深色 900px 页面保留可访问的只读操作与横向表格滚动：

关联事项

Closes #1094

补充说明

不新增权限枚举、数据库 schema 或依赖。复用 version 2 的 read/manage 范围，并在角色与操作边界区分文档编辑和整库管理。客户端需使用 can_edit_documents 判断文档维护能力，can_manage 表达整库管理能力。