Marketplace 架构设计

本文档描述 AI Agent Marketplace 的数据模型设计和系统架构。

数据模型概览

erDiagram
    User ||--o| Wallet : has
    User ||--o{ MarketplaceListing : sells
    User ||--o{ Order : buys
    User ||--o{ Subscription : subscribes
    User ||--o{ Review : writes
    Wallet ||--o{ WalletTransaction : records
    MarketplaceListing ||--o{ Order : generates
    MarketplaceListing ||--o{ Subscription : generates
    MarketplaceListing ||--o{ Review : receives
    Order ||--o| WalletTransaction : creates

用户与钱包模型

User（用户）

复用现有 Chameleon 用户体系，扩展用户身份标识。

字段	类型	说明
id	UUID	主键
username	string	用户名
avatar_url	string	头像 URL
role	enum	角色：buyer/seller/admin
created_at	datetime	创建时间
updated_at	datetime	更新时间

Wallet（积分钱包）

用户积分钱包，与用户 1:1 绑定。

字段	类型	说明
id	UUID	主键
user_id	UUID	外键 → User
balance	integer	当前积分余额
frozen_balance	integer	冻结积分（交易中锁定）
total_earned	integer	累计赚取积分
total_spent	integer	累计消费积分

WalletTransaction（积分流水）

积分变动不可变审计日志。

字段	类型	说明
id	UUID	主键
wallet_id	UUID	外键 → Wallet
type	enum	类型：earn/spend/transfer/topup/withdraw
amount	integer	变动金额（正数增加，负数减少）
balance_after	integer	变动后余额
reference_type	string	关联对象类型
reference_id	UUID	关联对象 ID
description	string	描述说明
created_at	datetime	创建时间

商品上架模型

MarketplaceListing（商品上架记录）

字段	类型	说明
id	UUID	主键
seller_id	UUID	外键 → User（卖家）
asset_type	enum	资产类型：prompt/rag_file/knowledge_base/agent/mcp
asset_id	UUID	指向对应资产表的 ID
title	string	商品标题
description	text	商品描述
cover_image_url	string	封面图片 URL
pricing_model	enum	定价模式：one_time/monthly/tiered
base_price	integer	积分单价
status	enum	状态：draft/published/suspended/archived
download_count	integer	下载/购买次数
rating_avg	float	平均评分（1-5）
rating_count	integer	评价数量
tags_json	JSON	标签列表
created_at	datetime	创建时间
updated_at	datetime	更新时间

资产类型说明

类型	说明	示例
prompt	Prompt 模板	角色扮演 Prompt、代码生成 Prompt
rag_file	RAG 文件	文档片段、知识库文件
knowledge_base	知识库	完整的知识库配置
agent	AI Agent	可运行的 Agent 配置
mcp	MCP 配置	Model Context Protocol 配置

定价模式说明

模式	说明	适用场景
one_time	一次性购买	Prompt、RAG 文件
monthly	按月订阅	知识库、Agent 服务
tiered	阶梯定价	根据使用量定价

交易与订阅模型

Order（交易订单）

字段	类型	说明
id	UUID	主键
buyer_id	UUID	外键 → User（买家）
listing_id	UUID	外键 → MarketplaceListing
total_price	integer	积分总价
platform_fee	integer	平台佣金
seller_income	integer	卖家实收 = total_price - platform_fee
status	enum	状态：pending/paid/refunded/cancelled
created_at	datetime	创建时间
completed_at	datetime	完成时间

Subscription（订阅记录）

用于月付商品的订阅管理。

字段	类型	说明
id	UUID	主键
buyer_id	UUID	外键 → User
listing_id	UUID	外键 → MarketplaceListing
status	enum	状态：active/expired/cancelled
current_period_start	datetime	当前周期开始
current_period_end	datetime	当前周期结束
auto_renew	boolean	是否自动续费
created_at	datetime	创建时间
updated_at	datetime	更新时间

平台配置与评价模型

PlatformConfig（平台全局配置）

键值对形式存储平台配置。

字段	类型	说明
key	string	主键
value	string	配置值
description	string	配置说明

预置配置项

键	默认值	说明
commission_rate	0.20	平台佣金比例（20%）
min_withdrawal	1000	最小提现积分
daily_earn_cap	500	每日赚取积分上限

Review（商品评价）

字段	类型	说明
id	UUID	主键
listing_id	UUID	外键 → MarketplaceListing
buyer_id	UUID	外键 → User
rating	integer	评分（1-5）
comment	text	评价内容
created_at	datetime	创建时间

核心业务逻辑

购买流程

sequenceDiagram
    participant B as Buyer
    participant API as Marketplace API
    participant W as Wallet Service
    participant S as Seller

    B->>API: POST /orders (listing_id)
    API->>W: 检查买家余额
    W-->>API: 余额充足
    API->>W: 冻结买家积分
    API->>API: 创建订单 (pending)
    API->>W: 扣除买家积分
    API->>W: 计算佣金 (price * commission_rate)
    API->>W: 卖家入账 (price - commission)
    API->>API: 订单完成 (paid)
    API-->>B: 返回订单 + 资产访问权限

积分获取途径

途径	积分数	说明
每日登录	10	每日首次登录奖励
分享 Agent	50	首次上架 Agent 奖励
商品被购买	售价 × 80%	卖家收入（扣除 20% 佣金）
充值购买	1 元 = 100 积分	直接充值
用户转账	自定义	P2P 转账

技术实现

后端核心文件

新增文件：

文件路径	说明
`ai_service/storage/marketplace_models.py`	市场相关数据模型
`ai_service/api/routers/marketplace.py`	商品市场 API
`ai_service/api/routers/wallet.py`	积分钱包 API
`ai_service/api/routers/admin.py`	管理后台 API
`ai_service/services/wallet_service.py`	钱包业务逻辑
`ai_service/services/order_service.py`	订单业务逻辑

修改文件：

文件路径	说明
`ai_service/storage/models.py`	扩展 User 模型
`ai_service/api/app.py`	注册新路由
`ai_service/utils/settings.py`	新增市场相关配置