banlv/cozsweet-frontend-nextjs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: banlv/cozsweet-frontend-nextjs:dev
Branches Tags
banlv/cozsweet-frontend-nextjs:main banlv/cozsweet-frontend-nextjs:dev banlv/cozsweet-frontend-nextjs:pre
..
compare: banlv/cozsweet-frontend-nextjs:96a2accde4deb1643d573c1128f5a48509712460
Branches Tags
banlv/cozsweet-frontend-nextjs:dev banlv/cozsweet-frontend-nextjs:pre banlv/cozsweet-frontend-nextjs:main

2 Commits
dev .. 96a2accde4

Author SHA1 Message Date
admin 96a2accde4 fix(splash): hide experimental splash components
Docker Image / Quality and Bundle Budgets (push) Successful in 3m33s
Details
Docker Image / Build and Push Docker Image (push) Successful in 1m53s
Details
2026-07-20 17:49:19 +08:00
admin 26ab790078 chore(icons): 使用生产环境的图标 2026-07-20 17:49:19 +08:00
461 changed files with 5040 additions and 21073 deletions
Expand all files Collapse all files
.gitea/workflows/docker-image.yml
+42 -13
View File
@@ -8,8 +8,39 @@ on:
workflow_dispatch: workflow_dispatch:
jobs: 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: publish:
name: Build and Push Docker Image name: Build and Push Docker Image
needs: quality
runs-on: gitea-label runs-on: gitea-label
container: container:
image: cozsweet-act-runner-node24-docker:latest image: cozsweet-act-runner-node24-docker:latest
@@ -152,9 +183,12 @@ jobs:
- name: Deploy image over SSH - name: Deploy image over SSH
env: env:
SSH_HOST: ${{ secrets.SSH_HOST }} SSH_HOST: ${{ secrets.SSH_HOST }}
SSH_USER: ${{ secrets.SSH_USER }}
SSH_PORT: ${{ secrets.SSH_PORT }} SSH_PORT: ${{ secrets.SSH_PORT }}
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }} SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
SSH_KNOWN_HOSTS: ${{ secrets.SSH_KNOWN_HOSTS }} 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_HOST: ${{ secrets.REGISTRY_HOST }}
REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }} REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }} REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
@@ -163,18 +197,16 @@ jobs:
case "$DEPLOY_ENV" in case "$DEPLOY_ENV" in
test) test)
DEPLOY_ROOT="/home/lzf/apps/cozsweet-web-test" DEPLOY_DIR="${TEST_DEPLOY_DIR:-/opt/cozsweet-web-test}"
HOST_PORT="9135" HOST_PORT="9135"
CONTAINER_NAME="cozsweet-web-test" CONTAINER_NAME="cozsweet-web-test"
PROJECT_NAME="cozsweet-web-test" PROJECT_NAME="cozsweet-web-test"
SERVER_RETAIN_COUNT="1"
;; ;;
prod) prod)
DEPLOY_ROOT="/home/lzf/apps/cozsweet-web-prod" DEPLOY_DIR="${PROD_DEPLOY_DIR:-/opt/cozsweet-web-prod}"
HOST_PORT="9185" HOST_PORT="9185"
CONTAINER_NAME="cozsweet-web-prod" CONTAINER_NAME="cozsweet-web-prod"
PROJECT_NAME="cozsweet-web-prod" PROJECT_NAME="cozsweet-web-prod"
SERVER_RETAIN_COUNT="2"
;; ;;
*) *)
echo "Unsupported deploy env: $DEPLOY_ENV" >&2 echo "Unsupported deploy env: $DEPLOY_ENV" >&2
@@ -182,11 +214,8 @@ jobs:
;; ;;
esac 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_HOST="$SSH_HOST"
DEPLOY_USER="lzf" DEPLOY_USER="$SSH_USER"
DEPLOY_PORT="${SSH_PORT:-22}" DEPLOY_PORT="${SSH_PORT:-22}"
DEPLOY_KEY="$SSH_PRIVATE_KEY" DEPLOY_KEY="$SSH_PRIVATE_KEY"
DEPLOY_KNOWN_HOSTS="$SSH_KNOWN_HOSTS" DEPLOY_KNOWN_HOSTS="$SSH_KNOWN_HOSTS"
@@ -212,19 +241,19 @@ jobs:
SSH_OPTS="-i $KEY_FILE -p $DEPLOY_PORT -o IdentitiesOnly=yes" SSH_OPTS="-i $KEY_FILE -p $DEPLOY_PORT -o IdentitiesOnly=yes"
SCP_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" \ ssh $SSH_OPTS "$SSH_TARGET" "mkdir -p '$DEPLOY_DIR'"
"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 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 scripts/server/deploy-docker-image.sh "$SSH_TARGET:$DEPLOY_DIR/deploy-docker-image.sh"
scp $SCP_OPTS "$NEXT_ENV_FILE" "$SSH_TARGET:$REMOTE_ENV_FILE" scp $SCP_OPTS "$NEXT_ENV_FILE" "$SSH_TARGET:$DEPLOY_DIR/$NEXT_ENV_FILE"
ssh $SSH_OPTS "$SSH_TARGET" "chmod 600 '$REMOTE_ENV_FILE'"
printf '%s' "$REGISTRY_PASSWORD" \ printf '%s' "$REGISTRY_PASSWORD" \
| ssh $SSH_OPTS "$SSH_TARGET" \ | ssh $SSH_OPTS "$SSH_TARGET" \
"docker login '$REGISTRY_HOST' -u '$REGISTRY_USERNAME' --password-stdin" "docker login '$REGISTRY_HOST' -u '$REGISTRY_USERNAME' --password-stdin"
SERVER_RETAIN_COUNT="1"
ssh $SSH_OPTS "$SSH_TARGET" \ ssh $SSH_OPTS "$SSH_TARGET" \
"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'" "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'"
- name: Purge Cloudflare cache - name: Purge Cloudflare cache
env: env:
.gitea/workflows/domestic-test.yml
-138
View File
@@ -1,138 +0,0 @@
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"
Dockerfile
+3 -5
View File
@@ -6,12 +6,10 @@ ENV PNPM_HOME=/pnpm
ENV PNPM_STORE_PATH=/pnpm/store ENV PNPM_STORE_PATH=/pnpm/store
ENV PATH=$PNPM_HOME:$PATH ENV PATH=$PNPM_HOME:$PATH
ARG NPM_REGISTRY=https://registry.npmmirror.com
RUN apk add --no-cache libc6-compat \ RUN apk add --no-cache libc6-compat \
&& npm install --global "pnpm@10.30.3" --registry="$NPM_REGISTRY" \ && corepack enable \
&& pnpm config set store-dir "$PNPM_STORE_PATH" \ && corepack prepare pnpm@10.30.3 --activate \
&& pnpm config set registry "$NPM_REGISTRY" && pnpm config set store-dir "$PNPM_STORE_PATH"
FROM base AS deps FROM base AS deps
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./ COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
FRONTEND_GIFT_PRODUCTS_API.md
-403
View File
@@ -1,403 +0,0 @@
# 虚拟礼物商品与付款后文案 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
+3 -3
View File
@@ -25,9 +25,9 @@
"./src/data/schemas/payment", "./src/data/schemas/payment",
"./src/data/schemas/payment/request", "./src/data/schemas/payment/request",
"./src/data/schemas/payment/response", "./src/data/schemas/payment/response",
"./src/data/schemas/private-zone", "./src/data/schemas/private-room",
"./src/data/schemas/private-zone/request", "./src/data/schemas/private-room/request",
"./src/data/schemas/private-zone/response", "./src/data/schemas/private-room/response",
"./src/data/schemas/user", "./src/data/schemas/user",
"./src/data/storage/app", "./src/data/storage/app",
"./src/data/storage/auth", "./src/data/storage/auth",
docs/backend/FRONTEND_LOCKED_MEDIA_UNLOCK_API.md
+496
View File
@@ -0,0 +1,496 @@
# 前端锁消息解锁 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
+448
View File
@@ -0,0 +1,448 @@
# 单角色应用迁移为多角色聊天架构
## 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
+92 -251
View File
@@ -1,95 +1,28 @@
# CozSweet 多角色聊天权威协议 # CozSweet 多角色聊天前端对接
## 1. 状态与范围 ## 3. Character IDs
本文是前端仓库中多角色目录、聊天、解锁、缓存隔离及关联业务的唯一人工维护协议。旧的单角色迁移方案和独立锁媒体协议已删除，不再作为实现或联调依据。 前端先调用：
协议描述当前前端已经执行的行为，不描述尚未落地的后端迁移步骤。字段和路径由下列机器可验证入口约束：
| 边界 | 实现位置 |
| --- | --- |
| 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 ```http
GET <API_BASE_URL>/api/characters?capability=chat 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 ```text
/characters/{slug}/splash elio
/characters/{slug}/chat maya-tan
/characters/{slug}/private-zone nayeli-cervantes
/characters/{slug}/tip
``` ```
当前 Splash 是角色详情入口，不是全角色列表页。以下旧地址保留为默认角色重定向，并原样保留查询参数： 只允许传递角色目录响应中的 `items[].id`，不要传展示名或 `@handle`。
```text 角色响应中的 `capabilities` 是后端权威开关。`chat=false` 时不得开放输入框；直接调用聊天接口会得到 `CHARACTER_DISABLED`，不会返回 Elio 历史。
/splash -> /characters/elio/splash
/chat -> /characters/elio/chat
/private-zone -> /characters/elio/private-zone
/tip -> /characters/elio/tip
```
Chat Provider 以 `characterId` 为边界，路由角色变化时创建新的 Actor。Private Zone 的角色边界由 [Private Zone 权威协议](./FRONTEND_PRIVATE_ZONE_API.md) 定义。 ## 4. Send Message
## 3. Chat HTTP 协议 ### Request URL
### 3.1 发送消息
```http ```http
POST <API_BASE_URL>/api/chat/send POST <API_BASE_URL>/api/chat/send
@@ -97,56 +30,73 @@ Content-Type: application/json
Authorization: Bearer <TOKEN> Authorization: Bearer <TOKEN>
``` ```
```json ### Parameters
{
"characterId": "maya-tan", | Field | Type | Required | Example | Meaning |
"message": "Hello Maya", | --- | --- | --- | --- | --- |
"useWebSocket": false | `characterId` | string | 新前端必传 | `maya-tan` | 当前聊天角色 ID |
} | `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`，无需从响应推断角色。
- `characterId` 必填； ## 5. Chat History
- `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 ```http
GET <API_BASE_URL>/api/chat/history?characterId=maya-tan&limit=50&offset=0 GET <API_BASE_URL>/api/chat/history?characterId=maya-tan&limit=50&offset=0
Authorization: Bearer <TOKEN> Authorization: Bearer <TOKEN>
``` ```
| Query | 必填 | 规则 | | Query | Type | Required | Rule |
| --- | --- | --- | | --- | --- | --- | --- |
| `characterId` | 是 | 角色业务 ID | | `characterId` | string | 新前端必传 | 只返回该角色数据 |
| `limit` | 否 | 前端默认 50 | | `limit` | integer | 否 | `1-200`，默认 `50` |
| `offset` | 否 | 前端默认 0 | | `offset` | integer | 否 | 最小 `0` |
响应数据包含 `messages`、`total`、`limit`、`offset`，并可包含当前私密额度快照。消息字段： `messages` 和 `total` 都只统计指定角色。切换角色时必须重新请求 history，不能复用上一个角色的本地数组。
```text ```json
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
}
}
``` ```
前端兼容 `createdAt` 和 `created_at` 输入，解析后统一为 `createdAt`。缺失的可空载荷会由 Schema 归一化，业务组件不直接读取原始 envelope。 ## 6. Latest Previews
本地快照可先进入可渲染状态；网络历史随后覆盖缓存并更新 UI。网络同步期间新增的乐观消息按 `displayId` 保留。向上拉取更早页面时也按 `displayId` 去重。 角色会话列表可一次请求所有可聊天角色的最后一条消息：
### 3.3 最新消息预览
```http ```http
GET <API_BASE_URL>/api/chat/previews GET <API_BASE_URL>/api/chat/previews
@@ -155,29 +105,20 @@ Authorization: Bearer <TOKEN>
```json ```json
{ {
"items": [ "code": 200,
{ "success": true,
"characterId": "elio", "data": {
"message": { "items": [
"id": "<MESSAGE_ID>", {"characterId": "elio", "message": {"id": "...", "role": "assistant", "type": "text", "content": "..."}},
"role": "assistant", {"characterId": "maya-tan", "message": null}
"type": "text", ]
"content": "How was your day?" }
}
},
{
"characterId": "maya-tan",
"message": null
}
]
} }
``` ```
接口可用时，Splash 以批量结果更新各角色预览；接口失败时，当前角色可回退到 `history?limit=1&offset=0`。预览缓存仍使用角色会话身份隔离。 锁定私密文本不会泄露内容，锁定语音不会返回 `audioUrl`（文字仍正常返回）。图片沿用现有协议，URL 可以存在；前端必须以 `lockDetail.locked=true` 覆盖展示，不能把“URL 非空”当作已解锁。
## 4. 解锁协议 ## 7. Unlock One Message
### 4.1 解锁单条消息
```http ```http
POST <API_BASE_URL>/api/chat/unlock-private POST <API_BASE_URL>/api/chat/unlock-private
@@ -185,144 +126,44 @@ Content-Type: application/json
Authorization: Bearer <TOKEN> Authorization: Bearer <TOKEN>
``` ```
已有后端消息：
```json
{
"characterId": "maya-tan",
"messageId": "<MESSAGE_ID>"
}
```
前端 Promotion 锁卡片：
```json ```json
{ {
"characterId": "maya-tan", "characterId": "maya-tan",
"messageId": "<MESSAGE_ID>",
"lockType": "voice_message", "lockType": "voice_message",
"clientLockId": "<STABLE_CLIENT_LOCK_ID>" "clientLockId": "maya-card-001"
} }
``` ```
请求必须包含 `characterId`，并至少包含 `messageId` 或 `lockType`。标准 `lockType` 为： `messageId` 存在时，后端会核对消息角色。拿 Elio 的 `messageId` 配 Maya 的 `characterId` 会返回 HTTP `409 / CHARACTER_MISMATCH`，且不会扣积分。
```text 前端临时伪造锁卡片没有 `messageId` 时，仍传 `characterId + lockType + clientLockId`。`clientLockId` 的幂等查找范围已包含账号和角色，同一个 ID 可以在不同角色下分别使用。
voice_message
image_paywall
private_message
```
前端解析的响应字段： ## 8. Unlock Current Character History
```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 ```http
POST <API_BASE_URL>/api/chat/unlock-history POST <API_BASE_URL>/api/chat/unlock-history
Content-Type: application/json Content-Type: application/json
Authorization: Bearer <TOKEN> Authorization: Bearer <TOKEN>
```
```json
{"characterId":"maya-tan"} {"characterId":"maya-tan"}
``` ```
请求和返回消息都限定当前角色。前端完成解锁后重新读取该角色历史，不复用其他角色 Actor 的消息。 费用、锁消息数量、成功解锁数量及 `messageIds` 都只计算当前角色。钱包余额仍是账号全局余额。
### 4.3 角色错误 ## 12. Tip Attribution
前端识别以下后端错误码： 只有 Tip 订单使用角色归属：
| 错误码 | 前端行为 | ```json
| --- | --- | {
| `CHARACTER_DISABLED` | 禁止继续发送并刷新角色目录 | "planId": "tip_coffee_usd_4_99",
| `CHARACTER_NOT_FOUND` | 清理待恢复导航、刷新目录并返回默认角色 | "payChannel": "stripe",
| `CHARACTER_MISMATCH` | 不进入支付，刷新当前角色历史 | "autoRenew": false,
| `CHARACTER_STATE_UNAVAILABLE` | 保留会话并提示稍后重试 | "recipientCharacterId": "maya-tan"
}
任何角色错误都不得在前端回退为另一个角色的历史。
## 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}
``` ```
同一个后端 ID 可能同时出现在 user 和 assistant 记录中，因此不得直接使用 `remoteId` 作为 React key。解锁前后 `displayId` 不变；图片 Overlay 始终写入 `displayId`，但读取时兼容旧的 `remoteId` URL。 Tip 订单必须携带 `recipientCharacterId`。VIP 和积分充值会忽略该字段。
## 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
-292
View File
@@ -1,292 +0,0 @@
# 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
-241
View File
@@ -1,241 +0,0 @@
# 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/external-entry/README.md
+65 -63
View File
@@ -1,11 +1,11 @@
# 外部入口接入说明 # 外部入口接入说明
Facebook 等外部应用统一通过 `/external-entry` 进入本应用。入口先保存外部身份和短期业务意图，再跳转到对应角色页面并清理地址栏中的入口查询参数。 外部应用通过 `/external-entry` 进入本应用。
| 环境 | APP HOST | | 环境 | APP HOST |
| --- | --- | | --- | --- |
| 预发环境 `pre` | `frontend-test.banlv-ai.com` | | 测试环境 | `frontend-test.banlv-ai.com` |
| 正式环境 `production` | `cozsweet.com` | | 正式环境 | `cozsweet.com` |
入口格式： 入口格式：
@@ -13,78 +13,80 @@ Facebook 等外部应用统一通过 `/external-entry` 进入本应用。入口
https://<APP_HOST>/external-entry?<参数> 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-zone` | 指定进入的页面；不传或值无效时进入聊天页。 | | `target` | `chat`、`tip`、`private-room` | 指定进入的页面；不传或值无效时进入聊天页。 |
| `character` | `elio`、`maya`、`nayeli` | 指定角色；不传或值无效时使用 Elio。正式投放链接必须显式传入。 | | `character` | `elio`、`maya`、`nayeli` | 指定角色；不传或值无效时使用 Elio。 |
| `psid` | string | Facebook Page-scoped User ID。Facebook 正式投放链接必须动态传入。 | | `psid` | string | 传入 Facebook Page-scoped User ID。 |
| `mode` | `promotion` | 开启聊天促销模式。 | | `mode` | `promotion` | 开启聊天促销模式。 |
| `promotion_type` | `voice`、`image`、`private` | 指定促销消息类型，仅与 `mode=promotion` 一起使用。 | | `promotion_type` | `voice`、`image`、`private` | 指定促销消息类型，仅与 `mode=promotion` 一起使用。 |
`mode=promotion` 只有在 `target=chat` 且同时提供有效的 `promotion_type` 时生效。当前 12 条正式投放链接只使用 `promotion_type=voice`；`image` 和 `private` 保留为兼容能力，不属于本次业务清单。 `mode=promotion` 只有在 `target=chat` 且同时提供有效的 `promotion_type` 时生效。
## 四类发送模板
发送前必须把 `<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 与登录状态流程
`psid` 可以和任意有效入口参数组合使用。应用会先保存 PSID，再执行登录状态判断和 Facebook Identity 绑定。详细流程见 [PSID 与登录状态流程图](./psid-login-flow.md)。 PSID 保存、登录状态判断和 Facebook Identity 绑定逻辑见 [PSID 与登录状态流程图](./psid-login-flow.md)。
所有参数值都必须进行 URL 编码。入口中禁止传递登录 Token、Page Access Token、App Secret 或其他秘密。 ## 使用示例
## 兼容说明 普通聊天：
- 历史参数 `target=private-room` 继续兼容进入 `private-zone`，但不得用于新投放链接。 ```text
- `private_zone` 等其他拼写仍按无效目标处理并回退聊天页。 https://<APP_HOST>/external-entry?target=chat
- `promotion_type=image` 和 `promotion_type=private` 继续由现有代码支持，但不计入当前 12 条 Facebook 业务链接。 ```
- 无效或缺失的 `character` 继续回退 Elio；正式投放模板始终显式传入角色，不能依赖回退。
## 调试与正式清单 进入 Maya 聊天：
- [本地调试链接清单](./debug-links.md) ```text
- [Facebook 12 条外部入口链接清单](./links.md) https://<APP_HOST>/external-entry?target=chat&character=maya
```
携带 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
-47
View File
@@ -1,47 +0,0 @@
# 外部入口本地调试链接清单
[返回外部入口接入说明](./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
+36 -45
View File
@@ -1,52 +1,43 @@
# Facebook 12 条外部入口链接清单 # 外部入口链接清单
本清单是 Facebook 正式投放的唯一业务链接清单，共 4 类入口乘以 3 个角色，合计 12 条模板。 [返回外部入口接入说明](./README.md)
## 发送规则 以下链接可以直接点击打开。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) |
预发验证不维护第二套业务清单。将上述 12 条模板的主机统一替换为 `frontend-test.banlv-ai.com`，其余路径和参数保持不变： 如需在其他入口携带 PSID，在链接末尾追加 `&psid=27511427698460020`。
```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
-188
View File
@@ -1,188 +0,0 @@
# 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. 待确认事项
- 无。
e2e/README.md
+1 -1
View File
@@ -40,6 +40,6 @@ pnpm test:e2e:real
```bash ```bash
PLAYWRIGHT_BASE_URL=https://cozsweet.com \ PLAYWRIGHT_BASE_URL=https://cozsweet.com \
E2E_API_BASE_URL=https://api.banlv-ai.com \ E2E_API_BASE_URL=https://proapi.banlv-ai.com \
pnpm test:e2e:prod pnpm test:e2e:prod
``` ```
e2e/fixtures/api-mocks.ts
+3 -3
View File
@@ -12,7 +12,7 @@ export interface MockCoreApisOptions {
paidImageFlow?: boolean; paidImageFlow?: boolean;
paidImageInsufficientCreditsFlow?: boolean; paidImageInsufficientCreditsFlow?: boolean;
paidVoiceInsufficientCreditsFlow?: boolean; paidVoiceInsufficientCreditsFlow?: boolean;
topUpHandoffFlow?: boolean; psidLoginFlow?: boolean;
} }
export async function mockCoreApis(page: Page, options: MockCoreApisOptions = {}) { export async function mockCoreApis(page: Page, options: MockCoreApisOptions = {}) {
@@ -22,14 +22,14 @@ export async function mockCoreApis(page: Page, options: MockCoreApisOptions = {}
paidImageFlow: options.paidImageFlow ?? false, paidImageFlow: options.paidImageFlow ?? false,
paidImageInsufficientCreditsFlow: options.paidImageInsufficientCreditsFlow ?? false, paidImageInsufficientCreditsFlow: options.paidImageInsufficientCreditsFlow ?? false,
paidVoiceInsufficientCreditsFlow: options.paidVoiceInsufficientCreditsFlow ?? false, paidVoiceInsufficientCreditsFlow: options.paidVoiceInsufficientCreditsFlow ?? false,
topUpHandoffFlow: options.topUpHandoffFlow ?? false, psidLoginFlow: options.psidLoginFlow ?? false,
}; };
const chatState = { hasExpiredChatSend: false, paidImageRequested: false, paidImageUnlocked: false }; const chatState = { hasExpiredChatSend: false, paidImageRequested: false, paidImageUnlocked: false };
await registerAuthMocks(page, { await registerAuthMocks(page, {
chatSendTokenRefreshFlow: chatOptions.chatSendTokenRefreshFlow, chatSendTokenRefreshFlow: chatOptions.chatSendTokenRefreshFlow,
isChatSendTokenExpired: () => chatState.hasExpiredChatSend, isChatSendTokenExpired: () => chatState.hasExpiredChatSend,
topUpHandoffFlow: chatOptions.topUpHandoffFlow, psidLoginFlow: chatOptions.psidLoginFlow,
}); });
await registerCharacterMocks(page); await registerCharacterMocks(page);
await registerUserMocks(page); await registerUserMocks(page);
e2e/fixtures/api/auth.ts
+6 -5
View File
@@ -1,21 +1,22 @@
import type { Page } from "@playwright/test"; import type { Page } from "@playwright/test";
import { apiEnvelope } from "../data/common"; import { apiEnvelope } from "../data/common";
import { emailLoginResponse, guestLoginResponse, refreshedEmailLoginResponse, refreshedGuestLoginResponse, topUpHandoffResponse } from "../data/auth"; import { emailLoginResponse, guestLoginResponse, psidLoginResponse, refreshedEmailLoginResponse, refreshedGuestLoginResponse } from "../data/auth";
export interface AuthMockState { export interface AuthMockState {
chatSendTokenRefreshFlow: boolean; chatSendTokenRefreshFlow: boolean;
isChatSendTokenExpired: () => boolean; isChatSendTokenExpired: () => boolean;
topUpHandoffFlow: boolean; psidLoginFlow: boolean;
} }
export async function registerAuthMocks(page: Page, state: AuthMockState) { export async function registerAuthMocks(page: Page, state: AuthMockState) {
await page.route("**/api/auth/handoff/topup/consume", async (route) => { await page.route("**/api/auth/login/facebook/psid", async (route) => {
if (!state.topUpHandoffFlow) { if (!state.psidLoginFlow) {
await route.continue(); await route.continue();
return; return;
} }
await route.fulfill({ json: apiEnvelope(topUpHandoffResponse) });
await route.fulfill({ json: apiEnvelope(psidLoginResponse) });
}); });
await page.route("**/api/auth/guest", async (route) => { await page.route("**/api/auth/guest", async (route) => {
e2e/fixtures/api/chat.ts
+1 -46
View File
@@ -20,23 +20,6 @@ export interface ChatMockState {
export async function registerChatMocks(page: Page, options: ChatMockOptions, state: ChatMockState) { export async function registerChatMocks(page: Page, options: ChatMockOptions, state: ChatMockState) {
let sendCount = 0; 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) => { await page.route("**/api/chat/history**", async (route) => {
const response = options.paidVoiceInsufficientCreditsFlow const response = options.paidVoiceInsufficientCreditsFlow
? paidVoiceHistoryResponse ? paidVoiceHistoryResponse
@@ -61,35 +44,7 @@ export async function registerChatMocks(page: Page, options: ChatMockOptions, st
await route.fulfill({ status: 401, json: { message: "expired" } }); await route.fulfill({ status: 401, json: { message: "expired" } });
return; return;
} }
const response = message.includes("discount offer test") const response = options.paidImageFlow && message.includes("给我发图片")
? {
...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 ? paidImageChatSendResponse
: options.chatLimitTriggerAt != null && sendCount >= options.chatLimitTriggerAt : options.chatLimitTriggerAt != null && sendCount >= options.chatLimitTriggerAt
? createWeeklyLimitChatSendResponse(sendCount, options.chatLimitTriggerAt) ? createWeeklyLimitChatSendResponse(sendCount, options.chatLimitTriggerAt)
e2e/fixtures/api/payment.ts
-10
View File
@@ -4,16 +4,6 @@ import { apiEnvelope } from "../data/common";
import { createPaymentOrderResponse, paidPaymentOrderStatusResponse, paymentPlansResponse, tipPaymentPlansResponse, vipStatusResponse } from "../data/payment"; import { createPaymentOrderResponse, paidPaymentOrderStatusResponse, paymentPlansResponse, tipPaymentPlansResponse, vipStatusResponse } from "../data/payment";
export async function registerPaymentMocks(page: Page) { 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/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/tip-plans**", async (route) => route.fulfill({ json: apiEnvelope(tipPaymentPlansResponse) }));
await page.route("**/api/payment/create-order", async (route) => route.fulfill({ json: apiEnvelope(createPaymentOrderResponse) })); await page.route("**/api/payment/create-order", async (route) => route.fulfill({ json: apiEnvelope(createPaymentOrderResponse) }));
e2e/fixtures/data/auth.ts
+10 -12
View File
@@ -50,16 +50,14 @@ export const refreshedEmailLoginResponse = {
refreshToken: "e2e-refreshed-email-refresh-token", refreshToken: "e2e-refreshed-email-refresh-token",
}; };
export const topUpHandoffResponse = { export const psidLoginResponse = {
token: "e2e-messenger-token", token: "e2e-psid-guest-token",
refreshToken: "e2e-messenger-refresh-token", refreshToken: "",
loginStatus: "facebookMessenger", matchedBy: "psid",
merged: false, fbAsid: "",
user: { fbPsid: "e2e-facebook-psid",
...e2eEmailUser, hasCompleteFacebookIdentity: false,
id: "user_e2e_messenger", isGuest: true,
username: "E2E Messenger User", user: e2eUser,
email: "messenger_hash@messenger.cozsweet.invalid", userId: e2eUser.id,
loginProvider: "facebook_messenger",
},
}; };
e2e/fixtures/data/chat.ts
+2 -3
View File
@@ -66,7 +66,6 @@ export function createWeeklyLimitChatSendResponse(
} }
export const paidImageMessageId = "msg_photo_paywall_001"; export const paidImageMessageId = "msg_photo_paywall_001";
export const paidImageDisplayMessageId = `server:${paidImageMessageId}:assistant`;
export const paidImageUrl = export const paidImageUrl =
"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII="; "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII=";
export const paidImageChatSendResponse = { export const paidImageChatSendResponse = {
@@ -75,13 +74,13 @@ export const paidImageChatSendResponse = {
messageId: paidImageMessageId, messageId: paidImageMessageId,
isGuest: true, isGuest: true,
timestamp: 1_782_180_725_000, timestamp: 1_782_180_725_000,
image: { type: "elio_schedule", url: null }, image: { type: "elio_schedule", url: paidImageUrl },
lockDetail: { locked: true, showContent: true, showUpgrade: true, reason: "image", hint: "Activate VIP to unlock the full photo.", detail: 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) { export function createPaidImageHistoryResponse(unlocked: boolean) {
return { 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: unlocked ? paidImageUrl : null }, 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: paidImageUrl }, 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, total: 1, limit: 50, offset: 0, isVip: unlocked, privateFreeLimit: 0, privateUsedToday: 0, privateCanViewFree: false,
}; };
} }
e2e/fixtures/data/payment.ts
+1 -7
View File
@@ -10,11 +10,5 @@ export const tipPaymentPlansResponse = { plans: [
] }; ] };
export const paymentOrderId = "order_e2e_vip_monthly"; export const paymentOrderId = "order_e2e_vip_monthly";
export const createPaymentOrderResponse = { orderId: paymentOrderId, payParams: { provider: "stripe", clientSecret: "pi_e2e_secret_mock" } }; export const createPaymentOrderResponse = { orderId: paymentOrderId, payParams: { provider: "stripe", clientSecret: "pi_e2e_secret_mock" } };
export const paidPaymentOrderStatusResponse = { export const paidPaymentOrderStatusResponse = { orderId: paymentOrderId, status: "paid", orderType: "vip_monthly", planId: "vip_monthly" };
orderId: paymentOrderId,
status: "paid",
orderType: "vip_monthly",
planId: "vip_monthly",
creditsAdded: 0,
};
export const vipStatusResponse = { isVip: false, expiresAt: null }; export const vipStatusResponse = { isVip: false, expiresAt: null };
e2e/fixtures/helpers/auth.ts
+1 -1
View File
@@ -11,7 +11,7 @@ export const splashStartChatButtonName = "Start Chatting";
export const defaultCharacterSlug = "elio"; export const defaultCharacterSlug = "elio";
export const defaultCharacterSplashPath = `/characters/${defaultCharacterSlug}/splash`; export const defaultCharacterSplashPath = `/characters/${defaultCharacterSlug}/splash`;
export const defaultCharacterChatPath = `/characters/${defaultCharacterSlug}/chat`; export const defaultCharacterChatPath = `/characters/${defaultCharacterSlug}/chat`;
export const defaultCharacterProfilePath = `/profile?returnTo=%2Fcharacters%2F${defaultCharacterSlug}%2Fchat`; export const defaultCharacterSidebarPath = `/sidebar?returnTo=%2Fcharacters%2F${defaultCharacterSlug}%2Fchat`;
export const defaultCharacterChatUrl = new RegExp( export const defaultCharacterChatUrl = new RegExp(
`/characters/${defaultCharacterSlug}/chat(?:\\?.*)?$`, `/characters/${defaultCharacterSlug}/chat(?:\\?.*)?$`,
); );
e2e/fixtures/helpers/chat.ts
+3 -1
View File
@@ -27,7 +27,7 @@ export async function enterChatFromSplash(page: Page, options: { expectedUrl?: R
await expect(startChatButton).toBeVisible({ timeout }); await expect(startChatButton).toBeVisible({ timeout });
await expect(startChatButton).toBeEnabled(); await expect(startChatButton).toBeEnabled();
for (let attempt = 0; attempt < 3; attempt += 1) { for (let attempt = 0; attempt < 3; attempt += 1) {
await startChatButton.click({ timeout: 3_000 }).catch(() => {}); await startChatButton.click();
try { await expect(page).toHaveURL(expectedUrl, { timeout: 3_000 }); return; } catch { await page.waitForTimeout(500); } try { await expect(page).toHaveURL(expectedUrl, { timeout: 3_000 }); return; } catch { await page.waitForTimeout(500); }
} }
await expect(page).toHaveURL(expectedUrl, { timeout }); await expect(page).toHaveURL(expectedUrl, { timeout });
@@ -42,7 +42,9 @@ export async function dismissChatInterruptions(page: Page) {
export async function signInWithEmailAndOpenChat(page: Page) { export async function signInWithEmailAndOpenChat(page: Page) {
await seedEmailSession(page); await seedEmailSession(page);
const historyResponsePromise = page.waitForResponse("**/api/chat/history**");
await page.goto(defaultCharacterChatPath); await page.goto(defaultCharacterChatPath);
await historyResponsePromise;
await dismissChatInterruptions(page); await dismissChatInterruptions(page);
await expect(page.getByRole("textbox", { name: "Message" })).toBeEnabled({ timeout: 20_000 }); await expect(page.getByRole("textbox", { name: "Message" })).toBeEnabled({ timeout: 20_000 });
} }
e2e/fixtures/helpers/payment.ts
+1 -11
View File
@@ -1,19 +1,9 @@
import { expect, type Page } from "@playwright/test"; import { expect, type Page } from "@playwright/test";
export async function completeVipPayment(page: Page) { 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 createOrderRequestPromise = page.waitForRequest("**/api/payment/create-order");
const orderStatusRequestPromise = page.waitForRequest("**/api/payment/order-status**"); const orderStatusRequestPromise = page.waitForRequest("**/api/payment/order-status**");
await checkoutButton.click(); await page.getByRole("button", { name: /Pay and Activ/i }).click();
const createOrderRequest = await createOrderRequestPromise; const createOrderRequest = await createOrderRequestPromise;
expect(createOrderRequest.postDataJSON()).toMatchObject({ planId: "vip_monthly", payChannel: "stripe" }); expect(createOrderRequest.postDataJSON()).toMatchObject({ planId: "vip_monthly", payChannel: "stripe" });
await orderStatusRequestPromise; await orderStatusRequestPromise;
e2e/specs/mock/auth/email-login-from-other-options.spec.ts
+1 -1
View File
@@ -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); expect(["desktop", "android"]).toContain(loginRequest?.postDataJSON().platform);
await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible(); await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
await expect(page.getByRole("button", { name: "Save CozSweet" })).toBeVisible(); await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
}); });
e2e/specs/mock/auth/logout-from-profile.spec.ts → e2e/specs/mock/auth/logout-from-sidebar.spec.ts
+4 -7
View File
@@ -3,7 +3,7 @@ import { expect, test } from "@playwright/test";
import { mockCoreApis } from "@e2e/fixtures/api-mocks"; import { mockCoreApis } from "@e2e/fixtures/api-mocks";
import { import {
clearBrowserState, clearBrowserState,
defaultCharacterProfilePath, defaultCharacterSidebarPath,
defaultCharacterSplashPath, defaultCharacterSplashPath,
defaultCharacterChatUrl, defaultCharacterChatUrl,
enterChatFromSplash, enterChatFromSplash,
@@ -17,7 +17,7 @@ test.beforeEach(async ({ baseURL, context, page }) => {
await mockCoreApis(page); await mockCoreApis(page);
}); });
test("user can log out from the profile after email login", async ({ test("user can log out from the sidebar after email login", async ({
page, page,
}) => { }) => {
await enterChatFromSplash(page); await enterChatFromSplash(page);
@@ -27,14 +27,11 @@ test("user can log out from the profile after email login", async ({
await expect(page).toHaveURL(/\/auth(?:\?.*)?$/); await expect(page).toHaveURL(/\/auth(?:\?.*)?$/);
await switchToEmailSignIn(page); await switchToEmailSignIn(page);
await submitEmailLogin(page, { expectedUrl: defaultCharacterChatUrl }); await submitEmailLogin(page, { expectedUrl: defaultCharacterChatUrl });
await page.getByRole("link", { name: "Back to home" }).click(); await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
await expect(page).toHaveURL(
new RegExp(defaultCharacterSplashPath.replace("?", "\\?") + "$"),
);
await page.getByRole("button", { name: "Menu" }).click(); await page.getByRole("button", { name: "Menu" }).click();
await expect(page).toHaveURL( await expect(page).toHaveURL(
new RegExp(defaultCharacterProfilePath.replace("?", "\\?") + "$"), new RegExp(defaultCharacterSidebarPath.replace("?", "\\?") + "$"),
); );
const logoutRequestPromise = page.waitForRequest("**/api/auth/logout"); const logoutRequestPromise = page.waitForRequest("**/api/auth/logout");
e2e/specs/mock/auth/psid-login-from-external-entry.spec.ts
+24 -49
View File
@@ -1,74 +1,49 @@
import { expect, test } from "@playwright/test"; import { expect, test } from "@playwright/test";
import { mockCoreApis } from "@e2e/fixtures/api-mocks"; import { mockCoreApis } from "@e2e/fixtures/api-mocks";
import { clearBrowserState } from "@e2e/fixtures/test-helpers"; import {
clearBrowserState,
defaultCharacterChatUrl,
} from "@e2e/fixtures/test-helpers";
const handoffToken = "e2e-handoff-token-that-is-at-least-32-characters"; const psid = "e2e-facebook-psid";
test.beforeEach(async ({ baseURL, context, page }) => { test.beforeEach(async ({ baseURL, context, page }) => {
await clearBrowserState(context, page, baseURL); await clearBrowserState(context, page, baseURL);
await mockCoreApis(page, { topUpHandoffFlow: true }); await mockCoreApis(page, { psidLoginFlow: true });
}); });
test("user consumes a top-up handoff and opens credit packages as a formal Messenger user", async ({ test("user enters from an external PSID link and becomes a guest", async ({
page, page,
}) => { }) => {
const handoffRequestPromise = page.waitForRequest( const psidLoginRequestPromise = page.waitForRequest(
"**/api/auth/handoff/topup/consume", "**/api/auth/login/facebook/psid",
); );
await page.goto( await page.goto(`/external-entry?target=chat&psid=${psid}`);
`/external-entry?target=topup&handoffToken=${encodeURIComponent(handoffToken)}`,
);
const handoffRequest = await handoffRequestPromise; const psidLoginRequest = await psidLoginRequestPromise;
expect(handoffRequest.method()).toBe("POST"); expect(psidLoginRequest.method()).toBe("POST");
expect(handoffRequest.postDataJSON()).toEqual({ handoffToken }); expect(psidLoginRequest.postDataJSON()).toMatchObject({
psid,
bindToGuest: true,
});
expect(psidLoginRequest.postDataJSON().deviceId).toEqual(expect.any(String));
await expect(page).toHaveURL("/subscription?type=topup"); await expect(page).toHaveURL(defaultCharacterChatUrl);
await expect( await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
page.getByRole("button", { name: /Pay and Top Up/i }),
).toBeVisible();
await expect await expect
.poll(() => .poll(() =>
page.evaluate(() => ({ page.evaluate(() => ({
loginProvider: localStorage.getItem("cozsweet:login_provider"), loginProvider: localStorage.getItem("cozsweet:login_provider"),
loginToken: localStorage.getItem("cozsweet:login_token"), guestToken: localStorage.getItem("cozsweet:guest_token"),
refreshToken: localStorage.getItem("cozsweet:refresh_token"), psid: localStorage.getItem("cozsweet:psid"),
})), })),
) )
.toMatchObject({ .toMatchObject({
loginProvider: "facebookMessenger", loginProvider: "guest",
loginToken: "e2e-messenger-token", guestToken: "e2e-psid-guest-token",
refreshToken: "e2e-messenger-refresh-token", psid,
}); });
}); });
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
-86
View File
@@ -1,86 +0,0 @@
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
-49
View File
@@ -1,49 +0,0 @@
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
-201
View File
@@ -1,201 +0,0 @@
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
+5 -1
View File
@@ -7,6 +7,7 @@ import {
defaultCharacterChatUrl, defaultCharacterChatUrl,
expectInsufficientCreditsDialog, expectInsufficientCreditsDialog,
expectVipChatSubscriptionUrl, expectVipChatSubscriptionUrl,
setEmailSessionStorage,
submitEmailLogin, submitEmailLogin,
switchToEmailSignIn, switchToEmailSignIn,
} from "@e2e/fixtures/test-helpers"; } from "@e2e/fixtures/test-helpers";
@@ -35,10 +36,13 @@ test("guest unlocks a promoted image through email login and top-up", async ({
await expect(page).toHaveURL(/\/auth\?redirect=/); await expect(page).toHaveURL(/\/auth\?redirect=/);
await switchToEmailSignIn(page); await switchToEmailSignIn(page);
await submitEmailLogin(page, { expectedUrl: defaultCharacterChatUrl });
await setEmailSessionStorage(page);
const unlockRequestPromise = page.waitForRequest( const unlockRequestPromise = page.waitForRequest(
"**/api/chat/unlock-private", "**/api/chat/unlock-private",
); );
await submitEmailLogin(page, { expectedUrl: defaultCharacterChatUrl }); await page.reload();
const unlockRequest = await unlockRequestPromise; const unlockRequest = await unlockRequestPromise;
expect(unlockRequest.method()).toBe("POST"); expect(unlockRequest.method()).toBe("POST");
e2e/specs/mock/favorite-menu-navigation.spec.ts
-206
View File
@@ -1,206 +0,0 @@
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
-264
View File
@@ -1,264 +0,0 @@
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
+28 -52
View File
@@ -1,12 +1,7 @@
import { expect, test } from "@playwright/test"; import { expect, test } from "@playwright/test";
import { mockCoreApis } from "@e2e/fixtures/api-mocks"; import { mockCoreApis } from "@e2e/fixtures/api-mocks";
import { apiEnvelope } from "@e2e/fixtures/data/common"; import { paidImageMessageId } from "@e2e/fixtures/test-data";
import { createPaidImageHistoryResponse } from "@e2e/fixtures/data/chat";
import {
paidImageDisplayMessageId,
paidImageMessageId,
} from "@e2e/fixtures/test-data";
import { import {
clearBrowserState, clearBrowserState,
completeVipPayment, completeVipPayment,
@@ -15,10 +10,15 @@ import {
enterChatFromSplash, enterChatFromSplash,
expectInsufficientCreditsDialog, expectInsufficientCreditsDialog,
expectVipChatSubscriptionUrl, expectVipChatSubscriptionUrl,
setEmailSessionStorage,
submitEmailLogin, submitEmailLogin,
switchToEmailSignIn, switchToEmailSignIn,
} from "@e2e/fixtures/test-helpers"; } from "@e2e/fixtures/test-helpers";
const paidImageOverlayUrl = new RegExp(
`${defaultCharacterChatPath}\\?image=${paidImageMessageId}$`,
);
test.beforeEach(async ({ baseURL, context, page }) => { test.beforeEach(async ({ baseURL, context, page }) => {
await clearBrowserState(context, page, baseURL); await clearBrowserState(context, page, baseURL);
await mockCoreApis(page, { await mockCoreApis(page, {
@@ -44,27 +44,38 @@ test("guest can unlock a paid image after email login and subscription payment",
message: "给我发图片", message: "给我发图片",
}); });
const lockedImageCard = page.getByRole("group", { const paidImageButton = page.getByRole("button", {
name: "Locked private image", name: "Open image in fullscreen",
}).last(); }).last();
await expect(lockedImageCard).toBeVisible(); await expect(paidImageButton).toBeVisible();
await expect(lockedImageCard.locator("img")).toHaveCount(0);
await lockedImageCard await paidImageButton.click();
.getByRole("button", { name: "Unlock private image" }) await expect(page).toHaveURL(paidImageOverlayUrl);
const lockedImageDialog = page.getByRole("dialog", {
name: "Locked fullscreen image",
});
await expect(lockedImageDialog).toBeVisible();
await lockedImageDialog
.getByRole("button", { name: "Unlock high-definition large image" })
.click(); .click();
await expect(page).toHaveURL(/\/auth\?redirect=/); await expect(page).toHaveURL(/\/auth\?redirect=/);
expect(new URL(page.url()).searchParams.get("redirect")).toBe( expect(new URL(page.url()).searchParams.get("redirect")).toBe(
defaultCharacterChatPath, `${defaultCharacterChatPath}?image=${paidImageMessageId}`,
); );
await switchToEmailSignIn(page); await switchToEmailSignIn(page);
await submitEmailLogin(page, {
expectedUrl: paidImageOverlayUrl,
});
await setEmailSessionStorage(page);
const unlockRequestPromise = page.waitForRequest( const unlockRequestPromise = page.waitForRequest(
"**/api/chat/unlock-private", "**/api/chat/unlock-private",
); );
await submitEmailLogin(page, { await page.goto(`${defaultCharacterChatPath}?image=${paidImageMessageId}`);
expectedUrl: new RegExp(`${defaultCharacterChatPath}$`),
});
const unlockRequest = await unlockRequestPromise; const unlockRequest = await unlockRequestPromise;
expect(unlockRequest.postDataJSON()).toMatchObject({ expect(unlockRequest.postDataJSON()).toMatchObject({
@@ -81,44 +92,9 @@ test("guest can unlock a paid image after email login and subscription payment",
await expect(page).toHaveURL( await expect(page).toHaveURL(
new RegExp( new RegExp(
`${defaultCharacterChatPath}(?:\\?image=${encodeURIComponent(paidImageDisplayMessageId)})?$`, `${defaultCharacterChatPath}(?:\\?image=msg_photo_paywall_001)?$`,
), ),
); );
expect(new URL(page.url()).pathname).toBe(defaultCharacterChatPath); expect(new URL(page.url()).pathname).toBe(defaultCharacterChatPath);
await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible(); 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
-119
View File
@@ -1,119 +0,0 @@
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
-422
View File
@@ -1,422 +0,0 @@
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
-153
View File
@@ -1,153 +0,0 @@
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
-164
View File
@@ -1,164 +0,0 @@
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
+20 -10
View File
@@ -1,17 +1,20 @@
import { expect, test } from "@playwright/test"; import { expect, test } from "@playwright/test";
import { mockCoreApis } from "@e2e/fixtures/api-mocks"; import { mockCoreApis } from "@e2e/fixtures/api-mocks";
import { import { paidImageMessageId } from "@e2e/fixtures/test-data";
paidImageMessageId,
} from "@e2e/fixtures/test-data";
import { import {
clearBrowserState, clearBrowserState,
defaultCharacterChatPath,
dismissChatInterruptions, dismissChatInterruptions,
expectInsufficientCreditsDialog, expectInsufficientCreditsDialog,
expectVipChatSubscriptionUrl, expectVipChatSubscriptionUrl,
signInWithEmailAndOpenChat, signInWithEmailAndOpenChat,
} from "@e2e/fixtures/test-helpers"; } from "@e2e/fixtures/test-helpers";
const paidImageOverlayUrl = new RegExp(
`${defaultCharacterChatPath}\\?image=${paidImageMessageId}$`,
);
test.beforeEach(async ({ baseURL, context, page }) => { test.beforeEach(async ({ baseURL, context, page }) => {
await clearBrowserState(context, page, baseURL); await clearBrowserState(context, page, baseURL);
await mockCoreApis(page, { await mockCoreApis(page, {
@@ -19,23 +22,30 @@ test.beforeEach(async ({ baseURL, context, page }) => {
}); });
}); });
test("user sees insufficient credits when unlocking from the locked image card and can navigate to subscription", async ({ test("user sees insufficient credits when unlocking a paid image from fullscreen and can navigate to subscription", async ({
page, page,
}) => { }) => {
await signInWithEmailAndOpenChat(page); await signInWithEmailAndOpenChat(page);
await dismissChatInterruptions(page); await dismissChatInterruptions(page);
const lockedImageCard = page.getByRole("group", { const paidImageButton = page.getByRole("button", {
name: "Locked private image", name: "Open image in fullscreen",
}).last(); }).last();
await expect(lockedImageCard).toBeVisible({ timeout: 10_000 }); await expect(paidImageButton).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( const unlockRequestPromise = page.waitForRequest(
"**/api/chat/unlock-private", "**/api/chat/unlock-private",
); );
await lockedImageCard await lockedImageDialog
.getByRole("button", { name: "Unlock private image" }) .getByRole("button", { name: "Unlock high-definition large image" })
.click(); .click();
const unlockRequest = await unlockRequestPromise; const unlockRequest = await unlockRequestPromise;
e2e/specs/real/email-login-from-other-options.spec.ts
+1 -1
View File
@@ -42,7 +42,7 @@ test.describe("pre-release email login smoke", () => {
urlTimeout: 20_000, urlTimeout: 20_000,
}); });
await expect(page.getByRole("button", { name: "Profile" })).toBeVisible(); await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible(); await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
}); });
}); });
env-example/.env.local.example
-1
View File
@@ -5,7 +5,6 @@ NEXTAUTH_URL=https://frontend-test.banlv-ai.com
NEXTAUTH_URL_INTERNAL=http://localhost:3000 NEXTAUTH_URL_INTERNAL=http://localhost:3000
NEXT_PUBLIC_API_BASE_URL=https://proapi.banlv-ai.com NEXT_PUBLIC_API_BASE_URL=https://proapi.banlv-ai.com
NEXT_PUBLIC_WS_BASE_URL=wss://proapi.banlv-ai.com/ws 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_STRIPE_PUBLISHABLE_KEY=pk_test_51Te8ybEJDtUGxQHo0UMySJ2hW0vVryynzllmIUI3UQdQCFgxNLci0Jmm2lQkRsTaIP7C7IQlFzfFyBJ5rOhr1ML800G8P8DF5R
NEXT_PUBLIC_API_CONNECT_TIMEOUT=30000 NEXT_PUBLIC_API_CONNECT_TIMEOUT=30000
env-example/.env.production.example
-1
View File
@@ -10,7 +10,6 @@ NEXT_PUBLIC_API_BASE_URL=https://api.banlv-ai.com
# WebSocket URL（生产环境） # WebSocket URL（生产环境）
NEXT_PUBLIC_WS_BASE_URL=wss://api.banlv-ai.com/ws NEXT_PUBLIC_WS_BASE_URL=wss://api.banlv-ai.com/ws
NEXT_PUBLIC_ENABLE_VOICE_CALL=false
# Stripe 支付（publishable key 可暴露在浏览器端） # Stripe 支付（publishable key 可暴露在浏览器端）
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_51Te8ybEJDtUGxQHouKlEMfMuCZWifzlhBIReeKvANOtyCXS4zL0SMTWJXiFHPKz7azpF6OnIKXUPFSLs82fevVjr00w1bw5mvl NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_51Te8ybEJDtUGxQHouKlEMfMuCZWifzlhBIReeKvANOtyCXS4zL0SMTWJXiFHPKz7azpF6OnIKXUPFSLs82fevVjr00w1bw5mvl
icons/test/favicon.ico
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 15 KiB

icons/test/icons/Icon-192.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.7 KiB

After

Width:  |  Height:  |  Size: 11 KiB

icons/test/icons/Icon-512.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 19 KiB

After

Width:  |  Height:  |  Size: 35 KiB

package.json
+2 -3
View File
@@ -25,9 +25,9 @@
"test:e2e:chrome": "PLAYWRIGHT_USE_SYSTEM_CHROME=1 playwright test --project=mock-chromium", "test:e2e:chrome": "PLAYWRIGHT_USE_SYSTEM_CHROME=1 playwright test --project=mock-chromium",
"test:e2e:headed": "playwright test --project=mock-chromium --headed", "test:e2e:headed": "playwright test --project=mock-chromium --headed",
"test:e2e:ui": "playwright test --ui", "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-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: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: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: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://api.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://proapi.banlv-ai.com} playwright test --project=prod-smoke",
"contract:check": "node scripts/contracts/check-openapi.mjs", "contract:check": "node scripts/contracts/check-openapi.mjs",
"test:contracts": "node --test scripts/contracts/__tests__/*.test.mjs", "test:contracts": "node --test scripts/contracts/__tests__/*.test.mjs",
"perf:bundle": "next experimental-analyze --output && node scripts/performance/report-bundle.mjs", "perf:bundle": "next experimental-analyze --output && node scripts/performance/report-bundle.mjs",
@@ -50,7 +50,6 @@
"next-auth": "^4.24.14", "next-auth": "^4.24.14",
"ofetch": "^1.5.1", "ofetch": "^1.5.1",
"pino": "^10.3.1", "pino": "^10.3.1",
"qrcode.react": "^4.2.0",
"react": "19.2.4", "react": "19.2.4",
"react-dom": "19.2.4", "react-dom": "19.2.4",
"react-icons": "^5.6.0", "react-icons": "^5.6.0",
playwright.config.ts
+1 -4
View File
@@ -12,10 +12,7 @@ export default defineConfig({
fullyParallel: true, fullyParallel: true,
forbidOnly: Boolean(process.env.CI), forbidOnly: Boolean(process.env.CI),
retries: process.env.CI ? 2 : 0, retries: process.env.CI ? 2 : 0,
// Next.js dev + Turbopack can return incomplete module payloads when the workers: process.env.CI ? 1 : undefined,
// local mock suite compiles many routes concurrently. Keep this tier
// deterministic locally as well as in CI.
workers: 1,
reporter: process.env.CI reporter: process.env.CI
? [["list"], ["html", { open: "never" }]] ? [["list"], ["html", { open: "never" }]]
: [["list"], ["html", { open: "never" }]], : [["list"], ["html", { open: "never" }]],
pnpm-lock.yaml
Generated
-12
View File
@@ -50,9 +50,6 @@ importers:
pino: pino:
specifier: ^10.3.1 specifier: ^10.3.1
version: 10.3.1 version: 10.3.1
qrcode.react:
specifier: ^4.2.0
version: 4.2.0(react@19.2.4)
react: react:
specifier: 19.2.4 specifier: 19.2.4
version: 19.2.4 version: 19.2.4
@@ -3293,11 +3290,6 @@ packages:
resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==} resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
engines: {node: '>=6'} 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: queue-microtask@1.2.3:
resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==} resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==}
@@ -7093,10 +7085,6 @@ snapshots:
punycode@2.3.1: {} punycode@2.3.1: {}
qrcode.react@4.2.0(react@19.2.4):
dependencies:
react: 19.2.4
queue-microtask@1.2.3: {} queue-microtask@1.2.3: {}
quick-format-unescaped@4.0.4: {} quick-format-unescaped@4.0.4: {}
public/images/cover/maya-home.webp
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 482 KiB

public/images/cover/maya.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 351 KiB

public/images/cover/maya.webp
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 581 KiB

public/images/cover/nayeli.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 351 KiB

public/images/cover/nayeli.webp
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 129 KiB

public/images/private-zone/banner/elio.png → public/images/private-room/banner/elio.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 814 KiB

After

Width:  |  Height:  |  Size: 814 KiB

public/images/private-zone/banner/maya.png → public/images/private-room/banner/maya.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 652 KiB

After

Width:  |  Height:  |  Size: 652 KiB

public/images/private-zone/banner/nayeli.png → public/images/private-room/banner/nayeli.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 907 KiB

After

Width:  |  Height:  |  Size: 907 KiB

public/images/profile/ic_user_vip.png → public/images/sidebar/ic_user_vip.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.7 KiB

After

Width:  |  Height:  |  Size: 2.7 KiB

public/images/profile/ic_user_voicemessage.png → public/images/sidebar/ic_user_voicemessage.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 10 KiB

After

Width:  |  Height:  |  Size: 10 KiB

public/images/profile/pic_bg_vip.png → public/images/sidebar/pic_bg_vip.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.3 KiB

After

Width:  |  Height:  |  Size: 7.3 KiB

public/images/tip/large.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 577 KiB

After

Width:  |  Height:  |  Size: 663 KiB

public/images/tip/medium.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 342 KiB

After

Width:  |  Height:  |  Size: 468 KiB

public/images/tip/small.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

public/images/tip/small.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 490 KiB

public/manifest.json
+2 -2
View File
@@ -11,13 +11,13 @@
"lang": "en", "lang": "en",
"icons": [ "icons": [
{ {
"src": "/images/icons/Icon-192.png?v=20260724", "src": "/images/icons/Icon-192.png",
"sizes": "192x192", "sizes": "192x192",
"type": "image/png", "type": "image/png",
"purpose": "any" "purpose": "any"
}, },
{ {
"src": "/images/icons/Icon-512.png?v=20260724", "src": "/images/icons/Icon-512.png",
"sizes": "512x512", "sizes": "512x512",
"type": "image/png", "type": "image/png",
"purpose": "any" "purpose": "any"
scripts/contracts/__tests__/domestic-test-workflow.test.mjs
-34
View File
@@ -1,34 +0,0 @@
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
+2 -2
View File
@@ -13,13 +13,13 @@ describe("OpenAPI contract comparison", () => {
chatHistory: { method: "get", path: "/api/chat/history" }, chatHistory: { method: "get", path: "/api/chat/history" },
unlockAlbum: { unlockAlbum: {
method: "post", method: "post",
path: "/api/private-zone/albums/{albumId}/unlock", path: "/api/private-room/albums/{albumId}/unlock",
}, },
}, },
{ {
paths: { paths: {
"/api/chat/history": { get: {} }, "/api/chat/history": { get: {} },
"/api/private-zone/albums/{album_id}/unlock/": { post: {} }, "/api/private-room/albums/{album_id}/unlock/": { post: {} },
}, },
}, },
); );
scripts/server/deploy-docker-image.sh
+2
View File
@@ -49,6 +49,8 @@ echo "=== compose project: $COMPOSE_PROJECT_NAME ==="
"${COMPOSE[@]}" up -d --remove-orphans --no-build web "${COMPOSE[@]}" up -d --remove-orphans --no-build web
"${COMPOSE[@]}" ps "${COMPOSE[@]}" ps
docker image prune -f
prune_project_images() { prune_project_images() {
local retain_count="$1" local retain_count="$1"
if ! [[ "$retain_count" =~ ^[0-9]+$ ]] || [ "$retain_count" -le 0 ]; then if ! [[ "$retain_count" =~ ^[0-9]+$ ]] || [ "$retain_count" -le 0 ]; then
scripts/server/deploy-domestic-test-archive.sh
-110
View File
@@ -1,110 +0,0 @@
#!/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
-30
View File
@@ -79,34 +79,4 @@ describe("shared Tailwind components", () => {
expect(guestHtml).toContain('aria-label="Guest avatar"'); expect(guestHtml).toContain('aria-label="Guest avatar"');
expect(guestHtml).toContain("%2Fimages%2Favatar%2Fplaceholder.png"); 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
-11
View File
@@ -1,11 +0,0 @@
export type AvatarInteractionProps =
| {
onClick?: undefined;
actionLabel?: never;
analyticsKey?: never;
}
| {
onClick: () => void;
actionLabel: string;
analyticsKey?: string;
};
src/app/_components/character-avatar.tsx
+18 -47
View File
@@ -3,9 +3,7 @@
import Image from "next/image"; import Image from "next/image";
import type { CSSProperties } from "react"; import type { CSSProperties } from "react";
import type { AvatarInteractionProps } from "./avatar-interaction"; export interface CharacterAvatarProps {
interface CharacterAvatarVisualProps {
src: string; src: string;
alt: string; alt: string;
className?: string; className?: string;
@@ -14,9 +12,6 @@ interface CharacterAvatarVisualProps {
priority?: boolean; priority?: boolean;
} }
export type CharacterAvatarProps = CharacterAvatarVisualProps &
AvatarInteractionProps;
export function CharacterAvatar({ export function CharacterAvatar({
src, src,
alt, alt,
@@ -24,9 +19,6 @@ export function CharacterAvatar({
size = 43, size = 43,
imageSize, imageSize,
priority = false, priority = false,
onClick,
actionLabel,
analyticsKey,
}: CharacterAvatarProps) { }: CharacterAvatarProps) {
const resolvedImageSize = const resolvedImageSize =
imageSize ?? (typeof size === "number" ? size : 96); imageSize ?? (typeof size === "number" ? size : 96);
@@ -35,45 +27,24 @@ export function CharacterAvatar({
height: size, 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 ( return (
<span className={avatarClassName} style={style}> <span
{image} className={[
"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> </span>
); );
} }
src/app/_components/core/__tests__/favorite-entry-button.test.tsx
-80
View File
@@ -1,80 +0,0 @@
/* @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
-119
View File
@@ -1,119 +0,0 @@
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
+11 -15
View File
@@ -79,20 +79,18 @@ describe("core Tailwind components", () => {
<AppBottomNav <AppBottomNav
activeItem="chat" activeItem="chat"
variant="dark" variant="dark"
privateZoneLabel="Maya Private Zone" privateRoomLabel="Maya Private room"
onChatClick={() => undefined} onChatClick={() => undefined}
onPrivateZoneClick={() => undefined} onPrivateRoomClick={() => undefined}
onMenuClick={() => undefined}
/>, />,
); );
const privateZoneHtml = renderToStaticMarkup( const privateRoomHtml = renderToStaticMarkup(
<AppBottomNav <AppBottomNav
activeItem="privateZone" activeItem="privateRoom"
variant="warm" variant="warm"
privateZoneLabel="Maya Private Zone" privateRoomLabel="Maya Private room"
onChatClick={() => undefined} onChatClick={() => undefined}
onPrivateZoneClick={() => undefined} onPrivateRoomClick={() => undefined}
onMenuClick={() => undefined}
/>, />,
); );
@@ -101,15 +99,13 @@ describe("core Tailwind components", () => {
expect(chatHtml).toMatch( expect(chatHtml).toMatch(
/<button[^>]*aria-current="page"[^>]*>.*?<span>Chat<\/span>/, /<button[^>]*aria-current="page"[^>]*>.*?<span>Chat<\/span>/,
); );
expect(privateZoneHtml).toMatch(/class="[^"]*warm[^"]*"/); expect(privateRoomHtml).toMatch(/class="[^"]*warm[^"]*"/);
expect(privateZoneHtml).toMatch( expect(privateRoomHtml).toMatch(
/<button[^>]*aria-current="page"[^>]*>.*?<span>Maya Private Zone<\/span>/, /<button[^>]*aria-current="page"[^>]*>.*?<span>Maya Private room<\/span>/,
); );
expect(chatHtml).toContain('data-analytics-key="navigation.chat"'); expect(chatHtml).toContain('data-analytics-key="navigation.chat"');
expect(privateZoneHtml).toContain( expect(privateRoomHtml).toContain(
'data-analytics-key="navigation.private_zone"', 'data-analytics-key="navigation.private_room"',
); );
expect(chatHtml).toContain('data-analytics-key="navigation.menu"');
expect(chatHtml).toContain("<span>Menu</span>");
}); });
}); });
src/app/_components/core/app-bottom-nav.module.css
+1 -1
View File
@@ -4,7 +4,7 @@
left: 50%; left: 50%;
z-index: 30; z-index: 30;
display: grid; display: grid;
grid-template-columns: repeat(3, minmax(0, 1fr)); grid-template-columns: 1fr 1fr;
box-sizing: border-box; box-sizing: border-box;
width: min(100vw, var(--app-max-width, 540px)); width: min(100vw, var(--app-max-width, 540px));
min-height: calc( min-height: calc(
src/app/_components/core/app-bottom-nav.tsx
+12 -25
View File
@@ -1,28 +1,26 @@
"use client"; "use client";
import { Camera, Menu as MenuIcon, MessageCircle } from "lucide-react"; import { Camera, MessageCircle } from "lucide-react";
import styles from "./app-bottom-nav.module.css"; import styles from "./app-bottom-nav.module.css";
export type AppBottomNavItem = "chat" | "privateZone" | "menu"; export type AppBottomNavItem = "chat" | "privateRoom";
export type AppBottomNavVariant = "warm" | "dark"; export type AppBottomNavVariant = "warm" | "dark";
export interface AppBottomNavProps { export interface AppBottomNavProps {
activeItem?: AppBottomNavItem | null; activeItem?: AppBottomNavItem | null;
variant?: AppBottomNavVariant; variant?: AppBottomNavVariant;
privateZoneLabel: string; privateRoomLabel: string;
onChatClick: () => void; onChatClick: () => void;
onPrivateZoneClick: () => void; onPrivateRoomClick: () => void;
onMenuClick: () => void;
} }
export function AppBottomNav({ export function AppBottomNav({
activeItem = null, activeItem = null,
variant = "warm", variant = "warm",
privateZoneLabel, privateRoomLabel,
onChatClick, onChatClick,
onPrivateZoneClick, onPrivateRoomClick,
onMenuClick,
}: AppBottomNavProps) { }: AppBottomNavProps) {
return ( return (
<nav className={getRootClass(variant)} aria-label="Primary navigation"> <nav className={getRootClass(variant)} aria-label="Primary navigation">
@@ -39,25 +37,14 @@ export function AppBottomNav({
</button> </button>
<button <button
type="button" type="button"
data-analytics-key="navigation.private_zone" data-analytics-key="navigation.private_room"
data-analytics-label="Private Zone navigation" data-analytics-label="Private room navigation"
className={getButtonClass(activeItem === "privateZone")} className={getButtonClass(activeItem === "privateRoom")}
aria-current={activeItem === "privateZone" ? "page" : undefined} aria-current={activeItem === "privateRoom" ? "page" : undefined}
onClick={onPrivateZoneClick} onClick={onPrivateRoomClick}
> >
<Camera size={20} aria-hidden="true" /> <Camera size={20} aria-hidden="true" />
<span>{privateZoneLabel}</span> <span>{privateRoomLabel}</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> </button>
</nav> </nav>
); );
src/app/_components/core/favorite-entry-button.module.css
-175
View File
@@ -1,175 +0,0 @@
.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
-162
View File
@@ -1,162 +0,0 @@
"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
-1
View File
@@ -5,7 +5,6 @@
export * from "./app-bottom-nav"; export * from "./app-bottom-nav";
export * from "./bottom-sheet"; export * from "./bottom-sheet";
export * from "./checkbox"; export * from "./checkbox";
export * from "./favorite-entry-button";
export * from "./loading-indicator"; export * from "./loading-indicator";
export * from "./mobile-shell"; export * from "./mobile-shell";
export * from "./page-loading-fallback"; export * from "./page-loading-fallback";
src/app/_components/core/modal-portal.tsx
+1 -9
View File
@@ -20,10 +20,7 @@ export interface ModalPortalProps {
scrimOpacity: number; scrimOpacity: number;
panelStyle?: CSSProperties; panelStyle?: CSSProperties;
persistent?: boolean; persistent?: boolean;
role?: "dialog" | "alertdialog";
ariaLabel?: string; ariaLabel?: string;
ariaLabelledBy?: string;
ariaDescribedBy?: string;
} }
export function ModalPortal({ export function ModalPortal({
@@ -35,10 +32,7 @@ export function ModalPortal({
scrimOpacity, scrimOpacity,
panelStyle, panelStyle,
persistent = false, persistent = false,
role = "dialog",
ariaLabel, ariaLabel,
ariaLabelledBy,
ariaDescribedBy,
}: ModalPortalProps) { }: ModalPortalProps) {
useEffect(() => { useEffect(() => {
if (!open || typeof document === "undefined") return; if (!open || typeof document === "undefined") return;
@@ -69,11 +63,9 @@ export function ModalPortal({
onClick={handleScrimClick} onClick={handleScrimClick}
> >
<div <div
role={role} role="dialog"
aria-modal="true" aria-modal="true"
aria-label={ariaLabel} aria-label={ariaLabel}
aria-labelledby={ariaLabelledBy}
aria-describedby={ariaDescribedBy}
className={panelClassName} className={panelClassName}
style={panelStyle} style={panelStyle}
onClick={(event) => event.stopPropagation()} onClick={(event) => event.stopPropagation()}
src/app/_components/index.ts
-1
View File
@@ -3,6 +3,5 @@
*/ */
export * from "./back-button"; export * from "./back-button";
export * from "./avatar-interaction";
export * from "./character-avatar"; export * from "./character-avatar";
export * from "./user-message-avatar"; export * from "./user-message-avatar";
src/app/_components/payment/__tests__/payment-launch-dialogs.test.tsx
+23 -164
View File
@@ -1,47 +1,23 @@
import { act } from "react"; import { renderToStaticMarkup } from "react-dom/server";
import { createRoot, type Root } from "react-dom/client"; import { describe, expect, it, vi } from "vitest";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { PaymentLaunchDialogs } from "../payment-launch-dialogs"; import { PaymentLaunchDialogs } from "../payment-launch-dialogs";
const hiddenLaunch = { const hiddenLaunch = {
handleEzpayCancel: vi.fn(), handleEzpayCancel: vi.fn(),
handleEzpayConfirm: vi.fn(), handleEzpayConfirm: vi.fn(),
handleRegionalQrClose: vi.fn(),
handleStripeClose: vi.fn(), handleStripeClose: vi.fn(),
handleStripeConfirmed: vi.fn(), handleStripeConfirmed: vi.fn(),
isConfirmingEzpay: false, isConfirmingEzpay: false,
regionalQrErrorMessage: null,
regionalQrPayment: null,
regionalQrStatus: null,
shouldShowEzpayConfirmDialog: false, shouldShowEzpayConfirmDialog: false,
shouldShowRegionalQrDialog: false,
shouldShowStripeDialog: false, shouldShowStripeDialog: false,
stripeClientSecret: null, stripeClientSecret: null,
}; };
describe("PaymentLaunchDialogs", () => { 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", () => { it("renders nothing when neither payment dialog is active", () => {
act(() => expect(
root.render( renderToStaticMarkup(
<PaymentLaunchDialogs <PaymentLaunchDialogs
currentOrderId={null} currentOrderId={null}
externalCheckoutAnalyticsKey="payment.external_checkout" externalCheckoutAnalyticsKey="payment.external_checkout"
@@ -49,145 +25,28 @@ describe("PaymentLaunchDialogs", () => {
launch={hiddenLaunch} launch={hiddenLaunch}
/>, />,
), ),
); ).toBe("");
expect(document.body.querySelector('[role="dialog"]')).toBeNull();
expect(document.body.querySelector('[role="alertdialog"]')).toBeNull();
}); });
it("portals the shared Ezpay confirmation outside transformed checkout UI", () => { it("renders the shared Ezpay confirmation content", () => {
act(() => const html = renderToStaticMarkup(
root.render( <PaymentLaunchDialogs
<PaymentLaunchDialogs currentOrderId="order-123"
currentOrderId="order-123" externalCheckoutAnalyticsKey="tip.external_checkout"
externalCheckoutAnalyticsKey="tip.external_checkout" ezpayDescription="Your coffee order is ready."
ezpayDescription="Your coffee order is ready." launch={{
launch={{ ...hiddenLaunch,
...hiddenLaunch, isConfirmingEzpay: true,
isConfirmingEzpay: true, shouldShowEzpayConfirmDialog: true,
shouldShowEzpayConfirmDialog: true, }}
}} />,
/>,
),
); );
const dialog = document.body.querySelector('[role="alertdialog"]'); expect(html).toContain('role="alertdialog"');
expect(dialog).not.toBeNull(); expect(html).toContain("Continue to GCash?");
expect(container.contains(dialog)).toBe(false); expect(html).toContain("Your coffee order is ready.");
expect(dialog?.parentElement?.parentElement).toBe(document.body); expect(html).toContain("Order No. order-123");
expect(dialog?.textContent).toContain("Continue to payment?"); expect(html).toContain('data-analytics-key="tip.external_checkout"');
expect(dialog?.textContent).toContain("Your coffee order is ready."); expect(html).toContain("Opening...");
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
-43
View File
@@ -62,49 +62,6 @@ 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", () => { it("does not render when payment method selection is unavailable", () => {
const html = renderToStaticMarkup( const html = renderToStaticMarkup(
<PaymentMethodSelector <PaymentMethodSelector
src/app/_components/payment/__tests__/stripe-payment-dialog.test.tsx
-63
View File
@@ -1,63 +0,0 @@
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
+9 -17
View File
@@ -2,8 +2,6 @@
import dynamic from "next/dynamic"; import dynamic from "next/dynamic";
import { ModalPortal } from "@/app/_components/core/modal-portal";
import type { StripePaymentDialogProps } from "./stripe-payment-dialog"; import type { StripePaymentDialogProps } from "./stripe-payment-dialog";
import { stripePaymentDialogStyles as styles } from "./stripe-payment-dialog.styles"; import { stripePaymentDialogStyles as styles } from "./stripe-payment-dialog.styles";
@@ -22,28 +20,22 @@ export function LazyStripePaymentDialog(props: StripePaymentDialogProps) {
return <StripePaymentDialog {...props} />; return <StripePaymentDialog {...props} />;
} }
export function StripePaymentDialogLoading() { function StripePaymentDialogLoading() {
return ( return (
<ModalPortal <div
open className={styles.overlay}
persistent role="dialog"
onClose={() => undefined} aria-modal="true"
scrimClassName={styles.overlay} aria-labelledby="stripe-payment-loading-title"
panelClassName={styles.dialog}
scrimOpacity={0.5}
ariaLabelledBy="stripe-payment-loading-title"
ariaDescribedBy="stripe-payment-loading-description"
> >
<div aria-busy="true"> <div className={styles.dialog} aria-busy="true">
<div className={styles.header}> <div className={styles.header}>
<h2 id="stripe-payment-loading-title" className={styles.title}> <h2 id="stripe-payment-loading-title" className={styles.title}>
Preparing secure payment Preparing secure payment
</h2> </h2>
<p id="stripe-payment-loading-description" className={styles.content}> <p className={styles.content}>Loading payment methods...</p>
Loading payment methods...
</p>
</div> </div>
</div> </div>
</ModalPortal> </div>
); );
} }
src/app/_components/payment/payment-launch-dialogs.tsx
+33 -195
View File
@@ -1,9 +1,7 @@
"use client"; "use client";
import { useId, type ReactNode } from "react"; 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 type { PaymentLaunchFlow } from "@/app/_hooks/use-payment-launch-flow";
import { LazyStripePaymentDialog } from "./lazy-stripe-payment-dialog"; import { LazyStripePaymentDialog } from "./lazy-stripe-payment-dialog";
@@ -13,15 +11,10 @@ type PaymentLaunchDialogFlow = Pick<
PaymentLaunchFlow, PaymentLaunchFlow,
| "handleEzpayCancel" | "handleEzpayCancel"
| "handleEzpayConfirm" | "handleEzpayConfirm"
| "handleRegionalQrClose"
| "handleStripeClose" | "handleStripeClose"
| "handleStripeConfirmed" | "handleStripeConfirmed"
| "isConfirmingEzpay" | "isConfirmingEzpay"
| "regionalQrErrorMessage"
| "regionalQrPayment"
| "regionalQrStatus"
| "shouldShowEzpayConfirmDialog" | "shouldShowEzpayConfirmDialog"
| "shouldShowRegionalQrDialog"
| "shouldShowStripeDialog" | "shouldShowStripeDialog"
| "stripeClientSecret" | "stripeClientSecret"
>; >;
@@ -53,14 +46,6 @@ export function PaymentLaunchDialogs({
onConfirm={launch.handleEzpayConfirm} onConfirm={launch.handleEzpayConfirm}
/> />
) : null} ) : null}
{launch.shouldShowRegionalQrDialog && launch.regionalQrPayment ? (
<RegionalQrPaymentDialog
payment={launch.regionalQrPayment}
status={launch.regionalQrStatus}
errorMessage={launch.regionalQrErrorMessage}
onClose={launch.handleRegionalQrClose}
/>
) : null}
{launch.shouldShowStripeDialog && launch.stripeClientSecret ? ( {launch.shouldShowStripeDialog && launch.stripeClientSecret ? (
<LazyStripePaymentDialog <LazyStripePaymentDialog
clientSecret={launch.stripeClientSecret} clientSecret={launch.stripeClientSecret}
@@ -73,151 +58,6 @@ 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 { interface EzpayRedirectConfirmDialogProps {
description: ReactNode; description: ReactNode;
externalCheckoutAnalyticsKey: string; externalCheckoutAnalyticsKey: string;
@@ -238,43 +78,41 @@ function EzpayRedirectConfirmDialog({
const titleId = useId(); const titleId = useId();
return ( return (
<ModalPortal <div
open className={styles.overlay}
persistent
onClose={onCancel}
scrimClassName={styles.overlay}
panelClassName={styles.dialog}
scrimOpacity={0.5}
role="alertdialog" role="alertdialog"
ariaLabelledBy={titleId} aria-modal="true"
aria-labelledby={titleId}
> >
<div className={styles.header}> <div className={styles.dialog}>
<h2 id={titleId} className={styles.title}> <div className={styles.header}>
Continue to payment? <h2 id={titleId} className={styles.title}>
</h2> Continue to GCash?
<p className={styles.content}>{description}</p> </h2>
<p className={styles.content}>Order No. {orderId}</p> <p className={styles.content}>{description}</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}> </div>
<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
+10 -29
View File
@@ -24,7 +24,6 @@ const PAYMENT_METHODS: readonly {
export interface PaymentMethodSelectorProps { export interface PaymentMethodSelectorProps {
config: PaymentMethodConfig; config: PaymentMethodConfig;
value: PayChannel; value: PayChannel;
density?: "default" | "compact";
disabled?: boolean; disabled?: boolean;
caption?: string; caption?: string;
className?: string; className?: string;
@@ -35,7 +34,6 @@ export interface PaymentMethodSelectorProps {
export function PaymentMethodSelector({ export function PaymentMethodSelector({
config, config,
value, value,
density = "default",
disabled = false, disabled = false,
caption = "Stripe by default", caption = "Stripe by default",
className, className,
@@ -43,53 +41,36 @@ export function PaymentMethodSelector({
onChange, onChange,
}: PaymentMethodSelectorProps) { }: PaymentMethodSelectorProps) {
if (!config.showPaymentMethodSelector) return null; 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 = const paymentMethods =
config.initialPayChannel === "ezpay" config.initialPayChannel === "ezpay"
? [...configuredPaymentMethods].sort((a, b) => ? [...PAYMENT_METHODS].sort((a, b) =>
a.channel === "ezpay" ? -1 : b.channel === "ezpay" ? 1 : 0, a.channel === "ezpay" ? -1 : b.channel === "ezpay" ? 1 : 0,
) )
: configuredPaymentMethods; : PAYMENT_METHODS;
return ( return (
<section <section
className={`flex flex-col ${isCompact ? "gap-2" : "gap-[clamp(8px,1.852vw,10px)]"} ${className ?? ""}`.trim()} className={`flex flex-col gap-[clamp(8px,1.852vw,10px)] ${className ?? ""}`.trim()}
data-density={density}
aria-labelledby="payment-method-title" aria-labelledby="payment-method-title"
> >
<div <div className="flex items-baseline justify-between gap-sm px-xs">
className={`flex items-baseline justify-between gap-sm ${isCompact ? "px-0.5" : "px-xs"}`}
>
<h2 <h2
id="payment-method-title" id="payment-method-title"
className={`m-0 font-bold leading-[1.2] text-auth-text-primary ${isCompact ? "text-base" : "text-(length:--responsive-card-title,var(--font-size-lg))"}`} className="m-0 text-(length:--responsive-card-title,var(--font-size-lg)) font-bold leading-[1.2] text-auth-text-primary"
style={{ fontFamily: "var(--font-athelas), var(--font-system)" }} style={{ fontFamily: "var(--font-athelas), var(--font-system)" }}
> >
Payment Method Payment Method
</h2> </h2>
{!isCompact ? ( <span className="whitespace-nowrap text-(length:--responsive-caption,var(--font-size-sm)) leading-[1.2] text-text-secondary">
<span className="whitespace-nowrap text-(length:--responsive-caption,var(--font-size-sm)) leading-[1.2] text-text-secondary"> {caption}
{caption} </span>
</span>
) : null}
</div> </div>
<div className="grid grid-cols-2 gap-sm"> <div className="grid grid-cols-2 gap-sm">
{paymentMethods.map((method) => { {paymentMethods.map((method) => {
const selected = method.channel === value; const selected = method.channel === value;
const classes = [ const classes = [
`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)]"}`, "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",
selected 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-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)]", : "border border-[rgba(246,87,160,0.18)] bg-white shadow-[0_5px_7px_0_rgba(247,89,168,0.08)]",
@@ -116,7 +97,7 @@ export function PaymentMethodSelector({
aria-hidden="true" aria-hidden="true"
width={122} width={122}
height={29} height={29}
className={`block object-contain ${isCompact ? "max-h-8 w-[min(100%,92px)]" : "max-h-8.5 w-[min(100%,92px)]"}`} className="block max-h-8.5 w-[min(100%,92px)] object-contain"
/> />
) : ( ) : (
<span className="text-(length:--responsive-body,16px) font-bold leading-[1.1] text-[#1e1e1e]"> <span className="text-(length:--responsive-body,16px) font-bold leading-[1.1] text-[#1e1e1e]">
src/app/_components/payment/stripe-payment-dialog.styles.ts
+1 -1
View File
@@ -2,7 +2,7 @@ export const stripePaymentDialogStyles = {
overlay: 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))]", "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: 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 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)]", "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)]",
header: "mb-(--page-section-gap,18px) text-left", header: "mb-(--page-section-gap,18px) text-left",
title: title:
"m-0 mb-[clamp(7px,1.481vw,8px)] text-(length:--responsive-page-title,22px) font-bold leading-[1.2] text-text-foreground", "m-0 mb-[clamp(7px,1.481vw,8px)] text-(length:--responsive-page-title,22px) font-bold leading-[1.2] text-text-foreground",
src/app/_components/payment/stripe-payment-dialog.tsx
+55 -71
View File
@@ -4,7 +4,7 @@
* *
* 后端当前返回 PaymentIntent clientSecret，因此这里直接用它完成前端确认。 * 后端当前返回 PaymentIntent clientSecret，因此这里直接用它完成前端确认。
*/ */
import { useId, useState, type FormEvent } from "react"; import { useState, type FormEvent } from "react";
import { import {
Elements, Elements,
PaymentElement, PaymentElement,
@@ -13,7 +13,6 @@ import {
} from "@stripe/react-stripe-js"; } from "@stripe/react-stripe-js";
import { loadStripe } from "@stripe/stripe-js"; import { loadStripe } from "@stripe/stripe-js";
import { ModalPortal } from "@/app/_components/core/modal-portal";
import { ExceptionHandler } from "@/core/errors"; import { ExceptionHandler } from "@/core/errors";
import { ROUTES } from "@/router/routes"; import { ROUTES } from "@/router/routes";
import { Logger } from "@/utils/logger"; import { Logger } from "@/utils/logger";
@@ -39,84 +38,69 @@ export function StripePaymentDialog({
onClose, onClose,
onConfirmed, onConfirmed,
}: StripePaymentDialogProps) { }: StripePaymentDialogProps) {
const titleId = useId();
const descriptionId = useId();
if (!stripePromise) { if (!stripePromise) {
return ( return (
<ModalPortal <div className={styles.overlay} role="alertdialog" aria-modal="true">
open <div className={styles.dialog}>
persistent <div className={styles.header}>
onClose={onClose} <h2 className={styles.title}>Payment unavailable</h2>
scrimClassName={styles.overlay} <p className={styles.content}>
panelClassName={styles.dialog} Stripe publishable key is not configured for this build.
scrimOpacity={0.5} </p>
role="alertdialog" </div>
ariaLabelledBy={titleId} <div className={styles.actions}>
ariaDescribedBy={descriptionId} <button
> type="button"
<div className={styles.header}> className={`${styles.button} ${styles.primary}`}
<h2 id={titleId} className={styles.title}> onClick={onClose}
Payment unavailable >
</h2> OK
<p id={descriptionId} className={styles.content}> </button>
Stripe publishable key is not configured for this build. </div>
</p>
</div> </div>
<div className={styles.actions}> </div>
<button
type="button"
className={`${styles.button} ${styles.primary}`}
onClick={onClose}
>
OK
</button>
</div>
</ModalPortal>
); );
} }
return ( return (
<ModalPortal <div
open className={styles.overlay}
persistent role="dialog"
onClose={onClose} aria-modal="true"
scrimClassName={styles.overlay} aria-labelledby="stripe-payment-title"
panelClassName={styles.dialog}
scrimOpacity={0.5}
ariaLabelledBy={titleId}
ariaDescribedBy={descriptionId}
> >
<div className={styles.header}> <div className={styles.dialog}>
<h2 id={titleId} className={styles.title}> <div className={styles.header}>
Complete payment <h2 id="stripe-payment-title" className={styles.title}>
</h2> Complete payment
<p id={descriptionId} className={styles.content}> </h2>
Enter your payment details securely through Stripe. <p className={styles.content}>
</p> Enter your payment details securely through Stripe.
</div> </p>
<Elements </div>
key={clientSecret} <Elements
stripe={stripePromise} key={clientSecret}
options={{ stripe={stripePromise}
clientSecret, options={{
appearance: { clientSecret,
theme: "stripe", appearance: {
variables: { theme: "stripe",
borderRadius: "14px", variables: {
colorPrimary: "#ff52a2", borderRadius: "14px",
colorText: "#171717", colorPrimary: "#ff52a2",
colorText: "#171717",
},
}, },
}, }}
}} >
> <StripePaymentForm
<StripePaymentForm returnPath={returnPath}
returnPath={returnPath} onClose={onClose}
onClose={onClose} onConfirmed={onConfirmed}
onConfirmed={onConfirmed} />
/> </Elements>
</Elements> </div>
</ModalPortal> </div>
); );
} }
src/app/_components/user-message-avatar.tsx
+20 -34
View File
@@ -2,30 +2,19 @@
import Image from "next/image"; import Image from "next/image";
import type { AvatarInteractionProps } from "./avatar-interaction"; export interface UserMessageAvatarProps {
interface UserMessageAvatarVisualProps {
avatarUrl?: string | null; avatarUrl?: string | null;
className?: string; className?: string;
size?: number | string; size?: number | string;
} }
export type UserMessageAvatarProps = UserMessageAvatarVisualProps &
AvatarInteractionProps;
export function UserMessageAvatar({ export function UserMessageAvatar({
avatarUrl, avatarUrl,
className, className,
size = 43, size = 43,
onClick,
actionLabel,
analyticsKey,
}: UserMessageAvatarProps) { }: UserMessageAvatarProps) {
const avatarClassName = [ const avatarClassName = [
"flex shrink-0 items-center justify-center overflow-hidden rounded-full border-2 border-(--color-avatar-border,#fbf3f5) bg-(--color-avatar-border,#fbf3f5) shadow-(--shadow-input-box,0_1px_2px_rgba(0,0,0,0.1))", "flex shrink-0 items-center justify-center overflow-hidden rounded-full border-2 border-(--color-avatar-border,#fbf3f5) bg-(--color-avatar-border,#fbf3f5) shadow-(--shadow-input-box,0_1px_2px_rgba(0,0,0,0.1))",
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, className,
] ]
.filter(Boolean) .filter(Boolean)
@@ -33,30 +22,21 @@ export function UserMessageAvatar({
const avatarStyle = { width: size, height: size }; const avatarStyle = { width: size, height: size };
const imageSize = typeof size === "number" ? size : 64; const imageSize = typeof size === "number" ? size : 64;
const hasUserAvatar = Boolean(avatarUrl && avatarUrl.length > 0); if (avatarUrl && avatarUrl.length > 0) {
const image = (
<Image
src={hasUserAvatar ? avatarUrl! : "/images/avatar/placeholder.png"}
alt={hasUserAvatar ? "" : "Guest"}
width={imageSize}
height={imageSize}
className="size-full object-cover"
/>
);
if (onClick) {
return ( return (
<button <div
type="button"
className={avatarClassName} className={avatarClassName}
style={avatarStyle} style={avatarStyle}
aria-label={actionLabel} aria-label="User avatar"
data-analytics-key={analyticsKey}
data-analytics-label={actionLabel}
onClick={onClick}
> >
{image} <Image
</button> src={avatarUrl}
alt=""
width={imageSize}
height={imageSize}
className="size-full object-cover"
/>
</div>
); );
} }
@@ -64,9 +44,15 @@ export function UserMessageAvatar({
<div <div
className={avatarClassName} className={avatarClassName}
style={avatarStyle} style={avatarStyle}
aria-label={hasUserAvatar ? "User avatar" : "Guest avatar"} aria-label="Guest avatar"
> >
{image} <Image
src="/images/avatar/placeholder.png"
alt="Guest"
width={imageSize}
height={imageSize}
className="size-full object-cover"
/>
</div> </div>
); );
} }
src/app/_hooks/__tests__/use-pending-payment-order-lifecycle.test.ts
-12
View File
@@ -38,16 +38,4 @@ describe("shouldInspectPendingPaymentOrder", () => {
}), }),
).toBe(false); ).toBe(false);
}); });
it("allows stale expired orders to be cleaned up", () => {
expect(
shouldInspectPendingPaymentOrder({
currentOrderId: "order-expired",
isPaid: false,
isPollingOrder: false,
shouldResumePendingOrder: false,
status: "expired",
}),
).toBe(true);
});
}); });
src/app/_hooks/use-payment-launch-flow.ts
+30 -187
View File
@@ -4,16 +4,15 @@ import { type Dispatch, useEffect, useRef, useState } from "react";
import { import {
getPaymentUrl, getPaymentUrl,
getPaymentUrlHostname,
getStripeClientSecret, getStripeClientSecret,
isEzpayPayment, isEzpayPayment,
launchEzpayRedirect, launchEzpayRedirect,
resolveEzpayLaunchTarget,
} from "@/lib/payment/payment_launch"; } from "@/lib/payment/payment_launch";
import { behaviorAnalytics } from "@/lib/analytics"; import { behaviorAnalytics } from "@/lib/analytics";
import type { import type {
PendingPaymentReturnTo, PendingPaymentReturnTo,
PendingPaymentSubscriptionType, PendingPaymentSubscriptionType,
PendingPaymentTipCoffeeType,
} from "@/lib/payment/pending_payment_order"; } from "@/lib/payment/pending_payment_order";
import type { import type {
PaymentContextState, PaymentContextState,
@@ -40,65 +39,22 @@ export interface UsePaymentLaunchFlowInput {
returnTo?: PendingPaymentReturnTo; returnTo?: PendingPaymentReturnTo;
characterSlug?: string; characterSlug?: string;
subscriptionType: PendingPaymentSubscriptionType; subscriptionType: PendingPaymentSubscriptionType;
giftCategory?: string | null; tipCoffeeType?: PendingPaymentTipCoffeeType;
giftPlanId?: string | null;
countryCode?: string | null;
} }
export interface PaymentLaunchFlow { export interface PaymentLaunchFlow {
ezpayPaymentUrl: string | null; ezpayPaymentUrl: string | null;
handleEzpayCancel: () => void; handleEzpayCancel: () => void;
handleEzpayConfirm: () => void; handleEzpayConfirm: () => void;
handleRegionalQrClose: () => void;
handleStripeClose: () => void; handleStripeClose: () => void;
handleStripeConfirmed: () => void; handleStripeConfirmed: () => void;
isConfirmingEzpay: boolean; isConfirmingEzpay: boolean;
regionalQrErrorMessage: string | null;
regionalQrPayment: RegionalQrPaymentDetails | null;
regionalQrStatus: PaymentContextState["orderStatus"];
resetLaunchState: () => void; resetLaunchState: () => void;
shouldShowEzpayConfirmDialog: boolean; shouldShowEzpayConfirmDialog: boolean;
shouldShowRegionalQrDialog: boolean;
shouldShowStripeDialog: boolean; shouldShowStripeDialog: boolean;
stripeClientSecret: string | null; stripeClientSecret: string | null;
} }
export interface RegionalQrPaymentDetails {
amountCents: number;
currency: string;
experience: "gcashQrPh" | "qris" | "paymentQr";
orderId: string;
qrData: string;
}
function paymentParamString(
payParams: Record<string, unknown>,
...keys: string[]
): string | null {
for (const key of keys) {
const value = payParams[key];
if (typeof value === "string" && value.trim()) return value.trim();
}
return null;
}
function paymentParamAmountCents(
payParams: Record<string, unknown>,
): number | null {
for (const key of [
"firstChargeAmountCents",
"first_charge_amount_cents",
"amountCents",
"amount_cents",
]) {
const value = payParams[key];
if (typeof value === "number" && Number.isFinite(value) && value > 0) {
return value;
}
}
return null;
}
function trackPaymentCheckoutOpened( function trackPaymentCheckoutOpened(
payment: PaymentContextState, payment: PaymentContextState,
checkoutUrl: string, checkoutUrl: string,
@@ -154,9 +110,7 @@ export function usePaymentLaunchFlow({
returnTo, returnTo,
characterSlug, characterSlug,
subscriptionType, subscriptionType,
giftCategory, tipCoffeeType,
giftPlanId,
countryCode,
}: UsePaymentLaunchFlowInput): PaymentLaunchFlow { }: UsePaymentLaunchFlowInput): PaymentLaunchFlow {
const launchedNonceRef = useRef(0); const launchedNonceRef = useRef(0);
const [hiddenStripeClientSecret, setHiddenStripeClientSecret] = useState< const [hiddenStripeClientSecret, setHiddenStripeClientSecret] = useState<
@@ -166,42 +120,9 @@ export function usePaymentLaunchFlow({
const stripeClientSecret = payment.payParams const stripeClientSecret = payment.payParams
? getStripeClientSecret(payment.payParams) ? getStripeClientSecret(payment.payParams)
: null; : null;
const selectedPlan = payment.plans.find( const ezpayPaymentUrl = payment.payParams
(item) => item.planId === payment.selectedPlanId, ? getPaymentUrl(payment.payParams)
); : null;
const paymentCurrency = payment.payParams
? paymentParamString(payment.payParams, "currency") ??
selectedPlan?.currency ??
null
: selectedPlan?.currency ?? null;
const ezpayLaunchTarget =
payment.payParams && isEzpayPayment(payment.payParams)
? resolveEzpayLaunchTarget(payment.payParams, {
countryCode,
currency: paymentCurrency,
})
: null;
const ezpayPaymentUrl =
ezpayLaunchTarget?.kind === "url"
? ezpayLaunchTarget.paymentUrl
: null;
const regionalQrPayment: RegionalQrPaymentDetails | null =
payment.payParams &&
payment.currentOrderId &&
ezpayLaunchTarget?.kind === "qr"
? {
amountCents:
paymentParamAmountCents(payment.payParams) ??
selectedPlan?.amountCents ??
0,
currency:
paymentCurrency ??
(ezpayLaunchTarget.experience === "gcashQrPh" ? "PHP" : "IDR"),
experience: ezpayLaunchTarget.experience,
orderId: payment.currentOrderId,
qrData: ezpayLaunchTarget.qrData,
}
: null;
useEffect(() => { useEffect(() => {
if (!payment.payParams || payment.launchNonce <= launchedNonceRef.current) { if (!payment.payParams || payment.launchNonce <= launchedNonceRef.current) {
return; return;
@@ -214,95 +135,38 @@ export function usePaymentLaunchFlow({
return; return;
} }
const isEzpay = isEzpayPayment(payment.payParams); const paymentUrl = getPaymentUrl(payment.payParams);
if (isEzpay) { if (paymentUrl) {
const target = resolveEzpayLaunchTarget(payment.payParams, { const isEzpay = isEzpayPayment(payment.payParams);
countryCode,
currency: paymentCurrency,
});
const channelType = paymentParamString(
payment.payParams,
"channelType",
"channel_type",
);
const channelCode = paymentParamString(
payment.payParams,
"channelCode",
"channel_code",
);
const namedPaymentUrl = getPaymentUrl(payment.payParams);
log.debug(`[${logScope}] ezpay launch target resolved`, {
countryCode: countryCode?.trim().toUpperCase() ?? null,
currency: paymentCurrency?.trim().toUpperCase() ?? null,
channelType: channelType?.toUpperCase() ?? null,
channelCode,
hasCashierUrl: getPaymentUrlHostname(namedPaymentUrl) !== null,
hasQrData: target.kind === "qr",
paymentUrlHost:
target.kind === "url"
? getPaymentUrlHostname(target.paymentUrl)
: null,
});
if (target.kind === "error") {
trackPaymentCheckoutFailed(payment, "missing_checkout_url");
paymentDispatch({
type: "PaymentLaunchFailed",
errorMessage: target.errorMessage,
});
return;
}
if (target.kind === "qr") { if (!AppEnvUtil.isProduction() && isEzpay) {
if (!payment.currentOrderId) {
trackPaymentCheckoutFailed(payment, "missing_checkout_url");
paymentDispatch({
type: "PaymentLaunchFailed",
errorMessage: "Missing order id before showing payment QR code.",
});
return;
}
trackPaymentCheckoutOpened(
payment,
target.experience === "qris"
? "qris_embedded"
: target.experience === "gcashQrPh"
? "gcash_qrph_embedded"
: "payment_qr_embedded",
);
return;
}
const paymentUrl = target.paymentUrl;
if (!AppEnvUtil.isProduction()) {
log.debug(`[${logScope}] ezpay confirmation required`, { log.debug(`[${logScope}] ezpay confirmation required`, {
orderId: payment.currentOrderId, orderId: payment.currentOrderId,
paymentUrlHost: getPaymentUrlHostname(paymentUrl), paymentUrl,
subscriptionType, subscriptionType,
}); });
return; return;
} }
void launchEzpayRedirect({ if (isEzpay) {
orderId: payment.currentOrderId, void launchEzpayRedirect({
paymentUrl, orderId: payment.currentOrderId,
subscriptionType, paymentUrl,
giftCategory, subscriptionType,
giftPlanId, ...(tipCoffeeType ? { tipCoffeeType } : {}),
...(returnTo ? { returnTo } : {}), ...(returnTo ? { returnTo } : {}),
...(characterSlug ? { characterSlug } : {}), ...(characterSlug ? { characterSlug } : {}),
onOpened: () => trackPaymentCheckoutOpened(payment, paymentUrl), onOpened: () => trackPaymentCheckoutOpened(payment, paymentUrl),
onFailed: (errorMessage) => { onFailed: (errorMessage) => {
trackPaymentCheckoutFailed(payment, "payment_redirect_failed"); trackPaymentCheckoutFailed(payment, "payment_redirect_failed");
paymentDispatch({ type: "PaymentLaunchFailed", errorMessage }); paymentDispatch({ type: "PaymentLaunchFailed", errorMessage });
}, },
}); });
return; return;
} }
const paymentUrl = getPaymentUrl(payment.payParams);
if (paymentUrl) {
try { try {
window.location.assign(paymentUrl); window.location.href = paymentUrl;
trackPaymentCheckoutOpened(payment, paymentUrl); trackPaymentCheckoutOpened(payment, paymentUrl);
} catch { } catch {
trackPaymentCheckoutFailed(payment, "payment_redirect_failed"); trackPaymentCheckoutFailed(payment, "payment_redirect_failed");
@@ -323,7 +187,6 @@ export function usePaymentLaunchFlow({
log, log,
logScope, logScope,
characterSlug, characterSlug,
countryCode,
payment.currentOrderId, payment.currentOrderId,
payment, payment,
payment.launchNonce, payment.launchNonce,
@@ -332,11 +195,9 @@ export function usePaymentLaunchFlow({
payment.plans, payment.plans,
payment.selectedPlanId, payment.selectedPlanId,
paymentDispatch, paymentDispatch,
paymentCurrency,
returnTo, returnTo,
subscriptionType, subscriptionType,
giftCategory, tipCoffeeType,
giftPlanId,
]); ]);
const shouldShowStripeDialog = const shouldShowStripeDialog =
@@ -349,9 +210,6 @@ export function usePaymentLaunchFlow({
payParams: payment.payParams, payParams: payment.payParams,
paymentUrl: ezpayPaymentUrl, paymentUrl: ezpayPaymentUrl,
}); });
const shouldShowRegionalQrDialog = Boolean(
regionalQrPayment && !payment.isPaid,
);
function resetLaunchState(): void { function resetLaunchState(): void {
setIsConfirmingEzpay(false); setIsConfirmingEzpay(false);
@@ -380,8 +238,7 @@ export function usePaymentLaunchFlow({
orderId: payment.currentOrderId, orderId: payment.currentOrderId,
paymentUrl: ezpayPaymentUrl, paymentUrl: ezpayPaymentUrl,
subscriptionType, subscriptionType,
giftCategory, ...(tipCoffeeType ? { tipCoffeeType } : {}),
giftPlanId,
...(returnTo ? { returnTo } : {}), ...(returnTo ? { returnTo } : {}),
...(characterSlug ? { characterSlug } : {}), ...(characterSlug ? { characterSlug } : {}),
onOpened: () => trackPaymentCheckoutOpened(payment, ezpayPaymentUrl), onOpened: () => trackPaymentCheckoutOpened(payment, ezpayPaymentUrl),
@@ -402,29 +259,15 @@ export function usePaymentLaunchFlow({
paymentDispatch({ type: "PaymentReset" }); paymentDispatch({ type: "PaymentReset" });
} }
function handleRegionalQrClose(): void {
log.debug(`[${logScope}] regional payment QR dialog closed`, {
orderId: regionalQrPayment?.orderId ?? payment.currentOrderId,
experience: regionalQrPayment?.experience ?? null,
subscriptionType,
});
paymentDispatch({ type: "PaymentReset" });
}
return { return {
ezpayPaymentUrl, ezpayPaymentUrl,
handleEzpayCancel, handleEzpayCancel,
handleEzpayConfirm, handleEzpayConfirm,
handleRegionalQrClose,
handleStripeClose, handleStripeClose,
handleStripeConfirmed, handleStripeConfirmed,
isConfirmingEzpay, isConfirmingEzpay,
regionalQrErrorMessage: payment.errorMessage,
regionalQrPayment,
regionalQrStatus: payment.orderStatus,
resetLaunchState, resetLaunchState,
shouldShowEzpayConfirmDialog, shouldShowEzpayConfirmDialog,
shouldShowRegionalQrDialog,
shouldShowStripeDialog, shouldShowStripeDialog,
stripeClientSecret, stripeClientSecret,
}; };
src/app/_hooks/use-payment-route-flow.ts
+23 -43
View File
@@ -19,12 +19,6 @@ export interface UsePaymentRouteFlowInput {
initialPayChannel: PayChannel; initialPayChannel: PayChannel;
paymentType: PendingPaymentSubscriptionType; paymentType: PendingPaymentSubscriptionType;
shouldResumePendingOrder: boolean; shouldResumePendingOrder: boolean;
characterId?: string;
initialCategory?: string | null;
initialPlanId?: string | null;
commercialOfferId?: string | null;
resumeOrderId?: string | null;
chatActionId?: string | null;
} }
export interface PaymentRouteFlow { export interface PaymentRouteFlow {
@@ -41,25 +35,10 @@ export function usePaymentRouteFlow({
initialPayChannel, initialPayChannel,
paymentType, paymentType,
shouldResumePendingOrder, shouldResumePendingOrder,
characterId,
initialCategory = null,
initialPlanId = null,
commercialOfferId = null,
resumeOrderId = null,
chatActionId = null,
}: UsePaymentRouteFlowInput): PaymentRouteFlow { }: UsePaymentRouteFlowInput): PaymentRouteFlow {
const payment = usePaymentState(); const payment = usePaymentState();
const paymentDispatch = usePaymentDispatch(); const paymentDispatch = usePaymentDispatch();
const initializedCatalogKeyRef = useRef<string | null>(null); const initialPayChannelAppliedRef = useRef(false);
const resumedOrderIdRef = useRef<string | null>(null);
const catalogKey = [
catalog,
characterId ?? "",
initialCategory ?? "",
initialPlanId ?? "",
commercialOfferId ?? "",
chatActionId ?? "",
].join(":");
usePendingPaymentOrderLifecycle({ usePendingPaymentOrderLifecycle({
payment, payment,
@@ -69,35 +48,36 @@ export function usePaymentRouteFlow({
}); });
useEffect(() => { useEffect(() => {
if (initializedCatalogKeyRef.current === catalogKey) return; if (payment.status === "idle") {
initializedCatalogKeyRef.current = catalogKey; initialPayChannelAppliedRef.current = true;
paymentDispatch({
type: "PaymentInit",
catalog,
payChannel: initialPayChannel,
});
return;
}
if (
initialPayChannelAppliedRef.current ||
payment.status !== "ready"
) {
return;
}
initialPayChannelAppliedRef.current = true;
if (payment.payChannel === initialPayChannel) return;
paymentDispatch({ paymentDispatch({
type: "PaymentInit", type: "PaymentPayChannelChanged",
catalog,
payChannel: initialPayChannel, payChannel: initialPayChannel,
...(characterId ? { characterId } : {}),
...(initialCategory ? { category: initialCategory } : {}),
...(initialPlanId ? { planId: initialPlanId } : {}),
...(commercialOfferId ? { commercialOfferId } : {}),
...(chatActionId ? { chatActionId } : {}),
}); });
}, [ }, [
catalog, catalog,
catalogKey,
characterId,
commercialOfferId,
chatActionId,
initialCategory,
initialPlanId,
initialPayChannel, initialPayChannel,
payment.payChannel,
payment.status,
paymentDispatch, paymentDispatch,
]); ]);
useEffect(() => {
if (!resumeOrderId || resumedOrderIdRef.current === resumeOrderId) return;
resumedOrderIdRef.current = resumeOrderId;
paymentDispatch({ type: "PaymentReturned", orderId: resumeOrderId });
}, [paymentDispatch, resumeOrderId]);
return { payment, paymentDispatch }; return { payment, paymentDispatch };
} }
src/app/_hooks/use-pending-payment-order-lifecycle.ts
+3 -10
View File
@@ -37,7 +37,7 @@ export function shouldInspectPendingPaymentOrder({
return ( return (
status === "ready" || status === "ready" ||
(!shouldResumePendingOrder && (!shouldResumePendingOrder &&
(isPollingOrder || isPaid || status === "failed" || status === "expired")) (isPollingOrder || isPaid || status === "failed"))
); );
} }
@@ -74,8 +74,7 @@ export function usePendingPaymentOrderLifecycle({
payment.currentOrderId === result.data.orderId && payment.currentOrderId === result.data.orderId &&
(payment.isPollingOrder || (payment.isPollingOrder ||
payment.isPaid || payment.isPaid ||
payment.status === "failed" || payment.status === "failed")
payment.status === "expired")
) { ) {
paymentDispatch({ type: "PaymentReset" }); paymentDispatch({ type: "PaymentReset" });
} }
@@ -109,13 +108,7 @@ export function usePendingPaymentOrderLifecycle({
useEffect(() => { useEffect(() => {
if (!payment.currentOrderId) return; if (!payment.currentOrderId) return;
if ( if (!payment.isPaid && payment.status !== "failed") return;
!payment.isPaid &&
payment.status !== "failed" &&
payment.status !== "expired"
) {
return;
}
void clearPendingPaymentOrder(); void clearPendingPaymentOrder();
}, [payment.currentOrderId, payment.isPaid, payment.status]); }, [payment.currentOrderId, payment.isPaid, payment.status]);
src/app/call/__tests__/voice-call-player.test.ts
-57
View File
@@ -1,57 +0,0 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { VoiceCallPlayer } from "@/app/call/voice-call-player";
describe("VoiceCallPlayer", () => {
afterEach(() => {
vi.unstubAllGlobals();
});
it("schedules decoded sentence audio on one continuous Web Audio timeline", async () => {
const starts: number[] = [];
const sources: Array<{ onended: (() => void) | null }> = [];
const context = {
state: "running",
currentTime: 0,
destination: {},
resume: vi.fn(async () => undefined),
close: vi.fn(async () => undefined),
decodeAudioData: vi.fn(async () => ({ duration: 1 })),
createBufferSource: vi.fn(() => {
const source = {
buffer: null,
onended: null as (() => void) | null,
connect: vi.fn(),
disconnect: vi.fn(),
stop: vi.fn(),
start: vi.fn((at: number) => starts.push(at)),
};
sources.push(source);
return source;
}),
};
vi.stubGlobal("AudioContext", function AudioContextMock() {
return context;
});
const player = new VoiceCallPlayer();
const gaps: number[] = [];
player.onGap = (milliseconds) => gaps.push(milliseconds);
const meta = {
callId: "call-1",
turnId: "turn-1",
index: 0,
mimeType: "audio/mpeg",
byteLength: 3,
};
player.enqueue(meta, new Uint8Array([1, 2, 3]).buffer);
player.enqueue({ ...meta, index: 1 }, new Uint8Array([4, 5, 6]).buffer);
await vi.waitFor(() => expect(starts).toHaveLength(2));
expect(starts).toEqual([0.025, 1.025]);
expect(gaps).toEqual([0]);
expect(sources).toHaveLength(2);
player.dispose();
});
});
src/app/call/page.tsx
-8
View File
@@ -1,8 +0,0 @@
import { redirect } from "next/navigation";
import { DEFAULT_CHARACTER_SLUG } from "@/data/constants/character";
import { getCharacterRoutes } from "@/router/routes";
export default function LegacyCallPage() {
redirect(getCharacterRoutes(DEFAULT_CHARACTER_SLUG).call);
}
src/app/call/voice-call-player.ts
-101
View File
@@ -1,101 +0,0 @@
import type { CallAudioChunkMeta } from "@/core/net/voice-call-transport";
export class VoiceCallPlayer {
private context: AudioContext | null = null;
private sources = new Set<AudioBufferSourceNode>();
private decodeChain: Promise<void> = Promise.resolve();
private scheduledUntil = 0;
private pendingDecodes = 0;
private generation = 0;
onPlaying: (() => void) | null = null;
onIdle: (() => void) | null = null;
onGap: ((milliseconds: number) => void) | null = null;
onError: ((error: Error) => void) | null = null;
get isPlaying(): boolean {
return this.sources.size > 0 || this.pendingDecodes > 0;
}
async prepare(): Promise<void> {
const context = this.getContext();
if (context.state === "suspended") await context.resume();
}
enqueue(_meta: CallAudioChunkMeta, bytes: ArrayBuffer): void {
const generation = this.generation;
this.pendingDecodes += 1;
this.decodeChain = this.decodeChain
.then(async () => {
const context = this.getContext();
if (context.state === "suspended") await context.resume();
const audioBuffer = await context.decodeAudioData(bytes.slice(0));
if (generation !== this.generation) return;
this.schedule(context, audioBuffer);
})
.catch((error: unknown) => {
this.onError?.(error instanceof Error ? error : new Error(String(error)));
})
.finally(() => {
this.pendingDecodes = Math.max(0, this.pendingDecodes - 1);
this.notifyIdleIfNeeded();
});
}
stop(): void {
this.generation += 1;
for (const source of this.sources) {
source.onended = null;
try {
source.stop();
} catch {
// 已自然结束的 source 无需重复停止。
}
source.disconnect();
}
this.sources.clear();
this.scheduledUntil = 0;
this.onIdle?.();
}
dispose(): void {
this.stop();
const context = this.context;
this.context = null;
if (context && context.state !== "closed") void context.close();
}
private getContext(): AudioContext {
if (!this.context || this.context.state === "closed") {
this.context = new AudioContext({ latencyHint: "interactive" });
}
return this.context;
}
private schedule(context: AudioContext, buffer: AudioBuffer): void {
const leadSeconds = 0.025;
const earliestStart = context.currentTime + leadSeconds;
const hadPreviousSegment = this.scheduledUntil > 0;
const startAt = Math.max(earliestStart, this.scheduledUntil);
if (hadPreviousSegment) {
this.onGap?.(Math.max(0, (startAt - this.scheduledUntil) * 1000));
}
const source = context.createBufferSource();
source.buffer = buffer;
source.connect(context.destination);
this.sources.add(source);
this.scheduledUntil = startAt + buffer.duration;
source.onended = () => {
source.disconnect();
this.sources.delete(source);
this.notifyIdleIfNeeded();
};
source.start(startAt);
this.onPlaying?.();
}
private notifyIdleIfNeeded(): void {
if (this.sources.size || this.pendingDecodes) return;
this.scheduledUntil = 0;
this.onIdle?.();
}
}
src/app/call/voice-call-screen.module.css
-47
View File
@@ -1,47 +0,0 @@
.screen {
position: relative;
display: flex;
min-height: var(--app-viewport-height, 100dvh);
overflow: hidden;
flex-direction: column;
color: #fff;
background: #090810;
}
.background { object-fit: cover; opacity: .48; }
.scrim { position: absolute; inset: 0; background: radial-gradient(circle at 50% 32%, rgba(239,83,155,.18), transparent 36%), linear-gradient(180deg, rgba(9,8,16,.28), rgba(9,8,16,.94)); }
.header { position: relative; z-index: 1; display: flex; align-items: center; justify-content: space-between; padding: calc(18px + var(--app-safe-top, 0px)) 20px 12px; }
.iconButton { display: inline-flex; width: 42px; height: 42px; cursor: pointer; align-items: center; justify-content: center; border: 1px solid rgba(255,255,255,.16); border-radius: 999px; color: #fff; background: rgba(10,9,18,.55); backdrop-filter: blur(14px); }
.balances { display: flex; gap: 8px; font-size: 12px; font-weight: 650; }
.balances span { padding: 7px 10px; border: 1px solid rgba(255,255,255,.12); border-radius: 999px; background: rgba(10,9,18,.58); backdrop-filter: blur(14px); }
.content { position: relative; z-index: 1; display: flex; min-height: 0; flex: 1; flex-direction: column; align-items: center; justify-content: center; padding: 24px 28px; text-align: center; }
.avatarRing { position: relative; display: grid; width: 174px; height: 174px; place-items: center; border-radius: 50%; background: linear-gradient(135deg, rgba(255,255,255,.24), rgba(239,83,155,.42)); box-shadow: 0 28px 72px rgba(0,0,0,.42); transition: transform .25s ease, box-shadow .25s ease; }
.avatarRing::after { position: absolute; inset: -10px; border: 1px solid rgba(255,255,255,.16); border-radius: inherit; content: ""; }
.avatarRing.listening, .avatarRing.speaking { animation: callPulse 1.8s ease-in-out infinite; box-shadow: 0 0 0 12px rgba(239,83,155,.08), 0 28px 72px rgba(0,0,0,.42); }
.avatar { width: 158px; height: 158px; border: 4px solid rgba(9,8,16,.8); border-radius: 50%; object-fit: cover; }
.content h1 { margin: 30px 0 8px; font-size: clamp(27px, 7vw, 36px); letter-spacing: -.025em; }
.state { display: flex; min-height: 28px; align-items: center; gap: 7px; color: rgba(255,255,255,.78); font-size: 15px; }
.lowBalance { margin: 12px 0 0; padding: 7px 11px; border-radius: 999px; color: #ffd6e8; background: rgba(210,48,121,.2); font-size: 12px; }
.transcript { width: min(100%, 440px); min-height: 105px; margin-top: 24px; text-align: left; }
.transcript p { margin: 0 0 10px; padding: 11px 13px; border: 1px solid rgba(255,255,255,.09); border-radius: 15px; color: rgba(255,255,255,.9); background: rgba(14,12,24,.48); font-size: 14px; line-height: 1.45; backdrop-filter: blur(12px); }
.transcript span { display: block; margin-bottom: 4px; color: #f3a3c8; font-size: 11px; font-weight: 700; text-transform: uppercase; }
.error { max-width: 360px; margin: 8px 0 0; color: #ffc2ca; font-size: 13px; }
.footer { position: relative; z-index: 1; display: flex; flex-direction: column; align-items: center; padding: 10px 24px calc(24px + var(--app-safe-bottom, 0px)); }
.footer p { margin: 12px 0 0; color: rgba(255,255,255,.52); font-size: 12px; }
.startButton { display: inline-flex; min-width: 170px; cursor: pointer; align-items: center; justify-content: center; gap: 9px; border: 0; border-radius: 999px; padding: 15px 24px; color: #fff; background: linear-gradient(135deg, #ee579d, #ce357c); box-shadow: 0 16px 36px rgba(212,54,127,.32); font-size: 15px; font-weight: 750; }
.endButton { display: inline-flex; width: 66px; height: 66px; cursor: pointer; align-items: center; justify-content: center; border: 0; border-radius: 50%; color: #fff; background: #e24456; box-shadow: 0 15px 34px rgba(226,68,86,.34); }
.topUpBackdrop { position: absolute; z-index: 10; inset: 0; display: flex; align-items: flex-end; justify-content: center; padding: 18px; background: rgba(5,4,9,.68); backdrop-filter: blur(8px); }
.topUpDialog { width: min(100%, 460px); padding: 24px; border: 1px solid rgba(255,255,255,.12); border-radius: 24px; background: #17131f; box-shadow: 0 24px 70px rgba(0,0,0,.5); text-align: center; }
.topUpDialog h2 { margin: 0; font-size: 21px; }
.topUpDialog p { margin: 10px 0 20px; color: rgba(255,255,255,.66); font-size: 14px; line-height: 1.5; }
.topUpDialog button { width: 100%; cursor: pointer; border: 0; border-radius: 999px; padding: 13px 18px; color: #fff; background: #df478d; font-weight: 750; }
.topUpDialog .secondaryButton { margin-top: 8px; color: rgba(255,255,255,.72); background: transparent; }
@keyframes callPulse { 0%,100% { transform: scale(1); } 50% { transform: scale(1.025); } }
@media (max-height: 700px) {
.avatarRing { width: 138px; height: 138px; }
.avatar { width: 124px; height: 124px; }
.content h1 { margin-top: 20px; }
.transcript { min-height: 72px; margin-top: 16px; }
}
src/app/call/voice-call-screen.tsx
-280
View File
@@ -1,280 +0,0 @@
"use client";
import Image from "next/image";
import { useCallback, useEffect, useRef, useState } from "react";
import { Mic, PhoneOff, RotateCcw, Volume2, X } from "lucide-react";
import { MobileShell } from "@/app/_components/core";
import { getApiConfig } from "@/core/net/config/api_config";
import {
VoiceCallTransport,
type CallBillingStatusPayload,
} from "@/core/net/voice-call-transport";
import { VoiceCallAudioCapture } from "@/integrations/voice-call-audio";
import { getSessionAccessToken } from "@/lib/auth/auth_session";
import { useActiveCharacter, useActiveCharacterRoutes } from "@/providers/character-provider";
import { useAppNavigator } from "@/router/use-app-navigator";
import { VoiceCallPlayer } from "./voice-call-player";
import styles from "./voice-call-screen.module.css";
type CallUiState = "idle" | "connecting" | "listening" | "thinking" | "speaking" | "ended" | "error";
const STATE_COPY: Record<CallUiState, string> = {
idle: "Ready to call",
connecting: "Connecting…",
listening: "Listening…",
thinking: "Thinking…",
speaking: "Speaking…",
ended: "Call ended",
error: "Call unavailable",
};
async function getSessionToken(): Promise<string> {
const token = await getSessionAccessToken();
if (token) return token;
throw new Error("Please sign in before starting a call");
}
export function VoiceCallScreen() {
const character = useActiveCharacter();
const routes = useActiveCharacterRoutes();
const navigator = useAppNavigator();
const [uiState, setUiState] = useState<CallUiState>("idle");
const [userTranscript, setUserTranscript] = useState("");
const [aiTranscript, setAiTranscript] = useState("");
const [freeTurns, setFreeTurns] = useState(0);
const [balance, setBalance] = useState(0);
const [cost, setCost] = useState(2);
const [error, setError] = useState<string | null>(null);
const [showTopUp, setShowTopUp] = useState(false);
const transportRef = useRef<VoiceCallTransport | null>(null);
const captureRef = useRef<VoiceCallAudioCapture | null>(null);
const playerRef = useRef<VoiceCallPlayer | null>(null);
const callIdRef = useRef("");
const activeTurnRef = useRef("");
const reconnectTurnRef = useRef("");
const resumeVersionRef = useRef(0);
const endingRef = useRef(false);
const pendingTopUpRef = useRef(false);
const finishCall = useCallback((navigate = true) => {
if (endingRef.current) return;
endingRef.current = true;
captureRef.current?.dispose();
playerRef.current?.dispose();
if (callIdRef.current) transportRef.current?.endCall(callIdRef.current);
transportRef.current?.disconnect();
reconnectTurnRef.current = "";
resumeVersionRef.current = 0;
setUiState("ended");
if (navigate) navigator.push(routes.chat);
}, [navigator, routes.chat]);
const beginListening = useCallback((turnId: string) => {
const capture = captureRef.current;
const transport = transportRef.current;
const callId = callIdRef.current;
if (!capture || !transport || !callId || !turnId) return;
activeTurnRef.current = turnId;
reconnectTurnRef.current = turnId;
setUiState(playerRef.current?.isPlaying ? "speaking" : "listening");
const preRoll: ArrayBuffer[] = [];
let streamOpened = false;
capture.startTurn({
onChunk: (chunk) => {
if (streamOpened) {
transport.sendAudioChunk(chunk);
return;
}
preRoll.push(chunk);
if (preRoll.length > 5) preRoll.shift();
},
onSpeechStart: () => {
setError(null);
if (playerRef.current?.isPlaying) {
playerRef.current.stop();
transport.interrupt(callId);
}
streamOpened = transport.startAudio(
callId,
turnId,
capture.mimeType,
capture.sampleRate,
);
if (streamOpened) {
for (const chunk of preRoll) transport.sendAudioChunk(chunk);
preRoll.length = 0;
setUserTranscript("");
setAiTranscript("");
setUiState("listening");
}
},
onTurnEnd: (vadLatencyMs) => {
if (streamOpened) {
transport.endAudio(callId, turnId, vadLatencyMs);
setUiState("thinking");
}
},
onError: (captureError) => {
setError(captureError.message);
setUiState("error");
},
});
}, []);
const applyBilling = useCallback((status: CallBillingStatusPayload) => {
setBalance(status.creditBalance);
setFreeTurns(status.freeTurnsRemaining);
setCost(status.requiredCredits || 2);
if (status.canContinue && status.nextTurnId) {
beginListening(status.nextTurnId);
return;
}
captureRef.current?.stopTurn();
pendingTopUpRef.current = true;
if (!playerRef.current?.isPlaying) setShowTopUp(true);
}, [beginListening]);
const startCall = useCallback(async () => {
if (uiState !== "idle" && uiState !== "error") return;
endingRef.current = false;
pendingTopUpRef.current = false;
setError(null);
setUiState("connecting");
try {
const player = new VoiceCallPlayer();
playerRef.current = player;
const playerReady = player.prepare();
const capture = new VoiceCallAudioCapture();
await Promise.all([capture.prepare(), playerReady]);
captureRef.current = capture;
const token = await getSessionToken();
const transport = new VoiceCallTransport(getApiConfig().wsUrl, token);
transportRef.current = transport;
player.onPlaying = () => setUiState("speaking");
player.onIdle = () => {
if (pendingTopUpRef.current) setShowTopUp(true);
else if (activeTurnRef.current) setUiState("listening");
};
player.onError = (playbackError) => setError(playbackError.message);
player.onGap = (milliseconds) => {
transport.sendClientMetric("audioChunkGap", milliseconds);
};
transport.onOpen = () => {
if (!reconnectTurnRef.current) reconnectTurnRef.current = crypto.randomUUID();
transport.startCall(
character.id,
reconnectTurnRef.current,
resumeVersionRef.current || undefined,
);
};
transport.onReconnecting = () => {
capture.stopTurn();
player.stop();
callIdRef.current = "";
setUiState("connecting");
};
transport.onStarted = (started) => {
callIdRef.current = started.callId;
activeTurnRef.current = started.turnId;
reconnectTurnRef.current = started.turnId;
resumeVersionRef.current = started.resumeVersion;
setFreeTurns(started.freeTurnsRemaining);
setBalance(started.creditBalance);
setCost(started.costPerPaidTurn || 2);
beginListening(started.turnId);
};
transport.onState = setUiState;
transport.onTranscript = (text) => setUserTranscript(text);
transport.onAiSentence = (text) => {
setAiTranscript((current) => `${current}${current ? " " : ""}${text}`);
};
transport.onAudioChunk = (meta, bytes) => player.enqueue(meta, bytes);
transport.onBillingStatus = applyBilling;
transport.onEnded = () => setUiState("ended");
transport.onError = (code, message) => {
setError(message);
if (
activeTurnRef.current
&& (code === "CALL_TURN_FAILED" || code === "CALL_STT_FAILED")
) {
setUiState("listening");
} else {
setUiState("error");
}
};
transport.connect();
} catch (startError) {
captureRef.current?.dispose();
playerRef.current?.dispose();
setError(startError instanceof Error ? startError.message : String(startError));
setUiState("error");
}
}, [applyBilling, beginListening, character.id, uiState]);
useEffect(() => () => finishCall(false), [finishCall]);
const lowBalance = freeTurns === 0 && balance < cost * 2 && balance >= cost;
return (
<MobileShell background="#090810">
<main className={styles.screen}>
<Image src={character.assets.chatBackground} alt="" fill priority className={styles.background} />
<div className={styles.scrim} />
<header className={styles.header}>
<button type="button" className={styles.iconButton} onClick={() => finishCall()} aria-label="Close call">
<X size={22} aria-hidden="true" />
</button>
<div className={styles.balances}>
<span>{freeTurns} free</span>
<span>{balance} credits</span>
</div>
</header>
<section className={styles.content} aria-live="polite">
<div className={`${styles.avatarRing} ${styles[uiState]}`}>
<Image src={character.assets.avatar} alt={character.displayName} width={148} height={148} className={styles.avatar} priority />
</div>
<h1>{character.displayName}</h1>
<div className={styles.state}>
{uiState === "listening" ? <Mic size={18} aria-hidden="true" /> : null}
{uiState === "speaking" ? <Volume2 size={18} aria-hidden="true" /> : null}
<span>{STATE_COPY[uiState]}</span>
</div>
{lowBalance ? <p className={styles.lowBalance}>Your balance covers fewer than two paid turns.</p> : null}
<div className={styles.transcript}>
{userTranscript ? <p><span>You</span>{userTranscript}</p> : null}
{aiTranscript ? <p><span>{character.shortName}</span>{aiTranscript}</p> : null}
</div>
{error ? <p className={styles.error}>{error}</p> : null}
</section>
<footer className={styles.footer}>
{uiState === "idle" || uiState === "error" ? (
<button type="button" className={styles.startButton} onClick={() => void startCall()}>
{uiState === "error" ? <RotateCcw size={20} aria-hidden="true" /> : <Mic size={20} aria-hidden="true" />}
{uiState === "error" ? "Try again" : "Start call"}
</button>
) : (
<button type="button" className={styles.endButton} onClick={() => finishCall()} aria-label="End call">
<PhoneOff size={27} aria-hidden="true" />
</button>
)}
<p>Speak naturally — you can interrupt at any time.</p>
</footer>
{showTopUp ? (
<div className={styles.topUpBackdrop} role="presentation">
<section className={styles.topUpDialog} role="dialog" aria-modal="true" aria-labelledby="call-topup-title">
<h2 id="call-topup-title">Not enough credits for another turn</h2>
<p>Your current reply has finished. Top up to keep the conversation going.</p>
<button type="button" onClick={() => navigator.openSubscription({ type: "topup", returnTo: "chat" })}>Top up credits</button>
<button type="button" className={styles.secondaryButton} onClick={() => finishCall()}>End call</button>
</section>
</div>
) : null}
</main>
</MobileShell>
);
}

Some files were not shown because too many files have changed in this diff Show More