PRD：以物换物平台（Barter Zone）

版本: v2.0 | 日期: 2026-05-18 | 作者: AI Pipeline Factory 技术底座: OpenClaw Agent + CloudBase + React 更新记录: v2.0 — 新增 UI 需求文档与 Agent 协议规范引用；优化匹配算法描述；补充安全与风控章节

一、产品概述

1.1 产品定位

一个基于 OpenClaw Agent 的智能以物换物社区。用户发布闲置物品，AI Agent 自动分析物品特征、匹配交换需求、撮合交易，打造「无现金」的物品流转生态。

1.2 核心价值

• 去货币化：纯物品交换，不需要现金中介
• AI 智能匹配：OpenClaw Agent 理解物品语义，自动推荐最优交换路径（包括多跳交换链）
• 信任机制：评价体系 + AI 辅助物品鉴定 + 实名认证
• 低门槛：拍照即发布，AI 自动识别物品类别和估值
• 社区化：兴趣圈层推荐、交换故事分享

1.3 目标用户

• 有闲置物品想换有用之物的个人用户
• 手工/技能服务提供者（愿意用技能换物品）
• 二手爱好者、极简主义者
• 社区团购/邻里交换用户

1.4 关键约束

• 移动端优先（微信生态）
• 单用户并发 ≤ 5 个进行中交换
• 物品图片上限 9 张/件，单张 ≤ 2MB

二、功能架构

2.1 用户端（client/）

模块	功能	优先级
首页	推荐物品流、分类入口、搜索、附近的人	P0
发布	拍照/选图 → AI识别分类 → 填描述+期望交换物 → 发布	P0
物品详情	大图浏览、描述、发布者信息、交换意向按钮	P0
智能匹配	Agent 分析供需，推荐匹配列表，支持多跳交换链	P1
交换管理	交换请求列表、状态流转（待确认→进行中→已完成/取消）	P0
消息	交换双方即时沟通（IM）	P1
个人中心	我的物品、交换记录、评价、收藏、认证管理	P0
认证	微信授权登录 + 手机号绑定	P0
附近	LBS 附近物品发现（同城交换）	P2

2.2 管理后台（admin/）

模块	功能
物品审核	违规物品下架、分类纠偏、批量操作
用户管理	用户列表、封禁/解封、实名审核
交换仲裁	纠纷处理、强制取消、历史记录
数据看板	交换量、活跃用户、热门品类、匹配转化率
内容管理	Banner/公告/推荐位
系统配置	Agent 参数调优、匹配阈值、敏感词库

2.3 OpenClaw Agent 能力集成

Agent 能力	应用场景	详见
图像识别	上传物品照片 → Agent 识别品类、成色、品牌	Agent 协议
语义匹配	分析物品描述 → 匹配「我想要」和「我提供」的交叉需求	Agent 协议
多跳交换链	A→B→C 三人环形交换，Agent 自动发现并推荐	Agent 协议
智能估值	基于品类+成色+市场参考，给出建议交换价值区间	Agent 协议
安全风控	识别虚假物品、异常行为、违规图片/文字	§ 八

三、技术方案

3.1 技术栈

• 前端：React 18 + TypeScript + Vite + Ant Design Mobile 5 + Zustand + TanStack Query
• 管理后台：React 18 + TypeScript + Vite + Ant Design 5 + @ant-design/pro-components
• 后端：CloudBase 云函数（Node.js 18）+ @cloudbase/node-sdk
• 数据库：CloudBase NoSQL
• 存储：CloudBase 云存储（物品图片）
• AI：OpenClaw Agent API（图像识别/语义匹配/多跳推荐）
• 部署：EdgeOne Pages（前端）+ CloudBase（后端）

3.2 数据库设计（核心集合）

items（物品）
├── _id, owner_id, title, description
├── category, condition, images[]
├── want_description（期望交换物描述）
├── want_tags[]（AI 提取的期望标签）
├── location（地理坐标，用于附近搜索）
├── status（available/exchanged/offline/reviewing）
├── ai_tags[]（Agent 自动标签）
├── ai_estimated_value（AI 估值区间 {min, max}）
├── view_count, fav_count
├── created_at, updated_at

swaps（交换记录）
├── _id, from_item_id, to_item_id
├── from_user_id, to_user_id
├── status（pending/accepted/rejected/completed/cancelled/disputed）
├── messages[]（协商记录）
├── delivery_info（物流信息，可选）
├── rating_from, rating_to（双方互评）
├── created_at, updated_at

users（用户）
├── _id, wx_openid, phone, nickname, avatar
├── realname_verified（实名状态）
├── location（常用地址坐标）
├── rating, swap_count, fav_count
├── blacklist[]（黑名单用户）
├── created_at

reviews（评价）
├── _id, swap_id, reviewer_id, target_id
├── rating（1-5）, content, images[]
├── tags[]（快捷标签：准时/物品如描述/沟通愉快）
├── created_at

matches（Agent匹配结果 — 缓存）
├── _id, item_id, matched_items[]
├── match_type（direct/chain）
├── chain_path[]（多跳路径，chain 类型时）
├── score, reason
├── is_read
├── created_at, expires_at

notifications（通知）
├── _id, user_id, type, title, body
├── related_id（关联物品/交换ID）
├── is_read
├── created_at

3.3 API 设计（云函数路由）

# 物品
POST   /api/items          创建物品
GET    /api/items          物品列表（分页+筛选+排序）
GET    /api/items/:id      物品详情
PUT    /api/items/:id      编辑物品
DELETE /api/items/:id      下架物品
POST   /api/items/:id/fav  收藏/取消收藏
GET    /api/items/nearby   附近物品（LBS）

# 交换
POST   /api/swaps          发起交换
PUT    /api/swaps/:id/status  交换状态变更
GET    /api/swaps          我的交换列表
GET    /api/swaps/:id      交换详情
POST   /api/swaps/:id/dispute  发起纠纷

# Agent
POST   /api/agent/match    触发Agent匹配（参数：item_id）
GET    /api/agent/matches  获取匹配结果列表
POST   /api/agent/analyze  触发Agent物品分析（参数：image_urls[]）
POST   /api/agent/estimate 触发Agent估值（参数：item_id）

# 用户
POST   /api/auth/login     微信登录
POST   /api/auth/phone     手机号绑定
GET    /api/users/me       当前用户信息
PUT    /api/users/me       更新个人信息
GET    /api/users/:id      其他用户信息

# 评价
POST   /api/reviews        提交评价
GET    /api/reviews/:user_id 用户评价列表

# 通知
GET    /api/notifications  通知列表
PUT    /api/notifications/:id/read  标记已读

3.4 Agent 工作流

用户上传物品图片
  → POST /api/agent/analyze（图片URL数组）
  → Agent 识别：品类、品牌、成色、关键特征
  → 返回 ai_tags + 建议分类 + 估值区间
  → 用户确认/修改后发布

物品发布成功后
  → Agent 异步扫描全库物品的 want_description + want_tags
  → 计算匹配度（want ↔ have 交叉匹配）
  → 评估价格区间重叠度
  → 存储匹配结果到 matches 集合
  → 推送通知给双方

多跳交换链
  → Agent 构建物品交换图（节点=物品，边=可交换关系）
  → BFS/DFS 发现环形交换链（≥3人）
  → 按综合匹配度排序
  → 推荐给链条上的所有用户

详细 Agent 交互协议见 docs/agent-protocol.md

四、页面设计

详细 UI 设计规范见 docs/ui-requirements.md

4.1 首页

• 顶部搜索栏 + 分类标签 + 附近/推荐 Tab
• 瀑布流物品卡片（图片 + 标题 + AI标签 + 期望交换物简述 + 距离）
• 底部导航：首页 / 发布 / 消息 / 我的

4.2 发布页

• 图片上传区（支持多图，拍照/相册，上限9张）
• 图片上传后 → 显示「AI分析中…」→ 自动填充分类、标签、估值
• 标题输入（自动建议）
• 物品描述（纯文本，≤500字）
• 「我想换」描述输入 + 标签选择
• 地点选择（可选，开启附近搜索）
• 发布按钮

4.3 物品详情页

• 图片轮播（支持缩放）
• 物品信息卡片（分类、成色、AI标签、估值区间）
• 发布者信息 + 信誉分 + 实名标识
• 「我想换这个」按钮 → 选择我的一件物品发起交换
• 匹配推荐区：「你可能也感兴趣」
• 收藏按钮

4.4 交换管理页

• Tab：收到的请求 / 发出的请求 / 进行中 / 已完成 / 纠纷
• 每个交换卡片：双方物品缩略图 + 状态 + 操作按钮
• 状态流转可视化

4.5 个人中心

• 头像 + 昵称 + 信誉分 + 实名状态
• 我的物品 / 收藏 / 评价
• 交换统计（完成数、好评率）
• 设置（黑名单、隐私）

五、非功能需求

• 响应时间：首页加载 < 2s，Agent匹配 < 5s，图片上传 < 3s
• 并发：支持 1000 QPS
• 图片：自动压缩到 500KB/张，支持 WebP；原图保留用于详情
• 安全：内容审核（图片+文字），防刷，频率限制
• 微信适配：移动端优先，支持微信内H5
• 可用性：SLA ≥ 99.9%

六、里程碑

阶段	内容	预估
M1	PRD + UI原型 + Agent协议	本流水线
M2	前端 + 后端核心（发布/浏览/交换）	本流水线
M3	Agent集成（识别+匹配+估值）	后续迭代
M4	多跳交换链 + IM + 附近搜索	后续迭代
M5	性能优化 + 安全加固 + 正式上线	TBD

七、成功指标

• 发布量：上线首月 ≥ 500 件物品
• 匹配率：Agent 推荐匹配点击率 ≥ 30%
• 交换完成率：发起交换 → 完成 ≥ 50%
• 用户留存：次日留存 ≥ 40%
• 用户满意度：好评率 ≥ 4.5/5

八、安全与风控

8.1 内容安全

• 图片审核：接入内容安全 API，过滤违禁图片
• 文字审核：标题/描述敏感词过滤 + AI 辅助审核
• 发布冷却：同一用户 30s 内最多发布 1 件

8.2 交易风控

• 新用户限制：注册 24h 内最多发起 3 次交换
• 异常检测：短时间内大量发布/交换请求触发验证
• 黑名单机制：用户可主动拉黑，系统自动拉黑违规用户

8.3 数据安全

• 用户隐私：手机号脱敏展示，位置信息模糊化
• 通信加密：全链路 HTTPS
• 日志脱敏：敏感字段不记录明文

附录

• UI 设计需求文档
• Agent 交互协议