photo-live/docs/plans/2026-09-22-UI06-全端视觉统一实施方案.md

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

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

0. 给执行者的强制说明

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

• 管理后台示例（20 页，screenshots/01.png–20.png 为渲染证据）
• App 示例（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. 交付物

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）零损失；不覆盖用户未提交改动，不自动部署生产。