feat(ov,viewer): two-tier download with wechat guidance

P4a Task 4（T12 收口）：ov 域公开照片下载端点 + viewer 下载 UI。

- interactions 增 downloads：GET /public/albums/{token}/photos/{photoId}
  /download?variant=browse|original。两级开关（A18）：browse 需
  downloadEnabled；original 需叠加 originalDownloadEnabled（级联，browse 关
  则两者均 403 DOWNLOAD_DISABLED）。水印相册 browse 现签 watermark pattern
  key（browse-key 解析抽取 shared/ov-browse-key 与 public-ov 复用）；原图
  现签 originalObjectKey（SIGNED_URL_TTL）。来源 IP 固定窗限速
  （DOWNLOAD_WINDOW_REQUESTS/DOWNLOAD_WINDOW_SECONDS，env 可调）；零浏览
  计数写入（排除规则）。STORAGE_PORT_OV 经新 StorageOvModule 与 public-ov
  共享同一实例。
- 契约微调登记：PublicAlbum 增 readOnly 必返 downloadEnabled/
  originalDownloadEnabled（cn+ov 同形返回；public e2e 精确键断言同步）。
- viewer：lightbox 下载入口随开关渲染（无/单按钮/分体菜单两选项）、过期
  凭证静默重取一次、微信内置浏览器（MicroMessenger UA）出保存图片指引
  浮层（复制深链 + 反馈）替代直接下载；i18n zh/en 词条。
- tests：api e2e +7（开关矩阵 + URL/字节级断言、水印键一致、隐藏 404、
  限速 429、零计数行）；viewer vitest +9（UA/矩阵/菜单/重取/失败/指引/
  复制）；viewer Playwright +3（入口矩阵、微信 UA 浮层、真实端点 200 +
  签名 URL 模式）。

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

apps/viewer/src/components/PhotoLightbox.vue

@@ -2,6 +2,7 @@
 import { computed, onBeforeUnmount, onMounted, reactive, ref, watch } from 'vue';
 import { useI18n } from 'vue-i18n';
 import type { PhotoSequence } from '../feed/sequence';
+import type { DownloadController } from '../download/useDownload';
 import type { LikesController } from '../likes/useLikes';
 import { MIN_SCALE, panBy, resetZoom, wheelFactor, zoomAt, type ZoomState } from '../viewer/zoom';
 
@@ -20,6 +21,11 @@ import { MIN_SCALE, panBy, resetZoom, wheelFactor, zoomAt, type ZoomState } from
 //   · 双击（鼠标 dblclick / 触控双 tap）：复位缩放；
 //   · 滚轮（无需 ctrl）：以光标为不动点缩放；Esc/关闭按钮/背景点击关闭。
 //
+// 下载（P4a Task 4）：工具栏入口按相册两级开关渲染（控制器 canDownload /
+// canDownloadOriginal；download prop 缺省不渲染——组件单测/降级组装）。原图
+// 可下时为分体按钮（主按钮=浏览图 + ▾ 菜单两选项）；微信内置浏览器由控制器
+// 判定并改走引导浮层（长按保存 + 复制深链）。
+//
 // 关闭回位（滚动锚点）与 URL 同步由 ActivityPage 负责（见 ActivityPage 注释）。
 
 const props = defineProps<{
@@ -27,6 +33,8 @@ const props = defineProps<{
   photoId: string;
   /** 点赞控制器（Task 10）：缺省不渲染点赞位（组件单测/降级组装）。 */
   likes?: LikesController;
+  /** 下载控制器（P4a Task 4）：缺省不渲染下载位（组件单测/降级组装）。 */
+  download?: DownloadController;
 }>();
 
 const emit = defineEmits<{
@@ -263,6 +271,29 @@ function likeCurrent(): void {
   props.likes.like(photo.value.photoId);
 }
 
+// —— 下载（P4a Task 4）：菜单开合随照片切换/关闭复位 ——
+
+const downloadMenuOpen = ref(false);
+
+watch(
+  () => props.photoId,
+  () => {
+    downloadMenuOpen.value = false;
+  },
+);
+
+/** 菜单选项点击：收起菜单后发起对应 variant 下载。 */
+function pickDownload(variant: 'browse' | 'original'): void {
+  downloadMenuOpen.value = false;
+  void props.download?.download(variant);
+}
+
+/** 主按钮：无原图位时直下浏览图；有原图位时也直下浏览图（菜单提供两项）。 */
+function downloadBrowse(): void {
+  downloadMenuOpen.value = false;
+  void props.download?.download('browse');
+}
+
 // —— 签名过期/下线处理 ——
 
 /** 大图加载失败：静默重取单图接口换新签名 URL；404 → 通知父级移除；其他失败可重试。 */
@@ -348,7 +379,40 @@ onBeforeUnmount(() => {
         <span class="like-count">{{ likes.displayFor(photo) }}</span>
       </button>
       <span v-else class="likes">{{ t('viewer.likeCount', { count: photo.likeCount }) }}</span>
-      <!-- P4a 预留：下载 / 分享操作位（P1b 不实现）。 -->
+      <!-- 下载（P4a Task 4）：两级开关驱动——都关无入口；browse 单按钮；
+           original 可下 → 分体按钮（主=浏览图 + ▾ 菜单两项）。 -->
+      <div
+        v-if="download !== undefined && download.canDownload"
+        class="download-group"
+      >
+        <button
+          type="button"
+          class="control download"
+          :disabled="download.busy"
+          :aria-label="t('download.action')"
+          @click="downloadBrowse"
+        >
+          {{ download.busy ? t('download.busy') : t('download.action') }}
+        </button>
+        <button
+          v-if="download.canDownloadOriginal"
+          type="button"
+          class="control download-caret"
+          :aria-label="t('download.options')"
+          :aria-expanded="downloadMenuOpen"
+          @click="downloadMenuOpen = !downloadMenuOpen"
+        >
+          ▾
+        </button>
+        <div v-if="downloadMenuOpen && download.canDownloadOriginal" class="download-menu" role="menu">
+          <button type="button" role="menuitem" @click="pickDownload('browse')">
+            {{ t('download.action') }}
+          </button>
+          <button type="button" role="menuitem" @click="pickDownload('original')">
+            {{ t('download.original') }}
+          </button>
+        </div>
+      </div>
       <button type="button" class="control close" :aria-label="t('viewer.close')" @click="emit('close')">
         ✕
       </button>
@@ -374,6 +438,41 @@ onBeforeUnmount(() => {
     </button>
 
     <p v-if="extending" class="loading">{{ t('album.loading') }}</p>
+
+    <!-- 下载失败轻提示（端点失败/网络；可重点击重试）。 -->
+    <p v-if="download !== undefined && download.failed" class="download-failed" role="alert">
+      {{ t('download.failed') }}
+    </p>
+
+    <!-- 微信内置浏览器引导（P4a Task 4）：替代直接下载——长按保存 + 复制深链。 -->
+    <div
+      v-if="download !== undefined && download.wechatGuide"
+      class="wechat-guide"
+      role="dialog"
+      aria-modal="true"
+      :aria-label="t('download.wechatTitle')"
+    >
+      <div class="wechat-card">
+        <h2>{{ t('download.wechatTitle') }}</h2>
+        <p>{{ t('download.wechatHint') }}</p>
+        <!-- clipboard 不可用降级：展示可选中文本供手动长按复制。 -->
+        <p v-if="download.copyNotice === 'failed'" class="copy-fallback">{{ download.shareUrl() }}</p>
+        <div class="guide-actions">
+          <button type="button" class="guide-copy" @click="download.copyShareLink()">
+            {{ t('download.copyLink') }}
+          </button>
+          <span v-if="download.copyNotice === 'copied'" class="copy-status" role="status">
+            {{ t('download.copied') }}
+          </span>
+          <span v-else-if="download.copyNotice === 'failed'" class="copy-status" role="status">
+            {{ t('download.copyFailed') }}
+          </span>
+          <button type="button" class="guide-dismiss" @click="download.dismissWechatGuide()">
+            {{ t('download.dismiss') }}
+          </button>
+        </div>
+      </div>
+    </div>
   </div>
 </template>
 
@@ -485,6 +584,125 @@ onBeforeUnmount(() => {
   border-radius: 6px;
   padding: 4px 10px;
 }
+/* —— 下载（P4a Task 4）—— */
+.download-group {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+}
+.control.download {
+  border: 1px solid rgba(249, 250, 251, 0.35);
+  border-radius: 999px 0 0 999px;
+  padding: 4px 12px;
+  font-size: 0.9rem;
+}
+.control.download:disabled {
+  opacity: 0.55;
+  cursor: default;
+}
+.control.download-caret {
+  border: 1px solid rgba(249, 250, 251, 0.35);
+  border-left: none;
+  border-radius: 0 999px 999px 0;
+  padding: 4px 8px;
+  font-size: 0.8rem;
+}
+.download-menu {
+  position: absolute;
+  top: calc(100% + 6px);
+  right: 0;
+  display: grid;
+  min-width: 9em;
+  border-radius: 8px;
+  background: rgba(17, 24, 39, 0.96);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+  overflow: hidden;
+  z-index: 2;
+}
+.download-menu button {
+  border: none;
+  background: transparent;
+  color: #f9fafb;
+  text-align: left;
+  padding: 8px 14px;
+  font-size: 0.9rem;
+  cursor: pointer;
+}
+.download-menu button:hover {
+  background: rgba(255, 255, 255, 0.08);
+}
+.download-failed {
+  position: absolute;
+  bottom: 52px;
+  left: 50%;
+  transform: translateX(-50%);
+  margin: 0;
+  border-radius: 8px;
+  background: rgba(185, 28, 28, 0.92);
+  color: #fef2f2;
+  padding: 6px 14px;
+  font-size: 0.875rem;
+}
+/* —— 微信引导浮层 —— */
+.wechat-guide {
+  position: absolute;
+  inset: 0;
+  z-index: 3;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(17, 24, 39, 0.72);
+  padding: 24px;
+}
+.wechat-card {
+  max-width: 420px;
+  border-radius: 12px;
+  background: #f9fafb;
+  color: #111827;
+  padding: 20px 24px;
+}
+.wechat-card h2 {
+  margin: 0 0 8px;
+  font-size: 1.05rem;
+}
+.wechat-card p {
+  margin: 0 0 12px;
+  font-size: 0.9rem;
+  line-height: 1.6;
+  white-space: pre-line;
+}
+.copy-fallback {
+  user-select: all;
+  word-break: break-all;
+  background: #e5e7eb;
+  border-radius: 6px;
+  padding: 6px 8px;
+}
+.guide-actions {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.guide-actions button {
+  border: none;
+  border-radius: 999px;
+  padding: 6px 16px;
+  font-size: 0.9rem;
+  cursor: pointer;
+}
+.guide-copy {
+  background: #1d4ed8;
+  color: #fff;
+}
+.guide-dismiss {
+  background: #e5e7eb;
+  color: #374151;
+}
+.copy-status {
+  font-size: 0.8rem;
+  color: #6b7280;
+}
 .control.nav {
   position: absolute;
   top: 50%;