Browse Source

docs: add attachment access control design for privacy

Document prefix-based MinIO policy, admin JWT file proxy, and
mobile local-only preview for feedback/suggestion attachments.

Co-authored-by: Cursor <cursoragent@cursor.com>
wuzilong 2 months ago
parent
commit
2c7869fb0b
1 changed files with 138 additions and 0 deletions
  1. 138 0
      docs/superpowers/specs/2026-09-09-attachment-access-control-design.md

+ 138 - 0
docs/superpowers/specs/2026-09-09-attachment-access-control-design.md

@@ -0,0 +1,138 @@
+# 附件访问控制设计(纪检隐私)
+
+**日期:** 2026-09-09  
+**状态:** 待实现  
+**范围:** `backend`、`web-admin`、`mobile-wx`
+
+## 1. 背景与目标
+
+纪检业务附件含隐私。当前 MinIO bucket `ajyy` 若整桶匿名可读,知链即可下载,不满足安全要求。
+
+**目标:**
+
+| 对象 | 访问规则 |
+|------|----------|
+| 二维码配置图片(`qrcode/*`) | 允许匿名可读(公示张贴、移动端展示) |
+| 在线反馈 / 建言献策附件 | **禁止**匿名读 |
+| web-admin | 必须登录;经后端 JWT 代理拉流查看/下载 |
+| mobile-wx | 仅上传界面用**本地临时文件**预览;不依赖远程可读 |
+
+## 2. 已定决策
+
+- 管理端访问方式:**后端鉴权代理**(非预签名直链)
+- Bucket 策略:**同一 bucket,按前缀分流**(非双 bucket)
+- 库表:继续存现有 `url` / objectKey 形态,**不迁表**
+
+## 3. 方案对比(摘要)
+
+| 方案 | 说明 | 结论 |
+|------|------|------|
+| **1(采用)** | `qrcode/*` 公开;其余私有;管理端 JWT 代理;移动端本地预览 | 采用 |
+| 2 | 整桶私有,二维码也走公开代理 | 二维码多一跳,无必要 |
+| 3 | 管理端短时预签名 | 与「代理 + 审计」决策不符 |
+
+## 4. 存储与权限
+
+### 4.1 MinIO bucket policy
+
+- **允许**匿名 `s3:GetObject`,Resource 限定:`arn:aws:s3:::ajyy/qrcode/*`
+- **撤销**整桶 `ajyy/*` 匿名可读策略
+- 后端启动 `_ensure_bucket` 时写入上述前缀策略(幂等覆盖)
+
+### 4.2 上传 folder 约束
+
+| 场景 | folder | 接口 |
+|------|--------|------|
+| 二维码图片 | 固定 `qrcode` | 仅管理端 `POST /api/web/admin/attachment/upload` |
+| 在线反馈附件 | 固定 `feedback` | 公开 `POST /api/public/attachment/upload` |
+| 建言献策附件 | 固定 `suggestion` | 公开上传同上 |
+
+- 公开上传:**白名单**仅 `feedback`、`suggestion`;拒绝其它 folder(含 `qrcode`)
+- 管理端二维码上传:使用 `qrcode`;管理端若上传其它业务附件,不得依赖匿名读
+
+### 4.3 数据存储
+
+- 业务表 `attachments` JSON / `image_url` 仍存服务端返回的 `url`(完整 MinIO URL 或等价 object 地址)
+- 私有对象匿名 GET 返回 403 即可;无需改写历史 URL 字符串
+
+## 5. 管理端鉴权代理
+
+### 5.1 接口
+
+```
+GET /api/web/admin/attachment/file?url=<库内存储的附件URL>
+```
+
+- **鉴权:** JWT;与反馈/建言**详情接口一致**,使用 `get_current_user`(任一已登录后台用户)。页面入口仍由菜单 `feedback` / `suggestion` 控制;本期不额外叠加 `require_menu`,避免比详情接口更严导致「能看详情却打不开附件」
+- **校验:** 从 `url` 解析 objectKey,必须属于当前 `MINIO_BUCKET`(或 local `/uploads/` 前缀);拒绝外链、空参数、路径穿越;**拒绝**代理 `qrcode/*` 以外也允许,但二维码前端不走此接口
+- **响应:** `StreamingResponse`;`Content-Type` 按扩展名推断;`Content-Disposition: inline`
+- **审计:** 应用日志记录操作者、时间、objectKey(本期不强制新审计表)
+
+Local 存储模式:代理从 `LOCAL_STORAGE_DIR` 读文件,同样需登录。
+
+### 5.2 web-admin UI
+
+- **反馈详情:** 附件不再用裸 MinIO `<a href>`;点击后用带 Authorization 的请求取 blob,再 `URL.createObjectURL` 打开/预览
+- **建言详情:** 补齐附件列表展示,走同一打开逻辑
+- **二维码配置:** 继续直链 `imageUrl`(`qrcode/*` 公开),不走代理
+
+## 6. 移动端本地预览
+
+### 6.1 预览
+
+- 选文件后生成本地预览:
+  - H5:`URL.createObjectURL(file)`
+  - 小程序/App:`tempFilePath`
+- 缩略图 / 文件展示只用 `previewUrl`,**禁止**用远程 MinIO `url` 作为 `<image :src>`
+- 移除单项或页面卸载时 H5 调用 `revokeObjectURL`
+
+### 6.2 上传与提交
+
+- 仍调用公开上传接口;返回 `{ id, url, fileName, size }`
+- 列表项结构:`{ previewUrl, url, fileName, size }`
+  - UI → `previewUrl`
+  - 提交 `attachmentUrls` → `url`(服务端地址)
+- 上传失败不入列表;本地预览不可用时仅显示文件名芯片,不回退远程 URL
+- 提交成功后离开页面;不提供「再次从服务器打开自己刚传附件」
+
+涉及:`mobile-wx/utils/upload.js`、`pages/feedback/index.vue`、`pages/suggest/index.vue`
+
+## 7. 错误与验收
+
+| 场景 | 期望 |
+|------|------|
+| 匿名 GET `…/feedback/…` 或 `…/suggestion/…` | 403 |
+| 匿名 GET `…/qrcode/…` | 200 |
+| 未登录调管理端代理 | 401 |
+| 无权限调代理 | 403 |
+| 代理非法 url / 外链 | 400 |
+| 移动端上传页 | 本地预览正常;断网无法打开远程附件 URL |
+| 管理端详情 | 登录后可打开反馈/建言附件 |
+| 二维码配置预览 | 匿名直链仍可显示 |
+
+**测试:**
+
+- 单测:bucket 前缀策略内容;代理鉴权与 objectKey 校验
+- 手工:上述验收表
+
+## 8. 非目标(本期不做)
+
+- 双 bucket 拆分
+- 管理端预签名下载
+- 公开附件访问审计表 / 下载水印
+- 改写历史附件 URL 字段
+- 移动端提交后再次拉取自己的附件
+
+## 9. 主要改动面
+
+| 层 | 文件/模块(预期) |
+|----|-------------------|
+| backend | `app/core/storage.py`(前缀策略、`get_object`/`open_file`);`app/api/admin.py`(代理接口);`app/api/public.py`(folder 白名单);相关 tests |
+| web-admin | `views/feedback/index.vue`;`views/suggestion/index.vue`;`api/admin.ts`(代理打开辅助) |
+| mobile-wx | `utils/upload.js`;反馈/建言页预览字段 |
+| 运维 | 对已部署环境立即覆盖 bucket policy(启动时或一次性脚本) |
+
+## 10. 风险与回滚
+
+- **风险:** 策略收紧后,若某处仍用私有对象直链,图片/链接会 403——按本设计改 UI 后消除
+- **回滚:** 恢复整桶公开策略可临时救急,但会重新暴露隐私,仅应急使用