Pg Tier0 Transaction Loop

Tier 0: 交易闭环修复执行指南

目标：修复核心交易流程断裂点，让买家能在独立站上（手机/TG/桌面）完成一笔完整交易。 主场景：买家通过社交链接到达卖家独立站 → 浏览 → 购买 → 评价 → 分享。 兼容要求：SaaS 模式同步可走通。 触发词："修复交易闭环"、"Tier 0"、"PG-001"~"PG-005"

执行前检查

1. 读取 docs/PROFESSIONAL_GRADE_ROADMAP.md Section 9 → Tier 0 进度
2. 找到第一个 ⏳ 的任务
3. 告知用户将要执行的任务和预估工作量

V1 前置能力确认（首次执行时完成）

在开始第一个 PG 任务前，先验证以下现有能力在独立站模式下可用：

确认结果记录在 docs/PROFESSIONAL_GRADE_ROADMAP.md Section 9 备注中。

AI-First 原则

每个 Tier 0 任务在实现时需考虑 AI 增强层（参见 Roadmap Section 6）：

• PG-002：AI 自动生成 meta description（接入 AI 基础设施）
• PG-003：AI 评价摘要（聚合评价生成一句话总结）
• PG-004：AI 语义搜索（自然语言查询理解）
• 如果 AI 增强无法立即实现，先预留接口和 UI 占位

独立站优先原则

V1 主要场景是独立站。买家通过 TG/社交链接到达卖家的独立站购物，可能完全不感知 SaaS 平台的存在。

• 独立站首页 = 品牌着陆页（不是 marketplace），需有商品展示和店铺信息
• SEO + OG 标签是独立站被发现的生命线
• 买家登录体验要自然（Casdoor OAuth popup → "登录以完成购买"）
• 同一套前端通过 isStandalone 环境变量兼容 SaaS 和独立站

产品设计贯穿原则

以下设计维度不是独立任务，而是执行每个 PG 任务时需持续考虑的：

• Crypto 支付 UX：余额预检 → gas 透明 → 交易等待 UI → 失败恢复（PG-001）
• 法币等价显示：所有价格旁标注法币等价（PG-001/PG-005）
• 术语抽象：用"买家保障"代替 Escrow，"网络手续费"代替 Gas Fee（PG-005）
• 买卖沟通：确保商品详情页和订单页有"联系卖家"入口（PG-005）
• 买家无需登录即可浏览：结账时才要求登录（PG-001）

Platform View 移动端策略

关键操作页面不使用纯响应式，而是设计独立的移动端视图。详见 Roadmap Section 4.7 第 7 条和 Section 5b。

Tier 0 逐任务移动端策略：

基础设施（PG-001 首任务时搭建）：

1. 新建 hooks/usePlatform.ts — 扩展现有 useBreakpoint()，增加 isTGMiniApp 检测
2. 新建 providers/TGMiniAppProvider.tsx — MainButton/BackButton/HapticFeedback 增强
3. 确立路由页面 thin shell 模式：usePlatform() → 分发 Desktop/Mobile 视图

TG Mini App 增强：移动端视图 + TG 特性叠加（不是第三套视图）

• MainButton 替代底部固定 CTA（"去结账"/"确认支付"）
• BackButton 替代自定义返回按钮
• HapticFeedback 在加购/支付确认时触发

完整设计指导见 Roadmap Section 4.7

PG-001: 购物车 + 结账（Mobile-First）

问题

• apps/web/src/app/cart/page.tsx 使用 mock 数据（mockCartItems）
• checkout 页面仅支持单品直接购买（URL params: ?slug=&peerID=&quantity=）
• 无法从购物车发起多商品结账
• 结账页无 MobilePageHeader，移动端无法返回
• MobileHeader 未全局注册，搜索入口不一致
• 部分按钮触摸目标小于 44px

设计原则（不照搬 Desktop）

Desktop 使用 Modal 弹窗做购物车和结账，这在 Web 应用中体验不佳：

• Modal 不可分享 URL、不可返回、SEO 不友好
• 复杂结账流在 Modal 内空间受限

Unified 采用现代 Web 电商模式 + Platform View 分视图：

结账是 V1 第一个采用 Platform View 分视图的页面。路由页面 /checkout/page.tsx 是 thin shell，通过 usePlatform() 分发到桌面/移动端视图组件。两个视图共享 useCheckout() hook 的全部业务逻辑。

历史项目参考（看意图，重新设计）

Desktop API（逻辑复用）：

API: frontend/src/api/shoppingCart.js
  - getShoppingCarts()    → GET /carts
  - addToShoppingCart()   → POST /carts/{peerID}
  - removeCartItem()      → DELETE /carts/{peerID}/{listingID}
  - clearShoppingCarts()  → DELETE /carts

Mobile App 移动端 UX 参考（参考信息层级和流程编排，不照搬 RN 组件）：

结账流：checkout.js → paymentMethod.js → purchaseState.js → paymentSuccess.js
  → 参考：步骤拆分、支付状态过渡动画、成功页信息架构
  → 重新设计：单屏滚动 + 底部 CTA（非多页跳转）

购物车：shoppingCart.js + ShoppingCart template
  → 参考：按卖家分组展示、底部结算栏
  → 重新设计：全页购物车（非 Modal）

商品详情：listing.js + ItemDetail organism
  → 参考：图片浏览、信息分区、底部操作栏
  → 重新设计：全宽 Swiper + Accordion 折叠内容

参考路径：mobazha-mobile/screens/、mobazha-mobile/components/
完整映射：Roadmap Section 8.1a

实施步骤

1. Cart Drawer 组件（新增）

   • 从右侧滑入的购物车预览
   • 显示商品列表 + 小计 + "查看购物车" + "去结账" 按钮
   • 添加商品到购物车后自动打开（短暂显示，确认添加成功）

2. Cart 页面重写

   • 接入真实 API（cartApi.getCarts()）
   • 按卖家分组展示
   • 数量修改、删除、清空
   • 优惠码输入（如商品支持）
   • 每个卖家分组有独立的"去结账"按钮

3. Checkout — Platform View 分视图（V1 第一个分视图页面）

   Step 0: 基础设施搭建（首次执行，后续 PG 任务复用）

   • 新建 hooks/usePlatform.ts（扩展现有 useBreakpoint，增加 isTGMiniApp）
   • 新建 providers/TGMiniAppProvider.tsx（MainButton/BackButton/HapticFeedback）
   • 路由 thin shell 模式：checkout/page.tsx 只做 usePlatform() → 分发

   共享业务逻辑 — useCheckout() hook：

   • 购物车/单品数据获取
   • 地址管理（CRUD、默认地址）
   • 配送方式选择
   • 支付币种选择 + 余额预检 + gas 预估
   • 订单提交 + 支付签名 + 状态追踪
   • 表单验证、错误处理

   CheckoutDesktop（桌面端视图）：

   • 左侧主区：多步 Wizard（地址 → 配送 → 支付）
   • 右侧 sidebar：订单摘要（商品列表 + 价格 + 法币等价 + 买家保障提示）
   • 步骤间有明确的进度指示器

   CheckoutMobile（移动端视图）：

   • 单屏纵向滚动，各区块以 Accordion/Card 形式排列
   • 底部固定 CTA 栏（价格 + "确认支付"按钮），TG Mini App 中用 MainButton 替代
   • 表单输入优化：大触摸目标（≥48px）、适配移动端键盘、autofill 支持
   • 返回按钮：TG 中用 BackButton，普通移动端用 MobilePageHeader

   Crypto 支付执行（两端共用逻辑，UI 适配各自视图）：

   • 余额预检：选择支付币种后立即显示钱包余额和预估 gas，余额不足时提前提示
   • 交易签名：点击"确认支付"后唤起钱包签名，页面显示"等待钱包确认"
   • 交易等待：签名完成后显示等待 UI（进度动画 + 预估确认时间 + "可安全关闭页面"提示）
   • 成功：跳转订单确认页
   • 失败恢复：明确错误原因 + 可操作下一步（重试/换币种/联系卖家）

   入口和登录：

   • 支持单品直购（Buy Now）和购物车结账两种入口
   • 买家无需登录即可浏览，结账时才要求登录（Casdoor OAuth popup → "登录以完成购买"）

4. 订单确认页（新增 /checkout/confirmation）

   • 支付成功后跳转到此页面（不是直接回首页或订单列表）
   • 内容：感谢信息 + 订单编号 + Escrow 初始状态 + 预计流程时间线
   • CTA："查看订单详情" + "继续购物"
   • ShareButton 集成（"分享你购买的商品"）
   • 移动端：确保在 TG Mini App 内显示正常

5. Header MiniCart Badge

   • 购物车图标 badge 接入真实 count
   • 点击打开 Cart Drawer（非跳转页面）

6. 移动端全流程保障（原 PG-006，现合并到 PG-001）

   • 结账页添加 MobilePageHeader（返回按钮 + "结账"标题）
   • root layout 中全局注册 MobileHeader（md:hidden），统一搜索行为
   • 所有内容页（checkout、cart、listing/new）都有 MobilePageHeader
   • 确认底部固定的 Place Order 栏在所有机型正常显示（iOS safe-area-bottom）
   • 所有可交互元素最小 44x44px
   • MobileNav 底栏在 checkout/payment 页面正确隐藏

7. 验收

   • 在 375px iPhone SE 模拟器上跑完全流程：首页→搜索→商品→加购物车→Cart Drawer→Cart 页面→结账→订单确认页→下单
   • 桌面端 1440px 同步验证

关键文件

PG-002: SEO + 社交分享

问题

1. 商品链接分享到社交媒体/聊天工具时没有预览卡片（无 Open Graph 标签）
2. 没有分享按钮，用户需手动复制 URL

合并原 PG-002（SEO）和原 PG-205（社交分享）— 两者强耦合：没有 OG 标签的链接分享出去也没有卡片预览。

实施步骤

1. SEO 工具函数

   • packages/core/utils/seo.ts — 生成 meta tags 的工具
   • 支持 title、description、image、url、type

2. 动态 Meta 标签（使用 react-helmet-async）

   • /product/:slug — 商品标题、描述、首图、价格
   • /store/:peerId — 店铺名、简介、头像
   • /marketplace — 固定 meta

3. ShareButton 组件

   • 复制链接（带 toast 确认）
   • 分享到 Twitter/X（预填文案）
   • 分享到 Telegram
   • 生成二维码（Dialog 展示）
   • 集成位置：ProductDetail、Store 页面、订单完成页

4. OG 标签预渲染（关键：CSR 对社交爬虫无效）

   • 社交平台爬虫（Twitter/Telegram/Discord）不执行 JS，纯 CSR 的 meta 标签对它们不可见
   • 方案 A（推荐）：后端为 /product/:slug 和 /store/:peerId 提供 HTML 预渲染端点，返回带 OG 标签的 HTML shell（仅 <head> 部分有效即可）
   • 方案 B：使用 Cloudflare Workers / Vercel Edge 等边缘渲染，检测 User-Agent 为爬虫时返回预渲染 HTML
   • 非爬虫请求正常走 CSR SPA
   • V1 至少保证分享到 Telegram/Twitter 时有预览卡片

5. 技术 SEO 基础设施（独立站被搜索引擎发现的基础）

   • sitemap.xml：动态生成，包含所有公开商品和店铺页面 URL
     • 独立站模式：后端提供 /sitemap.xml 端点，列出所有活跃商品的 canonical URL
     • 商品更新时自动更新 sitemap
   • JSON-LD 结构化数据：商品详情页输出 Product schema
     • 包含：name, description, image, price, currency, availability, seller
     • 使用 <script type="application/ld+json"> 嵌入
     • 店铺页输出 Organization/Store schema
   • robots.txt：独立站根目录提供，允许搜索引擎爬取商品和店铺页
   • Canonical URL：每个商品和页面有唯一的 canonical URL（<link rel="canonical">）
     • 防止同一商品通过不同路径被索引为重复内容