Stratos Project

联动链路:

登录/注册 → Supabase Auth → /api/auth/callback → middleware updateSession → useAuth Hook

2. 内容模块

2.1 帖子 (Posts)

联动链路:

创建帖子 → status=pending → Admin审核 → AI翻译/话题提取 → 通知关注者
编辑帖子 → 更新内容 → 重新审核 → 同步翻译
删除帖子 → 软删除 → 清理关联数据 → 更新计数

2.2 商品 (Products)

商品状态流转:

创建 → pending → Admin审核 → active → sold_out/inactive
  ↓       ↓         ↓          ↓
编辑    拒绝     上架销售    库存管理

3. 社交互动模块

限流保护:

• DB trigger: enforce_like_rate_limit, enforce_follow_rate_limit
• 前端防抖: 300ms (LikeButton), 2s (话题提取)

4. 电商订单模块

4.1 购物车系统

技术架构:

• 状态管理: Zustand + persist中间件（本地存储）
• 数据验证: 结算时实时验证商品状态
• 多规格支持: 支持颜色、尺寸等SKU变体

购物车数据结构:

interface CartItem {
  product_id: string      // 商品ID
  quantity: number        // 数量
  price: number          // 单价（下单时快照）
  currency?: string      // 货币
  name: string           // 商品名称
  image: string          // 商品图片
  color?: string | null  // 颜色规格
  size?: string | null   // 尺寸规格
}

核心功能:

变体处理逻辑:

// 判断是否为同一SKU（product_id + color + size）
function isSameVariant(a, b): boolean {
  return a.product_id === b.product_id &&
    (a.color ?? null) === (b.color ?? null) &&
    (a.size ?? null) === (b.size ?? null)
}

结算验证流程:

点击结算 → 验证选中商品 → 调用validateItems()
  ↓
检查库存是否充足
检查商品是否下架
检查价格是否变动
  ↓
验证通过 → 跳转/checkout
验证失败 → 提示用户更新购物车

4.2 订单系统

订单创建流程:

购物车选择商品 → /checkout → 填写地址 → 创建订单 → 跳转支付
      ↓                ↓           ↓            ↓
  多卖家拆单      选择收货地址   库存预占    生成order_number
  Affiliate追踪   运费计算      价格快照    状态=pending

多卖家订单处理:

• 一个购物车结算可能包含多个卖家的商品
• 系统自动按卖家拆分为多个独立订单
• 每个订单独立支付、独立物流、独立评价

订单状态流转:

pending (待支付) → paid (已支付) → shipped (已发货) → completed (已完成)
     ↓                  ↓                ↓
  30分钟超时        卖家发货         自动确认(7天)
  自动取消          物流单号         买家手动确认
     ↓                  ↓                ↓
cancelled (已取消)  dispute (纠纷中)  refund (已退款)

状态说明:

订单核心功能:

订单表结构:

orders (
  id UUID PRIMARY KEY,
  order_number TEXT UNIQUE,           -- 订单号 (如: ORD20250210001)
  buyer_id UUID REFERENCES profiles(id),
  seller_id UUID REFERENCES profiles(id),
  order_status TEXT,                  -- pending/paid/shipped/completed/cancelled/refunded/in_dispute
  total_amount DECIMAL(10,2),         -- 订单总金额
  currency VARCHAR(3),                -- 货币
  shipping_address JSONB,             -- 收货地址快照
  shipping_fee DECIMAL(10,2),         -- 运费
  affiliate_post_id UUID,             -- 关联的推广帖
  seller_type_snapshot TEXT,          -- 下单时卖家类型快照
  funds_recipient TEXT,               -- 资金流向 (platform/seller)
  created_at TIMESTAMPTZ,
  updated_at TIMESTAMPTZ
)

order_items (
  id UUID PRIMARY KEY,
  order_id UUID REFERENCES orders(id),
  product_id UUID REFERENCES products(id),
  quantity INTEGER,
  unit_price DECIMAL(10,2),           -- 下单时单价快照
  color TEXT,
  size TEXT,
  created_at TIMESTAMPTZ
)

定时任务:

4.3 订单履行（Fulfillment）系统

履行流程:

订单支付成功 (status=paid)
     ↓
卖家准备商品 → 打包 → 联系物流
     ↓
卖家在系统录入物流信息
     ↓
订单状态变为 shipped
     ↓
买家可查看物流跟踪信息
     ↓
商品送达 → 买家确认收货
     ↓
订单完成 (status=completed)

卖家发货要求:

发货API:

POST /api/orders/[id]/ship
{
  tracking_number: "SF1234567890",    // 物流单号
  logistics_provider: "顺丰速运"       // 物流公司
}

4.4 物流跟踪系统

支持的物流公司:

物流查询流程:

买家查看订单 → 点击物流跟踪
     ↓
系统调用快递100 API
     ↓
实时查询物流状态
     ↓
展示物流轨迹时间线

物流状态映射:

物流表结构:

order_tracking (
  id UUID PRIMARY KEY,
  order_id UUID REFERENCES orders(id),
  tracking_number TEXT,              -- 物流单号
  logistics_provider TEXT,           -- 物流公司
  status TEXT,                       -- 物流状态
  current_location TEXT,             -- 当前位置
  estimated_delivery TIMESTAMPTZ,    -- 预计送达
  tracking_details JSONB,            -- 物流轨迹
  last_updated TIMESTAMPTZ,
  created_at TIMESTAMPTZ
)

Affiliate订单追踪:

用户点击推广链接 → 写入cookie (affiliate_post_id)
      ↓
下单时读取cookie → 关联到订单
      ↓
订单支付成功 → 计算佣金 → 写入affiliate_commissions

支付渠道支持:

5. 订阅与会员模块

5.1 订阅类型概览

5.2 Seller订阅档位（3档纯净模式）

档位说明:

• Starter: 零佣金、即时聊天、基础订单管理、标准客服
• Growth: 优先客服(6小时内响应)、批量导入/导出、带货佣金设置、基础推广工具
• Scale: 专属客户经理(2小时内响应)、深度数据分析、库存预警、首页推荐位、品牌专属页面

5.3 订阅状态流转

创建订单 → pending → 支付成功 → active → 到期/取消
               ↓                        ↓
           支付失败                  自动续费
                                    ↓
                              cancelled/expired
                                    ↓
                              权益降级 → 通知用户

状态说明:

• pending: 待支付状态，创建订单后24小时内有效
• active: 已激活，享有全部权益
• cancelled: 用户主动取消，当前周期结束后失效
• expired: 已过期，权益自动降级

5.4 订阅生命周期管理

定时任务:

• 订阅到期提醒: 每天检查即将到期(7天内)的订阅，发送邮件提醒
• 订阅生命周期: 每天处理过期订阅，同步用户权益降级

权益同步机制:

订阅激活/续费:
  profiles.subscription_type = 'seller'
  profiles.subscription_tier = 购买的档位值
  profiles.product_limit = 对应的商品数量限制

订阅过期:
  profiles.subscription_type = NULL
  profiles.subscription_tier = NULL
  profiles.product_limit = 0
  profiles.role = 'user' (从seller降级)

5.5 首月折扣机制

• 新用户首次订阅可享受首月折扣
• 折扣价格显示在UI上，实际按折扣价扣费
• 次月起恢复原价，自动续费
• 折扣信息记录在 subscriptions.is_discounted 和 discount_expiry_date

5.6 订阅与卖家类型联动

特殊权限:

• internal_tip_enabled: Direct卖家无需Tip订阅即可接收打赏
• internal_affiliate_enabled: Direct卖家无需Affiliate订阅即可推广

5.7 核心API与Hook

API端点:

Hook:

// 检查用户是否有有效订阅
const { hasActiveSubscription, subscriptionTier } = useSubscription()

// 检查商品发布权限
const canCreateProduct = hasActiveSubscription && 
  (sellerType === 'direct' || productCount < productLimit)

5.8 订阅表结构

subscriptions (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES profiles(id),
  subscription_type TEXT CHECK (subscription_type IN ('seller', 'affiliate', 'tip')),
  subscription_tier INTEGER,              -- 内部档位值: 15/50/100
  display_price DECIMAL(10,2),            -- 显示价格(可能不同于tier)
  product_limit INTEGER DEFAULT 0,        -- 商品数量限制
  amount DECIMAL(10,2) NOT NULL,          -- 实际支付金额
  currency VARCHAR(3) DEFAULT 'USD',      -- 支付货币
  status TEXT CHECK (status IN ('pending', 'active', 'cancelled', 'expired')),
  is_discounted BOOLEAN DEFAULT FALSE,    -- 是否首月折扣
  discount_expiry_date TIMESTAMPTZ,       -- 折扣到期日
  deposit_credit DECIMAL(10,2),           -- 保证金额度(等于subscription_tier)
  starts_at TIMESTAMPTZ NOT NULL,
  expires_at TIMESTAMPTZ NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
)

6. 打赏模块

6.1 打赏系统概述

打赏是平台的内容变现功能，允许用户向喜欢的内容创作者或卖家表达支持。

打赏类型:

6.2 打赏流程

用户点击打赏 → 检查接收者是否开启打赏
     ↓
检查打赏者限额（防止洗钱）
     ↓
创建Stripe Checkout Session
     ↓
用户完成支付
     ↓
Webhook接收支付成功通知
     ↓
Stripe自动转账给接收者
     ↓
通知双方（打赏者、接收者）

6.3 打赏限额

6.4 打赏表结构

tip_transactions (
  id UUID PRIMARY KEY,
  sender_id UUID,                    -- 打赏者
  receiver_id UUID,                  -- 接收者
  amount DECIMAL(10,2),              -- 金额
  currency VARCHAR(3),               -- 货币
  post_id UUID,                      -- 关联帖子（可选）
  message TEXT,                      -- 留言
  status TEXT,                       -- pending/completed/failed
  stripe_transfer_id TEXT,           -- Stripe转账ID
  created_at TIMESTAMPTZ
)

6.5 核心API

7. 带货（Affiliate）模块

7.1 带货系统概述

带货是平台的推广分佣系统，允许推广者（Affiliate）帮助卖家推广商品并赚取佣金。

参与角色:

• 卖家: 设置商品佣金率，允许Affiliate推广
• Affiliate: 创建推广内容，赚取佣金
• 买家: 通过推广链接购买商品

7.2 带货流程

卖家设置商品allow_affiliate=true
     ↓
设置commission_rate（如10%）
     ↓
Affiliate创建推广帖（需Affiliate订阅）
     ↓
帖子中包含affiliate_post_id
     ↓
用户点击推广链接 → 写入cookie(affiliate_post_id)
     ↓
用户下单 → 关联affiliate_post_id到订单
     ↓
订单支付成功 → 自动计算佣金
     ↓
写入affiliate_commissions表
     ↓
Affiliate申请结算 → Admin审核 → 打款

7.3 佣金计算

计算公式:

佣金金额 = 商品金额 × 佣金率

佣金率来源优先级:
1. affiliate_products表中的自定义佣金率
2. products表中的默认佣金率

示例:

• 商品售价: $100
• 佣金率: 10%
• Affiliate佣金: $100 × 10% = $10

7.4 核心表结构

affiliate_posts (
  id UUID PRIMARY KEY,
  post_id UUID REFERENCES posts(id),    -- 关联帖子
  product_id UUID REFERENCES products(id), -- 关联商品
  affiliate_id UUID,                     -- 推广者ID
  commission_rate DECIMAL(5,2),          -- 自定义佣金率
  affiliate_code TEXT,                   -- 推广码
  clicks INT DEFAULT 0,                  -- 点击数
  conversions INT DEFAULT 0,             -- 转化数
  created_at TIMESTAMPTZ
)

affiliate_products (
  id UUID PRIMARY KEY,
  affiliate_id UUID,
  product_id UUID,
  post_id UUID,                          -- 关联推广帖
  commission_rate DECIMAL(5,2),          -- 自定义佣金率
  status TEXT,                           -- active/inactive
  created_at TIMESTAMPTZ
)

7.5 核心API

7. 佣金与推广模块

佣金链路:

Affiliate创建推广帖 → 用户点击带affiliate_id → 下单 → 支付成功 → 计算佣金 → 待结算 → Admin审核 → 打款

8. 保证金模块

8.1 保证金系统概述

保证金系统是平台风险控制的核心机制，主要用于：

• 交易担保: 确保卖家履约能力
• 纠纷赔付: 纠纷败诉时用于赔付买家
• 违规处罚: 扣除保证金作为违规惩罚

适用对象: 仅External卖家需要缴纳保证金，Direct卖家免保证金

8.2 保证金额度规则

额度计算:

当前可用额度 = 缴纳保证金总额 - 未完成订单总额
可接单条件: 新订单金额 ≤ 当前可用额度

8.3 保证金状态流转

缴纳保证金 → active (可用)
     ↓
接单占用 → locked (锁定)
     ↓
订单完成 → active (释放)
     ↓
申请退款 → pending_refund (退款中)
     ↓
Admin审核 → refunded (已退款) / active (拒绝)

8.4 保证金核心功能

8.5 接单控制机制

支付启用/禁用逻辑:

可用额度 ≥ 新订单金额 → 允许接单 (payment_enabled = true)
可用额度 < 新订单金额 → 禁止接单 (payment_enabled = false)

自动恢复机制:

• 订单完成后自动检查未完成的订单总额
• 如果未完成订单 ≤ 保证金额度，自动恢复接单权限
• 通过 checkAutoRecovery() 函数实现

8.6 保证金扣除场景

扣除函数:

await deductFromDeposit({
  sellerId: 'seller_uuid',
  amount: 50,
  currency: 'USD',
  reason: '纠纷败诉赔付',
  relatedId: 'order_uuid',
  relatedType: 'debt', // 'debt' | 'commission' | 'violation' | 'other'
  supabaseAdmin
})

8.7 保证金表结构

seller_deposit_lots (
  id UUID PRIMARY KEY,
  seller_id UUID REFERENCES profiles(id),
  amount DECIMAL(10,2),              -- 缴纳金额
  currency VARCHAR(3),               -- 货币
  status TEXT,                       -- active/locked/pending_refund/refunded
  payment_method TEXT,               -- 支付方式
  payment_transaction_id UUID,       -- 关联支付记录
  created_at TIMESTAMPTZ,
  updated_at TIMESTAMPTZ
)

-- 保证金审计日志
seller_deposit_audit_logs (
  id UUID PRIMARY KEY,
  seller_id UUID,
  action TEXT,                       -- deposit/lock/release/deduct/refund
  amount DECIMAL(10,2),
  currency VARCHAR(3),
  balance_after DECIMAL(10,2),       -- 操作后余额
  related_order_id UUID,             -- 关联订单
  reason TEXT,                       -- 操作原因
  created_at TIMESTAMPTZ
)

9. 即时通讯模块

联动:

• 新消息 → Realtime订阅 → 通知 → 未读计数
• 订单相关 → 自动创建会话 → 系统消息

10. 通知系统模块

11. 管理员模块

审核流程:

用户提交内容 → status=pending → Admin审核 → approve/reject → 通知用户 → 触发AI翻译

11.1 内容审核系统

审核内容类型:

帖子审核流程:

用户发布帖子 → status=pending
     ↓
Admin审核列表 → 查看内容、图片
     ↓
  ├─ 通过 → status=approved
  │         ↓
  │    触发AI翻译 → 写入post_translations
  │    触发话题提取 → 关联post_topics
  │    通知关注者
  │
  └─ 拒绝 → status=rejected
            ↓
      填写拒绝原因 → 通知作者

商品审核流程:

卖家发布商品 → status=pending
     ↓
Admin审核 → 检查图片、描述、价格
     ↓
  ├─ 通过 → status=active (上架销售)
  │
  └─ 拒绝 → status=rejected
            ↓
      卖家可编辑后重新提交

审核API:

11.2 佣金结算系统

结算流程:

Affiliate推广 → 用户下单 → 订单支付成功
     ↓
自动计算佣金 → 写入affiliate_commissions (status=pending)
     ↓
Affiliate申请结算
     ↓
Admin审核 → 验证订单有效性
     ↓
  ├─ 通过 → 打款 → status=settled
  │         ↓
  │    从保证金扣除或平台支付
  │
  └─ 拒绝 → 填写原因 → 可重新申请

佣金计算规则:

// 佣金金额 = 商品金额 × 佣金率
const commissionAmount = (itemPrice * quantity) * commissionRate / 100

// 佣金率来源优先级:
// 1. affiliate_products表中的自定义佣金率
// 2. products表中的默认佣金率

结算状态:

结算表结构:

affiliate_commissions (
  id UUID PRIMARY KEY,
  affiliate_id UUID,              -- 推广者ID
  order_id UUID,                  -- 关联订单
  product_id UUID,                -- 关联商品
  commission_rate DECIMAL(5,2),   -- 佣金率(%)
  commission_amount DECIMAL(10,2), -- 佣金金额
  currency VARCHAR(3),            -- 货币
  status TEXT,                    -- pending/requested/settled/cancelled
  settled_at TIMESTAMPTZ,         -- 结算时间
  created_at TIMESTAMPTZ
)

结算API:

12. AI自动化模块

12.1 AI系统概述

平台集成DeepSeek AI服务，提供内容翻译、话题提取、语言检测等自动化功能，支持多语言内容生态。

AI服务配置:

• API提供商: DeepSeek
• API密钥: DEEPSEEK_API_KEY 环境变量
• 支持功能: 翻译、话题提取、内容补全、语言检测

12.2 自动翻译系统

翻译触发时机:

• 帖子审核通过后自动翻译标题和内容
• 商品审核通过后自动翻译名称和描述
• 评论审核通过后自动翻译

翻译流程:

内容审核通过 → 检测源语言
     ↓
调用DeepSeek API翻译
     ↓
写入翻译表 (post_translations, product_translations等)
     ↓
用户切换语言时显示对应翻译

支持翻译的内容类型:

翻译API:

POST /api/ai/translate-after-publish
{
  type: 'post' | 'product' | 'comment' | 'product_comment',
  id: 'content_id'
}

12.3 话题提取系统

提取流程:

帖子审核通过 → 读取帖子正文
     ↓
调用AI提取话题关键词
     ↓
匹配已有话题或创建新话题
     ↓
关联帖子到话题 (post_topics表)

话题表结构:

topics (
  id UUID PRIMARY KEY,
  name TEXT UNIQUE,           -- 话题名称
  slug TEXT UNIQUE,           -- URL友好的标识
  description TEXT,           -- 话题描述
  icon_url TEXT,              -- 话题图标
  post_count INT DEFAULT 0,   -- 帖子数
  follower_count INT DEFAULT 0, -- 关注者数
  is_trending BOOLEAN DEFAULT false, -- 是否热门
  created_at TIMESTAMPTZ
)

post_topics (
  post_id UUID REFERENCES posts(id),
  topic_id UUID REFERENCES topics(id),
  PRIMARY KEY (post_id, topic_id)
)

12.4 语言检测

检测时机:

• 创建帖子时自动检测内容语言
• 写入 posts.content_lang 字段
• 用于Feed推荐和翻译目标语言判断

API:

// lib/ai/detect-language.ts
detectContentLanguage(content: string): 'zh' | 'en' | 'other'

12.5 内容补全

功能: AI辅助用户撰写帖子内容 入口: 帖子创建页面的"AI补全"按钮 API: POST /api/ai/complete

13. 客服工单系统

13.1 工单系统概述

客服工单系统用于处理用户提交的各类问题和请求，由Support角色管理和回复。

工单类型:

优先级:

13.2 工单状态流转

用户创建工单 → open (待处理)
     ↓
Admin/Support分配工单
     ↓
in_progress (处理中)
     ↓
回复用户 → waiting_for_user (等待用户回复)
     ↓
用户回复 → in_progress
     ↓
问题解决 → resolved (已解决)
     ↓
用户确认关闭 → closed (已关闭)

13.3 工单核心API

用户端:

Admin/Support端:

13.4 工单表结构

support_tickets (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES profiles(id),  -- 提交用户
  title TEXT,                            -- 标题
  description TEXT,                      -- 描述
  ticket_type TEXT,                      -- 工单类型
  priority TEXT,                         -- 优先级
  status TEXT,                           -- open/in_progress/waiting_for_user/resolved/closed
  assigned_to UUID,                      -- 分配给哪个Support
  created_at TIMESTAMPTZ,
  updated_at TIMESTAMPTZ
)

support_ticket_replies (
  id UUID PRIMARY KEY,
  ticket_id UUID REFERENCES support_tickets(id),
  user_id UUID,                          -- 回复者
  content TEXT,                          -- 回复内容
  is_internal BOOLEAN DEFAULT false,     -- 是否内部备注
  created_at TIMESTAMPTZ
)

14. 信任判断系统

14.1 信任判断概述

信任判断系统为买家提供交易风险评估，帮助买家做出更明智的购买决策。

判断维度:

• 卖家历史纠纷率
• 卖家完成订单数
• 商品价格偏离度

14.2 信任等级

14.3 判断规则配置

// lib/trust-judgment/config.ts
export const TRUST_JUDGMENT_CONFIG = {
  // 统计近90天的纠纷
  dispute_window_days: 90,
  
  // 近90天有1笔纠纷即高风险
  high_risk_dispute_threshold: 1,
  
  // 完成订单数=0视为新卖家
  new_seller_order_threshold: 0,
  
  // 当前价超过历史最高价×1.2判中风险
  price_deviation_ratio: 1.2,
  
  // 历史成交价统计365天
  price_history_window_days: 365,
}

14.4 判断逻辑

获取卖家近90天纠纷数
     ↓
纠纷数 ≥ 1 → high_risk
     ↓
完成订单数 = 0 → medium_risk (新卖家)
     ↓
检查商品价格
     ↓
当前价 > 历史最高价×1.2 → medium_risk
     ↓
low_risk

14.5 信任判断API

POST /api/trust/judgment
{
  sellerId: 'seller_uuid',
  productId: 'product_uuid'
}

Response:
{
  riskLevel: 'low_risk' | 'medium_risk' | 'high_risk',
  recommendation: '平台判断：该卖家可信',
  evidence: [
    { type: 'completed_orders', value: 10, description: '完成订单数' },
    { type: 'disputes', value: 0, description: '近90天纠纷数' }
  ]
}

15. 定时任务模块 (Cron Jobs)

用户类型与卖家类型系统

1. 用户角色 (User Role) - profiles.role

用户角色定义用户在平台上的基本身份权限，存储于 profiles.role 字段。

角色变更规则:

user → seller: 购买 Seller 订阅后自动升级
seller → user: 订阅过期且未续费
admin/support: 仅由现有管理员手动设置

2. 卖家类型 (Seller Type) - profiles.seller_type

卖家类型是 3档纯净模式 的核心概念，用于区分不同类型的卖家，影响支付流程、保证金要求和商品发布限制。

核心差异:

数据库定义:

ALTER TABLE profiles
  ADD COLUMN seller_type TEXT
  CHECK (seller_type IN ('external', 'direct'))
  DEFAULT 'external';

3. 用户来源 (User Origin) - profiles.user_origin

用户来源标记用户是外部注册还是内部创建，用于区分平台运营账号。

内部用户特殊权限 (由 Admin 设置):

• internal_tip_enabled: 无需 Tip 订阅即可接收打赏
• internal_affiliate_enabled: 无需 Affiliate 订阅即可推广

注意: user_origin 是敏感字段，绝不暴露给前端，仅在服务端 API 中使用。

4. 订阅档位 (Subscription Tier) - profiles.subscription_tier

订阅档位与卖家类型配合使用，控制外部卖家的功能和商品发布数量。

联动规则:

Direct 卖家: 无视 subscription_tier，无商品发布限制
External 卖家: 必须满足 subscription_tier 对应的商品数量限制

5. 订单中的卖家类型快照

订单创建时会快照记录卖家的类型信息，用于后续的支付和退款处理。

用途:

• 支付时决定使用谁的支付账户
• 退款时决定资金从哪退回
• 财务对账和审计

6. 类型系统联动链路

6.1 用户注册流程

用户注册 → auth.users 创建 → profiles 创建
  ↓
role = 'user'
seller_type = 'external' (默认)
user_origin = 'external' (默认)

6.2 成为卖家流程 (External)

用户购买 Seller 订阅
  ↓
支付成功 → subscription 创建
  ↓
Trigger: 更新 profiles
  role = 'seller'
  subscription_type = 'seller'
  subscription_tier = 购买的档位
  product_limit = 对应档位的限制
  ↓
用户可发布商品 (受 product_limit 限制)

6.3 创建直营卖家流程 (Direct)

Admin 创建内部用户
  ↓
POST /api/admin/internal-users
  ↓
profiles 创建
  role = 'seller'
  seller_type = 'direct'
  user_origin = 'internal'
  ↓
Admin 设置 seller_type = 'direct'
  ↓
记录 seller_type_audit_logs
  ↓
直营卖家可无限制发布商品

6.4 订单支付时的类型判断

创建订单
  ↓
记录 seller_type_snapshot = profiles.seller_type
记录 funds_recipient = 
  seller_type='direct' ? 'platform' : 'seller'
  ↓
支付时检查:
  IF seller_type_snapshot = 'direct'
    → 使用平台支付账户
    → 跳过保证金检查
  ELSE
    → 使用卖家绑定的支付账户
    → 检查保证金充足性

7. 关键 API 与类型检查

检查卖家是否可以创建商品

// /api/seller/product-limit/route.ts
const { data: profile } = await supabase
  .from('profiles')
  .select('seller_type, product_limit, subscription_tier')
  .eq('id', user.id)
  .single()

// Direct 卖家无限制
if (profile.seller_type === 'direct') {
  return { canCreate: true, limit: null }
}

// External 卖家检查当前商品数量和限制
const currentCount = await getUserActiveProductsCount(user.id)
return { 
  canCreate: currentCount < profile.product_limit,
  limit: profile.product_limit 
}

验证卖家支付就绪状态

// /lib/payments/validate-seller-payment-ready.ts
const sellerType = profile.seller_type as 'external' | 'direct' | null
const isDirect = sellerType === 'direct'

if (isDirect) {
  // Direct 卖家: 跳过订阅和保证金检查
  return { valid: true }
}

// External 卖家: 检查订阅、保证金、支付账户
// ... 详细检查逻辑

Admin 设置卖家类型

// /api/admin/profiles/[id]/seller-type/route.ts
const beforeType = profile.seller_type || 'external'
const afterType = sellerType // 'external' | 'direct'

// 更新 profiles
await supabase
  .from('profiles')
  .update({ seller_type: afterType })
  .eq('id', params.id)

// 记录审计日志
await supabase
  .from('seller_type_audit_logs')
  .insert({
    seller_id: params.id,
    operator_admin_id: adminId,
    before_type: beforeType,
    after_type: afterType,
  })

8. 类型系统数据表

支付系统详解

平台支持 5种支付方式，覆盖国际和国内市场：

1. Stripe（信用卡/借记卡）

适用场景: 国际支付，支持 Visa、MasterCard、American Express 等

技术实现:

• 使用 Stripe Payment Intents API 创建支付
• 支持 3D Secure 安全验证
• Webhook 处理支付状态变更

关键文件:

/lib/payments/stripe.ts                    # Stripe 核心逻辑
/lib/payments/stripe-connect.ts            # Stripe Connect 分账
/app/api/payments/stripe/webhook/route.ts  # Webhook 处理
/app/api/payments/stripe/create-checkout-session/route.ts
/app/api/payments/stripe/create-order-checkout-session/route.ts
/app/api/payments/stripe/create-intent/route.ts

支付流程:

选择 Stripe 支付
  ↓
创建 PaymentIntent / Checkout Session
  ↓
返回 client_secret 或跳转 URL
  ↓
前端调起 Stripe 支付界面
  ↓
用户输入卡信息并确认
  ↓
Stripe 处理支付 → Webhook 通知
  ↓
更新订单状态为 paid

环境变量:

STRIPE_SECRET_KEY=sk_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_...
STRIPE_WEBHOOK_SECRET=whsec_...

2. PayPal

适用场景: 国际支付，PayPal 余额或绑定的卡

技术实现:

• 使用 PayPal REST API v2
• 支持 Orders API 创建和捕获订单
• Webhook 处理支付状态

关键文件:

/lib/payments/paypal.ts                    # PayPal 核心逻辑
/lib/payments/paypal-payouts.ts            # PayPal 打款
/app/api/payments/paypal/create-order/route.ts
/app/api/payments/paypal/capture-order/route.ts
/app/api/payments/paypal/client-config/route.ts

支付流程:

选择 PayPal 支付
  ↓
创建 PayPal Order (v2/checkout/orders)
  ↓
返回 orderID
  ↓
前端调起 PayPal 弹窗/SDK
  ↓
用户登录并确认支付
  ↓
捕获订单 (capture)
  ↓
Webhook 通知 → 更新订单状态

环境变量:

PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...
PAYPAL_WEBHOOK_ID=...

3. 支付宝 (Alipay)

适用场景: 中国用户，支付宝余额/花呗/绑定的卡

技术实现:

• 使用支付宝开放平台 API
• 支持 PC 网站支付、手机网站支付
• 异步通知 (notify_url) 处理支付结果

关键文件:

/lib/payments/alipay.ts                    # 支付宝核心逻辑
/lib/payments/alipay-transfer.ts           # 支付宝转账
/app/api/payments/alipay/create-order/route.ts
/app/api/payments/alipay/callback/route.ts
/app/api/payments/alipay/refund/route.ts

支付流程:

选择支付宝支付
  ↓
生成支付宝订单参数（带签名）
  ↓
返回 form 表单或跳转 URL
  ↓
用户跳转支付宝页面/扫码
  ↓
支付完成 → 同步回调 + 异步通知
  ↓
验签并更新订单状态

环境变量:

ALIPAY_APP_ID=...
ALIPAY_PRIVATE_KEY=...
ALIPAY_PUBLIC_KEY=...
ALIPAY_NOTIFY_URL=https://.../api/payments/alipay/callback
ALIPAY_RETURN_URL=https://.../orders/success

4. 微信支付 (WeChat Pay)

适用场景: 中国用户，微信内支付或扫码支付

技术实现:

• 使用微信支付 Native/JSAPI API
• 支持扫码支付、公众号支付、H5 支付
• 异步通知处理支付结果

关键文件:

/lib/payments/wechat.ts                    # 微信支付核心逻辑
/lib/payments/wechat-transfer.ts           # 微信企业付款
/app/api/payments/wechat/create-order/route.ts
/app/api/payments/wechat/notify/route.ts

支付流程:

选择微信支付
  ↓
调用统一下单 API (unifiedorder)
  ↓
返回 prepay_id 和支付参数
  ↓
前端调起微信支付（JSAPI/扫码）
  ↓
用户确认支付
  ↓
微信异步通知 → 验签 → 更新订单

环境变量:

WECHAT_PAY_APP_ID=...
WECHAT_PAY_MCH_ID=...
WECHAT_PAY_API_KEY=...
WECHAT_PAY_CERT_PATH=./cert/apiclient_cert.pem
WECHAT_PAY_KEY_PATH=./cert/apiclient_key.pem

5. 银行转账 (Bank Transfer)

适用场景: 大额支付、企业客户、其他支付方式不可用

技术实现:

• 线下银行转账 + 线上凭证上传
• Admin 人工审核确认
• 支持多币种银行账户

关键文件:

/app/api/payments/bank/init/route.ts       # 初始化银行转账
/app/api/payments/bank/upload-proof/route.ts  # 上传转账凭证
/app/api/payments/bank/approve-proof/route.ts # Admin 审核凭证

支付流程:

选择银行转账
  ↓
获取平台银行账户信息
  ↓
创建待确认支付交易 (status=pending)
  ↓
用户线下转账到指定账户
  ↓
用户上传转账凭证
  ↓
Admin 审核凭证
  ↓
审核通过 → 更新订单为 paid
  ↓
审核拒绝 → 要求重新上传

数据库表:

• bank_account_settings: 平台收款账户配置
• bank_payment_proofs: 用户上传的转账凭证

支付方式对比

支付配置管理

平台支持 动态配置支付账户，通过数据库管理：

// 获取平台支付账户配置
const { data } = await supabase.rpc('get_platform_payment_account', {
  p_currency: 'USD',
  p_account_type: 'stripe',
})

优先级:

1. 数据库平台账户配置（支持多币种）
2. 环境变量（fallback）

卖家绑定支付账户:

• Stripe: 通过 Stripe Connect OAuth 绑定
• PayPal: 保存卖家 PayPal 邮箱
• 支付宝/微信: 保存卖家收款账号

支付安全与风控

1. Webhook 签名验证: 所有支付回调都验证签名
2. 幂等性处理: 防止重复处理同一笔支付
3. 金额校验: 支付金额必须与订单金额一致
4. 状态机校验: 只允许从 pending → paid 状态转换
5. 卖家类型检查: Direct 卖家使用平台账户收款

管理员后台系统

管理员后台是平台运营的核心，提供内容审核、用户管理、订单纠纷处理、财务管理等功能。

访问权限

• Admin 角色: 拥有所有后台权限
• Support 角色: 拥有部分权限（内容审核、工单处理、纠纷处理）

权限检查:

const { data: profile } = await supabase
  .from('profiles')
  .select('role')
  .eq('id', user.id)
  .single()

if (profile?.role !== 'admin' && profile?.role !== 'support') {
  redirect('/')
}

1. 仪表盘 (/admin/dashboard)

功能: 展示平台核心数据概览

显示内容:

关键文件:

/app/[locale]/(main)/admin/dashboard/page.tsx
/components/admin/ContentReview.tsx
/components/admin/ReportManagement.tsx
/components/admin/CommissionManagement.tsx

2. 内容审核 (/admin/review, /admin/content-review)

功能: 审核用户发布的帖子、商品、评论

审核内容类型:

审核流程:

用户提交内容 → status=pending
  ↓
Admin 查看待审核列表
  ↓
审核内容（查看详情、图片）
  ↓
选择操作：
  ├─ 通过 → 更新 status → 触发 AI 翻译 → 通知用户
  └─ 拒绝 → 更新 status → 填写拒绝原因 → 通知用户

关键 API:

POST /api/admin/content-review/[id]/approve
POST /api/admin/content-review/[id]/reject

图片迁移:

• 审核通过前，系统自动将图片从 Supabase 迁移到 Cloudinary
• 迁移失败则审核失败，需要重新尝试

3. 用户管理 (/admin/profiles, /admin/internal-users)

3.1 普通用户管理

功能: 查看用户信息、封禁/解封账号、设置卖家类型

操作:

3.2 内部用户管理 (/admin/internal-users)

功能: 创建平台运营账号（直营卖家、测试账号）

内部用户特性:

• user_origin = 'internal'
• 可设置为 seller_type = 'direct'（直营卖家）
• 可单独开启 internal_tip_enabled 和 internal_affiliate_enabled

关键 API:

GET    /api/admin/internal-users              # 列表
POST   /api/admin/internal-users              # 创建
POST   /api/admin/internal-users/[id]/set-direct-seller
POST   /api/admin/internal-users/[id]/tip-affiliate
POST   /api/admin/internal-users/[id]/set-password

4. 身份认证审核 (/admin/identity-verification)

功能: 审核用户提交的实名认证资料

审核流程:

用户提交认证资料 → identity_verifications 创建记录
  ↓
Admin 查看待审核列表
  ↓
审核证件照片、姓名、身份证号
  ↓
通过 → 更新 profiles.identity_verified = true
拒绝 → 填写拒绝原因

关键 API:

GET  /api/admin/identity-verification          # 待审核列表
POST /api/admin/identity-verification/[userId]/review

5. 订单与纠纷管理 (/admin/orders, /admin/disputes)

5.1 订单管理

功能: 查看所有订单、处理异常订单

订单状态:

• pending: 待支付
• paid: 已支付，待发货
• shipped: 已发货
• completed: 已完成
• cancelled: 已取消
• in_dispute: 纠纷中

5.2 纠纷处理 (/admin/disputes/[id])

功能: 处理买家发起的退款/纠纷申请

纠纷类型:

处理流程:

买家发起纠纷 → order_disputes 创建记录
  ↓
Admin 查看纠纷详情（订单信息、买卖双方、纠纷原因）
  ↓
调查沟通
  ↓
做出裁决：
  ├─ 支持买家 → 退款给买家 → 可能扣除卖家保证金
  ├─ 支持卖家 → 订单继续 → 可能扣除买家信用
  └─ 协商解决 → 双方达成一致

关键 API:

GET  /api/admin/disputes              # 纠纷列表
POST /api/admin/refunds/process       # 处理退款

6. 财务管理

6.1 平台支付账户配置 (/admin/platform-payment-accounts)

功能: 配置平台收款账户（用于 Direct 卖家收款）

支持的账户类型:

• Stripe
• PayPal
• 支付宝
• 微信支付

关键 API:

GET    /api/admin/platform-payment-accounts
POST   /api/admin/platform-payment-accounts
PUT    /api/admin/platform-payment-accounts/[id]
DELETE /api/admin/platform-payment-accounts/[id]

6.2 卖家支付账户审核 (/admin/payment-accounts)

功能: 审核卖家绑定的支付账户

审核状态:

• pending: 待审核
• verified: 已通过
• rejected: 已拒绝

关键 API:

POST /api/admin/payment-accounts/[id]/verify

6.3 佣金结算 (/admin/commissions)

功能: 审核并结算 Affiliate 推广佣金

结算流程:

Affiliate 申请结算 → status=pending
  ↓
Admin 审核推广订单有效性
  ↓
确认结算 → POST /api/admin/commissions/[id]/settle
  ↓
转账给 Affiliate → 更新状态为 settled

关键文件:

/components/admin/CommissionManagement.tsx

6.4 卖家债务管理 (/admin/seller-debts)

功能: 查看和管理卖家欠款（退款导致）

关键 API:

GET /api/admin/seller-debts
GET /api/admin/seller-debts/[sellerId]

6.5 平台费用收取 (/admin/platform-fees)

功能: 向卖家收取平台服务费

关键 API:

POST /api/admin/platform-fees/charge

7. 举报处理 (/admin/reports)

功能: 处理用户举报（内容违规、用户违规）

举报类型:

处理流程:

用户举报 → reports 创建记录
  ↓
Admin 查看举报详情
  ↓
调查被举报内容/用户
  ↓
处理：
  ├─ 内容违规 → 删除内容 + 警告/封禁用户
  ├─ 用户违规 → 封禁用户
  └─ 无违规 → 驳回举报
  ↓
通知举报者处理结果

关键 API:

POST /api/admin/reports/[id]/send-result-notification

关键文件:

/components/admin/ReportManagement.tsx

8. 客服工单系统 (/admin/support)

功能: 处理用户提交的客服工单

工单类型:

工单状态流转:

open → assigned → in_progress → resolved/closed
         ↓
      escalated (升级给 Admin)

关键 API:

GET    /api/admin/support/tickets              # 工单列表
POST   /api/admin/support/tickets/[id]/assign  # 分配工单
POST   /api/admin/support/tickets/[id]/respond  # 回复工单
POST   /api/admin/support/tickets/[id]/update-status
POST   /api/admin/support/tickets/[id]/escalate # 升级工单
POST   /api/admin/support/tickets/[id]/close    # 关闭工单

9. 账户注销审核 (/admin/deletion-requests)

功能: 审核用户的账户注销申请

审核流程:

用户申请注销 → account_deletion_requests 创建记录
  ↓
系统检查：是否有未完成订单、是否有欠款
  ↓
Admin 审核
  ↓
通过 → 软删除用户数据 → 发送确认邮件
拒绝 → 填写原因 → 通知用户

关键 API:

GET  /api/admin/deletion-requests
POST /api/admin/deletion-requests/[id]/approve
POST /api/admin/deletion-requests/[id]/reject

10. 系统监控 (/admin/monitoring)

功能: 查看系统运行状态和关键指标

监控内容:

关键 API:

GET /api/admin/monitoring/dashboard

11. 违规处罚 (/admin/violation-penalties)

功能: 对违规卖家进行处罚（扣除保证金）

关键 API:

POST /api/admin/violation-penalties/deduct

12. 社区管理 (/admin/community)

功能: 管理社区话题、群组

操作:

• 创建/编辑话题
• 管理群组
• 设置社区规则

管理员后台文件结构

src/
├── app/[locale]/(main)/admin/
│   ├── dashboard/page.tsx              # 仪表盘
│   ├── review/page.tsx                 # 内容审核
│   ├── content-review/page.tsx         # 内容审核（新）
│   ├── profile-review/page.tsx         # 资料审核
│   ├── identity-verification/page.tsx  # 身份认证审核
│   ├── internal-users/page.tsx         # 内部用户管理
│   ├── orders/page.tsx                 # 订单管理
│   ├── disputes/[id]/page.tsx          # 纠纷处理详情
│   ├── commissions/page.tsx            # 佣金结算
│   ├── reports/page.tsx                # 举报处理
│   ├── support/page.tsx                # 客服工单
│   ├── deletion-requests/page.tsx      # 注销审核
│   ├── platform-payment-accounts/page.tsx  # 平台支付配置
│   ├── payment-accounts/page.tsx       # 卖家支付账户审核
│   ├── seller-debts/page.tsx           # 卖家债务
│   ├── seller-debts/[sellerId]/page.tsx # 卖家债务详情
│   ├── platform-fees/page.tsx          # 平台费用
│   ├── violation-penalties/page.tsx    # 违规处罚
│   ├── monitoring/page.tsx             # 系统监控
│   └── community/page.tsx              # 社区管理
│
├── components/admin/
│   ├── ContentReview.tsx               # 内容审核组件
│   ├── ReportManagement.tsx            # 举报管理组件
│   └── CommissionManagement.tsx        # 佣金管理组件
│
└── app/api/admin/
    ├── content-review/[id]/approve/route.ts
    ├── content-review/[id]/reject/route.ts
    ├── profiles/[id]/ban/route.ts
    ├── profiles/[id]/unban/route.ts
    ├── profiles/[id]/seller-type/route.ts
    ├── internal-users/route.ts
    ├── disputes/route.ts
    ├── refunds/process/route.ts
    ├── commissions/[id]/settle/route.ts
    ├── reports/[id]/send-result-notification/route.ts
    ├── support/tickets/route.ts
    ├── deletion-requests/route.ts
    ├── platform-payment-accounts/route.ts
    ├── payment-accounts/[id]/verify/route.ts
    ├── seller-debts/route.ts
    ├── monitoring/dashboard/route.ts
    └── ...

核心数据流

1. 用户注册登录流

用户访问 /login 或 /register
  ↓
输入凭证 → Supabase Auth API
  ↓
认证成功 → /api/auth/callback
  ↓
middleware.ts updateSession (设置 cookie)
  ↓
页面渲染 → useAuth Hook 获取用户信息
  ↓
RLS 策略根据 auth.uid() 控制数据访问

2. 内容发布审核流

用户创建帖子/商品
  ↓
写入数据库 (status=pending)
  ↓
Admin 收到审核通知
  ↓
Admin 审核 (approve/reject)
  ↓
更新 status (approved/active 或 rejected)
  ↓
通知作者审核结果
  ↓
如通过 → 触发 AI 翻译/话题提取
  ↓
内容出现在 Feed/商城

3. 订单支付流

买家下单 → 创建订单 (status=pending)
  ↓
跳转支付页 → 选择支付方式
  ↓
调用支付 API (Stripe/Alipay/WeChat)
  ↓
第三方支付页面
  ↓
支付完成 → Webhook/回调
  ↓
验证支付 → 更新订单 (status=paid)
  ↓
扣减库存 → 计算佣金
  ↓
通知买卖双方
  ↓
卖家发货 → 买家确认收货 → 订单完成

4. 社交互动流

用户点击点赞/关注/评论
  ↓
前端限流 (防抖)
  ↓
API 请求
  ↓
DB 限流检查 (trigger)
  ↓
写入数据表
  ↓
更新计数 (trigger)
  ↓
通知接收者
  ↓
实时推送 (Realtime)

技术栈详解

核心框架

后端与数据

状态管理

UI 组件

国际化

支付

项目目录结构