定制商品方案adv

一、定制电商平台一期实施方案（重整版）

核心原则：

先 C 端再 B 端；

标题层级最多到三级；

API 注释不再用接口小标题（不出现 ### \GET…“）；

保留你原方案的完整业务语义，不做过度精简。

参考风格与产品定位

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

1. 应用介绍与定位
Section titled “1. 应用介绍与定位”

1.1 一人团队可行性与自动化前提
Section titled “1.1 一人团队可行性与自动化前提”
1. 产品与库存依赖 POD 供应商（Printful/Printify/Gelato）。
2. 网站和部署采用 Astro + Vercel，降低运维负担。
3. 客服与风控引入 AI（如 Google Vision）做内容审核辅助。
4. 支付成功后通过接口自动化推进订单流程。
1.2 运营日常与阶段路线
Section titled “1.2 运营日常与阶段路线”
1. 每日核心任务：引流内容生产 + 数据复盘。
2. 三阶段策略：
  - 第一阶段（1-2周）：极简验证（先跑通支付物流）。
  - 第二阶段（2-4周）：加入 2D 定制和自动化审核。
  - 第三阶段（长期）：扩展 AI 能力与虚拟助理协作。
1.3 定制产品池
Section titled “1.3 定制产品池”
1. 袜子 + 刺绣 + 贴图
2. 脸贴（Sticker Mule）
3. 宠物定制画像（AI）
4. 冰箱贴
5. 半袖
6. 杯子
7. 手机壳
2. 视觉与体验策略
Section titled “2. 视觉与体验策略”

2.1 架构策略（少 SKU 场景）
Section titled “2.1 架构策略（少 SKU 场景）”
1. 弱化分类页，强化首页叙事。
2. 首页即画廊（Home as Gallery），产品详情页承担核心转化。
3. 导航采用简洁形态（汉堡菜单/浮动导航）。
2.2 首页与详情页设计重点
Section titled “2.2 首页与详情页设计重点”
1. 首页：长卷轴/全屏分段，首屏高质感视频或动态 Mockup。
2. 详情页：实时预览、沉浸背景、材质细节展示。
3. 交互动效：滚动视差、缩放、动态过渡。
2.3 动效与性能平衡
Section titled “2.3 动效与性能平衡”
1. 动效分级：L0（CSS/SVG）/ L1（滚动 reveal）/ L2（Canvas滤镜）。
2. 非首屏动效必须懒加载。
3. 必须支持 prefers-reduced-motion。
3. 项目目标与关键决策
Section titled “3. 项目目标与关键决策”

3.1 项目目标
Section titled “3.1 项目目标”
1. 面向欧美与一带一路国家，优先速度与稳定性。
2. 商品数量少但定制复杂。
3. 商品数据优先供应商同步，减少手工后台录入。
4. 订单链路抗网络波动。
3.2 已确认决策
Section titled “3.2 已确认决策”
1. 前台：Astro + React Islands。
2. 定制：一期 2D（Konva/Fabric），二期 3D（R3F/Three）。
3. CMS：Strapi 5。
4. 数据库：Supabase PostgreSQL。
5. 一期下发策略：审批通过后同步调用供应商（不启用复杂队列分发）。
3.3 幂等与防重底线
Section titled “3.3 幂等与防重底线”
1. webhook 去重：unique(provider, event_id)。
2. 审批状态只允许一次跃迁：pending_review -> approved。
3. 下发固定幂等键：order_id + supplier_id。
4. supplier_orders 唯一约束：unique(order_id, supplier_id)。
4. C端菜单与功能点
Section titled “4. C端菜单与功能点”

4.1 C端菜单结构
Section titled “4.1 C端菜单结构”
1. 首页
2. 产品详情
3. 定制产品详情
4. 购物车
5. 结账支付
6. 我的订单
7. 个人信息
8. 登录/注册
9. 政策与帮助
4.2 菜单功能点
Section titled “4.2 菜单功能点”
1. 首页
  - 页面目标：快速传达品牌调性并把用户导向单品。
  - 展示内容：首屏 Hero、7 个单品入口、品牌故事、政策入口。
  - 交互动作：滚动分屏、CTA 跳转 products/[slug] 或 customize/[slug]。
  - 状态处理：首屏资源优先，非首屏动效懒加载。
  - 异常处理：政策接口失败时降级显示默认政策链接。
2. 产品详情
  - 页面目标：完成规格选择并决定进入普通购买或定制流程。
  - 展示内容：标题、价格、规格、材质、交期、侵权提示。
  - 交互动作：选规格、加购、进入定制产品详情。
  - 状态处理：规格未选时禁用“加入购物车”。
  - 异常处理：库存不足或参数非法时前端提示并阻止提交。
3. 定制产品详情
  - 页面目标：让用户完成定制并生成可落单数据。
  - 展示内容：2D 画布、文本/图片/颜色控件、实时预览、定制摘要。
  - 交互动作：上传图片、编辑文案、拖拽缩放、保存草稿、写入购物车。
  - 状态处理：校验通过才允许加购；模板缺失时禁用下单。
  - 异常处理：图片超限、敏感词命中、模板文件缺失均给明确提示。
4. 购物车
  - 页面目标：确认商品与定制内容，进入支付。
  - 展示内容：商品信息、定制摘要、数量、金额、运费估算。
  - 交互动作：增删改、切换规格、跳转结账。
  - 状态处理：登录后自动触发游客车归并。
  - 异常处理：价格变化或商品失效时提示刷新并重新确认。
5. 结账支付
  - 页面目标：创建支付并完成订单受理。
  - 展示内容：地址、费用拆分、支付状态。
  - 交互动作：创建草稿、创建支付意图、提交支付。
  - 状态处理：支付成功后等待 webhook 确认并展示受理结果。
  - 异常处理：支付失败可重试；重复回调不重复建单。
6. 我的订单
  - 页面目标：用户追踪订单进度与物流。
  - 展示内容：列表、筛选、详情、时间线。
  - 交互动作：分页、状态筛选、查看详情。
  - 状态处理：按支付/物流/完成状态过滤。
  - 异常处理：数据为空时显示空态引导去首页选购。
7. 个人信息
  - 页面目标：维护用户资料与收货地址。
  - 展示内容：基础资料、地址列表、默认地址标识。
  - 交互动作：编辑资料、新增/修改/删除地址。
  - 状态处理：表单实时校验（手机号、邮编、国家码）。
  - 异常处理：保存失败显示字段级错误信息。
8. 登录/注册
  - 页面目标：建立身份与会话。
  - 展示内容：快速注册（邮箱 OTP 一步注册即登录）、Google 登录入口。
  - 交互动作：快速注册/登录、登出、续期。
  - 状态处理：首次 OTP 验证成功自动创建账号并登录；登录成功后回跳来源页并归并购物车。
  - 异常处理：OTP 过期、频率限制、第三方登录失败给可重试提示。
9. 政策与帮助
  - 页面目标：满足合规与用户信任。
  - 展示内容：隐私、退换货、税费与运输说明。
  - 交互动作：按国家切换政策内容。
  - 状态处理：Geo-IP 无法识别时回落到默认国家策略。
  - 异常处理：策略接口失败时显示静态兜底政策页。
4.3 我的订单筛选（Tab/下拉）
Section titled “4.3 我的订单筛选（Tab/下拉）”
1. 已发货：shipping_status=shipped
2. 已付款：payment_status=paid
3. 待付款：payment_status=unpaid
4. 已完成：order_status=completed
4.4 定制能力实施细则（按你的原意）
Section titled “4.4 定制能力实施细则（按你的原意）”
1. 三组数据源
  - 数据库中的产品与定制参数数据。
  - 每个定制商品独立 html 模板。
  - 单产品补充配置（含未来 3D 参数位）。
2. 路由规则
  - products/[slug] 固定普通详情模板。
  - customize/[slug] 通过文件路由加载定制模板。
  - 模板文件缺失时禁用下单并提示。
3. 定制快照结构
  - product_id、template_id、selected_sku、options、render_meta。
5. B端菜单与功能点（字段全备注）
Section titled “5. B端菜单与功能点（字段全备注）”

5.1 B端菜单结构
Section titled “5.1 B端菜单结构”
1. 管理员登录
2. 产品管理（供应商产品、本地产品）
3. 订单管理（审批订单、本地订单、供应商订单、弃单）
4. 审批记录
5. 邮件模板
5.2 管理员登录
Section titled “5.2 管理员登录”
- 展示字段（含备注）
  - admin_email：管理员登录账号。
  - role：管理员角色（admin/operator），决定可见菜单和可执行动作。
  - last_login_at：最近登录时间，用于审计。
  - session_status：会话状态（有效/过期）。
- 功能点（详细）
  - 登录方式：邮箱密码登录（一期），可选 OTP。
  - 会话管理：登录、登出、会话续期、会话过期跳转。
  - 权限控制：按角色控制菜单可见与按钮权限。
  - 安全控制：登录失败次数限制、异常登录记录。
  - 审计记录：记录登录时间、IP、设备信息（可选一期）。
5.3 供应商产品
Section titled “5.3 供应商产品”
- 展示字段（含备注）
  - supplier_name：供应商名称。
  - supplier_product_id：供应商商品唯一 ID。
  - supplier_product_name：供应商商品名称。
  - product_type：普通/定制。
  - mapped_local_product：关联本地商品。
  - is_available：可售状态。
  - last_sync_at：最近同步时间。
  - sync_status：同步结果。
- 功能点（详细）
  - 查询与筛选：按供应商、类型、同步状态、是否已映射筛选。
  - 同步能力：单条同步、选中同步、全量同步、定时同步开关。
  - 映射能力：未映射商品一键创建本地商品并建立初始关联。
  - 排错能力：查看最近同步错误、查看原始 payload。
  - 风险控制：同步失败不覆盖旧可用数据，防止误下架。
5.4 本地产品
Section titled “5.4 本地产品”
- 展示字段（含备注）
  - product_id：本地商品主键。
  - name：商品名称。
  - status：发布状态。
  - product_kind：普通/定制。
  - base_price：基础售价。
  - publish_at：上架时间。
  - unpublish_at：下架时间。
  - custom_template_id：模板 ID。
  - custom_map_status：模板映射状态。
  - updated_at：更新时间。
- 功能点（详细）
  - 商品生命周期：新建、编辑、复制、上下架、定时发布。
  - 映射管理：绑定供应商 SKU、设置优先供应商。
  - 定制配置：绑定模板、绑定参数 schema、配置必填项。
  - 发布校验：价格、库存映射、模板映射、定制参数完整性校验。
  - 审计能力：记录每次变更人、变更时间、变更摘要。
5.5 审批订单
Section titled “5.5 审批订单”
- 展示字段（含备注）
  - order_no：订单号。
  - user_email：用户邮箱。
  - pay_status：支付状态。
  - approval_status：审批状态。
  - risk_flags：风控标记。
  - created_at：下单时间。
  - amount_total：订单总金额。
- 功能点（详细）
  - 审批查看：订单明细、定制快照、支付状态、风控标记。
  - 审批动作：通过、驳回、备注。
  - 通过后动作：按 supplier_id 聚合并同步调用供应商下单。
  - 驳回后动作：记录驳回原因并触发退款流程。
  - 并发保护：同单审批加行锁，防重复审批与重复下发。
5.6 本地订单
Section titled “5.6 本地订单”
- 展示字段（含备注）
  - order_no：订单号。
  - user_id/email：用户标识。
  - order_status：订单状态。
  - approval_status：审批状态。
  - payment_status：支付状态。
  - dispatch_status：下发状态。
  - amount_total：总金额。
  - created_at：创建时间。
- 功能点（详细）
  - 列表筛选：按时间、支付状态、审批状态、下发状态筛选。
  - 详情查看：订单项、支付流水、审批记录、物流摘要。
  - 客服处理：加备注、标记异常、人工跟进。
  - 售后处理：触发全额/部分退款。
  - 数据导出：按筛选条件导出运营报表（可选一期）。
5.7 供应商订单
Section titled “5.7 供应商订单”
- 展示字段（含备注）
  - order_no：本地订单号。
  - supplier_name：供应商名称。
  - supplier_order_id：供应商订单号。
  - supplier_status：供应商状态。
  - shipping_status：物流状态。
  - tracking_no：物流单号。
  - tracking_company：物流公司。
  - next_sync_at：下次同步时间。
  - sync_fail_count：失败次数。
  - last_error：最近错误。
- 功能点（详细）
  - 状态同步：单条同步、批量同步、定时同步。
  - 物流追踪：展示运单号、物流公司、状态时间线。
  - 异常处置：失败重试、错误信息查看、人工介入标记。
  - 事件审计：查看供应商返回的历史事件与 payload 快照。
  - 幂等保障：重试复用幂等键，避免重复下单。
5.8 弃单
Section titled “5.8 弃单”
- 展示字段（含备注）
  - user_id/email：用户标识与触达地址。
  - abandoned_cart_count：累计弃单次数。
  - last_abandoned_at：最近弃单时间。
  - email_send_count：发送次数。
  - recovered_count：挽回转化次数。
  - resend_quota_left：邮件服务额度。
- 功能点（详细）
  - 识别规则：草稿超时（45~60 分钟）标记为 abandoned。
  - 发送策略：自动发送、全量发送、按用户选中发送。
  - 模板联动：关联邮件模板并支持发送前预览。
  - 额度管理：展示 Resend 剩余额度，防超额发送。
  - 效果追踪：记录发送次数、打开情况（可选）、回收转化。
5.9 审批记录
Section titled “5.9 审批记录”
- 展示字段（含备注）
  - order_no：关联订单号。
  - event_type：审批事件类型。
  - actor_user_id：操作人。
  - note：备注。
  - metadata：参数摘要。
  - created_at：事件时间。
- 功能点（详细）
  - 时间线：按订单查看提交/通过/驳回/备注事件。
  - 筛选：按操作人、事件类型、时间范围筛选。
  - 审计：保留参数摘要、结果、时间，支持追责与复盘。
  - 导出：按条件导出审计记录（可选一期）。
5.10 邮件模板
Section titled “5.10 邮件模板”
- 展示字段（含备注）
  - template_key：模板唯一键。
  - template_name：模板名称。
  - subject：邮件标题。
  - enabled：是否启用。
  - updated_at：更新时间。
- 功能点（详细）
  - 模板管理：新增版本、编辑主题与正文变量。
  - 测试能力：指定邮箱测试发送并记录结果。
  - 启停控制：启用/禁用模板，避免误发。
  - 变量校验：发送前校验必填变量是否齐全。
  - 版本追踪：记录更新时间与操作人。
6. 订单、审批与供应商同步流程
Section titled “6. 订单、审批与供应商同步流程”

6.1 一期主流程
Section titled “6.1 一期主流程”
1. 用户支付成功，webhook 验签并落库受理订单。
2. 订单进入 pending_review。
3. 后台审批通过后，按 supplier_id 同步调用供应商下单。
4. 写入/更新 supplier_orders。
5. 定时任务同步供应商状态和物流。
6.2 审批通过接口关键控制
Section titled “6.2 审批通过接口关键控制”
1. 校验订单状态仍为 pending_review。
2. 使用 for update 防并发重复审批。
3. 更新审批字段（approved_by、approval_decided_at）。
4. 调用供应商接口并 upsert supplier_orders。
5. 任一供应商失败则记录错误并标记人工介入状态。
6.3 定时同步任务
Section titled “6.3 定时同步任务”
1. 扫描 next_sync_at <= now() 的 supplier_orders。
2. 拉取供应商订单/物流状态。
3. 回写 supplier_status、shipping_status、tracking_no、last_sync_at。
4. 按失败次数做退避重试。
7. 目录结构（详细）
Section titled “7. 目录结构（详细）”

7.1 一期目录树
Section titled “7.1 一期目录树”
```
custom-platform/
├─ apps/
│  ├─ storefront/                               # C端（Astro + React Islands）
│  │  ├─ src/pages/
│  │  │  ├─ index.astro                         # 首页
│  │  │  ├─ products/[slug].astro               # 产品详情
│  │  │  ├─ customize/[slug].astro              # 定制产品详情
│  │  │  ├─ cart/index.astro                    # 购物车
│  │  │  ├─ checkout/index.astro                # 结账支付
│  │  │  ├─ orders/index.astro                  # 我的订单
│  │  │  ├─ account/index.astro                 # 个人信息
│  │  │  ├─ login/index.astro                   # 登录/注册
│  │  │  ├─ legal/[slug].astro                  # 政策页面
│  │  │  └─ api/                                # BFF 接口
│  │  ├─ src/custom-pages/                      # 每个定制商品独立模板
│  │  ├─ src/custom-config/                     # 单产品补充配置
│  │  ├─ src/modules/                           # 业务模块
│  │  ├─ src/components/                        # 组件
│  │  └─ src/lib/                               # 请求、supabase、工具
│  ├─ admin/                                    # B端后台
│  │  ├─ src/pages/
│  │  ├─ src/modules/
│  │  └─ src/lib/
│  └─ worker/                                   # 一期定时任务
│     ├─ src/jobs/
│     ├─ src/adapters/
│     ├─ src/clients/
│     └─ src/lib/
├─ packages/
│  ├─ adapters/
│  ├─ db/
│  ├─ shared/
│  └─ ui/
└─ docs/
```
7.2 目录说明
Section titled “7.2 目录说明”
1. apps/storefront（C端）
  - src/pages/index.astro：品牌首页与产品导流入口。
  - src/pages/products/[slug].astro：普通商品详情页（规格、价格、加购）。
  - src/pages/customize/[slug].astro：定制产品详情页（2D 预览和定制交互）。
  - src/pages/cart/index.astro：购物车页（汇总、编辑、结账入口）。
  - src/pages/checkout/index.astro：支付前确认页（地址、费用、支付）。
  - src/pages/orders/index.astro：用户订单列表与筛选。
  - src/pages/account/index.astro：用户资料与地址管理。
  - src/pages/login/index.astro：登录注册入口。
  - src/pages/legal/[slug].astro：隐私/退换/税务等政策页面。
  - src/pages/api/*：BFF 接口层（购物车、支付、订单、政策聚合），所有敏感写操作走服务端。
  - src/custom-pages/*：每个定制商品独立模板文件（一个商品一个模板）。
  - src/custom-config/*：单产品补充配置（控件限制、默认值、二期3D参数预留）。
  - src/modules/*：按业务拆分前端逻辑（home/product/customizer/cart/checkout/orders/account）。
  - src/components/*：通用 UI 与业务组件（ui/common/sections/islands）。
  - src/lib/*：基础能力（Supabase 客户端、请求实例、常量、类型、工具）。
2. apps/admin（B端）
  - src/pages/*：后台页面路由，对应菜单页（供应商产品、本地产品、审批、订单、弃单、模板）。
  - src/modules/*：按菜单域拆分业务逻辑（如 approvals 只负责审批流程与动作）。
  - src/lib/request：adminReqClient 与统一错误处理。
  - src/lib/table：列表列定义、筛选项、排序规则。
  - src/lib/form：表单 schema 与字段校验。
  - src/lib/permission：角色权限与页面按钮权限控制。
3. apps/worker（定时任务）
  - src/jobs/supplier-product-sync：同步供应商商品与定制参数。
  - src/jobs/supplier-order-sync：同步供应商订单状态、物流状态、运单信息。
  - src/jobs/abandon-cart-reminder：扫描弃单并触发邮件提醒。
  - src/adapters：任务内部复用的供应商/支付调用封装。
  - src/clients：外部 API 客户端（供应商、支付、邮件服务）。
  - src/lib：重试策略、日志封装、告警工具。
4. packages（跨应用共享）
  - packages/adapters：供应商与支付适配器统一入口，屏蔽各供应商 JSON 差异。
  - packages/db/migrations：数据库迁移脚本（001/002/003…）。
  - packages/db/schema：表结构与字段定义。
  - packages/db/dao：数据访问层，统一查询写入行为。
  - packages/shared：共享类型、枚举、常量、错误码。
  - packages/ui：shadcn 二次封装组件（可选）。
5. docs（文档资产）
  - 定制电商平台主方案.md：原始总方案文档。
  - 一期实施方案-重整版-干净版.md：当前执行版本（本文件）。
  - 审批流与多供应商下单-详细设计.md：审批与供应商下发专题。
  - 00x_*.sql：数据库迁移与结构说明脚本。
6. 目录约束（执行规范）
  - 一期禁止引入与当前流程冲突的复杂分发目录（如 outbox dispatch worker 体系）。
  - 定制商品上线前必须同时具备：模板文件、参数映射、补充配置。
  - 新增菜单功能必须同步补充：src/pages、src/modules、API 路由与文档说明。
7.3 目录输入/输出数据映射
Section titled “7.3 目录输入/输出数据映射”
1. apps/storefront/src/pages
  - 输入：URL 参数（slug/查询参数）、登录态、BFF 返回数据。
  - 输出：页面 HTML、客户端交互状态、用户提交动作（加购/支付/查询）。
  - 关联菜单：首页、产品详情、定制产品详情、购物车、结账、我的订单、个人信息。
2. apps/storefront/src/pages/api
  - 输入：前端请求参数、用户 token、支付回调事件、Geo-IP 信息。
  - 输出：标准 JSON 响应、订单受理写入、策略聚合结果。
  - 关键产出：订单列表、支付意图、政策数据、购物车数据。
3. apps/storefront/src/custom-pages
  - 输入：product_id 对应模板映射、定制参数、用户交互输入。
  - 输出：定制预览 UI、customization_snapshot。
  - 关键约束：模板缺失则禁用下单。
4. apps/storefront/src/custom-config
  - 输入：商品维度补充配置（默认值、限制、坐标、材质规则）。
  - 输出：模板渲染行为参数、校验规则参数。
  - 关键作用：让不同商品可走不同定制规则。
5. apps/storefront/src/modules
  - 输入：页面参数 + API 数据 + 本地状态。
  - 输出：可复用业务逻辑（如购物车归并、定制校验、订单筛选）。
  - 关键作用：避免把业务逻辑散落在页面层。
6. apps/admin/src/pages
  - 输入：管理员登录态、筛选条件、模块层查询结果。
  - 输出：后台列表页、详情页、操作入口（审批、同步、退款）。
  - 关联菜单：供应商产品、本地产品、审批订单、本地订单、供应商订单、弃单、审批记录、邮件模板。
7. apps/admin/src/modules
  - 输入：页面动作（通过/驳回/同步/发送）、表单参数。
  - 输出：API 调用结果、操作状态、错误提示。
  - 关键产出：审批动作结果、同步任务结果、邮件发送结果。
8. apps/admin/src/lib
  - 输入：模块层请求参数、用户权限信息。
  - 输出：统一请求、统一错误、权限判断结果、表单与表格配置。
  - 关键作用：收敛后台通用能力。
9. apps/worker/src/jobs
  - 输入：数据库待处理记录（next_sync_at、弃单草稿等）、外部 API 响应。
  - 输出：同步后状态回写、失败重试计数、日志事件。
  - 关键产出：supplier_orders 状态推进、弃单发送记录。
10. apps/worker/src/adapters 与 src/clients
  - 输入：标准化任务参数（订单、供应商、支付、邮件）。
  - 输出：外部服务响应的标准化结果。
  - 关键作用：隔离不同供应商/支付平台接口差异。
11. packages/adapters
  - 输入：平台统一领域模型参数。
  - 输出：各供应商/支付渠道可执行 payload。
  - 关键作用：避免业务层直接依赖第三方 JSON 格式。
12. packages/db
  - 输入：迁移定义、业务读写需求。
  - 输出：数据库结构变更、DAO 查询写入能力。
  - 关键产出：表结构、索引、约束、数据访问封装。
13. packages/shared
  - 输入：跨应用公共定义需求。
  - 输出：统一类型、枚举、常量、错误码。
  - 关键作用：统一前后端语义，减少状态值不一致。
14. docs
  - 输入：产品策略、技术方案、评审反馈。
  - 输出：可执行文档、接口定义、迁移说明。
  - 关键作用：作为团队单一事实来源（SSOT）。
8. API 备注
Section titled “8. API 备注”

8.1 C端 API 备注
Section titled “8.1 C端 API 备注”
- Supabase Auth OTP：快速注册/登录（OTP 验证通过后自动创建账号并登录）。
- Supabase Auth Google OAuth：第三方登录。
- GET /api/auth/session：获取会话，过期返回 401。
- GET /api/cart：获取购物车，支持游客会话。
- POST /api/cart/items：新增购物项，定制商品必带 customization_snapshot。
- PATCH /api/cart/items/:id：修改购物项。
- DELETE /api/cart/items/:id：删除购物项。
- POST /api/checkout/create-draft：创建结账草稿。
- POST /api/checkout/shipping-rate：运费估算。
- POST /api/payments/create-intent：创建支付意图。
- POST /api/payments/webhook：支付回调，先验签后幂等。
- GET /api/orders：我的订单列表（支持筛选与分页）。
- GET /api/orders/:id：我的订单详情（校验归属）。
- GET/PATCH /api/profile：个人资料。
- GET/POST/PATCH/DELETE /api/addresses*：地址管理。
- GET /api/policies/by-country：按国家返回政策。
- GET /api/customize/:productId/base|options：定制基础信息与参数。
- POST /api/customize/:productId/validate|draft：定制校验与草稿保存。
8.2 B端 API 备注
Section titled “8.2 B端 API 备注”
- POST /admin-api/auth/login：管理员登录。
- POST /admin-api/auth/logout：管理员登出。
- GET /admin-api/session：管理员会话和角色。
- GET/POST /admin-api/supplier-products*：供应商商品查询与同步。
- GET /admin-api/supplier-products/:id/raw：原始 payload（脱敏）。
- GET/POST/PATCH /admin-api/products*：本地商品管理。
- POST /admin-api/products/:id/publish|unpublish|map-supplier-sku：发布与映射操作。
- GET /admin-api/orders/pending-approval：待审批订单。
- GET /admin-api/orders/:id：审批详情。
- POST /admin-api/orders/:id/approve|reject：审批通过/驳回。
- GET /admin-api/orders：本地订单列表。
- PATCH /admin-api/orders/:id/note：客服备注。
- POST /admin-api/orders/:id/refund：退款（幂等）。
- GET/POST /admin-api/supplier-orders*：供应商订单查询与同步。
- GET /admin-api/supplier-orders/:id/events：事件流水。
- GET/POST /admin-api/abandoned*：弃单查询与发送。
- GET /admin-api/order-approval-events*：审批审计查询。
- GET/PATCH/POST /admin-api/mail-templates*：模板管理与测试。
9. 基建规范（Supabase / 请求 / 状态 / UI）
Section titled “9. 基建规范（Supabase / 请求 / 状态 / UI）”

9.1 Supabase 双实例
Section titled “9.1 Supabase 双实例”
1. supabaseBrowserClient（anon）：C端快速注册（OTP）/Google 登录与用户侧数据。
2. supabaseServiceClient（service_role）：服务端写操作（订单/审批/支付/供应商）。
9.2 请求实例分层
Section titled “9.2 请求实例分层”
1. C端：publicReqClient、protectedReqClient、paymentReqClient。
2. B端：adminReqClient（可选 adminExportReqClient）。
9.3 状态管理
Section titled “9.3 状态管理”
1. 服务端状态：TanStack Query。
2. 本地交互状态：Zustand。
3. 表单：react-hook-form + zod。
9.4 shadcn 组件规范
Section titled “9.4 shadcn 组件规范”
1. 统一封装：AppTable、AppForm、AppDialog、StatusBadge、AppDrawer。
2. 列表页结构：筛选 + 表格 + 批量操作。
3. 详情页结构：卡片 + 时间线 + 操作区。
9.5 RLS 规则
Section titled “9.5 RLS 规则”
1. 公共可读：products(active)、countries、country_policies(active)。
2. 用户私有：carts、orders、profiles。
3. 服务端专有：payments、payment_events、supplier_orders、order_approval_events。
10. 数据与任务基建
Section titled “10. 数据与任务基建”

10.1 核心表
Section titled “10.1 核心表”
1. orders、order_items
2. payments、payment_events、payment_webhook_events
3. supplier_orders、supplier_order_events
4. order_approval_events
10.2 定时任务
Section titled “10.2 定时任务”
1. 商品同步（每日）
2. 供应商订单/物流同步（5~10 分钟）
3. 弃单提醒任务
10.3 幂等执行规则
Section titled “10.3 幂等执行规则”
1. webhook 先去重再处理。
2. 审批接口行锁 + 状态校验。
3. 下发复用固定幂等键。
11. 验收清单
Section titled “11. 验收清单”

11.1 C端验收
Section titled “11.1 C端验收”
- 登录/地址/购物车/结账/支付可用
- 定制产品详情可正常下单
- 我的订单支持状态筛选
11.2 B端验收
Section titled “11.2 B端验收”
- 供应商产品同步可用
- 本地产品发布可用
- 审批和下发可用
- 供应商订单同步和重试可用
- 弃单与邮件模板可用
11.3 稳定性验收
Section titled “11.3 稳定性验收”
- webhook 重复投递不重复建单
- 审批重复点击不重复下单
- 供应商重试不重复落单

定制商品方案adv

一、定制电商平台一期实施方案（重整版）

参考风格与产品定位

1. 应用介绍与定位

1.1 一人团队可行性与自动化前提

1.2 运营日常与阶段路线

1.3 定制产品池

2. 视觉与体验策略

2.1 架构策略（少 SKU 场景）

2.2 首页与详情页设计重点

2.3 动效与性能平衡

3. 项目目标与关键决策

3.1 项目目标

3.2 已确认决策

3.3 幂等与防重底线

4. C端菜单与功能点

4.1 C端菜单结构

4.2 菜单功能点

4.3 我的订单筛选（Tab/下拉）

4.4 定制能力实施细则（按你的原意）

5. B端菜单与功能点（字段全备注）

5.1 B端菜单结构

5.2 管理员登录

5.3 供应商产品

5.4 本地产品

5.5 审批订单

5.6 本地订单

5.7 供应商订单

5.8 弃单

5.9 审批记录

5.10 邮件模板

6. 订单、审批与供应商同步流程

6.1 一期主流程

6.2 审批通过接口关键控制

6.3 定时同步任务

7. 目录结构（详细）

7.1 一期目录树

7.2 目录说明

7.3 目录输入/输出数据映射

8. API 备注

8.1 C端 API 备注

8.2 B端 API 备注

9. 基建规范（Supabase / 请求 / 状态 / UI）

9.1 Supabase 双实例

9.2 请求实例分层

9.3 状态管理

9.4 shadcn 组件规范

9.5 RLS 规则

10. 数据与任务基建

10.1 核心表

10.2 定时任务

10.3 幂等执行规则

11. 验收清单

11.1 C端验收

11.2 B端验收

11.3 稳定性验收