浅念
153 lines
13 KiB
Markdown
153 lines
13 KiB
Markdown
# UI-01 App 与悬浮组件体验优化 验收记录
|
||
|
||
基线 commit：6754cd4 · 完成 commit：本提交（tag `ui01`）· 日期：2026-09-21 · 执行环境：Windows 11 + Docker Desktop（mysql/redis×2 + minio）+ MuMu 模拟器（Android 15，540×960@240dpi ≈ 360dp 逻辑宽）+ Playwright Chromium（1440×900 / 390×844）
|
||
|
||
## 1. 基线与完成 commit
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 基线 | 6754cd4（UI-01 实施计划提交后、U00 执行前） |
|
||
| 完成 | Task 8 文档提交（含本记录 + after 截图），tag `ui01` |
|
||
| 工作树 | 基线时清洁；验收提交仅含本记录、总纲注记与 after 截图目录 |
|
||
|
||
任务提交链：3b5f8d2 → 8f4ad11 → c94b9e5 → f6929ae → 1f67b7c → ddf26a1 → ac23a4c → 本提交，共 8 个。
|
||
|
||
## 2. 任务完成表（U00–U09）
|
||
|
||
| 任务 | 状态 | commit | 备注 |
|
||
|---|---|---|---|
|
||
| Task 1: U00 基线 | ✅ | 3b5f8d2 | 6 张 App 基线截图；嵌入组件/后台基线因当时 Playwright 环境冲突未采集（见偏差 2） |
|
||
| Task 2: U01 契约与数据 | ✅ | 8f4ad11 | cover/preview/scope=own/embed 新配置字段 + 权限矩阵 e2e（services/api/test/ui01-contracts.e2e-spec.ts） |
|
||
| Task 3: U02 主题与导航 | ✅ | c94b9e5 | tokens + ColorScheme 浅/深 + 公共组件 + 三 tab 导航 + 角标 |
|
||
| Task 4: U03 相册与照片 | ✅ | f6929ae | 封面卡片列表 / 紧凑详情 / 三列网格 / 大图查看器 / 权限操作 / URL 刷新 |
|
||
| Task 5: U04+U05 上传与辅助页 | ✅ | 1f67b7c | 上传中心摘要+筛选+状态映射 / 深色取景 / 分组表单 / 分享分层 / 设置分组 |
|
||
| Task 6: U06 嵌入组件 | ✅ | ddf26a1 | loader 新配置+收起重设计+destroy；轮播页组件拆分+预加载+暂停恢复+可访问性；跨源宿主测试 |
|
||
| Task 7: U07 后台配置与预览 | ✅ | ac23a4c | 新字段表单 + 桌面/手机双预览（本地数据）+ 嵌入代码卡仅显式覆盖 |
|
||
| Task 8: U08+U09 验收交接 | ✅ | 本提交 | 全量回归 + 13 张 after 截图 + 本记录 + 总纲注记 + tag `ui01` |
|
||
|
||
## 3. 验收矩阵（方案 §9.1）
|
||
|
||
| 编号 | 状态 | 证据 |
|
||
|---|---|---|
|
||
| UI-A01 | ✅ | apps/mobile/test/app/theme_test.dart（11 用例：浅色 §3.1 精确值、深色语义对应、字阶、动效时长/reducedMotion 归零）；截图 01–08（设备浅色实拍） |
|
||
| UI-A02 | ✅ | albums_tab_test（封面有无占位、标题回退、390 单列/900 双列）；截图 02（封面卡片：图→标题→时间地点→状态 badge） |
|
||
| UI-A03 | ✅ | album_photos_page_test（350→2/390→3/800→5 列、大图切换、返回位置、角标）；截图 05/06（网格 + contain 大图 1/12） |
|
||
| UI-A04 | ✅ | services/api/test/ui01-contracts.e2e-spec.ts 权限矩阵（admin/owner/collab-own/collab-other × cover/preview/scope；隐藏照片有权限可见无权限 404；删除照片 preview=null） |
|
||
| UI-A05 | ✅ | queue_tab_test（摘要计算、状态映射、行级进度订阅）；截图 07（摘要条"今天·本设备"+ 状态 chips + 服务端历史分区） |
|
||
| UI-A06 | ✅ | capture_page 测试（连拍模式、入队反馈不弹窗、拍摄不被上传打断）——Task 5 提交内用例 |
|
||
| UI-A07 | ⚠️ 部分验证 | 自动化覆盖 350/390/800/900 逻辑宽（widget 测试）+ 设备 ≈360dp 实拍；**320/430 宽度与文字 1.0/1.3/2.0 缩放未系统覆盖**，列入 G2 真机清单 |
|
||
| UI-A08 | ⚠️ 部分验证 | 窄屏 375（playwright embed.spec "narrow viewport starts collapsed and downgrades to sm size"）+ 390/1440 实拍（截图 10/09）+ admin 预览 320px 框（截图 12）；**320/768 宿主未逐一实拍** |
|
||
| UI-A09 | ✅ | EmbedStage 固定 4:3 舞台 + object-fit contain（换图不跳高由舞台固定保证）；失败图片保留上一张（viewer vitest）；演示 12 张渐变图 contain 实拍（截图 09/11）；真实全景/文字海报样本列入 G2 |
|
||
| UI-A10 | ✅ | embed.spec 6 项暂停恢复（按钮/悬停/键盘焦点/页面隐藏/reducedMotion/收起）+ collapse 持久化；截图 10（390 默认收起）/11（展开） |
|
||
| UI-A11 | ✅ | embed.spec（rebinding resets the feed、admin settings apply live via config message、ghost slot 404 destroy）；304/签名过期刷新 viewer vitest（ETag + 受控刷新有限重试） |
|
||
| UI-A12 | ✅ | embed-crossorigin.spec.ts（真实双端口跨源宿主 7 用例：渲染、非法 source 消息忽略、ghost destroy、多 slot 纵向 8px 间距、全局 button CSS 干扰、窄屏收起） |
|
||
| UI-A13 | ✅ | admin e2e embed-slot-config（表单交互窗口零 /v1/ 请求）；截图 12（未保存修改即时反映在本地预览，含"未保存"标记） |
|
||
| UI-A14 | ✅ | embed-loader 单测 27 用例（缺省/显式/config 消息合并+边界+优先级 data-* > config > 后台 > 默认）；v1 兼容入口保留（dist/embed/v1/loader.js）；截图 13（代码卡仅含显式覆盖） |
|
||
| UI-A15 | ✅ | P4b 三端语言守护（键集相等 + 错误码枚举全覆盖）延续有效；UI-01 新键入 arb 双语；embed.spec "lang=en renders English copy"；运行时长文案无裁切由 footer 布局测试覆盖 |
|
||
| UI-A16 | ✅ | 本记录 §8 外部关口明确列 G2/G4/P5 为待验证，未宣称生产验收完成 |
|
||
|
||
## 4. API 新字段与权限变化（全部可选/nullable，旧客户端零 break）
|
||
|
||
| 契约 | 变更 | 服务端 |
|
||
|---|---|---|
|
||
| AlbumSummary | `cover: SignedUrl \| null` | albums 列表按页批量查 album_assets（kind=cover, effective）+ 短期签名 URL，无 N+1 |
|
||
| AdminPhoto | `preview: {thumb: SignedUrl, browse: SignedUrl} \| null` | 管理列表按权限逐张判断（admin 全部/owner 本相册/collab 仅自己）；已删除返回 null |
|
||
| listAlbumPhotos | query `scope: 'all' \| 'own'`（默认 all 行为不变） | own=服务端过滤仅本人上传 + 成员资格逐次检查 |
|
||
| EmbedSlotSettings | `imageFit: 'contain'\|'cover'`、`offsetX: 0-120`、`offsetBottom: 0-240`、`zIndex: 1-2147483000`（均带默认） | cn 管理 PATCH 校验 → slot-state payload → ov 公开响应投影完整传递（sync 验证） |
|
||
|
||
旧客户端兼容：全部字段缺省不 break（ui01-contracts.e2e-spec 含旧请求无新字段用例）；ov 侧旧响应消费者不受影响。
|
||
|
||
## 5. 截图索引
|
||
|
||
基线（2026-09-21 采集，commit 3b5f8d2）：`ui01-screenshots/baseline/`
|
||
|
||
| 编号 | 页面 | 文件 | 备注 |
|
||
|---|---|---|---|
|
||
| 01 | 登录页 | baseline/01-login.png | Flutter App |
|
||
| 02 | 相册列表 | baseline/02-albums.png | 当前卡片无封面图 |
|
||
| 03 | 相册详情（上半） | baseline/03-album-detail.png | 字段堆叠布局 |
|
||
| 04 | 相册详情（滚动后） | baseline/04-album-detail-scrolled.png | 按钮均等强调 |
|
||
| 05 | 上传队列 | baseline/05-queue.png | 状态筛选/进度/操作 |
|
||
| 06 | 设置 | baseline/06-settings.png | 分组/语言/密码 |
|
||
| 07-09 | 嵌入组件/后台 | （未采集） | 当时 Playwright 环境冲突；after 侧本次补齐，基线以 P4b 验收记录组件描述为对照 |
|
||
|
||
优化后（2026-09-21 采集，本次提交）：`ui01-screenshots/after/`
|
||
|
||
| 编号 | 页面 | 文件 | 验证点 |
|
||
|---|---|---|---|
|
||
| 01 | 登录页 | after/01-login.png | 主题化登录（logo/品牌/输入/主按钮） |
|
||
| 02 | 相册列表 | after/02-albums.png | 封面卡片：图→标题→时间地点→状态 badge；无 publicToken 堆叠 |
|
||
| 03 | 相册详情 | after/03-album-detail.png | 大图封面+信息+公开/允许上传 badge+照片条预览 |
|
||
| 04 | 详情滚动后 | after/04-album-detail-scrolled.png | 照片区（12 张·3 分类 + 管理入口）/分类 chips/底部"从相册选择 + 拍摄上传"双按钮 |
|
||
| 05 | 照片网格 | after/05-photo-grid.png | 三列网格 + scope chips（全部/我的）+ 排序/筛选 |
|
||
| 06 | 大图查看器 | after/06-photo-viewer.png | contain 展示 + 1/12 页码 + 深色舞台 + 操作入口 |
|
||
| 07 | 上传中心 | after/07-queue.png | 摘要条（今天·本设备）+ 状态 chips + 服务端历史分区 |
|
||
| 08 | 设置 | after/08-settings.png | 账号/通用/安全/上传帮助/关于分组 + 退出登录 |
|
||
| 09 | 组件·桌面 1440 | after/09-embed-desktop-1440.png | md 320px 卡片、offsetX16/offsetBottom24、页码 1/12、收起把手、外链 |
|
||
| 10 | 组件·390 收起 | after/10-embed-mobile-390-collapsed.png | 窄屏默认收起 + sm 尺寸把手（≥44px 高） |
|
||
| 11 | 组件·390 展开 | after/11-embed-mobile-390-expanded.png | sm 280px 卡片无横向溢出 |
|
||
| 12 | 后台配置+预览 | after/12-admin-slot-config.png | 新字段全套（位置/尺寸/间隔/语言/收起/适配/偏移/层级）+ 桌面 320/手机 375 双预览 + 未保存标记 |
|
||
| 13 | 嵌入代码卡 | after/13-admin-embed-code.png | 仅 data-slot 显式覆盖 + 参数说明表 |
|
||
|
||
采集环境：01–08 MuMu 强杀冷启 + 本地 dev 栈（cn 8080 / ov 8081 / worker / MinIO 9000 + adb reverse）；09–13 vite preview dist + 独立宿主页（http.server 8090）+ 真实跨源 loader 接入，数据为 demo-seed 12 张渐变图 + 上传封面资产。
|
||
|
||
## 6. 测试命令与真实结果
|
||
|
||
命令序列：清场（杀残留 dev 进程）→ `pnpm lint` → `pnpm typecheck` → `pnpm test` → `pnpm build` → `pnpm e2e` → `source scripts/flutter-env.sh && cd apps/mobile && flutter analyze && flutter test` → `pnpm --filter @photo/embed-loader build` + sync 校验。
|
||
|
||
| 门 | 结果 |
|
||
|---|---|
|
||
| pnpm lint | 10/10 任务通过 |
|
||
| pnpm typecheck | 13/13 任务通过 |
|
||
| pnpm test（单元） | 12/12 任务、**359 用例全绿**：embed-loader 27 / contracts 29 / storage 6 / api-cn 51 / worker 14 / viewer 155（20 文件）/ admin 77（14 文件） |
|
||
| pnpm build | 10/10 任务通过 |
|
||
| pnpm e2e | **364 全绿**（第二跑；磁盘用例计数 api-cn 255（24 套件，含 ui01-contracts）+ viewer 44（9 specs，含 embed-crossorigin）+ admin 23（7 specs，含 embed-slot-config）+ sync 27 + worker 13 = 362，运行总数含 it.each 展开） |
|
||
| flutter analyze | No issues found!（0 问题） |
|
||
| flutter test | **341/341 全绿**（+61 相对 P4b 280） |
|
||
| loader build+sync | dist/v1/loader.js 与 apps/viewer/public/embed/v1/loader.js 字节一致（cmp 相同） |
|
||
|
||
测试统计对比（P4b 基线 → UI-01 后）：
|
||
|
||
| 维度 | 前（P4b） | 后（UI-01） | Δ |
|
||
|---|---|---|---|
|
||
| Web 单元 | 316（embed-loader 11 / viewer 136 / admin 69 / 其余 100） | 359（embed-loader 27 / viewer 155 / admin 77 / 其余 100） | +43 |
|
||
| Web e2e | 339（api-cn 247/23 套件 / viewer 32/8 / admin 20/6 / sync 27 / worker 13） | 364（api-cn 24 套件 / viewer 9 specs / admin 7 specs / sync 4 / worker 2） | +25 |
|
||
| Mobile | 280/280 | 341/341 | +61 |
|
||
| 合计 | 935 | 1064 | +129 |
|
||
|
||
性能观察（实测记录，不做百分比推算）：
|
||
|
||
- loader 体积：dist/v1/loader.js **9462 B 原始 / 3728 B gzip**（P4b 基线未记录 gzip 值，无从对比，不编数字）
|
||
- 相册列表封面：每页 1 次批量 album_assets 查询 + 按页签发，无 N+1（实现 + e2e 断言）
|
||
- 组件预加载窗口：仅当前 + 下一张（2 张），decode 成功才切换
|
||
- 轮播 intervalMs 与取数轮询（30s 基准）解耦，互不牵引
|
||
- 组件首屏（ov 日志实测）：slot-state 1 次 + visits 信标 1 次，之后按帧取图
|
||
|
||
## 7. 既有改动保护与外部环境
|
||
|
||
- 基线工作树清洁；全程未覆盖任何未提交改动。
|
||
- 无关未跟踪文件未纳入提交：`.playwright-mcp/`、`docs/designs/`、`docs/plans/2026-09-21-UI02-*.md` 保持原状。
|
||
- 未触碰用户自有进程（`scripts/serve.mjs` 4173 端口、Playwright MCP/Codex 进程保留）；仅清理本仓库残留 dev 服务（e2e 首跑失败的根因，见偏差 3）。
|
||
- 演示数据写入本地 dev 库（demo-seed + 封面资产），不影响任何远程/云资源。
|
||
|
||
## 8. 方案偏差与剩余事项
|
||
|
||
偏差：
|
||
|
||
1. **cover 契约无 width/height**：方案 Task 2 文稿为 `{url, expiresAt, width, height}`，实现为既有 `SignedUrl` 引用（url/expiresAt）。理由：卡片封面按固定宽高比占位（无图回退中性占位），客户端不需要服务端尺寸；避免契约膨胀。旧客户端零影响。
|
||
2. **基线嵌入组件/后台截图缺失**：U00 时 Playwright 环境冲突未采集；本次 after 侧补齐（09–13），基线对照沿用 P4b 验收记录的组件行为描述。
|
||
3. **e2e 首跑 sync 套件 9/27 失败**：根因是上一会话残留 dev:worker/dev:sync 进程消费了 BullMQ 任务与 outbox 事件（processPhoto 命中 'already' 快路径、picked 数被抢），属环境干扰非代码回归；清理后全量第二跑 364 全绿。
|
||
4. **320/430 逻辑宽、文字 1.3/2.0 缩放、深色模式真机截图**未系统采集（A07/A08 部分验证），随 G2 真机一并执行。
|
||
|
||
剩余（交接）：
|
||
|
||
- **G2 真机关口**（既定强制关口）：追加 UI-01 视觉项——深色模式实拍、320/430 宽度、文字缩放 1.0/1.3/2.0、横图/竖图/全景/文字海报真实样本。
|
||
- **G4/D08 用户接口**、**P5 真实环境接入**（G5/G6）按总纲推进；P4b 移交项（真实域名/CDN 预热/embed 页 frame-ancestors CSP/展示位授权 UI 按需/轮询参数冻结）继续有效。
|
||
- A22 展示位授权（embed_slot_members 建而未用）维持 P4b 状态，未在 UI-01 范围。
|
||
|
||
## 9. 外部关口（不变）
|
||
|
||
- G2 真机（未执行，不阻塞 UI-01 本地验收）
|
||
- G4/D08 用户接口（未到位，不阻塞 UI-01）
|
||
- P5 真实部署（测试服务器 219.157.255.213 已部署；UI-01 全部为本地开发环境验证）
|