feat(viewer): vite vue3 scaffold with routing and i18n

- apps/viewer (@photo/viewer): Vite 5 + Vue 3.4 + TS 最小骨架（无 Pinia/UI 库）
- router: /a/:token 活动页 + /a/:token/p/:photoId 单图深链（复用活动页组件）
- i18n: vue-i18n 9，zh-CN/en 词条，localStorage(viewer.locale) 持久 +
  navigator.language 检测兜底 zh-CN；顶栏语言切换组件；文案全量走 i18n
- api client: 类型化 fetch 封装（契约生成类型直连），错误信封 → ApiError，
  错误码 → i18n key 映射表（src/api/errors.ts）
- scripts: dev/build/preview/test(vitest 10 例)/test:e2e(Playwright 冒烟,
  webServer 自拉 dev)/lint/vue-tsc 全部接入 turbo
- root: +@playwright/test、+eslint-plugin-vue（flat config 收敛到 apps/**/*.vue）、
  pnpm.onlyBuiltDependencies 放行 esbuild

Co-Authored-By: Claude Code <noreply@anthropic.com>

apps/viewer/src/__tests__/api.spec.ts

@@ -0,0 +1,96 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ApiError, NETWORK_ERROR_CODE, getPublicAlbum, getPublicPhotos } from '../api/client';
+import { errorMessageKey } from '../api/errors';
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('api client', () => {
+  it('returns parsed payload and targets the /v1 public album endpoint', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      jsonResponse(200, { publicToken: 'tok-1', resolvedLocale: 'zh-CN', defaultLocale: 'zh-CN' }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const album = await getPublicAlbum('tok-1', 'zh-CN');
+    expect(album.publicToken).toBe('tok-1');
+    expect(fetchMock).toHaveBeenCalledWith(
+      '/v1/public/albums/tok-1?locale=zh-CN',
+      expect.objectContaining({ headers: expect.objectContaining({ accept: 'application/json' }) }),
+    );
+  });
+
+  it('builds cursor query for the photo list', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse(200, { items: [], nextCursor: null }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    await getPublicPhotos('tok-1', { cursor: 'c-9', limit: 30, category: 'cat-2' });
+    const calledUrl = new URL(String(fetchMock.mock.calls[0]?.[0]), 'http://viewer.local');
+    expect(calledUrl.pathname).toBe('/v1/public/albums/tok-1/photos');
+    expect(calledUrl.searchParams.get('cursor')).toBe('c-9');
+    expect(calledUrl.searchParams.get('limit')).toBe('30');
+    expect(calledUrl.searchParams.get('category')).toBe('cat-2');
+  });
+
+  it('throws ApiError carrying code/status/requestId from the error envelope', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue(jsonResponse(404, { code: 'ALBUM_NOT_FOUND', message: 'album not found', requestId: 'req-1' })),
+    );
+
+    const thrown = await getPublicAlbum('nope').then(
+      () => null,
+      (error: unknown) => error,
+    );
+    expect(thrown).toBeInstanceOf(ApiError);
+    const apiError = thrown as ApiError;
+    expect(apiError.code).toBe('ALBUM_NOT_FOUND');
+    expect(apiError.status).toBe(404);
+    expect(apiError.requestId).toBe('req-1');
+    expect(apiError.message).toBe('album not found');
+  });
+
+  it('degrades non-envelope error bodies to INTERNAL_ERROR with fallback message', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('<html>boom</html>', { status: 502 })));
+
+    const thrown = (await getPublicAlbum('tok').then(
+      () => null,
+      (error: unknown) => error,
+    )) as ApiError;
+    expect(thrown).toBeInstanceOf(ApiError);
+    expect(thrown.code).toBe('INTERNAL_ERROR');
+    expect(thrown.status).toBe(502);
+    expect(thrown.requestId).toBeNull();
+  });
+
+  it('maps fetch transport failures to the NETWORK_ERROR code', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new TypeError('Failed to fetch')));
+
+    const thrown = (await getPublicAlbum('tok').then(
+      () => null,
+      (error: unknown) => error,
+    )) as ApiError;
+    expect(thrown).toBeInstanceOf(ApiError);
+    expect(thrown.code).toBe(NETWORK_ERROR_CODE);
+    expect(errorMessageKey(thrown.code)).toBe('errors.network');
+  });
+});
+
+describe('error code to i18n key mapping', () => {
+  it('maps known codes to dedicated message keys', () => {
+    expect(errorMessageKey('ALBUM_NOT_FOUND')).toBe('errors.albumNotFound');
+    expect(errorMessageKey('ALBUM_NOT_PUBLIC')).toBe('errors.albumNotAvailable');
+    expect(errorMessageKey('PHOTO_NOT_PUBLIC')).toBe('errors.photoNotFound');
+    expect(errorMessageKey('NOT_FOUND')).toBe('errors.notFound');
+    expect(errorMessageKey('AUTH_TOKEN_EXPIRED')).toBe('errors.authExpired');
+  });
+
+  it('falls back to errors.unknown for unregistered codes', () => {
+    expect(errorMessageKey('SOMETHING_ELSE')).toBe('errors.unknown');
+  });
+});

apps/viewer/src/__tests__/i18n.spec.ts

@@ -0,0 +1,35 @@
+import { mount } from '@vue/test-utils';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { nextTick } from 'vue';
+import App from '../App.vue';
+import { LOCALE_STORAGE_KEY, i18n } from '../i18n';
+import { router } from '../router';
+
+describe('viewer i18n', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    i18n.global.locale.value = 'zh-CN';
+  });
+
+  it('switching locale re-renders messages and persists the choice', async () => {
+    await router.push('/a/tok-i18n');
+    await router.isReady();
+    const wrapper = mount(App, { global: { plugins: [router, i18n] } });
+
+    expect(wrapper.text()).toContain('照片即将上线');
+    expect(document.title).toBe('现场相册');
+
+    await wrapper.find('button.locale-switcher').trigger('click');
+    await nextTick();
+    expect(wrapper.text()).toContain('Photos coming soon');
+    expect(document.title).toBe('Live Gallery');
+    expect(document.documentElement.getAttribute('lang')).toBe('en');
+    expect(localStorage.getItem(LOCALE_STORAGE_KEY)).toBe('en');
+
+    // 切回 zh-CN 同样生效
+    await wrapper.find('button.locale-switcher').trigger('click');
+    await nextTick();
+    expect(wrapper.text()).toContain('照片即将上线');
+    expect(localStorage.getItem(LOCALE_STORAGE_KEY)).toBe('zh-CN');
+  });
+});

apps/viewer/src/__tests__/routing.spec.ts

@@ -0,0 +1,28 @@
+import { mount } from '@vue/test-utils';
+import { beforeEach, describe, expect, it } from 'vitest';
+import App from '../App.vue';
+import { i18n } from '../i18n';
+import { router } from '../router';
+
+describe('viewer routing', () => {
+  beforeEach(() => {
+    i18n.global.locale.value = 'zh-CN';
+  });
+
+  it('activity route resolves token param and renders empty notice', async () => {
+    await router.push('/a/tok-abc');
+    await router.isReady();
+    const wrapper = mount(App, { global: { plugins: [router, i18n] } });
+    expect(wrapper.text()).toContain('tok-abc');
+    expect(wrapper.text()).toContain('照片即将上线');
+    expect(wrapper.text()).not.toContain('photo-');
+  });
+
+  it('deep link resolves token and photoId params on the activity page', async () => {
+    await router.push('/a/tok-abc/p/photo-42');
+    const wrapper = mount(App, { global: { plugins: [router, i18n] } });
+    await router.isReady();
+    expect(wrapper.text()).toContain('tok-abc');
+    expect(wrapper.text()).toContain('photo-42');
+  });
+});