photo-live/docs/plans/2026-09-22-UI05-管理后台分析与新版设计说明.md

# UI-05：管理后台现状分析与新版设计说明

日期：2026-09-22。交付类型：代码静态分析、概念效果图、可运行离线 HTML 原型。**未修改管理后台业务源码，未连接真实账号、数据库、OSS 或生产接口。**

## 1. 交付入口

- [新版后台 HTML 入口](../designs/admin-preview-2026-09-22/index.html)
- [后台概念效果图](../designs/admin-redesign-concept-2026-09-22.png)
- [HTML 使用说明与页面索引](../designs/admin-preview-2026-09-22/README.md)
- [HTML 实际截图](../designs/admin-preview-2026-09-22/screenshots/)
- [自动检查记录](../designs/admin-preview-2026-09-22/validation.json)
- [前一项 App 20 页原型](../designs/app-preview-2026-09-22/index.html)

双击 HTML 入口即可离线查看。左侧“全部页面目录”可直达20个页面与关键状态；相册、成员、分类、水印、账号等按钮可在示例状态中操作。图片、二维码和脚本均保存在本地目录，不依赖 CDN。

## 2. 分析依据与结论

### 2.1 实际框架

`apps/admin/package.json` 明确记录 Art Design Pro **v3.0.2** 裁剪版，实际使用 Vue 3、Element Plus、Pinia、vue-i18n、Tailwind、Vite。模板的演示视图和图表等依赖已裁剪。

布局保留 `ArtSidebarMenu`、`ArtHeaderBar`、`ArtPageContent` 和 `ArtGlobalComponent`。因此本次设计适合通过模板主题 token、业务组件及页面布局改造实现，无须换后台框架，也不应重新安装完整演示模板覆盖已有代码。

### 2.2 已核对的入口

| 当前入口 | 已有业务 | 设计处理 |
|---|---|---|
| `router/modules/albums.ts` | 相册管理、隐藏的相册详情路由 | 保留相册为主要工作入口，详情保持所属菜单高亮 |
| `views/albums/manage/index.vue` | 文字表格、公开 token、状态、开关、游标加载 | 默认摄影封面卡片，可切换表格；token收敛到分享/高级资料 |
| `views/albums/detail/index.vue` | 资料描述表、宣传图上传、照片/成员/分类/水印/分享页签 | 紧凑活动摘要在上，照片区成为主内容；资产编辑独立页签 |
| `AlbumPhotos.vue` | 处理/可见性状态表格、点赞副本、批量隐藏、软删除 | 增加照片网格和管理大图，保留表格、筛选、部分成功语义 |
| `AlbumMembers.vue` / `AlbumTransferDialog.vue` | 内部账号邀请、成员管理、所有者交接 | 成员列表简洁化，交接独立确认，不改权限 |
| `AlbumCategories.vue` | 分类多语言 CRUD | 双语同屏编辑，避免另一个语言被全量替换丢失 |
| `AlbumWatermark.vue` | 文本水印配置、示意预览、生成任务与重生成 | 参数与摄影预览双栏，任务记录保持独立 |
| `system/users` | 搜索、角色/凭据/来源/本地锁定、密码重置与激活 | 状态分列，治理操作更清楚，保留自身账号保护 |
| `system/user-sync` | 定时拉取状态、手动补拉、批次历史、失败明细 | 状态摘要、历史表格、失败详情弹层 |
| `system/usage` | 原图/变体/合计、相册用量、阈值与告警 | 单位一致的汇总卡、资产构成、告警优先级 |
| `system/embed-slots` | 展示位、绑定、启停、配置版本、接入代码、预览 | 列表与独立配置页，保留v1并突出v2固定小窗 |
| `auth/login` / `exception` | 账号密码登录、403/404/500 | 统一品牌与回退路径，不增加注册、飞书 |

本次是静态代码和契约核查；没有以生产运行截图作为现状证据，没有宣称测试了当前后台的真实登录、权限和 API 链路。`views/index/index.vue` 是布局壳，不是已有业务仪表盘。

## 3. 当前值得调整的地方

### 3.1 照片业务却以信息表格为第一视觉

相册列表首先呈现标题、token和多个开关标签，活动识别需要读文字。详情的大型 `ElDescriptions` 和宣传图上传占据照片之前的区域。摄影业务应先让工作人员认出活动和照片，再进入参数编辑。

调整：相册封面卡片默认、表格备选；详情摘要高度受控，日期地点、创建者与访问状态简洁排列；编辑、分享为固定主操作；照片网格可切回信息表格。

### 3.2 技术信息与高频操作没有分层

公开 token、内部ownerId和配置信息不应成为主视觉字段。操作人员常用的是进入相册、查看照片、管理成员、分享与关闭公开访问。

调整：token保留在链接和代码生成流程；内部ID按需展开；保留处理状态和可见性差异，不能把照片处理完成等同于已公开。

### 3.3 状态很多，需要保持语义独立

公开/未公开、上传允许、相册active/offline、处理ready/failed、账号sourceStatus/credentialStatus/localLocked不可合并为一个“启用”标签。

调整：相册主卡只放主要状态；详情与表格提供完整事实。账号治理分列。用量阈值是告警而非硬配额；“用户同步”是企业账号目录同步，不能画成已验证的跨境照片同步监控。

### 3.4 局部页面已经具备保护，重做样式不能损失

- `useCursorList` 已为游标API设计，不要换成要求总数和随机页码的通用分页。
- 批量隐藏已有逐项成功/失败结果，不要用全成功动画掩盖局部失败。
- 账号来源状态只读，自己的角色/锁定存在保护。
- 水印为异步任务，受理不等于全部生成成功。
- 展示位无删除端点；停用、解绑、收起含义不同。
- 同步手动补拉的受理、运行、最终结果是不同状态。

## 4. 已确认的契约对齐项

### 4.1 相册封面：契约存在，管理端类型尚未对齐

`packages/contracts/openapi.yaml` 的 Album 定义已有可空 `cover` 短期签名URL摘要，明确按页批量组装。所读 `apps/admin/src/types/api/album.d.ts` 的 `Summary` 还未声明 `cover`。

正式实施先核查服务实际响应，再对齐管理端类型和展示组件；不需要凭空发明封面服务，也不应为了卡片每个相册额外请求一次详情。无封面用中性占位，不偷用另一个活动图片。

### 4.2 管理照片预览：契约已有权限约束，不能绕过

OpenAPI 的 `AdminPhoto.preview` 已提供 `thumb/browse` 签名URL，可为null；隐藏照片预览仅admin/owner签发。当前管理端 `AdminPhoto` 类型还未声明此字段，现有 `AlbumPhotos.vue` 以资料表为主。

正式实现：补齐可空类型，使用该预览字段；为空呈现无预览/处理中/无权限的真实状态；签名过期经受控重取刷新。不能用公开原图URL、猜OSS对象键或匿名观众接口绕过管理权限。

### 4.3 搜索与相册创建不能按原型直接照搬API

- `fetchAlbumList` 当前参数仅cursor/limit，没有全局标题搜索和任意排序。原型明确写“搜索当前已加载相册”；生产若要全局搜索，应兼容扩展API再上线。
- `fetchAlbumPhotos` 当前支持visibility/categoryId/cursor/limit，没有按文件名全局搜索。原型文件名是示例，正式无文件名时显示可用安全回退，不强行编造原文件名。
- 相册列表只有ownerId，没有直接提供owner显示名；生产需评估批量显示名投影/缓存，不能N+1查人。
- `CreatePayload` 当前只接受下载相关开关，公开/上传开关在更新载荷中。原型创建表单展示完整视觉模型，正式新建页应按契约禁用或解释这些字段，不能直接把UI字段塞进创建请求；也不能静默创建后再自动多次PATCH。
- 生产只要求默认语言内容满足真实校验；原型为展示双语同时要求填写两列，不构成新增产品必填政策。
- `translations` 为全量替换，修改单语言必须合并保留其他语言。

### 4.4 展示位v2类型已有，配置表单应复核调用链

此次读取的 `types/api/embedSlot.d.ts` 已有 `displayMode/scrollSpeed/reactionsEnabled`，但同次读取的 `SlotFormDialog.vue` 仍主要呈现size/intervalMs/imageFit等旧配置。工作树存在其他进行中的UI04改动，实施前必须重新核对最新版本。

正式新版明确区分v1与v2：v2固定195×280，不让size恢复320px；v1保留旧字段；settings整体替换时保留全部字段。后台最终应复用真正的展示组件，不能把此HTML中的简化预览当生产组件。

## 5. 新版视觉规范

| 项目 | 规格 |
|---|---|
| 布局 | 左侧216px固定导航，顶部64px，内容最大宽1660px |
| 工作区 | 背景#F5F7FA，常规左右30px，卡片间距20–22px |
| 主色 | #1A73E8；蓝色主操作，白色次级操作 |
| 字体 | 系统无衬线，Windows中文优先Microsoft YaHei |
| 标题 | 页面27px；卡片17px；表单/正文12–13px；辅助10–11px |
| 边框与圆角 | #E5EAF1，卡片12px、控件8px，不使用重阴影 |
| 相册列表 | 1440宽下三列封面卡；可切换表格；无假全局总数 |
| 相册详情 | 300×144封面+简洁资料，页签承载管理功能 |
| 照片网格 | 桌面四列，选择框、状态、文件回退名、上传者；无公众点赞按钮 |
| 治理表格 | 表头浅底、轻分隔、长内容局部横滚，不能撑破整个页面 |
| 状态 | 绿成功/公开，橙待处理，红危险/失败，灰非活跃；同时提供文字 |
| 窄屏 | 侧栏抽屉、主栏换行、表格局部滚动；不把桌面整页缩成缩略图 |
| 动态 | 减少无意义动效；焦点可见、弹窗限制焦点、Escape可关闭 |

概念效果图中的“246 uploads”等数字只是图像生成的示例，不是新的数据口径。HTML采用“可上传/上传关闭”及已有数据语义；正式实现不照抄概念图中的数量、人员、文件名和统计。

## 6. 20页与关键交互覆盖

01登录；02相册卡片/表格；03相册照片网格/表格；04成员；05分类；06水印；07分享；08新建；09编辑；10账号治理；11用户同步；12存储用量；13展示位列表；14展示位配置；15宣传图资产；16照片大图；17/18/19对应403/404/500；20同步批次详情。

同时提供可操作弹层：邀请/移除成员、所有者交接、分类增改删、照片隐藏/恢复/软删除、批量隐藏、账号编辑/重置/激活/锁定、阈值设置、展示位绑定及接入代码。

入口的菜单重组是展示层优化：相册和展示位归工作空间；账号、用户同步、用量归组织治理。可以保留真实 `system/embed-slots` 路由，不必为导航名称改数据库或路由权限体系。

## 7. Art Design Pro 实施映射

1. 在主题层增加或对齐主色、背景、圆角、边框与字号，不引入另一套UI框架。
2. `ArtSidebarMenu/ArtHeaderBar` 保留菜单权限、响应式、语言、账号与原有导航行为；重排必要展示元素。
3. `albums/manage` 提取 AlbumCoverCard 与列表/表格切换组件，保留游标数据源。
4. `albums/detail` 提取 AlbumSummaryHeader，删除重复描述区；把现有BannerUpload收进资产页签。
5. `AlbumPhotos` 共用一份照片序列，添加PhotoGrid/PhotoPreview，不复制新的状态存储；保留现有表格和批量结果处理。
6. 成员、分类和分享复用现有API；统一表单footer、危险操作确认和错误定位。
7. 治理页面继续复用Element Plus Table/Dialog/Drawer/Switch；保持账号保护与任务轮询清理。
8. 展示位页面对齐UI04最终实现，参数与预览使用同一来源，不维护两个不同逻辑的“漂亮预览”。

## 8. 原型与生产实现的边界

- 本HTML没有引入Art Design Pro运行依赖，是供确认视觉与交互的独立原型，不是替代模板的生产实现。
- 示例数据仅存在当前文档内存。刷新或独立打开另页会重置；无真实写请求。
- 默认以公司管理员视角展示全部页面；员工/协作者角色的正式权限验收未实现于此原型。
- 摄影来自已有/本次生成图的局部，适用于说明布局。不得当成公司真实活动素材。
- 二维码编码的是example.com演示地址；复制链接和“打开观众页”指向本机观众页原型。
- 展示位配置内的CSS上滚只用于说明样式，不声明是生产有限队列、真实气泡或严格速度实现；精确滚动可另开此前组件HTML查看。
- 没有实现生产背景任务、密码重置、真实目录同步、OSS上传、海外复制、真实错误恢复或全套系统深色主题。
- 统计由样例构成；不添加尚不存在的营业额、趋势、在线人数等仪表盘指标。

## 9. 检查结果与落地验收建议

HTML检查通过：20页在1440×1000渲染，无页面JS异常、图片加载失败或文档横向溢出；390宽代表页检查通过。已验证相册搜索、批量隐藏、可见性筛选、账号搜索、语言切换、展示位195×280尺寸/收起/v1配置、水印预览。

原生App原型亦已补完：20页390×844渲染；5类320宽代表页；登录→相册→拍摄模拟入队、隐藏→恢复、语言提交均通过。两套结果均只代表HTML，不代表真实Flutter或管理后台上线验收。

正式后台实施仍需补：角色矩阵、真实API响应、签名过期、403/404/断网、批处理部分失败、水印异步任务、账号自保护、settings全量替换、真实v1/v2预览一致性。保留当前所有已有测试，在隔离环境验证，不自动部署或操作真实云资源。

## 10. 生成方式

概念图使用内置 image_gen（imagegen 技能），非CLI。完整提示词随设计资产保存于 `../designs/admin-preview-2026-09-22/image-prompt.txt`。HTML与截图由本地实现和Playwright生成。生成图与运行截图分别保留，不互相冒充。