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

基于 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生成