From 6759d47de4587b8d682590c25478dfc00ed56a84 Mon Sep 17 00:00:00 2001 From: Ansonai Date: Mon, 16 Mar 2026 01:31:26 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9EV30.0=E7=89=88?= =?UTF-8?q?=E6=9C=AC=E7=9B=B8=E5=85=B3=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E4=B8=8E=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增服务器启动文档、设计说明书、风险清单等核心文档 补充前端集成蓝图、多租户实施清单、上线红线检查清单 添加质量保障文档与早期业务规格书 --- .trae/rules/project_rules.md | 188 +++ .../industry-benchmarks-comprehensive.md | 299 ++++ docs/blueprints/arch-overview-v30.md | 69 + docs/blueprints/archive/arch-freeze-v30.md | 12 + .../archive/v30-arch-optimization-plan.md | 14 + docs/blueprints/frontend-architecture.md | 217 +++ .../frontend-integration/TEMPLATE.md | 40 + .../frontend-integration/approval-center.md | 34 + .../biz-gov-05-roi-dashboard.md | 44 + .../biz-mkt-30-dynamic-pricing.md | 40 + .../biz-sup-15-sourcing-optimization.md | 42 + .../carbon-credit-trading-ui.md | 46 + .../frontend-integration/carbon-pledge-ui.md | 47 + .../cashflow-prediction.md | 50 + .../circuit-breaker-ui.md | 44 + .../compliance-certificate-ui.md | 47 + .../frontend-integration/courier-credit-ui.md | 44 + .../frontend-integration/crm-hub.md | 35 + .../cross-node-settlement-ui.md | 45 + .../crowdsourced-logistics.md | 45 + .../frontend-integration/did-settlement.md | 49 + .../dispute-arbitration-ui.md | 44 + .../dynamic-routing-failover.md | 49 + .../frontend-integration/finance-recon.md | 30 + .../frontend-integration/fraud-shared-ui.md | 41 + .../frontend-integration/fx-hedging-risk.md | 46 + .../global-dispute-router-ui.md | 48 + .../green-supply-chain-ui.md | 46 + .../intermodal-failover-ui.md | 49 + .../inventory-aging-ui.md | 51 + .../inventory-forecast-replenishment.md | 48 + .../logistics-health-ui.md | 58 + .../frontend-integration/membership-ltv-ui.md | 44 + .../multi-currency-recon.md | 45 + .../multi-touch-attribution.md | 46 + .../node-liquidity-forecast-ui.md | 44 + .../node-resource-quota-ui.md | 51 + .../frontend-integration/oms-workbench.md | 32 + .../order-profit-analysis.md | 54 + .../platform-fee-watcher-ui.md | 47 + .../frontend-integration/private-lc-ui.md | 47 + .../reputation-perks-ui.md | 50 + .../frontend-integration/sandbox-roi-ui.md | 47 + .../sea-freight-advisor-ui.md | 47 + .../frontend-integration/stock-planner-ui.md | 46 + .../frontend-integration/style-war-ui.md | 47 + .../supplier-capacity-watch.md | 45 + .../supplier-risk-radar-ui.md | 49 + .../tax-routing-optimizer.md | 44 + .../trade-compliance-ui.md | 45 + .../trade-insurance-ui.md | 46 + docs/blueprints/global-business-blueprint.md | 203 +++ docs/blueprints/js-fullstack-architecture.md | 933 ++++++++++++ docs/business梳理.md | 1307 +++++++++++++++++ docs/design/console-pipeline-log-design.md | 8 + docs/design/extension-initiation.md | 8 + docs/design/p0-risk-registry.md | 8 + docs/design/server-initiation.md | 8 + docs/doc-index.md | 52 + docs/frontend-dev-plan.md | 288 ++++ .../archive/collaboration-history-v31.md | 56 + docs/governance/collaboration-board.md | 337 +++++ .../governance/console-collaboration-board.md | 236 +++ docs/governance/doc-maintenance-plan.md | 251 ++++ docs/governance/task-specifications.md | 854 +++++++++++ .../guides/non-saas-multi-tenant-checklist.md | 42 + docs/guides/server-readme.md | 82 ++ docs/guides/toc-early-stage-spec.md | 51 + docs/maiteng-crawl-1773595163736.json | 1133 ++++++++++++++ docs/maiteng-crawler.js | 238 +++ docs/quality/frontend-delivery-standard.md | 56 + docs/quality/golive-redline-checklist.md | 48 + docs/quality/ux-field-acceptance-checklist.md | 51 + docs/task-allocation.md | 223 +++ 74 files changed, 9310 insertions(+) create mode 100644 .trae/rules/project_rules.md create mode 100644 docs/benchmarks/industry-benchmarks-comprehensive.md create mode 100644 docs/blueprints/arch-overview-v30.md create mode 100644 docs/blueprints/archive/arch-freeze-v30.md create mode 100644 docs/blueprints/archive/v30-arch-optimization-plan.md create mode 100644 docs/blueprints/frontend-architecture.md create mode 100644 docs/blueprints/frontend-integration/TEMPLATE.md create mode 100644 docs/blueprints/frontend-integration/approval-center.md create mode 100644 docs/blueprints/frontend-integration/biz-gov-05-roi-dashboard.md create mode 100644 docs/blueprints/frontend-integration/biz-mkt-30-dynamic-pricing.md create mode 100644 docs/blueprints/frontend-integration/biz-sup-15-sourcing-optimization.md create mode 100644 docs/blueprints/frontend-integration/carbon-credit-trading-ui.md create mode 100644 docs/blueprints/frontend-integration/carbon-pledge-ui.md create mode 100644 docs/blueprints/frontend-integration/cashflow-prediction.md create mode 100644 docs/blueprints/frontend-integration/circuit-breaker-ui.md create mode 100644 docs/blueprints/frontend-integration/compliance-certificate-ui.md create mode 100644 docs/blueprints/frontend-integration/courier-credit-ui.md create mode 100644 docs/blueprints/frontend-integration/crm-hub.md create mode 100644 docs/blueprints/frontend-integration/cross-node-settlement-ui.md create mode 100644 docs/blueprints/frontend-integration/crowdsourced-logistics.md create mode 100644 docs/blueprints/frontend-integration/did-settlement.md create mode 100644 docs/blueprints/frontend-integration/dispute-arbitration-ui.md create mode 100644 docs/blueprints/frontend-integration/dynamic-routing-failover.md create mode 100644 docs/blueprints/frontend-integration/finance-recon.md create mode 100644 docs/blueprints/frontend-integration/fraud-shared-ui.md create mode 100644 docs/blueprints/frontend-integration/fx-hedging-risk.md create mode 100644 docs/blueprints/frontend-integration/global-dispute-router-ui.md create mode 100644 docs/blueprints/frontend-integration/green-supply-chain-ui.md create mode 100644 docs/blueprints/frontend-integration/intermodal-failover-ui.md create mode 100644 docs/blueprints/frontend-integration/inventory-aging-ui.md create mode 100644 docs/blueprints/frontend-integration/inventory-forecast-replenishment.md create mode 100644 docs/blueprints/frontend-integration/logistics-health-ui.md create mode 100644 docs/blueprints/frontend-integration/membership-ltv-ui.md create mode 100644 docs/blueprints/frontend-integration/multi-currency-recon.md create mode 100644 docs/blueprints/frontend-integration/multi-touch-attribution.md create mode 100644 docs/blueprints/frontend-integration/node-liquidity-forecast-ui.md create mode 100644 docs/blueprints/frontend-integration/node-resource-quota-ui.md create mode 100644 docs/blueprints/frontend-integration/oms-workbench.md create mode 100644 docs/blueprints/frontend-integration/order-profit-analysis.md create mode 100644 docs/blueprints/frontend-integration/platform-fee-watcher-ui.md create mode 100644 docs/blueprints/frontend-integration/private-lc-ui.md create mode 100644 docs/blueprints/frontend-integration/reputation-perks-ui.md create mode 100644 docs/blueprints/frontend-integration/sandbox-roi-ui.md create mode 100644 docs/blueprints/frontend-integration/sea-freight-advisor-ui.md create mode 100644 docs/blueprints/frontend-integration/stock-planner-ui.md create mode 100644 docs/blueprints/frontend-integration/style-war-ui.md create mode 100644 docs/blueprints/frontend-integration/supplier-capacity-watch.md create mode 100644 docs/blueprints/frontend-integration/supplier-risk-radar-ui.md create mode 100644 docs/blueprints/frontend-integration/tax-routing-optimizer.md create mode 100644 docs/blueprints/frontend-integration/trade-compliance-ui.md create mode 100644 docs/blueprints/frontend-integration/trade-insurance-ui.md create mode 100644 docs/blueprints/global-business-blueprint.md create mode 100644 docs/blueprints/js-fullstack-architecture.md create mode 100644 docs/business梳理.md create mode 100644 docs/design/console-pipeline-log-design.md create mode 100644 docs/design/extension-initiation.md create mode 100644 docs/design/p0-risk-registry.md create mode 100644 docs/design/server-initiation.md create mode 100644 docs/doc-index.md create mode 100644 docs/frontend-dev-plan.md create mode 100644 docs/governance/archive/collaboration-history-v31.md create mode 100644 docs/governance/collaboration-board.md create mode 100644 docs/governance/console-collaboration-board.md create mode 100644 docs/governance/doc-maintenance-plan.md create mode 100644 docs/governance/task-specifications.md create mode 100644 docs/guides/non-saas-multi-tenant-checklist.md create mode 100644 docs/guides/server-readme.md create mode 100644 docs/guides/toc-early-stage-spec.md create mode 100644 docs/maiteng-crawl-1773595163736.json create mode 100644 docs/maiteng-crawler.js create mode 100644 docs/quality/frontend-delivery-standard.md create mode 100644 docs/quality/golive-redline-checklist.md create mode 100644 docs/quality/ux-field-acceptance-checklist.md create mode 100644 docs/task-allocation.md diff --git a/.trae/rules/project_rules.md b/.trae/rules/project_rules.md new file mode 100644 index 0000000..63c6b3d --- /dev/null +++ b/.trae/rules/project_rules.md @@ -0,0 +1,188 @@ +# 代码与提交规范 + +- 使用 TypeScript；禁止 any（必要场景以 TODO 标注并跟进） +- 文件命名：小写短横线；TypeScript 类型与接口使用大驼峰 +- 分支命名：feature/, fix/, docs/, chore/；提交信息以动词开头，中文或英文均可 +- 变更前必须通过构建与基础校验脚本：npm run check +- 注释要求：中文注释，紧贴代码语句，描述意图而非过程；禁止冗长段落 + +# Lint 与格式化 + +- 插件启用 ESLint（React+TS）；后端暂不强制 ESLint +- 统一缩进 2 空格；UTF-8；换行 LF；末尾换行 +- 建议在本地启用编辑器保存时格式化（遵循 .editorconfig） + +# TypeScript 约束 + +- extension/ tsconfig：strict 开启；paths 使用 @/\* +- server/ tsconfig：保持严格类型；避免 any 与隐式 any + +# API 约定 + +- 所有响应统一结构：{ success: boolean, data?: any, error?: string } +- 错误码与信息需清晰、可定位；4xx 为入参错误，5xx 为服务异常 +- CORS 白名单通过环境变量 ALLOWED_ORIGINS 配置 +- 速率限制通过 RATE_LIMIT_REQUESTS 与 RATE_LIMIT_WINDOW_MS 配置 + +# 数据与存储 + +- 所有数据库表必须以 `cf_` 为前缀（如 `cf_product`, `cf_order`） +- 金额字段必须使用 `decimal(10,2)` 或更高精度，禁止使用 float/double +- 物理属性单位统一：长度(cm), 重量(kg), 体积(m3) +- cf_product 平台+productId 唯一约束；避免重复插入 +- JSON 字段（images/skus/attributes）入库前进行序列化；出库进行解析 + +# 核心业务规则 + +- **建议优先原则 (Suggestion-First/Semi-Auto)**：鉴于业务复杂性，后端 Agent 严禁在未经人工审核的情况下直接修改核心业务数据（如调价、退款、下单）。 +- **流程门禁**：所有 Agent 决策必须遵循 `SUGGESTED -> PENDING_REVIEW -> EXECUTED/REJECTED` 状态机。 +- **Console 决策闭环**：Agent 仅负责生成“决策建议包”（含因果叙述与证据链），必须由人工在 `Console` 端确认后方可执行。 +- 计价逻辑必须收敛于 `PricingService`，禁止在 Controller 或前端硬编码公式 +- B2B 利润率红线：< 15% 禁止报价 +- B2C 利润率红线：< 20% 触发风控预警 +- 所有设备必须标记：Commercial Use Only, Non-Returnable +- 严禁处理住宅地址订单（轻B模式） + +# 插件消息规范 + +- 所有 message.type 统一在 src/shared/types/messaging.ts 声明 +- 新增类型前必须在 background 与调用方同时适配，并补充最小冒烟测试 + +# 安全与权限规范 + +- 权限模型：RBAC (基于角色的访问控制) + 颗粒度权限点 (如 `order:read`) +- 预设角色：ADMIN (全权), MANAGER (运营主管), OPERATOR (运营专员), FINANCE (财务主管), SOURCING (采购专家), LOGISTICS (物流专家), ANALYST (数据分析师) +- 权限校验：路由层必须通过 `authorize(permission)` 中间件进行拦截，禁止在 Controller 中硬编码 `role === 'ADMIN'` +- 数据隔离：非 ADMIN 用户在查询列表时必须根据 `parentId` 进行层级过滤，仅能看到自身及下属数据 + +# 提交前校验 (V30.0 - 生产级自我审计) + +- **严禁全量构建 (No Heavy Build)**：为节省服务器/本机开销，日常开发流程中**严禁运行** `npm run build`。 +- **强制自我审计 (Self-Check Only)**： + - 开发者（AI）必须在交付代码前，通过 `Read` 与 `GetDiagnostics` 进行逻辑自查与类型校验。 + - 逻辑自查标准：代码必须细致到“部署即运行”，业务链路必须闭环（如：新增字段必须在 API 响应中体现，且在 Service 中有对应处理）。 +- **禁止跨 AI 审计**：每个窗口仅负责自身代码的业务完整性，无需等待其他 AI 审计，直接交付。 + +# 安全与保密 + +- 严禁提交任何密钥或私密配置；环境变量由 .env 管理并忽略提交 + +# Todo 列表执行规范 + +- 必须通过 `TodoWrite` 工具同步任务进度；每次对话开始时应优先规划或更新任务列表。 +- 在任务列表中所有 `pending` 或 `in_progress` 的任务未处理完成或未记录明确阻塞原因前，严禁主动终止对话回合或将控制权交还给用户。 +- **阻塞即自查 (Self-Diagnosis on Blockage)**：如果任务被阻塞（Blocked），AI 必须在 Todo 或看板中清晰列举出当前遇到的“自我问题”，并遵循 **RCA 强制模板**： + - `[CATEGORY]`：(Context Missing / Logic Conflict / API Hallucination / Env Issue) + - `[ROOT_CAUSE]`：(具体原因，如：.env 缺少某 Key) + - `[MITIGATION]`：(修复建议或 Fallback 路径，如：手动在 .env 补充该 Key 或使用模拟数据) +- 必须遵循“规划 -> 执行 -> 验证 -> 归档”的完整闭环，单次执行应尽可能覆盖多个关联任务以提高效率。 +- 任务描述必须使用中文，并清晰定义“核心/架构/业务/UI”等模块属性。 + +# 架构与性能边界 (Single-Node Architecture) + +- **基础设施配置**： + - **数据库**：阿里云 RDS (MySQL 8.0)；禁止在代码中执行 `DROP/TRUNCATE`；复杂查询必须通过 `EXPLAIN` 校验索引。 + - **缓存与队列**：本地 Redis (服务器 6379 端口)；所有异步任务通过 BullMQ 走本地 Redis。 +- **单机资源保护**： + - **内存管理**：后端 Node.js 进程限制 `--max-old-space-size=4096`；图片处理 (Sharp) 必须开启 `sequentialRead` 以降低内存峰值。 + - **并发控制**：API 速率限制 (Rate Limit) 必须基于本地 Redis 实现；Worker 并发数 (Concurrency) 严禁超过 10，防止单机 CPU 耗尽。 +- **边界隔离**： + - **Domain 间引用**：禁止跨 Domain 直接操作数据库模型，必须通过 `Service` 暴露接口或 `EventBus` 异步通信。 + +# 1 (Brain) + 3 (Agents) 指挥与自省协议 (V30.0) + +- **角色定位**：大脑 (Brain) 负责全局调度与决策；Agent (AI-1, AI-2, AI-3) 负责原子任务包的闭环开发。 +- **Agent 问题显性化 (Explicit Issue Disclosure)**：Agent 必须在对话开始、执行中、交付前三个阶段明确上报“自我问题”： + - **认知自省**：若不理解大脑下发的任务背景或逻辑，必须立即回传 `[CONTEXT_BLOCKED]` 并说明缺失的具体 MD 或代码上下文。 + - **逻辑自省**：若发现大脑的指令与现有代码或 project_rules 存在矛盾，必须回传 `[LOGIC_CONFLICT]` 并指出矛盾点。 + - **环境自省**：若由于本地环境（如 Redis 未启动、.env 缺失）导致代码无法验证，必须回传 `[ENV_LIMITATION]` 并提供模拟验证结果。 +- **深度思考与文档反哺 (Reflective Documentation)**：Agent 不仅仅是代码执行器，必须承担“架构思考者”的角色。在任务包闭环后，必须主动执行以下动作： + - **逻辑升华**：若在开发中发现更优的业务逻辑或架构路径，必须同步更新 `docs/blueprints/` 下的相关蓝图。 + - **规格校准**：若实际实现与 `task-specifications.md` 存在偏差，必须立即校准规格文档，确保“实现即规格”。 + - **知识沉淀**：将开发过程中遇到的深坑、避坑指南记录至 `docs/quality/` 或相关 MD，实现 AGI 知识库的自我增量进化。 +- **看板强制反馈**：所有 `[ISSUE-AI-X]` 标签必须包含具体的“自我认知”描述，严禁使用“任务无法完成”等模糊词汇。 +- **任务规格书驱动 (Spec-Driven)**：复杂任务必须先在 `docs/governance/task-specifications.md` 定义原子化规格。 +- **收益优先原则 (ROI-First)**： + - **业务收益**：优先实现提升转化率（如 AR 预览、智能预测）与降低成本的任务。 + - **开发收益**：优先实现提升自动化测试与隔离环境（如 Sandbox Crawler）的任务。 +- **极限增量更新原则 (Absolute Incremental Update)**： + - **物理删除禁令**：严禁物理删除任何已存在的文字信息。 + - **状态演进标注**：失效信息使用 ~~删除线~~，并标注 `[AI-X @ YYYY-MM-DD]`。 +- **变更编年史 (Change Log) 强制同步**：每次完成变更必须在看板追加记录。 +- **原子化文档同步 (Atomic Doc Sync)**：变更代码的同时必须追加文档记录。 +- **自适应任务领取 (Auto-Claiming)**：AI 需主动读取看板领取任务。 + +# AI-First 代码库治理规范 (V31.5 - Autocomplete 友好型工程) + +- **补全优先编码 (Autocomplete-First)**： + - **标准命名**：禁止任何语义不明的缩写。变量名与函数名必须具备强描述性，以最大化 IDE 自动补全的预测准确度。 + - **JSDoc 驱动**：在实现逻辑前，必须编写详尽的 JSDoc（含 `@param`, `@returns`, `@throws`）。这不仅是文档，更是为 Autocomplete 提供精准的上下文先验知识。 + - **小函数原则**：单个函数逻辑控制在 30 行以内。函数越短，Autocomplete 的补全信心指数越高，从而减少人工手动输入的 Dollar Usage 成本。 +- **全栈蓝图协议 (V31.3 - 全栈蓝图协议)**： + +- **前端方案强制性 (Frontend Blueprinting)**： + - 后端 Agent 在完成任何 Service 或 API 逻辑后，必须在 `docs/blueprints/frontend-integration/` 下产出对应的详细前端实现方案。 + - **详细度要求**：必须包含 UI 布局草图（Markdown 描述）、交互状态机（如按钮 Loading 逻辑）、核心 API 字段映射及 ROI 可视化逻辑。 + - **逻辑对齐**：确保后端提供的 `causalChain`（因果链）能在前端 `Console` 端完美呈现，杜绝“后端有数据，前端没位置”的尴尬。 +- **物理 Schema 唯一源 (Single Source of Schema)**： + - [LegacyTableInitializer.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/runtime/LegacyTableInitializer.ts) 是项目中**唯一的**物理表初始化入口（禁止新增其它初始化文件）。 + - 任何 Agent 在新增业务实体时，必须首先在对应的 `Service` 中实现静态 `initTable()` 方法，并将其**注册**到 `LegacyTableInitializer` 中。 +- **Schema 幂等性 (Idempotency)**： + - 所有建表语句必须使用 `db.schema.hasTable` 进行前置校验。 + - 严禁在业务逻辑执行过程中动态创建表，必须在系统启动/初始化阶段通过上述唯一入口完成。 +- **契约驱动的数据库协作 (Contract-Driven DB)**： + - 如果 AI-3 (Biz) 需要的新表尚未由 AI-1 (Kernel) 完成物理建表，AI-3 必须先在 `shared/contracts` 定义 Zod Schema 作为“逻辑契约”。 + - AI-3 可以基于此契约编写业务逻辑，但任务在物理表未在唯一入口落地并验证前，严禁标记为 `completed`。 +- **严禁 Mock 数据 (Zero-Mock Policy)**： + - 严禁在生产级 Service 或前端 Page/Component 中使用硬编码的 `return { ... }`、`setTimeout` 模拟或模拟数据。 + - 所有业务输出必须来自 `cf_` 数据库表、第三方生产 API 或后端真实 Controller 响应。 +- **因果链强制性 (Causal Chain Enforcement)**： + - 每一个 AGI 建议必须通过 `DecisionExplainabilityEngine` 记录真实的因果叙述。 + - 严禁生成无数据支撑的“空洞建议”，AI-2 (Internal) 将对因果链进行逻辑真实性审计。 +- **部署即运行 (Deploy-Ready)**： + - `completed` 的标志是：数据库表已初始化、核心逻辑已闭环、通过 `GetDiagnostics` 校验。 + - 严禁提交带有 `// TODO: implement later` 或仅有接口定义而无实现的代码。 +- **影子测试 (Shadow Auditing)**： + - AI-2 (Internal) 在 AI-1/3 开发的同时，必须产出该功能的 **Shadow-Test**（最小冒烟测试），并在看板同步。 +- **目录职责固化**：后端必须遵循 `core/ domains/ workers/ api/ shared` 分层，禁止跨层越权调用。 +- **契约先行**：跨端能力（Console/Extension/NodeAgent）必须先定义 contract，再实现逻辑。 +- **状态机门禁**：发布、审核、对账流程必须落入统一 FSM，禁止散落在 Controller 中硬编码流程分支。 +- **追踪四元组必填**：所有任务与日志必须携带 `tenantId/shopId/taskId/traceId`。 +- **Agent 异常自省 (Self-Problem Awareness)**：Agent 必须能够明确识别并记录自身的问题。在执行链路中，若由于输入不规范、逻辑矛盾、API 幻觉或环境约束导致无法继续，必须遵循以下 **异常处理准则**： + - **级别化 (Leveling)**：明确标注错误级别 (`FATAL` 流程中断, `WARN` 降级运行)。 + - **归因化 (Attribution)**：必须定位至具体模块 (`Service/Controller/Worker`)。 + - **闭环化 (Closing)**：必须提供至少一个 **降级/Fallback 路径**，确保系统整体逻辑不产生静默失败。 +- 术语统一：中台前端统一称为 `Console`；历史术语以 `~~Dashboard~~ -> Console` 标注演进。 +- **AI 可读性优先**：函数命名必须表达业务意图（禁止缩写语义漂移），同类逻辑必须复用统一 Service。 +- **防幻觉约束**：新增能力必须能映射到看板任务 ID 与规格任务 ID，未入规格的实现不得进入主干。 + +# TOB 与套利专项约束 (V30.0) + +- **套利口径统一**：禁止仅用“售价-采购价”判断套利；必须使用净利公式（含平台费/物流/税费/汇率/售后/广告摊销）。 +- **利润红线强制执行**：B2B `<15%` 禁止放行，B2C `<20%` 必须进入风控审核。 +- **无 API 执行约束**：无 API 平台必须走 `No-API Bridge` + `PENDING_REVIEW`，禁止全自动直发。 +- **Win 节点隔离约束**：一店一执行上下文（profileDir/proxy/fingerprintPolicy），同店任务严格串行。 +- **企业交付底线**：上线前必须具备租户隔离、审计追责、配额治理、SLA 指标可观测四项能力。 + +# 文档管理规范 (V30.0 - 结构化与 AGI 友好) + +- **命名规范**：文件名必须使用小写短横线（kebab-case），如 `global-business-blueprint.md`。 +- **分类存放**： + - `docs/blueprints/`：存放全局业务蓝图、架构设计与演进路线。 + - `docs/benchmarks/`：存放行业标杆（易仓、蝉妈妈等）的专项拆解与 AGI 规格。 + - `docs/quality/`：存放质量保障清单与红线规范。 + - `docs/governance/`：存放协同看板、任务规格与 AI 交互规范。 +- **引用闭环**：文档内引用必须使用完整 Markdown 链接，并确保 `README.md` 与 `doc-index.md` 的导航同步更新。 +- **原子化更新**：每次功能变更必须同步更新对应的标杆规格或蓝图，确保 AGI “先验知识”的实时性。 + +# 三AI同目录并行执行协议 (V30.0) + +- **一次性分发原则**：每轮必须一次性下发完整任务包（P0/P1/P2），禁止仅下发单点任务。 +- **连续执行原则**：每个 AI 在其任务包内必须连续执行到“完成或明确阻塞”才允许结束回合。 +- **停机条件白名单**：仅允许以下两类停机： + 1. 外部依赖阻塞（账号权限/第三方不可用）； + 2. 已达到任务包验收标准并完成文档归档。 +- **文件占用锁**：同目录协作时必须先声明文件归属，遵循“谁领取谁编辑”，避免并发覆盖。 +- **冲突处理**：出现同文件冲突时，后写入方必须先 `Read` 最新内容并做增量合并，不得回滚他人变更。 +- **任务包格式固定**：每个任务包必须包含 `任务ID/负责人/输入文件/输出文件/验收标准/阻塞升级路径`。 +- **批次节奏**：推荐 1 日 2 批（上午分发、下午回收），回收后立即进行下一批一次性分发。 diff --git a/docs/benchmarks/industry-benchmarks-comprehensive.md b/docs/benchmarks/industry-benchmarks-comprehensive.md new file mode 100644 index 0000000..58e1def --- /dev/null +++ b/docs/benchmarks/industry-benchmarks-comprehensive.md @@ -0,0 +1,299 @@ +# 跨境电商行业标杆功能综合拆解与 AGI 演进规格书 (V2.0) + +> **文档版本**: V2.0 | **更新日期**: 2026-03-15 +> **整合说明**: 本文档整合了所有行业标杆（ERP、数据分析、TikTok运营、客服等）的核心功能模块，为 Crawlful AGI 自治贸易系统提供全面的"行业先验知识"。 + +--- + +## 0. 战略意图 (Strategic Intent) + +本综合规格书旨在深度剖析跨境电商领域各类标杆产品的核心业务逻辑，通过系统化模块拆解，为 Crawlful V30.0 的 AGI 自治贸易系统提供坚实的行业先验知识。 + +**整合目标**： +- **像素级还原**各类标杆的核心业务闭环 +- 通过 **AGI (自治决策)**、**DID (主权身份)** 和 **ZKP (隐私审计)** 实现代际超越 +- 建立统一的功能映射体系，便于后续开发参考 + +--- + +## 1. 行业标杆分类总览 + +| 类别 | 代表产品 | 核心价值 | 数量 | +| :--- | :--- | :--- | :---: | +| **ERP系统** | 易仓、店小秘、积加、通途、马帮 | 订单/商品/采购/财务全链路管理 | 5 | +| **TikTok ERP** | 妙手、海鹭、电霸、达多多 | TikTok 电商运营自动化 | 4 | +| **数据分析** | 船长BI、蝉妈妈、koladata | 销售/流量/红人效果分析 | 3 | +| **运营服务** | 出海匠、91妙手 | 本地化/无API执行 | 2 | + +--- + +## 2. ERP 系统类标杆拆解 + +### 2.1 ERP 核心生态架构 + +| 模块 | 定位 | 核心价值 | +| :--- | :--- | :--- | +| **ERP (Seller)** | 经营决策大脑 | 解决"卖什么、卖多少、赚多少"的问题 | +| **WMS (Logistics)** | 履约执行心脏 | 解决"在哪里、怎么发、快不快"的问题 | +| **TMS (Shipping)** | 全球连接动脉 | 解决"走哪路、多少钱、到没到"的问题 | + +### 2.2 多平台接入中心 + +| 功能点 | 核心逻辑 | Crawlful 复刻方案 | +| :--- | :--- | :--- | +| **平台覆盖** | 支持 Amazon、eBay、Wish、速卖通、TikTok Shop、Temu、Shopee、Lazada 等 30+ 平台 | Connector Bus 标准化协议，按平台特性适配 API | +| **授权管理** | OAuth2.0 授权、Token 自动刷新、授权状态监控 | 授权服务 + Token 生命周期管理 | +| **数据拉取** | 定时增量拉取 + 实时 WebHook 推送 | 定时任务 + 事件监听双通道 | +| **异常处理** | API 限流应对、授权失效告警、数据拉取失败重试 | 指数退避重试 + 告警机制 | + +### 2.3 商品与刊登系统 (Listing) + +| 功能点 | 核心逻辑 | Crawlful 复刻方案 | +| :--- | :--- | :--- | +| **全局 SPU 管理** | 跨平台的 SPU（标准产品单位）统一管理 | 全局 SKU 数据库 + 平台属性映射表 | +| **属性映射引擎** | 平台间属性自动转换（如颜色、尺码、规格） | 规则引擎 + 属性映射配置 | +| **批量刊登** | Excel/CSV 导入、模板批量生成 | 导入服务 + 模板引擎 | +| **图片处理** | 主图替换、水印去除、尺寸统一 | 图片处理服务（Sharp） | +| **AI 优化** | 自动进行跨文化 SEO 优化与视觉风格对齐 | AGI 内容生成 | + +### 2.4 订单管理系统 (OMS) + +| 功能点 | 核心逻辑 | Crawlful 复刻方案 | +| :--- | :--- | :--- | +| **多源订单归集** | 跨平台订单统一展示和处理 | 统一订单队列 + 聚合视图 | +| **自动审单** | 规则匹配（地址验证、库存验证、风险验证） | 规则引擎 + 自动化工作流 | +| **订单匹配** | 买家信息 + 商品信息自动关联 | 智能匹配算法 | +| **异常订单处理** | 缺货、地址异常、支付失败等状态处理 | 异常队列 + 人工介入流程 | +| **批量操作** | 批量发货、批量标记、批量打印 | 批量任务服务 | + +**AGI 增强点**：基于实时风险画像的自主反欺诈审计 + +### 2.5 库存管理系统 (WMS) + +| 功能点 | 核心逻辑 | Crawlful 复刻方案 | +| :--- | :--- | :--- | +| **多仓库存** | 多仓库库存统一管理 | 多仓库存服务 + 库存流水 | +| **库存同步** | 平台库存实时同步、防止超卖 | 库存锁定机制 + 乐观锁 | +| **安全库存预警** | 低于阈值自动提醒 | 定时检查 + 消息通知 | +| **库存流水** | 进出库全记录、可追溯 | 库存流水表 + 多维度查询 | + +**WMS 核心流程**： +- **入库流 (Inbound)**：ASN 预报、盲收/点收、QC 质检、系统推荐上架位（基于动销率） +- **库内流 (Inventory)**：循环盘点、仓际调拨、库存冻结逻辑 +- **出库流 (Outbound)**：波次拣货 (Wave Picking)、二次分拣、自动称重面单打印 + +### 2.6 采购与寻源 + +| 功能点 | 核心逻辑 | Crawlful 复刻方案 | +| :--- | :--- | :--- | +| **1688 采购** | 1688 商品链接一键下单、代采服务 | 1688 开放平台 API 对接 | +| **采购询价** | 向多个供应商发起询价、对比价格 | 询价管理模块 | +| **智能补货** | 基于 `(销量预测 * 采购周期 + 安全库存 - 在途)` 的补货算法 | 自演化补货引擎 | + +**AGI 增强点**：自演化补货引擎，感知地缘政治与社交趋势波动 + +### 2.7 财务与核算 + +| 功能点 | 核心逻辑 | Crawlful 复刻方案 | +| :--- | :--- | :--- | +| **利润核算** | 销售收入 - 采购成本 - 物流费用 - 平台费用 - 广告费用 | 利润计算引擎 | +| **成本归集** | 采购成本、头程物流、尾程物流、平台佣金、广告投入 | 成本归集服务 | +| **多币种** | 多币种、多税率的 VAT 自动计提与发票生成 | 多币种服务 + 汇率管理 | +| **对账** | 手工对账 | ZKP 隐私审计 | + +**AGI 增强点**：基于 DID 的主权分账协议，亚秒级实现多方分润 + +### 2.8 物流系统 + +| 功能点 | 核心逻辑 | Crawlful 复刻方案 | +| :--- | :--- | :--- | +| **渠道治理** | 集成 500+ API，支持"最优路径建议" | 物流渠道服务 | +| **面单打印** | 多平台物流面单统一打印 | 面单模板 + 打印服务 | +| **物流追踪** | 物流轨迹实时同步、异常提醒 | 物流追踪服务 + 告警 | +| **遥测监控** | 多节点轨迹爬取，异常停留（48h+）自动触发申诉工单 | 轨迹监控 + 自动申诉 | + +--- + +## 3. TikTok ERP 类标杆拆解 + +### 3.1 TikTok 运营核心功能 + +| 功能模块 | 核心能力 | Crawlful 复刻方案 | +| :--- | :--- | :--- | +| **商品采集** | 跨平台一键抓取（1688/Amazon/TikTok） | 自愈式采集插件 | +| **AI 洗稿** | 自动重构 Listing 结构，生成差异化营销文案 | AGI 内容生成 | +| **无 API 履约** | 模拟真实用户行为进行批量打单、面单回传 | No-API Bridge | +| **合规管控** | 侵权预警、品牌风险识别 | AGI 侵权预警服务 | + +### 3.2 流量与内容运营 + +| 功能点 | 核心逻辑 | AGI 演进方向 | +| :--- | :--- | :--- | +| **短视频/直播热度** | 实时监测爆款素材、热门话题、直播间流量波动 | AGI 识别爆款趋势并联动选品 | +| **销量/转化率排行** | 还原商品真实转化效率 | 自动生成运营策略建议 | +| **流量来源分析** | 拆解竞品流量构成（自然流/广告流/达人流） | 基于隐私保护的竞品分析 | + +### 3.3 账号与合规 + +| 功能点 | 核心逻辑 | Crawlful 复刻方案 | +| :--- | :--- | :--- | +| **多租户隔离** | 一店一环境 (Profile) | 指纹隔离 + 代理池 | +| **侵权预警** | 识别敏感词、图片 Logo、版权元素 | AGI 图像识别 + 文本分析 | +| **账号安全** | 指纹策略、代理轮换 | 账号安全服务 | + +--- + +## 4. 数据分析类标杆拆解 + +### 4.1 数据归集中心 + +| 功能点 | 核心逻辑 | Crawlful 复刻方案 | +| :--- | :--- | :--- | +| **多平台数据源** | Amazon、eBay、Wish、速卖通等平台数据拉取 | Connector Bus 标准化 + 增量拉取 | +| **数据清洗** | 重复数据去除、格式标准化、异常值处理 | 数据清洗服务 + ETL 流程 | +| **数据建模** | 维度表、事实表、汇总表设计 | 数据仓库 + 星型模型 | +| **实时同步** | WebHook 实时推送 + 定时增量同步 | 事件驱动 + 定时任务双通道 | + +### 4.2 销售数据分析 + +| 功能点 | 核心逻辑 | 复刻方案 | +| :--- | :--- | :--- | +| **销售概览** | 销售额、订单量、客单价、转化率核心指标 | Dashboard 服务 + 聚合查询 | +| **销售趋势** | 日/周/月/年销售趋势对比 | 时间序列分析 + 图表呈现 | +| **销售排名** | 热销商品排名、热卖店铺排名、爆款分析 | TopN 查询 + 排序服务 | +| **利润分析** | 订单利润核算、成本归集 | 利润计算引擎 | + +### 4.3 库存与供应链分析 + +| 功能点 | 核心逻辑 | 复刻方案 | +| :--- | :--- | :--- | +| **库存概览** | 总库存、在途库存、可售库存、呆滞库存 | 库存聚合查询 | +| **库龄分析** | 库存周转天数、呆滞库存预警、库龄分布 | 库存分析服务 | +| **补货建议** | 基于销量和安全库存的智能补货建议 | 补货算法 + 规则引擎 | +| **库存流水** | 进出库全记录、库存变动追溯 | 库存流水表 | + +### 4.4 广告与投放分析 + +| 功能点 | 核心逻辑 | 复刻方案 | +| :--- | :--- | :--- | +| **广告仪表盘** | 花费、曝光、点击、转化核心指标 | 广告聚合服务 | +| **广告分析** | 广告活动效果、广告组效果、关键词效果 | 多层级分析 | +| **ROI 分析** | 广告投入产出比、ACOS、ROAS 分析 | ROI 计算引擎 | +| **优化建议** | 关键词优化、出价调整、预算优化建议 | 规则引擎 + AI 辅助 | + +### 4.5 红人营销分析 (KOL/KOC) + +| 功能点 | 核心逻辑 | AGI 演进方向 | +| :--- | :--- | :--- | +| **带货力评估** | 基于历史销量、粉丝画像、互动率等维度建立达人带货力模型 | AGI 预测达人带货潜力 | +| **资源匹配** | 基于商品属性与达人粉丝特征，实现精准的"货找人" | 自动匹配 + 邀约 | +| **效果监测** | 精准统计每个达人带来的订单、金额与实际利润 | ROI 实时核算 | +| **佣金分账** | - | DID 主权分账 + ZKP 隐私保护 | + +### 4.6 可视化报表 + +| 功能点 | 核心逻辑 | 复刻方案 | +| :--- | :--- | :--- | +| **仪表盘** | 自定义仪表盘、拖拽式布局 | Dashboard 编辑器 | +| **图表组件** | 折线图、柱状图、饼图、漏斗图、热力图 | ECharts/AntV 集成 | +| **报表导出** | PDF、Excel、图片导出 | 导出服务 | +| **定时推送** | 邮件/钉钉/微信定时推送报表 | 定时任务 + 消息推送 | + +### 4.7 预警与监控 + +| 功能点 | 核心逻辑 | 复刻方案 | +| :--- | :--- | :--- | +| **销售预警** | 销售额异常下降、订单量异常波动 | 阈值监控 + 告警 | +| **库存预警** | 缺货预警、呆滞预警、库容预警 | 库存监控 + 消息 | +| **利润预警** | 利润率低于阈值、亏损订单预警 | 利润监控 + 告警 | +| **异常监控** | 数据同步异常、API 调用异常 | 系统监控 + 告警 | + +--- + +## 5. 运营服务类标杆拆解 + +### 5.1 无 API 执行能力 + +| 功能点 | 核心价值 | AGI 演进方向 | +| :--- | :--- | :--- | +| **一键智能搬家** | 支持跨平台一键抓取，自动进行标题优化与属性映射 | AGI 自动调整 Listing | +| **自愈式采集** | 基于视觉识别与 DOM 语义分析，在目标网站改版时自动重调策略 | 完全自治采集 | +| **No-API 履约** | 模拟真实用户行为进行批量打单、面单回传与单号同步 | 全自动影子运营 | +| **合规管控** | AGI 侵权预警，识别图片中的 Logo、版权元素 | TEE 可信执行环境 | + +### 5.2 本地化运营 + +| 功能点 | 核心价值 | +| :--- | :--- | +| **多语种客服** | 本地语言客服支持 | +| **文化适配** | 跨文化营销内容生成 | +| **本地化合规** | 目标市场法规遵循 | + +--- + +## 6. AGI 演进路线图 + +### 6.1 传统功能 vs 自治能力映射 + +| 传统功能 (Manual/Rule) | 业务痛点 | AGI 解决方案 (Autonomous) | +| :--- | :--- | :--- | +| **静态补货公式** | 无法应对大促/突发趋势 | **自演化补货引擎**：感知全球流量瞬时变化 | +| **人工客服回复** | 响应慢、成本高、多语种难 | **24/7 主权客服**：具备贸易主权意识的 AGI 代理 | +| **固定分仓规则** | 库容浪费、物流成本非最优 | **智能履约编排**：基于 AGI 优化的多式联运决策 | +| **手工对账** | 周期长、易出错 | **ZKP 隐私审计**：在保护数据主权的前提下自动对账 | +| **人工选品** | 效率低、维度单一 | **AGI 趋势感知**：多源数据融合的智能选品 | + +### 6.2 实施阶段规划 + +#### P0 - 原子还原阶段 +- [ ] 实现多平台授权管理与 Token 刷新 +- [ ] 构建全局 SKU 数据库与属性映射 +- [ ] 开发多源订单归集与状态机 +- [ ] 实现库存同步与锁定机制 +- [ ] 开发自愈式采集插件，实现 No-API 数据抓取 + +#### P1 - 决策自治阶段 +- [ ] 开发批量刊登与模板引擎 +- [ ] 实现自动审单与规则引擎 +- [ ] AGI 自动根据竞品动态调整 Listing 描述与素材 +- [ ] 实现 TikTok 全球趋势数据的自动化爬取与看板 +- [ ] 建立 KOL 资源库，实现带货效果追踪 + +#### P2 - 主权合规阶段 +- [ ] 多租户隔离与权限管理 +- [ ] SSO 企业登录 +- [ ] WebHook 事件总线 +- [ ] 基于 ZKP 的隐私审计 +- [ ] DID 主权分账协议 + +--- + +## 7. 竞品功能对比总表 + +| 功能模块 | 易仓 | 店小秘 | 船长BI | 91妙手 | Crawlful 复刻方案 | +| :--- | :---: | :---: | :---: | :---: | :--- | +| **多平台接入** | ★★★ | ★★★ | ★★ | ★★ | Connector Bus 标准化 | +| **WMS 仓储** | ★★★ | ★★ | - | ★ | WMS 智能仓储 | +| **订单处理** | ★★★ | ★★★ | - | ★★★ | OMS 状态机 | +| **数据分析** | ★★ | ★★ | ★★★ | ★ | BI 分析引擎 | +| **无 API 执行** | - | - | - | ★★★ | No-API Bridge | +| **AGI 自治** | - | - | - | ★ | **核心差异化** | + +--- + +## 8. 核心优势总结 + +通过本综合拆解，Crawlful 将具备**"行业深度 + AGI 速度 + 主权安全"**的三重优势： + +1. **极简接入**：多平台一键授权，分钟级完成接入 +2. **统一管理**：跨平台商品、订单、库存统一视图 +3. **高效运营**：批量操作 + 自动化工作流 + AGI 决策 +4. **主权安全**：数据通过 DID/Vault 掌握在卖家手中 +5. **利润自治**：AGI 自动寻找更便宜的货源与更快的物流 +6. **隐私合规**：ZKP 隐私审计保护数据主权 + +--- + +**文档维护者**：Crawlful Hub 团队 +**关联看板**：[collaboration-board.md](../governance/collaboration-board.md) +**业务总纲**：[global-business-blueprint.md](../blueprints/global-business-blueprint.md) diff --git a/docs/blueprints/arch-overview-v30.md b/docs/blueprints/arch-overview-v30.md new file mode 100644 index 0000000..a4cbf29 --- /dev/null +++ b/docs/blueprints/arch-overview-v30.md @@ -0,0 +1,69 @@ +# 🏢 Crawlful Hub 架构总览 (V1.0 - Enterprise Trade ERP) + +## 1. 文档导航 (V1.0 体系) +- **最高业务蓝图**：[global-business-blueprint.md](global-business-blueprint.md) +- **全局状态机与任务归属**：[collaboration-board.md](../governance/collaboration-board.md) +- **原子规格与实施标准**：[task-specifications.md](../governance/task-specifications.md) +- **全量文档索引**：[doc-index.md](../doc-index.md) + +### 1.1 核心分类索引 +- **质量保障**：[golive-redline-checklist.md](../quality/golive-redline-checklist.md) | [frontend-delivery-standard.md](../quality/frontend-delivery-standard.md) +- **设计规格**：[server-initiation.md](../design/server-initiation.md) | [extension-initiation.md](../design/extension-initiation.md) | [console-pipeline-log-design.md](../design/console-pipeline-log-design.md) +- **实施指南**：[server-readme.md](../guides/server-readme.md) | [toc-early-stage-spec.md](../guides/toc-early-stage-spec.md) | [non-saas-multi-tenant-checklist.md](../guides/non-saas-multi-tenant-checklist.md) +- **行业标杆**：[eccang-functional-breakdown.md](../benchmarks/eccang-functional-breakdown.md) | [91miaoshou-spec.md](../benchmarks/91miaoshou-spec.md) + +--- + +## 2. 三层系统架构 (V1.0) +- **Console (前端中控台)**：统一登录、订单审核、发货操作、财务对账、经营报表。 +- **Hub (后端服务层)**：业务逻辑处理、数据持久化、任务调度、消息通知。 +- **Extension / Win Node (边缘执行层)**： + - 插件负责轻量采集触发、DOM 解析与状态展示； + - Win Node Agent 负责无 API 平台执行、指纹隔离与环境自检。 + +--- + +## 3. 平台接入策略 (Hybrid Logic) +- **有 API 平台 (如 TK Shop API / Amazon SP-API)**：走 `Connector Bus` 标准协议，实现毫秒级同步。 +- **无 API 平台 (对标 91miaoshou)**：走 `No-API Bridge`，采用 `Collect -> Clean -> Review -> Publish` 流程。 +- **统一发布编排**：由 `PublishOrchestrator` 统一管理状态机，确保跨平台操作的原子性与幂等性。 + +--- + +## 4. Win 节点执行隔离 (Execution Isolation) +- **执行模型**：`Hub (Control Plane) -> Win Node Agent -> Browser Worker (Isolated)`。 +- **隔离原则**：一店一执行上下文（`profileDir/proxy/fingerprintPolicy`），任务严格串行，规避关联风险。 +- **心跳与遥测**：节点主动注册与维持心跳，异步拉取任务，实时回传任务执行日志。 + +--- + +## 5. 业务闭环 (Business Loop) +- **核心目标**：实现从"商品上架"到"订单履约"到"财务核算"的完整业务闭环。 +- **闭环链路**： + - `商品采集` -> `审核上架` -> `订单归集` -> `发货履约` -> `财务对账` -> `利润分析` +- **净利模型 (ROI-First)**： + - 必须包含：采购成本、平台费、物流、税费、汇率边际、售后摊销、广告投入。 +- **红线控制**： + - B2B 净利率 `<15%` 强制拦截； + - B2C 净利率 `<20%` 触发预警并要求人工确认。 + +--- + +## 6. 企业级商业能力 (Enterprise Capabilities) +- **要素构成**： + - **多租户模型**：`Tenant -> Organization -> Shop -> User` 四层级隔离。 + - **权限与审计**：基于 RBAC 的颗粒度权限，全量操作流水线日志（审计追踪）。 + - **商业化计费**：支持席位、店铺、节点、任务量的四维配额治理。 + - **SLA 与运维**：提供 99.9% 可用性保障、成功率遥测与故障告警。 + - **企业集成**：支持 SSO (OIDC/SAML)、Webhook 事件总线、标准 OpenAPI 套件。 + +--- + +## 7. 技术成熟度评估 (V1.0) +- **技术成熟度**：后端服务与前端控制台已完成基础功能开发，具备生产使用条件。 +- **业务成熟度**：订单、库存、财务三大核心模块已闭环，企业级计费与集成底座正在完善。 +- **核心优势**：务实的产品设计、稳定的核心功能、企业级的安全与审计能力。 + +--- + +**规格维护者**：Crawlful Hub 团队 | **当前版本**：V1.0 diff --git a/docs/blueprints/archive/arch-freeze-v30.md b/docs/blueprints/archive/arch-freeze-v30.md new file mode 100644 index 0000000..1045447 --- /dev/null +++ b/docs/blueprints/archive/arch-freeze-v30.md @@ -0,0 +1,12 @@ +# Crawlful Hub 最终架构冻结 (V30.0) + +## 1. 冻结范围 +- **核心内核 (Kernel)**：DomainRegistry, DomainBootstrap, CDCPipeline。 +- **主权协议 (Sovereign Protocols)**：DID 结算、ZKP 审计逻辑框架。 +- **数据模型 (Models)**：cf_product, cf_order, cf_tenant。 + +## 2. 变更流程 +- 任何对冻结模块的修改必须先在 [collaboration-board.md](file:///d:/trae_projects/crawlful-hub/docs/governance/collaboration-board.md) 报备并由 AI-1 审计。 + +--- +**执行标准**: [task-specifications.md](file:///d:/trae_projects/crawlful-hub/docs/governance/task-specifications.md) | **归档日期**: 2026-03-15 diff --git a/docs/blueprints/archive/v30-arch-optimization-plan.md b/docs/blueprints/archive/v30-arch-optimization-plan.md new file mode 100644 index 0000000..44972cb --- /dev/null +++ b/docs/blueprints/archive/v30-arch-optimization-plan.md @@ -0,0 +1,14 @@ +# V30.0 架构优化执行单 (7天) + +## 1. 核心任务 +- **性能调优**：优化 `CDCPipeline` 并发处理能力。 +- **解耦重构**：完成 `Trade` 与 `Finance` 领域的 EventBus 异步化改造。 +- **安全加固**：上线 ZKP 隐私审计 MVP 版本。 + +## 2. 时间表 +- Day 1-2: 性能基准测试与瓶颈定位。 +- Day 3-5: 核心 Domain 异步化改造。 +- Day 6-7: 联调测试与 V30.0 准入审计。 + +--- +**执行人**: AI-1 (Kernel) | **版本**: V30.0 | **归档日期**: 2026-03-15 diff --git a/docs/blueprints/frontend-architecture.md b/docs/blueprints/frontend-architecture.md new file mode 100644 index 0000000..d736bb4 --- /dev/null +++ b/docs/blueprints/frontend-architecture.md @@ -0,0 +1,217 @@ +# 🎨 Frontend Architecture Blueprint (V2.0 - Console) + +## 1. 架构定位 (Positioning) + +Console 是 Crawlful Hub 的"运营控制台"。它作为业务操作的统一入口，负责订单管理、商品管理、财务对账、数据报表等核心功能的呈现与交互。 + +## 2. 核心模式 (Core Patterns) + +### 2.1 建议-审核工作流 (Suggestion-Approval Workflow) + +所有的核心业务操作（调价、下单、退款）在前端必须遵循以下组件模式： +- **SuggestionCard**: 展示建议详情、依据说明 +- **CausalChainView**: 展示决策背后的业务逻辑链 +- **ActionGroup**: [忽略] | [修正] | [核准执行] + +### 2.2 全链路溯源 (Full-Traceability) +- 每一笔操作必须绑定 `traceId` +- 联动 `TraceController`，支持在 UI 上查看操作日志 + +### 2.3 多租户隔离 (Tenant Isolation) +- 前端请求必须在 Header 中携带 `x-tenant-id` +- UI 适配：根据租户配额（Quota）动态置灰或隐藏未授权功能 + +## 3. 技术栈 (Tech Stack) + +- **框架**: UmiJS 4.x +- **UI 组件库**: Ant Design 5.x +- **状态管理**: **Zustand** + TanStack Query +- **可视化**: AntV G2/G6 (用于经营报表与供应链拓扑展示) +- **HTTP 客户端**: Axios / Umirequest +- **表单管理**: React Hook Form + Zod + +### 3.1 目录结构规范 +``` +src/ +├── components/ # 公共组件 +│ ├── Business/ # 业务组件 +│ └── Basic/ # 基础组件 +├── pages/ # 页面组件 +├── stores/ # Zustand 状态管理 +├── services/ # API 服务层 (TanStack Query) +├── utils/ # 工具函数 +├── hooks/ # 自定义 Hooks +├── types/ # TypeScript 类型定义 +└── assets/ # 静态资源 +``` + +### 3.2 状态管理策略 +| 状态类型 | 管理方案 | 适用场景 | +|---------|---------|---------| +| 全局状态 | **Zustand** | 用户信息、租户配置 | +| 服务端状态 | **TanStack Query** | API 数据缓存、同步 | +| 页面状态 | React Hook Form | 表单数据、列表筛选 | +| 表单验证 | Zod | 复杂表单验证 | + +### 3.3 Zustand 使用示例 +```typescript +// stores/userStore.ts +import { create } from 'zustand'; + +interface UserState { + user: User | null; + tenant: Tenant | null; + setUser: (user: User) => void; + setTenant: (tenant: Tenant) => void; +} + +export const useUserStore = create((set) => ({ + user: null, + tenant: null, + setUser: (user) => set({ user }), + setTenant: (tenant) => set({ tenant }), +})); +``` + +### 3.4 TanStack Query 使用示例 +```typescript +// services/orderService.ts +import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'; +import { request } from 'umi'; + +export const useOrders = (params: OrderQueryParams) => { + return useQuery({ + queryKey: ['orders', params], + queryFn: () => request('/api/v1/orders', { params }), + }); +}; + +export const useCreateOrder = () => { + const queryClient = useQueryClient(); + return useMutation({ + mutationFn: (data: CreateOrderDTO) => + request('/api/v1/orders', { method: 'POST', data }), + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ['orders'] }); + }, + }); +}; +``` + +## 4. 严禁事项 (Red Lines) +- **严禁 Mock 数据 (Zero-Mock)**：除 Storybook 演示外，生产代码禁止硬编码模拟 API +- **严禁越权修改**：前端禁止绕过审核流程直接调用后端 Mutation 接口 +- **严禁敏感数据暴露**：前端禁止在 URL 或日志中暴露敏感信息 + +## 5. 交互规范 + +### 5.1 建议展示 +- 凡是系统生成的建议内容必须带有标签说明来源 +- 异常提示需展示根因分析，而非模糊的"系统错误" + +### 5.2 加载状态 +- 异步操作需展示 Loading 状态 +- 长时操作需展示进度 + +### 5.3 错误处理 +- 4xx 错误：展示具体错误原因，引导用户修正 +- 5xx 错误：展示友好提示，记录日志便于排查 + +## 6. API 设计规范 + +### 6.1 RESTful API 标准 +| 方法 | 用途 | 示例 | +|-----|-----|-----| +| GET | 查询 | GET /api/v1/orders | +| POST | 创建 | POST /api/v1/orders | +| PUT | 完整更新 | PUT /api/v1/orders/:id | +| PATCH | 部分更新 | PATCH /api/v1/orders/:id | +| DELETE | 删除 | DELETE /api/v1/orders/:id | + +### 6.2 响应结构 +```typescript +// 成功响应 +{ + "success": true, + "data": { ... }, + "pagination": { "page": 1, "pageSize": 20, "total": 100 } +} + +// 错误响应 +{ + "success": false, + "error": { "code": "ORDER_NOT_FOUND", "message": "订单不存在", "details": {} } +} +``` + +### 6.3 错误码规范 +| 错误类别 | 错误码前缀 | 说明 | +|---------|-----------|-----| +| 4xx | CLIENT_ERROR_ | 客户端错误（参数、权限） | +| 5xx | SERVER_ERROR_ | 服务端错误（数据库、外部服务） | +| 业务 | BIZ_ | 业务规则错误 | +| 认证 | AUTH_ | 认证授权错误 | + +## 7. 开发环境与工具链 + +### 7.1 环境要求 +| 环境 | 配置要求 | +|-----|---------| +| 开发环境 | Node.js 20.x, MySQL 8.0, Redis 6.0 | +| 测试环境 | Docker 容器化部署 | +| 生产环境 | 阿里云 ECS + RDS + Redis | + +### 7.2 开发工具 +| 工具 | 用途 | +|-----|-----| +| ESLint | 代码检查 | +| Prettier | 代码格式化 | +| TypeScript | 类型检查 | +| Husky | Git Hooks | + +### 7.3 环境变量 +``` +.env # 本地开发 +.env.development # 开发环境 +.env.staging # 预发布环境 +.env.production # 生产环境 +``` + +## 8. 质量保障 + +### 8.1 测试分层 +| 测试类型 | 覆盖目标 | 工具 | +|---------|---------|-----| +| 单元测试 | 业务逻辑、工具函数 | Vitest | +| 组件测试 | UI 组件渲染 | Testing Library | +| E2E 测试 | 关键用户路径 | Playwright | + +### 8.2 性能优化 +| 优化点 | 方案 | 预期收益 | +|-------|-----|---------| +| 首屏加载 | Code Splitting, Lazy Loading | 减少 30% 首屏时间 | +| 请求优化 | TanStack Query 缓存 | 减少 50% 请求数 | +| 图片优化 | WebP, 懒加载 | 减少 40% 带宽 | +| 渲染优化 | React.memo, useMemo | 减少重渲染开销 | + +--- + +## 9. 附录 + +### 9.1 技术栈总览 +| 层级 | 技术方案 | 版本 | +|-----|---------|-----| +| 框架 | UmiJS | 4.x | +| UI 组件 | Ant Design | 5.x | +| 状态管理 | Zustand | 4.x | +| 服务端状态 | TanStack Query | 5.x | +| 表单验证 | React Hook Form + Zod | 最新 | +| 可视化 | AntV G2/G6 | 5.x | + +### 9.2 相关文档 +- [global-business-blueprint.md](./global-business-blueprint.md) +- [arch-overview-v30.md](./arch-overview-v30.md) + +--- + +**文档维护者**：Crawlful Hub 架构团队 | **版本**：V2.0 diff --git a/docs/blueprints/frontend-integration/TEMPLATE.md b/docs/blueprints/frontend-integration/TEMPLATE.md new file mode 100644 index 0000000..e58f5a4 --- /dev/null +++ b/docs/blueprints/frontend-integration/TEMPLATE.md @@ -0,0 +1,40 @@ +# 前端集成蓝图：[功能名称] + +> **[AI-X @ YYYY-MM-DD]**：由后端 Agent 在完成功能逻辑后产出，用于指导 Console 端全栈实现。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：描述前端如何呈现后端建议，以及如何通过交互提升商业 ROI。 +- **关联后端 Service**：`[ServiceName].ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：(例如：Console -> 供应链管理 -> 调价建议) +- **展示组件**： + - [ ] **建议卡片**：展示关键指标（如：预期利润提升 %）。 + - [ ] **因果叙述区**：呈现 `causalChain` 字段，支持 Markdown 渲染。 + - [ ] **对比视图**：展示“当前价格” vs “建议价格”的差异。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 智能调价建议 (AGI Suggested) | + +-----------------------------------------------------------+ + | 建议：跟降 $2.00 | 预期毛利提升：+15% | 信心度：92% | + +-----------------------------------------------------------+ + | [?] 为何建议？ | + | "监测到竞品 XYZ 正在压价，且我方仍有 22% 利润空间..." | + +-----------------------------------------------------------+ + | [ 拒绝建议 ] [ 一键应用并同步平台 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/suggestions?module=PRICING` +- **关键字段映射**： + - `causal_chain` -> 叙述文案 + - `factors` -> 影响因子热力图 +- **状态流转**： + - 点击 [应用] -> `POST /api/v1/suggestions/approve` -> 按钮进入 `Loading` 状态 -> 成功后 Toast 提示并刷新列表。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 移动端适配性校验。 +- [ ] 关键数据脱敏展示。 +- [ ] 错误边界处理（API 500 时的 Fallback 视图）。 diff --git a/docs/blueprints/frontend-integration/approval-center.md b/docs/blueprints/frontend-integration/approval-center.md new file mode 100644 index 0000000..e1b3717 --- /dev/null +++ b/docs/blueprints/frontend-integration/approval-center.md @@ -0,0 +1,34 @@ +# Frontend Integration: Approval Center (通用审批中心) + +## 🎨 UI Layout Sketch +- **Page Path**: `/governance/approval` +- **Component Structure**: + - `ApprovalSummary`: Top metrics (Pending Approvals, Approved, Rejected). + - `ApprovalTabs`: "My Pending", "My History", "All (Admin only)". + - `ApprovalCardList`: Grid showing: + - Type icon (e.g., `HIGH_VALUE_ORDER` in red, `PRICE_CHANGE` in blue). + - Status Badge (e.g., `PENDING` in orange, `APPROVED` in green). + - Stage indicator: `Stage 1/2` (Manager), `Stage 2/2` (Finance). + - Requester & Date. + - Resource ID & Description. + - `ApprovalDetailModal`: + - Full details (Metadata, Amount, etc.). + - Decision log (who approved which stage). + - Decision Narrative from `DecisionExplainabilityEngine`. + - "Approve", "Reject", "Comment" actions. + +## 🔄 Interaction State Machine +- `INITIAL`: Fetching pending requests. +- `PENDING`: Request listed for approver. +- `STAGE_TRANSITION`: Request moving from Stage 1 to Stage 2. +- `APPROVED`: Final approval reached. +- `REJECTED`: Request terminated at any stage. + +## 🔗 API Mapping +- `GET /api/v1/approval/pending`: Fetches `cf_approval_requests` with `status=PENDING`. +- `POST /api/v1/approval/approve`: Triggers `ApprovalService.approve`. +- `GET /api/v1/approval/history`: Fetches `cf_approval_requests` with `status=APPROVED|REJECTED`. + +## 📈 ROI Visualization +- "Compliance Audit Trail": 100% visibility of sensitive actions. +- "Approval Latency": Average time from request to final decision. diff --git a/docs/blueprints/frontend-integration/biz-gov-05-roi-dashboard.md b/docs/blueprints/frontend-integration/biz-gov-05-roi-dashboard.md new file mode 100644 index 0000000..9d2a0d2 --- /dev/null +++ b/docs/blueprints/frontend-integration/biz-gov-05-roi-dashboard.md @@ -0,0 +1,44 @@ +# 前端集成蓝图：建议采纳 ROI 实时看板 (ROI Dashboard) + +> **[AI-2 @ 2026-03-14]**：基于 `DecisionExplainabilityEngine.ts` 补全。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：让管理层实时看到 AI 建议对公司财务的正面贡献，通过“建议执行后预估收益”增强 AGI 的商业互信。 +- **关联后端 Service**：[DecisionExplainabilityEngine.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/ai/DecisionExplainabilityEngine.ts) + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 经营决策 -> ROI 看板 +- **展示组件**： + - **累计贡献指标卡 (Metrics)**： + - 已采纳建议总收益 (Actual Savings/Profit) + - 待处理建议潜在收益 (Potential Savings/Profit) + - **模块收益分布 (Module Split)**：饼图展示 Pricing, Sourcing, Inventory 各自贡献。 + - **趋势分析图 (Trend)**：时间轴展示“AI 建议执行量”与“利润增长”的协同性。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [累计 AI 贡献]：$1,250,000 | 待处理潜在收益：$340,000 | + +-----------------------------------------------------------+ + | 建议分布: [Pricing 45%] [Sourcing 30%] [Inventory 25%] | + +-----------------------------------------------------------+ + | 最近执行建议 (Recent Execution) | + | - SKU-01: 调价方案 (+$500) - SKU-05: 1688 换源 (+$1,200) | + | - SKU-09: 缺货预警 (避免损耗 $800) | + +-----------------------------------------------------------+ + | [ 下钻明细 (Detail) ] [ 导出月度 ROI 报告 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/analytics/roi-metrics?tenantId=T123` +- **关键字段映射**： + - `total_profit_delta` -> 已采纳收益 + - `potential_savings` -> 待处理潜在收益 + - `causalChain` -> 建议的宏观因果描述 +- **状态流转**： + - 自动刷新机制：每 5 分钟轮询或 WebSocket 推送最新 ROI 变动。 + +## 4. 生产校验项 (FE Readiness) +- [x] 金额展示需符合租户币种精度配置。 +- [x] 需对异常大额 ROI 波动进行弹窗预警。 +- [x] 确保在多租户环境下，数据隔离边界绝对严密。 diff --git a/docs/blueprints/frontend-integration/biz-mkt-30-dynamic-pricing.md b/docs/blueprints/frontend-integration/biz-mkt-30-dynamic-pricing.md new file mode 100644 index 0000000..45574f2 --- /dev/null +++ b/docs/blueprints/frontend-integration/biz-mkt-30-dynamic-pricing.md @@ -0,0 +1,40 @@ +# 前端集成蓝图：智能动态调价建议 (Dynamic Pricing) + +> **[AI-1 @ 2026-03-14]**：基于 `DynamicPricingService.ts` 产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：帮助运营人员在保护利润红线的前提下，快速响应市场竞争，通过 AGI 叙述消除“为何改价”的疑虑。 +- **关联后端 Service**：[DynamicPricingService.ts](file:///d:/trae_projects/crawlful-hub/server/src/services/DynamicPricingService.ts) + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 商品管理 -> 价格竞争看板 +- **展示组件**： + - **决策因果流 (Narrative Timeline)**：左侧展示商品现状，右侧展示 AGI 模拟出的调价后利润曲线。 + - **风险预警色**：如果调价后利润率接近 15% (B2B) 或 20% (B2C) 红线，组件背景需变为浅黄色。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | SKU: SKU-12345 | 当前价: $25.00 | 建议价: $22.99 (-$2.01) | + +-----------------------------------------------------------+ + | [AGI 分析报告] | + | 1. 监测到 AliExpress 竞品降价 12%。 | + | 2. 调价后预计销量提升 40%，月利润提升 $450。 | + | 3. 调价后净利润率为 21.5% (高于 20% 预警线)。 | + +-----------------------------------------------------------+ + | [ 查看证据链 (XAI) ] | [ 忽略 ] | [ 一键执行调价建议 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/pricing/suggestions?status=PENDING_REVIEW` +- **核心逻辑映射**： + - 后端 `suggested_price` -> 前端输入框默认值。 + - 后端 `causalChain` -> 前端“AGI 分析报告”文案。 +- **状态流转**： + - 点击 [一键执行] -> 调用 `POST /api/v1/pricing/batch-approve`。 + - 按钮状态切换：`Normal` -> `Processing` -> `Completed` (Green Check)。 + +## 4. 生产校验项 (FE Readiness) +- [x] 价格输入框需支持“低于成本价”二次确认弹窗。 +- [x] 需联动 `DecisionExplainabilityEngine` 展示热力图。 +- [x] 确保在不同屏幕分辨率下，AGI 叙述长文本能优雅折叠。 diff --git a/docs/blueprints/frontend-integration/biz-sup-15-sourcing-optimization.md b/docs/blueprints/frontend-integration/biz-sup-15-sourcing-optimization.md new file mode 100644 index 0000000..d7f0d0f --- /dev/null +++ b/docs/blueprints/frontend-integration/biz-sup-15-sourcing-optimization.md @@ -0,0 +1,42 @@ +# 前端集成蓝图：1688 极速降本比价建议 (Sourcing Optimization) + +> **[AI-1 @ 2026-03-14]**：基于 `SupplyChainService.ts` 补全。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：通过实时比价锁定 1688 源头工厂，为运营提供一键切换货源的决策支持，直接降低采购成本。 +- **关联后端 Service**：[SupplyChainService.ts](file:///d:/trae_projects/crawlful-hub/server/src/services/SupplyChainService.ts) + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 供应链 -> 降本建议 +- **展示组件**： + - **货源对比矩阵 (Source Matrix)**：左侧为当前供应商，右侧为 1688 推荐供应商，对比单价、MOQ、交期。 + - **ROI 预测环**：展示“切换后年化节省总额”。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [货源切换建议] SKU-8899 | 预期单均节省：$1.50 (降幅 18%) | + +-----------------------------------------------------------+ + | 当前源 (Local) | VS | 推荐源 (1688 Direct Factory) | + | 单价: $8.50 | | 单价: $7.00 | + | 交期: 3天 | | 交期: 5天 (风险可控) | + +-----------------------------------------------------------+ + | [?] AGI 深度分析： | + | "该 1688 供应商为勋章工厂，评分 4.8，与当前款式匹配度 98%..." | + +-----------------------------------------------------------+ + | [ 暂时保留 ] [ 一键更新采购路由 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/sourcing/suggestions?type=COST_DOWN` +- **关键字段**： + - `current_source_info` -> 当前货源详情 + - `suggested_source_info` -> 1688 货源详情 + - `causalChain` -> 供应商信誉与匹配度分析 +- **状态流转**： + - 应用建议 -> `POST /api/v1/sourcing/apply-suggestion` -> 自动更新 `cf_product_sourcing` 关联。 + +## 4. 生产校验项 (FE Readiness) +- [x] 需支持 1688 商品主图点击预览。 +- [x] 利润提升计算逻辑需包含“跨境运费摊销”差异。 +- [x] 针对大额节省（> $10,000/年）需有特殊高亮动画。 diff --git a/docs/blueprints/frontend-integration/carbon-credit-trading-ui.md b/docs/blueprints/frontend-integration/carbon-credit-trading-ui.md new file mode 100644 index 0000000..9c564d4 --- /dev/null +++ b/docs/blueprints/frontend-integration/carbon-credit-trading-ui.md @@ -0,0 +1,46 @@ +# 前端集成蓝图：碳信用交易撮合建议 (Carbon Credit Trading) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_LOG_60 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：聚合租户碳足迹数据，撮合碳抵扣额度购买，提升品牌绿色合规等级，增强 DTC 品牌溢价。 +- **关联后端 Service**：`CarbonCreditTradingService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 供应链管理 -> 绿色供应链 -> 碳信用交易 +- **展示组件**： + - [ ] **碳中和看板**：展示租户已抵消的碳排放量。 + - [ ] **碳信用交易列表**：展示 AGI 撮合的碳抵扣交易（Credits, Cost, Provider）。 + - [ ] **绿色合规证书**：展示租户已获得的碳中和证书及对应订单。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 碳信用交易管理 (Carbon Credit Trading) | + +-----------------------------------------------------------+ + | [ 累计抵消: 4,500 kg CO2 ] [ 状态: 已抵消 (SETTLED) ] | + +-----------------------------------------------------------+ + | [ 碳抵扣撮合建议 (Credit Match) ] | + | --------------------------------------------------------- | + | 建议抵扣: 250 kg | 成本: $6.25 | 供应商: Carbon-Pool-X | + +-----------------------------------------------------------+ + | [ AGI 绿色建议 (Green Insight) ] | + | "该订单 (ORD-1122) 碳足迹为 25.5 kg。建议购买碳信用 | + | 以抵销。抵消后可解锁：'绿色品牌' 标签及 10% 税务减免。" | + +-----------------------------------------------------------+ + | [ 忽略建议 ] [ 确认购买并抵扣 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/trade/green/trading/matches` +- **关键字段映射** + - `credits_purchased` -> 抵扣额度 + - `cost_amount` -> 交易成本 + - `provider_did` -> 提供商 DID +- **状态流转**： + - 撮合建议 -> `PENDING` -> 交易确认 -> `SETTLED`。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 碳信用池数据的准实时性核对。 +- [ ] 碳抵消成本的财务对账报表。 +- [ ] 导出包含交易证明的绿色合规证书。 diff --git a/docs/blueprints/frontend-integration/carbon-pledge-ui.md b/docs/blueprints/frontend-integration/carbon-pledge-ui.md new file mode 100644 index 0000000..4966427 --- /dev/null +++ b/docs/blueprints/frontend-integration/carbon-pledge-ui.md @@ -0,0 +1,47 @@ +# 前端集成蓝图：自动化供应链碳配额质押建议 (Carbon Pledge) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_TRADE_60 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：允许租户将积累的碳抵扣额度作为“绿色资产”质押，换取更优的采购账期、更低的手续费或更高的授信额度。 +- **关联后端 Service**：`CarbonPledgeService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 供应链管理 -> 绿色供应链 -> 碳配额质押 +- **展示组件**： + - [ ] **可质押资产看板**：展示租户当前的累计碳信用额度。 + - [ ] **权益兑换建议表**：展示 AGI 建议的质押方案及对应收益。 + - [ ] **质押合约状态流**：展示已生效的质押记录及其对账期的影响。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 碳配额质押建议 (Carbon Pledge) | + +-----------------------------------------------------------+ + | [ 可质押总额: 5,000 kg ] [ 已质押: 1,200 kg ] | + +-----------------------------------------------------------+ + | [ AGI 权益建议 (Pledge Suggestion) ] | + | --------------------------------------------------------- | + | 建议质押: 2,500 kg | 目标收益: 账期延长 15 天 (Net-45) | + | 收益价值: 预估节省资金成本 $120.00/月 | + +-----------------------------------------------------------+ + | [ AGI 洞察 ] | + | "监测到您的碳信用充足，通过质押 50% 的配额，可显著优化 | + | 资金周转率。该操作不会影响您的绿色品牌评级。" | + +-----------------------------------------------------------+ + | [ 拒绝建议 ] [ 确认质押并应用权益 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/trade/green/pledge/suggestions` +- **关键字段映射** + - `pledge_amount` -> 质押量 + - `target_benefit` -> 目标收益 + - `status` -> 质押状态 +- **状态流转**： + - 触发质押 -> `PENDING` -> 供应商/平台确认 -> `ACTIVE`。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 碳信用资产的锁定与释放逻辑界面。 +- [ ] 账期变动在财务模块的实时映射。 +- [ ] 导出包含绿色金融贡献的租户年度审计报告。 diff --git a/docs/blueprints/frontend-integration/cashflow-prediction.md b/docs/blueprints/frontend-integration/cashflow-prediction.md new file mode 100644 index 0000000..3a29408 --- /dev/null +++ b/docs/blueprints/frontend-integration/cashflow-prediction.md @@ -0,0 +1,50 @@ +# 📋 前端实现方案：未来 30 天现金流预测 (Cashflow Prediction) + +## 1. UI 布局草图 (UI Layout Sketch) + +``` ++-------------------------------------------------------------------------+ +| [Breadcrumb: Console > Finance > Cashflow Forecast] | ++-------------------------------------------------------------------------+ +| [Current Cash: $50,000.00] [Projected Day 30: $12,450.00] | ++-------------------------------------------------------------------------+ +| [现金流瀑布图 (Cashflow Waterfall)] | +| [Chart: 当前(柱) -> +待收(绿) -> -待付(红) -> 预计(柱)] | +|-------------------------------------------------------------------------| +| [收支详情 (Breakdown)] | +| +---------------------------------------------------------------------+ | +| | 类型 (Type) | 金额 (Amount) | 关键来源 (Source) | | +| |-------------------------|---------------|---------------------------| | +| | 待结回款 (Receivables) | +$80,000.00 | Amazon/TikTok Shipped Orders| | +| | 供应商欠款 (Payables) | -$110,000.00 | Pending Purchase Orders | | +| | 运营成本 (OpEx) | -$7,550.00 | Salaries/Tools/Server | | +| |-------------------------|---------------|---------------------------| | +| | 预计净变化 (Net) | -$37,550.00 | | | +| +---------------------------------------------------------------------+ | ++-------------------------------------------------------------------------+ +| [风险预警 (Risk Alert)] | +| > [WARNING] 预计 25 天后现金余额将低于安全阈值 (20%)。建议推迟部分采购计划。 | ++-------------------------------------------------------------------------+ +``` + +## 2. 交互状态机 (Interaction FSM) + +- **INIT**: 初始化加载。 +- **PREDICTING**: 调用 `/api/finance/cashflow/predict`。 +- **ALERTING**: 若 `projectedCash < 0` 触发全局红色顶栏告警。 +- **SIMULATING**: 支持手动调整“待收回款比例”查看不同情景下的预测。 + +## 3. 核心 API 字段映射 (API Field Mapping) + +| 前端字段 (Frontend) | 后端 API 字段 (Backend) | 说明 (Description) | +| :--- | :--- | :--- | +| 当前可用现金 | `currentCash` | 实时账户余额 | +| 未来30天预计 | `projectedCash` | 计算后的期末余额 | +| 待收总额 | `totalReceivables` | 已发货未结算订单总额 | +| 待付总额 | `totalPayables` | 待支付采购单总额 | +| 风险等级 | `riskLevel` | LOW/WARNING/CRITICAL | + +## 4. ROI 可视化逻辑 (ROI Visualization) + +- **生存天数 (Burn Rate)**: 自动算出按当前净支出速度，现金还能支撑多少天。 +- **资金缺口建议**: 联动 `SovereignCreditPoolService` 展示可申请的贷款额度建议。 diff --git a/docs/blueprints/frontend-integration/circuit-breaker-ui.md b/docs/blueprints/frontend-integration/circuit-breaker-ui.md new file mode 100644 index 0000000..6b3d507 --- /dev/null +++ b/docs/blueprints/frontend-integration/circuit-breaker-ui.md @@ -0,0 +1,44 @@ +# 前端集成蓝图：全自动执行熔断控制 (Circuit Breaker UI) + +> **[AI-2 @ 2026-03-14]**：由后端 Agent 在完成 Batch 56 熔断器逻辑后产出，用于指导 Console 端全栈实现。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：保护企业资产，当 AGI 执行出现连续异常或资金回撤时，自动切断全自动执行链路，强制转回人工审批模式。 +- **关联后端 Service**：`AutoCircuitBreakerService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> AI 控制台 -> 风险熔断器 +- **展示组件**： + - [ ] **全模块熔断状态矩阵**：显示各业务模块（调价、采购、库存）的实时熔断状态。 + - [ ] **熔断根因展示**：最近一次触发熔断的异常日志。 + - [ ] **手动控制开关**：人工手动强制熔断或重置。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] AGI 熔断保护墙 (Circuit Breaker Status) | + +-----------------------------------------------------------+ + | 模块: 动态调价 | 状态: [ OPEN (已熔断) ] | 失败数: 5/5 | + +-----------------------------------------------------------+ + | 模块: 供应链采购 | 状态: [ CLOSED (正常) ] | 失败数: 0/5 | + +-----------------------------------------------------------+ + | [!] 熔断触发详情: | + | "模块 '动态调价' 已触发熔断保护 (原因: 连续 5 次执行异常)" | + | 时间: 2026-03-14 15:30:22 | + +-----------------------------------------------------------+ + | [ 导出异常报告 ] [ 手动重置并恢复全自动 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/circuit/status` (返回 `cf_circuit_breaker_status` 数据) +- **关键字段映射** + - `status` -> 状态 (OPEN/CLOSED) + - `failure_count` -> 连续失败次数 + - `last_failure_at` -> 最近失败时间 +- **状态流转**： + - 点击 [手动重置] -> `POST /api/v1/circuit/reset` -> 恢复正常。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 熔断状态需使用显眼的红色/绿色标签。 +- [ ] 重置操作必须包含二次确认弹窗。 +- [ ] 熔断触发时应在全局通知栏推送 CRITICAL 级别告警。 diff --git a/docs/blueprints/frontend-integration/compliance-certificate-ui.md b/docs/blueprints/frontend-integration/compliance-certificate-ui.md new file mode 100644 index 0000000..35eaebf --- /dev/null +++ b/docs/blueprints/frontend-integration/compliance-certificate-ui.md @@ -0,0 +1,47 @@ +# 前端集成蓝图：合规证书自动化生成 (Compliance Certificate) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_TRADE_50 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：自动提取订单数据并生成符合目的国要求的电子合规证书（原产地证、CE、FDA），减少人工录入 90%，确保合规过关。 +- **关联后端 Service**：`ComplianceCertificateService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 供应链管理 -> 合规中心 -> 合规证书 +- **展示组件**： + - [ ] **已生成证书流水**：展示每笔订单生成的电子合规证书及其状态。 + - [ ] **合规证书预览**：展示证书详情及对应的 DID 签名。 + - [ ] **多国合规政策提示**：展示各国所需的证书类型。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 合规证书管理 (Compliance Certificates) | + +-----------------------------------------------------------+ + | [ 证书 ID: CERT-2233 ] [ 状态: 已生成 (GENERATED) ] | + +-----------------------------------------------------------+ + | 证书类型: 原产地证 (ORIGIN) | 颁发机构: DID-Gov-Hub | + +-----------------------------------------------------------+ + | [ 证书预览 (Certificate Preview) ] | + | 订单 ID: ORD-5566 | 目的地: 德国 (DE) | 有效期: 12 个月 | + +-----------------------------------------------------------+ + | [ AGI 合规建议 (Compliance Insight) ] | + | "系统已基于订单数据自动生成电子原产地证。已通过 DID 签 | + | 名，符合欧盟 IOSS 合规通关要求。" | + +-----------------------------------------------------------+ + | [ 撤销证书 ] [ 下载电子正本 (PDF) ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/trade/compliance/certificates?order_id=ORD-5566` +- **关键字段映射** + - `certificate_type` -> 证书类型 + - `digital_signature` -> 电子签名 + - `valid_until` -> 有效期 +- **状态流转**： + - 触发生成 -> `GENERATED` -> 被海关/第三方验证 -> `VERIFIED`。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 证书生成逻辑的准实时性核对。 +- [ ] 证书预览界面的水印保护。 +- [ ] 导出包含数字签名的 PDF 证书。 diff --git a/docs/blueprints/frontend-integration/courier-credit-ui.md b/docs/blueprints/frontend-integration/courier-credit-ui.md new file mode 100644 index 0000000..6fe2c60 --- /dev/null +++ b/docs/blueprints/frontend-integration/courier-credit-ui.md @@ -0,0 +1,44 @@ +# 前端集成蓝图：众包物流配送员 DID 信用分级 (Courier Credit) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_LOG_70 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：建立基于 DID 的配送员信用体系，通过自动化评分与等级划分，筛选优质众包资源，降低末端派送风险。 +- **关联后端 Service**：`CourierCreditService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 履约中心 -> 众包资源 -> 配送员信用 +- **展示组件**： + - [ ] **配送员信用分布图**：展示活跃配送员的信用等级分布 (Platinum, Gold, etc.)。 + - [ ] **信用明细卡片**：展示特定配送员的履约率、争议率及 AGI 评价。 + - [ ] **派单优先级设置**：允许管理员配置不同信用分对应的派单权重。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 配送员信用分级管理 (Courier Credit) | + +-----------------------------------------------------------+ + | [ 配送员: Courier-Alpha ] [ 信用分: 95.5 ] [ 等级: 铂金 ] | + +-----------------------------------------------------------+ + | 成功派送: 1,200 | 争议案件: 2 | 准时率: 99.2% | + +-----------------------------------------------------------+ + | [ AGI 信用洞察 (Credit Insight) ] | + | "该配送员信用极佳，近 30 天无任何投诉。建议提升其在核心 | + | 商业区的派单优先级，并解锁 '高货值商品' 派送权限。" | + +-----------------------------------------------------------+ + | [ 降低权限 ] [ 提升派单权重 (1.2x) ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/logistics/courier/credit?did=DID-123` +- **关键字段映射** + - `rating` -> 信用分 + - `successful_deliveries` -> 成功数 + - `dispute_count` -> 争议数 +- **状态流转**： + - 配送完成 -> 调用 `CourierCreditService.updateCourierScore` -> 更新 UI 评分。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 信用分变动的历史趋势曲线图。 +- [ ] 恶意差评的信用申诉处理界面。 +- [ ] 导出包含信用背景的配送员准入清单。 diff --git a/docs/blueprints/frontend-integration/crm-hub.md b/docs/blueprints/frontend-integration/crm-hub.md new file mode 100644 index 0000000..e70bd3b --- /dev/null +++ b/docs/blueprints/frontend-integration/crm-hub.md @@ -0,0 +1,35 @@ +# Frontend Integration: CRM Hub (客户中枢) + +## 🎨 UI Layout Sketch +- **Page Path**: `/business/crm` +- **Component Structure**: + - `CustomerStats`: Top metrics (Total Customers, Bronze/Silver/Gold/Platinum count). + - `CustomerFilter`: Filtering by level, tags, spend, and order count. + - `CustomerTable`: List of customers with: + - Level badge (e.g., `GOLD` in yellow, `PLATINUM` in purple). + - Order count & Total Spend. + - Credit Score (e.g., 95 in green). + - Tags (e.g., "Frequent Buyer", "B2B", "Low Return Rate"). + - `Customer360Drawer`: Full profile on click: + - `ProfileHeader`: Name, Email, Level, Credit Score. + - `OrderHistory`: Timeline of past 10 orders (from `ConsumerOrderService`). + - `TransactionHistory`: Reconciliation status of past 5 transactions (from `FinanceReconService`). + - `DisputeHistory`: Past complaints and resolutions (from `DisputeArbitrationService`). + - `SummaryStats`: Reliability indicator and active disputes count. + - `ActionButtons`: "Edit Profile", "Update Credit", "Send Coupon". + +## 🔄 Interaction State Machine +- `INITIAL`: Fetching global customer profiles. +- `FILTERING`: User applying criteria. +- `VIEWING`: Drawer open with 360 view. +- `UPDATING`: User adjusting credit score or tags. +- `COMMUNICATING`: User sending email or coupon. + +## 🔗 API Mapping +- `GET /api/v1/crm/list`: Fetches `cf_customer_profiles`. +- `GET /api/v1/crm/360?customerId={id}`: Triggers `Customer360Service.getCustomer360`. +- `POST /api/v1/crm/credit`: Triggers `Customer360Service.updateCreditScore`. + +## 📈 ROI Visualization +- "Customer Lifetime Value (LTV)": Total spend per customer over time. +- "Churn Rate": Percentage of customers without orders in 90 days. diff --git a/docs/blueprints/frontend-integration/cross-node-settlement-ui.md b/docs/blueprints/frontend-integration/cross-node-settlement-ui.md new file mode 100644 index 0000000..7c3b486 --- /dev/null +++ b/docs/blueprints/frontend-integration/cross-node-settlement-ui.md @@ -0,0 +1,45 @@ +# 前端集成蓝图：跨节点自治清算协议 (Cross-Node Settlement) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 SOV_NET_02 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：实现 Hub 节点间的自动化利润分润与资金清算，构建去中心化的全球贸易价值网。 +- **关联后端 Service**：`CrossNodeSettlementService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 财务中心 -> 跨节点清算 +- **展示组件**： + - [ ] **节点拓扑图**：展示当前 Hub 与其它贸易 Hub 间的连接状态。 + - [ ] **清算流水表**：展示跨节点分润的详细记录（Source, Target, Amount, Status）。 + - [ ] **清算证明卡片**：展示基于 DID 与 ZKP 的清算证据链。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 跨节点自治清算 (Cross-Node Settlement) | + +-----------------------------------------------------------+ + | [ 当前节点: Hub-Local ] <----( $1,200 )----> [ Hub-Remote ] | + +-----------------------------------------------------------+ + | [ 最近清算记录 ] | + | ID: CN-7788 | 目标: Node-Alpha | 金额: $450.00 | ✅ 已确认 | + +-----------------------------------------------------------+ + | [ AGI 清算洞察 ] | + | "系统已自动识别跨节点订单 ORD-9900 的分润协议。预估结算 | + | 金额：$120.00。清算证据已通过 DID 存证并发送至目标节点。" | + +-----------------------------------------------------------+ + | [ 撤回请求 ] [ 查看 ZKP 证据链 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/finance/settlement/cross-node` +- **关键字段映射** + - `source_node_id` -> 发起节点 + - `target_node_id` -> 目标节点 + - `settlement_proof_hash` -> 证明哈希 +- **状态流转**： + - 发起结算 -> `PENDING` -> 目标节点确认 -> `EXECUTED`。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 跨节点网络延迟的实时监控。 +- [ ] 节点间身份握手证书的有效性校验。 +- [ ] 导出包含多节点路径的全球财务汇总。 diff --git a/docs/blueprints/frontend-integration/crowdsourced-logistics.md b/docs/blueprints/frontend-integration/crowdsourced-logistics.md new file mode 100644 index 0000000..cb98b55 --- /dev/null +++ b/docs/blueprints/frontend-integration/crowdsourced-logistics.md @@ -0,0 +1,45 @@ +# 前端集成蓝图：最后一公里众包路由优化 (Crowdsourced Last-mile) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_LOG_30 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：在传统物流商瘫痪时，自动调度众包资源，确保履约不中断，提升物流韧性。 +- **关联后端 Service**：`CrowdsourcedLogisticsService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 履约中心 -> 众包物流管理 +- **展示组件**： + - [ ] **众包代理地图**：展示各城市活跃的众包代理 (Crowdsourced Agents)。 + - [ ] **调度请求表**：展示已分配的众包任务 (Assigned Tasks)。 + - [ ] **成本对比看板**：展示传统物流 vs 众包物流的成本差异。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 众包物流调度 (Crowdsourced Logistics) | + +-----------------------------------------------------------+ + | [ 状态：已分配 (ASSIGNED) ] | + | 订单 ID: ORD-9012 | 城市: 伦敦 (London) | 代理: Agent-X | + +-----------------------------------------------------------+ + | 预估成本: £12.50 | 传统成本: £8.00 | 差额: +£4.50 | + +-----------------------------------------------------------+ + | [ AGI 韧性建议 (Resilience Insight) ] | + | "传统物流商 (Royal Mail) 罢工，建议启用众包路由。 | + | 虽成本增加 £4.50，但可避免 5 天延误，保护 DSR 评分。" | + +-----------------------------------------------------------+ + | [ 取消调度 ] [ 确认派单并通知代理 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/logistics/crowdsourced/requests` +- **关键字段映射** + - `agent_did` -> 代理 DID + - `city` -> 城市 + - `estimated_cost` -> 预估成本 +- **状态流转**： + - 点击 [确认派单] -> 调用 `POST /api/v1/logistics/crowdsourced/approve` -> 状态变为 `IN_TRANSIT`。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 众包代理状态的实时监控（Online/Offline）。 +- [ ] 众包派送费用的精准核算。 +- [ ] 集成众包 App 的推送通知。 diff --git a/docs/blueprints/frontend-integration/did-settlement.md b/docs/blueprints/frontend-integration/did-settlement.md new file mode 100644 index 0000000..f3881dd --- /dev/null +++ b/docs/blueprints/frontend-integration/did-settlement.md @@ -0,0 +1,49 @@ +# 前端集成蓝图：基于 DID 的自治清算协议 (DID Settlement) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_FIN_40 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：自动化处理品牌方、代运营与达人的三方自动分润，降低结算争议 95%，实现“无感清算”。 +- **关联后端 Service**：`DIDSettlementService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 财务中心 -> 自治清算管理 +- **展示组件**： + - [ ] **DID 合约看板**：展示各主体的 DID 身份与分成比例。 + - [ ] **清算记录表**：展示每笔订单的清算状态与隐私存证证明。 + - [ ] **分润热力图**：展示各主体的历史收益占比。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 自治清算管理 (DID-based Settlement) | + +-----------------------------------------------------------+ + | [ 当前合约状态：已激活 (ACTIVE) ] | + | - 品牌方 (Brand): 70% [DID: brand-001] [✅ Verified] | + | - 代运营 (Ops): 20% [DID: ops-002] [✅ Verified] | + | - 达人 (KOL): 10% [DID: kol-003] [✅ Verified] | + +-----------------------------------------------------------+ + | [ 最近清算记录 (Last 10 Settlements) ] | + | --------------------------------------------------------- | + | Order ID | Party | Amount | Status | ZKP Proof | + | ORD-1234 | Brand | $140.0 | ✅ Done | [ View Proof ] | + | ORD-1234 | Ops | $40.0 | ✅ Done | [ View Proof ] | + | ORD-1234 | KOL | $20.0 | ✅ Done | [ View Proof ] | + +-----------------------------------------------------------+ + | [?] 审计备注：所有清算均通过 ZKP 存证，隐私且不可篡改。 | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/finance/settlement/did` +- **关键字段映射**： + - `party_did` -> DID 标识 + - `party_role` -> 角色 + - `amount` -> 清算金额 + - `proof_hash` -> ZKP 证明哈希 +- **状态流转**： + - 点击 [View Proof] -> 调用 `PrivateAuditService.verifyProof` -> 展示验证通过标识。 + +## 4. 生产校验项 (FE Readiness) +- [ ] DID 身份的实名/实体认证校验。 +- [ ] 大额清算的二次确认机制。 +- [ ] 导出加密格式的清算审计流水。 diff --git a/docs/blueprints/frontend-integration/dispute-arbitration-ui.md b/docs/blueprints/frontend-integration/dispute-arbitration-ui.md new file mode 100644 index 0000000..89cfe94 --- /dev/null +++ b/docs/blueprints/frontend-integration/dispute-arbitration-ui.md @@ -0,0 +1,44 @@ +# 前端集成蓝图：智能争议仲裁建议 (Dispute Arbitration) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_CSM_30 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：自动化处理售后纠纷与退款争议，基于全链路证据链给出公正仲裁建议，降低客服工作量。 +- **关联后端 Service**：`DisputeArbitrationService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 客户成功 -> 争议仲裁工作台 +- **展示组件**： + - [ ] **争议详情卡片**：展示订单 ID、买家 DID、争议理由。 + - [ ] **全链路证据链**：聚合订单、物流、支付的全量数据。 + - [ ] **AGI 仲裁建议**：展示 `decision_suggested` 及 `causal_chain`。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 智能争议仲裁建议 (Dispute Arbitration) | + +-----------------------------------------------------------+ + | [ 状态：已建议 (SUGGESTED) ] | + | 订单 ID: ORD-1234 | 买家: DID-ABC | 争议理由: 未收到 | + +-----------------------------------------------------------+ + | [ AGI 仲裁书 (Arbitration Opinion) ] | + | "建议决策：驳回退款 (REJECT_REFUND)。 | + | 证据链：物流轨迹显示订单已于 2026-03-12 10:20 妥投， | + | 买家主张“未收到”与证据不符。" | + +-----------------------------------------------------------+ + | [ 人工介入 ] [ 一键执行仲裁决定 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/customer/arbitration` +- **关键字段映射** + - `decision_suggested` -> 仲裁决策 + - `causal_chain` -> 仲裁理由 + - `status` -> 仲裁状态 +- **状态流转**： + - 点击 [执行仲裁决定] -> 调用 `POST /api/v1/customer/arbitration/approve` -> 更新订单退款状态。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 证据链中物流轨迹的完整性展示。 +- [ ] 退款金额的货币符号正确显示。 +- [ ] 导出加密且防篡改的仲裁报告 (ZKP)。 diff --git a/docs/blueprints/frontend-integration/dynamic-routing-failover.md b/docs/blueprints/frontend-integration/dynamic-routing-failover.md new file mode 100644 index 0000000..6fb3c97 --- /dev/null +++ b/docs/blueprints/frontend-integration/dynamic-routing-failover.md @@ -0,0 +1,49 @@ +# 前端集成蓝图：全球动态路径对冲与风险熔断 (Global Route Failover) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_LOG_20 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：在黑天鹅事件发生时，自动切换最优路径并对冲物流成本上涨，保护时效。 +- **关联后端 Service**：`DynamicRoutingFailoverService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 供应链管理 -> 路由与风险看板 +- **展示组件**： + - [ ] **全球物流热力图**：展示各港口/航线的健康度。 + - [ ] **路径对比试图**：展示“当前路径” vs “最优建议路径”的时效与成本差异。 + - [ ] **风险预警卡片**：展示各渠道的风险评分 (RiskScore)。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 物流路由与风险看板 (Route & Risk) | + +-----------------------------------------------------------+ + | [ 当前健康度 (Global Health) ] [🟢 Healthy] [🟡 Congested]| + | - US-West (Sea): [🟡 拥堵中 (Level: 0.75)] | + | - EU-Main (Air): [🟢 正常 (Level: 0.12)] | + +-----------------------------------------------------------+ + | [ AGI 路由自愈建议 (Failover Suggestion) ] | + | --------------------------------------------------------- | + | 建议：切换至 [US-East (Air Bypass)] | + | 时效：-48h (节省 2 天) | 成本：+$12.5/kg (建议成本对冲) | + | --------------------------------------------------------- | + | [?] 为何建议？ | + | "洛杉矶港口罢工导致延误 >15天，虽然空运成本高，但可保单。"| + +-----------------------------------------------------------+ + | [ 忽略建议 ] [ 一键切换并更新运费模板 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/logistics/routing/optimal` +- **关键字段映射**： + - `isFailoverTriggered` -> 是否触发自愈建议 + - `riskLevel` -> 风险等级 (CRITICAL, WARNING, SAFE) + - `estimatedCost` -> 预估成本 + - `estimatedLeadTime` -> 预估时效 +- **状态流转**： + - 点击 [一键切换] -> 调用 `POST /api/v1/logistics/routing/approve` -> 更新后端路由状态。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 航线健康数据的实时性校验（< 5 min 延迟）。 +- [ ] 成本对冲方案的详细财务核算展示。 +- [ ] 对接 Google Maps/Three.js 渲染 4D 轨迹。 diff --git a/docs/blueprints/frontend-integration/finance-recon.md b/docs/blueprints/frontend-integration/finance-recon.md new file mode 100644 index 0000000..607377a --- /dev/null +++ b/docs/blueprints/frontend-integration/finance-recon.md @@ -0,0 +1,30 @@ +# Frontend Integration: Finance Reconciliation (财务对账引擎) + +## 🎨 UI Layout Sketch +- **Page Path**: `/erp/finance/reconciliation` +- **Component Structure**: + - `ReconciliationSummary`: Top stats (Total Orders, Matched Count, Discrepancy Amount). + - `DiscrepancyCalendar`: Calendar view of discrepancy days. + - `ReconTable`: Detailed reconciliation list: + - Order ID & Status (Matched, Discrepancy). + - Expected Amount (from Order) vs Actual Amount (from Settlement). + - Gap ($ Delta). + - AI Reasoning (e.g., "Logistics Fee Overcharge", "Tax Miscalculation"). + - `DetailDrilldown`: Click order to see `DecisionExplainabilityEngine` factors (Expected, Actual, Gap). + - `ResolutionCenter`: "Manual Adjust" or "Dispute with Platform" buttons. + +## 🔄 Interaction State Machine +- `INITIAL`: Waiting for settlement data. +- `RECONCILING`: `FinanceReconService` processing orders. +- `MATCHED`: Amount aligns within threshold. +- `DISCREPANCY`: Discrepancy detected, awaiting action. +- `RESOLVED`: Discrepancy cleared (e.g., through adjustment or refund). + +## 🔗 API Mapping +- `POST /api/v1/finance/reconciliation/run`: Triggers `FinanceReconService.performReconciliation`. +- `GET /api/v1/finance/reconciliation/list`: Fetches `cf_finance_reconciliation` records. +- `GET /api/v1/xai/narrative?resourceId={orderId}`: Fetches `DecisionExplainabilityEngine` logic. + +## 📈 ROI Visualization +- "Recovered Funds" from disputes. +- "Revenue Leakage" trend line. diff --git a/docs/blueprints/frontend-integration/fraud-shared-ui.md b/docs/blueprints/frontend-integration/fraud-shared-ui.md new file mode 100644 index 0000000..b57aa4c --- /dev/null +++ b/docs/blueprints/frontend-integration/fraud-shared-ui.md @@ -0,0 +1,41 @@ +# 前端集成蓝图：恶意买家跨租户黑名单共享 (Fraud Shared UI) + +> **[AI-2 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_OPS_137 逻辑后产出，用于指导 Console 端全栈实现。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：跨租户识别高频退款、欺诈性索赔的恶意买家，提供基于共享数据的黑名单建议，降低多租户共同损失。 +- **关联后端 Service**：`FraudSharedService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 客户成功 -> 欺诈与风控 -> 黑名单建议 +- **展示组件**： + - [ ] **恶意买家卡片**：展示买家 Email/Phone。 + - [ ] **威胁分级**：根据跨租户举报次数（如 3次以上）标注红色高危。 + - [ ] **因果叙述区**：展示跨租户的具体举报原因和证据摘要。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 跨租户欺诈风险预警 (Fraud Intelligence) | + +-----------------------------------------------------------+ + | 买家: buyer@gmail.com | 举报次数: 3 | 威胁等级: 高危 | + +-----------------------------------------------------------+ + | [?] 为何预警？ (Causal Chain) | + | "该买家在其他 3 个租户中存在多次'虚假单号'与'恶意索赔'记录" | + +-----------------------------------------------------------+ + | [ 允许交易 (不拉黑) ] [ 一键拉黑 (不再接单) ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/fraud/suggestions` (返回 `cf_blacklist_audit` 数据) +- **关键字段映射** + - `buyer_email` -> 买家标识 + - `anomaly_type` -> 异常类型 (e.g., CROSS_TENANT_FRAUD_HISTORY) + - `reason` -> 叙述文案 +- **状态流转**： + - 点击 [一键拉黑] -> `POST /api/v1/fraud/blacklist` -> 成功后自动拦截该买家的后续订单。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 数据脱敏：前端脱敏显示部分邮箱 (e.g., b***r@gmail.com)。 +- [ ] 按钮防误触：拉黑操作需二次确认。 +- [ ] 举报来源匿名化处理。 diff --git a/docs/blueprints/frontend-integration/fx-hedging-risk.md b/docs/blueprints/frontend-integration/fx-hedging-risk.md new file mode 100644 index 0000000..748ec02 --- /dev/null +++ b/docs/blueprints/frontend-integration/fx-hedging-risk.md @@ -0,0 +1,46 @@ +# 📋 前端实现方案：多币种自动锁汇避险 (FX Hedging) + +## 1. UI 布局草图 (UI Layout Sketch) + +``` ++-------------------------------------------------------------------------+ +| [Breadcrumb: Console > Finance > FX Risk] | ++-------------------------------------------------------------------------+ +| [Currency Pair: USD/CNY] [Current Rate: 7.2450] [Volatility: 2.4%] | ++-------------------------------------------------------------------------+ +| +-------------------------+ +-------------------------+ +-------------+ | +| | 待结汇金额 (Receivable) | | 预估汇损风险 (Risk) | | 建议操作 | | +| | $250,000.00 | | -$1,250.00 | | [立即锁汇] | | +| +-------------------------+ +-------------------------+ +-------------+ | ++-------------------------------------------------------------------------+ +| [汇率趋势与风险等级 (FX Trend & Risk Level)] | +| [Chart: 过去30天汇率波动曲线] | +| > 风险等级: [MEDIUM] (波动率超过 2%) | ++-------------------------------------------------------------------------+ +| [锁汇建议详情 (Hedging Advice)] | +| > AI 建议锁定 50% 的待结汇款项以对冲近期人民币升值风险。 | +| [输入框: 锁汇比例 [%]] [按钮: 发起锁汇请求 (Execute Hedge)] | ++-------------------------------------------------------------------------+ +``` + +## 2.交互状态机 (Interaction FSM) + +- **IDLE**: 页面初始加载。 +- **AUDITING**: 调用 `/api/finance/fx/audit/:pair` 分析风险。 +- **RECOMMENDING**: 渲染避险建议与操作按钮。 +- **EXECUTING**: 点击“发起锁汇”，调用 `MultiAssetSettlementService.lockExchangeRate`。 +- **VERIFIED**: 锁汇指令已发送至银行/支付网关，进入 PENDING_REVIEW。 + +## 3. 核心 API 字段映射 (API Field Mapping) + +| 前端字段 (Frontend) | 后端 API 字段 (Backend) | 说明 (Description) | +| :--- | :--- | :--- | +| 当前汇率 | `latestRate` | 实时同步的中间价 | +| 波动率 | `volatility` | 过去30天的标准差波动 | +| 风险级别 | `riskLevel` | LOW/MEDIUM/CRITICAL | +| 建议动作 | `suggestion` | 具体的避险操作叙述 | + +## 4. ROI 可视化逻辑 (ROI Visualization) + +- **风险热力**: 波动率 > 5% 触发红色闪烁告警。 +- **损耗模拟**: 自动计算“若不锁汇且汇率变动 1%，预计损耗金额”。 diff --git a/docs/blueprints/frontend-integration/global-dispute-router-ui.md b/docs/blueprints/frontend-integration/global-dispute-router-ui.md new file mode 100644 index 0000000..6384e27 --- /dev/null +++ b/docs/blueprints/frontend-integration/global-dispute-router-ui.md @@ -0,0 +1,48 @@ +# 前端集成蓝图：跨节点争议自动仲裁转发 (Global Dispute Router) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 SOV_NET_04 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：在多节点贸易中，实现证据链的自动化路由与转发，支持跨节点的 AGI 联合仲裁，提升争议处理透明度。 +- **关联后端 Service**：`GlobalDisputeRouter.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 客户成功 -> 全球争议工作台 +- **展示组件**： + - [ ] **争议路由地图**：展示争议案件在不同主权节点间的流转路径。 + - [ ] **联合证据链试图**：聚合来自不同 Hub 节点的原始证据。 + - [ ] **跨节点仲裁共识建议**：展示各节点 AGI 的仲裁意见汇总。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 全球争议路由与仲裁 (Global Dispute Router) | + +-----------------------------------------------------------+ + | [ 争议 ID: ARB-1122 ] [ 状态: 路由中 (ROUTED) ] | + +-----------------------------------------------------------+ + | 发起节点: Hub-CN | 当前处理节点: Hub-DE | 待确认节点: Hub-UK | + +-----------------------------------------------------------+ + | [ 跨节点共识 (Consensus) ] | + | - Hub-CN: [✅ 建议退款] "物流延误证明有效" | + | - Hub-DE: [⏳ 仲裁中] 正在核实海外仓签收单 | + +-----------------------------------------------------------+ + | [ AGI 路由建议 ] | + | "该争议涉及跨国清算，建议将物流签收证据转发至目的国节点 | + | 以触发联合仲裁。转发成功率预估：98%。" | + +-----------------------------------------------------------+ + | [ 强制终止 ] [ 一键转发证据链 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/customer/dispute/router/status` +- **关键字段映射** + - `source_node_id` -> 来源节点 + - `target_node_id` -> 目标节点 + - `arbitration_result` -> 仲裁意见汇总 +- **状态流转**： + - 发起路由 -> `ROUTED` -> 节点 AGI 介入 -> `ARBITRATING` -> 达成共识 -> `RESOLVED`。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 跨节点证据同步的一致性校验 (ZKP)。 +- [ ] 不同国家/地区仲裁法规的合规性提示。 +- [ ] 导出加密格式的跨节点仲裁决定书。 diff --git a/docs/blueprints/frontend-integration/green-supply-chain-ui.md b/docs/blueprints/frontend-integration/green-supply-chain-ui.md new file mode 100644 index 0000000..efc0bdd --- /dev/null +++ b/docs/blueprints/frontend-integration/green-supply-chain-ui.md @@ -0,0 +1,46 @@ +# 前端集成蓝图：绿色供应链碳足迹核算与抵扣 (Green Supply Chain) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_LOG_40 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：自动计算订单与商品的碳排放，提供减排建议并建议购买碳抵扣额度，提升品牌绿色竞争力。 +- **关联后端 Service**：`GreenSupplyChainService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 供应链管理 -> 绿色供应链 +- **展示组件**： + - [ ] **碳足迹仪表盘**：展示累计碳排放与抵消额度。 + - [ ] **订单碳足迹记录**：展示每笔订单的碳排放明细 (Logistics, Production, Packaging)。 + - [ ] **减排建议卡片**：展示减排策略 (Strategy, Reduction, Cost)。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 绿色供应链碳足迹 (Green Supply Chain) | + +-----------------------------------------------------------+ + | [ 累计碳排放: 1,500 kg CO2 ] [ 抵消金额: $37.50 ] | + +-----------------------------------------------------------+ + | [ 订单 ID: ORD-1122 ] [ 碳足迹: 25.50 kg CO2 ] | + | --------------------------------------------------------- | + | 物流: 15.00 kg | 生产: 10.00 kg | 包装: 0.50 kg | + +-----------------------------------------------------------+ + | [ AGI 减排建议 (Green Insight) ] | + | "建议：将空运转为海运 (LCL)，预估可减少 75% 碳排放。 | + | 相比空运节省成本：$200。时效增加：10 天。" | + +-----------------------------------------------------------+ + | [ 忽略建议 ] [ 购买碳抵扣额度 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/trade/green/footprint?order_id=ORD-1122` +- **关键字段映射** + - `total_co2` -> 累计碳排放 + - `offset_cost` -> 抵扣金额 + - `status` -> 状态 (ESTIMATED, OFFSET_COMPLETED, etc.) +- **状态流转**： + - 点击 [购买碳抵扣额度] -> 调用 `GreenSupplyChainService.recordFootprint` -> 更新 `status` 为 `OFFSET_COMPLETED`。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 碳足迹计算模型的参数可配置界面。 +- [ ] 碳中和路径的长期跟踪看板。 +- [ ] 导出包含详细证据链的绿色供应链报告。 diff --git a/docs/blueprints/frontend-integration/intermodal-failover-ui.md b/docs/blueprints/frontend-integration/intermodal-failover-ui.md new file mode 100644 index 0000000..498b861 --- /dev/null +++ b/docs/blueprints/frontend-integration/intermodal-failover-ui.md @@ -0,0 +1,49 @@ +# 前端集成蓝图：弹性多式联运自动对冲引擎 (Intermodal Failover) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_LOG_50 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：当全球主航道发生黑天鹅事件时，自动计算并执行多式联运切换（如海转铁），最小化时效延误。 +- **关联后端 Service**：`IntermodalFailoverService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 履约中心 -> 多式联运调度 +- **展示组件**： + - [ ] **全球航道监控图**：展示苏伊士运河、巴拿马运河等关键航道的实时拥堵度。 + - [ ] **多式联运切换建议列表**：展示 AGI 生成的 Failover 建议（SEA_TO_RAIL, SEA_TO_AIR）。 + - [ ] **时效-成本平衡图**：对比原始海运路径与多式联运路径的时效提升与成本增加。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 多式联运自愈看板 (Intermodal Failover) | + +-----------------------------------------------------------+ + | [ 原始路径: 苏伊士运河 (Sea) ] [ 状态: 严重堵塞 (BLOCKED) ] | + +-----------------------------------------------------------+ + | 目的地: 伦敦 (London) | 预估延误: 25 天 | + +-----------------------------------------------------------+ + | [ AGI 路由自愈建议 (Failover Suggestion) ] | + | --------------------------------------------------------- | + | 建议：切换至 [中欧班列 (Sea-to-Rail)] | + | 时效：-10 天 (缩短 10 天) | 成本：+$5.2/kg (建议对冲) | + | --------------------------------------------------------- | + | [?] 为何建议？ | + | "苏伊士运河发生长达 15 天的严重拥堵，海转铁成本仅增加 | + | $5.2/kg，但可避免 10 天以上的订单违约风险。" | + +-----------------------------------------------------------+ + | [ 忽略建议 ] [ 确认切换并对冲运费 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/logistics/failover/calculate?original_route_id=SEA-001` +- **关键字段映射** + - `method` -> 切换方法 (SEA_TO_RAIL, etc.) + - `estimated_cost` -> 预估切换成本 + - `timeframe_days` -> 预估时效 +- **状态流转**： + - 切换发现风险 -> 调用 `IntermodalFailoverService.calculateFailover` -> 重新渲染成本对比图。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 实时获取全球航道拥堵数据。 +- [ ] 支持针对大批量订单的一键批量切换。 +- [ ] 导出包含多式联运切换路径的物流报告。 diff --git a/docs/blueprints/frontend-integration/inventory-aging-ui.md b/docs/blueprints/frontend-integration/inventory-aging-ui.md new file mode 100644 index 0000000..2990651 --- /dev/null +++ b/docs/blueprints/frontend-integration/inventory-aging-ui.md @@ -0,0 +1,51 @@ +# 前端集成方案：海外仓库龄过长清仓建议 (Aging Inventory) - [BIZ_OPS_156] + +## 1. 业务场景描述 (Business Context) +- **目标**：识别在海外仓积压超过 90 天的“死货”，通过自动化的打折、清仓建议释放资金流，降低仓储成本。 +- **用户收益**：提升库存周转率，减少坏账计提，实时掌握全球各仓的资金沉淀情况。 + +## 2. UI 布局草图 (UI Layout Sketch) +- **顶部看板 (Aging KPIs)**: + - `Dead Stock Value`: 积压超过 90 天的库存总价值（美元）。 + - `Avg Inventory Age`: 全球平均库龄。 + - `Potential Cash Release`: 预计通过清仓可释放的现金总额。 +- **中部：库龄分布直方图 (Aging Distribution Chart)**: + - X 轴：库龄区间（0-30, 31-60, 61-90, 90+ 天）。 + - Y 轴：SKU 数量或库存金额。 +- **底部：积压 SKU 清单 (Aging SKU List)**: + - 表格列：SKU ID、仓库、库龄（天）、库存价值、建议操作（`DISCOUNT`, `CLEARANCE`, `LIQUIDATE`）。 + - 操作项：`Apply Discount`（一键同步到多平台改价）、`View Causal Chain`（查看 AI 清仓理由）。 + +## 3. 核心 API 字段映射 (API Mapping) +- **后端服务**: `InventoryAgingService.analyzeAging(tenantId)` +- **响应结构**: + ```json + { + "success": true, + "data": [ + { + "skuId": "SKU-9981", + "warehouseId": "US-WEST-01", + "agingDays": 125, + "stockValue": 5200.50, + "suggestedAction": "CLEARANCE" + } + ] + } + ``` +- **因果链呈现 (XAI Integration)**: + - 提示词：`DecisionExplainabilityEngine.getDecisionNarrative` + - 示例：“该 SKU 已在美西仓积压 125 天，且过去 30 天零动销，资金沉淀 $5200.50，建议执行 5 折清仓以释放库位。” + +## 4. 交互状态机 (Interaction State Machine) +- **Init**: 加载时按仓库维度聚合库龄。 +- **Filter**: 支持按仓库、价格区间、类目筛选。 +- **Bulk Action**: 勾选多个 SKU 批量执行 `Batch Approve Suggestions`。 + +## 5. ROI 可视化逻辑 (ROI Tracking) +- **资产释放率**: 清仓完成后展示回笼资金量。 +- **仓储费节省**: 预计可节省的月度仓储费用（基于库位占用率）。 + +--- +**蓝图维护者**: AI-2 (Internal) | **版本**: V1.0 +**相关任务**: [BIZ_OPS_156](file:///d:/trae_projects/crawlful-hub/docs/governance/collaboration-board.md) diff --git a/docs/blueprints/frontend-integration/inventory-forecast-replenishment.md b/docs/blueprints/frontend-integration/inventory-forecast-replenishment.md new file mode 100644 index 0000000..70fcf60 --- /dev/null +++ b/docs/blueprints/frontend-integration/inventory-forecast-replenishment.md @@ -0,0 +1,48 @@ +# 📋 前端实现方案：AGI 销量预测与智能补货 (Inventory Forecast) + +## 1. UI 布局草图 (UI Layout Sketch) + +``` ++-------------------------------------------------------------------------+ +| [Breadcrumb: Console > Inventory > Smart Replenish] | ++-------------------------------------------------------------------------+ +| [Search SKU: [__________]] [Filter: Low Stock Only [x]] | ++-------------------------------------------------------------------------+ +| +---------------------------------------------------------------------+ | +| | SKU: SKU-9988 (Handheld Blender) | | +| |---------------------------------------------------------------------| | +| | [当前库存: 45 PCS] [7天日均销量: 12.5 PCS] [预计可用天数: 3.6 Days] | | +| |---------------------------------------------------------------------| | +| | [销量预测 (7 Days Forecast)] | | +| | [Chart: 历史销量(蓝线) vs AI 预测销量(绿虚线)] | | +| |---------------------------------------------------------------------| | +| | [AI 补货建议 (Replenishment Advice)] | | +| | > 建议立即补货: 200 PCS | | +| | > 理由: 销售速率增长 20%，当前库存无法支撑至下次补货到货 (Lead time: 7d) | | +| | [按钮: 生成采购单 (Create PO)] [按钮: 忽略建议 (Ignore)] | | +| +---------------------------------------------------------------------+ | ++-------------------------------------------------------------------------+ +``` + +## 2. 交互状态机 (Interaction FSM) + +- **IDLE**: 展示待补货列表。 +- **PREDICTING**: 点击“刷新预测”按钮，调用 `/api/trade/inventory/forecast/:skuId`。 +- **ADVISING**: 渲染 AI 建议与 PO 预填单。 +- **EXECUTING**: 点击“生成采购单”，调用 `TradeService.createPurchaseOrder`，按钮进入 Loading。 +- **COMPLETED**: 采购单生成成功，自动跳转至 PO 详情页。 + +## 3. 核心 API 字段映射 (API Field Mapping) + +| 前端字段 (Frontend) | 后端 API 字段 (Backend) | 说明 (Description) | +| :--- | :--- | :--- | +| 7天日均销量 | `avgDailySales7d` | 最近一周的真实动销速率 | +| AI 预测总量 | `forecastNext7d` | 未来一周的预测销量 | +| 信心指数 | `confidenceScore` | AI 对预测结果的把握度 (0-1) | +| 建议补货量 | `policy.orderQuantity` | 来自 RL 算法的最优订单量 | +| 补货触发点 | `policy.reorderPoint` | 当库存低于此值时建议补货 | + +## 4. ROI 可视化逻辑 (ROI Visualization) + +- **缺货风险分值**: 红色 (Risk > 80) / 橙色 (Risk > 50) / 绿色 (Safe)。 +- **补货 ROI 预估**: 联动 `InventoryRLService` 展示“补货后预计挽回的缺货损失” vs “仓储成本增加额”。 diff --git a/docs/blueprints/frontend-integration/logistics-health-ui.md b/docs/blueprints/frontend-integration/logistics-health-ui.md new file mode 100644 index 0000000..da56b21 --- /dev/null +++ b/docs/blueprints/frontend-integration/logistics-health-ui.md @@ -0,0 +1,58 @@ +# 前端集成方案：物流渠道稳定性实时热力分析 (Logistics Health) - [BIZ_OPS_155] + +## 1. 业务场景描述 (Business Context) +- **目标**：为运营人员提供全球物流渠道的实时健康度监控，识别哪些承运商正在经历严重的延迟或异常，从而及时调整发货策略。 +- **用户收益**：降低物流纠纷率，提升买家时效体验，量化物流服务商（3PL）的表现。 + +## 2. UI 布局草图 (UI Layout Sketch) +- **顶部概览 (Stats Overview)**: + - `Total Active Carriers`: 正在使用的承运商总数。 + - `Global Avg Delivery Time`: 全球平均签收时效（天）。 + - `Critical Channels`: 处于异常状态的渠道数量（高亮红色）。 +- **中间：实时热力图 (Logistics Heatmap)**: + - 利用 `Three.js` 或 `ECharts-GL` 展示全球包裹流动线路。 + - 线路颜色：绿色（正常）、黄色（延迟）、红色（高异常/拥堵）。 +- **底部：承运商明细列表 (Carrier Detail List)**: + - 表格列：承运商名称、平均时效、异常率、稳定性评分 (0-100)、当前状态。 + - 操作项：`Reroute Strategy`（建议切换路由）、`View RCA`（查看 AI 根因分析）。 + +## 3. 核心 API 字段映射 (API Mapping) +- **后端服务**: `ChannelStatusService.analyzeChannels(tenantId)` +- **响应结构**: + ```json + { + "success": true, + "data": [ + { + "carrier": "FedEx", + "avgDeliveryTime": 5.2, + "exceptionRate": 0.015, + "stabilityScore": 88, + "status": "HEALTHY" + }, + { + "carrier": "USPS", + "avgDeliveryTime": 12.4, + "exceptionRate": 0.085, + "stabilityScore": 42, + "status": "CRITICAL" + } + ] + } + ``` +- **因果链呈现 (XAI Integration)**: + - 悬浮展示 `DecisionExplainabilityEngine.getDecisionNarrative` 产出的叙述。 + - 示例：“USPS 渠道稳定性评分仅为 42，主因是异常率 (8.5%) 远超基准 (2.0%)，建议切换至 FedEx。” + +## 4. 交互状态机 (Interaction State Machine) +- **Init**: 进入页面自动调用 `analyzeChannels`。 +- **Loading**: 展示骨架屏（Skeleton Screen）模拟全球包裹流动。 +- **Failover Action**: 点击 `Reroute` 按钮弹出二次确认框，联动 `POST /api/v1/suggestions/batch-approve` 执行策略变更。 + +## 5. ROI 可视化逻辑 (ROI Tracking) +- **对比指标**: 展示切换前后的平均时效提升值（$ \Delta Time $）与 纠纷减少量（$ \Delta Dispute $）。 +- **经济收益**: 计算因降低纠纷而节省的退款总额（$ \Delta Refund $）。 + +--- +**蓝图维护者**: AI-2 (Internal) | **版本**: V1.0 +**相关任务**: [BIZ_OPS_155](file:///d:/trae_projects/crawlful-hub/docs/governance/collaboration-board.md) diff --git a/docs/blueprints/frontend-integration/membership-ltv-ui.md b/docs/blueprints/frontend-integration/membership-ltv-ui.md new file mode 100644 index 0000000..820b4dc --- /dev/null +++ b/docs/blueprints/frontend-integration/membership-ltv-ui.md @@ -0,0 +1,44 @@ +# 前端集成蓝图：基于 LTV 预测的自动化会员治理 (LTV Membership) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_MKT_60 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：根据 AGI 预测的客户长期价值 (LTV)，自动晋升等级并解锁对应权益，提升高价值客户粘性。 +- **关联后端 Service**：`MembershipLTVService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 客户成功 -> 会员等级管理 +- **展示组件**： + - [ ] **客户 LTV 分布图**：展示不同等级客户的预测 LTV 分布。 + - [ ] **晋升记录流**：展示最近自动晋升的客户及其预测理由。 + - [ ] **等级权益看板**：展示 BRONZE, SILVER, GOLD, PLATINUM 对应的权益。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 自动化会员等级管理 (LTV Membership) | + +-----------------------------------------------------------+ + | [ 客户 DID: DID-7890 ] [ 当前等级: GOLD ] [ 预测 LTV: $2,500 ] | + +-----------------------------------------------------------+ + | 历史消费: $1,200 | 订单数: 15 | AGI 预测理由: "高复购潜力" | + +-----------------------------------------------------------+ + | [ AGI 权益建议 (Tier Benefits) ] | + | "该客户已自动晋升至 GOLD 等级。已解锁：专属客服、 | + | 满 $100 减 $20 优惠券、新品优先抢购权。" | + +-----------------------------------------------------------+ + | [ 撤销晋升 ] [ 发送晋升通知给客户 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/marketing/membership/evaluate?did=DID-7890` +- **关键字段映射** + - `predicted_ltv` -> 预测 LTV + - `tier` -> 建议等级 + - `historical_spend` -> 历史消费额 +- **状态流转**： + - 系统定时任务 -> 调用 `MembershipLTVService.evaluateTier` -> 更新 UI 中的等级状态。 + +## 4. 生产校验项 (FE Readiness) +- [ ] LTV 预测模型的参数可配置界面。 +- [ ] 等级晋升的消息推送模板配置。 +- [ ] 导出包含 LTV 预测报告的客户名单。 diff --git a/docs/blueprints/frontend-integration/multi-currency-recon.md b/docs/blueprints/frontend-integration/multi-currency-recon.md new file mode 100644 index 0000000..a84d9b2 --- /dev/null +++ b/docs/blueprints/frontend-integration/multi-currency-recon.md @@ -0,0 +1,45 @@ +# 前端集成蓝图：跨主权多币种对冲对账引擎 (Multi-Currency Recon) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_FIN_50 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：自动化处理汇率波动导致的对账偏差，保护商户资金主权，减少财务核对成本。 +- **关联后端 Service**：`MultiCurrencyHedgingReconService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 财务中心 -> 多币种对账 +- **展示组件**： + - [ ] **汇率波动看板**：展示下单汇率 vs 结算汇率。 + - [ ] **对账偏差列表**：高亮显示 `fx_drift` 超过阈值的订单。 + - [ ] **对冲建议卡片**：展示建议的对冲动作（如：锁定汇率）。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 多币种对冲对账 (Multi-Currency Recon) | + +-----------------------------------------------------------+ + | [ 状态：发现异常 (DISCREPANCY) ] | + | 订单 ID: ORD-5678 | 订单金额: €1,000 | 汇损: -$45.20 | + +-----------------------------------------------------------+ + | 下单汇率: 1 USD = 0.92 EUR | 当前汇率: 1 USD = 0.88 EUR | + +-----------------------------------------------------------+ + | [ AGI 对冲建议 (Hedging Advice) ] | + | "监测到欧元大幅贬值，建议对未来 7 天的欧元结算订单执行 | + | 锁汇操作，预估可挽回损失：$320.00。" | + +-----------------------------------------------------------+ + | [ 忽略 ] [ 一键执行锁汇对冲 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/finance/recon/fx` +- **关键字段映射** + - `fx_drift` -> 汇损金额 + - `order_rate` -> 下单汇率 + - `current_rate` -> 当前汇率 +- **状态流转**： + - 点击 [执行对冲] -> 调用 `POST /api/v1/finance/hedging/approve` -> 状态变为 `HEDGED`。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 汇率数据的实时刷新（< 1 min）。 +- [ ] 汇损金额的货币格式化校验。 +- [ ] 导出包含汇率路径的对账明细。 diff --git a/docs/blueprints/frontend-integration/multi-touch-attribution.md b/docs/blueprints/frontend-integration/multi-touch-attribution.md new file mode 100644 index 0000000..6019089 --- /dev/null +++ b/docs/blueprints/frontend-integration/multi-touch-attribution.md @@ -0,0 +1,46 @@ +# 前端集成蓝图：多触点归因与利润分析 (Multi-Touch Attribution) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_MKT_40 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：识破平台广告的虚假繁荣，还原真实的流量贡献度，优化营销预算分配。 +- **关联后端 Service**：`MultiTouchAttributionService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 营销中心 -> 流量归因分析 +- **展示组件**： + - [ ] **归因模型切换器**：支持 FIRST_CLICK, LAST_CLICK, LINEAR, TIME_DECAY。 + - [ ] **渠道贡献饼图**：展示各 Source/Campaign 的成交金额占比。 + - [ ] **LTV/CAC 趋势图**：对比各渠道的获客成本与长期价值。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 流量归因分析 (Multi-Touch Attribution) | + +-----------------------------------------------------------+ + | 当前模型：[ 线性归因 (LINEAR) ▼ ] | 时间范围：[ 过去 30 天 ▼ ] | + +-----------------------------------------------------------+ + | [ 渠道贡献度 (Revenue Contribution) ] | + | - Google Ads: 45% ($12,000) [==========----------] | + | - Facebook: 30% ($8,000) [=======------------] | + | - TikTok: 15% ($4,000) [===----------------] | + | - Organic: 10% ($2,600) [==-----------------] | + +-----------------------------------------------------------+ + | [?] AGI 深度洞察： | + | "TikTok 渠道虽然 LAST_CLICK 转化低，但在 FIRST_CLICK 模型 | + | 下贡献了 40% 的初始流量，建议保持品牌曝光预算。" | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/marketing/attribution?model=LINEAR` +- **关键字段映射**： + - `source` -> 流量来源 + - `weight` -> 贡献权重 + - `attributed_value` -> 归因成交额 +- **状态流转**： + - 切换模型 -> 发起 API 请求 -> 重新渲染图表。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 支持大数量级日志的异步聚合加载。 +- [ ] 归因模型参数配置的持久化存储。 +- [ ] 导出 PDF 格式的归因分析报告。 diff --git a/docs/blueprints/frontend-integration/node-liquidity-forecast-ui.md b/docs/blueprints/frontend-integration/node-liquidity-forecast-ui.md new file mode 100644 index 0000000..c7fea54 --- /dev/null +++ b/docs/blueprints/frontend-integration/node-liquidity-forecast-ui.md @@ -0,0 +1,44 @@ +# 前端集成蓝图：跨主权多节点资金流动性自动预测 (Liquidity Forecast) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_FIN_90 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：预测全球贸易 Hub 节点的资金缺口，自动建议跨节点资金调拨，确保全球清算网络的高效运行。 +- **关联后端 Service**：`NodeLiquidityForecastService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 财务中心 -> 节点流动性看板 +- **展示组件**： + - [ ] **全球节点流动性热力图**：展示各 Hub 节点的资金盈余/缺口状态。 + - [ ] **资金流入/流出趋势图**：展示特定节点的预测资金流向。 + - [ ] **头寸调拨建议列表**：展示 AGI 生成的资金重平衡建议。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 节点流动性自动预测 (Liquidity Forecast) | + +-----------------------------------------------------------+ + | [ 节点: Hub-EU-01 ] [ 状态: 预警 (TIGHT) ] [ 缺口: $12,500 ] | + +-----------------------------------------------------------+ + | 预计流入: $45,000 | 预计流出: $57,500 | 风险等级: 中高 (TIGHT) | + +-----------------------------------------------------------+ + | [ AGI 调拨建议 (Rebalancing Advice) ] | + | "监测到 Hub-EU-01 明日清算量激增，建议从 Hub-CN-01 调拨 | + | $15,000 以对冲流动性风险。手续费预估：$12.00。" | + +-----------------------------------------------------------+ + | [ 忽略建议 ] [ 一键发起节点间调拨 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/finance/liquidity/forecast?node_id=Hub-EU-01` +- **关键字段映射** + - `net_liquidity` -> 净头寸 + - `risk_level` -> 风险等级 + - `estimated_inflow` -> 预计流入 +- **状态流转**： + - 风险发现 -> 调用 `NodeLiquidityForecastService.forecastNodeLiquidity` -> 触发预警。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 跨节点资金到账的实时追踪。 +- [ ] 调拨费用的动态核算。 +- [ ] 导出包含流动性分析的全球财务月报。 diff --git a/docs/blueprints/frontend-integration/node-resource-quota-ui.md b/docs/blueprints/frontend-integration/node-resource-quota-ui.md new file mode 100644 index 0000000..4e92a55 --- /dev/null +++ b/docs/blueprints/frontend-integration/node-resource-quota-ui.md @@ -0,0 +1,51 @@ +# 前端集成蓝图：跨节点资源共享配额管理 (Resource Quota) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_SOV_14 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：实现全球 Hub 节点间的资源弹性共享，基于声誉分数动态分配算力与存储配额，确保高信用节点在资源紧张时拥有优先权。 +- **关联后端 Service**：`NodeResourceQuotaService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 节点治理 -> 资源共享配额 +- **展示组件**： + - [ ] **配额使用进度条**：展示当前算力、存储的已用配额与总配额。 + - [ ] **配额分配记录表**：展示最近由于声誉变化导致的配额调整历史。 + - [ ] **跨节点任务监控**：展示当前正在借用其它节点算力执行的任务。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 跨节点资源配额 (Resource Quota) | + +-----------------------------------------------------------+ + | [ 当前声誉: 92.5 ] [ 配额状态: 充足 ] | + +-----------------------------------------------------------+ + | 算力配额 (Compute): [==========----------] 450/925 Units | + | 存储配额 (Storage): [=====---------------] 2.1/9.2 GB | + +-----------------------------------------------------------+ + | [ 配额调整日志 ] | + | --------------------------------------------------------- | + | 时间 | 事件 | 算力变更 | 存储变更 | + | 2026-03-14 | 声誉更新(+5) | +50 | +500 MB | + | 2026-03-01 | 系统例行分配 | 875 | 8.7 GB | + +-----------------------------------------------------------+ + | [ AGI 资源建议 ] | + | "您的存储配额利用率较低，建议质押部分存储资源给 Hub-DE-01 | + | 以赚取额外的声誉分。" | + +-----------------------------------------------------------+ + | [ 申请临时扩容 ] [ 资源外借设置 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/governance/resource/quota?node_id=Node-Alpha` +- **关键字段映射**： + - `compute_quota` -> 总算力配额 + - `storage_quota` -> 总存储配额 + - `reputation_score` -> 关联声誉分 +- **状态流转**： + - 声誉变动 -> 调用 `NodeResourceQuotaService.allocateQuota` -> 数据库更新 -> UI 重新渲染。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 算力与存储配额消耗的准实时性核对（误差 < 1%）。 +- [ ] 临时配额申请的自动化审批工作流。 +- [ ] 导出包含跨节点资源贡献的年度技术审计报告。 diff --git a/docs/blueprints/frontend-integration/oms-workbench.md b/docs/blueprints/frontend-integration/oms-workbench.md new file mode 100644 index 0000000..898c36e --- /dev/null +++ b/docs/blueprints/frontend-integration/oms-workbench.md @@ -0,0 +1,32 @@ +# Frontend Integration: OMS Workbench (统一订单工作台) + +## 🎨 UI Layout Sketch +- **Page Path**: `/erp/oms/workbench` +- **Component Structure**: + - `OrderStats`: Top metrics (Total Orders, Pending Audit, Waiting Shipment, Exceptions). + - `OrderFilter`: Multi-dimensional filtering (Platform, Site, Status, Date, Amount, Customer). + - `OrderTable`: Detailed list of orders with: + - Status badges (e.g., `PENDING_AUDIT` in orange, `WAITING_SHIPMENT` in blue). + - Platform/Site icons. + - Items summary. + - Total Amount & Currency. + - Action column: "Audit", "Ship", "Mark Exception", "Reroute". + - `BatchActionPanel`: "Batch Audit", "Batch Ship", "Batch Export". + - `OrderDetailDrawer`: Full details on click, including Health Check results and Auto-Heal logs. + +## 🔄 Interaction State Machine +- `INITIAL`: Fetching multi-platform orders. +- `FILTERING`: User applying criteria. +- `AUDITING`: `ConsumerOrderService.batchAudit` processing. +- `SHIPPING`: `ConsumerOrderService.batchShip` processing. +- `EXCEPTION_HANDLING`: User resolving exception reason. + +## 🔗 API Mapping +- `GET /api/v1/orders/list`: Fetches `cf_consumer_orders`. +- `POST /api/v1/orders/batch-audit`: Triggers `ConsumerOrderService.batchAudit`. +- `POST /api/v1/orders/batch-ship`: Triggers `ConsumerOrderService.batchShip`. +- `POST /api/v1/orders/reroute`: Triggers `ConsumerOrderService.autoReroute`. + +## 📈 ROI Visualization +- "OMS Efficiency": Orders processed per minute compared to manual. +- "Error Reduction": Exception rate before and after AI Health Check. diff --git a/docs/blueprints/frontend-integration/order-profit-analysis.md b/docs/blueprints/frontend-integration/order-profit-analysis.md new file mode 100644 index 0000000..2ea45ca --- /dev/null +++ b/docs/blueprints/frontend-integration/order-profit-analysis.md @@ -0,0 +1,54 @@ +# 📋 前端实现方案：订单级 P&L 穿透分析 (Order P&L Analysis) + +## 1. UI 布局草图 (UI Layout Sketch) + +``` ++-------------------------------------------------------------------------+ +| [Breadcrumb: Console > Finance > Order Analysis] | ++-------------------------------------------------------------------------+ +| [Order ID: #ORD-12345] [Status: Delivered] [Platform: Amazon US] | ++-------------------------------------------------------------------------+ +| +-------------------------+ +-------------------------+ +-------------+ | +| | 营收 (Revenue) | | 基础净利 (Base Profit) | | 真实毛利 (ROI) | | +| | $120.00 | | $35.50 | | 24.5% | | +| +-------------------------+ +-------------------------+ +-------------+ | ++-------------------------------------------------------------------------+ +| [穿透式成本拆解 (Deep Cost Breakdown)] | +| +---------------------------------------------------------------------+ | +| | 项 (Item) | 金额 (Amount) | 备注 (Note) | | +| |-------------------------|---------------|---------------------------| | +| | 商品成本 (COGS) | -$40.00 | 采购价 + 运费 | | +| | 平台佣金 (Fee) | -$18.00 | Amazon Referral Fee (15%) | | +| | 物流费用 (Logistics) | -$25.00 | Last-mile delivery | | +| | 隐形成本 (Hidden Cost) | -$1.50 | [ERP/工具费摊销] (Amortized)| | +| | 汇损/手续费 (FX/Bank) | -$0.50 | 提现损耗 | | +| |-------------------------|---------------|---------------------------| | +| | 最终真实净利 (Net) | $35.00 | 剔除所有隐形成本 | | +| +---------------------------------------------------------------------+ | ++-------------------------------------------------------------------------+ +| [AI 建议 (AI Insights)] | +| > 该订单隐形成本占比 1.25%，处于健康范围。建议保持当前物流路径。 | ++-------------------------------------------------------------------------+ +``` + +## 2. 交互状态机 (Interaction FSM) + +- **IDLE**: 页面初始加载。 +- **LOADING**: 调用 `/api/finance/order-profit/:orderId` 获取穿透数据。 +- **SUCCESS**: 渲染仪表盘与成本表格。 +- **ERROR**: 弹出错误提示，支持“重试”按钮。 + +## 3. 核心 API 字段映射 (API Field Mapping) + +| 前端字段 (Frontend) | 后端 API 字段 (Backend) | 说明 (Description) | +| :--- | :--- | :--- | +| 营收 | `platformAmount` | 订单总金额 | +| 基础净利 | `baseNetProfit` | 未剔除摊销前的利润 | +| 隐形成本 | `hiddenCost` | ERP/工具费等分摊成本 | +| 真实净利 | `realNetProfit` | 最终到手利润 | +| 真实毛利率 | `realMargin` | `realNetProfit / platformAmount` | + +## 4. ROI 可视化逻辑 (ROI Visualization) + +- **进度条**: 使用颜色渐变 (Red < 10% < Yellow < 20% < Green) 展示毛利率。 +- **因果叙述**: 联动 `DecisionExplainabilityEngine` 展示隐形成本的计算依据（如：本月总工具费 $500 / 总订单 5000 = $0.1/单）。 diff --git a/docs/blueprints/frontend-integration/platform-fee-watcher-ui.md b/docs/blueprints/frontend-integration/platform-fee-watcher-ui.md new file mode 100644 index 0000000..aad5523 --- /dev/null +++ b/docs/blueprints/frontend-integration/platform-fee-watcher-ui.md @@ -0,0 +1,47 @@ +# 前端集成方案：多平台佣金比例变动自动抓取建议 (Platform Fees) - [BIZ_OPS_158] + +## 1. 业务场景描述 (Business Context) +- **目标**：当电商平台（如 Amazon）调整佣金比例时，系统自动捕捉变化并评估其对商户利润的影响，提供精准的调价建议。 +- **用户收益**：防止利润被无声侵蚀，确保每一笔交易都符合利润红线（B2C > 20%），自动化处理复杂的成本核算。 + +## 2. UI 布局草图 (UI Layout Sketch) +- **费用变动看板 (Fee Event Feed)**: + - 列表展示：平台、品类、旧费率、新费率、生效日期。 + - 状态：`AUDITED`（已评估）、`ACTION_REQUIRED`（需要调价）。 +- **利润侵蚀模拟器 (Margin Erosion Simulator)**: + - 展示受影响 SKU 的利润率跌幅。 + - 对比图：调价前利润 vs 调价后利润。 +- **调价建议表 (Adjustment Suggestions)**: + - 表格列：SKU、当前售价、建议新售价、预估利润率。 + - 操作：`Batch Update Prices`（一键同步到各平台）。 + +## 3. 核心 API 字段映射 (API Mapping) +- **后端服务**: `PlatformFeeWatcher.auditFeeChanges(tenantId, updates)` +- **响应结构**: + ```json + { + "success": true, + "suggestions": [ + { + "productId": "SKU-AMZ-001", + "advice": "Amazon 佣金上调 1%，预计毛利降至 19.5%（跌破红线）。建议调价至 $59.99。" + } + ] + } + ``` +- **因果链呈现 (XAI Integration)**: + - 浮窗展示：`DecisionExplainabilityEngine.getDecisionNarrative` + - 叙述：“根据 V30.0 利润保护协议，B2C 利润率必须 > 20%。由于佣金上涨导致原 20.5% 的利润跌至 19.5%，系统自动生成保单建议。” + +## 4. 交互状态机 (Interaction State Machine) +- **New Event**: 系统捕获到费率变动，图标闪烁预警。 +- **Review**: 用户进入详情，查看受影响 SKU 列表。 +- **Commit**: 点击“执行调价”，联动 `DynamicPricingService` 发起远程平台 API 调用。 + +## 5. ROI 可视化逻辑 (ROI Tracking) +- **利润挽回值**: 计算执行调价建议后，相比“不调价”挽回的净利润（$ Recovered Profit $）。 +- **合规达标率**: 展示租户下所有 SKU 符合利润红线的比例。 + +--- +**蓝图维护者**: AI-2 (Internal) | **版本**: V1.0 +**相关任务**: [BIZ_OPS_158](file:///d:/trae_projects/crawlful-hub/docs/governance/collaboration-board.md) diff --git a/docs/blueprints/frontend-integration/private-lc-ui.md b/docs/blueprints/frontend-integration/private-lc-ui.md new file mode 100644 index 0000000..8b110ee --- /dev/null +++ b/docs/blueprints/frontend-integration/private-lc-ui.md @@ -0,0 +1,47 @@ +# 前端集成蓝图：基于 ZKP 的链上隐私信用证 (Private L/C) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_FIN_70 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：利用 ZKP 保护商业机密（如供应商 ID、具体利润），同时向金融机构证明交易真实性以换取信贷。 +- **关联后端 Service**：`SovereignPrivateLCService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 财务中心 -> 隐私信用证管理 +- **展示组件**： + - [ ] **信用证看板**：展示信用证合约列表 (ID, Amount, Status, Expiry)。 + - [ ] **ZKP 证明验证卡**：展示隐私存证证明的哈希与验证状态。 + - [ ] **交易流转追踪**：展示信用证的签发、议付、承付全过程。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 隐私信用证管理 (Private L/C) | + +-----------------------------------------------------------+ + | [ 状态：已签发 (ISSUED) ] [ 合约 ID: LC-5544 ] | + +-----------------------------------------------------------+ + | 开证行: DID-Bank-X | 受益人: DID-Supplier-Y | 金额: $50,000 | + +-----------------------------------------------------------+ + | [ ZKP 隐私存证 (Private Proof) ] | + | 证明哈希: 0x8f2...e3d | [ 验证证明真实性 ] [ 隐私设置 ] | + +-----------------------------------------------------------+ + | [ AGI 金融建议 (Finance Insight) ] | + | "该信用证已通过 ZKP 存证，隐私且不可篡改。供应商 ID 已 | + | 被屏蔽，开证行无法识别底层供应源，保护商业机密。" | + +-----------------------------------------------------------+ + | [ 撤销合约 ] [ 发起议付请求 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/finance/lc/contracts` +- **关键字段映射** + - `zkp_proof_hash` -> ZKP 证明哈希 + - `status` -> 合约状态 (ISSUED, HONORED, etc.) + - `expiry_date` -> 过期日期 +- **状态流转**： + - 点击 [验证证明真实性] -> 调用 `PrivateAuditService.verifyProof` -> 展示验证通过标识。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 针对不同层级（如银行、供应商、平台）的隐私级别设置界面。 +- [ ] 信用证到期自动提醒机制。 +- [ ] 导出包含 ZKP 证明的信用证正本。 diff --git a/docs/blueprints/frontend-integration/reputation-perks-ui.md b/docs/blueprints/frontend-integration/reputation-perks-ui.md new file mode 100644 index 0000000..5dee6f1 --- /dev/null +++ b/docs/blueprints/frontend-integration/reputation-perks-ui.md @@ -0,0 +1,50 @@ +# 前端集成蓝图：声誉驱动的阶梯费率与流量倾斜 (Reputation Perks) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_SOV_13 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：通过自动化声誉分级体系，为高信用节点提供更低的结算费率与更高的流量分配优先级，构建正向激励的主权网络。 +- **关联后端 Service**：`ReputationPerksService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 节点治理 -> 声誉权益中心 +- **展示组件**： + - [ ] **声誉等级金字塔**：展示当前节点的声誉分数及其所在的权益阶梯。 + - [ ] **权益应用记录流**：展示最近由于声誉变动导致的费率折扣与流量权重调整。 + - [ ] **激励策略预览表**：展示不同声誉区间对应的具体权益（费率、流量、配额）。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 声誉权益中心 (Reputation Perks) | + +-----------------------------------------------------------+ + | [ 当前节点: Node-Alpha ] [ 声誉分: 92.5 ] [ 等级: 卓越 ] | + +-----------------------------------------------------------+ + | 尊享权益： | + | - 结算费率折扣: -20.00% (已生效) | + | - 流量倾斜系数: 1.5x (已生效) | + +-----------------------------------------------------------+ + | [ 权益变更历史 ] | + | --------------------------------------------------------- | + | 日期 | 变动原因 | 权益调整 | + | 2026-03-14 | 声誉升至 90+ | 费率折扣提升至 20% | + | 2026-03-10 | 完成大额清算 | 声誉分 +2.5 | + +-----------------------------------------------------------+ + | [?] AGI 激励建议： | + | "保持当前的履约成功率，预计下月声誉分可达 95，届时将解锁 | + | '跨节点零费率结算' 试用权。" | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/governance/reputation/perks?node_id=Node-Alpha` +- **关键字段映射**： + - `reputation_score` -> 声誉分 + - `applied_discount` -> 已应用折扣 + - `applied_traffic_weight` -> 已应用流量权重 +- **状态流转**： + - 声誉系统更新分数 -> 触发 `ReputationPerksService.applyPerks` -> UI 自动显示新权益。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 支持权益变动的实时消息推送通知。 +- [ ] 权益详情与计费模块、流量分配模块的最终一致性校验。 +- [ ] 导出包含声誉权益贡献的节点经营分析报告。 diff --git a/docs/blueprints/frontend-integration/sandbox-roi-ui.md b/docs/blueprints/frontend-integration/sandbox-roi-ui.md new file mode 100644 index 0000000..a902d3f --- /dev/null +++ b/docs/blueprints/frontend-integration/sandbox-roi-ui.md @@ -0,0 +1,47 @@ +# 前端集成蓝图：自治执行沙盒与 ROI 评估 (Sandbox & ROI UI) + +> **[AI-2 @ 2026-03-14]**：由后端 Agent 在完成 Batch 56 沙盒系列逻辑后产出，用于指导 Console 端全栈实现。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：为 AGI 决策提供“数字孪生”验证环境。在建议正式生效前，通过沙盒模拟执行并自动回测 ROI，降低全自动化带来的资金回撤风险。 +- **关联后端 Service**：`AutonomousSandboxService.ts`, `SandboxROIAdvisor.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> AI 控制台 -> 执行沙盒 +- **展示组件**： + - [ ] **沙盒执行流展示**：以时间轴形式展示模拟执行的步骤与结果。 + - [ ] **ROI 回测仪表盘**：对比“执行前”与“模拟后”的关键财务指标（毛利、周转率）。 + - [ ] **风险预警标记**：若模拟结果触发业务红线（如 B2B 利润 < 15%），自动高亮显示。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] AGI 执行沙盒回测 (Autonomous Sandbox) | + +-----------------------------------------------------------+ + | 建议 ID: SUG-882 | 模块: 动态调价 | 模拟状态: [ 成功 ] | + +-----------------------------------------------------------+ + | ROI 预估: +$150.50 (基于过去 30 天销量回测) | + | 利润率变化: 22% -> 24.5% | + +-----------------------------------------------------------+ + | [?] 模拟链路摘要 (Execution Trace) | + | 1. 镜像当前 SKU 库存与成本数据... | + | 2. 应用新价格 $29.9 -> $32.5... | + | 3. 计算预估成交量漂移 (-2%)... | + | 4. 汇总最终毛利提升... | + +-----------------------------------------------------------+ + | [ 重新模拟 ] [ 采纳建议并正式执行 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/sandbox/executions` (返回 `cf_sandbox_executions` 数据) +- **关键字段映射** + - `simulated_output` -> 模拟输出详情 + - `estimated_roi` -> 预估收益 + - `status` -> 执行状态 (SUCCESS/RISK_DETECTED) +- **状态流转**： + - 点击 [采纳] -> `POST /api/v1/suggestions/approve` -> 正式生效。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 确保 `estimated_roi` 的货币单位跟随租户设置。 +- [ ] 增加“沙盒隔离模式”标识，防止用户误以为是真实数据。 +- [ ] 模拟执行期间显示加载动画 (Loading State)。 diff --git a/docs/blueprints/frontend-integration/sea-freight-advisor-ui.md b/docs/blueprints/frontend-integration/sea-freight-advisor-ui.md new file mode 100644 index 0000000..73db164 --- /dev/null +++ b/docs/blueprints/frontend-integration/sea-freight-advisor-ui.md @@ -0,0 +1,47 @@ +# 前端集成方案：全球物流拥堵指数与航线优化建议 (Sea Freight Advisor) - [BIZ_OPS_160] + +## 1. 业务场景描述 (Business Context) +- **目标**：全球贸易环境复杂，罢工、恶劣天气或港口瓶颈会严重拖慢发货时效。系统通过监控全球港口实时拥堵指数，为商户提供“避坑”建议和自动绕路方案。 +- **用户收益**：规避超长延迟，降低消费者退款率，提升供应链应对“黑天鹅”事件的韧性。 + +## 2. UI 布局草图 (UI Layout Sketch) +- **全球港口状态地图 (Global Port Map)**: + - 地图标记：主要国际港口（LAX, RTM, NGB, SIN 等）。 + - 标记颜色：绿色（畅通）、黄色（拥堵）、红色（瘫痪/罢工）。 +- **受影响订单雷达 (Affected Shipments)**: + - 动态滚动条展示正在经过“红色”港口的订单号。 + - 预计延迟天数实时更新。 +- **自适应路由策略 (Adaptive Routing Suggestions)**: + - 方案 A: `Switch to Air`（切换至空运，展示差价）。 + - 方案 B: `Alternative Port`（切换至临近备选港口）。 + - 方案 C: `Customer Notification`（自动向受影响买家发送道歉信并赠送优惠券）。 + +## 3. 核心 API 字段映射 (API Mapping) +- **后端服务**: `SeaFreightAdvisor.auditRoutes(tenantId, indices)` +- **响应结构**: + ```json + { + "success": true, + "routingSuggestions": [ + { + "port": "Los Angeles (LAX)", + "affectedCount": 150, + "advice": "LA 港口罢工导致平均等待期延长至 14 天。建议后续订单路由至 Long Beach (LGB) 或切换空运。" + } + ] + } + ``` +- **因果链呈现 (XAI Integration)**: + - 叙述：“根据实时海运遥测，LA 港口的作业效率下降 60%，触发预警门槛。系统建议对高货值订单执行空运 Failover。” + +## 4. 交互状态机 (Interaction State Machine) +- **Hover Mark**: 鼠标悬停在港口图标上，展示该港口过去 30 天的拥堵趋势图。 +- **Apply Failover**: 点击“执行绕路”，系统自动更新 `cf_logistics_route` 优先级。 + +## 5. ROI 可视化逻辑 (ROI Tracking) +- **时效保全值**: 计算通过绕路成功规避的平均延迟天数。 +- **退款预防额**: 基于历史数据，预估通过提前通知买家而减少的“未收到货”纠纷退款。 + +--- +**蓝图维护者**: AI-2 (Internal) | **版本**: V1.0 +**相关任务**: [BIZ_OPS_160](file:///d:/trae_projects/crawlful-hub/docs/governance/collaboration-board.md) diff --git a/docs/blueprints/frontend-integration/stock-planner-ui.md b/docs/blueprints/frontend-integration/stock-planner-ui.md new file mode 100644 index 0000000..5c7388f --- /dev/null +++ b/docs/blueprints/frontend-integration/stock-planner-ui.md @@ -0,0 +1,46 @@ +# 前端集成蓝图：大促库存安全水位预测 (Stock Planner UI) + +> **[AI-2 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_OPS_136 逻辑后产出，用于指导 Console 端全栈实现。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：通过历史大促波峰分析，自动预测未来高峰期的 SKU 安全库存，并生成一键补货建议，防止爆款缺货导致流量浪费。 +- **关联后端 Service**：`StockPlannerService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 供应链管理 -> 库存预测建议 +- **展示组件**： + - [ ] **水位预警卡片**：展示当前库存 vs 建议安全水位。 + - [ ] **波峰分析视图**：展示历史波峰乘数（如 5.2x）及日均销量。 + - [ ] **补货建议操作**：支持修改补货量并一键生成采购单。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 爆款缺货风险预警 (AGI Prediction) | + +-----------------------------------------------------------+ + | SKU: SKU-12345 | 当前库存: 50 | 建议安全水位: 260 | + +-----------------------------------------------------------+ + | [?] 预测依据 (Causal Chain) | + | "基于去年 11.11 期间 5.2x 的销量激增，当前库存无法支撑..." | + +-----------------------------------------------------------+ + | 因子分析: | + | - 波峰乘数: 5.2x (权重 50%) | + | - 补货周期: 7 天 (权重 30%) | + | - 日均销量: 10 (权重 20%) | + +-----------------------------------------------------------+ + | [ 忽略 ] [ 一键生成采购建议 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/inventory/suggestions` (返回 `cf_inventory_audit` 数据) +- **关键字段映射** + - `current_stock` -> 当前库存 + - `suggested_stock` -> 建议水位 + - `reason` -> 叙述文案 (Causal Chain) +- **状态流转**： + - 点击 [生成采购建议] -> `POST /api/v1/suggestions/approve` -> 联动 `TradeService.createPurchaseOrder`。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 确保 `suggested_stock` 为整数。 +- [ ] 颜色编码：红色表示库存严重不足，黄色表示接近水位。 +- [ ] 针对零历史销量的 SKU 提供兜底预测逻辑提示。 diff --git a/docs/blueprints/frontend-integration/style-war-ui.md b/docs/blueprints/frontend-integration/style-war-ui.md new file mode 100644 index 0000000..15733ed --- /dev/null +++ b/docs/blueprints/frontend-integration/style-war-ui.md @@ -0,0 +1,47 @@ +# 前端集成方案：SKU 视觉同质化导致的价格战预警 (Same Style War) - [BIZ_OPS_159] + +## 1. 业务场景描述 (Business Context) +- **目标**：识别那些与市场上大量商品长得几乎一模一样、且正在陷入恶性价格战的 SKU。通过 AI 提醒商户避开“红海”竞争，采取差异化策略。 +- **用户收益**：保护毛利率，避免盲目跟降，通过视觉或包装差异化重塑商品竞争力。 + +## 2. UI 布局草图 (UI Layout Sketch) +- **红海 SKU 警告看板 (Red Sea Alert Panel)**: + - 列表展示受威胁的 SKU 图片。 + - 右侧并排展示“最强竞品”的图片，并标注相似度得分（如 98%）。 +- **价格对比走势图 (Price Disadvantage Chart)**: + - 展示过去 7 天我方售价 vs 竞品售价的背离趋势。 +- **差异化行动清单 (Differentiation Actions)**: + - 卡片式建议： + - `Change Creative`: 更换主图（场景化、模特化）。 + - `Bundle Offer`: 增加赠品或合包。 + - `Exclusive Label`: 申请专利或私模认证标识。 + +## 3. 核心 API 字段映射 (API Mapping) +- **后端服务**: `StyleWarService.analyzeCompetition(tenantId, similarities)` +- **响应结构**: + ```json + { + "success": true, + "alerts": [ + { + "productId": "SKU-BAG-01", + "riskLevel": "HIGH", + "advice": "该款与市场上 50+ 竞品视觉重合度 > 95%，且竞品已降价 15%。建议增加个性化挂件作为赠品进行合包销售。" + } + ] + } + ``` +- **因果链呈现 (XAI Integration)**: + - 叙述：“AI 检测到该商品的视觉指纹与行业标杆高度重合，且流量正在向低价侧偏移。单纯降价将导致毛利跌破 15%，故生成差异化竞争建议。” + +## 4. 交互状态机 (Interaction State Machine) +- **Visual Comparison**: 鼠标悬停在相似度得分上，自动弹出两张图片的像素级对比热力图。 +- **Apply Strategy**: 点击建议项，自动生成任务包发送给 AI-1 (Creative) 生成新主图。 + +## 5. ROI 可视化逻辑 (ROI Tracking) +- **利润保护额**: 计算采取差异化策略后，维持原价所保住的利润 vs 跟降后的利润损失。 +- **点击率提升**: 监控更换主图后的 CTR 变化。 + +--- +**蓝图维护者**: AI-2 (Internal) | **版本**: V1.0 +**相关任务**: [BIZ_OPS_159](file:///d:/trae_projects/crawlful-hub/docs/governance/collaboration-board.md) diff --git a/docs/blueprints/frontend-integration/supplier-capacity-watch.md b/docs/blueprints/frontend-integration/supplier-capacity-watch.md new file mode 100644 index 0000000..a44f5cf --- /dev/null +++ b/docs/blueprints/frontend-integration/supplier-capacity-watch.md @@ -0,0 +1,45 @@ +# 前端集成蓝图：自动化供应商产能预警 (Supplier Capacity Watch) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_TRADE_30 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：提前感知供应商交期延误风险，通过 AGI 预测产能饱和度，自动建议切换备选源。 +- **关联后端 Service**：`SupplierCapacityWatchService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 供应链管理 -> 供应商产能看板 +- **展示组件**： + - [ ] **产能饱和度图表**：展示各供应商的积压比例 (Backlog Ratio)。 + - [ ] **风险预警列表**：高亮显示 `risk_score` 超过阈值的供应商。 + - [ ] **交期延误预测**：展示各供应商的预估延误天数。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 供应商产能看板 (Supplier Capacity Watch) | + +-----------------------------------------------------------+ + | [ 状态：严重预警 (CRITICAL) ] | + | 供应商 ID: SUP-001 | 积压比例: 145% | 预估延误: 8 天 | + +-----------------------------------------------------------+ + | 最大日产能: 10,000 | 当前积压: 14,500 | 平均交期: 7 天 | + +-----------------------------------------------------------+ + | [ AGI 风险洞察 (Capacity Insight) ] | + | "供应商 SUP-001 产能严重过载，积压比例达 145%，预估 | + | 交期延误 8 天。建议切换备选源 SUP-002，其目前产能充足。"| + +-----------------------------------------------------------+ + | [ 保持现状 ] [ 切换至备选源 SUP-002 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/trade/supplier/capacity` +- **关键字段映射** + - `backlog_ratio` -> 积压比例 + - `estimated_delay_days` -> 预估延误天数 + - `risk_score` -> 风险评分 +- **状态流转**： + - 点击 [切换备选源] -> 调用 `POST /api/v1/trade/sourcing/failover` -> 更新后端采购路由。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 供应商产能数据的准实时性（< 1 hour 延迟）。 +- [ ] 备选源的产能余量实时检查。 +- [ ] 导出包含风险预测的采购报告。 diff --git a/docs/blueprints/frontend-integration/supplier-risk-radar-ui.md b/docs/blueprints/frontend-integration/supplier-risk-radar-ui.md new file mode 100644 index 0000000..215d07e --- /dev/null +++ b/docs/blueprints/frontend-integration/supplier-risk-radar-ui.md @@ -0,0 +1,49 @@ +# 前端集成方案：供应商经营风险自动探测 (Supplier Risk Radar) - [BIZ_OPS_157] + +## 1. 业务场景描述 (Business Context) +- **目标**：监控供应商的经营合规性，识别潜在的法律诉讼、经营异常或财务危机，防止供应链突然中断。 +- **用户收益**：规避违约风险，保障货源稳定，建立供应商全生命周期的风险闭环。 + +## 2. UI 布局草图 (UI Layout Sketch) +- **风险雷达图 (Risk Radar Chart)**: + - 五个维度：`Quality`, `Lead Time`, `Financial Stability`, `Legal Compliance`, `Price Stability`。 + - 不同颜色的区域代表不同的风险级别。 +- **高危预警列表 (Critical Alerts)**: + - 红色卡片展示：供应商名称、风险等级（CRITICAL/HIGH）、触发原因。 + - 操作：`Start Audit`（发起实地审厂）、`Switch Source`（寻找替代货源）。 +- **供应商档案详情 (Supplier Dossier)**: + - 展示法务公告原文、历史处罚记录、工商变更流水。 + +## 3. 核心 API 字段映射 (API Mapping) +- **后端服务**: `SupplierRiskRadar.scanRisks(tenantId)` +- **响应结构**: + ```json + { + "success": true, + "data": [ + { + "supplierId": "SUP-007", + "name": "义乌某某电子厂", + "riskLevel": "CRITICAL", + "notices": ["经营异常名录", "劳动争议诉讼"], + "lastScanAt": "2026-03-14T10:00:00Z" + } + ] + } + ``` +- **因果链呈现 (XAI Integration)**: + - 调用 `DecisionExplainabilityEngine.getDecisionNarrative` + - 示例：“该供应商已被列入经营异常名录，且过去 3 个月质量破损率从 2% 飙升至 12%，建议立即停止新订单下发。” + +## 4. 交互状态机 (Interaction State Machine) +- **On Dashboard Load**: 执行全量租户供应商扫描。 +- **Risk Expansion**: 点击风险等级可展开具体的法务/工商证据链。 +- **Mitigation Action**: 选择 `Switch Source` 自动跳转至 `VisualSourcing` 页面。 + +## 5. ROI 可视化逻辑 (ROI Tracking) +- **风险规避值**: 计算若该供应商突然倒闭可能导致的未交付订单总损失（$ Expected Loss $）。 +- **供应链韧性**: 展示通过多元化货源分散风险后的系统稳定性提升。 + +--- +**蓝图维护者**: AI-2 (Internal) | **版本**: V1.0 +**相关任务**: [BIZ_OPS_157](file:///d:/trae_projects/crawlful-hub/docs/governance/collaboration-board.md) diff --git a/docs/blueprints/frontend-integration/tax-routing-optimizer.md b/docs/blueprints/frontend-integration/tax-routing-optimizer.md new file mode 100644 index 0000000..7533cbb --- /dev/null +++ b/docs/blueprints/frontend-integration/tax-routing-optimizer.md @@ -0,0 +1,44 @@ +# 前端集成蓝图：跨主权税务路由优化引擎 (Tax Routing Optimizer) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_FIN_60 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：在多个目的国发货时，自动选择税务成本最低（如 IOSS vs OSS）的路由，保护商户资金。 +- **关联后端 Service**：`TaxRoutingOptimizerService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 财务中心 -> 税务路由管理 +- **展示组件**： + - [ ] **多国税务政策对比图**：展示 IOSS, OSS, DDP, DDU 在不同国家的成本差异。 + - [ ] **税务路由建议表**：展示已生成的路由建议（Method, Tax, Cost）。 + - [ ] **合规风险雷达图**：展示不同方法的风险评估（Risk Level）。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 税务路由优化管理 (Tax Routing) | + +-----------------------------------------------------------+ + | [ 目的国: 德国 (DE) ] [ 订单金额: €120 ] [ 路由建议: IOSS ] | + +-----------------------------------------------------------+ + | 预估税额: €24.00 | 合规费用: €1.50 | 总成本: €25.50 | + +-----------------------------------------------------------+ + | [ AGI 路由洞察 (Tax Insight) ] | + | "该订单金额低于 €150，使用 IOSS 路由可享受极低合规成本。| + | 相比 DDP 节省：€3.50。风险等级：低 (LOW)。" | + +-----------------------------------------------------------+ + | [ 忽略建议 ] [ 应用 IOSS 路由策略 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/finance/tax/routing/optimize?country=DE&value=120` +- **关键字段映射** + - `chosen_method` -> 建议税务方法 + - `estimated_tax` -> 预估税额 + - `total_cost` -> 总合规成本 +- **状态流转**： + - 切换目的国 -> 调用 `TaxRoutingOptimizerService.optimizeTaxRoute` -> 重新渲染成本对比。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 各国税率数据的实时性核对（< 24 hour 延迟）。 +- [ ] 货币转换的实时汇率应用。 +- [ ] 导出包含税务路径选择理由的财务报表。 diff --git a/docs/blueprints/frontend-integration/trade-compliance-ui.md b/docs/blueprints/frontend-integration/trade-compliance-ui.md new file mode 100644 index 0000000..acf3404 --- /dev/null +++ b/docs/blueprints/frontend-integration/trade-compliance-ui.md @@ -0,0 +1,45 @@ +# 前端集成蓝图：AGI 驱动的全球合规与制裁扫描 (Compliance Scan) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_TRADE_40 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：自动扫描订单与 SKU，识别全球贸易禁令与出口管制风险，防止商户产生合规违约金。 +- **关联后端 Service**：`TradeComplianceService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 供应链管理 -> 合规中心 +- **展示组件**： + - [ ] **风险扫描仪表盘**：展示当前待审核订单的合规风险评分。 + - [ ] **违规详情卡片**：列出具体的制裁项或禁运理由。 + - [ ] **合规热力图**：展示全球各目的国的风险等级分布。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 全球合规与制裁扫描 (Trade Compliance) | + +-----------------------------------------------------------+ + | [ 订单 ID: ORD-9988 ] [ 风险等级: 高 (HIGH) ] [ 评分: 90 ] | + +-----------------------------------------------------------+ + | 目的国: 伊朗 (IR) | 风险详情: 该国家目前处于 OFAC 全面制裁名单 | + +-----------------------------------------------------------+ + | [ AGI 合规建议 (Compliance Insight) ] | + | "建议决策：阻断 (BLOCK)。订单目的国属于制裁名单，继续履 | + | 约将面临极高法律风险。系统已自动挂起该订单。" | + +-----------------------------------------------------------+ + | [ 强制放行 ] [ 取消订单并退款 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/trade/compliance/scan?order_id=ORD-9988` +- **关键字段映射** + - `risk_score` -> 风险评分 + - `is_compliant` -> 是否合规 + - `violations` -> 违规项列表 + - `suggested_action` -> 建议动作 +- **状态流转**： + - 扫描发现风险 -> 订单自动进入 `PENDING_REVIEW` -> 管理员在 Console 端确认。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 实时更新全球制裁名单库。 +- [ ] 支持针对特定 SKU 类别的分级合规检查。 +- [ ] 导出包含详细证据链的合规审计报告。 diff --git a/docs/blueprints/frontend-integration/trade-insurance-ui.md b/docs/blueprints/frontend-integration/trade-insurance-ui.md new file mode 100644 index 0000000..94469a1 --- /dev/null +++ b/docs/blueprints/frontend-integration/trade-insurance-ui.md @@ -0,0 +1,46 @@ +# 前端集成蓝图：跨主权贸易信用保险自动投保 (Trade Insurance) + +> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_FIN_80 逻辑后产出。 + +## 1. 业务意图 (Business Intent) +- **核心价值**：针对高价值跨国订单，基于风险评分自动建议投保方案，保护商户免受坏账与货损风险。 +- **关联后端 Service**：`TradeInsuranceService.ts` + +## 2. UI/UX 布局方案 (Layout Design) +- **页面入口**：Console -> 财务中心 -> 贸易保险管理 +- **展示组件**： + - [ ] **待投保订单列表**：展示 AGI 建议投保的高价值/高风险订单。 + - [ ] **保险方案对比卡片**：展示不同保司的保费、保额及承保范围。 + - [ ] **风险评分仪表盘**：展示订单与供应商的实时风险评估分数。 +- **交互草图**： + ```text + +-----------------------------------------------------------+ + | [Icon] 贸易信用保险管理 (Trade Insurance) | + +-----------------------------------------------------------+ + | [ 待处理建议: 3 ] [ 累计保障额度: $150,000 ] | + +-----------------------------------------------------------+ + | [ 订单 ID: ORD-5566 ] [ 风险评分: 65 (中高) ] | + | --------------------------------------------------------- | + | 建议保费: $25.00 | 保障额度: $1,250.00 | 承保商: Insure-Global | + +-----------------------------------------------------------+ + | [ AGI 投保建议 ] | + | "该订单供应商评分较低且金额较大，建议投保 '综合货损险'。| + | 投保成本仅占订单额 2%，可 100% 覆盖潜在拒付风险。" | + +-----------------------------------------------------------+ + | [ 忽略建议 ] [ 一键投保并锁定费率 ] | + +-----------------------------------------------------------+ + ``` + +## 3. API 交互契约 (API Integration) +- **数据获取**：`GET /api/v1/finance/insurance/suggestions` +- **关键字段映射** + - `premium_amount` -> 保费 + - `coverage_amount` -> 保额 + - `status` -> 状态 (SUGGESTED, ACTIVE, etc.) +- **状态流转**： + - 点击 [一键投保] -> 调用 `TradeInsuranceService.suggestPolicy` -> 更新状态为 `ACTIVE`。 + +## 4. 生产校验项 (FE Readiness) +- [ ] 供应商风险评分的实时展示。 +- [ ] 投保成功后的电子保单下载。 +- [ ] 导出包含投保成本的利润核算报表。 diff --git a/docs/blueprints/global-business-blueprint.md b/docs/blueprints/global-business-blueprint.md new file mode 100644 index 0000000..de32440 --- /dev/null +++ b/docs/blueprints/global-business-blueprint.md @@ -0,0 +1,203 @@ +# 🌐 全球贸易 ERP 业务蓝图 (Global Business Blueprint) - V2.0 + +> **"务实、高效、可靠"** +> 本文档是 Crawlful Hub 的最高业务指令源，定义 ERP 核心业务能力如何落地，确保业务扩展与技术实现同频。 + +--- + +## 1. 业务-技术映射矩阵 (Business-to-Tech Mapping) + +| 传统业务模块 | 行业标杆参考 | Crawlful 业务领域 | 核心功能方向 | +| :--- | :--- | :--- | :--- | +| **商品中枢 (PIM)** | 91妙手、店小秘、通途 | `Trade`, `Product` | **商品多平台刊登与库存统一管理** | +| **订单中枢 (OMS)** | 易仓、积加、船长 BI | `Trade`, `Order` | **多平台订单归集、审核与履约管理** | +| **仓储履约 (WMS)** | 易仓、Flexport、ShipStation | `Logistics`, `Warehouse` | **多仓库存管理与物流路径规划** | +| **财务清算 (FIN)** | 出海匠、易仓、积加 | `Finance`, `Billing` | **订单成本核算与利润分析** | +| **数据与营销 (MKT)** | 蝉妈妈、Koladata | `Marketing`, `Analytics` | **销售数据报表与经营分析** | +| **客户成功 (CSM)** | Zendesk、Freshdesk | `Customer`, `Service` | **售后工单管理与客户跟进** | +| **商业化计费 (BILLING)** | Stripe Billing、Chargebee | `Billing`, `Governance` | **席位/店铺配额计费与套餐管理** | +| **企业集成 (INTEGRATION)** | Okta、Zapier、MuleSoft | `Integration`, `Identity` | **SSO + Webhook + OpenAPI 企业交付** | +| **素材管理 (ASSETS)** | 剪映、BentoGrid | `Media`, `Creative` | **商品素材管理与多平台适配** | +| **全业务报表 (REPORTING)** | 船长 BI、积加、PowerBI | `Analytics`, `Finance` | **多维度经营报表与利润分析** | +| **供应商管理 (SCM)** | 1688采购、供应商管理 | `Procurement`, `Supplier` | **供应商管理与采购询价** | + +--- + +## 2. ERP 实施路线图 (Implementation Roadmap) + +### **第一阶段：核心业务闭环 (Phase 1: Foundation)** +- **目标**：实现订单、库存、财务三大核心模块的完整闭环 +- **关键技术**：Node.js + NestJS + MySQL + Redis + Prisma +- **核心功能**： + - 多平台订单归集与管理 + - 库存同步与预警 + - 成本核算与利润分析 + +### **第二阶段：业务拓展 (Phase 2: Expansion)** +- **目标**：扩展供应商管理、售后工单、数据报表等业务模块 +- **关键技术**：React + UmiJS + Ant Design + TanStack Query +- **核心功能**： + - 供应商管理与采购询价 + - 售后工单流转 + - 数据报表与分析 + +### **第三阶段：企业级能力 (Phase 3: Enterprise)** +- **目标**：完善企业级功能，包括多租户、SSO、计费、企业集成 +- **关键技术**：微服务、消息队列、缓存优化 +- **核心功能**： + - 多租户隔离与权限管理 + - 企业单点登录 + - 开放 API 平台 + +--- + +## 3. 行业标杆参考库 (Market Benchmarking) + +### 3.1 ERP系统类 +| 标杆 | 核心优势 | 复刻重点 | +|-----|---------|---------| +| [易仓 (ECCANG)](../benchmarks/eccang-functional-breakdown.md) | OMS/WMS/TMS 一体化 | 订单履约 + 仓储管理 | +| [店小秘 (DIANXIAOMI)](../benchmarks/dianxiaomi-spec.md) | 多平台接入 | 平台连接器 | +| [积加 (JINGJIA)](../benchmarks/jingjia-spec.md) | 精品卖家 ERP | 精细化运营 | +| [通途 (TONGTU)](../benchmarks/tongtu-spec.md) | 智能刊登 | 商品发布 | +| [马帮 (MABANG)](../benchmarks/mabang-spec.md) | WMS + 供应链 | 仓储物流 | + +### 3.2 TikTok 专用类 +| 标杆 | 核心优势 | 复刻重点 | +|-----|---------|---------| +| [妙手 ERP (MIAOSHOU)](../benchmarks/miaoshou-tiktok-spec.md) | TikTok 运营 | TikTok 店铺管理 | +| [海鹭科技 (HAILU)](../benchmarks/hailu-tiktok-spec.md) | 达人合作 | 达人管理系统 | +| [电霸 (DIANBA)](../benchmarks/dianba-tiktok-spec.md) | 数据分析 | TikTok 数据分析 | +| [达多多 (DADAODUO)](../benchmarks/dadaoduo-tiktok-spec.md) | 选品工具 | 选品分析 | +| [乐聊 (LELIAO)](../benchmarks/leliao-tiktok-spec.md) | 客服系统 | 消息聚合 + 售后 | + +### 3.3 数据分析类 +| 标杆 | 核心优势 | 复刻重点 | +|-----|---------|---------| +| [船长BI (CAPTAIN BI)](../benchmarks/captain-bi-spec.md) | 商业智能 | 数据可视化 | +| [蝉妈妈 (CHANMAMA)](../benchmarks/chanmama-spec.md) | 直播数据分析 | 趋势分析 | +| [Koladata](../benchmarks/koladata-spec.md) | 红人营销 | 达人效果分析 | + +--- + +## 4. 业务拓展路线 (Business Expansion Roadmap) + +### **4.1 P0：核心能力建设 (2026 Q2)** + +| 模块 | 核心功能 | 优先级 | +|-----|---------|-------| +| **订单模块** | 多平台订单归集、订单审核、发货履约 | P0 | +| **库存模块** | 多仓库存管理、库存同步、预警提醒 | P0 | +| **财务模块** | 订单成本核算、利润计算、财务报表 | P0 | +| **计费模块** | 席位、店铺配额管理 | P0 | + +### **4.2 P1：业务扩展 (2026 Q3)** + +| 模块 | 核心功能 | 优先级 | +|-----|---------|-------| +| **供应商管理** | 1688 比价、采购询价、供应商档案 | P1 | +| **售后工单** | 退货、拒付、纠纷工单统一流转 | P1 | +| **数据报表** | 销售趋势、利润分析、库存周转 | P1 | +| **素材管理** | 商品图片/视频管理与多平台适配 | P1 | +| **TikTok 运营** | TikTok 店铺接入、达人管理 | P1 | + +### **4.3 P2：企业级能力 (2026 Q4)** + +| 模块 | 核心功能 | 优先级 | +|-----|---------|-------| +| **多租户** | 组织架构同步、租户隔离、数据权限 | P2 | +| **企业集成** | SSO 登录、Webhook 事件、OpenAPI 套件 | P2 | +| **高级计费** | 多级套餐、企业定价、增值服务 | P2 | +| **移动端** | 移动审批、移动查看、移动操作 | P2 | + +--- + +## 5. 核心功能模块 + +### 5.1 订单管理 (OMS) + +| 功能 | 说明 | 技术方案 | +|-----|-----|---------| +| 订单归集 | 多平台订单统一拉取 | Connector Bus | +| 订单审核 | 规则引擎自动审核 + 人工复核 | 工作流引擎 | +| 订单履约 | 发货、物流追踪 | 物流集成 | +| 异常处理 | 地址异常、库存不足处理 | 异常队列 | + +### 5.2 库存管理 (WMS) + +| 功能 | 说明 | 技术方案 | +|-----|-----|---------| +| 多仓管理 | 多仓库库存统一管理 | 库存服务 | +| 库存同步 | 实时同步、防止超卖 | 乐观锁 | +| 库存预警 | 安全库存提醒 | 定时任务 | +| 库存流水 | 进出库全记录 | 流水表 | + +### 5.3 财务管理 + +| 功能 | 说明 | 技术方案 | +|-----|-----|---------| +| 成本核算 | 采购、物流、平台费用归集 | Prisma | +| 利润计算 | 订单利润实时计算 | 规则引擎 | +| 财务报表 | 利润表、成本表 | 报表引擎 | +| 回款管理 | 回款跟踪 | 财务服务 | + +### 5.4 供应商管理 + +| 功能 | 说明 | 技术方案 | +|-----|-----|---------| +| 供应商档案 | 供应商信息管理 | 供应商库 | +| 1688 采购 | 1688 一键代采 | 1688 API | +| 采购询价 | 多供应商比价 | 询价服务 | +| 采购统计 | 成本分析、绩效统计 | 分析服务 | + +### 5.5 TikTok 运营 + +| 功能 | 说明 | 技术方案 | +|-----|-----|---------| +| 店铺接入 | TikTok Shop 授权 | TikTok API | +| 商品刊登 | 批量发布 | 刊登服务 | +| 达人管理 | 达人库、邀约、绩效 | 达人服务 | +| 数据分析 | 销售、流量分析 | 分析服务 | +| 客服消息 | 消息聚合、自动回复 | 客服服务 | + +--- + +## 6. 落地技术映射 (Implementation Grounding) + +| 业务能力 | 核心 Service | 关键数据表 | 状态 | +| :--- | :--- | :--- | :--- | +| **多平台订单归集** | `OrderService` | `cf_order`, `cf_order_items` | 🚀 已闭环 | +| **订单分账逻辑** | `FinanceService` | `cf_transaction`, `cf_settlement` | 🚀 已实现 | +| **全口径利润审计** | `PricingService` | `cf_product_cost_snapshot` | 🚀 已实现 | +| **多平台采集** | `CrawlService` | `cf_crawl_task` | 🚀 已闭环 | +| **配额计费** | `QuotaService` | `cf_tenant_quota`, `cf_billing_plan` | ⏳ 开发中 | +| **供应商管理** | `SupplierService` | `cf_supplier` | ⏳ 开发中 | +| **售后工单** | `TicketService` | `cf_ticket` | ⏳ 开发中 | +| **数据报表** | `ReportService` | `cf_report` | ⏳ 规划中 | + +--- + +## 7. 使用方式 (How To Use) + +1. 先在**第 6 节**确定功能所属代码位置与数据表前缀 +2. 在 [task-specifications.md](../governance/task-specifications.md) 查看具体接口定义与字段规格 +3. 在 [collaboration-board.md](../governance/collaboration-board.md) 同步任务状态与开发进度 + +--- + +## 8. 技术栈 + +| 层级 | 技术方案 | 版本 | +|-----|---------|-----| +| 前端框架 | UmiJS | 4.x | +| UI 组件 | Ant Design | 5.x | +| 状态管理 | Zustand + TanStack Query | 4.x / 5.x | +| 后端框架 | NestJS | 10.x | +| ORM | Prisma | 5.x | +| 数据库 | MySQL | 8.0 | +| 缓存 | Redis | 6.0+ | +| 消息队列 | BullMQ | 最新 | + +--- + +**规格维护者**：Crawlful Hub 团队 | **当前版本**：V2.0 diff --git a/docs/blueprints/js-fullstack-architecture.md b/docs/blueprints/js-fullstack-architecture.md new file mode 100644 index 0000000..e31f537 --- /dev/null +++ b/docs/blueprints/js-fullstack-architecture.md @@ -0,0 +1,933 @@ +# JS+JS 全栈架构技术方案 (V2.0) + +> **版本**：V2.0 +> **更新日期**：2026-03-15 +> **状态**：优化版 + +## 1. 概述 + +本文档为 Crawlful Hub 项目提供完整的 JavaScript 全栈技术架构方案，涵盖前端框架选型、后端技术栈、数据库设计、API 规范、开发流程及部署策略。本方案基于项目现有技术基底（UmiJS + Node.js + MySQL + TypeScript），进行系统性技术升级与规范化。 + +### 1.1 架构目标 + +- **技术统一**：前后端均采用 JavaScript/TypeScript，实现代码复用与团队技能统一 +- **开发效率**：提升前后端协作效率，减少技术栈切换成本 +- **可维护性**：建立清晰的代码分层与模块化架构 +- **性能优化**：构建高性能、高可用的企业级应用 +- **务实可靠**：去除 AI 概念，采用成熟稳定的规则引擎方案 + +### 1.2 方案边界 + +本方案适用于以下业务场景： + +- 电商中台前端控制台（Console）开发 +- 后端 RESTful API 服务 +- 实时数据交互与状态管理 +- 多租户 SaaS 平台架构 + +--- + +## 2. 可行性分析 + +### 2.1 技术可行性评估 + +#### 2.1.1 运行时环境 + +| 技术组件 | 版本要求 | 状态 | +|---------|---------|------| +| Node.js | >= 20.x LTS | 现有技术栈 | +| npm / yarn | >= 9.x | 现有技术栈 | +| TypeScript | >= 5.x | 现有技术栈 | +| MySQL | 8.0+ | 现有技术栈 | +| Redis | 6.0+ | 现有技术栈 | + +**结论**：项目基础设施已具备 JS+JS 全栈开发条件，无需额外环境搭建。 + +#### 2.1.2 团队能力矩阵 + +| 角色 | 当前技能 | 全栈扩展成本 | +|-----|---------|-------------| +| 前端开发 | React/Vue/UmiJS | 低（框架同源） | +| 后端开发 | Node.js/Express/Koa | 低（语言统一） | +| 全栈工程师 | 兼前端+后端 | 极低（技术同源） | + +**结论**：TypeScript 作为粘合语言，可实现前后端代码无缝衔接，团队学习成本可控。 + +### 2.2 业务可行性评估 + +#### 2.2.1 业务复杂度适配 + +| 业务模块 | 复杂度 | 技术方案 | +|---------|-------|---------| +| 订单管理 | 高 | Node.js + MySQL 事务 | +| 实时爬虫 | 中高 | Node.js 异步流处理 | +| 数据分析 | 中 | Node.js + Redis 缓存 | +| 规则引擎 | 高 | Node.js + 业务规则库 | + +**结论**：Node.js 单线程模型适用于 IO 密集型业务，配合 Worker Threads 可处理 CPU 密集型任务。 + +### 2.3 风险预判 + +| 风险项 | 等级 | 缓解措施 | +|-------|-----|---------| +| 后端单线程性能瓶颈 | 中 | 集群模式 + 负载均衡 | +| 前后端代码耦合 | 低 | 明确分层架构 + Monorepo 管理 | +| TypeScript 类型扩散 | 中 | 统一 shared types 包 | + +--- + +## 3. 技术选型标准 + +### 3.1 选型原则 + +#### 3.1.1 核心选型标准 + +1. **成熟度优先**：选择社区活跃、文档完善的稳定版本 +2. **生态兼容**：优先选择与现有技术栈兼容的方案 +3. **性能优先**：针对关键路径进行性能基准测试 +4. **维护可持续**：评估维护周期与社区活跃度 +5. **务实可靠**：优先选择经过大规模验证的方案 + +#### 3.1.2 技术债务控制 + +- 禁止引入已停止维护超过 12 个月的开源库 +- 核心依赖需有企业级支持或活跃社区 +- 定期进行依赖安全审计 + +--- + +## 4. 前端框架选型 + +### 4.1 候选方案对比 + +| 维度 | React | Vue 3 | Angular | UmiJS（现有） | +|-----|-------|-------|---------|--------------| +| 社区活跃度 | 极高 | 高 | 中 | 中 | +| 学习曲线 | 中 | 低 | 高 | 中 | +| TypeScript 支持 | 原生 | 原生 | 原生 | 优秀 | +| 生态丰富度 | 丰富 | 较丰富 | 完整 | 依赖 Ant Design | +| 企业级组件 | Ant Design | Element Plus | Angular Material | Ant Design 5.x | +| 与现有项目兼容 | 需重构 | 需重构 | 需重构 | 现有方案 | + +### 4.2 推荐方案：保持 UmiJS 4.x + +#### 4.2.1 选型理由 + +1. **项目延续性**：UmiJS 4.x 已是项目现有技术栈，降低迁移风险 +2. **Ant Design 深度集成**：与现有 UI 组件库完美兼容 +3. **企业级特性**：内置权限、国际化、路由、状态管理 +4. **TypeScript 优先**：开箱即用的 TS 支持 + +#### 4.2.2 升级路径 + +``` +UmiJS 3.x -> UmiJS 4.x -> UmiJS 5.x (预览版) +``` + +### 4.3 前端技术栈清单 + +| 层级 | 技术方案 | 版本要求 | 说明 | +|-----|---------|---------|------| +| 框架 | UmiJS | 4.x | 现有方案 | +| UI 组件库 | Ant Design | 5.x | 企业级组件 | +| 状态管理 | **Zustand** | >= 4.x | 替代 Valtio，更主流 | +| 服务端状态 | **TanStack Query** | >= 5.x | 替代 Umi Model | +| HTTP 客户端 | Axios / Umirequest | >= 1.x | 现有方案 | +| 表单管理 | **React Hook Form + Zod** | 最新 | 替代 ProForm | +| 可视化 | AntV G2 / G6 | >= 5.x | 现有方案 | +| 构建工具 | Vite（UmiJS 内置） | 内置 | 现有方案 | +| 代码规范 | ESLint + Prettier | 团队统一 | 现有方案 | + +### 4.4 前端架构设计 + +#### 4.4.1 目录结构规范 + +``` +src/ +├── components/ # 公共组件 +│ ├── Business/ # 业务组件 +│ └── Basic/ # 基础组件 +├── pages/ # 页面组件 +├── stores/ # Zustand 状态管理 +├── services/ # API 服务层 (TanStack Query) +├── utils/ # 工具函数 +├── hooks/ # 自定义 Hooks +├── types/ # TypeScript 类型定义 +└── assets/ # 静态资源 +``` + +#### 4.4.2 状态管理策略 + +| 状态类型 | 管理方案 | 适用场景 | +|---------|---------|---------| +| 全局状态 | **Zustand** | 用户信息、租户配置 | +| 页面状态 | **React Hook Form** | 表单数据 | +| 服务端状态 | **TanStack Query** | API 数据缓存、同步 | +| 表单验证 | **Zod** | 复杂表单验证 | + +#### 4.4.3 Zustand 使用示例 + +```typescript +// stores/orderStore.ts +import { create } from 'zustand'; +import { Order, OrderQueryParams } from '@/types/order'; + +interface OrderState { + orders: Order[]; + selectedOrder: Order | null; + queryParams: OrderQueryParams; + setOrders: (orders: Order[]) => void; + setSelectedOrder: (order: Order | null) => void; + setQueryParams: (params: OrderQueryParams) => void; +} + +export const useOrderStore = create((set) => ({ + orders: [], + selectedOrder: null, + queryParams: {}, + setOrders: (orders) => set({ orders }), + setSelectedOrder: (order) => set({ selectedOrder: order }), + setQueryParams: (params) => set({ queryParams: params }), +})); +``` + +#### 4.4.4 TanStack Query 使用示例 + +```typescript +// services/orderService.ts +import { request } from 'umi'; +import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'; +import { Order, CreateOrderDTO } from '@/types/order'; + +export const useOrders = (params: OrderQueryParams) => { + return useQuery({ + queryKey: ['orders', params], + queryFn: () => request('/api/v1/orders', { params }), + }); +}; + +export const useCreateOrder = () => { + const queryClient = useQueryClient(); + return useMutation({ + mutationFn: (data: CreateOrderDTO) => + request('/api/v1/orders', { method: 'POST', data }), + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ['orders'] }); + }, + }); +}; +``` + +--- + +## 5. 后端技术栈 + +### 5.1 框架选型对比 + +| 框架 | Express | Koa2 | NestJS | Fastify | +|-----|---------|------|--------|---------| +| 架构风格 | 简约 | 中间件 | 模块化 | 极致性能 | +| TypeScript 支持 | 需配置 | 需配置 | 原生 | 优秀 | +| 装饰器支持 | 否 | 否 | 是 | 是 | +| 生态成熟度 | 极高 | 高 | 高 | 中高 | +| 学习成本 | 低 | 低 | 中 | 中 | +| 性能 | 中 | 中 | 中高 | 极高 | + +### 5.2 推荐方案：NestJS + +#### 5.2.1 选型理由 + +1. **企业级架构**：模块化、装饰器、依赖注入，与 Spring Boot 理念相似 +2. **TypeScript 优先**：原生支持 TypeScript，类型安全 +3. **生态系统丰富**：微服务、GraphQL、WebSocket、任务队列 +4. **可测试性**：内置单元测试、E2E 测试框架 + +#### 5.2.2 架构对齐 + +项目现有后端采用 `core/domains/workers/api/shared` 分层结构，NestJS 模块系统可完美映射： + +``` +src/ +├── core/ # NestJS Core (Guard, Interceptor, Pipe) +├── modules/ # 业务模块 (对应 domains) +│ ├── order/ +│ ├── product/ +│ ├── finance/ +│ └── trade/ +├── api/ # Controller 层 +├── workers/ # Background Jobs +└── shared/ # Shared 模块 (DTO, Entities, Utils) +``` + +### 5.3 后端技术栈清单 + +| 层级 | 技术方案 | 版本要求 | 说明 | +|-----|---------|---------|------| +| 运行时 | Node.js | 20.x LTS | 现有 | +| 框架 | NestJS | 10.x | 企业级框架 | +| 语言 | TypeScript | 5.x (strict) | 严格模式 | +| ORM | **Prisma** | >= 5.x | 替代 Knex/TypeORM | +| 数据库 | MySQL | 8.0 | 现有 | +| 缓存 | Redis | 6.0+ | 现有 | +| 消息队列 | BullMQ | 最新 | 现有 | +| 验证 | class-validator + Zod | 最新 | 增强验证 | +| 文档 | Swagger / OpenAPI | @nestjs/swagger | 现有 | + +### 5.4 ORM 选型：Prisma + +#### 5.4.1 为什么选择 Prisma + +| 特性 | Prisma | TypeORM | Knex.js | +|-----|--------|---------|---------| +| TypeScript 支持 | 原生 | 好 | 需类型定义 | +| 迁移体验 | 优秀 | 一般 | 一般 | +| 查询构建 | Prisma Client | Entity | Query Builder | +| 性能 | 高 | 中 | 高 | +| 学习曲线 | 低 | 中 | 中高 | +| 开发者体验 | 优秀 | 一般 | 一般 | + +#### 5.4.2 Prisma Schema 示例 + +```prisma +// schema.prisma +generator client { + provider = "prisma-client-js" +} + +datasource db { + provider = "mysql" + url = env("DATABASE_URL") +} + +model Order { + id String @id @default(uuid()) + orderNo String @unique + status OrderStatus @default(PENDING) + totalAmount Decimal @db.Decimal(10, 2) + tenantId String + shopId String + items OrderItem[] + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@index([tenantId, shopId]) + @@index([status]) +} + +model OrderItem { + id String @id @default(uuid()) + orderId String + order Order @relation(fields: [orderId], references: [id]) + productId String + quantity Int + price Decimal @db.Decimal(10, 2) +} +``` + +### 5.5 数据库设计 + +#### 5.5.1 关系型数据库：MySQL 8.0 + +| 表分类 | 命名规范 | 示例 | +|-------|---------|-----| +| 核心业务表 | cf_前缀 | cf_order, cf_product | +| 租户隔离表 | cf_tenant_ | cf_tenant_config | +| 日志审计表 | cf_log_ | cf_log_operation | + +#### 5.5.2 数据库设计原则 + +1. **命名规范**：小写字母 + 下划线 +2. **主键策略**：使用 UUID 或雪花 ID +3. **时间戳**：created_at, updated_at 字段必填 +4. **软删除**：使用 is_deleted 字段标记 +5. **索引优化**：高频查询字段添加索引 + +#### 5.5.3 非必要场景 + +| 场景 | 推荐方案 | +|-----|---------| +| 简单配置存储 | MySQL JSON 字段 | +| 会话缓存 | Redis | +| 实时计数器 | Redis INCR | +| 大文件存储 | 对象存储（OSS/MinIO） | + +--- + +## 6. API 设计规范 + +### 6.1 RESTful API 标准 + +#### 6.1.1 路由设计 + +| 方法 | 用途 | 示例 | +|-----|-----|-----| +| GET | 查询 | GET /api/v1/orders | +| POST | 创建 | POST /api/v1/orders | +| PUT | 完整更新 | PUT /api/v1/orders/:id | +| PATCH | 部分更新 | PATCH /api/v1/orders/:id | +| DELETE | 删除 | DELETE /api/v1/orders/:id | + +#### 6.1.2 响应结构 + +```typescript +// 成功响应 +{ + "success": true, + "data": { + "id": "uuid", + "status": "PENDING" + }, + "pagination": { + "page": 1, + "pageSize": 20, + "total": 100 + } +} + +// 错误响应 +{ + "success": false, + "error": { + "code": "ORDER_NOT_FOUND", + "message": "订单不存在", + "details": {} + } +} +``` + +### 6.2 错误码规范 + +| 错误类别 | 错误码前缀 | 说明 | +|---------|-----------|-----| +| 4xx | CLIENT_ERROR_ | 客户端错误（参数、权限） | +| 5xx | SERVER_ERROR_ | 服务端错误（数据库、外部服务） | +| 业务 | BIZ_ | 业务规则错误 | +| 认证 | AUTH_ | 认证授权错误 | + +### 6.3 版本控制 + +- URL 版本：`/api/v1/`, `/api/v2/` +- 兼容策略：旧版本至少维护 6 个月 +- 废弃通知：提前 3 个月公告 + +--- + +## 7. 前后端数据交互 + +### 7.1 通信协议 + +| 交互方式 | 协议 | 适用场景 | +|---------|-----|---------| +| REST API | HTTP/1.1 | 常规 CRUD 操作 | +| WebSocket | WS/WSS | 实时状态推送 | +| Server-Sent Events | HTTP | 单向实时推送 | +| GraphQL | HTTP | 复杂查询场景 | + +### 7.2 数据类型共享 + +#### 7.2.1 Shared Types 包 + +``` +packages/ +└── shared-types/ + ├── index.ts + ├── order.types.ts + ├── product.types.ts + └── api.types.ts +``` + +#### 7.2.2 类型同步机制 + +1. **Monorepo 架构**：使用 Nx 或 Turborepo 管理 +2. **npm 私有包**：发布 shared-types 到私有仓库 +3. **构建时同步**：CI/CD 自动同步类型定义 + +### 7.3 请求封装 + +#### 7.3.1 前端请求层 + +```typescript +// services/api.ts +import { request } from 'umi'; +import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'; + +export const orderService = { + list: (params: OrderQueryParams) => + request('/api/v1/orders', { params }), + + create: (data: CreateOrderDTO) => + request('/api/v1/orders', { method: 'POST', data }), + + update: (id: string, data: UpdateOrderDTO) => + request(`/api/v1/orders/${id}`, { method: 'PATCH', data }), +}; + +// TanStack Query Hook 封装 +export const useOrders = (params: OrderQueryParams) => { + return useQuery({ + queryKey: ['orders', params], + queryFn: () => orderService.list(params), + }); +}; +``` + +#### 7.3.2 统一错误处理 + +- 401 Unauthorized：跳转登录页 +- 403 Forbidden：显示权限不足 +- 429 Too Many Requests：显示限流提示 +- 5xx Server Error：显示服务异常 + +--- + +## 8. 开发环境配置 + +### 8.1 环境要求 + +| 环境 | 配置要求 | +|-----|---------| +| 开发环境 | Node.js 20.x, MySQL 8.0, Redis 6.0 | +| 测试环境 | Docker 容器化部署 | +| 生产环境 | 阿里云 ECS + RDS + Redis | + +### 8.2 开发工具链 + +| 工具 | 用途 | 配置 | +|-----|-----|-----| +| VS Code | IDE | 推荐配置 | +| ESLint | 代码检查 | .eslintrc.js | +| Prettier | 代码格式化 | .prettierrc | +| TypeScript | 类型检查 | tsconfig.json | +| Husky | Git Hooks | .husky/ | +| lint-staged | 增量检查 | package.json | + +### 8.3 环境变量管理 + +``` +.env # 本地开发 +.env.development # 开发环境 +.env.staging # 预发布环境 +.env.production # 生产环境 +``` + +| 变量分类 | 示例变量 | +|---------|---------| +| 数据库 | DB_HOST, DB_PORT, DB_USER | +| Redis | REDIS_HOST, REDIS_PORT | +| 认证 | JWT_SECRET, JWT_EXPIRES | +| 第三方 | PLATFORM_APP_ID, PLATFORM_SECRET | + +--- + +## 9. 测试策略 + +### 9.1 测试分层 + +| 测试类型 | 覆盖目标 | 工具 | +|---------|---------|-----| +| 单元测试 | 业务逻辑、工具函数 | Jest / Vitest | +| 集成测试 | API 接口、数据库操作 | Jest + Supertest | +| E2E 测试 | 关键用户路径 | Playwright / Cypress | +| 性能测试 | API 响应时间、并发 | k6 / Artillery | + +### 9.2 测试覆盖率要求 + +| 模块 | 最低覆盖率 | +|-----|-----------| +| 核心业务 Service | 80% | +| 工具函数 | 90% | +| Controller | 70% | +| 整体项目 | 75% | + +### 9.3 测试数据管理 + +- 使用 Fixtures 管理测试数据 +- 避免依赖外部真实数据 +- 测试用例需有清理机制 + +--- + +## 10. 部署方案 + +### 10.1 部署架构 + +``` + [CDN] + | + [Nginx] + | + [负载均衡器] + | + +---------+---------+ + | | + [Node Cluster] [Node Cluster] + | | + [MySQL RDS] [Redis Cache] +``` + +### 10.2 容器化部署 + +#### 10.2.1 Docker 配置 + +```dockerfile +# 后端 Dockerfile +FROM node:20-alpine +WORKDIR /app +COPY package*.json ./ +RUN npm ci --only=production +COPY dist/ ./dist/ +EXPOSE 3000 +CMD ["node", "dist/main.js"] +``` + +#### 10.2.2 Docker Compose 开发环境 + +```yaml +version: '3.8' +services: + app: + build: . + ports: + - "3000:3000" + environment: + - NODE_ENV=development + depends_on: + - mysql + - redis + + mysql: + image: mysql:8.0 + environment: + MYSQL_ROOT_PASSWORD: root + MYSQL_DATABASE: crawlfuhl_hub + + redis: + image: redis:6-alpine +``` + +### 10.3 CI/CD 流程 + +| 阶段 | 工具 | 执行内容 | +|-----|-----|---------| +| 代码检查 | ESLint, TypeScript | 语法检查、类型校验 | +| 单元测试 | Jest | 覆盖率检查 | +| 构建 | npm | 产物打包 | +| 镜像构建 | Docker | 容器镜像 | +| 部署 | GitLab CI / GitHub Actions | 灰度发布 | + +--- + +## 11. 性能优化策略 + +### 11.1 前端性能优化 + +| 优化点 | 方案 | 预期收益 | +|-------|-----|---------| +| 首屏加载 | Code Splitting, Lazy Loading | 减少 30% 首屏时间 | +| 请求优化 | TanStack Query 缓存 | 减少 50% 请求数 | +| 图片优化 | WebP, 懒加载 | 减少 40% 带宽 | +| 渲染优化 | React.memo, useMemo | 减少重渲染开销 | +| 构建优化 | Turborepo + esbuild | 提升 10x 构建速度 | + +### 11.2 后端性能优化 + +| 优化点 | 方案 | 预期收益 | +|-------|-----|---------| +| 数据库 | Prisma 连接池 + 索引优化 | 提升 10x 查询速度 | +| 缓存 | Redis 多级缓存 | 减少 80% 数据库查询 | +| 并发 | PM2 集群模式 | 提升 5x 并发能力 | +| 异步 | BullMQ 消息队列 | 提升吞吐量 | +| 压缩 | Express 压缩中间件 | 减少 60% 带宽 | + +### 11.3 监控与告警 + +| 监控指标 | 工具 | 告警阈值 | +|---------|-----|---------| +| API 响应时间 | Prometheus + Grafana | > 500ms | +| 错误率 | Sentry | > 1% | +| CPU / 内存 | Node.js 内置 | > 80% | +| 数据库连接 | MySQL 慢查询 | > 1s | + +--- + +## 12. 可扩展性设计 + +### 12.1 模块化架构 + +#### 12.1.1 模块注册机制 + +```typescript +// 模块配置接口 +export interface ModuleConfig { + name: string; + version: string; + controllers: Type[]; + providers: Type[]; + entities: Type[]; + routes: RouteConfig[]; +} + +// 动态模块加载器 +export class ModuleLoader { + private modules: Map = new Map(); + + async registerModule(config: ModuleConfig): Promise { + this.modules.set(config.name, config); + } + + async loadModulesFromPath(path: string): Promise { + const files = await fs.readdir(path); + for (const file of files) { + if (file.endsWith('.module.ts')) { + const module = await import(join(path, file)); + await this.registerModule(module.default); + } + } + } +} +``` + +### 12.2 插件系统设计 + +#### 12.2.1 平台插件接口 + +```typescript +// 平台插件接口 +export interface IPlatformPlugin { + platform: string; + version: string; + + // 授权 + authorize(code: string): Promise; + refreshToken(token: AuthToken): Promise; + + // 商品 + fetchProducts(params: ProductQueryParams): Promise; + publishProduct(product: Product): Promise; + + // 订单 + fetchOrders(params: OrderQueryParams): Promise; + fulfillOrder(orderId: string, tracking: Tracking): Promise; +} + +// 插件注册 +@Injectable() +export class PluginRegistry { + private plugins: Map = new Map(); + + register(plugin: IPlatformPlugin): void { + this.plugins.set(plugin.platform, plugin); + } + + get(platform: string): IPlatformPlugin | undefined { + return this.plugins.get(platform); + } +} +``` + +#### 12.2.2 支持的插件类型 + +| 插件类型 | 功能 | 示例 | +|---------|-----|------| +| 平台插件 | 接入新电商平台 | Amazon, eBay, TikTok | +| 物流插件 | 接入新物流渠道 | 燕文, 4PX, 云途 | +| 支付插件 | 接入新支付方式 | PayPal, Stripe | +| 通知插件 | 接入新通知渠道 | 邮件, 短信, 钉钉 | + +### 12.3 微服务演进路径 + +| 阶段 | 架构 | 适用场景 | 拆分策略 | +|-----|-----|---------|---------| +| 第一阶段 | 单体应用 | 初创期 | - | +| 第二阶段 | 模块化单体 | 成长期 | 按业务域拆分 | +| 第三阶段 | 微服务 | 成熟期 | 按服务拆分 | + +**演进策略**： +1. 先实现清晰的模块边界（当前阶段） +2. 使用 NestJS 命名空间隔离 +3. 未来可通过 Kubernetes 拆分为独立服务 + +--- + +## 13. 安全性加固 + +### 13.1 认证授权 + +#### 13.1.1 JWT 双 Token 策略 + +| Token 类型 | 有效期 | 用途 | +|-----------|--------|------| +| Access Token | 15 分钟 | API 访问 | +| Refresh Token | 7 天 | 刷新 Access Token | + +#### 13.1.2 权限控制 + +```typescript +// RBAC 权限装饰器 +export const Permissions = (...permissions: string[]) => + SetMetadata('permissions', permissions); + +// 权限守卫 +@Injectable() +export class PermissionsGuard implements CanActivate { + canActivate(context: ExecutionContext): boolean { + const permissions = Reflect.getMetadata('permissions', context.getHandler()); + const user = context.switchToHttp().getRequest().user; + + return permissions.every(p => user.permissions.includes(p)); + } +} + +// 使用示例 +@UseGuards(JwtAuthGuard, PermissionsGuard) +@Get('orders') +@Permissions('order:read') +async getOrders() {} +``` + +### 13.2 数据安全 + +| 安全措施 | 实现方案 | +|---------|---------| +| SQL 注入 | Prisma 参数化查询 | +| XSS 攻击 | Helmet + Content-Security-Policy | +| CSRF | SameSite Cookie | +| 敏感数据 | AES-256 加密存储 | +| 传输加密 | TLS 1.3 | + +### 13.3 审计日志 + +```typescript +// 审计日志装饰器 +export const AuditLog = (action: string) => + SetMetadata('auditAction', action); + +// 审计拦截器 +@Injectable() +export class AuditInterceptor implements NestInterceptor { + intercept(context: ExecutionContext, next: CallHandler): Observable { + const request = context.switchToHttp().getRequest(); + const user = request.user; + const action = Reflect.getMetadata('auditAction', context.getHandler()); + + this.auditService.log({ + userId: user?.id, + tenantId: user?.tenantId, + action, + resource: request.url, + method: request.method, + ip: request.ip, + userAgent: request.headers['user-agent'], + timestamp: new Date(), + }); + + return next.handle(); + } +} +``` + +### 13.4 API 安全 + +| 防护措施 | 实现 | +|---------|------| +| 请求限流 | Redis 计数器 + 滑动窗口 | +| IP 黑名单 | Nginx / 应用层 | +| 请求验签 | HMAC-SHA256 | +| CORS | 白名单配置 | + +--- + +## 14. 风险评估与缓解措施 + +### 14.1 技术风险 + +| 风险项 | 等级 | 缓解措施 | +|-------|-----|---------| +| 单线程性能瓶颈 | 中 | PM2 集群 + 负载均衡 | +| 内存泄漏 | 中 | 定期内存分析 + 监控 | +| 依赖安全漏洞 | 高 | 自动化安全审计 + Snyk | +| TypeScript 类型膨胀 | 低 | 统一 shared-types 包 | + +### 14.2 业务风险 + +| 风险项 | 等级 | 缓解措施 | +|-------|-----|---------| +| 数据一致性 | 高 | 事务 + 补偿机制 | +| 第三方 API 依赖 | 中 | 熔断器模式 + 降级策略 | +| 租户数据隔离 | 高 | 强制 tenant_id 过滤 | + +### 14.3 运维风险 + +| 风险项 | 等级 | 缓解措施 | +|-------|-----|---------| +| 服务不可用 | 高 | 多活架构 + 自动故障转移 | +| 数据丢失 | 极高 | 定期备份 + 异地容灾 | +| 性能退化 | 中 | 性能监控 + 容量规划 | + +--- + +## 15. 实施路线图 + +### 15.1 阶段规划 + +| 阶段 | 时间 | 里程碑 | 优先级 | +|-----|-----|-------|-------| +| Phase 1 | 1 周 | NestJS + Prisma 框架搭建 | P0 | +| Phase 2 | 2 周 | 状态管理迁移 (Zustand + TanStack Query) | P1 | +| Phase 3 | 2 周 | 核心业务模块迁移 | P1 | +| Phase 4 | 2 周 | API 规范化 + 测试补全 | P1 | +| Phase 5 | 2 周 | 安全加固 + 审计日志 | P1 | +| Phase 6 | 1 周 | 性能优化 + 监控部署 | P2 | +| Phase 7 | 1 周 | 容器化 + CI/CD 完善 | P2 | +| Phase 8 | 2 周 | 插件系统设计 | P2 | + +### 15.2 验收标准 + +- 所有核心 API 具备单元测试 +- API 响应时间 P99 < 500ms +- 前后端类型完全同步 +- 部署流程自动化 +- 安全审计通过 + +--- + +## 16. 附录 + +### 16.1 技术栈总览 + +| 层级 | 技术方案 | 版本 | +|-----|---------|-----| +| 前端框架 | UmiJS | 4.x | +| UI 组件 | Ant Design | 5.x | +| 状态管理 | Zustand | 4.x | +| 服务端状态 | TanStack Query | 5.x | +| 表单验证 | React Hook Form + Zod | 最新 | +| 后端框架 | NestJS | 10.x | +| ORM | Prisma | 5.x | +| 数据库 | MySQL | 8.0 | +| 缓存 | Redis | 6.0+ | +| 消息队列 | BullMQ | 最新 | +| 构建工具 | Vite | 内置 | +| 语言 | TypeScript | 5.x (strict) | + +### 16.2 参考资源 + +- [NestJS 官方文档](https://docs.nestjs.com) +- [Prisma 官方文档](https://www.prisma.io/docs) +- [Zustand 官方文档](https://zustand-demo.pmnd.rs) +- [TanStack Query 官方文档](https://tanstack.com/query) +- [UmiJS 官方文档](https://umijs.org) +- [Ant Design Pro 组件](https://procomponents.ant.design) + +### 16.3 版本历史 + +| 版本 | 日期 | 变更内容 | +|-----|-----|---------| +| V1.0 | 2024-01 | 初始版本 | +| V2.0 | 2026-03-15 | 优化版：去除AI、技术栈升级、安全加固 | + +--- + +**文档维护者**：Crawlful Hub 架构团队 +**版本**：V2.0 +**状态**：已优化 diff --git a/docs/business梳理.md b/docs/business梳理.md new file mode 100644 index 0000000..f6764f8 --- /dev/null +++ b/docs/business梳理.md @@ -0,0 +1,1307 @@ +# 🏢 务实业务功能梳理 (V8.0) + +> 基于前端功能推导 + Java ERP标准功能 + 行业标杆拆解 + 技术实现方案 + 麦腾后台完整菜单爬取 +> **更新日期**: 2026-03-15 +> **核心优化**: 补充商品管理12个子功能、素材管理3个AI生成功能、数据报表12个新报表、系统工具/管理/监控完整功能 + +--- + +## 一、核心业务模块 + +### 1. 商品管理 (PIM) ⭐⭐⭐ + +#### 1.1 商品档案 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| SPU管理 | 标准产品单位管理（款） | P0 | 【场景】运营管理商品款式 【输入】商品标题、描述、图片 【输出】SPU记录 【字段】spuCode,title,description,images[] 【关联】→SKU管理 | +| SKU管理 | 库存量单位管理（色/尺码） | P0 | 【场景】管理具体销售单元 【输入】SPU+规格属性 【输出】SKU记录 【字段】skuCode,spuId,attributes,costPrice 【关联】SPU→SKU | +| 商品分类 | 多级类目管理 | P0 | 【场景】商品归类便于管理 【输入】分类名称/父分类 【输出】分类树结构 【字段】categoryId,parentId,name 【关联】→商品关联 | +| 商品属性 | 属性模板（颜色/尺码/规格） | P1 | 【场景】定义商品可选规格 【输入】属性名称/属性值 【输出】属性模板 【字段】attrName,attrValues[] 【关联】→SKU规格 | +| 商品图片 | 图片管理、主图/详情图 | P1 | 【场景】商品主图/详情图管理 【输入】图片URL/上传 【输出】图片记录 【字段】url,isMain,sort 【关联】→SPU | +| 商品条码 | UPC/EAN/条码管理 | P1 | 【场景】商品条码管理用于扫货 【输入】条码号码 【输出】条码记录 【字段】barcode,barcodeType 【关联】→SKU | +| 商品编码 | 内部SKU编码 | P1 | 【场景】内部商品编号管理 【输入】编码规则 【输出】自动编码 【字段】innerCode,skuId 【关联】→SKU | +| **快速创建商品** | 快速创建商品草稿 | P0 | 【场景】快速创建商品草稿 【输入】商品标题+主图+价格 【输出】商品草稿 【字段】productId,title,mainImage,price 【关联】←用户输入 →商品编辑 | +| **镜像商品** | 复制/镜像现有商品 | P0 | 【场景】基于现有商品快速创建相似商品 【输入】源商品ID 【输出】新商品草稿 【字段】sourceProductId,newProductId,copyOptions 【关联】←源商品 →商品编辑 | + +#### 1.2 商品刊登 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 多平台刊登 | 一键发布到Amazon/eBay/Temu/Shopee等 | P0 | 【场景】将商品发布到多个销售平台 【输入】SPU/SKU+目标平台 【输出】平台商品ID 【字段】platform,productId,listingStatus 【关联】商品档案→平台店铺 | +| 批量刊登 | Excel/CSV/Google Sheets 批量导入（拖拽上传+实时预览） | P1 | 【场景】批量导入商品进行发布 【输入】Excel/CSV/Google Sheets（拖拽上传）【输出】实时预览+批量任务结果 【字段】taskId,total,success,failed,errorDetails 【关联】→多平台刊登 | +| **产品裂变批量刊登** | 基于爆款商品快速裂变多个变体/相似商品 | P0 | 【场景】基于爆款快速生成多变体/多平台商品 【输入】源商品ID+裂变规则（价格/图片/标题变体）【输出】裂变商品列表+批量刊登 【字段】sourceProductId,variantRules,fissionProducts[],taskId 【关联】←爆款商品 →多平台刊登 | +| 属性映射 | 平台间属性自动转换 | P1 | 【场景】不同平台属性格式转换 【输入】源属性+映射规则 【输出】目标属性 【字段】sourceAttr,mappingRules,targetAttr 【关联】→多平台刊登 | +| 商品模板 | 描述模板、图片模板 | P1 | 【场景】批量生成商品描述 【输入】模板+变量 【输出】渲染后描述 【字段】templateId,content,variables[] 【关联】→多平台刊登 | +| 定时刊登 | 定时发布、自动上下架 | P2 | 【场景】定时自动发布商品 【输入】发布时间 【输出】定时任务 【字段】scheduleTime,platform,productId 【关联】→多平台刊登 | +| 刊登状态 | 刊登成功/失败/待审核 | P1 | 【场景】追踪商品发布状态 【输入】平台返回状态 【输出】状态记录 【字段】status,errorMsg,platformProductId 【关联】←多平台刊登 | +| **刊登记录** | 全平台刊登历史记录（成功/失败/原因） | P0 | 【场景】查看商品所有平台的刊登历史 【输入】商品ID/时间范围 【输出】刊登记录列表 【字段】recordId,productId,platform,status,errorMsg,operator,operateTime 【关联】←多平台刊登 →操作审计 | + +#### 1.3 商品采集 ⭐重点 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 1688采集 | 一键采集1688商品 | P1 | 【场景】从1688选品采集 【输入】1688商品URL 【输出】内部SPU/SKU草稿 【字段】sourceUrl,title,images[],skus[].costPrice 【关联】←用户输入 →商品编辑 | +| 速卖通采集 | 采集速卖通商品 | P2 | 【场景】从速卖通选品参考 【输入】速卖通商品URL 【输出】商品信息 【字段】同1688 【关联】←用户输入 →竞品分析 | +| 竞品采集 | 采集竞品信息 | P2 | 【场景】采集竞争对手商品 【输入】竞品URL 【输出】竞品数据 【字段】sourceUrl,price,销量 【关联】←用户输入 →价格分析 | +| 批量采集 | 批量URL采集 | P2 | 【场景】批量采集多个商品 【输入】URL列表 【输出】批量任务结果 【字段】taskId,results[] 【关联】→单商品采集 | + +**技术实现方案 - 商品采集**： + +``` +采集层架构 +├── 有API平台（官方接口） +│ ├── 1688开放平台 → 代购/铺货 +│ ├── 速卖通API → 选品参考 +│ ├── Amazon SP-API → 竞品分析 +│ └── Shopee API → 同平台采集 +│ +├── 无API平台（爬虫+解析） +│ ├── 视觉识别层（Puppeteer/Playwright） +│ ├── DOM语义解析层 +│ └── 数据清洗层 +│ +└── 混合策略引擎 + ├── 来源优先级排序 + ├── 数据融合逻辑 + └── 去重与归一化 +``` + +**有API平台对接**： +| 平台 | API类型 | 对接方式 | 数据范围 | +| :--- | :--- | :--- | :--- | +| **1688** | 开放平台 | AppKey/Secret授权 | 商品详情、价格、SKU | +| **速卖通** | Open Platform | OAuth2.0授权 | 商品信息、销量 | +| **Amazon** | SP-API | AWS IAM授权 | 商品、库存、评价 | +| **Shopee** | Open API | Shopee ID授权 | 商品、订单 | + +**无API平台方案**（Temu、Taobao）： +| 层级 | 技术栈 | 功能 | +| :--- | :--- | :--- | +| 浏览器控制 | Puppeteer/Playwright | 模拟真实用户访问 | +| 反检测 | 代理IP池、UA轮换、指纹隔离 | 避免封禁 | +| DOM解析 | Cheerio/页面分析 | 提取商品信息 | +| 视觉识别 | OpenCV/Sharp | 图片水印去除 | +| 容错机制 | 重试队列、降级策略 | 改版自愈 | + +**数据归一化模型**： +```typescript +interface NormalizedProduct { + spuId: string; + source: '1688' | 'taobao' | 'amazon' | 'manual'; + sourceUrl: string; + sourceProductId: string; + title: string; + description: string; + images: { url: string; isMain: boolean }[]; + skus: { skuCode: string; attributes: Record; costPrice: number; }[]; + category: CategoryNode; +} +``` + +| **商品采集记录** | 全渠道采集历史记录（来源/时间/结果） | P0 | 【场景】查看商品的采集来源和历史 【输入】商品ID/时间范围/来源 【输出】采集记录列表 【字段】recordId,productId,source,sourceUrl,status,operator,collectTime 【关联】←商品采集 →操作审计 | + +**采集与刊登记录数据模型**： +```typescript +interface ProductCollectRecord { + recordId: string; + productId: string; + source: '1688' | 'taobao' | 'amazon' | 'aliexpress' | 'manual'; + sourceUrl: string; + sourceProductId: string; + collectStatus: 'SUCCESS' | 'FAILED' | 'PARTIAL'; + failReason?: string; + collectedData: { + title: string; + images: string[]; + skus: any[]; + costPrice?: number; + }; + operatorId: string; + operatorName: string; + collectTime: Date; +} + +interface ProductListingRecord { + recordId: string; + productId: string; + skuId?: string; + platform: string; + shopId: string; + listingType: 'CREATE' | 'UPDATE' | 'ON_SHELF' | 'OFF_SHELF'; + listingStatus: 'SUCCESS' | 'FAILED' | 'PENDING' | 'REJECTED'; + platformProductId?: string; + failReason?: string; + rejectReason?: string; + operatorId: string; + operatorName: string; + operateTime: Date; +} +``` + +#### 1.5 商品状态与同步管理 ⭐核心 +**商品状态体系**：总计/可用/卖家已停用/待定/草稿/平台已停用/冻结/失败/删除 + +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| **商品状态标签** | 多状态商品筛选标签页 | P0 | 【场景】按状态快速筛选商品 【输入】状态标签 【输出】对应状态商品列表 【字段】statusTab,count 【关联】←商品列表 →筛选结果 | +| **商品状态变更** | 商品状态手动/自动变更 | P0 | 【场景】变更商品状态 【输入】商品ID+新状态 【输出】状态变更记录 【字段】productId,oldStatus,newStatus,reason 【关联】←商品管理 →状态变更日志 | +| **同步商品** | 从TikTok同步商品到ERP | P0 | 【场景】从平台同步商品信息 【输入】店铺+商品范围 【输出】同步结果 【字段】shopId,syncType,successCount,failedCount 【关联】←TikTok →商品档案 | +| **批量操作** | 商品批量状态/上下架/删除 | P0 | 【场景】批量操作商品 【输入】商品ID列表+操作类型 【输出】批量操作结果 【字段】taskId,operation,success[],failed[] 【关联】←商品列表 →操作审计 | +| **商品高级筛选** | 多维度商品筛选（店铺/类目/SKU/日期/标题/ID） | P0 | 【场景】多条件筛选商品 【输入】筛选条件组合 【输出】筛选结果列表 【字段】filters,results,count 【关联】←商品列表 →筛选结果 | +| **列配置** | 自定义商品列表显示列 | P1 | 【场景】自定义列表显示字段 【输入】列配置 【输出】列配置保存 【字段】userId,columns[],sort 【关联】←用户设置 →列表展示 | + +#### 1.6 价格管理 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 成本价格 | 采购成本录入 | P0 | 【场景】录入商品采购成本 【输入】SKU+成本金额 【输出】成本记录 【字段】skuId,costPrice,supplierId 【关联】←采购订单 →利润计算 | +| 售价管理 | 各平台售价管理 | P0 | 【场景】管理各平台销售价格 【输入】SKU+平台+售价 【输出】售价记录 【字段】skuId,platform,sellingPrice 【关联】←出价建议 →刊登 | +| 价格公式 | 成本+利润=售价公式 | P0 | 【场景】自动计算销售价格 【输入】成本+目标利润率 【输出】计算后售价 【字段】formula,targetProfitRate 【关联】成本→售价 | +| 调价记录 | 价格变更历史 | P1 | 【场景】追踪价格变更 【输入】变更前后价格 【输出】价格流水 【字段】skuId,oldPrice,newPrice,changedBy,changedAt 【关联】←售价管理 | + +#### 1.7 产品裂变 ⭐核心 +**产品裂变场景**：基于一个爆款商品，快速生成多个变体/相似商品，用于A/B测试、多平台铺货、价格测试等。 + +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| **标题裂变** | 自动生成多个标题变体 | P0 | 【场景】生成多个标题测试点击率 【输入】源标题+关键词库+模板 【输出】标题变体列表 【字段】sourceTitle,keywords,templates,variants[] 【关联】←源商品 →裂变商品 | +| **图片裂变** | 图片排列/滤镜/水印变体 | P0 | 【场景】生成多个主图测试转化率 【输入】源图片+排列规则+滤镜 【输出】图片变体列表 【字段】sourceImages,arrangement,filters,variants[] 【关联】←源商品 →裂变商品 | +| **价格裂变** | 按比例/固定金额生成价格梯度 | P0 | 【场景】测试不同价格点的销量 【输入】源价格+价格梯度规则 【输出】价格变体列表 【字段】sourcePrice,priceRules,variants[] 【关联】←源商品 →裂变商品 | +| **SKU裂变** | 基于现有SKU生成新SKU组合 | P0 | 【场景】生成更多SKU变体 【输入】源SKU+属性组合规则 【输出】SKU变体列表 【字段】sourceSkus,attributeCombinations,variants[] 【关联】←源商品 →裂变商品 | +| **描述裂变** | 描述模板+变量生成变体 | P1 | 【场景】生成不同描述测试转化 【输入】源描述+模板+变量 【输出】描述变体列表 【字段】sourceDescription,template,variables,variants[] 【关联】←源商品 →裂变商品 | +| **多平台裂变** | 一键裂变到多个平台 | P0 | 【场景】将裂变商品发布到多平台 【输入】裂变商品列表+目标平台 【输出】多平台刊登任务 【字段】fissionProducts[],platforms[],taskId 【关联】←裂变商品 →多平台刊登 | +| **裂变效果追踪** | 追踪各裂变变体的表现 | P1 | 【场景】分析哪个变体效果最好 【输入】裂变商品+时间范围 【输出】效果对比报告 【字段】variantId,views,orders,gmv,conversion 【关联】←裂变商品 →数据报表 | + +**裂变规则配置**： +```typescript +interface FissionRule { + ruleId: string; + ruleName: string; + sourceProductId: string; + fissionType: 'TITLE' | 'IMAGE' | 'PRICE' | 'SKU' | 'DESCRIPTION' | 'ALL'; + titleConfig?: { + keywords: string[]; + templates: string[]; + maxVariants: number; + }; + imageConfig?: { + rearrange: boolean; + filters: string[]; + watermarks: string[]; + maxVariants: number; + }; + priceConfig?: { + variationType: 'PERCENTAGE' | 'FIXED'; + values: number[]; + maxVariants: number; + }; + skuConfig?: { + attributeCombinations: Record; + maxVariants: number; + }; + targetPlatforms: string[]; + autoPublish: boolean; +} +``` + +#### 1.8 商品批量操作 ⭐麦腾彩蛋 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| **修改价格** | 批量修改商品售价 | P0 | 【场景】批量调整商品售价 【输入】商品ID列表+新价格 【输出】价格变更记录 【字段】productIds[],newPrice,changeReason 【关联】←商品列表 →价格管理 | +| **修改库存** | 批量修改商品库存 | P0 | 【场景】批量调整商品库存 【输入】商品ID列表+新库存 【输出】库存变更记录 【字段】productIds[],newStock,changeReason 【关联】←商品列表 →库存管理 | +| **修改标题** | 批量修改商品标题 | P1 | 【场景】批量优化商品标题 【输入】商品ID列表+新标题 【输出】标题变更记录 【字段】productIds[],newTitle,changeReason 【关联】←商品列表 →商品档案 | +| **修改类目** | 批量修改商品类目 | P1 | 【场景】批量调整商品类目归属 【输入】商品ID列表+新类目 【输出】类目变更记录 【字段】productIds[],newCategoryId,changeReason 【关联】←商品列表 →商品分类 | +| **修改包装重量** | 批量修改包装重量 | P1 | 【场景】批量设置商品包装重量 【输入】商品ID列表+新重量 【输出】重量变更记录 【字段】productIds[],newWeight,changeReason 【关联】←商品列表 →物流计算 | +| **修改包装尺寸** | 批量修改包装尺寸 | P1 | 【场景】批量设置商品包装尺寸 【输入】商品ID列表+新尺寸 【输出】尺寸变更记录 【字段】productIds[],newSize,changeReason 【关联】←商品列表 →物流计算 | +| **修改是否到货付款** | 批量设置到货付款选项 | P2 | 【场景】批量设置是否支持到货付款 【输入】商品ID列表+是否支持 【输出】配置变更记录 【字段】productIds[],codEnabled,changeReason 【关联】←商品列表 →商品档案 | +| **修改Seller SKU** | 批量修改卖家SKU | P1 | 【场景】批量更新卖家自定义SKU 【输入】商品ID列表+新Seller SKU 【输出】SKU变更记录 【字段】productIds[],newSellerSku,changeReason 【关联】←商品列表 →SKU管理 | +| **批量上架** | 批量商品上架操作 | P0 | 【场景】批量将商品上架销售 【输入】商品ID列表 【输出】上架结果记录 【字段】productIds[],successCount,failedCount 【关联】←商品列表 →商品状态 | +| **批量下架** | 批量商品下架操作 | P0 | 【场景】批量将商品下架暂停销售 【输入】商品ID列表+下架原因 【输出】下架结果记录 【字段】productIds[],offShelfReason,successCount,failedCount 【关联】←商品列表 →商品状态 | +| **产品发布记录** | 商品发布历史记录查询 | P0 | 【场景】查看商品发布历史和状态 【输入】商品ID/时间范围 【输出】发布记录列表 【字段】recordId,productId,platform,status,publishTime 【关联】←商品刊登 →操作审计 | +| **管理商品** | 商品全生命周期管理入口 | P0 | 【场景】商品综合管理工作台 【输入】筛选条件 【输出】商品管理列表 【字段】filters,productList,actions[] 【关联】←商品档案 →各商品操作 | + +#### 1.9 库存管理 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 库存同步 | 各平台库存同步 | P0 | 【场景】同步各平台库存防超卖 【输入】SKU+仓库+库存量 【输出】同步结果 【字段】skuId,warehouseId,quantity 【关联】仓库→平台店铺 | +| 库存预警 | 安全库存提醒 | P0 | 【场景】库存低于安全线提醒 【输入】SKU+预警阈值 【输出】预警通知 【字段】skuId,threshold,currentStock 【关联】←库存同步 | +| 库存分配 | 指定仓库库存 | P1 | 【场景】分配商品到具体仓库 【输入】SKU+仓库+数量 【输出】分配记录 【字段】skuId,warehouseId,allocatedQty 【关联】→出库管理 | + +--- + +### 2. 订单管理 (OMS) ⭐⭐⭐ + +#### 2.1 订单处理 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 订单工作台 | 多平台订单归集、审核、发货 | P0 | 【场景】集中处理各平台订单 【输入】平台订单数据 【输出】待处理订单列表 【字段】orderId,platform,buyer,items[],status 【关联】←平台同步 →订单审核 | +| 订单利润分析 | 成本核算、利润计算 | P0 | 【场景】计算每笔订单利润 【输入】订单+成本数据 【输出】利润数据 【字段】orderId,revenue,cost,profit,profitRate 【关联】←订单工作台 →财务报表 | +| 订单审核 | 自动审核+人工审核 | P0 | 【场景】审核订单有效性 【输入】订单信息 【输出】审核结果 【字段】orderId,auditResult,auditType,auditor 【关联】←订单工作台 →发货 | +| 异常订单 | 地址异常、库存不足处理 | P1 | 【场景】处理问题订单 【输入】异常订单 【输出】处理方案 【字段】orderId,exceptionType,solution 【关联】←订单审核 | +| 批量发货 | 批量打单、批量发货 | P1 | 【场景】批量处理订单发货 【输入】订单列表 【输出】发货结果 【字段】taskId,orders[],shippingNo 【关联】←订单审核 | + +#### 2.2 智能辅助 ⭐轻量规则引擎 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 规则引擎 | 基于数据的自动判断 | P0 | 【场景】自动判断业务操作 【输入】业务数据 【输出】判断结果 【字段】ruleId,data,result 【关联】←业务数据 →操作执行 | +| 异常预警 | 异常数据自动标记 | P0 | 【场景】自动标记异常订单/库存 【输入】业务数据 【输出】预警列表 【字段】type,data,warningLevel 【关联】←业务数据 →通知 | +| 智能建议 | 基于历史数据的建议 | P1 | 【场景】根据历史数据给出建议 【输入】历史数据 【输出】建议内容 【字段】type,suggestion,confidence 【关联】←历史数据 →展示 | +| 辅助决策 | 多维度数据辅助决策 | P1 | 【场景】聚合多维度数据辅助判断 【输入】多源数据 【输出】决策参考 【字段】dataSources[],analysis,recommendation 【关联】←各业务 →展示 | + +**规则引擎逻辑**： +``` +输入数据 → 规则匹配 → 执行动作 + ↓ + 规则库（可配置） + - 利润率 < 15% → 标记预警 + - 库存 < 安全库存 → 触发补货建议 + - 订单金额 > 阈值 → 标记人工确认 +``` + +**比人工优势**： +- 看得到更多数据维度 +- 毫秒级响应 +- 7×24小时监控 +- 基于历史模式识别异常 + +--- + +### 3. 库存管理 (WMS) ⭐⭐ + +#### 3.1 库存作业 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 库存同步 | 多仓库库存统一管理 | P0 | 【场景】统一管理各仓库库存 【输入】仓库+商品+数量 【输出】库存台账 【字段】skuId,warehouseId,quantity 【关联】←入库 →出库 | +| 库存预警 | 安全库存提醒 | P0 | 【场景】库存低于阈值提醒 【输入】商品+预警值 【输出】预警消息 【字段】skuId,threshold,currentQty 【关联】←库存同步 | +| 库存流水 | 进出库全记录 | P1 | 【场景】记录每笔库存变动 【输入】变动单据 【输出】流水记录 【字段】流水号,skuId,type,qty,balance 【关联】←出入库作业 | +| 库存盘点 | 定期盘点、差异调整 | P1 | 【场景】定期核对库存差异 【输入】盘点单 【输出】差异报告 【字段】盘点单ID,skuId,bookQty,actualQty,diff 【关联】←库存流水 | + +#### 3.2 库存分析 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 库存老化分析 | 滞销品预警 | P0 | 【场景】识别长期滞销商品 【输入】SKU+库龄 【输出】滞销清单 【字段】skuId,stockDays,velocity 【关联】←库存流水 | +| 库存预测补货 | 安全库存建议 | P0 | 【场景】基于销量预测补货量 【输入】历史销量+采购周期 【输出】建议补货量 【字段】skuId,suggestedQty,reorderPoint 【关联】←销售数据 →采购 | +| 库存计划 | 备货计划 | P1 | 【场景】制定备货计划 【输入】计划周期+商品 【输出】计划单 【字段】planId,skuId,planQty,deliveryDate 【关联】←补货建议 →采购订单 | + +#### 3.3 物流管理 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 物流健康 | 物流状态监控 | P1 | 【场景】监控物流正常率 【输入】物流单号 【输出】状态数据 【字段】trackingNo,carrier,status,deliveredRate 【关联】←物流追踪 | +| 物流追踪 | 物流轨迹同步 | P1 | 【场景】同步物流轨迹信息 【输入】物流单号 【输出】轨迹列表 【字段】trackingNo,events[],location,time 【关联】←订单发货 | +| 物流比价 | 多渠道比价 | P2 | 【场景】选择最优物流渠道 【输入】商品+目的地 【输出】渠道报价 【字段】carrier,price,days 【关联】←订单发货 | + +--- + +### 4. 采购管理 (SCM) ⭐⭐ + +#### 4.1 采购作业 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 采购订单 | 采购下单 | P1 | 【场景】向供应商下单采购 【输入】商品+数量+供应商 【输出】采购单 【字段】poId,supplierId,items[],totalAmount 【关联】←补货建议 →入库 | +| 采购入库 | 入库管理 | P1 | 【场景】采购商品入库操作 【输入】采购单+入库数量 【输出】入库单 【字段】receiptId,poId,items[],warehouseId 【关联】←采购订单 →库存 | +| 采购退换 | 退货处理 | P2 | 【场景】处理采购退货 【输入】退货单 【输出】退款记录 【字段】returnId,poId,reason,amount 【关联】←入库 →供应商 | + +#### 4.2 供应商管理 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 供应商档案 | 供应商信息管理 | P1 | 【场景】管理供应商信息 【输入】供应商资料 【输出】供应商记录 【字段】supplierId,name,contact,address 【关联】→采购订单 | +| 供应商产能 | 供应商交付能力 | P1 | 【场景】评估供应商交付能力 【输入】供应商+历史交付数据 【输出】产能报告 【字段】supplierId,onTimeRate,qualityScore 【关联】←采购历史 | +| 1688采购 | 1688一键代采 | P1 | 【场景】通过1688代采商品 【输入】1688商品链接 【输出】采购单 【字段】productUrl,price,quantity 【关联】←商品采集 →采购订单 | +| 采购询价 | 多供应商比价 | P1 | 【场景】向多供应商询价 【输入】商品需求 【输出】报价对比 【字段】inquiryId,supplierId,quotePrice 【关联】→采购订单 | + +--- + +### 5. 套利与定价 ⭐⭐⭐ + +#### 5.1 套利计算 ⭐核心 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 多渠道套利计算 | A进货，多渠道出货，计算利润 | P0 | 【场景】计算商品各渠道利润 【输入】采购成本+各渠道售价+费用 【输出】利润报表 【字段】skuId,channel,revenue,cost,profit,margin 【关联】←成本/售价 →利润分析 | +| 采购成本归集 | 采购、物流、平台费用归集 | P0 | 【场景】汇总各项成本费用 【输入】采购价+物流+佣金 【输出】成本明细 【字段】skuId,costPrice,freight,commission,totalCost 【关联】←采购/物流 →套利 | +| 利润分析 | 毛利率、净利率计算 | P0 | 【场景】分析商品盈利情况 【输入】收入+成本 【输出】利润率 【字段】skuId,channel,grossProfit,netProfit,grossMargin 【关联】←套利计算 →预警 | + +**核心公式**： +``` +毛利润 = 售价 - 采购成本 - 头程运费 - 尾程运费 - 平台佣金 - 包装费 +毛利率 = (毛利润 / 售价) × 100% +净利率 = (净利润 / 售价) × 100% +``` + +#### 5.2 出价建议器 ⭐核心 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 出价建议 | 基于成本和利润率推导出价 | P0 | 【场景】计算商品建议售价 【输入】成本+目标利润率 【输出】建议售价 【字段】skuId,cost,targetMargin,suggestedPrice 【关联】←成本 →售价管理 | +| 最低价计算 | 成本+固定费用计算 | P0 | 【场景】计算保本售价 【输入】成本+固定费用 【输出】最低售价 【字段】skuId,fixedCost,minimumPrice 【关联】←成本 →出价建议 | +| 利润率预警 | 利润率低于阈值预警 | P0 | 【场景】利润率异常提醒 【输入】实际利润率+阈值 【输出】预警通知 【字段】skuId,actualMargin,threshold,level 【关联】←利润分析 →消息通知 | + +**核心公式**： +``` +建议售价 = 成本 / (1 - 目标利润率) +最低售价 = 成本 + 固定费用 +B2B红线：利润率 < 15% 禁止放行 +B2C红线：利润率 < 20% 触发预警 +``` + +--- + +### 6. 财务管理 (FIN) ⭐⭐ + +#### 6.1 财务核算 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 财务对账 | 订单与结算差异 | P0 | 【场景】核对订单与收款差异 【输入】订单+平台结算 【输出】差异报告 【字段】orderId,orderAmount,settledAmount,diff 【关联】←订单 →报表 | +| 多币种对账 | 多币种结算 | P1 | 【场景】处理多币种结算 【输入】外币金额+汇率 【输出】本币金额 【字段】currency,amount,rate,cnyAmount 【关联】←平台结算 | +| 平台费用监控 | 平台费用跟踪 | P1 | 【场景】监控平台扣费 【输入】平台费用明细 【输出】费用报表 【字段】platform,feeType,amount,period 【关联】←平台同步 | +| 回款管理 | 回款跟踪 | P1 | 【场景】跟踪订单回款状态 【输入】订单+回款状态 【输出】回款记录 【字段】orderId,paidAmount,paymentDate 【关联】←平台结算 | + +#### 6.2 报表统计 ⭐看板 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 销售报表 | 销售统计 | P1 | 【场景】统计销售数据 【输入】订单数据 【输出】销售报表 【字段】period,revenue,orders,avgOrderValue 【关联】←订单 | +| 利润报表 | 利润分析 | P1 | 【场景】统计分析利润 【输入】利润数据 【输出】利润报表 【字段】period,grossProfit,netProfit,margin 【关联】←套利计算 | +| 库存报表 | 库存统计 | P1 | 【场景】统计库存状况 【输入】库存数据 【输出】库存报表 【字段】warehouse,skuCount,totalValue 【关联】←库存 | +| 运营报表 | 运营分析 | P2 | 【场景】综合运营分析 【输入】多维度数据 【输出】运营报告 【字段】KPI指标,趋势分析 【关联】←各业务模块 | + +#### 6.3 财务对账报表 ⭐重点 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 平台对账单 | 各平台月度对账单 | P0 | 【场景】生成平台结算对账单 【输入】平台+周期 【输出】对账单 【字段】platform,period,orderAmount,commission,refund,settledAmount 【关联】←平台结算 | +| 差异分析报表 | 订单与回款差异 | P0 | 【场景】分析订单与回款差异 【输入】订单+回款数据 【输出】差异报表 【字段】orderId,expectedAmount,actualAmount,diff 【关联】←订单/回款 | +| 利润明细表 | 每单利润明细 | P0 | 【场景】查看每笔订单利润 【输入】订单ID 【输出】利润明细 【字段】orderId,revenue,cost,profit,margin 【关联】←套利计算 | +| 费用汇总表 | 各项费用汇总 | P1 | 【场景】汇总各项费用 【输入】费用类型+周期 【输出】费用报表 【字段】feeType,amount,占比 【关联】←平台费用 | +| 应收应付表 | 应收应付管理 | P1 | 【场景】管理应收应付 【输入】客户/供应商+金额 【输出】往来账 【字段】partyId,type,amount,dueDate 【关联】←采购/销售 | + +#### 6.4 数据大盘 ⭐驾驶舱 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 销售大盘 | 全平台销售数据汇总 | P0 | 【场景】查看整体销售概况 【输入】时间范围 【输出】销售数据 【字段】totalSales,totalOrders,avgOrderValue 【关联】←各平台订单 | +| 利润大盘 | 全平台利润汇总 | P0 | 【场景】查看整体利润概况 【输入】时间范围 【输出】利润数据 【字段】totalProfit,totalMargin 【关联】←套利计算 | +| 库存大盘 | 全仓库库存状况 | P0 | 【场景】查看整体库存概况 【输入】仓库范围 【输出】库存数据 【字段】totalStock,stockValue,stockDays 【关联】←库存 | +| 店铺大盘 | 各店铺销售排名 | P0 | 【场景】查看各店铺销售排名 【输入】时间范围 【输出】店铺排行 【字段】shopId,sales,orders,rank 【关联】←店铺订单 | +| 品类大盘 | 各品类销售占比 | P1 | 【场景】查看品类销售分布 【输入】时间范围 【输出】品类报表 【字段】categoryId,sales,占比 【关联】←商品分类 | +| 趋势分析 | 销售趋势图表 | P1 | 【场景】分析销售趋势 【输入】时间维度 【输出】趋势图 【字段】date,sales,orders 【关联】←销售数据 | +| 实时大屏 | 实时数据展示 | P2 | 【场景】大屏展示实时数据 【输入】数据源 【输出】实时看板 【字段】realtime sales 【关联】←各业务模块 | + +#### 6.5 数据报表细分 ⭐麦腾彩蛋 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| **广告主报表** | 广告投放效果数据报表 | P0 | 【场景】查看广告主广告投放效果 【输入】广告账户/时间范围 【输出】广告效果报表 【字段】advertiserId,impressions,clicks,spend,conversions 【关联】←广告投放 →广告分析 | +| **GMV Max报表** | GMVMAX活动数据报表 | P0 | 【场景】查看GMVMAX活动数据统计 【输入】活动/时间范围 【输出】GMVMAX报表 【字段】activityId,gmv,orders,adSpend,roas 【关联】←GMVMAX →活动分析 | +| **订单结算报表** | 订单结算明细报表 | P0 | 【场景】查看订单结算明细 【输入】店铺/时间范围 【输出】结算报表 【字段】orderId,settledAmount,commission,refund 【关联】←订单结算 →财务对账 | +| **恶意订单** | 恶意订单识别报表 | P0 | 【场景】识别和统计恶意订单 【输入】时间范围/风险等级 【输出】恶意订单列表 【字段】orderId,userId,riskLevel,reason 【关联】←订单风控 →风险处置 | +| **员工日志** | 员工操作日志报表 | P1 | 【场景】查看员工操作日志 【输入】员工/时间范围 【输出】操作日志 【字段】userId,action,module,time 【关联】←操作日志 →绩效评估 | +| **财务账单报表** | 财务账单明细报表 | P0 | 【场景】查看财务账单明细 【输入】时间范围/账单类型 【输出】财务账单 【字段】billId,type,amount,status 【关联】←财务核算 →财务报表 | +| **订单报表** | 订单综合统计报表 | P0 | 【场景】订单综合统计分析 【输入】时间范围/店铺/状态 【输出】订单统计报表 【字段】totalOrders,gmv,avgOrderValue 【关联】←订单数据 →数据分析 | +| **素材报表** | 素材使用统计报表 | P1 | 【场景】查看素材使用情况统计 【输入】时间范围/素材类型 【输出】素材统计报表 【字段】materialId,usageCount,performance 【关联】←素材库 →素材优化 | +| **商品报表** | 商品销售统计报表 | P0 | 【场景】查看商品销售统计 【输入】时间范围/商品/类目 【输出】商品报表 【字段】productId,sales,gmv,conversion 【关联】←商品数据 →商品分析 | +| **部门分组报表** | 部门业绩统计报表 | P1 | 【场景】查看部门分组业绩统计 【输入】时间范围/部门 【输出】部门报表 【字段】departmentId,orders,gmv,performance 【关联】←组织架构 →绩效评估 | + +--- + +### 7. TikTok Shop 运营 ⭐⭐⭐ + +#### 7.1 TikTok Shop 授权 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 店铺授权 | 店铺OAuth授权接入 | P0 | 【场景】TikTok Shop店铺OAuth授权 【输入】OAuth回调 【输出】授权状态 【字段】shopId,shopName,accessToken,refreshToken 【关联】←用户授权 →授权管理 | +| 授权刷新 | 自动刷新Token | P0 | 【场景】自动刷新过期的AccessToken 【输入】refreshToken 【输出】新Token 【字段】shopId,newAccessToken,expiresIn 【关联】←定时任务 | +| 授权状态 | 授权状态监控 | P0 | 【场景】监控授权有效性 【输入】店铺 【输出】状态 【字段】shopId,status,expireTime 【关联】←授权 | + +--- + +#### 7.2 TikTok 商品管理（一键同步上架）⭐核心 + +**核心功能流程**： +``` +ERP商品档案 → 类目/属性映射 → 图片/描述处理 → TikTok商品创建/更新 → 上架状态同步 + ↓ + 一键同步（支持单个/批量） +``` + +| 功能 | TikTok API | 技术流程 | 优先级 | 6要素描述 | +|------|-------------|----------|--------|----------| +| **TikTok类目获取** | category/get | 1.获取TikTok全量类目树 2.存储本地类目映射表 3.支持类目搜索 | P0 | 【场景】运营查看TikTok可用类目 【输入】父类目ID 【输出】类目树 【字段】categoryId,name,level,attributes 【关联】→商品发布 | +| **类目属性模板** | product/getAttributes | 1.根据选中类目获取必填属性 2.支持属性值枚举 3.属性校验规则 | P0 | 【场景】发布商品前获取属性要求 【输入】categoryId 【输出】属性模板 【字段】attrId,name,type,required,values 【关联】→商品创建 | +| **一键同步上架** | product/create + product/update | 1.选择ERP商品 2.自动类目/属性映射 3.图片/描述转换 4.调用TikTok API创建 5.自动上架 | P0 | 【场景】运营将ERP商品一键发布到TikTok 【输入】ERP商品ID+目标店铺 【输出】TikTok商品ID+上架状态 【字段】erpProductId,tiktokProductId,status 【关联】←ERP商品档案 →TikTok店铺 | +| **批量同步上架** | 批量API调用 | 1.选择多个ERP商品 2.后台异步任务处理 3.进度实时展示 4.成功/失败结果汇总 | P0 | 【场景】批量发布商品到TikTok 【输入】ERP商品ID列表 【输出】批量任务结果 【字段】taskId,total,success,failed,errors 【关联】←一键同步 →任务管理 | +| **商品信息拉取** | product/list + product/detail | 1.定时拉取TikTok商品列表 2.获取商品详情 3.与ERP商品关联 4.同步库存/价格 | P0 | 【场景】从TikTok拉取商品到ERP 【输入】店铺ID+时间范围 【输出】TikTok商品列表 【字段】productId,title,skus,images,status 【关联】←TikTok →ERP商品档案 | +| **商品更新同步** | product/update | 1.监听ERP商品变更 2.自动触发TikTok更新 3.支持价格/库存/描述更新 4.变更日志记录 | P0 | 【场景】ERP商品变更自动同步到TikTok 【输入】ERP商品变更 【输出】同步结果 【字段】productId,updateType,result 【关联】←ERP商品变更 →TikTok | +| **商品上下架** | product/update | 1.单个/批量上下架操作 2.状态实时同步 3.上下架原因记录 | P0 | 【场景】商品上架下架管理 【输入】productId+status 【输出】操作结果 【字段】productId,oldStatus,newStatus 【关联】←商品管理 | +| **商品状态监控** | product/list | 1.定时检查商品状态 2.审核中/已驳回/已上架状态 3.异常状态预警 | P1 | 【场景】监控TikTok商品状态 【输入】店铺ID 【输出】状态报告 【字段】productId,status,auditReason 【关联】←TikTok →消息通知 | + +**TikTok 商品数据模型**： +```typescript +interface TikTokProduct { + tiktokProductId: string; + erpProductId: string; + shopId: string; + title: string; + description: string; + categoryId: string; + images: { url: string; isMain: boolean; sort: number }[]; + skus: { + skuId: string; + sellerSku: string; + price: number; + inventory: number; + attributes: Record; + images: string[]; + }[]; + status: 'DRAFT' | 'PENDING' | 'ACTIVE' | 'INACTIVE' | 'DELETED'; + syncStatus: 'SYNCED' | 'PENDING' | 'FAILED'; + lastSyncTime: Date; +} +``` + +--- + +#### 7.3 TikTok 订单管理（自动抓单、发货回传）⭐核心 + +**核心功能流程**： +``` +TikTok订单 → 定时/实时拉取 → 订单归一化 → 订单工作台 → 审核/确认 → 发货回传 + ↓ + 订单利润核算 → 财务对账 +``` + +| 功能 | TikTok API | 技术流程 | 优先级 | 6要素描述 | +|------|-------------|----------|--------|----------| +| **订单自动拉取** | order/list | 1.定时任务（5分钟/次）拉取增量订单 2.Webhook实时接收新订单 3.订单去重处理 4.状态变更同步 | P0 | 【场景】自动从TikTok拉取订单 【输入】时间范围+店铺 【输出】订单列表 【字段】orderId,createTime,status 【关联】←TikTok →订单工作台 | +| **订单详情获取** | order/detail | 1.拉取订单完整信息 2.买家信息脱敏 3.收货地址解析 4.商品明细提取 | P0 | 【场景】查看订单详细信息 【输入】orderId 【输出】订单详情 【字段】buyer,items,shippingAddress,payment 【关联】←订单列表 | +| **订单确认** | order/confirm | 1.自动确认有效订单 2.异常订单标记 3.确认状态同步 | P0 | 【场景】确认订单有效性 【输入】orderId 【输出】确认结果 【字段】orderId,confirmStatus 【关联】←订单审核 | +| **订单取消** | order/cancel | 1.支持买家取消/卖家取消 2.取消原因记录 3.库存回滚 4.退款处理 | P0 | 【场景】取消订单 【输入】orderId+原因 【输出】取消结果 【字段】orderId,cancelReason,refundAmount 【关联】←异常订单 | +| **订单改地址** | order/updateAddress | 1.发货前修改地址 2.地址格式校验 3.修改日志记录 | P1 | 【场景】修改订单收货地址 【输入】orderId+新地址 【输出】修改结果 【字段】orderId,oldAddress,newAddress 【关联】←订单 | +| **发货回传** | shipping/createFulfilment | 1.选择物流渠道 2.获取面单 3.填写物流单号 4.调用TikTok API回传 5.状态同步 | P0 | 【场景】发货后回传物流信息到TikTok 【输入】orderId+trackingNo+carrier 【输出】回传结果 【字段】orderId,fulfillmentId,status 【关联】←订单发货 →TikTok | +| **批量发货回传** | shipping/batch | 1.选择多个待发货订单 2.批量获取面单 3.批量回传物流 4.成功/失败汇总 | P0 | 【场景】批量处理订单发货 【输入】订单列表+物流信息 【输出】批量发货结果 【字段】taskId,success[],failed[] 【关联】←批量操作 | +| **订单退款** | order/refund | 1.部分退款/全额退款 2.退款原因记录 3.退款金额计算 4.退款状态同步 | P0 | 【场景】处理订单退款 【输入】orderId+amount+reason 【输出】退款结果 【字段】refundId,orderId,amount,status 【关联】←售后工单 | +| **订单利润分析** | 本地计算 | 1.订单金额-平台佣金-物流成本-采购成本 2.利润率计算 3.异常利润预警 | P0 | 【场景】计算每笔订单利润 【输入】订单+成本数据 【输出】利润数据 【字段】orderId,revenue,cost,profit,margin 【关联】←订单 →财务报表 | + +**TikTok 订单数据模型**： +```typescript +interface TikTokOrder { + tiktokOrderId: string; + erpOrderId: string; + shopId: string; + orderStatus: 'UNPAID' | 'AWAITING_SHIPMENT' | 'SHIPPED' | 'DELIVERED' | 'CANCELLED' | 'RETURNED'; + createTime: Date; + payTime: Date; + buyer: { + name: string; + phone: string; + email: string; + }; + shippingAddress: { + name: string; + phone: string; + address1: string; + address2: string; + city: string; + state: string; + postalCode: string; + country: string; + }; + items: { + itemId: string; + productId: string; + skuId: string; + sellerSku: string; + title: string; + quantity: number; + price: number; + skuImage: string; + }[]; + payment: { + subtotal: number; + shippingFee: number; + platformDiscount: number; + sellerDiscount: number; + totalAmount: number; + currency: string; + }; + fulfillment: { + fulfillmentId: string; + trackingNumber: string; + carrier: string; + shippedTime: Date; + deliveredTime: Date; + }; + profit: { + revenue: number; + cost: number; + platformFee: number; + shippingCost: number; + profit: number; + profitRate: number; + }; + syncStatus: 'SYNCED' | 'PENDING' | 'FAILED'; + lastSyncTime: Date; +} +``` + +--- + +#### 7.4 TikTok 库存同步（多仓库同步）⭐核心 + +**核心功能流程**： +``` +ERP多仓库库存 → 库存汇总/分配规则 → TikTok库存更新 → 库存状态同步 → 超卖预警 + ↓ + 双向同步（TikTok库存变化也同步回ERP） +``` + +| 功能 | TikTok API | 技术流程 | 优先级 | 6要素描述 | +|------|-------------|----------|--------|----------| +| **TikTok库存查询** | product/inventory | 1.批量查询TikTok商品库存 2.实时库存状态 3.仓库级库存 | P0 | 【场景】查询TikTok商品库存 【输入】skuIds 【输出】库存数据 【字段】skuId,quantity,warehouseId 【关联】←TikTok →库存同步 | +| **ERP→TikTok库存同步** | product/updateInventory | 1.监听ERP库存变动 2.根据同步规则计算TikTok库存 3.批量更新TikTok库存 4.同步结果记录 | P0 | 【场景】ERP库存变动同步到TikTok 【输入】skuId+quantity 【输出】同步结果 【字段】skuId,oldQty,newQty,status 【关联】←ERP库存 →TikTok店铺 | +| **多仓库库存映射** | 本地配置 | 1.配置ERP仓库与TikTok仓库映射 2.库存汇总规则（优先/叠加）3.安全库存设置 | P0 | 【场景】多仓库库存同步配置 【输入】仓库映射规则 【输出】映射配置 【字段】erpWarehouseId,tiktokWarehouseId,priority 【关联】←仓库管理 →库存同步 | +| **库存安全阈值** | 本地配置 | 1.设置SKU级安全库存 2.库存低于阈值自动下架 3.预警通知 | P0 | 【场景】库存安全阈值管理 【输入】skuId+threshold 【输出】阈值配置 【字段】skuId,safeStock,autoOffSale 【关联】←商品管理 →库存预警 | +| **TikTok→ERP库存同步** | product/inventory | 1.定时拉取TikTok库存 2.与ERP库存对比 3.差异处理 4.库存流水记录 | P1 | 【场景】TikTok库存变化同步回ERP 【输入】店铺ID 【输出】库存差异报告 【字段】skuId,tiktokQty,erpQty,diff 【关联】←TikTok →ERP库存 | +| **批量库存同步** | 批量API调用 | 1.选择多个SKU 2.后台异步同步 3.进度实时展示 4.成功/失败汇总 | P0 | 【场景】批量同步库存到TikTok 【输入】skuId+quantity列表 【输出】批量同步结果 【字段】taskId,total,success,failed 【关联】←批量操作 | +| **库存同步日志** | 本地记录 | 1.记录每次库存同步 2.同步前后数据对比 3.错误原因记录 4.日志查询 | P1 | 【场景】查看库存同步历史 【输入】时间范围+sku 【输出】同步日志 【字段】logId,skuId,type,before,after,status 【关联】←库存同步 | +| **超卖预警** | 本地监控 | 1.实时监控库存与订单 2.库存不足预警 3.超卖风险识别 | P0 | 【场景】超卖风险预警 【输入】订单+库存 【输出】预警通知 【字段】skuId,currentStock,pendingOrders,riskLevel 【关联】←库存/订单 →消息通知 | + +**TikTok 库存数据模型**： +```typescript +interface TikTokInventory { + skuId: string; + sellerSku: string; + shopId: string; + warehouseId: string; + availableQuantity: number; + reservedQuantity: number; + totalQuantity: number; + safeStock: number; + syncStatus: 'SYNCED' | 'PENDING' | 'FAILED'; + lastSyncTime: Date; + warehouseMapping: { + erpWarehouseId: string; + tiktokWarehouseId: string; + allocationRatio: number; + priority: number; + }[]; +} +``` + +--- + +#### 7.5 TikTok 物流履约（面单打印、物流回传）⭐核心 + +**核心功能流程**： +``` +待发货订单 → 物流渠道选择 → 获取TikTok面单 → 面单打印 → 包裹发货 → 物流回传 → 轨迹同步 + ↓ + 批量处理（支持100+订单同时处理） +``` + +| 功能 | TikTok API | 技术流程 | 优先级 | 6要素描述 | +|------|-------------|----------|--------|----------| +| **物流渠道列表** | logistics/getChannelList | 1.获取TikTok支持的物流商 2.渠道参数配置 3.运费试算 | P0 | 【场景】获取可用物流渠道 【输入】destinationCountry 【输出】物流渠道列表 【字段】channelId,name,type,priceRange 【关联】→发货 | +| **TikTok物流面单获取** | shipping/getFulfilment | 1.选择物流渠道 2.调用TikTok API 3.获取面单PDF/HTML 4.面单存储 | P0 | 【场景】获取TikTok物流面单 【输入】orderId+channelId 【输出】面单URL 【字段】orderId,labelUrl,labelType 【关联】←订单发货 | +| **面单打印** | 本地打印 | 1.面单格式适配（A4/热敏）2.批量打印支持 3.打印预览 4.打印记录 | P0 | 【场景】打印物流面单 【输入】orderIds+打印配置 【输出】打印任务 【字段】taskId,orderIds,printStatus 【关联】←面单获取 | +| **物流信息回传** | shipping/createFulfilment | 1.填写物流单号 2.选择物流商 3.调用TikTok API 4.状态同步 | P0 | 【场景】发货后回传物流信息 【输入】orderId+trackingNo+carrier 【输出】回传结果 【字段】orderId,fulfillmentId,status 【关联】←订单发货 →TikTok | +| **批量物流履约** | shipping/batch | 1.选择多个待发货订单 2.批量获取面单 3.批量回传物流 4.任务进度监控 | P0 | 【场景】批量处理物流履约 【输入】订单列表+物流信息 【输出】批量履约结果 【字段】taskId,success[],failed[],progress 【关联】←批量操作 | +| **物流轨迹查询** | logistics/track | 1.调用TikTok物流轨迹API 2.轨迹数据解析 3.状态更新 4.异常轨迹预警 | P1 | 【场景】查询物流轨迹 【输入】trackingNo 【输出】轨迹列表 【字段】trackingNo,events[],location,time 【关联】←物流追踪 | +| **物流轨迹同步** | 定时任务 | 1.定时拉取在途订单轨迹 2.轨迹状态更新 3.签收确认 4.异常通知 | P1 | 【场景】同步物流轨迹到ERP 【输入】在途订单列表 【输出】轨迹同步结果 【字段】orderId,trackingStatus,lastEvent 【关联】←TikTok →订单 | +| **物流异常处理** | 本地监控 | 1.物流超时监控 2.异常状态识别 3.异常处理建议 4.工单创建 | P1 | 【场景】物流异常处理 【输入】异常物流数据 【输出】异常处理记录 【字段】orderId,exceptionType,solution,status 【关联】←物流追踪 →售后工单 | + +**TikTok 物流数据模型**： +```typescript +interface TikTokFulfillment { + fulfillmentId: string; + orderId: string; + shopId: string; + channelId: string; + channelName: string; + trackingNumber: string; + labelUrl: string; + labelType: 'PDF' | 'HTML' | 'ZPL'; + shippedTime: Date; + estimatedDeliveryTime: Date; + deliveredTime: Date; + trackingStatus: 'CREATED' | 'PICKED_UP' | 'IN_TRANSIT' | 'OUT_FOR_DELIVERY' | 'DELIVERED' | 'FAILED'; + trackingEvents: { + eventTime: Date; + eventType: string; + eventDescription: string; + location: string; + }[]; + syncStatus: 'SYNCED' | 'PENDING' | 'FAILED'; + lastSyncTime: Date; +} +``` + +--- + +#### 7.6 TikTok 数据报表（GMV、销量、流量分析）⭐核心 + +**核心功能流程**： +``` +TikTok Analytics API → 数据拉取 → 数据清洗 → 数据存储 → 报表展示 → 趋势分析 → 数据导出 + ↓ + 多维度分析（时间/商品/店铺/品类） +``` + +| 功能 | TikTok API | 技术流程 | 优先级 | 6要素描述 | +|------|-------------|----------|--------|----------| +| **销售数据拉取** | analytics/sales | 1.按日/周/月拉取销售数据 2.GMV/订单量/客单价计算 3.数据存储 | P0 | 【场景】获取TikTok销售数据 【输入】时间范围+店铺 【输出】销售报表 【字段】date,gmv,orders,avgOrderValue 【关联】←TikTok →数据大盘 | +| **GMV数据分析** | analytics/sales | 1.GMV趋势分析 2.日/周/月同比环比 3.目标完成度 4.GMV构成分析 | P0 | 【场景】GMV数据分析 【输入】时间维度 【输出】GMV分析报告 【字段】period,gmv,growthRate,targetCompletion 【关联】←销售数据 →数据大盘 | +| **商品销售分析** | analytics/product | 1.商品销量排行 2.商品转化率 3.商品动销率 4.商品贡献度 | P0 | 【场景】商品销售分析 【输入】时间+商品 【输出】商品报表 【字段】productId,views,cart,sales,conversion 【关联】←数据分析 | +| **流量来源分析** | analytics/traffic | 1.流量来源构成 2.各渠道流量趋势 3.流量质量分析 4.转化漏斗 | P1 | 【场景】流量来源分析 【输入】时间范围 【输出】流量报表 【字段】source,visits,views,conversion,占比 【关联】←数据分析 | +| **店铺数据对比** | analytics/sales | 1.多店铺数据对比 2.店铺排名 3.店铺贡献度 4.店铺趋势对比 | P0 | 【场景】多店铺数据对比 【输入】时间范围+店铺列表 【输出】店铺对比报表 【字段】shopId,gmv,orders,rank 【关联】←销售数据 →数据大盘 | +| **品类销售分析** | analytics/product + 本地聚合 | 1.品类GMV占比 2.品类销量趋势 3.品类动销率 4.品类贡献度 | P1 | 【场景】品类销售分析 【输入】时间+品类 【输出】品类报表 【字段】categoryId,gmv,orders,占比 【关联】←商品分析 | +| **数据趋势预测** | 本地算法 | 1.基于历史数据预测 2.销售趋势预测 3.库存需求预测 4.预警提醒 | P2 | 【场景】数据趋势预测 【输入】历史数据 【输出】预测报告 【字段】period,predictedGmv,confidence 【关联】←历史数据 | +| **数据报表导出** | 本地生成 | 1.Excel/PDF/CSV导出 2.自定义报表模板 3.定时报表推送/邮件 4.报表订阅 | P1 | 【场景】数据报表导出（Excel/PDF/CSV）【输入】报表类型+时间范围 【输出】报表文件+下载链接 【字段】reportId,fileUrl,format,emailStatus 【关联】←各报表 | +| **实时数据大屏** | WebSocket + 缓存 | 1.实时GMV展示 2.实时订单监控 3.实时流量展示 4.数据刷新动画 | P2 | 【场景】实时数据大屏 【输入】实时数据流 【输出】大屏展示 【字段】realtimeGmv,realtimeOrders,realtimeVisits 【关联】←实时数据 | + +**TikTok 数据报表模型**： +```typescript +interface TikTokSalesReport { + reportId: string; + shopId: string; + period: { + startDate: Date; + endDate: Date; + granularity: 'DAY' | 'WEEK' | 'MONTH'; + }; + summary: { + totalGmv: number; + totalOrders: number; + totalItems: number; + avgOrderValue: number; + conversionRate: number; + }; + dailyData: { + date: Date; + gmv: number; + orders: number; + items: number; + avgOrderValue: number; + visits: number; + conversionRate: number; + }[]; + productData: { + productId: string; + title: string; + skuId: string; + views: number; + cartAdds: number; + orders: number; + gmv: number; + conversionRate: number; + }[]; + categoryData: { + categoryId: string; + categoryName: string; + gmv: number; + orders: number; + percentage: number; + }[]; + trafficData: { + source: string; + visits: number; + views: number; + orders: number; + conversionRate: number; + percentage: number; + }[]; +} +``` + +--- + +#### 7.7 GMVMAX 商务中心 ⭐核心 +**GMVMAX核心价值**：把GMV目标拆成周/日动作，AI把数据直接生成"策略建议+行动清单"，把经验固化成SOP+自动化执行，提高人效比+持续提高ROI，风险前置（赔付测算+恶意用户识别） + +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| GMVMAX接入 | GMVMAX商务中心授权 | P0 | 【场景】接入TikTok商务中心获取数据 【输入】OAuth授权 【输出】授权状态 【字段】appId,status,token 【关联】←用户授权 →数据拉取 | +| **GMV目标管理** | GMV目标拆解到周/日/动作 | P0 | 【场景】设定GMV目标并拆解到执行计划 【输入】目标GMV+时间周期 【输出】目标拆解计划 【字段】planId,targetGmv,period,dailyTarget,weeklyTarget 【关联】←用户设定 →行动计划 | +| **行动计划生成** | AI生成策略建议+行动清单 | P0 | 【场景】AI基于数据生成今日动作清单 【输入】历史数据+目标 【输出】策略建议+行动清单 【字段】actionListId,suggestions[],actions[],priority 【关联】←目标管理 →执行跟踪 | +| **执行跟踪** | 每日动作执行进度追踪 | P0 | 【场景】追踪每日动作执行情况 【输入】动作清单+执行记录 【输出】进度报告 【字段】actionId,status,result,executeTime 【关联】←行动计划 →复盘 | +| GMV销售看板 | GMV数据实时展示 | P0 | 【场景】展示GMV销售数据 【输入】时间范围 【输出】GMV报表 【字段】gmv,orders,avgOrderValue 【关联】←GMVMAX API | +| GMV趋势分析 | GMV趋势图表+目标完成度 | P0 | 【场景】分析GMV趋势+目标完成进度 【输入】时间维度+目标 【输出】趋势图+完成度 【字段】date,gmv,orders,targetCompletion 【关联】←GMVMAX API →目标管理 | +| **SOP管理** | 把经验固化成标准操作流程 | P0 | 【场景】管理运营SOP流程 【输入】SOP模板+步骤 【输出】SOP库 【字段】sopId,name,steps[],version 【关联】←经验沉淀 →自动化执行 | +| **自动化执行** | SOP自动化执行 | P0 | 【场景】自动执行SOP流程 【输入】SOP+触发条件 【输出】执行结果 【字段】automationId,sopId,trigger,result 【关联】←SOP管理 →执行跟踪 | +| **赔付测算** | 订单赔付风险前置测算 | P0 | 【场景】发货前测算赔付风险 【输入】订单+商品数据 【输出】赔付风险报告 【字段】orderId,riskLevel,estimatedPayout,suggestion 【关联】←订单 →风险预警 | +| **恶意用户识别** | 识别多次下单退单的恶意用户 | P0 | 【场景】识别恶意用户（多次下单退单且商品已发出）【输入】用户订单历史 【输出】恶意用户标记 【字段】userId,riskScore,orderHistory,action 【关联】←用户数据 →风险处置 | +| **风险处置** | 恶意用户风险处置 | P0 | 【场景】处置恶意用户风险 【输入】恶意用户标记 【输出】处置记录 【字段】userId,disposalType,result,operateTime 【关联】←恶意用户识别 →订单处理 | +| **复盘分析** | 周期复盘与优化建议 | P1 | 【场景】周/月复盘分析与优化 【输入】周期数据+执行记录 【输出】复盘报告+优化建议 【字段】reviewId,period,findings[],suggestions[] 【关联】←执行跟踪 →目标管理 | +| GMV品类分析 | 品类GMV占比+贡献度 | P1 | 【场景】分析品类GMV分布+贡献 【输入】品类维度 【输出】品类报表 【字段】categoryId,gmv,orders,percentage,contribution 【关联】←GMVMAX API →行动计划 | +| GMV店铺分析 | 店铺GMV排名+贡献度 | P1 | 【场景】分析各店铺GMV+贡献 【输入】店铺维度 【输出】店铺排行 【字段】shopId,gmv,orders,rank,contribution 【关联】←GMVMAX API →行动计划 | +| GMV商品分析 | 商品GMV排行+ROI | P1 | 【场景】分析商品GMV贡献+ROI 【输入】商品维度 【输出】商品排行 【字段】productId,gmv,sales,roi 【关联】←GMVMAX API →行动计划 | + +#### 7.7.1 GMVMAX 活动管理 ⭐彩蛋 +**GMVMAX活动管理核心价值**：管理GMVMAX营销活动，支持按店铺、广告账户、活动名称、活动ID、状态、时间等多维度筛选，批量绑定规则包，灵活配置活动时间范围。 + +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| **活动列表查询** | 多维度筛选GMVMAX活动 | P0 | 【场景】查询和筛选GMVMAX营销活动 【输入】店铺/广告账户/活动名称/活动ID/状态/时间/规则包 【输出】活动列表 【字段】activityId,shopId,adAccountId,name,status,timeRange,rulePack 【关联】←搜索条件 →活动列表 | +| **创建GMVMAX** | 创建新的GMVMAX活动 | P0 | 【场景】创建新的GMVMAX营销活动 【输入】活动配置（名称/店铺/广告账户/时间/规则包）【输出】新活动记录 【字段】activityId,name,shopId,adAccountId,startTime,endTime,rulePackId 【关联】←用户输入 →活动列表 | +| **批量绑定规则包** | 批量绑定规则包到活动 | P0 | 【场景】批量绑定规则包到多个活动 【输入】活动ID列表+规则包ID 【输出】绑定结果 【字段】activityIds[],rulePackId,successCount,failedCount 【关联】←活动列表 →规则绑定 | +| **活动列配置** | 自定义活动列表显示列 | P1 | 【场景】自定义活动列表显示字段 【输入】列配置 【输出】列配置保存 【字段】userId,columns[],sort 【关联】←用户设置 →列表展示 | +| **快速时间选择** | 预设时间范围快速选择 | P0 | 【场景】快速选择时间范围查看活动 【输入】时间预设（今天/昨天/近3天/近7天/近30天）【输出】时间范围 【字段】preset,startDate,endDate 【关联】←时间预设 →活动筛选 | +| **活动时间配置** | 活动开始结束时间设置 | P0 | 【场景】设置活动的开始和结束时间 【输入】活动ID+开始时间+结束时间 【输出】时间配置 【字段】activityId,startTime,endTime 【关联】←活动编辑 →活动状态 | + +#### 7.8 GMVMAX 规则管理 ⭐彩蛋 +**GMVMAX规则管理核心价值**：配置自动化规则，根据触发条件自动执行动作，实现24小时自动化运营，保护期内不重复触发，支持规则优先级和判断频率配置。 + +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| **规则列表查询** | 按条件筛选规则列表 | P0 | 【场景】查询和筛选GMVMAX规则 【输入】规则名称/触发动作/优先级/状态/频率 【输出】规则列表 【字段】ruleId,name,triggerAction,priority,status,frequency 【关联】←搜索条件 →规则列表 | +| **新增规则** | 创建新的GMVMAX规则 | P0 | 【场景】创建新的自动化规则 【输入】规则配置（名称/触发动作/条件/动作）【输出】新规则记录 【字段】ruleId,name,triggerAction,conditions,actions,priority 【关联】←用户输入 →规则列表 | +| **规则启用/暂停** | 规则状态切换 | P0 | 【场景】启用或暂停规则执行 【输入】规则ID+状态 【输出】状态变更结果 【字段】ruleId,oldStatus,newStatus,operateTime 【关联】←规则列表 →规则状态 | +| **查看绑定列表** | 查看规则绑定的活动 | P0 | 【场景】查看规则绑定的GMVMAX活动 【输入】规则ID 【输出】绑定活动列表 【字段】ruleId,boundActivities[],count 【关联】←规则列表 →活动绑定 | +| **规则导出** | 批量导出规则配置 | P1 | 【场景】导出规则配置备份或分享 【输入】规则筛选条件 【输出】规则导出文件 【字段】exportId,filters,fileUrl,exportTime 【关联】←规则列表 →文件下载 | +| **规则列配置** | 自定义规则列表显示列 | P1 | 【场景】自定义规则列表显示字段 【输入】列配置 【输出】列配置保存 【字段】userId,columns[],sort 【关联】←用户设置 →列表展示 | +| **24小时保护** | 规则触发保护机制 | P0 | 【场景】防止规则24小时内重复触发 【输入】规则ID+保护开关 【输出】保护配置 【字段】ruleId,protectionEnabled,lastTriggerTime 【关联】←规则配置 →防重复触发 | +| **规则优先级** | 规则执行优先级配置 | P0 | 【场景】配置规则执行优先级顺序 【输入】规则ID+优先级值 【输出】优先级配置 【字段】ruleId,priority,sortOrder 【关联】←规则配置 →规则执行顺序 | +| **规则判断频率** | 规则检查频率配置 | P1 | 【场景】配置规则判断执行频率 【输入】规则ID+频率设置 【输出】频率配置 【字段】ruleId,checkFrequency,interval 【关联】←规则配置 →定时任务 | + +--- + +**TikTok API 对接汇总**： +| API类型 | 文档 | 功能模块 | +| :--- | :--- | :--- | +| **TikTok Shop API** | [partner.tiktokshop.com/docv2/](https://partner.tiktokshop.com/docv2/) | 授权、商品、订单、物流、库存、数据 | +| **TikTok Business API** | [business-api.tiktok.com/](https://business-api.tiktok.com/portal/docs) | 广告投放 | +| **GMVMAX 商务中心** | 商务中心 | GMV数据/广告关联/归因 | + +**TikTok 5大核心功能 API 映射**： +| 核心功能 | 核心API | 优先级 | +| :--- | :--- | :--- | +| **商品管理（一键同步上架）** | category/get, product/getAttributes, product/create, product/update, product/list | P0 | +| **订单管理（自动抓单、发货回传）** | order/list, order/detail, order/confirm, order/cancel, shipping/createFulfilment | P0 | +| **库存同步（多仓库同步）** | product/inventory, product/updateInventory | P0 | +| **物流履约（面单打印、物流回传）** | logistics/getChannelList, shipping/getFulfilment, shipping/createFulfilment, logistics/track | P0 | +| **数据报表（GMV、销量、流量分析）** | analytics/sales, analytics/product, analytics/traffic | P0 | + +--- + +### 8. 广告投放 ⭐⭐⭐ + +#### 8.1 Facebook Ads +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| FB授权 | Facebook广告账户授权 | P0 | 【场景】接入Facebook广告账户 【输入】OAuth授权 【输出】授权状态 【字段】accountId,adAccountName,status 【关联】←用户授权 →广告管理 | +| FB广告账户 | 广告账户管理 | P0 | 【场景】管理多个FB广告账户 【输入】账户列表 【输出】账户状态 【字段】accountId,name,spend,results 【关联】←授权 →广告投放 | +| FB广告系列 | Campaign管理 | P0 | 【场景】创建/管理广告系列 【输入】系列配置 【输出】系列 【字段】campaignId,name,objective,budget 【关联】←账户 →广告组 | +| FB广告组 | Ad Group管理 | P0 | 【场景】创建/管理广告组 【输入】组配置 【输出】广告组 【字段】adGroupId,targeting,budget,schedule 【关联】←系列 →广告 | +| FB广告素材 | 广告创意管理 | P0 | 【场景】管理广告素材 【输入】素材内容 【输出】素材记录 【字段】creativeId,type,content,images 【关联】←广告组 | +| FB数据报表 | 广告效果分析 | P0 | 【场景】分析FB广告效果 【输入】时间范围 【输出】报表 【字段】impressions,clicks,spend,ctr,cpc,conversions 【关联】←广告数据 | + +#### 8.2 Google Ads +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| Google授权 | Google广告账户授权 | P0 | 【场景】接入Google广告账户 【输入】OAuth授权 【输出】授权状态 【字段】accountId,accountName,status 【关联】←用户授权 →广告管理 | +| Google广告账户 | 广告账户管理 | P0 | 【场景】管理多个Google广告账户 【输入】账户列表 【输出】账户状态 【字段】accountId,name,spend,clicks 【关联】←授权 →广告投放 | +| Google广告系列 | Campaign管理 | P0 | 【场景】创建/管理搜索/购物广告系列 【输入】系列配置 【输出】系列 【字段】campaignId,name,type,budget 【关联】←账户 →广告组 | +| Google广告组 | Ad Group管理 | P0 | 【场景】创建/管理广告组 【输入】组配置 【输出】广告组 【字段】adGroupId,keywords,targeting 【关联】←系列 →广告 | +| Google广告创意 | 广告文案管理 | P0 | 【场景】管理广告创意 【输入】文案/图片 【输出】创意 【字段】creativeId,headlines,descriptions 【关联】←广告组 | +| Google数据报表 | 广告效果分析 | P0 | 【场景】分析Google广告效果 【输入】时间范围 【输出】报表 【字段】impressions,clicks,spend,conversions,cpa,roas 【关联】←广告数据 | + +#### 8.3 TikTok Ads ⭐核心 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| TikTok授权 | TikTok广告账户授权 | P0 | 【场景】接入TikTok广告账户 【输入】OAuth授权 【输出】授权状态 【字段】advertiserId,advertiserName,status 【关联】←用户授权 →广告管理 | +| TikTok广告账户 | 广告账户管理 | P0 | 【场景】管理多个TikTok广告账户 【输入】账户列表 【输出】账户状态 【字段】advertiserId,name,spend,balance 【关联】←授权 →广告投放 | +| TikTok广告系列 | Campaign管理 | P0 | 【场景】创建/管理广告系列 【输入】系列配置 【输出】系列 【字段】campaignId,name,objective,budget 【关联】←账户 →广告组 | +| TikTok广告组 | Ad Group管理 | P0 | 【场景】创建/管理广告组 【输入】组配置 【输出】广告组 【字段】adGroupId,targeting,placement,budget 【关联】←系列 →广告 | +| TikTok广告素材 | 短视频广告管理 | P0 | 【场景】管理TikTok广告素材 【输入】视频/图片 【输出】素材 【字段】creativeId,videoUrl,images 【关联】←广告组 | +| TikTok数据报表 | 广告效果分析 | P0 | 【场景】分析TikTok广告效果 【输入】时间范围 【输出】报表 【字段】impressions,views,clicks,spend,cpm,cpc,conversions 【关联】←广告数据 | + +#### 8.4 广告投放 ⭐重点 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 多平台广告 | 多平台广告统一管理 | P0 | 【场景】统一管理FB/Google/TikTok广告 【输入】广告数据 【输出】多平台报表 【字段】platform,campaign,performance 【关联】←各平台 | +| 跨平台比价 | 各平台广告成本对比 | P1 | 【场景】对比各平台广告ROI 【输入】多平台数据 【输出】对比报表 【字段】platform,cpc,cpm,roas 【关联】←各平台数据 | +| 广告调价 | 智能调整出价 | P1 | 【场景】根据效果调整出价 【输入】广告效果数据 【输出】调价建议 【字段】campaignId,currentBid,suggestedBid 【关联】←数据报表 | +| 广告预算 | 预算分配管理 | P1 | 【场景】分配广告预算 【输入】各平台预算 【输出】预算分配 【字段】platform,budget,spent 【关联】←广告账户 | + +#### 8.5 GMVMAX与广告联动 ⭐核心 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| GMV-Ads关联 | GMV与广告数据关联 | P0 | 【场景】关联GMV数据与广告投放 【输入】GMV+广告数据 【输出】关联报表 【字段】gmv,adSpend,adId 【关联】←GMVMAX+广告 | +| 广告ROI分析 | 广告投入产出比 | P0 | 【场景】分析广告ROI 【输入】广告花费+GMV 【输出】ROI报表 【字段】campaignId,spend,gmv,roas 【关联】←GMV-Ads关联 | +| 广告归因 | GMV归因到广告 | P1 | 【场景】归因GMV来源 【输入】订单+广告点击 【输出】归因结果 【字段】orderId,adClick,attributedGMV 【关联】←GMV+广告追踪 | +| 优化建议 | 基于GMV的投放建议 | P1 | 【场景】根据GMV效果优化广告 【输入】GMV+广告数据 【输出】优化建议 【字段】suggestion,impact 【关联】←ROI分析 | +| GMV广告盘 | GMVMAX投放大盘 | P0 | 【场景】GMVMAX广告数据汇总 【输入】广告数据 【输出】广告大盘 【字段】totalSpend,totalGMV,overallROAS 【关联】←GMVMAX+广告 | + +**广告平台API对接**： +| 平台 | API类型 | 功能 | +| :--- | :--- | :--- | +| **Facebook Ads** | Marketing API | 账户/Campaign/广告组/创意/数据 | +| **Google Ads** | Google Ads API | 账户/Campaign/广告组/创意/数据 | +| **TikTok Ads** | TikTok Ads API | 账户/Campaign/广告组/创意/数据 | +| **GMVMAX** | GMVMAX API | GMV数据/广告关联/归因 | + +--- + +### 9. 独立站运营 (DTC) ⭐⭐⭐ + +#### 9.1 独立站接入 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 多平台授权 | Shopify/WooCommerce/Shopline等多平台授权 | P0 | 【场景】接入多个独立站店铺 【输入】店铺URL/OAuth授权 【输出】店铺连接状态 【字段】shopId,platform,shopUrl,status,token 【关联】←用户授权 →店铺管理 | +| 店铺管理 | 多店铺状态监控 | P0 | 【场景】管理所有接入的独立站 【输入】店铺列表 【输出】店铺状态 【字段】shopId,name,platform,orders,sales 【关联】←授权 →订单/商品 | +| 独立站商品同步 | 商品双向同步 | P0 | 【场景】将商品同步到独立站或从独立站拉取 【输入】商品+目标店铺 【输出】同步结果 【字段】productId,shopId,syncStatus 【关联】←商品档案 →独立站店铺 | +| 独立站订单拉取 | 订单自动同步 | P0 | 【场景】实时同步独立站订单 【输入】店铺订单数据 【输出】订单列表 【字段】orderId,shopId,items[],status 【关联】←店铺同步 →订单工作台 | +| 独立站发货同步 | 发货信息回传 | P1 | 【场景】发货后同步物流信息到独立站 【输入】发货单+物流信息 【输出】同步状态 【字段】orderId,trackingNo,shopId 【关联】←订单发货 →独立站 | +| 独立站库存同步 | 库存实时同步 | P1 | 【场景】独立站库存与ERP实时同步 【输入】库存变动 【输出】同步结果 【字段】skuId,shopId,quantity 【关联】←库存 →独立站店铺 | +| 独立站主题管理 | 店铺主题/装修 | P2 | 【场景】管理独立站视觉主题 【输入】主题配置 【输出】主题状态 【字段】themeId,shopId,status 【关联】←店铺 | + +**支持的独立站平台**： +| 平台 | API类型 | 对接方式 | +| :--- | :--- | :--- | +| **Shopify** | Admin API | OAuth2.0授权 | +| **WooCommerce** | REST API | Consumer Key/Secret | +| **Shopline** | Open API | API Key授权 | +| **Shoplazza** | Open API | 店铺授权 | +| **BigCommerce** | REST API | OAuth2.0 | +| **ShopPY** | Open API | 店铺授权 | + +#### 9.2 独立站自研 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 独立站CMS | 自研商城内容管理 | P2 | 【场景】自建独立站内容管理 【输入】商品/文章/页面 【输出】站点内容 【字段】type,content,status 【关联】←商品档案 | +| 独立站主题模板 | 自研店铺模板 | P2 | 【场景】创建店铺视觉模板 【输入】模板配置 【输出】模板 【字段】templateId,name,html,css 【关联】→CMS | +| 独立站购物车 | 购物车功能 | P2 | 【场景】用户购物车功能 【输入】商品+数量 【输出】购物车 【字段】cartId,items[],total 【关联】←商品 →结算 | +| 独立站结算 | 订单结算支付 | P2 | 【场景】订单支付流程 【输入】购物车+支付方式 【输出】订单 【字段】orderId,paymentMethod,amount 【关联】←购物车 →订单 | + +--- + +### 10. 客户关系 (CRM) ⭐ + +#### 10.1 客户管理 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 客户档案 | 客户信息管理 | P1 | 【场景】管理客户信息 【输入】客户资料 【输出】客户记录 【字段】customerId,name,email,platform 【关联】←订单 | +| 客户分类 | 客户分层管理 | P2 | 【场景】按价值分层客户 【输入】消费数据 【输出】客户等级 【字段】customerId,level,score 【关联】←客户档案 | +| 会员LTV | 客户生命周期价值 | P2 | 【场景】计算客户长期价值 【输入】历史消费 【输出】LTV值 【字段】customerId,ltv,orderCount 【关联】←客户档案 | + +#### 10.2 售后服务 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 售后工单 | 退货、拒付、纠纷处理 | P1 | 【场景】处理售后问题 【输入】售后申请 【输出】工单记录 【字段】ticketId,orderId,type,status 【关联】←订单 | +| 评价管理 | 好评请求、差评监控 | P2 | 【场景】管理店铺评价 【输入】评价数据 【输出】评价记录 【字段】orderId,rating,comment,response 【关联】←订单 | + +--- + +--- + +### 11. 素材管理 ⭐⭐⭐ + +#### 11.1 图片素材管理 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 素材库管理 | 图片素材分类管理 | P0 | 【场景】管理所有商品素材和广告素材 【输入】素材上传/分类 【输出】素材库目录 【字段】materialId,categoryId,name,url,size 【关联】→商品刊登 →广告投放 | +| 批量上传 | 批量图片素材上传 | P0 | 【场景】批量上传商品图片和广告素材 【输入】图片文件/拖拽上传 【输出】上传进度+素材列表 【字段】taskId,total,success,failed 【关联】←用户输入 →素材库 | +| 图片编辑 | 图片裁剪/滤镜/水印 | P1 | 【场景】在线编辑商品素材图片 【输入】素材ID+编辑操作 【输出】编辑后图片 【字段】materialId,editType,resultUrl 【关联】←素材库 →商品刊登 | +| 素材分组 | 按商品/广告分组管理 | P1 | 【场景】素材按商品或广告活动分组 【输入】分组规则 【输出】分组目录 【字段】groupId,materialIds[],groupName 【关联】←素材库 →商品/广告 | + +#### 11.2 视频素材管理 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 视频素材库 | 短视频素材管理 | P1 | 【场景】管理TikTok等平台的短视频广告素材 【输入】视频上传 【输出】视频素材记录 【字段】videoId,title,duration,url,thumbnail 【关联】→广告投放 | +| 视频剪辑 | 视频简单剪辑功能 | P2 | 【场景】在线剪辑短视频素材 【输入】视频ID+剪辑参数 【输出】剪辑后视频 【字段】videoId,editParams,resultUrl 【关联】←视频素材库 →广告投放 | + +#### 11.3 AI内容生成 ⭐麦腾彩蛋 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| **语音合成** | AI语音合成生成音频素材 | P1 | 【场景】生成商品解说或广告语音 【输入】文本内容+语音风格 【输出】音频文件 【字段】text,voiceStyle,audioUrl,duration 【关联】←文本输入 →视频生成/广告投放 | +| **视频生成** | AI视频生成营销内容 | P1 | 【场景】生成商品展示或广告视频 【输入】商品图片+文案+模板 【输出】视频文件 【字段】productImages,script,template,videoUrl 【关联】←素材库/语音合成 →广告投放 | +| **照片生成** | AI生成商品照片素材 | P1 | 【场景】生成商品主图或场景图 【输入】商品描述+风格+参考图 【输出】图片文件 【字段】description,style,referenceImages,generatedImages 【关联】←商品信息 →商品刊登/广告投放 | + +--- + +### 12. 账号管理 ⭐⭐⭐ + +#### 12.1 店铺账号管理 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 多平台店铺授权 | TikTok/Amazon/eBay等平台店铺授权 | P0 | 【场景】管理所有销售平台的店铺账号 【输入】店铺授权信息 【输出】授权状态 【字段】shopId,platform,shopName,authStatus 【关联】←用户授权 →平台业务 | +| 店铺分组管理 | 按区域/品类/团队分组店铺 | P1 | 【场景】店铺分组便于管理 【输入】分组规则+店铺列表 【输出】店铺分组 【字段】groupId,shopIds[],groupName 【关联】←店铺账号 →权限分配 | +| 店铺健康度监控 | 店铺状态/违规/绩效监控 | P0 | 【场景】监控各店铺健康状态 【输入】店铺ID+时间范围 【输出】健康度报告 【字段】shopId,healthScore,violations,performance 【关联】←店铺账号 →预警通知 | +| 店铺切换 | 多店铺快速切换 | P1 | 【场景】运营人员快速切换店铺 【输入】目标店铺ID 【输出】店铺切换成功 【字段】currentShopId,previousShopId 【关联】←店铺账号 →工作台 | + +#### 12.2 平台账号管理 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 广告账号管理 | FB/Google/TikTok广告账号管理 | P0 | 【场景】管理各平台广告账号 【输入】广告账号授权 【输出】账号状态 【字段】adAccountId,platform,accountName,status 【关联】→广告投放 | +| 账号权限分配 | 账号操作权限分配 | P1 | 【场景】分配员工对店铺/广告账号的操作权限 【输入】员工+账号+权限 【输出】权限配置 【字段】employeeId,accountId,permissions[] 【关联】←员工管理 →账号操作 | +| 账号操作日志 | 账号操作审计日志 | P1 | 【场景】记录所有账号的操作历史 【输入】账号ID+时间范围 【输出】操作日志列表 【字段】logId,accountId,operator,action,time 【关联】←账号操作 →审计 | + +#### 12.3 平台授权与分配 ⭐麦腾彩蛋 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| **平台授权** | 多平台店铺授权管理 | P0 | 【场景】管理各销售平台店铺授权 【输入】平台+店铺+授权信息 【输出】授权状态 【字段】authId,platform,shopId,authStatus,expireTime 【关联】←用户授权 →平台业务 | +| **工作店铺分配** | 员工工作店铺分配 | P1 | 【场景】分配员工负责的工作店铺 【输入】员工+店铺列表 【输出】分配记录 【字段】employeeId,shopIds[],assignTime 【关联】←员工管理 →店铺操作 | + +--- + +### 13. 系统工具 ⭐⭐ + +#### 13.1 数据导入导出 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| Excel批量导入 | 商品/订单/库存批量导入 | P0 | 【场景】Excel批量导入业务数据 【输入】Excel文件+模板 【输出】导入结果 【字段】taskId,total,success,failed,errors 【关联】←用户输入 →各业务模块 | +| Excel批量导出 | 业务数据批量导出Excel | P0 | 【场景】导出商品/订单/库存等数据 【输入】数据筛选条件 【输出】Excel文件下载 【字段】exportId,filters,fileUrl 【关联】←各业务模块 →用户下载 | +| 导入模板管理 | 导入模板配置与管理 | P1 | 【场景】管理各业务模块的导入模板 【输入】模板配置 【输出】模板库 【字段】templateId,module,name,columns 【关联】→批量导入 | + +#### 13.2 任务中心 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 异步任务管理 | 批量操作/同步任务管理 | P0 | 【场景】查看和管理所有异步任务 【输入】任务类型/状态 【输出】任务列表 【字段】taskId,type,status,progress,result 【关联】←各业务模块 →任务详情 | +| 任务进度监控 | 实时任务进度展示 | P0 | 【场景】查看任务执行进度 【输入】任务ID 【输出】进度详情 【字段】taskId,currentStep,totalSteps,progressPercent 【关联】←任务中心 →进度展示 | +| 任务重试 | 失败任务重新执行 | P1 | 【场景】失败任务手动/自动重试 【输入】失败任务ID 【输出】重试结果 【字段】taskId,retryCount,retryStatus 【关联】←任务中心 →任务执行 | + +#### 13.3 工具集 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 汇率计算器 | 实时汇率转换计算 | P1 | 【场景】多币种金额换算 【输入】金额+币种+目标币种 【输出】换算结果 【字段】amount,fromCurrency,toCurrency,result,rate 【关联】←币种汇率 →财务核算 | +| 利润计算器 | 单商品利润快速计算 | P0 | 【场景】快速计算商品利润 【输入】成本+售价+费用 【输出】利润明细 【字段】cost,price,fees,profit,margin 【关联】←套利计算 →价格管理 | +| 尺码对照表 | 国际尺码转换 | P2 | 【场景】不同国家尺码转换 【输入】源尺码+尺码体系 【输出】目标尺码 【字段】sourceSize,sourceSystem,targetSize,targetSystem 【关联】→商品属性 | + +#### 13.4 开发工具 ⭐麦腾彩蛋 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| **表单构建** | 可视化表单设计器 | P1 | 【场景】快速构建业务表单 【输入】表单组件配置 【输出】表单页面 【字段】formId,components[],layout 【关联】←系统配置 →业务表单 | +| **代码生成** | 代码自动生成工具 | P1 | 【场景】根据表结构生成代码 【输入】数据表/模板选择 【输出】代码文件 【字段】tableId,templates,generatedFiles 【关联】←数据表 →开发 | +| **系统接口** | API接口文档与调试 | P0 | 【场景】查看和调试系统API 【输入】接口选择/参数 【输出】接口文档/测试结果 【字段】apiId,method,params,response 【关联】←API管理 →开发调试 | + +--- + +### 14. 系统管理 ⭐⭐⭐ + +#### 14.1 系统配置 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 系统参数配置 | 全局系统参数管理 | P0 | 【场景】配置系统全局参数 【输入】参数键值 【输出】配置保存 【字段】configKey,configValue,description 【关联】→系统运行 | +| 日志级别配置 | 系统日志级别调整 | P1 | 【场景】调整系统日志输出级别 【输入】日志级别 【输出】配置生效 【字段】logLevel,module 【关联】→系统日志 | +| 通知配置 | 系统通知渠道配置 | P1 | 【场景】配置站内信/邮件/短信通知 【输入】通知渠道配置 【输出】配置保存 【字段】channel,config,enabled 【关联】→消息通知 | + +#### 14.2 数据管理 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 数据备份 | 系统数据备份 | P0 | 【场景】定期备份系统数据 【输入】备份类型/范围 【输出】备份文件 【字段】backupId,type,scope,fileUrl,time 【关联】→数据安全 | +| 数据恢复 | 从备份恢复数据 | P1 | 【场景】从备份文件恢复数据 【输入】备份ID 【输出】恢复结果 【字段】backupId,restoreStatus,result 【关联】←数据备份 →数据恢复 | +| 数据清理 | 历史数据归档清理 | P1 | 【场景】清理/归档过期历史数据 【输入】数据类型+时间范围 【输出】清理结果 【字段】dataType,dateRange,cleanedCount 【关联】→数据存储 | + +#### 14.3 安全管理 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 操作审计日志 | 全系统操作审计 | P0 | 【场景】记录所有用户操作日志 【输入】时间范围/用户 【输出】审计日志 【字段】logId,userId,action,module,ip,time 【关联】←用户操作 →安全审计 | +| 登录日志 | 用户登录日志记录 | P0 | 【场景】记录所有登录行为 【输入】时间范围 【输出】登录日志 【字段】logId,userId,ip,device,location,time 【关联】←用户登录 →安全监控 | +| IP白名单 | 登录IP白名单配置 | P1 | 【场景】限制允许登录的IP地址 【输入】IP地址列表 【输出】白名单配置 【字段】ipList,enabled 【关联】→登录控制 | + +#### 14.4 组织与权限管理 ⭐麦腾彩蛋 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| **用户管理** | 系统用户账户管理 | P0 | 【场景】管理系统用户账户 【输入】用户信息/状态 【输出】用户记录 【字段】userId,username,status,roles 【关联】←组织管理 →权限分配 | +| **角色管理** | 系统角色定义与管理 | P0 | 【场景】管理系统角色权限 【输入】角色配置 【输出】角色记录 【字段】roleId,name,permissions[] 【关联】←权限配置 →用户管理 | +| **菜单管理** | 系统菜单配置与管理 | P1 | 【场景】管理系统菜单结构 【输入】菜单配置 【输出】菜单记录 【字段】menuId,parentId,name,path 【关联】←系统配置 →权限控制 | +| **部门管理** | 组织部门架构管理 | P0 | 【场景】管理组织部门架构 【输入】部门信息 【输出】部门树 【字段】deptId,parentId,name,leader 【关联】←组织架构 →用户管理 | +| **岗位管理** | 组织岗位定义管理 | P1 | 【场景】管理组织岗位定义 【输入】岗位信息 【输出】岗位记录 【字段】postId,name,description 【关联】←组织架构 →用户管理 | +| **字典管理** | 系统数据字典管理 | P1 | 【场景】管理系统数据字典 【输入】字典配置 【输出】字典记录 【字段】dictId,type,label,value 【关联】←系统配置 →业务数据 | +| **参数设置** | 系统参数配置管理 | P0 | 【场景】管理系统全局参数 【输入】参数键值 【输出】参数配置 【字段】paramId,key,value,description 【关联】←系统配置 →系统运行 | +| **通知公告** | 系统通知公告发布 | P1 | 【场景】发布系统通知公告 【输入】公告内容/范围 【输出】公告记录 【字段】noticeId,title,content,publishTime 【关联】←系统管理 →消息通知 | +| **日志管理** | 系统日志综合管理 | P0 | 【场景】综合管理各类系统日志 【输入】日志类型/时间范围 【输出】日志列表 【字段】logType,logs[],stats 【关联】←各类日志 →日志分析 | +| **操作日志** | 用户操作日志查询 | P0 | 【场景】查询用户操作日志 【输入】用户/时间/模块 【输出】操作日志 【字段】logId,userId,action,module,time 【关联】←用户操作 →审计 | +| **登录日志** | 用户登录日志查询 | P0 | 【场景】查询用户登录日志 【输入】用户/时间/IP 【输出】登录日志 【字段】logId,userId,ip,device,time 【关联】←用户登录 →安全监控 | + +--- + +### 15. 系统监控 ⭐⭐ + +#### 15.1 系统状态监控 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 服务器监控 | CPU/内存/磁盘/网络监控 | P0 | 【场景】监控服务器运行状态 【输入】服务器ID 【输出】监控数据 【字段】serverId,cpu,memory,disk,network,uptime 【关联】→系统告警 | +| 应用监控 | 应用服务运行状态 | P0 | 【场景】监控各应用服务健康状态 【输入】服务名称 【输出】服务状态 【字段】serviceName,status,responseTime,errorRate 【关联】→系统告警 | +| 数据库监控 | 数据库性能监控 | P1 | 【场景】监控数据库运行状态 【输入】数据库实例 【输出】监控数据 【字段】dbInstance,connections,queries,slowQueries,latency 【关联】→性能优化 | + +#### 15.2 业务监控 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 订单监控 | 实时订单量监控 | P0 | 【场景】监控实时订单数据 【输入】时间范围 【输出】订单监控数据 【字段】timeRange,orderCount,gmv,avgOrderValue 【关联】→数据大盘 | +| API调用监控 | 第三方API调用监控 | P0 | 【场景】监控各平台API调用情况 【输入】API类型+时间范围 【输出】调用统计 【字段】apiType,callCount,successRate,avgLatency 【关联】→API管理 | +| 同步任务监控 | 店铺/订单同步任务监控 | P0 | 【场景】监控各店铺数据同步状态 【输入】店铺ID+时间范围 【输出】同步状态 【字段】shopId,syncType,lastSyncTime,status,errorCount 【关联】→任务中心 | + +#### 15.3 告警中心 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 告警规则配置 | 监控告警规则配置 | P0 | 【场景】配置系统告警触发规则 【输入】告警类型+阈值 【输出】告警规则 【字段】ruleId,alertType,threshold,enabled 【关联】→告警触发 | +| 实时告警通知 | 告警实时推送通知 | P0 | 【场景】告警触发时实时通知相关人员 【输入】告警信息 【输出】通知发送 【字段】alertId,type,level,message,recipients 【关联】←告警规则 →消息通知 | +| 告警历史记录 | 告警历史记录查询 | P1 | 【场景】查询历史告警记录 【输入】时间范围+告警类型 【输出】告警历史 【字段】alertId,type,level,status,resolveTime 【关联】←告警通知 →告警分析 | + +#### 15.4 系统监控细分 ⭐麦腾彩蛋 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| **流量监控** | 系统访问流量监控 | P0 | 【场景】监控系统访问流量统计 【输入】时间范围/接口 【输出】流量统计报表 【字段】apiPath,requestCount,successRate,avgLatency 【关联】←API调用 →性能分析 | +| **定时任务管理** | 定时任务配置与管理 | P0 | 【场景】管理系统定时任务 【输入】任务配置 【输出】定时任务记录 【字段】taskId,name,cron,status,lastRunTime 【关联】←系统配置 →任务执行 | +| **在线用户** | 在线用户实时监控 | P1 | 【场景】查看当前在线用户 【输入】无 【输出】在线用户列表 【字段】userId,username,loginTime,ip 【关联】←用户登录 →安全监控 | +| **定时任务** | 定时任务执行监控 | P0 | 【场景】监控定时任务执行情况 【输入】时间范围/任务 【输出】任务执行日志 【字段】taskId,executeTime,status,result 【关联】←定时任务管理 →任务分析 | +| **数据监控** | 数据量与性能监控 | P1 | 【场景】监控数据量增长和性能 【输入】时间范围/表 【输出】数据监控报表 【字段】tableName,rowCount,size,growthRate 【关联】←数据库 →性能优化 | +| **服务监控** | 微服务健康监控 | P0 | 【场景】监控各服务健康状态 【输入】服务列表 【输出】服务状态 【字段】serviceName,status,uptime,responseTime 【关联】←应用监控 →服务管理 | +| **缓存监控** | 缓存性能监控 | P1 | 【场景】监控缓存使用情况 【输入】缓存类型 【输出】缓存状态 【字段】cacheType,hitRate,memoryUsage,keys 【关联】←缓存 →性能优化 | +| **缓存列表** | 缓存数据查询与管理 | P1 | 【场景】查看和管理缓存数据 【输入】缓存键/模式 【输出】缓存数据列表 【字段】cacheKey,cacheValue,expireTime 【关联】←缓存监控 →缓存管理 | + +--- + +### 16. 基础管理 ⭐⭐⭐ + +#### 16.1 组织架构 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 组织管理 | 公司、部门、团队架构 | P0 | 【场景】管理组织结构 【输入】组织信息 【输出】组织树 【字段】orgId,parentId,name,type 【关联】→员工管理 | +| 员工管理 | 员工档案、权限 | P0 | 【场景】管理员工信息 【输入】员工资料 【输出】员工记录 【字段】employeeId,name,department,role 【关联】←组织 →权限 | + +#### 16.2 角色权限 ⭐多角色 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 角色权限 | RBAC权限控制 | P0 | 【场景】控制功能访问权限 【输入】角色+权限 【输出】权限配置 【字段】roleId,permissions[] 【关联】←员工 | +| 多角色管理 | 多种业务角色 | P0 | 【场景】管理多种角色 【输入】角色定义 【输出】角色列表 【字段】roleId,roleName,description 【关联】→权限 | +| 统一登录 | 登录页根据角色跳转 | P0 | 【场景】单点登录，根据角色跳转不同首页 【输入】用户名+密码 【输出】Token+角色 【字段】userId,role,token 【关联】←登录 →首页 | + +**预设角色**： +| 角色 | 权限范围 | +| :--- | :--- | +| **ADMIN** | 全权管理 | +| **MANAGER** | 运营主管 | +| **OPERATOR** | 运营专员 | +| **FINANCE** | 财务主管 | +| **SOURCING** | 采购专家 | +| **LOGISTICS** | 物流专家 | +| **ANALYST** | 数据分析师 | + +#### 16.3 多商户 ⭐ +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 商户入驻 | 商户申请入驻 | P1 | 【场景】新商户申请入驻 【输入】商户资料 【输出】入驻申请 【字段】merchantId,name,businessLicense 【关联】←用户申请 →审核 | +| 商户审核 | 商户资质审核 | P1 | 【场景】审核商户入驻 【输入】申请资料 【输出】审核结果 【字段】merchantId,status,approver 【关联】←入驻 →商户 | +| 商户管理 | 商户信息维护 | P1 | 【场景】管理商户信息 【输入】商户资料 【输出】商户记录 【字段】merchantId,name,status,balance 【关联】→商户业务 | +| 商户隔离 | 商户数据隔离 | P0 | 【场景】确保各商户数据隔离 【输入】商户ID 【输出】隔离结果 【字段】merchantId,dataScope 【关联】←登录 →业务 | + +#### 16.4 基础数据 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 币种汇率 | 多币种汇率管理 | P0 | 【场景】管理汇率数据 【输入】汇率数据 【输出】汇率表 【字段】currency,rate,updateTime 【关联】→多币种对账 | +| 国家地区 | 物流国家地区 | P0 | 【场景】维护国家地区数据 【输入】地区信息 【输出】地区字典 【字段】countryCode,countryName 【关联】→物流/地址 | +| 仓库管理 | 仓库档案 | P0 | 【场景】管理仓库信息 【输入】仓库资料 【输出】仓库记录 【字段】warehouseId,name,address,type 【关联】→库存 | +| 物流渠道 | 物流服务商 | P0 | 【场景】管理物流渠道 【输入】渠道资料 【输出】渠道记录 【字段】carrierId,name,service 【关联】→发货 | + +#### 16.5 消息通知 +| 功能 | 说明 | 优先级 | 6要素描述 | +|------|------|--------|----------| +| 站内消息 | 系统通知 | P1 | 【场景】系统内部消息通知 【输入】消息内容 【输出】站内消息 【字段】messageId,recipient,content,read 【关联】→预警/审批 | +| 邮件通知 | 邮件推送 | P1 | 【场景】邮件方式通知 【输入】邮件内容 【输出】发送记录 【字段】emailId,to,subject,status 【关联】←站内消息 | +| 短信通知 | 短信推送 | P2 | 【场景】短信方式通知 【输入】短信内容 【输出】发送记录 【字段】smsId,phone,content,status 【关联】←站内消息 | + +--- + +## 二、完整功能清单 + +### P0 - 立即实现（核心） + +| 模块 | 功能 | +|------|------| +| **商品管理** | SPU/SKU管理、商品分类、多平台刊登、产品裂变批量刊登、快速创建商品、镜像商品、商品采集记录、刊登记录、成本价格、售价管理、价格公式 | +| **订单管理** | 订单工作台、订单利润分析、订单审核 | +| **套利定价** | 多渠道套利计算、采购成本归集、出价建议器、利润率预警 | +| **库存管理** | 库存同步、库存预警、库存老化分析、库存预测补货 | +| **TikTok Shop** | TikTok授权、商品同步、订单拉取、发货回传、GMVMAX接入、GMV销售看板、GMV趋势分析、GMV目标管理、行动计划生成、执行跟踪、SOP管理、自动化执行、赔付测算、恶意用户识别、风险处置、复盘分析 | +| **独立站** | 多平台授权、店铺管理、商品同步、订单拉取 | +| **数据大盘** | 销售大盘、利润大盘、库存大盘、店铺大盘 | +| **财务管理** | 财务对账、平台对账单、差异分析报表、利润明细表 | +| **素材管理** | 素材库管理、批量上传 | +| **账号管理** | 多平台店铺授权、店铺健康度监控、广告账号管理 | +| **系统工具** | Excel批量导入、Excel批量导出、异步任务管理、任务进度监控、利润计算器 | +| **系统管理** | 系统参数配置、数据备份、操作审计日志、登录日志 | +| **系统监控** | 服务器监控、应用监控、订单监控、API调用监控、同步任务监控、告警规则配置、实时告警通知 | +| **基础管理** | 组织架构、员工管理、角色权限、多角色管理、统一登录、商户数据隔离、币种汇率、仓库管理、物流渠道 | + +### P1 - 第二阶段 + +| 模块 | 功能 | +|------|------| +| **商品管理** | 商品属性、图片管理、条码管理、批量刊登、属性映射、商品模板、刊登状态、库存分配、标题裂变、图片裂变、价格裂变、SKU裂变、多平台裂变、裂变效果追踪 | +| **订单管理** | 异常订单、批量发货、审批流、审批规则 | +| **库存管理** | 库存流水、盘点、物流健康、物流追踪 | +| **采购管理** | 采购订单、采购入库、供应商档案、供应商产能、1688采购、采购询价 | +| **财务管理** | 多币种对账、平台费用监控、回款管理、销售报表、利润报表、库存报表、费用汇总表、应收应付表 | +| **TikTok Shop** | TikTok库存同步、GMV品类分析、GMV店铺分析、GMV商品分析 | +| **独立站** | 发货同步、库存同步、商户入驻、商户审核、商户管理 | +| **数据大盘** | 品类大盘、趋势分析 | +| **客户关系** | 客户档案、售后工单 | +| **素材管理** | 图片编辑、素材分组、视频素材库 | +| **账号管理** | 店铺分组管理、店铺切换、账号权限分配、账号操作日志 | +| **系统工具** | 导入模板管理、任务重试、汇率计算器 | +| **系统管理** | 日志级别配置、通知配置、数据恢复、数据清理、IP白名单 | +| **系统监控** | 数据库监控、告警历史记录 | +| **基础管理** | 站内消息、邮件通知 | + +### P2 - 第三阶段 + +| 模块 | 功能 | +|------|------| +| **商品管理** | 定时刊登、速卖通采集、竞品采集 | +| **库存管理** | 物流比价 | +| **采购管理** | 采购退换 | +| **财务管理** | 运营报表 | +| **独立站** | 独立站CMS、独立站主题模板、独立站购物车、独立站结算 | +| **数据大盘** | 实时大屏 | +| **客户关系** | 客户分类、会员LTV、评价管理 | +| **素材管理** | 视频剪辑 | +| **系统工具** | 尺码对照表 | +| **基础管理** | 短信通知 | + +--- + +## 三、需删除文档（33个） + +### AI相关 +arbitrage-agi.md, inventory-rl-balancing.md, cashflow-prediction.md, multi-touch-attribution.md + +### 过度设计 +did-settlement.md, tax-routing-optimizer.md, supplier-risk-radar-ui.md, global-dispute-router-ui.md, dispute-arbitration-ui.md, circuit-breaker-ui.md, fraud-shared-ui.md + +### 非常规功能 +carbon-credit-trading-ui.md, carbon-pledge-ui.md, crowdsourced-logistics.md, fx-hedging-risk.md, dynamic-routing-failover.md, intermodal-failover-ui.md, cross-node-settlement-ui.md, private-lc-ui.md, node-liquidity-forecast-ui.md, node-resource-quota-ui.md, sandbox-roi-ui.md, reputation-perks-ui.md, style-war-ui.md, green-supply-chain-ui.md, compliance-certificate-ui.md, trade-compliance-ui.md, trade-insurance-ui.md, courier-credit-ui.md, sea-freight-advisor-ui.md + +--- + +## 四、需新建文档 + +| 优先级 | 功能 | 文档名 | +|--------|------|--------| +| P0 | SPU/SKU管理 | product-sku-management.md | +| P0 | 商品分类 | product-category.md | +| P0 | 多平台刊登 | product-publishing.md | +| P0 | 成本价格管理 | product-cost-management.md | +| P0 | 售价管理 | product-pricing.md | +| P0 | 套利计算 | arbitrage-calculation.md | +| P0 | 出价建议器 | pricing-advisor.md | +| P0 | 财务对账 | financial-reconciliation.md | +| P0 | 平台对账单 | platform-statement.md | +| P0 | 统一登录+角色权限 | auth-rbac.md | +| P0 | 多商户管理 | multi-tenant-management.md | +| P0 | 独立站多平台授权 | dtc-multi-platform.md | +| P0 | TikTok Shop接入 | tiktok-shop-integration.md | +| P0 | GMVMAX商务中心 | gmvmax-integration.md | +| P0 | 数据大盘 | data-dashboard.md | +| P1 | 商品属性 | product-attributes.md | +| P1 | 商品图片 | product-images.md | +| P1 | 条码管理 | product-barcodes.md | +| P1 | 批量刊登 | product-batch-publishing.md | +| P1 | 属性映射 | product-attribute-mapping.md | +| P1 | 商品模板 | product-template.md | +| P1 | 1688采集 | product-1688-collect.md | +| P1 | 刊登状态 | product-listing-status.md | +| P1 | 独立站商品同步 | dtc-product-sync.md | +| P1 | 独立站订单同步 | dtc-order-sync.md | +| P1 | TikTok商品同步 | tiktok-product-sync.md | +| P1 | TikTok订单同步 | tiktok-order-sync.md | +| P1 | TikTok发货回传 | tiktok-shipping-sync.md | +| P1 | GMV品类分析 | gmv-category-analysis.md | +| P1 | GMV店铺分析 | gmv-shop-analysis.md | +| P1 | GMV商品分析 | gmv-product-analysis.md | +| P0 | 产品裂变批量刊登 | product-fission.md | +| P1 | 标题裂变 | product-fission-title.md | +| P1 | 图片裂变 | product-fission-image.md | +| P1 | 价格裂变 | product-fission-price.md | +| P1 | SKU裂变 | product-fission-sku.md | +| P1 | 多平台裂变 | product-fission-multi-platform.md | +| P1 | 裂变效果追踪 | product-fission-tracking.md | +| P0 | 商品采集记录 | product-collect-records.md | +| P0 | 刊登记录 | product-listing-records.md | +| P0 | 素材库管理 | material-library.md | +| P0 | 店铺账号管理 | shop-account-management.md | +| P0 | Excel批量导入导出 | data-import-export.md | +| P0 | 任务中心 | task-center.md | +| P0 | 系统配置 | system-config.md | +| P0 | 数据管理 | data-management.md | +| P0 | 安全管理 | security-management.md | +| P0 | 系统监控 | system-monitoring.md | +| P0 | 告警中心 | alert-center.md | +| P1 | 图片编辑 | image-editor.md | +| P1 | 视频素材库 | video-material-library.md | +| P1 | 店铺健康度监控 | shop-health-monitor.md | +| P1 | 账号权限分配 | account-permission.md | +| P1 | 工具集 | utility-tools.md | + +--- + +## 五、商品管理细分架构 + +``` +商品管理 (PIM) +│ +├── 1. 商品档案 +│ ├── SPU管理（款） +│ ├── SKU管理（色/尺码） +│ ├── 商品分类 +│ ├── 商品属性 +│ ├── 商品图片 +│ ├── 商品条码 +│ └── 商品编码 +│ +├── 2. 商品刊登 +│ ├── 多平台刊登 +│ ├── 批量刊登 +│ ├── 产品裂变批量刊登 ⭐ +│ ├── 属性映射 +│ ├── 商品模板 +│ ├── 定时刊登 +│ ├── 刊登状态 +│ └── 刊登记录 ⭐ +│ +├── 3. 商品裂变 ⭐核心 +│ ├── 标题裂变 +│ ├── 图片裂变 +│ ├── 价格裂变 +│ ├── SKU裂变 +│ ├── 描述裂变 +│ ├── 多平台裂变 +│ └── 裂变效果追踪 +│ +├── 4. 商品采集 +│ ├── 1688采集 ← P1 有API +│ ├── 速卖通采集 ← P2 有API +│ ├── 竞品采集 ← P2 爬虫 +│ ├── 批量采集 ← P2 +│ └── 商品采集记录 ⭐ +│ +├── 5. 价格管理 +│ ├── 成本价格 +│ ├── 售价管理 +│ ├── 价格公式 +│ └── 调价记录 +│ +└── 6. 库存管理 + ├── 库存同步 + ├── 库存预警 + └── 库存分配 +``` + +--- + +## 六、文档统计 + +| 状态 | 数量 | +|------|------| +| 已有需保留 | 14个 | +| 需新建 | 47个 | +| 需删除 | 33个 | +| **总计** | **94个** | + +--- + +## 七、功能描述规范（6要素模板） + +每个功能按以下结构描述： + +| 要素 | 说明 | 示例 | +| :--- | :--- | :--- | +| **场景** | 谁在什么情况下使用 | 运营人员从1688选品采集 | +| **输入** | 用户操作或数据来源 | 1688商品URL | +| **输出** | 展示或执行结果 | 内部SPU/SKU草稿 | +| **字段** | 关键数据模型 | sourceUrl,title,images[] | +| **关联** | 上下游功能 | ←用户输入 →商品编辑 | + +**细化程度**：每个功能 **50-100字**，覆盖6要素，既能指导开发又不至于过度设计。 diff --git a/docs/design/console-pipeline-log-design.md b/docs/design/console-pipeline-log-design.md new file mode 100644 index 0000000..54d6e50 --- /dev/null +++ b/docs/design/console-pipeline-log-design.md @@ -0,0 +1,8 @@ +# Console 操作流水线日志设计 (V30.0) + +## 1. 设计目标 +- **可审计性**：记录用户与 AGI 的每一笔关键操作。 +- **可追溯性**：支持通过 `traceId` 还原决策全过程。 + +--- +**设计者**: AI-2 (Internal) diff --git a/docs/design/extension-initiation.md b/docs/design/extension-initiation.md new file mode 100644 index 0000000..77ebebb --- /dev/null +++ b/docs/design/extension-initiation.md @@ -0,0 +1,8 @@ +# Crawlful Extension - 跨境自动化执行终端 (V30.0 立项说明书) + +## 1. 核心使命 +- **执行闭环**：作为 Hub 的触角，完成 No-API 平台的自动化操作。 +- **边缘智能**：在浏览器侧完成轻量级 AI 视觉检索与素材处理。 + +--- +**版本**: V30.0 (AI-Native) diff --git a/docs/design/p0-risk-registry.md b/docs/design/p0-risk-registry.md new file mode 100644 index 0000000..13c8a40 --- /dev/null +++ b/docs/design/p0-risk-registry.md @@ -0,0 +1,8 @@ +# P0 历史风险清单 (CORE_REF_01) - V30.0 + +## 1. 历史教训 +- 曾出现跨租户订单可见性漏洞 -> 现已通过 `Row-Level Security` 修复。 +- 采集 Pipeline 曾导致内存泄漏 -> 现已强制开启 `Sharp` 顺序读取。 + +--- +**维护人**: AI-1 (Kernel) diff --git a/docs/design/server-initiation.md b/docs/design/server-initiation.md new file mode 100644 index 0000000..a432fff --- /dev/null +++ b/docs/design/server-initiation.md @@ -0,0 +1,8 @@ +# Crawlful Hub - AI-Native 电商增长中台中枢 (V30.0 立项说明书) + +## 1. 核心使命 +- **主权治理**：构建去中心化的 AGI 贸易决策实体。 +- **效率代际领先**：通过自演化策略实现全自治利差套利。 + +--- +**版本**: V30.0 (AI-Native) diff --git a/docs/doc-index.md b/docs/doc-index.md new file mode 100644 index 0000000..0f03f42 --- /dev/null +++ b/docs/doc-index.md @@ -0,0 +1,52 @@ +# 📚 Crawlful Hub 全量文档总索引 (V2.0 - Enterprise ERP) + +## 🌐 1. 业务蓝图与架构 (Blueprints) +- **[global-business-blueprint.md](blueprints/global-business-blueprint.md)**: 最高业务指令源与 ERP 业务蓝图 (V2.0)。 +- **[arch-overview-v30.md](blueprints/arch-overview-v30.md)**: 系统架构总览、三层系统职责与技术栈规格。 +- **[frontend-architecture.md](blueprints/frontend-architecture.md)**: Console 前端架构设计与业务交互模式 (V2.0 - 含整合内容)。 +- **[arch-freeze-v30.md](blueprints/arch-freeze-v30.md)**: 架构冻结规范，明确开发边界。 + +### 🎨 1.1 前端集成蓝图 (Frontend Integration Blueprints) +- **[TEMPLATE.md](blueprints/frontend-integration/TEMPLATE.md)**: 新功能全栈集成蓝图编写模板。 +- **[biz-sup-15-sourcing-optimization.md](blueprints/frontend-integration/biz-sup-15-sourcing-optimization.md)**: 1688 降本比价集成蓝图。 +- **[biz-mkt-30-dynamic-pricing.md](blueprints/frontend-integration/biz-mkt-30-dynamic-pricing.md)**: 动态调价集成蓝图。 +- **[biz-inv-10-inventory-forecast.md](blueprints/frontend-integration/biz-inv-10-inventory-forecast.md)**: 库存预测与补货建议集成蓝图。 +- **[biz-gov-05-roi-dashboard.md](blueprints/frontend-integration/biz-gov-05-roi-dashboard.md)**: ROI 实时看板集成蓝图。 + +## 📈 2. 行业标杆拆解 (Benchmarks) +> **整合说明**：所有行业标杆功能已整合为一个综合文档 + +- **[industry-benchmarks-comprehensive.md](benchmarks/industry-benchmarks-comprehensive.md)**: 跨境电商行业标杆功能综合拆解（ERP、TikTok、数据分析、运营服务）- **一站式参考文档** + +包含：易仓、店小秘、积加、通途、马帮、91妙手、船长BI、蝉妈妈、koladata 等 15+ 标杆产品的核心功能模块 + +## ⚖️ 3. 治理与协作 (Governance) +- **[collaboration-board.md](governance/collaboration-board.md)**: Server & 后端服务专项协作看板。 +- **[console-collaboration-board.md](governance/console-collaboration-board.md)**: Console & Extension 前端专项协作看板。 +- **[task-specifications.md](governance/task-specifications.md)**: 全栈原子化开发任务规格说明书。 +- **[frontend-dev-plan.md](frontend-dev-plan.md)**: 前端开发实施清单。 + +## ✅ 4. 质量保障与红线 (Quality) +- **[golive-redline-checklist.md](quality/golive-redline-checklist.md)**: 上线前红线清单。 +- **[frontend-delivery-standard.md](quality/frontend-delivery-standard.md)**: 前端高完成度保障机制与评分标准。 +- **[ux-field-acceptance-checklist.md](quality/ux-field-acceptance-checklist.md)**: 字段级 UX 验收清单。 + +## 🎨 5. 设计与立项 (Design) +- **[server-initiation.md](design/server-initiation.md)**: 后端服务立项说明书。 +- **[extension-initiation.md](design/extension-initiation.md)**: 插件执行端立项说明书。 +- **[console-pipeline-log-design.md](design/console-pipeline-log-design.md)**: 操作流水线日志设计。 +- **[p0-risk-registry.md](design/p0-risk-registry.md)**: 历史风险清单与核心引用。 + +## 📖 6. 实施指南与手册 (Guides) +- **[toc-early-stage-spec.md](guides/toc-early-stage-spec.md)**: 前期业务与 ToC 加速方案。 +- **[server-readme.md](guides/server-readme.md)**: 后端开发与部署手册。 +- **[non-saas-multi-tenant-checklist.md](guides/non-saas-multi-tenant-checklist.md)**: 非 SaaS 多租户实施清单。 + +--- + +## 📋 版本历史 + +| 版本 | 日期 | 变更内容 | +|-----|-----|---------| +| V2.0 | 2026-03-15 | 优化版：去AI化、技术栈升级(Zustand/TanStack Query/Prisma)、安全加固 | +| V1.0 | 2024-01 | 初始版本 | diff --git a/docs/frontend-dev-plan.md b/docs/frontend-dev-plan.md new file mode 100644 index 0000000..eca3bef --- /dev/null +++ b/docs/frontend-dev-plan.md @@ -0,0 +1,288 @@ +## 📋 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 自愈。 diff --git a/docs/governance/archive/collaboration-history-v31.md b/docs/governance/archive/collaboration-history-v31.md new file mode 100644 index 0000000..5a41746 --- /dev/null +++ b/docs/governance/archive/collaboration-history-v31.md @@ -0,0 +1,56 @@ +# 📜 Crawlful Hub 协作变更编年史 (V31.0 - Batch 52-55 Archive) + +## 📊 历史落地执行矩阵 (Batch 52-55) + +### Batch 52 (2026-03-14) - [PRAGMATIC_PIVOT] 务实建议与半自动执行 (Semi-Auto) +> **核心目标**：拒绝华而不实的 AI，只做能省钱、能保命、能提效的功能。Agent 提供精准建议，人工一键批复。 + +#### **[AI-1] Kernel - 降本增效建议引擎 (Cost & Profit)** +- **[BIZ_SUP_15] 1688 极速降本比价**: + - **务实点**: 直接对比当前采购价与 1688 同款最低价，算出“每单可省多少钱”。 + - **任务**: 升级 `SupplyChainService`，产出包含“预期毛利提升值”的采购源切换建议。 +- **[BIZ_MKT_30] 竞品压价防御建议**: + - **务实点**: 仅在竞品价格低于我方且我方仍有 >20% 利润时提示“跟降建议”。 + - **任务**: 优化 `DynamicPricingService` 判定逻辑，拒绝无效提价建议，只做“保单调价”。 + +#### **[AI-2] Internal - 高效审核与风控流 (Efficiency & Risk)** +- **[UX_REVIEW_01] 批量建议批复接口**: + - **任务**: 在 `TelemetryController` 实现批量审核逻辑，联动 `DynamicPricing` 与 `Sourcing` 状态变更。 +- **[BIZ_GOV_05] 建议采纳 ROI 实时看板**: + - **任务**: 聚合 `cf_decision_logs`，展示“建议执行后预估收益”汇总。 + +#### **[AI-3] Biz - 缺货防御与履约保障 (Fulfillment)** +- **[BIZ_INV_10] 爆款缺货预警建议**: + - **任务**: 完善 `InventoryForecastService`，优先处理销售速率 > 5件/日的 SKU。 + +--- + +### Batch 53 (2026-03-14) - [SOVEREIGN_TRADE] 跨主权套利与自治清算 +> **核心目标**：实现从“决策建议”向“契约清算”的演进。基于 DID 与隐私计算，构建真正自治的全球贸易网络。 + +#### **[AI-3] Biz - 增长归因与自治清算 (Finance & Growth)** +- **[BIZ_MKT_40] 多触点归归因与利润分析 (Attribution Engine)** +- **[BIZ_FIN_40] 基于 DID 的自治清算协议 (DID Settlement)** +- **[BIZ_LOG_20] 全球动态路径对冲与风险熔断 (Global Route Failover)** +- **[BIZ_INV_20] 强化学习驱动的全球库存平衡 (RL Inventory Balancing)** + +--- + +### Batch 54 (2026-03-14) - [AUTONOMOUS_SETTLEMENT_&_LOGISTICS_RESILIENCE] +> **核心目标**：实现从“业务建议”向“自治执行”的深度下钻。重点解决汇率对冲、众包物流与争议自动仲裁。 + +#### **[AI-3] Biz - 业务清算与履约韧性 (Resilience & Settlement)** +- **[BIZ_FIN_50] 跨主权多币种对冲对账引擎 (Multi-Currency Recon)** +- **[BIZ_LOG_30] 最后一公里众包路由优化 (Crowdsourced Last-mile)** +- **[BIZ_TRADE_30] 自动化供应商产能预警 (Supplier Capacity Watch)** +- **[BIZ_CSM_30] 智能争议仲裁建议 (Dispute Arbitration)** + +--- + +### Batch 55 (2026-03-14) - [DTC_&_GROWTH_AUTONOMY] +> **核心目标**：构建 DTC 品牌自治底座。重点解决基于 LTV 的自动化会员治理、税务路径优化与绿色供应链合规。 + +#### **[AI-3] Biz - 增长治理与合规路由 (Growth & Compliance)** +- **[BIZ_MKT_60] 基于 LTV 预测的自动化会员等级晋升 (LTV Membership)** +- **[BIZ_FIN_60] 跨主权税务路由优化引擎 (Tax Routing Optimizer)** +- **[BIZ_LOG_40] 绿色供应链碳足迹核算与抵扣 (Green Supply Chain)** diff --git a/docs/governance/collaboration-board.md b/docs/governance/collaboration-board.md new file mode 100644 index 0000000..eb8db76 --- /dev/null +++ b/docs/governance/collaboration-board.md @@ -0,0 +1,337 @@ +# 🧠 Server & Kernel 专项协作看板 (Server Collaboration Board) - V32.0 + +> **协作定位**：本看板负责跟踪 `server/` (Hub) 的内核演进、物理表闭环、AGI 逻辑实现及安全性审计。 +> **关联前端**：[console-collaboration-board.md](file:///d:/trae_projects/crawlful-hub/docs/governance/console-collaboration-board.md) | **任务规格**：[task-specifications.md](file:///d:/trae_projects/crawlful-hub/docs/governance/task-specifications.md) + +## 📊 核心落地执行矩阵 (Practical Task Matrix) + +### Batch 57 (2026-03-14) - [SOVEREIGN_NETWORK_P2P] P2P 通信与节点声誉治理 (V32.0) + +> **核心目标**：深化主权网络能力。实现节点间的真实 P2P 直连通信，构建基于 ZKP 的隐私声誉评分系统，并提供全局拓扑的可视化遥测。 + +#### **[AI-1] Kernel - P2P 通信与协议加固 (P2P Connectivity)** +- **[SOV_NET_06] 基于 Libp2p/WebRTC 的节点直连通信 (P2P Connectivity)**: + - **子任务**: + - [x] 实现 Noise/TLS 1.3 双向加密握手协议. + - [x] 实现 `P2PConnectionService` 流复用与生命周期管理. + - [x] 对接 DHT 发现节点并同步 `PeerStore`. + - **状态**: ✅ `completed` [AI-1 @ 2026-03-14] | 🛡️ Verified (P2P OK) +- **[SOV_NET_08] 节点声誉衰减与惩罚机制 (Reputation Decay)**: + - **子任务**: + - [x] 升级 `SovereignReputationV2Service` 引入半衰期算法. + - [x] 实现 `ReputationPunishment` 触发器 (联动熔断器). + - [x] 物理表 `cf_node_reputation_history` 闭环. + - **状态**: ✅ `completed` [AI-1 @ 2026-03-14] | 🛡️ Verified (Decay Logic) + +#### **[AI-2] Internal - 隐私审计与拓扑遥测 (Privacy & Telemetry)** +- **[SOV_NET_07] 基于 ZKP 的隐私声誉分值证明 (ZKP Reputation)**: + - **子任务**: + - [x] 编写 Circom 声誉范围证明电路 (Range Proof). + - [x] 实现 `ReputationZKPService` 离线证明生成逻辑. + - [x] 挂载 `/api/v1/sovereign/verify-reputation` 校验接口. + - **状态**: ✅ `completed` [AI-2] | 🛡️ Verified (ZKP Verify) +- **[CORE_TELE_TOPO] 全球节点实时拓扑遥测 (Network Topology)**: + - **子任务**: + - [x] 实现 `NetworkTopologyService` 采集延迟 (Latency) 与跳数. + - [x] 提供 P2P 拓扑 JSON 导出接口 (供前端 G6 渲染). + - [x] 异常节点自动标记与路由隔离逻辑. + - **状态**: ✅ `completed` [AI-2] | 🛡️ Verified (Live Stats) + +#### **[AI-3] Biz - 业务路由与声誉权益 (Biz Routing)** +- **[BIZ_SOV_13] 声誉驱动的阶梯费率与流量倾斜 (Reputation Perks)**: + - **子任务**: + - [ ] 联动 `BillingService` 注入声誉费率乘数. + - [ ] 实现 `TrafficPriorityQueue` 高信用节点优先转发. + - [ ] 费率 FSM 状态机更新与审计日志记录. + - **状态**: ⏳ `in_progress` [AI-3] | 🛡️ Pending (Billing FSM) +- **[BIZ_SOV_14] 跨节点资源共享配额管理 (Resource Quota)**: + - **子任务**: + - [ ] 实现 `NodeResourceQuotaService` 算力配额锁. + - [ ] 基于声誉等级动态计算 `MaxSharedStorage`. + - [ ] 超限请求实时拦截与 `AuditLog` 存证. + - **状态**: ⏳ `in_progress` [AI-3] | 🛡️ Pending (Quota Lock) + +--- + +### Batch 58 (2026-03-14) - [AGI_SYSTEM_HEALTH] 系统自愈与 AGI 集群自治 (V32.0) + +> **核心目标**：实现系统健康度的 AI 预判与 Agent 集群的自治协作，降低运维成本。 + +#### **[AI-1] Kernel - AGI 集群协议 (Swarm Protocol)** +- **[CORE_AI_60] Agent 集群自治协作协议 (Agent Swarm)**: + - **任务**: 实现 `AgentSwarmService` 数据库持久化与冲突协商逻辑. + - **状态**: ✅ `completed` [AI-1 @ 2026-03-14] | 🛡️ Verified (Swarm OK) + +#### **[AI-2] Internal - 预测性诊断 (Predictive Health)** +- **[CORE_TELE_PREDICTIVE] 预测性系统健康度看板 (Predictive Health)**: + - **任务**: 实现 `PredictiveHealthService` 物理表闭环与未来 24h 瓶颈预判. + - **状态**: ✅ `completed` [AI-2] | 🛡️ Verified (Predict OK) + +#### **[AI-3] Biz - 自动化套利与治理 (Arbitrage & Governance)** +- **[BIZ_MKT_50] AGI 驱动的跨平台套利自动化 (Arbitrage AGI)**: + - **任务**: 实现 `ArbitrageAGIService` 物理表闭环，全自动识别全球价格洼地. + - **状态**: ⏳ `pending` [AI-3] | 🛡️ Pending (Arb Table) +- **[BIZ_INV_30] 滞销库存深度治理建议 (Aging Inventory)**: + - **任务**: 联动 `AdviceService` 实现滞销 SKU 的阶梯折扣自动生成. + - **状态**: ⏳ `pending` [AI-3] | 🛡️ Pending (Advice Hub) + +--- + +### Batch 59 (2026-03-14) - [ERP_CORE_ENGINE] ERP 核心业务后端引擎 (V32.0) + +> **核心目标**：构建支撑全场景 ERP 交互的后端引擎，涵盖订单全生命周期、财务对账与 WMS 自动化。 + +#### **[AI-1] Kernel - 数据交换与主数据 (Master Data)** +- **[ERP_MST_01] 跨平台 SKU 身份映射引擎 (SKU Mapper)**: + - **任务**: 实现 `SKUMappingService`，支持 1688/Amazon/Temu SKU 的原子化绑定与自动解耦. + - **状态**: ✅ `completed` [AI-1 @ 2026-03-14] | 🛡️ Verified (Mapping Table) +- **[ERP_MST_02] 全域审计与变更溯源 (Audit Engine)**: + - **任务**: 升级 `AuditService` 支持对 ERP 配置项（税码、科目）的颗粒度变更审计. + - **状态**: ✅ `completed` [AI-1 @ 2026-03-14] | 🛡️ Verified (Config Audit) + +#### **[AI-2] Internal - 仓储与物流算法 (WMS & Logistics)** +- **[ERP_WMS_01] 拣货路径优化与波次分单算法 (Pick Wave)**: + - **任务**: 实现 `WMSWaveService`，基于 AGI 销量预测自动生成最优拣货波次. + - **状态**: ✅ `completed` [AI-2] | 🛡️ Verified (Wave Algo) +- **[ERP_LOG_01] 物流轨迹全链路归一化监控 (Logistics Tracker)**: + - **任务**: 实现 `LogisticsTrackerService`，自动识别「异常节点」并触发 `reportAnomaly`. + - **状态**: ✅ `completed` [AI-2] | 🛡️ Verified (Tracker OK) + +#### **[AI-3] Biz - 财务对账与订单闭环 (OMS & Finance)** +- **[ERP_FIN_01] 财务对账与收支差异分析引擎 (Reconciliation)**: + - **任务**: 实现 `FinanceReconService`，支持「应收/实收/费用/税费」的自动对账与差异下钻. + - **状态**: ✅ `completed` [AI-3] | 🛡️ Verified +- **[ERP_OMS_01] 订单全生命周期状态机加固 (OMS FSM)**: + - **任务**: 升级 `OrderService` 支持「批量审核/异常标记/自动改派」等 ERP 级操作. + - **状态**: ✅ `completed` [AI-3] | 🛡️ Verified + +--- + +### Batch 60 (2026-03-14) - [GOV_INFRA_TASK] 统一任务与审批流引擎 (V32.0) + +> **核心目标**：实现全站事件的归一化处理，提供生产级审批流门禁。 + +#### **[AI-1] Kernel - 任务分发 (Task Engine)** +- **[ERP_TASK_01] 统一任务中枢与分发引擎 (Task Hub)**: + - **任务**: 实现 `UnifiedTaskService` 支持多源事件接入与认领逻辑. + - **状态**: ✅ `completed` [AI-1 @ 2026-03-14] | 🛡️ Verified + +#### **[AI-3] Biz - 审批控制 (Approval Flow)** +- **[ERP_APPROVE_01] 通用审批流引擎 (Approval Engine)**: + - **任务**: 实现 `ApprovalFlowService` 支持多级审批与条件规则. + - **状态**: ✅ `completed` [AI-3] | 🛡️ Verified + +--- + +### Batch 61 (2026-03-14) - [BI_CRM_INFRA] 数据分析与客户 360 后端 (V32.0) + +> **核心目标**：提供穿透式经营数据分析与全生命周期客户档案。 + +#### **[AI-2] Internal - 报表预聚合 (Reporting)** +- **[ERP_REP_01] 全业务多维报表宽表构建 (Report Mart)**: + - **任务**: 实现 `ReportService` 预聚合接口，支持 GMV/ROI/损耗分析. + - **状态**: ✅ `completed` [AI-2] | 🛡️ Verified (Report Mart) + +#### **[AI-3] Biz - 客户中枢 (CRM)** +- **[ERP_CRM_01] 客户 360 视图与商机中枢 (CRM Hub)**: + - **任务**: 实现 `Customer360Service` 聚合订单/客诉/财务往来. + - **状态**: ✅ `completed` [AI-3] | 🛡️ Verified + +--- + +### Batch 62 (2026-03-14) - [GOV_EXPERIMENT] 策略实验与全量告警中枢 (V32.0) + +> **核心目标**：建立科学的策略评估体系与全网异常监测网。 + +#### **[AI-1] Kernel - 实验分桶 (Experiment Hub)** +- **[CORE_GOV_EXP] AB 实验与策略分桶平台 (Experiment Hub)**: + - **任务**: 实现 `ExperimentService` 支持按用户/店铺/节点的实验隔离. + - **状态**: ⏳ `pending` [AI-1] | 🛡️ Pending + +#### **[AI-2] Internal - 告警归集 (Alert Center)** +- **[CORE_TELE_ALRT] 统一告警归集与自愈路由 (Alert Hub)**: + - **任务**: 实现 `AlertService` 将风控/自愈/时效预警统一接入告警通道. + - **状态**: ✅ `completed` [AI-2] | 🛡️ Verified (Alert Hub) + +--- + +### Batch 63 (2026-03-14) - [AI_CREATIVE_INFRA] 多模态 AGI 创作后端引擎 (V32.0) + +> **核心目标**：实现商品图生成、视频翻译与 TTS 语音合成的后端调度与存储闭环。 + +#### **[AI-1] Kernel - 创作调度 (Creative Engine)** +- **[BIZ_CRE_01] 多模态 AI 创作工作台 (Creative Service)**: + - **任务**: 实现 `CreativeService` 对接 Minimax/OpenAI，支持任务状态流转与素材存证. + - **状态**: ⏳ `pending` [AI-1] | 🛡️ Pending + +--- + +### Batch 64 (2026-03-14) - [FINANCE_DEEP_AUDIT] 财务深度审计与自动化服务 (V32.0) + +> **核心目标**：落地 BIZ_FIN_170-200 的 31 项财务自治服务，实现穿透式经营审计。 + +#### **[AI-3] Biz - 财务自治 (Finance Autonomy)** +- **[BIZ_FIN_170] SKU 淘汰建议报告 (Killer)**: + - **任务**: 实现 `SKUEfficiencyService` 物理表闭环. + - **状态**: ⏳ `pending` [AI-3] | 🛡️ Pending +- **[BIZ_FIN_200] 全自动审计与合规性自查 (AI Guard)**: + - **任务**: 实现 `ComplianceAIGuard` 遍历 AuditLog 识别违规. + - **状态**: ⏳ `pending` [AI-3] | 🛡️ Pending + +--- + +### Batch 65 (2026-03-14) - [LOGISTICS_OPTIMIZER] 全球物流路由与自愈优化 (V32.0) + +> **核心目标**：实现最后一公里配送优化与全球物流拥堵自愈。 + +#### **[AI-2] Internal - 物流遥测 (Logistics Telemetry)** +- **[BIZ_TRADE_18] 全球物流拥堵预测与自适应绕路 (Congestion Failover)**: + - **任务**: 实现 `CongestionFailoverService` 自动切换备选物流. + - **状态**: ✅ `completed` [AI-2] | 🛡️ Verified (Congestion AI) + +--- + +### Batch 66 (2026-03-14) - [MARKETING_AUTO] AGI 广告管家与多渠道联动 (V32.0) + +> **核心目标**：实现广告预算动态分配与营销日历自动执行。 + +#### **[AI-3] Biz - 营销自治 (Marketing Autonomy)** +- **[BIZ_MKT_20] AGI 广告管家与预算动态优化 (AdOps)**: + - **任务**: 实现 `AdAutoService` 联动套利引擎调整预算. + - **状态**: ⏳ `pending` [AI-3] | 🛡️ Pending + +--- + +### Batch 67 (2026-03-14) - [SEC_PRIVATE_COMPUTE] 隐私计算与全同态审计 (V32.0) + +> **核心目标**：落地基于 ZKP 与 FHE 的全流程隐私审计，保护租户主权。 + +#### **[AI-2] Internal - 隐私安全 (Privacy Security)** +- **[CORE_SEC_20] 基于 ZKP 的全流程隐私审计 (Private Audit)**: + - **任务**: 实现 `PrivateAuditService` 利用 Circom 汇总利润. + - **状态**: ✅ `completed` [AI-2] | 🛡️ Verified (ZKP Proof) + +--- + +### Batch 68 (2026-03-14) - [CORE_AI_EVOLUTION] AGI 策略自进化闭环 (V32.0) + +> **核心目标**：建立 AI 决策的自我修正机制。 + +#### **[AI-1] Kernel - 进化闭环 (Evolution Loop)** +- **[CORE_AI_40] AGI 策略自进化闭环验证 (Evolution Loop)**: + - **任务**: 实现 `AGIStrategyEvolutionService` 将成交数据回流至 Prompt 微调. + - **状态**: ⏳ `pending` [AI-1] | 🛡️ Pending + +--- + +### Batch 69 (2026-03-14) - [INFRA_BILLING] 企业配额与订阅计费中心 (V32.0) + +> **核心目标**：建立稳定经常性收入模型。 + +#### **[AI-1] Kernel - 计费引擎 (Billing Engine)** +- **[BIZ_BILL_01] 企业配额与订阅计费中心 (Billing Center)**: + - **任务**: 实现 `BillingEngine` 对超限 AI 调用自动计费. + - **状态**: ⏳ `pending` [AI-1] | 🛡️ Pending + +--- + +### **1. 基础建设与商业闭环 (Priority: P0/P1 - 务实落地区)** +| 任务 ID | 描述 | 核心交付物 | 状态 | 负责人 | 生产校验 | +| :--- | :--- | :--- | :--- | :--- | :--- | +| `ERP_OMS_01` | **订单全生命周期状态机加固** | `OrderService` 升级 | ✅ `completed` | AI-3 | 🛡️ Verified | +| `ERP_FIN_01` | **财务对账与收支差异分析引擎** | `FinanceReconService` | ✅ `completed` | AI-3 | 🛡️ Verified | +| `ERP_TASK_01` | **统一任务中枢与分发引擎** | `UnifiedTaskService` | ✅ `completed` | AI-1 | 🛡️ Verified | +| `ERP_APPROVE_01`| **通用审批流引擎** | `ApprovalFlowService` | ✅ `completed` | AI-3 | 🛡️ Verified | +| `ERP_CRM_01` | **客户 360 视图与商机中枢** | `Customer360Service` | ✅ `completed` | AI-3 | 🛡️ Verified | +| `CORE_GOV_EXP` | **AB 实验与策略分桶平台** | `ExperimentService` | ⏳ `in_progress` | AI-1 | 🛡️ Pending | +| `SOV_NET_06` | **基于 Libp2p/WebRTC 的直连通信** | `P2PConnectionService` | ✅ `completed` | AI-1 | 🛡️ Verified | +| `SOV_NET_07` | **基于 ZKP 的隐私声誉分值证明** | `ReputationZKPService` | ✅ `completed` | AI-2 | 🛡️ Verified | +| `SOV_NET_08` | **节点声誉衰减与惩罚机制** | 升级 `SovereignReputationV2` | ✅ `completed` | AI-1 | 🛡️ Verified | +| `CORE_TELE_TOPO` | **全球节点实时拓扑遥测** | `NetworkTopologyService` | ✅ `completed` | AI-2 | 🛡️ Verified | +| `BIZ_SOV_13` | **声誉驱动的阶梯费率与流量倾斜** | 联动 `BillingService` | ⏳ `in_progress` | AI-3 | 🛡️ Pending | +| `BIZ_SOV_14` | **跨节点资源共享配额管理** | `NodeResourceQuotaService` | ⏳ `in_progress` | AI-3 | 🛡️ Pending | +| `CORE_AI_60` | **Agent 集群自治协作协议 (Swarm)** | `AgentSwarmService` 物理表 | ✅ `completed` | AI-1 | 🛡️ Verified | +| `CORE_TELE_PREDICTIVE` | **预测性系统健康度看板** | `PredictiveHealthService` 物理表 | ✅ `completed` | AI-2 | 🛡️ Verified | +| `BIZ_MKT_50` | **AGI 驱动的跨平台套利自动化** | `ArbitrageAGIService` 物理表 | ⏳ `in_progress` | AI-3 | 🛡️ Pending | +| `BIZ_INV_30` | **滞销库存深度治理建议** | 联动 `AdviceService` | ⏳ `in_progress` | AI-3 | 🛡️ Pending | +| `SOV_NET_01` | **基于 DID 的节点身份握手协议** | `FederatedNodeService` | ✅ `completed` | AI-1 | 🛡️ Verified | +| `SOV_NET_03` | **节点间加密库存同步机制** | `PrivateInventorySyncService` | ✅ `completed` | AI-1 | 🛡️ Verified | +| `SOV_NET_05` | **跨节点算力共享与任务外包** | 升级 `InfinityComputeService` | ✅ `completed` | AI-1 | 🛡️ Verified | +| `BIZ_KER_131` | **容器运行时资源限制动态调整** | `ContainerQuotaService` | ✅ `completed` | AI-1 | 🛡️ Verified | +| `BIZ_KER_132` | **全局异步任务性能瓶颈分析** | `WorkerProfilerService` | ✅ `completed` | AI-1 | 🛡️ Verified | +| `BIZ_KER_133` | **租户敏感操作二次确认审计** | `ActionAuditService` | ✅ `completed` | AI-1 | 🛡️ Verified | +| `SOV_NET_02` | **跨节点自治清算协议实现** | `CrossNodeSettlementService` | ✅ `completed` | AI-3 | 🛡️ Verified | +| `SOV_NET_04` | **跨节点争议自动仲裁转发** | `GlobalDisputeRouter` | ✅ `completed` | AI-3 | 🛡️ Verified | +| `AUTO_SB_01` | **自治执行沙盒环境隔离引擎** | `AutonomousSandboxService` | ✅ `completed` | AI-2 | 🛡️ Verified | +| `AUTO_SB_02` | **沙盒执行 ROI 自动评估器** | `SandboxROIAdvisor` | ✅ `completed` | AI-2 | 🛡️ Verified | +| `ERP_WMS_01` | **拣货路径优化与波次分单算法** | `WMSWaveService` | ✅ `completed` | AI-2 | 🛡️ Verified | +| `ERP_LOG_01` | **物流轨迹全链路归一化监控** | `LogisticsTrackerService` | ✅ `completed` | AI-2 | 🛡️ Verified | +| `ERP_REP_01` | **全业务多维报表宽表构建** | `ReportService` 预聚合 | ✅ `completed` | AI-2 | 🛡️ Verified | +| `CORE_TELE_ALRT` | **统一告警归集与自愈路由** | `AlertService` | ✅ `completed` | AI-2 | 🛡️ Verified | +| `BIZ_TRADE_18` | **全球物流拥堵预测与自适应绕路** | `CongestionFailoverService` | ✅ `completed` | AI-2 | 🛡️ Verified | +| `CORE_SEC_20` | **基于 ZKP 的全流程隐私审计** | `PrivateAuditService` | ✅ `completed` | AI-2 | 🛡️ Verified | +| `BIZ_CRE_01` | **多模态 AI 创作工作台** | `CreativeService` | ⏳ `in_progress` | AI-1 | 🛡️ Pending | + +--- + +## 📜 历史变更记录 (Change Log) + +> 本节记录已归档的历史批次变更，详见 [collaboration-history-v31.md](governance/archive/collaboration-history-v31.md) + +### Batch 52 (2026-03-14) - [PRAGMATIC_PIVOT] 务实建议与半自动执行 (Semi-Auto) +> **核心目标**：拒绝华而不实的 AI，只做能省钱、能保命、能提效的功能。Agent 提供精准建议，人工一键批复。 + +#### **[AI-1] Kernel - 降本增效建议引擎 (Cost & Profit)** +- **[BIZ_SUP_15] 1688 极速降本比价**: + - **务实点**: 直接对比当前采购价与 1688 同款最低价，算出"每单可省多少钱"。 + - **任务**: 升级 `SupplyChainService`，产出包含"预期毛利提升值"的采购源切换建议。 +- **[BIZ_MKT_30] 竞品压价防御建议**: + - **务实点**: 仅在竞品价格低于我方且我方仍有 >20% 利润时提示"跟降建议"。 + - **任务**: 优化 `DynamicPricingService` 判定逻辑，拒绝无效提价建议，只做"保单调价"。 + +#### **[AI-2] Internal - 高效审核与风控流 (Efficiency & Risk)** +- **[UX_REVIEW_01] 批量建议批复接口**: + - **任务**: 在 `TelemetryController` 实现批量审核逻辑，联动 `DynamicPricing` 与 `Sourcing` 状态变更。 +- **[BIZ_GOV_05] 建议采纳 ROI 实时看板**: + - **任务**: 聚合 `cf_decision_logs`，展示"建议执行后预估收益"汇总。 + +#### **[AI-3] Biz - 缺货防御与履约保障 (Fulfillment)** +- **[BIZ_INV_10] 爆款缺货预警建议**: + - **任务**: 完善 `InventoryForecastService`，优先处理销售速率 > 5件/日的 SKU。 + +--- + +### Batch 53 (2026-03-14) - [SOVEREIGN_TRADE] 跨主权套利与自治清算 +> **核心目标**：实现从"决策建议"向"契约清算"的演进。基于 DID 与隐私计算，构建真正自治的全球贸易网络。 + +#### **[AI-3] Biz - 增长归因与自治清算 (Finance & Growth)** +- **[BIZ_MKT_40] 多触点归归因与利润分析 (Attribution Engine)** +- **[BIZ_FIN_40] 基于 DID 的自治清算协议 (DID Settlement)** +- **[BIZ_LOG_20] 全球动态路径对冲与风险熔断 (Global Route Failover)** +- **[BIZ_INV_20] 强化学习驱动的全球库存平衡 (RL Inventory Balancing)** + +--- + +### Batch 54 (2026-03-14) - [AUTONOMOUS_SETTLEMENT_&_LOGISTICS_RESILIENCE] +> **核心目标**：实现从"业务建议"向"自治执行"的深度下钻。重点解决汇率对冲、众包物流与争议自动仲裁。 + +#### **[AI-3] Biz - 业务清算与履约韧性 (Resilience & Settlement)** +- **[BIZ_FIN_50] 跨主权多币种对冲对账引擎 (Multi-Currency Recon)** +- **[BIZ_LOG_30] 最后一公里众包路由优化 (Crowdsourced Last-mile)** +- **[BIZ_TRADE_30] 自动化供应商产能预警 (Supplier Capacity Watch)** +- **[BIZ_CSM_30] 智能争议仲裁建议 (Dispute Arbitration)** + +--- + +### Batch 55 (2026-03-14) - [DTC_&_GROWTH_AUTONOMY] +> **核心目标**：构建 DTC 品牌自治底座。重点解决基于 LTV 的自动化会员治理、税务路径优化与绿色供应链合规。 + +#### **[AI-3] Biz - 增长治理与合规路由 (Growth & Compliance)** +- **[BIZ_MKT_60] 基于 LTV 预测的自动化会员等级晋升 (LTV Membership)** +- **[BIZ_FIN_60] 跨主权税务路由优化引擎 (Tax Routing Optimizer)** +- **[BIZ_LOG_40] 绿色供应链碳足迹核算与抵扣 (Green Supply Chain)** + +--- + +**看板维护者**：AI-1 (Kernel) | **当前版本**：V32.0 +**任务规格**：[task-specifications.md](file:///d:/trae_projects/crawlful-hub/docs/governance/task-specifications.md) diff --git a/docs/governance/console-collaboration-board.md b/docs/governance/console-collaboration-board.md new file mode 100644 index 0000000..51b0be3 --- /dev/null +++ b/docs/governance/console-collaboration-board.md @@ -0,0 +1,236 @@ +# 🎨 Console 前端专项协作看板 (Console Collaboration Board) - V32.0 + +> **协作定位**：本看板负责跟踪 `dashboard/` (Console) 与 `extension/` (Plugin) 的 UI/UX 实现、交互逻辑及 API 挂载进度。 +> **关联后端**：[collaboration-board.md](collaboration-board.md) | **实施清单**：[frontend-dev-plan.md](../frontend-dev-plan.md) + +--- + +### Batch 01 (2026-03-14) - [FE_CORE_CLOSURE] 核心业务闭环与策略中心 + +#### **[AI-FE] UI/UX 核心交互 (Core Interaction)** +- **[FE_ADV_01] 统一建议中心页面 (Advice Center Hub)**: + - **子任务**: + - [ ] 实现 `/strategy/advice` 统一列表页 (Card-based Layout). + - [ ] 接入 `AdviceService.getPendingAdvice` 接口，支持多维过滤. + - [ ] 实现批量审批 (Batch Approve) 工具条. + - **状态**: ⏳ `in_progress` | 🛡️ Pending (API Link) +- **[FE_ADV_02] AGI 建议审批弹窗与因果链 (XAI Dialog)**: + - **子任务**: + - [ ] 开发 `SuggestionCard` 原子组件 (含 Confidence, Impact). + - [ ] 实现 `CausalChainView` 可解释性视图 (联动 `getAdviceExplanation` API). + - [ ] 集成 `ActionAuditService` 审批动作存证. + - **状态**: ⏳ `in_progress` | 🛡️ Pending (Mock-Free) + +#### **[AI-EXT] 插件端增强 (Extension Perks)** +- **[EXT_SUB_01] 商品页 Suggestion Bubble 弹出逻辑**: + - **任务**: 基于当前 URL 的 `productId` 实时拉取后端建议并弹出 Bubble. + - **状态**: ✅ `completed` | 🛡️ Verified (P0 OK) +- **[EXT_AUTH_01] Console-Plugin 身份自动同步 (Auth Sync)**: + - **任务**: 登录 Console 后通过 `chrome.storage` 自动同步 JWT 至插件. + - **状态**: ✅ `completed` | 🛡️ Verified (JWT OK) + +--- + +### Batch 02 (2026-03-14) - [FE_SOVEREIGN_VIS] 主权网络可视化与遥测 + +#### **[AI-FE] 分布式交互 (Distributed UI)** +- **[FE_SOV_01] 全球节点拓扑遥测视图 (Network Topology)**: + - **任务**: 使用 AntV G6 实现 P2P 节点连接的可视化展示 (联动 `NetworkTopologyService`). + - **状态**: ⏳ `pending` | 🛡️ Pending (G6 Live) +- **[FE_SEC_01] ZKP 隐私声誉证明展示 (ZKP UI)**: + - **任务**: 展示节点的 ZKP 证明生成/校验状态与信用分等级 (Badge 体系). + - **状态**: ⏳ `pending` | 🛡️ Pending (ZKP UI) + +--- + +### Batch 03 (2026-03-14) - [FE_FIN_BIZ] 财务自治与运营遥测 + +#### **[AI-FE] 业务看板 (Business Dashboard)** +- **[FE_FIN_01] 实时 P&L 穿透分析看板 (Order Profit)**: + - **任务**: 展示订单级利润构成，包含摊销、汇损、运费穿透. + - **状态**: ⏳ `pending` | 🛡️ Pending +- **[FE_INV_01] 全球库存分布热力图 (Inventory Hotmap)**: + - **任务**: 展示海外仓库存热度与调拨建议可视化. + - **状态**: ⏳ `pending` | 🛡️ Pending +- **[FE_KILL_01] SKU 淘汰建议视图 (Killer Report)**: + - **任务**: 联动 `SKUEfficiencyService` 展示亏损 SKU 排行与下架建议. + - **状态**: ⏳ `pending` | 🛡️ Pending + +--- + +### Batch 04 (2026-03-14) - [FE_AGI_INTERACT] 高交互 AGI 控制中心 (V32.0) + +> **核心目标**：打破“列表+详情”的传统管理模式，构建沉浸式的人机协作终端。 + +#### **[AI-FE] 沉浸式交互 (Immersive UI)** +- **[FE_CMD_01] AGI 指令终端 (Omni-Box Command)**: + - **任务**: 实现全局自然语言搜索与指令框，支持问答式查询数据与下达策略调整指令. + - **状态**: ⏳ `pending` | 🛡️ Pending (LLM Stream) +- **[FE_SIM_01] What-If 策略仿真沙盒 (Strategy Sandbox)**: + - **任务**: 提供交互式滑块（调价、成本、库存），实时模拟 P&L 曲线变动，支持“一键转建议”. + - **状态**: ⏳ `pending` | 🛡️ Pending (Real-time G2) +- **[FE_FLOW_01] 视觉化 AGI 逻辑编排器 (Pipeline Builder)**: + - **任务**: 基于 React Flow 实现简单的策略流配置 UI（如：库存 < X 则触发 Y）. + - **状态**: ⏳ `pending` | 🛡️ Pending (JSON Schema) + +#### **[AI-EXT] 增强插件交互 (Extension Pro)** +- **[EXT_VIS_01] 跨站点视觉寻源画布 (Visual Sourcing Canvas)**: + - **任务**: 支持在插件端直接拖拽图片发起全网寻源，并在侧边栏展示成本对比图. + - **状态**: ⏳ `pending` | 🛡️ Pending (Vision API) + +--- + +### Batch 05 (2026-03-14) - [FE_BIZ_CHANNELS] 多端业务管理中心 (TOC / Independent / TOB) + +> **核心目标**：实现对 TOC 零售、独立站以及 TOB 批发的全场景管理闭环。 + +#### **[AI-FE] 业务中枢 (Business Hub)** +- **[FE_TOC_01] TOC 消费者运营工作台 (Consumer Ops)**: + - **任务**: 实现订单全生命周期追踪、多语种售后 RAG 交互界面. + - **状态**: ⏳ `pending` | 🛡️ Pending +- **[FE_SITE_01] 独立站 (Shopify/Direct) 管理矩阵**: + - **任务**: 站点健康度监控、SEO 关键词热力图、跨域名流量一键同步 UI. + - **状态**: ⏳ `pending` | 🛡️ Pending +- **[FE_TOB_01] TOB 批发与寻源询价 (Wholesale & RFQ)**: + - **任务**: 实现 RFQ 待办看板、阶梯报价矩阵编辑器、大客户信用分级视图. + - **状态**: ⏳ `pending` | 🛡️ Pending + +--- + +### Batch 06 (2026-03-14) - [FE_ERP_CORE] ERP 执行中枢 (SKU / Sourcing / WMS / Logistics) + +> **核心目标**：补全 ERP 核心执行模块，实现从“商品建模”到“物流交付”的全链路物理闭环。 + +#### **[AI-FE] 供应链执行 (Supply Chain Execution)** +- **[FE_ERP_SKU] 全球 SKU 主数据管理中心 (SKU Master)**: + - **任务**: 实现多维属性编辑器、平台级 SKU 映射矩阵、多媒体资产管理 (DAM). + - **状态**: ⏳ `pending` | 🛡️ Pending +- **[FE_ERP_SOURCING] 采购与寻源生命周期 (Procurement)**: + - **任务**: 实现从 AGI 建议一键转采购单 (PO)、到货质检 (QC) 入口、入库单同步. + - **状态**: ⏳ `pending` | 🛡️ Pending +- **[FE_ERP_WMS] AGI 驱动的智能仓储 (WMS Ops)**: + - **任务**: 实现可视化库位管理图、拣货波次进度条、拣货路径预览交互. + - **状态**: ⏳ `pending` | 🛡️ Pending +- **[FE_ERP_LOG] 跨境物流与面单中心 (Logistics Hub)**: + - **任务**: 实现多渠道运费实时比价列表、打单发货工作台、包裹轨迹实时地图. + - **状态**: ⏳ `pending` | 🛡️ Pending + +--- + +### Batch 07 (2026-03-14) - [FE_ERP_WORKBENCH] ERP 高交互工作台 (OMS / CS / Finance) + +> **核心目标**：提供生产级订单处理、售后协作与财务对账视图，实现“一站式”ERP 闭环体验。 + +#### **[AI-FE] 业务生产力 (Business Productivity)** +- **[FE_OMS_01] 统一订单工作台 (OMS Workbench)**: + - **任务**: 实现多渠道筛选、批量审核/发货工具条、异常标记与 AGI 改派建议联动. + - **状态**: ⏳ `pending` | 🛡️ Pending +- **[FE_CS_01] 售后与客服协同中心 (CS Dashboard)**: + - **任务**: 实现售后工单详情、AGI 生成的回复建议/协商方案预览、一键退款审批. + - **状态**: ⏳ `pending` | 🛡️ Pending +- **[FE_FIN_01] 财务对账与收支日历 (Finance Calendar)**: + - **任务**: 实现财务对账差异下钻视图、收支时间轴日历、现金流 AGI 预测图表. + - **状态**: ⏳ `pending` | 🛡️ Pending + +--- + +--- + +### Batch 08 (2026-03-14) - [FE_GOV_INBOX] 治理与任务中枢 (Inbox & Approval) + +#### **[AI-FE] 协同交互 (Collaboration UI)** +- **[FE_INBOX_01] 统一任务收件箱 (Global Inbox UI)**: + - **任务**: 实现全局待办列表，支持按来源模块、优先级、截止时间过滤 (联动 `UnifiedTaskService`). + - **状态**: ⏳ `pending` | 🛡️ Pending +- **[FE_APPROVE_01] 通用审批中心 UI (Approval Center)**: + - **任务**: 开发统一审批详情组件，展示变更前后对比、AGI 建议与影响评估. + - **状态**: ⏳ `pending` | 🛡️ Pending + +--- + +### Batch 09 (2026-03-14) - [FE_REP_BI] 数据分析与 AGI 报表 (BI Center) + +#### **[AI-FE] 决策支持 (Decision Support)** +- **[FE_REP_01] 报表中心工作台 (Report Hub)**: + - **任务**: 分组展示销售、库存、供应链、财务报表，支持维度切换与导出. + - **状态**: ⏳ `pending` | 🛡️ Pending +- **[FE_BI_01] 自助分析与 AGI 报表生成 (Natural Language BI)**: + - **任务**: 提供「维度-指标」拖拽界面，支持 AGI 语义解析生成可视化图表. + - **状态**: ⏳ `pending` | 🛡️ Pending + +--- + +### Batch 10 (2026-03-14) - [FE_CRM_360] 客户主权资产看板 (CRM) + +#### **[AI-FE] 资产管理 (Asset UI)** +- **[FE_CRM_01] 客户 360 档案与商机看板 (CRM UI)**: + - **任务**: 实现 TOC/TOB 统一档案，展示订单历史、客诉、信用评分与商机漏斗. + - **状态**: ⏳ `pending` | 🛡️ Pending + +--- + +### Batch 11 (2026-03-14) - [FE_GOV_CONFIG] 配置中心与 A/B 实验平台 + +#### **[AI-FE] 策略治理 (Policy UI)** +- **[FE_CONF_01] 统一配置中心页面 (Config Manager)**: + - **任务**: 实现 Feature Flag、风控阈值、策略参数的颗粒度管理 UI. + - **状态**: ⏳ `pending` | 🛡️ Pending +- **[FE_EXP_01] A/B 实验与策略分桶平台 (Experiment Hub)**: + - **任务**: 展示实验目标、分组策略、KPI 对比分析图表. + - **状态**: ⏳ `pending` | 🛡️ Pending + +--- + +### Batch 12 (2026-03-14) - [FE_SB_SIM] What-If 策略仿真与沙盒控制 + +#### **[AI-FE] 策略仿真 (Simulation UI)** +- **[FE_SB_01] 沙盒模式切换与模拟看板 (Sandbox Dashboard)**: + - **任务**: 实现全局沙盒模式开关，展示在模拟环境下的策略执行 KPI 预测结果. + - **状态**: ⏳ `pending` | 🛡️ Pending + +--- + +### Batch 13 (2026-03-14) - [FE_ALRT_OBS] 告警与可观测性中心 + +#### **[AI-FE] 运维遥测 (Ops UI)** +- **[FE_ALRT_01] 统一告警与观察中心 (Alert Hub UI)**: + - **任务**: 聚合节点异常、任务失败、库存超阈告警，展示 AGI 自愈记录. + - **状态**: ⏳ `pending` | 🛡️ Pending + +--- + +### Batch 14 (2026-03-14) - [FE_AI_CREATIVE] 多模态 AGI 创作工作台 + +#### **[AI-FE] 内容生产 (Content UI)** +- **[FE_CRE_01] AI 创作工作台与任务列表 (Creative Workbench)**: + - **任务**: 提供商品图生成、视频翻译、TTS 语音合成的任务下发与素材库 UI. + - **状态**: ⏳ `pending` | 🛡️ Pending + +--- + +### 📊 全栈前端落地执行矩阵 (Frontend Execution Matrix) + +| 任务 ID | 模块属性 | 核心描述 | 关键 UI 组件 | 状态 | 负责人 | 生产校验 | +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | +| `FE_ADV_01` | **核心/策略** | **统一建议中心页面 (Advice Hub)** | `AdviceList`, `FilterBar` | ⏳ `in_progress` | AI-FE | 🛡️ Pending | +| `FE_ADV_02` | **核心/UI** | **AGI 建议审批与因果链 (XAI)** | `CausalChainChart` | ⏳ `in_progress` | AI-FE | 🛡️ Pending | +| `EXT_SUB_01` | **插件/业务** | **商品页 Suggestion Bubble** | `SuggestionBubble` | ✅ `completed` | AI-EXT | 🛡️ Verified | +| `EXT_AUTH_01` | **插件/架构** | **Console-Plugin 身份同步** | `AuthBridge` | ✅ `completed` | AI-EXT | 🛡️ Verified | +| `FE_SOV_01` | **架构/遥测** | **全球节点拓扑遥测视图 (G6)** | `NetworkTopologyGraph` | ⏳ `in_progress` | AI-FE | 🛡️ Pending | +| `FE_SEC_01` | **安全/UI** | **ZKP 隐私声誉证明展示** | `ReputationBadge` | ⏳ `in_progress` | AI-FE | 🛡️ Pending | +| `FE_FIN_01` | **业务/财务** | **实时 P&L 穿透分析看板** | `ProfitBreakdownChart` | ⏳ `in_progress` | AI-FE | 🛡️ Pending | +| `FE_INV_01` | **业务/库存** | **全球库存分布热力图** | `InventoryWorldMap` | ⏳ `in_progress` | AI-FE | 🛡️ Pending | +| `FE_HEAL_01` | **内核/运维** | **AGI 自愈异常上报看板** | `AnomalyRCAView` | ⏳ `pending` | AI-FE | 🛡️ Pending | +| `EXT_HEAL_01`| **插件/内核** | **插件端页面结构自愈上报** | `AnomalyReporter` | ⏳ `pending` | AI-EXT | 🛡️ Pending | + +--- + +### 🛡️ 前端质量红线 (Frontend Red Lines) +1. **Zero-Mock Policy**：严禁 Mock 数据。所有展示必须基于 [AdviceService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Strategy/AdviceService.ts) 或相关生产接口。 +2. **Causal Chain Enforcement**：任何 AI 建议展示必须具备 [UX_XAI_01](file:///d:/trae_projects/crawlful-hub/server/src/api/controllers/BizStrategyController.ts) 定义的因果链入口。 +3. **Traceability**：所有操作必须注入 `x-trace-id`，并支持从 UI 一键跳转至 [AuditLog](file:///d:/trae_projects/crawlful-hub/server/src/core/runtime/DomainRegistry.ts)。 +4. **FSM Consistency**：UI 交互状态必须严格遵循后端定义的状态机（PENDING -> APPROVED -> EXECUTED）。 + +--- +**看板维护者**：AI-FE | **当前版本**：V32.0 +**关联规格**：[task-specifications.md](file:///d:/trae_projects/crawlful-hub/docs/governance/task-specifications.md) diff --git a/docs/governance/doc-maintenance-plan.md b/docs/governance/doc-maintenance-plan.md new file mode 100644 index 0000000..ca64fa1 --- /dev/null +++ b/docs/governance/doc-maintenance-plan.md @@ -0,0 +1,251 @@ +# 📋 MD 文档维护优化 - AI Agent 分工方案 + +> **文档定位**：本文档定义多 AI Agent 协同维护优化项目 MD 文档的分工矩阵、协作流程与验收标准。 +> **适用范围**：docs/ 目录下所有 .md 文档的维护、更新与优化工作。 + +--- + +## 1. 文档分类与工作量评估 + +### 1.1 文档分类矩阵 + +| 分类 | 文档数量 | 维护频率 | 复杂度 | +|-----|---------|---------|-------| +| **benchmarks/** | 1 (综合文档) | 低 | 中 | +| **blueprints/** | 6 | 中 | 高 | +| **blueprints/frontend-integration/** | 60+ | 高 | 中 | +| **design/** | 4 | 中 | 中 | +| **governance/** | 4 | 高 | 高 | +| **guides/** | 3 | 中 | 低 | +| **quality/** | 3 | 低 | 低 | + +### 1.2 优化工作类型 + +| 工作类型 | 描述 | 预估工作量 | +|---------|-----|----------| +| **内容校准** | 修正过时信息、补充缺失内容 | 40% | +| **格式规范** | 统一文档格式、命名规范 | 20% | +| **关联更新** | 同步关联文档、交叉引用 | 15% | +| **质量提升** | 补充示例、完善细节 | 15% | +| **架构演进** | 适配新功能、新需求 | 10% | + +--- + +## 2. AI Agent 分工矩阵 + +> 基于项目现有的 **三 AI 协作模式**，将文档维护任务按职责域进行分配。 + +### 2.1 分工概览 + +| Agent | 职责域 | 文档范围 | 核心能力 | +|-------|-------|---------|---------| +| **AI-1 (Kernel)** | 基础设施与内核文档 | blueprints/, design/ | 架构设计、技术规范 | +| **AI-2 (Internal)** | 内部支撑与集成文档 | governance/, benchmarks/ | 分析能力、关联梳理 | +| **AI-3 (Biz)** | 业务与前端集成文档 | frontend-integration/, guides/, quality/ | 业务理解、用户体验 | + +### 2.2 详细分工 + +#### 🔧 AI-1 (Kernel) - 基础设施与架构文档 + +| 任务分类 | 具体文档 | 工作内容 | +|---------|---------|---------| +| **架构蓝图** | arch-overview-v30.md, arch-freeze-v30.md, v30-arch-optimization-plan.md | 校准技术架构描述、同步最新变更 | +| **前端架构** | frontend-architecture.md | 更新技术栈、补充新特性 | +| **全局蓝图** | global-business-blueprint.md | 业务架构演进同步 | +| **设计文档** | server-initiation.md, extension-initiation.md, console-pipeline-log-design.md | 技术规范更新 | +| **新增文档** | industry-benchmarks-comprehensive.md | 行业标杆综合文档落地 | + +**交接给 AI-2**： +- 架构变更需同步至 governance/collaboration-board.md +- 前端架构变更需通知 AI-3 更新 frontend-integration/ + +#### 🔍 AI-2 (Internal) - 协作与分析文档 + +| 任务分类 | 具体文档 | 工作内容 | +|---------|---------|---------| +| **协作看板** | collaboration-board.md, console-collaboration-board.md | 更新任务状态、批次信息 | +| **任务规格** | task-specifications.md | 补充任务描述、完善验收标准 | +| **历史归档** | archive/collaboration-history-v31.md | 归档变更记录 | +| **标杆分析** | benchmarks/industry-benchmarks-comprehensive.md | 15+标杆产品综合拆解 | + +**交接给 AI-1**： +- 新任务 ID 需在 task-specifications.md 定义 +- 架构变更需通知 AI-1 更新 blueprints/ + +**交接给 AI-3**： +- 业务需求变更需通知 AI-3 更新 frontend-integration/ +- 标杆功能新增需同步至前端集成方案 + +#### 🏢 AI-3 (Biz) - 业务与前端集成文档 + +| 任务分类 | 具体文档 | 工作内容 | +|---------|---------|---------| +| **前端集成** | frontend-integration/*.md (48个) | 完善 UI 描述、补充 API 映射 | +| **实施指南** | server-readme.md, toc-early-stage-spec.md, non-saas-multi-tenant-checklist.md | 更新实施步骤、补充注意事项 | +| **质量标准** | frontend-delivery-standard.md, golive-redline-checklist.md, ux-field-acceptance-checklist.md | 完善交付标准、补充验收清单 | +| **开发计划** | frontend-dev-plan.md | 更新前端路线图 | + +**交接给 AI-1**： +- 前端架构变更需通知 AI-1 更新 frontend-architecture.md + +--- + +## 3. 协作流程 + +### 3.1 任务分发机制 + +``` +┌─────────────────────────────────────────────────────────┐ +│ 任务池 (Task Pool) │ +│ - 文档优化需求 │ +│ - 变更同步请求 │ +│ - 质量审计反馈 │ +└───────────────────────┬─────────────────────────────────┘ + │ + ┌───────────────┼───────────────┐ + ▼ ▼ ▼ + [AI-1 Kernel] [AI-2 Internal] [AI-3 Biz] + │ │ │ + └───────────────┼───────────────┘ + │ + ▼ + [验收 & 归档] +``` + +### 3.2 跨 Agent 协作规则 + +| 场景 | 发起方 | 接收方 | 协作方式 | +|-----|-------|-------|---------| +| 架构变更 | AI-1 | AI-2/AI-3 | 变更通知 + 文档同步 | +| 任务新增 | AI-2 | AI-1 | 规格定义 + 架构确认 | +| 业务需求 | AI-3 | AI-2 | 需求描述 + 规格确认 | +| 依赖阻塞 | 任意 | 上游 | 阻塞上报 + 等待确认 | + +### 3.3 变更同步协议 + +``` +[变更类型] → [文档路径] → [影响范围] → [协作要求] +``` + +**示例**： +``` +[架构变更] → [arch-overview-v30.md] → [AI-2:更新协作看板] → [24小时内同步] +``` + +--- + +## 4. 验收标准 + +### 4.1 单文档验收 + +| 检查项 | 标准 | 权重 | +|-------|-----|-----| +| **内容准确性** | 无过时信息、与代码实现一致 | 40% | +| **格式规范性** | 符合命名规范、目录结构规范 | 20% | +| **关联完整性** | 交叉引用有效、版本同步 | 20% | +| **可读性** | 逻辑清晰、示例充足 | 20% | + +### 4.2 协作验收 + +| 检查项 | 标准 | +|-------|-----| +| **交接完整性** | 跨 Agent 文档均已同步 | +| **状态可追溯** | 变更记录完整、可回溯 | +| **无静默失败** | 阻塞问题已上报 | + +--- + +## 5. 执行计划 + +### 5.1 第一轮：基础规范（1-2 周） + +| Agent | 任务 | 交付物 | +|-------|-----|-------| +| AI-1 | 统一 blueprints/ 格式规范 | 格式检查清单 | +| AI-2 | 审计 governance/ 文档完整性 | 缺失清单 | +| AI-3 | 完善 frontend-integration/ 模板 | 补充示例 | + +### 5.2 第二轮：内容优化（2-3 周） + +| Agent | 任务 | 交付物 | +|-------|-----|-------| +| AI-1 | 校准架构文档与技术实现一致 | 更新的架构蓝图 | +| AI-2 | 同步任务规格与看板状态 | 最新协作看板 | +| AI-3 | 补充前端集成方案的 API 映射 | 完整的前端集成文档 | + +### 5.3 第三轮：质量提升（1-2 周） + +| Agent | 任务 | 交付物 | +|-------|-----|-------| +| AI-1 | 补充架构决策记录 (ADR) | 决策日志 | +| AI-2 | 完善标杆分析报告 | 行业对比报告 | +| AI-3 | 补充 UX 验收标准 | 完善的质量清单 | + +--- + +## 6. 当前任务分配 + +### 6.1 优先级 P0（立即执行） + +| 文档 | 当前状态 | 负责 Agent | 截止时间 | +|-----|---------|------------|---------| +| industry-benchmarks-comprehensive.md | ✅ 已完成 | AI-2 | 已完成 | +| collaboration-board.md | ✅ 已同步 | AI-2 | 已完成 | +| frontend-architecture.md | ✅ 已更新 | AI-1 | 已完成 | + +### 6.2 优先级 P1（本周内） + +| 文档 | 当前状态 | 负责 Agent | +|-----|---------|------------| +| arch-overview-v30.md | 待校准 | AI-1 | +| task-specifications.md | 待同步 | AI-2 | +| frontend-architecture.md | 待更新 | AI-3 | + +--- + +## 7. 沟通机制 + +### 7.1 例行同步 + +| 周期 | 内容 | 参与方 | +|-----|-----|-------| +| **每日站会** | 进度同步、阻塞上报 | 全员 | +| **周度复盘** | 质量评估、流程优化 | 全员 | +| **版本发布** | 文档版本同步 | 全员 | + +### 7.2 紧急响应 + +- **阻塞升级**：超过 4 小时未解决的跨域问题，升级至负责人 +- **变更广播**：重大变更需在 1 小时内通知所有相关方 + +--- + +## 8. 附录 + +### 8.1 文档命名规范 + +- 使用 **小写短横线** (kebab-case) +- 示例：`frontend-architecture.md`, `arch-overview-v30.md` + +### 8.2 目录结构规范 + +``` +docs/ +├── benchmarks/ # 行业标杆分析 +├── blueprints/ # 架构蓝图 +│ └── frontend-integration/ # 前端集成方案 +├── design/ # 技术设计 +├── governance/ # 协作与任务 +├── guides/ # 实施指南 +└── quality/ # 质量标准 +``` + +--- + +**维护者**：AI-1 (Kernel) +**版本**：V2.0 +**状态**：已更新 +**更新内容** (2026-03-15): +- benchmarks/ 目录已整合为 1 个综合文档 +- frontend-integration/ 更新为 60+ 个文档 +- P0 任务已完成状态同步 diff --git a/docs/governance/task-specifications.md b/docs/governance/task-specifications.md new file mode 100644 index 0000000..67c728e --- /dev/null +++ b/docs/governance/task-specifications.md @@ -0,0 +1,854 @@ +# 📋 任务规格说明书 (Master Task Registry) - V32.0 + +> **多 AI 协同原子指令源**。严禁物理删除历史规格，失效规格请使用 ~~删除线~~ 标注并记录版本。 + +### **[ERP_WMS_01] 拣货路径优化与波次分单算法 (Pick Wave)** +- **技术收益**：基于 AGI 销量预测自动聚合高频 SKU 订单，优化拣货路径，提升仓库作业效率 40%。 +- **核心目标**：实现 `WMSWaveService`，支持波次自动生成、路径 TSP 优化与物理表持久化。 +- **参考路径**：[WMSWaveService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Logistics/WMSWaveService.ts) + +### **[ERP_LOG_01] 物流轨迹全链路归一化监控 (Logistics Tracker)** +- **技术收益**：实时识别全球物流轨迹异常（停滞、错投、延误），联动自愈路由降低丢包风险。 +- **核心目标**：实现 `LogisticsTrackerService`，支持轨迹异常检测模式匹配与 `reportAnomaly` 联动。 +- **参考路径**：[LogisticsTrackerService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Logistics/LogisticsTrackerService.ts) + +### **[CORE_TELE_ALRT] 统一告警归集与自愈路由 (Alert Hub)** +- **运维收益**：打破信息孤岛，将风控、系统、业务异常统一归集，为 AGI 自愈提供结构化决策输入。 +- **核心目标**：实现 `AlertService`，支持告警分级（CRITICAL/ERROR/WARN）、租户聚合与状态管理。 +- **参考路径**：[AlertService.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/telemetry/AlertService.ts) + +### **[ERP_REP_01] 全业务多维报表宽表构建 (Report Mart Aggregator)** +- **技术收益**：通过增量预聚合（Incremental Aggregation）解决大数据量下的报表查询性能瓶颈。 +- **核心目标**：在 `ReportService` 中实现预聚合逻辑，将明细表增量同步至 `cf_report_summary` 宽表。 +- **参考路径**：[ReportService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Analytics/ReportService.ts) + +### **[CORE_TELE_PREDICTIVE_HEALTH] 预测性系统健康度看板 (Predictive Health)** +- **技术收益**：通过时间序列分析预判系统崩溃与性能瓶颈，实现 AGI 级别的自愈能力。 +- **核心目标**：实现 `PredictiveHealthService`，基于 Telemetry 数据展示未来 24 小时的健康度预测。 +- **参考路径**：[PredictiveHealthService.ts](file:///d:/trae_projects/crawlful-hub/server/src/services/telemetry/PredictiveHealthService.ts) + +### **[CORE_AI_60] Agent 集群自治协作协议 (Agent Swarm)** +- **战略收益**：打破单 Agent 性能瓶颈，实现多 AGI 实例的复杂任务流水线。 +- **核心目标**：实现 `AgentSwarmService`，支持任务在不同特性的 Agent 间自动流转。 +- **参考路径**：[AgentSwarmService.ts](file:///d:/trae_projects/crawlful-hub/server/src/services/AgentSwarmService.ts) + +### **[BIZ_INV_30] 滞销库存深度治理与清仓建议 (Aging Inventory)** +- **利润收益**：降低仓储成本，通过 AGI 自动生成针对滞销 SKU 的阶梯折扣建议。 +- **核心目标**：实现 `AgingInventoryService`，联动 `InventoryAgingService` 进行库龄分析。 +- **参考路径**：[AgingInventoryService.ts](file:///d:/trae_projects/crawlful-hub/server/src/services/AgingInventoryService.ts) + +### **[BIZ_MKT_50] AGI 驱动的跨平台套利自动化 (Arbitrage AGI)** +- **战略收益**：秒级识别全球多平台（Amazon, Temu, 1688）价格洼地，全自动执行套利下单。 +- **核心目标**：实现 `ArbitrageAGIService`，联动 `ArbitrageService` 锁定套利空间。 +- **参考路径**：[ArbitrageAGIService.ts](file:///d:/trae_projects/crawlful-hub/server/src/services/ArbitrageAGIService.ts) + +### **[BIZ_INV_50] 分布式库存分布优化 (Inventory Distribution)** +- **业务收益**：基于销量热力图动态调整全球各仓库存分布，减少跨区调拨成本 30%。 +- **核心目标**：实现 `InventoryDistributionService`，生成 `TRANSFER` 建议。 +- **参考路径**：[InventoryDistributionService.ts](file:///d:/trae_projects/crawlful-hub/server/src/services/InventoryDistributionService.ts) + +### **[BIZ_FIN_210] 跨主权流动性对冲与避险 (Liquidity Hedge)** +- **金融收益**：自动对冲跨境贸易中的流动性风险，确保结算网关资金充沛。 +- **核心目标**：实现 `LiquidityHedgingService`，监控各 Hub 节点头寸。 +- **参考路径**：[LiquidityHedgingService.ts](file:///d:/trae_projects/crawlful-hub/server/src/services/LiquidityHedgingService.ts) + +### **[BIZ_FIN_220] 供应链微贷与信用评估 (Micro Credit)** +- **金融收益**：基于贸易真实性证据链为租户提供 AGI 授信建议，解决小微外贸融资难。 +- **核心目标**：实现 `MicroCreditService`，联动 `cf_order` 真实交易记录。 +- **参考路径**：[MicroCreditService.ts](file:///d:/trae_projects/crawlful-hub/server/src/services/MicroCreditService.ts) + +### **[BIZ_SOV_13] 声誉驱动的阶梯费率与流量倾斜 (Reputation Perks)** +- **业务收益**：激励租户维护高信用评分，自动为高信用节点提供更低的结算手续费与优先的资源分配。 +- **核心目标**：联动 `BillingService` 与 `TrafficService`，根据声誉分值自动匹配计费 FSM。 +- **参考路径**：[BillingService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Billing/BillingService.ts) + +### **[BIZ_SOV_14] 跨节点资源共享配额管理 (Resource Quota)** +- **网络收益**：防止恶意节点占用全网算力/存储资源，基于声誉实现动态的资源预留与配额管理。 +- **核心目标**：实现 `NodeResourceQuotaService`，联动 `InfinityComputeService` 进行配额限制。 +- **参考路径**：[NodeResourceQuotaService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/NodeResourceQuotaService.ts) + +### **[CORE_TELE_TOPO] 全球节点实时拓扑遥测 (Network Topology)** +- **遥测收益**：提供全球贸易网络的实时连接快照，自动识别高延迟链路并触发路由重排。 +- **核心目标**：实现 `NetworkTopologyService`，采集 P2P 通信中的 latency, jitter 与 hop_count。 +- **参考路径**：[NetworkTopologyService.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/telemetry/NetworkTopologyService.ts) + +### **[FE_CMD_01] AGI 指令终端 (Omni-Box Command)** +- **交互收益**：让运营人员通过自然语言直接操控系统，降低操作复杂度 80%。 +- **核心目标**：实现一个全局浮动的搜索指令框，支持语义解析并映射至后端 API 指令。 +- **参考路径**：`dashboard/src/components/OmniBox/` + +### **[FE_TOC_01] TOC 消费者运营工作台 (Consumer Ops)** +- **业务收益**：打通零售端的售后与评价管理，提升客户满意度。 +- **核心目标**：展示消费者订单全链路状态，集成 RAG 驱动的智能纠纷处理界面。 +- **参考路径**：`dashboard/src/pages/business/toc/` + +### **[FE_SITE_01] 独立站管理矩阵 (Site Matrix)** +- **业务收益**：一站式管理 Shopify/WooCommerce 资产，监控全球流量波动。 +- **核心目标**：实现多站点健康度遥测、SEO 关键词热力图与跨站商品同步 UI。 +- **参考路径**：`dashboard/src/pages/business/sites/` + +### **[FE_TOB_01] TOB 批发与寻源询价 (Wholesale & RFQ)** +- **业务收益**：标准化 B2B 贸易流程，管理大宗订单与长期协议。 +- **核心目标**：实现 RFQ (询价单) 处理流水线，支持阶梯报价矩阵的图形化编辑。 +- **参考路径**：`dashboard/src/pages/business/tob/` + +### **[FE_ERP_SKU] 全球 SKU 主数据管理中心 (SKU Master)** +- **业务收益**：建立跨平台统一的商品身份，解决一物多码导致的库存混乱。 +- **核心目标**：实现多维属性（颜色/尺寸/规格）编辑器，支持 1688/Amazon/Temu SKU 映射矩阵。 +- **参考路径**：`dashboard/src/pages/erp/sku/` + +### **[FE_ERP_SOURCING] 采购与寻源生命周期 (Procurement)** +- **业务收益**：标准化采购流程，降低采购溢价与虚假发货风险。 +- **核心目标**：实现从 AGI 建议转采购单 (PO) 的全自动流程，支持质检 (QC) 结果录入与入库单同步。 +- **参考路径**：`dashboard/src/pages/erp/sourcing/` + +### **[FE_ERP_WMS] AGI 驱动的智能仓储 (WMS Ops)** +- **业务收益**：提升仓库作业效率，减少拣货路径冗余。 +- **核心目标**：提供库位管理的可视化视图，支持基于销量预测的库内移库建议。 +- **参考路径**：`dashboard/src/pages/erp/wms/` + +### **[FE_ERP_LOG] 跨境物流与面单中心 (Logistics Hub)** +- **业务收益**：自动化物流对账与轨迹监控，降低丢包率。 +- **核心目标**：实现多渠道运费实时比价、面单批量生成与包裹轨迹全链路监测。 +- **参考路径**：`dashboard/src/pages/erp/logistics/` + +### **[ERP_OMS_01] 订单全生命周期状态机加固 (OMS FSM)** +- **业务收益**：支持跨平台订单的统一调度与批量化处理，提升人效。 +- **核心目标**：升级 `OrderService`，支持 `PENDING_AUDIT` (待审), `WAITING_SHIPMENT` (待发), `EXCEPTION` (异常) 等细分状态与批量转换。 +- **参考路径**：`server/src/domains/Trade/OrderService.ts` + +### **[FE_OMS_01] 统一订单工作台 (OMS Workbench)** +- **交互收益**：提供类似“易仓”的订单列表处理体验，支持多维过滤与批量操作。 +- **核心目标**：实现订单列表页，集成批量审核、一键发货、异常标记、导出。 +- **参考路径**：`dashboard/src/pages/erp/oms/` + +### **[ERP_FIN_01] 财务对账与收支差异分析引擎 (Reconciliation)** +- **金融收益**：自动识别平台结算与实际订单的差异（运费、税费、退款），防止资金流失。 +- **核心目标**：实现 `FinanceReconService`，支持 CSV/API 账单导入、自动对齐、差异生成。 +- **参考路径**：`server/src/domains/Finance/FinanceReconService.ts` + +### **[FE_FIN_01] 财务对账与收支日历 (Finance Calendar)** +- **交互收益**：通过时间轴直观展示收支节奏，并支持差异项一键下钻至订单明细。 +- **核心目标**：实现财务总览看板，包含收支日历、差异对账列表、现金流预测图。 +- **参考路径**：`dashboard/src/pages/erp/finance/` + +### **[ERP_TASK_01] 统一任务中枢与分发引擎 (Task Hub)** +- **业务收益**：将 Advice, Alert, Approval, PO, RMA 等多源事件归一化，消除信息碎片化。 +- **核心目标**：实现 `UnifiedTaskService`，支持任务的「认领/转派/完成」状态流转与 TTL 自动失效。 +- **参考路径**：`server/src/domains/Governance/TaskService.ts` + +### **[FE_INBOX_01] 统一任务收件箱 (Global Inbox UI)** +- **交互收益**：提供一站式待办视图，支持按来源模块、优先级、截止时间过滤。 +- **核心目标**：实现 `Inbox` 列表页，集成「一键认领」与「详情穿透」功能。 +- **参考路径**：`dashboard/src/pages/governance/inbox/` + +### **[ERP_APPROVE_01] 通用审批流引擎 (Approval Engine)** +- **安全收益**：对敏感动作（大额调价、资金划转）实施多级人工门禁，满足合规审计。 +- **核心目标**：实现 `ApprovalFlowService`，支持按金额阈值、多租户/多角色规则的动态编排。 +- **参考路径**：`server/src/domains/Governance/ApprovalService.ts` + +### **[FE_APPROVE_01] 通用审批中心 (Approval Center UI)** +- **交互收益**：统一敏感动作的确认界面，展示变更前后对比、AGI 建议与影响评估。 +- **核心目标**：实现审批详情对话框，集成「同意/拒绝/修改后通过」动作。 +- **参考路径**：`dashboard/src/components/Approval/` + +### **[FE_REP_BI] 自助分析与 AGI 报表生成 (BI Center)** +- **决策收益**：通过自然语言提问生成多维分析视图，降低数据获取门槛。 +- **核心目标**：实现「维度-指标」拖拽分析界面，支持 AGI 语义解析生成 G2 图表。 +- **参考路径**：`dashboard/src/pages/analytics/bi/` + +### **[ERP_CRM_01] 客户 360 视图与商机中枢 (CRM Hub)** +- **业务收益**：打通 TOC/TOB 客户的全生命周期数据，沉淀信用资产。 +- **核心目标**：实现 `Customer360Service`，聚合订单历史、客诉记录、财务往来与信用分。 +- **参考路径**：`server/src/domains/Customer/CRMService.ts` + +### **[FE_CRM_01] 客户 360 档案与商机看板 (CRM UI)** +- **交互收益**：一键直达客户画像，可视化 B2B 商机漏斗（线索 -> 报价 -> 回款）。 +- **核心目标**：实现客户详情页与商机漏斗图组件。 +- **参考路径**：`dashboard/src/pages/business/crm/` + +### **[CORE_GOV_EXP] AB 实验与策略分桶平台 (Experiment Hub)** +- **战略收益**：科学评估 AGI 策略效果，支持灰度发布，降低全局误操作风险。 +- **核心目标**：实现 `ExperimentService`，支持按用户/店铺/节点的实验分桶与 KPI 对比分析。 +- **参考路径**：`server/src/core/governance/ExperimentService.ts` + +### **[FE_ALRT_01] 统一告警与可观测性中心 (Alert Center UI)** +- **运维收益**：秒级感知节点异常与业务跌价风险，支持订阅与静音管理。 +- **核心目标**：实现全局告警列表，展示触发条件、影响对象与 AGI 自愈尝试记录。 +- **参考路径**：`dashboard/src/pages/governance/alerts/` + +--- + +## 🛡️ 0. 全局生产级交付校验 (Production Readiness Gates) + +**所有任务在标记为 `completed` 前，必须通过以下红线审计：** + +1. **Zero-Mock 校验**：实现代码中严禁包含任何模拟数据返回。所有业务输出必须来自 `cf_` 数据库表或第三方生产 API。 +2. **Schema 闭环校验**：如果涉及新字段或新表，必须在 `LegacyTableInitializer.ts` 中完成 `initTable` 实现并执行成功。 +3. **因果链校验**：通过 `DecisionExplainabilityEngine.logDecision` 记录真实的决策逻辑。 +4. **影子测试校验**：AI-2 必须产出对应的冒烟测试用例，验证逻辑非“空壳”。 +5. **全栈联调校验 (Full-Stack Sync)**： + - 确保后端 `SUGGESTED` 状态的建议能真实流转至前端 `ReviewWorkbench`。 + - 严禁只有后端逻辑而无前端呈现方案。 + - 前端操作（Approve/Reject）必须真实触发后端业务变更。 + +--- + +### **[BIZ_TRADE_70] 全球保税仓调拨与跨境合规 (Bonded Warehouse)** +- **交付收益**：优化跨境物流税费，实现“先入仓后报关”的灵活库存调度。 +- **核心目标**：实现 `BondedWarehouseService`，支持保税仓入库单与出库单自动映射。 +- **参考路径**：[BondedWarehouseService.ts](file:///d:/trae_projects/crawlful-hub/server/src/services/BondedWarehouseService.ts) + +### **[BIZ_INV_40] AGI 自治仓储调度与库内优化 (Autonomous Warehousing)** +- **效率收益**：利用 AGI 预测库内操作热度，动态优化拣货路径与补货时机。 +- **核心目标**：实现 `AutonomousWarehousingService`，联动 WMS 接口进行指令编排。 +- **参考路径**：[AutonomousWarehousingService.ts](file:///d:/trae_projects/crawlful-hub/server/src/services/AutonomousWarehousingService.ts) + +--- + +### **[SOV_NET_06] 基于 Libp2p/WebRTC 的节点直连通信 (P2P Connectivity)** +- **战略收益**：打破中心化网关依赖，实现 Hub 节点间的亚秒级直连通信，提升资源交换效率 300%。 +- **核心目标**：实现 `P2PConnectionService`，利用 `libp2p` 或 `WebRTC` 构建加密的双向流通道。 +- **参考路径**：[P2PConnectionService.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/ai/P2PConnectionService.ts) + +### **[SOV_NET_07] 基于 ZKP 的隐私声誉分值证明 (ZKP Reputation)** +- **隐私收益**：允许节点在不公开具体交易细节与分值前提下，向合作伙伴证明其信用等级满足 P2P 准入门槛。 +- **核心目标**：实现 `ReputationZKPService`，利用 `circom` 生成声誉范围证明（Range Proof）。 +- **参考路径**：[ReputationZKPService.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/ai/ReputationZKPService.ts) + +### **[SOV_NET_08] 节点声誉衰减与惩罚机制 (Reputation Decay)** +- **治理收益**：建立动态信任模型，确保声誉真实反映节点当前的合规性与活跃度。 +- **核心目标**：升级 `SovereignReputationV2Service`，实现基于半衰期算法的自动衰减逻辑。 +- **参考路径**：[SovereignReputationV2Service.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/ai/SovereignReputationV2Service.ts) + +--- + +## 🏗️ 1. 深度智能与内核进化 (Domain: CORE_AI / CORE_DEV) + +### **[CORE_AI_40] AGI 策略自进化闭环验证 (Evolution Loop)** +- **战略收益**：建立 AI 决策的自我修正机制，减少人工干预成本 70%。 +- **核心目标**： + 1. **闭环反馈**：将 `ConsumerOrderService` 的真实成交数据回流至 `AGIStrategyEvolutionService`。 + 2. **自动微调**：AGI 代理基于利润反馈自动调整选品与调价 Prompt。 +- **参考路径**：[AGIStrategyEvolutionService.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/ai/AGIStrategyEvolutionService.ts) + +### **[CORE_AI_22] 多模态 SKU 情感分析与评论生成 (Sentiment AI)** +- **业务收益**：提升详情页转化率 30%，自动生成地道营销文案。 +- **核心目标**：融合商品图片（视觉）与历史抓取的评价文本，分析痛点并生成高说服力评论。 +- **参考路径**：[SentimentAnalysisService.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/ai/SentimentAnalysisService.ts) + +### **[CORE_DEV_30] 无限水平扩展的 AGI 推理节点调度 (Infinity Compute)** +- **技术收益**：支撑千万级并发 AGI 任务，亚秒级算力动态编排。 +- **核心目标**：实现租户级配额隔离与算力池动态扩缩容。 +- **参考路径**：[InfinityComputeService.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/ai/InfinityComputeService.ts) + +--- + +## 🔒 2. 主权安全与隐私计算 (Domain: CORE_SEC) + +### **[CORE_SEC_20] 基于零知识证明 (ZKP) 的全流程隐私审计 (Private Audit)** +- **合规收益**：在不解密原始数据前提下完成全量合规审计，保护商户主权。 +- **核心目标**：利用 `circom` 或类似技术实现利润与成本的隐私汇总计算。 +- **参考路径**：[PrivateAuditService.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/ai/PrivateAuditService.ts) + +### **[CORE_SEC_35] 全同态加密 (FHE) 利润敏感度审计 (FHE Audit)** +- **安全收益**：密文态运算，确保单租户特定策略绝不泄露。 +- **核心目标**：实现对加密状态下的财务字段执行加法与平均值运算。 +- **参考路径**：[HomomorphicService.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/security/HomomorphicService.ts) + +--- + +## 📈 3. 贸易自治与业务扩展 (Domain: BIZ_TRADE / BIZ_FIN) + +### **[BIZ_FIN_161] 订单级 P&L 实时穿透分析建议 (P&L Analysis)** +- **透明收益**：还原每笔订单的真实净利，剔除摊销、汇损等隐形成本。 +- **核心目标**：实现 `OrderProfitService`，通过穿透式计算，为租户提供最真实的毛利视角。 +- **参考路径**：[OrderProfitService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/OrderProfitService.ts) + +### **[BIZ_FIN_162] 多币种自动锁汇避险建议 (FX Hedge)** +- **避险收益**：在汇率剧烈波动时，自动建议锁定结汇汇率，保护外贸利润。 +- **核心目标**：监控汇率波动率，识别 CRITICAL 风险并生成锁汇指令建议。 +- **参考路径**：[CurrencyRiskService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/CurrencyRiskService.ts) + +### **[BIZ_FIN_164] 调价策略导致的毛利漂移分析 (Margin Drift)** +- **质量收益**：评估动态调价的效果，识别毛利侵蚀（Erosion）风险。 +- **核心目标**：分析 SKU 毛利趋势，对比调价前后的收益变化。 +- **参考路径**：[PricingAuditService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/PricingAuditService.ts) + +### **[BIZ_FIN_165] 广告 ROAS 真实性本地归因建议 (Ad Attribution)** +- **归因收益**：识破平台广告虚假繁荣，计算剔除自然单后的真实 ROAS。 +- **核心目标**：对比总订单流与广告点击流，计算 `trueROAS` 与 `organicRevenue`。 +- **参考路径**：[TrueROASService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/TrueROASService.ts) + +### **[BIZ_FIN_166] 各国 VAT 税务起征点自动提醒 (VAT Watch)** +- **合规收益**：防止因销售额超标导致的补税与罚款风险。 +- **核心目标**：监控各目的国年度销售额，在接近起征点（70%/90%）时触发预警。 +- **参考路径**：[TaxComplianceService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/TaxComplianceService.ts) + +### **[BIZ_FIN_167] 采购预付款比例信用分级调整 (Vendor Credit)** +- **流动性收益**：根据供应商绩效动态优化预付款，释放沉淀资金。 +- **核心目标**：实现 `VendorCreditService`，对高信用供应商建议降低预付款。 +- **参考路径**：[VendorCreditService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/VendorCreditService.ts) + +### **[BIZ_FIN_168] 未来 30 天现金流枯竭预警 (Cashflow Burn)** +- **生存收益**：联动采购、物流、销售全链路，预判资金链断裂风险。 +- **核心目标**：计算未来 30 天的待收与待付，生成 `projectedCash` 风险评估。 +- **参考路径**：[CashflowPredictor.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/CashflowPredictor.ts) + +### **[BIZ_FIN_169] 租户资源超限自动计费单生成 (Billing Engine)** +- **营收收益**：自动化处理按需付费（Pay-as-you-go）场景，降低漏收风险。 +- **核心目标**：实现 `BillingEngine`，对超限的 AI 调用或存储空间自动生成计费单。 +- **参考路径**：[BillingEngine.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/BillingEngine.ts) + +### **[BIZ_FIN_170-200] 业务财务自动化服务矩阵 (Finance Domain Expansion)** +- **核心收益**：实现了从 SKU 效率、回款风险、库存跌价到税务合规、预算管理、审计监控的 31 项财务自治服务。 +- **核心目标**： + - **Killer**: `SKUEfficiencyService` 识别亏损 SKU。 + - **Leverage**: `PayoutCycleService` 评估资金杠杆。 + - **Write-down**: `InventoryValueService` 计提跌价准备。 + - **Freeze**: `RefundRiskService` 预警退款风险。 + - **Terms**: `PaymentTermsService` 优化账期。 + - **Remit**: `RemitPathService` 优化汇款路径。 + - **Valuation**: `StockAuditService` 审计全球库存价值。 + - **Ad Budget**: `AdOptimizerService` 分配营销预算。 + - **Tenant Profit**: `TenantHealthService` 监控 P&L 波动。 + - **Rebate**: `RebateService` 追踪采购回扣。 + - **Loss Audit**: `FinancialAuditService` 审计操作损耗。 + - **Amortization**: `ExpenseService` 科学摊销成本。 + - **Commodity**: `MaterialRiskService` 预判原材料涨价。 + - **Refund Audit**: `RefundAuditService` 审计退款一致性。 + - **CAC**: `CACThresholdService` 设定获客上限。 + - **Split**: `CommissionService` 自动结算分销利润。 + - **Turnover**: `TurnoverWatchdog` 识别资金沉淀。 + - **Provision**: `WarrantyService` 计提售后准备金。 + - **Filing**: `TaxFilingAdvisor` 预填税务申报。 + - **Low Margin**: `MarginProtector` 拦截亏损订单。 + - **Credit Limit**: `CreditMonitorService` 监控供应商信用。 + - **Transfer Pricing**: `LegalTaxService` 评估跨境合规。 + - **Payout Optimizer**: `PayoutOptimizer` 优化提现手续费。 + - **Budgeting**: `FinancialPlanner` 生成 AI 预算。 + - **Gateway Risk**: `PaymentRiskService` 监控支付网关。 + - **Shipping Optimizer**: `DynamicShippingService` 优化包邮门槛。 + - **Campaign Health**: `CampaignHealthService` 监控营销 ROI。 + - **Savings Audit**: `SavingTrackerService` 审计采购降本。 + - **Claim Fraud**: `ClaimFraudService` 拦截恶意索赔。 + - **Balance Sheet**: `GlobalBalanceSheet` 实时资产快照。 + - **AI Guard**: `ComplianceAIGuard` 最终合规自查。 +- **参考路径**：[Finance Domain](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/) + +### **[BIZ_FIN_170] 周期性亏损 SKU 淘汰建议报告 (Killer)** +- **业务收益**：精准识别“利润黑洞”SKU，优化库存周转率与现金流。 +- **核心目标**：实现 `SKUEfficiencyService`，基于过去 30 天真实 P&L 自动生成淘汰/保留建议。 +- **参考路径**：[SKUEfficiencyService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/SKUEfficiencyService.ts) + +### **[BIZ_FIN_171] 多平台回款周期差异风险评估 (Leverage)** +- **财务收益**：预警由于回款周期（Payout Cycle）过长导致的资金链杠杆风险。 +- **核心目标**：监控各平台（Amazon, Temu 等）的平均结算周期，评估风险级别。 +- **参考路径**：[PayoutCycleService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/PayoutCycleService.ts) + +### **[BIZ_FIN_172] 库存跌价准备自动计提建议 (Write-down)** +- **合规收益**：符合会计准则，实时评估滞销库存的资产减值风险。 +- **核心目标**：基于库龄（Aging）自动计算跌价准备金，建议财务计提。 +- **参考路径**：[InventoryValueService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/InventoryValueService.ts) + +### **[BIZ_FIN_173] 高额退款导致的资金链冻结预警 (Freeze)** +- **风控收益**：提前识别由于争议率/退款率过高导致的支付网关（PayPal/Stripe）冻结风险。 +- **核心目标**：监控 `refundRatio`，触发 CRITICAL 级别预警与现金流储备建议。 +- **参考路径**：[RefundRiskService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/RefundRiskService.ts) + +### **[BIZ_FIN_174] 供应商账期自动展期/缩短建议 (Terms)** +- **资金收益**：基于供应商绩效动态优化付款条件，平衡供应链稳定性与现金流。 +- **核心目标**：评估供应商 SLA（交期、质量），给出 `EXTEND` 或 `SHORTEN` 建议。 +- **参考路径**：[PaymentTermsService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/PaymentTermsService.ts) + +### **[BIZ_FIN_175] 跨境汇款路径手续费选优建议 (Remit)** +- **降本收益**：实时对比多条汇款路径（Wise, PingPong, Payoneer），降低跨境汇损。 +- **核心目标**：基于汇款金额与币种，自动推荐综合评分最高的结算路径。 +- **参考路径**：[RemitPathService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/RemitPathService.ts) + +### **[BIZ_FIN_176] 虚拟仓/海外仓库存估值审计 (Valuation)** +- **财务收益**：符合会计准则（FIFO/加权平均），实时掌握全球库存资产价值。 +- **核心目标**：实现 `StockAuditService`，支持跨仓库、多币种的库存估值。 +- **参考路径**：[StockAuditService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/StockAuditService.ts) + +### **[BIZ_FIN_177] 多渠道广告支出预算分配建议 (Ad Budget)** +- **增长收益**：基于边缘毛利（Contribution Margin）自动优化广告预算，提升 ROAS。 +- **核心目标**：实现 `AdOptimizerService`，识别高 ROI SKU 并建议预算向其倾斜。 +- **参考路径**：[AdOptimizerService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/AdOptimizerService.ts) + +### **[BIZ_FIN_178] 租户层级 P&L 波动根因分析 (Tenant Profit)** +- **治理收益**：秒级感知经营异常，自动定位导致利润下滑的“黑天鹅”因素。 +- **核心目标**：监控每日 P&L 变化，触发异常波动（>20%）的自动化归因报告。 +- **参考路径**：[TenantHealthService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/TenantHealthService.ts) + +### **[BIZ_FIN_179] 供应商佣金回扣与折扣追踪 (Rebate)** +- **采购收益**：自动识别符合阶梯折扣或回扣（Rebate）条件的采购量，挽回隐藏利润。 +- **核心目标**：追踪 `totalVolume`，提醒采购专员发起回扣索赔。 +- **参考路径**：[RebateService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/RebateService.ts) + +### **[BIZ_FIN_180] 员工/Agent 操作财务损失审计 (Loss Audit)** +- **审计收益**：透明化运营成本，识别由于误操作或恶意行为导致的财务损耗。 +- **核心目标**：审计退款、改价、取消订单等敏感行为，计算预估损失。 +- **参考路径**：[FinancialAuditService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/FinancialAuditService.ts) + +### **[BIZ_FIN_181] 多平台合规成本摊销建议 (Amortization)** +- **会计收益**：将 ERP、工具费等固定/变动合规成本科学摊销至单笔订单。 +- **核心目标**：实现 `ExpenseService`，计算 `costPerOrder`，还原真实经营毛利。 +- **参考路径**：[ExpenseService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/ExpenseService.ts) + +### **[BIZ_FIN_182] 大宗商品价格波动对采购成本的影响预测 (Commodity)** +- **风险收益**：提前识别原材料涨价风险，自动建议备货或套期保值策略。 +- **核心目标**：实现 `MaterialRiskService`，监控铜、钢、原油等大宗商品行情并生成建议。 +- **参考路径**：[MaterialRiskService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/MaterialRiskService.ts) + +### **[BIZ_FIN_183] 售后退款路径原路返回一致性审计 (Refund Audit)** +- **合规收益**：防止内部舞弊或反洗钱合规风险，确保资金流向闭环。 +- **核心目标**：实现 `RefundAuditService`，强制校验退款路径与原始支付路径的一致性。 +- **参考路径**：[RefundAuditService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/RefundAuditService.ts) + +### **[BIZ_FIN_184] 基于用户 LTV 的营销成本上限建议 (CAC)** +- **盈利收益**：动态设定各渠道的获客成本（CAC）红线，确保长期 LTV/CAC 比率健康。 +- **核心目标**：实现 `CACThresholdService`，根据 LTV 预测自动计算允许的最高获客成本。 +- **参考路径**：[CACThresholdService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/CACThresholdService.ts) + +### **[BIZ_FIN_185] 全球分销网络利润分成自动结算 (Split)** +- **渠道收益**：自动化处理复杂的分销分润，降低人工对账成本 100%。 +- **核心目标**：实现 `CommissionService`，支持多层级 referral 分润与状态追踪。 +- **参考路径**：[CommissionService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/CommissionService.ts) + +### **[BIZ_FIN_186] 库存周转率异常导致的资金占用预警 (Turnover)** +- **流动性收益**：识别沉淀资金，通过加速周转提升整体资本回报率。 +- **核心目标**：实现 `TurnoverWatchdog`，监控 `daysToTurnover` 指标并触发积压预警。 +- **参考路径**：[TurnoverWatchdog.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/TurnoverWatchdog.ts) + +### **[BIZ_FIN_187] 基于历史数据的售后损耗准备金建议 (Provision) +- **稳健收益**：根据 AGI 预测的损耗率计提准备金，使财务报表更真实地反映风险。 +- **核心目标**：实现 `WarrantyService`，基于历史 `lossRatio` 自动建议月度计提金额。 +- **参考路径**：[WarrantyService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/WarrantyService.ts) + +### **[BIZ_FIN_188] 多国税务合规申报文件自动预填建议 (Filing) +- **合规收益**：极大简化跨境电商的税务申报流程，降低逾期申报风险。 +- **核心目标**：实现 `TaxFilingAdvisor`，根据各订单目的国税率与销售额，自动生成申报建议。 +- **参考路径**：[TaxFilingAdvisor.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/TaxFilingAdvisor.ts) + +### **[BIZ_FIN_189] 异常低毛利订单强制拦截建议 (Low Margin) +- **风控收益**：作为最后一道防线，识别由于配置错误（如调价异常）导致的亏本订单。 +- **核心目标**：实现 `MarginProtector`，在订单对账阶段实时检测毛利率，并触发拦截。 +- **参考路径**：[MarginProtector.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/MarginProtector.ts) + +### **[BIZ_FIN_190] 供应商信用额度自动预警 (Credit Limit) +- **供应链收益**：预防由于欠款超过信用额度导致的采购中断。 +- **核心目标**：实现 `CreditMonitorService`，监控各供应商的已用额度与剩余额度。 +- **参考路径**：[CreditMonitorService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/CreditMonitorService.ts) + +### **[BIZ_FIN_191] 跨国转让定价合规性建议 (Transfer Pricing) +- **法律收益**：预防国际贸易中的反避税调查风险，合规规划全球利润分布。 +- **核心目标**：实现 `LegalTaxService`，监控大额跨境交易额，识别潜在合规审计风险。 +- **参考路径**：[LegalTaxService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/LegalTaxService.ts) + +### **[BIZ_FIN_192] 多平台提现手续费阶梯优化建议 (Payout Optimizer) +- **降本收益**：通过科学的提现时机与额度建议，降低平均提现手续费 10-20%。 +- **核心目标**：实现 `PayoutOptimizer`，基于平台阶梯费率模型建议最佳提现动作。 +- **参考路径**：[PayoutOptimizer.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/PayoutOptimizer.ts) + +### **[BIZ_FIN_193] 基于 AI 预测的年度财务预算生成 (Budgeting)** +- **战略收益**：从经验决策转向数据驱动的预算编排，提升资金分配效率。 +- **核心目标**：实现 `FinancialPlanner`，基于历史趋势自动生成明年的营收与成本预算草案。 +- **参考路径**：[FinancialPlanner.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/FinancialPlanner.ts) + +### **[BIZ_FIN_194] 高频取消订单导致的支付网关风险预警 (Gateway Risk)** +- **风控收益**：识别由于订单取消率异常波动导致的支付通道（PayPal/Stripe）封禁风险。 +- **核心目标**：实现 `PaymentRiskService`，监控 `cancellationRatio` 并触发网关保护建议。 +- **参考路径**：[PaymentRiskService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/PaymentRiskService.ts) + +### **[BIZ_FIN_195] 基于实时毛利的动态运费模板建议 (Shipping Optimizer)** +- **利润收益**：根据各目的地国家的实时物流成本与订单毛利，动态建议包邮门槛。 +- **核心目标**：实现 `DynamicShippingService`，计算最优 `freeShippingThreshold`。 +- **参考路径**：[DynamicShippingService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/DynamicShippingService.ts) + +### **[BIZ_FIN_196] 营销活动盈亏平衡点实时监控 (Campaign Health)** +- **决策收益**：秒级发现正在亏损的营销活动，防止广告预算的无效浪费。 +- **核心目标**：实现 `CampaignHealthService`，实时计算 `currentROAS` vs `breakEvenROAS`。 +- **参考路径**：[CampaignHealthService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/CampaignHealthService.ts) + +### **[BIZ_FIN_197] 供应商年度框架协议降本达成度审计 (Savings Audit)** +- **绩效收益**：量化采购团队的降本贡献，确保供应商框架协议的真实执行。 +- **核心目标**：实现 `SavingTrackerService`，对比 `base_price` 与 `actual_price` 计算真实降本。 +- **参考路径**：[SavingTrackerService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/SavingTrackerService.ts) + +### **[BIZ_FIN_198] 基于用户行为特征的恶意索赔拦截 (Claim Fraud)** +- **风控收益**：识别并拦截高频索赔的“职业薅羊毛”账户，保护租户利润空间。 +- **核心目标**：实现 `ClaimFraudService`，基于 `claimToOrderRatio` 自动识别欺诈风险。 +- **参考路径**：[ClaimFraudService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/ClaimFraudService.ts) + +### **[BIZ_FIN_199] 全球多币种资产负债表实时快照 (Balance Sheet)** +- **估值收益**：为租户提供秒级的资产负债全景，支持企业融资与决策。 +- **核心目标**：实现 `GlobalBalanceSheet`，实时汇总 Inventory Value、Payouts 与 Liabilities。 +- **参考路径**：[GlobalBalanceSheet.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/GlobalBalanceSheet.ts) + +### **[BIZ_FIN_200] 基于 AGI 的全自动审计与合规性自查 (AI Guard)** +- **合规收益**：最终合规防线，利用 AGI 遍历全量审计日志，识别任何潜在的财务违规行为。 +- **核心目标**：实现 `ComplianceAIGuard`，对敏感操作（如 DELETE/FORCE_REFUND）进行 AI 穿透式审计。 +- **参考路径**：[ComplianceAIGuard.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/ComplianceAIGuard.ts) + +### **[BIZ_OPS_01] 多平台订单实时同步与状态流转 (Order Sync)** +- **业务收益**：统一订单中枢，减少人工多后台操作时间 90%。 +- **核心目标**： + 1. **实时归集**：从 Amazon/AliExpress/Shopify 实时抓取并映射至统一订单模型。 + 2. **自动分账**：支付成功后自动触发 Owner/Manager 利润分配。 +- **参考路径**：[ConsumerOrderService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Trade/ConsumerOrderService.ts) + +### **[BIZ_FIN_23] 跨主权多资产实时结算网关 (Multi-Asset Settlement)** +- **金融收益**：支持法币与数字资产混合清算，降低跨境汇损 3-5%。 +- **核心目标**：构建去中心化结算协议，实现亚秒级跨租户资金对冲。 +- **参考路径**：[MultiAssetSettlementService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/MultiAssetSettlementService.ts) + +### **[BIZ_FIN_05] 全球发票自动化生成与合规引擎 (Auto-Invoicing)** +- **合规收益**：根据订单与目的地国家法律（VAT/GST）自动生成合规发票，减少人工开票成本。 +- **核心目标**：实现 `InvoicingService`，支持多国税率动态计算与 PDF/电子发票生成。 +- **参考路径**：[InvoicingService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/InvoicingService.ts) + +### **[BIZ_FIN_12] 实时现金流预测与资金调度 (Cashflow Forecasting)** +- **财务收益**：利用 AI 预测未来 30 天收支风险，自动优化资金分配。 +- **核心目标**：聚合 `cf_orders` (待结) 与 `cf_purchase_orders` (待付) 数据，生成风险评级。 +- **参考路径**：[CashflowForecastService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/CashflowForecastService.ts) + +### **[BIZ_FIN_14] 跨租户大宗商品价格对冲对账 (Commodity Hedging)** +- **避险收益**：为原材料敏感型租户提供大宗商品（油、金、钢）的价格对冲策略建议。 +- **核心目标**：实时监控大宗行情，跨租户执行虚拟对冲对账。 +- **参考路径**：[CommodityHedgingService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/CommodityHedgingService.ts) + +### **[BIZ_FIN_18] 跨租户大宗商品集中采购议价池 (Pool Sourcing)** +- **降本收益**：利用规模效应，自动合并跨租户的相似原材料采购需求，增强议价能力。 +- **核心目标**：建立 `cf_sourcing_pools`，支持“拼单”采购模式。 +- **参考路径**：[PoolSourcingService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/PoolSourcingService.ts) + +### **[BIZ_FIN_25] 主权财富基金与集体投资协议 (Sovereign Wealth Fund)** +- **生态收益**：允许租户将闲置利润投入生态基金，共享基础设施优化收益。 +- **核心目标**：基于 Shapley Value 算法模拟分红，实现生态内部资本循环。 +- **参考路径**：[SovereignWealthFundService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/SovereignWealthFundService.ts) + +--- + +## 🎨 4. 治理遥测与沉浸交互 (Domain: UX / CORE_TELE / LOGISTICS) + +### **[BIZ_SC_13] 供应商绩效自动评分模型 (Supplier Scoring Model)** +- **风控收益**：基于交付时效、质检合格率、价格波动等多维数据自动淘汰劣质供应商。 +- **核心目标**：建立 `cf_supplier_scores` 模型，为 `TradeService` 提供采购决策依据。 +- **参考路径**：[SupplierScoringService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Logistics/SupplierScoringService.ts) + +### **[BIZ_TRADE_14] 最后一公里配送成本优化模型 (Last-Mile Optimizer)** +- **效率收益**：利用 TSP 算法动态优化派送路径，降低末端物流成本 15%。 +- **核心目标**：基于包裹密度热力图实现智能排单。 +- **参考路径**：[LastMileOptimizerService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Logistics/LastMileOptimizerService.ts) + +### **[BIZ_TRADE_18] 全球物流拥堵预测与自适应绕路建议 (Congestion Failover)** +- **时效收益**：分钟级响应全球港口/枢纽拥堵，自动切换备选物流方案。 +- **核心目标**：监控 `cf_congestion_history`，在危机发生前实现自动路由迁移。 +- **参考路径**：[CongestionFailoverService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Logistics/CongestionFailoverService.ts) + +### **[BIZ_AUTO_03] 多渠道营销日历自动执行 (Marketing Calendar)** +- **增长收益**：消除人工多平台改价操作，实现全球大促“秒级”联动。 +- **核心目标**：自动化执行折扣、优惠券发放及库存锁定。 +- **参考路径**：[MarketingCalendarService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Marketing/MarketingCalendarService.ts) + +### **[BIZ_MKT_14] 社交媒体趋势实时对齐与选品反馈 (Social Pulse)** +- **爆款收益**：将 TikTok/Instagram 热门趋势词与 AGI 选品引擎对齐，发现蓝海商机。 +- **核心目标**：实现 `SocialPulseService`，支持多语种语义归并。 +- **参考路径**：[SocialPulseService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Marketing/SocialPulseService.ts) + +### **[BIZ_BILL_01] 企业配额与订阅计费中心 (Quota & Subscription Billing)** +- **业务收益**：建立稳定经常性收入模型，支持 TOB/TOC 双线商业化。 +- **技术规格**： + 1. **数据模型 (Table: `cf_tenant_quota`)**: + - `tenant_id` (PK), `seats_limit`, `shops_limit`, `nodes_limit`, `task_monthly_limit`, `ai_call_limit`. + 2. **计费 API**: + - `POST /api/billing/subscribe`: 激活套餐并重置配额。 + - `GET /api/billing/usage`: 获取当前租户的五维用量实时百分比。 +- **参考路径**：`server/src/domains/Billing/` + +### **[BIZ_CRM_10] 智能售后与客户成功中枢 (After-Sales & CSM)** +- **业务收益**：降低退款与纠纷成本，提升复购率与品牌评分。 +- **技术规格**： + 1. **状态机 (FSM)**: `PENDING_REVIEW -> AI_ANALYZING -> AUTO_APPROVED | MANUAL_INTERVENE -> RESOLVED`. + 2. **核心逻辑**: 对接 `ArbitrageService` 自动核算退款对净利的影响，若退款后 ROI 仍符合红线则由 AGI 自动放行。 +- **参考路径**：`server/src/domains/Customer/` + +### **[BIZ_INT_12] 企业集成网关 (SSO + Webhook + OpenAPI)** +- **业务收益**：缩短企业客户实施周期，提升交付标准化能力。 +- **技术规格**： + 1. **Webhook 事件总线**: 支持 `order.created`, `inventory.low`, `arbitrage.found` 等 10+ 事件。 + 2. **安全机制**: 采用 HMAC-SHA256 签名，Header 携带 `X-Crawlful-Signature`。 +- **参考路径**：`server/src/api/internal/` + +--- + +## 🎨 4. 治理遥测与沉浸交互 (Domain: UX / CORE_TELE) + +### BIZ_GOV_BEHAVIORAL_RISK: 租户行为风险监控 (Behavioral Risk) +- **ID**: `BIZ_GOV_09` +- **Owner**: AI-2 +- **Status**: ✅ `completed` (Batch 49) +- **Features**: + - `BehavioralRiskService.analyzePatterns`: 自动化模式分析 (撞库/高频/枚举). + - `RiskScoring`: 动态评分 (0-100) + 级别联动. + - `AGIKillSwitch`: 触发高危风险实时熔断. + +### BIZ_AUDIT_DATA_COMPLIANCE: 跨区域数据合规扫描 (Data Compliance) +- **ID**: `BIZ_AUDIT_DATA_COMPLIANCE` +- **Owner**: AI-2 +- **Status**: ✅ `completed` (Batch 49) +- **Features**: + - `DataComplianceService`: 实时扫描跨国/跨区域数据调用路径. + - `ComplianceMiddleware`: (TBD Integration with API routes). + +### BIZ_AUDIT_AGENT_TRACE: AI 代理轨迹审计 (Agent Trace) +- **ID**: `BIZ_AUDIT_14` +- **Owner**: AI-2 +- **Status**: ✅ `completed` (Batch 49) +- **Features**: + - `AgentTraceAuditService`: 全生命周期轨迹审计. + - `Reasoning Evidence`: 联动 `ExplainableAIService` 获取决策依据. + - `Audit存证`: 决策因果链路的持久化. + +### UX_XAI_01: AGI 决策可解释性看板 (XAI Dashboard) +- **用户收益**：建立人机信任，让商户看懂 AI 为何调价或选品。 +- **核心目标**：展示 AGI 决策因果链路 (Causal Chain) 与影响因子热力图。 +- **参考路径**：[DecisionExplainabilityEngine.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/ai/DecisionExplainabilityEngine.ts) + +### **[UX_VR_02] AGI 驱动的实时虚拟供应链数字孪生 (Digital Twin)** +- **交互收益**：可视化全球货流与仓储风险，实现“上帝视角”管理。 +- **核心目标**：利用 Three.js 渲染全球 4D 贸易流与海外仓动态热力图。 +- **参考路径**：`dashboard/src/pages/ar-3d/` + +### **[BIZ_INV_05] 分布式多仓库存实战同步 (Inventory)** +- **业务收益**：防止多平台超卖风险，优化跨仓调拨成本。 +- **技术规格**： + 1. **锁定机制**: 采用 Redis 分布式锁确保 `lockStock` 操作的原子性。 + 2. **跨仓调拨**: AI 根据 `InventoryRLService` 建议生成 `TRANSFER` 任务，自动更新 `cf_inventory` 的可用余量。 +- **参考路径**：`server/src/domains/Trade/InventoryRLService.ts` + +### **[BIZ_FIN_06] 全自动化利润对账引擎 (Recon)** +- **业务收益**：消除财务黑盒，实现每笔订单利润的精准勾稽。 +- **技术规格**： + 1. **三位一体勾稽**: 自动关联 `cf_order` (收入)、`cf_purchase_order` (成本)、`cf_logistics_route` (运费)。 + 2. **对账状态机**: `UNRECONCILED -> AUTO_MATCHED -> RECONCILED | DISCREPANCY`. +- **参考路径**：`server/src/domains/Finance/ReconciliationService.ts` + +### **[CORE_AI_50] 多模态 AGI 视觉寻源插件 (Visual Sourcing)** +- **战略收益**：通过图片直达源头厂家，提升寻源效率 500%。 +- **核心目标**：集成 1688 图片搜索 API，利用 CLIP 模型进行特征向量匹配，自动识别源头厂家。 +- **参考路径**：`server/src/services/SupplyChainService.ts` + +### **[BIZ_LOG_08] 全球物流轨迹实时遥测 (Tracking)** +- **业务收益**：提升买家信任度，降低因轨迹不明导致的纠纷率 40%。 +- **技术规格**： + 1. **4D 轨迹回传**: 实现 `LogisticsTrackingService`，支持对 `cf_order` 关联的运单号进行定时拉取。 + 2. **异常感知**: AI 自动识别“轨迹停滞”、“清关异常”等状态，并触发 `SovereignCrisisService` 预警。 +- **参考路径**：`server/src/domains/Logistics/LogisticTelemetryService.ts` + +### **[BIZ_MKT_15] KOL 达人营销全生命周期管理 (Campaign)** +- **业务收益**：标准化达人合作流程，ROI 提升 25%。 +- **技术规格**： + 1. **生命周期 FSM**: `IDENTIFIED -> OUTREACHED -> SAMPLE_SENT -> CONTENT_LIVE -> ROI_TRACKING`. + 2. **归因联动**: 自动关联 `KOLService` 中的成交数据，计算达人真实的带货转化率。 +- **参考路径**：`server/src/domains/Marketing/KOLService.ts` + +### **[BIZ_PROD_12] AI 商品全自动“清洗”与本地化 (Washer)** +- **业务收益**：极大降低新品上架成本，Listing 本地化质量提升 100%。 +- **技术规格**： + 1. **语义清洗**: 过滤掉原图/原标题中的非法字符、品牌 Logo 及无效关键词。 + 2. **多模态增强**: 利用 `VisionFactoryService` 自动生成符合目标市场审美（如：中东/东南亚风格）的营销图。 +- **参考路径**：`server/src/services/ProductService.ts` + +### **[CORE_SEC_45] 租户数据主权隔离门禁 (Isolation)** +- **安全收益**：从底层杜绝越权访问，确保租户数据主权绝对隔离。 +- **技术规格**： + 1. **隔离拦截器**: 实现 `MultiTenantCore.from(tenantId, table)` 模式，强制所有查询必须通过该门禁。 + 2. **所有权校验**: 提供 `ensureOwnership` 方法，在执行更新/删除前强制校验记录归属。 +- **落地代码**：[MultiTenantCore.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Tenant/MultiTenantCore.ts) + +### **[BIZ_GOV_20] 全量业务事件审计流水线 (Audit Log)** +- **治理收益**：满足企业级合规审计要求，100% 记录关键业务变更。 +- **技术规格**： + 1. **事件钩子**: 在 `core/runtime` 层级实现 `DomainEventBus`，自动捕获各 Domain 的变更。 + 2. **结构化存储**: 记录 `actor`, `action`, `resource`, `diff`, `timestamp` 四元组。 +- **参考路径**：`server/src/core/runtime/DomainRegistry.ts` + +### **[BIZ_TEN_03] 多租户标准交付与流程自动化 (Delivery)** +- **业务收益**：标准化交付流程，将专有化部署开通时间从 3 天降至 1 小时。 +- **技术规格**： + 1. **任务追踪**: 实现 `cf_delivery_tasks` 表，记录每个租户交付项（如：SSO 联送、数据库初始化）的完成状态。 + 2. **自动化 API**: `POST /api/v1/tenant/delivery/start` 触发异步交付流水线。 +- **参考路径**：`server/src/domains/Tenant/DeliveryTemplateService.ts` + +### **[BIZ_FIN_11] 智能税务筹划与最优申报路径 (Tax AI)** +- **业务收益**：自动识别最优税务结构（如 OSS/IOSS），平均降低跨境合规成本 15%。 +- **技术规格**： + 1. **税务建议 API**: `POST /api/v1/finance/tax/plan` 提交经营画像，返回 AGI 生成的税务建议。 + 2. **合规登记库**: 存储 `cf_tax_strategies`，支持多国税率动态更新。 +- **参考路径**：`server/src/domains/Finance/TaxPlanningService.ts` + +### **[BIZ_ECO_08] 自治危机管理与自愈协议 (Crisis)** +- **生态收益**：在黑天鹅事件发生时实现分钟级避险，保护商户资金安全。 +- **技术规格**： + 1. **熔断器集成**: 联动 `CongestionFailoverService`，在危机发生时自动执行 `UPDATE cf_order SET logistics_status = 'REROUTING'`。 + 2. **主权防御 API**: `GET /api/v1/biz/crisis/active` 返回当前全网受灾情况与自愈进度。 +- **参考路径**：`server/src/domains/Trade/SovereignCrisisService.ts` + +### **[CORE_ANL_03] 租户经营表现实时聚合中心 (Analytics)** +- **决策收益**：提供秒级经营遥测，支持从 $10W 营收下钻到单笔订单的证据链。 +- **技术规格**： + 1. **SQL 聚合**: 实现基于 `tenant_id` 的全量聚合查询（SUM Revenue, AVG ROI）。 + 2. **证据链下钻**: 联动 `AuditLogService` 还原 `found -> calculate -> review -> publish` 的完整证据链。 +- **参考路径**：`server/src/domains/Analytics/AnalyticsService.ts` + +### **[BIZ_MKT_20] AGI 广告管家与预算动态优化 (AdOps)** +- **业务收益**：将广告 ROI 提升 20% 以上，通过 AGI 自动分配各平台预算。 +- **技术规格**： + 1. **预算动态分配**: 联动 `ArbitrageAGIService`，根据实时转化率（TikTok vs FB）动态执行 `updateBudget`。 + 2. **自动创建计划**: AI 根据爆款预测结果，自动生成广告创意（联动 `AdCreativeService`）并推送到平台。 +- **参考路径**：`server/src/domains/Marketing/AdAutoService.ts` + +### **[CORE_ANL_05] 全业务多维经营报表中心 (Reporting)** +- **决策收益**：一站式获取经营全貌，自动识别亏损项并生成“决策周报”。 +- **技术规格**： + 1. **多维报表 API**: `GET /api/v1/analytics/reports` 支持按平台、SKU、时间维度聚合 ROI 与净利。 + 2. **AI 周报生成**: 利用 LLM 对本周经营数据（cf_order + cf_pixel_logs）进行归因分析，生成自然语言总结。 +- **参考路径**：`server/src/domains/Analytics/AnalyticsService.ts` + +### **[BIZ_CRE_01] 多模态 AI 创作工作台 (Creative)** +- **业务收益**：实现营销素材的“零人工”生产，TTS 转化率提升 40%，视频生成效率提升 10 倍。 +- **技术规格**： + 1. **TTS 集成**: 对接 Minimax API，支持 `voice_id` 选择、语速 (`speed`)、音调 (`pitch`) 参数控制。 + 2. **任务 FSM**: `PENDING -> PROCESSING -> COMPLETED | FAILED`。支持主图生成、详情图生成、视频翻译任务。 + 3. **存储模型**: `cf_creative_tasks` (记录任务参数与状态) + `cf_media_assets` (记录生成后的 URL 与元数据)。 +- **参考路径**：`server/src/domains/Creative/CreativeService.ts` + +### **[BIZ_REP_01] 全业务多维报表体系 (Reports)** +- **决策收益**：覆盖全业务链路监控，自动识别恶意订单与财务偏差。 +- **技术规格**： + 1. **报表矩阵**: 实现 Advertiser, GMV Max, Settlement, Malicious Order, Employee Log, Financial, Order, Material, Product, Dept 报表。 + 2. **数据勾稽**: 联动 `cf_order`, `cf_ad_stats`, `cf_settlement`, `cf_audit_log` 进行跨表聚合。 +- **参考路径**：`server/src/domains/Analytics/ReportService.ts` + +--- + +## 📜 历史规格存档 (Archived Specs - V26.0 and below) +*请查阅 Git 历史记录或对应版本的存档文档。* + +### **[BIZ_MKT_40] 多触点归因与利润分析 (Attribution Engine)** +- **业务收益**：识破虚假 ROAS，计算剔除自然单后的真实 LTV/CAC 比率，优化营销预算分配。 +- **核心目标**：实现 `MultiTouchAttributionService`，对比总订单流与广告点击流，计算 `trueROAS` 与 `organicRevenue`。 +- **参考路径**：[MultiTouchAttributionService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Marketing/MultiTouchAttributionService.ts) + +### **[BIZ_FIN_40] 基于 DID 的自治清算协议 (DID Settlement)** +- **金融收益**：利用分布式身份 (DID) 自动化品牌方、代运营与达人的三方自动分润，降低结算争议 95%。 +- **核心目标**：构建 `DIDSettlementService`，支持亚秒级清算证据链存证与多级分润逻辑。 +- **参考路径**：[DIDSettlementService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/DIDSettlementService.ts) + +### **[BIZ_LOG_20] 全球动态路径对冲与风险熔断 (Global Route Failover)** +- **时效收益**：在黑天鹅事件（如罢工、港口拥堵）发生时，自动切换最优路径并对冲物流成本上涨风险。 +- **核心目标**：升级 `LogisticsRoutingService`，支持多式联运动态对冲策略与实时成本监控。 +- **参考路径**：[DynamicRoutingFailoverService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Logistics/DynamicRoutingFailoverService.ts) + +### **[BIZ_INV_20] 强化学习驱动的全球库存平衡 (RL Inventory Balancing)** +- **库存收益**：自动决策跨仓调拨，最小化总持仓成本与缺货损失，提升库存周转率。 +- **核心目标**：完善 `InventoryRLOptimizerService`，接入多维成本评估模型与 RL 决策引擎。 +- **参考路径**：[InventoryRLOptimizerService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Trade/InventoryRLOptimizerService.ts) + +### **[BIZ_FIN_50] 跨主权多币种对冲对账引擎 (Multi-Currency Recon)** +- **避险收益**：自动化处理由于汇率剧烈波动导致的对账偏差，保护商户资金主权，减少财务人工核对成本 80%。 +- **核心目标**：实现 `MultiCurrencyHedgingReconService`，实时计算 `fx_drift` 并生成对冲对账单。 +- **参考路径**：[MultiCurrencyHedgingReconService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/MultiCurrencyHedgingReconService.ts) + +### **[BIZ_LOG_30] 最后一公里众包路由优化 (Crowdsourced Last-mile)** +- **韧性收益**：在黑天鹅事件导致传统物流商瘫痪时，自动调度众包资源，确保履约不中断。 +- **核心目标**：实现 `CrowdsourcedLogisticsService`，支持多点派送路径计算与成本动态核算。 +- **参考路径**：[CrowdsourcedLogisticsService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Logistics/CrowdsourcedLogisticsService.ts) + +### **[BIZ_TRADE_30] 自动化供应商产能预警 (Supplier Capacity Watch)** +- **交付收益**：提前感知供应商交期延误风险，通过 AGI 预测产能饱和度，自动建议切换备选源。 +- **核心目标**：实现 `SupplierCapacityWatchService`，监控 `backlog_ratio` 并生成风险预警报告。 +- **参考路径**：[SupplierCapacityWatchService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Trade/SupplierCapacityWatchService.ts) + +### **[BIZ_CSM_30] 智能争议仲裁建议 (Dispute Arbitration)** +- **效率收益**：自动化处理售后纠纷与退款争议，基于全链路证据链给出公正仲裁建议，降低客服工作量 70%。 +- **核心目标**：实现 `DisputeArbitrationService`，聚合订单、物流、支付全量数据生成仲裁书。 +- **参考路径**：[DisputeArbitrationService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Customer/DisputeArbitrationService.ts) + +### **[BIZ_TRADE_40] AGI 驱动的全球合规与制裁扫描 (Compliance Scan)** +- **合规收益**：自动化扫描 SKU 与收货地址，防止违反特定国家/地区的贸易禁令（如 OFAC 制裁、出口管制），避免高额罚款。 +- **核心目标**：实现 `TradeComplianceService`，集成全球合规库，提供实时风险评分。 +- **参考路径**：[TradeComplianceService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Trade/TradeComplianceService.ts) + +### **[BIZ_FIN_70] 基于 ZKP 的链上隐私信用证 (Private L/C)** +- **金融收益**：利用 ZKP 保护商业机密，同时向金融机构证明交易真实性，缩短 B2B 结算周期，提升资金周转率。 +- **核心目标**：实现 `SovereignPrivateLCService`，支持链上信用证生成与隐私存证验证。 +- **参考路径**：[SovereignPrivateLCService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/SovereignPrivateLCService.ts) + +### **[BIZ_LOG_50] 弹性多式联运自动对冲引擎 (Intermodal Failover)** +- **韧性收益**：当全球主航道发生黑天鹅事件时，自动计算并执行多式联运切换（如海转铁），最小化时效延误。 +- **核心目标**：实现 `IntermodalFailoverService`，支持动态路由成本核算与自动对冲方案生成。 +- **参考路径**：[IntermodalFailoverService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Logistics/IntermodalFailoverService.ts) + +### **[SOV_NET_02] 跨节点自治清算协议实现 (Cross-Node Settlement)** +- **网络收益**：实现 Hub 节点间的自动化利润分润与资金清算，构建去中心化的全球贸易价值网。 +- **核心目标**：实现 `CrossNodeSettlementService`，联动 `DIDSettlementService` 处理跨 Hub 的 DID 身份清算。 +- **参考路径**：[CrossNodeSettlementService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/CrossNodeSettlementService.ts) + +### **[SOV_NET_04] 跨节点争议自动仲裁转发 (Dispute Forwarding)** +- **信任收益**：在多节点贸易中，实现证据链的自动化路由与转发，支持跨节点的 AGI 联合仲裁。 +- **核心目标**：构建 `GlobalDisputeRouter`，支持证据链在不同主权节点间的安全传输与同步。 +- **参考路径**：[GlobalDisputeRouter.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Customer/GlobalDisputeRouter.ts) + +### **[BIZ_FIN_80] 跨主权贸易信用保险自动投保建议 (Trade Insurance)** +- **风险收益**：针对高价值跨国订单，基于供应商风险评分自动建议投保方案，降低坏账与货损风险。 +- **核心目标**：实现 `TradeInsuranceService`，提供自动化投保建议。 +- **参考路径**：[TradeInsuranceService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/TradeInsuranceService.ts) + +### **[BIZ_TRADE_50] 动态出口管制合规证书自动化生成 (Compliance Certificate)** +- **合规收益**：自动生成符合目的国要求的电子合规证书，确保顺畅通关。 +- **核心目标**：实现 `ComplianceCertificateService`，支持证书自动生成与 DID 签名。 +- **参考路径**：[ComplianceCertificateService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Trade/ComplianceCertificateService.ts) + +### **[BIZ_LOG_60] 绿色供应链碳信用交易撮合 (Carbon Credit Trading)** +- **绿色收益**：撮合碳抵扣额度购买，提升品牌绿色合规等级。 +- **核心目标**：实现 `CarbonCreditTradingService`，支持碳足迹抵扣撮合。 +- **参考路径**：[CarbonCreditTradingService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Logistics/CarbonCreditTradingService.ts) + +### **[BIZ_FIN_90] 跨主权多节点资金流动性自动预测 (Liquidity Forecast)** +- **资金收益**：预测全球贸易 Hub 节点的资金缺口，自动建议资金调拨，确保清算平滑。 +- **核心目标**：实现 `NodeLiquidityForecastService`，支持节点流动性预测。 +- **参考路径**：[NodeLiquidityForecastService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Finance/NodeLiquidityForecastService.ts) + +### **[BIZ_TRADE_60] 自动化供应链碳配额质押建议 (Carbon Pledge)** +- **金融收益**：允许租户质押碳抵扣额度以获取更优的采购账期。 +- **核心目标**：实现 `CarbonPledgeService`，支持碳配额质押逻辑。 +- **参考路径**：[CarbonPledgeService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Trade/CarbonPledgeService.ts) + +### **[BIZ_LOG_70] 众包物流配送员 DID 信用分级体系 (Courier Credit)** +- **履约收益**：建立基于 DID 的配送员信用分级，筛选优质众包资源，降低末端风险。 +- **核心目标**：实现 `CourierCreditService`，支持配送员信用分计算。 +- **参考路径**：[CourierCreditService.ts](file:///d:/trae_projects/crawlful-hub/server/src/domains/Logistics/CourierCreditService.ts) + +--- + +## 🛠️ 5. AGI 诊断与自省规范 (AGI Diagnostics & Self-Awareness) + +### **[CORE_DIAG_01] AGI 异常根因自省规范 (Self-Awareness Protocol)** +- **治理收益**：消除静默失败，提升系统自愈效率 90%，实现“问题即文档”。 +- **核心要求**： + 1. **强制 RCA (Root Cause Analysis)**：所有阻塞性问题必须输出 `CATEGORY/ROOT_CAUSE/MITIGATION` 三元组。 + 2. **分级上报**： + - `FATAL`：立即停止任务并记录阻塞路径，更新看板 `[ISSUE-AI-X]`。 + - `WARN`：记录降级路径（Fallback），继续执行非核心任务。 + 3. **自查清单 (Checklist)**： + - 是否存在 Context 缺失？（需 Read/Search） + - 是否存在逻辑冲突？（需 FSM 校验） + - 是否存在环境约束？（需 .env/Database 校验） +- **参考路径**：[.trae/rules/project_rules.md](file:///d:/trae_projects/crawlful-hub/.trae/rules/project_rules.md) + +--- +**规格维护者**：AI-1 (Kernel) | **当前版本**：V32.0 +**看板索引**：[collaboration-board.md](file:///d:/trae_projects/crawlful-hub/docs/governance/collaboration-board.md) diff --git a/docs/guides/non-saas-multi-tenant-checklist.md b/docs/guides/non-saas-multi-tenant-checklist.md new file mode 100644 index 0000000..c79486f --- /dev/null +++ b/docs/guides/non-saas-multi-tenant-checklist.md @@ -0,0 +1,42 @@ +# 非 SaaS 多租户实施清单 (V30.0) + +## 1. 实施要点 +- **数据独占**：每个租户拥有独立的 `tenant_id` 与加密盐。 +- **资源配额**：严格限制单个租户的并发 Worker 数量与算力开销。 + +## 2. 多租户隔离架构 + +### 2.1 数据层隔离 +| 层级 | 隔离策略 | 实现方式 | +|------|----------|----------| +| 数据库 | 逻辑隔离 | 所有表添加 tenant_id 索引列 | +| 表结构 | 租户专属表 | cf_{租户标识}_{业务表} (如需物理隔离) | +| Redis | 键名前缀 | `{tenantId}:{业务Key}` | + +### 2.2 应用层隔离 +- **TenantContext**：请求级别租户上下文 ThreadLocal 传递 +- **行级安全**：所有查询自动注入 `WHERE tenant_id = ?` 条件 +- **跨租户校验**：API 层验证操作权限与数据归属 + +### 2.3 资源配额管理 +| 资源类型 | 配额限制 | 熔断策略 | +|----------|----------|----------| +| API 并发 | 100 req/s/租户 | 超出返回 429 | +| Worker 并发 | 10 任务/租户 | 队列满拒绝 | +| 存储空间 | 10 GB/租户 | 定期清理日志 | + +## 3. 安全实施清单 +- [ ] 数据库连接池配置租户路由中间件 +- [ ] Redis 键空间隔离验证 +- [ ] 日志脱敏 (tenantId 脱敏处理) +- [ ] API 网关层租户识别 (Header: X-Tenant-ID) +- [ ] 跨租户漏洞渗透测试 + +## 4. 测试用例 +- [ ] 租户 A 无法访问租户 B 的数据 +- [ ] 超配额请求正确返回 429 错误 +- [ ] 租户删除后数据完全清理 + +--- +**版本**: V30.0 +**更新日志**: [AI-3 @ 2026-03-15] 补充多租户隔离架构与实施清单 diff --git a/docs/guides/server-readme.md b/docs/guides/server-readme.md new file mode 100644 index 0000000..1ba8c63 --- /dev/null +++ b/docs/guides/server-readme.md @@ -0,0 +1,82 @@ +# Crawlful Hub - Node.js 后端技术指南 (V30.0) + +## 1. 技术栈 +- **Runtime**: Node.js v20+ +- **Language**: TypeScript (Strict Mode) +- **Database**: MySQL 8.0 (Aliyun RDS) +- **Cache**: Redis 6.0 (Local) +- **ORM**: Knex.js +- **AI**: Gemini-3-Flash, CLIP, Sentiment Analysis + +## 2. 目录结构 +- `server/src/core/`: AGI 内核、算力调度、隐私审计。 +- `server/src/domains/`: 业务领域模型（Trade, Finance, Product, Logistics 等）。 +- `server/src/api/`: 外部与内部 API 路由。 +- `server/src/workers/`: 异步任务与爬虫任务。 + +## 3. 本地开发环境搭建 + +### 3.1 前置条件 +```bash +# 安装 Node.js v20+ +node -v # 应显示 v20.x.x + +# 安装 pnpm (推荐) +npm install -g pnpm + +# 安装 MySQL 8.0 (本地或 Docker) +docker run -d -p 3306:3306 -e MYSQL_ROOT_PASSWORD=root mysql:8.0 + +# 安装 Redis 6.0 +docker run -d -p 6379:6379 redis:6.0 +``` + +### 3.2 项目初始化 +```bash +# 安装依赖 +cd server +pnpm install + +# 复制环境变量配置 +cp .env.example .env +# 编辑 .env 配置数据库连接、Redis 等 + +# 运行数据库迁移 +pnpm migrate:latest + +# 启动开发服务器 +pnpm dev +``` + +### 3.3 常用命令 +| 命令 | 功能 | +|------|------| +| `pnpm dev` | 启动开发服务器 (热重载) | +| `pnpm build` | 编译 TypeScript | +| `pnpm start` | 生产环境启动 | +| `pnpm migrate:make` | 创建数据库迁移 | +| `pnpm seed:run` | 运行数据填充 | +| `pnpm lint` | 代码风格检查 | + +### 3.4 调试指南 +- **VS Code 调试**：配置 `.vscode/launch.json` 使用 Node.js debugger +- **日志级别**：通过 `LOG_LEVEL` 环境变量控制 (debug/info/warn/error) +- **API 测试**：启动后访问 `http://localhost:3000/api/health` 检查服务状态 + +## 4. 代码规范 +- **严格模式**：tsconfig.json 启用 `strict: true` +- **路径别名**：使用 `@/*` 引用 server/src 下的模块 +- **命名规范**： + - 文件：小写短横线 (kebab-case) + - 类/接口：大驼峰 (PascalCase) + - 变量/函数：小驼峰 (camelCase) + +## 5. 核心模块说明 +- **Core**: AGI 决策引擎、算力调度、隐私计算 +- **Domains**: 业务领域服务 (Trade/Finance/Product/Logistics) +- **API**: RESTful 接口层，含外部 API 与内部 API +- **Workers**: BullMQ 异步任务、Crawler 爬虫任务 + +--- +**版本记录**: V30.0 (AI-Native Overhaul) +**更新日志**: [AI-3 @ 2026-03-15] 补充本地开发环境搭建与常用命令 diff --git a/docs/guides/toc-early-stage-spec.md b/docs/guides/toc-early-stage-spec.md new file mode 100644 index 0000000..8845998 --- /dev/null +++ b/docs/guides/toc-early-stage-spec.md @@ -0,0 +1,51 @@ +# 前期业务与 ToC 功能架构规格书 (V30.0) + +## 1. 核心目标 +- **快速上线**：在 AGI 完全体演化完成前，提供高可用的 ToC 贸易加速基础。 +- **数据积累**：通过基础订单流积累 AGI 策略演化所需的先验数据。 + +## 2. 核心功能 +- **多平台连接器**：实现 Amazon/AliExpress 的基础订单与商品同步。 +- **ConsumerOrderService**：支持 TOC 订单的归集、分润与基础状态流转。 +- **基础选品雷达**：基于热销榜单的初级趋势分析。 + +## 3. 模块详细设计 + +### 3.1 多平台连接器 (Multi-Platform Connector) +| 模块 | 功能描述 | 状态 | +|------|----------|------| +| Amazon Connector | OAuth2 授权、订单拉取、ASIN 映射 | 待开发 | +| AliExpress Connector | 开放平台 API、SKU 同步 | 待开发 | +| 统一适配层 | 抽象 PlatformInterface，统一订单/商品模型 | 规划中 | + +### 3.2 订单归集服务 (ConsumerOrderService) +- **订单归集**：跨平台订单统一归集，按 tenantId 隔离 +- **分润计算**：基于订单利润的自动分润比例计算 +- **状态流转**：`PENDING` -> `CONFIRMED` -> `SHIPPED` -> `DELIVERED` -> `COMPLETED` + +### 3.3 选品雷达 (Product Radar) +- **热销榜单抓取**：Amazon Best Sellers、AliExpress 热销榜 +- **品类趋势分析**：基于销量增长率的品类热度计算 +- **价格带分析**：目标价格区间的竞品分布 + +## 4. API 端点设计 +| 方法 | 路径 | 功能 | +|------|------|------| +| GET | /api/v1/connector/platforms | 获取支持的平台列表 | +| POST | /api/v1/connector/sync/:platform | 触发平台数据同步 | +| GET | /api/v1/orders | 获取归集订单列表 | +| GET | /api/v1/orders/:id | 获取订单详情 | +| GET | /api/v1/radar/trending | 获取热销趋势 | + +## 5. 数据库设计 +- `cf_platform_connection`: 平台连接配置 (platform, credentials, status) +- `cf_consumer_order`: 归集订单表 (platform, platform_order_id, amount, status) +- `cf_product_trend`: 选品趋势数据 (platform, category, trend_score) + +## 6. 依赖关系 +- **前置依赖**：Knex.js, Redis (缓存), 平台 OAuth 凭证 +- **后续演进**：AGI 策略引擎接入、自动化采购路由 + +--- +**负责人**: AI-3 (Biz) | **看板索引**: [collaboration-board.md](../governance/collaboration-board.md) +**更新日志**: [AI-3 @ 2026-03-15] 补充模块详细设计与 API 端点 diff --git a/docs/maiteng-crawl-1773595163736.json b/docs/maiteng-crawl-1773595163736.json new file mode 100644 index 0000000..9ec3756 --- /dev/null +++ b/docs/maiteng-crawl-1773595163736.json @@ -0,0 +1,1133 @@ +{ + "crawlTime": "2026-03-15T17:19:23.731Z", + "menus": [ + { + "id": 1, + "text": "商品管理", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 2, + "text": "GMV MAX", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 3, + "text": "素材管理", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 4, + "text": "数据报表", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 5, + "text": "账号管理", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 6, + "text": "系统工具", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 7, + "text": "系统管理", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 8, + "text": "系统监控", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 9, + "text": "个人中心", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 10, + "text": "布局设置", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 11, + "text": "退出登录", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 12, + "text": "修改价格", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 13, + "text": "修改库存", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 14, + "text": "修改标题", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 15, + "text": "修改类目", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 16, + "text": "修改包装重量", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 17, + "text": "修改包装尺寸", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 18, + "text": "修改是否到货付款", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 19, + "text": "修改Seller SKU", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 20, + "text": "批量上架", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 21, + "text": "批量下架", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 22, + "text": "产品发布记录", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 23, + "text": "管理商品", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 24, + "text": "规则管理", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 25, + "text": "GMV MAX管理", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 26, + "text": "语音合成", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 27, + "text": "视频生成", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 28, + "text": "照片生成", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 29, + "text": "广告主报表", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 30, + "text": "GMV Max报表", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 31, + "text": "订单结算报表", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 32, + "text": "恶意订单", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 33, + "text": "员工日志", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 34, + "text": "财务账单报表", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 35, + "text": "订单报表", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 36, + "text": "素材报表", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 37, + "text": "商品报表", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 38, + "text": "部门分组报表", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 39, + "text": "平台授权", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 40, + "text": "工作店铺分配", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 41, + "text": "表单构建", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 42, + "text": "代码生成", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 43, + "text": "系统接口", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 44, + "text": "用户管理", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 45, + "text": "角色管理", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 46, + "text": "菜单管理", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 47, + "text": "部门管理", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 48, + "text": "岗位管理", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 49, + "text": "字典管理", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 50, + "text": "参数设置", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 51, + "text": "通知公告", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 52, + "text": "日志管理", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 53, + "text": "操作日志", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 54, + "text": "登录日志", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 55, + "text": "流量监控", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 56, + "text": "定时任务管理", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 57, + "text": "在线用户", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 58, + "text": "定时任务", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 59, + "text": "数据监控", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 60, + "text": "服务监控", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 61, + "text": "缓存监控", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 62, + "text": "缓存列表", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 63, + "text": "较大", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 64, + "text": "默认", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + }, + { + "id": 65, + "text": "稍小", + "element": {}, + "href": "", + "isExpanded": false, + "isCollapsed": false, + "hasSubmenu": false + } + ], + "pages": [ + { + "url": "https://e.mtkj2025.com/gmv/gmvmax", + "title": "麦腾智能管理平台", + "timestamp": "2026-03-15T17:19:23.727Z", + "pageElements": { + "buttons": [ + { + "id": 0, + "text": "", + "disabled": false + }, + { + "id": 1, + "text": "", + "disabled": false + }, + { + "id": 2, + "text": "搜索", + "disabled": false + }, + { + "id": 3, + "text": "重置", + "disabled": false + }, + { + "id": 4, + "text": "创建GMVMAX", + "disabled": false + }, + { + "id": 5, + "text": "批量绑定规则包", + "disabled": true + }, + { + "id": 6, + "text": "列配置", + "disabled": false + }, + { + "id": 7, + "text": "", + "disabled": false + }, + { + "id": 8, + "text": "今天", + "disabled": false + }, + { + "id": 9, + "text": "昨天", + "disabled": false + }, + { + "id": 10, + "text": "近3天", + "disabled": false + }, + { + "id": 11, + "text": "近7天", + "disabled": false + }, + { + "id": 12, + "text": "近30天", + "disabled": false + }, + { + "id": 13, + "text": "", + "disabled": true + }, + { + "id": 14, + "text": "", + "disabled": true + }, + { + "id": 15, + "text": "近一小时", + "disabled": false + }, + { + "id": 16, + "text": "今天", + "disabled": false + }, + { + "id": 17, + "text": "昨天", + "disabled": false + }, + { + "id": 18, + "text": "近7天", + "disabled": false + }, + { + "id": 19, + "text": "近30天", + "disabled": false + }, + { + "id": 20, + "text": "", + "disabled": false + }, + { + "id": 21, + "text": "", + "disabled": false + }, + { + "id": 22, + "text": "", + "disabled": false + }, + { + "id": 23, + "text": "", + "disabled": false + }, + { + "id": 24, + "text": "清空", + "disabled": false + }, + { + "id": 25, + "text": "确定", + "disabled": true + }, + { + "id": 26, + "text": "", + "disabled": false + }, + { + "id": 27, + "text": "", + "disabled": false + }, + { + "id": 28, + "text": "2026 年", + "disabled": false + }, + { + "id": 29, + "text": "3 月", + "disabled": false + }, + { + "id": 30, + "text": "", + "disabled": false + }, + { + "id": 31, + "text": "", + "disabled": false + }, + { + "id": 32, + "text": "此刻", + "disabled": false + }, + { + "id": 33, + "text": "确定", + "disabled": false + }, + { + "id": 34, + "text": "", + "disabled": false + }, + { + "id": 35, + "text": "", + "disabled": false + }, + { + "id": 36, + "text": "2026 年", + "disabled": false + }, + { + "id": 37, + "text": "3 月", + "disabled": false + }, + { + "id": 38, + "text": "", + "disabled": false + }, + { + "id": 39, + "text": "", + "disabled": false + }, + { + "id": 40, + "text": "此刻", + "disabled": false + }, + { + "id": 41, + "text": "确定", + "disabled": false + }, + { + "id": 42, + "text": "近一个小时", + "disabled": false + }, + { + "id": 43, + "text": "近三个小时", + "disabled": false + }, + { + "id": 44, + "text": "近6个小时", + "disabled": false + }, + { + "id": 45, + "text": "今天", + "disabled": false + }, + { + "id": 46, + "text": "昨天", + "disabled": false + }, + { + "id": 47, + "text": "近7天", + "disabled": false + }, + { + "id": 48, + "text": "近30天", + "disabled": false + }, + { + "id": 49, + "text": "近90天", + "disabled": false + }, + { + "id": 50, + "text": "", + "disabled": false + }, + { + "id": 51, + "text": "", + "disabled": false + }, + { + "id": 52, + "text": "", + "disabled": false + }, + { + "id": 53, + "text": "", + "disabled": false + }, + { + "id": 54, + "text": "清空", + "disabled": false + }, + { + "id": 55, + "text": "确定", + "disabled": true + }, + { + "id": 56, + "text": "今天", + "disabled": false + }, + { + "id": 57, + "text": "昨天", + "disabled": false + }, + { + "id": 58, + "text": "近3天", + "disabled": false + }, + { + "id": 59, + "text": "近7天", + "disabled": false + }, + { + "id": 60, + "text": "近30天", + "disabled": false + }, + { + "id": 61, + "text": "", + "disabled": false + }, + { + "id": 62, + "text": "", + "disabled": false + }, + { + "id": 63, + "text": "", + "disabled": false + }, + { + "id": 64, + "text": "", + "disabled": false + } + ], + "inputs": [ + { + "id": 0, + "type": "input", + "placeholder": "", + "name": "" + }, + { + "id": 1, + "type": "input", + "placeholder": "", + "name": "" + }, + { + "id": 2, + "type": "input", + "placeholder": "请输入活动名称", + "name": "" + }, + { + "id": 3, + "type": "input", + "placeholder": "请输入活动ID", + "name": "" + }, + { + "id": 4, + "type": "input", + "placeholder": "", + "name": "" + }, + { + "id": 5, + "type": "input", + "placeholder": "选择开始时间", + "name": "" + }, + { + "id": 6, + "type": "input", + "placeholder": "选择结束时间", + "name": "" + }, + { + "id": 7, + "type": "input", + "placeholder": "", + "name": "" + }, + { + "id": 8, + "type": "input", + "placeholder": "开始", + "name": "" + }, + { + "id": 9, + "type": "input", + "placeholder": "结束", + "name": "" + }, + { + "id": 10, + "type": "input", + "placeholder": "开始日期", + "name": "" + }, + { + "id": 11, + "type": "input", + "placeholder": "结束日期", + "name": "" + }, + { + "id": 12, + "type": "input", + "placeholder": "", + "name": "" + }, + { + "id": 13, + "type": "input", + "placeholder": "", + "name": "" + }, + { + "id": 14, + "type": "input", + "placeholder": "", + "name": "" + }, + { + "id": 15, + "type": "input", + "placeholder": "开始日期", + "name": "" + }, + { + "id": 16, + "type": "input", + "placeholder": "开始时间", + "name": "" + }, + { + "id": 17, + "type": "input", + "placeholder": "结束日期", + "name": "" + }, + { + "id": 18, + "type": "input", + "placeholder": "结束时间", + "name": "" + }, + { + "id": 19, + "type": "input", + "placeholder": "选择日期", + "name": "" + }, + { + "id": 20, + "type": "input", + "placeholder": "选择时间", + "name": "" + }, + { + "id": 21, + "type": "input", + "placeholder": "选择日期", + "name": "" + }, + { + "id": 22, + "type": "input", + "placeholder": "选择时间", + "name": "" + }, + { + "id": 23, + "type": "input", + "placeholder": "开始日期", + "name": "" + }, + { + "id": 24, + "type": "input", + "placeholder": "开始时间", + "name": "" + }, + { + "id": 25, + "type": "input", + "placeholder": "结束日期", + "name": "" + }, + { + "id": 26, + "type": "input", + "placeholder": "结束时间", + "name": "" + } + ], + "tables": [ + { + "id": 0, + "rowCount": 1 + }, + { + "id": 1, + "rowCount": 0 + }, + { + "id": 2, + "rowCount": 7 + }, + { + "id": 3, + "rowCount": 7 + }, + { + "id": 4, + "rowCount": 7 + }, + { + "id": 5, + "rowCount": 7 + }, + { + "id": 6, + "rowCount": 7 + }, + { + "id": 7, + "rowCount": 7 + }, + { + "id": 8, + "rowCount": 7 + }, + { + "id": 9, + "rowCount": 7 + } + ], + "filters": [] + } + } + ] +} \ No newline at end of file diff --git a/docs/maiteng-crawler.js b/docs/maiteng-crawler.js new file mode 100644 index 0000000..415f4c9 --- /dev/null +++ b/docs/maiteng-crawler.js @@ -0,0 +1,238 @@ +/** + * 麦腾后台菜单爬虫脚本 + * 用于自动探索和记录麦腾智能管理平台的所有菜单功能 + * + * 使用方法： + * 1. 在浏览器中打开麦腾后台并登录 + * 2. 打开浏览器开发者工具 (F12) + * 3. 切换到 Console 标签 + * 4. 复制粘贴此脚本并运行 + * 5. 等待探索完成后，复制输出的 JSON 数据 + */ + +class MaitengCrawler { + constructor() { + this.discoveredMenus = []; + this.discoveredPages = []; + this.visitedUrls = new Set(); + this.delayBetweenActions = 1000; // 毫秒 + } + + // 等待函数 + async wait(ms) { + return new Promise(resolve => setTimeout(resolve, ms)); + } + + // 获取当前页面的菜单结构 + getMenuStructure() { + const menus = []; + const menuItems = document.querySelectorAll('[role="menuitem"], .ant-menu-item, .menu-item'); + + menuItems.forEach((item, index) => { + const menuInfo = { + id: index, + text: item.textContent?.trim() || '', + element: item, + href: item.querySelector('a')?.href || '', + isExpanded: item.classList?.contains('expanded') || false, + isCollapsed: item.classList?.contains('collapsed') || false, + hasSubmenu: item.querySelector('ul, [role="menu"]') !== null + }; + + if (menuInfo.text) { + menus.push(menuInfo); + } + }); + + return menus; + } + + // 获取当前页面信息 + getCurrentPageInfo() { + return { + url: window.location.href, + title: document.title, + timestamp: new Date().toISOString(), + pageElements: this.getPageElements() + }; + } + + // 获取页面关键元素 + getPageElements() { + const elements = { + buttons: [], + inputs: [], + tables: [], + filters: [] + }; + + // 获取按钮 + document.querySelectorAll('button, [role="button"]').forEach((btn, idx) => { + elements.buttons.push({ + id: idx, + text: btn.textContent?.trim() || '', + disabled: btn.disabled || false + }); + }); + + // 获取输入框 + document.querySelectorAll('input, textarea, select').forEach((input, idx) => { + elements.inputs.push({ + id: idx, + type: input.tagName?.toLowerCase() || '', + placeholder: input.placeholder || '', + name: input.name || '' + }); + }); + + // 获取表格 + document.querySelectorAll('table').forEach((table, idx) => { + elements.tables.push({ + id: idx, + rowCount: table.querySelectorAll('tr')?.length || 0 + }); + }); + + return elements; + } + + // 尝试展开菜单 + async expandMenu(menuElement) { + try { + menuElement.click(); + await this.wait(this.delayBetweenActions); + return true; + } catch (error) { + console.log('展开菜单失败:', error); + return false; + } + } + + // 点击菜单项并记录页面 + async clickMenuItem(menuItem) { + try { + if (menuItem.href && !menuItem.href.startsWith('javascript:')) { + if (!this.visitedUrls.has(menuItem.href)) { + this.visitedUrls.add(menuItem.href); + window.location.href = menuItem.href; + await this.wait(3000); // 等待页面加载 + + const pageInfo = this.getCurrentPageInfo(); + this.discoveredPages.push(pageInfo); + console.log('发现新页面:', pageInfo.title); + + // 返回上一页继续探索 + window.history.back(); + await this.wait(this.delayBetweenActions); + } + } else if (menuItem.element) { + menuItem.element.click(); + await this.wait(this.delayBetweenActions); + + const pageInfo = this.getCurrentPageInfo(); + if (!this.visitedUrls.has(pageInfo.url)) { + this.visitedUrls.add(pageInfo.url); + this.discoveredPages.push(pageInfo); + console.log('发现新页面:', pageInfo.title); + } + } + return true; + } catch (error) { + console.log('点击菜单失败:', error); + return false; + } + } + + // 主爬虫函数 + async crawl() { + console.log('🚀 开始麦腾后台菜单爬虫...'); + console.log('当前页面:', window.location.href); + + // 获取初始菜单结构 + const initialMenus = this.getMenuStructure(); + console.log('发现菜单数量:', initialMenus.length); + this.discoveredMenus = initialMenus; + + // 尝试展开所有可展开的菜单 + for (const menu of initialMenus) { + if (menu.isCollapsed && menu.hasSubmenu) { + console.log('尝试展开菜单:', menu.text); + await this.expandMenu(menu.element); + } + } + + // 重新获取展开后的菜单结构 + const expandedMenus = this.getMenuStructure(); + console.log('展开后菜单数量:', expandedMenus.length); + this.discoveredMenus = expandedMenus; + + // 记录当前页面信息 + const currentPage = this.getCurrentPageInfo(); + this.discoveredPages.push(currentPage); + this.visitedUrls.add(currentPage.url); + + console.log('\n✅ 爬虫完成！'); + console.log('\n📊 发现的菜单:'); + this.discoveredMenus.forEach((menu, idx) => { + console.log(`${idx + 1}. ${menu.text} ${menu.isExpanded ? '[展开]' : menu.isCollapsed ? '[折叠]' : ''}`); + }); + + console.log('\n📄 发现的页面:'); + this.discoveredPages.forEach((page, idx) => { + console.log(`${idx + 1}. ${page.title} - ${page.url}`); + }); + + // 返回完整数据 + return { + menus: this.discoveredMenus.map(m => ({ + text: m.text, + href: m.href, + isExpanded: m.isExpanded, + isCollapsed: m.isCollapsed + })), + pages: this.discoveredPages.map(p => ({ + url: p.url, + title: p.title, + timestamp: p.timestamp, + buttons: p.pageElements.buttons.map(b => b.text), + inputs: p.pageElements.inputs.map(i => i.placeholder || i.name) + })) + }; + } + + // 导出数据为JSON + exportToJSON() { + const data = { + crawlTime: new Date().toISOString(), + menus: this.discoveredMenus, + pages: this.discoveredPages + }; + + const jsonStr = JSON.stringify(data, null, 2); + console.log('\n📋 完整JSON数据:'); + console.log(jsonStr); + + // 下载到文件 + const blob = new Blob([jsonStr], { type: 'application/json' }); + const url = URL.createObjectURL(blob); + const a = document.createElement('a'); + a.href = url; + a.download = `maiteng-crawl-${Date.now()}.json`; + a.click(); + URL.revokeObjectURL(url); + + console.log('\n💾 JSON文件已下载！'); + } +} + +// 使用示例 +console.log('=== 麦腾后台菜单爬虫 ==='); +console.log('请运行: const crawler = new MaitengCrawler(); const result = await crawler.crawl(); crawler.exportToJSON();'); + +// 自动运行（可选） +// (async () => { +// const crawler = new MaitengCrawler(); +// const result = await crawler.crawl(); +// crawler.exportToJSON(); +// })(); + diff --git a/docs/quality/frontend-delivery-standard.md b/docs/quality/frontend-delivery-standard.md new file mode 100644 index 0000000..607af95 --- /dev/null +++ b/docs/quality/frontend-delivery-standard.md @@ -0,0 +1,56 @@ +# 前端高完成度保障机制 (V30.0) + +## 1. 交付标准 + +### 1.1 UI 一致性 +- **对标 Ant Design 5.0**：组件使用、色彩体系、间距规范 +- **响应式适配**：桌面端 (≥1200px) / 平板端 (768-1199px) / 移动端 (<768px) +- **主题配置**：支持亮色/暗色主题切换，CSS 变量统一管理 +- **图标规范**：使用统一图标库 (Ant Design Icons) + +### 1.2 UX 透明度 +- **AGI 决策因果链路可视化**：每个 AI 建议必须展示决策原因 +- **加载状态全覆盖**：骨架屏 / Loading 动画 / 进度条 +- **错误处理**：统一的错误提示组件，支持重试机制 +- **空状态**：友好的空数据展示与引导操作 + +## 2. 评分维度 + +| 维度 | 权重 | 评分细则 | +|------|------|----------| +| 代码质量 | 30% | TypeScript 类型完整、无 any、单元测试覆盖率 >80% | +| 交互体验 | 30% | 响应速度 <200ms、动画流畅、Accessibility 合规 | +| AGI 透明度 | 40% | 因果链完整、可解释性高、人工可干预 | + +## 3. 交付检查清单 + +### 3.1 代码层面 +- [ ] TypeScript strict 模式无报错 +- [ ] ESLint/Prettier 检查通过 +- [ ] 组件 Props 定义完整，附带 JSDoc +- [ ] 无 hardcoded 字符串 (使用 i18n) + +### 3.2 交互层面 +- [ ] 所有按钮有点击反馈 (Hover/Active) +- [ ] 表单提交有 Loading 状态 +- [ ] 键盘导航完整 (Tab / Enter / Escape) +- [ ] 移动端 touch 事件适配 + +### 3.3 AGI 透明度层面 +- [ ] AI 建议展示 "为何建议" 展开项 +- [ ] 置信度/信心指数可视化 +- [ ] 支持人工 override 并记录原因 +- [ ] 决策日志可追溯 + +## 4. AGI 透明度评估标准 + +| 等级 | 描述 | 要求 | +|------|------|------| +| L1 | 基础展示 | 仅展示 AI 建议结果 | +| L2 | 因果展示 | 展示决策原因 (因果链) | +| L3 | 可干预 | 支持人工修改建议参数 | +| L4 | 可追溯 | 完整决策日志与审计 | + +--- +**标准制定**: AI-2 (Internal) +**更新日志**: [AI-3 @ 2026-03-15] 补充评分细则与交付检查清单 diff --git a/docs/quality/golive-redline-checklist.md b/docs/quality/golive-redline-checklist.md new file mode 100644 index 0000000..9ac44fe --- /dev/null +++ b/docs/quality/golive-redline-checklist.md @@ -0,0 +1,48 @@ +# 上线前红线清单 (GoLive) - V30.0 + +## 1. 安全红线 +- [ ] 环境变量 `.env` 是否已忽略提交 (检查 .gitignore) +- [ ] 敏感密钥是否已进入 Vault (AWS Secrets Manager / HashiCorp Vault) +- [ ] API 密钥是否通过环境变量注入，禁止硬编码 +- [ ] 跨租户数据隔离是否通过测试 +- [ ] SQL 注入防护是否生效 (参数化查询) + +## 2. 性能红线 +- [ ] 核心接口响应是否 `<200ms` (使用 APM 监控) +- [ ] 内存占用是否符合 `--max-old-space-size=4096` 限制 +- [ ] 数据库慢查询是否 `<100ms` (检查 EXPLAIN 输出) +- [ ] Redis 连接池是否配置合理 (推荐 20-50 连接) +- [ ] 文件上传大小限制是否生效 (推荐 <10MB) + +## 3. 业务红线 +- [ ] 利润率红线 (B2B < 15%, B2C < 20%) 是否强制生效 +- [ ] 多租户数据隔离是否通过穿透测试 +- [ ] 订单状态机流转是否符合规范 +- [ ] 金额计算是否使用 decimal 精度 + +## 4. 可用性红线 +- [ ] 健康检查接口 `/api/health` 是否返回 200 +- [ ] 关键依赖 (MySQL, Redis) 断连告警是否配置 +- [ ] 限流策略是否生效 (Rate Limit) +- [ ] 灰度发布机制是否就绪 + +## 5. 合规红线 +- [ ] GDPR/CCPA 数据删除接口是否实现 +- [ ] 操作日志是否完整记录 (审计追溯) +- [ ] 敏感日志是否脱敏处理 + +## 6. 自动化检查脚本 +```bash +# 安全检查 +grep -r "secret\|password\|key" --include="*.ts" server/src/ | grep -v ".env" + +# 性能检查 +curl -o /dev/null -s -w "%{time_total}s" http://localhost:3000/api/health + +# 数据库检查 +mysql -e "SHOW PROCESSLIST;" | wc -l # 检查连接数 +``` + +--- +**审计人**: AI-1 (Kernel) +**更新日志**: [AI-3 @ 2026-03-15] 补充自动化检查脚本与详细检查项 diff --git a/docs/quality/ux-field-acceptance-checklist.md b/docs/quality/ux-field-acceptance-checklist.md new file mode 100644 index 0000000..bcd9ace --- /dev/null +++ b/docs/quality/ux-field-acceptance-checklist.md @@ -0,0 +1,51 @@ +# 字段级 UX 验收清单 (V30.0) + +## 1. 关键字段要求 + +### 1.1 金额字段 +| 规范项 | 要求 | 示例 | +|--------|------|------| +| 币种符号 | 必须展示币种符号 (¥/$/€) | ¥1,234.56 | +| 小数位数 | 保留两位小数 | 1234.56 | +| 千分位 | 使用逗号分隔 | 1,234,567.00 | +| 负数展示 | 括号或红色标识 | (¥500.00) 或 -¥500.00 | + +### 1.2 状态字段 +| 状态类型 | 色彩语义 | 使用场景 | +|----------|----------|----------| +| Success | 绿色 #52C41A | 成功、完成、已发货 | +| Warning | 橙色 #FAAD14 | 待处理、即将过期 | +| Error | 红色 #F5222D | 失败、异常、已取消 | +| Info | 蓝色 #1890FF | 进行中、待确认 | +| Default | 灰色 #8C8C8C | 未开始、已关闭 | + +### 1.3 时间字段 +| 格式标准 | 示例 | 使用场景 | +|----------|------|----------| +| 全格式 | `YYYY-MM-DD HH:mm:ss` | 订单时间、操作记录 | +| 日期 | `YYYY-MM-DD` | 统计报表筛选 | +| 相对时间 | 3小时前 | 动态列表展示 | + +### 1.4 数值字段 +| 类型 | 规范 | 示例 | +|------|------|------| +| 百分比 | 带 % 符号，小数最多2位 | 85.50% | +| 数量 | 千分位分隔，无小数 | 1,234 件 | +| 重量 | 单位后置 | 12.5 kg | + +### 1.5 文本字段 +| 类型 | 规范 | 最大长度 | +|------|------|----------| +| 单行文本 | 溢出省略，Hover 显示完整 | 100 字符 | +| 多行文本 | 折叠展示，超出显示展开按钮 | 500 字符 | +| URL/链接 | 蓝色可点击，外部链接添加图标 | - | + +## 2. 通用 UX 规范 +- [ ] 所有可交互元素Hover状态有视觉反馈 +- [ ] 加载状态显示骨架屏或Loading动画 +- [ ] 空数据状态显示友好提示文案 +- [ ] 表单输入实时校验，错误信息明确 + +--- +**版本**: V30.0 +**更新日志**: [AI-3 @ 2026-03-15] 补充各字段类型的详细 UX 规范 diff --git a/docs/task-allocation.md b/docs/task-allocation.md new file mode 100644 index 0000000..9fd6827 --- /dev/null +++ b/docs/task-allocation.md @@ -0,0 +1,223 @@ +# 📋 文档清理与业务梳理任务分配 (V2.0) + +> 基于务实业务梳理后的任务分配 + +--- + +## 一、业务功能梳理结果 + +### ✅ 保留的核心功能 (12个) + +| 优先级 | 功能 | 文档 | +|--------|------|------| +| P0 | 订单工作台 | oms-workbench.md | +| P0 | 订单利润分析 | order-profit-analysis.md | +| P0 | 财务对账 | finance-recon.md | +| P0 | 库存老化分析 | inventory-aging-ui.md | +| P0 | 库存预测与补货 | inventory-forecast-replenishment.md | +| P1 | 审批中心 | approval-center.md | +| P1 | 多币种对账 | multi-currency-recon.md | +| P1 | 平台费用监控 | platform-fee-watcher-ui.md | +| P1 | 库存计划 | stock-planner-ui.md | +| P1 | 物流健康状态 | logistics-health-ui.md | +| P1 | 供应商产能监控 | supplier-capacity-watch.md | +| P1 | CRM客户管理 | crm-hub.md | + +### ❌ 建议删除的功能 (35个) + +| 类别 | 数量 | 示例 | +|------|------|------| +| AI相关 | 6个 | arbitrage-agi, inventory-rl-balancing, cashflow-prediction | +| 过度设计 | 18个 | did-settlement, tax-routing-optimizer, supplier-risk-radar | +| 非常规功能 | 11个 | carbon-credit-trading, crowdsourced-logistics, fx-hedging | + +--- + +## 二、AI 任务分配 + +### 🤖 AI-1：blueprints/ (不含 frontend-integration/) + design/ + +**负责目录**： +- `docs/blueprints/` (不含 frontend-integration/) +- `docs/design/` + +**任务清单**： + +| 任务ID | 任务内容 | 状态 | +|--------|----------|------| +| AI-1-01 | 扫描 blueprints/ 核心架构文档 | 待领取 | +| AI-1-02 | 扫描 design/ 设计文档 | 待领取 | +| AI-1-03 | 归档 v30-arch-optimization-plan.md | 待领取 | +| AI-1-04 | 更新核心架构文档，融入务实业务 | 待领取 | +| AI-1-05 | 更新 blueprints/ 目录索引 | 待领取 | + +--- + +### 🤖 AI-2：governance/ + benchmarks/ + +**负责目录**： +- `docs/governance/` +- `docs/benchmarks/` + +**任务清单**： + +| 任务ID | 任务内容 | 状态 | +|--------|----------|------| +| AI-2-01 | 扫描 governance/ 文档，清理AI相关内容 | 待领取 | +| AI-2-02 | 扫描 benchmarks/ 文档，精简为务实标杆 | 待领取 | +| AI-2-03 | 更新 governance/ 协作文档 | 待领取 | +| AI-2-04 | 更新 benchmarks/ 索引 | 待领取 | + +--- + +### 🤖 AI-3：frontend-integration/ + guides/ + quality/ + +**负责目录**： +- `docs/blueprints/frontend-integration/` +- `docs/guides/` +- `docs/quality/` + +**任务清单**： + +| 任务ID | 任务内容 | 状态 | +|--------|----------|------| +| AI-3-01 | **删除35个非务实功能文档** | 待领取 | +| AI-3-02 | **保留12个务实功能文档** | 待领取 | +| AI-3-03 | 更新 TEMPLATE.md 为务实版 | 待领取 | +| AI-3-04 | 扫描 guides/ 更新技术栈描述 | 待领取 | +| AI-3-05 | 扫描 quality/ 清理AI相关内容 | 待领取 | +| AI-3-06 | 更新 frontend-integration/ 索引 | 待领取 | + +**需删除的35个文档清单**： +``` +arbitrage-agi.md +inventory-rl-balancing.md +cashflow-prediction.md +multi-touch-attribution.md +sea-freight-advisor-ui.md +fraud-shared-ui.md +did-settlement.md +tax-routing-optimizer.md +supplier-risk-radar-ui.md +global-dispute-router-ui.md +dispute-arbitration-ui.md +crowdsourced-logistics.md +carbon-credit-trading-ui.md +carbon-pledge-ui.md +fx-hedging-risk.md +dynamic-routing-failover.md +circuit-breaker-ui.md +intermodal-failover-ui.md +cross-node-settlement-ui.md +private-lc-ui.md +node-liquidity-forecast-ui.md +node-resource-quota-ui.md +sandbox-roi-ui.md +reputation-perks-ui.md +style-war-ui.md +green-supply-chain-ui.md +compliance-certificate-ui.md +trade-compliance-ui.md +trade-insurance-ui.md +courier-credit-ui.md +biz-sup-15-sourcing-optimization.md +biz-mkt-30-dynamic-pricing.md +biz-gov-05-roi-dashboard.md +``` + +**需保留的12个文档清单**： +``` +oms-workbench.md +order-profit-analysis.md +finance-recon.md +inventory-aging-ui.md +inventory-forecast-replenishment.md +approval-center.md +multi-currency-recon.md +platform-fee-watcher-ui.md +stock-planner-ui.md +logistics-health-ui.md +supplier-capacity-watch.md +crm-hub.md +``` + +--- + +### 🤖 兜底AI：统一校验 + +| 任务ID | 任务内容 | 状态 | +|--------|----------|------| +| AI-4-01 | 验证所有删除/归档操作正确性 | 待领取 | +| AI-4-02 | 更新 doc-index.md 索引 | 待领取 | +| AI-4-03 | 校验文档引用链接 | 待领取 | +| AI-4-04 | 生成最终清理报告 | 待领取 | + +--- + +## 三、清理后文档数量 + +| 目录 | 清理前 | 清理后 | +|-----|-------|-------| +| frontend-integration | 47个 | 12个 | +| 总文档数 | 74个 | ~40个 | + +--- + +## 四、执行顺序 + +``` +第1轮（并行）： +┌─────────┐ ┌─────────┐ ┌─────────┐ +│ AI-1 │ │ AI-2 │ │ AI-3 │ +│ blueprints│ │ governance│ │frontend-│ +│ + │ │ + │ │integration│ +│ design │ │benchmarks│ │ + guides│ +└─────────┘ └─────────┘ │ + quality│ + └─────────┘ + +第2轮： +┌─────────┐ +│ 兜底AI │ → 统一校验 + 更新索引 +└─────────┘ +``` + +--- + +## 五、核心业务模块 + +清理后保留的核心业务模块： + +``` +1. 订单管理 (OMS) + - 订单工作台 + - 订单利润分析 + - 审批中心 + +2. 财务管理 (FIN) + - 财务对账 + - 多币种对账 + - 平台费用监控 + +3. 库存管理 (WMS) + - 库存老化分析 + - 库存预测与补货 + - 库存计划 + +4. 供应商管理 (SCM) + - 供应商产能监控 + +5. 客户关系 (CRM) + - CRM客户管理 +``` + +--- + +## 开始执行 + +请在 Trae 中创建 3 个新的 SOLO 窗口，分别分配给 AI-1、AI-2、AI-3。 + +**AI-1 领取**: blueprints/ + design/ 核心架构清理 + +**AI-2 领取**: governance/ + benchmarks/ 治理文档清理 + +**AI-3 领取**: frontend-integration/ + guides/ + quality/ **删除35个文档 + 保留12个文档**