chore(trellis): add task tracking for ios apple pay feature

.trellis/tasks/04-27-feat-ios-apple-pay/check.jsonl

@@ -0,0 +1,12 @@
+{"role": "system", "content": "You are checking the iOS Apple Pay implementation. Verify all acceptance criteria are met."}
+{"role": "user", "content": "Run checks for the iOS Apple Pay integration feature."}
+{"role": "assistant", "content": "Running verification checks..."}
+{"role": "assistant", "action": "check", "name": "Backend module structure", "command": "ls -la backend/src/v1/payments/", "expected": "Should have __init__.py, schemas.py, service.py, repository.py, router.py, dependencies.py"}
+{"role": "assistant", "action": "check", "name": "Router registration", "command": "grep -r 'payments_router' backend/src/v1/router.py", "expected": "payments_router should be registered in main v1 router"}
+{"role": "assistant", "action": "check", "name": "Error codes documentation", "command": "grep -E 'PAYMENT_|PAYMENT_RECEIPT_|PAYMENT_ALREADY_|PAYMENT_PRODUCT_' docs/protocols/common/http-error-codes.md", "expected": "Should have payment-related error codes documented"}
+{"role": "assistant", "action": "check", "name": "Points integration", "command": "grep -r 'PointsChangeType.PURCHASE' backend/src/", "expected": "Should have PURCHASE change type for points ledger"}
+{"role": "assistant", "action": "check", "name": "iOS StoreKit module", "command": "ls -la apps/lib/features/payments/", "expected": "Should have payments module with data/ and presentation/ subdirs"}
+{"role": "assistant", "action": "check", "name": "StoreKit integration", "command": "grep -r 'StoreKit\\|InAppPurchase' apps/lib/features/payments/", "expected": "Should use StoreKit2 for IAP"}
+{"role": "assistant", "action": "check", "name": "Type checking", "command": "cd backend && uv run basedpyright src/v1/payments/", "expected": "No type errors"}
+{"role": "assistant", "action": "check", "name": "Lint check", "command": "cd backend && uv run ruff check src/v1/payments/", "expected": "No lint errors"}
+{"role": "assistant", "action": "check", "name": "Unit tests", "command": "cd backend && uv run pytest tests/unit/test_apple_payment.py -v", "expected": "All tests pass"}

.trellis/tasks/04-27-feat-ios-apple-pay/implement.jsonl

@@ -0,0 +1,12 @@
+{"role": "system", "content": "You are implementing iOS Apple Pay integration. Follow the task.json requirements. Reference existing code patterns from v1/points/ and features/points/."}
+{"role": "user", "content": "Start implementing the iOS Apple Pay integration feature."}
+{"role": "assistant", "content": "I'll implement this feature in phases:\n\n**Phase 1: Backend - Apple Receipt Validation**\n1. Create `v1/payments/` module with Apple IAP endpoints\n2. Implement receipt validation with Apple's servers\n3. Integrate with existing PointsService for crediting\n4. Add purchase tracking\n\n**Phase 2: iOS - StoreKit2 Integration**\n1. Create `features/payments/` module in Flutter\n2. Implement StoreKit2 product fetching\n3. Implement purchase flow\n4. Connect to backend validation endpoint\n\n**Phase 3: Error Handling & Testing**\n1. Add error codes to http-error-codes.md\n2. Handle edge cases (network, cancelled, pending)\n3. Add integration tests\n\nLet me start with Phase 1."}
+{"role": "assistant", "action": "create_file", "path": "backend/src/v1/payments/__init__.py", "content": "from v1.payments.router import router as payments_router\n\n__all__ = [\"payments_router\"]"}
+{"role": "assistant", "action": "create_file", "path": "backend/src/v1/payments/schemas.py", "content": "from __future__ import annotations\n\nfrom pydantic import BaseModel, ConfigDict, Field\n\n\nclass ApplePurchaseRequest(BaseModel):\n    model_config = ConfigDict(extra=\"forbid\")\n\n    product_id: str = Field(min_length=1, max_length=100)\n    transaction_id: str = Field(min_length=1, max_length=200)\n    receipt_data: str = Field(min_length=1)\n\n\nclass ApplePurchaseResponse(BaseModel):\n    success: bool\n    credits_added: int\n    new_balance: int\n    transaction_id: str"}
+{"role": "assistant", "action": "create_file", "path": "backend/src/v1/payments/service.py", "content": "from __future__ import annotations\n\nimport hashlib\nfrom dataclasses import dataclass\nfrom decimal import Decimal\nfrom typing import TYPE_CHECKING\nfrom uuid import UUID\n\nfrom core.config.packages import get_packages_config_for_region
+from core.http.errors import ApiProblemError, problem_payload
+from schemas.enums import PointsChangeType, PointsBizType
+from schemas.domain.points import ApplyPointsChangeCommand, PurchaseLedgerMetadata
+from v1.points.repository import PointsRepository
+
+if TYPE_CHECKING:\n    pass\n\n\n@dataclass(frozen=True)\nclass AppleReceiptValidationResult:\n    valid: bool\n    product_id: str\n    transaction_id: str\n    purchase_date_ms: int\n    quantity: int = 1\n\n\nclass ApplePaymentService:\n    def __init__(self, repository: PointsRepository) -> None:\n        self._repository = repository\n\n    async def validate_and_process_purchase(\n        self,\n        *,\n        user_id: UUID,\n        user_email: str,\n        product_id: str,\n        transaction_id: str,\n        receipt_data: str,\n        country: str = \"US\",\n    ) -> ApplePurchaseResponse:\n        \"\"\"Validate Apple receipt and credit points.\"\"\"\n        # Step 1: Validate receipt with Apple\n        validation = await self._validate_receipt_with_apple(\n            receipt_data=receipt_data,\n            product_id=product_id,\n            transaction_id=transaction_id,\n        )\n        \n        if not validation.valid:\n            raise ApiProblemError(\n                status_code=400,\n                detail=problem_payload(\n                    code=\"PAYMENT_RECEIPT_INVALID\",\n                    detail=\"Apple receipt validation failed\",\n                ),\n            )\n\n        # Step 2: Check for duplicate transaction\n        event_id = f\"apple.iap:{validation.transaction_id}\"\n        if await self._repository.has_ledger_event(\n            user_id=user_id, event_id=event_id\n        ):\n            raise ApiProblemError(\n                status_code=409,\n                detail=problem_payload(\n                    code=\"PAYMENT_ALREADY_PROCESSED\",\n                    detail=\"Transaction already processed\",\n                ),\n            )\n\n        # Step 3: Get credits for product\n        pkg_config = get_packages_config_for_region(country)\n        credits = self._get_credits_for_product(\n            packages=pkg_config.packages,\n            product_id=product_id,\n        )\n        \n        if credits <= 0:\n            raise ApiProblemError(\n                status_code=400,\n                detail=problem_payload(\n                    code=\"PAYMENT_PRODUCT_NOT_FOUND\",\n                    detail=\"Product not found in catalog\",\n                ),\n            )\n\n        # Step 4: Credit points\n        account = await self._repository.get_or_create_user_points_for_update(\n            user_id=user_id\n        )\n        account.balance = int(account.balance) + credits\n        account.lifetime_earned = int(account.lifetime_earned) + credits\n        account.version = int(account.version) + 1\n\n        # Step 5: Record ledger\n        metadata = PurchaseLedgerMetadata(\n            platform=\"apple\",\n            product_id=product_id,\n            transaction_id=validation.transaction_id,\n        )\n        command = ApplyPointsChangeCommand(\n            user_id=user_id,\n            change_type=PointsChangeType.PURCHASE,\n            biz_type=PointsBizType.PAYMENT,\n            event_id=event_id,\n            amount=credits,\n            direction=1,\n            operator_id=None,\n            metadata=metadata,\n        )\n        await self._repository.append_ledger(\n            command=command,\n            balance_after=int(account.balance),\n        )\n\n        return ApplePurchaseResponse(\n            success=True,\n            credits_added=credits,\n            new_balance=int(account.balance),\n            transaction_id=validation.transaction_id,\n        )\n\n    async def _validate_receipt_with_apple(\n        self,\n        *,\n        receipt_data: str,\n        product_id: str,\n        transaction_id: str,\n    ) -> AppleReceiptValidationResult:\n        \"\"\"Validate receipt with Apple's servers.\"\"\"\n        # TODO: Implement actual Apple server verification\n        # For now, return mock validation for development\n        # Production: Call https://buy.itunes.apple.com/verifyReceipt\n        # Sandbox: Call https://sandbox.itunes.apple.com/verifyReceipt\n        return AppleReceiptValidationResult(\n            valid=True,\n            product_id=product_id,\n            transaction_id=transaction_id,\n            purchase_date_ms=0,\n        )\n\n    def _get_credits_for_product(\n        self,\n        packages: list,\n        product_id: str,\n    ) -> int:\n        \"\"\"Get credits amount for a product ID.\"\"\"\n        for pkg in packages:\n            if pkg.product_code == product_id and pkg.enabled:\n                return pkg.credits\n        return 0"}

.trellis/tasks/04-27-feat-ios-apple-pay/prd.md

@@ -0,0 +1,491 @@
+# PRD：iOS Apple 内购接入积分购买
+
+## 1. 背景与目标
+
+当前应用已经有积分账户、积分流水、注册赠送积分和积分套餐展示能力。用户可以在积分中心看到套餐，但还不能通过 iOS 完成真实购买。本任务目标是在 iOS 端接入 Apple In-App Purchase（IAP），购买成功后由后端验证 Apple 签名交易并给用户发放积分。
+
+本 PRD 同时明确支付数据如何落库、哪些现有表可以复用、哪些表必须新增，以及 iOS 到后端的完整闭环。
+
+## 2. 当前事实
+
+### 2.1 后端现状
+
+- 积分账户表：`user_points`
+- 积分业务流水：`points_ledger`
+- 成本/审计流水：`points_audit_ledger`
+- 注册奖励与新手包资格表：`register_bonus_claims`
+- 积分套餐配置：`backend/src/core/config/static/packages/*.yaml`
+- 当前套餐：`new_user_pack`、`basic_pack`、`popular_pack`、`premium_pack`
+- 当前套餐接口：`GET /api/v1/points/packages`
+- 当前积分余额接口：`GET /api/v1/points/balance`
+
+### 2.2 前端现状
+
+- Flutter 应用已有积分中心：`apps/lib/features/settings/presentation/screens/coin_center_screen.dart`
+- 当前积分中心只加载后端套餐并展示卡片，没有真实购买动作。
+- `apps/pubspec.yaml` 还没有 IAP 相关依赖。
+
+### 2.3 关键约束
+
+- Apple 官方文档已标记旧 `verifyReceipt` 端点为 deprecated。新实现不应以 `receipt_data + verifyReceipt` 作为主方案。
+- StoreKit2 的交易以 Apple 签名的 JWS 形式表达。后端应验证交易签名与交易内容，而不是信任客户端传来的商品、金额或积分数。
+- 当前 `points_ledger` 的约束只允许 `change_type in ('register', 'consume', 'grant', 'adjust')`，`biz_type` 只允许 `chat`。因此它不能直接合法记录“购买入账”。
+
+## 3. 需求范围
+
+### 3.1 必须实现
+
+- iOS 积分中心展示 App Store Connect 中可购买的消耗型 IAP 商品。
+- 用户点击套餐后通过 Apple 支付完成购买。
+- 后端验证 Apple StoreKit2 signed transaction JWS。
+- 后端保证 Apple transaction 只发放一次积分。
+- 后端把积分入账到 `user_points`。
+- 后端把积分入账记录写入 `points_ledger`。
+- 新手包购买后更新 `register_bonus_claims.has_purchased_starter_pack = true`。
+- 购买完成后前端刷新积分余额和套餐列表。
+- 支持购买失败、取消、pending、后端验证失败、网络中断后的恢复处理。
+
+### 3.2 本期不做
+
+- Android / Google Play Billing。
+- 订阅型商品。
+- 非消耗型商品。
+- 后台运营发放、优惠券、折扣码。
+- Web 支付。
+
+## 4. 产品定义
+
+### 4.1 商品类型
+
+所有积分包均为 Apple 消耗型商品（consumable）。
+
+| 后端 `product_code` | App Store Product ID | 类型 | 积分 | 备注 |
+|---|---|---|---:|---|
+| `new_user_pack` | `com.meeyao.qianwen.new_user_pack` | starter | 60 | 每个邮箱身份只允许购买一次 |
+| `basic_pack` | `com.meeyao.qianwen.basic_pack` | regular | 100 | 可重复购买 |
+| `popular_pack` | `com.meeyao.qianwen.popular_pack` | regular | 210 | 可重复购买 |
+| `premium_pack` | `com.meeyao.qianwen.premium_pack` | regular | 415 | 可重复购买 |
+
+价格以 App Store Connect 为准。后端 YAML 中的价格仅用于非商店展示参考；iOS 支付页最终展示应以 StoreKit 返回的本地化价格为准。
+
+### 4.2 新手包资格
+
+- 后端继续使用 `register_bonus_claims.has_purchased_starter_pack` 作为新手包资格的源头。
+- `GET /api/v1/points/packages` 中，如果该字段为 `true`，不返回 `new_user_pack`。
+- 后端支付校验时必须再次检查资格，不能只依赖前端是否展示。
+- 如果用户删除账号后用同一邮箱重新注册，`register_bonus_claims` 的邮箱哈希仍应阻止再次购买新手包。
+
+## 5. 数据保存方案
+
+### 5.1 结论
+
+不能只复用现有数据库表。应采用“复用积分账户和资格表 + 新增 Apple 支付交易表 + 最小扩展积分流水约束”的方案。
+
+复用现有表：
+
+- `user_points`：继续保存余额、累计获得、累计消耗。
+- `register_bonus_claims`：继续保存新手包是否已购买。
+- `points_ledger`：继续作为用户积分变动的权威流水，但需要扩展枚举和约束来支持购买入账。
+
+必须新增表：
+
+- `apple_iap_transactions`：保存 Apple 交易校验、幂等、发放状态、退款/撤销状态和原始签名快照。
+
+### 5.2 为什么必须新增支付交易表
+
+`points_ledger` 只回答“用户积分为什么变了”，不适合作为支付交易系统的唯一事实表，原因如下：
+
+- 支付交易有独立生命周期：`received -> verified -> granted -> failed -> refunded/revoked`。
+- 支付幂等需要按 Apple `transactionId` 全局去重，而 `points_ledger` 当前唯一约束是 `(user_id, event_id)`。
+- 支付需要保存 Apple 交易环境、原始交易 ID、签名 JWS、购买时间、撤销时间、bundle id、appAccountToken 等审计字段。
+- 支付成功但积分入账失败时，需要能补偿重试；单靠 `points_ledger` 无法表达“已验证未发放”。
+- 后续退款、客服核查、对账、App Store Server Notifications V2 都需要独立交易表承载。
+
+### 5.3 `apple_iap_transactions` 表设计
+
+建议新增 Alembic 迁移创建表：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | UUID PK | 内部交易记录 ID |
+| `user_id` | UUID not null | 当前购买归属用户，来自后端 JWT，不接受客户端传入 |
+| `product_code` | varchar not null | 后端套餐码，例如 `basic_pack` |
+| `app_store_product_id` | varchar not null | Apple 商品 ID |
+| `transaction_id` | varchar not null unique | Apple 交易 ID，核心幂等键 |
+| `original_transaction_id` | varchar null | Apple 原始交易 ID |
+| `web_order_line_item_id` | varchar null | Apple 可选订单行 ID |
+| `environment` | varchar not null | `Sandbox` 或 `Production` |
+| `bundle_id` | varchar not null | 必须等于当前 iOS bundle id |
+| `app_account_token` | UUID null | 客户端购买时传入的用户绑定 token，用于降低串单风险 |
+| `purchase_date` | timestamptz not null | Apple 交易购买时间 |
+| `revocation_date` | timestamptz null | Apple 撤销/退款时间 |
+| `status` | varchar not null | `received`、`verified`、`granted`、`failed`、`refunded`、`revoked` |
+| `credits` | bigint not null | 本次应发积分，由后端套餐配置决定 |
+| `currency` | varchar null | Apple 或后端记录的币种 |
+| `price_milliunits` | bigint null | 如 Apple JWS 提供则保存，单位按 Apple 字段定义 |
+| `ledger_event_id` | varchar null unique | 对应 `points_ledger.event_id` |
+| `signed_transaction_info` | text not null | 客户端提交或服务器查询到的 Apple signed transaction JWS |
+| `apple_payload` | jsonb not null default `{}` | 验签后的交易 payload 快照 |
+| `failure_code` | varchar null | 验证或入账失败原因码 |
+| `created_at` / `updated_at` | timestamptz | 时间戳 |
+
+约束与索引：
+
+- `transaction_id` 全局唯一。
+- `(user_id, created_at desc)` 索引用于用户购买记录查询。
+- `(status, updated_at)` 索引用于补偿任务扫描。
+- `status` 使用 check constraint 限定合法值。
+- `environment` 使用 check constraint 限定 `Sandbox` / `Production`。
+
+### 5.4 `points_ledger` 最小扩展
+
+新增积分变更类型：
+
+- `PointsChangeType.PURCHASE = 'purchase'`
+
+新增业务类型：
+
+- `PointsBizType.PAYMENT = 'payment'`
+
+约束调整：
+
+- `change_type` 允许 `purchase`。
+- `biz_type` 允许 `payment`。
+- `purchase` 必须 `direction = 1`。
+- `purchase` 必须 `biz_type = 'payment'` 且 `biz_id` 不为空。
+- `purchase` 的 `biz_id` 保存 `apple_iap_transactions.id`。
+- `purchase` 的 `event_id` 建议为 `payment.apple_iap:{transaction_id}`。
+
+`points_ledger.metadata.ext` 建议保存：
+
+```json
+{
+  "source": "apple_iap",
+  "platform": "ios",
+  "product_code": "basic_pack",
+  "app_store_product_id": "com.meeyao.qianwen.basic_pack",
+  "transaction_id": "1000000123456789",
+  "original_transaction_id": "1000000123456789",
+  "environment": "Production",
+  "apple_iap_transaction_id": "uuid"
+}
+```
+
+### 5.5 `points_audit_ledger` 是否扩展
+
+本期不强制把购买写入 `points_audit_ledger`。支付审计以 `apple_iap_transactions` 为准，用户积分变更以 `points_ledger` 为准。
+
+如果后续希望所有积分变动都统一进入 `points_audit_ledger`，再单独扩展它的 `change_type/biz_type` 约束。不要在本期为了“统一”扩大实现范围。
+
+### 5.6 `register_bonus_claims` 使用方式
+
+新手包入账成功后：
+
+- 按当前用户邮箱计算 `email_hash`。
+- 如果对应 claim 已存在，设置 `has_purchased_starter_pack = true`。
+- 如果不存在但用户购买的是新手包，后端应创建 claim，并写入 `email_hash`、`user_email_snapshot`、`first_user_id_snapshot`、`grant_event_id`。
+- 该操作必须与积分入账在同一个数据库事务中完成。
+
+## 6. 后端接口设计
+
+### 6.1 新增接口
+
+`POST /api/v1/payments/apple/transactions/verify`
+
+请求：
+
+```json
+{
+  "productCode": "basic_pack",
+  "appStoreProductId": "com.meeyao.qianwen.basic_pack",
+  "transactionId": "1000000123456789",
+  "signedTransactionInfo": "eyJhbGciOiJFUzI1NiIs...",
+  "appAccountToken": "7c4c7a82-2f6f-4e70-b57a-8b0a7f2e9b72"
+}
+```
+
+字段规则：
+
+- `productCode` 必须是后端套餐配置中的合法值。
+- `appStoreProductId` 必须与后端映射表匹配。
+- `transactionId` 必须与验签后的 Apple payload 中的 `transactionId` 一致。
+- `signedTransactionInfo` 必须是 Apple 签名 JWS。
+- `appAccountToken` 如果存在，必须与后端为当前用户生成/约定的 token 一致。
+
+响应 200：
+
+```json
+{
+  "status": "granted",
+  "productCode": "basic_pack",
+  "transactionId": "1000000123456789",
+  "creditsAdded": 100,
+  "newBalance": 180,
+  "ledgerEventId": "payment.apple_iap:1000000123456789"
+}
+```
+
+重复提交同一已发放交易时仍返回 200：
+
+```json
+{
+  "status": "already_granted",
+  "productCode": "basic_pack",
+  "transactionId": "1000000123456789",
+  "creditsAdded": 0,
+  "newBalance": 180,
+  "ledgerEventId": "payment.apple_iap:1000000123456789"
+}
+```
+
+### 6.2 可选接口
+
+`GET /api/v1/payments/apple/transactions/{transactionId}`
+
+用途：前端在网络中断或 App 重启后查询交易是否已经入账。可延后实现；如果本期不做，前端应通过重新提交 `signedTransactionInfo` 实现幂等恢复。
+
+### 6.3 错误码
+
+新增到 `docs/protocols/common/http-error-codes.md`：
+
+| code | status | 说明 | 前端处理 |
+|---|---:|---|---|
+| `PAYMENT_PRODUCT_NOT_FOUND` | 404 | `productCode` 不存在或未启用 | 刷新套餐并提示商品不可用 |
+| `PAYMENT_PRODUCT_MISMATCH` | 422 | 客户端商品 ID 与后端/Apple 验证结果不一致 | 阻断入账并提示重试 |
+| `PAYMENT_TRANSACTION_INVALID` | 422 | Apple signed transaction 无效、验签失败或 payload 不合法 | 提示购买验证失败 |
+| `PAYMENT_TRANSACTION_REVOKED` | 409 | 交易已撤销或退款，不允许入账 | 提示购买不可用 |
+| `PAYMENT_TRANSACTION_CONFLICT` | 409 | 交易已由另一个用户或冲突状态处理 | 提示联系客服或刷新余额 |
+| `PAYMENT_STARTER_PACK_INELIGIBLE` | 409 | 当前邮箱身份已购买过新手包 | 刷新套餐并隐藏新手包 |
+| `PAYMENT_APPLE_UNAVAILABLE` | 503 | Apple Server API 或证书获取不可用 | 提示稍后重试，前端不要 finish/complete 交易 |
+| `PAYMENT_GRANT_FAILED` | 500 | 验证成功但入账事务失败 | 提示稍后重试，保留交易用于补偿 |
+
+注：如果重复提交同一用户已完成发放的交易，应返回 200 `already_granted`，不应返回错误。
+
+## 7. 后端处理流程
+
+### 7.1 主流程
+
+1. 前端收到 StoreKit 购买成功事件。
+2. 前端把 `signedTransactionInfo`、`transactionId`、`productCode`、`appStoreProductId` 发送到后端。
+3. 后端从 JWT 获取 `user_id` 和邮箱。
+4. 后端校验 `productCode` 是否启用，并映射到期望的 Apple Product ID。
+5. 后端验证 Apple JWS 签名、证书链、bundle id、environment、transaction id、product id、购买时间、撤销状态。
+6. 后端按 `transaction_id` 查 `apple_iap_transactions`。
+7. 如果交易已经由当前用户成功发放，返回 `already_granted`。
+8. 如果交易已绑定其他用户或处于冲突状态，返回结构化错误。
+9. 后端开启数据库事务。
+10. 后端插入或锁定 `apple_iap_transactions` 记录。
+11. 后端锁定 `user_points` 行。
+12. 后端按套餐配置计算积分，不信任客户端传入的积分数。
+13. 如果是新手包，锁定/创建 `register_bonus_claims` 并检查 `has_purchased_starter_pack`。
+14. 后端增加 `user_points.balance` 和 `lifetime_earned`。
+15. 后端写入 `points_ledger` 的 `purchase` 流水。
+16. 后端更新 `apple_iap_transactions.status = 'granted'`、写入 `ledger_event_id`。
+17. 如果是新手包，设置 `has_purchased_starter_pack = true`。
+18. 事务提交。
+19. 后端返回新增积分和新余额。
+20. 前端收到成功响应后调用 `completePurchase` / finish transaction。
+21. 前端刷新余额和套餐列表。
+
+### 7.2 幂等策略
+
+- Apple `transactionId` 是支付发放的全局幂等键。
+- `apple_iap_transactions.transaction_id` 必须唯一。
+- `points_ledger.event_id = payment.apple_iap:{transaction_id}`。
+- 同一用户重复提交已完成交易返回 200 `already_granted`。
+- 不同用户提交同一 transaction 必须拒绝，避免串单。
+
+### 7.3 补偿策略
+
+- 如果 Apple 已扣款、客户端未收到后端成功响应，前端下次启动或交易流恢复时重新提交同一交易。
+- 后端接口必须可重复调用。
+- 如果后端已插入 `apple_iap_transactions` 但未完成 `points_ledger`，后台补偿任务可扫描 `status='verified'` 或 `status='failed'` 且具备有效 Apple payload 的记录重试入账。
+- 前端只有在后端确认 `granted/already_granted` 后才完成 StoreKit 交易，避免交易被提前 finish 后丢失发放机会。
+
+### 7.4 退款与撤销
+
+本期至少保存 `revocationDate` 和交易状态，不自动扣回已发放积分。
+
+后续建议接入 App Store Server Notifications V2：
+
+- 收到退款/撤销通知后按 `transactionId` 更新 `apple_iap_transactions.status`。
+- 是否扣回积分需要产品另行决策。考虑积分可能已消耗，直接扣回可能导致负余额或复杂追偿，本期不默认实现。
+
+## 8. iOS / Flutter 接入设计
+
+### 8.1 技术选择
+
+优先使用 Flutter 官方 `in_app_purchase` 插件及 iOS StoreKit 实现。若当前插件版本无法稳定提供 StoreKit2 `Transaction.signedData`，则增加最小 iOS platform channel 获取 `signedTransactionInfo`，不要把旧 `verifyReceipt` 作为主验证方案。
+
+建议依赖：
+
+- `in_app_purchase`
+- 如需 iOS 细节能力，再引入官方 StoreKit 平台包。
+
+### 8.2 前端模块建议
+
+```text
+apps/lib/features/payments/
+├── data/
+│   ├── apis/
+│   │   └── apple_payment_api.dart
+│   ├── models/
+│   │   └── apple_purchase_models.dart
+│   └── services/
+│       └── apple_iap_service.dart
+└── presentation/
+    └── bloc/
+        └── payment_bloc.dart
+```
+
+如果实现时发现只服务积分中心，`PaymentBloc` 可以先保持轻量，不要过度抽象。
+
+### 8.3 前端购买流程
+
+1. 积分中心加载后端套餐。
+2. 前端把后端 `productCode` 映射为 App Store Product ID。
+3. 前端调用 StoreKit 查询商品详情。
+4. UI 用 StoreKit 返回的本地化价格覆盖后端展示价格。
+5. 用户点击购买。
+6. 前端构造购买参数，带上当前用户绑定用的 `appAccountToken`。
+7. 前端调用 consumable purchase。
+8. 前端监听 purchase stream。
+9. 状态为 `pending`：展示处理中，不调用后端入账。
+10. 状态为 `error` 或 `canceled`：展示失败/取消，不调用后端入账。
+11. 状态为 `purchased` 且含可验证数据：调用后端验证接口。消耗型商品不依赖 restore 作为补发入口，补发应通过未完成交易重新提交实现。
+12. 后端返回 `granted/already_granted` 后，前端调用 `completePurchase`。
+13. 前端刷新 `GET /api/v1/points/balance` 和 `GET /api/v1/points/packages`。
+
+### 8.4 UI 状态
+
+- 套餐加载中：使用项目统一加载组件。
+- 商品不可用：禁用对应卡片并提示稍后再试。
+- 购买中：当前卡片按钮进入 loading，避免重复点击。
+- pending：显示 Apple 正在处理，不发放积分。
+- 成功：刷新余额；正常成功路径可不打扰，必要时显示轻量成功反馈。
+- 失败：按后端 RFC7807 `code` 映射本地化错误。
+
+## 9. App Store Connect 配置
+
+上线前必须完成：
+
+1. iOS App ID 开启 In-App Purchase capability。
+2. Xcode Runner target 开启 In-App Purchase capability。
+3. App Store Connect 创建 4 个 consumable 商品。
+4. Product ID 与本 PRD 表格完全一致。
+5. 配置价格、展示名称、描述和审核截图。
+6. 配置沙盒测试账号。
+7. 后端配置 Apple 验签所需 bundle id、Apple 根证书/JWS 证书链校验策略；如果需要主动调用 App Store Server API，再配置 issuer/key id/private key。
+8. 确认后端区分 Sandbox / Production，但业务逻辑保持一致。
+
+## 10. 协议与文档更新要求
+
+实现前必须先更新协议文档：
+
+- 新增支付协议文档：`docs/protocols/payments/apple-iap-protocol.md`
+- 更新错误码文档：`docs/protocols/common/http-error-codes.md`
+- 更新积分数据协议：`docs/protocols/common/user-points-chat-data-protocol.md`
+
+需要修正的现有协议不一致点：
+
+- `docs/protocols/common/user-points-chat-data-protocol.md` 中套餐示例仍使用旧字段 `priceUsd`、`badge`、`new_user_pack_099_60`，但当前后端实际返回 `price`、`productCode` 等字段，应同步修正。
+- 该文档仍描述 `points_ledger.biz_id -> sessions.id`，但当前模型和迁移已取消该外键，应同步修正为快照引用。
+
+## 11. 安全要求
+
+- 后端永远从 JWT 获取用户身份，客户端不得传 `userId`。
+- 后端不信任客户端传入的积分、价格、币种。
+- 后端必须验证 Apple signed transaction JWS。
+- 后端必须验证 `bundleId`、`productId`、`transactionId`、`environment`、`revocationDate`。
+- 后端必须按 `transactionId` 全局幂等。
+- 后端日志禁止打印完整 JWS、用户邮箱、访问令牌或 Apple 私钥。
+- Apple 私钥只能通过 `core.config.settings` 读取配置，不允许散落 `os.getenv`。
+- 支付入账必须在数据库事务中完成。
+
+## 12. 测试策略
+
+### 12.1 后端单元测试
+
+- 验签成功后创建 `apple_iap_transactions`。
+- 商品不存在返回 `PAYMENT_PRODUCT_NOT_FOUND`。
+- product id 不匹配返回 `PAYMENT_PRODUCT_MISMATCH`。
+- revoked transaction 不发放积分。
+- 同一 transaction 重复提交只发放一次。
+- 同一 transaction 被不同用户提交时拒绝。
+- 新手包第一次购买成功，第二次返回 `PAYMENT_STARTER_PACK_INELIGIBLE`。
+- 入账后 `user_points.balance/lifetime_earned` 正确增加。
+- 入账后 `points_ledger` 写入 `purchase/payment`。
+
+### 12.2 后端集成测试
+
+- 使用伪造的 Apple verifier 依赖注入，避免测试依赖真实 Apple 网络。
+- 覆盖事务回滚：支付记录、积分账户、流水、新手包标记必须一致提交或一致回滚。
+- 覆盖并发重复提交：只有一个请求成功入账。
+
+### 12.3 前端测试
+
+- 套餐接口与 StoreKit 商品映射正确。
+- 购买成功后调用后端验证并刷新余额。
+- 后端返回 `already_granted` 时仍完成 StoreKit 交易并刷新余额。
+- pending/error/canceled 不调用入账接口。
+- 后端错误码正确映射本地化提示。
+
+### 12.4 手工测试
+
+- Xcode StoreKit Configuration 本地测试。
+- App Store Connect Sandbox 账号测试。
+- 网络中断后重启 App，未完成交易可重新提交并发放。
+- TestFlight 环境测试。
+- 新手包隐藏与重复购买阻断。
+
+## 13. 实施阶段
+
+### Phase 1：协议与数据库
+
+1. 更新协议文档和错误码。
+2. 新增 `apple_iap_transactions` 模型与 Alembic 迁移。
+3. 扩展 `PointsChangeType`、`PointsBizType` 与 `points_ledger` check constraints。
+
+### Phase 2：后端支付服务
+
+1. 新增 `v1/payments/` 模块。
+2. 实现 Apple transaction verifier 抽象。
+3. 实现支付校验、幂等和积分入账服务。
+4. 接入 `v1/router.py`。
+5. 添加单元测试和集成测试。
+
+### Phase 3：iOS / Flutter
+
+1. 添加 IAP 依赖。
+2. 实现商品查询和购买流监听。
+3. 实现后端验证 API client。
+4. 接入 `CoinCenterScreen`。
+5. 添加前端测试。
+
+### Phase 4：联调与发布准备
+
+1. 配置 App Store Connect 商品。
+2. 配置后端 Apple 验签参数。
+3. Sandbox 和 TestFlight 测试。
+4. 检查日志、错误码、补偿路径。
+
+## 14. 风险与缓解
+
+| 风险 | 缓解 |
+|---|---|
+| 客户端支付成功但后端未入账 | 后端幂等接口 + 前端不提前 completePurchase + 重启后重新提交 |
+| 重复发放积分 | `apple_iap_transactions.transaction_id` 唯一 + `points_ledger.event_id` 幂等 |
+| 商品配置不一致 | 后端维护 `productCode -> App Store Product ID` 映射并强校验 |
+| 新手包被重复购买 | 后端事务内锁定/更新 `register_bonus_claims` |
+| Apple 服务临时不可用 | 返回 `PAYMENT_APPLE_UNAVAILABLE`，前端保留交易稍后重试 |
+| 退款后积分已消耗 | 本期只记录退款状态，不自动扣回；后续单独设计追偿策略 |
+| Flutter 插件无法暴露 StoreKit2 signedData | 增加最小 iOS platform channel 获取 `Transaction.signedData` |
+
+## 15. 成功标准
+
+- iOS Sandbox 可完成 4 个积分包购买。
+- 每笔 Apple transaction 最多发放一次积分。
+- 新手包同一邮箱身份只能发放一次。
+- 支付入账后 `user_points`、`points_ledger`、`apple_iap_transactions` 数据一致。
+- 网络中断/重复提交不会导致漏发或重复发放。
+- 新增/修改的协议文档、错误码、迁移、后端测试、前端测试均完成。

.trellis/tasks/04-27-feat-ios-apple-pay/task.json

@@ -0,0 +1,34 @@
+{
+  "title": "iOS Apple Pay Integration for Points Purchase",
+  "slug": "feat-ios-apple-pay",
+  "branch": "worktree/feat-ios-apple-pay",
+  "status": "pending",
+  "priority": "high",
+  "dev_type": "fullstack",
+  "created_at": "2026-04-27",
+  "updated_at": "2026-04-27",
+  "assignee": null,
+  "labels": [
+    "ios",
+    "payment",
+    "apple-iap",
+    "points",
+    "backend"
+  ],
+  "description": "Integrate Apple In-App Purchase (IAP) for iOS points purchase flow, connecting frontend StoreKit2 with backend receipt validation.",
+  "acceptance_criteria": [
+    "iOS app can display available packages via StoreKit2",
+    "User can purchase points through Apple IAP",
+    "Backend validates Apple receipt and credits points",
+    "Purchase history is recorded in points_ledger",
+    "Error handling for failed/cancelled purchases",
+    "Starter pack purchase tracked in register_bonus_claims"
+  ],
+  "dependencies": [],
+  "blocks": [],
+  "related_docs": [
+    "docs/protocols/common/http-error-codes.md",
+    "backend/src/v1/points/service.py",
+    "apps/lib/features/points/data/models/package_info.dart"
+  ]
+}