wurenzhi/makemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c0870dce501feae6fe1ad8911dad2b46f537ef66
makemd/docs/frontend-dev-plan.md
Ansonai 6759d47de4 docs: 新增V30.0版本相关设计文档与指南 
新增服务器启动文档、设计说明书、风险清单等核心文档
补充前端集成蓝图、多租户实施清单、上线红线检查清单
添加质量保障文档与早期业务规格书
2026-03-16 01:31:26 +08:00

18 KiB
Raw Blame History

📋 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 推送的 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 的数据，渲染节点的信用等级与 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。
    • 通过步骤条或折叠面板展示决策背后的核心权重因子（如：库存占用 > 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 的 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 中定义的物理列。
  • 逻辑闭环验证：
    • 点击“Approve”按钮后，必须验证后端 AdviceService.ts 是否真实触发了目标 Domain 的业务逻辑。
    • 异常上报必须携带 x-trace-id，并在 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 自愈。
Reference in New Issue View Git Blame Copy Permalink