feat(viewer): photo viewer with zoom, navigation and deep link

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-09-18 11:04:05 +08:00
parent d0b79dd0c9
commit 90fe64f637
15 changed files with 2170 additions and 345 deletions
@@ -0,0 +1,188 @@
+import { flushPromises, mount, type VueWrapper } from '@vue/test-utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import App from '../App.vue';
+import { ApiError, getPublicAlbum, getPublicPhoto, getPublicPhotos, type PublicPhoto, type PublicPhotoList } from '../api/client';
+import { createViewerI18n } from '../i18n';
+import { router } from '../router';
+import { makeAlbum } from './fixtures';
+
+// 大图查看器路由编排（Task 8）：URL 同步（打开 push / 切换 replace / 关闭 back 或
+// replace）、滚动锚点恢复、深链解析顺序（单图先行 → 相邻页构成序列）、深链 404
+// 本地化提示与返回链接。使用真实 router 单例（jsdom 提供_history），对齐
+// routing.spec.ts 的既定模式；api 三端点替身。
+
+vi.mock('../api/client', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../api/client')>();
+  return {
+    ...actual,
+    getPublicAlbum: vi.fn(),
+    getPublicPhotos: vi.fn(),
+    getPublicPhoto: vi.fn(),
+  };
+});
+
+const mockedGetPublicAlbum = vi.mocked(getPublicAlbum);
+const mockedGetPublicPhotos = vi.mocked(getPublicPhotos);
+const mockedGetPublicPhoto = vi.mocked(getPublicPhoto);
+
+function makePhoto(id: string): PublicPhoto {
+  return {
+    photoId: id,
+    width: 800,
+    height: 500,
+    thumb: { url: `http://img.test/${id}-thumb.jpg?s=1`, expiresAt: '2026-10-01T00:00:00.000Z' },
+    browse: { url: `http://img.test/${id}-browse.jpg?s=1`, expiresAt: '2026-10-01T00:00:00.000Z' },
+    likeCount: 0,
+    publishedAt: '2026-10-01T00:00:00.000Z',
+  };
+}
+
+function makeList(items: PublicPhoto[], nextCursor: string | null = null): PublicPhotoList {
+  return { items, nextCursor, hasMore: nextCursor !== null };
+}
+
+let i18n: ReturnType<typeof createViewerI18n>;
+const mounted: VueWrapper[] = [];
+
+function mountApp(): VueWrapper {
+  const wrapper = mount(App, { global: { plugins: [router, i18n] } });
+  mounted.push(wrapper);
+  return wrapper;
+}
+
+function keydown(key: string): void {
+  window.dispatchEvent(new KeyboardEvent('keydown', { key, cancelable: true }));
+}
+
+describe('viewer url sync and deep link (Task 8)', () => {
+  beforeEach(async () => {
+    localStorage.clear();
+    i18n = createViewerI18n('zh-CN');
+    mockedGetPublicAlbum.mockReset().mockResolvedValue(makeAlbum());
+    mockedGetPublicPhotos.mockReset().mockResolvedValue(makeList([makePhoto('p1'), makePhoto('p2'), makePhoto('p3')]));
+    mockedGetPublicPhoto.mockReset().mockImplementation(async (_token, photoId) => ({
+      ...makePhoto(photoId),
+      categoryId: null,
+    }));
+  });
+
+  afterEach(() => {
+    while (mounted.length > 0) {
+      mounted.pop()?.unmount();
+    }
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it('open pushes the photo route, navigate replaces, close restores scroll and pops back', async () => {
+    await router.push('/a/tok-view');
+    await router.isReady();
+    const wrapper = mountApp();
+    await flushPromises();
+    expect(wrapper.findAll('.cell')).toHaveLength(3);
+
+    const pushSpy = vi.spyOn(router, 'push');
+    const replaceSpy = vi.spyOn(router, 'replace');
+    const scrollTo = vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+    vi.stubGlobal('scrollY', 650);
+
+    // 点击第 2 格开大图：push 深链路由，browse 渲染。
+    await wrapper.findAll('.cell')[1].trigger('click');
+    await flushPromises();
+    expect(wrapper.find('img.photo').attributes('src')).toBe('http://img.test/p2-browse.jpg?s=1');
+    expect(router.currentRoute.value.path).toBe('/a/tok-view/p/p2');
+    expect(pushSpy).toHaveBeenCalledTimes(1);
+
+    // 键盘右切：replace（不新增历史条目）。
+    keydown('ArrowRight');
+    await flushPromises();
+    expect(router.currentRoute.value.path).toBe('/a/tok-view/p/p3');
+    expect(replaceSpy).toHaveBeenCalledTimes(1);
+    expect(pushSpy).toHaveBeenCalledTimes(1);
+
+    // Esc 关闭：恢复滚动锚点 + 历史出栈回相册路由（jsdom 的 popstate 异步，需等待）。
+    scrollTo.mockClear();
+    keydown('Escape');
+    await vi.waitFor(() => expect(router.currentRoute.value.path).toBe('/a/tok-view'));
+    expect(wrapper.find('.lightbox').exists()).toBe(false);
+    expect(scrollTo).toHaveBeenCalledWith(0, 650);
+    expect(replaceSpy).toHaveBeenCalledTimes(1); // 关闭未额外 replace
+  });
+
+  it('browser back from the photo route closes the lightbox without touching history further', async () => {
+    await router.push('/a/tok-view');
+    await router.isReady();
+    const wrapper = mountApp();
+    await flushPromises();
+
+    vi.stubGlobal('scrollY', 320);
+    const scrollTo = vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+    await wrapper.findAll('.cell')[0].trigger('click');
+    await flushPromises();
+    expect(wrapper.find('.lightbox').exists()).toBe(true);
+
+    scrollTo.mockClear();
+    router.back(); // 等价浏览器后退（popstate 异步派发）
+    await vi.waitFor(() => expect(router.currentRoute.value.path).toBe('/a/tok-view'));
+    await flushPromises();
+    expect(wrapper.find('.lightbox').exists()).toBe(false);
+    expect(scrollTo).toHaveBeenCalledWith(0, 320);
+  });
+
+  it('deep link renders the single photo first, then naturalizes it as pages arrive', async () => {
+    // 第 1 页挂起（受控）：验证「先单图、后序列」的解析顺序。
+    let resolveFirstPage!: (value: PublicPhotoList) => void;
+    mockedGetPublicPhotos.mockReset();
+    mockedGetPublicPhotos
+      .mockReturnValueOnce(
+        new Promise<PublicPhotoList>((resolve) => {
+          resolveFirstPage = resolve;
+        }),
+      )
+      .mockResolvedValueOnce(makeList([makePhoto('p4'), makePhoto('p5')], null));
+
+    await router.push('/a/tok-view/p/p5');
+    await router.isReady();
+    const wrapper = mountApp();
+    await flushPromises();
+
+    // 单图先行：列表仍在加载，大图已可看（solo 序列 1/1）。
+    expect(mockedGetPublicPhoto).toHaveBeenCalledWith('tok-view', 'p5');
+    expect(wrapper.find('img.photo').attributes('src')).toBe('http://img.test/p5-browse.jpg?s=1');
+    expect(wrapper.find('.counter').text()).toBe('1 / 1');
+
+    // 第 1 页到达（无 p5）→ 深链 watcher 追拉第 2 页 → p5 归位自然顺序（5/5）。
+    resolveFirstPage(makeList([makePhoto('p1'), makePhoto('p2'), makePhoto('p3')], 'cur-1'));
+    await vi.waitFor(() => expect(wrapper.findAll('.cell')).toHaveLength(5));
+    expect(wrapper.find('.counter').text()).toBe('5 / 5');
+
+    // 序列已构成：左切到前一张。
+    keydown('ArrowLeft');
+    await flushPromises();
+    expect(wrapper.find('img.photo').attributes('src')).toBe('http://img.test/p4-browse.jpg?s=1');
+    expect(router.currentRoute.value.path).toBe('/a/tok-view/p/p4');
+  });
+
+  it('deep link to a non-public photo shows the localized notice with a back link', async () => {
+    mockedGetPublicPhoto.mockRejectedValue(new ApiError('PHOTO_NOT_PUBLIC', 'hidden', 404, 'req-1'));
+
+    await router.push('/a/tok-view/p/gone');
+    await router.isReady();
+    const wrapper = mountApp();
+    await flushPromises();
+
+    expect(wrapper.find('.lightbox').exists()).toBe(false);
+    const notice = wrapper.find('.deep-link-notice[role="alert"]');
+    expect(notice.text()).toContain('照片不存在或已下线');
+    expect(notice.text()).not.toContain('PHOTO_NOT_PUBLIC'); // 不裸露错误码
+
+    const back = notice.find('a');
+    expect(back.text()).toBe('返回相册');
+    expect(back.attributes('href')).toBe('/a/tok-view');
+    await back.trigger('click');
+    await flushPromises();
+    expect(router.currentRoute.value.path).toBe('/a/tok-view');
+    expect(wrapper.find('.deep-link-notice').exists()).toBe(false);
+    expect(wrapper.text()).toContain('2026 公司年会');
+  });
+});