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/api/client.ts

@@ -0,0 +1,108 @@
+import type { components } from '@photo/contracts';
+
+// 契约生成类型直连（Vite 原生 ESM，无需 mapper）
+export type PublicAlbum = components['schemas']['PublicAlbum'];
+export type PublicPhotoList = components['schemas']['PublicPhotoList'];
+export type PublicPhotoDetail = components['schemas']['PublicPhotoDetail'];
+
+/** 客户端合成码：fetch 本身失败（离线/DNS），非服务端错误信封。 */
+export const NETWORK_ERROR_CODE = 'NETWORK_ERROR';
+
+/** 服务端错误信封 {code,message,requestId} 的类型化形态。 */
+export class ApiError extends Error {
+  readonly code: string;
+  readonly status: number;
+  readonly requestId: string | null;
+
+  constructor(code: string, message: string, status: number, requestId: string | null) {
+    super(message);
+    this.name = 'ApiError';
+    this.code = code;
+    this.status = status;
+    this.requestId = requestId;
+  }
+}
+
+interface ErrorEnvelopeLike {
+  code?: unknown;
+  message?: unknown;
+  requestId?: unknown;
+}
+
+function parseErrorEnvelope(body: unknown): { code: string | null; message: string | null; requestId: string | null } {
+  if (typeof body === 'object' && body !== null) {
+    const env = body as ErrorEnvelopeLike;
+    return {
+      code: typeof env.code === 'string' ? env.code : null,
+      message: typeof env.message === 'string' ? env.message : null,
+      requestId: typeof env.requestId === 'string' ? env.requestId : null,
+    };
+  }
+  return { code: null, message: null, requestId: null };
+}
+
+/** 类型化 fetch 封装：统一前缀 /v1、JSON 解析、错误信封 → ApiError。 */
+export async function apiRequest<T>(path: string, init?: RequestInit): Promise<T> {
+  let response: Response;
+  try {
+    response = await fetch(`/v1${path}`, {
+      ...init,
+      headers: { accept: 'application/json', ...init?.headers },
+    });
+  } catch {
+    throw new ApiError(NETWORK_ERROR_CODE, 'network request failed', 0, null);
+  }
+  const text = await response.text();
+  let body: unknown = null;
+  if (text.length > 0) {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = null;
+    }
+  }
+  if (!response.ok) {
+    const env = parseErrorEnvelope(body);
+    throw new ApiError(
+      env.code ?? 'INTERNAL_ERROR',
+      env.message ?? `request failed with status ${response.status}`,
+      response.status,
+      env.requestId,
+    );
+  }
+  return body as T;
+}
+
+function withQuery(path: string, query: Record<string, string | number | undefined>): string {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined) params.set(key, String(value));
+  }
+  const qs = params.toString();
+  return qs.length > 0 ? `${path}?${qs}` : path;
+}
+
+/** 公开相册信息（观众页入口；locale 缺省由服务端按相册 defaultLocale 回退）。 */
+export function getPublicAlbum(token: string, locale?: string): Promise<PublicAlbum> {
+  return apiRequest<PublicAlbum>(withQuery(`/public/albums/${encodeURIComponent(token)}`, { locale }));
+}
+
+// type 别名（非 interface）：可赋给 Record 索引签名形参
+export type PublicPhotosQuery = {
+  category?: string;
+  cursor?: string;
+  limit?: number;
+  locale?: string;
+};
+
+/** 公开照片列表（游标分页；Task 7 瀑布流数据源）。 */
+export function getPublicPhotos(token: string, query: PublicPhotosQuery = {}): Promise<PublicPhotoList> {
+  return apiRequest<PublicPhotoList>(withQuery(`/public/albums/${encodeURIComponent(token)}/photos`, query));
+}
+
+/** 公开单图（深链定位与签名过期刷新入口；Task 8 大图数据源）。 */
+export function getPublicPhoto(token: string, photoId: string, locale?: string): Promise<PublicPhotoDetail> {
+  return apiRequest<PublicPhotoDetail>(
+    withQuery(`/public/albums/${encodeURIComponent(token)}/photos/${encodeURIComponent(photoId)}`, { locale }),
+  );
+}

apps/viewer/src/api/errors.ts

@@ -0,0 +1,25 @@
+import { NETWORK_ERROR_CODE } from './client';
+
+// 错误码 → i18n 文案键映射表：401/404 等观众可认知的码给出确定性文案，
+// 未登记码统一走 errors.unknown（原始 message 仅用于日志/排查）。
+export const errorCodeI18nKeys: Readonly<Record<string, string>> = {
+  // 客户端合成码
+  [NETWORK_ERROR_CODE]: 'errors.network',
+  // 401 域
+  AUTH_TOKEN_EXPIRED: 'errors.authExpired',
+  AUTH_FORBIDDEN: 'errors.forbidden',
+  AUTH_RATE_LIMITED: 'errors.rateLimited',
+  // 404 域
+  NOT_FOUND: 'errors.notFound',
+  ALBUM_NOT_FOUND: 'errors.albumNotFound',
+  ALBUM_NOT_PUBLIC: 'errors.albumNotAvailable',
+  PHOTO_NOT_FOUND: 'errors.photoNotFound',
+  PHOTO_NOT_PUBLIC: 'errors.photoNotFound',
+  // 其余
+  VALIDATION_FAILED: 'errors.validationFailed',
+  INTERNAL_ERROR: 'errors.internal',
+};
+
+export function errorMessageKey(code: string): string {
+  return errorCodeI18nKeys[code] ?? 'errors.unknown';
+}