# UI-06：全端视觉统一实施方案（管理后台 + App，以 HTML 示例为唯一视觉基准）

版本：1.0
日期：2026-09-22
状态：待执行。本文只规划，不代表页面已还原。
目标：把 `apps/admin`（Vue3 + Element Plus / Art Design Pro 裁剪版）与 `apps/mobile`（Flutter）的实际界面，逐页还原到两个 HTML 示例的视觉效果，并以截图对照 + 测试服务器部署作为验收证据。

## 0. 给执行者的强制说明

**两个 HTML 预览目录是唯一视觉真相源。** 用户已明确：「要以示例 HTML 效果为主」。任何规格表、旧方案、设计板、组件库默认值与示例冲突时，一律以示例为准。

- [管理后台示例](../designs/admin-preview-2026-09-22/index.html)（20 页，`screenshots/01.png`–`20.png` 为渲染证据）
- [App 示例](../designs/app-preview-2026-09-22/index.html)（20 页，`screenshots/01.png`–`20.png` 为渲染证据）

裁决优先级（高→低）：

1. HTML 示例的实际渲染效果（以 `screenshots/` 与浏览器打开实物为准）
2. UI-05（后台）/ UI-03R（App）中与示例一致的数值规格、契约对齐项、保护项
3. 组件库（Element Plus / Material）默认值——**不得作为不还原的理由**

还原 = 修改真实代码。两个预览目录本身只读，不得为迁就实现反向修改示例。

其他强制项：

- 不得用「测试/类型检查通过」代替视觉验收；每页必须真实截图并对照示例。
- 不得只换颜色不改结构：示例中相册封面卡、照片网格、整页表单、菜单分组均为结构性改动，必须落地。
- 不得覆盖用户当前未提交改动；每批开工前核对 `git status`，异常先停下确认。
- 不自动提交推送打标签；每批完成提交需用户可见信息。不自动部署生产、不操作云资源；测试服务器部署按 §4.3 既有流程。
- 示例中的样例数据（人数、文件名、"82 uploaded"、演示二维码）不得抄进生产默认值。

## 1. 基线与前置

### 1.1 基线提交

开工前把工作树中未入库的成果先提交（属上一阶段产物，不属本方案改动）：

- `docs/designs/admin-preview-2026-09-22/`（含 screenshots、validation.json、image-prompt.txt）
- `docs/designs/app-preview-2026-09-22/`（含 screenshots、validation.json、check-preview.cjs 及 app.js/styles.css 未提交小改）
- `docs/designs/admin-redesign-concept-2026-09-22.png`
- `docs/plans/2026-09-22-UI05-管理后台分析与新版设计说明.md`
- `docs/plans/2026-09-22-用户列表分页与同步信息展示-实施计划.md`
- `services/api/src/scripts/g4-sync-once.ts`

基线提交后新建 `docs/plans/progress/UI06-验收记录.md` 骨架。

### 1.2 Before 截图

本地起 admin（`pnpm --filter @photo/admin dev`，接口指向测试服务器 cn API），用 Playwright 对现有页面截图存入 `docs/designs/ui06-implementation/before/`，命名与示例编号对齐（`02-albums.png` 等）。App 侧 before 不直接复用 UI-03 截图作为证据（仅覆盖 10/20 页且为 540×960 设备分辨率）——A0 阶段在固定 390×844 画布对全部 20 页补拍当前态。

## 2. 管理后台线（先行）

视觉规范依据示例与 UI-05 §5：主色 `#1A73E8`；工作区背景 `#F5F7FA`；边框 `#E5EAF1`；卡片圆角 12、控件 8；左侧导航 216px、顶部 64px、内容最大宽 1660px、常规左右边距 30px、卡间距 20–22px；页面标题 27px、卡片标题 17px、正文 12–13px、辅助 10–11px；字体为系统无衬线栈、Windows 中文优先 Microsoft YaHei；状态色绿=成功/公开、橙=待处理、红=危险/失败、灰=非活跃，且必须同时有文字。

### 2.1 二十页映射与结构性改动

| # | 示例页 | 代码入口 | 结构性改动（以示例为准） |
|---|---|---|---|
| 01 | 登录 | `views/auth/login/index.vue` | 整页重做：摄影拼贴主视觉 + 居中表单；摄影素材先以示例 assets 概念图裁片作占位入库，**标记为占位**，待用户提供正式品牌素材后替换 |
| 02 | 相册列表 | `views/albums/manage/index.vue` | **默认封面卡片三列**（1440 宽），可切表格；搜索按当前已加载过滤（契约无全局搜索，UI-05 §4.3）；token 收敛进分享/高级区 |
| 03 | 照片网格 | `views/albums/detail/AlbumPhotos.vue` | 新增照片**网格视图 + 管理大图**，保留表格/筛选/批量语义切换 |
| 04 | 成员 | `detail/AlbumMembers.vue` + `AlbumTransferDialog.vue` | 列表视觉简化；交接独立确认步骤 |
| 05 | 分类 | `detail/AlbumCategories.vue` | 双语同屏编辑，禁止全量替换丢语言 |
| 06 | 水印 | `detail/AlbumWatermark.vue` | 参数左、摄影预览右双栏；即时预览 |
| 07 | 分享 | `detail/AlbumShareCard.vue` | 分享卡视觉对齐：封面、二维码、复制链接布局 |
| 08 | 新建表单 | `manage/AlbumFormDialog.vue` → **改为整页表单路由** | 从对话框改整页（示例 08）；新增隐藏路由（沿用相册详情隐藏路由先例，保持父菜单高亮）；字段分组、footer 按钮对齐；`manage/index.vue` 与 `detail/index.vue` 两处消费入口一并改造 |
| 09 | 编辑表单 | 同上（edit 模式，含 `detail/index.vue:153` 编辑入口重接） | 整页 + 资料/访问分区；`translations` 合并保留其他语言 |
| 10 | 账号治理 | `system/users/` | 状态分列（凭据/来源/锁定）；**保留 2026-09-22 刚上线的分页 + 同步档案列**，仅重排视觉 |
| 11 | 用户同步 | `system/user-sync/` | 状态摘要卡 + 历史 + 失败明细弹层视觉对齐 |
| 12 | 用量 | `system/usage/` | 汇总卡单位一致、资产构成、阈值对话框对齐 |
| 13 | 展示位列表 | `system/embed-slots/index.vue` | 列表视觉对齐；启停/绑定/收起语义不变 |
| 14 | 展示位配置 | `SlotFormDialog.vue` 等 | **参数与预览复用 UI-04 真实组件**（v2 固定 195×280）；不搬示例里的简化 CSS 预览（UI-05 §4.4） |
| 15 | 品牌资产 | `detail/AlbumBannerUpload.vue` | 收进相册详情资产页签，独立视觉区 |
| 16 | 照片大图 | AlbumPhotos 新增 PhotoPreview | 深色舞台 + 元信息 + 隐藏/恢复/软删除动作条 |
| 17–19 | 403/404/500 | `views/exception/` | 品牌统一、回退路径视觉对齐 |
| 20 | 同步批次详情 | `system/user-sync/index.vue` 失败明细抽屉（:165 ElDrawer） | 抽屉视觉对齐示例 20 |

菜单分组（仅展示层重排，路由与权限不动，UI-05 §6）：工作空间（相册管理、网站展示位）/ 组织与治理（账号管理、用户同步、存储与用量）。

### 2.2 契约核对（B0 内完成，结论写进验收记录）

对测试服务器实际响应核对，不得凭空发明：

- Album `cover`（可空签名 URL 摘要）：核对测试服务器 `fetchAlbumList` 实际响应 → 补 `apps/admin/src/types/api/album.d.ts` `Summary.cover` → 卡片使用。**分支处理**：(a) 服务端已返回、仅部分相册无封面 → 中性占位验收；(b) 服务端响应根本无此字段（未实现）→ 属服务端补齐（OpenAPI 已定义、超出纯前端范围），**停下向用户确认**后再做，不得假造封面或 N+1 拉详情。
- `AdminPhoto.preview`（thumb/browse 可空）：核对响应 → 补类型 → 网格/大图使用；为空呈现真实空态；签名过期经受控重取。
- 相册创建载荷仅下载开关；公开/上传开关属更新载荷：整页表单按契约禁用或解释，不得塞进创建请求。
- 展示位 v2 `displayMode/scrollSpeed/reactionsEnabled` 已有类型；实施前重核 `SlotFormDialog.vue` 最新版本（工作树 UI-04 改动已提交，以 HEAD 为准）。

### 2.3 任务清单

### B0 基线（半天）
- [ ] §1.1 基线提交；`git status` 干净后开工。
- [ ] 编写可复用 Playwright 截图脚本（登录 → 逐页 capture → 存 `docs/designs/ui06-implementation/`），后续 before/comparisons 全部用它；需有效测试服务器管理员账号（向用户获取，凭据不写入仓库）。
- [ ] before 截图（admin dev + 测试服务器 API）。
- [ ] 契约核对 §2.2 四项，结论记入验收记录。
- [ ] 核对 Element Plus 主题变量入口（`assets/styles/core/el-light.scss`、`el-ui.scss`）与 Art 布局组件（`components/core/layouts/`）现状。
- 出口：偏差清单 + 契约结论齐，才进 B1。

### B1 主题 + 布局壳（1 天）
- [ ] token 落地：以 admin-preview `styles.css` 的 `:root` CSS 变量块为对照来源，映射到 Element Plus 主题变量（`--el-color-primary` 等）与 Art token；字体按 §2（系统无衬线栈，Windows 中文优先 Microsoft YaHei）；同库双部署不受影响。
- [ ] `ArtSidebarMenu` 216px + 菜单分组标题；`ArtHeaderBar` 64px；保留权限、响应式抽屉、语言切换、账号菜单行为。菜单分组实现 = 调整 `router/modules` 的 meta（标题/分组/顺序），路径与权限标识不变。
- [ ] 全部新增文案（菜单分组名、状态标签、表单字段等）走 vue-i18n zh/en 双语 key，不得硬编码中文或英文。
- [ ] 深色模式（Art 模板自带）保持可用不重设计——示例仅浅色；token 改动后在深色下做可用性抽查，偏差登记验收记录。
- [ ] 全局卡片/表格/按钮/输入/开关/标签视觉对齐示例（状态色 + 文字）。
- [ ] 01 登录页重做（摄影拼贴素材以示例概念图裁片占位入库，验收记录登记"素材为占位"）。
- [ ] 抽查截图：布局壳 + 登录页 vs `screenshots/01.png`。
- 出口：全局壳一致；未动业务数据流。

### B2 共享业务组件（1–2 天）
- [ ] `AlbumCoverCard`：封面 16:9 区域、标题、日期地点、状态行（Public/Uploads on 语义分开）、主操作（进入相册/分享）；无封面中性占位；不显示 owner 显示名（契约无投影、避免 N+1，UI-05 §4.3）。
- [ ] 列表/表格视图切换（保留游标 `useCursorList` 数据源，不换随机分页）。
- [ ] `PhotoGrid`（桌面四列、选择框、状态角标、文件回退名、上传者）+ `PhotoPreview` 大图（签名 URL、隐藏/恢复/软删除入口）。
- [ ] `AlbumSummaryHeader`（300×144 封面 + 紧凑资料，编辑/分享固定主操作）。
- [ ] 统一状态标签、表单 footer、危险操作确认、错误定位样式。
- 出口：组件级截图核对；AlbumPhotos 仍共用一份照片序列，无重复状态存储。

### B3 页面批次（每批：完成 → lint/test 绿 → **本地提交（不推送）** → 构建部署测试服务器 → 用户 32005 验收 → 通过后进下一批；不通过则修复后重新提交部署）

> 部署构建用 `git archive HEAD`，只含已提交内容——所以**必须先提交再部署**。B1/B2 为本地截图验收，不部署服务器；部署从 B3 批次开始。
- **B3a 核心批**：02 相册列表 + 03 照片网格/表格（含 16 大图）+ **详情页壳（AlbumSummaryHeader 落地 detail/index.vue、页签重组）**——页签宿主先改好，B3b/c 的各页签内容才有稳定挂载点。
- **B3b 管理批**：04 成员 + 05 分类 + 06 水印 + 07 分享。
- **B3c 表单批**：08 新建 + 09 编辑（整页表单路由，含 15 资产页签收纳）。
- **B3d 治理批**：10 账号 + 11 同步（含 20 批次明细）+ 12 用量。
- **B3e 收尾批**：13/14 展示位（对齐 UI-04 组件）+ 17/18/19 异常页。
- 每批出口：该批页面 1440×1000 截图与示例并排对照入 `docs/designs/ui06-implementation/comparisons/`；窄屏 390 抽查一页；`pnpm --filter @photo/admin lint typecheck test` 绿；admin 相关 e2e 保持绿（UI-04 已于 8c4906c 全绿收尾，无"既有失败"豁免——本方案改动若致 e2e 失败须当批修复或登记偏差，不得沿用旧豁免说法）。

### B4 回归与验收（半天）
- [ ] 全 20 页截图对照齐；`pnpm --filter @photo/admin lint typecheck test` 全绿。
- [ ] 部署测试服务器全量复核（§4.3）；真实账号登录、相册卡片、照片大图、账号治理冒烟。
- [ ] UI06 验收记录（后台部分）完成；偏差逐条列出（已修/接受+原因）。

## 3. App 线（管理后台验收后启动）

工程框架沿用 UI-03R（素材清单、固定 390×844 fixture、双轨证据、可量化阈值 ≤4dp、逐页截图流程）；**视觉参考从五张设计板切换为 app-preview HTML（20 页实物）**，两者同源，冲突以 HTML 为准。五张设计板降级为辅助参考。

页面映射沿用 UI-03 验收记录 §2（20 页 → `lib/pages/` 各入口），不重复列出。

### A0 复核基线
- [ ] 固定 390×844 画布补拍当前 App 全部 20 页 before 截图（UI-03 截图仅 10/20 页且分辨率不符，只作历史参考）。
- [ ] 逐页对照 app-preview `screenshots/` 与补拍 before，重建「参考/当前/偏差/目标」表（UI-03R §1.2 表更新为 HTML 基准）。
- [ ] 确认 Flutter（仓库固定版本）、字体、素材、截图工具可用。
- 出口：不沿用 UI-03 全通过结论；新偏差表入库。

### A1 素材与 fixture
- [ ] 按 UI-03R §4/§7 建 `docs/designs/ui03r-assets-manifest.md`。**素材分两轨**：测试/fixture 素材可复用 app-preview `assets/`（低分辨率局部裁片，仅限固定画布验收）；**生产素材（登录拼贴、相册封面 ≥720px）必须另行准备合规资源**——app-preview README 明确其素材"不作为生产图片素材"，UI-03R §4.1 要求生产拼贴随包合规资源。生产素材未落实时在清单中列为阻塞项，不得以低清裁片顶替上线。
- [ ] 固定英文数据、12 张照片、正常/异常状态 fixture 注入真实组件；生产隔离。

### A2 公共组件
- [ ] theme/tokens 显式化。**注意 UI-03R §5.1 色板与 app-preview CSS 存在五处色值差异**（softBlue #EEF5FF↔#EDF4FF、textSecondary #647084↔#69778E、successText #16794B↔#279966、errorText #B42318↔#E74E58、waitingText #996300↔#D89020）——按 §0 优先级**以 HTML 示例实测值为准**，不得以"两处一致"为由跳过核对；无胶囊根导航、两种分段、输入、按钮、Sheet、封面卡按示例重核。

### A3 三个样板页
- [ ] 01 登录、05 相册列表、14 上传中心对照 app-preview 达 UI-03R §8.1 阈值后推广。

### A4–A6 其余 17 页
- 按 UI-03R R04（02/03/04/06/07/08）、R05（09–12）、R06（13/15/16）、R07（17–20）分组推进，每页固定画布截图 + 对照 + 测量。

### A7 全量验收
- 视口矩阵（390 全量；320/430/横屏/平板/大字体/zh-CN/dark 抽查按 UI-03R §10.1）。
- `flutter analyze` / `flutter test` 全绿（执行前 `source scripts/flutter-env.sh`）。
- UI06 验收记录（App 部分）+ UI-03R 记录衔接说明。

## 4. 验收方法

### 4.1 后台逐页对照

1. 打开示例对应页（HTML 实物）与本页实现，1440×1000 截图并排存 `docs/designs/ui06-implementation/comparisons/`。
2. 核对项：布局结构、色彩、字号层级、卡片/控件形态、状态语义、操作入口位置。
3. 允许偏差：真实数据与示例样例数据的差异（如实际封面图不同）；须记录，不得借「数据不同」掩饰布局偏差。
4. 窄屏：每批抽 1 页 390 宽检查（侧栏抽屉、表格横滚，不整页缩略）。

### 4.2 App 逐页对照

UI-03R §8 流程不变（参考裁片等比 390、固定画布截图、左右对照、几何测量表），参考来源换为 app-preview 截图；§8.1 阈值（≤4dp、字号 ≤1sp 等）继续有效。

### 4.3 测试服务器部署（每批后台改动后）

**后台前端产物在 web 镜像（`docker/web.Dockerfile`，nginx 承载 viewer + /admin/），不在 server 镜像**（server.Dockerfile 不构建 apps/admin）。后台视觉批次的部署流程：

1. `git archive HEAD | docker build -f docker/web.Dockerfile -t photo-live-web:ui06-<sha>-<日期> -`（`git archive HEAD` 只含已提交内容，**部署前必须已提交该批改动**；VITE_* 构建参数集见 `docs/plans/2026-09-21-测试服务器部署方案.md`）。
2. save/gzip → scp → docker load（与既有流程相同）。
3. `SERVER_IMAGE=<保持当前 server tag> WEB_IMAGE=photo-live-web:ui06-<sha>-<日期> docker compose -f docker-compose.cn.yml up -d`（WEB_IMAGE 须带完整 `photo-live-web:` 仓库名——compose 默认值 `photo-live-web:latest` 同格式）→ **restart web 容器**（否则 nginx 缓存旧上游 IP 502）。
4. 验证入口 `http://219.157.255.213:32005/admin/`；仅当本批同时改了 API/服务端才重建 server 镜像。
5. 回滚 = 用上一批 WEB_IMAGE tag 重复步骤 3（镜像均在服务器本地保留）。

App 线无服务器部署，走本地固定画布 + 模拟器双轨证据。

## 5. 红线与保护项（两端通用，违反即回退）

- 游标分页 `useCursorList` 语义保留；后台用户页 page/pageSize 新分页不回退。
- 批量操作逐项成功/失败结果保留，不得全成功动画掩盖。
- 账号自保护（自身角色/锁定不可改）、来源状态只读。
- 水印/同步等异步任务「受理≠完成」语义保留。
- 展示位 settings 整体替换时保留全部字段；v1/v2 区分，v2 固定 195×280。
- `translations` 全量替换时合并保留其他语言。
- App 上传引擎、权限契约、凭证续签零语义改动（`lib/features` 不动，样式工程如触及控制逻辑须补测试并登记）。
- 同步账本（outbox/sync_inbox/sync_state）任何情况不清理不重置。
- viewer/embed（UI-02/UI-04 线）不在本方案范围。

## 6. 交付物

```text
docs/plans/2026-09-22-UI06-全端视觉统一实施方案.md   （本文）
docs/plans/progress/UI06-验收记录.md
docs/designs/ui06-implementation/
  before/            后台改动前截图
  comparisons/       每页示例 vs 实现并排对照
  README.md          索引与复现命令
docs/designs/ui03r-assets-manifest.md                （App 线，沿用 UI-03R 要求）
```

完成门槛：

- 后台 20 页对照证据齐 + 测试服务器部署复核通过；App 20 页固定画布截图与结论齐（双轨）。
- 无本方案列明的默认样式残留（紫胶囊、黑框分段、灰占位主视觉、ID 裸露等）。
- 全部测试与类型检查绿；保护项回归通过。
- 素材/真机等外部关口未完成时如实标注「部分完成」，不得宣称 100%。

## 7. 给 Claude 的执行指令

> 请执行 docs/plans/2026-09-22-UI06-全端视觉统一实施方案.md。视觉唯一基准是 docs/designs/admin-preview-2026-09-22 与 app-preview-2026-09-22 两个 HTML 示例，冲突一律以示例为准。先做 §1.1 基线提交与 B0（截图脚本 + before 截图 + 契约核对），再按 B1→B2→B3a–B3e 顺序推进管理后台（B1/B2 本地验收；B3 每批：lint/test 绿 → 本地提交不推送 → 按 §4.3 构建部署 web 镜像（restart web 容器）→ 用户在 32005 验收 → 通过后进下一批）。后台 B4 验收后启动 App 线 A0–A7（继承 UI-03R 工程标准，参考换 HTML）。每页必须截图对照，不得以测试通过代替视觉验收；保护项（§5）零损失；不覆盖用户未提交改动，不自动部署生产。