最新文章

基于 Django 实现的电商系统功能需求文档¶

对标 Shopify Plus（含 Online Store 2.0、Admin/Storefront API、Checkout Extensibility）的全量电商系统需求规格说明书

文档版本：v1.0
编写日期：2026-07-21
适用技术栈：Python 3.11 + Django 5.x + Django REST Framework + Celery + PostgreSQL + Redis

目录¶

• 第 1 章 文档说明
• 第 2 章 系统总体架构
• 第 3 章 功能模块总览
• 第 4 章 商品与目录管理
• 第 5 章 库存与履约
• 第 6 章 购物车与结账
• 第 7 章 订单管理
• 第 8 章 支付与结算
• 第 9 章 客户与会员体系
• 第 10 章 折扣、优惠与促销
• 第 11 章 营销与触达
• 第 12 章 数据分析与报表
• 第 13 章 主题与模板系统
• 第 14 章 页面、博客与内容
• 第 15 章 SEO 与域名
• 第 16 章 多渠道销售
• 第 17 章 权限、多语言与税务
• 第 18 章 核心数据模型设计
• 第 19 章 REST API 设计
• 第 20 章 非功能性需求
• 第 21 章 开发阶段与里程碑
• 第 22 章 风险与合规
• 附录 A Shopify 与 Django 概念映射表

第 1 章 文档说明¶

1.1 文档目的¶

本文档以 Shopify Plus（含 Online Store 2.0 主题体系、Admin GraphQL API、Storefront API、Checkout Extensibility）为功能对标基准，落地到 Python + Django 技术栈，形成一份覆盖全量电商业务的功能需求规格说明书。

文档面向以下读者：

• 产品经理 / 业务负责人：用于确认功能范围、字段口径与业务规则
• 后端开发工程师：用于理解 Django app 切分、数据模型、API 设计
• 前端 / 主题开发工程师：用于理解模板系统、Storefront 数据契约
• 测试工程师：用于逐条拆解验收点

1.2 对标范围¶

1.3 非目标（本期不实现）¶

• 不复刻 Shopify 的 SaaS 控制台（不提供”商家注册即开店”的多租户入驻流程，本期默认单商户私有部署，但底层数据结构预留 shop_id 字段以支持未来扩展）
• 不实现 Shopify App Store 应用市场机制（仅支持以 Django app 方式插件化扩展）
• 不复刻 Shopify 系、Shop Pay、Shop App 等品牌专属封闭能力，用通用的快捷支付、钱包方案替代
• 不自建支付网关（接入第三方：Stripe / 支付宝 / 微信支付 / 银联等）

1.4 名词术语¶

第 2 章 系统总体架构¶

2.1 整体分层架构¶

系统采用 前后端分离 + 服务端渲染混合 架构（对标 Shopify 由 Liquid 服务端渲染 + Hydrogen 客户端的混合策略）。

┌────────────────────────────────────────────────────────────────────┐
│                          客户端层 (Clients)                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────┐ │
│  │ Online Store │  │ Headless 站点│  │ 第三方渠道   │  │ Admin 后台│ │
│  │ (Django 模板)│  │ (React/Vue 等│  │ (POS/社交/Mk│  │ (Django+JS│ │
│  │              │  │  走Storefront│  │  走Admin API│  │  Admin)  │ │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────┘ │
└────────────────────────────────────────────────────────────────────┘
                                  │
        ┌─────────────────────────┼─────────────────────────┐
        ▼                         ▼                         ▼
┌──────────────┐          ┌──────────────┐         ┌──────────────┐
│  Storefront  │          │   Admin API  │         │ Webhook /    │
│  API (DRF)   │          │   (DRF/Graph │         │ Event Bus    │
│  只读+下单   │          │  ql via      │         │ (Celery+     │
│              │          │   strawberry)│         │  Redis pubsub)│
└──────────────┘          └──────────────┘         └──────────────┘
        └─────────────────────────┬─────────────────────────┘
                                  ▼
        ┌─────────────────────────────────────────────┐
        │           核心业务领域层 (Domain Apps)         │
        │  products │ inventory │ orders │ payments    │
        │  checkout │ customers │ discounts │ marketing│
        │  themes   │ content   │ analytics │ channels │
        │  shops    │ settings  │ metafields│ users     │
        └─────────────────────────────────────────────┘
                                  ▼
        ┌─────────────────────────────────────────────┐
        │   基础设施层 (Infrastructure)                  │
        │  PostgreSQL │ Redis │ Celery │ Storage(S3)   │
        │  Search(Postgres FTS/Elastic) │ Cache │ MQ   │
        └─────────────────────────────────────────────┘

2.2 技术选型¶

2.3 Django App 拆分¶

采用 DDD 限界上下文 切分，每个 app 内含 models.py / services.py / api.py / admin.py / signals.py / migrations。

project/
├── apps/
│   ├── shops/              # 店铺、店铺设置、域名
│   ├── accounts/           # 员工、权限、客户账户
│   ├── products/           # 商品、变体、收藏、图片
│   ├── inventory/          # 库存、库位、调拨、库存事件
│   ├── pricing/            # 价格、多市场定价、汇率
│   ├── cart/               # 购物车、运费预估
│   ├── checkout/           # 结账会话、地址、运费、税额、订单生成
│   ├── orders/             # 订单、履约、退款、取消、退货
│   ├── payments/           # 支付意图、支付凭证、对账、网关适配
│   ├── customers/          # 客户档案、地址簿、积分
│   ├── discounts/          # 折扣码、自动折扣、购物车规则
│   ├── marketing/          # 邮件/SMS 触达、自动化、Audience 分群
│   ├── analytics/          # 销售分析、漏斗、留存、报表
│   ├── themes/             # 主题、模板、sections、blocks、资源
│   ├── content/            # 页面、博客、文章
│   ├── catalog/            # 导航、菜单、Shopify Metaobject
│   ├── metafields/         # 通用元字段
│   ├── seo/                # SEO 模板、 redirects、URL 别名
│   ├── channels/           # 多渠道（POS / Online / 手动 / Facebook 等）
│   ├── tax/                # 税率、税务计算引擎
│   ├── shipping/           # 运费策略、承运商适配
│   ├── webhooks/           # Webhook 订阅、推送、重试
│   ├── notifications/      # 通知模板（邮件/SMS/站内）
│   └── web/                # 商城前台视图（Liquid-like 渲染入口）
├── core/                   # 公共：BaseModel、混入、枚举、错误码
├── infra/                  # 基础设施接入：storage、cache、mq、observability
├── config/                 # settings、urls、wsgi/asgi
└── tests/

2.4 与 Shopify 概念的映射策略¶

• Shopify 的 Liquid + Sections architecture → 在 Django 中以”主题资源 + 模板引擎 JSON schema + 区块组件类” 实现，见第 13 章
• Shopify 的 Admin/Storefront 双 API → 同样拆分两套 endpoint：Admin API 走 /api/admin/*（店铺员工鉴权），Storefront API 走 /api/storefront/*（Public Token 鉴权，对应 Shopify 的 Storefront Access Token）
• Shopify 的 Metafields → 通用 apps/metafields/，所有主业务模型 mixin HasMetafieldsMixin，以 JSONB 列存储 + schema 校验
• Shopify 的 Functions / Flow → 用 apps/discounts + services/script_engine.py 实现基于 Python 的可执行折扣/运费/税脚本（受控沙箱，禁用 import）

第 3 章 功能模块总览¶

按业务对象划分共 17 个一级模块，每个模块下若干功能点（FP，Function Point）。

优先级说明：P0 = MVP 必须具备；P1 = 首个大版本必须具备；P2 = 后续迭代。

每个功能模块的章节统一格式：
1. 业务目标
2. 角色与流程
3. 功能点清单（按 FR 编号）
4. 关键业务规则
5. 数据要点
6. 接口要点（Admin / Storefront / Webhook）
7. Shopify 对标说明
8. 验收要点

第 4 章 商品与目录管理¶

4.1 业务目标¶

对标 Shopify 的 Products / Variants / Collections / Inventory / Metafields，提供从商品建模、多属性管理、商品分组、自动集合规则到自定义字段扩展的完整能力，支撑实物 / 数字 / 服务三类商品。

4.2 角色与流程¶

• 商品编辑员：建商品、配变体、配图、配元字段、配 SEO
• 商品管理员：批量上下架、调价、归类、调库存
• 主题开发者：通过 sections 渲染商品数据
• 客户：浏览、搜索、加入购物车

关键流程示例：商品创建→变体生成→库存初始化→上架

编辑员新建 Product (draft)
  ↓ 配置 Option（颜色/尺码）→ 自动生成 Variant 笛卡尔积
  ↓ 为每个 Variant 维护 SKU / Barcode / Price / Weight / Inventory Policy
  ↓ 绑定 Image（多图，可设主图）
  ↓ 加入 Collection 或建立自动集合规则
  ↓ 设置 Status = active → 商城可见

4.3 功能点清单¶

4.3.1 商品（Product）¶

4.3.2 变体（Variant）¶

4.3.3 收藏/集合（Collection）¶

4.3.4 元字段与元对象（Metafield / Metaobject）¶

4.4 关键业务规则¶

• R-4.1：商品至少一个变体，且变体价格、库存策略均可独立设置。删除父商品须级联归档所有变体，不物理删除（保留 90 天软删除以兼容历史订单）。
• R-4.2：Handle 在店铺内唯一，自动根据标题生成（中文走 pinyin slugify 或拼音首字母），手动改后保留 301 重定向至新 handle。
• R-4.3：自动集合规则匹配采用”快照+定时刷新”双策略——保存即时快照匹配一次，之后每 15 分钟由 Celery 周期重算一次以保证新上架商品被收录。
• R-4.4：变体数 > 1000 时禁止前端”加载全部变体”，须改为按选项展开懒加载（与 Shopify 后台一致）。
• R-4.5：商品图片上传单文件默认上限 20MB，超过自动 WebP 转码并保留原图链接。SVG 须校验无 <script>。
• R-4.6：Metafield 删除时记录 deleted_metafield 审计表，便于回滚。
• R-4.7：商品库存可见性 = is_published AND status='active' AND inventory_policy != 'deny' OR inventory > 0，三重判断。

4.5 数据要点¶

Product、ProductVariant、Collection、CollectionProduct（排序表）、Image、Metafield 等。详见 第 18 章 数据模型设计。关键约束：

• Product.handle 联合 shop_id 唯一索引
• ProductVariant.sku 联合 shop_id 唯一索引（可配置为可空非唯一）
• CollectionProduct 用 (collection_id, product_id, position) 复合索引支撑分页与排序
• Metafield.owner_type + owner_id + namespace + key 组合唯一
• 商品搜索：Product.search_vector（PostgreSQL tsvector + GIN 索引，由 title/tags/description 拼接构建）

4.6 接口要点¶

Admin API（REST）¶

Storefront API（GraphQL，对标 Shopify Storefront）¶

query productByHandle($handle: String!) {
  productByHandle(handle: $handle) {
    id title description handle
    featuredImage { url altText width height }
    images(first: 20) { edges { node { url altText } } }
    variants(first: 50) {
      edges { node { id title sku priceV2 { amount currencyCode }
        availableForSale selectedOptions { name value } } }
    }
    options { id name values }
    metafields(namespace: "custom") { edges { node { key value } } }
  }
}

Webhook 事件¶

4.7 Shopify 对标说明¶

• 字段粒度上完整对齐 Shopify Product / ProductVariant / Collection / Image / Metafield 模型
• automatic collection 规则引擎实现 Shopify 的 5 类条件 + AND/OR 组合
• template_suffix 等同 Shopify 的”模板后缀”机制
• 缺省不实现的 Shopify 功能：Product.media（视频/3D 模型），标注为 P2 后续迭代
• Product.quoted_price、priceV2 等价格对象对标 Storefront API 的多币种价格结构

4.8 验收要点¶

• [ ] 单个商品 100 个变体在管理后台可在 1.5s 内完成列表渲染
• [ ] 删除商品后历史订单仍可查询到SKU 与商品名（软删除生效）
• [ ] 自动集合规则修改后 15 分钟内新匹配商品可见
• [ ] Metafield PRIVATE 类型不出现在 Storefront API 响应中
• [ ] 商品搜索 1 万商品库下 p95 < 200ms

第 5 章 库存与履约¶

5.1 业务目标¶

对标 Shopify Inventory Locations / Inventory Levels / Inventory Adjust / Fulfillment / FulfillmentService，提供多仓多库位的库存跟踪、调拨、出库履约。

5.2 角色与流程¶

• 库存管理员：建库位、调拨、盘点
• 履约运营：订单分仓、生成发货单、对接物流
• 系统自动：库存阈值告警、超卖拦截、跨库位分配

订单支付完成 → inventory engine 按"就近+充足"算法选库位 → 锁库存 →
履约：拣货 → 包装 → 称重 → 生成物流面单 → 发出 → 库存递减 →
完成履约，订单状态进入 shipped

5.3 功能点清单¶

5.3.1 库位（Location）¶

5.3.2 库存数量与变动¶

5.3.3 履约（Fulfillment）¶

5.4 关键业务规则¶

• R-5.1：库存 = available（可售）+ committed（预留/已售未发）+ incoming（在途）；available 是前端可见可购买的库存，不允许超卖除非 inventory_policy=continue 或 oversell。
• R-5.2：跨库位库存同步必须使用 Redis 分布式锁防并发扣减竞争。
• R-5.3：退货入库必须走人工审核，自动入库仅限未发出的履约取消。
• R-5.4：库位发货能力受限于店铺设置：商家可指定仅某些库位对外发货。
• R-5.5：每个 SKU 在每个库位保留独立的安全库存，触发阈值告警必须包含库位名、当前库存、阈值、商品名/SKU。

5.5 数据要点¶

Location / InventoryLevel / InventoryAdjustment / InventoryEvent / FulfillmentOrder / Fulfillment / FulfillmentEvent。详细字段见第 18 章。

5.6 接口要点¶

Admin API¶

Storefront API¶

query variantAvailability($id: ID!) {
  node(id: $id) {
    ... on ProductVariant { availableForSale quantityAvailable }
  }
}

Webhook 事件¶

• inventory_levels/update
• fulfillment_orders/create、/fulfilled、/cancelled
• fulfillments/create、/update

5.7 Shopify 对标说明¶

• 完整对齐 Shopify 的 Location / InventoryLevel / InventoryAdjustment / FulfillmentOrder / Fulfillment 抽象
• quantity_available 字段定义、committed/incoming 三态语义复用 Shopify Inventory API 1:1
• 缺省不实现 Shopify 配套的”FulfillmentService 应用市场”机制，仅支持本地配置的履约服务

5.8 验收要点¶

• [ ] 100 并发下单同一 SKU 不出现超卖（基于行级锁 + Redis 锁双保障）
• [ ] 库存调整日志可追溯到操作员、时间、原因、前后值
• [ ] 部分履约后的订单状态与库存数据自洽
• [ ] 物流轨迹自动拉取，缓存 30 分钟，超时回源

第 6 章 购物车与结账¶

6.1 业务目标¶

对标 Shopify Cart API + Checkout（结合 Checkout Extensibility），实现商品入车、改数量、加备注、估算运费税额，最终生成订单前完整的地址+运费+税额+支付方式选择会话。

6.2 角色与流程¶

• 客户：访问商城 → 加购物车 → 进入结账 → 填地址 → 选运费 → 选支付 → 完成下单
• 系统自动：结账会话创建后倒计时 30 分钟，过期清空预留库存

核心状态机：

[GUEST/LOGGED_IN]
   ↓ add-to-cart
[CART] ── 持久化 (Session + DB 行)
   ↓ enter-checkout (校验商品 still for_sale)
[CHECKOUT_SESSION]  预留库存 5~15 分钟
   ↓ submit_shipping_address
[SHIPPING_VALIDATED]
   ↓ select_shipping_rate
[RATES_LOCKED]
   ↓ submit_payment_intent
[PAYMENT_AUTHED]
   ↓ complete (原子事务)
[ORDER_CREATED] → release/persist reserved stock

6.3 功能点清单¶

6.3.1 购物车（Cart）¶

6.3.2 结账会话（Checkout Session）¶

6.4 关键业务规则¶

• R-6.1：购物车中已下架 / 断货变体加入购物车时返回”无法购买”提示并保留其他项；进入结账时强制重新校验，不通过则回退购物车并提示。
• R-6.2：结账会话 5 分钟无操作释放库存预留；保留 30 分钟内可继续（地址等已填信息不变）。
• R-6.3：运费 rate 列表必须包含”运费金额+预估时效（天）+承运商名+是否免税”四要素。
• R-6.4：税额由 apps/tax 集中计算，单一来源；前端任何展示都必须来自 tax_lines 字段。
• R-6.5：当 inventory_policy=deny 且库存不足时，结账前调整数量并提示客户。
• R-6.6：完成结账用 transaction.atomic() 包裹：”建订单 → 锁定 line_items → 扣减库存 → 记录 payment_intent”。任一步骤异常整体回滚。
• R-6.7：放弃结账挽回邮件默认 1 小时 + 24 小时各一封，模板可配；同一 checkout_token 不重复发送。
• R-6.8：商家可后台查询”放弃结账”列表，手动重发挽回邮件或一键创建草稿订单。

6.5 数据要点¶

• Cart / CartItem（line item 的购物车态）
• CheckoutSession：状态 IN_PROGRESS / COMPLETED / EXPIRED，记录快照化字段（避免后续商品价格变化导致金额混乱）
• CheckoutAddress（收件/账单）
• CheckoutShippingRate（rate 快照，含金额、时效、承运商 ID）
• CheckoutTaxLine（每行税目）
• AbandonedCheckout：checkout_token + email + created_at + abandoned_at + line_items_snapshot

6.6 接口要点¶

Storefront API（Cart / Checkout，对标 Shopify Storefront Cart）¶

mutation cartCreate($input: CartInput!) {
  cartCreate(input: $input) {
    cart { id totalQuantity cost { totalAmount { amount currencyCode } }
      lines(first: 50) { edges { node { id quantity merchandise { ... on ProductVariant { id sku } } } } } }
  }
}
mutation cartLinesAdd / cartLinesUpdate / cartLinesRemove
mutation checkoutCreate($input: CheckoutCreateInput!)
mutation checkoutShippingAddressUpdateV2
mutation checkoutShippingLineUpdate

Admin API¶

Webhook¶

• carts/create、carts/update（仅 API 购物车）
• checkouts/create、checkouts/update、checkouts/delete
• abandoned_checkouts/create

6.7 Shopify 对标说明¶

• 完全采用 Shopify 的 Cart + Checkout 拆分：Cart 是无身份会话态，Checkout 是产生 Order 必经的”已分配库存且校验通过”过渡态
• Checkout Extensibility 通过 apps/checkout/extensions.py 加插件机制实现（hooks: address_step、shipping_step、payment_step、summary_widget、thank_you_page），与 Shopify 的 UI Extensions 语义对齐
• 实现 Web Pixel 接口：可注册 Pixel 监听 add_to_cart / begin_checkout / add_payment_info / purchase 等事件

6.8 验收要点¶

• [ ] 50 并发同一变体加购物车，库存不超卖
• [ ] 结账会话过期机制 5 分钟内不可下单（释放后再次完成会重派库存）
• [ ] 运费 rate 改变后前端实时校准
• [ ] 支付完成原子性：支付凭证与订单 1:1，无孤立支付凭证

第 7 章 订单管理¶

7.1 业务目标¶

对标 Shopify Order / Draft Order / Refund / Return / Cancel / Order Edit，提供完整订单生命周期管理。

7.2 角色与流程¶

• 客户：下单 → 查订单 → 申请退款/退货
• 客服：编辑订单、改地址、退款、换货、手动改状态
• 仓库：履约（详见第 5 章）
• 系统：订单状态机自动推进

订单状态机（financial_status × fulfillment_status）：

financial_status:
  pending → authorized → paid → partially_paid → refunded → partially_refunded → voided

fulfillment_status:
  null → unfulfilled → partial → fulfilled → restocked

order status:
  open → closed (90 天自动 closed) / cancelled

7.3 功能点清单¶

7.3.1 订单基本信息¶

7.3.2 订单状态流转¶

7.3.3 退款与退货¶

7.3.4 草稿订单¶

7.4 关键业务规则¶

• R-7.1：所有金额以”最小货币单位 ×10^decimal_places”整数保存（防浮点），与 Shopify cents 模型一致。
• R-7.2：取消订单产生 cancel_reason 与 cancelled_at，触发 orders/cancelled webhook。
• R-7.3：line_items 在订单生成时深度快照，原商品/变体删除不影响已存订单查询。
• R-7.4：order_edit 产生新版本，旧版本可查询；编辑差额生成 OrderAdjustment。
• R-7.5：退款必须遵循”先发支付再退款”原则，未付款订单不存在退款。
• R-7.6：自动同步 tags 至客户记录（如 wholesale），便于后续营销分群。

7.5 数据要点¶

• Order / OrderLineItem / OrderAddress（收件 + 账单）/ OrderShippingLine / OrderTaxLine / OrderAdjustment / Refund / RefundLineItem / Return / DraftOrder / DraftOrderLineItem
• 订单按月分区表 orders_2026_07，历史归档冷库

7.6 接口要点¶

Admin API¶

Storefront API（客户订单查询）¶

query customerOrders {
  customer {
    orders(first: 20) {
      edges { node { orderNumber processedAt fulfillments(first: 5) {
        edges { node { trackingInfo { number url } } } }
        totalPrice { amount currencyCode } } }
    }
  }
}

Webhook¶

• orders/create、orders/updated、orders/paid、orders/cancelled、orders/fulfilled、orders/partially_fulfilled、orders/deleted
• refunds/create
• draft_orders/create、draft_orders/update、draft_orders/delete

7.7 Shopify 对标说明¶

• 订单字段、状态、退款结构 1:1 对齐 Shopify Order REST API
• DraftOrder 与 Shopify 行为完全一致（先草稿后客户付款链接）
• Order Edit 机制对标 Shopify 2022 起开放的 editing API
• Return 流程对标 Shopify Returns API（含 RMA）

7.8 验收要点¶

• [ ] 已下单商品删除后订单查询历史价/名 SKU 无损
• [ ] 部分退款再部分退款，最终退款金额不超过订单实付
• [ ] 取消订单后库存正确归还
• [ ] 草稿订单付款邮件链接 24 小时有效

第 8 章 支付与结算¶

8.1 业务目标¶

对标 Shopify Payments / 第三方支付网关 / 礼品卡 / 支付网关适配层，提供统一的支付意图管理、清算对账、防欺诈。

8.2 角色与流程¶

• 客户：选支付方式 → 跳转网关 or 站内支付 → 回跳确认
• 系统：支付意图 → 凭证上链 → 订单状态推进
• 财务：日终对账

CheckoutSession → 创建 PaymentIntent（多条候选支付方式）
   ↓ 选定方式
[EXTERNAL_AUTH] 第三方托管 / iframe 内嵌
   ↓ 用户完成授权
[AUTHORIZED] payment_id 返回 + 3DS 校验通过
   ↓ capture（即时/延后）
[CAPTURED] 财务 paid
   ↓ 对账日终核对
[RECONCILED]

8.3 功能点清单¶

8.3.1 支付意图与凭证¶

8.3.2 支付网关适配¶

8.3.3 礼品卡¶

8.3.4 对账与防欺诈¶

8.4 关键业务规则¶

• R-8.1：所有支付凭证必须可凭 (shop_id, transaction_id) 唯一定位；网关侧 ID 与本地 transaction_id 双向存储。
• R-8.2：金额必须以”整数最小货币单位”在前后端流转，仅在展示时按 currency.decimal_places 格式化。
• R-8.3：退款金额累计不得超过实付金额；礼品卡退款不可超过原核销金额。
• R-8.4：网关响应原文保留 90 天后归档冷库。
• R-8.5：所有 capture 失败必须有 failure_code + failure_message + next_retry_at 三元日志。

8.5 数据要点¶

• PaymentIntent、PaymentTransaction（authorize / capture / void / refund 各一笔）、GiftCard、GiftCardTransaction、ReconciliationReport、ReconciliationLine、FraudFlag
• 敏感字段（卡号、CVV）不入库；仅存 masked_pan（4242****4242）

8.6 接口要点¶

Admin API¶

Storefront API¶

mutation checkoutCompleteWithCreditCardV2
mutation checkoutGiftCardApply
mutation giftCardCredit

Webhook¶

• payment_intent/payment_failed、payment_intent/payment_authorized、payment_intent/payment_captured
• gift_cards/create、/update

8.7 Shopify 对标说明¶

• 抽象层与 Shopify Transaction API 字段（kind = authorization / capture / sale / void / refund）一一对齐
• 礼品卡对标 Shopify GiftCard 资源（含 balance、initial_value、currency、code、disabled_at）
• Shop Pay 不实现，用”快捷钱包”插件抽象留扩展位

8.8 验收要点¶

• [ ] 同卡同金额两个相同请求只生成一笔支付凭证
• [ ] 网关失败重试不超过 3 次，且单笔订单 24 小时内最多 10 次
• [ ] 对账任务异常自动告警，财务人员在 24h 内确认
• [ ] 敏感字段（如卡号）一律不入库

第 9 章 客户与会员体系¶

9.1 业务目标¶

对标 Shopify Customer / Customer Address / Customer Saved Search / Customer Group / Customer Tags / Customer Metafields，提供客户档案、地址簿、客户分群、消费历史、积分会员成长体系。

9.2 角色与流程¶

• 客户：访问商城 → 注册/游客下单 → 自动建档 → 查询订单/地址 → 申请退货
• 客服：合并/拆分客户档案、调标签、发分群邮件
• 营销：基于分群发起新一批营销活动

9.3 功能点清单¶

9.3.1 客户档案¶

9.3.2 地址簿¶

9.3.3 客户分群¶

9.3.4 会员等级与积分¶

9.4 关键业务规则¶

• R-9.1：客户唯一性 = shop + email 或 shop + phone（phone 仅在主短信登录场景作为唯一键）
• R-9.2：客户合并必须经财务/合规确认；订单归属变更需记录 customer_merge_audit
• R-9.3：积分有效期由”获赠日期 + 店铺设置”决定；过期日 Cron 自动清零并记录
• R-9.4：会员等级每次订单完成后即时判定，但降级延迟生效（保护客户体验）
• R-9.5：删除客户时其订单保留为 guest_order，仅客户可识别信息脱敏

9.5 数据要点¶

• Customer、CustomerAddress、CustomerMetafield、CustomerSegment、CustomerSegmentMember、CustomerSavedSearch、MembershipTier、PointLedger、CustomerMergeAudit
• Customer.summary 字段（last_order_at、orders_count、total_spent）由 Celery 任务异步更新

9.6 接口要点¶

Storefront API¶

query customer {
  customer { id displayName email firstName lastName defaultAddress { ... }
    orders(first: 10) { edges { node { orderNumber } } } }
}

Webhook¶

• customers/create、customers/update、customers/delete、customers/merge、customers/disable、customers/enable

9.7 Shopify 对标说明¶

• Customer 主表字段与 Shopify 一致；Segment 模块对标 Shopify Audiences（静态+动态）
• 客户合并是 Shopify Plus 增强，本系统完整实现以适应中国市场对客档合并的强需求
• 引入 Shopify 未提供的会员等级/积分体系（中国市场标配）

9.8 验收要点¶

• [ ] 同 email 在 30 秒内连续两次游客下单只生成一个客户档案
• [ ] 客户合并后订单历史可追溯
• [ ] GDPR 删除 14 天后真实删除验证

第 10 章 折扣、优惠与促销¶

10.1 业务目标¶

对标 Shopify DiscountCode / AutomaticDiscount / PriceRule，提供折扣码、自动折扣、限时活动、买赠、阶梯优惠、组合购物优惠、可编程折扣函数。

10.2 角色与流程¶

• 营销：定义 PriceRule → 生成 Discount Code（批量）或 Automatic Discount
• 客户：结账输入折扣码 / 自动应用满足条件的折扣
• 系统：折扣引擎在结账阶段计算并分摊至 line_items

10.3 功能点清单¶

10.3.1 Price Rule（规则）¶

10.3.2 Discount Code（折扣码）¶

10.3.3 Automatic Discount（自动折扣）¶

10.3.4 可编程折扣函数（Discount Functions，对标 Shopify Functions）¶

10.4 关键业务规则¶

• R-10.1：折扣金额不可超过 line_item 小计；免运费仅作用于已选定 shipping_line
• R-10.2：折扣分摊按”价格比例”分配至各 line_item，写入 discount_allocations，便于按行退款
• R-10.3：折扣与已应用礼品卡的优先级：先礼品卡再折扣码、再自动折扣
• R-10.4：折扣码使用日志 discount_usage 表记录 code/rule/cart_snapshot/customer/order_id，用于审计
• R-10.5：自动折扣与折扣码冲突时，按 rule 配置选择”最大优惠” or “禁用”

10.5 数据要点¶

• PriceRule、DiscountCode、AutomaticDiscount、DiscountUsage、DiscountAllocation（写在 order_line_item 上）、DiscountScript、DiscountScriptVersion、DiscountScriptRun

10.6 接口要点¶

Storefront API¶

mutation checkoutDiscountCodeApplyV2($discountCode: String!)
query discountByCode($code: String!) { discountByCode(code: $code) { ... } }

Webhook¶

• discounts/create、discounts/delete、discounts/redeem

10.7 Shopify 对标说明¶

• 字段完全对齐 Shopify PriceRule + DiscountCode + AutomaticDiscount
• Discount Functions 用 RestrictedPython 复刻 Shopify Functions 思路（WASM/Rust 不引入）
• 不可叠加策略支持 Shopify 全部场景

10.8 验收要点¶

• [ ] 折扣分摊后所有 line_item 折扣金额之和等于折扣总金额
• [ ] 折扣码达到使用上限后立即失效
• [ ] 折扣脚本性能 < 100ms，超时降级

第 11 章 营销与触达¶

11.1 业务目标¶

对标 Shopify Email / SMS / Marketing Campaign / Audience / Automation，提供邮件 / 短信 / 站内信多渠道营销、活动效果归因、自动化工作流。

11.2 角色与流程¶

• 营销：选目标分群 → 设计邮件 → 设置发送时间 → 发送 → 监控效果
• 系统：弃单挽回 / 生日问候 / 库存到货提醒等场景化自动化触发

11.3 功能点清单¶

11.3.1 模板编辑¶

11.3.2 活动与发送¶

11.3.3 自动化工作流¶

11.3.4 营销归因¶

11.4 关键业务规则¶

• R-11.1：所有营销触达必须基于 accepts_marketing=True 客户；交易性邮件（订单确认、退款）不受此限制
• R-11.2：硬弹邮件地址自动加入 email_suppression 表永不重发；软弹 3 次后加入
• R-11.3：自动化工作流执行使用 Celery + 编排引擎（轻量状态机），单客户同一工作流不并发
• R-11.4：营销效果统计延迟 1 小时聚合，未触达实时告警

11.5 数据要点¶

• EmailTemplate / SmsTemplate / Campaign / CampaignSend（单客户单发送）/ Automation / AutomationStep / AutomationEnrollment / MarketingAttribution / EmailSuppression

11.6 接口要点¶

Webhook¶

• marketing/campaign_sent、marketing/email_delivered、marketing/email_opened、marketing/email_clicked

11.7 Shopify 对标说明¶

• Shopify Email + Shopify Audiences + Shopify Automation 三合一，对标其字段与触发器
• 自动化工作流节点设计基于 Shopify Flow 的 Trigger / Condition / Action 三段式
• 与外部 ESP（如 Mailchimp / Klaviyo / 阿里云 DM）可通过 webhook + API 实现对接

11.8 验收要点¶

• [ ] 退订链接点击后立即更新客户档案，30 分内不再发送
• [ ] 硬弹地址永不重发
• [ ] 自动化工作流并发数稳定（同客户不重复触发）

第 12 章 数据分析与报表¶

12.1 业务目标¶

对标 Shopify Analytics / Live View / Reports / Cohorts / LTV，提供实时业务看板、销售分析、客户行为分析、可自定义报表。

12.2 角色与流程¶

• 老板/CEO：每日看核心 KPI、Live View、经营趋势
• 营销：分析活动 ROI、分群表现
• 运营：分析品类、渠道、退货率
• 财务：导出对账与税务报表

12.3 功能点清单¶

12.3.1 实时看板（Live View）¶

12.3.2 销售报表¶

12.3.3 客户分析¶

12.3.4 转化漏斗¶

12.3.5 自定义报表¶

12.4 关键业务规则¶

• R-12.1：报表数据来自专用 ETL（每晚从 OLTP 同步至 OLAP，Postgres 可用 crosstab / 物化视图或独立 DuckDB）
• R-12.2：所有金额按订单时点币种与汇率折算
• R-12.3：退款与售后金额以负数计入销售维度
• R-12.4：实时看板允许 ±5% 误差（异步聚合），日报/月报必须 100% 精确

12.5 数据要点¶

• 物化视图：mv_order_daily、mv_customer_cohort、mv_product_sales_monthly
• 报表元数据：Report / ReportColumn / ReportFilter / ReportSchedule、ReportSnapshot
• 实时计数器：Redis 自增键 + SETEX TTL

12.6 接口要点¶

Webhook¶

• reports/export_completed

12.7 Shopify 对标说明¶

• 完整覆盖 Shopify Analytics 五大块：Live View、Sales、Customer、Conversion、Reports
• 引入 RFM / Cohort / LTV 三种中国市场习惯的分析模型
• 自定义报表对标 Shopify Custom Reports

12.8 验收要点¶

• [ ] 实时看板数据延迟 ≤ 5 秒
• [ ] 月报数据与财务对账误差 0
• [ ] 自定义报表可在 10s 内返回结果

第 13 章 主题与模板系统¶

13.1 业务目标¶

对标 Shopify Online Store 2.0 的 sections + blocks + JSON templates + theme settings 架构，提供可视化拖拽的主题编辑器、模板文件系统和主题资源管理，让商家在不改代码前提下完整定制店铺外观。

13.2 角色与流程¶

• 主题开发者：通过本地开发工具链开发并打包 .zip 主题包
• 商家：上传主题 → 选择模板 → 在 sections 中添加/移动 blocks → 实时预览 → 发布
• 前端访客：访问店铺 → Django 模板引擎按 “Liquid-like” 渲染

主题目录结构（复刻 Shopify 2.0）：

my-theme/
├── assets/         # CSS/JS/图片等静态资源
├── config/         # settings_schema.json + settings_data.json
├── layout/         # theme.liquid 主布局
├── locales/        # en.default.json / zh.json 多语言
├── sections/       # 可复用的 section（含 schema）
│   ├── header.liquid
│   ├── product-card.liquid
│   └── ...
├── snippets/       # 可复用片段
└── templates/
    ├── index.liquid          # 首页
    ├── product.liquid / product.<suffix>.liquid
    ├── collection.liquid / collection.<suffix>.liquid
    ├── cart.liquid
    ├── page.liquid / page.<suffix>.liquid
    ├── blog.liquid
    ├── article.liquid
    ├── list-collections.liquid
    ├── 404.liquid
    ├── password.liquid
    ├── search.liquid
    ├── gift_card.liquid
    ├── customers/
    │   ├── account.liquid
    │   ├── login.liquid
    │   ├── register.liquid
    │   ├── order.liquid
    │   ├── addresses.liquid
    │   └── reset_password.liquid
    └── *.json                # 模板配置（持久化 section 顺序与 block 实例）

13.3 功能点清单¶

13.3.1 主题管理¶

13.3.2 Sections 与 Blocks（核心）¶

13.3.3 JSON Templates¶

13.3.4 主题设置（Theme Settings）¶

13.3.5 主题渲染引擎¶

13.3.6 资源 URL 生成¶

13.4 关键业务规则¶

• R-13.1：schema 校验不通过的 section 不会被加载，且在主题编辑器中置灰；模板 JSON 必须能通过 schema 校验
• R-13.2：所有渲染基于”已发布主题 + 当前模板 JSON”，未发布预览主题需 ?preview_token=xxx
• R-13.3：模板编译错误必须降级到”简化 error page”，绝不向访客暴露 500
• R-13.4：theme settings 的图片必须落到店铺的 CDN bucket，禁止外链图片
• R-13.5：Liquid 模板执行时长上限 500ms，超时降级到 cached HTML

13.5 数据要点¶

• Theme（name/version/status/active_at/preview_token）
• ThemeAsset（path/type/content/checksum）
• ThemeTemplate（template_type/handle/json_content）
• ThemeSettings（theme_id + value JSON）
• 资源静态文件落对象存储

13.6 接口要点¶

第 14 章 页面、博客与内容¶

14.1 业务目标¶

对标 Shopify Pages / Blogs / Articles / Menus / Navigation，提供企业页面（关于我们/联系/政策）、博客内容、店铺导航菜单管理。

14.2 功能点清单¶

14.3 业务规则¶

• R-14.1：page/article 的 handle 在店铺内唯一；修改保留 301 redirect
• R-14.2：博客发布文章采用 future-dated 调度（Celery Beat 按时发布）
• R-14.3：私密页面访问需密码或登录

14.4 数据要点¶

Page / Blog / Article / ArticleComment / Menu / MenuItem（自引用实现层级）

14.5 接口¶

第 15 章 SEO 与域名¶

15.1 业务目标¶

对标 Shopify 的内置 SEO（meta 标签、URL handle、canonical、redirect、sitemap、robots.txt）与多域名绑定能力。

15.2 功能点清单¶

15.3 数据要点¶

SeoTemplate（按类型组合模板如 {{product.title}} - {{shop.name}}）、Redirect（from_path/to_path/status/priority）、DomainBinding

第 16 章 多渠道销售¶

16.1 业务目标¶

对标 Shopify Sales Channels（Online Store、POS、Manual、Facebook/Instagram、Google、TikTok、Wholesale 等），抽象统一的渠道适配层，让同一商品池与订单池服务多渠道。

16.2 功能点清单¶

16.3 业务规则¶

• R-16.1：每个订单必有 channel_id；缺省 = Online Store
• R-16.2：渠道适配失败不应阻塞主订单流程，回退到 manual，留日志
• R-16.3：产品目录与外部平台同步频率可配置（默认 1 小时）

16.4 数据要点¶

Channel / ChannelProduct（商品配置覆盖）/ ChannelAdapter / ChannelSyncLog

第 17 章 权限、多语言与税务¶

17.1 权限与多账号¶

17.2 多语言与多币种（Markets 对标）¶

17.3 税务¶

17.4 业务规则¶

• R-17.1：所有面向客户的字段变更走”翻译工作流”流程；非默认语言缺省回退默认语言
• R-17.2：税率以结算时点为准；订单 line_item tax_lines 快照锁定
• R-17.3：员工删除/降权需 Owner 同意审签
• R-17.4：API Token 不可读取 owner 与 staff 完整列表，避免越权

第 18 章 核心数据模型设计¶

18.1 设计约定¶

• 所有业务表继承 core.models.TimeStampedOwnerModel，包含统一字段：id (BigAutoField)、shop_id (FK)、created_at、updated_at、deleted_at（软删除，默认 NULL）
• 金额一律存 整数最小货币单位（如人民币：分）；展示时按 Shop.currency.decimal_places 格式化
• 所有”国际化名称”字段使用 django-modeltranslation 注册翻译，DB 多列 name_en / name_zh 自动生成
• 所有”对外 ID”用 gid://shop/<Type>/<numeric_id> 格式（对标 Shopify GraphQL Global ID），Admin/Storefront API 输出统一转 base64
• 多租户预留：所有表带 shop_id，单店铺部署写在配置 DEFAULT_SHOP_ID
• 使用枚举：枚举值定义在 core/enums.py，模型字段统一用 django-enumchoice 或自定义 CharField + choices

18.2 店铺与基础设施¶

Shop¶

Location¶

StaffAccount、StaffRole、Permission¶

• StaffAccount.user FK → auth.User；shop FK；role FK
• StaffRole 预设记录：owner/admin/manager/staff/developer
• Permission 表 (role_id, module, action, scope)：action ∈ read/create/update/delete/refund；scope ∈ all/owned/warehouse

18.3 商品与目录¶

Product¶

索引：(shop_id, handle) unique、(shop_id, status)、search_vector GIN

ProductVariant¶

索引：(shop_id, sku)、(product_id, position)

Image（商品图）¶

shop, product(FK), variant(FK nullable), src(url), alt, width, height, position ；图片实体存 S3

Collection¶

shop, title, body_html, handle, sort_order(char Enum: manual/best_selling/...), disjunctive(bool: True=OR, False=AND), rules(JSONArray of {column, relation, condition}), template_suffix, published_at, image(FK)

CollectionProduct¶

collection(FK), product(FK), position(Integer)，索引 (collection_id, product_id) unique, (collection_id, position)

Metafield、Metaobject¶

• Metafield: shop, owner_type, owner_id, namespace, key, value(JSON), type(CharField Enum), description, is_public(Boolean)
• Metaobject: shop, type(CharField), handle, fields(JSONField: {name: value}), display_name
• MetaobjectDefinition: shop, name, type, field_definitions(JSONArray)

18.4 库存与履约¶

InventoryLevel¶

唯一索引 (variant_id, location_id)

InventoryAdjustment¶

id, variant(FK), location(FK), delta(Integer), previous_available, after_available, reason(Enum: correction/cycle_count/received/cancelled_order/return), note, staff(FK nullable), created_at

InventoryEvent¶

不可变事件表：event_type(Enum), variant_id, location_id, delta, source(refund_id/order_id/...), created_at

FulfillmentOrder、Fulfillment¶

• FulfillmentOrder: order(FK), location(FK), status(unfulfilled/in_progress/on_hold/cancelled), assigned_location.location, line_items(JSON of order_line_item ids + quantity), fulfill_at, deadline
• Fulfillment: fulfillment_order(FK), status(open/success/cancelled/error), tracking_company, tracking_number, tracking_url, receipt(JSON), notify_customer, created_at

18.5 购物车与结账¶

Cart、CartLine¶

• Cart: shop, customer(FK nullable), token(UUID UNIQUE), note, attributes(JSON), created_at, updated_at, expires_at
• CartLine: cart(FK), variant(FK), quantity, properties(JSON), attributes(JSON)；唯一索引 (cart_id, variant_id)

CheckoutSession¶

shop, customer(FK), cart(FK), token(UUID UNIQUE),
status(Enum: in_progress/completed/expired),
shipping_address(JSON), billing_address(JSON),
shipping_rate(JSON snapshot), tax_lines(JSON),
discount_codes(Array), gift_cards(Array),
total_price, total_tax, total_shipping, total_discount,
payment_provider(CharField),
expires_at, completed_at, abandoned_at

AbandonedCheckout¶

shop, checkout_session(FK), email, line_items_snapshot(JSON), created_at, abandoned_at, recovery_email_sent_at

18.6 订单¶

Order¶

按月分区 pg_partman：orders_YYYY_MM

OrderLineItem¶

order(FK), variant_id_snapshot, sku_snapshot, title, variant_title, quantity, price(price_each), total_discount, tax_lines(JSON), discount_allocations(JSON), requires_shipping, taxable, fulfillment_status, fulfillable_quantity, properties(JSON), position

OrderShippingLine、OrderTaxLine¶

• ShippingLine: order(FK), title, code, price, tax_lines(JSON), carrier_identifier, requested_fulfillment_service_id
• TaxLine: order(FK), price, rate, title, channel

OrderAdjustment、Refund、RefundLineItem、Return、DraftOrder¶

• OrderAdjustment: order(FK), amount, kind(order_edit/discount/refund_diff), note
• Refund: order(FK), created_at, note, restock, amount, transactions(GenericRelation), refund_line_items
• RefundLineItem: refund(FK), line_item(FK), quantity, restock_type, subtotal, total_tax, subtotal_set
• Return: order(FK), status(requested/approved/received/cancelled), line_items(JSON), restocking_fee
• DraftOrder: shop, customer(FK nullable), line_items, shipping_address, billing_address, total, invoice_url, status(open/invoice_sent/completed), completed_at

18.7 支付¶

PaymentIntent¶

shop, order(FK nullable), checkout_session(FK nullable), amount, currency, status(None/requires_payment_method/requires_confirmation/requires_action/processing/requires_capture/canceled/succeeded), provider, provider_data(JSON), metadata(JSON), created_at

PaymentTransaction¶

payment_intent(FK), kind(Enum: authorization/capture/sale/void/refund), gateway, amount, currency, status(success/pending/failure/error), provider_transaction_id, failure_code, failure_message, response_raw(JSON), masked_pan, created_at

GiftCard¶

shop, code(CharField UNIQUE), initial_value, balance, currency, customer_id(FK nullable), disabled_at, expires_on, note, template_suffix

GiftCardTransaction¶

gift_card(FK), order(FK nullable), amount, action(Enum: debit/credit/expire), created_at

18.8 客户与会员¶

Customer¶

shop, first_name, last_name, email, phone, accepts_marketing, accepts_marketing_updated_at, marketing_opt_in_level, note, tags, last_order_at, orders_count, total_spent,verified_email, state(enabled/disabled/invited/declined), tax_exempt, tax_exemptions(Array), currency, default_address(FK nullable), created_at, updated_at, deleted_at(软删除时 email 改为 deleted_<id>@removed.local)

唯一索引 (shop_id, email)；(shop_id, phone) 软唯一

CustomerAddress¶

customer(FK), first_name, last_name, company, address1, address2, city, province, province_code, zip, country, country_code, phone, default(Boolean)

CustomerSegment、CustomerSegmentMember¶

• CustomerSegment: shop, name, kind(static/dynamic/saved_search), definition(JSON rule expression), last_evaluated_at
• CustomerSegmentMember: segment(FK), customer(FK), joined_at
• 动态分群由 Celery Beat 每日重算

MembershipTier、PointLedger¶

• MembershipTier: shop, name, threshold_amount, multiplier(Decimal), benefits(JSON), active
• PointLedger: customer(FK), action(earn/spend/expire/adjust), delta, balance_after, expires_on, ref(order_id/coupon_id), note, created_at

18.9 折扣¶

PriceRule¶

shop, title, target_type(line_item/shipping_line), target_selection(all/entitled),
allocation_method(each/across), value_type(fixed_amount/percentage),
value, once_per_customer(Boolean), usage_limit(Integer nullable),
once_per_order(Boolean), starts_at, ends_at, prerequisite_subtotal_range,
prerequisite_quantity, prerequisite_to_entitlement_quantity_ratio(JSON),
entitled_product_ids, entitled_collection_ids, entitled_country_ids,
prerequisite_product_ids, prerequisite_collection_ids, prerequisite_customer_segment_ids,
prerequisite_to_entitlement_purchase, allocation_method, market_ids

DiscountCode¶

price_rule(FK), code(CharField shop_unique), usage_count(Integer default 0), usage_limit(Integer nullable), customer_id(FK nullable for bound code), created_at, expires_at(nullable)

AutomaticDiscount、DiscountUsage、DiscountScript、DiscountScriptVersion¶

• AutomaticDiscount: price_rule(FK), title, status(active/expired/scheduled), starts_at, ends_at
• DiscountUsage: discount_code(FK nullable), automatic_discount(FK nullable), customer(FK nullable), order(FK nullable), used_at
• DiscountScript: title, type(Enum: discount/shipping/payment), source_code, version, status(draft/active/archived), active_version
• DiscountScriptVersion: script(FK), version, source_code, published_by, published_at, gray_percent

18.10 主题与内容¶

Theme¶

shop, name, version, status(unpublished/published/deleted), active_at, preview_token, processing, created_at

ThemeAsset¶

theme(FK), key(CharField, e.g. 'templates/product.liquid'), content(Text), checksum(CharField), attachment(URL for binary), content_type, size, updated_at，索引 (theme_id, key) unique

ThemeTemplate¶

theme(FK), template_type(Enum: product/collection/page/...), handle, json_content(JSON), published_scope(web/global), created_at, updated_at

ThemeSettings¶

theme(FK), data(JSON) 单条记录

Page、Blog、Article、ArticleComment、Menu、MenuItem¶

• Page: shop, title, handle, body_html, template_suffix, author(FK), published_at, published_scope,seo_title, seo_description, admin_graphql_api_id, visible(public/private/password), password
• Blog: shop, title, handle, template_suffix, feed_url, commentable
• Article: blog(FK), title, handle, body_html, author(FK), tags(Array), image(FK), published_at, status, summary, seo_title, seo_description
• ArticleComment: article(FK), author, email, body, status(unapproved/published/spam), ip, user_agent, created_at
• Menu: shop, handle, title，内置 handle main-menu, footer, mobile
• MenuItem: menu(FK), parent(FK self nullable), title, link_type(page/collection/product/blog/url/manual), link_value, position

18.11 渠道与 SEO¶

Channel、ChannelProduct¶

• Channel: shop, name, type(online_store/pos/manual/facebook/instagram/google/tiktok/wholesale/custom), status, configuration(JSON), created_at
• ChannelProduct: channel(FK), product(FK), published(Boolean), price_override(BigInteger nullable), inventory_override(Integer nullable), external_id

Redirect、SeoTemplate、DomainBinding¶

• Redirect: shop, path(CharField), target(CharField), status(301/302), priority(Integer)
• SeoTemplate: shop, content_type(product/collection/article/page), title_template, description_template
• DomainBinding: shop, domain(CharField unique), primary(Boolean), ssl_enabled, ssl_expires_at, subdirectory_prefix

18.12 Webhook 与通知¶

WebhookSubscription¶

shop, topic(CharField), address(URL), format(json/xml), api_version, fields(Array), metafield_namespaces(Array), secret, created_at, status(active/disabled)

WebhookDelivery¶

webhook_subscription(FK), payload(Text), headers(JSON), status(success/failure/queued), attempts(Integer), last_attempt_at, response_code, response_body

NotificationTemplate¶

shop, type(CharField Enum: order_confirmation/order_cancelled/refund_issued/...), channel(email/sms), subject, body_html, body_text, active

18.13 ER 关系总览（关键关联）¶

Shop ── Location
Shop ── Product ── ProductVariant ── InventoryLevel ── Location
Shop ── Collection ──< CollectionProduct >── Product
Shop ── Customer ── CustomerAddress
Shop ── Order ──< OrderLineItem >── ProductVariant  (snapshot)
Order ── Customer
Order ──< FulfillmentOrder ──< Fulfillment
Order ──< Refund ──< RefundLineItem >── OrderLineItem
Order ──< PaymentIntent ──< PaymentTransaction
Shop ── PriceRule ──< DiscountCode  ──< DiscountUsage >── Order
Shop ── Theme ──< ThemeAsset ; Theme ──< ThemeTemplate
Shop ── Page / Blog ──< Article
Shop ──< Channel ──< ChannelProduct >── Product
Shop ──< Menu ──< MenuItem

详细 Model 代码生成另出《Django 模型实现规范》（v1.0 落地版本）。

第 19 章 REST API 设计¶

19.1 API 总览¶

本系统开放三套对外接口，对标 Shopify：

19.2 通用规范¶

19.2.1 版本与兼容¶

• API 版本以 YYYY-MM 命名（如 2026-07），写在 URL 或 Header X-API-Version
• 每年发布 4 个稳定版本；旧版本至少保留 12 个月
• 弃用字段在响应中标 "deprecated": true，并在响应头 X-Shopify-API-Deprecated-Reason 解释

19.2.2 请求/响应规范¶

• 列表默认每页 50 条，最大 250 条；分页使用 page_info cursor 令牌
• 创建/更新接口要求 Content-Type: application/json
• 所有时间字段 UTC ISO 8601 字符串；金额按各模型说明字段类型在响应中输出 {amount, currency_code} 结构对象
• 错误响应统一结构：

{
  "errors": {
    "title": "Resource Not Found",
    "code": "NOT_FOUND",
    "message": "Product#gid://shop/Product/999 not found",
    "status": 404
  }
}

19.2.3 限流¶

• Admin API：每 App 40 req/s（leaky bucket）；超限 HTTP 429 + Retry-After
• Storefront API：每 Token 100 req/s
• 写操作（POST/PUT/DELETE）额外每 5 秒 2 次/资源
• Burst：最多 2× 平均速率

19.2.4 幂等性¶

• 写操作支持请求头 Idempotency-Key: <uuid>，5 分钟内同 key 重复请求复用原响应
• 幂等键记录表 IdempotencyRecord(key, response, created_at)

19.3 Admin REST API 资源清单¶

下表仅列核心资源（细分 fields/relations 见 API 详设文档）：

19.4 Storefront API（GraphQL）¶

19.4.1 Query 类型（对标 Shopify Storefront）¶

type Query {
  shop: Shop!
  productByHandle(handle: String!): Product
  product(id: ID!): Product
  products(first: Int, after: String, query: String, sortKey: ProductSortKeys, reverse: Boolean): ProductConnection!
  collectionByHandle(handle: String!): Collection
  collection(id: ID!): Collection
  collections(first: Int, after: String): CollectionConnection!
  node(id: ID!): Node
  nodes(ids: [ID!]!): [Node]!
  cart(id: ID!): Cart
  customer: Customer
  pageByHandle(handle: String!): Page
  blogByHandle(handle: String!): Blog
  articleByHandle(blogHandle: String!, articleHandle: String!): Article
  search(query: String!, first: Int, after: String): SearchResultConnection!
  publicMetafields(identifiers: [MetafieldIdentifier!], ownerType: String): [Metafield]
}

19.4.2 Mutation 类型¶

type Mutation {
  cartCreate(input: CartCreateInput!): CartCreatePayload
  cartLinesAdd(cartId: ID!, lines: [CartLineInput!]!): CartLinesAddPayload
  cartLinesUpdate(cartId: ID!, lines: [CartLineUpdateInput!]!): CartLinesUpdatePayload
  cartLinesRemove(cartId: ID!, lineIds: [ID!]!): CartLinesRemovePayload
  cartDiscountCodesUpdate(cartId: ID!, discountCodes: [String!]): CartDiscountCodesUpdatePayload
  cartGiftCardApply ...)
  cartBuyerIdentityUpdate(...)
  checkoutCreate(input: CheckoutCreateInput!): CheckoutCreatePayload
  checkoutShippingAddressUpdateV2(...)
  checkoutShippingLineUpdate(...)
  checkoutDiscountCodeApplyV2(...)
  checkoutEmailUpdate(...)
  checkoutCompleteWithCreditCardV2(...)
  checkoutCompleteWithTokenPayment(...)
  customerAccessTokenCreate(input: CustomerAccessTokenCreateInput!): ...
  customerCreate(input: CustomerCreateInput!): ...
  customerUpdate(input: CustomerUpdateInput!): ...
  customerAddressCreate/Update/Delete(...)
  customerRecover/Reset/Activate(...)
}

19.4.3 核心对象与字段（节选）¶

• Product：title handle description featuredImage variants(first:Int) options priceRange metafields
• ProductVariant：id sku title priceV2 {amount currencyCode} compareAtPriceV2 availableForSale selectedOptions image weight
• Collection：title handle description image products(first,after,filters:ProductFilters)
• Cart：id totalQuantity cost{subtotalAmount totalAmount} lines(first){edges{node{id quantity merchandise{…on ProductVariant{id}} cost{…}}}}
• Checkout：id ready webUrl lineItemsShippingAddress shippingLine taxLines totalPriceV2 appliedGiftCards discountApplications
• Customer：id displayName email firstName lastName defaultAddress orders(first){edges}

19.5 Webhook 设计¶

19.5.1 订阅¶

POST /api/admin/webhooks.json：

{ "webhook": { "topic": "orders/create", "address": "https://erp.demo/hook/orders", "format": "json" } }

19.5.2 推送机制¶

• HMAC-SHA256 请求头：X-TeleAgent-Signature: sha256=<hex> + X-TeleAgent-Topic + X-TeleAgent-Hmac-Sha256
• 推送为 HTTP POST，body 为 JSON
• 失败重试：指数退避（10s/1m/10m/1h/3h/12h/24h/48h），共 8 次；超过 24h 仍失败标记 disabled 并发邮件告警
• 重放：商家可在 Admin API 触发 POST /webhooks/{id}/replay 手动重推最近 30 天任意事件

19.5.3 关键事件清单（已散见各模块，此处汇总）¶

• products/create|update|delete
• collections/create|update|delete
• inventory_levels/update、inventory_items/update
• carts/create|update
• checkouts/create|update|delete
• abandoned_checkouts/create
• orders/create|updated|paid|cancelled|fulfilled|partially_fulfilled|delete
• orders/edited、transactions/create
• refunds/create
• draft_orders/create|update|delete
• fulfillment_orders/create|fulfilled|cancelled
• fulfillments/create|update
• customers/create|update|delete|disable|enable|merge
• discounts/create|delete|redeem
• gift_cards/create|update
• payment_intent/payment_authorized|payment_captured|payment_failed
• themes/publish、themes/update
• marketing/campaign_sent|email_delivered|email_opened|email_clicked
• reports/export_completed
• app/uninstalled（OAuth 应用卸载）

19.6 鉴权与权限¶

19.6.1 Admin API 鉴权¶

OAuth2 流程（用于第三方集成）：

GET /admin/oauth/authorize?client_id=XXX&scope=read_products,write_orders&redirect_uri=...
   ↓ 商家同意
GET /admin/oauth/redirect?code=AAAA&hmac=BBB&shop=xxx
POST /admin/oauth/access_token {client_id, client_secret, code}
   ↓
{ access_token, scope }

API Token 流程（员工自建）：

• 在 Admin 后台生成 Token，绑定 ShopStaff；可指定 scope 与过期时间
• 请求头 X-TeleAgent-Access-Token: <token>
• 权限校验：scope 必须覆盖资源（read_products、write_orders 等）

19.6.2 Storefront API 鉴权¶

• 每个 Theme / Channel 生成一个 Public Storefront Token
• 请求头 X-TeleAgent-Storefront-Access-Token: <public_token>
• Public Token 不可读 Admin 资源，只能读已发布商品 + 创建购物车/结账
• 后台可禁用某 Token，30 秒内全球生效（Redis 失效广播）

19.6.3 权限矩阵（节选）¶

19.7 OpenAPI / GraphQL Schema¶

• Admin REST 通过 drf-spectacular 自动生成 OpenAPI 3.0 文档，访问 /api/admin/openapi.json、/api/admin/docs/
• GraphQL 通过 strawberry-django 输出 schema，访问 /api/admin/graphql/schema.graphql

第 20 章 非功能性需求¶

20.1 性能指标¶

20.2 可用性与可扩展性¶

• 可用性 SLA 99.9% / 月（电商旺季 99.95%）；数据库主从 + Read replica；多 AZ 部署
• 读扩展：商品/集合读流量 100% 走 Read replica，写流量走主库
• 写扩展：订单写高峰按 shop_id 分片（Phase 3 引入），第一阶段单库分区表
• 水平扩展：Web + Celery 无状态、可水平扩；Redis Cluster；对象存储天然多副本
• 缓存策略：商品详情（10 分钟 + 主动失效）+ 集合列表（5 分钟）+ 主题渲染（编译缓存 + 内容 hash）+ 用户 session
• 降级预案：搜索服务不可用 → 降级到 PG like 搜索；推荐服务不可用 → 降级到时序热门；支付网关熔断 → 暂用其他网关
• 熔断：所有外部网关（支付、物流、短信）走 circuitbreaker 包

20.3 安全¶

• 传输：全站 HSTS + TLS 1.3；API 仅 HTTPS
• 存储：API Key 用 Fernet 加密；密码 BCrypt；DB 字段级加密敏感信息
• CSRF：DRF SessionAuthentication + SameSite=Strict；Admin 表单 {% csrf_token %}
• XSS：富文本 body_html 经 bleach 白名单清洗，禁用 iframe/script
• SQL 注入：ORM 强制参数化；禁止 raw query 拼接
• IDOR：所有对象级查询带 shop_id + owner_id 过滤，靠 BaseShopQuerySet 强制
• 限流：基于 IP + Token 双维度，按 API 与 IP 双重阈值
• 审计：敏感操作（退款、删除、Token 生成、权限变更）写 audit_log，保留 ≥ 3 年
• GDPR / 个保法：客户删除请求 → 14 天宽限 → 真实删除（订单客户字段脱敏）；客户可导出全部个人数据
• PCI DSS：不落地卡号；用 Stripe/AliPay 等已认证网关；不追求独立过 PCI
• WAF：接 Cloudflare / 阿里云 WAF，规则 OWASP Top 10
• DDoS：CDN 前置；管理后台强制 IP allowlist / VPN

20.4 可观测性¶

20.5 数据备份与灾备¶

• 数据库：每日全量 + 每小时增量，保留 30 天；PITR 支持
• 对象存储：跨区复制
• 异地灾备：异地热备 RPO ≤ 1h，RTO ≤ 4h
• 定期演练：每季度一次恢复演练

20.6 国际化与本地化¶

• 后端 i18n：django.utils.translation + DB 翻译
• 前端 i18n：主题 locales/*.json 文件
• 时区：服务端全 UTC，展示按店铺时区
• 货币：所有金额多币种支持，符合 ISO 4217
• 文字排布：支持 LTR/RTL（预留）

20.7 浏览器兼容与无障碍¶

• 主流浏览器：Chrome/Edge/Safari/Firefox 最近 2 个大版本；移动端 iOS Safari/Android Chrome 最近 2 个大版本
• 主题默认符合 WCAG 2.1 AA；图片 alt、按钮 ARIA 标签
• 视图组件预留 Lighthouse ≥ 90 分要求

20.8 容量评估（基于 10 万 SKU / 月 GMV 5000 万）¶

建议 Phase 1 用 PG 单库 + 主从，Phase 2 引入只读库分库 + OLAP ClickHouse/DuckDB。

第 21 章 开发阶段与里程碑¶

21.1 阶段总览¶

21.2 Phase 0 基础设施（3 周）¶

• 仓库结构、Docker Compose 一键启动
• CI：lint（ruff/black/mypy）+ pytest + 安全扫描（pip-audit、trivy）
• 基础设施层：PostgreSQL、Redis、MinIO、Celery、Sentry、Prometheus 接入示例
• 公共 core 模型基类、错误码、JWT/OAuth 框架

21.3 Phase 1 MVP（13 周，关键路径）¶

Phase 1 完成 = 冷启动可用：商家可上架、前台搜索购物、完成下单、看到订单。

21.4 Phase 2 商家增强（12 周）¶

21.5 Phase 3 生态与扩展（12 周）¶

21.6 团队建议¶

21.7 关键里程碑甘特图（Mermaid）¶

gantt
    title Django 电商平台开发节奏
    dateFormat  YYYY-MM-DD
    section Phase0
    基础设施        :p0, 2026-08-01, 21d
    section Phase1
    MVP 核心模块    :p1, 2026-08-22, 91d
    section Phase2
    商家增强        :p2, 2026-11-21, 84d
    section Phase3
    多渠道生态      :p3, 2027-02-13, 84d

第 22 章 风险与合规¶

22.1 风险登记¶

22.2 法律与合规清单¶

• 《个人信息保护法》/ GDPR 数据字段最小化；同意弹窗；删除权
• 《电子商务法》商家资质存档；订单保存 3 年
• 《网络安全法》等级保护 2.0（建议三级）；日志保留 ≥ 6 个月
• PCI DSS：通过使用合规第三方网关规避直接获取卡数据
• 海关/进口：跨境订单按平台/集货/直报模式分别对接
• 税务：增值税开票系统集成（电子发票 / 数电票）
• 招投标与商业条款相关留痕审计

22.3 数据治理¶

• 数据分类：公开 / 内部 / 机密 / 受限
• 数据脱敏：开发与测试环境强制脱敏；生产数据访问需 ticket + 双审
• 数据传输：内部服务 mTLS
• 数据导出：所有大表导出走审批；导出文件加水印与有效期 24 小时

22.4 文档与变更管理¶

• 文档体系：本功能需求 → 接口规约（OpenAPI/GraphQL）→ 数据模型详设 → 设计决策记录 (ADR) → 运维手册
• 变更管理：所有破坏性 API 改动走 RFC，需 2 人 review + 1 周 window
• 版本：使用 SemVer；每次 Release 配 CHANGELOG

附录 A Shopify 与 Django 概念映射表¶

文档结束。

本文档为对标 Shopify Plus 全量电商系统的 Django 实现需求规格说明书。各模块 API 字段细则、OpenAPI 文档、数据迁移规范将在独立交付物中以工程化形式输出。本文作为功能基线供产品评审与开发对接使用。

AI生成

央视节目中小学语文学习指南¶

按年段推荐节目 · 学习目标 · 方法 · 结果检测

适用对象：小学1年级至初中3年级学生及家长

前言¶

央视出品的文化类节目，以其制作精良、内容权威、语言优美而广受好评。近年来，《典籍里的中国》《中国诗词大会》《经典咏流传》《跟着书本去旅行》等节目，已成为中小学语文学习的「宝藏资源」。这些节目将课本中抽象的文字转化为生动的画面与故事，让「死」的知识变「活」，让远去的历史可感、可触、可思。

本指南按小学低段（1-2年级）、小学中段（3-4年级）、小学高段（5-6年级）、初中段（7-9年级）四个年段，分别推荐适合的央视节目，并为每个节目设置明确的学习目标、学习方法和结果检测标准。使用时请注意以下原则：

• 循序渐进：低段重兴趣与感知，高段重理解与思辨，不可跳跃
• 课本优先：节目是课本的「延伸」而非「替代」，应先学课本再看节目
• 输出倒逼输入：每看完一期都要有「写」或「说」的输出，而非纯被动观看
• 亲子共学：低段建议家长全程陪伴，高段逐步放手但定期检查输出成果

一、小学低段（1-2年级）¶

此阶段以汉字启蒙、语感培养和阅读兴趣激发为核心，节目选择侧重画面生动、语言浅近、时长短的内容，契合低龄儿童的认知特点与注意力时长。

1.《”字”从遇见你》¶

2.《中国唱诗班》¶

3.《跟着书本去旅行》¶

二、小学中段（3-4年级）¶

此阶段语文学习进入词句积累与阅读理解并重的时期，节目选择兼顾趣味性与知识密度，着重培养「从看懂到能说、能写」的过渡能力。

1.《经典咏流传》¶

2.《中国诗词大会》（精选季）¶

3.《跟着书本去旅行》（进阶）¶

4.《如果国宝会说话》¶

三、小学高段（5-6年级）¶

高段是阅读理解与写作能力飞跃的关键期，节目选择侧重深度理解、写作素材积累和思辨能力培养，逐步从「看懂」走向「能评、能论」。

1.《典籍里的中国》¶

2.《宗师列传·唐宋八大家》¶

3.《书简阅中国》¶

4.《跟着唐诗去旅行》¶

四、初中段（7-9年级）¶

初中语文进入深度阅读、思辨写作与文化传承并重的阶段。节目选择侧重文言文理解、文学史脉络、思辨表达与传统文化体系化认知，服务于中考与终身素养。

1.《典籍里的中国》（全季精读）¶

2.《宗师列传·唐宋八大家》（深度研讨）¶

3.《汉字五千年》¶

4.《中国》（第一季·第二季）¶

5.《唐之韵》¶

6.《书简阅中国》（拓展：议论文素材积累）¶

附录：节目总览速查表¶

使用建议¶

1. 时间规划¶

建议每周安排 2-3 次「央视课堂」，每次 20-45 分钟（低段短、高段长），固定时间形成习惯。周末可安排 1 次较长观看（如《典籍里的中国》90分钟完整版），日常利用碎片时间观看短集节目。

2. 输出管理¶

为每个年段准备一本「央视学习笔记」：低段以图画+拼音为主，中段加入摘抄+短文，高段以评析+思辨为主。每学期末翻阅笔记，回顾学习轨迹，成就感会极大地推动持续学习。

3. 家长角色¶

• 低段家长是「陪看者」——同看同聊，引导表达
• 中段家长是「督促者」——检查输出，参与互动
• 高段家长是「倾听者」——让孩子讲给你听，培养独立学习与思辨能力

无论哪个年段，家长的认真对待都是孩子坚持学习的最大动力。

4. 观看平台¶

以上节目均可通过央视网（tv.cctv.com）、央视频APP、B站（bilibili）等平台观看。建议优先使用央视频APP，画质清晰且无广告干扰。部分节目在央视频上有「完整版」和「精华版」，低段选精华版，高段选完整版。

AI生成

美国富裕人群 B2C 跨境电商商品推荐调研报告¶

报告版本：V1.0
完成日期：2026-07-21
研究范围：美国富裕人群消费偏好、$50–$500 轻奢/高品质平替价位段、优先中国供应链优势品类、面向电商公司业务拓展
研究方法：三阶段深度研究法（综合网络研究 → 学术与技术深度 → 交叉验证综合），共执行 30+ 次网络搜索，覆盖政府文件、海关数据、上市公司财报、行业研究机构、亿邦动力/雨果网等专业媒体
当前日期：2026 年 7 月 21 日

摘要（Executive Summary）¶

美国仍是全球最大的内需驱动型经济体——2025 年 GDP 达 30.8 万亿美元，居民消费支出占 GDP 的 81%，连续多年在 68%–81% 区间高位运行（东方财富网，2026）。在这一庞大消费盘子中，富裕人群是绝对的核心引擎：纽约联储 2026 年 5 月《Tracking the K-Shaped Economy》报告确认，自 2023 年以来美国零售支出增长持续由年收入 12.5 万美元以上的家庭驱动，前 10% 家庭贡献了近 50% 的家庭消费支出（纽约联储，2026）。但 2026 年 6 月最新调研显示，即便是年薪 10 万美元以上的高收入群体也出现”集体降级”——超七成转向折扣店采购，外食消费腰斩（搜狐网，2026-06-10）。这一表面的张力，恰恰揭示了 B2C 跨境电商真正的机会窗口：$100K–$300K”压力富裕层”既想维持品质生活感又有控支压力，正是 $150–$500 轻奢平替价位段的核心客群。

在政策一侧，2025 年 8 月 29 日美国正式终止执行近百年的 de minimis 800 美元免税规则，约 92% 的日均 400 万件小额包裹不再免税（山东外贸职业学院，2025-09-16）；2026 年 7 月 14 日美国司法部新设”全球贸易与商务执法处（GTCES）”，将贸易欺诈从行政处罚升级为刑事追诉，不到一年追缴损失已超 10 亿美元（网易，2026-07-20）；2026 年 7 月 24 日”122% 临时关税”到期将展开新一轮博弈（搜狐网，2026-07-15）。这三重政策夹击正在系统性将跨境电商从”流量+效率”模式推向”品牌+本土化+合规”模式，对走品牌化路径的卖家反而构成合规护城河。

基于机会空间、竞争烈度、利润水平、富裕人群契合度四维度综合评估，本报告推荐品类优先级阶梯为：第一梯队 AI 智能家居（扫地机器人、智能照明、智能安防）+ 居家咖啡器具（强烈推荐，毛利 35–55%）；第二梯队宠物智能硬件 AI 款 + 高端骑行电子装备（推荐，毛利 30–50%）；第三梯队 S925 设计师珠宝首饰（谨慎切入，毛利 50–80% 但原产地心智仍受限，建议第二阶段）；第四梯队健康个护电器（仅作辅助，FDA 合规门槛高）。渠道策略上，亚马逊 FBA + Shopify 独立站是主销售阵地，TikTok Shop 应作为内容种草与爆款引爆层而非主战场——美区 TikTok POP 综合费率已超 30%，90% 卖家不赚钱（网经社，2026-03-12），平台繁荣与卖家困局并存。行动路径上，建议参考安克创新”技术差异化 → 亚马逊 FBA 起量 → 独立站沉淀用户 → 线下零售渗透”四步走，避开 SHEIN 纯效率模式在政策周期下的脆弱性（其毛利率仅 5%，对比安克 45%）。

一、研究背景与方法¶

1.1 研究背景¶

美国是全球跨境电商最重要的目的国，多年来占据中国跨境电商出口 35% 以上份额。但 2025 年以来，中美贸易摩擦进入新一轮剧烈波动期：301 关税多次升级、de minimis 免税终止、贸易欺诈执法刑事化——这些变化正在根本性重塑中国跨境卖家进入美国市场的成本结构与商业模式。在政策不确定性的同时，美国国内消费也呈现出 K 形分化加剧的特征：富裕人群仍是消费韧性的核心引擎，但其内部消费行为也在发生微妙变化。

对电商公司而言，判断”是否仍应深耕美国市场”“应切入哪些品类”“应采用怎样的价位与渠道策略” 已成为紧迫的战略决策。本报告聚焦美国富裕人群（家庭收入 $100K+），在 $50–$500 轻奢/高品质平替价位段，优先考虑中国供应链优势品类，面向 B2C 跨境电商模式，旨在为电商公司业务拓展提供数据驱动的决策依据。

1.2 研究方法与局限¶

本报告采用三阶段深度研究法：第一阶段执行综合网络研究，覆盖市场宏观、富裕人群画像、消费偏好、渠道格局等 20+ 来源；第二阶段执行供应链与政策深度挖掘，覆盖 301 关税、de minimis、平台费率、六大品类供应链与利润结构、品牌案例等 12 轮搜索；第三阶段对前两阶段发现进行交叉验证与综合分析，特别补充 2026 年 Q2–Q3 最新数据。

研究方法的主要局限在于：第一，部分供应链拿货价数据来自阿里巴巴 1688 平台公开报价，并非实地调研一手数据，实际议价空间可能更高；第二，富裕人群对中国品牌电商接受度的定量调研数据有限，部分判断基于案例推断；第三，跨境电商政策环境处于剧烈变动期（2026 年 7 月 24 日、11 月 10 日为两个关键观察节点），报告结论需结合政策变化动态调整。

二、目标人群画像：美国富裕人群的内部差异化¶

2.1 富裕人群的规模与分层¶

美国富裕人群的定义存在多个分层口径，但收敛于年收入与资产两条主轴。Statista 2024 年基于美国人口普查数据的统计显示，约 45% 的美国家庭年收入低于 7.5 万美元，而约 16% 的家庭年收入达到或超过 20 万美元（Statista，2026）。这意味着年收入 20 万美元以上的家庭已处于全美前 1/5。在资产端，瑞银（UBS，2026）预估 2025 年全球每天新增超过 2680 名美元百万富翁，全年新增近 100 万，其中美国新增超 44 万，同比增长 1.9%，”仅美国一国便贡献了全球新增百万富翁的近一半”（虎嗅网，2026）。

FCW 发布的《2025 年美国富裕人群财富全景报告》调查了 1100 名拥有 50 万美元以上可投资资产的美国人，样本平均家庭年收入 32.1 万美元，平均可投资资产 190 万美元（新浪网，2026-03-12）。财富来源结构上，投资是最核心的财富来源（占比 89%），其次是工作收入（75%），企业所有权贡献 45%（FCW，2025）。这一画像描述的是一个由”投资回报+高薪职业+企业主”构成的复合富裕层，而非传统印象中的”继承型老钱”。

2.2 消费支出结构：体验化、健康化、品质化¶

富裕人群的消费支出呈现明显的”体验化、健康化、品质化”特征，且与中低收入群体结构差异显著。2025 年的核心变化是体验型消费增速持续超过实体商品。贝恩公司（2026）指出”奢侈品消费者越来越追求体验而非物质拥有”，而个人奢侈品消费市场 2026 年预计仅增长 2%–4%（贝恩公司与 Altagamma，2026）。在美国零售地产端，这一结构性转变的佐证更为直观：2025 年服务类租户（水疗中心、健身房等）租下的零售面积占比首次超过 50%，历史上首次超越实物商品零售，15 年前该比例仅为 40%（百家号，2026）。

在具体实物品类上，运动服装与户外是富裕人群的稳定消费支柱——2025 年美国运动服装市场规模达 822.7 亿美元，约占全球的 30%，预计 2030 年将达 1014 亿美元（腾讯网，2026）。中国体育用品业联合会发布的《户外度假报告 2025》指出，高收入消费者户外消费支出增长 2.2%，而低收入劳动者支出增长仅 0.3%（体育用品业联合会，2025）。宠物经济是另一个刚需赛道，据美国宠物用品协会（APPA，2026）《2026 年行业状况报告》，2025 年美国宠物行业总支出达 1580 亿美元，同比增长 3.7%，预计 2026 年增至 1650 亿美元；美国拥有宠物的家庭数量已达 9500 万户，占家庭总数的 71%（网易，2026）。珠宝则是少数具备”抗周期属性”的高增长赛道，贝恩与 Altagamma 联合报告显示 2025 财年珠宝行业同比增长率预计维持在 4%–6% 区间。居家咖啡是另一个值得关注的趋势——美国国家咖啡协会调查显示 85% 的咖啡饮用发生在家里，创 2012 年以来最高值（新浪网，2026）。

2.3 “压力富裕层”的核心洞察¶

报告最关键的人群洞察是：富裕人群并非铁板一块，$100K–$300K 的”压力富裕层”才是 $150–$500 轻奢平替的真正核心客群。FCW 调查显示，即便是平均可投资资产 190 万美元的富裕群体中，”超过半数受访者仍对个人财务状况感到压力”（新浪网，2026-03-12）。高盛也警告”美国家庭收入、现金流与消费者信心正在同步恶化”，财富效应主要集中在社会财富金字塔的顶层（新浪网，2026）。

2026 年 6 月最新调研进一步证实：年薪超 10 万美元的高收入家庭中超过七成将食品采购转向折扣店，外食消费腰斩，轻奢等非必要开支被优先砍掉（搜狐网，2026-06-10）。麦肯锡 2025 年 11 月报告显示 47% 消费者计划削减非必需品支出，密歇根大学消费者信心指数从 74.0 跌至 52.9（百家号，2026-02-27）。

这一表面矛盾恰恰构成机会：这些”压力富裕层”既不想彻底放弃品质生活感（家居、健康、宠物、户外、咖啡等核心消费仍需维持），又开始精打细算地选择更具性价比的选项。它不是停止消费，而是从”无差别溢价消费”转向”精挑细选的高品质消费”——这恰恰扩大了 $150–$500 轻奢平替的市场空间。他们的消费心理基础是”affordable luxury alternative”——愿意为设计感、品质、性能付溢价，但拒绝传统奢侈品牌的高溢价，这正是中国跨境品牌切入的核心机会窗口。

三、政策环境与合规护城河¶

3.1 301 关税与 de minimis 终止的连锁冲击¶

301 关税在 2025 年的演进链条十分清晰：2025 年 2 月 1 日特朗普签署行政令对中国商品加征 10% 关税；3 月 3 日升级至 20%；4 月 2 日宣布额外加征 34%（即”对等关税”）；2025 年 10 月 10 日特朗普宣布自 11 月 1 日起对所有中国商品加征额外 100% 关税，使总关税水平达到 130% 以上（四川省商务厅，2025-10-28）。但 2025 年 11 月 1 日中美达成历史性贸易与经济协议，11 月 26 日美国贸易代表办公室（USTR）宣布将 178 项”301 调查”关税豁免期限从原定 2025 年 11 月 29 日延长至2026 年 11 月 10 日（中华人民共和国商务部，2025-12-18）。这意味着 178 项豁免给大部分消费电子与家居品类提供了喘息窗口，但 2026 年 11 月 10 日将成为下一个关键博弈节点。

De minimis（800 美元小包裹免税）层面的冲击更为彻底。2025 年 2 月 1 日特朗普首次取消该政策，但因美国邮政处理能力不足于 2 月 7 日恢复；4 月 2 日宣布自 5 月 2 日起正式取消中国大陆与香港小额包裹免税待遇；7 月 30 日特朗普再次签署行政令，自 8 月 29 日起暂停对全球所有国家的低价值货物最低限度免税待遇；8 月 22 日午夜，实施近百年的”de minimis”规则正式终止，约 92% 日均 400 万件的小额包裹不再免税（山东外贸职业学院，2025-09-16）。2026 年 2 月美国正式引入 10% 全球关税（搜狐网，2026-07-08）。欧盟也同步于 2026 年 7 月 1 日取消 150 欧元以下小额包裹免税、每件征收 3 欧元临时固定关税——2024 年欧盟进口此类包裹 46 亿件、91% 来自中国（百家号，2026-07-07）。

3.2 贸易欺诈执法升级：从行政处罚到刑事追诉¶

2026 年 7 月 14 日美国司法部在国家欺诈执法司下新设”全球贸易与商务执法处”（GTCES），专门调查关税逃避、原产地造假、转运避税、强迫劳动；贸易欺诈特别工作组（TFTF）由司法部与国土安全部于 2025 年 8 月成立，”不到一年内涉及的民事及刑事追缴、罚款、没收和已公开起诉损失已超过 10 亿美元”，且明确将”报关行、境外制造商、美国分销商、仓储企业均纳入调查范围”（网易，2026-07-20）。这意味着海关违规行为从以补税和行政处罚为主升级为刑事追诉，对中国卖家的合规要求系统性提升。

3.3 政策夹击反向保护品牌化卖家¶

政策冲击的实质效果是结构性淘汰低价铺货、直邮小包、效率型模式，为品牌化路径腾出空间。反映在数据上：2025 年 5 月中国对美小包裹出口同比暴跌 40%；Temu 全托管模式下原本以 10–30 美元直邮美国的低价服装、生活杂货类目，在新关税下成本结构完全失衡，被迫大规模转向海外仓模式，单件物流成本从 2–3 美元飙升至 8–12 美元（搜狐网，2026-07-08）；Temu 被迫转向”半托管+POD 零库存”模式。

对走品牌化路径的卖家而言，政策反而构成”合规护城河”：竞争对手的合规成本同步上升，海外仓本土化+合规架构成为新门槛，纯白牌价格战模式被加速淘汰。这一逻辑构成对 $150–$500 价位段+品牌策略的反向政策学支撑——价位越高、产品差异化越强、品牌资产越深厚的卖家，对关税与物流成本的承受力越强。报告核心论点之一是：在 2026 年下半年这个政策窗口期，”合规门槛即护城河”——率先完成本土化+合规布局的品牌商，将在 2026 Q4–2027 年进入存量收割阶段。

四、渠道格局：三栖打法的三角关系¶

4.1 亚马逊：流量集中、规则严苛但仍是主战场¶

亚马逊仍是美国消费者首选购物平台，但其内部呈现高度集中——Marketplace Pulse 研究发现，仅 1.6% 的头部卖家贡献了亚马逊美国第三方 GMV 的 50%（网易，2026），流量与销量高度向少数头部卖家倾斜。同时亚马逊美国站 2026 年配送费上调、入库配置费上涨，超龄库存附加费范围扩大至 241–270 天，倒逼卖家优化库存周转（亚马逊官网，2025-12-01）。

亚马逊销售佣金按品类浮动，是测算利润必须锚定的基线：消费电子 8%、美妆个护 8–15%、家居与厨房 15%、服装鞋靴 17%、珠宝首饰 20%（≤$250 部分）、亚马逊设备配件 45%；FBA 配送费标准尺寸商品 $3.22–$3.86，广告 CPC 服装类约 $1.2，3C 及家居竞争激烈类目超过 $2（亚马逊官网，2025-12-31；连连支付，2025-11-14）。在 $50–$500 价位段，每件商品需扣除：佣金（按 15% 计 $7.5–$75）+ FBA 配送（$3.22–$3.86）+ 头程物流（约 $3–$15）+ 广告（占售价 8–15%）+ 退货损耗（服装 8–15%、电子 3–5%），总成本结构通常吃掉售价的 40–55%，对未建立品牌壁垒的玩家净利润率普遍被压缩至 5–12%（数字酋长，2026-05-15）。

但亚马逊的高流量与 Prime 会员心智仍然不可替代。2025 年上半年亚马逊美国站增长最快类目为：花园凉棚/遮阳棚（+50%）、汽配摩托车配件（+33%）、运动户外骑行用品（+37%）、工业科研餐饮服务设备（+29%）、工具家装手动工具（+11%）（百家号，2025-09-23）——这些类目恰恰落在 $50–$500 高品质平替价位段，是富裕人群”愿意为高价值产品买单但不必追求超奢品牌”的典型表现。亚马逊在 B2C 跨境电商中仍是不可绕开的主销售阵地，但必须以品牌化路径切入，避开纯白牌的费率陷阱。

4.2 TikTok Shop：繁荣背后的卖家困局¶

TikTok Shop 是 2025 年增速最快的电商渠道——eMarketer 数据显示 2025 全球 GMV 达 802 亿美元、同比增长 65%，活跃消费者 4 亿，增速全球第一（网经社，2026-03-12）。2025 年 TikTok Shop 美区上半年 GMV 58 亿美元同比+116%；2026 年年中促 TikTok Shop 美区全托管生意同比去年增长 1.5 倍，服饰类目 GMV 爆发 200%，首饰/发饰等配饰应季爆品增长 180%（亿邦动力，2026-03-24）。

但繁荣的另一面是残酷的卖家困局：什么值得买 2026 年 5 月拆解 TikTok 美区 POP 成本显示综合费率超 30%（什么值得买，2026-05-22），网经社报告指出”90% 以上的 TikTok 卖家不赚钱“（网经社，2026-03-12）。关键数据：TikTok Shop 美区 2025 上半年本土店贡献 75% GMV，跨境店+全托管仅占 25%，头部卖家中本土店优势明显（微博，2025-08-03）——这意味着跨境卖家在 TikTok Shop 美区面临巨大的本土化壁垒。

结论是：TikTok Shop 对未建品牌的中小卖家是”流量陷阱”（综合费率 30%+、90% 不赚钱），仅推荐已具备品牌资产的卖家将 TikTok 作为种草+引流渠道，而非主销售阵地。TikTok Shop 的价值在于内容种草与爆款引爆能力——一款带钢制支架的中国户外吊床在 TikTok Shop 卖出 3.3 万单狂揽 1400 万（百家号，2026-07-13），EcoFlow 新品移动电源借助 Super Brand Day 实现增量突破（百家号，2025）——但卖家需具备将这些流量导回亚马逊 FBA 或独立站沉淀用户的能力，否则将陷入”流量不沉淀、利润被吞掉”的循环。

4.3 Shopify 独立站：品牌资产的沉淀阵地¶

Shopify 过去 5 年在 LTM 收入增长持续超过亚马逊，3 年复合年均增长率 63%，反映了 DTC 独立站生态的快速扩张（新浪网，2026）。2025 年上半年 B2C 模式上半年同比增长 25.3%，独立站建设成为企业”掌握用户数据、提升复购的核心路径”（百家号，2025-06）。Shopify 独立站的核心价值在于用户数据沉淀、复购率提升、品牌资产积累——亚马逊不分享客户邮箱与购买行为数据，而 Shopify 卖家可直接掌握用户 LTV，通过邮件营销、会员体系、新品众筹等模式建立持续运营能力。

对富裕人群而言，独立站还提供”稀缺感”与”品牌故事”的承载——富裕消费者对”亚马逊一键下单的白牌”心智定价有限，对”有完整品牌叙事、有设计师故事、有零售体验的独立站”心智定价可上探 2–3 倍。出海网 CHWANG（2025）发布的《2025 年 Shopify 高利润利基市场指南》推荐的高利润利基包括环保产品（2025 年全球市场预计突破 1500 亿美元，44% 消费者愿意多花 12% 买可持续产品）、智能宠物用品等典型 $50–$500 品类。

五、品类推荐优先级阶梯¶

基于机会空间、竞争烈度、利润水平、富裕人群契合度四维度评估，本报告将六大候选品类分为四个梯队，每个梯队附以四维评分（满分 5 星）与切入建议。

5.1 第一梯队：AI 智能家居 + 居家咖啡（强烈推荐）¶

5.1.1 AI 智能家居——技术壁垒+品牌空间的双重护城河

AI 智能家居是综合得分最高的品类。中国扫地机器人 2025 年全球市占率 21.1%（石头科技），iRobot 鼻祖于 2025 年 12 月 14 日申请破产保护，被深圳杉川以债转股方式 100% 收购（百家号，2026-07-16）。中国日报 2026 年 6 月 22 日报道”中国扫地机品牌凭借 AI 系统与智能家居集成 clean up in global rankings”（中国日报，2026-06-22），证实这一价位段的中国产品已在全球站稳。

苏州扫地机器人产业链从核心零部件（绿的谐波减速器、汇川伺服系统）到整机闭环，制造成本结构优势全球无对手（雪球，2026-05-10）。价位段与毛利：海外扫地机市场均价 414 美元（开源证券研报），石头科技旗舰 S8 MaxV Ultra 定价 1799.99 美元；中端 $400–$800 区间是销量主力，毛利可达 35–45%（基于石头科技 2025 年财报推算）。$50–$500 价位段对应石头 S 系列入门款、eufy 扫地机中端款、米家海外版，拿货成本约 $120–$200（深圳/苏州 OEM），加上关税+FBA+佣金后售价 $299–$499 仍可实现 25–35% 净利率。小米 2026 年款扫地机器人在英国零售价 £139.99–£429.99（约 $175–$540，小米英国官网 2026-05-14），价位验证精确。

智能照明品类推荐智岩科技 Govee 作为参考——其 2018 年入驻亚马逊美国站后连续三年营收增速超 300%，2025 年年营收超 40 亿元人民币，启动 IPO 辅导（东方财富网，2026-03-26）。战略路径是避开传统基础照明红海，聚焦”情绪与氛围场景”——把灯光从照明工具升级为情绪表达、场景营造载体；通过 CogniGlow AI 算法、DreamView 智慧光域系统、RGBIC 分段式流光幻彩技术三大自研引擎构建壁垒。在 $50–$500 价位段（典型为 RGBIC 灯带 $60–$200、氛围落地灯 $150–$400、户外灯串 $80–$300），毛利可达 40–50%，远高于普通 LED 照明 15–20% 的水平。

智能安防摄像头品类，eufy 品牌”卷性能不卷价格”——旗舰款售价高于同类 2–3 倍仍保持高增长（搜狐网，2025-07-28）。1688 平台拿货成本区间：基础室内摄像头 ¥10.8–80、4G 室外摄像头 ¥118–166、AI 喂鸟器摄像头 ¥284.5、涂鸦 tuya 智能 50 倍变焦云台防水款 ¥589（1688，2026-07-15）。$150–$500 中高端带 AI 识别、云台、双目款拿货 ¥150–300（约 $21–42），零售 $149–$299，毛利 35–45%。风险提示：基础摄像头同质化极严重，无品牌壁垒玩家 5% 以下净利率常态，必须选 AI 识别+差异化功能款。

5.1.2 居家咖啡器具——蓝海窗口期+心智空白品类

居家咖啡是本报告重点推荐的”心智空白品类”。美国国家咖啡协会调查显示，在受访前一天饮用过咖啡的人群中，85% 是在家饮用，创 2012 年以来最高值；66% 美国成年人每天饮用咖啡，平均 2.8 杯，全美每日咖啡消费量超 5 亿杯（新浪网，2026）。2026 年家居奢侈回归趋势（阿里巴巴国际站 2026-07-02”royal style dining”热潮）佐证居家品质消费升级。

全球咖啡机近 80% 由中国生产，但中国长期不是主流玩家——La Marzocco、西蒙利、Slayer 等高端品牌均来自意大利和美国。36 氪（2025）报道中国创业者打造万元级家用咖啡机 Meraki 海外一上市就爆单，正在改变”中国咖啡机鲜少掌握核心技术”的难题。$50–$500 价位段：1688 拿货价——跨境便携式电动磨豆机 USB 充电约 ¥49–78（浙江星瑞、博琛科技）、手摇磨豆机套装 ¥80–200、半自动家用咖啡机 ¥200–500（基础款）至 ¥800–1500（带 PID 控温）。零售在美国站 $79–$299 为主力价位，$300–$499 为入门半自动机。毛利结构：手冲/磨豆类毛利 40–55%，但市场体量有限；家用半自动咖啡机毛利 25–35%（关税+大件 FBA 配送费吃掉较多）。关键洞察：咖啡器具品类品牌壁垒尚未形成，是新晋跨境品牌切入”高品质平替”心智的蓝海窗口，且契合”居家仪式感”消费心理。

5.2 第二梯队：宠物智能硬件 AI 款 + 高端骑行电子装备（推荐）¶

5.2.1 宠物智能硬件 AI 款——红海中的蓝海再分化

宠物经济是富裕人群消费的刚需赛道。全球宠物技术市场年增速 15%，预计 2032 年突破 350 亿美元（搜狐网，2025-10-17）。重点案例：CATLINK 创始人张晓林深耕国际宠物智能用品十余年，2019 年推出首款支持 AI 智能语音的猫砂盆，4 个月销售额破 1000 万元，通过”代理+跨境 B2C”模式进入海外市场，服务 100 万只猫、年入过亿（腾讯网，2026-07-07）；Petlibro 深圳跨境大佬靠智能喂食器做到头部品牌，年入破亿（百家号，2026-01-22）；福州某公司从空气炸锅到智能猫砂盆，连续 9 年超 25% 增速，年销 2 亿美元，旗下爆品常年霸榜亚马逊前 20（百家号，2025-09-23）。

价位段与利润：智能猫砂盆 TOP3 售价从 600 美元暴跌至 150 美元，普通款拿货 ¥300–800（约 $42–110），零售 $149–$299，毛利 35–50% 但因价格战加剧边际利润率被洗薄至 15–25%；AI 识别+健康监测的差异化款零售 $299–$499，毛利 45–55%。搜狐报道指出”AI 识别技术正在开辟利润新蓝海”，搭载 AI 识别、健康监测的中高端产品客单价提升 30–50%，对价格战免疫（搜狐网，2025-10-17）。策略建议：必须避开普通智能猫砂盆红海，选 AI 识别+健康监测的差异化款，目标 $299–$499 价位段。

5.2.2 高端骑行电子装备——体验型消费的延伸

2025 年美国骑行装备市场规模超 70 亿美元，2025 年中国户外运动产业总规模突破 3 万亿元（界面新闻，2026-07-14）。关键案例：洛克兄弟（ROCKBROS）成立 14 年，从配件商升级为”骑行界迪卡侬”，在亚马逊+独立站+TikTok 多平台上覆盖头盔、码表、车灯、车锁、骑行服全品类（新浪网，2026-01-19）；某深圳品牌智能头盔日销 10 万美元、年收入超 4 亿元、业务遍及 70 多国（知乎，2025-10-20）。

$150–$500 价位段：骑行码表 $50–$200（拿货 ¥80–300）、智能头盔 $80–$250（拿货 ¥150–400）、骑行服套装 $60–$180（拿货 ¥80–200），毛利率普遍 30–45%，但季节性强、退货率高（服饰类 8–15% 退货损耗），实际净利率 25–35%。策略建议：聚焦 $150–$500 高端骑行电子装备（智能头盔、码表、骑行台），避开服饰类高退货品类，配合”Fishing to Fairway”（从钓鱼到高尔夫的多功能运动生活方式）内容营销切入富裕男性市场。

5.3 第三梯队：S925 设计师珠宝（谨慎，第二阶段切入）¶

S925 银饰与轻奢首饰是中国出口最被低估的高毛利品类之一。1688 拿货价数据：义乌流萤珠宝 S925 纯银蝴蝶项链 ¥3.71；海丰县梅陇老银匠首饰厂（9 年老店）S925 立体爱心吊坠项链 ¥53.64；深圳璎珞珠宝跨境专供莫桑石戒指 S925 纯银三生三世 2 克拉 ¥173.96；义乌淑童饰品法式复古渐变珍珠耳钉 ¥18.81（阿里巴巴 1688，2026-06-17 与 2026-07-10）。$50–$500 价位段与利润：S925 银饰项链拿货 ¥4–50（$0.5–7），终端零售 $29–$79，毛利 65–80%；莫桑石戒指拿货 ¥150–300，零售 $99–$299，毛利 50–65%；人造宝石定制款拿货 ¥200–500，零售 $199–$499，毛利 50–60%。

案例：HEFANG 何方珠宝 2025 年天猫双十一天猫珠宝饰品类目登顶榜首，超越施华洛世奇、潘多拉等国际品牌，正加速出海欧美（百家号，2025-12-15）。行业大背景：Michael Kors 母公司 Capri 集团 2025 财年 Q2 净利润大跌 73%，亚洲销售大跌 43%；Tapestry（Coach/Kate Spade 母公司）2025 财年净利润从 8.19 亿美元暴跌——传统轻奢整体承压，为中国轻奢平替品牌提供了渗透窗口（新浪网，2026-01-12）。

但两个隐忧使珠宝只能处于第三梯队：一是原产地效应在情感型/身份型品类中仍较强，富裕人群对”Made in China 珠宝”的信任壁垒高于功能性品类（详见第七章）；二是亚马逊珠宝首饰佣金高达 20%（≤$250 部分），是美国站少数高佣金类目之一，再加上认证成本（如镍释放量测试、铅含量合规）与高退货率，实际净利率被压至 20–35%。策略建议：作为第二阶段品类切入，配合强内容种草和设计师品牌叙事，主推 S925+莫桑石+设计师系列三层次产品矩阵，避免直接对标潘多拉/施华洛世奇的中低端定位。