fix: gate attachment uploads by project ACL

docs/LOCAL_DELIVERY.md

@@ -74,15 +74,18 @@ nb env auth nb-mcp
 
 默认只读。如需项目创建和更新，在参数末尾加入 `--enable-writes`。这些写工具只允许预先定义的项目字段，不提供删除或任意资源访问能力。
 
-附件上传需要可选的本机 HTTP 模式。它默认只监听 `127.0.0.1:10087`，不得暴露到局域网或公网：
+附件上传需要可选的本机 HTTP 模式。HTTP 服务默认只监听 `127.0.0.1:10087`；上传路由本身也默认关闭，不得暴露到局域网或公网：
 
 ```bash
 NOCOBASE_MCP_TOKEN='<随机长字符串>' \
+NOCOBASE_MCP_ENABLE_UPLOADS=0 \
   uv run nocobase-crm-mcp --transport streamable-http --config config.json
 ```
 
 Linux 用户也可以执行 `bash scripts/mcp_service.sh start` 安装用户级 systemd 服务。
 
+只有管理员确认该用户角色拥有 `t_projects` 的 create 或 update 后，才能在 `.runtime/nocobase-crm-mcp.env` 中设置 `NOCOBASE_MCP_ENABLE_UPLOADS=1` 并重新执行 `bash scripts/mcp_service.sh start`。即使已显式启用，MCP 仍会在每次上传前调用当前账号的 `roles:check`；无项目写权限时返回 `403 / nb_upload_forbidden`，不会调用 `attachments:create`。
+
 ## 权限验收
 
 交付前至少使用两个权限不同的测试账号验证：
@@ -91,8 +94,11 @@ Linux 用户也可以执行 `bash scripts/mcp_service.sh start` 安装用户级
 2. 使用相同参数调用 `list_customers`、`list_contacts`、`list_followups` 和 `list_projects`。
 3. 确认各自只能看到 NocoBase UI 中本人有权查看的数据。
 4. 对无项目写权限的账号调用 `create_project`，确认 NocoBase 拒绝。
-5. 对有写权限的账号创建测试项目，确认审计字段记录的是该用户，而不是共享服务账号。
-6. 退出或使 Token 过期后，确认 MCP 返回 `nb_auth_failed`，且不会降级使用其他凭证。
+5. 显式启用上传后，对无项目写权限的账号上传一个小文件，确认返回 `nb_upload_forbidden`，并用管理员确认附件记录数没有增加。
+6. 对有写权限的账号创建测试项目并完成上传、关联和移除，确认审计字段记录的是该用户，而不是共享服务账号。
+7. 退出或使 Token 过期后，确认 MCP 返回 `nb_auth_failed`，且不会降级使用其他凭证。
+
+修改测试账号角色后，如果 `roles:check` 仍返回旧角色，先由管理员执行 `nb api app clear-cache`，再重新执行 `nb env auth <环境名>`。这是服务端角色缓存刷新，不应通过共享 Token 绕过。
 
 ## 凭证安全
 
@@ -102,6 +108,7 @@ Linux 用户也可以执行 `bash scripts/mcp_service.sh start` 安装用户级
 - 不要共享操作系统账号运行 MCP；本机权限隔离依赖每位用户拥有独立的 `nb` 登录存储。
 - `NOCOBASE_MCP_API_TOKEN` 只为旧部署兼容保留，不用于终端用户交付。
 - `include_raw=true` 默认被 MCP 拒绝。只有在管理员审核 `config.json` 字段和 AI 数据使用政策后，才可在该用户本机设置 `NOCOBASE_MCP_ENABLE_RAW_DATA=1`。
+- `POST /uploads` 默认不存在。只有在管理员完成角色验收后才设置 `NOCOBASE_MCP_ENABLE_UPLOADS=1`；MCP 的项目写权限门禁是纵深防御，NocoBase ACL 仍是最终权限边界。
 
 ## 更新、回滚与恢复
 
@@ -148,4 +155,5 @@ bash scripts/mcp_service.sh start
 - `nb_auth_failed`：执行 `nb env auth nb-mcp`。
 - `NO_PERMISSIONS`：由 NocoBase 管理员调整该用户的角色、字段或行级数据权限。
 - 附件返回 `nb_upload_unauthorized`：重新登录后重试；不要把其他用户的 Token 写入环境变量。
+- 附件返回 `nb_upload_forbidden`：当前角色没有项目 create/update；不要为了绕过门禁而改用共享高权限账号。
 - 环境连接错误：执行 `nb env info nb-mcp`，确认 `apiBaseUrl` 指向目标环境的 `/api`。