# Genex 平台 - UI设计需求文档

> 基于《软件需求规格 v4.1》提取的全部界面设计需求。所有界面遵循 **Web2体验原则**：零区块链术语，与支付宝/Zelle一致的使用体验。

---

## 设计原则

1. **零区块链感知**：用户界面不出现"钱包/链上/Gas/哈希/NFT"等术语
2. **术语映射**：我的券（非NFT）、订单号（非TX Hash）、余额（非USDC）、转赠（非Transfer）
3. **3秒规则**：核心操作（购买/核销/转赠）3步以内完成
4. **信息层级**：关键信息一屏可见，详情按需展开
5. **AI Agent优先**：所有端深度融合AI Agent，AI作为用户管理和使用券资源的核心助手

---

## AI Agent 设计规范

> 所有客户端（消费者端、商户端、发行方管理端、Web管理端、小程序/H5）均深度融合AI Agent，用于协助用户使用和管理平台全部券资源。

### 总体设计原则

1. **全局入口**：所有端右下角悬浮AI助手按钮（可拖拽），点击展开对话面板
2. **上下文感知**：AI Agent感知当前页面、用户身份、持券状态、交易历史，主动提供相关建议
3. **自然语言交互**：支持文字和语音输入，理解券交易领域语义
4. **操作代理**：AI不仅提供建议，还可代用户执行操作（需用户确认）
5. **多模态理解**：支持截图识别券信息、拍照识别线下优惠券导入

### AI Agent 通用UI组件

| 组件 | 说明 | 交互 |
|------|------|------|
| **悬浮入口按钮** | 圆形AI图标按钮，右下角悬浮，显示未读建议数量红点 | 点击展开对话面板，长按显示快捷操作 |
| **对话面板** | 底部Sheet或侧边抽屉，支持文字/语音输入 | 流式输出回答，支持富文本（券卡片、图表、操作按钮） |
| **快捷建议条** | 页面顶部/底部横向滚动的AI建议标签 | 如"这张券3天后到期，建议今天使用"，点击执行建议 |
| **智能卡片** | AI主动推送的建议卡片，嵌入信息流 | 出现在首页Feed、我的券列表中，可关闭/执行 |
| **操作确认弹窗** | AI代理执行操作前的二次确认 | 展示操作详情，用户确认后执行 |

### 各端AI Agent功能

#### 消费者端AI Agent

| 场景 | AI能力 | UI表现 |
|------|--------|--------|
| **智能选券** | 根据用户偏好、消费记录、位置推荐最优券 | 首页智能推荐Feed + 对话中推荐券卡片 |
| **价格顾问** | 分析券价格走势，提示最佳买入/卖出时机 | 券详情页AI价格趋势分析标签 + "AI建议：当前价格偏低，适合买入" |
| **到期管理** | 追踪所有持券到期时间，按紧迫度提醒 | 我的券列表中AI排序"即将到期优先"，推送提醒卡片 |
| **出售定价** | 基于市场供需和历史成交，建议挂单价格 | 出售页面中AI建议价格标签 + 价格解释 |
| **使用规划** | 根据行程/位置智能规划券使用顺序 | "您附近有3家可使用门店，建议路线：..." |
| **自然语言搜索** | "帮我找200元以下的星巴克券" | 对话面板中返回筛选后的券卡片列表 |
| **交易助手** | 自动比价、批量操作、组合购买建议 | "同类券在二级市场更便宜，要看看吗？" |
| **资产报告** | 生成个人券资产报告（总价值、收益率、使用率） | 周/月报告推送，可视化图表 |

#### 商户端AI Agent

| 场景 | AI能力 | UI表现 |
|------|--------|--------|
| **核销辅助** | 异常券实时识别（过期/已用/非本店）、快速提示 | 核销时AI红色警示标签 |
| **客流预测** | 基于历史核销数据预测当日/本周客流量 | 仪表盘AI预测卡片 |
| **问题解答** | 回答核销操作疑问、离线模式说明 | 对话面板 |

#### 发行方管理端AI Agent

| 场景 | AI能力 | UI表现 |
|------|--------|--------|
| **发券建议** | 分析市场趋势，建议发券时间/面值/折扣/数量 | 发券中心顶部AI建议卡片 |
| **定价优化** | 基于三因子模型 + AI定价引擎，提供最优定价策略 | 创建券时AI推荐价格 + 对比分析 |
| **信用提升** | 分析信用评分各维度，给出提升建议 | 信用等级页面AI改善建议列表 |
| **销售分析** | 智能解读销售数据，发现异常和机会 | 数据中心AI洞察卡片 |
| **额度规划** | 预测发行额度消耗速度，建议补充计划 | 额度页面AI规划时间线 |
| **合规助手** | 提醒合规要求，辅助材料准备 | 入驻审核时AI检查清单 |

#### Web管理端AI Agent

| 场景 | AI能力 | UI表现 |
|------|--------|--------|
| **风险预警** | 实时检测异常交易模式，自动预警 | 风控仪表盘AI警告卡片 + 处理建议 |
| **审核辅助** | AI预审发行方资料/券信息，标记风险点 | 审核页面AI评分+风险标签 |
| **合规报告** | 自动生成SAR/CTR/监管报表草稿 | 合规报表页AI生成按钮 |
| **运营洞察** | 分析平台运营数据，提出优化建议 | Dashboard AI洞察面板 |
| **智能搜索** | 自然语言查询用户/订单/交易 | "查找过去7天金额超过5000的可疑交易" |
| **决策支持** | 手续费率调整建议、额度配置建议 | 系统配置页AI建议标签 |

#### 小程序/H5 AI Agent

| 场景 | AI能力 | UI表现 |
|------|--------|--------|
| **轻量推荐** | 基于分享来源和用户标签快速推荐 | 首页精简推荐条 |
| **购买引导** | 引导新用户完成首次购买 | 对话气泡式引导 |

---

## A. 消费者端（Consumer App）— Flutter

### A1. 注册/登录模块

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **欢迎页** | 品牌Logo、Slogan、「手机号注册」「邮箱注册」按钮、社交登录入口（Google/Apple） | 启动页→欢迎页→注册 |
| **手机号注册** | 手机号输入、获取验证码、验证码输入、设置密码、用户协议勾选 | 注册成功后后台静默创建MPC钱包 |
| **邮箱注册** | 邮箱输入、获取验证码、设置密码 | 同上 |
| **登录** | 手机号/邮箱+密码、忘记密码、验证码快捷登录 | |
| **忘记密码** | 手机号/邮箱验证→重置密码 | |

### A2. 首页/市场模块

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **首页** | 搜索栏、Banner轮播（推荐券/活动）、热门分类（餐饮/购物/娱乐/出行）、精选券列表、底部Tab导航 | Tab：首页/市场/我的券/消息/我的 |
| **市场（交易大厅）** | 分类筛选（行业/品牌/折扣范围）、排序（价格/折扣率/到期时间）、券卡片列表（图片+品牌+面值+当前价+折扣率+到期时间） | 一级市场（全新）+二级市场（转售）标签切换 |
| **券详情页** | 券图片、品牌Logo、面值、当前价格、折扣率（如"8.5折"）、有效期、使用条件、使用门店、发行方信用等级（如AAA）、「立即购买」「加入收藏」按钮、价格走势图（可选）、历史成交价、同类券推荐 | |
| **搜索结果** | 搜索框+筛选器+结果列表 | 支持品牌、券名称、分类搜索 |

### A3. 购买流程

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **确认订单** | 券信息摘要、数量选择、价格计算（单价×数量）、支付方式选择 | |
| **支付** | 银行卡/信用卡/Apple Pay选择、支付确认（密码/指纹/Face ID） | 后台：法币→USDC→Settlement合约 |
| **支付成功** | 成功动画、订单号（如GNX-20260209-001234）、「查看我的券」「继续逛」 | |

### A4. 我的券模块

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **我的券列表** | 券卡片（图片+品牌+面值+状态+到期倒计时）、筛选（全部/可使用/待使用/已过期）、批量操作 | 状态标签：可使用/待核销/已过期 |
| **券详情** | 券二维码/条形码（核销用）、券信息、使用说明、「转赠」「出售」「使用说明」按钮 | |
| **转赠流程** | 输入对方手机号/邮箱、确认转赠、安全验证（密码/指纹）、成功页 | 后台：手机号→地址解析→P2P链上转移 |
| **出售挂单** | 设定售价（系统提示建议价格和面值上限）、确认挂单 | Utility Track价格 ≤ 面值 |
| **提取到外部钱包** | 输入外部钱包地址、确认提取、风险提示（提取后平台不再托管） | 需KYC L2+ |

### A5. 交易模块（二级市场）

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **我的挂单** | 挂单列表（券信息+挂单价+状态+挂单时间）、撤单按钮 | |
| **我的交易记录** | 买入/卖出记录、成交价、时间、状态、订单号 | |
| **求购（可选P2）** | 设定求购券品牌+价格+数量 | 延后实现 |

### A6. 账户模块

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **我的余额** | 总余额（美元显示）、可提现金额、冻结金额、「充值」「提现」按钮 | 后台聚合链上+链下余额 |
| **充值** | 选择支付方式、输入金额、确认 | |
| **提现** | 输入提现金额、选择银行卡、确认 | T+1到账 |
| **交易记录** | 时间线列表（买入/卖出/转赠/核销/充值/提现），每条含订单号、金额、状态 | |

### A7. 个人中心

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **个人主页** | 头像、昵称、KYC等级标识、信用积分 | |
| **KYC认证** | 当前等级、升级引导（L0→L1→L2→L3）、身份证/护照上传、人脸识别 | |
| **支付管理** | 已绑定银行卡列表、添加银行卡 | 需KYC L2 |
| **设置** | 通知设置、语言切换、安全设置（修改密码/支付密码）、「高级设置」（Pro模式入口）、关于、退出登录 | |
| **Pro模式设置** | 开启说明、风险提示确认、WalletConnect连接、链上地址显示、交易哈希查看 | 默认隐藏，设置→高级 |

### A8. 消息模块

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **消息列表** | 交易通知、系统公告、券到期提醒、价格提醒 | 分类Tab |
| **消息详情** | 消息内容、关联操作跳转 | |

---

## B. 商户核销端（Merchant App）— Flutter

### B1. 登录与权限

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **员工登录** | 手机号+密码/验证码、门店选择（多门店员工） | 权限：收银员(仅核销)/店长(核销+数据)/管理员(全部) |

### B2. 核销模块

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **扫码核销**（主页） | 大面积扫码区域、手电筒开关、「手动输码」入口 | 扫码→显示券信息→确认核销→成功/失败提示 |
| **券信息确认** | 券名称、面值、有效期、使用条件、消费者头像/昵称、「确认核销」按钮 | 核销≤3秒 |
| **核销成功** | 成功动画、券信息摘要、「继续核销」 | |
| **手动输码** | 券码输入框、「查询」按钮 | 扫码设备故障时备用 |
| **离线核销提示** | 网络状态标识（在线/离线）、离线核销说明、待同步数量标记 | 断网自动切换离线模式 |

### B3. 核销记录

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **核销记录列表** | 时间、券名、面值、核销员、状态（已同步/待同步） | 筛选：今日/本周/自定义时间 |
| **待同步队列** | 离线核销待上链的记录、「手动同步」按钮 | 联网后自动同步 |

### B4. 门店数据（店长权限）

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **门店仪表盘** | 今日核销笔数/金额、本周趋势图、核销员排行 | |

---

## C. 发行方管理后台App（Issuer Console）— Flutter

### C1. 发行方入驻

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **企业注册** | 企业名称、营业执照上传（OCR识别）、联系人信息、法人信息 | |
| **审核状态** | 审核进度条（已提交→审核中→已通过/已驳回）、驳回原因 | |

### C2. 发券中心

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **券模板选择** | 预设模板卡片（满减券/折扣券/礼品卡/储值券）、模板预览 | |
| **创建券活动** | 券名称、面值、发行价格（折扣率）、有效期、使用条件描述、券封面图上传、发行数量 | 发行方视角：创建"优惠活动" |
| **规则配置** | 7项可配置规则（可转让/转售次数/人群限定/限购数量/门店限定/叠加使用/最低消费）、开关+输入表单 | Web2界面，无合约参数 |
| **预览与提交** | 券预览卡片、规则摘要、发行费用提示、「提交审核」 | 审核通过后自动链上铸造+上架 |
| **券管理列表** | 券名、状态（审核中/已上架/已下架/已售罄）、发行量/已售/已核销/已过期统计 | |
| **券详情管理** | 券信息、下架/召回操作、补充发行 | |

### C3. 核销管理

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **核销概览** | 今日/本周/本月核销统计、核销趋势图 | |
| **门店管理** | 门店列表（总部→区域→门店树形结构）、添加门店、门店核销权限配置 | |
| **员工管理** | 员工列表、角色分配（收银员/店长/管理员） | |

### C4. 财务管理

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **收入概览** | 总销售额、已到账金额、待结算金额、Breakage收入 | 法币视图 |
| **提现** | 可提现金额、银行账户选择、提现申请 | |
| **对账报表** | 日/月对账单、交易流水、导出 | |

### C5. 数据中心

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **仪表盘** | 发行量/销量/兑付率/Breakage率/流通中数量 实时图表 | |
| **销售分析** | 按时间/按券类型/按门店 分析 | |
| **用户画像** | 购买用户分布（仅汇总数据，不含个人信息） | |

### C6. 信用与额度

| 页面 | 核心元素 | 交互说明 |
|------|---------|---------|
| **信用等级** | 当前等级（如AA）、评分详情（核销率/沉淀率/满意度/存续时长）、提升建议 | |
| **发行额度** | 当前额度/已用额度/剩余额度、额度变动历史 | |

---

## D. Web管理前端（Platform Admin）— React + Next.js

### D1. 平台运营仪表盘

| 页面 | 核心元素 |
|------|---------|
| **总览Dashboard** | 平台总交易量/金额、活跃用户数、发行方数量、券流通总量、实时交易流、系统健康状态 |

### D2. 发行方管理

| 页面 | 核心元素 |
|------|---------|
| **入驻审核列表** | 待审核/已通过/已驳回列表、审核详情（企业资料、工商数据校验结果） |
| **发行方详情** | 企业信息、信用评级、发行记录、违规记录、操作（升级/降级/冻结/解冻） |
| **券审核列表** | 待审核券列表、券信息预览、审核通过/驳回 |

### D3. 用户管理

| 页面 | 核心元素 |
|------|---------|
| **用户列表** | 搜索（手机号/邮箱/用户ID）、KYC等级筛选、用户详情入口 |
| **用户详情** | 基本信息、KYC状态、持券列表、交易记录、风险标签 |
| **KYC审核** | 待审核KYC申请、证件照片查看、人脸比对结果、通过/驳回 |

### D4. 交易监控

| 页面 | 核心元素 |
|------|---------|
| **实时交易流** | 交易实时滚动列表、大额交易高亮 |
| **交易统计** | 交易量/金额趋势、各类型交易占比、平均折扣率 |
| **订单管理** | 订单搜索、订单详情、争议订单标记 |

### D5. 风控中心

| 页面 | 核心元素 |
|------|---------|
| **风险仪表盘** | 风险事件数量、可疑交易数量、冻结账户数量 |
| **可疑交易** | 可疑交易列表（异常模式、大额、高频）、处理操作（标记/冻结/上报SAR） |
| **黑名单管理** | 黑名单列表（用户/地址）、添加/移除 |
| **OFAC筛查日志** | 筛查记录、命中记录、处理状态 |

### D6. 合规报表

| 页面 | 核心元素 |
|------|---------|
| **SAR管理** | 可疑活动报告列表、生成SAR、提交状态 |
| **CTR管理** | 大额交易报告、自动生成 |
| **审计日志** | 全链路操作日志搜索、导出 |
| **监管报表** | 日报/月报自动生成、下载 |

### D7. 系统管理

| 页面 | 核心元素 |
|------|---------|
| **管理员账号** | 管理员列表、角色权限配置（RBAC）、操作日志 |
| **系统配置** | 手续费率设置、KYC阈值配置、交易限额配置 |
| **合约管理** | 合约部署状态、升级提案管理、升级日志 |
| **系统监控** | 服务健康检查、API响应时间、Genex Chain节点状态 |

### D8. 争议处理

| 页面 | 核心元素 |
|------|---------|
| **工单列表** | 争议工单（买方申诉/卖方申诉/退款申请）、状态、处理时效 |
| **工单详情** | 双方信息、链上交易记录（作为证据）、仲裁操作 |

---

## E. 小程序 + H5

> 消费者端的轻量版，核心购买和查看功能。

### E1. 小程序核心页面

| 页面 | 说明 |
|------|------|
| **首页** | 同Consumer App首页，精简版（热门券+分类入口） |
| **券详情+购买** | 同App，微信支付/支付宝支付 |
| **我的券** | 券列表+券码展示（核销用） |
| **我的订单** | 订单列表 |

### E2. H5页面

| 页面 | 说明 |
|------|------|
| **券分享页** | 券信息展示+「打开App购买」/「小程序购买」引导 |
| **活动落地页** | 发行方推广活动入口页 |
| **注册引导页** | 未注册用户引导注册 |

---

## F. 通用组件库

| 组件 | 说明 | 使用端 |
|------|------|--------|
| **券卡片** | 券封面图+品牌+面值+折扣率+到期时间 | 全端 |
| **价格标签** | 当前价格（大字）+ 原价删除线 + 折扣标签 | 全端 |
| **信用等级徽章** | AAA/AA/A/BBB/BB颜色标识 | 全端 |
| **KYC等级标识** | L0/L1/L2/L3徽章 | 消费者端+管理端 |
| **交易状态标签** | 处理中/已完成/已取消/退款中 颜色标签 | 全端 |
| **空状态页** | 各场景的空状态插画+引导操作 | 全端 |
| **加载/骨架屏** | 列表加载、详情加载 | 全端 |
| **底部Sheet** | 支付确认、转赠确认等操作确认 | 移动端 |
| **Toast/Snackbar** | 操作反馈提示 | 全端 |

---

## G. 核心用户流程图

### G1. 消费者购买券

```
首页浏览 → 券详情 → 立即购买 → 确认订单 → 选择支付 → 支付验证 → 成功
                                                                    ↓
                                                            我的券（可查看）
```

### G2. 消费者转赠券

```
我的券 → 选择券 → 转赠 → 输入对方手机号 → 安全验证 → 成功
```

### G3. 消费者出售券

```
我的券 → 选择券 → 出售 → 设定价格（≤面值提示） → 确认挂单 → 等待成交
```

### G4. 消费者使用券（线下）

```
我的券 → 选择券 → 出示券码（二维码/条形码） → 商户扫码核销 → 核销成功通知
```

### G5. 发行方发券

```
登录后台 → 发券中心 → 选择模板 → 填写券信息+规则 → 预览 → 提交审核
                                                                ↓
                                                    审核通过 → 自动铸造上架
```

### G6. 商户核销

```
打开核销App → 扫码 → 确认券信息 → 核销 → 成功
                ↓ (断网)
            离线验证 → 暂存 → 联网后自动同步
```

---

---

## H. AI Agent 技术架构要求

### H1. 前端集成架构

```
┌──────────────────────────────────┐
│          UI Layer (各端)          │
│  悬浮按钮 / 对话面板 / 建议卡片    │
├──────────────────────────────────┤
│       AI Agent SDK (统一)         │
│  对话管理 / 上下文组装 / 流式渲染   │
├──────────────────────────────────┤
│       Agent Gateway API          │
│  WebSocket(实时) / REST(批量)     │
├──────────────────────────────────┤
│     Backend AI Agent Service     │
│  LLM编排 / RAG / 工具调用 / 记忆   │
└──────────────────────────────────┘
```

### H2. 上下文数据协议

AI Agent需要的上下文数据（前端组装后发送至后端Agent Service）：

| 上下文字段 | 说明 | 来源 |
|-----------|------|------|
| `user_profile` | 用户身份、KYC等级、偏好 | 本地缓存 + API |
| `current_page` | 当前页面路由和关键参数 | 路由状态 |
| `coupon_portfolio` | 用户持券列表摘要 | 本地状态 |
| `recent_actions` | 最近10条操作记录 | 本地记录 |
| `market_snapshot` | 当前市场热门/价格摘要 | API缓存 |
| `location` | 用户位置（如授权） | 设备GPS |

### H3. AI Agent 操作能力（Tool Calling）

AI Agent可代用户执行的操作（均需用户确认）：

| 操作 | 描述 | 适用端 |
|------|------|--------|
| `search_coupons` | 按条件搜索券 | 消费者/小程序 |
| `get_price_analysis` | 获取券价格分析 | 消费者/发行方 |
| `create_sell_order` | 创建出售挂单 | 消费者 |
| `suggest_pricing` | 获取AI定价建议 | 发行方 |
| `generate_report` | 生成数据报告 | 发行方/管理端 |
| `query_transactions` | 查询交易记录 | 全端 |
| `risk_assessment` | 风险评估 | 管理端 |
| `compliance_check` | 合规检查 | 管理端 |

---

---

## I. Utility Track / Securities Track UI隔离设计

> SRS 1.6要求：Utility Track和Securities Track使用不同的交易市场界面（前端隔离）。当前仅开放Utility Track，Securities Track待牌照后启用。

### I1. 双轨UI隔离原则

| 维度 | Utility Track（消费型券） | Securities Track（投资型券） |
|------|--------------------------|---------------------------|
| **市场入口** | 默认市场（首页即Utility市场） | 独立入口（需KYC L2+才可见） |
| **价格展示** | 显示"折扣价"标签，面值上限提示 | 显示价格走势、K线图、涨跌幅 |
| **挂单界面** | 价格输入上限=面值，自动校验 | 无价格上限，自由定价 |
| **交易提示** | "您正在购买消费券用于消费" | "您正在进行投资交易，有亏损风险" |
| **转售计数** | 显示"剩余可转售X次" | 不显示限制 |
| **合规标识** | "消费券"标签（绿色） | "投资券"标签（橙色）+ 风险警示 |
| **KYC要求** | 交易前提示升级KYC L1 | 交易前提示升级KYC L2+ |

### I2. 当前阶段处理

```
当前阶段（Utility Track）：
- 默认展示Utility Track市场
- Securities Track入口通过配置开关控制（待牌照后启用）
- 所有挂单价格自动校验 ≤ 面值
- 券详情页不显示"投资收益"相关信息
```

### I3. 关键UI差异点

| 页面 | Utility Track | Securities Track（预留） |
|------|--------------|------------------------|
| **券详情页** | 面值、折扣价、使用条件、发行方信用、到期日 | 同左 + 价格历史K线 + 涨跌幅 + 收益率 |
| **出售页面** | 价格滑块上限=面值，溢价时红色提示 | 无价格限制，显示市场参考价 |
| **持有目的声明** | 购买时弹窗确认"购买用于消费" | 购买时弹窗确认"我了解投资风险" |
| **我的券列表** | 标签：消费券（绿） | 标签：投资券（橙） |

---

*文档版本: v1.2*
*基于: Genex 券交易平台 - 软件需求规格说明书 v4.1*
*更新: 增加AI Agent深度融合设计规范、Utility/Securities Track UI隔离设计*