## 📋 Crawlful Hub Console 前端开发实施清单 (V32.0 - Sovereign Edition)

> **目标**：在 V32.0 主权网络架构下，将 Console 从“管理后台”升级为“AGI 决策终端”。前端需深度对齐 **Suggestion-First (建议优先)** 哲学，确保分布式节点、隐私声誉与因果链在 UI 层实现 100% 闭环。

---

### 1. 核心业务主线对齐 (V32.0 增量)

- **主线 A：采集 → AGI 建议包 (Advice Hub) → 决策执行**
  - **Extension 采集**：支持在插件端实时接收 [AdviceService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Strategy/AdviceService.ts) 推送的 `ActionableInsight`。
  - **Console 决策**：实现统一的 `AdviceCenter` 页面，支持对 `PRICING`, `INVENTORY`, `LOGISTICS`, `SUPPLIER` 等多维建议的批量审核。
  - **沉浸式控制**：引入 `Omni-Box` (AGI 指令终端)，支持用户通过自然语言调整全局策略参数。
- **主线 B：多端业务管理 (Multi-Channel Management)**
  - **TOC 零售**：实现基于订单流的消费者运营看板，联动售后 RAG 自动回复。
  - **独立站/直接站**：提供 Shopify 等站点的健康度遥测与跨域名流量资产同步 UI。
  - **TOB 批发**：构建 RFQ (询价单) 工作台与大客户信用分级视图，支持阶梯报价编辑器。
- **主线 C：ERP 执行中枢 (ERP Core Execution)**
  - **SKU 管理**：实现多维属性编辑器、多平台 SKU 映射矩阵、多媒体资产管理 (DAM)。
  - **采购与寻源**：支持从 AGI 建议一键转 PO，集成到货质检 (QC) 与入库流程。
  - **仓储 (WMS)**：实现可视化库位管理、拣货路径预览与循环盘点交互。
  - **物流 (Logistics)**：提供多渠道实时比价、打单发货工作台与全链路轨迹遥测。
- **主线 D：主权网络 (Sovereign Network) 治理**
  - **节点发现与握手**：实现 `FederatedNodePage`，展示 DID 身份握手过程与连接状态。
  - **隐私声誉可视化**：基于 [ReputationZKPService.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/ai/ReputationZKPService.ts) 的数据，渲染节点的信用等级与 ZKP 证明状态。
  - **P2P 拓扑遥测**：利用 G6 渲染全球节点拓扑图，展示实时延迟 (Latency) 与跳数 (Hops)。
- **主线 D：异常感知与 AGI 自愈 (Self-Healing)**
  - **插件自愈反馈**：插件端检测到页面结构变化（Selector 失效）时，通过 `reportAnomaly` 接口上报。
  - **运维视图**：在 Console 展示自愈动作（Heal Action）的执行过程，包含“根因分析 (RCA)”与“修复建议”。

---

### 2. 前后端契约与枚举规范 (Single Source of Truth)

- **状态机对齐 (FSM)**：
  - **Advice 状态**：`PENDING` (待审) / `APPROVED` (已准) / `EXECUTING` (执行中) / `EXECUTED` (已闭环) / `IGNORED` (已忽略)。
  - **Node 状态**：`DISCOVERED` / `HANDSHAKING` / `VERIFIED` / `REJECTED` / `OFFLINE`。
- **全局枚举下发**：
  - 前端禁止硬编码业务枚举，必须通过 `ConfigController` 动态获取后端定义的 `ActionableInsightType` 与 `ReputationLevel`。
- **动作门禁 (Action Guards)**：
  - 只有 `PENDING` 状态的建议才显示“Approve/Reject”按钮；只有 `VERIFIED` 状态的节点才允许执行“Resource Sharing”。

---

### 3. UI/UX 核心组件标准 (V32.0 规格)

- **SuggestionCard (建议卡片)**：
  - 必须包含：建议标题、信心指数 (Confidence)、影响评估 (Impact: High/Med/Low)。
  - 必须包含：[RobotOutlined] 图标，标注“AGI 建议”。
- **CausalChainView (因果链视图)**：
  - 联动 [DecisionExplainabilityEngine.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/ai/DecisionExplainabilityEngine.ts)。
  - 通过步骤条或折叠面板展示决策背后的核心权重因子（如：库存占用 > 60%, 利润率 < 15%）。
- **SovereignTelemetry (主权遥测)**：
  - 展示跨节点通信的延迟波动图。
  - 展示 ZKP 证明的生成与校验时间。

---

### 4. 跨端通讯与 API 调用层 (V32.0 加固)

- **统一 Header 注入**：
  - `x-tenant-id`：多租户隔离唯一标识。
  - `x-trace-id`：全链路追踪 ID（格式：`trace_ext_${timestamp}` 或 `trace_con_${timestamp}`）。
  - `Authorization`：Bearer Token（含租户与角色信息）。
- **插件-Console 消息桥接**：
  - 实现 `AUTH_SYNC` 逻辑：Console 登录成功后自动将 Token 同步至插件 `chrome.storage.local`。
  - 实现 `GET_ADVICE` 逻辑：插件端基于当前 URL 的 `productId` 主动查询针对性建议。

---

### 5. 质量红线与交付标准 (🛡️ Verified)

- **Zero-Mock Policy (严禁 Mock)**：
  - 生产代码中严禁使用 `setTimeout` 模拟数据，所有数据必须来自 `cf_` 数据库或后端 API。
- **Deploy-Ready (部署即运行)**：
  - `completed` 的标志是：前端页面已挂载、API 契约已对齐、因果链可回溯。
- **可观测性要求**：
  - 每一个按钮点击必须在后端生成 `AuditLog`。
  - 每一个 API 错误必须展示对应的 `traceId` 供运维下钻。

---

### 6. ERP 级业务交互补充 (Orders / WMS / Finance)

- **订单中心 (OMS) 前端职责**
  - 实现统一的「订单工作台」：支持按渠道 (Temu / TikTok / Shopee / 自营站等)、店铺、时间、状态多维筛选。
  - 支持从订单列表一键联动：售后工单、物流轨迹、发票 / 对账详情。
  - 提供批量操作：批量审核、批量发货、批量标记异常、批量导出。
- **售后与客服协同**
  - 售后列表：`售后中 / 已完成 / 已拒绝 / 等待买家 / 等待平台` 等状态视图。
  - 工单详情页：左侧聚合订单与商品信息，右侧嵌入 AGI 生成的回复建议 / 协商方案。
  - 预置快捷动作：一键同意退款 / 换货；一键生成平台仲裁材料。
- **库存与仓储 (WMS) 交互**
  - 仓库维度视图：多仓列表 + 仓库健康度（周转天数、缺货率、爆仓风险）。
  - 库位视图：库位示意图 / 表格模式 + SKU 分布；支持库位调整 / 锁定库存。
  - 拣货波次管理：前端支持生成/编辑拣货波次，展示拣货路径建议与进度。
- **采购与供应链**
  - 采购需求池：从销售预测 / 缺货预警自动生成「采购建议池」，前端支持筛选、编辑、合并。
  - PO 订单管理：创建 / 审核 / 下发 / 收货 / 质检 / 入库的可视化流程条。
  - 供应商维度看板：展示交付准时率 / 退货率 / 质量评分，与 AGI 建议联动。
- **物流与发货**
  - 打单发货工作台：支持多快递模板、运费试算、面单打印队列管理。
  - 轨迹监控：多渠道轨迹归一展示，标记「异常节点」（滞留 / 派送失败 / 清关问题）。
  - AGI 辅助动作：针对异常轨迹，一键生成催件 / 投诉 / 改派建议。
- **财务与结算 (Finance)**
  - 对账视图：按店铺 / 渠道 / 结算周期展示「应收 / 实收 / 平台费用 / 税费」。
  - 差异明细：前端支持从差异总额下钻到交易级明细，并与原订单 / 退款记录联动。
  - 收支日历 / 现金流预测：用时间轴组件展示未来收支节奏，并嵌入 AGI 预测结果。
- **主数据与配置**
  - SKU 主数据中心：支持多平台映射、条码 / SPU 维护、套装拆分 / 组合的可视交互。
  - 计量单位 / 税码 / 费用科目等 ERP 配置项在前端提供统一管理入口，变更记录可审计。
- **跨模块联动体验**
  - 任意详情页顶部固定「全局操作条」：支持一键跳转到：订单 / 库存 / 供应商 / 财务相关视图。
  - 所有「行动按钮」都带上 traceId 与业务上下文，确保 ERP 级动作可回溯。

---

### 7. 任务收件箱与审批流 (Task Inbox & Approvals)

- **统一任务收件箱 (Task Inbox)**
  - 前端实现全局 `Inbox` 视图，聚合：AGI 建议待处理、异常告警、审批请求、对账差异、PO 待审、售后待办等。
  - 支持按「来源模块 (订单 / 库存 / 财务 / 节点)」「优先级」「截止时间」筛选与排序。
  - 提供「认领 / 转派 / 完成」等基础任务操作，并在详情页内跳转到对应业务对象。
- **任务模型与后端能力**
  - 后端提供统一 `Task` 域服务，支持多来源（Advice、Alert、Approval、Reconciliation、PO、RMA 等）接入。
  - 每个 Task 绑定业务主键（订单号、SKU、节点 ID 等）和 traceId，以便 UI 一键回溯全链路。
- **通用审批中心 (Approval Center)**
  - 前端提供统一“审批中心”，所有敏感动作（大额调价、促销策略、PO 下发、资金划转、配置变更等）都走同一审批 UI。
  - 审批详情组件包含：变更前后对比、AGI 建议、影响评估、历史审批记录。
  - 支持一键「同意 / 拒绝 / 修改后通过」，并记录审批意见。
- **审批流引擎**
  - 后端实现 `ApprovalFlow` 服务：支持多级审批、条件审批（如金额阈值、多租户/角色规则）。
  - 所有审批流状态变更写入审计日志，并同步生成 Task 和通知。

---

### 8. 报表中心与自助分析 (Reporting & BI)

- **报表中心 (Report Hub)**
  - 前端实现统一报表入口，分组展示销售、库存、供应链、物流、财务、营销等标准报表。
  - 支持收藏常用报表、快速切换时间范围与维度（店铺 / 渠道 / 品类 / 活动）。
  - 提供导出能力（CSV / Excel / 图表截图），并记录导出行为用于审计。
- **自助分析 (Self-Service BI)**
  - 提供基础「维度-指标」拖拽分析界面（简易 Pivot），支持选择维度（时间、渠道、店铺等）与指标（GMV、毛利、库存周转等）。
  - 与 AGI 联动：支持自然语言生成分析视图（例如“帮我看过去 30 天 TikTok 广告投放 ROI”）。
- **后端支持**
  - 后端提供统一报表查询接口，基于预聚合宽表或物化视图，避免前端直接拼复杂 SQL。
  - 报表访问需经过权限控制，细到报表级 / 指标级授权。

---

### 9. 客户与商机视图 (CRM / Customer 360)

- **客户 360 视图**
  - 前端提供 TOC 用户与 TOB 客户的统一档案页面：展示基本信息、订单历史、客诉记录、财务往来、信用评分等。
  - 在订单 / 售后 / 对账等页面支持一键跳转到对应客户档案。
- **商机与销售漏斗**
  - 针对 B2B 场景，提供商机漏斗视图（线索 → 商机 → 报价 → 合同 → 回款）。
  - 商机详情页展示关联订单、报价单、沟通记录与 AGI 生成的跟进建议。
- **后端域服务**
  - 后端实现 `Customer` / `Account` / `Opportunity` 域，支持与订单、收款、风控服务打通。
  - 客户风险评分与信用额度由风控 / AI 服务计算，并在前端展示。

---

### 10. 配置中心与实验平台 (Config & Experiments)

- **配置中心 UI**
  - 前端提供统一的配置管理页面：包括 feature flag、风控阈值、策略参数、渠道开关、节点配额等。
  - 每个配置项展示：当前值、描述、影响范围、最近变更记录。
- **实验平台 (Experiment)**
  - 支持创建 AB 实验：定义实验目标、分组策略（按用户 / 店铺 / 节点）、实验期等。
  - 在相关页面显示当前用户/店铺所属实验组，方便排查行为差异。
- **后端能力**
  - 扩展现有 Governance / Config 服务，支持版本化配置与灰度发布。
  - 提供实验分桶服务，保证前后端对同一实体使用一致实验组。

---

### 11. 沙盒与模拟执行 (Sandbox / Simulation)

- **沙盒环境开关**
  - 前端在关键操作区域提供「沙盒模式」显式切换（明显的 UI 标识），防止误用。
  - 沙盒模式下的模拟结果（例如调价、促销、库存策略）以“虚线 / 标签”区分显示。
- **模拟看板**
  - 提供专门的「模拟执行看板」，展示在沙盒中跑过的策略、对应 KPI 变化（GMV、毛利、库存占用、现金流等）。
  - 支持选中一条模拟策略，查看其在不同渠道/店铺下的预测效果。
- **后端支持**
  - Hub 的相关接口支持 `sandbox=true` 参数，将模拟数据写入隔离表或隔离租户。
  - 模拟执行不触发真实 Node Agent / 外部平台调用，仅生成预测与分析数据。

---

### 12. 模板与批量操作 (Templates & Bulk Ops)

- **模板系统**
  - 前端提供商品模板、PO 模板、促销模板、报表模板等管理 UI。
  - 在创建对象时可选择模板，一键填充大部分字段；支持保存当前配置为新模板。
- **批量导入 / 导出**
  - 支持 Excel/CSV 导入商品、库存调整、价格表、PO 等；导入过程展示进度与错误行详情。
  - 提供与 AGI 联动的“修正建议”：对脏数据或缺失字段给出自动修正方案。
- **后端批处理能力**
  - 后端 `Template` 域服务与批处理任务（异步导入队列）对接现有 pipeline/worker 体系。
  - 对大规模批量操作提供进度查询与错误报告接口。

---

### 13. 告警与观察中心 (Alerts & Observability)

- **告警中心 UI**
  - 前端实现统一“告警中心”，聚合：节点异常、任务失败、库存超阈、应收异常、API 限流、自愈失败等。
  - 支持按严重级别、来源模块、时间窗口、是否已处理进行过滤。
  - 告警详情页展示：触发条件、影响对象、AGI 给出的处理建议、自愈尝试记录。
- **订阅与静音**
  - 用户可订阅某类告警（例如某个店铺的库存告警），也可以对某类告警静音一段时间。
  - 所有订阅 / 静音设置持久化在后端，支持多设备同步。
- **后端告警模型**
  - 统一 `Alert` 模型，将自愈、风控、SLA Guard、Pipeline 错误等告警统一到一个通道。
  - 为每条告警生成 traceId 与关联 Task，便于从告警直接跳到待办与相关对象。

---

### 14. 开发节奏 (V0 → V32.0)

- **V0 (当前阶段)：核心闭环 + 最小 ERP 工作台**
  - [ ] 实现 `AdviceCenter` 基础列表与 `Approve` 动作。
  - [ ] 实现插件端 `SuggestionBubble` 的弹出与处理。
  - [ ] 落地一个「订单 & 售后工作台」的最小版本（查询 + 状态流转 + 与 AGI 建议的基本联动）。
- **V1 (下阶段)：主权网络增强 + ERP 深度化 + 任务 & 审批 & 报表**
  - [ ] 接入 `NetworkTopology` 拓扑图。
  - [ ] 实现 ZKP 声誉证明的 UI 展示。
  - [ ] 扩展库存 / 仓储 / 采购 / 对账等 ERP 视图，保证从订单到现金的主链路可视化。
---

### 15. AGI 交互哲学与组件契约 (V32.0 - Core Philosophy)

- **建议优先 (Suggestion-First)**
  - 前端不仅是展示数据的容器，更是 **AGI 建议的执行终端**。
  - 所有关键业务变更（调价、补货、结算）必须经过：`AGI 生成建议 -> 前端展示因果链 -> 人工/策略审批 -> 后端原子执行`。
- **因果可解释性 (Explainability)**
  - 任何 AGI 建议卡片必须绑定 [DecisionExplainabilityEngine.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/ai/DecisionExplainabilityEngine.ts) 的 `traceId`。
  - UI 必须提供“为什么这么建议？”的下钻视图，展示核心权重（如：库存占用率、市场价格波动、物流时效波动）。
- **零 Mock 协议 (Zero-Mock Enforcement)**
  - 前端开发过程中，如果后端 API 未就绪，必须先在 `shared/contracts` 定义 Zod Schema。
  - 严禁在页面中使用 `const mockData = [...]`。所有数据流必须映射到 `cf_` 物理表对应的 Service 响应。

---

### 16. 全场景 AGI 决策终端模块分布 (Module Map)

- **核心域 (Core)**
  - `AdviceCenterHub`：全局建议分发与批量执行。
  - `OmniBox`：全局 AGI 指令终端。
  - `TaskInbox`：全业务待办归一化入口。
- **业务域 (Business)**
  - `TOC / TOB / Site Matrix`：全渠道消费者与商机运营。
  - `CRM 360`：全生命周期客户主权资产看板。
- **执行域 (ERP)**
  - `OMS / SKU / WMS / Logistics`：从订单到履约的物理闭环。
  - `Finance Recon`：从收入到利润的透明勾稽。
- **治理域 (Governance)**
  - `Sovereign Network`：P2P 拓扑与 ZKP 声誉可视化。
  - `Experiment Hub`：策略 A/B 实验与分桶管理。
  - `Alert Center`：全链路异常感知与自愈反馈。
- **创意域 (Creative)**
  - `AI Creative Workbench`：多模态营销素材生产。

---

### 17. 两头校准与质量校验 (🛡️ Verified Gates)

- **物理表对齐**：前端展示的每一个状态位必须对应 [LegacyTableInitializer.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/runtime/LegacyTableInitializer.ts) 中定义的物理列。
- **逻辑闭环验证**：
  - 点击“Approve”按钮后，必须验证后端 [AdviceService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Strategy/AdviceService.ts) 是否真实触发了目标 Domain 的业务逻辑。
  - 异常上报必须携带 `x-trace-id`，并在 [AlertService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Governance/AlertService.ts) 中生成对应的告警记录。
- **审计全覆盖**：所有前端写操作（POST/PUT/DELETE）必须在后端生成 `AuditLog`。

---

### 18. V32.0 阶段验收里程碑 (Milestones)

- **🛡️ Milestone 1: P2P & Trust (Batch 01-02)**
  - 实现分布式节点发现、ZKP 声誉展示与 P2P 拓扑遥测。
- **🛡️ Milestone 2: ERP & Business (Batch 03-07)**
  - 实现从 SKU 映射到财务对账的全链路 ERP 执行 UI。
- **🛡️ Milestone 3: Governance & Intelligence (Batch 08-14)**
  - 落地 AGI 指令终端、仿真沙盒、自助 BI 与多模态创作中心。
- **🛡️ Milestone 4: Total Verified (V32.0 Finale)**
  - 全量物理表闭环，全场景因果链穿透，全业务 AGI 自愈。