From c33c06d5c30a4a74c823057347aa62a431ec286b Mon Sep 17 00:00:00 2001 From: ila Date: Thu, 27 Aug 2026 09:58:29 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E7=94=9F=E6=88=90?= =?UTF-8?q?=E5=AA=92=E4=BD=93=E6=9F=A5=E7=9C=8B=E8=AF=B4=E6=98=8E=20(#72)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/02-architecture-and-code-map.md | 16 +++++++++++++-- docs/03-business-rules-and-glossary.md | 14 +++++++++++-- docs/04-local-development-and-verification.md | 20 +++++++++++++++++-- 3 files changed, 44 insertions(+), 6 deletions(-) diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md index 35d396e..442eb11 100644 --- a/docs/02-architecture-and-code-map.md +++ b/docs/02-architecture-and-code-map.md @@ -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 # 架构与代码地图 @@ -487,3 +487,15 @@ Migration 000009 将原“Chorus 运营”平铺导航改为四个一级分组 管理员与终端用户继续分表：管理端使用 `sys_user`，Portal 使用 `users`，两者凭据和权限不得复用。保护判断在后端 service 中执行，前端禁用按钮只是交互提示。 + + +## 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。 + diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md index d24a3b6..985a871 100644 --- a/docs/03-business-rules-and-glossary.md +++ b/docs/03-business-rules-and-glossary.md @@ -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 # 业务规则与术语 @@ -228,3 +228,13 @@ synchronized_at: 2026-08-26T14:50:42Z - 菜单结构、接口清单和登录日志是只读管理资料。前端不提供写入口，后端不注册对应写路由；不得通过恢复 go-admin 默认按钮绕过。 - 管理端管理员、终端用户、真实凭据、请求正文和 JWT 不得写入错误、日志、测试、工单、Wiki 或截图。 + + +## 管理员查看生成媒体（#72） + +- 具有“生成记录”读取权限的管理员可以在单条任务详情中查看提示词原图、生成图片和文本输出，用于运营排错。 +- 媒体读取必须同时满足 Admin JWT/Casbin、URL 中的记录归属关系和存储对象 owner/generation 元数据校验。 +- 详情和媒体响应不得返回存储键、磁盘路径、Provider 密钥或终端用户凭据；对象缺失或元数据不一致统一按资源不存在处理。 +- 媒体端点只读，不提供编辑、删除、重新生成、批量下载或公开分享。 +- Admin 列表不批量返回输入/输出，只有显式打开详情后才加载。 + diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index 10731c0..5930490 100644 --- a/docs/04-local-development-and-verification.md +++ b/docs/04-local-development-and-verification.md @@ -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 # 本地开发与验证 @@ -604,3 +604,19 @@ go -C admin test -count=1 -run '^TestAdminProtectionMySQL$' ./app/admin/service 两项测试都会在连接后再次核对数据库名；迁移测试会重置目标库。浏览器测试使用合成导航、账号和空列表响应，不需要真实登录凭据，也不调用 Provider。 + + +## 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 或存储键。 +