Skip to content
YN Blog Logo Creatwang

定制商品base

应用介绍

Section titled “应用介绍”

实话实说：如果全靠“手干”，一个人绝对做不过来；但如果靠“系统”，一个人绰绰有余。

跨境电商圈有很多年入百万的“一人公司”（One-man Band），他们的核心逻辑不是勤奋，而是自动化。

你可以把你的创业过程想象成在编写一个**“自动赚钱的脚本”**。作为开发者，你有天然的优势。以下是我为你设计的“一个人如何分身”的方案：

  1. 为什么你能做过来？（自动化是你的分身）
  • 产品与库存：由 Printful 搞定。你不用找工厂、不用打包、不用贴单、不用雇仓库管理员。
  • 网站与运维：由 Astro + Vercel 搞定。静态网站不需要维护数据库服务器，不用担心宕机，部署一次就不用管了。
  • 客服与风控：由 AI（如 Google Vision） 搞定。它 24 小时帮你盯着侵权图，比雇个员工更靠谱。
  • 日常发货：由 Webhook 接口 搞定。客户付钱 -> 触发代码 -> 自动给 Printful 下单。这部分你的工作量是 0。
  • 你每天真正的“核心工作”只有两件事

当你把上面的系统搭好后，你的日常工作会缩减为：

  1. 引流（最耗时）：每天花 1-2 小时拍 TikTok 视频或写 SEO 博客。这是独立站的命脉。
  2. 看数据（最关键）：花 30 分钟看 Stripe 的流水、广告的转化率，决定要不要换个产品方向。
  3. 建议的“三步走”减压路线

不要想第一天就做到完美，分阶段来：

  • 第一阶段：极简验证（1-2周）
    • 先不搞 Canvas DIY。
    • 自己用 AI 生成 5 个酷炫设计，录入 Markdown，手动对接 Printful。
    • 目的：先跑通支付和物流，看看到底有没有人买。
  • 第二阶段：技术升级（2-4周）
    • 加入 Canvas DIY 功能和 Google Vision 审核。
    • 完善自动下单脚本。
    • 目的：形成差异化竞争，解放自己的双手。
  • 第三阶段：规模化（长期）
    • 接入更多的 AI 辅助。
    • 如果订单多了，请一个海外的**虚拟助理（VA）**处理邮件（月薪仅需几百美金）。

定制产品

Section titled “定制产品”
  1. 袜子+刺绣+贴图
  2. 脸贴 Sticker Mule
  3. 宠物定制画像 + ai
  4. 冰箱贴
  5. 半袖
  6. 杯子
  7. 手机壳

针对只有 6-7个全定制单品 且追求 “高度吸睛” 的独立站，传统的电商架构（冗长的分类页、列表页）反而会稀释品牌的质感。

建议采用 “极简架构 + 沉浸式视觉”。以下是具体的页面设计建议：

  1. 架构建议：去中心化，弱化分类页

对于 6-7 个品，不需要单独的产品分类页。分类页通常是为成百上千个 SKU 准备的，在产品少的情况下，分类页会显得空旷，降低消费者的购买欲望。

推荐架构：

  • 首页 (Home/Landing Page)：品牌门面，直接展示核心单品。
  • 产品详情页 (PDP)：这是转化核心，因为是定制品，这里需要承载复杂的交互。
  • 购物车/侧边购物车 (Cart/Drawer Cart)：保持流畅。
  • 关于我们/定制指南 (Optional)：讲述定制背后的工艺或故事。
  1. 页面设计核心建议

A. 首页：采用“长卷轴”或“全屏分段”设计

既然品少，就把首页做成一个数字展厅。

  • Hero Section（首屏）：不要放轮播图，用一张冲击力极强的高质感视频或 Mockup 效果图作为背景，文案直接击中定制需求。
  • 分块展示：由于只有 6-7 个品，可以在首页为每个产品分配一个独立的、视觉风格迥异的模块。例如：向上滑动时，背景颜色随产品色调改变。
  • 直接交互：在首页直接露出“开始定制”按钮，缩短用户路径。

B. 详情页：从“货架”转变为“设计工坊”

对于全定制产品，详情页的设计决定了用户是否觉得“值钱”：

  • 实时预览 (Live Preview)：这是吸睛的关键。用户输入文字或上传图片时，Mockup 效果要能实时渲染在产品上。
  • 沉浸式背景：不要使用纯白底色，尝试使用符合品牌调性的渐变色或深色系（Dark Mode），配合高帧率的微交互动作。
  • 细节微距图：展示定制部分的材质细节（如刺绣的线头质感、印刷的凹凸感），用视觉弥补无法触摸的遗憾。

C. 导航栏：隐藏式设计

使用 Menu（汉堡菜单） 或 浮动导航。不要让一排分类链接挡住你精心设计的视觉大图。

  1. 如何实现“高度吸睛”？
  • 利用 Mockup 动态化：不要只放静态图。使用 Lottie 动画或短视频，展示产品从“空白”到“定制完成”的动态过程。
  • 大字报美学 (Typography)：如果产品本身比较简约，可以使用极具张力的超大字体作为设计元素。
  • 交互动效：当用户滚动页面时，产品图片可以有微小的 3D 视差位移或缩放效果。

总结建议

方案：首页即画廊 + 强交互详情页。 把 6-7 个产品当成 6-7 个艺术品来卖。你可以把所有产品直接列在首页，每个产品占满一个屏幕高度，用户滑一下就是一个新品，这种沉浸式体验比传统的分类列表高级得多。

参考https://www.allbirds.com/和https://www.floema.com/en/journal/institutional的设计

每个 POD 供应商（Printful, Printify, Gelato）的 API 文档和参数格式（JSON 结构）都不一样。你需要为每个供应商写一套对接逻辑。

定制电商平台完整方案（整合版 v1.0）

Section titled “定制电商平台完整方案（整合版 v1.0）”

一. 参考风格与产品定位

Section titled “一. 参考风格与产品定位”
  • 视觉/交互风格参考：
  • 首页策略：Home as Gallery（商品少但高定制，弱分类、强叙事）
  • 一期重点：高性能上线 + 2D 定制 + 多供应商基础能力
  • 二期重点：3D 定制、扩展支付、多供应商智能路由

二. 项目目标和代码基建规范

Section titled “二. 项目目标和代码基建规范”
  1. 面向 欧美 + 一带一路 国家访问，速度与评分要顶级。
  2. 商品数量少，但每个商品定制复杂度高。
  3. 不做重商品手工后台录入，优先供应商同步。
  4. 运营/投放/审批类页面可由 CMS 实时更新，不依赖重发版。
  5. 订单链路必须抗网络波动（供应商 API 跨境延迟不可控）。

2.2、 API 路由与 Key 对齐Astro src/pages/api

Section titled “2.2、 API 路由与 Key 对齐Astro src/pages/api”
API方法浏览器 Key服务端 Key
/api/cart/*GET/PATCHauthenticated（或匿名 session 走服务端）service_role 合并匿名车
/api/checkout/create-draftPOSTauthenticatedservice_role 写草稿
/api/orders/createPOST不传 DB，只传业务参数service_role 创建订单
/api/payments/create-intentPOST同上service_role
/api/payments/webhookPOST—service_role + 验签
/api/policies/by-countryGETanon 可读缓存结果可选 service_role 聚合

三. 已确认关键决策（结论）

Section titled “三. 已确认关键决策（结论）”
  1. 前台框架：Astro + React Islands
  2. 定制器：一期 2D（Konva/Fabric）；二期 3D（R3F/Three）
  3. CMS：Strapi 5（投放页/审批页/政策页/内容页）
  4. 主数据库：Supabase PostgreSQL
  5. 队列与编排：Outbox + Worker（二期异步供应商下发）
  6. 上架/下架：一期必须做（站内发布层独立于供应商）
  7. 弃单挽回：一期做“轻量版”（识别 + 单次提醒 + 回收追踪）
  8. 动画规范：新增独立动画目录，分级加载，严格性能预算
  9. 组件策略：原生优先(封装基础组件库)，第三方按需；性能差异通常次于图片/脚本体积

整理

Section titled “整理”

c端

  1. 首页，产品详情页，订单，个人信息，购物车， 2.登录页

b端

  1. 管理员登录
  2. 产品
    1. 供应商产品
    2. 本地产品
  3. 订单
    1. 弃单
    2. 本地订单
    3. 供应商订单
  4. 审批
    1. 审批记录
    2. 审批列表
  5. 邮件模板

四. 功能范围（完整清单）

Section titled “四. 功能范围（完整清单）”

4.1、登录

Section titled “4.1、登录”

  1. 登录/注册本身：前端直连 Supabase Auth（anon key），体验更顺、少一层代理。

  2. 会影响订单/审批/支付的数据操作：全部走后端 API，做权限与业务校验。

  3. c端前端请求实例封装 publicReqClient， 和 认证客户端实例 protectedReqClient

  4. b端全部要认证

  • 登录（可先邮箱/OTP）+ google登录
  • 用户资料
  • 地址/国家
  • 历史订单
  • 购物车数据

A. 本地商品与供应商产品

Section titled “A. 本地商品与供应商产品”

b端菜单：

  1. 供应商产品：

  2. 本地产品

  3. 初始版本，我会默认写死几个供应商的产品id, 然后每次更新供应商产品数据，库存是否可售等这些信息，同步到供应商产品表，会有开启同步(每天自动同步)和手动同步(同步全部，选中同步)

  4. 对接供应商定时更新供应商数据，也可以手动更新供应商产品信息

  5. 供应商产品列表信息，会有供应商名称，产品名称，产品类型，普通|定制，关联的的本地产品，更新时间，操作同步按钮，点击回去供应商接口拉取最新的，没有关联本地产品的供应商产品，会有新建本地产品按钮，点击之后会新建

  6. 多供应商接入（后续可扩到 N 家）初版本先写2家供应商，后面也应该都是写死的

  7. 本地产品列表，会有上下架功能

  8. 商品展示前：先走 Canonical 模型，各供应商商品数据先归一成你平台的统一商品结构，再给前台展示。

  9. 用户下单时：做 SKU 映射 购物车里是你平台 SKU，提交订单时根据映射表找到可用的供应商 SKU 列表。

  10. 下单前校验：查最新库存/价格 调供应商接口做实时校验（或用最近同步数据），确认有货且价格未变。

  11. 落单与记录：写入快照 订单确认时，把“当时用的供应商、价格、库存状态”保存成快照，后续售后/对账可追溯。

  12. 运行保障：异常供应商自动暂停（一期先不做） 如果某供应商连续超时/失败超阈值，系统自动熔断暂停分单，切换到其他供应商，保障整体下单成功率

B. 定制能力

Section titled “B. 定制能力”

c端详情页功能

  1. 定制产品只会拉取基本的产品信息用于基本展示
  2. 定制产品的，产品详情会有对应html文件来高度定制，可以理解一个定制产品会有一个html，来进行高度定制，普通产品只有一个普通产品的模板
  3. 定制的sku参数，会拉取供应商产品的时候会直接同步到库里，这种数据称为定制数据

总结会有3组数据

  1. 数据库中的产品信息和定制信息
  2. 商品详情定制html文件，会选项到详情区域，这个是前端配好产品id写死的
  3. 可能会在定制信息的基础上，写死一些针对这个产品的定制数据比如3d模型等

定制功能

  • 2D 实时预览
  • 二期 3D 实时预览

D. 支付

Section titled “D. 支付”
  • 先支付成功之后会落库，然后后台审批发货
  • 后面有可能拒绝的情况定制品不合规侵权或者供应商没有库存了，退款并说明原因
  • 多支付渠道扩展接口（Provider Adapter）
  • 支付 intent 创建
  • webhook 回调
  • 幂等、防重复处理
  • 退款/部分退款预留

C. 购物与下单

Section titled “C. 购物与下单”

后台菜单，

  1. 供应商订单(例如发货状态，物流信息查看等)，会有开启同步(每天自动同步)和手动同步(同步全部，选中同步)

  2. 2.本地订单(这个数据是要展示到c端的数据，会是一个tree table，父级是用户自己是本地的order西信息)，

  3. 3.审批订单，

  4. 4，审批记录

  5. 支付 webhook 处理 验签、幂等、重试

  6. create order（支付成功，本地落库成功即受理），下单失败提供失败日志，会有一个错误表，收集错误原因，自动5次重试

  7. 下单之后订单会进入后台，等待人工审批

  8. 审批通过之后会调用供应商接口进行发货，留存审批记录

  9. 审批记录的作用有可能供应商出现问题了，用审批记录，拿到用户的完整的下单信息，这里会扩展功能后面再说，只先做个审批记录

  10. 物流信息, c端这里考虑定时拉取供应商数据还是，每天定时同步物流， b端查看订单时候就要调用供应商接口查看物流信息

  11. 成功更新 supplier_order_id，失败重试

  12. 弃单

    • 草稿超过阈值（45~60 分钟）标记 abandoned
    • 发送 1 次提醒
    • 如后续下单则记录 recovered

F. 国家与政策

Section titled “F. 国家与政策”

识别ip地址

  1. 强隐私监管区：欧盟 (EU) & 英国

这是最难啃的骨头，政策配置不当会直接导致广告账户封禁。

  • GDPR 合规：必须在 storefront 强制弹出 Cookie 同步同意弹窗（不是简单的提示，而是用户未点击同意前不能加载 FB/Google 的 Pixel 脚本）。

  • 政策入口：法律条款（Privacy Policy）必须包含对 GDPR 的解释，明确告知数据去向。

  • 投放限制：严禁针对 18 岁以下人群进行个性化广告推送。

  • 高投诉敏感区：美国 (USA)

  • CCPA (加州消费者隐私法)：你的 legal/[slug].astro 页面中必须有一个“Do Not Sell My Personal Information”的链接。

  • 合规声明：美国海关对“定制化产品”的产地标注要求严格。

  • 广告素材：FB/Google 对误导性宣传（比如宣称 3 天到货但实际由于定制需 10 天）监控极严，容易导致主页评分降低直至封号。

  • 政策特殊的其他国家

  • 德国 (Germany)：需要极其严格的 Impressum (法律声明)，必须包含公司负责人、地址、税号等实名信息，否则会面临当地律师的“职业打假”。

  • 中东 (GCC)：广告素材不能包含宗教禁忌或过度暴露的画面。

  • 东南亚/拉美：这些地区更看重退换货政策 (Refund Policy)，因为信任度较低，明确的退货承诺能显著提升转化率。

💡 架构建议：如何在代码中实现多国政策自动切换？

既然你的 api/policies/* 负责按国家聚合政策，建议在 src/lib/seo 中加入以下逻辑：

  1. Geo-IP 定位：在 BFF 层（api/）根据请求 IP 判断国家。
  2. 动态渲染条款：
    • 如果是 DE (德国)：强行在页脚显示详细的 Impressum。
    • 如果是 US (美国)：在结账页显示 Sales Tax 说明。
  3. 广告 GTM 配置：针对不同国家的隐私政策，动态决定加载哪些监测脚本（例如：欧盟用户在同意前，islands 不触发 FB Pixel）。

G. CMS 运营

Section titled “G. CMS 运营”

用来做文章，宣传页等，还有版本发布或者产品更新等页面

H. 增长

Section titled “H. 增长”

b端：弃单菜单， 邮件模板菜单

以用户为基准

弃单table tree 父级用户，子级弃单

当前页面展示Resend 免费额度

可以选择自动发送弃单邮件，也可以点击全部发送，也可以选中用户发送

每个用户记录当前row接收邮件的次数，发送完要同步页面上的邮件额度和当前行的邮件次数

  • 弃单识别
  • 弃单提醒（一期单次）

I. 动画视觉

Section titled “I. 动画视觉”
  • GSAP 滚动与节制入场
  • SVG 动画
  • Canvas 背景/粒子（按需）
  • 图片滤镜（按需）
  • reduced-motion 降级

L. 订单审批

Section titled “L. 订单审批”

要保留审批信息 记录 actor_user_id、时间、请求参数摘要、结果

内容说明
概念订单审批闸门 vs 按供应商拆分下发；一单多供应商如何按 order_items.supplier_id 分组
枚举order_approval_status、order_approval_event_type（完整 CREATE TYPE）
productsrequires_manual_approval boolean
suppliersadapter_key、adapter_config（路由到不同下单接口/Adapter）
ordersapproval_status、approved_by、rejected_by、rejection_reason 等 ALTER
order_approval_events审计流水表 + 可选「仅追加」触发器
dispatch_tasks扩展列：idempotency_key、adapter_key、幂等唯一索引；附整表建表示例（若你尚未建表可对照合并）
事务顺序审批通过时：更新订单 → 写事件 → 按供应商插入多条 dispatch_tasks
支付先审后付 / 先付后审 与表结构的关系（流程在应用层）

说明：若你现有库里已有 task_status、dispatch_tasks 或枚举同名，迁移里要改成 IF NOT EXISTS / 拆分迁移 / 先处理依赖，文档末尾已提醒。

你可以把该 md 整章复制进主文档；若你希望「纯 .sql 迁移文件、零叙述」，我也可以再帮你拆成一个仅含可执行语句的 xxx.sql 文件。

审批流与多供应商下单 — 详细设计（含完整 SQL）

Section titled “审批流与多供应商下单 — 详细设计（含完整 SQL）”

核心原则：审批通过后立即调用供应商下单，不引入 dispatch_tasks/outbox/worker 这套队列体系； 后续靠定时任务轮询供应商同步发货、物流、订单状态。

1) 业务流程（最终版）

Section titled “1) 业务流程（最终版）”
  1. 用户下单：写本地 orders + order_items，approval_status='pending_review'
  2. 运营审批通过：调用你的 Admin API
  3. Admin API 在同一请求中：
    • 更新审批通过字段
    • 直接调用供应商下单接口
    • 成功后写供应商订单映射（supplier_orders）
  4. 定时任务（cron）每 N 分钟跑一次：
    • 拉取供应商订单状态/物流
    • 回写本地 supplier_orders、并同步推进 orders.status/dispatch_status
  5. 异常重试：失败计数 + 下次同步时间退避
  1. 数据库

你已有 orders/order_items/suppliers，只新增一张轻量表即可：

supplier_orders（建议新增）

Section titled “supplier_orders（建议新增）”
  • id
  • order_id（本地订单）
  • supplier_id
  • supplier_order_id（供应商订单号）
  • supplier_status
  • shipping_status
  • tracking_no
  • tracking_company
  • last_sync_at
  • next_sync_at
  • sync_fail_count
  • last_error
  • raw_payload
  • created_at/updated_at

约束建议

Section titled “约束建议”
  • unique(order_id, supplier_id)：同一订单同一供应商只保留一条主映射
  • index(next_sync_at)：给定时任务扫待同步记录
  • index(supplier_status)：运营后台筛选

3) 审批通过接口（关键控制）

Section titled “3) 审批通过接口（关键控制）”
POST /admin/orders/:id/approve

执行顺序建议：

  1. 校验订单状态仍是 pending_review（防重复审批）
  2. 加行锁（for update）防并发重复点击
  3. 更新 orders.approval_status='approved'、approved_by、approval_decided_at
  4. 聚合该订单的 order_items，按 supplier_id 组织 payload
  5. 直接调用供应商 API 下单（可串行，先简单）
  6. 成功后 upsert supplier_orders
  7. 任一供应商失败：
    • 记录失败信息（last_error）
    • 订单标记为 manual_review 或 dispatch_failed（按你偏好）

4) 定时同步任务（你要的主流程）

Section titled “4) 定时同步任务（你要的主流程）”

每 5~10 分钟执行：

  • 查询 supplier_orders where next_sync_at <= now()
  • 调供应商“查订单/查物流”接口
  • 回写：
    • supplier_status
    • shipping_status
    • tracking_no/tracking_company
    • last_sync_at
    • next_sync_at（成功后正常间隔；失败后指数退避）
  • 映射推进 orders：
    • 全部供应商都 shipped -> orders.status='shipped'
    • 全部 completed -> orders.status='completed'
    • 有异常 -> orders.dispatch_status='manual_review'

重点：供应商审批下单

  • 审批接口只允许一次状态跃迁：pending_review -> approved
  • 每次 order_id + supplier_id 生成固定 idempotency_key
  • supplier_orders 加唯一键：unique(order_id, supplier_id)

五. 目录结构（完整建议）

Section titled “五. 目录结构（完整建议）”
custom-platform/                                                    # Monorepo 根目录：前台 / 后台 / CMS / Worker / 共享包 / 运维文档
├─ apps/                                                            # 可独立部署的应用集合
│  ├─ storefront/                                                   # 消费者官网（Astro + React Islands，主站）
│  │  ├─ src/pages/                                                 # 路由页面：首页、商品、定制、法律/投放等
│  │  │  ├─ index.astro                                             # 首页
│  │  │  ├─ products/[slug].astro                                   # 商品详情（静态/增量生成）
│  │  │  ├─ customize/[slug].astro                                  # 2D/3D 定制入口页（重交互用 island）
│  │  │  ├─ legal/[slug].astro                                      # 法律/条款类页面壳（内容可来自 Strapi）
│  │  │  ├─ campaign/[slug].astro                                   # 投放/活动落地页壳
│  │  │  └─ api/                                                    # BFF：需密钥/聚合/写库的接口，禁止暴露 service_role 到浏览器
│  │  │     ├─ cart/*                                               # 购物车读写、合并游客车等
│  │  │     ├─ checkout/*                                           # 结算草稿、弃单相关、国家/运费试算
│  │  │     ├─ orders/*                                              # 创建订单（宜服务端落库+outbox，不授权前端直写表）
│  │  │     ├─ payments/*                                            # 支付 intent、webhook 入口（验签+幂等）
│  │  │     └─ policies/*                                            # 按国家聚合政策/展示用（可带边缘缓存）
│  │  ├─ src/components/{ui,common,sections,islands}                 # 组件：ui=原子；common=全站；sections=区块；islands=React 岛
│  │  ├─ src/content/{products,stories,legal}                          # 可选：本地 MD/MDX 内容（与 Strapi 二选一或混用）
│  │  ├─ src/animations/                                             # 动画资源与逻辑分层（与业务组件解耦）
│  │  │  ├─ core/                                                    # 动画公共：参数、reduced-motion、视口、生命周期
│  │  │  ├─ gsap/                                                    # 时间轴/滚动 reveal 等
│  │  │  ├─ svg/                                                     # 矢量动效
│  │  │  ├─ canvas/                                                  # 粒子/噪点/重绘制（懒加载）
│  │  │  └─ filters/                                                 # 图片滤镜/预设
│  │  ├─ src/lib/{cms,products,checkout,seo,observability}            # 业务库：拉 CMS、商品/定制、结账、SEO、监控
│  │  ├─ src/styles/                                                 # 全局样式、设计 token
│  │  └─ public/                                                   # 不经打包的静态资源：字体、图标、favicon 等
│  │
│  ├─ admin/                                                        # 运营后台：供应商/商品/上下架/订单/支付/国家策略（非内容 CMS）
│  │  ├─ src/modules/                                              # 按业务域分模块
│  │  │  ├─ suppliers                                              # 供应商、凭证引用、同步配置
│  │  │  ├─ products                                               # 站内商品、上下架、定时发布
│  │  │  ├─ mappings                                               # 商品↔供应商 SKU 映射、路由权重
│  │  │  ├─ publish-control                                        # 发布调度、批量暂停/恢复
│  │  │  ├─ orders                                                 # 订单运营、人工介入
│  │  │  ├─ payments                                               # 支付对账、退款入口
│  │  │  ├─ countries                                              # 国家/区域开关
│  │  │  └─ policies                                               # 业务侧政策（与 Strapi 内容页可并存）
│  │  └─ src/pages/*                                               # 后台页面路由
│  │
│  ├─ cms/            # Strapi 5                                    # 内容 CMS：投放页、审批材料页、品牌文章、可配置导航
│  │  ├─ src/api/page                                              # 通用内容页结构
│  │  ├─ src/api/legal                                             # 条款/隐私等（或独立 collection）
│  │  ├─ src/api/campaign                                          # 活动/投放页
│  │  └─ src/api/navigation                                        # 导航/页脚配置
│  │
│  └─ worker/                                                     # 异步 Worker：无 UI，长任务/定时/队列
│     ├─ src/jobs/supplier-sync                                    # 定时拉供应商、写原始层、触发归一化
│     ├─ src/jobs/order-dispatch                                   # outbox 消费、供应商下单、重试与死信
│     ├─ src/jobs/abandon-cart                                     # 弃单扫描与单次提醒
│     ├─ src/jobs/publish-scheduler                                # 定时上架/下架任务
│     └─ src/jobs/cache-revalidate                                 # 失效 CDN/边缘缓存、预热关键路径
│
├─ packages/                                                      # 共享代码：类型、适配器、DB、队列，被多个 app 引用
│  ├─ core/           # canonical schema                           # 统一领域模型与校验（商品/定制项/订单/支付）
│  ├─ adapters/       # supplier/payment adapters                  # 供应商与支付渠道适配实现
│  ├─ db/             # schema + migrations + dao                   # Supabase 迁移、生成类型、数据访问层
│  ├─ queue/          # outbox/retry/idempotency                   # 异步可靠投递、幂等、重试策略
│  ├─ cache/          # redis helpers                              # 可选缓存封装（热读、锁、限流）
│  └─ shared/                                                      # 工具、常量、错误码等纯共享
└─ infra/                                                          # 仓库外沿：运维脚本、监控配置、文档（一般不打包进 app）
   ├─ sql/                                                         # 可选：运维 SQL、一次性脚本（与 packages/db 迁移分工）
   ├─ monitoring/                                                  # 告警、仪表盘配置片段、SLO
   └─ docs/                                                        # 架构文档、目录说明、上线 Runbook

六. 动画模块规范（已纳入）

Section titled “六. 动画模块规范（已纳入）”

6.1 分级

Section titled “6.1 分级”
  • L0：首屏轻量（CSS/SVG）
  • L1：滚动 reveal（GSAP）
  • L2：Canvas/滤镜（可选，懒加载）

6.2 规则

Section titled “6.2 规则”
  • 非首屏动画必须懒加载
  • 动画模块统一 init()/destroy()
  • 支持 prefers-reduced-motion
  • 低端设备自动降级关闭 L2
  • 首屏动画 JS 预算建议 <= 40KB gzip

七. 数据库模型设计（Supabase/PostgreSQL）

Section titled “七. 数据库模型设计（Supabase/PostgreSQL）”

使用 auth.users 作为登录主表，业务数据在 public schema。 以下 SQL 为统一版（可拆 migration）。

八. 性能与网络策略（针对你的核心担心）

Section titled “八. 性能与网络策略（针对你的核心担心）”
  • 首屏尽量静态化，不依赖外部 API
  • Supabase 作为主库（数据量小足够）
  • API 聚合减少往返
  • 对国家政策/运费规则做缓存
  • Redis 用于增强，不做主存储
  • 供应商/支付调用异步化，避免阻塞用户体验

九. 非功能要求（NFR）

Section titled “九. 非功能要求（NFR）”
  • Lighthouse：Performance/SEO/Best Practices/Accessibility 目标 95+
  • Core Web Vitals：LCP < 1.8s，INP < 150ms，CLS < 0.05
  • 首屏 JS 预算严格控制（重交互仅 island 懒加载）
  • 供应商/支付外部依赖异常不阻塞“下单受理”

十. 技术栈与功能点映射（逐项）

Section titled “十. 技术栈与功能点映射（逐项）”
  • Astro：营销页、商品页、政策页静态渲染
  • React Islands：定制器、购物车抽屉等高交互模块
  • ReactBits：仅在 islands 按需使用
  • GSAP：关键动画（非全站重动效）
  • Konva/Fabric：2D 定制
  • R3F/Three：3D 定制（二期）
  • Strapi 5：可运营内容页
  • Supabase：主数据（订单/用户/购物车/政策）
  • Worker：同步/下发/弃单/发布调度
  • Sentry + Web Vitals：监控与告警

十一. 最后检查清单（防遗漏）

Section titled “十一. 最后检查清单（防遗漏）”
  • 供应商 adapter 是否按家拆分
  • 定制项统一 schema 是否已覆盖 image/text/color/enum/size
  • 上/下架是否独立于供应商库存状态
  • 支付 webhook 幂等是否落地
  • CMS 是否只管理内容，不侵入订单逻辑
  • 弃单一期是否上线
  • 动画目录与降级策略是否建立
  • 性能预算是否写入 CI 检查
  • 国家/政策/支付策略是否可按区域切换