fix(payment): route Philippine GCash separately from QRIS

(cherry picked from commit ef9b79bc83)

.gitea/workflows/docker-image.yml

@@ -4,43 +4,12 @@ on:
   push:
     branches:
       - main
-      - test
+      - pre
   workflow_dispatch:
 
 jobs:
-  quality:
-    name: Quality and Bundle Budgets
-    runs-on: gitea-label
-    container:
-      image: cozsweet-act-runner-node24-docker:latest
-    env:
-      NEXT_TELEMETRY_DISABLED: "1"
-      SENTRY_UPLOAD_SOURCEMAPS: "0"
-
-    steps:
-      - name: Skip quality gate for test branch
-        if: ${{ github.ref == 'refs/heads/test' }}
-        run: echo "Quality gate is disabled for the test branch."
-
-      - name: Checkout
-        if: ${{ github.ref != 'refs/heads/test' }}
-        uses: actions/checkout@v4
-
-      - name: Install dependencies
-        if: ${{ github.ref != 'refs/heads/test' }}
-        run: pnpm install --frozen-lockfile
-
-      - name: Run quality checks
-        if: ${{ github.ref != 'refs/heads/test' }}
-        run: pnpm quality
-
-      - name: Enforce bundle budgets
-        if: ${{ github.ref != 'refs/heads/test' }}
-        run: pnpm perf:bundle:check
-
   publish:
     name: Build and Push Docker Image
-    needs: quality
     runs-on: gitea-label
     container:
       image: cozsweet-act-runner-node24-docker:latest
@@ -79,7 +48,7 @@ jobs:
               DEPLOY_ENV="prod"
               NEXT_ENV_FILE=".env.production"
               ;;
-            test)
+            pre)
               DEPLOY_ENV="test"
               NEXT_ENV_FILE=".env.local"
               ;;
@@ -183,12 +152,9 @@ jobs:
       - name: Deploy image over SSH
         env:
           SSH_HOST: ${{ secrets.SSH_HOST }}
-          SSH_USER: ${{ secrets.SSH_USER }}
           SSH_PORT: ${{ secrets.SSH_PORT }}
           SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
           SSH_KNOWN_HOSTS: ${{ secrets.SSH_KNOWN_HOSTS }}
-          TEST_DEPLOY_DIR: ${{ secrets.TEST_DEPLOY_DIR }}
-          PROD_DEPLOY_DIR: ${{ secrets.PROD_DEPLOY_DIR }}
           REGISTRY_HOST: ${{ secrets.REGISTRY_HOST }}
           REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
           REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
@@ -197,16 +163,18 @@ jobs:
 
           case "$DEPLOY_ENV" in
             test)
-              DEPLOY_DIR="${TEST_DEPLOY_DIR:-/opt/cozsweet-web-test}"
+              DEPLOY_ROOT="/home/lzf/apps/cozsweet-web-test"
               HOST_PORT="9135"
               CONTAINER_NAME="cozsweet-web-test"
               PROJECT_NAME="cozsweet-web-test"
+              SERVER_RETAIN_COUNT="1"
               ;;
             prod)
-              DEPLOY_DIR="${PROD_DEPLOY_DIR:-/opt/cozsweet-web-prod}"
+              DEPLOY_ROOT="/home/lzf/apps/cozsweet-web-prod"
               HOST_PORT="9185"
               CONTAINER_NAME="cozsweet-web-prod"
               PROJECT_NAME="cozsweet-web-prod"
+              SERVER_RETAIN_COUNT="2"
               ;;
             *)
               echo "Unsupported deploy env: $DEPLOY_ENV" >&2
@@ -214,8 +182,11 @@ jobs:
               ;;
           esac
 
+          DEPLOY_DIR="$DEPLOY_ROOT/current"
+          DEPLOY_SHARED_DIR="$DEPLOY_ROOT/shared"
+          REMOTE_ENV_FILE="$DEPLOY_SHARED_DIR/$NEXT_ENV_FILE"
           DEPLOY_HOST="$SSH_HOST"
-          DEPLOY_USER="$SSH_USER"
+          DEPLOY_USER="lzf"
           DEPLOY_PORT="${SSH_PORT:-22}"
           DEPLOY_KEY="$SSH_PRIVATE_KEY"
           DEPLOY_KNOWN_HOSTS="$SSH_KNOWN_HOSTS"
@@ -241,19 +212,19 @@ jobs:
           SSH_OPTS="-i $KEY_FILE -p $DEPLOY_PORT -o IdentitiesOnly=yes"
           SCP_OPTS="-i $KEY_FILE -P $DEPLOY_PORT -o IdentitiesOnly=yes"
 
-          ssh $SSH_OPTS "$SSH_TARGET" "mkdir -p '$DEPLOY_DIR'"
+          ssh $SSH_OPTS "$SSH_TARGET" \
+            "mkdir -p '$DEPLOY_DIR' '$DEPLOY_SHARED_DIR' '$DEPLOY_ROOT/releases' '$DEPLOY_ROOT/backups' '$DEPLOY_ROOT/tmp' && chmod 700 '$DEPLOY_SHARED_DIR'"
           scp $SCP_OPTS docker-compose.yml "$SSH_TARGET:$DEPLOY_DIR/docker-compose.yml"
           scp $SCP_OPTS scripts/server/deploy-docker-image.sh "$SSH_TARGET:$DEPLOY_DIR/deploy-docker-image.sh"
-          scp $SCP_OPTS "$NEXT_ENV_FILE" "$SSH_TARGET:$DEPLOY_DIR/$NEXT_ENV_FILE"
+          scp $SCP_OPTS "$NEXT_ENV_FILE" "$SSH_TARGET:$REMOTE_ENV_FILE"
+          ssh $SSH_OPTS "$SSH_TARGET" "chmod 600 '$REMOTE_ENV_FILE'"
 
           printf '%s' "$REGISTRY_PASSWORD" \
             | ssh $SSH_OPTS "$SSH_TARGET" \
                 "docker login '$REGISTRY_HOST' -u '$REGISTRY_USERNAME' --password-stdin"
 
-          SERVER_RETAIN_COUNT="1"
-
           ssh $SSH_OPTS "$SSH_TARGET" \
-            "cd '$DEPLOY_DIR' && chmod +x ./deploy-docker-image.sh && ./deploy-docker-image.sh '$IMAGE_VERSION_TAG' '$NEXT_ENV_FILE' '$HOST_PORT' '$CONTAINER_NAME' '$PROJECT_NAME' '$SERVER_RETAIN_COUNT'"
+            "cd '$DEPLOY_DIR' && chmod +x ./deploy-docker-image.sh && ./deploy-docker-image.sh '$IMAGE_VERSION_TAG' '$REMOTE_ENV_FILE' '$HOST_PORT' '$CONTAINER_NAME' '$PROJECT_NAME' '$SERVER_RETAIN_COUNT'"
 
       - name: Purge Cloudflare cache
         env:

.gitea/workflows/domestic-test.yml

@@ -0,0 +1,138 @@
+name: Deploy frontend to domestic test
+
+on:
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    name: Build and deploy isolated domestic test
+    runs-on: gitea-label
+    container:
+      image: cozsweet-act-runner-node24-docker:latest
+    env:
+      NEXT_TELEMETRY_DISABLED: "1"
+      SENTRY_UPLOAD_SOURCEMAPS: "0"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Validate domestic SSH configuration
+        env:
+          SSH_HOST: ${{ secrets.DOMESTIC_TEST_SSH_HOST }}
+          SSH_PORT: ${{ secrets.DOMESTIC_TEST_SSH_PORT }}
+          SSH_PRIVATE_KEY_B64: ${{ secrets.DOMESTIC_TEST_SSH_PRIVATE_KEY_B64 }}
+          SSH_KNOWN_HOSTS: ${{ secrets.DOMESTIC_TEST_SSH_KNOWN_HOSTS }}
+        run: |
+          set -eu
+          if [ -z "$SSH_HOST" ] || [ -z "$SSH_PRIVATE_KEY_B64" ] || [ -z "$SSH_KNOWN_HOSTS" ]; then
+            echo "Missing domestic test SSH secrets" >&2
+            exit 1
+          fi
+          mkdir -p "$HOME/.ssh"
+          chmod 700 "$HOME/.ssh"
+          printf '%s' "$SSH_PRIVATE_KEY_B64" | base64 -d > "$HOME/.ssh/domestic_test_deploy_key"
+          printf '%s\n' "$SSH_KNOWN_HOSTS" > "$HOME/.ssh/known_hosts"
+          chmod 600 "$HOME/.ssh/domestic_test_deploy_key" "$HOME/.ssh/known_hosts"
+
+      - name: Prepare domestic test environment
+        env:
+          TEST_ENV_FILE_CONTENT: ${{ secrets.TEST_ENV_FILE }}
+        run: |
+          set -eu
+          if [ -z "$TEST_ENV_FILE_CONTENT" ]; then
+            echo "Missing existing secret: TEST_ENV_FILE" >&2
+            exit 1
+          fi
+          umask 077
+          printf '%s\n' "$TEST_ENV_FILE_CONTENT" > .env.domestic-test
+
+          replace_env() {
+            key="$1"
+            value="$2"
+            awk -v key="$key" -v value="$value" '
+              BEGIN { replaced = 0 }
+              $0 ~ "^" key "=" { print key "=" value; replaced = 1; next }
+              { print }
+              END { if (!replaced) print key "=" value }
+            ' .env.domestic-test > .env.domestic-test.next
+            mv .env.domestic-test.next .env.domestic-test
+          }
+
+          replace_env NEXT_PUBLIC_APP_ENV test
+          replace_env NEXT_PUBLIC_API_BASE_URL https://testapi.banlv-ai.com
+          replace_env NEXT_PUBLIC_WS_BASE_URL wss://testapi.banlv-ai.com/ws
+          replace_env NEXTAUTH_URL http://127.0.0.1:9135
+          replace_env NEXTAUTH_URL_INTERNAL http://127.0.0.1:3000
+
+          grep -Eq '^AUTH_SECRET=.+$' .env.domestic-test
+          grep -Eq '^NEXT_PUBLIC_API_BASE_URL=https://testapi\.banlv-ai\.com/?$' .env.domestic-test
+          grep -Eq '^NEXT_PUBLIC_WS_BASE_URL=wss://testapi\.banlv-ai\.com/ws/?$' .env.domestic-test
+
+      - name: Prepare image metadata
+        run: |
+          set -eu
+          SHORT_SHA="$(git rev-parse --short HEAD)"
+          IMAGE="cozsweet-frontend-domestic-test:test-$SHORT_SHA"
+          ARCHIVE="cozsweet-frontend-domestic-test-$SHORT_SHA.tar.gz"
+          {
+            echo "SHORT_SHA=$SHORT_SHA"
+            echo "IMAGE=$IMAGE"
+            echo "ARCHIVE=$ARCHIVE"
+          } >> "$GITHUB_ENV"
+
+      - name: Run frontend quality checks
+        run: |
+          set -eu
+          pnpm install --frozen-lockfile
+          pnpm lint
+          pnpm typecheck
+          pnpm test:contracts
+
+      - name: Build and archive runtime image
+        run: |
+          set -eu
+          DOCKER_BUILDKIT=1 docker build \
+            --secret id=next_env,src=.env.domestic-test \
+            --build-arg NEXT_ENV_FILE=.env.domestic-test \
+            -t "$IMAGE" \
+            .
+          docker save "$IMAGE" | gzip -1 > "$ARCHIVE"
+          test -s "$ARCHIVE"
+
+      - name: Deploy isolated domestic test container
+        env:
+          SSH_HOST: ${{ secrets.DOMESTIC_TEST_SSH_HOST }}
+          SSH_PORT: ${{ secrets.DOMESTIC_TEST_SSH_PORT }}
+        run: |
+          set -eu
+          DEPLOY_PORT="${SSH_PORT:-22}"
+          KEY_FILE="$HOME/.ssh/domestic_test_deploy_key"
+          SSH_TARGET="lzf@$SSH_HOST"
+          RUN_TOKEN="${GITHUB_RUN_ID:-manual}-${GITHUB_RUN_ATTEMPT:-1}"
+          DEPLOY_ROOT="/home/lzf/apps/cozsweet-web-test"
+          REMOTE_TMP="$DEPLOY_ROOT/tmp/actions-$RUN_TOKEN"
+          REMOTE_ARCHIVE="$REMOTE_TMP/$ARCHIVE"
+          REMOTE_ENV_FILE="$DEPLOY_ROOT/shared/test.env"
+          SSH_OPTS="-i $KEY_FILE -p $DEPLOY_PORT -o BatchMode=yes -o IdentitiesOnly=yes"
+          SCP_OPTS="-i $KEY_FILE -P $DEPLOY_PORT -o BatchMode=yes -o IdentitiesOnly=yes"
+
+          cleanup_remote() {
+            ssh $SSH_OPTS "$SSH_TARGET" \
+              "rm -f '$REMOTE_ARCHIVE' && rmdir '$REMOTE_TMP' 2>/dev/null || true"
+          }
+          trap cleanup_remote EXIT
+
+          ssh $SSH_OPTS "$SSH_TARGET" \
+            "mkdir -p '$DEPLOY_ROOT/current' '$DEPLOY_ROOT/releases/docker' '$DEPLOY_ROOT/shared' '$REMOTE_TMP' && chmod 700 '$DEPLOY_ROOT/shared'"
+          scp $SCP_OPTS scripts/server/deploy-domestic-test-archive.sh \
+            "$SSH_TARGET:$DEPLOY_ROOT/current/deploy-domestic-test-archive.sh"
+          scp $SCP_OPTS .env.domestic-test "$SSH_TARGET:$REMOTE_ENV_FILE"
+          scp $SCP_OPTS "$ARCHIVE" "$SSH_TARGET:$REMOTE_ARCHIVE"
+          ssh $SSH_OPTS "$SSH_TARGET" \
+            "chmod 600 '$REMOTE_ENV_FILE' && chmod 700 '$DEPLOY_ROOT/current/deploy-domestic-test-archive.sh' && '$DEPLOY_ROOT/current/deploy-domestic-test-archive.sh' '$REMOTE_ARCHIVE' '$IMAGE' '$REMOTE_ENV_FILE' 9135"
+
+      - name: Cleanup runner artifacts
+        if: always()
+        run: |
+          rm -f .env.domestic-test .env.domestic-test.next "${ARCHIVE:-}" "$HOME/.ssh/domestic_test_deploy_key"

.githooks/post-receive

@@ -72,12 +72,12 @@ copy_env_by_branch() {
             START_PORT=9185
             echo "=== env: copied .env.production (main → prod) ===" >> "$LOG_FILE"
             ;;
-        test)
+        pre)
             cp -f env-example/.env.local.example .env.local
             ENV_FILE=".env.local"
             DEPLOY_ENV="test"
             START_PORT=9135
-            echo "=== env: copied .env.local (test → test) ===" >> "$LOG_FILE"
+            echo "=== env: copied .env.local (pre branch → test runtime) ===" >> "$LOG_FILE"
             ;;
         dev)
             cp -f env-example/.env.development.example .env.local

Dockerfile

@@ -6,10 +6,12 @@ ENV PNPM_HOME=/pnpm
 ENV PNPM_STORE_PATH=/pnpm/store
 ENV PATH=$PNPM_HOME:$PATH
 
+ARG NPM_REGISTRY=https://registry.npmmirror.com
+
 RUN apk add --no-cache libc6-compat \
-  && corepack enable \
+  && npm install --global "pnpm@10.30.3" --registry="$NPM_REGISTRY" \
-  && corepack prepare pnpm@10.30.3 --activate \
+  && pnpm config set store-dir "$PNPM_STORE_PATH" \
-  && pnpm config set store-dir "$PNPM_STORE_PATH"
+  && pnpm config set registry "$NPM_REGISTRY"
 
 FROM base AS deps
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./

FRONTEND_GIFT_PRODUCTS_API.md

@@ -0,0 +1,403 @@
+# 虚拟礼物商品与付款后文案 API
+
+## 一、用途
+
+前端按当前角色一次获取全部启用的礼物品类和商品，在本地完成品类切换与商品筛选。页面不得写死咖啡、鲜花、服装等品类，也不得根据 `planId` 推算名称、图片或价格。付款成功后，前端使用订单号获取稳定的角色感谢文案。
+
+## 三、推荐接入流程
+
+1. 当前角色确定后，只请求一次 `GET /api/payment/gift-products?characterId=<CHARACTER_ID>`。
+2. 使用 `data.categories` 渲染品类栏，使用 `data.plans` 保存完整商品目录。
+3. 用户切换品类时只在前端按 `product.category` 本地筛选，不再请求后端。
+4. 使用商品自身的 `planName`、`description`、`imageUrl`、`amountCents` 和 `currency` 渲染通用商品卡片。
+5. 用户选择商品后，使用该商品原始 `planId` 创建订单。
+6. 用户切换商品时清除旧 `orderId`、`clientSecret` 和支付组件状态，再创建新订单。
+7. Stripe 使用本次订单返回的 `payParams.clientSecret` 挂载 Payment Element。
+8. 每 3 至 5 秒轮询订单状态，直到状态变成 `paid`、`failed` 或 `expired`。
+9. 状态为 `paid` 后调用 `POST /api/payment/tip-message`，展示 `data.message`。
+
+> `amountCents`、`currency` 和 `planId` 必须来自同一条商品数据。后端下单时会再次按 `planId` 校验真实价格，前端展示值不得作为收费依据。
+
+---
+
+## 四、一次获取完整礼物目录
+
+### 4.1 请求
+
+```http
+GET /api/payment/gift-products?characterId=elio
+```
+
+- 完整地址：`https://proapi.banlv-ai.com/api/payment/gift-products`
+- 兼容别名：`GET /api/payment/tip-plans`
+- 登录鉴权：不需要
+- 请求格式：Query String
+
+### 4.2 查询参数
+
+| 字段 | 类型 | 必填 | 可空 | 示例 | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `characterId` | string | 前端必传 | 否 | `elio` | 当前收礼角色 ID。后端仍兼容省略，但多角色前端不得省略。 |
+| `category` | string | 否 | 否 | `coffee` | 兼容旧的按品类懒加载方式。新版前端首屏不传此字段。 |
+
+### 4.3 请求示例
+
+```bash
+curl 'https://proapi.banlv-ai.com/api/payment/gift-products?characterId=elio'
+```
+
+### 4.4 成功响应
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "success": true,
+  "data": {
+    "characterId": "elio",
+    "categories": [
+      {
+        "category": "coffee",
+        "name": "Coffee",
+        "productCount": 3,
+        "imageUrl": null
+      },
+      {
+        "category": "flowers",
+        "name": "Flowers",
+        "productCount": 2,
+        "imageUrl": "https://example.com/flowers.jpg"
+      }
+    ],
+    "plans": [
+      {
+        "planId": "tip_coffee_usd_4_99",
+        "planName": "Velvet Espresso",
+        "orderType": "tip",
+        "tipType": "coffee_small",
+        "category": "coffee",
+        "characterId": "elio",
+        "description": "Buy Elio a small coffee",
+        "imageUrl": null,
+        "amountCents": 499,
+        "currency": "USD",
+        "autoRenew": false,
+        "isFirstRechargeOffer": false,
+        "firstRechargeDiscountPercent": 0,
+        "promotionType": null
+      }
+    ]
+  }
+}
+```
+
+### 4.5 响应字段
+
+| 字段 | 类型 | 可空 | 说明 |
+| --- | --- | --- | --- |
+| `data.characterId` | string | 是 | 本次查询的角色；省略请求参数时为 `null`。 |
+| `data.categories` | array | 否 | 当前结果中的品类，顺序与 Manager 商品排序一致。 |
+| `categories[].category` | string | 否 | 稳定品类值，只用于关联和筛选。 |
+| `categories[].name` | string | 否 | 品类展示名称。 |
+| `categories[].productCount` | number（整数） | 否 | 当前品类中的启用商品数量。 |
+| `categories[].imageUrl` | string | 是 | 该品类第一张可用商品图；没有图片时为 `null`。 |
+| `data.plans` | array | 否 | 当前角色全部启用商品；没有商品时为空数组。 |
+| `plans[].planId` | string | 否 | 商品唯一标识，创建订单时必须原样传回。 |
+| `plans[].planName` | string | 否 | 商品展示名称。 |
+| `plans[].orderType` | string enum | 否 | 礼物固定为 `tip`。 |
+| `plans[].tipType` | string | 否 | 支付成功事件使用的礼物细分类型。 |
+| `plans[].category` | string | 否 | 所属品类，与 `categories[].category` 对应。 |
+| `plans[].characterId` | string | 否 | 收礼角色 ID。 |
+| `plans[].description` | string | 否 | 商品说明，可能为空字符串。 |
+| `plans[].imageUrl` | string | 是 | 完整公开图片 URL；没有图片时为 `null`。 |
+| `plans[].amountCents` | number（整数） | 否 | 展示金额的百分之一；USD 下 `499` 表示 `$4.99`。 |
+| `plans[].currency` | string | 否 | 三位大写币种代码，例如 `USD`。 |
+| `plans[].autoRenew` | boolean | 否 | 礼物固定为 `false`。 |
+| `plans[].isFirstRechargeOffer` | boolean | 否 | 礼物固定为 `false`。 |
+| `plans[].firstRechargeDiscountPercent` | number（整数） | 否 | 礼物固定为 `0`。 |
+| `plans[].promotionType` | string | 是 | 礼物没有促销时为 `null`。 |
+
+## 五、前端通用品类与商品显示逻辑
+
+### 5.1 建议类型
+
+```ts
+interface GiftCategory {
+  category: string;
+  name: string;
+  productCount: number;
+  imageUrl: string | null;
+}
+
+interface GiftProduct {
+  planId: string;
+  planName: string;
+  orderType: "tip";
+  tipType: string;
+  category: string;
+  characterId: string;
+  description: string;
+  imageUrl: string | null;
+  amountCents: number;
+  currency: string;
+  autoRenew: false;
+}
+
+interface GiftCatalog {
+  characterId: string | null;
+  categories: GiftCategory[];
+  plans: GiftProduct[];
+}
+```
+
+### 5.2 状态和筛选
+
+```ts
+const [catalog, setCatalog] = useState<GiftCatalog | null>(null);
+const [selectedCategory, setSelectedCategory] = useState<string | null>(null);
+const [selectedPlanId, setSelectedPlanId] = useState<string | null>(null);
+
+const visibleProducts = (catalog?.plans ?? []).filter(
+  product => product.category === selectedCategory,
+);
+```
+
+- 角色变化时重新请求，并以 `characterId` 作为缓存键，不能复用另一个角色的目录。
+- 请求完成后默认选择 `categories[0].category`；深链指定的品类存在时优先选择深链值。
+- 切换品类只更新 `selectedCategory`，不请求第二个接口。
+- 只有一个品类时可以隐藏品类切换栏。
+- 新增未知品类时仍使用同一套通用商品卡片，禁止编写 `if (category === "coffee")` 一类业务分支。
+- 商品图片优先级：`product.imageUrl` → 当前 `category.imageUrl` → 通用礼物占位图。
+- 商品名称和说明使用 `planName`、`description`；不要使用前端本地咖啡常量覆盖。
+- 价格使用 `Intl.NumberFormat`，金额为 `amountCents / 100`。
+
+```ts
+const displayPrice = new Intl.NumberFormat("en-US", {
+  style: "currency",
+  currency: product.currency,
+}).format(product.amountCents / 100);
+```
+
+### 5.3 页面状态
+
+| 状态 | 前端行为 |
+| --- | --- |
+| 加载中 | 显示稳定尺寸的商品骨架，不显示旧角色缓存。 |
+| `categories=[]`、`plans=[]` | 显示“该角色暂时没有可用礼物”，不要回退到写死咖啡。 |
+| 某品类没有商品 | 自动切换到第一个有商品的品类；全部为空时显示空状态。 |
+| `imageUrl=null` | 使用品类图或通用占位图。 |
+| 请求失败 | 显示重试操作，不使用可能过期的价格创建订单。 |
+| 角色切换 | 取消旧请求，清空品类、商品、选中商品、订单和 Stripe 状态。 |
+
+### 5.4 兼容接口
+
+- `GET /api/payment/gift-categories` 保留给只需要品类的旧客户端，新版前端主流程不调用。
+- `GET /api/payment/gift-products?characterId=elio&category=coffee` 仍支持按品类过滤，适用于未来商品数很大时懒加载。
+- `GET /api/payment/tip-plans` 与 `/gift-products` 返回同一协议，旧前端继续读取 `data.plans` 不受影响。
+- 新增的 `data.characterId` 和 `data.categories` 是向后兼容字段。
+
+---
+
+## 六、创建礼物支付订单
+
+### 6.1 请求
+
+```http
+POST /api/payment/create-order
+```
+
+- 完整地址：`https://proapi.banlv-ai.com/api/payment/create-order`
+- 登录鉴权：需要
+- Header：`Authorization: Bearer <USER_TOKEN>`
+- Content-Type：`application/json`
+
+### 6.2 请求字段
+
+| 字段 | 类型 | 必填 | 可空 | 示例 | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `planId` | string | 是 | 否 | `tip_coffee_usd_4_99` | 必须使用本次商品接口返回的原始值。 |
+| `payChannel` | enum string | 是 | 否 | `stripe` | 可选值：`stripe`、`ezpay`。 |
+| `autoRenew` | boolean | 是 | 否 | `false` | 礼物是一次性付款，固定发送 `false`。 |
+| `recipientCharacterId` | string | 否 | 否 | `elio` | 可省略；省略时使用商品所属角色。传入其他角色会被拒绝。 |
+
+### 6.3 请求示例
+
+```bash
+curl -X POST 'https://proapi.banlv-ai.com/api/payment/create-order' \
+  -H 'Authorization: Bearer <USER_TOKEN>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "planId": "tip_coffee_usd_4_99",
+    "payChannel": "stripe",
+    "autoRenew": false,
+    "recipientCharacterId": "elio"
+  }'
+```
+
+### 6.4 Stripe 成功响应
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "success": true,
+  "data": {
+    "orderId": "pay_xxx",
+    "payParams": {
+      "clientSecret": "<STRIPE_CLIENT_SECRET>",
+      "provider": "stripe",
+      "automaticRenewal": false,
+      "firstChargeAmountCents": 499,
+      "renewalAmountCents": null
+    },
+    "expiresAt": "2026-07-20T10:30:00+00:00",
+    "expiresInSeconds": 1800
+  }
+}
+```
+
+### 6.5 Stripe 前端处理要求
+
+- 使用 `data.payParams.clientSecret` 挂载 Stripe Payment Element。
+- `firstChargeAmountCents` 应与所选商品的 `amountCents` 一致，可用于提交支付前的防错校验。
+- 用户切换商品或重新创建订单后，必须销毁旧 Payment Element，并使用新的 `orderId + clientSecret` 重新挂载。
+- 不要复用上一件商品的 `clientSecret`，否则页面商品名称、显示价格和实际 PaymentIntent 可能不属于同一订单。
+- 礼物不会增加积分或 VIP，不参加首充折扣，也不会自动续费。
+
+EzPay 响应可能在 `payParams` 中返回 `cashierUrl` 或 `payData`，前端按对应支付渠道处理。
+
+---
+
+## 七、轮询订单状态
+
+### 7.1 请求
+
+```http
+GET /api/payment/order-status?order_id=<ORDER_ID>
+```
+
+- 完整地址：`https://proapi.banlv-ai.com/api/payment/order-status`
+- 登录鉴权：需要，必须与创建订单的用户一致
+- Header：`Authorization: Bearer <USER_TOKEN>`
+- 查询字段兼容性说明：当前字段名是 `order_id`，不是 `orderId`
+
+### 7.2 请求示例
+
+```bash
+curl 'https://proapi.banlv-ai.com/api/payment/order-status?order_id=<ORDER_ID>' \
+  -H 'Authorization: Bearer <USER_TOKEN>'
+```
+
+### 7.3 关键响应字段
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "success": true,
+  "data": {
+    "orderId": "pay_xxx",
+    "status": "paid",
+    "orderType": "tip",
+    "planId": "tip_coffee_usd_4_99",
+    "creditsAdded": 0
+  }
+}
+```
+
+| 字段 | 类型 | 可空 | 说明 |
+| --- | --- | --- | --- |
+| `orderId` | string | 否 | 当前订单号。 |
+| `status` | enum string | 否 | `pending`、`paid`、`failed` 或 `expired`。 |
+| `orderType` | string | 否 | 礼物订单为 `tip`。 |
+| `planId` | string | 是 | 当前订单对应的商品 `planId`。 |
+| `creditsAdded` | number（整数） | 否 | 礼物订单固定为 `0`。 |
+
+建议每 3 至 5 秒轮询一次；出现 `paid`、`failed` 或 `expired` 后立即停止。
+
+---
+
+## 八、获取付款后感谢文案
+
+### 8.1 请求
+
+```http
+POST /api/payment/tip-message
+```
+
+仅在订单状态已经变为 `paid` 后调用。
+
+- 完整地址：`https://proapi.banlv-ai.com/api/payment/tip-message`
+- 登录鉴权：需要，必须是订单所属用户
+- Header：`Authorization: Bearer <USER_TOKEN>`
+- Content-Type：`application/json`
+
+### 8.2 请求字段
+
+| 字段 | 类型 | 必填 | 可空 | 示例 | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `orderId` | string | 是 | 否 | `pay_xxx` | 当前用户已经支付成功的礼物订单号。 |
+
+### 8.3 请求示例
+
+```bash
+curl -X POST 'https://proapi.banlv-ai.com/api/payment/tip-message' \
+  -H 'Authorization: Bearer <USER_TOKEN>' \
+  -H 'Content-Type: application/json' \
+  -d '{"orderId":"<PAID_ORDER_ID>"}'
+```
+
+### 8.4 成功响应
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "success": true,
+  "data": {
+    "orderId": "pay_xxx",
+    "characterId": "elio",
+    "planId": "tip_coffee_usd_4_99",
+    "productName": "Velvet Espresso",
+    "tipCount": 1,
+    "poolIndex": 37,
+    "message": "This is the 1st time you've sent me \"Velvet Espresso\". You have a knack for making me smile."
+  }
+}
+```
+
+### 8.5 响应字段
+
+| 字段 | 类型 | 可空 | 说明 |
+| --- | --- | --- | --- |
+| `orderId` | string | 否 | 已支付订单号。 |
+| `characterId` | string | 否 | 收礼角色 ID。 |
+| `planId` | string | 否 | 本次实际支付商品的 `planId`。 |
+| `productName` | string | 否 | 本次实际支付商品名称。 |
+| `tipCount` | number（整数） | 否 | 当前用户对同一 `planId` 的成功支付次数。 |
+| `poolIndex` | number（整数） | 否 | 本次选中的预生成文案下标，范围为 `0` 至 `99`。 |
+| `message` | string | 否 | 可直接展示的完整英文文案。 |
+
+每个角色在 Manager 中预先保存正好 100 条英文感谢语。后端使用 `characterId + orderId` 稳定选择一条，因此同一个 `orderId` 重复请求时，`poolIndex` 和 `message` 保持一致。该接口不会在请求时调用 AI。
+
+---
+
+## 十、前端验收步骤
+
+1. 在预发请求 Elio 的品类，确认页面根据接口返回结果渲染，没有写死咖啡品类。
+2. 请求选中品类的商品，确认商品名称、`planId`、图片、`amountCents` 和币种全部来自接口。
+3. 分别选择 `$4.99`、`$9.99` 商品，确认创建订单请求发送的是对应商品自己的 `planId`。
+4. 创建订单后校验 `payParams.firstChargeAmountCents === product.amountCents`；不一致时阻止支付并重新创建订单。
+5. 切换商品后确认旧 Stripe Payment Element 已销毁，新的组件使用新 `clientSecret`。
+6. 使用预发测试账号完成一笔允许的支付，轮询状态直到 `paid`。
+7. 连续两次调用付款后文案接口，确认同一订单返回内容完全一致。
+8. 再次购买同一商品，确认 `tipCount` 增加 1。
+9. 确认礼物付款后没有增加积分、VIP 或自动续费。
+
+## 十一、注意事项
+
+- 前端不要缓存并跨商品复用 `orderId`、`clientSecret` 或 `payParams`。
+- `planId` 是商品身份，`amountCents` 是商品价格；二者必须来自同一次商品接口响应。
+- 品类或商品为空时展示空状态，不要回退到写死的旧咖啡商品。
+- `imageUrl=null` 是合法结果，应显示本地占位图。
+- 本接口没有新增数据库迁移，也没有改变现有公开字段命名。

barrelsby.json

@@ -25,9 +25,9 @@
     "./src/data/schemas/payment",
     "./src/data/schemas/payment/request",
     "./src/data/schemas/payment/response",
-    "./src/data/schemas/private-room",
+    "./src/data/schemas/private-zone",
-    "./src/data/schemas/private-room/request",
+    "./src/data/schemas/private-zone/request",
-    "./src/data/schemas/private-room/response",
+    "./src/data/schemas/private-zone/response",
     "./src/data/schemas/user",
     "./src/data/storage/app",
     "./src/data/storage/auth",

docs/auto-build-restart.md

@@ -12,7 +12,7 @@
 
 | 环境 | Git remote | 推送分支 | 宿主机端口 | 容器端口 | 部署脚本 |
 | --- | --- | --- | --- | --- | --- |
-| 测试环境 | `test` | `test` | `9135` | `3000` | `scripts/deploy/deploy_web_test.sh` |
+| 预发环境 | `test` | `pre` | `9135` | `3000` | `scripts/deploy/deploy_web_test.sh` |
 | 生产环境 | `production` | `main` | `9185` | `3000` | `scripts/deploy/deploy_web.sh` |
 
 当前 remote 配置示例：
@@ -26,15 +26,15 @@ production root@43.106.13.130:/root/cozsweet-repos/main
 
 ## 本地发布流程
 
-旧测试环境发布流程（脚本迁移前）：
+旧预发环境发布流程（脚本迁移前）：
 
-1. 进入 test worktree：`cozsweet-frontend-nextjs.worktrees/cozsweet-nextjs-test`
+1. 进入 pre worktree：`cozsweet-frontend-nextjs.worktrees/cozsweet-nextjs-pre`
 2. 确认当前分支。
-3. 执行 `git rebase dev`，把 `dev` 的最新代码变基到 `test` 分支。
+3. 执行 `git rebase dev`，把 `dev` 的最新代码变基到 `pre` 分支。
 4. 复制测试环境图标到 `public/`。
 5. 复制 `env-example/.env.local.example` 到 `.env.local`。
 6. 执行旧版 `scripts/deploy/deploy_web_test.sh`。
-7. 旧版 `deploy_web_test.sh` 推送 `test` remote 的 `test` 分支。
+7. 旧版 `deploy_web_test.sh` 推送 `test` remote 的 `pre` 分支。
 8. 推送成功后尝试清除 Cloudflare CDN 缓存。
 
 旧生产环境发布流程（脚本迁移前）：
@@ -71,7 +71,7 @@ production root@43.106.13.130:/root/cozsweet-repos/main
 | 服务端分支 | 环境变量复制 | 宿主机端口 | 容器名 | 镜像标签 |
 | --- | --- | --- | --- | --- |
 | `main` | `env-example/.env.production.example` → `.env.production` | `9185` | `cozsweet-web-prod` | `cozsweet-web:prod-<commit>` |
-| `test` | `env-example/.env.local.example` → `.env.local` | `9135` | `cozsweet-web-test` | `cozsweet-web:test-<commit>` |
+| `pre` | `env-example/.env.local.example` → `.env.local` | `9135` | `cozsweet-web-test` | `cozsweet-web:test-<commit>` |
 | `dev` | `env-example/.env.development.example` → `.env.local` | `9135` | `cozsweet-web-dev` | `cozsweet-web:dev-<commit>` |
 | 其他分支 | 使用默认 `.env.local` | `9135` | `cozsweet-web-<branch>` | `cozsweet-web:<branch>-<commit>` |
 
@@ -264,12 +264,12 @@ ABORTED ... (docker compose up failed)
 
 1. `scripts/deploy/*` 只负责推送代码，不负责本地构建和本地启动。
 2. 自动构建和自动重启只发生在服务器端 `post-receive` hook。
-3. `main` 分支对应生产环境，`test` 分支对应测试环境。
+3. `main` 分支对应生产环境，`pre` 分支对应预发环境。
 4. 生产推送当前使用 `git push --force production main`。
 5. 构建失败时不会重启容器，旧容器继续运行。
 6. 服务启动由 Docker Compose 管理，不再使用 `nohup pnpm run start`。
 7. 服务器需要安装 Docker，并支持 `docker compose` 或旧版 `docker-compose` 命令。
-8. 测试环境和生产环境都通过同一套 `post-receive` 容器化流程部署，差异仅由分支、环境变量文件和端口决定。
+8. 预发环境和生产环境都通过同一套 `post-receive` 容器化流程部署，差异仅由分支、环境变量文件和端口决定。
 
 ## 后续优化建议
 

docs/backend/FRONTEND_LOCKED_MEDIA_UNLOCK_API.md

@@ -1,496 +0,0 @@
-# 前端锁消息解锁 API 接入文档
-
-## 1. 文档状态
-
-本文档描述 `POST /api/chat/unlock-private` 与 `GET /api/chat/history` 的最新接口协议，覆盖后端已有锁消息和前端临时创建锁消息两种场景。
-
-当前协议已经实现并通过自动化测试。前端联调前可通过目标环境的 `/openapi.json` 确认 `UnlockPrivateRequest` 已包含 `messageId`、`lockType` 和 `clientLockId`。
-
-`unlock-private` 响应已收敛为紧凑结构。历史兼容别名不再返回，前端必须使用本文列出的标准 camelCase 字段。
-
-环境地址：
-
-| 环境 | API Base URL |
-| --- | --- |
-| test 测试环境 | `https://testapi.banlv-ai.com` |
-| pro 预发环境 | `https://proapi.banlv-ai.com` |
-| production 生产环境 | `https://api.banlv-ai.com` |
-
-## 2. 功能目标
-
-前端可以先展示一条本地锁消息。用户点击解锁时，即使该消息还没有后端 `messageId`，后端也会创建对应的聊天记录，并根据余额决定是否生成真实内容。
-
-核心规则：
-
-1. 余额不足时不生成真实语音、图片或私密内容，不扣积分，但会保存锁消息并返回真实 `messageId`。
-2. 用户充值后，前端使用同一个 `clientLockId` 再次解锁，后端更新原消息，不新增另一条聊天记录。
-3. 成功扣积分并持久化解锁后，`history` 才返回解锁状态。
-4. 刷新页面不会自动解锁。未扣积分、未消耗免费私密额度时，`history` 仍返回 `locked=true`。
-5. 前端只能使用 `unlocked` 或 `lockDetail.locked` 判断锁状态，不能根据 URL 是否为空判断。
-
-## 3. 身份认证
-
-两个接口都使用当前聊天用户的登录 Token：
-
-```http
-Authorization: Bearer <TOKEN>
-Content-Type: application/json
-```
-
-前端不得保存或传递 Supabase service key。
-
-## 4. 解锁接口
-
-### 4.1 请求地址
-
-```http
-POST <API_BASE_URL>/api/chat/unlock-private
-```
-
-生产环境完整地址：
-
-```http
-POST https://api.banlv-ai.com/api/chat/unlock-private
-```
-
-### 4.2 请求参数
-
-请求体为 JSON：
-
-```json
-{
-  "messageId": "可选，有就传",
-  "lockType": "voice_message",
-  "clientLockId": "前端生成的唯一ID，可选但强烈建议"
-}
-```
-
-| 字段 | 类型 | 是否必填 | 示例 | 说明 |
-| --- | --- | --- | --- | --- |
-| `messageId` | string | 否 | `"9a43..."` | 后端真实消息 ID。已有消息时传；前端临时锁消息首次解锁时可以不传。 |
-| `lockType` | string | 临时锁消息必填 | `"voice_message"` | 锁类型。没有有效 `messageId` 时必须传。 |
-| `clientLockId` | string | 否，强烈建议 | `"fb_voice_3737_001"` | 前端锁卡片唯一 ID，用于充值后重试、刷新找回和避免重复创建。 |
-
-`lockType` 支持以下值：
-
-| 标准值 | 兼容别名 | 积分价格 |
-| --- | --- | ---: |
-| `voice_message` | `voice`、`audio` | 20 |
-| `image_paywall` | `image`、`photo`、`picture` | 40 |
-| `private_message` | `private`、`private_topic`、`private_room` | 10 |
-
-建议前端只使用标准值。
-
-### 4.3 `clientLockId` 生成规则
-
-前端在创建锁卡片时生成一次，之后不得改变：
-
-```ts
-const clientLockId = crypto.randomUUID();
-```
-
-同一条锁消息在以下场景中必须继续使用同一个值：
-
-- 第一次点击解锁；
-- 余额不足后进入充值；
-- 充值成功后重新点击解锁；
-- 网络超时后重试；
-- 前端重新渲染同一条本地锁卡片。
-
-首次响应拿到后端 `messageId` 后，前端应同时保存 `messageId` 和 `clientLockId`。
-
-### 4.4 最小请求示例
-
-解锁已有后端消息：
-
-```bash
-curl -X POST 'https://api.banlv-ai.com/api/chat/unlock-private' \
-  -H 'Authorization: Bearer <TOKEN>' \
-  -H 'Content-Type: application/json' \
-  -d '{"messageId":"<MESSAGE_ID>"}'
-```
-
-解锁前端临时语音锁消息：
-
-```bash
-curl -X POST 'https://api.banlv-ai.com/api/chat/unlock-private' \
-  -H 'Authorization: Bearer <TOKEN>' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "lockType":"voice_message",
-    "clientLockId":"codex_test_voice_001"
-  }'
-```
-
-充值后建议把三个字段都传回：
-
-```json
-{
-  "messageId": "<FIRST_RESPONSE_MESSAGE_ID>",
-  "lockType": "voice_message",
-  "clientLockId": "codex_test_voice_001"
-}
-```
-
-## 5. 统一响应结构
-
-```json
-{
-  "code": 200,
-  "message": "success",
-  "success": true,
-  "data": {}
-}
-```
-
-业务解锁失败通常也返回 HTTP 200。前端必须读取 `data.unlocked` 和 `data.reason`，不能只检查 HTTP 状态或顶层 `success`。
-
-重要字段：
-
-| 字段 | 类型 | 说明 |
-| --- | --- | --- |
-| `unlocked` | boolean | 本次操作后是否已真实解锁。 |
-| `reason` | string/null | 本次操作结果原因。 |
-| `messageId` | string | 后端真实消息 ID。首次临时锁请求后也会返回。 |
-| `clientLockId` | string/null | 后端识别到的前端锁 ID。 |
-| `lockType` | string/null | 规范化后的锁类型。 |
-| `content` | string/null | 当前消息文字；私密内容未解锁时可以为 `null`。 |
-| `type` | string | `text` 或 `voice`。 |
-| `audioUrl` | string | 锁定语音为空字符串，成功解锁后是完整 URL。 |
-| `image.url` | string/null | 图片完整 URL；是否展示仍由 `lockDetail.locked` 决定。 |
-| `creditBalance` | number/null | 操作后的当前积分。 |
-| `creditsCharged` | number | 本次实际扣除积分；失败或免费额度解锁为 0。 |
-| `requiredCredits` | number | 当前锁类型需要的积分。 |
-| `shortfallCredits` | number | 余额不足时还差多少积分。 |
-| `lockDetail.locked` | boolean | 前端锁卡片的最终展示开关。 |
-| `lockDetail.showContent` | boolean | 是否允许展示文字内容。 |
-| `lockDetail.showUpgrade` | boolean | 是否展示充值入口。 |
-| `lockDetail.reason` | string/null | 锁定原因。 |
-
-以下重复或与解锁无关的字段已经删除：`message_id`、`messageType`、`reply`、`response`、`audio_url`、`displayMessage`、`localizedMessage`、`paywallTriggered`、`showUpgrade`、`timestamp`、`isGuest`、亲密度字段以及 `blocked` 系列字段。
-
-## 6. 余额不足
-
-请求：
-
-```json
-{
-  "lockType": "voice_message",
-  "clientLockId": "fb_voice_37370387172559600_001"
-}
-```
-
-代表性响应：
-
-```json
-{
-  "code": 200,
-  "message": "success",
-  "success": true,
-  "data": {
-    "unlocked": false,
-    "reason": "insufficient_credits",
-    "type": "voice",
-    "messageId": "<BACKEND_MESSAGE_ID>",
-    "clientLockId": "fb_voice_37370387172559600_001",
-    "lockType": "voice_message",
-    "content": "I left a voice message for you. Unlock it to listen.",
-    "audioUrl": "",
-    "creditBalance": 5,
-    "creditsCharged": 0,
-    "requiredCredits": 20,
-    "shortfallCredits": 15,
-    "lockDetail": {
-      "locked": true,
-      "showContent": true,
-      "showUpgrade": true,
-      "reason": "voice_message",
-      "detail": {
-        "messageId": "<BACKEND_MESSAGE_ID>",
-        "clientLockId": "fb_voice_37370387172559600_001",
-        "lockType": "voice_message",
-        "requiredCredits": 20
-      }
-    }
-  }
-}
-```
-
-前端处理：
-
-1. 使用返回的 `messageId` 替换本地临时消息 ID。
-2. 保留原 `clientLockId`。
-3. 保持锁定状态并打开充值页面。
-4. 充值完成后再次调用解锁接口。
-5. 请求期间禁用解锁按钮，避免用户连续点击。
-
-## 7. 解锁成功
-
-### 7.1 语音成功
-
-后端先确认并扣除 20 积分，然后生成真实文字和语音，更新同一条聊天记录：
-
-```json
-{
-  "code": 200,
-  "message": "success",
-  "success": true,
-  "data": {
-    "unlocked": true,
-    "reason": "ok",
-    "type": "voice",
-    "messageId": "<BACKEND_MESSAGE_ID>",
-    "clientLockId": "fb_voice_37370387172559600_001",
-    "lockType": "voice_message",
-    "content": "I made this voice just for you.",
-    "audioUrl": "https://api.banlv-ai.com/audio/<FILE>.mp3",
-    "creditBalance": 10,
-    "creditsCharged": 20,
-    "requiredCredits": 20,
-    "shortfallCredits": 0,
-    "lockDetail": {
-      "locked": false,
-      "showContent": true,
-      "showUpgrade": false
-    }
-  }
-}
-```
-
-前端收到后直接用本次响应替换锁卡片，播放地址读取 `data.audioUrl`。
-
-### 7.2 图片成功
-
-```json
-{
-  "unlocked": true,
-  "reason": "ok",
-  "messageId": "<BACKEND_MESSAGE_ID>",
-  "clientLockId": "fb_image_001",
-  "lockType": "image_paywall",
-  "image": {
-    "type": "elio_schedule",
-    "url": "https://dbapi.banlv-ai.com/storage/v1/object/public/<PATH>"
-  },
-  "creditBalance": 60,
-  "creditsCharged": 40,
-  "requiredCredits": 40,
-  "lockDetail": {
-    "locked": false,
-    "showContent": true,
-    "showUpgrade": false
-  }
-}
-```
-
-图片读取 `data.image.url`。后端已有图片锁消息可能在锁定时也返回真实 URL，因为 URL 本身不作为解锁凭证；前端仍必须根据 `lockDetail.locked` 遮挡或禁止查看。
-
-前端临时创建、尚未确定图片内容的锁消息，在成功扣积分前可能没有图片 URL；成功后后端选择图片并返回 URL。
-
-### 7.3 私密文本成功
-
-前端临时私密消息按 10 积分生成并解锁：
-
-```json
-{
-  "unlocked": true,
-  "reason": "ok",
-  "messageId": "<BACKEND_MESSAGE_ID>",
-  "clientLockId": "fb_private_001",
-  "lockType": "private_message",
-  "content": "<REAL_PRIVATE_REPLY>",
-  "creditsCharged": 10,
-  "requiredCredits": 10,
-  "lockDetail": {
-    "locked": false,
-    "showContent": true,
-    "showUpgrade": false
-  }
-}
-```
-
-已有后端私密文本仍优先使用每日免费私密额度：登录用户默认每天 2 条，游客默认每天 1 条。成功消耗免费额度后也会持久解锁，但 `creditsCharged=0`。
-
-## 8. History 接口
-
-### 8.1 请求
-
-```http
-GET <API_BASE_URL>/api/chat/history?limit=50&offset=0
-Authorization: Bearer <TOKEN>
-```
-
-```bash
-curl 'https://api.banlv-ai.com/api/chat/history?limit=50&offset=0' \
-  -H 'Authorization: Bearer <TOKEN>'
-```
-
-`limit=1&offset=0` 返回最新的一条数据库聊天记录展开后的消息；接口最终按聊天展示顺序返回 `data.messages`。
-
-### 8.2 锁定消息示例
-
-```json
-{
-  "role": "assistant",
-  "type": "voice",
-  "content": "I left a voice message for you. Unlock it to listen.",
-  "id": "<BACKEND_MESSAGE_ID>",
-  "created_at": "2026-07-13T08:00:00+00:00",
-  "audioUrl": null,
-  "image": {
-    "type": null,
-    "url": null
-  },
-  "lockDetail": {
-    "locked": true,
-    "showContent": true,
-    "showUpgrade": true,
-    "reason": "voice_message",
-    "detail": {
-      "messageId": "<BACKEND_MESSAGE_ID>",
-      "clientLockId": "fb_voice_37370387172559600_001",
-      "lockType": "voice_message",
-      "requiredCredits": 20
-    }
-  }
-}
-```
-
-### 8.3 前端展示规则
-
-```ts
-const locked = message.lockDetail?.locked === true;
-const showText = message.lockDetail?.showContent !== false;
-
-if (locked) {
-  // 展示锁卡片、遮罩或解锁按钮
-} else {
-  // 展示真实内容
-}
-```
-
-各类型规则：
-
-| 状态 | `lockDetail.locked` | URL/内容行为 |
-| --- | ---: | --- |
-| 锁定语音 | `true` | `audioUrl=null`，不能播放。 |
-| 已解锁语音 | `false` | `audioUrl` 是完整可播放 URL。 |
-| 锁定图片 | `true` | `image.url` 可能有值，也可能为空；必须遮挡。 |
-| 已解锁图片 | `false` | 使用完整 `image.url` 展示。 |
-| 锁定私密文本 | `true` | 根据 `showContent` 决定是否显示 `content`。 |
-| 已解锁私密文本 | `false` | 展示完整 `content`。 |
-
-## 9. 推荐 TypeScript 类型
-
-```ts
-type LockType = "voice_message" | "image_paywall" | "private_message";
-
-interface UnlockPrivateRequest {
-  messageId?: string;
-  lockType?: LockType;
-  clientLockId?: string;
-}
-
-interface LockDetail {
-  locked: boolean;
-  showContent: boolean;
-  showUpgrade: boolean;
-  reason?: string | null;
-  hint?: string | null;
-  actionLabel?: string | null;
-  detail?: {
-    messageId?: string;
-    clientLockId?: string;
-    lockType?: LockType;
-    requiredCredits?: number;
-    refundedCredits?: number;
-  } | null;
-}
-
-interface UnlockPrivateData {
-  unlocked: boolean;
-  reason?: string | null;
-  messageId: string;
-  clientLockId?: string | null;
-  lockType?: LockType | null;
-  type: "text" | "voice";
-  content?: string | null;
-  audioUrl: string;
-  image: {
-    type?: string | null;
-    url?: string | null;
-  };
-  creditBalance?: number | null;
-  creditsCharged: number;
-  requiredCredits: number;
-  shortfallCredits: number;
-  lockDetail: LockDetail;
-}
-```
-
-## 10. 异常与前端处理
-
-| `data.reason` | 含义 | 前端处理 |
-| --- | --- | --- |
-| `ok` | 成功扣费并解锁 | 用响应替换锁卡片。 |
-| `not_locked` | 消息已经不是锁定状态 | 直接按已解锁内容展示，不再扣费。 |
-| `insufficient_credits` | 积分不足 | 保存返回的 `messageId`，保持锁定并进入充值。 |
-| `content_generation_failed` | 临时锁内容生成失败 | 后端尝试退回本次积分；保持锁定，允许稍后重试。 |
-| `voice_generation_failed` | 已有语音消息生成失败 | 未扣积分，保持锁定并允许重试。 |
-| `quota_exhausted` | 已有私密文本每日免费额度用完 | 展示 `lockDetail.hint`。 |
-| `invalid_lock_type` | `lockType` 不支持 | 记录前端错误并停止请求。 |
-| `not_found` | 消息不存在且没有有效 `lockType` | 禁用当前解锁按钮或重新同步 history。 |
-
-认证失败会返回 HTTP 401。请求字段类型不合法可能返回 HTTP 422。
-
-## 11. 前端完整流程
-
-```text
-创建本地锁卡片并生成 clientLockId
-  -> 用户点击解锁
-  -> POST /api/chat/unlock-private
-     -> unlocked=true：替换卡片并展示真实内容
-     -> insufficient_credits：保存 messageId，打开充值
-        -> 充值成功
-        -> 使用相同 messageId + lockType + clientLockId 重试
-        -> unlocked=true：替换卡片
-  -> 页面刷新
-  -> GET /api/chat/history
-  -> 只按 lockDetail.locked 恢复锁定或解锁状态
-```
-
-## 12. 测试方法
-
-必须使用测试账号，不要用真实付费用户验证扣费。
-
-1. 准备余额低于 20 的测试账号。
-2. 不传 `messageId`，使用唯一 `clientLockId` 请求 `voice_message`。
-3. 确认 `unlocked=false`、`creditsCharged=0`，并取得非空 `messageId`。
-4. 调用 history，确认同一 `messageId` 存在且 `locked=true`、`audioUrl=null`。
-5. 给测试账号增加到至少 20 积分。
-6. 使用相同 `messageId`、`lockType`、`clientLockId` 再次请求。
-7. 确认 `unlocked=true`、`creditsCharged=20`、`audioUrl` 非空。
-8. 再次调用 history，确认同一消息 `locked=false` 且 `audioUrl` 非空。
-9. 对图片 40 积分和私密文本 10 积分重复验证。
-10. 测试结束后记录测试账号积分变化；生成的聊天记录会保留在 history 中，没有自动清理接口。
-
-后端自动化测试：
-
-```powershell
-.\.venv\Scripts\python.exe -m pytest tests\test_private_unlock.py -q
-```
-
-当前结果：`20 passed`；私密解锁、图片 paywall、私密相册和私密空间相关回归共 `48 passed`。
-
-## 13. 兼容性与回滚
-
-- 已有前端继续只传 `messageId` 的调用方式保持兼容。
-- 请求参数保持兼容：已有前端继续只传 `messageId` 仍可使用。
-- 响应字段有收敛：旧别名不再返回，前端需要按第 5、9 节使用标准字段。
-- 本次功能不需要数据库迁移，通过现有 `chat_messages` 和解锁记录保存状态。
-- 如果上线后需要回滚，只回滚本次后端路由和 schema 代码即可；已生成的聊天记录可保留，不影响旧 history 读取。
-- 上线前需将代码提交并推送到目标环境对应分支：`test`、`pro` 或 `main`，再部署对应环境。
-
-## 14. Needs confirmation
-
-- `https://api.cozsweet.com` 是否继续作为生产 API 别名，不在本次代码和环境配置中确认；本文统一使用正式生产地址 `https://api.banlv-ai.com`。

docs/backend/FRONTEND_MULTI_CHARACTER_API.md

@@ -1,448 +0,0 @@
-# 单角色应用迁移为多角色聊天架构
-
-## 1. 文档目标
-
-本文档定义 CozSweet 从单角色 Elio 迁移到多角色架构时，后端需要完成的接口、数据模型和兼容策略调整。
-
-迁移目标：
-
-1. 前端通过统一的 Character Catalog 边界读取角色目录，当前由本地只读目录提供，后端只识别稳定角色 ID。
-2. 同一用户可以分别与多个角色聊天。
-3. 不同角色的聊天历史、媒体、锁内容、私密相册和打赏归属必须隔离。
-4. 钱包、VIP、支付套餐和每日免费额度继续按用户全局共享。
-5. 现有客户端和历史数据继续默认归属于 Elio。
-
-本文档中的标准角色标识：
-
-| 类型 | Elio 示例 | 用途 |
-| --- | --- | --- |
-| `id` | `character_elio` | 数据库关联、API 请求和缓存隔离 |
-| `slug` | `elio` | 前端 URL 和外部入口 |
-
-后端业务接口必须使用 `id`，不能使用可能变化的展示名称。
-
-环境地址：
-
-| 环境 | API Base URL |
-| --- | --- |
-| test 测试环境 | `https://testapi.banlv-ai.com` |
-| pro 预发环境 | `https://proapi.banlv-ai.com` |
-| production 生产环境 | `https://api.banlv-ai.com` |
-
-## 2. 前端 Character Catalog
-
-后端角色目录协议尚未确定。过渡阶段由前端本地只读 Catalog 提供角色，并使用 `slug` 解析角色路径、使用 `id` 调用后端业务接口。业务页面只消费 Catalog 边界；后续切换为服务端目录时不改变角色路由和业务组件接口。
-
-当前角色：
-
-| `id` | `slug` | `displayName` | 头像 | 页面封面 | 私密空间 Banner |
-| --- | --- | --- | --- | --- | --- |
-| `character_elio` | `elio` | Elio Silvestri | `/images/avatar/elio.png` | `/images/cover/elio.png` | `/images/private-room/banner/elio.png` |
-| `character_maya` | `maya` | Maya Tan | `/images/avatar/maya.png` | `/images/cover/maya.png` | `/images/private-room/banner/maya.png` |
-| `character_nayeli` | `nayeli` | Nayeli Cervantes | `/images/avatar/nayeli.png` | `/images/cover/nayeli.png` | `/images/private-room/banner/nayeli.png` |
-
-当前开发环境开放表中的全部角色。Catalog 同时保存短名称、页面资源、空聊天问候语、排序及 Chat、Private Room、Tip 能力。后端配置中的角色 ID 必须与前端目录一致。
-
-## 3. 聊天接口调整
-
-### 3.1 通用规则
-
-以下接口新增标准字段 `characterId`：
-
-```text
-POST /api/chat/send
-GET  /api/chat/history
-POST /api/chat/unlock-private
-POST /api/chat/unlock-history
-```
-
-`characterId` 使用前端本地角色目录中的 `id`，例如 `character_elio`，不能传 slug 或显示名称。
-
-后端必须使用以下维度定位聊天数据：
-
-```text
-正式用户：userId + characterId
-游客：guest identity/device identity + characterId
-```
-
-任何历史查询、消息发送、解锁和配额判断都不能只按用户查找。
-
-### 3.2 发送消息
-
-```http
-POST /api/chat/send
-Content-Type: application/json
-Authorization: Bearer <TOKEN>
-```
-
-现有请求体增加 `characterId`，其他字段保持原协议：
-
-```json
-{
-  "characterId": "character_elio",
-  "message": "Hello Elio",
-  "image": "",
-  "imageId": "",
-  "imageThumbUrl": "",
-  "imageMediumUrl": "",
-  "imageOriginalUrl": "",
-  "imageWidth": 0,
-  "imageHeight": 0,
-  "useWebSocket": false
-}
-```
-
-后端处理要求：
-
-1. 校验角色存在且已启用。
-2. 使用 `characterId` 选择对应角色 Prompt、模型配置和聊天上下文。
-3. 只加载该用户与该角色的历史。
-4. 新消息和生成结果必须写入相同 `characterId`。
-5. 响应继续沿用现有 `ChatSendResponse`，不额外返回前端不使用的角色字段。
-
-如果后端启用 WebSocket，连接握手或每条发送帧也必须携带 `characterId`，不能依赖服务端进程内的“当前角色”状态。
-
-### 3.3 获取聊天历史
-
-```http
-GET /api/chat/history?characterId=character_elio&limit=50&offset=0
-Authorization: Bearer <TOKEN>
-```
-
-| 参数 | 类型 | 是否必填 | 说明 |
-| --- | --- | --- | --- |
-| `characterId` | string | 是 | 角色业务 ID。 |
-| `limit` | integer | 否 | 保持现有分页规则。 |
-| `offset` | integer | 否 | 保持现有分页规则。 |
-
-响应结构和分页字段保持不变。`messages`、`total` 和 `offset` 必须只统计当前角色。
-
-禁止在当前角色历史中返回其他角色的消息，即使消息属于同一用户。
-
-### 3.4 解锁单条消息
-
-```http
-POST /api/chat/unlock-private
-Content-Type: application/json
-Authorization: Bearer <TOKEN>
-```
-
-请求体增加 `characterId`：
-
-```json
-{
-  "characterId": "character_elio",
-  "messageId": "message-id",
-  "lockType": "voice_message",
-  "clientLockId": "client-generated-id"
-}
-```
-
-现有 `messageId`、`lockType` 和 `clientLockId` 规则保持不变。
-
-后端必须验证：
-
-- 已存在消息的 `character_id` 与请求 `characterId` 一致。
-- 临时锁消息不存在 `messageId` 时，新建消息必须写入请求角色。
-- `clientLockId` 的幂等范围至少包含身份和角色，推荐唯一键：
-
-```text
-identity + character_id + client_lock_id
-```
-
-跨角色解锁返回 `CHARACTER_MISMATCH`，不能扣积分，也不能修改消息。
-
-### 3.5 一键解锁历史
-
-```http
-POST /api/chat/unlock-history
-Content-Type: application/json
-Authorization: Bearer <TOKEN>
-```
-
-请求体由空请求调整为：
-
-```json
-{
-  "characterId": "character_elio"
-}
-```
-
-后端只能统计和解锁当前角色的锁消息。`requiredCredits`、解锁数量和返回 messages 都必须按当前角色计算。
-
-## 4. 角色最新消息接口
-
-角色列表需要一次性获取各角色的最新消息，避免对每个角色分别请求 history。
-
-### 4.1 请求
-
-```http
-GET /api/chat/previews
-Authorization: Bearer <TOKEN>
-```
-
-### 4.2 响应
-
-```json
-{
-  "success": true,
-  "message": "success",
-  "data": {
-    "items": [
-      {
-        "characterId": "character_elio",
-        "message": {
-          "id": "message-id",
-          "role": "assistant",
-          "type": "text",
-          "content": "How was your day?",
-          "createdAt": "2026-07-17T10:00:00Z"
-        }
-      },
-      {
-        "characterId": "character_aria",
-        "message": null
-      }
-    ]
-  }
-}
-```
-
-- `items` 按前端本地角色目录顺序返回当前可用角色。
-- `message` 使用现有 ChatMessage wire 结构；没有历史时返回 `null`。
-- 锁消息继续遵循现有内容隐藏规则，不能通过预览接口泄露 URL 或锁定内容。
-- 查询应批量完成，避免后端内部出现按角色逐条查询的 N+1 问题。
-
-## 5. 私密空间接口调整
-
-### 5.1 获取相册
-
-标准请求改为：
-
-```http
-GET /api/private-room/albums?characterId=character_elio&limit=20
-Authorization: Bearer <TOKEN>
-```
-
-兼容期继续接受旧参数：
-
-```http
-GET /api/private-room/albums?character=elio&limit=20
-```
-
-参数优先级：
-
-1. 存在 `characterId` 时使用标准 ID。
-2. 兼容期仅存在 `character` 时，将旧 slug 解析为角色 ID。
-3. 两者同时存在但指向不同角色时返回 `CHARACTER_MISMATCH`。
-4. 两者都缺失时，兼容期默认 Elio。
-
-响应结构保持不变，不增加前端未使用的角色字段。
-
-### 5.2 解锁相册
-
-接口路径保持不变：
-
-```http
-POST /api/private-room/albums/{albumId}/unlock
-```
-
-`albumId` 已能唯一确定角色，因此请求体不增加 `characterId`。后端必须根据 album 关联的角色进行权限、积分和解锁记录校验。
-
-## 6. Tip 支付接口调整
-
-### 6.1 创建订单
-
-现有接口：
-
-```http
-POST /api/payment/create-order
-```
-
-请求体增加可选字段 `recipientCharacterId`：
-
-```json
-{
-  "planId": "tip_coffee_medium",
-  "payChannel": "stripe",
-  "autoRenew": false,
-  "recipientCharacterId": "character_elio"
-}
-```
-
-后端必须先根据 `planId` 判断订单类型：
-
-| 订单类型 | `recipientCharacterId` 规则 |
-| --- | --- |
-| Tip | 必填，并校验角色存在且启用 |
-| VIP | 忽略，不保存 |
-| Top-up | 忽略，不保存 |
-
-Tip 订单和最终支付记录需要保存 `recipient_character_id`，用于归属、统计和后续展示。
-
-支付套餐、创建订单响应和订单状态响应不增加角色字段。
-
-## 7. 数据模型调整
-
-### 7.1 Characters 表
-
-后台建议至少保存：
-
-| 字段 | 说明 |
-| --- | --- |
-| `id` | 主键，稳定角色 ID。 |
-| `slug` | 唯一 URL 标识。 |
-| `display_name` | 展示名称。 |
-| `avatar_url` | 头像地址。 |
-| `enabled` | 是否对用户启用，仅后台使用。 |
-| `sort_order` | 运营排序，仅后台使用。 |
-| `created_at` | 创建时间。 |
-| `updated_at` | 更新时间。 |
-
-`enabled` 和 `sort_order` 是后端管理字段，不返回前端。
-
-### 7.2 业务表
-
-以下数据增加 `character_id` 外键：
-
-- conversations 或等价会话表；
-- chat messages；
-- 锁消息、解锁记录和 `clientLockId` 幂等记录；
-- private albums 及相册解锁记录；
-- Tip 订单或 Tip 业务记录。
-
-推荐索引：
-
-```text
-(user_id, character_id, created_at)
-(guest_id, character_id, created_at)
-(character_id, enabled)
-(identity, character_id, client_lock_id) UNIQUE
-```
-
-如果当前系统没有 conversations 表，可以继续使用 messages，但所有历史查询必须显式包含 `character_id`。
-
-## 8. 历史数据迁移
-
-上线新接口前执行：
-
-1. 创建 Elio 角色，固定 `id=character_elio`、`slug=elio`。
-2. 为相关业务表增加可空 `character_id`。
-3. 将现有消息、锁记录、相册和 Tip 记录全部回填为 `character_elio`。
-4. 检查不存在空角色或无法关联的数据。
-5. 创建联合索引和外键。
-6. 将必要业务表的 `character_id` 调整为非空。
-
-回填前后需要核对每张表的记录数量，迁移不能删除历史聊天或解锁状态。
-
-## 9. 兼容发布策略
-
-### 第一阶段：后端兼容
-
-- 上线角色 ID 配置和新字段。
-- Chat 请求缺少 `characterId` 时暂时默认 `character_elio`。
-- Private Room 缺少角色时暂时默认 Elio。
-- Tip 旧客户端缺少 recipient 时，旧 Tip 订单暂时默认 Elio。
-- 记录缺少角色参数的调用次数和客户端版本。
-
-### 第二阶段：前端迁移
-
-- 新前端所有请求显式发送角色 ID。
-- 动态路由和支付回跳携带角色上下文。
-- 观察错误率、跨角色校验和旧请求占比。
-
-### 第三阶段：收紧协议
-
-- Chat 接口缺少 `characterId` 时返回 `CHARACTER_REQUIRED`。
-- Tip 订单缺少 recipient 时返回 `CHARACTER_REQUIRED`。
-- 删除 Private Room 旧 `character` 参数。
-- 删除默认 Elio 的接口兼容逻辑。
-
-由于 PWA 和浏览器可能长期缓存旧前端，第三阶段只能在旧请求流量降至可接受水平后执行。
-
-只有“完全缺少角色字段”的旧请求可以在兼容期默认 Elio。显式传入不存在、禁用或不匹配角色时不得回退 Elio。
-
-## 10. 错误响应
-
-统一失败 envelope：
-
-```json
-{
-  "success": false,
-  "message": "Character is not available",
-  "error": "CHARACTER_DISABLED"
-}
-```
-
-新增错误：
-
-| HTTP 状态 | error | 场景 |
-| ---: | --- | --- |
-| `400` | `CHARACTER_REQUIRED` | 收紧协议后缺少角色字段。 |
-| `404` | `CHARACTER_NOT_FOUND` | `id` 或兼容 slug 不存在。 |
-| `403` | `CHARACTER_DISABLED` | 角色存在但未启用。 |
-| `409` | `CHARACTER_MISMATCH` | 消息、相册或重复参数属于不同角色。 |
-
-角色错误不能扣积分、创建消息、创建订单或修改任何解锁状态。
-
-## 11. 安全和一致性要求
-
-- 角色 ID 必须由后端查询验证，不能信任客户端展示信息。
-- 用户只能读取自己的某个角色会话，不能通过替换 characterId 读取其他用户数据。
-- messageId、albumId 和 clientLockId 必须同时校验身份与角色归属。
-- 角色禁用后不能继续发送、解锁、创建相册订单或 Tip 订单。
-- 角色禁用不删除历史数据，恢复启用后历史仍可读取。
-- 日志可以记录 `characterId`，但不能记录聊天正文、Token 或私密媒体 URL。
-- Analytics 和业务统计统一使用角色 ID，不使用 displayName。
-
-## 12. 联调验收
-
-后端完成后至少验证：
-
-1. 前端本地目录中的每个角色 ID 均可调用 Chat、Private Room 和 Tip 业务接口。
-2. Login Token 和 Guest Token 均可按角色 ID 聊天。
-3. 同一用户在 Elio 和其他角色中的历史完全隔离。
-4. 发送消息、历史分页、单条解锁和历史解锁都限定当前角色。
-5. 使用 Elio 的 messageId 配合其他角色 ID 解锁时返回 `CHARACTER_MISMATCH`，且不扣积分。
-6. Private Room 的标准 characterId 与旧 character slug 在兼容期结果一致。
-7. Tip 订单正确保存 `recipient_character_id`，VIP 和 Top-up 不保存。
-8. 角色预览接口一次返回各启用角色的最新消息，没有历史时返回 `null`。
-9. 后端禁用角色后，直接访问业务接口返回 `CHARACTER_DISABLED`；前端发布时同步移除本地记录。
-10. 缺少角色字段的旧请求在兼容期仍进入 Elio。
-11. 历史数据回填前后记录数量、积分和解锁状态一致。
-
-## 13. OpenAPI 参考
-
-```yaml
-paths:
-  /api/chat/history:
-    get:
-      parameters:
-        - in: query
-          name: characterId
-          required: true
-          schema:
-            type: string
-        - in: query
-          name: limit
-          required: false
-          schema:
-            type: integer
-        - in: query
-          name: offset
-          required: false
-          schema:
-            type: integer
-  /api/chat/unlock-history:
-    post:
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required: [characterId]
-              properties:
-                characterId:
-                  type: string
-```

docs/backend/FRONTEND_MULTI_ROLE_CHAT_API.md

@@ -1,28 +1,95 @@
-# CozSweet 多角色聊天前端对接
+# CozSweet 多角色聊天权威协议
 
-## 3. Character IDs
+## 1. 状态与范围
 
-前端先调用：
+本文是前端仓库中多角色目录、聊天、解锁、缓存隔离及关联业务的唯一人工维护协议。旧的单角色迁移方案和独立锁媒体协议已删除，不再作为实现或联调依据。
+
+协议描述当前前端已经执行的行为，不描述尚未落地的后端迁移步骤。字段和路径由下列机器可验证入口约束：
+
+| 边界 | 实现位置 |
+| --- | --- |
+| API 路径与方法 | `src/data/services/api/api_contract.json` |
+| 请求与响应字段 | `src/data/schemas/character`、`src/data/schemas/chat` |
+| 角色 ID、slug 与本地资源 | `src/data/constants/character.ts` |
+| Chat UI 消息身份 | `src/stores/chat/ui-message.ts` |
+| 本地缓存身份 | `src/data/repositories/chat_cache_identity.ts`、`src/lib/chat/chat_cache_keys.ts` |
+
+如本文与上述实现发生差异，修改代码时必须在同一变更中更新本文，不能新增第二份并行协议。
+
+## 2. 角色目录与路由
+
+### 2.1 角色身份
+
+`id` 是 API、状态机、缓存和数据归属使用的稳定业务身份；`slug` 只用于 URL。
+
+| `id` | `slug` | 展示名称 |
+| --- | --- | --- |
+| `elio` | `elio` | Elio Silvestri |
+| `maya-tan` | `maya` | Maya Tan |
+| `nayeli-cervantes` | `nayeli` | Nayeli Cervantes |
+
+不得向业务 API 发送 slug、展示名称、`@handle` 或旧 ID。旧 ID `character_elio`、`character_maya`、`character_nayeli` 仅用于本地持久化数据迁移。
+
+### 2.2 角色目录接口
 
 ```http
 GET <API_BASE_URL>/api/characters?capability=chat
+Authorization: Bearer <TOKEN>
 ```
 
-聊天业务统一使用响应里的 `items[].id`。当前规范 ID 是：
+标准响应数据：
+
+```json
+{
+  "items": [
+    {
+      "id": "maya-tan",
+      "displayName": "Maya Tan",
+      "isActive": true,
+      "capabilities": {
+        "chat": true,
+        "privateContent": true
+      },
+      "sortOrder": 20
+    }
+  ],
+  "defaultCharacterId": "elio"
+}
+```
+
+前端只接纳同时满足以下条件的角色：
+
+1. `id` 存在于本地资源目录；
+2. `isActive=true`；
+3. `capabilities.chat=true`。
+
+服务端目录决定角色是否可聊天及排序；本地目录继续提供 slug、图片、文案和 Tip 能力。`privateZone` 只有在本地能力和服务端 `privateContent` 同时开启时可用。
+
+远端目录返回前，生产环境只使用 Elio 作为临时目录；非生产环境可使用完整本地目录。远端目录加载成功后，以合并结果为准。
+
+### 2.3 页面路由
 
 ```text
-elio
+/characters/{slug}/splash
-maya-tan
+/characters/{slug}/chat
-nayeli-cervantes
+/characters/{slug}/private-zone
+/characters/{slug}/tip
 ```
 
-只允许传递角色目录响应中的 `items[].id`，不要传展示名或 `@handle`。
+当前 Splash 是角色详情入口，不是全角色列表页。以下旧地址保留为默认角色重定向，并原样保留查询参数：
 
-角色响应中的 `capabilities` 是后端权威开关。`chat=false` 时不得开放输入框；直接调用聊天接口会得到 `CHARACTER_DISABLED`，不会返回 Elio 历史。
+```text
+/splash       -> /characters/elio/splash
+/chat         -> /characters/elio/chat
+/private-zone -> /characters/elio/private-zone
+/tip          -> /characters/elio/tip
+```
 
-## 4. Send Message
+Chat Provider 以 `characterId` 为边界，路由角色变化时创建新的 Actor。Private Zone 的角色边界由 [Private Zone 权威协议](./FRONTEND_PRIVATE_ZONE_API.md) 定义。
 
-### Request URL
+## 3. Chat HTTP 协议
+
+### 3.1 发送消息
 
 ```http
 POST <API_BASE_URL>/api/chat/send
@@ -30,73 +97,56 @@ Content-Type: application/json
 Authorization: Bearer <TOKEN>
 ```
 
-### Parameters
+```json
-
+{
-| Field | Type | Required | Example | Meaning |
+  "characterId": "maya-tan",
-| --- | --- | --- | --- | --- |
+  "message": "Hello Maya",
-| `characterId` | string | 新前端必传 | `maya-tan` | 当前聊天角色 ID |
+  "useWebSocket": false
-| `message` | string | 与图片至少一项有值 | `Hello Maya` | 用户文本，最多 4000 字符 |
+}
-| `imageId` | string | 否 | `abc123` | 上传图片 ID |
-| `imageThumbUrl` | string | 否 | `/images/...` | 缩略图 |
-| `imageMediumUrl` | string | 否 | `/images/...` | 模型识图使用 |
-| `imageOriginalUrl` | string | 否 | `/images/...` | 原图 |
-| `imageWidth` | integer | 否 | `1080` | 图片宽 |
-| `imageHeight` | integer | 否 | `1440` | 图片高 |
-| `useWebSocket` | boolean | 否 | `false` | 是否同时通过已连接 WS 推送 |
-
-```bash
-curl -X POST 'https://proapi.banlv-ai.com/api/chat/send' \
-  -H 'Authorization: Bearer <TOKEN>' \
-  -H 'Content-Type: application/json' \
-  -d '{"characterId":"maya-tan","message":"Hello Maya","useWebSocket":false}'
 ```
 
-响应沿用现有发送结构。前端仍读取 `data.reply`、`data.messageId`、`data.audioUrl`、`data.image` 和 `data.lockDetail`，无需从响应推断角色。
+请求规则：
 
-## 5. Chat History
+- `characterId` 必填；
+- `message` 最大 4000 字符；
+- `message` 与 `imageId`、`imageThumbUrl`、`imageMediumUrl`、`imageOriginalUrl` 至少一项有效；
+- 图片请求可附带 `imageWidth`、`imageHeight`；
+- `useWebSocket` 缺失时按 `false` 处理。
+
+前端使用的响应字段为：
+
+```text
+reply, audioUrl, messageId, isGuest, timestamp, image, lockDetail,
+canSendMessage, creditBalance, creditsCharged, requiredCredits,
+shortfallCredits
+```
+
+`messageId` 是后端消息身份，不是 React key。锁状态只读取 `lockDetail.locked` 和 `lockDetail.reason`。
+
+### 3.2 获取历史
 
 ```http
 GET <API_BASE_URL>/api/chat/history?characterId=maya-tan&limit=50&offset=0
 Authorization: Bearer <TOKEN>
 ```
 
-| Query | Type | Required | Rule |
+| Query | 必填 | 规则 |
-| --- | --- | --- | --- |
+| --- | --- | --- |
-| `characterId` | string | 新前端必传 | 只返回该角色数据 |
+| `characterId` | 是 | 角色业务 ID |
-| `limit` | integer | 否 | `1-200`，默认 `50` |
+| `limit` | 否 | 前端默认 50 |
-| `offset` | integer | 否 | 最小 `0` |
+| `offset` | 否 | 前端默认 0 |
 
-`messages` 和 `total` 都只统计指定角色。切换角色时必须重新请求 history，不能复用上一个角色的本地数组。
+响应数据包含 `messages`、`total`、`limit`、`offset`，并可包含当前私密额度快照。消息字段：
 
-```json
+```text
-{
+role, type, content, id, createdAt/created_at, audioUrl, image, lockDetail
-  "code": 200,
-  "success": true,
-  "message": "success",
-  "data": {
-    "messages": [
-      {
-        "role": "user",
-        "type": "text",
-        "content": "Hello Maya",
-        "id": "<MESSAGE_ID>",
-        "created_at": "2026-07-17T09:00:00Z",
-        "audioUrl": null,
-        "image": {"type": null, "url": null},
-        "lockDetail": {"locked": false, "showContent": true, "showUpgrade": false}
-      }
-    ],
-    "total": 1,
-    "limit": 50,
-    "offset": 0,
-    "isVip": false
-  }
-}
 ```
 
-## 6. Latest Previews
+前端兼容 `createdAt` 和 `created_at` 输入，解析后统一为 `createdAt`。缺失的可空载荷会由 Schema 归一化，业务组件不直接读取原始 envelope。
 
-角色会话列表可一次请求所有可聊天角色的最后一条消息：
+本地快照可先进入可渲染状态；网络历史随后覆盖缓存并更新 UI。网络同步期间新增的乐观消息按 `displayId` 保留。向上拉取更早页面时也按 `displayId` 去重。
+
+### 3.3 最新消息预览
 
 ```http
 GET <API_BASE_URL>/api/chat/previews
@@ -105,20 +155,29 @@ Authorization: Bearer <TOKEN>
 
 ```json
 {
-  "code": 200,
+  "items": [
-  "success": true,
+    {
-  "data": {
+      "characterId": "elio",
-    "items": [
+      "message": {
-      {"characterId": "elio", "message": {"id": "...", "role": "assistant", "type": "text", "content": "..."}},
+        "id": "<MESSAGE_ID>",
-      {"characterId": "maya-tan", "message": null}
+        "role": "assistant",
-    ]
+        "type": "text",
-  }
+        "content": "How was your day?"
+      }
+    },
+    {
+      "characterId": "maya-tan",
+      "message": null
+    }
+  ]
 }
 ```
 
-锁定私密文本不会泄露内容，锁定语音不会返回 `audioUrl`（文字仍正常返回）。图片沿用现有协议，URL 可以存在；前端必须以 `lockDetail.locked=true` 覆盖展示，不能把“URL 非空”当作已解锁。
+接口可用时，Splash 以批量结果更新各角色预览；接口失败时，当前角色可回退到 `history?limit=1&offset=0`。预览缓存仍使用角色会话身份隔离。
 
-## 7. Unlock One Message
+## 4. 解锁协议
+
+### 4.1 解锁单条消息
 
 ```http
 POST <API_BASE_URL>/api/chat/unlock-private
@@ -126,44 +185,144 @@ Content-Type: application/json
 Authorization: Bearer <TOKEN>
 ```
 
+已有后端消息：
+
 ```json
 {
   "characterId": "maya-tan",
-  "messageId": "<MESSAGE_ID>",
+  "messageId": "<MESSAGE_ID>"
-  "lockType": "voice_message",
-  "clientLockId": "maya-card-001"
 }
 ```
 
-`messageId` 存在时，后端会核对消息角色。拿 Elio 的 `messageId` 配 Maya 的 `characterId` 会返回 HTTP `409 / CHARACTER_MISMATCH`，且不会扣积分。
+前端 Promotion 锁卡片：
 
-前端临时伪造锁卡片没有 `messageId` 时，仍传 `characterId + lockType + clientLockId`。`clientLockId` 的幂等查找范围已包含账号和角色，同一个 ID 可以在不同角色下分别使用。
+```json
+{
+  "characterId": "maya-tan",
+  "lockType": "voice_message",
+  "clientLockId": "<STABLE_CLIENT_LOCK_ID>"
+}
+```
 
-## 8. Unlock Current Character History
+请求必须包含 `characterId`，并至少包含 `messageId` 或 `lockType`。标准 `lockType` 为：
+
+```text
+voice_message
+image_paywall
+private_message
+```
+
+前端解析的响应字段：
+
+```text
+unlocked, content, messageId, clientLockId, lockType, audioUrl, image,
+reason, creditBalance, creditsCharged, requiredCredits, shortfallCredits
+```
+
+处理规则：
+
+1. `unlocked=true` 时更新内容、音频、图片和锁状态；
+2. `unlocked=false` 时保持锁定，并根据 `reason` 决定是否打开支付流程；
+3. `reason=not_found` 不打开支付流程；
+4. 响应 `messageId` 只写入 `remoteId`，不得替换 `displayId`；
+5. Promotion 重试继续使用同一个 `clientLockId`；
+6. 跨支付、登录和图片 Overlay 恢复时同时保存显示身份与后端身份。
+
+### 4.2 解锁当前角色历史
 
 ```http
 POST <API_BASE_URL>/api/chat/unlock-history
 Content-Type: application/json
 Authorization: Bearer <TOKEN>
-```
 
-```json
 {"characterId":"maya-tan"}
 ```
 
-费用、锁消息数量、成功解锁数量及 `messageIds` 都只计算当前角色。钱包余额仍是账号全局余额。
+请求和返回消息都限定当前角色。前端完成解锁后重新读取该角色历史，不复用其他角色 Actor 的消息。
 
-## 12. Tip Attribution
+### 4.3 角色错误
 
-只有 Tip 订单使用角色归属：
+前端识别以下后端错误码：
 
-```json
+| 错误码 | 前端行为 |
-{
+| --- | --- |
-  "planId": "tip_coffee_usd_4_99",
+| `CHARACTER_DISABLED` | 禁止继续发送并刷新角色目录 |
-  "payChannel": "stripe",
+| `CHARACTER_NOT_FOUND` | 清理待恢复导航、刷新目录并返回默认角色 |
-  "autoRenew": false,
+| `CHARACTER_MISMATCH` | 不进入支付，刷新当前角色历史 |
-  "recipientCharacterId": "maya-tan"
+| `CHARACTER_STATE_UNAVAILABLE` | 保留会话并提示稍后重试 |
-}
+
+任何角色错误都不得在前端回退为另一个角色的历史。
+
+## 5. UI 消息身份协议
+
+网络字段继续使用 `messageId`；前端 UI 严格区分三种身份：
+
+| 字段 | 用途 | 是否稳定 |
+| --- | --- | --- |
+| `displayId` | React key、DOM 定位、Overlay URL、解锁目标 | 消息生命周期内必须稳定 |
+| `remoteId` | 后端 `messageId`、媒体缓存、解锁 API | 后端返回后可补充 |
+| `clientId` | 乐观发送消息或无后端 ID 的回复 | 创建时生成 |
+
+标准 `displayId`：
+
+```text
+历史消息         server:{encodedRemoteId}:{assistant|user}
+同角色重复 ID    server:{encodedRemoteId}:{role}:{occurrence}
+无后端 ID 历史   legacy:{stableHash}
+乐观文本         client:message:{uuid}
+乐观图片         client:image:{uuid}
+无 ID 回复        client:reply:{uuid}
+错误提示         client:error:{uuid}
+空会话问候语     greeting:{characterId}
+Promotion        promotion:{clientLockId}
 ```
 
-Tip 订单必须携带 `recipientCharacterId`。VIP 和积分充值会忽略该字段。
+同一个后端 ID 可能同时出现在 user 和 assistant 记录中，因此不得直接使用 `remoteId` 作为 React key。解锁前后 `displayId` 不变；图片 Overlay 始终写入 `displayId`，但读取时兼容旧的 `remoteId` URL。
+
+## 6. 本地缓存与会话隔离
+
+缓存 owner 规则：
+
+```text
+正式用户或已有用户 ID 的会话  user:{userId}
+没有用户 ID 的 Guest 会话      device:{deviceId}
+```
+
+正式账号缺少持久化用户 ID 时跳过 Chat 缓存，不得回退到设备级或匿名缓存。
+
+消息和媒体共同使用会话键：
+
+```text
+conversationKey = {ownerKey}::character:{encodeURIComponent(characterId)}
+```
+
+媒体键在该会话下继续包含后端消息 ID 和媒体类型：
+
+```text
+{conversationKey}:{remoteId}:{image|audio}
+```
+
+旧的无角色 owner key 迁移到 Elio；包含旧角色 ID 的 key 迁移到当前后端 ID。迁移是幂等的，不能覆盖已经存在的当前命名空间数据。
+
+切换用户、Guest/正式账号或角色时，不得复用前一个 `conversationKey`。切换角色会销毁旧 Chat Actor；请求取消信号会阻止旧响应写入新角色状态。
+
+## 7. 关联业务边界
+
+- Private Zone 的相册、解锁、Gallery 和支付回跳由 [Private Zone 权威协议](./FRONTEND_PRIVATE_ZONE_API.md) 定义。
+- Tip 的角色归属、订单轮询和支付回跳由 [Payment 权威协议](./FRONTEND_PAYMENT_API.md) 定义；Chat 只保存解锁所需的原角色回跳地址。
+- 登录、支付和解锁回跳保存原角色动态 URL，不能降级为通用 `/chat`。
+- Analytics 可以使用 `characterId`，聊天正文不属于路由或身份协议的一部分。
+
+## 8. 变更验收
+
+协议相关变更至少验证：
+
+1. Character、Chat、Storage、Navigation 和 Payment 的 TypeScript 类型检查；
+2. `src/data/services/api/__tests__/multi_character_api.test.ts`；
+3. `src/stores/chat/__tests__`；
+4. `src/data/storage/chat/__tests__` 与 `src/data/storage/navigation/__tests__`；
+5. `src/app/chat/__tests__` 及 Chat 组件测试；
+6. 同一用户的不同角色、Guest 与正式账号、账号切换后的历史和媒体均不串联；
+7. 快速切换角色时，旧请求不能覆盖新 Actor；
+8. 动态 URL、旧地址重定向、登录和支付回跳恢复正确角色；
+9. 解锁后 `displayId` 不变，`remoteId` 可从响应补齐。

docs/backend/FRONTEND_PAYMENT_API.md

@@ -0,0 +1,292 @@
+# CozSweet Payment 权威协议
+
+## 1. 状态与范围
+
+本文是前端仓库中 VIP、Top-up、Tip、支付渠道、订单轮询和支付回跳的唯一人工维护协议。旧的 Tip 成功结果扩展文档已删除，不再单独定义 Payment 行为。
+
+协议描述当前前端实际执行的行为。字段和状态由以下机器可验证入口约束：
+
+| 边界 | 实现位置 |
+| --- | --- |
+| API 路径与方法 | `src/data/services/api/api_contract.json` |
+| 请求与响应字段 | `src/data/schemas/payment` |
+| API 调用 | `src/data/services/api/payment_api.ts` |
+| Payment 状态机 | `src/stores/payment` |
+| 支付拉起与回跳 | `src/app/_hooks/use-payment-launch-flow.ts`、`src/lib/payment` |
+| Subscription 页面 | `src/app/subscription` |
+| Tip 页面 | `src/app/tip` |
+
+修改上述实现时必须在同一变更中更新本文，不能再新增按支付页面或支付渠道拆分的并行协议。
+
+## 2. API 总览
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| `GET` | `/api/payment/plans` | VIP 与 Top-up 套餐目录 |
+| `GET` | `/api/payment/gift-products?characterId={id}` | 当前角色的完整礼物目录 |
+| `POST` | `/api/payment/create-order` | 创建 VIP、Top-up 或 Tip 订单 |
+| `GET` | `/api/payment/order-status?order_id={id}` | 查询订单状态 |
+| `POST` | `/api/payment/tip-message` | 获取已支付礼物订单的稳定感谢文案 |
+
+所有响应先由通用 envelope 解包，再进入 Payment Schema。页面和状态机不直接读取原始 envelope。
+
+## 3. 套餐目录
+
+### 3.1 默认套餐
+
+```http
+GET <API_BASE_URL>/api/payment/plans
+Authorization: Bearer <TOKEN>
+```
+
+响应数据：
+
+```json
+{
+  "isFirstRecharge": true,
+  "firstRechargeOffer": {
+    "enabled": true,
+    "type": "topup",
+    "discountPercent": 50
+  },
+  "plans": []
+}
+```
+
+`plans[]` 的标准字段：
+
+```text
+planId, planName, orderType, vipDays, dolAmount, creditBalance,
+amountCents, originalAmountCents, dailyPriceCents, currency,
+isFirstRechargeOffer, mostPopular, firstRechargeDiscountPercent,
+promotionType
+```
+
+默认目录写入本地套餐缓存。Payment Actor 启动时先读缓存；有缓存则先渲染并后台刷新，没有缓存则直接请求网络。
+
+支付成功后会清除默认套餐缓存、刷新用户权益，并在当前 Actor 中消费首充展示状态。服务端下一次目录响应仍是最终权威结果。
+
+### 3.2 Gift Products 目录
+
+```http
+GET <API_BASE_URL>/api/payment/gift-products?characterId=elio
+```
+
+```json
+{
+  "characterId": "elio",
+  "categories": [
+    {
+      "category": "coffee",
+      "name": "Coffee",
+      "productCount": 1,
+      "imageUrl": null
+    }
+  ],
+  "plans": [
+    {
+      "planId": "tip_coffee_usd_4_99",
+      "planName": "Velvet Espresso",
+      "orderType": "tip",
+      "tipType": "coffee_small",
+      "category": "coffee",
+      "characterId": "elio",
+      "description": "Buy Elio a small coffee",
+      "imageUrl": null,
+      "amountCents": 499,
+      "currency": "USD",
+      "autoRenew": false
+    }
+  ]
+}
+```
+
+目录不需要登录，也不写入默认套餐缓存。前端必须传当前角色 ID，一次读取 `categories` 和全部 `plans`；当前 Tip 页面固定使用第一分类，并按商品原始顺序默认选择第一件商品，不展示分类切换栏。
+
+名称、说明、图片、金额、币种和 `planId` 全部来自同一条商品数据。状态机把当前分类商品映射为 `PaymentPlan` 以复用 Checkout 和埋点，同时保留完整 Gift Product 供 UI 展示。目录为空或请求失败时禁止创建订单，不回退到本地固定商品或价格。
+
+## 4. 创建订单
+
+```http
+POST <API_BASE_URL>/api/payment/create-order
+Content-Type: application/json
+Authorization: Bearer <TOKEN>
+```
+
+标准请求：
+
+```json
+{
+  "planId": "tip_coffee_usd_4_99",
+  "payChannel": "stripe",
+  "autoRenew": false,
+  "recipientCharacterId": "maya-tan"
+}
+```
+
+| 字段 | 规则 |
+| --- | --- |
+| `planId` | 必须来自当前 Actor 已加载的目录 |
+| `payChannel` | `stripe` 或 `ezpay` |
+| `autoRenew` | Tip 和一次性 Top-up 为 `false`；VIP 根据套餐和用户选择决定 |
+| `recipientCharacterId` | Schema 可选；当前 Tip 页面必传角色业务 ID，VIP 和 Top-up 不传 |
+
+Payment Actor 只有在 `selectedPlanId` 非空且用户已同意协议时创建订单。套餐加载、创建和轮询期间页面会禁用重复提交；Tip 在 paid 状态展示成功页，Subscription 在 paid 状态展示成功 Dialog，随后通过 reset 明确开始下一笔订单。
+
+创建订单响应统一归一化为：
+
+```ts
+interface CreatePaymentOrderResponse {
+  orderId: string;
+  payParams: Record<string, unknown>;
+}
+```
+
+后端可以把支付 URL 放在 `payParams`，也可以使用以下顶层兼容字段；Schema 会把非空值合并进 `payParams`：
+
+```text
+cashierUrl/cashier_url
+checkoutUrl/checkout_url
+paymentUrl/payment_url
+approvalUrl/approval_url
+redirectUrl/redirect_url
+url
+```
+
+## 5. 支付渠道与拉起方式
+
+### 5.1 渠道选择
+
+| 环境与地区 | 行为 |
+| --- | --- |
+| 生产环境、菲律宾 | 可选择 Stripe 或 Ezpay，默认 Ezpay |
+| 生产环境、其他地区 | 强制 Stripe，不展示渠道选择器 |
+| 非生产环境 | 允许选择两个渠道；菲律宾默认 Ezpay，其他地区默认 Stripe |
+
+当生产环境不允许选择渠道时，URL 中请求的 `payChannel` 不生效。
+
+### 5.2 Stripe
+
+`payParams.clientSecret` 或 `payParams.client_secret` 存在，且 provider 未声明为非 Stripe 时，前端动态加载嵌入式 Stripe Dialog。
+
+关闭尚未支付的 Stripe Dialog 会重置当前订单状态；确认支付后隐藏 Dialog，并继续由 Payment Actor 轮询订单状态。
+
+### 5.3 Ezpay 与其他跳转支付
+
+`payParams.provider="ezpay"` 且存在支付 URL 时：
+
+- 生产环境先保存待恢复订单，然后直接跳转外部支付页；
+- 非生产环境先显示确认 Dialog，确认后保存并跳转；
+- 待恢复订单保存失败时不得离开当前页面。
+
+存在支付 URL 但 provider 不是 Ezpay 时，前端直接设置 `window.location.href`。既没有 Stripe client secret 也没有支付 URL 时，订单进入失败状态并展示参数错误。
+
+## 6. 订单状态轮询
+
+```http
+GET <API_BASE_URL>/api/payment/order-status?order_id=<ORDER_ID>
+Authorization: Bearer <TOKEN>
+```
+
+响应数据：
+
+```json
+{
+  "orderId": "tip_order_123",
+  "status": "paid",
+  "orderType": "tip",
+  "planId": "tip_coffee_usd_4_99",
+  "creditsAdded": 0
+}
+```
+
+| 字段 | 前端规则 |
+| --- | --- |
+| `status` | 只接受 `pending`、`paid`、`failed`、`expired` |
+| `planId` | 可为 `null` |
+| `creditsAdded` | 整数；Tip 固定为 `0` |
+
+状态机创建订单或恢复订单后立即查询一次。`pending` 每 4 秒再次查询，最长持续 5 分钟：
+
+- `paid`：进入最终成功状态并停止轮询；
+- `failed`：进入失败状态并停止轮询；
+- `expired`：进入订单过期状态、销毁旧支付参数并停止轮询；
+- 超过 5 分钟：本地标记为失败并显示超时错误；
+- 查询请求本身失败：进入失败状态，不在当前 Actor 中自动重试。
+
+## 7. 外部支付回跳
+
+只有 Ezpay 跳转需要持久化 `PendingPaymentOrder`：
+
+```text
+orderId
+payChannel = ezpay
+subscriptionType = vip | topup | tip
+giftCategory（仅 Tip，可空）
+giftPlanId（仅 Tip，可空）
+returnTo = chat | private-zone | profile（可选）
+characterSlug（可选）
+createdAt
+```
+
+`/subscription/return` 读取该记录并恢复到对应入口：
+
+```text
+VIP / Top-up -> /subscription?type=...&payChannel=ezpay&paymentReturn=1
+Tip          -> /characters/{slug}/tip?category=...&planId=...&payChannel=ezpay&paymentReturn=1
+```
+
+恢复页面只接受与当前 `paymentType` 相同的待处理订单。带有 `paymentReturn=1` 时派发 `PaymentReturned` 并继续轮询；普通进入支付页时会清理同类型的旧待处理订单。订单进入 paid、failed 或 expired 后清理持久化记录。缺少 Gift 字段的旧记录由最新目录默认选择第一件商品，不再读取 `coffee_type`。
+
+无效或未知 `characterSlug` 回退到默认角色 slug。有效角色回跳必须保留原角色，不能统一返回 Elio。`returnTo=private-zone` 的最终页面行为由 [Private Zone 权威协议](./FRONTEND_PRIVATE_ZONE_API.md) 定义。
+
+## 8. 成功后的跨域同步
+
+`PaymentSuccessSync` 在每个订单首次进入 paid 时：
+
+1. 消费当前 Actor 的首充展示状态；
+2. 清除默认套餐缓存；
+3. 派发 `UserFetch` 刷新积分、VIP 和权益。
+
+Chat 路由额外挂载 `ChatPaymentSuccessSync`。如果当前角色没有待恢复的单消息解锁，它会派发 `ChatPaymentSucceeded`，由 Chat 决定是否展示历史解锁提示；存在待恢复单消息解锁时，由原解锁流程接管。
+
+Subscription 显示成功 Dialog，关闭后根据 `returnTo` 和原角色 slug 返回。Tip 直接显示角色成功页，重置后可以再次创建订单。
+
+## 9. Tip 成功结果
+
+Tip 订单进入 paid 后调用：
+
+```http
+POST <API_BASE_URL>/api/payment/tip-message
+Content-Type: application/json
+Authorization: Bearer <TOKEN>
+
+{"orderId":"pay_xxx"}
+```
+
+响应包含 `orderId`、`characterId`、`planId`、`productName`、`tipCount`、`poolIndex` 和可直接展示的完整 `message`。`tipCount` 表示当前付款身份对同一商品的累计成功次数。
+
+Tip 成功页在文案加载期间立即确认支付成功。`tipCount=1` 时展示固定首次咖啡文案并忽略后端 `message`；大于 1 时按纯文本直接展示 `message`。接口失败时展示本地通用感谢语和 Retry，重试只重新请求 Tip Message，不重复轮询订单或创建订单。
+
+## 10. Provider 与状态边界
+
+- `/subscription` 使用独立 Payment Actor；
+- `/characters/{slug}/tip` 使用以 `characterId` 为 key 的 Payment Actor；
+- Chat 路由使用角色级 Payment Actor，以便支付成功桥接当前 Chat；
+- 切换角色或离开对应 Provider 后，不得把旧订单状态显示到另一个角色页面；
+- Payment Actor 只根据订单状态接口判断最终结果，不根据支付 Dialog 或外部跳转本身推断已扣款。
+
+## 11. 变更验收
+
+Payment 协议相关变更至少验证：
+
+1. `src/data/services/api/__tests__/payment_api.test.ts`；
+2. `src/data/repositories/__tests__/payment_repository.test.ts`；
+3. `src/stores/payment/__tests__`；
+4. `src/lib/payment/__tests__`；
+5. `src/app/_hooks/__tests__` 中的 Payment 流程测试；
+6. `src/app/subscription/__tests__` 与 `src/app/tip/__tests__`；
+7. Stripe、Ezpay、paid、failed、expired、timeout 和回跳恢复路径；
+8. Tip 创建订单携带当前角色 ID，VIP/Top-up 不携带；
+9. Tip Message 成功、失败和重试不重复创建订单；
+10. 支付成功后用户权益、套餐缓存和 Chat 解锁协调结果正确。

docs/backend/FRONTEND_PRIVATE_ZONE_API.md

@@ -0,0 +1,241 @@
+# CozSweet Private Zone 权威协议
+
+## 1. 状态与范围
+
+本文是前端仓库中角色私密空间、相册列表、相册解锁、Gallery 和积分不足导航的唯一人工维护协议。
+
+协议描述当前前端实际执行的行为。字段和状态由以下机器可验证入口约束：
+
+| 边界 | 实现位置 |
+| --- | --- |
+| API 路径与方法 | `src/data/services/api/api_contract.json` |
+| 请求与响应字段 | `src/data/schemas/private-zone` |
+| API 与 Repository | `src/data/services/api/private_zone_api.ts`、`src/data/repositories/private_zone_repository.ts` |
+| Private Zone 状态机 | `src/stores/private-zone` |
+| 页面、Gallery 与导航 | `src/app/private-zone` |
+| 角色 Provider | `src/providers/private-zone-route-provider.tsx` |
+
+修改上述实现时必须在同一变更中更新本文，不能再新增按相册列表、解锁或 Gallery 拆分的并行协议。
+
+## 2. 角色与路由边界
+
+标准路由：
+
+```text
+/characters/{characterSlug}/private-zone
+```
+
+旧地址保留为默认角色重定向，并保留查询参数：
+
+```text
+/private-zone -> /characters/elio/private-zone
+```
+
+URL 使用角色 `slug`，API 和 Actor 使用角色业务 `id`：
+
+| `id` | `slug` |
+| --- | --- |
+| `elio` | `elio` |
+| `maya-tan` | `maya` |
+| `nayeli-cervantes` | `nayeli` |
+
+角色必须同时存在于本地目录且 `capabilities.privateZone=true`。该能力由本地配置和角色目录响应的 `privateContent` 共同决定；能力关闭或 slug 未知时路由返回 Not Found。
+
+`PrivateZoneProvider` 以 `characterId` 为输入和 React key。切换角色会销毁旧 Actor 并创建空状态，不能复用上一角色的相册、余额或解锁请求。
+
+## 3. 相册列表
+
+```http
+GET <API_BASE_URL>/api/private-zone/albums?characterId=maya-tan&limit=20
+Authorization: Bearer <TOKEN>
+```
+
+| Query | 必填 | 前端规则 |
+| --- | --- | --- |
+| `characterId` | 是 | 当前角色业务 ID |
+| `limit` | 否 | 当前固定为 20 |
+
+前端当前只加载第一页，不实现 Private Zone 分页，也不把相册列表写入本地缓存。初始化、手动刷新或登录身份变化时重新请求网络。
+
+标准响应数据：
+
+```json
+{
+  "items": [
+    {
+      "albumId": "album-1",
+      "title": "A quiet afternoon",
+      "content": "I saved these for you.",
+      "previewText": "Unlock to view",
+      "imageCount": 3,
+      "images": [
+        {
+          "url": "https://example.com/private/cover.jpg",
+          "locked": true,
+          "index": 0
+        }
+      ],
+      "locked": true,
+      "unlocked": false,
+      "unlockCost": 40,
+      "publishedAt": "2026-07-20T09:00:00Z",
+      "lockDetail": {
+        "locked": true
+      }
+    }
+  ],
+  "creditBalance": 20
+}
+```
+
+前端将缺失或非法的可空字段按 Schema 默认值归一化。页面不直接读取原始响应 envelope。
+
+相册只要满足任意条件即视为锁定：
+
+```ts
+album.locked || !album.unlocked || album.lockDetail.locked
+```
+
+因此不能只根据图片 URL 是否存在判断已解锁。锁定相册允许存在封面 URL，但只能显示锁定预览，不能打开 Gallery。
+
+## 4. 解锁相册
+
+### 4.1 请求
+
+用户点击锁定相册后，前端先展示确认 Dialog。只有待确认 `albumId` 仍存在于当前 Actor 的 `items` 中，才会发起请求。
+
+```http
+POST <API_BASE_URL>/api/private-zone/albums/{albumId}/unlock
+Content-Type: application/json
+Authorization: Bearer <TOKEN>
+```
+
+```json
+{
+  "expectedCost": 40
+}
+```
+
+`albumId` 来自当前角色列表；请求 body 只发送用户确认时看到的 `expectedCost`，不重复发送 `characterId`。后端通过 `albumId` 确定相册与角色归属。
+
+### 4.2 响应
+
+```json
+{
+  "albumId": "album-1",
+  "locked": false,
+  "unlocked": true,
+  "reason": "ok",
+  "unlockCost": 40,
+  "requiredCredits": 40,
+  "creditBalance": 60,
+  "shortfallCredits": 0,
+  "images": [
+    {
+      "url": "https://example.com/private/photo-1.jpg",
+      "locked": false,
+      "index": 0
+    }
+  ]
+}
+```
+
+前端识别的标准 reason：
+
+```text
+ok
+already_unlocked
+insufficient_credits
+cost_changed
+unlock_in_progress
+deduct_failed
+persist_failed_refunded
+not_found
+```
+
+Schema 同时允许未知字符串，未知失败原因使用通用错误文案。
+
+### 4.3 状态机处理
+
+| 条件 | 行为 |
+| --- | --- |
+| `unlocked=true` 且 `locked=false` | 更新相册、余额和图片；增加成功 nonce；刷新用户权益 |
+| `reason=insufficient_credits` | 更新相册与余额，生成 Paywall 请求 |
+| `reason=cost_changed` | 清除确认状态、展示价格变化错误并重新加载列表 |
+| `reason=not_found` | 从当前列表移除相册并展示错误 |
+| 其他业务失败 | 使用响应补丁更新相册，并展示对应或通用错误 |
+| 请求异常 | 保留列表，清除进行中状态并展示异常信息 |
+
+响应补丁只替换匹配 `albumId` 的相册：
+
+- `locked`、`unlocked` 使用响应值；
+- 非零 `unlockCost` 更新当前价格，否则保留列表价格；
+- 非空 `images` 更新图片，否则保留列表图片；
+- `lockDetail.locked` 与响应 `locked` 对齐。
+
+解锁请求进行期间确认按钮保持禁用，避免同一个 Actor 重复提交。
+
+## 5. 身份与支付导航
+
+Private Zone 初始化会复用 Guest 登录引导。Auth 尚未初始化或正在加载时不请求列表；`notLoggedIn` 完成 Guest bootstrap 后再进入列表加载。Guest 和正式用户都可以读取后端允许的相册列表。
+
+积分不足生成 Paywall 请求后：
+
+| 当前身份 | 导航 |
+| --- | --- |
+| Guest 或 Not Logged In | 打开 Auth，redirect 为当前角色 Private Zone |
+| 已认证用户 | 打开 Top-up，`returnTo=private-zone`，保留当前角色来源 |
+
+Paywall 导航发起后立即消费当前请求，避免 React 重渲染重复导航。支付回跳和订单恢复遵循 [Payment 权威协议](./FRONTEND_PAYMENT_API.md)。
+
+解锁成功后 `unlockSuccessNonce` 递增，页面桥接到 `UserFetch`，刷新当前积分和权益。Private Zone 不自行修改 User Store 余额。
+
+## 6. Gallery URL 协议
+
+解锁相册使用查询参数打开页内 Gallery：
+
+```text
+/characters/{slug}/private-zone?album={albumId}&image={zeroBasedIndex}
+```
+
+解析规则：
+
+- `album` 必须是非空字符串；
+- `image` 必须是大于等于 0 的整数，缺失时使用 0；
+- 相册必须仍在当前角色列表中；
+- 相册必须已解锁；
+- 对应图片必须存在非空 URL。
+
+任一条件不满足时，页面通过 replace 删除 `album` 和 `image`，并保留其他查询参数。
+
+页面内点击九宫格缩略图时，Gallery 从该图片的后端数组原始索引打开。关闭操作优先使用浏览器 back；直接刷新或外部分享 Gallery URL 时，关闭操作使用 replace 返回当前角色 Private Zone。
+
+Gallery 只浏览 `locked=false` 且 URL 非空的图片，但 URL 中的 `image` 仍使用原始数组索引。横向拖动时图片跟随指针，达到视口宽度 18%（最低 56px），或达到 0.45px/ms 且至少移动 24px 时切换；首尾越界拖动使用 0.28 阻尼且不循环。松手后使用 240ms 横向吸附动画，键盘方向键和左右按钮复用相同切换逻辑。Escape 关闭；`prefers-reduced-motion` 下取消吸附过渡。
+
+## 7. UI 与数据边界
+
+- React key 使用稳定 `albumId`；
+- 卡片图片数量优先使用 `imageCount`，为 0 时回退到 `images.length`；
+- 锁定相册显示模糊封面、角色头像、锁标识、图片数量和 `View collection` 入口；卡片不展示视频数量或积分价格，解锁价格只在确认 Dialog 中展示；
+- 解锁相册过滤锁定或空 URL 图片，并保留剩余图片的原始数组索引；
+- 1 张图片显示 4:5 大图，2/4 张使用两列，其余使用三列正方形九宫格；
+- 超过 9 张时卡片显示前九张，末格显示 `+N`，Gallery 仍可浏览全部有效图片；
+- Gallery 只挂载当前图片和相邻图片，避免多图相册同时解码全部原图；
+- `creditBalance` 是当前列表/解锁响应快照，不替代 User Store 权益；
+- Private Zone 不使用 Chat 的 `conversationKey`、消息缓存或媒体缓存；
+- Private Zone 不持有 Payment Actor，Top-up 通过路由级导航进入独立 Payment Provider。
+
+## 8. 变更验收
+
+Private Zone 协议相关变更至少验证：
+
+1. `src/data/schemas/private-zone/__tests__`；
+2. `src/data/services/api/__tests__/multi_character_api.test.ts` 中的 Private Zone 请求；
+3. `src/stores/private-zone/__tests__`；
+4. `src/app/private-zone/__tests__` 与组件测试；
+5. Elio、Maya、Nayeli 列表互不串联；
+6. 登录身份变化会刷新当前角色列表；
+7. 成功、余额不足、价格变化、重复解锁、退款失败和 not found 分支；
+8. Auth、Top-up 和支付成功后返回原角色；
+9. 锁定相册不能通过 Gallery URL 绕过；
+10. 切换角色后旧 Actor 的相册与解锁状态不再可见。

docs/docker-image-ci.md

@@ -8,13 +8,13 @@
 
 | Workflow | 触发时机 | 职责 |
 | --- | --- | --- |
-| `.gitea/workflows/ci.yml` | `dev`、`main`、`test` push / PR | 安装依赖、执行完整质量检查、Python 后端 OpenAPI 差异检查、移动端 smoke，并校验 bundle 预算 |
+| `.gitea/workflows/ci.yml` | `dev`、`main`、`pre` push / PR | 安装依赖、执行完整质量检查、Python 后端 OpenAPI 差异检查、移动端 smoke，并校验 bundle 预算 |
-| `.gitea/workflows/docker-image.yml` | `main`、`test` push / 手动触发 | 构建 Docker 镜像、推送到镜像仓库，并通过 SSH 部署 |
+| `.gitea/workflows/docker-image.yml` | `main`、`pre` push / 手动触发 | 构建 Docker 镜像、推送到镜像仓库，并通过 SSH 部署 |
 
 这样可以避免所有开发分支都发布镜像，并确保生产镜像通过发布门禁。
 
-`main` 分支发布前会执行 Docker workflow 内的完整质量和 bundle 门禁。`test`
+`main` 分支发布前会执行 Docker workflow 内的完整质量和 bundle 门禁。`pre`
-分支为快速部署测试环境，会跳过完整质量检查，但仍必须通过 bundle 预算；独立的
+分支用于快速部署预发环境，会跳过完整质量检查，但仍必须通过 bundle 预算；独立的
 `ci.yml` 会同时执行完整检查并提供测试结果。
 
 ## 必需 Secrets
@@ -39,7 +39,7 @@ Next.js 的 `NEXT_PUBLIC_*` 会在构建期固化到产物中，因此测试环
 
 ## 镜像 Tag 规则
 
-`test` 分支发布：
+`pre` 分支发布时继续使用现有 `test-*` 运行镜像标签：
 
 ```bash
 REGISTRY_IMAGE:test-<short_sha>
@@ -81,7 +81,7 @@ volumes:
 
 ## 验证方式
 
-推送到 `test` 分支后，检查 Actions 日志中是否出现：
+推送到 `pre` 分支后，检查 Actions 日志中是否出现：
 
 ```text
 Build Docker image
@@ -124,4 +124,4 @@ gitea.banlv-ai.com/admin/cozsweet-web:prod-<short_sha>
 - `prod-*` 精确 tag 只保留最近 3 个，`prod-latest` 不计入也不删除。
 - 当前刚推送的 `IMAGE_VERSION_TAG` 永远不会被删除。
 
-SSH 部署成功后，服务器本机只保留当前环境正在运行的一个精确版本镜像；测试环境清理旧 `test-*`，生产环境清理旧 `prod-*`。
+SSH 部署成功后，服务器本机只保留当前环境正在运行的一个精确版本镜像；预发环境清理旧 `test-*`，生产环境清理旧 `prod-*`。

docs/external-entry/README.md

@@ -1,11 +1,11 @@
 # 外部入口接入说明
 
-外部应用通过 `/external-entry` 进入本应用。
+Facebook 等外部应用统一通过 `/external-entry` 进入本应用。入口先保存外部身份和短期业务意图，再跳转到对应角色页面并清理地址栏中的入口查询参数。
 
 | 环境 | APP HOST |
 | --- | --- |
-| 测试环境 | `frontend-test.banlv-ai.com` |
+| 预发环境 `pre` | `frontend-test.banlv-ai.com` |
-| 正式环境 | `cozsweet.com` |
+| 正式环境 `production` | `cozsweet.com` |
 
 入口格式：
 
@@ -13,80 +13,78 @@
 https://<APP_HOST>/external-entry?<参数>
 ```
 
-## 可选参数
+## 当前 Facebook 业务入口
 
-所有参数均为可选参数。
+当前正式投放固定为 4 类入口乘以 3 个角色，共 12 条链接。Facebook 业务名称与应用页面的对应关系如下：
+
+| Facebook 入口 | 参数组合 | 落地行为 |
+| --- | --- | --- |
+| 私密空间 | `target=chat` | 进入普通聊天页，不插入任何锁定内容。 |
+| 语音 | `target=chat&mode=promotion&promotion_type=voice` | 进入聊天页，并插入一条待解锁语音。 |
+| 图片包 | `target=private-zone` | 进入角色的 `private-zone` 图片空间。 |
+| 帮忙买咖啡 | `target=tip` | 进入角色的咖啡打赏页。 |
+
+每条正式链接还必须显式传入：
+
+- `character=elio`、`character=maya` 或 `character=nayeli`；
+- `psid=<PSID>`，其中 `<PSID>` 必须由 Facebook 发送端替换为当前用户经过 URL 编码的 Page-scoped User ID。
+
+完整的 12 条正式发送模板见 [Facebook 12 条外部入口链接清单](./links.md)。
+
+## 参数说明
 
 | 参数 | 可选值或格式 | 用途 |
 | --- | --- | --- |
-| `target` | `chat`、`tip`、`private-room` | 指定进入的页面；不传或值无效时进入聊天页。 |
+| `target` | `chat`、`tip`、`private-zone` | 指定进入的页面；不传或值无效时进入聊天页。 |
-| `character` | `elio`、`maya`、`nayeli` | 指定角色；不传或值无效时使用 Elio。 |
+| `character` | `elio`、`maya`、`nayeli` | 指定角色；不传或值无效时使用 Elio。正式投放链接必须显式传入。 |
-| `psid` | string | 传入 Facebook Page-scoped User ID。 |
+| `psid` | string | Facebook Page-scoped User ID。Facebook 正式投放链接必须动态传入。 |
 | `mode` | `promotion` | 开启聊天促销模式。 |
 | `promotion_type` | `voice`、`image`、`private` | 指定促销消息类型，仅与 `mode=promotion` 一起使用。 |
 
-`mode=promotion` 只有在 `target=chat` 且同时提供有效的 `promotion_type` 时生效。
+`mode=promotion` 只有在 `target=chat` 且同时提供有效的 `promotion_type` 时生效。当前 12 条正式投放链接只使用 `promotion_type=voice`；`image` 和 `private` 保留为兼容能力，不属于本次业务清单。
+
+## 四类发送模板
+
+发送前必须把 `<CHARACTER>` 替换为角色值，把 `<PSID>` 替换为当前 Facebook 用户的真实 PSID；不得把占位符原样发送给用户。
+
+私密空间（普通聊天）：
+
+```text
+https://<APP_HOST>/external-entry?target=chat&character=<CHARACTER>&psid=<PSID>
+```
+
+语音：
+
+```text
+https://<APP_HOST>/external-entry?target=chat&character=<CHARACTER>&mode=promotion&promotion_type=voice&psid=<PSID>
+```
+
+图片包：
+
+```text
+https://<APP_HOST>/external-entry?target=private-zone&character=<CHARACTER>&psid=<PSID>
+```
+
+帮忙买咖啡：
+
+```text
+https://<APP_HOST>/external-entry?target=tip&character=<CHARACTER>&psid=<PSID>
+```
 
 ## PSID 与登录状态流程
 
-PSID 保存、登录状态判断和 Facebook Identity 绑定逻辑见 [PSID 与登录状态流程图](./psid-login-flow.md)。
+`psid` 可以和任意有效入口参数组合使用。应用会先保存 PSID，再执行登录状态判断和 Facebook Identity 绑定。详细流程见 [PSID 与登录状态流程图](./psid-login-flow.md)。
 
-## 使用示例
+所有参数值都必须进行 URL 编码。入口中禁止传递登录 Token、Page Access Token、App Secret 或其他秘密。
 
-普通聊天：
+## 兼容说明
 
-```text
+- 历史参数 `target=private-room` 继续兼容进入 `private-zone`，但不得用于新投放链接。
-https://<APP_HOST>/external-entry?target=chat
+- `private_zone` 等其他拼写仍按无效目标处理并回退聊天页。
-```
+- `promotion_type=image` 和 `promotion_type=private` 继续由现有代码支持，但不计入当前 12 条 Facebook 业务链接。
+- 无效或缺失的 `character` 继续回退 Elio；正式投放模板始终显式传入角色，不能依赖回退。
 
-进入 Maya 聊天：
+## 调试与正式清单
 
-```text
+- [本地调试链接清单](./debug-links.md)
-https://<APP_HOST>/external-entry?target=chat&character=maya
+- [Facebook 12 条外部入口链接清单](./links.md)
-```
-
-携带 PSID 进入聊天，示例 PSID 为 `27511427698460020`：
-
-```text
-https://<APP_HOST>/external-entry?target=chat&psid=27511427698460020
-```
-
-语音促销聊天：
-
-```text
-https://<APP_HOST>/external-entry?target=chat&mode=promotion&promotion_type=voice
-```
-
-图片促销聊天：
-
-```text
-https://<APP_HOST>/external-entry?target=chat&mode=promotion&promotion_type=image
-```
-
-私密文本促销聊天：
-
-```text
-https://<APP_HOST>/external-entry?target=chat&mode=promotion&promotion_type=private
-```
-
-咖啡打赏：
-
-```text
-https://<APP_HOST>/external-entry?target=tip
-```
-
-私密空间：
-
-```text
-https://<APP_HOST>/external-entry?target=private-room
-```
-
-进入 Nayeli 私密空间：
-
-```text
-https://<APP_HOST>/external-entry?target=private-room&character=nayeli
-```
-
-`psid` 可以与任意 `target` 或聊天促销参数组合使用。参数值需要进行 URL 编码，不要在入口中传递登录 Token、Page Access Token 或 App Secret。
-
-测试环境和正式环境的完整可点击示例见 [外部入口链接清单](./links.md)。

docs/external-entry/debug-links.md

@@ -0,0 +1,47 @@
+# 外部入口本地调试链接清单
+
+[返回外部入口接入说明](./README.md)
+
+启动本地应用后，可以直接点击以下链接进行调试。根网址为 `http://localhost:3000`，PSID 示例统一使用 `27511427698460020`。
+
+## 默认入口
+
+| 入口 | 链接 |
+| --- | --- |
+| 默认入口（Elio 聊天） | [打开默认入口](http://localhost:3000/external-entry) |
+| 普通聊天 | [打开普通聊天](http://localhost:3000/external-entry?target=chat) |
+| 携带 PSID 的聊天 | [打开 PSID 聊天示例](http://localhost:3000/external-entry?target=chat&psid=27511427698460020) |
+
+## 角色聊天
+
+| 角色 | 链接 |
+| --- | --- |
+| Elio | [打开 Elio 聊天](http://localhost:3000/external-entry?target=chat&character=elio) |
+| Maya | [打开 Maya 聊天](http://localhost:3000/external-entry?target=chat&character=maya) |
+| Nayeli | [打开 Nayeli 聊天](http://localhost:3000/external-entry?target=chat&character=nayeli) |
+
+## 聊天促销
+
+| 促销类型 | 链接 |
+| --- | --- |
+| 语音促销 | [打开语音促销](http://localhost:3000/external-entry?target=chat&mode=promotion&promotion_type=voice) |
+| 图片促销 | [打开图片促销](http://localhost:3000/external-entry?target=chat&mode=promotion&promotion_type=image) |
+| 私密文本促销 | [打开私密文本促销](http://localhost:3000/external-entry?target=chat&mode=promotion&promotion_type=private) |
+
+## 咖啡打赏
+
+| 角色 | 链接 |
+| --- | --- |
+| Elio | [打开 Elio 咖啡打赏](http://localhost:3000/external-entry?target=tip&character=elio) |
+| Maya | [打开 Maya 咖啡打赏](http://localhost:3000/external-entry?target=tip&character=maya) |
+| Nayeli | [打开 Nayeli 咖啡打赏](http://localhost:3000/external-entry?target=tip&character=nayeli) |
+
+## 私密空间
+
+| 角色 | 链接 |
+| --- | --- |
+| Elio | [打开 Elio 私密空间](http://localhost:3000/external-entry?target=private-zone&character=elio) |
+| Maya | [打开 Maya 私密空间](http://localhost:3000/external-entry?target=private-zone&character=maya) |
+| Nayeli | [打开 Nayeli 私密空间](http://localhost:3000/external-entry?target=private-zone&character=nayeli) |
+
+如需为其他入口携带 PSID，在链接末尾追加 `&psid=27511427698460020`。对于不带查询参数的默认入口，请改为追加 `?psid=27511427698460020`。

docs/external-entry/links.md

@@ -1,43 +1,52 @@
-# 外部入口链接清单
+# Facebook 12 条外部入口链接清单
 
-[返回外部入口接入说明](./README.md)
+本清单是 Facebook 正式投放的唯一业务链接清单，共 4 类入口乘以 3 个角色，合计 12 条模板。
 
-以下链接可以直接点击打开。PSID 示例统一使用 `27511427698460020`。
+## 发送规则
 
-## 测试环境
+- 发送前必须把每条模板中的 `<PSID>` 替换为当前用户经过 URL 编码的 Facebook Page-scoped User ID；不得把占位符原样发送。
+- 每条链接都显式传入 `character`，不得依赖缺省角色回退。
+- Facebook 业务名称“私密空间”进入普通聊天页；业务名称“图片包”才进入应用的 `private-zone`。
+- 不要在入口中传递登录 Token、Page Access Token、App Secret 或其他秘密。
+- 以下模板包含占位符，替换真实 PSID 后才能直接发送或点击。
 
-| 入口 | 链接 |
+## 正式投放模板
-| --- | --- |
-| 普通聊天 | [打开普通聊天](https://frontend-test.banlv-ai.com/external-entry?target=chat) |
-| Maya 聊天 | [打开 Maya 聊天](https://frontend-test.banlv-ai.com/external-entry?target=chat&character=maya) |
-| Nayeli 聊天 | [打开 Nayeli 聊天](https://frontend-test.banlv-ai.com/external-entry?target=chat&character=nayeli) |
-| 携带 PSID 的聊天 | [打开 PSID 聊天示例](https://frontend-test.banlv-ai.com/external-entry?target=chat&psid=27511427698460020) |
-| 语音促销 | [打开语音促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=voice) |
-| 图片促销 | [打开图片促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=image) |
-| 私密文本促销 | [打开私密文本促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=private) |
-| 咖啡打赏 | [打开咖啡打赏](https://frontend-test.banlv-ai.com/external-entry?target=tip) |
-| Maya 咖啡打赏 | [打开 Maya 咖啡打赏](https://frontend-test.banlv-ai.com/external-entry?target=tip&character=maya) |
-| Nayeli 咖啡打赏 | [打开 Nayeli 咖啡打赏](https://frontend-test.banlv-ai.com/external-entry?target=tip&character=nayeli) |
-| 私密空间 | [打开私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-room) |
-| Maya 私密空间 | [打开 Maya 私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-room&character=maya) |
-| Nayeli 私密空间 | [打开 Nayeli 私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-room&character=nayeli) |
 
-## 正式环境
+| 编号 | Facebook 入口 | 角色 | 发送模板 | 预期落地与页面状态 |
+| --- | --- | --- | --- | --- |
+| 1 | 私密空间 | Elio | `https://cozsweet.com/external-entry?target=chat&character=elio&psid=<PSID>` | `/characters/elio/chat`，不显示促销锁卡 |
+| 2 | 私密空间 | Maya | `https://cozsweet.com/external-entry?target=chat&character=maya&psid=<PSID>` | `/characters/maya/chat`，不显示促销锁卡 |
+| 3 | 私密空间 | Nayeli | `https://cozsweet.com/external-entry?target=chat&character=nayeli&psid=<PSID>` | `/characters/nayeli/chat`，不显示促销锁卡 |
+| 4 | 语音 | Elio | `https://cozsweet.com/external-entry?target=chat&character=elio&mode=promotion&promotion_type=voice&psid=<PSID>` | `/characters/elio/chat`，显示一条锁定语音 |
+| 5 | 语音 | Maya | `https://cozsweet.com/external-entry?target=chat&character=maya&mode=promotion&promotion_type=voice&psid=<PSID>` | `/characters/maya/chat`，显示一条锁定语音 |
+| 6 | 语音 | Nayeli | `https://cozsweet.com/external-entry?target=chat&character=nayeli&mode=promotion&promotion_type=voice&psid=<PSID>` | `/characters/nayeli/chat`，显示一条锁定语音 |
+| 7 | 图片包 | Elio | `https://cozsweet.com/external-entry?target=private-zone&character=elio&psid=<PSID>` | `/characters/elio/private-zone` |
+| 8 | 图片包 | Maya | `https://cozsweet.com/external-entry?target=private-zone&character=maya&psid=<PSID>` | `/characters/maya/private-zone` |
+| 9 | 图片包 | Nayeli | `https://cozsweet.com/external-entry?target=private-zone&character=nayeli&psid=<PSID>` | `/characters/nayeli/private-zone` |
+| 10 | 帮忙买咖啡 | Elio | `https://cozsweet.com/external-entry?target=tip&character=elio&psid=<PSID>` | `/characters/elio/tip` |
+| 11 | 帮忙买咖啡 | Maya | `https://cozsweet.com/external-entry?target=tip&character=maya&psid=<PSID>` | `/characters/maya/tip` |
+| 12 | 帮忙买咖啡 | Nayeli | `https://cozsweet.com/external-entry?target=tip&character=nayeli&psid=<PSID>` | `/characters/nayeli/tip` |
 
-| 入口 | 链接 |
+## 预发验证
-| --- | --- |
-| 普通聊天 | [打开普通聊天](https://cozsweet.com/external-entry?target=chat) |
-| Maya 聊天 | [打开 Maya 聊天](https://cozsweet.com/external-entry?target=chat&character=maya) |
-| Nayeli 聊天 | [打开 Nayeli 聊天](https://cozsweet.com/external-entry?target=chat&character=nayeli) |
-| 携带 PSID 的聊天 | [打开 PSID 聊天示例](https://cozsweet.com/external-entry?target=chat&psid=27511427698460020) |
-| 语音促销 | [打开语音促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=voice) |
-| 图片促销 | [打开图片促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=image) |
-| 私密文本促销 | [打开私密文本促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=private) |
-| 咖啡打赏 | [打开咖啡打赏](https://cozsweet.com/external-entry?target=tip) |
-| Maya 咖啡打赏 | [打开 Maya 咖啡打赏](https://cozsweet.com/external-entry?target=tip&character=maya) |
-| Nayeli 咖啡打赏 | [打开 Nayeli 咖啡打赏](https://cozsweet.com/external-entry?target=tip&character=nayeli) |
-| 私密空间 | [打开私密空间](https://cozsweet.com/external-entry?target=private-room) |
-| Maya 私密空间 | [打开 Maya 私密空间](https://cozsweet.com/external-entry?target=private-room&character=maya) |
-| Nayeli 私密空间 | [打开 Nayeli 私密空间](https://cozsweet.com/external-entry?target=private-room&character=nayeli) |
 
-如需在其他入口携带 PSID，在链接末尾追加 `&psid=27511427698460020`。
+预发验证不维护第二套业务清单。将上述 12 条模板的主机统一替换为 `frontend-test.banlv-ai.com`，其余路径和参数保持不变：
+
+```text
+https://frontend-test.banlv-ai.com/external-entry?<与正式模板相同的查询参数>
+```
+
+预发环境是 `pre`，不是正式环境。预发验证通过不代表已经更新 `cozsweet.com` 或获得生产发布批准。
+
+## 验收判断
+
+- 最终浏览器地址必须是表格中的预期页面，且不再保留 `/external-entry` 的查询参数。
+- `<PSID>` 替换后的真实值必须由应用保存。
+- “私密空间”只进入普通聊天，不得出现锁定语音、锁定图片或私密文本促销卡。
+- “语音”进入聊天后必须只注入一条锁定语音。
+- “图片包”和“帮忙买咖啡”必须分别进入对应角色的 `private-zone` 与 `tip`，不能串到其他角色。
+
+## 不属于当前 12 条清单的兼容能力
+
+- 历史 `target=private-room` 继续兼容，但不得创建新的投放链接。
+- `promotion_type=image`、`promotion_type=private` 和独立 PSID 示例不属于当前正式业务清单。
+- 兼容能力的保留不改变本页“只有 12 条正式投放模板”的口径。

docs/frontend-integration/2026-07-22-private-zone-rename.md

@@ -0,0 +1,188 @@
+# Private Zone 全链路改名联调说明
+
+- 日期：2026-07-22
+- 目标环境：本地、`pre`、生产
+- 当前状态：已验证
+
+## 1. 目标
+
+原功能名称存在拼写错误。本次将前端、unified 后端、Manager、数据库、埋点和文档中的正式命名统一为 `Private Zone`，并同步切换页面路由、API 路径和公开枚举值。
+
+## 2. 环境地址
+
+| 环境 | 前端 | API Base URL |
+| --- | --- | --- |
+| `pre` | `https://frontend-test.banlv-ai.com` | `https://proapi.banlv-ai.com` |
+| 生产 | `https://cozsweet.com` | `https://api.banlv-ai.com` |
+
+## 3. 前端影响
+
+前端已完成以下修改：
+
+- 页面路由统一为 `/private-zone` 和 `/characters/{characterSlug}/private-zone`。
+- 外部入口参数统一为 `target=private-zone`。
+- 支付回跳参数统一为 `returnTo=private-zone`。
+- 类型、Repository、API client、XState actor、Provider 和资源目录统一使用 `privateZone`、`PrivateZone`、`private-zone` 或 `private_zone`。
+- 埋点键统一为 `navigation.private_zone`、`chat.open_private_zone_from_avatar` 等新名称。
+- 角色能力字段统一为 `capabilities.privateZone`。
+
+旧页面和旧查询参数不再作为正式入口保留。发布时必须让前后端属于同一个发布批次。
+
+## 4. API 变更清单
+
+所有接口都使用 `Authorization: Bearer <TOKEN>`，响应继续使用现有统一 envelope。请求与响应中未列出的业务字段保持原类型和含义。
+
+| 方法 | 新路径 | 用途 |
+| --- | --- | --- |
+| `GET` | `/api/private-zone/albums` | 查询付费图片包 |
+| `POST` | `/api/private-zone/albums/{albumId}/unlock` | 解锁图片包 |
+| `GET` | `/api/private-zone/moments` | 查询朋友圈式内容 |
+| `POST` | `/api/private-zone/moments/{momentId}/unlock` | 解锁单条内容 |
+| `GET` | `/api/private-zone/config` | 查询当前角色和用户解锁配置 |
+| `GET` | `/api/private-zone/diaries` | 查询关系日记 |
+| `POST` | `/api/private-zone/diaries/{diaryId}/seen` | 标记关系日记已读 |
+| `POST` | `/api/private-zone/diaries/{diaryId}/unlock` | 解锁关系日记 |
+
+### 4.1 图片包列表
+
+```http
+GET /api/private-zone/albums?characterId=elio&limit=20
+Authorization: Bearer <TOKEN>
+```
+
+| 字段 | 位置 | 类型 | 必填 | 可为 `null` | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `characterId` | query | string | 是 | 否 | 角色 ID |
+| `limit` | query | integer | 否 | 否 | `1-50`，默认 `20` |
+| `cursor` | query | string | 否 | 是 | 分页游标 |
+
+调用示例：
+
+```bash
+curl 'https://proapi.banlv-ai.com/api/private-zone/albums?characterId=elio&limit=20' \
+  -H 'Authorization: Bearer <TOKEN>'
+```
+
+### 4.2 解锁图片包
+
+```http
+POST /api/private-zone/albums/{albumId}/unlock
+Authorization: Bearer <TOKEN>
+Content-Type: application/json
+```
+
+| 字段 | 位置 | 类型 | 必填 | 可为 `null` | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `albumId` | path | string | 是 | 否 | 图片包 ID |
+| `expectedCost` | body | integer | 否 | 是 | 前端确认价格；与后端价格不一致时拒绝解锁 |
+
+```bash
+curl -X POST 'https://proapi.banlv-ai.com/api/private-zone/albums/<ALBUM_ID>/unlock' \
+  -H 'Authorization: Bearer <TOKEN>' \
+  -H 'Content-Type: application/json' \
+  -d '{"expectedCost":320}'
+```
+
+### 4.3 Moments 内容与解锁
+
+```http
+GET /api/private-zone/moments?characterId=elio&limit=20
+POST /api/private-zone/moments/{momentId}/unlock
+```
+
+解锁请求体与图片包一致，`expectedCost` 为可选整数。响应中的正式分类值同步改为：
+
+```json
+{
+  "lockDetail": {
+    "type": "private_zone_moment",
+    "reason": "private_zone_moment"
+  }
+}
+```
+
+## 5. 其他公开值
+
+| 使用位置 | 新值 | 类型 |
+| --- | --- | --- |
+| `/api/chat/unlock-private` 的 `lockType` 别名 | `private_zone` | string enum |
+| 日程导入 `contentType` 别名 | `private_zone` | string enum，归一化为 `paid_content` |
+| 外部入口 `target` | `private-zone` | string enum |
+| 支付回跳 `returnTo` | `private-zone` | string enum |
+| 锁定详情分类 | `private_zone_moment` | string enum |
+
+## 6. 数据库迁移
+
+因为 `pre` 与生产当前共用 `https://dbapi.banlv-ai.com`，预发部署前先执行 unified 仓库中的临时桥接脚本：
+
+```text
+database/private-zone-bridge.sql
+```
+
+桥接脚本会创建新表并在切换窗口内保持新旧解锁写入双向同步。生产前后端全部切换完成后，再执行最终迁移：
+
+```text
+database/private-zone-migration.sql
+```
+
+迁移会在同一事务中完成：
+
+- 将历史解锁表无损重命名；新旧表同时存在时先合并再删除旧表。
+- 重命名关联约束、索引、策略和触发器。
+- 合并 `users.preferences` 中历史解锁键，防止已解锁内容重新锁定。
+- 把 `credit_ledger` 历史分类迁移到 `private_zone` 和 `private_zone_moment`。
+- 定向迁移历史埋点键、页面 URL 和系统媒体路径，不改写用户聊天正文。
+- 删除切换窗口使用的双写触发器和函数。
+- 支持重复执行。
+
+## 7. 兼容性与发布顺序
+
+这是破坏性命名修正，不保留旧 API、旧页面路由或旧公开枚举作为正式兼容层。必须按以下顺序发布：
+
+1. 备份数据库并记录当前 unified、前端和 Manager 版本。
+2. 执行 `database/private-zone-bridge.sql`，确认新旧表双向写入一致。
+3. 部署 unified `pre`，验证所有 `/api/private-zone/*` 接口。
+4. 部署前端 `pre`，验证页面、外部入口、解锁和支付回跳。
+5. Manager 更新后验证积分用途显示为新分类。
+6. `pre` 验证通过后，先启动新生产后端并临时配置旧 API 到新 API 的 Nginx 转发。
+7. 切换生产后端，再部署同批次生产前端；确认新前端只调用 `/api/private-zone/*`。
+8. 删除临时 Nginx 转发，执行 `database/private-zone-migration.sql` 清理旧数据库对象。
+
+## 8. 错误与界面状态
+
+- `401`：Token 缺失或无效，前端进入现有登录恢复流程。
+- `403`：游客访问仅注册用户可用的关系日记操作，展示现有注册引导。
+- `404`：角色、图片包、内容或日记不存在，展示现有空状态或失效提示。
+- `409`：`expectedCost` 与后端价格不同，刷新列表后重新确认。
+- `402` 或业务余额不足错误：进入现有充值流程，并使用 `returnTo=private-zone` 返回原角色页面。
+- 网络失败：不修改本地解锁状态，保留重试入口。
+
+## 9. 验收用例
+
+1. `/characters/elio/private-zone`、Maya 和 Nayeli 对应页面均可打开。
+2. `GET /api/private-zone/albums` 返回当前角色内容，角色之间不混用。
+3. 已解锁历史记录在迁移后保持解锁状态，不重复扣积分。
+4. 新解锁成功后刷新页面仍为已解锁状态。
+5. 积分不足进入充值页后，回跳到原角色 `/private-zone` 页面。
+6. `target=private-zone&character=nayeli` 进入 Nayeli 对应页面。
+7. Manager 的积分用途不再出现旧分类。
+8. 三个仓库执行旧命名残留扫描，结果为 `0`。
+
+## 10. 当前测试证据
+
+- unified：`316 passed`。
+- 前端：TypeScript 类型检查通过；Vitest `639 passed`；ESLint 通过；契约测试 `4 passed`；生产构建通过并生成三个角色的 `/private-zone` 页面。
+- Manager：`75 passed`。
+- PostgreSQL 16 临时库：升级、重复升级、回滚和再次升级全部通过；历史解锁、偏好键、积分账本、埋点、媒体路径和数据库对象名均通过断言，临时容器已删除。
+- `pre`：unified `71da49b` 和前端 `35939e7` 已验证；新 API 已注册 `8` 条 `/api/private-zone/*` 路径，旧 API 路径数量为 `0`；新页面返回 `200`，旧页面返回 `404`。
+- 生产：unified 镜像 `ai-boyfriend-unified:prod-20260722-71da49b`（镜像 ID `sha256:755ef5741856d83d7d808e7df8ee259b6fa5fb94fe333b523ee280ed1d5f674b`）和前端镜像 `prod-35939e7` 已健康运行；Manager 当前版本为 `6eea005`。
+- 生产接口：测试账号调用 `GET https://api.banlv-ai.com/api/private-zone/config?characterId=elio` 返回 `200`，`success=true`；旧版 API 路径在所有公开 API 入口均返回 `404`。
+- 生产数据库：最终迁移已执行，旧表、桥接函数、桥接触发器、旧偏好键、旧积分分类和旧埋点值的残留数量均为 `0`。
+
+## 11. 回滚影响
+
+最终迁移执行前可直接恢复旧应用，桥接表会保留双向一致的数据。最终迁移执行后，回滚必须同时执行 unified 仓库中的 `database/private-zone-rollback.sql`。回滚前应停止写入，先保存切换后的新增解锁记录，再执行逆向迁移并恢复旧应用版本。不得只恢复前端或只恢复 unified。
+
+## 12. 待确认事项
+
+- 无。

docs/gitea-actions-ssh-deploy.md

@@ -3,7 +3,7 @@
 当前推荐部署链路：
 
 ```text
-push test/main
+push pre/main
 → Gitea Actions 构建并推送 Docker 镜像
 → Actions 通过 SSH 登录目标服务器
 → 目标服务器 docker pull 指定镜像 tag
@@ -16,7 +16,7 @@ push test/main
 
 | 分支 | 环境 | 镜像 tag | 宿主机端口 | 默认服务器目录 | 容器名 |
 | --- | --- | --- | --- | --- | --- |
-| `test` | 测试环境 | `test-<short_sha>` | `9135` | `/opt/cozsweet-web-test` | `cozsweet-web-test` |
+| `pre` | 预发环境 | `test-<short_sha>` | `9135` | `/opt/cozsweet-web-test` | `cozsweet-web-test` |
 | `main` | 生产环境 | `prod-<short_sha>` | `9185` | `/opt/cozsweet-web-prod` | `cozsweet-web-prod` |
 
 ## Gitea Secrets
@@ -75,14 +75,14 @@ prod-<short_sha> 最近 3 个
 
 `test-latest` / `prod-latest` 不计入保留数量，也不会主动删除。
 
-部署脚本会在 `docker compose up` 成功后清理服务器本机旧镜像，只保留当前环境正在运行的一个精确版本镜像：测试环境保留当前 `test-<short_sha>`，生产环境保留当前 `prod-<short_sha>`。
+部署脚本会在 `docker compose up` 成功后清理服务器本机旧镜像，只保留当前环境正在运行的一个精确版本镜像：预发环境保留当前 `test-<short_sha>`，生产环境保留当前 `prod-<short_sha>`。
 
 ## 本地发布入口
 
 本地发布脚本现在只负责推送 Gitea 分支，触发 Actions：
 
 ```bash
-# 测试环境
+# 预发环境
 ./scripts/release/pre_release_web.sh
 
 # 生产环境
@@ -92,16 +92,16 @@ prod-<short_sha> 最近 3 个
 也可以直接推送：
 
 ```bash
-git push gitea test
+git push gitea pre
 git push --force gitea main
 ```
 
 ## 验证
 
-测试环境：
+预发环境：
 
 ```bash
-ssh <user>@<test-host>
+ssh <user>@<pre-host>
 cd /opt/cozsweet-web-test
 docker compose ps
 curl -I http://127.0.0.1:9135/

e2e/README.md

@@ -27,8 +27,8 @@ pnpm exec playwright install chromium
 For local development on macOS, `pnpm test:e2e:chrome` can reuse the installed Google Chrome.
 
 `pnpm test:e2e:mobile-smoke` runs the critical authentication, logout, token
-refresh and paid-image unlock paths with the Pixel 7 profile. CI runs this tier
+refresh and paid-image unlock paths with the Pixel 7 profile. CI 在所有 pull
-on every pull request and `dev` / `test` / `main` push.
+request 以及 `dev` / `pre` / `main` push 时运行这一层测试。
 
 ## Environment overrides
 
@@ -40,6 +40,6 @@ pnpm test:e2e:real
 
 ```bash
 PLAYWRIGHT_BASE_URL=https://cozsweet.com \
-E2E_API_BASE_URL=https://proapi.banlv-ai.com \
+E2E_API_BASE_URL=https://api.banlv-ai.com \
 pnpm test:e2e:prod
 ```

e2e/fixtures/api-mocks.ts

@@ -12,7 +12,7 @@ export interface MockCoreApisOptions {
   paidImageFlow?: boolean;
   paidImageInsufficientCreditsFlow?: boolean;
   paidVoiceInsufficientCreditsFlow?: boolean;
-  psidLoginFlow?: boolean;
+  topUpHandoffFlow?: boolean;
 }
 
 export async function mockCoreApis(page: Page, options: MockCoreApisOptions = {}) {
@@ -22,14 +22,14 @@ export async function mockCoreApis(page: Page, options: MockCoreApisOptions = {}
     paidImageFlow: options.paidImageFlow ?? false,
     paidImageInsufficientCreditsFlow: options.paidImageInsufficientCreditsFlow ?? false,
     paidVoiceInsufficientCreditsFlow: options.paidVoiceInsufficientCreditsFlow ?? false,
-    psidLoginFlow: options.psidLoginFlow ?? false,
+    topUpHandoffFlow: options.topUpHandoffFlow ?? false,
   };
   const chatState = { hasExpiredChatSend: false, paidImageRequested: false, paidImageUnlocked: false };
 
   await registerAuthMocks(page, {
     chatSendTokenRefreshFlow: chatOptions.chatSendTokenRefreshFlow,
     isChatSendTokenExpired: () => chatState.hasExpiredChatSend,
-    psidLoginFlow: chatOptions.psidLoginFlow,
+    topUpHandoffFlow: chatOptions.topUpHandoffFlow,
   });
   await registerCharacterMocks(page);
   await registerUserMocks(page);

e2e/fixtures/api/auth.ts

@@ -1,22 +1,21 @@
 import type { Page } from "@playwright/test";
 
 import { apiEnvelope } from "../data/common";
-import { emailLoginResponse, guestLoginResponse, psidLoginResponse, refreshedEmailLoginResponse, refreshedGuestLoginResponse } from "../data/auth";
+import { emailLoginResponse, guestLoginResponse, refreshedEmailLoginResponse, refreshedGuestLoginResponse, topUpHandoffResponse } from "../data/auth";
 
 export interface AuthMockState {
   chatSendTokenRefreshFlow: boolean;
   isChatSendTokenExpired: () => boolean;
-  psidLoginFlow: boolean;
+  topUpHandoffFlow: boolean;
 }
 
 export async function registerAuthMocks(page: Page, state: AuthMockState) {
-  await page.route("**/api/auth/login/facebook/psid", async (route) => {
+  await page.route("**/api/auth/handoff/topup/consume", async (route) => {
-    if (!state.psidLoginFlow) {
+    if (!state.topUpHandoffFlow) {
       await route.continue();
       return;
     }
-
+    await route.fulfill({ json: apiEnvelope(topUpHandoffResponse) });
-    await route.fulfill({ json: apiEnvelope(psidLoginResponse) });
   });
 
   await page.route("**/api/auth/guest", async (route) => {

e2e/fixtures/api/character.ts

@@ -4,7 +4,7 @@ import { apiEnvelope } from "../data/common";
 import { chatCharactersResponse } from "../data/character";
 
 export async function registerCharacterMocks(page: Page) {
-  await page.route("**/api/characters**", async (route) => {
+  await page.route(/\/api\/characters(?:\?.*)?$/, async (route) => {
     await route.fulfill({ json: apiEnvelope(chatCharactersResponse) });
   });
 }

e2e/fixtures/api/chat.ts

@@ -20,6 +20,23 @@ export interface ChatMockState {
 export async function registerChatMocks(page: Page, options: ChatMockOptions, state: ChatMockState) {
   let sendCount = 0;
 
+  await page.route("**/api/chat/opening-message", async (route) => {
+    const body = route.request().postDataJSON() as {
+      openingMessage?: unknown;
+    } | undefined;
+    await route.fulfill({
+      json: apiEnvelope({
+        messageId: "mock-opening-message",
+        created: true,
+        openingMessage:
+          typeof body?.openingMessage === "string"
+            ? body.openingMessage
+            : "Hello",
+        createdAt: "2026-07-23T00:00:00Z",
+      }),
+    });
+  });
+
   await page.route("**/api/chat/history**", async (route) => {
     const response = options.paidVoiceInsufficientCreditsFlow
       ? paidVoiceHistoryResponse
@@ -44,7 +61,35 @@ export async function registerChatMocks(page: Page, options: ChatMockOptions, st
       await route.fulfill({ status: 401, json: { message: "expired" } });
       return;
     }
-    const response = options.paidImageFlow && message.includes("给我发图片")
+    const response = message.includes("discount offer test")
+      ? {
+          ...chatSendResponse,
+          reply: "I know you're thinking carefully about the price.",
+          messageId: "discount-action-message",
+          commercialAction: {
+            actionId: "13ec8a10-58d7-4d24-b66b-8db5699a1aa8",
+            type: "discountOffer",
+            copy: "Want me to ask for my best private offer?",
+            ctaLabel: "Yes, ask for me",
+            target: "discountConsent",
+            ruleId: "discount_after_price_objection",
+          },
+        }
+      : message.includes("private album offer test")
+      ? {
+          ...chatSendResponse,
+          reply: "You always know how to make me smile.",
+          messageId: "commercial-action-message",
+          commercialAction: {
+            actionId: "commercial-action-1",
+            type: "privateAlbumOffer",
+            copy: "There are more private photos waiting for you.",
+            ctaLabel: "Open private zone",
+            target: "privateZone",
+            ruleId: "private_album_after_appearance_praise",
+          },
+        }
+      : options.paidImageFlow && message.includes("给我发图片")
       ? paidImageChatSendResponse
       : options.chatLimitTriggerAt != null && sendCount >= options.chatLimitTriggerAt
         ? createWeeklyLimitChatSendResponse(sendCount, options.chatLimitTriggerAt)

e2e/fixtures/api/payment.ts

@@ -4,6 +4,16 @@ import { apiEnvelope } from "../data/common";
 import { createPaymentOrderResponse, paidPaymentOrderStatusResponse, paymentPlansResponse, tipPaymentPlansResponse, vipStatusResponse } from "../data/payment";
 
 export async function registerPaymentMocks(page: Page) {
+  await page.route("**/api/payment/commercial-offers/*/accept", async (route) => route.fulfill({ json: apiEnvelope({
+    commercialOfferId: "13ec8a10-58d7-4d24-b66b-8db5699a1aa8",
+    planId: "vip_annual",
+    subscriptionType: "vip",
+    discountPercent: 30,
+    pricePercent: 70,
+    expiresAt: "2026-07-24T08:00:00+00:00",
+    message: "I got it for you.",
+    promotionType: "commercial_seven_discount",
+  }) }));
   await page.route("**/api/payment/plans**", async (route) => route.fulfill({ json: apiEnvelope(paymentPlansResponse) }));
   await page.route("**/api/payment/tip-plans**", async (route) => route.fulfill({ json: apiEnvelope(tipPaymentPlansResponse) }));
   await page.route("**/api/payment/create-order", async (route) => route.fulfill({ json: apiEnvelope(createPaymentOrderResponse) }));

e2e/fixtures/data/auth.ts

@@ -50,14 +50,16 @@ export const refreshedEmailLoginResponse = {
   refreshToken: "e2e-refreshed-email-refresh-token",
 };
 
-export const psidLoginResponse = {
+export const topUpHandoffResponse = {
-  token: "e2e-psid-guest-token",
+  token: "e2e-messenger-token",
-  refreshToken: "",
+  refreshToken: "e2e-messenger-refresh-token",
-  matchedBy: "psid",
+  loginStatus: "facebookMessenger",
-  fbAsid: "",
+  merged: false,
-  fbPsid: "e2e-facebook-psid",
+  user: {
-  hasCompleteFacebookIdentity: false,
+    ...e2eEmailUser,
-  isGuest: true,
+    id: "user_e2e_messenger",
-  user: e2eUser,
+    username: "E2E Messenger User",
-  userId: e2eUser.id,
+    email: "messenger_hash@messenger.cozsweet.invalid",
+    loginProvider: "facebook_messenger",
+  },
 };

e2e/fixtures/data/chat.ts

@@ -66,6 +66,7 @@ export function createWeeklyLimitChatSendResponse(
 }
 
 export const paidImageMessageId = "msg_photo_paywall_001";
+export const paidImageDisplayMessageId = `server:${paidImageMessageId}:assistant`;
 export const paidImageUrl =
   "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII=";
 export const paidImageChatSendResponse = {
@@ -74,13 +75,13 @@ export const paidImageChatSendResponse = {
   messageId: paidImageMessageId,
   isGuest: true,
   timestamp: 1_782_180_725_000,
-  image: { type: "elio_schedule", url: paidImageUrl },
+  image: { type: "elio_schedule", url: null },
   lockDetail: { locked: true, showContent: true, showUpgrade: true, reason: "image", hint: "Activate VIP to unlock the full photo.", detail: null },
 };
 
 export function createPaidImageHistoryResponse(unlocked: boolean) {
   return {
-    messages: [{ role: "assistant", type: "image", content: unlocked ? "" : paidImageChatSendResponse.reply, id: paidImageMessageId, created_at: "2026-06-30T00:00:00.000Z", audioUrl: null, image: { type: "elio_schedule", url: paidImageUrl }, lockDetail: unlocked ? { locked: false, showContent: true, showUpgrade: false, reason: null, hint: null, detail: null } : paidImageChatSendResponse.lockDetail }],
+    messages: [{ role: "assistant", type: "image", content: unlocked ? "" : paidImageChatSendResponse.reply, id: paidImageMessageId, created_at: "2026-06-30T00:00:00.000Z", audioUrl: null, image: { type: "elio_schedule", url: unlocked ? paidImageUrl : null }, lockDetail: unlocked ? { locked: false, showContent: true, showUpgrade: false, reason: null, hint: null, detail: null } : paidImageChatSendResponse.lockDetail }],
     total: 1, limit: 50, offset: 0, isVip: unlocked, privateFreeLimit: 0, privateUsedToday: 0, privateCanViewFree: false,
   };
 }

e2e/fixtures/data/payment.ts

@@ -10,5 +10,11 @@ export const tipPaymentPlansResponse = { plans: [
 ] };
 export const paymentOrderId = "order_e2e_vip_monthly";
 export const createPaymentOrderResponse = { orderId: paymentOrderId, payParams: { provider: "stripe", clientSecret: "pi_e2e_secret_mock" } };
-export const paidPaymentOrderStatusResponse = { orderId: paymentOrderId, status: "paid", orderType: "vip_monthly", planId: "vip_monthly" };
+export const paidPaymentOrderStatusResponse = {
+  orderId: paymentOrderId,
+  status: "paid",
+  orderType: "vip_monthly",
+  planId: "vip_monthly",
+  creditsAdded: 0,
+};
 export const vipStatusResponse = { isVip: false, expiresAt: null };

e2e/fixtures/helpers/auth.ts

@@ -11,7 +11,7 @@ export const splashStartChatButtonName = "Start Chatting";
 export const defaultCharacterSlug = "elio";
 export const defaultCharacterSplashPath = `/characters/${defaultCharacterSlug}/splash`;
 export const defaultCharacterChatPath = `/characters/${defaultCharacterSlug}/chat`;
-export const defaultCharacterSidebarPath = `/sidebar?returnTo=%2Fcharacters%2F${defaultCharacterSlug}%2Fchat`;
+export const defaultCharacterProfilePath = `/profile?returnTo=%2Fcharacters%2F${defaultCharacterSlug}%2Fchat`;
 export const defaultCharacterChatUrl = new RegExp(
   `/characters/${defaultCharacterSlug}/chat(?:\\?.*)?$`,
 );

e2e/fixtures/helpers/chat.ts

@@ -27,7 +27,7 @@ export async function enterChatFromSplash(page: Page, options: { expectedUrl?: R
   await expect(startChatButton).toBeVisible({ timeout });
   await expect(startChatButton).toBeEnabled();
   for (let attempt = 0; attempt < 3; attempt += 1) {
-    await startChatButton.click();
+    await startChatButton.click({ timeout: 3_000 }).catch(() => {});
     try { await expect(page).toHaveURL(expectedUrl, { timeout: 3_000 }); return; } catch { await page.waitForTimeout(500); }
   }
   await expect(page).toHaveURL(expectedUrl, { timeout });
@@ -42,9 +42,7 @@ export async function dismissChatInterruptions(page: Page) {
 
 export async function signInWithEmailAndOpenChat(page: Page) {
   await seedEmailSession(page);
-  const historyResponsePromise = page.waitForResponse("**/api/chat/history**");
   await page.goto(defaultCharacterChatPath);
-  await historyResponsePromise;
   await dismissChatInterruptions(page);
   await expect(page.getByRole("textbox", { name: "Message" })).toBeEnabled({ timeout: 20_000 });
 }

e2e/fixtures/helpers/payment.ts

@@ -1,9 +1,19 @@
 import { expect, type Page } from "@playwright/test";
 
 export async function completeVipPayment(page: Page) {
+  const checkoutButton = page.getByRole("button", { name: "Pay and Top Up" });
+  await expect(checkoutButton).toBeDisabled();
+  await page.getByRole("button", { name: /Monthly,/i }).click();
+  const renewalDialog = page.getByRole("dialog", {
+    name: "Automatic Renewal Confirmation",
+  });
+  await expect(renewalDialog).toBeVisible();
+  await renewalDialog.getByRole("button", { name: "Confirm" }).click();
+  await expect(checkoutButton).toBeEnabled();
+
   const createOrderRequestPromise = page.waitForRequest("**/api/payment/create-order");
   const orderStatusRequestPromise = page.waitForRequest("**/api/payment/order-status**");
-  await page.getByRole("button", { name: /Pay and Activ/i }).click();
+  await checkoutButton.click();
   const createOrderRequest = await createOrderRequestPromise;
   expect(createOrderRequest.postDataJSON()).toMatchObject({ planId: "vip_monthly", payChannel: "stripe" });
   await orderStatusRequestPromise;

e2e/specs/mock/auth/email-login-from-other-options.spec.ts

@@ -31,5 +31,5 @@ test("user can email login from other sign-in options and return to chat", async
   expect(["desktop", "android"]).toContain(loginRequest?.postDataJSON().platform);
 
   await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
-  await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Save CozSweet" })).toBeVisible();
 });

e2e/specs/mock/auth/logout-from-profile.spec.ts

@@ -3,7 +3,7 @@ import { expect, test } from "@playwright/test";
 import { mockCoreApis } from "@e2e/fixtures/api-mocks";
 import {
   clearBrowserState,
-  defaultCharacterSidebarPath,
+  defaultCharacterProfilePath,
   defaultCharacterSplashPath,
   defaultCharacterChatUrl,
   enterChatFromSplash,
@@ -17,7 +17,7 @@ test.beforeEach(async ({ baseURL, context, page }) => {
   await mockCoreApis(page);
 });
 
-test("user can log out from the sidebar after email login", async ({
+test("user can log out from the profile after email login", async ({
   page,
 }) => {
   await enterChatFromSplash(page);
@@ -27,11 +27,14 @@ test("user can log out from the sidebar after email login", async ({
   await expect(page).toHaveURL(/\/auth(?:\?.*)?$/);
   await switchToEmailSignIn(page);
   await submitEmailLogin(page, { expectedUrl: defaultCharacterChatUrl });
-  await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
+  await page.getByRole("link", { name: "Back to home" }).click();
+  await expect(page).toHaveURL(
+    new RegExp(defaultCharacterSplashPath.replace("?", "\\?") + "$"),
+  );
 
   await page.getByRole("button", { name: "Menu" }).click();
   await expect(page).toHaveURL(
-    new RegExp(defaultCharacterSidebarPath.replace("?", "\\?") + "$"),
+    new RegExp(defaultCharacterProfilePath.replace("?", "\\?") + "$"),
   );
 
   const logoutRequestPromise = page.waitForRequest("**/api/auth/logout");

e2e/specs/mock/auth/psid-login-from-external-entry.spec.ts

@@ -1,49 +1,74 @@
 import { expect, test } from "@playwright/test";
 
 import { mockCoreApis } from "@e2e/fixtures/api-mocks";
-import {
+import { clearBrowserState } from "@e2e/fixtures/test-helpers";
-  clearBrowserState,
-  defaultCharacterChatUrl,
-} from "@e2e/fixtures/test-helpers";
 
-const psid = "e2e-facebook-psid";
+const handoffToken = "e2e-handoff-token-that-is-at-least-32-characters";
 
 test.beforeEach(async ({ baseURL, context, page }) => {
   await clearBrowserState(context, page, baseURL);
-  await mockCoreApis(page, { psidLoginFlow: true });
+  await mockCoreApis(page, { topUpHandoffFlow: true });
 });
 
-test("user enters from an external PSID link and becomes a guest", async ({
+test("user consumes a top-up handoff and opens credit packages as a formal Messenger user", async ({
   page,
 }) => {
-  const psidLoginRequestPromise = page.waitForRequest(
+  const handoffRequestPromise = page.waitForRequest(
-    "**/api/auth/login/facebook/psid",
+    "**/api/auth/handoff/topup/consume",
   );
 
-  await page.goto(`/external-entry?target=chat&psid=${psid}`);
+  await page.goto(
+    `/external-entry?target=topup&handoffToken=${encodeURIComponent(handoffToken)}`,
+  );
 
-  const psidLoginRequest = await psidLoginRequestPromise;
+  const handoffRequest = await handoffRequestPromise;
-  expect(psidLoginRequest.method()).toBe("POST");
+  expect(handoffRequest.method()).toBe("POST");
-  expect(psidLoginRequest.postDataJSON()).toMatchObject({
+  expect(handoffRequest.postDataJSON()).toEqual({ handoffToken });
-    psid,
-    bindToGuest: true,
-  });
-  expect(psidLoginRequest.postDataJSON().deviceId).toEqual(expect.any(String));
 
-  await expect(page).toHaveURL(defaultCharacterChatUrl);
+  await expect(page).toHaveURL("/subscription?type=topup");
-  await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: /Pay and Top Up/i }),
+  ).toBeVisible();
 
   await expect
     .poll(() =>
       page.evaluate(() => ({
         loginProvider: localStorage.getItem("cozsweet:login_provider"),
-        guestToken: localStorage.getItem("cozsweet:guest_token"),
+        loginToken: localStorage.getItem("cozsweet:login_token"),
-        psid: localStorage.getItem("cozsweet:psid"),
+        refreshToken: localStorage.getItem("cozsweet:refresh_token"),
       })),
     )
     .toMatchObject({
-      loginProvider: "guest",
+      loginProvider: "facebookMessenger",
-      guestToken: "e2e-psid-guest-token",
+      loginToken: "e2e-messenger-token",
-      psid,
+      refreshToken: "e2e-messenger-refresh-token",
     });
 });
+
+test("invalid top-up handoff does not log in and is removed from the URL", async ({
+  page,
+}) => {
+  await page.route("**/api/auth/handoff/topup/consume", async (route) => {
+    await route.fulfill({
+      status: 410,
+      json: {
+        detail: {
+          code: "HANDOFF_EXPIRED",
+          message: "充值链接已过期",
+        },
+      },
+    });
+  });
+
+  await page.goto(
+    `/external-entry?target=topup&handoffToken=${encodeURIComponent(handoffToken)}`,
+  );
+
+  await expect(page).toHaveURL("/external-entry?target=topup");
+  await expect(
+    page.getByText(/invalid or has expired/i),
+  ).toBeVisible();
+  await expect
+    .poll(() => page.evaluate(() => localStorage.getItem("cozsweet:login_provider")))
+    .not.toBe("facebookMessenger");
+});

e2e/specs/mock/chat/chat-avatar-navigation.spec.ts

@@ -0,0 +1,86 @@
+import { expect, test, type Page } from "@playwright/test";
+
+import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+import {
+  clearBrowserState,
+  defaultCharacterProfilePath,
+  dismissChatInterruptions,
+  enterChatFromSplash,
+  submitEmailLogin,
+  switchToEmailSignIn,
+} from "@e2e/fixtures/test-helpers";
+
+const characters = [
+  { slug: "elio", displayName: "Elio Silvestri" },
+  { slug: "maya", displayName: "Maya Tan" },
+  { slug: "nayeli", displayName: "Nayeli Cervantes" },
+] as const;
+
+test.beforeEach(async ({ baseURL, context, page }) => {
+  await clearBrowserState(context, page, baseURL);
+  await mockCoreApis(page);
+});
+
+test("guest user avatar returns to Profile after sign-in", async ({
+  page,
+}) => {
+  await enterChatFromSplash(page, { timeout: 30_000 });
+  await sendMessage(page, "Open my profile");
+
+  await page.getByRole("button", { name: "Open profile" }).click();
+
+  await expect(page).toHaveURL(/\/auth\?redirect=/);
+  expect(new URL(page.url()).searchParams.get("redirect")).toBe(
+    defaultCharacterProfilePath,
+  );
+  await switchToEmailSignIn(page);
+  await submitEmailLogin(page, {
+    expectedUrl: new RegExp(
+      `${defaultCharacterProfilePath.replace("?", "\\?")}$`,
+    ),
+  });
+});
+
+for (const character of characters) {
+  test(`${character.displayName} avatar opens the matching Private Zone`, async ({
+    page,
+  }) => {
+    await enterCharacterChat(page, character.slug);
+    await sendMessage(page, `Hello ${character.displayName}`);
+
+    await page
+      .getByRole("button", {
+        name: `Open ${character.displayName}'s private zone`,
+      })
+      .last()
+      .click();
+
+    await expect(page).toHaveURL(
+      new RegExp(`/characters/${character.slug}/private-zone(?:\\?.*)?$`),
+    );
+  });
+}
+
+async function enterCharacterChat(page: Page, characterSlug: string) {
+  const chatPath = `/characters/${characterSlug}/chat`;
+
+  await page.goto(`/characters/${characterSlug}/splash`);
+  await page.getByRole("button", { name: "Start Chatting" }).click();
+  await expect(page).toHaveURL(new RegExp(`${chatPath}(?:\\?.*)?$`));
+  await dismissChatInterruptions(page);
+  await expect(page.getByRole("textbox", { name: "Message" })).toBeEnabled({
+    timeout: 20_000,
+  });
+}
+
+async function sendMessage(page: Page, message: string) {
+  await dismissChatInterruptions(page);
+  const messageInput = page.getByRole("textbox", { name: "Message" });
+
+  await expect(messageInput).toBeEnabled({ timeout: 20_000 });
+  await messageInput.fill(message);
+  await messageInput.press("Enter");
+  await expect(page.getByRole("button", { name: "Open profile" })).toBeVisible({
+    timeout: 10_000,
+  });
+}

e2e/specs/mock/chat/commercial-action-navigation.spec.ts

@@ -0,0 +1,49 @@
+import { expect, test } from "@playwright/test";
+
+import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+import {
+  clearBrowserState,
+  enterChatFromSplash,
+} from "@e2e/fixtures/test-helpers";
+
+test.beforeEach(async ({ baseURL, context, page }) => {
+  await clearBrowserState(context, page, baseURL);
+  await mockCoreApis(page);
+});
+
+test("renders a backend commercial action and opens the private zone", async ({
+  page,
+}) => {
+  await enterChatFromSplash(page);
+
+  const input = page.getByRole("textbox", { name: "Message" });
+  await expect(input).toBeEnabled();
+  await input.fill("private album offer test");
+  await input.press("Enter");
+
+  const offer = page.getByLabel("Open private zone");
+  await expect(offer).toContainText(
+    "There are more private photos waiting for you.",
+  );
+  await offer.getByRole("button", { name: "Open private zone" }).click();
+
+  await expect(page).toHaveURL(/\/characters\/elio\/private-zone$/);
+});
+
+test("asks for consent before opening a user-bound discount plan", async ({
+  page,
+}) => {
+  await enterChatFromSplash(page);
+
+  const input = page.getByRole("textbox", { name: "Message" });
+  await input.fill("discount offer test");
+  await input.press("Enter");
+
+  const offer = page.getByLabel("Yes, ask for me");
+  await expect(offer).toContainText("Want me to ask for my best private offer?");
+  await offer.getByRole("button", { name: "Yes, ask for me" }).click();
+
+  await expect(page).toHaveURL(
+    /\/subscription\?type=vip.*planId=vip_annual.*commercialOfferId=13ec8a10/,
+  );
+});

e2e/specs/mock/chat/facebook-external-entry-links.spec.ts

@@ -0,0 +1,201 @@
+import { expect, test, type Page } from "@playwright/test";
+
+import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+import { apiEnvelope } from "@e2e/fixtures/data/common";
+import { clearBrowserState } from "@e2e/fixtures/test-helpers";
+
+const testPsid = "e2e-facebook-psid-27511427698460020";
+
+const characters = [
+  {
+    id: "elio",
+    slug: "elio",
+    displayName: "Elio Silvestri",
+    shortName: "Elio",
+  },
+  {
+    id: "maya-tan",
+    slug: "maya",
+    displayName: "Maya Tan",
+    shortName: "Maya",
+  },
+  {
+    id: "nayeli-cervantes",
+    slug: "nayeli",
+    displayName: "Nayeli Cervantes",
+    shortName: "Nayeli",
+  },
+] as const;
+
+type Character = (typeof characters)[number];
+type EntryKind = "private-space" | "voice" | "image-pack" | "coffee";
+
+interface FacebookEntryCase {
+  character: Character;
+  kind: EntryKind;
+  target: "chat" | "private-zone" | "tip";
+  expectedPath: string;
+  promotionType?: "voice";
+}
+
+const entryCases: FacebookEntryCase[] = characters.flatMap((character) => [
+  {
+    character,
+    kind: "private-space",
+    target: "chat",
+    expectedPath: `/characters/${character.slug}/chat`,
+  },
+  {
+    character,
+    kind: "voice",
+    target: "chat",
+    expectedPath: `/characters/${character.slug}/chat`,
+    promotionType: "voice",
+  },
+  {
+    character,
+    kind: "image-pack",
+    target: "private-zone",
+    expectedPath: `/characters/${character.slug}/private-zone`,
+  },
+  {
+    character,
+    kind: "coffee",
+    target: "tip",
+    expectedPath: `/characters/${character.slug}/tip`,
+  },
+]);
+
+test.beforeEach(async ({ baseURL, context, page }) => {
+  await clearBrowserState(context, page, baseURL);
+  await mockCoreApis(page);
+  await registerEntryPageMocks(page);
+});
+
+for (const entryCase of entryCases) {
+  test(`${entryCase.character.displayName} opens Facebook ${entryCase.kind} entry`, async ({
+    page,
+  }) => {
+    await page.goto(buildEntryUrl(entryCase));
+
+    await expect(page).toHaveURL(entryCase.expectedPath, { timeout: 20_000 });
+    await expect
+      .poll(() =>
+        page.evaluate(() => localStorage.getItem("cozsweet:psid")),
+      )
+      .toBe(testPsid);
+
+    if (entryCase.kind === "private-space") {
+      await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
+      await expect(
+        page.getByRole("button", { name: "Unlock voice message" }),
+      ).toHaveCount(0);
+      return;
+    }
+
+    if (entryCase.kind === "voice") {
+      await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
+      await expect(
+        page.getByRole("button", { name: "Unlock voice message" }),
+      ).toHaveCount(1);
+      return;
+    }
+
+    if (entryCase.kind === "image-pack") {
+      await expect(
+        page.getByRole("heading", { name: "Private albums" }),
+      ).toBeVisible();
+      await expect(
+        page.getByText(entryCase.character.displayName).last(),
+      ).toBeVisible();
+      return;
+    }
+
+    await expect(
+      page.getByRole("heading", {
+        name: `Buy ${entryCase.character.shortName} a coffee`,
+      }),
+    ).toBeVisible();
+  });
+}
+
+function buildEntryUrl(entryCase: FacebookEntryCase): string {
+  const params = new URLSearchParams({
+    target: entryCase.target,
+    character: entryCase.character.slug,
+    psid: testPsid,
+  });
+  if (entryCase.promotionType) {
+    params.set("mode", "promotion");
+    params.set("promotion_type", entryCase.promotionType);
+  }
+  return `/external-entry?${params.toString()}`;
+}
+
+async function registerEntryPageMocks(page: Page): Promise<void> {
+  await page.route("**/api/private-zone/posts**", async (route) => {
+    const url = new URL(route.request().url());
+    const characterId = url.searchParams.get("characterId") ?? "elio";
+    await route.fulfill({
+      json: apiEnvelope({
+        characterId,
+        items: [],
+        nextCursor: null,
+        hasMore: false,
+        creditBalance: 1000,
+        currency: "credits",
+      }),
+    });
+  });
+
+  await page.route("**/api/private-zone/albums**", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope({
+        creditBalance: 1000,
+        pendingImageCount: 0,
+        hasIncompleteContent: false,
+        items: [],
+      }),
+    });
+  });
+
+  await page.route("**/api/payment/gift-products**", async (route) => {
+    const url = new URL(route.request().url());
+    const characterId = url.searchParams.get("characterId") ?? "elio";
+    const planPrefix =
+      characterId === "elio"
+        ? "tip"
+        : `tip_${characterId.replaceAll("-", "_")}`;
+    await route.fulfill({
+      json: apiEnvelope({
+        characterId,
+        categories: [
+          {
+            category: "coffee",
+            name: "Coffee",
+            productCount: 1,
+            imageUrl: null,
+          },
+        ],
+        plans: [
+          {
+            planId: `${planPrefix}_coffee_usd_4_99`,
+            planName: "Small Coffee",
+            orderType: "tip",
+            tipType: "coffee_small",
+            category: "coffee",
+            characterId,
+            description: "A character-scoped coffee gift",
+            imageUrl: null,
+            amountCents: 499,
+            currency: "USD",
+            autoRenew: false,
+            isFirstRechargeOffer: false,
+            firstRechargeDiscountPercent: 0,
+            promotionType: null,
+          },
+        ],
+      }),
+    });
+  });
+}

e2e/specs/mock/chat/paid-image-promotion-topup.spec.ts

@@ -7,7 +7,6 @@ import {
   defaultCharacterChatUrl,
   expectInsufficientCreditsDialog,
   expectVipChatSubscriptionUrl,
-  setEmailSessionStorage,
   submitEmailLogin,
   switchToEmailSignIn,
 } from "@e2e/fixtures/test-helpers";
@@ -36,13 +35,10 @@ test("guest unlocks a promoted image through email login and top-up", async ({
   await expect(page).toHaveURL(/\/auth\?redirect=/);
 
   await switchToEmailSignIn(page);
-  await submitEmailLogin(page, { expectedUrl: defaultCharacterChatUrl });
-
-  await setEmailSessionStorage(page);
   const unlockRequestPromise = page.waitForRequest(
     "**/api/chat/unlock-private",
   );
-  await page.reload();
+  await submitEmailLogin(page, { expectedUrl: defaultCharacterChatUrl });
 
   const unlockRequest = await unlockRequestPromise;
   expect(unlockRequest.method()).toBe("POST");

e2e/specs/mock/favorite-menu-navigation.spec.ts

@@ -0,0 +1,206 @@
+import path from "node:path";
+
+import { expect, test, type Page } from "@playwright/test";
+
+import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+import { apiEnvelope } from "@e2e/fixtures/data/common";
+import { e2eEmailUser } from "@e2e/fixtures/data/auth";
+import { chatCharactersResponse } from "@e2e/fixtures/data/character";
+import {
+  emptyChatHistoryResponse,
+  emptyChatPreviewsResponse,
+} from "@e2e/fixtures/data/chat";
+import { paymentPlansResponse } from "@e2e/fixtures/data/payment";
+import { userEntitlementsResponse } from "@e2e/fixtures/data/user";
+import {
+  defaultCharacterChatPath,
+  defaultCharacterSplashPath,
+  seedEmailSession,
+} from "@e2e/fixtures/helpers/auth";
+
+const previewDirectory = path.join(
+  process.cwd(),
+  ".codex",
+  "artifacts",
+  "frontend-preview",
+  "2026-07-22",
+  "favorite-menu",
+);
+
+test.beforeEach(async ({ page }) => {
+  await registerFavoriteMenuMocks(page);
+});
+
+test("favorite entry and three-tab Menu navigation render on the real pages", async ({
+  page,
+}, testInfo) => {
+  const mobile = testInfo.project.name.includes("mobile");
+  await page.setViewportSize(
+    mobile ? { width: 390, height: 844 } : { width: 1440, height: 900 },
+  );
+  const browserErrors = collectBrowserErrors(page);
+
+  await seedEmailSession(page);
+  await page.goto(defaultCharacterChatPath);
+
+  await expect(page.getByRole("button", { name: "Save CozSweet" })).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: /First recharge offer, 50% off/i }),
+  ).toBeVisible();
+  await expect(page.getByRole("button", { name: "Profile" })).toHaveCount(0);
+  await savePreview(page, `${mobile ? "mobile" : "desktop"}-chat.png`);
+
+  await page.goto(defaultCharacterSplashPath);
+  await expect(page.getByRole("button", { name: "Save CozSweet" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
+  const navigation = page.getByRole("navigation", {
+    name: "Primary navigation",
+  });
+  await expect(navigation).toContainText("Chat");
+  await expect(navigation).toContainText("Private Zone");
+  await expect(navigation).toContainText("Menu");
+  await savePreview(page, `${mobile ? "mobile" : "desktop"}-splash.png`);
+
+  await page.goto("/characters/elio/private-zone");
+  await expect(page.getByRole("button", { name: "Save CozSweet" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
+  await savePreview(
+    page,
+    `${mobile ? "mobile" : "desktop"}-private-zone.png`,
+  );
+
+  await page.getByRole("button", { name: "Menu" }).click();
+  await expect(page.getByRole("heading", { name: "Menu" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Save CozSweet" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Menu" })).toHaveAttribute(
+    "aria-current",
+    "page",
+  );
+  await savePreview(page, `${mobile ? "mobile" : "desktop"}-menu.png`);
+
+  if (mobile) {
+    await page.evaluate(() => {
+      localStorage.setItem("cozsweet:favorite_entry", "1");
+    });
+    await page.goto(defaultCharacterChatPath);
+    await expect(page.getByRole("button", { name: "Download" })).toBeVisible();
+    await savePreview(page, "mobile-android-external-chat-download.png");
+
+    await page.addInitScript(() => {
+      Object.defineProperty(navigator, "userAgent", {
+        configurable: true,
+        value:
+          "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1",
+      });
+    });
+    await page.goto(defaultCharacterChatPath);
+    const iosDownload = page.getByRole("button", { name: "Download" });
+    await expect(iosDownload).toBeVisible();
+    await iosDownload.click();
+    await expect(
+      page.getByRole("heading", { name: "Add CozSweet to Home Screen" }),
+    ).toBeVisible();
+    await expect(page.getByRole("dialog")).toContainText(
+      "In Safari, tap the Share button, then choose “Add to Home Screen”.",
+    );
+    await savePreview(page, "mobile-ios-external-chat-download.png");
+  }
+
+  expect(browserErrors.filter(isFeatureRuntimeError)).toEqual([]);
+});
+
+async function registerFavoriteMenuMocks(page: Page): Promise<void> {
+  await mockCoreApis(page);
+  await page.route("**/api/payment/plans**", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope({
+        ...paymentPlansResponse,
+        isFirstRecharge: true,
+      }),
+    });
+  });
+  await page.route("**/api/private-zone/albums**", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope({ items: [], creditBalance: 80 }),
+    });
+  });
+  await page.context().route("**/api/**", async (route) => {
+    const pathname = new URL(route.request().url()).pathname;
+    if (pathname === "/api/auth/session") {
+      await route.fulfill({
+        json: {
+          expires: "2099-12-31T23:59:59.000Z",
+          user: { email: null, image: null, name: null },
+        },
+      });
+      return;
+    }
+    if (pathname === "/api/characters") {
+      await route.fulfill({ json: apiEnvelope(chatCharactersResponse) });
+      return;
+    }
+    if (pathname === "/api/user/profile") {
+      await route.fulfill({ json: apiEnvelope(e2eEmailUser) });
+      return;
+    }
+    if (pathname === "/api/user/entitlements") {
+      await route.fulfill({ json: apiEnvelope(userEntitlementsResponse) });
+      return;
+    }
+    if (pathname === "/api/chat/history") {
+      await route.fulfill({ json: apiEnvelope(emptyChatHistoryResponse) });
+      return;
+    }
+    if (pathname === "/api/chat/previews") {
+      await route.fulfill({ json: apiEnvelope(emptyChatPreviewsResponse) });
+      return;
+    }
+    if (pathname === "/api/payment/plans") {
+      await route.fulfill({
+        json: apiEnvelope({
+          ...paymentPlansResponse,
+          isFirstRecharge: true,
+        }),
+      });
+      return;
+    }
+    if (pathname === "/api/payment/vip-status") {
+      await route.fulfill({
+        json: apiEnvelope({ isVip: false, expiresAt: null }),
+      });
+      return;
+    }
+    if (pathname === "/api/private-zone/albums") {
+      await route.fulfill({
+        json: apiEnvelope({ items: [], creditBalance: 80 }),
+      });
+      return;
+    }
+    await route.fallback();
+  });
+}
+
+function collectBrowserErrors(page: Page): string[] {
+  const errors: string[] = [];
+  page.on("pageerror", (error) => errors.push(error.message));
+  page.on("console", (message) => {
+    if (message.type() === "error") errors.push(message.text());
+  });
+  return errors;
+}
+
+function isFeatureRuntimeError(message: string): boolean {
+  const isKnownLocalPreviewDependencyError =
+    message.includes("[ApiLoggingInterceptor]") ||
+    message.includes("[next-auth][error][CLIENT_FETCH_ERROR]") ||
+    message.includes("[Result] Result.wrap caught exception");
+  return !isKnownLocalPreviewDependencyError;
+}
+
+async function savePreview(page: Page, fileName: string): Promise<void> {
+  if (process.env.FRONTEND_PREVIEW_SCREENSHOTS !== "1") return;
+  await page.screenshot({
+    path: path.join(previewDirectory, fileName),
+    animations: "disabled",
+  });
+}

e2e/specs/mock/multi-role-commercial.spec.ts

@@ -0,0 +1,264 @@
+import path from "node:path";
+
+import { expect, test, type Page } from "@playwright/test";
+
+import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+import { apiEnvelope } from "@e2e/fixtures/data/common";
+import { clearBrowserState } from "@e2e/fixtures/test-helpers";
+
+const characters = [
+  {
+    id: "elio",
+    slug: "elio",
+    displayName: "Elio Silvestri",
+    shortName: "Elio",
+    cover: "elio.png",
+    splashCover: "elio.png",
+  },
+  {
+    id: "maya-tan",
+    slug: "maya",
+    displayName: "Maya Tan",
+    shortName: "Maya",
+    cover: "maya.webp",
+    splashCover: "maya-home.webp",
+  },
+  {
+    id: "nayeli-cervantes",
+    slug: "nayeli",
+    displayName: "Nayeli Cervantes",
+    shortName: "Nayeli",
+    cover: "nayeli.webp",
+    splashCover: "nayeli.webp",
+  },
+] as const;
+
+const previewDirectory = path.join(
+  process.cwd(),
+  ".codex",
+  "artifacts",
+  "frontend-preview",
+  "2026-07-22",
+  "multi-role-commercial",
+);
+
+test.beforeEach(async ({ baseURL, context, page }) => {
+  await clearBrowserState(context, page, baseURL);
+  await mockCoreApis(page);
+  await registerMultiRoleCommercialMocks(page);
+});
+
+for (const character of characters) {
+  test(`${character.displayName} homepage renders its assigned cover`, async ({
+    page,
+  }, testInfo) => {
+    const mobile = testInfo.project.name.includes("mobile");
+    await page.setViewportSize(
+      mobile ? { width: 390, height: 844 } : { width: 1440, height: 900 },
+    );
+
+    await page.goto(`/characters/${character.slug}/splash`);
+
+    const cover = page.locator(`img[src*="${character.splashCover}"]`);
+    await expect(cover).toBeVisible();
+    await expect(
+      page.getByRole("navigation", { name: "Primary navigation" }),
+    ).toContainText("Private Zone");
+    await expect
+      .poll(() =>
+        cover.evaluate((image: HTMLImageElement) =>
+          image.complete ? image.naturalWidth : 0,
+        ),
+      )
+      .toBeGreaterThan(0);
+
+    if (
+      process.env.FRONTEND_PREVIEW_SCREENSHOTS === "1" &&
+      character.id !== "elio"
+    ) {
+      await page.screenshot({
+        path: path.join(
+          previewDirectory,
+          `${character.slug}-${mobile ? "mobile-390x844" : "desktop-1440x900"}.png`,
+        ),
+        animations: "disabled",
+      });
+    }
+  });
+
+  test(`${character.displayName} can open a character-scoped Private Zone`, async ({
+    page,
+  }) => {
+    const momentsRequest = page.waitForRequest((request) => {
+      const url = new URL(request.url());
+      return (
+        url.pathname === "/api/private-zone/posts" &&
+        url.searchParams.get("characterId") === character.id
+      );
+    });
+    const albumRequest = page.waitForRequest((request) => {
+      const url = new URL(request.url());
+      return (
+        url.pathname === "/api/private-zone/albums" &&
+        url.searchParams.get("characterId") === character.id
+      );
+    });
+
+    await page.goto(`/characters/${character.slug}/private-zone`);
+
+    await Promise.all([momentsRequest, albumRequest]);
+    await expect(
+      page.getByRole("heading", { name: "Private albums" }),
+    ).toBeVisible();
+    await expect(page.getByRole("tab")).toHaveText(["Albums", "Moments"]);
+    await expect(page.getByRole("tab", { name: "Albums" })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+    await expect(page.getByText(character.displayName).last()).toBeVisible();
+    const albumButton = page.getByRole("button", {
+      name: `View locked collection with 8 images from ${character.displayName}`,
+    });
+    if (character.id === "maya-tan") {
+      await expect(albumButton).toHaveCount(0);
+      await expect(page.getByRole("button", { name: "Refresh" })).toHaveCount(0);
+      await expect(page.getByText("No private albums yet.")).toHaveCount(0);
+    } else {
+      await expect(albumButton).toBeVisible();
+    }
+  });
+
+  test(`${character.displayName} receives a character-scoped Tip catalog`, async ({
+    page,
+  }) => {
+    const catalogRequest = page.waitForRequest((request) => {
+      const url = new URL(request.url());
+      return (
+        url.pathname === "/api/payment/gift-products" &&
+        url.searchParams.get("characterId") === character.id
+      );
+    });
+
+    await page.goto(`/characters/${character.slug}/tip`);
+
+    await catalogRequest;
+    await expect(
+      page.getByRole("heading", { name: `Buy ${character.shortName} a coffee` }),
+    ).toBeVisible();
+    await expect(page.getByRole("radio", { name: /Small Coffee/ })).toBeChecked();
+    await expect(
+      page.getByRole("button", { name: "Order and Buy" }),
+    ).toBeEnabled();
+    await expect(
+      page.getByText("This character does not have any gifts available yet."),
+    ).toHaveCount(0);
+  });
+}
+
+test("a real Private Zone request failure still offers Retry", async ({
+  page,
+}) => {
+  await page.route("**/api/private-zone/albums**", async (route) => {
+    await route.fulfill({ status: 503, json: { message: "Albums unavailable" } });
+  });
+
+  await page.goto("/characters/maya/private-zone");
+
+  await expect(page.getByRole("button", { name: "Retry" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Refresh" })).toHaveCount(0);
+});
+
+async function registerMultiRoleCommercialMocks(page: Page): Promise<void> {
+  await page.route("**/api/private-zone/posts**", async (route) => {
+    const url = new URL(route.request().url());
+    const characterId = url.searchParams.get("characterId") ?? "elio";
+    await route.fulfill({
+      json: apiEnvelope({
+        characterId,
+        items: [],
+        nextCursor: null,
+        hasMore: false,
+        creditBalance: 1000,
+        currency: "credits",
+      }),
+    });
+  });
+
+  await page.route("**/api/private-zone/albums**", async (route) => {
+    const url = new URL(route.request().url());
+    const characterId = url.searchParams.get("characterId") ?? "elio";
+    const character =
+      characters.find((candidate) => candidate.id === characterId) ?? characters[0];
+
+    const hasCompleteAlbum = character.id !== "maya-tan";
+    await route.fulfill({
+      json: apiEnvelope({
+        creditBalance: 1000,
+        pendingImageCount: hasCompleteAlbum ? 0 : 7,
+        hasIncompleteContent: !hasCompleteAlbum,
+        items: hasCompleteAlbum ? [
+          {
+            albumId: `album-${character.id}`,
+            title: `${character.shortName} private photos`,
+            content: null,
+            previewText: "Unlock this private album",
+            imageCount: 8,
+            images: [
+              {
+                url: `/images/private-zone/banner/${character.slug}.png`,
+                locked: true,
+                index: 0,
+              },
+            ],
+            locked: true,
+            unlocked: false,
+            unlockCost: 320,
+            publishedAt: "2026-07-22T10:00:00+08:00",
+            lockDetail: { locked: true },
+          },
+        ] : [],
+      }),
+    });
+  });
+
+  await page.route("**/api/payment/gift-products**", async (route) => {
+    const url = new URL(route.request().url());
+    const characterId = url.searchParams.get("characterId") ?? "elio";
+    const planPrefix =
+      characterId === "elio"
+        ? "tip"
+        : `tip_${characterId.replaceAll("-", "_")}`;
+
+    await route.fulfill({
+      json: apiEnvelope({
+        characterId,
+        categories: [
+          {
+            category: "coffee",
+            name: "Coffee",
+            productCount: 1,
+            imageUrl: null,
+          },
+        ],
+        plans: [
+          {
+            planId: `${planPrefix}_coffee_usd_4_99`,
+            planName: "Small Coffee",
+            orderType: "tip",
+            tipType: "coffee_small",
+            category: "coffee",
+            characterId,
+            description: "A character-scoped coffee gift",
+            imageUrl: null,
+            amountCents: 499,
+            currency: "USD",
+            autoRenew: false,
+            isFirstRechargeOffer: false,
+            firstRechargeDiscountPercent: 0,
+            promotionType: null,
+          },
+        ],
+      }),
+    });
+  });
+}

e2e/specs/mock/paid-image.spec.ts

@@ -1,7 +1,12 @@
 import { expect, test } from "@playwright/test";
 
 import { mockCoreApis } from "@e2e/fixtures/api-mocks";
-import { paidImageMessageId } from "@e2e/fixtures/test-data";
+import { apiEnvelope } from "@e2e/fixtures/data/common";
+import { createPaidImageHistoryResponse } from "@e2e/fixtures/data/chat";
+import {
+  paidImageDisplayMessageId,
+  paidImageMessageId,
+} from "@e2e/fixtures/test-data";
 import {
   clearBrowserState,
   completeVipPayment,
@@ -10,15 +15,10 @@ import {
   enterChatFromSplash,
   expectInsufficientCreditsDialog,
   expectVipChatSubscriptionUrl,
-  setEmailSessionStorage,
   submitEmailLogin,
   switchToEmailSignIn,
 } from "@e2e/fixtures/test-helpers";
 
-const paidImageOverlayUrl = new RegExp(
-  `${defaultCharacterChatPath}\\?image=${paidImageMessageId}$`,
-);
-
 test.beforeEach(async ({ baseURL, context, page }) => {
   await clearBrowserState(context, page, baseURL);
   await mockCoreApis(page, {
@@ -44,38 +44,27 @@ test("guest can unlock a paid image after email login and subscription payment",
     message: "给我发图片",
   });
 
-  const paidImageButton = page.getByRole("button", {
+  const lockedImageCard = page.getByRole("group", {
-    name: "Open image in fullscreen",
+    name: "Locked private image",
   }).last();
-  await expect(paidImageButton).toBeVisible();
+  await expect(lockedImageCard).toBeVisible();
-
+  await expect(lockedImageCard.locator("img")).toHaveCount(0);
-  await paidImageButton.click();
+  await lockedImageCard
-  await expect(page).toHaveURL(paidImageOverlayUrl);
+    .getByRole("button", { name: "Unlock private image" })
-
-  const lockedImageDialog = page.getByRole("dialog", {
-    name: "Locked fullscreen image",
-  });
-  await expect(lockedImageDialog).toBeVisible();
-
-  await lockedImageDialog
-    .getByRole("button", { name: "Unlock high-definition large image" })
     .click();
 
   await expect(page).toHaveURL(/\/auth\?redirect=/);
   expect(new URL(page.url()).searchParams.get("redirect")).toBe(
-    `${defaultCharacterChatPath}?image=${paidImageMessageId}`,
+    defaultCharacterChatPath,
   );
 
   await switchToEmailSignIn(page);
-  await submitEmailLogin(page, {
-    expectedUrl: paidImageOverlayUrl,
-  });
-
-  await setEmailSessionStorage(page);
   const unlockRequestPromise = page.waitForRequest(
     "**/api/chat/unlock-private",
   );
-  await page.goto(`${defaultCharacterChatPath}?image=${paidImageMessageId}`);
+  await submitEmailLogin(page, {
+    expectedUrl: new RegExp(`${defaultCharacterChatPath}$`),
+  });
 
   const unlockRequest = await unlockRequestPromise;
   expect(unlockRequest.postDataJSON()).toMatchObject({
@@ -92,9 +81,44 @@ test("guest can unlock a paid image after email login and subscription payment",
 
   await expect(page).toHaveURL(
     new RegExp(
-      `${defaultCharacterChatPath}(?:\\?image=msg_photo_paywall_001)?$`,
+      `${defaultCharacterChatPath}(?:\\?image=${encodeURIComponent(paidImageDisplayMessageId)})?$`,
     ),
   );
   expect(new URL(page.url()).pathname).toBe(defaultCharacterChatPath);
   await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
 });
+
+test("fullscreen image closes from its back button, the image, and browser history Back", async ({
+  page,
+}) => {
+  await page.route("**/api/chat/history**", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope(createPaidImageHistoryResponse(true)),
+    });
+  });
+  await enterChatFromSplash(page);
+  await dismissChatInterruptions(page);
+
+  const imageButton = page.getByRole("button", {
+    name: "Open image in fullscreen",
+  });
+  const imageDialog = page.getByRole("dialog", { name: "Fullscreen image" });
+
+  await imageButton.click();
+  await expect(imageDialog).toBeVisible();
+  await imageDialog.getByRole("button", { name: "Back" }).click();
+  await expect(imageDialog).toHaveCount(0);
+  await expect(page).toHaveURL(defaultCharacterChatPath);
+
+  await imageButton.click();
+  await expect(imageDialog).toBeVisible();
+  await imageDialog.locator("img").click();
+  await expect(imageDialog).toHaveCount(0);
+  await expect(page).toHaveURL(defaultCharacterChatPath);
+
+  await imageButton.click();
+  await expect(imageDialog).toBeVisible();
+  await page.goBack();
+  await expect(imageDialog).toHaveCount(0);
+  await expect(page).toHaveURL(defaultCharacterChatPath);
+});

e2e/specs/mock/payment-dialog-layout.spec.ts

@@ -0,0 +1,119 @@
+import { expect, test, type Page } from "@playwright/test";
+
+import { stripePaymentDialogStyles } from "@/app/_components/payment/stripe-payment-dialog.styles";
+import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+
+const viewports = [
+  { width: 390, height: 844 },
+  { width: 405, height: 797 },
+  { width: 540, height: 900 },
+] as const;
+
+test.beforeEach(async ({ page }) => {
+  await mockCoreApis(page);
+});
+
+for (const viewport of viewports) {
+  test(`payment portal stays viewport-bound at ${viewport.width}x${viewport.height}`, async ({
+    page,
+  }) => {
+    await page.setViewportSize(viewport);
+    await page.goto("/subscription?type=topup", {
+      waitUntil: "domcontentloaded",
+    });
+
+    await mountPaymentPanel(page, 180);
+    await expectViewportScrim(page, viewport);
+    await expectCenteredShortPanel(page, viewport);
+
+    await mountPaymentPanel(page, 1_200);
+    await expectViewportScrim(page, viewport);
+    await expectScrollableTallPanel(page, viewport);
+  });
+}
+
+async function mountPaymentPanel(page: Page, contentHeight: number) {
+  await page.evaluate(
+    ({ dialogClassName, overlayClassName, requestedContentHeight }) => {
+      document.querySelector('[data-testid="payment-layout-overlay"]')?.remove();
+      document.querySelector('[data-testid="transformed-checkout-host"]')?.remove();
+
+      const transformedCheckoutHost = document.createElement("div");
+      transformedCheckoutHost.dataset.testid = "transformed-checkout-host";
+      transformedCheckoutHost.style.transform = "translateX(50%)";
+      document.body.appendChild(transformedCheckoutHost);
+
+      const overlay = document.createElement("div");
+      overlay.dataset.testid = "payment-layout-overlay";
+      overlay.className = overlayClassName;
+
+      const panel = document.createElement("div");
+      panel.dataset.testid = "payment-layout-panel";
+      panel.className = dialogClassName;
+
+      const content = document.createElement("div");
+      content.style.height = `${requestedContentHeight}px`;
+      content.textContent = "Complete payment";
+      panel.appendChild(content);
+      overlay.appendChild(panel);
+
+      // Mirrors ModalPortal: the overlay must be a body child, never a child of
+      // the transformed checkout host that triggered it.
+      document.body.appendChild(overlay);
+    },
+    {
+      dialogClassName: stripePaymentDialogStyles.dialog,
+      overlayClassName: stripePaymentDialogStyles.overlay,
+      requestedContentHeight: contentHeight,
+    },
+  );
+}
+
+async function expectViewportScrim(
+  page: Page,
+  viewport: { width: number; height: number },
+) {
+  const overlay = page.getByTestId("payment-layout-overlay");
+  await expect(overlay).toBeVisible();
+  const box = await overlay.boundingBox();
+
+  expect(box).not.toBeNull();
+  expect(box?.x).toBeCloseTo(0, 0);
+  expect(box?.y).toBeCloseTo(0, 0);
+  expect(box?.width).toBeCloseTo(viewport.width, 0);
+  expect(box?.height).toBeCloseTo(viewport.height, 0);
+  await expect(overlay.evaluate((node) => node.parentElement === document.body))
+    .resolves.toBe(true);
+}
+
+async function expectCenteredShortPanel(
+  page: Page,
+  viewport: { width: number; height: number },
+) {
+  const panel = page.getByTestId("payment-layout-panel");
+  const box = await panel.boundingBox();
+
+  expect(box).not.toBeNull();
+  expect(box?.y ?? 0).toBeGreaterThan(100);
+  expect(Math.abs((box?.y ?? 0) * 2 + (box?.height ?? 0) - viewport.height))
+    .toBeLessThanOrEqual(2);
+}
+
+async function expectScrollableTallPanel(
+  page: Page,
+  viewport: { width: number; height: number },
+) {
+  const panel = page.getByTestId("payment-layout-panel");
+  const box = await panel.boundingBox();
+  const scrollMetrics = await panel.evaluate((node) => ({
+    clientHeight: node.clientHeight,
+    scrollHeight: node.scrollHeight,
+  }));
+
+  expect(box).not.toBeNull();
+  expect(box?.y ?? 0).toBeGreaterThanOrEqual(15);
+  expect(box?.y ?? 100).toBeLessThanOrEqual(25);
+  expect((box?.y ?? 0) + (box?.height ?? 0))
+    .toBeLessThanOrEqual(viewport.height - 15);
+  expect(scrollMetrics.scrollHeight).toBeGreaterThan(scrollMetrics.clientHeight);
+}

e2e/specs/mock/payment/indonesia-qris.spec.ts

@@ -0,0 +1,422 @@
+import { expect, test, type Page } from "@playwright/test";
+
+import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+import { apiEnvelope } from "@e2e/fixtures/data/common";
+import { e2eEmailUser } from "@e2e/fixtures/data/user";
+import {
+  clearBrowserState,
+  seedEmailSession,
+} from "@e2e/fixtures/test-helpers";
+
+const idrPlans = {
+  plans: [
+    {
+      planId: "vip_monthly",
+      planName: "Monthly",
+      orderType: "vip_monthly",
+      amountCents: 19_590_000,
+      originalAmountCents: 19_590_000,
+      dailyPriceCents: 653_000,
+      currency: "IDR",
+      vipDays: 30,
+      dolAmount: null,
+      creditBalance: 3_000,
+    },
+    {
+      planId: "dol_1000",
+      planName: "1,000 Credits",
+      orderType: "dol",
+      amountCents: 8_890_000,
+      originalAmountCents: null,
+      dailyPriceCents: null,
+      currency: "IDR",
+      vipDays: null,
+      dolAmount: 1_000,
+      creditBalance: 1_000,
+    },
+  ],
+};
+
+const idrGiftCatalog = {
+  characterId: "elio",
+  categories: [
+    {
+      category: "coffee",
+      name: "Coffee",
+      productCount: 1,
+      imageUrl: null,
+    },
+  ],
+  plans: [
+    {
+      planId: "tip_coffee_usd_4_99",
+      planName: "Velvet Espresso",
+      orderType: "tip",
+      tipType: "coffee_small",
+      category: "coffee",
+      characterId: "elio",
+      description: "Buy Elio a Velvet Espresso",
+      imageUrl: null,
+      amountCents: 8_929_900,
+      currency: "IDR",
+      autoRenew: false,
+      isFirstRechargeOffer: false,
+      firstRechargeDiscountPercent: 0,
+      promotionType: null,
+    },
+  ],
+};
+
+async function registerIndonesiaPaymentMocks(page: Page) {
+  const orderStatuses = new Map<string, "pending" | "paid">();
+  const orderPlans = new Map<string, { planId: string; orderType: string }>();
+  let createOrderCount = 0;
+
+  await page.route("**/api/user/profile", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope({ ...e2eEmailUser, countryCode: "ID" }),
+    });
+  });
+  await page.route("**/api/payment/plans**", async (route) => {
+    await route.fulfill({ json: apiEnvelope(idrPlans) });
+  });
+  await page.route("**/api/payment/gift-products**", async (route) => {
+    await route.fulfill({ json: apiEnvelope(idrGiftCatalog) });
+  });
+  await page.route("**/api/payment/create-order", async (route) => {
+    createOrderCount += 1;
+    const body = route.request().postDataJSON() as {
+      planId: string;
+      payChannel: "ezpay" | "stripe";
+    };
+    const plan =
+      idrPlans.plans.find((item) => item.planId === body.planId) ??
+      idrGiftCatalog.plans.find((item) => item.planId === body.planId);
+    const orderId = `order_${body.payChannel}_${body.planId}`;
+    orderStatuses.set(orderId, "pending");
+    orderPlans.set(orderId, {
+      planId: body.planId,
+      orderType: plan?.orderType ?? "dol",
+    });
+    await route.fulfill({
+      json: apiEnvelope({
+        orderId,
+        payParams:
+          body.payChannel === "stripe"
+            ? {
+                provider: "stripe",
+                clientSecret: "pi_e2e_secret_mock",
+              }
+            : {
+                provider: "ezpay",
+                countryCode: "ID",
+                channelCode: "ID_QRIS_DYNAMIC_QR",
+                channelType: "QR",
+                payData: "00020101021226670016COM.NOBUBANK.WWW",
+                firstChargeAmountCents: plan?.amountCents ?? 0,
+                currency: "IDR",
+              },
+      }),
+    });
+  });
+  await page.route("**/api/payment/order-status**", async (route) => {
+    const url = new URL(route.request().url());
+    const orderId = url.searchParams.get("order_id") ?? "";
+    const plan = orderPlans.get(orderId);
+    await route.fulfill({
+      json: apiEnvelope({
+        orderId,
+        status: orderStatuses.get(orderId) ?? "pending",
+        orderType: plan?.orderType ?? "dol",
+        planId: plan?.planId ?? null,
+        creditsAdded: 0,
+      }),
+    });
+  });
+  await page.route("**/api/payment/tip-message", async (route) => {
+    const body = route.request().postDataJSON() as { orderId: string };
+    await route.fulfill({
+      json: apiEnvelope({
+        orderId: body.orderId,
+        characterId: "elio",
+        planId: "tip_coffee_usd_4_99",
+        productName: "Velvet Espresso",
+        tipCount: 1,
+        poolIndex: 0,
+        message: "Thank you. Your gift made me smile.",
+      }),
+    });
+  });
+
+  return {
+    getCreateOrderCount() {
+      return createOrderCount;
+    },
+    markPaid(orderId: string) {
+      orderStatuses.set(orderId, "paid");
+    },
+  };
+}
+
+async function prepareIndonesiaUser(page: Page) {
+  await seedEmailSession(page);
+  await page.evaluate(() => {
+    const rawUser = localStorage.getItem("cozsweet:user");
+    const user = rawUser ? JSON.parse(rawUser) : {};
+    localStorage.setItem(
+      "cozsweet:user",
+      JSON.stringify({ ...user, countryCode: "ID" }),
+    );
+  });
+}
+
+async function expectQrisOrder(
+  page: Page,
+  buttonName: RegExp,
+  planId: string,
+  formattedAmount: RegExp,
+) {
+  const requestPromise = page.waitForRequest("**/api/payment/create-order");
+  await page.getByRole("button", { name: buttonName }).click();
+  const request = await requestPromise;
+  expect(request.postDataJSON()).toMatchObject({
+    planId,
+    payChannel: "ezpay",
+    recipientCharacterId: "elio",
+  });
+
+  const dialog = page.getByRole("dialog", { name: "Scan to pay with QRIS" });
+  await expect(dialog).toBeVisible();
+  await expect(dialog).toContainText(formattedAmount);
+  await expect(dialog).toContainText("Waiting for payment");
+  await expect(
+    dialog.getByRole("img", { name: "QRIS payment QR code" }),
+  ).toBeVisible();
+  return `order_ezpay_${planId}`;
+}
+
+async function expectCheckoutButtonLayout(page: Page) {
+  const viewport = page.viewportSize();
+  const checkoutBox = await page
+    .getByRole("button", { name: "Pay and Top Up" })
+    .boundingBox();
+  const stripeBox = await page.getByRole("button", { name: "Stripe" }).boundingBox();
+  expect(viewport).not.toBeNull();
+  expect(checkoutBox).not.toBeNull();
+  expect(stripeBox).not.toBeNull();
+  if (!viewport || !checkoutBox || !stripeBox) return;
+  expect(checkoutBox.y + checkoutBox.height).toBeLessThanOrEqual(viewport.height);
+  expect(stripeBox.y + stripeBox.height).toBeLessThanOrEqual(checkoutBox.y);
+}
+
+test.beforeEach(async ({ baseURL, context, page }) => {
+  await clearBrowserState(context, page, baseURL);
+  await mockCoreApis(page);
+});
+
+test("Indonesia VIP defaults to QRIS and completes after status polling", async ({
+  page,
+}) => {
+  const payment = await registerIndonesiaPaymentMocks(page);
+  await prepareIndonesiaUser(page);
+  await page.goto("/subscription?type=vip&character=elio");
+
+  await expect(page.getByText("Choose who you want to support")).toHaveCount(0);
+  await expect(page.getByText("Supporting Elio")).toHaveCount(0);
+  await expect(
+    page.getByRole("button", { name: "Elio", exact: true }),
+  ).toHaveCount(0);
+
+  await expect(page.getByRole("button", { name: "QRIS" })).toHaveAttribute(
+    "aria-pressed",
+    "true",
+  );
+  const checkoutButton = page.getByRole("button", { name: "Pay and Top Up" });
+  await expect(checkoutButton).toBeDisabled();
+  await expectCheckoutButtonLayout(page);
+
+  await page.getByRole("button", { name: /Monthly, 195900 IDR/i }).click();
+  const renewalDialog = page.getByRole("dialog", {
+    name: "Automatic Renewal Confirmation",
+  });
+  await expect(renewalDialog).toBeVisible();
+  expect(payment.getCreateOrderCount()).toBe(0);
+
+  await renewalDialog.getByRole("button", { name: "Confirm" }).click();
+  await expect(renewalDialog).toBeHidden();
+  await expect(checkoutButton).toBeEnabled();
+  expect(payment.getCreateOrderCount()).toBe(0);
+
+  const orderId = await expectQrisOrder(
+    page,
+    /Pay and Top Up/i,
+    "vip_monthly",
+    /Rp\s*195[.,]900/,
+  );
+  expect(payment.getCreateOrderCount()).toBe(1);
+  payment.markPaid(orderId);
+
+  const success = page.getByRole("alertdialog", { name: "Payment successful" });
+  await expect(success).toBeVisible({ timeout: 10_000 });
+  await expect(
+    page.getByRole("dialog", { name: "Scan to pay with QRIS" }),
+  ).toBeHidden();
+});
+
+test("Indonesia credit top-up uses QRIS display cents", async ({ page }) => {
+  const payment = await registerIndonesiaPaymentMocks(page);
+  await prepareIndonesiaUser(page);
+  await page.goto("/subscription?type=topup&character=elio");
+  await expect(page.getByText("Supporting Elio")).toHaveCount(0);
+  await expectCheckoutButtonLayout(page);
+
+  const orderId = await expectQrisOrder(
+    page,
+    /Pay and Top Up/i,
+    "dol_1000",
+    /Rp\s*88[.,]900/,
+  );
+  payment.markPaid(orderId);
+
+  await expect(
+    page.getByRole("alertdialog", { name: "Payment successful" }),
+  ).toBeVisible({ timeout: 10_000 });
+});
+
+test("closing QRIS restores payment selection and allows switching to Stripe", async ({
+  page,
+}) => {
+  const payment = await registerIndonesiaPaymentMocks(page);
+  await prepareIndonesiaUser(page);
+  await page.goto("/subscription?type=topup&character=elio");
+
+  await expectQrisOrder(
+    page,
+    /Pay and Top Up/i,
+    "dol_1000",
+    /Rp\s*88[.,]900/,
+  );
+  const dialog = page.getByRole("dialog", { name: "Scan to pay with QRIS" });
+  await dialog.getByRole("button", { name: "Close" }).click();
+
+  await expect(dialog).toBeHidden();
+  await expect(page.getByRole("button", { name: "Stripe" })).toBeEnabled();
+  await page.getByRole("button", { name: "Stripe" }).click();
+  await expect(page.getByRole("button", { name: "Stripe" })).toHaveAttribute(
+    "aria-pressed",
+    "true",
+  );
+  await expect(page.getByRole("button", { name: "Pay and Top Up" })).toBeEnabled();
+  expect(payment.getCreateOrderCount()).toBe(1);
+});
+
+test("closing QRIS allows switching to Stripe and creating a Stripe order", async ({
+  page,
+}) => {
+  const payment = await registerIndonesiaPaymentMocks(page);
+  await prepareIndonesiaUser(page);
+  await page.goto("/subscription?type=topup&character=elio");
+
+  await expectQrisOrder(
+    page,
+    /Pay and Top Up/i,
+    "dol_1000",
+    /Rp\s*88[.,]900/,
+  );
+  const dialog = page.getByRole("dialog", { name: "Scan to pay with QRIS" });
+  await dialog.getByRole("button", { name: "Close" }).click();
+  await expect(dialog).toBeHidden();
+
+  const stripeButton = page.getByRole("button", {
+    name: "Stripe",
+    exact: true,
+  });
+  await expect(stripeButton).toBeEnabled();
+  await stripeButton.click();
+  await expect(stripeButton).toHaveAttribute("aria-pressed", "true");
+  await expect(
+    page.getByRole("button", { name: "Resume QRIS payment" }),
+  ).toHaveCount(0);
+
+  const stripeRequestPromise = page.waitForRequest(
+    "**/api/payment/create-order",
+  );
+  await page.getByRole("button", { name: "Pay and Top Up" }).click();
+  const stripeRequest = await stripeRequestPromise;
+  expect(stripeRequest.postDataJSON()).toMatchObject({
+    planId: "dol_1000",
+    payChannel: "stripe",
+    recipientCharacterId: "elio",
+  });
+  expect(payment.getCreateOrderCount()).toBe(2);
+});
+
+test("payment issue submits Other to the feedback API without creating an order", async ({
+  page,
+}) => {
+  const payment = await registerIndonesiaPaymentMocks(page);
+  await prepareIndonesiaUser(page);
+  let feedbackBody = "";
+  let idempotencyKey = "";
+  await page.route("**/api/feedback", async (route) => {
+    feedbackBody = route.request().postData() ?? "";
+    idempotencyKey = route.request().headers()["idempotency-key"] ?? "";
+    await route.fulfill({
+      json: apiEnvelope({ feedbackId: "feedback-payment-1", duplicate: false }),
+    });
+  });
+
+  await page.goto("/subscription?type=topup&character=elio");
+  await page.getByRole("button", { name: "Payment issue?" }).click();
+  const dialog = page.getByRole("dialog", {
+    name: "What problem did you encounter?",
+  });
+  await expect(dialog).toBeVisible();
+  await dialog.getByRole("radio", { name: "Other" }).check();
+  await dialog
+    .getByLabel("Please describe the issue")
+    .fill("QRIS did not open correctly.");
+  await dialog.getByRole("button", { name: "Submit" }).click();
+
+  await expect(page.getByRole("status")).toHaveText(
+    "Thanks. Your payment issue has been submitted.",
+  );
+  await expect(dialog).toBeHidden();
+  expect(payment.getCreateOrderCount()).toBe(0);
+  expect(idempotencyKey).toMatch(/^payment_feedback_[A-Za-z0-9_-]+$/);
+  expect(feedbackBody).toContain('name="category"');
+  expect(feedbackBody).toContain("payment");
+  expect(feedbackBody).toContain(
+    "Payment issue: Other\r\nDetails: QRIS did not open correctly.",
+  );
+  expect(feedbackBody).toContain('name="context"');
+  expect(feedbackBody).toContain('"paymentIssueReason":"other"');
+  expect(feedbackBody).toContain('"characterId":"elio"');
+});
+
+test("Indonesia gift checkout keeps IDR price through QRIS and thank-you flow", async ({
+  page,
+}) => {
+  const payment = await registerIndonesiaPaymentMocks(page);
+  await prepareIndonesiaUser(page);
+  await page.goto("/characters/elio/tip");
+
+  await expect(page.getByText(/IDR\s*89[.,]299/)).toBeVisible();
+  await expectQrisOrder(
+    page,
+    /Order and Buy/i,
+    "tip_coffee_usd_4_99",
+    /Rp\s*89[.,]299/,
+  );
+  const dialog = page.getByRole("dialog", { name: "Scan to pay with QRIS" });
+  await dialog.getByRole("button", { name: "Close" }).click();
+  await expect(dialog).toBeHidden();
+
+  await expect(page.getByRole("button", { name: "Stripe" })).toBeEnabled();
+  await page.getByRole("button", { name: "Stripe" }).click();
+  await expect(page.getByRole("button", { name: "Stripe" })).toHaveAttribute(
+    "aria-pressed",
+    "true",
+  );
+  expect(payment.getCreateOrderCount()).toBe(1);
+});

e2e/specs/mock/payment/philippines-gcash.spec.ts

@@ -0,0 +1,153 @@
+import { expect, test, type Page } from "@playwright/test";
+
+import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+import { apiEnvelope } from "@e2e/fixtures/data/common";
+import { e2eEmailUser } from "@e2e/fixtures/data/user";
+import {
+  clearBrowserState,
+  seedEmailSession,
+} from "@e2e/fixtures/test-helpers";
+
+const phpPlans = {
+  plans: [
+    {
+      planId: "dol_1000",
+      planName: "1,000 Credits",
+      orderType: "dol",
+      amountCents: 49_990,
+      originalAmountCents: 74_990,
+      dailyPriceCents: null,
+      currency: "PHP",
+      vipDays: null,
+      dolAmount: 1_000,
+      creditBalance: 1_000,
+    },
+  ],
+};
+
+async function registerPhilippinesPaymentMocks(
+  page: Page,
+  response: "hosted" | "qr",
+) {
+  let createOrderCount = 0;
+
+  await page.route("**/api/user/profile", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope({ ...e2eEmailUser, countryCode: "PH" }),
+    });
+  });
+  await page.route("**/api/payment/plans**", async (route) => {
+    await route.fulfill({ json: apiEnvelope(phpPlans) });
+  });
+  await page.route("**/api/payment/create-order", async (route) => {
+    createOrderCount += 1;
+    await route.fulfill({
+      json: apiEnvelope({
+        orderId: `order_gcash_${response}`,
+        payParams: {
+          provider: "ezpay",
+          countryCode: "PH",
+          channelCode: "PH_QRPH_DYNAMIC",
+          channelType: "QR",
+          payData: "000201010212ph-qr-payload",
+          ...(response === "hosted"
+            ? { cashierUrl: "https://pay.example/gcash-hosted" }
+            : {}),
+          firstChargeAmountCents: 49_990,
+          currency: "PHP",
+        },
+      }),
+    });
+  });
+  await page.route("**/api/payment/order-status**", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope({
+        orderId: `order_gcash_${response}`,
+        status: "pending",
+        orderType: "dol",
+        planId: "dol_1000",
+        creditsAdded: 0,
+      }),
+    });
+  });
+
+  return {
+    getCreateOrderCount: () => createOrderCount,
+  };
+}
+
+async function preparePhilippinesUser(page: Page) {
+  await seedEmailSession(page);
+  await page.evaluate(() => {
+    const rawUser = localStorage.getItem("cozsweet:user");
+    const user = rawUser ? JSON.parse(rawUser) : {};
+    localStorage.setItem(
+      "cozsweet:user",
+      JSON.stringify({ ...user, countryCode: "PH" }),
+    );
+  });
+}
+
+test.beforeEach(async ({ baseURL, context, page }) => {
+  await clearBrowserState(context, page, baseURL);
+  await mockCoreApis(page);
+});
+
+test("Philippines checkout prefers the hosted GCash URL even for a QR response", async ({
+  page,
+}) => {
+  const payment = await registerPhilippinesPaymentMocks(page, "hosted");
+  await preparePhilippinesUser(page);
+  await page.goto("/subscription?type=topup&character=elio");
+
+  await expect(page.getByRole("button", { name: "GCash" })).toHaveAttribute(
+    "aria-pressed",
+    "true",
+  );
+  await page.getByRole("button", { name: "Pay and Top Up" }).click();
+
+  await expect(
+    page.getByRole("alertdialog", { name: "Continue to payment?" }),
+  ).toBeVisible();
+  await expect(
+    page.getByRole("dialog", { name: "Pay with GCash / QR Ph" }),
+  ).toHaveCount(0);
+  await expect(
+    page.getByRole("dialog", { name: "Scan to pay with QRIS" }),
+  ).toHaveCount(0);
+  expect(payment.getCreateOrderCount()).toBe(1);
+
+  await page.getByRole("button", { name: "Cancel" }).click();
+  await expect(page.getByRole("button", { name: "Stripe" })).toBeEnabled();
+  expect(payment.getCreateOrderCount()).toBe(1);
+});
+
+test("Philippines QR-only fallback is labeled GCash / QR Ph and can switch to Stripe", async ({
+  page,
+}) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  const payment = await registerPhilippinesPaymentMocks(page, "qr");
+  await preparePhilippinesUser(page);
+  await page.goto("/subscription?type=topup&character=elio");
+
+  await page.getByRole("button", { name: "Pay and Top Up" }).click();
+  const dialog = page.getByRole("dialog", {
+    name: "Pay with GCash / QR Ph",
+  });
+  await expect(dialog).toBeVisible();
+  await expect(dialog).toContainText(/₱\s*499\.90/);
+  await expect(dialog).not.toContainText("QRIS");
+  await expect(
+    dialog.getByRole("img", { name: "GCash / QR Ph payment QR code" }),
+  ).toBeVisible();
+
+  await dialog.getByRole("button", { name: "Close" }).click();
+  await expect(dialog).toBeHidden();
+  await expect(page.getByRole("button", { name: "Stripe" })).toBeEnabled();
+  await page.getByRole("button", { name: "Stripe" }).click();
+  await expect(page.getByRole("button", { name: "Stripe" })).toHaveAttribute(
+    "aria-pressed",
+    "true",
+  );
+  expect(payment.getCreateOrderCount()).toBe(1);
+});

e2e/specs/mock/private-zone-video.spec.ts

@@ -0,0 +1,164 @@
+import { expect, test, type Page } from "@playwright/test";
+
+import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+import { apiEnvelope } from "@e2e/fixtures/data/common";
+import {
+  clearBrowserState,
+  seedEmailSession,
+} from "@e2e/fixtures/test-helpers";
+
+const postId = "11111111-1111-1111-1111-111111111111";
+let unlocked = false;
+
+test.beforeEach(async ({ baseURL, context, page }) => {
+  unlocked = false;
+  await clearBrowserState(context, page, baseURL);
+  await mockCoreApis(page);
+  await registerPrivateZoneVideoMocks(page);
+});
+
+test("Private Zone defaults to Albums and reveals video after switching to Moments", async ({
+  page,
+}) => {
+  await seedEmailSession(page);
+
+  const listRequest = page.waitForRequest((request) => {
+    const url = new URL(request.url());
+    return (
+      url.pathname === "/api/private-zone/posts" &&
+      url.searchParams.get("characterId") === "maya-tan"
+    );
+  });
+  await page.goto("/characters/maya/private-zone");
+  await listRequest;
+
+  await expect(
+    page.getByRole("heading", { name: "Private albums" }),
+  ).toBeVisible();
+  await expect(page.getByText("Maya archive")).toBeVisible();
+  await page.getByRole("tab", { name: "Moments" }).click();
+  await expect(
+    page.getByRole("heading", { name: "Private moments" }),
+  ).toBeVisible();
+  await expect(page.getByText("Only for you.")).toBeVisible();
+  await expect(page.locator("video")).toHaveCount(0);
+
+  await page.getByRole("button", { name: "Unlock for 100 credits" }).click();
+  const dialog = page.getByRole("alertdialog");
+  await expect(dialog).toContainText("100 credits");
+  const unlockRequest = page.waitForRequest(
+    `**/api/private-zone/posts/${postId}/unlock`,
+  );
+  await dialog.getByRole("button", { name: "Unlock", exact: true }).click();
+  expect((await unlockRequest).postDataJSON()).toEqual({ expectedCost: 100 });
+
+  const video = page.locator("video");
+  await expect(video).toHaveCount(1);
+  await expect(video.locator("source")).toHaveAttribute("src", /video\.mp4/);
+  await expect(page.getByRole("alertdialog")).toHaveCount(0);
+});
+
+test("Albums render first and Moments remain available behind the second tab", async ({ page }) => {
+  await seedEmailSession(page);
+  await page.goto("/characters/maya/private-zone");
+
+  const tabs = page.getByRole("tab");
+  await expect(tabs).toHaveText(["Albums", "Moments"]);
+  await expect(page.getByRole("tab", { name: "Albums" })).toHaveAttribute(
+    "aria-selected",
+    "true",
+  );
+  await expect(
+    page.getByRole("heading", { name: "Private albums" }),
+  ).toBeVisible();
+  await expect(page.getByText("Maya archive")).toBeVisible();
+
+  await page.getByRole("tab", { name: "Moments" }).click();
+  await expect(page.getByRole("tab", { name: "Moments" })).toHaveAttribute(
+    "aria-selected",
+    "true",
+  );
+  await expect(
+    page.getByRole("heading", { name: "Private moments" }),
+  ).toBeVisible();
+});
+
+async function registerPrivateZoneVideoMocks(page: Page): Promise<void> {
+  await page.route("**/api/private-zone/posts**", async (route) => {
+    const url = new URL(route.request().url());
+    await route.fulfill({
+      json: apiEnvelope({
+        characterId: url.searchParams.get("characterId") ?? "maya-tan",
+        items: [videoPost(unlocked)],
+        nextCursor: null,
+        hasMore: false,
+        creditBalance: unlocked ? 150 : 250,
+        currency: "credits",
+      }),
+    });
+  });
+
+  // Playwright evaluates page routes in reverse registration order. Register
+  // the specific mutation last so the broader list route cannot intercept it.
+  await page.route("**/api/private-zone/posts/*/unlock", async (route) => {
+    unlocked = true;
+    await route.fulfill({
+      json: apiEnvelope({
+        postId,
+        reason: "ok",
+        unlocked: true,
+        creditsCharged: 100,
+        requiredCredits: 100,
+        currentCredits: 150,
+        shortfallCredits: 0,
+        creditBalance: 150,
+        post: videoPost(true),
+      }),
+    });
+  });
+
+  await page.route("**/api/private-zone/albums**", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope({
+        items: [
+          {
+            albumId: "album-maya",
+            title: "Maya archive",
+            content: null,
+            previewText: "Private photos",
+            imageCount: 1,
+            images: [{ url: "/images/private-zone/banner/maya.png", locked: true, index: 0 }],
+            locked: true,
+            unlocked: false,
+            unlockCost: 80,
+            publishedAt: "2026-07-24T10:00:00+00:00",
+            lockDetail: { locked: true },
+          },
+        ],
+        creditBalance: 250,
+        pendingImageCount: 0,
+        hasIncompleteContent: false,
+      }),
+    });
+  });
+}
+
+function videoPost(isUnlocked: boolean) {
+  return {
+    postId,
+    characterId: "maya-tan",
+    caption: "Only for you.",
+    posterUrl: "/images/private-zone/banner/maya.png",
+    mediaType: "video",
+    videoUrl: isUnlocked ? "/test-video.mp4?token=short" : null,
+    videoMimeType: "video/mp4",
+    videoSizeBytes: 1024,
+    durationSeconds: 18,
+    unlockCostCredits: 100,
+    currency: "credits",
+    locked: !isUnlocked,
+    unlocked: isUnlocked,
+    availableForNewUnlock: true,
+    publishedAt: "2026-07-24T10:00:00+00:00",
+  };
+}

e2e/specs/mock/unlock-message/image-unlock-insufficient-credits.spec.ts

@@ -1,20 +1,17 @@
 import { expect, test } from "@playwright/test";
 
 import { mockCoreApis } from "@e2e/fixtures/api-mocks";
-import { paidImageMessageId } from "@e2e/fixtures/test-data";
+import {
+  paidImageMessageId,
+} from "@e2e/fixtures/test-data";
 import {
   clearBrowserState,
-  defaultCharacterChatPath,
   dismissChatInterruptions,
   expectInsufficientCreditsDialog,
   expectVipChatSubscriptionUrl,
   signInWithEmailAndOpenChat,
 } from "@e2e/fixtures/test-helpers";
 
-const paidImageOverlayUrl = new RegExp(
-  `${defaultCharacterChatPath}\\?image=${paidImageMessageId}$`,
-);
-
 test.beforeEach(async ({ baseURL, context, page }) => {
   await clearBrowserState(context, page, baseURL);
   await mockCoreApis(page, {
@@ -22,30 +19,23 @@ test.beforeEach(async ({ baseURL, context, page }) => {
   });
 });
 
-test("user sees insufficient credits when unlocking a paid image from fullscreen and can navigate to subscription", async ({
+test("user sees insufficient credits when unlocking from the locked image card and can navigate to subscription", async ({
   page,
 }) => {
   await signInWithEmailAndOpenChat(page);
   await dismissChatInterruptions(page);
 
-  const paidImageButton = page.getByRole("button", {
+  const lockedImageCard = page.getByRole("group", {
-    name: "Open image in fullscreen",
+    name: "Locked private image",
   }).last();
-  await expect(paidImageButton).toBeVisible({ timeout: 10_000 });
+  await expect(lockedImageCard).toBeVisible({ timeout: 10_000 });
-
+  await expect(lockedImageCard.locator("img")).toHaveCount(0);
-  await paidImageButton.click();
-  await expect(page).toHaveURL(paidImageOverlayUrl);
-
-  const lockedImageDialog = page.getByRole("dialog", {
-    name: "Locked fullscreen image",
-  });
-  await expect(lockedImageDialog).toBeVisible();
 
   const unlockRequestPromise = page.waitForRequest(
     "**/api/chat/unlock-private",
   );
-  await lockedImageDialog
+  await lockedImageCard
-    .getByRole("button", { name: "Unlock high-definition large image" })
+    .getByRole("button", { name: "Unlock private image" })
     .click();
 
   const unlockRequest = await unlockRequestPromise;

e2e/specs/real/email-login-from-other-options.spec.ts

@@ -42,7 +42,7 @@ test.describe("pre-release email login smoke", () => {
       urlTimeout: 20_000,
     });
 
-    await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
+    await expect(page.getByRole("button", { name: "Profile" })).toBeVisible();
     await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
   });
 });

env-example/.env.local.example

@@ -5,6 +5,7 @@ NEXTAUTH_URL=https://frontend-test.banlv-ai.com
 NEXTAUTH_URL_INTERNAL=http://localhost:3000
 NEXT_PUBLIC_API_BASE_URL=https://proapi.banlv-ai.com
 NEXT_PUBLIC_WS_BASE_URL=wss://proapi.banlv-ai.com/ws
+NEXT_PUBLIC_ENABLE_VOICE_CALL=false
 NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_51Te8ybEJDtUGxQHo0UMySJ2hW0vVryynzllmIUI3UQdQCFgxNLci0Jmm2lQkRsTaIP7C7IQlFzfFyBJ5rOhr1ML800G8P8DF5R
 
 NEXT_PUBLIC_API_CONNECT_TIMEOUT=30000

env-example/.env.production.example

@@ -10,6 +10,7 @@ NEXT_PUBLIC_API_BASE_URL=https://api.banlv-ai.com
 
 # WebSocket URL（生产环境）
 NEXT_PUBLIC_WS_BASE_URL=wss://api.banlv-ai.com/ws
+NEXT_PUBLIC_ENABLE_VOICE_CALL=false
 
 # Stripe 支付（publishable key 可暴露在浏览器端）
 NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_51Te8ybEJDtUGxQHouKlEMfMuCZWifzlhBIReeKvANOtyCXS4zL0SMTWJXiFHPKz7azpF6OnIKXUPFSLs82fevVjr00w1bw5mvl

package.json

@@ -25,9 +25,9 @@
     "test:e2e:chrome": "PLAYWRIGHT_USE_SYSTEM_CHROME=1 playwright test --project=mock-chromium",
     "test:e2e:headed": "playwright test --project=mock-chromium --headed",
     "test:e2e:ui": "playwright test --ui",
-    "test:e2e:mobile-smoke": "playwright test --project=mock-mobile-chrome e2e/specs/mock/auth/email-login-from-other-options.spec.ts e2e/specs/mock/auth/logout-from-sidebar.spec.ts e2e/specs/mock/chat/chat-send-token-refresh-retry.spec.ts e2e/specs/mock/unlock-message/image-unlock-insufficient-credits.spec.ts",
+    "test:e2e:mobile-smoke": "playwright test --project=mock-mobile-chrome e2e/specs/mock/auth/email-login-from-other-options.spec.ts e2e/specs/mock/auth/logout-from-profile.spec.ts e2e/specs/mock/chat/chat-send-token-refresh-retry.spec.ts e2e/specs/mock/unlock-message/image-unlock-insufficient-credits.spec.ts",
     "test:e2e:real": "E2E_REAL_BACKEND=1 PLAYWRIGHT_BASE_URL=${PLAYWRIGHT_BASE_URL:-https://frontend-test.banlv-ai.com} E2E_API_BASE_URL=${E2E_API_BASE_URL:-https://proapi.banlv-ai.com} playwright test --project=real-backend",
-    "test:e2e:prod": "E2E_REAL_BACKEND=1 PLAYWRIGHT_BASE_URL=${PLAYWRIGHT_BASE_URL:-https://cozsweet.com} E2E_API_BASE_URL=${E2E_API_BASE_URL:-https://proapi.banlv-ai.com} playwright test --project=prod-smoke",
+    "test:e2e:prod": "E2E_REAL_BACKEND=1 PLAYWRIGHT_BASE_URL=${PLAYWRIGHT_BASE_URL:-https://cozsweet.com} E2E_API_BASE_URL=${E2E_API_BASE_URL:-https://api.banlv-ai.com} playwright test --project=prod-smoke",
     "contract:check": "node scripts/contracts/check-openapi.mjs",
     "test:contracts": "node --test scripts/contracts/__tests__/*.test.mjs",
     "perf:bundle": "next experimental-analyze --output && node scripts/performance/report-bundle.mjs",
@@ -50,6 +50,7 @@
     "next-auth": "^4.24.14",
     "ofetch": "^1.5.1",
     "pino": "^10.3.1",
+    "qrcode.react": "^4.2.0",
     "react": "19.2.4",
     "react-dom": "19.2.4",
     "react-icons": "^5.6.0",

playwright.config.ts

@@ -12,7 +12,10 @@ export default defineConfig({
   fullyParallel: true,
   forbidOnly: Boolean(process.env.CI),
   retries: process.env.CI ? 2 : 0,
-  workers: process.env.CI ? 1 : undefined,
+  // Next.js dev + Turbopack can return incomplete module payloads when the
+  // local mock suite compiles many routes concurrently. Keep this tier
+  // deterministic locally as well as in CI.
+  workers: 1,
   reporter: process.env.CI
     ? [["list"], ["html", { open: "never" }]]
     : [["list"], ["html", { open: "never" }]],

pnpm-lock.yaml

@@ -50,6 +50,9 @@ importers:
       pino:
         specifier: ^10.3.1
         version: 10.3.1
+      qrcode.react:
+        specifier: ^4.2.0
+        version: 4.2.0(react@19.2.4)
       react:
         specifier: 19.2.4
         version: 19.2.4
@@ -3290,6 +3293,11 @@ packages:
     resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
     engines: {node: '>=6'}
 
+  qrcode.react@4.2.0:
+    resolution: {integrity: sha512-QpgqWi8rD9DsS9EP3z7BT+5lY5SFhsqGjpgW5DY/i3mK4M9DTBNz3ErMi8BWYEfI3L0d8GIbGmcdFAS1uIRGjA==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
   queue-microtask@1.2.3:
     resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==}
 
@@ -7085,6 +7093,10 @@ snapshots:
 
   punycode@2.3.1: {}
 
+  qrcode.react@4.2.0(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+
   queue-microtask@1.2.3: {}
 
   quick-format-unescaped@4.0.4: {}

public/manifest.json

@@ -11,13 +11,13 @@
   "lang": "en",
   "icons": [
     {
-      "src": "/images/icons/Icon-192.png",
+      "src": "/images/icons/Icon-192.png?v=20260724",
       "sizes": "192x192",
       "type": "image/png",
       "purpose": "any"
     },
     {
-      "src": "/images/icons/Icon-512.png",
+      "src": "/images/icons/Icon-512.png?v=20260724",
       "sizes": "512x512",
       "type": "image/png",
       "purpose": "any"

scripts/contracts/__tests__/domestic-test-workflow.test.mjs

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+
+const workflowUrl = new URL(
+  "../../../.gitea/workflows/domestic-test.yml",
+  import.meta.url,
+);
+const deployScriptUrl = new URL(
+  "../../server/deploy-domestic-test-archive.sh",
+  import.meta.url,
+);
+
+test("domestic frontend workflow is manual and registry-free", async () => {
+  const workflow = await readFile(workflowUrl, "utf8");
+
+  assert.match(workflow, /workflow_dispatch:/);
+  assert.doesNotMatch(workflow, /\bpush:/);
+  assert.doesNotMatch(workflow, /REGISTRY_IMAGE/);
+  assert.match(workflow, /docker save/);
+  assert.match(workflow, /DOMESTIC_TEST_SSH_PRIVATE_KEY_B64/);
+  assert.match(workflow, /base64 -d/);
+});
+
+test("domestic frontend workflow pins the China test API and isolated port", async () => {
+  const workflow = await readFile(workflowUrl, "utf8");
+  const deployScript = await readFile(deployScriptUrl, "utf8");
+
+  assert.match(workflow, /https:\/\/testapi\.banlv-ai\.com/);
+  assert.match(workflow, /wss:\/\/testapi\.banlv-ai\.com\/ws/);
+  assert.match(workflow, /9135/);
+  assert.match(deployScript, /127\.0\.0\.1:\$HOST_PORT/);
+  assert.match(deployScript, /cozsweet-frontend-domestic-test/);
+});

scripts/contracts/__tests__/openapi-contract.test.mjs

@@ -13,13 +13,13 @@ describe("OpenAPI contract comparison", () => {
         chatHistory: { method: "get", path: "/api/chat/history" },
         unlockAlbum: {
           method: "post",
-          path: "/api/private-room/albums/{albumId}/unlock",
+          path: "/api/private-zone/albums/{albumId}/unlock",
         },
       },
       {
         paths: {
           "/api/chat/history": { get: {} },
-          "/api/private-room/albums/{album_id}/unlock/": { post: {} },
+          "/api/private-zone/albums/{album_id}/unlock/": { post: {} },
         },
       },
     );

scripts/deploy/_deploy_lib.sh

@@ -3,7 +3,7 @@
 # 推送指定分支到指定远端。
 # 当前发布由 Gitea Actions 构建镜像并通过 SSH 部署；本脚本只负责触发分支 push。
 # 调用方：deploy_web.sh（production）→ push_to_remote "gitea" "main"
-#        deploy_web_test.sh（test）→ push_to_remote "gitea" "test"
+#        deploy_web_test.sh（pre）→ push_to_remote "gitea" "pre"
 push_to_remote() {
     local remote="$1"
     local branch="$2"

scripts/deploy/deploy_web_test.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # ==========================================
-# 测试环境 Web 部署脚本（Next.js + Gitea Actions SSH 部署模型）
+# 预发环境 Web 部署脚本（Next.js + Gitea Actions SSH 部署模型）
 # 原始 Dart: scripts/deploy/deploy_web_test.sh
 # ==========================================
 
@@ -11,7 +11,7 @@ source "$SCRIPT_DIR/_deploy_lib.sh"
 
 # 主函数
 main() {
-    push_to_remote "gitea" "test"
+    push_to_remote "gitea" "pre"
 }
 
 main

scripts/release/pre_release_web.sh

@@ -11,9 +11,9 @@ unset_git_hook_env() {
 
 unset_git_hook_env
 
-# Test 分支 worktree 路径
+# pre 分支 worktree 路径
-WORKTREE_PATH="/Users/chase/Documents/frontend/cozsweet-frontend-nextjs.worktrees/cozsweet-nextjs-test"
+WORKTREE_PATH="/Users/chase/Documents/frontend/cozsweet-frontend-nextjs.worktrees/cozsweet-nextjs-pre"
-echo "=== 进入 test 分支 worktree ==="
+echo "=== 进入 pre 分支 worktree ==="
 cd "$WORKTREE_PATH" || { echo "错误: 无法进入 $WORKTREE_PATH"; exit 1; }
 
 echo "=== 检查当前分支 ==="
@@ -22,17 +22,17 @@ git branch --show-current
 echo "=== 变基到 dev 分支 ==="
 git rebase dev
 
-# 复制测试环境图标（source: $WORKTREE_PATH/icons/test → dest: $WORKTREE_PATH/public/）
+# 复制预发环境图标（运行资源目录仍为 icons/test）
-echo "=== 复制测试环境图标（icons/test → public/） ==="
+echo "=== 复制预发环境图标（icons/test → public/） ==="
 cp -f "$WORKTREE_PATH/icons/test/favicon.ico" "$WORKTREE_PATH/public/favicon.ico"
 cp -f "$WORKTREE_PATH/icons/test/icons/Icon-192.png" "$WORKTREE_PATH/public/images/icons/Icon-192.png"
 cp -f "$WORKTREE_PATH/icons/test/icons/Icon-512.png" "$WORKTREE_PATH/public/images/icons/Icon-512.png"
 
-# 准备测试环境变量（$WORKTREE_PATH/env-example/.env.local.example → $WORKTREE_PATH/.env.local）
+# 准备预发环境变量（运行配置仍使用 .env.local）
-echo "=== 准备测试环境变量（env-example/.env.local.example → .env.local） ==="
+echo "=== 准备预发环境变量（env-example/.env.local.example → .env.local） ==="
 cp -f "$WORKTREE_PATH/env-example/.env.local.example" "$WORKTREE_PATH/.env.local"
 
-echo "=== 执行构建部署脚本（测试环境）==="
+echo "=== 执行构建部署脚本（预发环境）==="
 ./scripts/deploy/deploy_web_test.sh
 
 echo "=== 预发布完成 ==="

scripts/server/deploy-docker-image.sh

@@ -49,8 +49,6 @@ echo "=== compose project: $COMPOSE_PROJECT_NAME ==="
 "${COMPOSE[@]}" up -d --remove-orphans --no-build web
 "${COMPOSE[@]}" ps
 
-docker image prune -f
-
 prune_project_images() {
   local retain_count="$1"
   if ! [[ "$retain_count" =~ ^[0-9]+$ ]] || [ "$retain_count" -le 0 ]; then

scripts/server/deploy-domestic-test-archive.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ARCHIVE="${1:-}"
+IMAGE="${2:-}"
+ENV_FILE="${3:-}"
+HOST_PORT="${4:-9135}"
+CONTAINER_NAME="cozsweet-frontend-domestic-test"
+INTERNAL_PORT="3000"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SERVICE_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+SHARED_ROOT="$SERVICE_ROOT/shared"
+RELEASE_ROOT="$SERVICE_ROOT/releases/docker"
+
+if [ -z "$ARCHIVE" ] || [ -z "$IMAGE" ] || [ -z "$ENV_FILE" ]; then
+  echo "Usage: $0 <image-archive> <image> <env-file> [host-port]" >&2
+  exit 64
+fi
+if [ "$HOST_PORT" != "9135" ]; then
+  echo "Domestic frontend test must use isolated host port 9135" >&2
+  exit 64
+fi
+case "$ENV_FILE" in
+  "$SHARED_ROOT"/*) ;;
+  *)
+    echo "Environment file must be stored under $SHARED_ROOT" >&2
+    exit 64
+    ;;
+esac
+if [ ! -s "$ARCHIVE" ] || [ ! -s "$ENV_FILE" ]; then
+  echo "Image archive or environment file is missing" >&2
+  exit 66
+fi
+
+mkdir -p "$RELEASE_ROOT"
+chmod 700 "$SHARED_ROOT"
+gzip -dc "$ARCHIVE" | docker load >/dev/null
+docker image inspect "$IMAGE" >/dev/null
+
+old_image_id=""
+old_image_ref=""
+if docker container inspect "$CONTAINER_NAME" >/dev/null 2>&1; then
+  old_image_id="$(docker inspect -f '{{.Image}}' "$CONTAINER_NAME")"
+  old_image_ref="$(docker inspect -f '{{.Config.Image}}' "$CONTAINER_NAME")"
+elif ss -ltnH "sport = :$HOST_PORT" 2>/dev/null | grep -q .; then
+  echo "Host port $HOST_PORT is already used by another service" >&2
+  exit 69
+fi
+
+run_container() {
+  local image_ref="$1"
+  docker run -d \
+    --name "$CONTAINER_NAME" \
+    --restart unless-stopped \
+    -p "127.0.0.1:$HOST_PORT:$INTERNAL_PORT" \
+    --env-file "$ENV_FILE" \
+    -e "PORT=$INTERNAL_PORT" \
+    "$image_ref" >/dev/null
+}
+
+wait_healthy() {
+  local deadline=$((SECONDS + 180))
+  while [ "$SECONDS" -le "$deadline" ]; do
+    state="$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}' "$CONTAINER_NAME" 2>/dev/null || true)"
+    status="$(curl -sS -o /dev/null -w '%{http_code}' "http://127.0.0.1:$HOST_PORT/" 2>/dev/null || true)"
+    if [[ "$status" =~ ^(200|204|301|302|303|307|308)$ ]] && { [ "$state" = "healthy" ] || [ "$state" = "running" ]; }; then
+      return 0
+    fi
+    sleep 2
+  done
+  return 1
+}
+
+docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true
+deployment_ok="1"
+if ! run_container "$IMAGE"; then
+  deployment_ok="0"
+elif ! wait_healthy; then
+  deployment_ok="0"
+fi
+
+if [ "$deployment_ok" != "1" ]; then
+  docker logs --tail 120 "$CONTAINER_NAME" >&2 || true
+  docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true
+  if [ -n "$old_image_id" ] && docker image inspect "$old_image_id" >/dev/null 2>&1; then
+    echo "New container failed health checks; restoring previous image" >&2
+    run_container "$old_image_id"
+    wait_healthy || true
+  fi
+  exit 1
+fi
+
+created_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+image_id="$(docker image inspect "$IMAGE" -f '{{.Id}}')"
+record="{\"createdAt\":\"$created_at\",\"environment\":\"domestic-test\",\"image\":\"$IMAGE\",\"imageId\":\"$image_id\",\"container\":\"$CONTAINER_NAME\",\"hostPort\":$HOST_PORT}"
+if [ -f "$RELEASE_ROOT/current.json" ]; then
+  cp "$RELEASE_ROOT/current.json" "$RELEASE_ROOT/previous.json"
+fi
+printf '%s\n' "$record" > "$RELEASE_ROOT/current.json"
+printf '%s\n' "$record" >> "$RELEASE_ROOT/releases.jsonl"
+
+echo "Domestic frontend test is healthy"
+echo "container=$CONTAINER_NAME"
+echo "host_port=$HOST_PORT"
+echo "image=$IMAGE"
+if [ -n "$old_image_ref" ]; then
+  echo "previous_image=$old_image_ref"
+fi

src/app/_components/__tests__/tailwind-components.test.tsx

@@ -79,4 +79,34 @@ describe("shared Tailwind components", () => {
     expect(guestHtml).toContain('aria-label="Guest avatar"');
     expect(guestHtml).toContain("%2Fimages%2Favatar%2Fplaceholder.png");
   });
+
+  it("renders interactive avatars as accessible buttons", () => {
+    const characterHtml = renderToStaticMarkup(
+      <CharacterAvatar
+        src="/images/avatar/elio.png"
+        alt="Elio Silvestri"
+        actionLabel="Open Elio's private zone"
+        analyticsKey="chat.open_private_zone_from_avatar"
+        onClick={() => undefined}
+      />,
+    );
+    const userHtml = renderToStaticMarkup(
+      <UserMessageAvatar
+        actionLabel="Open profile"
+        analyticsKey="chat.open_profile_from_avatar"
+        onClick={() => undefined}
+      />,
+    );
+
+    expect(characterHtml).toContain('<button type="button"');
+    expect(characterHtml).toContain(
+      'aria-label="Open Elio&#x27;s private zone"',
+    );
+    expect(characterHtml).toContain(
+      'data-analytics-key="chat.open_private_zone_from_avatar"',
+    );
+    expect(userHtml).toContain('<button type="button"');
+    expect(userHtml).toContain('aria-label="Open profile"');
+    expect(userHtml).toContain("focus-visible:outline-3");
+  });
 });

src/app/_components/avatar-interaction.ts

@@ -0,0 +1,11 @@
+export type AvatarInteractionProps =
+  | {
+      onClick?: undefined;
+      actionLabel?: never;
+      analyticsKey?: never;
+    }
+  | {
+      onClick: () => void;
+      actionLabel: string;
+      analyticsKey?: string;
+    };

src/app/_components/character-avatar.tsx

@@ -3,7 +3,9 @@
 import Image from "next/image";
 import type { CSSProperties } from "react";
 
-export interface CharacterAvatarProps {
+import type { AvatarInteractionProps } from "./avatar-interaction";
+
+interface CharacterAvatarVisualProps {
   src: string;
   alt: string;
   className?: string;
@@ -12,6 +14,9 @@ export interface CharacterAvatarProps {
   priority?: boolean;
 }
 
+export type CharacterAvatarProps = CharacterAvatarVisualProps &
+  AvatarInteractionProps;
+
 export function CharacterAvatar({
   src,
   alt,
@@ -19,6 +24,9 @@ export function CharacterAvatar({
   size = 43,
   imageSize,
   priority = false,
+  onClick,
+  actionLabel,
+  analyticsKey,
 }: CharacterAvatarProps) {
   const resolvedImageSize =
     imageSize ?? (typeof size === "number" ? size : 96);
@@ -27,24 +35,45 @@ export function CharacterAvatar({
     height: size,
   };
 
+  const avatarClassName = [
+    "inline-flex shrink-0 items-center justify-center overflow-hidden rounded-full border-0 bg-(--color-avatar-border,#fbf3f5)",
+    onClick
+      ? "cursor-pointer p-0 transition-transform duration-150 focus-visible:outline-3 focus-visible:outline-offset-3 focus-visible:outline-accent active:scale-96"
+      : undefined,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+  const image = (
+    <Image
+      src={src}
+      alt={alt}
+      width={resolvedImageSize}
+      height={resolvedImageSize}
+      priority={priority}
+      className="size-full object-cover"
+    />
+  );
+
+  if (onClick) {
+    return (
+      <button
+        type="button"
+        className={avatarClassName}
+        style={style}
+        aria-label={actionLabel}
+        data-analytics-key={analyticsKey}
+        data-analytics-label={actionLabel}
+        onClick={onClick}
+      >
+        {image}
+      </button>
+    );
+  }
+
   return (
-    <span
+    <span className={avatarClassName} style={style}>
-      className={[
+      {image}
-        "inline-flex shrink-0 items-center justify-center overflow-hidden rounded-full bg-(--color-avatar-border,#fbf3f5)",
-        className,
-      ]
-        .filter(Boolean)
-        .join(" ")}
-      style={style}
-    >
-      <Image
-        src={src}
-        alt={alt}
-        width={resolvedImageSize}
-        height={resolvedImageSize}
-        priority={priority}
-        className="size-full object-cover"
-      />
     </span>
   );
 }

src/app/_components/core/__tests__/favorite-entry-button.test.tsx

@@ -0,0 +1,80 @@
+/* @vitest-environment jsdom */
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { BrowserDetector } from "@/utils/browser-detect";
+import { PlatformDetector } from "@/utils/platform-detect";
+import { pwaUtil } from "@/utils/pwa";
+
+import { FavoriteEntryButton } from "../favorite-entry-button";
+
+describe("FavoriteEntryButton install flow", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
+      .IS_REACT_ACT_ENVIRONMENT = true;
+    window.localStorage.setItem("cozsweet:favorite_entry", "1");
+    vi.spyOn(BrowserDetector, "isInAppBrowser").mockReturnValue(false);
+    vi.spyOn(pwaUtil, "isInstalled").mockReturnValue(false);
+    vi.spyOn(pwaUtil, "prepareInstallPrompt").mockImplementation(() => undefined);
+    vi.spyOn(pwaUtil, "subscribe").mockReturnValue(() => undefined);
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    window.localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("shows Download on iOS and opens Safari add-to-home instructions", () => {
+    vi.spyOn(PlatformDetector, "isIOS").mockReturnValue(true);
+    vi.spyOn(PlatformDetector, "isAndroid").mockReturnValue(false);
+
+    renderButton();
+    const downloadButton = getButton("Download");
+    act(() => downloadButton.click());
+
+    expect(container.querySelector('[role="dialog"]')).not.toBeNull();
+    expect(container.textContent).toContain("Add CozSweet to Home Screen");
+    expect(container.textContent).toContain(
+      "In Safari, tap the Share button, then choose “Add to Home Screen”.",
+    );
+  });
+
+  it("opens the native Android install prompt and marks an accepted install as Saved", async () => {
+    vi.spyOn(PlatformDetector, "isIOS").mockReturnValue(false);
+    vi.spyOn(PlatformDetector, "isAndroid").mockReturnValue(true);
+    const install = vi.spyOn(pwaUtil, "install").mockResolvedValue("accepted");
+
+    renderButton();
+    await act(async () => {
+      getButton("Download").click();
+      await Promise.resolve();
+    });
+
+    expect(install).toHaveBeenCalledTimes(1);
+    expect(getButton("Saved")).not.toBeNull();
+  });
+
+  function renderButton(): void {
+    act(() => {
+      root.render(<FavoriteEntryButton characterSlug="elio" />);
+    });
+  }
+
+  function getButton(label: string): HTMLButtonElement {
+    const button = container.querySelector<HTMLButtonElement>(
+      `button[aria-label="${label}"]`,
+    );
+    if (!button) throw new Error(`Missing button: ${label}`);
+    return button;
+  }
+});

src/app/_components/core/__tests__/modal-portal.test.tsx

@@ -0,0 +1,119 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ModalPortal } from "../modal-portal";
+
+describe("ModalPortal", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
+      .IS_REACT_ACT_ENVIRONMENT = true;
+    container = document.createElement("div");
+    container.style.transform = "translateX(50%)";
+    document.body.appendChild(container);
+    document.body.style.overflow = "auto";
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    document.body.style.overflow = "";
+  });
+
+  it("portals outside transformed ancestors and exposes dialog semantics", () => {
+    const onClose = vi.fn();
+
+    act(() =>
+      root.render(
+        <ModalPortal
+          open
+          onClose={onClose}
+          scrimClassName="fixed inset-0"
+          panelClassName="payment-panel"
+          scrimOpacity={0.5}
+          role="alertdialog"
+          ariaLabelledBy="payment-title"
+          ariaDescribedBy="payment-description"
+        >
+          <h2 id="payment-title">Complete payment</h2>
+          <p id="payment-description">Choose a payment method.</p>
+        </ModalPortal>,
+      ),
+    );
+
+    const dialog = document.body.querySelector('[role="alertdialog"]');
+    expect(dialog).not.toBeNull();
+    expect(container.contains(dialog)).toBe(false);
+    expect(dialog?.parentElement?.parentElement).toBe(document.body);
+    expect(dialog?.getAttribute("aria-labelledby")).toBe("payment-title");
+    expect(dialog?.getAttribute("aria-describedby")).toBe(
+      "payment-description",
+    );
+    expect(document.body.style.overflow).toBe("hidden");
+  });
+
+  it("restores the previous body overflow after the final modal closes", () => {
+    const renderModals = (showFirst: boolean, showSecond: boolean) => (
+      <>
+        <ModalPortal
+          open={showFirst}
+          onClose={() => undefined}
+          scrimClassName="first-scrim"
+          panelClassName="first-panel"
+          scrimOpacity={0.4}
+        >
+          First
+        </ModalPortal>
+        <ModalPortal
+          open={showSecond}
+          onClose={() => undefined}
+          scrimClassName="second-scrim"
+          panelClassName="second-panel"
+          scrimOpacity={0.4}
+        >
+          Second
+        </ModalPortal>
+      </>
+    );
+
+    act(() => root.render(renderModals(true, true)));
+    expect(document.body.style.overflow).toBe("hidden");
+
+    act(() => root.render(renderModals(false, true)));
+    expect(document.body.style.overflow).toBe("hidden");
+
+    act(() => root.render(renderModals(false, false)));
+    expect(document.body.style.overflow).toBe("auto");
+  });
+
+  it("keeps persistent payment modals open on scrim click and Escape", () => {
+    const onClose = vi.fn();
+
+    act(() =>
+      root.render(
+        <ModalPortal
+          open
+          persistent
+          onClose={onClose}
+          scrimClassName="fixed inset-0"
+          panelClassName="payment-panel"
+          scrimOpacity={0.5}
+        >
+          Payment
+        </ModalPortal>,
+      ),
+    );
+
+    const scrim = document.body.querySelector(".fixed.inset-0");
+    act(() => scrim?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    act(() =>
+      document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })),
+    );
+
+    expect(onClose).not.toHaveBeenCalled();
+  });
+});

src/app/_components/core/__tests__/tailwind-components.test.tsx

@@ -79,18 +79,20 @@ describe("core Tailwind components", () => {
       <AppBottomNav
         activeItem="chat"
         variant="dark"
-        privateRoomLabel="Maya Private room"
+        privateZoneLabel="Maya Private Zone"
         onChatClick={() => undefined}
-        onPrivateRoomClick={() => undefined}
+        onPrivateZoneClick={() => undefined}
+        onMenuClick={() => undefined}
       />,
     );
-    const privateRoomHtml = renderToStaticMarkup(
+    const privateZoneHtml = renderToStaticMarkup(
       <AppBottomNav
-        activeItem="privateRoom"
+        activeItem="privateZone"
         variant="warm"
-        privateRoomLabel="Maya Private room"
+        privateZoneLabel="Maya Private Zone"
         onChatClick={() => undefined}
-        onPrivateRoomClick={() => undefined}
+        onPrivateZoneClick={() => undefined}
+        onMenuClick={() => undefined}
       />,
     );
 
@@ -99,13 +101,15 @@ describe("core Tailwind components", () => {
     expect(chatHtml).toMatch(
       /<button[^>]*aria-current="page"[^>]*>.*?<span>Chat<\/span>/,
     );
-    expect(privateRoomHtml).toMatch(/class="[^"]*warm[^"]*"/);
+    expect(privateZoneHtml).toMatch(/class="[^"]*warm[^"]*"/);
-    expect(privateRoomHtml).toMatch(
+    expect(privateZoneHtml).toMatch(
-      /<button[^>]*aria-current="page"[^>]*>.*?<span>Maya Private room<\/span>/,
+      /<button[^>]*aria-current="page"[^>]*>.*?<span>Maya Private Zone<\/span>/,
     );
     expect(chatHtml).toContain('data-analytics-key="navigation.chat"');
-    expect(privateRoomHtml).toContain(
+    expect(privateZoneHtml).toContain(
-      'data-analytics-key="navigation.private_room"',
+      'data-analytics-key="navigation.private_zone"',
     );
+    expect(chatHtml).toContain('data-analytics-key="navigation.menu"');
+    expect(chatHtml).toContain("<span>Menu</span>");
   });
 });

src/app/_components/core/app-bottom-nav.module.css

@@ -4,7 +4,7 @@
   left: 50%;
   z-index: 30;
   display: grid;
-  grid-template-columns: 1fr 1fr;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
   box-sizing: border-box;
   width: min(100vw, var(--app-max-width, 540px));
   min-height: calc(

src/app/_components/core/app-bottom-nav.tsx

@@ -1,26 +1,28 @@
 "use client";
 
-import { Camera, MessageCircle } from "lucide-react";
+import { Camera, Menu as MenuIcon, MessageCircle } from "lucide-react";
 
 import styles from "./app-bottom-nav.module.css";
 
-export type AppBottomNavItem = "chat" | "privateRoom";
+export type AppBottomNavItem = "chat" | "privateZone" | "menu";
 export type AppBottomNavVariant = "warm" | "dark";
 
 export interface AppBottomNavProps {
   activeItem?: AppBottomNavItem | null;
   variant?: AppBottomNavVariant;
-  privateRoomLabel: string;
+  privateZoneLabel: string;
   onChatClick: () => void;
-  onPrivateRoomClick: () => void;
+  onPrivateZoneClick: () => void;
+  onMenuClick: () => void;
 }
 
 export function AppBottomNav({
   activeItem = null,
   variant = "warm",
-  privateRoomLabel,
+  privateZoneLabel,
   onChatClick,
-  onPrivateRoomClick,
+  onPrivateZoneClick,
+  onMenuClick,
 }: AppBottomNavProps) {
   return (
     <nav className={getRootClass(variant)} aria-label="Primary navigation">
@@ -37,14 +39,25 @@ export function AppBottomNav({
       </button>
       <button
         type="button"
-        data-analytics-key="navigation.private_room"
+        data-analytics-key="navigation.private_zone"
-        data-analytics-label="Private room navigation"
+        data-analytics-label="Private Zone navigation"
-        className={getButtonClass(activeItem === "privateRoom")}
+        className={getButtonClass(activeItem === "privateZone")}
-        aria-current={activeItem === "privateRoom" ? "page" : undefined}
+        aria-current={activeItem === "privateZone" ? "page" : undefined}
-        onClick={onPrivateRoomClick}
+        onClick={onPrivateZoneClick}
       >
         <Camera size={20} aria-hidden="true" />
-        <span>{privateRoomLabel}</span>
+        <span>{privateZoneLabel}</span>
+      </button>
+      <button
+        type="button"
+        data-analytics-key="navigation.menu"
+        data-analytics-label="Menu navigation"
+        className={getButtonClass(activeItem === "menu")}
+        aria-current={activeItem === "menu" ? "page" : undefined}
+        onClick={onMenuClick}
+      >
+        <MenuIcon size={20} aria-hidden="true" />
+        <span>Menu</span>
       </button>
     </nav>
   );

src/app/_components/core/favorite-entry-button.module.css

@@ -0,0 +1,175 @@
+.wrap {
+  position: relative;
+  display: inline-flex;
+  flex: 0 0 auto;
+  justify-content: flex-end;
+}
+
+.button {
+  display: inline-flex;
+  min-width: var(--responsive-icon-button-size, 42px);
+  height: var(--responsive-icon-button-size, 42px);
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  box-sizing: border-box;
+  padding: 0 11px;
+  border: 1px solid var(--favorite-border);
+  border-radius: 999px;
+  background: var(--favorite-background);
+  color: var(--favorite-color);
+  cursor: pointer;
+  font: inherit;
+  font-size: 12px;
+  font-weight: 850;
+  line-height: 1;
+  box-shadow: var(--favorite-shadow);
+  backdrop-filter: blur(16px);
+  transition: background 160ms ease, transform 160ms ease,
+    box-shadow 160ms ease;
+  -webkit-tap-highlight-color: transparent;
+}
+
+.dark {
+  --favorite-background: rgba(18, 15, 24, 0.72);
+  --favorite-border: rgba(255, 255, 255, 0.22);
+  --favorite-color: #ffffff;
+  --favorite-shadow: 0 10px 26px rgba(0, 0, 0, 0.24);
+}
+
+.light {
+  --favorite-background: rgba(255, 255, 255, 0.88);
+  --favorite-border: rgba(43, 27, 34, 0.1);
+  --favorite-color: #34272c;
+  --favorite-shadow: 0 10px 24px rgba(74, 48, 58, 0.1);
+}
+
+.favorite {
+  width: var(--responsive-icon-button-size, 42px);
+  padding: 0;
+}
+
+.download {
+  color: #ffffff;
+  background: linear-gradient(135deg, #ff76ab, #f84d96);
+  border-color: rgba(255, 255, 255, 0.42);
+  box-shadow: 0 10px 25px rgba(248, 77, 150, 0.3);
+}
+
+.saved {
+  color: #f84d96;
+}
+
+.button:hover {
+  transform: translateY(-1px);
+  box-shadow: 0 13px 30px rgba(0, 0, 0, 0.2);
+}
+
+.button:active {
+  transform: translateY(1px) scale(0.98);
+}
+
+.button:focus-visible {
+  outline: 2px solid #ffffff;
+  outline-offset: 3px;
+}
+
+.light:focus-visible {
+  outline-color: #f84d96;
+}
+
+.guideBackdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 240;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding:
+    calc(18px + var(--app-safe-top, 0px))
+    calc(18px + var(--app-safe-right, 0px))
+    calc(18px + var(--app-safe-bottom, 0px))
+    calc(18px + var(--app-safe-left, 0px));
+  background: rgba(15, 11, 18, 0.58);
+  backdrop-filter: blur(4px);
+}
+
+.guideDialog {
+  position: relative;
+  display: flex;
+  width: min(100%, 340px);
+  flex-direction: column;
+  align-items: center;
+  padding: 28px 22px 20px;
+  border: 1px solid rgba(255, 255, 255, 0.72);
+  border-radius: 28px;
+  background: rgba(255, 250, 252, 0.98);
+  box-shadow: 0 24px 70px rgba(33, 17, 26, 0.3);
+  color: #2d2026;
+  text-align: center;
+}
+
+.guideClose {
+  position: absolute;
+  top: 12px;
+  right: 12px;
+  display: inline-flex;
+  width: 36px;
+  height: 36px;
+  align-items: center;
+  justify-content: center;
+  border: 0;
+  border-radius: 999px;
+  background: rgba(45, 32, 38, 0.07);
+  color: #5b4a52;
+  cursor: pointer;
+}
+
+.guideIcon {
+  display: inline-flex;
+  width: 58px;
+  height: 58px;
+  align-items: center;
+  justify-content: center;
+  margin-bottom: 14px;
+  border-radius: 19px;
+  background: linear-gradient(135deg, #ff82b2, #f84d96);
+  box-shadow: 0 12px 26px rgba(248, 77, 150, 0.26);
+  color: #ffffff;
+}
+
+.guideDialog h2 {
+  margin: 0;
+  color: #281a21;
+  font-size: 21px;
+  font-weight: 850;
+  line-height: 1.2;
+}
+
+.guideDialog p {
+  margin: 12px 0 20px;
+  color: #685761;
+  font-size: 15px;
+  font-weight: 650;
+  line-height: 1.5;
+}
+
+.guideConfirm {
+  width: 100%;
+  min-height: 46px;
+  border: 0;
+  border-radius: 999px;
+  background: linear-gradient(135deg, #ff76ab, #f84d96);
+  box-shadow: 0 10px 24px rgba(248, 77, 150, 0.24);
+  color: #ffffff;
+  cursor: pointer;
+  font: inherit;
+  font-size: 16px;
+  font-weight: 850;
+}
+
+.guideClose:focus-visible,
+.guideConfirm:focus-visible {
+  outline: 2px solid #f84d96;
+  outline-offset: 3px;
+}

src/app/_components/core/favorite-entry-button.tsx

@@ -0,0 +1,162 @@
+"use client";
+
+import { useEffect, useId, useState } from "react";
+import { Download, Share2, Star, X } from "lucide-react";
+
+import { openChatInExternalBrowser } from "@/lib/chat/chat_external_browser";
+import {
+  hasPersistedFavoriteEntryIntent,
+  resolveFavoriteEntryMode,
+  type FavoriteEntryMode,
+} from "@/lib/navigation/favorite_entry";
+import { BrowserDetector } from "@/utils/browser-detect";
+import { PlatformDetector } from "@/utils/platform-detect";
+import { pwaUtil } from "@/utils/pwa";
+
+import styles from "./favorite-entry-button.module.css";
+
+export interface FavoriteEntryButtonProps {
+  characterSlug: string;
+  tone?: "dark" | "light";
+}
+
+export function FavoriteEntryButton({
+  characterSlug,
+  tone = "dark",
+}: FavoriteEntryButtonProps) {
+  const [mode, setMode] = useState<FavoriteEntryMode>("favorite");
+  const [installGuide, setInstallGuide] = useState<
+    "ios" | "browser" | null
+  >(null);
+  const installGuideTitleId = useId();
+
+  useEffect(() => {
+    const updateMode = () => {
+      setMode(
+        resolveFavoriteEntryMode({
+          hasFavoriteIntent: hasPersistedFavoriteEntryIntent(),
+          isAndroid: PlatformDetector.isAndroid(),
+          isIOS: PlatformDetector.isIOS(),
+          isInAppBrowser: BrowserDetector.isInAppBrowser(),
+          isInstalled: pwaUtil.isInstalled(),
+        }),
+      );
+    };
+
+    pwaUtil.prepareInstallPrompt();
+    updateMode();
+    const unsubscribe = pwaUtil.subscribe(updateMode);
+    return unsubscribe;
+  }, []);
+
+  useEffect(() => {
+    if (!installGuide) return;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setInstallGuide(null);
+    };
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [installGuide]);
+
+  const handleClick = async (): Promise<void> => {
+    if (mode === "favorite") {
+      await openChatInExternalBrowser({ characterSlug });
+      return;
+    }
+
+    if (mode === "download") {
+      if (PlatformDetector.isIOS()) {
+        setInstallGuide("ios");
+        return;
+      }
+      pwaUtil.prepareInstallPrompt();
+      const result = await pwaUtil.install();
+      if (result === "accepted" || pwaUtil.isInstalled()) {
+        setMode("saved");
+        setInstallGuide(null);
+        return;
+      }
+      if (result === "unavailable") setInstallGuide("browser");
+    }
+  };
+
+  const label = getFavoriteEntryLabel(mode);
+
+  return (
+    <div className={styles.wrap}>
+      <button
+        type="button"
+        data-analytics-key={`favorite.${mode}`}
+        data-analytics-label={label}
+        className={[styles.button, styles[tone], styles[mode]]
+          .filter(Boolean)
+          .join(" ")}
+        aria-label={label}
+        aria-pressed={mode === "saved"}
+        onClick={() => void handleClick()}
+      >
+        {mode === "download" ? (
+          <Download size={16} strokeWidth={2.4} aria-hidden="true" />
+        ) : (
+          <Star
+            size={21}
+            strokeWidth={2.3}
+            fill={mode === "saved" ? "currentColor" : "none"}
+            aria-hidden="true"
+          />
+        )}
+        {mode === "favorite" ? null : <span>{label}</span>}
+      </button>
+      {installGuide ? (
+        <div
+          className={styles.guideBackdrop}
+          onClick={() => setInstallGuide(null)}
+          role="presentation"
+        >
+          <section
+            className={styles.guideDialog}
+            role="dialog"
+            aria-modal="true"
+            aria-labelledby={installGuideTitleId}
+            onClick={(event) => event.stopPropagation()}
+          >
+            <button
+              type="button"
+              className={styles.guideClose}
+              onClick={() => setInstallGuide(null)}
+              aria-label="Close install instructions"
+            >
+              <X size={18} aria-hidden="true" />
+            </button>
+            <span className={styles.guideIcon} aria-hidden="true">
+              {installGuide === "ios" ? (
+                <Share2 size={28} strokeWidth={2.2} />
+              ) : (
+                <Download size={28} strokeWidth={2.2} />
+              )}
+            </span>
+            <h2 id={installGuideTitleId}>Add CozSweet to Home Screen</h2>
+            <p>
+              {installGuide === "ios"
+                ? "In Safari, tap the Share button, then choose “Add to Home Screen”."
+                : "Open your browser menu, then choose “Add to Home screen”."}
+            </p>
+            <button
+              type="button"
+              className={styles.guideConfirm}
+              onClick={() => setInstallGuide(null)}
+            >
+              Got it
+            </button>
+          </section>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function getFavoriteEntryLabel(mode: FavoriteEntryMode): string {
+  if (mode === "download") return "Download";
+  if (mode === "saved") return "Saved";
+  return "Save CozSweet";
+}

src/app/_components/core/index.ts

@@ -5,6 +5,7 @@
 export * from "./app-bottom-nav";
 export * from "./bottom-sheet";
 export * from "./checkbox";
+export * from "./favorite-entry-button";
 export * from "./loading-indicator";
 export * from "./mobile-shell";
 export * from "./page-loading-fallback";

src/app/_components/core/modal-portal.tsx

@@ -20,7 +20,10 @@ export interface ModalPortalProps {
   scrimOpacity: number;
   panelStyle?: CSSProperties;
   persistent?: boolean;
+  role?: "dialog" | "alertdialog";
   ariaLabel?: string;
+  ariaLabelledBy?: string;
+  ariaDescribedBy?: string;
 }
 
 export function ModalPortal({
@@ -32,7 +35,10 @@ export function ModalPortal({
   scrimOpacity,
   panelStyle,
   persistent = false,
+  role = "dialog",
   ariaLabel,
+  ariaLabelledBy,
+  ariaDescribedBy,
 }: ModalPortalProps) {
   useEffect(() => {
     if (!open || typeof document === "undefined") return;
@@ -63,9 +69,11 @@ export function ModalPortal({
       onClick={handleScrimClick}
     >
       <div
-        role="dialog"
+        role={role}
         aria-modal="true"
         aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledBy}
+        aria-describedby={ariaDescribedBy}
         className={panelClassName}
         style={panelStyle}
         onClick={(event) => event.stopPropagation()}

src/app/_components/index.ts

@@ -3,5 +3,6 @@
  */
 
 export * from "./back-button";
+export * from "./avatar-interaction";
 export * from "./character-avatar";
 export * from "./user-message-avatar";

src/app/_components/payment/__tests__/payment-launch-dialogs.test.tsx

@@ -1,23 +1,47 @@
-import { renderToStaticMarkup } from "react-dom/server";
+import { act } from "react";
-import { describe, expect, it, vi } from "vitest";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { PaymentLaunchDialogs } from "../payment-launch-dialogs";
 
 const hiddenLaunch = {
   handleEzpayCancel: vi.fn(),
   handleEzpayConfirm: vi.fn(),
+  handleRegionalQrClose: vi.fn(),
   handleStripeClose: vi.fn(),
   handleStripeConfirmed: vi.fn(),
   isConfirmingEzpay: false,
+  regionalQrErrorMessage: null,
+  regionalQrPayment: null,
+  regionalQrStatus: null,
   shouldShowEzpayConfirmDialog: false,
+  shouldShowRegionalQrDialog: false,
   shouldShowStripeDialog: false,
   stripeClientSecret: null,
 };
 
 describe("PaymentLaunchDialogs", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
+      .IS_REACT_ACT_ENVIRONMENT = true;
+    container = document.createElement("div");
+    container.style.transform = "translateX(50%)";
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    document.body.style.overflow = "";
+  });
+
   it("renders nothing when neither payment dialog is active", () => {
-    expect(
+    act(() =>
-      renderToStaticMarkup(
+      root.render(
         <PaymentLaunchDialogs
           currentOrderId={null}
           externalCheckoutAnalyticsKey="payment.external_checkout"
@@ -25,28 +49,145 @@ describe("PaymentLaunchDialogs", () => {
           launch={hiddenLaunch}
         />,
       ),
-    ).toBe("");
-  });
-
-  it("renders the shared Ezpay confirmation content", () => {
-    const html = renderToStaticMarkup(
-      <PaymentLaunchDialogs
-        currentOrderId="order-123"
-        externalCheckoutAnalyticsKey="tip.external_checkout"
-        ezpayDescription="Your coffee order is ready."
-        launch={{
-          ...hiddenLaunch,
-          isConfirmingEzpay: true,
-          shouldShowEzpayConfirmDialog: true,
-        }}
-      />,
     );
 
-    expect(html).toContain('role="alertdialog"');
+    expect(document.body.querySelector('[role="dialog"]')).toBeNull();
-    expect(html).toContain("Continue to GCash?");
+    expect(document.body.querySelector('[role="alertdialog"]')).toBeNull();
-    expect(html).toContain("Your coffee order is ready.");
+  });
-    expect(html).toContain("Order No. order-123");
+
-    expect(html).toContain('data-analytics-key="tip.external_checkout"');
+  it("portals the shared Ezpay confirmation outside transformed checkout UI", () => {
-    expect(html).toContain("Opening...");
+    act(() =>
+      root.render(
+        <PaymentLaunchDialogs
+          currentOrderId="order-123"
+          externalCheckoutAnalyticsKey="tip.external_checkout"
+          ezpayDescription="Your coffee order is ready."
+          launch={{
+            ...hiddenLaunch,
+            isConfirmingEzpay: true,
+            shouldShowEzpayConfirmDialog: true,
+          }}
+        />,
+      ),
+    );
+
+    const dialog = document.body.querySelector('[role="alertdialog"]');
+    expect(dialog).not.toBeNull();
+    expect(container.contains(dialog)).toBe(false);
+    expect(dialog?.parentElement?.parentElement).toBe(document.body);
+    expect(dialog?.textContent).toContain("Continue to payment?");
+    expect(dialog?.textContent).toContain("Your coffee order is ready.");
+    expect(dialog?.textContent).toContain("Order No. order-123");
+    expect(
+      dialog?.querySelector("button[data-analytics-key]")?.getAttribute(
+        "data-analytics-key",
+      ),
+    ).toBe("tip.external_checkout");
+    expect(dialog?.textContent).toContain("Opening...");
+    expect(document.body.style.overflow).toBe("hidden");
+  });
+
+  it("portals an accessible QRIS dialog with display cents and order status", () => {
+    act(() =>
+      root.render(
+        <PaymentLaunchDialogs
+          currentOrderId="order-id-qris"
+          externalCheckoutAnalyticsKey="tip.external_checkout"
+          ezpayDescription="Scan QRIS to finish the payment."
+          launch={{
+            ...hiddenLaunch,
+            regionalQrPayment: {
+              qrData: "00020101021226670016COM.NOBUBANK.WWW",
+              orderId: "order-id-qris",
+              amountCents: 5_000_000,
+              currency: "IDR",
+              experience: "qris",
+            },
+            regionalQrStatus: "pending",
+            shouldShowRegionalQrDialog: true,
+          }}
+        />,
+      ),
+    );
+
+    const dialog = document.body.querySelector('[role="dialog"]');
+    expect(dialog).not.toBeNull();
+    expect(container.contains(dialog)).toBe(false);
+    expect(dialog?.textContent).toContain("Scan to pay with QRIS");
+    expect(dialog?.querySelector("svg title")?.textContent).toBe(
+      "QRIS payment QR code",
+    );
+    expect(dialog?.textContent).toContain("Order No. order-id-qris");
+    expect(dialog?.textContent).toContain("Rp");
+    expect(dialog?.textContent).toContain("50.000");
+    expect(dialog?.textContent).toContain("Waiting for payment");
+  });
+
+  it("labels a Philippine QR fallback as GCash / QR Ph", () => {
+    act(() =>
+      root.render(
+        <PaymentLaunchDialogs
+          currentOrderId="order-ph-qr"
+          externalCheckoutAnalyticsKey="payment.external_checkout"
+          ezpayDescription="Pay with GCash."
+          launch={{
+            ...hiddenLaunch,
+            regionalQrPayment: {
+              qrData: "000201010212ph-qr-payload",
+              orderId: "order-ph-qr",
+              amountCents: 49_990,
+              currency: "PHP",
+              experience: "gcashQrPh",
+            },
+            regionalQrStatus: "pending",
+            shouldShowRegionalQrDialog: true,
+          }}
+        />,
+      ),
+    );
+
+    const dialog = document.body.querySelector('[role="dialog"]');
+    expect(dialog?.textContent).toContain("Pay with GCash / QR Ph");
+    expect(dialog?.textContent).not.toContain("QRIS");
+    expect(dialog?.querySelector("svg title")?.textContent).toBe(
+      "GCash / QR Ph payment QR code",
+    );
+    expect(dialog?.textContent).toContain("₱");
+
+    const closeButton = Array.from(
+      dialog?.querySelectorAll("button") ?? [],
+    ).find((button) => button.textContent?.trim() === "Close");
+    act(() => closeButton?.click());
+    expect(hiddenLaunch.handleRegionalQrClose).toHaveBeenCalledOnce();
+  });
+
+  it("shows QRIS failure state and handles empty QR data safely", () => {
+    act(() =>
+      root.render(
+        <PaymentLaunchDialogs
+          currentOrderId="order-id-qris"
+          externalCheckoutAnalyticsKey="payment.external_checkout"
+          ezpayDescription="Scan QRIS to finish the payment."
+          launch={{
+            ...hiddenLaunch,
+            regionalQrErrorMessage: "Payment failed or was cancelled.",
+            regionalQrPayment: {
+              qrData: "",
+              orderId: "order-id-qris",
+              amountCents: 5_000_000,
+              currency: "IDR",
+              experience: "qris",
+            },
+            regionalQrStatus: "failed",
+            shouldShowRegionalQrDialog: true,
+          }}
+        />,
+      ),
+    );
+
+    const dialog = document.body.querySelector('[role="dialog"]');
+    expect(dialog?.textContent).toContain("QRIS data is unavailable");
+    expect(dialog?.textContent).toContain("Payment failed or was cancelled.");
+    expect(dialog?.textContent).toContain("Close");
   });
 });

src/app/_components/payment/__tests__/payment-method-selector.test.tsx

@@ -62,6 +62,49 @@ describe("PaymentMethodSelector", () => {
     );
   });
 
+  it("labels Indonesia Ezpay as QRIS without the GCash logo", () => {
+    const html = renderToStaticMarkup(
+      <PaymentMethodSelector
+        config={{
+          canChoosePaymentMethod: true,
+          initialPayChannel: "ezpay",
+          showPaymentMethodSelector: true,
+          ezpayDisplayName: "QRIS",
+        }}
+        value="ezpay"
+        caption="QRIS by default in Indonesia"
+        analyticsKey="subscription.payment_method"
+        onChange={() => undefined}
+      />,
+    );
+
+    expect(html).toContain('aria-label="QRIS"');
+    expect(html).toContain("QRIS by default in Indonesia");
+    expect(html).not.toContain("gcash-logo.svg");
+  });
+
+  it("renders compact controls without the caption", () => {
+    const html = renderToStaticMarkup(
+      <PaymentMethodSelector
+        config={{
+          canChoosePaymentMethod: true,
+          initialPayChannel: "ezpay",
+          showPaymentMethodSelector: true,
+        }}
+        value="ezpay"
+        density="compact"
+        caption="This caption is hidden"
+        analyticsKey="tip.payment_method"
+        onChange={() => undefined}
+      />,
+    );
+
+    expect(html).toContain('data-density="compact"');
+    expect(html).toContain("Payment Method");
+    expect(html).not.toContain("This caption is hidden");
+    expect(html).toContain("min-h-13");
+  });
+
   it("does not render when payment method selection is unavailable", () => {
     const html = renderToStaticMarkup(
       <PaymentMethodSelector

src/app/_components/payment/__tests__/stripe-payment-dialog.test.tsx

@@ -0,0 +1,63 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { StripePaymentDialogLoading } from "../lazy-stripe-payment-dialog";
+import { StripePaymentDialog } from "../stripe-payment-dialog";
+
+describe("Stripe payment portal states", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
+      .IS_REACT_ACT_ENVIRONMENT = true;
+    container = document.createElement("div");
+    container.style.transform = "translateX(50%)";
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    document.body.style.overflow = "";
+  });
+
+  it("portals the unavailable state and keeps its explicit close action", () => {
+    const onClose = vi.fn();
+
+    act(() =>
+      root.render(
+        <StripePaymentDialog
+          clientSecret="client-secret"
+          onClose={onClose}
+        />,
+      ),
+    );
+
+    const dialog = document.body.querySelector('[role="alertdialog"]');
+    expect(dialog).not.toBeNull();
+    expect(container.contains(dialog)).toBe(false);
+    expect(dialog?.textContent).toContain("Payment unavailable");
+    expect(dialog?.getAttribute("aria-labelledby")).toBeTruthy();
+    expect(dialog?.getAttribute("aria-describedby")).toBeTruthy();
+
+    const okButton = Array.from(dialog?.querySelectorAll("button") ?? []).find(
+      (button) => button.textContent === "OK",
+    );
+    act(() => okButton?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it("portals the lazy loading state", () => {
+    act(() => root.render(<StripePaymentDialogLoading />));
+
+    const dialog = document.body.querySelector('[role="dialog"]');
+    expect(dialog).not.toBeNull();
+    expect(container.contains(dialog)).toBe(false);
+    expect(dialog?.textContent).toContain("Preparing secure payment");
+    expect(dialog?.textContent).toContain("Loading payment methods...");
+    expect(dialog?.querySelector('[aria-busy="true"]')).not.toBeNull();
+  });
+});

src/app/_components/payment/lazy-stripe-payment-dialog.tsx

@@ -2,6 +2,8 @@
 
 import dynamic from "next/dynamic";
 
+import { ModalPortal } from "@/app/_components/core/modal-portal";
+
 import type { StripePaymentDialogProps } from "./stripe-payment-dialog";
 import { stripePaymentDialogStyles as styles } from "./stripe-payment-dialog.styles";
 
@@ -20,22 +22,28 @@ export function LazyStripePaymentDialog(props: StripePaymentDialogProps) {
   return <StripePaymentDialog {...props} />;
 }
 
-function StripePaymentDialogLoading() {
+export function StripePaymentDialogLoading() {
   return (
-    <div
+    <ModalPortal
-      className={styles.overlay}
+      open
-      role="dialog"
+      persistent
-      aria-modal="true"
+      onClose={() => undefined}
-      aria-labelledby="stripe-payment-loading-title"
+      scrimClassName={styles.overlay}
+      panelClassName={styles.dialog}
+      scrimOpacity={0.5}
+      ariaLabelledBy="stripe-payment-loading-title"
+      ariaDescribedBy="stripe-payment-loading-description"
     >
-      <div className={styles.dialog} aria-busy="true">
+      <div aria-busy="true">
         <div className={styles.header}>
           <h2 id="stripe-payment-loading-title" className={styles.title}>
             Preparing secure payment
           </h2>
-          <p className={styles.content}>Loading payment methods...</p>
+          <p id="stripe-payment-loading-description" className={styles.content}>
+            Loading payment methods...
+          </p>
         </div>
       </div>
-    </div>
+    </ModalPortal>
   );
 }

src/app/_components/payment/payment-launch-dialogs.tsx

@@ -1,7 +1,9 @@
 "use client";
 
 import { useId, type ReactNode } from "react";
+import { QRCodeSVG } from "qrcode.react";
 
+import { ModalPortal } from "@/app/_components/core/modal-portal";
 import type { PaymentLaunchFlow } from "@/app/_hooks/use-payment-launch-flow";
 
 import { LazyStripePaymentDialog } from "./lazy-stripe-payment-dialog";
@@ -11,10 +13,15 @@ type PaymentLaunchDialogFlow = Pick<
   PaymentLaunchFlow,
   | "handleEzpayCancel"
   | "handleEzpayConfirm"
+  | "handleRegionalQrClose"
   | "handleStripeClose"
   | "handleStripeConfirmed"
   | "isConfirmingEzpay"
+  | "regionalQrErrorMessage"
+  | "regionalQrPayment"
+  | "regionalQrStatus"
   | "shouldShowEzpayConfirmDialog"
+  | "shouldShowRegionalQrDialog"
   | "shouldShowStripeDialog"
   | "stripeClientSecret"
 >;
@@ -46,6 +53,14 @@ export function PaymentLaunchDialogs({
           onConfirm={launch.handleEzpayConfirm}
         />
       ) : null}
+      {launch.shouldShowRegionalQrDialog && launch.regionalQrPayment ? (
+        <RegionalQrPaymentDialog
+          payment={launch.regionalQrPayment}
+          status={launch.regionalQrStatus}
+          errorMessage={launch.regionalQrErrorMessage}
+          onClose={launch.handleRegionalQrClose}
+        />
+      ) : null}
       {launch.shouldShowStripeDialog && launch.stripeClientSecret ? (
         <LazyStripePaymentDialog
           clientSecret={launch.stripeClientSecret}
@@ -58,6 +73,151 @@ export function PaymentLaunchDialogs({
   );
 }
 
+interface RegionalQrPaymentDialogProps {
+  errorMessage: string | null;
+  onClose: () => void;
+  payment: NonNullable<PaymentLaunchFlow["regionalQrPayment"]>;
+  status: PaymentLaunchFlow["regionalQrStatus"];
+}
+
+function formatRegionalQrAmount(amountCents: number, currency: string): string {
+  const normalizedCurrency = currency.trim().toUpperCase() || "IDR";
+  try {
+    return new Intl.NumberFormat(
+      normalizedCurrency === "PHP" ? "en-PH" : "id-ID",
+      {
+        style: "currency",
+        currency: normalizedCurrency,
+        maximumFractionDigits: normalizedCurrency === "IDR" ? 0 : 2,
+      },
+    ).format(amountCents / 100);
+  } catch {
+    return `${normalizedCurrency} ${(amountCents / 100).toFixed(2)}`;
+  }
+}
+
+function regionalQrStatusMessage(
+  status: PaymentLaunchFlow["regionalQrStatus"],
+  errorMessage: string | null,
+  paymentName: string,
+): string {
+  if (status === "failed") {
+    return errorMessage || "Payment failed. Please try again.";
+  }
+  if (status === "expired") {
+    return errorMessage || `This ${paymentName} order has expired.`;
+  }
+  return "Waiting for payment";
+}
+
+function RegionalQrPaymentDialog({
+  errorMessage,
+  onClose,
+  payment,
+  status,
+}: RegionalQrPaymentDialogProps) {
+  const titleId = useId();
+  const copy = regionalQrCopy(payment.experience);
+  const statusMessage = regionalQrStatusMessage(
+    status,
+    errorMessage,
+    copy.paymentName,
+  );
+
+  return (
+    <ModalPortal
+      open
+      persistent
+      onClose={onClose}
+      scrimClassName={styles.overlay}
+      panelClassName={styles.dialog}
+      scrimOpacity={0.5}
+      ariaLabelledBy={titleId}
+    >
+      <div className={`${styles.header} text-center`}>
+        <h2 id={titleId} className={styles.title}>
+          {copy.title}
+        </h2>
+        <p className={styles.content}>
+          {copy.description}
+        </p>
+      </div>
+      <div className="mb-4 flex min-h-64 items-center justify-center rounded-2xl bg-white p-4">
+        {payment.qrData ? (
+          <QRCodeSVG
+            value={payment.qrData}
+            title={copy.qrTitle}
+            size={256}
+            level="M"
+            marginSize={2}
+            className="h-auto w-full max-w-64"
+          />
+        ) : (
+          <p className={styles.error} role="alert">
+            {copy.unavailableMessage}
+          </p>
+        )}
+      </div>
+      <div className="mb-4 flex flex-col gap-2 text-center">
+        <p className={styles.content}>Order No. {payment.orderId}</p>
+        <p className="m-0 text-xl font-bold text-text-foreground">
+          {formatRegionalQrAmount(payment.amountCents, payment.currency)}
+        </p>
+        <p
+          className={status === "failed" || status === "expired" ? styles.error : styles.content}
+          role="status"
+        >
+          {statusMessage}
+        </p>
+      </div>
+      <div className={styles.actions}>
+        <button
+          type="button"
+          className={`${styles.button} ${styles.secondary}`}
+          onClick={onClose}
+        >
+          Close
+        </button>
+      </div>
+    </ModalPortal>
+  );
+}
+
+function regionalQrCopy(
+  experience: NonNullable<PaymentLaunchFlow["regionalQrPayment"]>["experience"],
+) {
+  if (experience === "gcashQrPh") {
+    return {
+      paymentName: "GCash / QR Ph",
+      title: "Pay with GCash / QR Ph",
+      description:
+        "Open GCash or another QR Ph-compatible app and scan this code.",
+      qrTitle: "GCash / QR Ph payment QR code",
+      unavailableMessage:
+        "GCash / QR Ph data is unavailable. Please close this dialog and try again.",
+    };
+  }
+  if (experience === "qris") {
+    return {
+      paymentName: "QRIS",
+      title: "Scan to pay with QRIS",
+      description:
+        "Open a QRIS-compatible banking or wallet app and scan this code.",
+      qrTitle: "QRIS payment QR code",
+      unavailableMessage:
+        "QRIS data is unavailable. Please close this dialog and try again.",
+    };
+  }
+  return {
+    paymentName: "payment QR",
+    title: "Scan to pay",
+    description: "Open a compatible banking or wallet app and scan this code.",
+    qrTitle: "Payment QR code",
+    unavailableMessage:
+      "Payment QR data is unavailable. Please close this dialog and try again.",
+  };
+}
+
 interface EzpayRedirectConfirmDialogProps {
   description: ReactNode;
   externalCheckoutAnalyticsKey: string;
@@ -78,41 +238,43 @@ function EzpayRedirectConfirmDialog({
   const titleId = useId();
 
   return (
-    <div
+    <ModalPortal
-      className={styles.overlay}
+      open
+      persistent
+      onClose={onCancel}
+      scrimClassName={styles.overlay}
+      panelClassName={styles.dialog}
+      scrimOpacity={0.5}
       role="alertdialog"
-      aria-modal="true"
+      ariaLabelledBy={titleId}
-      aria-labelledby={titleId}
     >
-      <div className={styles.dialog}>
+      <div className={styles.header}>
-        <div className={styles.header}>
+        <h2 id={titleId} className={styles.title}>
-          <h2 id={titleId} className={styles.title}>
+          Continue to payment?
-            Continue to GCash?
+        </h2>
-          </h2>
+        <p className={styles.content}>{description}</p>
-          <p className={styles.content}>{description}</p>
+        <p className={styles.content}>Order No. {orderId}</p>
-          <p className={styles.content}>Order No. {orderId}</p>
-        </div>
-        <div className={styles.actions}>
-          <button
-            type="button"
-            className={`${styles.button} ${styles.secondary}`}
-            disabled={isConfirming}
-            onClick={onCancel}
-          >
-            Cancel
-          </button>
-          <button
-            type="button"
-            data-analytics-key={externalCheckoutAnalyticsKey}
-            data-analytics-label="Continue to external checkout"
-            className={`${styles.button} ${styles.primary}`}
-            disabled={isConfirming}
-            onClick={onConfirm}
-          >
-            {isConfirming ? "Opening..." : "Continue"}
-          </button>
-        </div>
       </div>
-    </div>
+      <div className={styles.actions}>
+        <button
+          type="button"
+          className={`${styles.button} ${styles.secondary}`}
+          disabled={isConfirming}
+          onClick={onCancel}
+        >
+          Cancel
+        </button>
+        <button
+          type="button"
+          data-analytics-key={externalCheckoutAnalyticsKey}
+          data-analytics-label="Continue to external checkout"
+          className={`${styles.button} ${styles.primary}`}
+          disabled={isConfirming}
+          onClick={onConfirm}
+        >
+          {isConfirming ? "Opening..." : "Continue"}
+        </button>
+      </div>
+    </ModalPortal>
   );
 }

src/app/_components/payment/payment-method-selector.tsx

@@ -24,6 +24,7 @@ const PAYMENT_METHODS: readonly {
 export interface PaymentMethodSelectorProps {
   config: PaymentMethodConfig;
   value: PayChannel;
+  density?: "default" | "compact";
   disabled?: boolean;
   caption?: string;
   className?: string;
@@ -34,6 +35,7 @@ export interface PaymentMethodSelectorProps {
 export function PaymentMethodSelector({
   config,
   value,
+  density = "default",
   disabled = false,
   caption = "Stripe by default",
   className,
@@ -41,36 +43,53 @@ export function PaymentMethodSelector({
   onChange,
 }: PaymentMethodSelectorProps) {
   if (!config.showPaymentMethodSelector) return null;
+  const isCompact = density === "compact";
+  const ezpayDisplayName = config.ezpayDisplayName ?? "GCash";
+  const configuredPaymentMethods = PAYMENT_METHODS.map((method) =>
+    method.channel === "ezpay"
+      ? {
+          ...method,
+          title: ezpayDisplayName,
+          logoSrc:
+            ezpayDisplayName === "GCash" ? method.logoSrc : undefined,
+        }
+      : method,
+  );
 
   const paymentMethods =
     config.initialPayChannel === "ezpay"
-      ? [...PAYMENT_METHODS].sort((a, b) =>
+      ? [...configuredPaymentMethods].sort((a, b) =>
           a.channel === "ezpay" ? -1 : b.channel === "ezpay" ? 1 : 0,
         )
-      : PAYMENT_METHODS;
+      : configuredPaymentMethods;
 
   return (
     <section
-      className={`flex flex-col gap-[clamp(8px,1.852vw,10px)] ${className ?? ""}`.trim()}
+      className={`flex flex-col ${isCompact ? "gap-2" : "gap-[clamp(8px,1.852vw,10px)]"} ${className ?? ""}`.trim()}
+      data-density={density}
       aria-labelledby="payment-method-title"
     >
-      <div className="flex items-baseline justify-between gap-sm px-xs">
+      <div
+        className={`flex items-baseline justify-between gap-sm ${isCompact ? "px-0.5" : "px-xs"}`}
+      >
         <h2
           id="payment-method-title"
-          className="m-0 text-(length:--responsive-card-title,var(--font-size-lg)) font-bold leading-[1.2] text-auth-text-primary"
+          className={`m-0 font-bold leading-[1.2] text-auth-text-primary ${isCompact ? "text-base" : "text-(length:--responsive-card-title,var(--font-size-lg))"}`}
           style={{ fontFamily: "var(--font-athelas), var(--font-system)" }}
         >
           Payment Method
         </h2>
-        <span className="whitespace-nowrap text-(length:--responsive-caption,var(--font-size-sm)) leading-[1.2] text-text-secondary">
+        {!isCompact ? (
-          {caption}
+          <span className="whitespace-nowrap text-(length:--responsive-caption,var(--font-size-sm)) leading-[1.2] text-text-secondary">
-        </span>
+            {caption}
+          </span>
+        ) : null}
       </div>
       <div className="grid grid-cols-2 gap-sm">
         {paymentMethods.map((method) => {
           const selected = method.channel === value;
           const classes = [
-            "flex min-h-[clamp(54px,11.481vw,62px)] cursor-pointer items-center justify-center rounded-(--responsive-card-radius-sm,18px) px-[clamp(12px,2.593vw,14px)] py-[clamp(9px,1.852vw,10px)] text-center font-[inherit] text-[#3c3b3b] transition-[border-color,box-shadow,transform] duration-150 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent active:enabled:scale-98 disabled:cursor-not-allowed disabled:opacity-72",
+            `flex cursor-pointer items-center justify-center text-center font-[inherit] text-[#3c3b3b] transition-[border-color,box-shadow,transform] duration-150 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent active:enabled:scale-98 disabled:cursor-not-allowed disabled:opacity-72 ${isCompact ? "min-h-13 rounded-[18px] px-3 py-2" : "min-h-[clamp(54px,11.481vw,62px)] rounded-(--responsive-card-radius-sm,18px) px-[clamp(12px,2.593vw,14px)] py-[clamp(9px,1.852vw,10px)]"}`,
             selected
               ? "border-2 border-[#f657a0] bg-[#fff4f9] shadow-[0_8px_18px_rgba(217,47,127,0.24),0_0_0_3px_rgba(217,47,127,0.18)] -translate-y-0.5"
               : "border border-[rgba(246,87,160,0.18)] bg-white shadow-[0_5px_7px_0_rgba(247,89,168,0.08)]",
@@ -97,7 +116,7 @@ export function PaymentMethodSelector({
                   aria-hidden="true"
                   width={122}
                   height={29}
-                  className="block max-h-8.5 w-[min(100%,92px)] object-contain"
+                  className={`block object-contain ${isCompact ? "max-h-8 w-[min(100%,92px)]" : "max-h-8.5 w-[min(100%,92px)]"}`}
                 />
               ) : (
                 <span className="text-(length:--responsive-body,16px) font-bold leading-[1.1] text-[#1e1e1e]">

src/app/_components/payment/stripe-payment-dialog.styles.ts

@@ -2,7 +2,7 @@ export const stripePaymentDialogStyles = {
   overlay:
     "fixed inset-0 z-70 flex items-center justify-center bg-[rgba(0,0,0,0.5)] pb-[calc(var(--dialog-safe-margin,20px)+var(--app-safe-bottom,0))] pl-[calc(var(--dialog-safe-margin,20px)+var(--app-safe-left,0))] pr-[calc(var(--dialog-safe-margin,20px)+var(--app-safe-right,0))] pt-[calc(var(--dialog-safe-margin,20px)+var(--app-safe-top,0))]",
   dialog:
-    "max-h-[calc(var(--app-visible-height,100dvh)-calc(var(--dialog-safe-margin,20px)*2))] w-full max-w-(--dialog-wide-max-width,420px) overflow-y-auto rounded-(--responsive-card-radius,32px) bg-(--color-page-background,#ffffff) px-(--responsive-card-padding,18px) pb-(--responsive-card-padding,18px) pt-(--responsive-card-padding-lg,24px) shadow-[0_18px_40px_rgba(0,0,0,0.16)]",
+    "max-h-[calc(var(--app-visible-height,100dvh)-calc(var(--dialog-safe-margin,20px)*2))] w-full max-w-(--dialog-wide-max-width,420px) overflow-y-auto overscroll-contain rounded-(--responsive-card-radius,32px) bg-(--color-page-background,#ffffff) px-(--responsive-card-padding,18px) pb-(--responsive-card-padding,18px) pt-(--responsive-card-padding-lg,24px) shadow-[0_18px_40px_rgba(0,0,0,0.16)]",
   header: "mb-(--page-section-gap,18px) text-left",
   title:
     "m-0 mb-[clamp(7px,1.481vw,8px)] text-(length:--responsive-page-title,22px) font-bold leading-[1.2] text-text-foreground",