docs: 同步生成媒体查看说明 (#72)

2026-08-27 09:58:29 +08:00
parent ee4f87db50
commit c33c06d5c3
3 changed files with 44 additions and 6 deletions
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Architecture-and-Code-Map
 wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Architecture-and-Code-Map.-
-wiki_revision: 8fb1f5622b7cfe6ecb1872623cd51397bfd043b5
-synchronized_at: 2026-08-26T14:50:35Z
+wiki_revision: cc8d6fe5bd31eb22aeca2b7e4b6a13077589a0a7
+synchronized_at: 2026-08-27T01:57:40Z
 <!-- gitea-wiki-mirror:end -->

 # 架构与代码地图
@@ -487,3 +487,15 @@ Migration 000009 将原“Chorus 运营”平铺导航改为四个一级分组

 管理员与终端用户继续分表：管理端使用 `sys_user`，Portal 使用 `users`，两者凭据和权限不得复用。保护判断在后端 service 中执行，前端禁用按钮只是交互提示。
 <!-- issues-67-69-system-admin:end -->
+
+<!-- issue-72-admin-generation-media:start -->
+## Admin 生成记录媒体查看（#72）
+
+Admin 生成记录列表仍只返回任务摘要。管理员点击“查看”或双击列表行后，前端调用 `GET /api/v1/chorus/generations/:id` 取得输入、图片输出和文本输出的安全元数据，再通过以下受保护端点读取媒体：
+
+- `GET /api/v1/chorus/generations/:id/inputs/:inputID`
+- `GET /api/v1/chorus/generations/:id/outputs/:outputID`
+- `GET /api/v1/chorus/generations/:id/outputs/:outputID/thumbnail`
+
+请求沿用 go-admin JWT 与 Casbin。服务先核对 generation 与 input/output 的数据库关系，再核对存储对象的 owner、generation 和 MIME 元数据；响应不包含 `storage_key`、缩略图 key 或本地路径。Admin 只注入 `storage.Reader` 的 `Open` 能力，不持有 `Put` 或 `Delete`。前端通过带 Authorization header 的 Axios Blob 请求读取图片，并在关闭详情时释放对象 URL，不把 Token 拼入媒体 URL。
+<!-- issue-72-admin-generation-media:end -->
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Business-Rules-and-Glossary
 wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Business-Rules-and-Glossary.-
-wiki_revision: a56ba63d7962719016a38ae85e22f8b00af765ea
-synchronized_at: 2026-08-26T14:50:42Z
+wiki_revision: 3ea4bac9925a081f33c2745438deac7e218cb309
+synchronized_at: 2026-08-27T01:57:53Z
 <!-- gitea-wiki-mirror:end -->

 # 业务规则与术语
@@ -228,3 +228,13 @@ synchronized_at: 2026-08-26T14:50:42Z
 - 菜单结构、接口清单和登录日志是只读管理资料。前端不提供写入口，后端不注册对应写路由；不得通过恢复 go-admin 默认按钮绕过。
 - 管理端管理员、终端用户、真实凭据、请求正文和 JWT 不得写入错误、日志、测试、工单、Wiki 或截图。
 <!-- issues-67-69-admin-protection:end -->
+
+<!-- issue-72-admin-media-rules:start -->
+## 管理员查看生成媒体（#72）
+
+- 具有“生成记录”读取权限的管理员可以在单条任务详情中查看提示词原图、生成图片和文本输出，用于运营排错。
+- 媒体读取必须同时满足 Admin JWT/Casbin、URL 中的记录归属关系和存储对象 owner/generation 元数据校验。
+- 详情和媒体响应不得返回存储键、磁盘路径、Provider 密钥或终端用户凭据；对象缺失或元数据不一致统一按资源不存在处理。
+- 媒体端点只读，不提供编辑、删除、重新生成、批量下载或公开分享。
+- Admin 列表不批量返回输入/输出，只有显式打开详情后才加载。
+<!-- issue-72-admin-media-rules:end -->
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Local-Development-and-Verification
 wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Local-Development-and-Verification.-
-wiki_revision: e2281f6e17e04a96cc98e0111c87464e37bead9a
-synchronized_at: 2026-08-26T14:50:51Z
+wiki_revision: 4a087f2f6a5fbdb7a93380ef8df8ea722fed2f71
+synchronized_at: 2026-08-27T01:58:01Z
 <!-- gitea-wiki-mirror:end -->

 # 本地开发与验证
@@ -604,3 +604,19 @@ go -C admin test -count=1 -run '^TestAdminProtectionMySQL$' ./app/admin/service

 两项测试都会在连接后再次核对数据库名；迁移测试会重置目标库。浏览器测试使用合成导航、账号和空列表响应，不需要真实登录凭据，也不调用 Provider。
 <!-- issues-67-69-system-verification:end -->
+
+<!-- issue-72-admin-media-verification:start -->
+## Admin 生成媒体验证（#72）
+
+定向验证：
+
+```powershell
+go test ./internal/core/storage ./internal/platform/storage ./migrations
+go -C admin test -count=1 ./app/chorus ./cmd
+pnpm -C admin-ui lint
+pnpm -C admin-ui test:unit --runInBand
+pnpm -C admin-ui build:prod
+```
+
+migration 10 必须在精确命名的可丢弃 MySQL 8 测试库执行 up/down/up。测试应核对四个 API、菜单关联和 `chorus_operator` Casbin 规则，并确认 down 只移除本迁移登记的权限数据。浏览器验收使用现有管理员会话和已有记录，不调用 Provider；覆盖详情按需打开、多图、文本、空结果、对象缺失、错误状态和窄屏，检查媒体请求使用 Authorization header 且 URL 不包含 Token 或存储键。
+<!-- issue-72-admin-media-verification:end -->