# 分享弹窗升级设计（Share Modal Redesign）

> 状态：待用户 review
> 作者：通过 brainstorming 协作完成
> 日期：2026-06-11
> 项目：TopFans（uni-app + Vue 3，`appid: __UNI__F199FF4`，versionCode 109）

## 1. 背景与目标

`frontend/pages/components/ShareModal.vue` 当前只暴露 **2 个**分享入口："保存图片" + "微信好友"。本次升级需扩展到 **5 个分享平台 + 1 个保存图片** 共 6 个按钮，并打通"二维码水印"和"图片合成"两件目前缺失的能力。

**目标平台**：app-plus（iOS / Android）。H5 暂不支持，**为后续接入 `mp-weixin` 预留接口**（前端调用代码不需变更）。

**新增目标 - 分享归因追踪**（用户 2026-06-16 提出）：
- 每次分享动作需记录**当前分享人**的身份标识 `sharer_user_id`（**仅限已登录用户**，未登录用户不能分享，见 § 3.4）
- 每次分享动作需记录**分享来源端**（`system_type`：android / ios / mp-weixin / h5 等，见 § 3 枚举表）
- 这两个字段用于后续追溯分享链路、二级传播、渠道归因（例：用户 A 在 iOS 上分享给用户 B，B 扫码注册/打开后可识别出"来自 A"）

**关键决策**（用户确认）：

| 决策点 | 结论 |
|--------|------|
| 覆盖平台 | 微信好友 / 朋友圈 / QQ 好友 / QQ 空间 / 微博（5 个） |
| 按钮布局 | 单行 6 个图标（保存图片 + 5 分享），`flex: 1` 等分宽度 |
| 保存图片 | 保留为第 6 个按钮 |
| 技术路线 | `uni.share` API（统一跨端，预留 mp-weixin 接入时验证） |
| 分享内容 | **带二维码的合成图** |
| 图片合成 | **前端 Canvas 离屏合成**（方案 A） |
| 二维码来源 | **后端接口**（消除 `ShareReportButtons.vue:75` 的占位图路径 `/static/icon/qrcode-placeholder.png`，该文件实际不存在，见 § 12） |
| 分享人身份字段 | **仅** `sharer_user_id`（强制登录；不提供匿名/share_code 兜底） |
| 分享端识别 | 客户端读取 `uni.getSystemInfo()`（`android` / `ios` / `h5` / `mp-weixin` 等 uni-app 标准值） |
| 归因数据落点 | 新增后端接口 + 同步埋点（详见 § 3.5、§ 8） |
| 未登录用户处理 | **禁止分享**：弹窗上"保存图片"和 5 个分享按钮全部禁用，顶部显示"登录后才能分享"提示并提供登录入口（详见 § 3.4） |

## 2. 架构与组件拆分

```
┌──────────────────────────────────────────────────────────────┐
│ ShareModal.vue (容器：开关/布局/事件编排)                    │
│   ├─ <SharePreviewCard>    渲染分享卡 DOM（已有逻辑迁移）   │
│   ├─ <ShareActionBar>      6 个按钮的纯展示组件              │
│   └─ useShare()            composable：合成+分发+错误处理    │
└──────────────────────────────────────────────────────────────┘
```

| 单元 | 文件 | 职责 | 不做的事 |
|------|------|------|---------|
| `ShareModal.vue` | `frontend/pages/components/ShareModal.vue` | 控制 visible、承载布局、组合子组件、emit close | 写分享/canvas 逻辑 |
| `SharePreviewCard.vue` | `frontend/pages/components/SharePreviewCard.vue` | 渲染封面 + 头像 + 二维码 + 文案（纯模板） | 导出图片、调 API |
| `ShareActionBar.vue` | `frontend/pages/components/ShareActionBar.vue` | 6 按钮单行 flex 布局（`flex: 1` 等分），`emit('pick', action)` | 直接调 `uni.share` |
| `useShare.js` | `frontend/composables/useShare.js` | 状态机、合成调度、错误处理 | 写 UI |
| `image-compositor.js` | `frontend/utils/image-compositor.js` | 纯函数 `composeShareImage(opts) → tempFilePath` | 不感知分享渠道 |

**收益**：
- `image-compositor` 是纯函数 → 易单元测试、不依赖 vue 运行时
- `useShare` 后续可被其他场景复用（长按图片直接分享）
- `ShareActionBar` 是纯展示 → 未来改成 2×3 grid 时只动它一个文件
- 现有 320 行 `ShareModal.vue` 拆细后单文件 < 80 行

> **放置约定**：上述 5 个文件全部按项目现有目录约定放置 —— `pages/components/` 放 vue 组件（与 `ShareReportButtons.vue` 同层）、`composables/` 放 composable（已有 `useDashboardData.js`/`useLaserMint.js` 等）、`utils/` 放纯函数工具（已有 `assetImageHelper.js`/`avatarCache.js` 等）。**不创建新顶层目录**。

## 3. 二维码后端接口契约

`ShareReportButtons.vue:75` 当前用占位图，本设计要求后端出真实二维码。**二维码内容必须编码分享人信息和分享端**，用于二级传播追溯（接收端扫码后能从 URL 参数识别"来自谁"和"从哪个平台"）。

| 项 | 值 |
|----|----|
| Method & Path | `GET /api/v1/share/asset-qrcode/:assetId` |
| Query 参数 | `sharer_user_id`（**必填**，登录用户 ID；与 § 3.4 登录门槛联动，未登录前端不调此接口） |
| | `system_type`（**必填**，系统/平台类型，决定分享来源端的运行环境，值见下表） |
| | `share_target`（可选，候选值 `weixin_friend` / `weixin_moment` / `qq` / `qq_zone` / `sinaweibo` / `save_image`；前端弹窗打开时已知要分享的目标，但本期**不传**，默认所有二维码按 `weixin_friend` 编码，后续按需扩展） |
| 鉴权 | 需要登录态 |

#### `system_type` 取值（分享来源端的系统类型）

> 该字段标识**用户发起分享时所在的客户端运行环境**，用于二级归因中区分渠道。值取自 `uni.getSystemInfo()`，**按需扩展**，后端字段类型 `varchar(32)` 不强制 enum。

| 取值 | 含义 | uni-app 对应 | 优先级 |
|------|------|--------------|--------|
| **`android`** | Android 原生 App（app-plus 打包） | `platform === 'android'` | 高 |
| **`ios`** | iOS 原生 App（app-plus 打包） | `platform === 'ios'` | 高 |
| **`mp-weixin`** | 微信小程序 | `platform === 'mp-weixin'` | 高 |
| **`mp-alipay`** | 支付宝小程序 | `platform === 'mp-alipay'` | 中 |
| **`mp-baidu`** | 百度小程序 | `platform === 'mp-baidu'` | 中 |
| **`mp-toutiao`** | 字节跳动小程序（抖音/头条） | `platform === 'mp-toutiao'` | 中 |
| **`mp-lark`** | 飞书小程序 | `platform === 'mp-lark'` | 低 |
| **`mp-qq`** | QQ 小程序 | `platform === 'mp-qq'` | 中 |
| **`mp-kuaishou`** | 快手小程序 | `platform === 'mp-kuaishou'` | 低 |
| **`mp-xhs`** | 小红书小程序 | `platform === 'mp-xhs'` | 低 |
| **`h5`** | 移动端 H5 页面（含普通浏览器、WebView 内嵌页） | `platform === 'h5'` | 中 |
| **`app-plus`** | uni-app app-plus 通用兜底（Android/iOS 未能识别时） | `platform === 'app-plus'` | 兜底 |
| **`other`** | 上述都未覆盖的新平台/调试场景 | 兜底 | 兜底 |

> **关键说明**：
> - 本期产品**实际覆盖**只有 `android` / `ios` / `mp-weixin`（其中 mp-weixin 待后续小程序上线后启用，见 § 4.4）。其他值仅在 schema 层预留
> - `android` 与 `ios` 由当前 app-plus 客户端上报；`mp-weixin` 待 § 4.4 接入小程序时启用
> - `system_type` 与 `share_target` 是**正交**维度：前者是"分享来源端"（客户端类型），后者是"分享目标渠道"（微信好友/QQ/微博等）。例如「在 Android 上分享到微信好友」= `system_type=android, share_target=weixin_friend」
| 响应 | `200 { qrcode_url: string, expires_at: number }`（Unix 秒，签发后 7 天过期） |
| 失败 | `400`（缺 `sharer_user_id` / `system_type`）、`404`（asset 不存在）、`5xx`（降级） |
| 二维码内容 | `https://h5.topfans.com/asset/{assetId}?from={sharer_user_id}&s={system_type}` |
| | - `from`：分享人用户 ID（短参数名 `from`，节省扫码密度） |
| | - `s`：分享来源端的系统类型（短参数名 `s`；值为 `android` / `ios` / `mp-weixin` 等，见 § 3 枚举表） |
| | h5 落地页解析这两个参数后：
| | 1. 展示资产详情
| | 2. 调埋点 `qr_scan_landing`（带 `from` / `s` / `asset_id`）
| | 3. 若用户未登录 + 跳登录页，登录成功回跳后**预填**邀请码 `from` 到注册请求中（**本期不做**，仅预留 URL 参数） |
| 缓存 | 同一 `(assetId, sharer_user_id, system_type)` 三元组会话内只请求一次（前端 `ref` 缓存）。三元组任一变更 → 重新请求 |
| 续签策略 | `expires_at - now < 24h` 时下次开弹窗**预热**请求（不阻塞 UI）。过期不阻断分享，弹窗打开仍能用缓存的 URL |
| 失败兜底 | 弹窗 UI 用占位图，toast 提示"二维码生成失败，分享图可能无水印" |

**与 image-compositor 协作**：`composeShareImage` 接收一个**已下载到本地的** `qrcodeLocalPath`（经过 `uni.downloadFile`），不再关心来源是后端还是占位图。

### 3.3 二维码请求示例

**前端调用**（`useShare` 内部）：

```js
async function fetchQrcode(assetId) {
  // 1. 取登录用户信息（同步 OK，storage 读取不阻塞 UI）
  const userInfo = JSON.parse(uni.getStorageSync('user') || '{}');

  // 2. 取系统类型（异步，避免阻塞 UI 线程）
  const { platform } = await uni.getSystemInfo();

  // 3. 调后端二维码接口
  const res = await uni.request({
    url: `/api/v1/share/asset-qrcode/${assetId}`,
    method: 'GET',
    data: {
      sharer_user_id: userInfo.id,
      system_type:    platform
    }
  });
  return res.data; // { qrcode_url, expires_at }
}
```

> **为什么用 `uni.getSystemInfo()` 而不是 `uni.getSystemInfoSync()`**：
> - `getSystemInfoSync` 在低端机上可能阻塞 UI 主线程数十毫秒（特别是冷启动首次调用时）
> - `getSystemInfo` 是异步 Promise API，不阻塞 UI；现代 uni-app 最佳实践推荐异步版本
> - 当前业务场景（弹窗打开时调用）用户对延迟敏感，应优先用异步版本

**后端生成逻辑**（伪代码）：
```go
func (h *Handler) GetAssetQrcode(c *gin.Context) {
    assetID := c.Param("assetId")
    sharerUserID := c.Query("sharer_user_id")  // 必填，未填返 400
    systemType   := c.Query("system_type")     // 必填，未填返 400

    // 1. 校验资产存在
    // 2. 拼接目标 URL：https://h5.topfans.com/asset/{assetId}?from={sharerUserID}&s={systemType}
    // 3. 用 qrcode 库生成 PNG，转 CDN URL
    // 4. 写缓存 share:qrcode:{assetId}:{sharerUserID}:{systemType} → qrcode_url，TTL 7d
    // 5. 返回 { qrcode_url, expires_at }
}
```

**后端缓存键设计**：
- Redis key 格式：`share:qrcode:{asset_id}:{sharer_user_id}:{system_type}`
- TTL：7 天（与 `expires_at` 一致）
- 命中后直接返回缓存的 `qrcode_url`，不重新生成
- 不同 sharer 分享同一个 asset → 生成不同二维码（因为 `from` 参数不同）

> **后端可选优化（YAGNI：本期不做）**：用短链服务把 `https://h5.topfans.com/asset/12345?from=678&s=android` 缩短为 `https://t.fans/a8K2` 之类的短链，进一步降低二维码密度。本期直接用完整 URL，落地页跳转用 query 参数解析。

### 3.4 未登录用户禁止分享（登录门槛）

**结论**：用户必须登录后才能触发任何分享动作（保存图片 + 5 个分享按钮）。这是产品侧对 2026-06-16 反馈的最终决策：**只登录用户才能分享**，不做匿名 / 临时分享码兜底。

**为什么不做匿名分享**：
- 归因数据质量：匿名用户无法追溯到具体账号，渠道归因统计价值低
- 业务诉求：分享行为本身是用户主动传播行为，登录门槛可筛掉机器人/脚本刷量
- 隐私更简单：无需设计 `share_code` 生成 / 存储 / 清理机制

**前端处理**：

| 触发点 | 检查项 | 未登录时行为 |
|--------|--------|------------|
| 用户点击"分享"按钮（`ShareReportButtons.vue:handleShare`） | `uni.getStorageSync('user')` 是否存在且能解析出有效 `user_id` | 不打开弹窗，弹 toast「请先登录」并跳转到登录页（沿用项目现有登录跳转逻辑） |
| 直接渲染 `<ShareModal>`（其他调用方未来可能直接传 `visible=true`） | `useShare` 初始化时检查登录态 | 不渲染 6 个按钮，弹窗内显示"登录后才能分享"提示 + 「去登录」按钮 |

**未登录态弹窗 UI**：

```
┌────────────────────────────────────┐
│  ✕  分享藏品                       │
├────────────────────────────────────┤
│                                    │
│     [图片预览区域 - 仍然渲染]      │
│                                    │
│                                    │
│  ┌──────────────────────────────┐  │
│  │ 🔒 登录后才能分享            │  │
│  │                              │  │
│  │   [ 去登录 ]  [ 再看看 ]      │  │
│  └──────────────────────────────┘  │
│                                    │
└────────────────────────────────────┘
```

- 保留图片预览（让用户看到要分享什么）
- 6 个分享按钮**完全不渲染**（不是 disabled，而是 v-if 移除，避免 DOM 探嗅）
- 「去登录」点击后 emit('close') + 跳转登录页
- 「再看看」点击后 emit('close')

**后端校验**：即便前端做了拦截，`POST /share/track` 也必须做服务端二次校验：

```go
// share track handler
// 注：TrackShareRequest 中 SharerUserId 定义为 int64（值类型，非指针）
func (h *Handler) TrackShare(ctx context.Context, req *TrackShareRequest) (*TrackShareResponse, error) {
    // 二次拦截：从 JWT token / context 取当前用户 ID 与请求中传入的 SharerUserId 比对
    currentUserID := auth.GetUserIDFromContext(ctx)
    if currentUserID == 0 {
        return nil, codex.NewError(codex.ErrUnauthorized, "请先登录后再分享")
    }
    if req.SharerUserId != currentUserID {
        // 防止越权：前端篡改 user_id 上报他人
        return nil, codex.NewError(codex.ErrForbidden, "分享人 ID 与当前登录用户不一致")
    }
    // ... 后续落库逻辑
}
```

- 缺 `sharer_user_id` 直接返回 `ErrUnauthorized`（业务码 +1xxxxx）
- 不依赖前端拦截，前端漏洞不污染数据库
- 详见 § 3.5 接口契约（`sharer_user_id` 改为必填）

### 3.5 分享归因追踪接口（新增）

每次分享动作（无论成功 / 失败 / 取消）需调用后端接口记录**分享人**和**分享端**，用于渠道归因、二级传播追溯。**调用前必须已登录**（见 § 3.4）。

| 项 | 值 |
|----|----|
| Method & Path | `POST /api/v1/share/track` |
| Content-Type | `application/json` |
| 鉴权 | **强制**（缺 `sharer_user_id` 直接 401） |
| 请求体 | 见下方 Request Body |
| 响应 | `200 { topfans.common.BaseResponse base = 1; int64 share_event_id = 2; }`（`share_event_id` 为后端落库的事件 ID） |
| 失败 | `401`（未登录）、`4xx`（参数错误，**前端不重试**）/ `5xx`（前端**静默失败**，不阻断分享流程，不弹 toast） |

#### Request Body

```jsonc
{
  "asset_id":        12345,                            // 必填，被分享的资产 ID
  "sharer_user_id":  678,                              // 必填，已登录用户 ID（前端从 storage 取）
  "system_type":     "android" | "ios" | "mp-weixin" | "mp-alipay" | ...,  // 必填，uni.getSystemInfo()
  "share_target":    "weixin_friend" | "weixin_moment" | "qq" | "qq_zone" | "sinaweibo" | "save_image",  // 必填，本次分享的目标渠道
  "result":          "success" | "cancel" | "fail_app_missing" | "fail_network" | "fail_canvas" | "fail_other",  // 必填，分享结果
  "client_ts":       1718500000000,                    // 必填，客户端时间戳（毫秒）
  "extra": {                                           // 可选，扩展字段
    "app_version":   "1.0.0",
    "os_version":    "Android 13",
    "device_id":     "..."                             // 用于风控的去标识化设备指纹
  }
}
```

#### 字段补充说明

- **`sharer_user_id`**：**必填**，从 `uni.getStorageSync('user').id` 取。后端校验该用户存在且状态正常（未注销/封禁），否则返回 401
- **`system_type` 取值**：直接传 `uni.getSystemInfo()` 的值。uni-app 标准枚举包括 `android` / `ios` / `h5` / `mp-weixin` / `mp-alipay` / `mp-baidu` / `mp-toutiao` / `mp-lark` / `mp-qq` / `mp-kuaishou` / `mp-xhs` / `app-plus`。后端字段类型用 `varchar(32)`，不强制 enum（保留扩展性）。**完整取值表见 § 3** |
- **写库 vs 异步队列**：本期**直接同步写库**（`share_events` 表）。如果未来 QPS 上升导致 DB 压力，可改为异步 MQ，本期不做
- **隐私**：已登录用户场景下不存在 PII 问题（`user_id` 本身就是业务标识）；GDPR 合规要求下后端仍可保留 90 天滚动清理机制（**本期不做**，由运营/法务后续提需求）

#### 数据库表设计

```sql
-- 分享事件追踪表（落库 share_events）
CREATE TABLE IF NOT EXISTS share_events (
    id              BIGSERIAL PRIMARY KEY,
    asset_id        BIGINT          NOT NULL,                -- 被分享的资产
    sharer_user_id  BIGINT          NOT NULL,                -- 分享人用户 ID（强制非空：见 § 3.4）
    system_type     VARCHAR(32)     NOT NULL,                -- android / ios / mp-weixin / h5 ...（见 § 3 枚举表）
    share_target    VARCHAR(32)     NOT NULL,                -- weixin_friend / qq / sinaweibo / save_image
    result          VARCHAR(32)     NOT NULL,                -- success / cancel / fail_*
    client_ts       BIGINT          NOT NULL,                -- 客户端时间戳（毫秒）
    server_ts       BIGINT          NOT NULL DEFAULT (EXTRACT(EPOCH FROM NOW()) * 1000)::BIGINT,
    extra           JSONB           DEFAULT '{}'::jsonb,     -- 扩展信息（app_version / os_version / device_id）
    
    CONSTRAINT fk_share_events_sharer FOREIGN KEY (sharer_user_id) REFERENCES users(id) ON DELETE RESTRICT
);

CREATE INDEX idx_share_events_asset_id    ON share_events (asset_id);
CREATE INDEX idx_share_events_sharer      ON share_events (sharer_user_id);
CREATE INDEX idx_share_events_system_type ON share_events (system_type);
CREATE INDEX idx_share_events_server_ts   ON share_events (server_ts DESC);

-- 序列起始值预留（按 CLAUDE.md 数据库规范）
CREATE SEQUENCE share_events_id_seq START WITH 10000;
```

> **设计变化**（对比初版）：移除 `share_code` 列与相关约束/索引；`sharer_user_id` 改为 `NOT NULL`；新增 `FOREIGN KEY` 约束确保分享事件始终关联有效用户。

#### 客户端调用流程

- **触发时机**：`uni.share` 回调（success / fail）或 `uni.saveImageToPhotosAlbum` 回调后
- **前置校验**：`useShare` 内部 `pick()` 时先确认 `currentUserId` 非空（前端 § 3.4 二次拦截，避免误上报）
- **失败兜底**：接口调用失败时**不弹 toast**、**不重试**、**不阻断**当前分享流程。最多在 console.warn 输出一行
- **批量上报**（**YAGNI：本期不做**）：理论上可以攒批上报（10s 一次），本期先按"每次分享 = 一次 HTTP 请求"实现。后续如果出现 QPS 瓶颈再优化
- **节流保护**：单用户 1s 内最多上报 5 次（前端 `useShare` 内部维护计数器 + setTimeout 节流），防止异常情况下被刷

## 4. `manifest.json` 配置变更

### 4.1 启用 Share 模块与 URL Scheme

```jsonc
"app-plus": {
  "modules": {
    "Share": {},              // 新增
    "VideoPlayer": {},
    "Camera": {},
    "Speech": {},
    "Push": {}
  },
  "distribute": {
    "android": {
      "schemes": ["topfans"]    // 新增（数组类型，不是字符串）
    },
    "ios": {
      "urltypes": [           // 新增
        { "urlschemes": ["topfans"] }
      ]
    }
  }
}
```

### 4.2 各平台 SDK 凭证

```jsonc
"sdkConfigs": {
  "share": {
    "weixin": {
      "appid":         "<TBD: 微信开放平台移动应用 AppID>",
      "UniversalLinks": "https://h5.topfans.com/uni-universallinks/"
    },
    "qq": {
      "appid":         "<TBD: QQ 互联移动应用 AppID>"
    },
    "sinaweibo": {
      "appid":         "<TBD: 微博开放平台 AppID>"
    }
  }
}
```

#### 4.2.1 `uni.share` 的 `provider` / `scene` 字段映射

| 按钮 | `provider` | `scene` | 备注 |
|------|-----------|---------|------|
| 微信好友 | `weixin` | `WXSceneSession` | 单聊/群聊 |
| 朋友圈 | `weixin` | `WXSceneTimeline` | 朋友圈 |
| QQ 好友 | `qq` | `""`（空串） | QQ SDK 用 `type: 0` 区分，本 spec 暂不依赖 type |
| QQ 空间 | `qq` | `""`（空串） | 同上 |
| 微博 | `sinaweibo` | `undefined`（不传该字段） | 微博 SDK 无 scene 概念，传空串可能被 SDK 拒收 |

> ⚠️ 微信/QQ 的 AppID 必须在**开放平台/互联**申请「移动应用」（不能用现有小程序/公众号 AppID），且必须配置 Android 应用签名 SHA1 和 iOS Universal Links，否则 `uni.share` 调起后会被对方 App 拒绝。

> ⚠️ **manifest schema 准确性问题**：上述 `sdkConfigs.share.*` 结构按 uni-app 官方文档（2024 版）的最小必填字段给出。但各 SDK 实际接入时可能需要 `iOS` / `Android` 子块（如 weixin 的 `{ appid, UniversalLinks, iOS: { appid }, Android: { appid, sha1 } }`）以适配两端差异。**实施时需以 [uni-app 官方 manifest 文档](https://uniapp.dcloud.net.cn/manifest/share.html) 当时的字段为准**。本 spec 不锁死字段结构，落地时以官方文档 + 各开放平台申请时的回调指引为准。

> ⚠️ **iOS Universal Links 后端配合**：Universal Links 路径 `https://h5.topfans.com/uni-universallinks/` 下**必须**部署 `apple-app-site-association` 文件（无后缀的 JSON），内容至少包含：
> ```json
> {
>   "applinks": {
>     "apps": [],
>     "details": [{ "appIDs": ["<TeamID>.com.topfans.app"], "components": [{ "/": "/uni-universallinks/*", "comment": "match" }] }]
>   }
> }
> ```
> **需后端/运维在落地 manifest.json 前确认已部署该文件**。

> ⚠️ **微博 OAuth 路径澄清**：纯图片分享（`uni.share({provider: 'sinaweibo', imageUrl, ...})`）**不需要** `redirect_uri`，那是微博 OAuth 登录场景（`uni.login({provider: 'sinaweibo'})`）才需要。本 spec 仅做图片分享，**不**配置 redirect_uri。

### 4.3 平台未安装的探测

`uni.share` 的 fail 回调无法区分"用户取消"和"App 未安装"，需**前置探测**：

| 平台 | Android pname | iOS bundleid |
|------|---------------|--------------|
| 微信 | `com.tencent.mm` | `com.tencent.xinWeChat` |
| QQ | `com.tencent.mobileqq` | `com.tencent.mqq` |
| 微博 | `com.sina.weibo` | `com.sina.weibo` |

通过 `plus.runtime.isApplicationExist({ pname / bundleid })` 探测，未安装时 `uni.showToast({ title: '请先安装微信' })` 直接返回，不调 `uni.share`。

> **跨端判空**：`plus.runtime` 在 **h5 / mp-weixin 端是 `undefined`**。需写为：
> ```js
> function isAppInstalled(pname, bundleid) {
>   if (typeof plus === 'undefined' || !plus.runtime) {
>     return true; // 非 app-plus 端：跳过探测（小程序有自己的 wx.canIUse / h5 用 navigator）
>   }
>   return new Promise(resolve => {
>     // 5+ API 回调签名：callback({ exist: boolean })
>     plus.runtime.isApplicationExist({ pname, bundleid }, e => resolve(!!e.exist));
>   });
> }
> ```

### 4.4 后续接小程序的预留（**YAGNI**：本期不实施）

> ⚠️ 本节为**预留/参考资料**，**本期不实施、不实现、不进入 plan**。移到此处仅为不丢失长期设计意图。

`mp-weixin.appid: ""`（manifest 当前值）填上后，`uni.share` 在小程序端**理论上**自动用 `wx.miniProgram.shareTo*` API，前端调用代码不需要改。**这是当时推荐方案 A 的关键收益之一，但需要在 mp-weixin 真机/IDE 上实测验证**（uni-app 对 `imageUrl` + `provider: 'weixin'` 在小程序端的转译行为，文档与实际实现可能不一致）。

**降级路径**（实测后再决定）：若发现 uni.share 在小程序端不支持 imageUrl-only 分享，则降级为 `uni.showShareMenu` + `onShareAppMessage`。`onShareAppMessage` 是页面级生命周期，弹窗组件内无法注册，需在承载页面（如 `asset-detail.vue`）提供该钩子。具体 handoff 协议（`getApp().globalData` 还是 EventBus）待接入时再设计。

## 5. 分享时序

### 5.1 状态机

```
         ┌────────┐  pick(action)
         │  idle  │ ────────────►┌────────────┐
         └───┬────┘               │ composing  │
             │ 弹窗关闭/取消      └──┬─────┬───┘
             │◄─────────────────────┘     │ 成功
             │                            ▼
             │                       ┌────────────┐
             │                       │  sharing   │ 失败
             │                       └──┬─────┬───┘ ◄──┐
             │                          │     │       │
             │                          │     ▼       │
             │                          │  ┌────────┐ │
             │                          │  │  done  │─┘
             │                          │  └────────┘  2s 后自动关闭弹窗
             │                          │
             │                          ▼
             │                       ┌────────┐
             │   pick(again) ────────►│ error  │ 用户再次点任意按钮
             │                       └────┬───┘
             │◄───────────────────────────┘ 回到 composing 重试
             │
             ▼
          ┌────────┐
          │  idle  │ (任何状态点关闭弹窗 / emit('close'))
          └────────┘
```

| 状态 | UI 反馈 |
|------|---------|
| `composing` | 半透明遮罩 + 菊花转圈，禁用 6 个按钮 |
| `sharing` | 系统分享面板已弹出，前端不强 loading（避免双重弹窗） |
| `done` | `uni.showToast('分享成功')`，2s 后自动关闭弹窗 |
| `error` | `uni.showToast` 错误文案，弹窗保持打开，用户可重试 |

### 5.2 端到端时序

**阶段 A：弹窗打开 + 拉 QR code**

```
用户       ShareReportButtons  ShareModal   useShare       后端
 │             │                  │              │              │
 │ 点击[分享]  │                  │              │              │
 │─────────────►                  │              │              │
 │             │ showShareModal=t │              │              │
 │             │─────────────────►│              │              │
 │             │                  │ onMounted/   │              │
 │             │                  │ watch(visible)             │
 │             │                  │─────────────►│              │
 │             │                  │              │ GET /share/  │
 │             │                  │              │ asset-qrcode │
 │             │                  │              │─────────────►│
 │             │                  │              │◄─────────────│
 │             │                  │              │ qrcode_url   │
 │             │                  │ props.qrcodeUrl = qrcode_url
 │             │                  │ 渲染预览卡  │              │
```

**阶段 B：用户选平台 → 探测 → 合成 + 分享**

> **关键顺序**：**便宜操作（探测）先于昂贵操作（合成）**。App 没装就根本不该进入 composing 状态，也省一次 downloadFile + canvas。

```
用户       ShareActionBar   useShare      image-compositor   uni.share   微信/QQ/微博
 │             │              │                 │              │            │
 │ 点击[微信]  │              │                 │              │            │
 │─────────────►              │                 │              │            │
 │             │ emit('pick') │                 │              │            │
 │             │─────────────►│                 │              │            │
 │             │              │ 探测 App 是否安装(plus.runtime)              │
 │             │              │  ↓ 未装 → setState(error)+toast+return       │
 │             │              │  ↓ 已装 ↓               │            │
 │             │              │ setState(composing)│            │            │
 │             │              │  (loading 效果由 composing 状态驱动 v-if)    │
 │             │              │                 │              │            │
 │             │              │ composeShareImage(opts)        │            │
 │             │              │────────────────►│              │            │
 │             │              │                 │ downloadFile │            │
 │             │              │                 │ (cover/qr/   │            │
 │             │              │                 │  avatar)     │            │
 │             │              │                 │ canvas draw  │            │
 │             │              │                 │ canvas.toTempFilePath      │
 │             │              │ ◄───────────────│              │            │
 │             │              │ tempFilePath    │              │            │
 │             │              │                                 │            │
 │             │              │ uni.share({provider, scene, imageUrl})            │
 │             │              │─────────────────────────────────►            │
 │             │              │                                 │  唤起 App  │
 │             │              │                                 │───────────►│
 │             │              │                                 │  等待回调  │
 │             │              │                                 │◄───────────│
 │             │              │ ◄───────────────────────────────│            │
 │             │              │ success / fail(errMsg)         │            │
 │             │              │ showToast() / emit('close')    │            │
```

### 5.3 `composeShareImage` 契约

```js
// 入参对象 ComposeOpts
//   coverLocalPath:    string  本地封面临时文件路径（已由 useShare 调 uni.downloadFile 转换）
//   qrcodeLocalPath:   string  本地二维码临时文件路径（缺失时回退到 /static/share/mock_qrcode.png）
//   avatarLocalPath:   string  本地头像临时文件路径（缺失时回退到 /static/square/gerenzhongxinkangpinkuang.png）
//   nickname:          string  用户昵称（缺首字母时回退到 'T'）
//   slogan:            { brandLine: string, brandDesc: string }? 默认由 useShare 从 BRAND_SLOGANS 随机抽取一条（见 § 5.3.2）
//
// 返回 Promise，resolve 后得到 { tempFilePath, width, height }
//   tempFilePath: 本地临时文件路径，可直接传给 uni.share / uni.saveImageToPhotosAlbum
//   width/height: 物理像素（不是 rpx）
//
// 重要：本函数不发起任何网络 IO，所有 *LocalPath 由 useShare 提前下载
export function composeShareImage(opts) { /* ... */ }
```

合成图层（统一画布 750×1334 px，固定物理像素，不使用 rpx）：

| 层 | 元素 | 位置（y 范围，px） | 覆盖底层 | 来源（**本地路径**，由 useShare 提前 `uni.downloadFile` 转好） |
|----|------|-------------------|---------|------|
| L0 | 750×1334 白底背景 | 整图 0~1334 | — | 固定 fillRect（同时规避 iOS 离屏 canvas 黑底） |
| L1 | 750×1000 封面 | 顶部 0~1000 | ❌ | `coverLocalPath` `aspectFill` 缩放 |
| L2 | 头像圆 (240×240 px) + "ID: {nickname}" 文字 | y=720~960 | ✅（在 L1 上叠加） | `avatarLocalPath` + `nickname` |
| L3 | 二维码 (240×240 px) + 边框背景 | y=960~1200 | ✅（在 L1 上叠加） | `qrcodeLocalPath` |
| L4 | `{slogan.brandLine}` + `{slogan.brandDesc}` | y=1200~1334 | ✅（在 L0 上叠加） | `slogan` 入参（由 useShare 从 `BRAND_SLOGANS` 随机抽取，见 § 5.3.2） |


> **覆盖关系关键点**：L2 / L3 都在 L1（封面）之上叠加绘制（海报布局），L4 在 L0 之上叠加。L1 顶部 0~1000 区域不被 L2 遮挡的部分（y=0~720）即为封面顶部净空。L3 底部 1200 处开始让位给 L4。
>
> 输出物理尺寸固定 750×1334（iOS 分享面板对最大边有压缩，1334 在 iPhone 6 之后机型上不会触发压缩降级）。L0 已 fillRect 白底，若仍出现黑底可加 `uni.compressImage` 二次处理。

### 5.3.1 `useShare()` 初始化约定

- **生命周期**：`ShareModal.vue` 在 `<script setup>` 顶层调用一次 `const { state, pick } = useShare({ ... })`。**不**在 `pick()` 内临时创建 composable（避免每次丢失缓存）。
- **入参与 composeKey 约定**（**重要：自洽设计**）：
  - `useShare` 接收 props = `{ coverUrl, qrcodeUrl, avatarUrl, nickname }`（**全部远程 URL**），由 `ShareModal` 从 `ShareReportButtons` 透传进来
  - **首次 pick** 时 `useShare` 内部 `uni.downloadFile` 把 3 个 URL 转 local path，然后**用 local path** 算 `composeKey`（确保 nickname 变化 / 头像变化 / 远端图被替换都能触发重合成）
  - **后续 pick**（弹窗内切换平台）复用缓存的 local path（`uni.downloadFile` 结果本身可缓存），不再重复下载
  - props（URL）变化时 `watch` 触发 **缓存失效 + 清除 lastLocalPaths**，下次 pick 重新 download
- **品牌文案初始化**（新增）：
  - `useShare` 顶层初始化时调一次 `pickRandomSlogan()`（见 § 5.3.2），结果缓存为闭包内常量 `currentSlogan`
  - 整个弹窗会话内 `currentSlogan` 不变（避免同一弹窗切换平台时文案跳变）
  - 弹窗关闭后下次再开 → 重新随机抽一条（用户每次打开看到不同文案的概率高，增加新鲜感）
  - `composeShareImage(opts)` 调用时把 `slogan: currentSlogan` 传入，**L4 层渲染时使用**
- **两级缓存**（**仅进程内有效**，不做持久化）：
  - **L1 内存缓存**（`useShare` 闭包内 `Map`）：key = `composeKey`（用 local path + slogan 算，见 § 5.4），value = `tempFilePath`。弹窗打开期间切换平台直接命中。
  - **L2 模块级缓存**（`image-compositor.js` 顶层 `Map`）：跨 `useShare` 实例（同一进程内 `ShareModal` 多次 mount / 多个组件同时使用）共享。**最多保留 20 条**，LRU 淘汰。
  - **不持久化原因**：`uni.saveImageToPhotosAlbum` / `uni.share` 使用的本地临时文件路径在 app 进程结束后失效，写入 `uni.storage` 在下次启动时拿到也是死路径。`uni.storage` 只适合存**元数据**（如 composeKey → 远端 URL），不适合存**文件路径**。
  - **查询顺序**：L1 → L2 → composeShareImage
- **5s/15s 无回调兜底（按平台差异化）**：`uni.share` 调起后启动定时器，到时若仍在 `sharing` 状态（无 success / fail 回调），强制 `setState('idle')` + 弹 L2 toast"分享超时，请重试"。该机制与 § 9 iOS 偶发无回调问题对应。**时长按 provider 区分**：
  - `weixin` / `qq`：5s（系统面板唤起快，5s 足够）
  - `sinaweibo`：15s（微博 SDK 唤起 + 渲染慢，5s 容易误判为失败导致假阳性）
  - **假阳性缓解**：除超时外，再叠加一个"app 失焦"判断——监听 `App.onHide`（uni-app 应用生命周期，对应底层 `plus.runtime` 的 `pause` 事件）触发即 **clearTimeout 定时器**，避免用户正在系统分享面板上选好友时被强制重置。
  - **app 回到前台兜底**：`App.onShow` 触发时若 `state` 仍为 `sharing`（说明回调一直没来），启动 8s 兜底定时器，到时强制重置（避免用户回到 app 后 state 永远卡在 sharing）。
- **多组件复用**：`ShareReportButtons.vue`（当前调用方）未来可继续用同一 composable；新增"长按图片直接分享"场景时再开一个 composable 实例即可。


### 5.3.2 品牌文案随机选取

L4 文案从候选池中**每个会话随机抽取一条**（不是每次合成重抽），避免同一弹窗打开期间切换平台看到不同文案的诡异体验。

**数据源**（新增文件）：

```js
// frontend/utils/brand-slogans.js (新增)
export const BRAND_SLOGANS = [
  { brandLine: 'TOPFANS，让热爱被发现',  brandDesc: 'AI做周边，应援全免费' },
  { brandLine: 'TOPFANS，星河璀璨',         brandDesc: '为你喜爱的明星加油' },
  { brandLine: 'TOPFANS，你的应援主场',      brandDesc: '百万粉丝在线互动' },
  { brandLine: 'TOPFANS，与你同频',         brandDesc: '把热爱变成专属周边' },
  { brandLine: 'TOPFANS，热爱可抵岁月长',    brandDesc: '一键定制你的专属应援' },
  { brandLine: 'TOPFANS，粉丝的小宇宙',      brandDesc: '和同好一起为爱发电' },
  { brandLine: 'TOPFANS，让世界看见你',      brandDesc: 'AI 让应援更有趣' },
  { brandLine: 'TOPFANS，为热爱加冕',        brandDesc: '你的应援值得被收藏' }
  // ... 共 8~12 条，运营/设计后续可调整
];

export function pickRandomSlogan() {
  return BRAND_SLOGANS[Math.floor(Math.random() * BRAND_SLOGANS.length)];
}
```

**useShare 集成**（在 § 5.3.1 初始化约定中增加）：

- `useShare` 在 `<script setup>` 顶层（首次挂载时）调用 `pickRandomSlogan()` 一次，缓存为闭包内变量 `currentSlogan`
- 整个弹窗会话期间 `currentSlogan` 不变（**不论切换多少次平台都复用同一条**）
- 弹窗关闭后下次再开 → 重新随机抽一条（用户感知到"每次打开文案可能不一样"，增加新鲜感）
- `composeShareImage` 调用时把 `currentSlogan` 作为 `slogan` 字段传入

**缓存键影响**：`composeKey` 计算时必须把 `slogan` 也算进去（不同文案 → 不同合成图）。具体更新见 § 5.4。

**手动换一句**（**YAGNI：本期不做**）：弹窗底部未来可加"换一句文案"按钮，调用 `pickRandomSlogan()` 重抽并触发 `composeShareImage` 重新合成。本期不实现，文案每会话稳定即可。

### 5.4 跨分享复用合成图

`useShare` 内部维护**两级进程内缓存**（实现细节见 § 5.3.1）：

- **L1 内存缓存**（`useShare` 闭包内 `Map<composeKey, tempFilePath>`）：弹窗打开期间切换平台直接命中
- **L2 模块级缓存**（`image-compositor.js` 顶层 `Map<composeKey, tempFilePath>`）：跨 `useShare` 实例 / 多次 mount 复用，最多 20 条 LRU

```js
if (l1Cache.has(composeKey) || l2ModuleCache.has(composeKey)) {
  // 跳过 composeShareImage，直接调 uni.share
  return l1Cache.get(composeKey) || l2ModuleCache.get(composeKey);
}
```

> **不再使用 `uni.storage` 持久化**（理由见 § 5.3.1：临时文件路径进程结束后失效）。

`composeKey` 用 `coverLocalPath + qrcodeLocalPath + avatarLocalPath + nickname + slogan.brandLine + slogan.brandDesc` 做 hash（`useShare` 内部 download 后的 local path + 当前会话的随机 slogan，详见 § 5.3.1 / § 5.3.2），**任一变更则重合成**（含用户换头像场景、含 slogan 重新随机场景）。

### 5.5 错误码映射

| 错误源 | 用户提示 |
|--------|---------|
| `downloadFile` 失败 | "图片加载失败，请重试" |
| canvas 导出失败 | "图片生成失败，请重试" |
| `isApplicationExist` 返回 false | "请先安装 {微信/QQ/微博}" |
| `uni.share` fail 且 errMsg 含 `cancel` | **静默不弹 toast** |
| `uni.share` fail 其他 | "分享失败，请稍后再试" |

**errMsg 平台差异**：`cancel` 关键字需要做平台兼容：

```js
function isUserCancel(errMsg = '') {
  // iOS: "user cancel" / "cancel"（英文）
  // Android: "用户取消" / "取消"（中文，部分 SDK 报英文 "cancel"）
  // 注：h5 端 navigator.share 报 "AbortError"，但本 spec 不做 h5（§ 13），故不匹配
  return /cancel|取消/i.test(errMsg);
}
```

### 5.6 归因追踪调用流程

分享动作结束（success / fail / cancel 任一回调触发）后，**调用追踪接口**记录分享人 + 分享端：

```
用户       ShareActionBar   useShare      后端追踪接口
 │             │              │                 │
 │ 选完平台    │              │                 │
 │ uni.share  │              │                 │
 │ 回调触发    │              │                 │
 │             │              │                 │
 │             │              │ 准备 payload   │
 │             │              │  - sharer_user_id (从 storage 取，登录态校验)
 │             │              │  - system_type (uni.getSystemInfo())
 │             │              │  - share_target  (本次选的平台)
 │             │              │  - result        (success / cancel / fail_*)
 │             │              │  - asset_id
 │             │              │  - client_ts     (Date.now())
 │             │              │                 │
 │             │              │ POST /share/track
 │             │              │────────────────►│
 │             │              │                 │ 校验登录态 + 写库 share_events
 │             │              │◄────────────────│
 │             │              │ { share_event_id } | 401 Unauthorized
 │             │              │ (失败静默)       │
```

**关键约束**：
- 追踪接口调用**不影响**弹窗关闭、toast 显示等用户感知行为。`uni.share` 回调触发后**先**走弹窗关闭 / toast 流程，**再** fire-and-forget 调追踪接口（await 不阻塞 UI）
- 取消分享（`cancel`）**也**要上报（用于统计「分享被取消率」），仅 `result: 'cancel'`
- 失败同样上报（用于渠道失败率归因），按 § 5.5 错误码映射填 `result`
- **保存图片** 走同一接口，`share_target: 'save_image'`
- **`sharer_user_id` 取值**：从 `uni.getStorageSync('user').id` 取（项目现有登录逻辑已写 storage）。`useShare` 内部在 `pick()` 入口再做一次非空校验（防 § 3.4 拦截被绕过）

**登录态校验示例代码**（位于 `useShare` 内部）：

```js
function pick(action) {
  // 前端二次拦截：未登录不进入分享流程（兜底 § 3.4）
  const userStr = uni.getStorageSync('user');
  if (!userStr) {
    uni.showToast({ title: '请先登录', icon: 'none' });
    setTimeout(() => uni.navigateTo({ url: '/pages/login/login' }), 800);
    return;
  }
  const userInfo = JSON.parse(userStr);
  if (!userInfo?.id) {
    uni.showToast({ title: '请先登录', icon: 'none' });
    return;
  }
  // ... 后续 composing/sharing 流程
}
```


## 6. 图标资源

当前 `ShareModal.vue` 用了错误的占位图（`wenhao.png`、`shangxiahuadong.png`），新增以下资源到 `frontend/static/share/`：

> 资源文件尺寸按**物理像素**（设计稿 @2x），uni-app 在样式里用 `rpx` 标注显示尺寸。设计稿宽度基准 750rpx。

| 资源路径 | 用途 | 文件物理像素（@2x） |
|---------|------|---------------------|
| `/static/share/ic_wechat_friend.png` | 微信好友 | 192×192 px |
| `/static/share/ic_wechat_moment.png` | 朋友圈 | 192×192 px |
| `/static/share/ic_qq.png` | QQ 好友 | 192×192 px |
| `/static/share/ic_qq_zone.png` | QQ 空间 | 192×192 px |
| `/static/share/ic_weibo.png` | 微博 | 192×192 px |
| `/static/share/ic_save_image.png` | 保存图片 | 192×192 px |
| `/static/share/ic_loading.gif` | 合成中菊花（可选） | 128×128 px |

设计风格保持弹窗调性（白色线性图标 + 阴影），参考小红书/微信原生分享面板的视觉。

> ⚠️ **商标风险**：微信 / QQ / 朋友圈 / QQ空间 / 微博 的官方 logo 是注册商标。**不能直接用各平台官方 PNG**。落地时有两种走法：
> 1. **简化图形 + 品牌色**：用文字 "微信" "朋友圈" "QQ" "空间" "微博" 配合各自品牌色（微信绿 #07C160 / QQ 蓝 #1296DB / 微博橙 #E6162D）的简化形状（气泡/相机/铅笔），**自行设计**后提交设计 review
> 2. **走法 B**：若已获得品牌方书面授权（市场/法务确认），才允许使用官方 logo
>
> **本 spec 默认采用走法 1**（简化图形 + 文字 + 品牌色），由设计师出图后再最终替换。

## 7. 错误处理分级

| 错误等级 | 触发条件 | 用户体验 | 是否上报 |
|---------|---------|---------|---------|
| **L0 静默** | `uni.share` fail 且 errMsg 含 `cancel` | 不弹 toast，弹窗可继续点 | ❌ |
| **L1 提示** | App 未安装/参数错误 | `uni.showToast` 显示 1.5s（toast 期间按钮可点） | ✅ |
| **L2 重试** | 网络/download 失败 | toast 显示 1.5s 期间按钮可点（toast 不阻塞），toast 消失后弹窗保持，用户可点任意按钮自由重试 | ✅ |
| **L3 兜底** | canvas 导出失败 / 多次重试仍失败 | toast "分享暂不可用" + **显示「复制链接」降级入口** | ✅ |

**「复制链接」降级**（L3）：**单次弹窗会话内** L1+L2 失败累计 ≥ 2 次后，弹窗底部出现"复制链接"按钮，复制 `https://h5.topfans.com/asset/{assetId}` 到剪贴板，**不依赖任何 SDK**。关闭弹窗后计数器清零，不跨弹窗累计（L0 静默不计）。

## 8. 监控埋点

接入项目现有的 `uniStatistics`（manifest 已 `enable: true`）。**保存图片走独立事件** `save_image_*`，不与分享事件混报（语义不同）。**所有事件均带上分享人（`user_id`）和分享来源端系统类型（`system_type`）字段**（已登录用户才有分享事件，见 § 3.4）：

```js
// useShare composable 初始化时一次性取到 systemType，后续所有事件复用（避免在事件回调里再 await）
const { platform: systemType } = await uni.getSystemInfo();

// 5 个分享平台共用
uni.report('share_action_click', {
  asset_id:       assetId,
  target:         'weixin_friend' | 'weixin_moment' | 'qq' | 'qq_zone' | 'sinaweibo',  // 仅 5 个 share target；save_image 走独立事件
  user_id:        currentUserId,                          // 已登录用户 ID（必填）
  system_type:    systemType                              // 预解析值：'android' / 'ios' / 'mp-weixin' / 'h5' 等
});

uni.report('share_result', {
  asset_id:       assetId,
  target:         'weixin_friend' | 'weixin_moment' | 'qq' | 'qq_zone' | 'sinaweibo',
  user_id:        currentUserId,
  system_type:    systemType,
  result:         'success' | 'cancel' | 'fail_app_missing' | 'fail_network' | 'fail_canvas' | 'fail_other',
  duration_ms:    elapsed
});

// 保存图片独立事件（target 字段在 save_image_* 中省略，事件名本身已区分）
uni.report('save_image_click',  {
  asset_id:       assetId,
  user_id:        currentUserId,
  system_type:    systemType
});
//   duration_ms: 从调用 uni.saveImageToPhotosAlbum 到回调止
uni.report('save_image_result', {
  asset_id:       assetId,
  user_id:        currentUserId,
  system_type:    systemType,
  result:         'success' | 'fail_permission' | 'fail_already_saved' | 'fail_other',
  duration_ms:    elapsed
});

// 追踪接口调用结果（可选埋点：用于监控 share_events 落库失败率）
uni.report('share_track_result', {
  share_event_id: shareEventId,        // 后端返回的事件 ID
  http_status:    200 | 401 | 4xx | 5xx,
  duration_ms:    elapsed
});
```

> **`target` 字段约定**：`share_action_click` / `share_result` 的 `target` 字段**仅包含 5 个 share target**（`weixin_friend` / `weixin_moment` / `qq` / `qq_zone` / `sinaweibo`）。保存图片行为通过独立事件 `save_image_*` 区分，不在 `target` 枚举里。
>
> **`system_type` 取值时机**：在 `useShare` 初始化时一次性 `await uni.getSystemInfo()` 拿到 `systemType`，所有事件复用同一个值。不要在事件回调里再 await（避免每次都触发异步调用且字段值为 Promise 对象）。

通过这些事件可计算：
- 分享 CTR（`share_action_click` / 弹窗打开次数）
- 各平台失败率（`share_result.result != 'success'` 占比）
- canvas 成功率（iOS 黑底问题占比）
- **分享渠道分布**（按 `system_type` 分组：iOS 用户占比、Android 用户占比、微信小程序用户占比）
- **人均分享次数**（按 `user_id` 分组聚合）
- **追踪接口健康度**（`share_track_result` 失败率）

## 9. iOS 平台特定坑

| 坑 | 触发场景 | 规避 |
|----|---------|------|
| Universal Links 未配 | iOS 13+ 微信 SDK 强制 | § 4.2 已配，必须 |
| `uni.share` 偶发无回调 | 系统分享面板被快速关闭 | 5s/15s 超时后强制 `setState('idle')` + L2 toast（按 provider 区分：weixin/qq 5s, sinaweibo 15s，实现细节见 § 5.3.1） |
| canvas 离屏黑底 | 透明 PNG 合成 | 先 fillRect 白底再 draw |
| iOS 剪贴板读取需用户授权 | 「复制链接」降级 | `uni.setClipboardData` 写入不需要用户授权（uni-app 已封装），但 iOS 14+ **读取** 剪贴板会弹「允许粘贴」系统弹窗。**写场景不受影响**，本设计只是写剪贴板，无需额外处理 |

## 10. 测试

### 10.0 前置：接入测试框架

**项目当前 `frontend/package.json` 只有 `vuex` 一个依赖，无任何测试框架**。**已确认项目构建工具是 Vite**（`frontend/vite.config.js` 存在，未发现 webpack/vue-cli 痕迹）。Vitest 与 Vite 原生兼容（共享配置、resolve.alias、transform 流水线），无需额外胶水代码。

接入步骤：

1. 安装 `vitest` + `@vue/test-utils` + `happy-dom`（或 jsdom）作为 devDependencies
2. `frontend/vitest.config.js` 配置好 alias `@` 指向 `frontend/`（与 vite.config.js 保持一致）
3. `frontend/package.json` 增加脚本：`"test:unit": "vitest run"`、`"test:watch": "vitest"`
4. 在 `frontend/.gitignore` 里加 `coverage/` 排除覆盖率产物

预计工作量 0.5 人天。**没这一步 § 10.1 全部不成立**。

### 10.1 测试分层

| 层 | 工具 | 覆盖 |
|----|------|------|
| 单元 | Vitest | `image-compositor.js`（纯函数，**100% 行覆盖**） |
| 单元 | Vitest | `useShare.js` 的状态机分支（mock `uni.share`/`uni.downloadFile`） |
| 组件 | @vue/test-utils | `ShareActionBar.vue` 渲染 6 个按钮、点击抛 `onPick` |
| E2E | uni-app 自动化 (`automator`) | iOS 真机 / Android 真机 5 平台分享（后续迭代，本期不做） |
| 手动 | 验收 checklist | 见 § 10.3 |

**Vitest 注入 `uni` 全局 stub**（解决 happy-dom/jsdom 不带 uni 的问题）：

在 `frontend/test/setup.js`（`vitest.config.js` 的 `setupFiles` 指定）顶部用 `globalThis.uni` 注入 stub；具体测试用 `vi.mocked(uni.xxx).mockResolvedValueOnce(...)` 模拟回调。最小示例：

```js
// frontend/test/setup.js
import { vi } from 'vitest';
if (!globalThis.uni) {
  globalThis.uni = {
    downloadFile: vi.fn(({ url }) => Promise.resolve({ tempFilePath: '/mock/' + url.split('/').pop() })),
    share:         vi.fn(() => Promise.resolve({ errMsg: 'share:ok' })),
    saveImageToPhotosAlbum: vi.fn(() => Promise.resolve()),
    showToast:     vi.fn(),
    getStorageSync: vi.fn(() => ''),
    setStorageSync: vi.fn(),
    report:        vi.fn()
  };
}
```

> 实施时如发现 `globalThis.uni` 被 Vite 编译时静态分析剔除（uni-app 编译时会把 `uni.xxx` 替换成平台代码），需要改用 `vi.stubGlobal('uni', { ... })` 或在 `vitest.config.js` 的 `define` 里注入。

### 10.2 关键单元用例

`image-compositor`：

> **download 边界约定**：`composeShareImage` **不负责 download**。所有远端图（cover/qrcode/avatar）由 `useShare` 在调用前 `uni.downloadFile` 转本地，传入 `composeShareImage` 的都是本地路径。`composeShareImage` 自身只在拿不到本地路径时使用占位图兜底，**不**触发任何网络 IO。

- `composeShareImage`: 3 个本地路径全部有效 → 返回 tempFilePath
- `composeShareImage`: 任意本地路径缺失 → 使用占位图兜底，**不**抛错
- `composeShareImage`: nickname 为空 → 用首字母占位圆（取昵称首字符 ASCII 65~90 区间）
- `composeShareImage`: 合成图尺寸 = 750×1334 px
- `composeShareImage`: L0 白底已 fillRect → 输出图背景非透明（非黑底）

`useShare`（独立测试组）：

- useShare 调用前 cover/qrcode/avatar 任一 `uni.downloadFile` 失败 → 抛 L2 错误，不进入 composing
- useShare 调用前 download 全部成功 → 进入 composing + composeShareImage + uni.share

**状态机转换测试**（覆盖 § 5.1 状态图）：

- `idle` 初始状态，`pick()` → 探测成功 → `composing`；探测失败 → `error`（不进入 composing）
- `composing` → `sharing`（uni.share 调起）
- `sharing` → `done`（success 回调）→ 2s 后自动 emit('close') 弹窗
- `sharing` → `error`（fail 回调且非 cancel）
- `error` → 再次 `pick()` → `composing`（重试路径）
- 任何状态 → `emit('close')` → `idle` + 清理所有定时器
- `sharing` 状态 5s（weixin/qq）/ 15s（sinaweibo）无回调 → 强制 `idle` + L2 toast
- `sharing` 状态收到 `App.onHide` → 清除超时定时器（不重置状态）
- `sharing` 状态收到 `App.onShow`（之前 onHide 过）→ 启动 8s 兜底定时器

`useShare` 业务分支（与状态机转换测试互补）：

- 选 weixin_friend → 探测 App 未装 → 抛 L1 错误，不调 `uni.share`
- 选 weixin_friend → 探测已装 → 调 `composeShareImage` → 调 `uni.share`
- `uni.share` 回调 errMsg 含 `cancel` → 静默，不弹 toast
- 同一 `coverLocalPath+qrcodeLocalPath+avatarLocalPath+nickname+slogan` 二次调用 → 跳过合成，复用 `lastComposedPath`
- 任意入参变化 → 重新合成（含 `avatarLocalPath` 变化，即用户换头像场景）
- `slogan` 字段变化（slogan 重抽） → 重新合成（composeKey 失效）

`brand-slogans`（独立测试组）：

- `pickRandomSlogan()` 返回值必须是 `BRAND_SLOGANS` 数组中的某个元素（不能返回未定义值）
- `pickRandomSlogan()` 连续调用 1000 次 → 至少覆盖 6 条不同 slogan（验证随机性，候选池 ≥ 8 条时的概率统计）
- `BRAND_SLOGANS` 数组所有元素都包含 `brandLine` 和 `brandDesc` 两个字段（schema 校验）

`composeShareImage` 文案分支：

- `opts.slogan` 提供 → L4 层渲染 `slogan.brandLine` + `slogan.brandDesc`
- `opts.slogan` 缺失 → 回退默认文案 `'TOPFANS，让热爱被发现'` + `'AI做周边，应援全免费'`（不抛错）
- `opts.slogan.brandLine` 为空字符串 → 跳过 brandLine 行只渲染 brandDesc（容错）

### 10.3 手动验收 Checklist

**功能**

- 弹窗打开后，6 个按钮均可点击，无错位
- 微信好友：分享到文件传输助手/好友，能看到带二维码的合成图
- 朋友圈：发到自己朋友圈，能看到合成图 + 文字
- QQ 好友：发到 QQ 好友/群，能看到合成图
- QQ 空间：发到自己空间，能看到合成图
- 微博：发到微博（自己可见），能看到合成图
- 保存图片：相册中能找保存的图（与弹窗预览一致）
- 复制链接降级：连续失败 2 次后出现「复制链接」按钮，点击后系统剪贴板有正确 URL

**异常路径**

- 未装微信：toast「请先安装微信」，弹窗不关闭
- 用户在系统分享面板点取消：弹窗不关闭，不弹 toast
- 飞行模式下点击分享：toast「图片加载失败，请重试」
- 同一资产重新打开弹窗 3 次：只请求一次后端 QR code

**视觉**

- 6 个按钮在 iPhone 13 mini（5.4 寸）也能完整显示（最小目标机型）
- 合成图在微信聊天中不被压缩成马赛克
- 合成图右下角二维码可正常扫码
- **iOS 真机手动验证合成图无黑底**（E2E 暂不做，依赖 iPhone 8 / iPhone 13 真机目视确认）

**性能**

- 弹窗从打开到 6 个按钮可点击 ≤ 500ms（中端机如 iPhone X / 小米 8 实测基线；低端机不保证）
- 同一分享图二次调用合成耗时 ≤ 100ms（L1 内存缓存命中路径；L2 模块级缓存命中再 +50ms，差值主要来自 Map 查找）

## 11. Definition of Done

- 上述手动 checklist 全部 ✅
- 单元测试 100% 通过，`image-compositor` 行覆盖 100%（与 § 10.1 一致）
- iPhone X（iOS 16+）和小米 12（Android 13）真机各 5 次分享无崩溃
- 上线后 24 小时 L1+L2 错误率不上升 > 0.3pp（基线对照：发布前 7 天均值）
- `manifest.json` 占位 `<TBD>` 全部替换为真实凭证

## 12. 待用户/后端提供的信息

- [ ] 微信开放平台移动应用 AppID（§ 12.2.1）
- [ ] QQ 互联移动应用 AppID（§ 12.2.2）
- [ ] 微博开放平台 AppID（§ 12.2.3）
- [ ] iOS Bundle ID
- [ ] Android 应用签名 SHA1（微信/QQ）/ MD5（微博）— **见 § 12.2.4 说明**
- [ ] 后端 `GET /api/v1/share/asset-qrcode/:assetId` 接口就绪
- [ ] 后端 `POST /api/v1/share/track` 接口就绪（§ 3.5）+ `share_events` 表 migration 落地
- [ ] 后端 `/share/track` 实现登录态校验（401 路径），与 § 3.4 一致

> **当前线上坏路径**：`frontend/pages/components/ShareReportButtons.vue:75` 引用 `/static/icon/qrcode-placeholder.png`，但该文件**在仓库中不存在**（已验证 `frontend/static/icon/` 目录里无此文件）。当前线上代码该路径已坏。本 spec 落地时同步处理：要么创建该占位图，要么改路径到 `/static/share/mock_qrcode.png`（推荐后者，与 § 6 资源目录一致）。

### 12.1 前端 mock 策略（后端接口未就绪时）

为不阻塞前端开发，前端在 `frontend/utils/share-mock.js` 实现 mock：

- **二维码 mock**：`useShare` 初始化时若 `import.meta.env.DEV` 为 true，先调真实接口 → 失败则回退到 `/static/share/mock_qrcode.png`（提交时一并放入，1 个测试二维码图）
- **App 探测 mock**：dev 环境下 `plus.runtime.isApplicationExist` 始终返回 `true`（避免开发机没装目标 App 时阻塞测试）
- **埋点 mock**：`uni.report` 在 dev 环境下不发送，console.log 输出 payload 即可
- **生产环境**：所有 mock 分支用 `if (import.meta.env.DEV) { ... }` 包裹，Vite 构建 production 时被 dead-code elimination 自动消除。**统一用 `import.meta.env.DEV`（不用 `MODE`/`NODE_ENV`）**，避免不同环境变量在自定义 build mode 下不一致。

预计后端接口到位后删除 `share-mock.js` 即可，不影响生产代码。

### 12.2 各平台 AppID 申请路径

> ⚠️ **三平台 AppID 申请均需 1~7 个工作日审核**，必须在打包前至少 1 周启动申请。**可并行申请三个平台**以节省时间。

#### 12.2.1 微信开放平台 AppID

| 项 | 值 |
|----|----|
| **入口 URL** | https://open.weixin.qq.com/ |
| **账号要求** | 重新注册（与公众号/小程序账号**不通用**） |
| **资质** | **仅企业**（营业执照 + 对公账户验证，1~3 工作日）；个人开发者**无法**申请移动应用 |
| **审核周期** | 1~7 个工作日 |
| **价格** | 免费 |

**申请流程**：
1. 登录后进入"管理中心 → 移动应用 → 创建移动应用"
2. 填写：应用官网（需 ICP 备案的域名）、应用名称、简介、图标（28×28 / 108×108）、Android 包名 + 签名 SHA1、iOS Bundle ID
3. 提交审核

**拿到后要配**：
- iOS：注册 Universal Links 域名（与 manifest § 4.2 `UniversalLinks: "https://h5.topfans.com/uni-universallinks/"` 一致），并部署 `apple-app-site-association`（见 § 4.2 模板）
- Android：用打包 keystore 算 SHA1 — `keytool -list -v -keystore xxx.keystore` 取 SHA1 填到开放平台"应用签名"

**最终填到 manifest § 4.2**：`weixin.appid = "wx..."`

#### 12.2.2 QQ 互联 AppID

| 项 | 值 |
|----|----|
| **入口 URL** | https://connect.qq.com/ |
| **账号要求** | 用 QQ 登录即可（QQ 互联开发者账号） |
| **资质** | **个人可**（身份证 + 银行卡验证）；企业开发者更稳 |
| **审核周期** | 1~3 个工作日 |
| **价格** | 免费 |

**申请流程**：
1. 进入"应用管理 → 创建应用 → 移动应用"
2. 填写：应用名称、简介、图标、Android 包名 + 签名 SHA1、iOS Bundle ID、上线后必填应用市场下载链接
3. 提交审核

**拿到后要配**：
- Android SHA1 / iOS Bundle ID 与打包配置严格一致
- 开放平台"回调域"填 `https://h5.topfans.com`（虽然纯图片分享不走 OAuth，但平台默认要求填）

**最终填到 manifest § 4.2**：`qq.appid = "10..."`（QQ 互联后台叫 "APP ID"，数字格式）

#### 12.2.3 微博开放平台 AppID

| 项 | 值 |
|----|----|
| **入口 URL** | https://open.weibo.com/ |
| **账号要求** | 用已**实名认证的微博账号**登录（个人认证即可） |
| **资质** | **个人可** |
| **审核周期** | 1~5 个工作日 |
| **价格** | 免费 |

**申请流程**：
1. 进入"微连接 → 移动应用 → 创建应用"
2. 填写：应用名称、图标、简介、类别、Android 包名 + **签名 MD5**（不是 SHA1）、iOS Bundle ID
3. "高级信息" 填 Bundle ID / 包名
4. 提交审核

**拿到后要配**：
- Android 签名 **MD5**（**与微信/QQ 的 SHA1 不同**）：`keytool -list -v -keystore xxx.keystore | grep MD5`
- iOS Universal Links（微博 SDK 也要求 iOS 13+ 配 Universal Links）
- 微博后台"授权回调页"字段必填（填 `https://h5.topfans.com` 即可，**不影响纯图片分享**——那是 OAuth 登录场景才用）

**最终填到 manifest § 4.2**：`sinaweibo.appid = "..."`（微博后台叫 "App Key"，**不是 AppID**，按 uni-app 规范统一写 `appid`）

#### 12.2.4 签名算法三平台对比

| 平台 | Android 签名算法 | 取法 |
|------|----------------|------|
| 微信 | SHA1 | `keytool -list -v -keystore xxx.keystore \| grep SHA1` |
| QQ | SHA1 | `keytool -list -v -keystore xxx.keystore \| grep SHA1` |
| 微博 | **MD5** | `keytool -list -v -keystore xxx.keystore \| grep MD5` |

> ⚠️ **同一个 keystore 同时算出 SHA1 + MD5 即可**，不需要为不同平台准备多个 keystore。

#### 12.2.5 三平台申请前 checklist

| 准备项 | 微信 | QQ | 微博 | 备注 |
|--------|------|------|------|------|
| 营业执照（企业） | ✅ 必需 | ⭕ 可选 | ❌ 个人可 | 决定走企业或个人通道 |
| 备案域名 | ✅ 必需 | ❌ | ❌ | 准备好 ICP 备案号 |
| Android keystore | ✅ | ✅ | ✅ | 同一个 keystore 即可 |
| iOS Bundle ID | ✅ | ✅ | ✅ | 全平台共用，唯一 |
| 应用图标 (108×108) | ✅ | ✅ | ✅ | 设计师出 |
| 应用截图 | ✅ 5 张 | ✅ 3~5 张 | ✅ 3~5 张 | 提前准备 |

#### 12.2.6 ❌ 常见错路

| 需求 | 错路 | 正确方向 |
|------|------|---------|
| 微信 AppID | 微信公众号后台 / 微信小程序后台 | **微信开放平台** open.weixin.qq.com |
| QQ AppID | QQ 公众平台 | **QQ 互联** connect.qq.com |
| 微博 AppID | 微博广告平台 | **微博开放平台** open.weibo.com |
| 复用现有 AppID | 现有 H5 / 小程序的 AppID 直接用 | **必须**重新申请移动应用 AppID |

## 13. 不做的事（YAGNI）

- 不做海报编辑/二次裁剪
- 不做"先选平台 → 再选好友"的二级分享面板（直接走 `uni.share` 系统面板）
- 不做分享到抖音/小红书/钉钉（这些平台没有稳定的 uni-app 集成）
- 不做分享后回跳游戏内领奖励的回调（独立需求，后续单独 spec）
- 不做 h5 端的分享（`uni.share` 在 h5 下行为不一致，h5 用 Web Share API 单独处理，本次不做）