PolyHermes/docs/zh/crypto-tail-strategy-ui-spec.md

加密市场尾盘策略 - 前端 UI 规格

周期推导与市场数据获取详见 crypto-tail-strategy-market-data.md。

与现有跟单/回测保持同一风格（Ant Design、响应式、多语言），以下为页面结构及所含元素。

---

1. 导航与路由

项目	说明
菜单	在「跟单管理」同级或其下增加一项，如「尾盘策略」，key 建议 /crypto-tail-strategy。
路由	列表页 /crypto-tail-strategy；可选详情/触发记录 /crypto-tail-strategy/records/:id。

参考：Layout.tsx 中 /copy-trading、/backtest 的配置；App.tsx 中对应 Route。

---

2. 列表页（主页面）

路径：/crypto-tail-strategy
组件：如 CryptoTailStrategyList.tsx（或 TailStrategyList.tsx）。

2.1 顶部操作区

元素	类型	说明
页面标题	标题文案	如「加密尾盘策略」，用 t('cryptoTailStrategy.list.title')。
钱包使用提示	Alert（Warning）	必须在页面顶部或标题下方展示：提示用户使用单独/专用钱包运行本策略，避免该钱包用于手动交易、跟单等其他操作，否则可能导致余额或仓位变化，进而造成策略执行异常（如余额不足、下单失败等）。文案走多语言 t('cryptoTailStrategy.list.walletTip')，可带 showIcon。
新增策略	Button（Primary）	点击时先检查自动赎回相关配置（见 2.4）；若未配置则弹出「去配置」简易弹窗，若已配置则打开「新增策略」表单弹窗。图标可用 PlusOutlined。
筛选（可选）	Select / 筛选项	按账户、启用状态筛选；移动端可收起到抽屉或折叠。

2.2 列表内容（桌面端：Table，移动端：Card 列表）

列/卡片项	说明
策略名称	用户填的配置名或自动生成名。
关联市场	展示市场标题 + 周期，如「Bitcoin Up or Down - 5 minute」。
时间区间	如「3 分 0 秒 ~ 12 分 0 秒」（与周期类型一致：5min 为 0–5 分，15min 为 0–15 分）。
价格区间	如 [0.92, 1] 或「0.92 ~ 1」（maxPrice 为空时显示为 1）。
投入方式	「比例 10%」或「固定 100 USDC」，用 formatUSDC 格式化金额。
状态	Tag 或 Switch：启用 / 停用。
最近触发	最近一次触发时间（若有）；无则「-」。
操作	编辑、启用/停用、删除、查看触发记录。删除前 Popconfirm 二次确认。

2.3 与现有风格对齐

• 加载态：Spin 包裹列表。
• 空状态：无数据时展示空状态插画 + 引导「新增策略」。
• 响应式：useMediaQuery({ maxWidth: 768 })，桌面用 Table，移动用 Card + 操作折叠/抽屉。

参考：CopyTradingList.tsx 的 Table 列、Card 布局、筛选与 Modal 打开方式。

2.4 创建前检查：自动赎回配置（必须）

策略依赖自动赎回（需通过 Relayer/Builder API 提交链上赎回）。用户点击「新增策略」时：

1. 检查：请求系统配置（如 apiService.systemConfig.getConfig() 或已有接口），判断是否已配置 Builder API Key（及可选：自动赎回已开启）。若 builderApiKeyConfigured === false（或后端约定之「未配置」状态），视为未配置。
2. 未配置时：不打开新增策略表单，改为弹出简易弹窗（Modal），内容建议：
   • 标题：如「请先配置自动赎回」，t('cryptoTailStrategy.redeemRequiredModal.title')。
   • 正文：简短说明尾盘策略依赖自动赎回，需要先在「系统设置」中配置 Builder API Key 及自动赎回。文案 t('cryptoTailStrategy.redeemRequiredModal.description')。
   • 操作：
     • 去配置：主按钮，点击后关闭弹窗并跳转到系统设置页（如 /system-settings，该页含 Relayer 配置与自动赎回开关）。
     • 取消：次按钮或关闭图标，仅关闭弹窗。
3. 已配置时：正常打开新增策略表单弹窗。

弹窗保持简易，无需表单，仅提示 + 跳转；多语言键示例：cryptoTailStrategy.redeemRequiredModal.title、cryptoTailStrategy.redeemRequiredModal.description、cryptoTailStrategy.redeemRequiredModal.goToSettings、cryptoTailStrategy.redeemRequiredModal.cancel。

---

3. 新增 / 编辑策略弹窗（Modal）

组件：如 CryptoTailStrategyFormModal.tsx 或内嵌在列表页的 Modal。

3.1 表单字段

表单项	类型	必填	说明
钱包提示（简短）	Alert（Warning）	-	在「选择账户」上方或表单单列顶部展示简短提示：建议使用专用钱包，避免手动操作等导致异常。文案如 t('cryptoTailStrategy.form.walletTip')。
策略名称	Input	否	用于列表展示，可占位「自动生成」。
选择账户	Select	是	下拉已导入账户（与跟单一致，来自 useAccountStore() 或接口）。
选择市场	市场选择器	是	仅展示 5/15 分钟加密市场；支持搜索；展示市场标题 + 周期（5min/15min）；一个策略绑一个市场。
时间区间	开始 / 结束	是	仅在本周期内的该时间窗口内，价格满足时才下单；区间外不处理。见下方说明。
区间开始	下拉（分 + 秒）	是	从周期起点起算的「开始」偏移。5 分钟市场可选 0～5 分 + 0～59 秒（总不超过 5 分钟）；15 分钟市场可选 0～15 分 + 0～59 秒（总不超过 15 分钟）。
区间结束	下拉（分 + 秒）	是	从周期起点起算的「结束」偏移。范围同上，且区间开始不得大于区间结束（前端校验）。
最低价 minPrice	InputNumber	是	0～1，精度 2～4 位小数；校验 minPrice ≤ 1。
最高价 maxPrice	InputNumber	否	0～1，占位「不填默认为 1」；若填则校验 minPrice ≤ maxPrice ≤ 1。
投入方式	Radio.Group	是	选项：「按比例」「固定金额」。
比例 %	InputNumber	条件必填	选「按比例」时显示；0～100；可展示当前账户 USDC 余额与预估金额。
固定金额 (USDC)	InputNumber	条件必填	选「固定金额」时显示；≥ 最小下单额，≤ 账户余额；用 formatUSDC 展示。
启用状态	Switch	否	新增默认开启；编辑可切换。

时间区间说明：例如 15 分钟市场配置「3 分 0 秒」～「12 分 0 秒」，表示从周期开始后第 3 分钟到第 12 分钟之间，若价格进入 [minPrice, maxPrice] 才下单；第 0～3 分钟、第 12～15 分钟即使价格满足也不下单。5 分钟市场同理，可选 0～5 分钟内的一段（如 0～2、2～5）。前端用下拉选择「分钟」+「秒」，后端存为相对周期起点的秒数（如 windowStartSeconds、windowEndSeconds）。

3.2 校验与提交

• 提交前：市场为 5/15 分钟、时间区间开始 ≤ 时间区间结束、时间区间不超出周期长度（5min 市场结束 ≤ 5 分 0 秒，15min 市场结束 ≤ 15 分 0 秒）、minPrice 合法、maxPrice 若填则 ≥ minPrice、余额/比例合法。
• 提交后：关闭弹窗、刷新列表、message.success；失败在表单上展示接口错误信息。

参考：CopyTradingOrders/AddModal.tsx 的 Form 布局、Form.Item + rules、条件显示（比例/固定金额）。

---

4. 触发记录

入口：列表行操作「查看触发记录」或单独 Tab/页。

4.1 展示方式（二选一或并存）

• 弹窗：Modal 内 Table，按策略 ID 拉取该策略的触发记录。
• 独立页：路由如 /crypto-tail-strategy/records/:strategyId，页面内 Table 或 Card 列表。

4.2 记录列表字段

列/项	说明
触发时间	时间戳格式化为本地时间。
市场	市场标题 + 周期。
方向 (outcome)	Up / Down。
触发价格	当时进入区间的价格。
投入金额	USDC，用 formatUSDC。
订单 ID	若有；可截断 + Tooltip 全量。
状态	成功 / 失败。

支持按时间范围、状态筛选；移动端用 Card 或折叠列表。

---

5. 组件与技术要点

要点	说明
钱包提示	列表页与新增/编辑表单必须包含「使用单独钱包」的 Alert 提示，避免用户用混用钱包导致异常；文案走多语言。
创建前检查	点击「新增策略」时先检查自动赎回/Builder API 是否已配置；未配置则弹出简易「去配置」弹窗，引导用户到系统设置配置 API Key 与自动赎回，不打开策略表单。
多语言	所有文案 t('cryptoTailStrategy.xxx')，在 locales/zh-CN、zh-TW、en 的 common.json 中增加键。需包含：cryptoTailStrategy.list.walletTip、cryptoTailStrategy.form.walletTip，以及 cryptoTailStrategy.redeemRequiredModal.title、cryptoTailStrategy.redeemRequiredModal.description、cryptoTailStrategy.redeemRequiredModal.goToSettings、cryptoTailStrategy.redeemRequiredModal.cancel。文案示例：列表页 walletTip：「请使用单独的钱包运行尾盘策略，避免该钱包用于手动交易、跟单等其他操作，否则可能导致余额或仓位变化，造成策略执行异常。」表单内 walletTip：「建议使用专用钱包，避免手动操作等导致余额或下单异常。」未配置赎回弹窗 title：「请先配置自动赎回」；description：「尾盘策略依赖自动赎回功能，请先在系统设置中配置 Builder API Key 并开启自动赎回。」；goToSettings：「去配置」；cancel：「取消」。
金额	统一 formatUSDC（见 frontend.mdc）。
响应式	useMediaQuery；按钮触摸目标 ≥ 44px；移动端主操作突出。
类型	不用 any；为策略、触发记录定义 TypeScript 类型。
API	通过 apiService 封装（如 apiService.cryptoTailStrategy.list/create/update/delete/records）。

---

6. 页面与文件建议对应

功能	建议路径/文件
列表页	frontend/src/pages/CryptoTailStrategyList.tsx
未配置赎回时的简易弹窗	内嵌在列表页的 Modal，或 CryptoTailStrategyList/RedeemRequiredModal.tsx
新增/编辑弹窗	frontend/src/pages/CryptoTailStrategyList/FormModal.tsx 或内嵌 Modal
触发记录	frontend/src/pages/CryptoTailStrategyList/TriggerRecordsModal.tsx 或 CryptoTailStrategyRecords.tsx
路由	App.tsx 中 /crypto-tail-strategy、可选 /crypto-tail-strategy/records/:id
菜单	Layout.tsx 中增加「尾盘策略」菜单项
类型	frontend/src/types/index.ts 或 types/cryptoTailStrategy.ts 中增加策略与触发记录类型
多语言	frontend/src/locales/{zh-CN,zh-TW,en}/common.json 中增加 cryptoTailStrategy.*

---

7. 小结：UI 包含的主要元素

• 导航：主导航中「尾盘策略」入口。
• 列表页：标题、钱包提示 Alert、新增按钮（点击前先检查赎回配置，未配置则弹「去配置」简易弹窗）、筛选、表格/卡片（策略名、市场、价格区间、投入方式、状态、最近触发、操作）、加载与空状态。
• 未配置赎回弹窗：简易 Modal，提示依赖自动赎回、需先配置 Builder API Key 与自动赎回；按钮「去配置」（跳转 /system-settings）、「取消」。
• 表单弹窗：策略名、账户、市场选择、minPrice/maxPrice、投入方式（比例/固定）、启用开关、提交/取消。
• 触发记录：时间、市场、outcome、触发价格、金额、订单 ID、状态；支持弹窗或独立页。
• 通用：Ant Design 组件、响应式、多语言、formatUSDC、TypeScript 类型。

---

附录 A 后端/产品要求：自动赎回须支持本策略仓位

自动赎回逻辑必须支持赎回由尾盘策略产生的订单所对应的仓位。即：本策略触发的市价买入会形成仓位，这些仓位在满足「可赎回」条件时，应被纳入现有自动赎回流程并正常发起赎回，不得因来源为「尾盘策略」而被排除。后端实现时需保证：

• 尾盘策略下单产生的仓位，与跟单/手动下单等来源的仓位一视同仁，参与可赎回查询与批量赎回；
• 若当前自动赎回按账户或仓位类型过滤，需将「尾盘策略订单产生的仓位」包含在内。

这样前端所依赖的「自动赎回」对该策略才完整有效。