docs: 新增V30.0版本相关设计文档与指南

新增服务器启动文档、设计说明书、风险清单等核心文档补充前端集成蓝图、多租户实施清单、上线红线检查清单添加质量保障文档与早期业务规格书
2026-03-16 01:31:26 +08:00
commit 6759d47de4
74 changed files with 9310 additions and 0 deletions
--- a/docs/blueprints/arch-overview-v30.md
+++ 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
--- a/docs/blueprints/archive/arch-freeze-v30.md
+++ 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
--- a/docs/blueprints/archive/v30-arch-optimization-plan.md
+++ 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
--- a/docs/blueprints/frontend-architecture.md
+++ 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<UserState>((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
--- a/docs/blueprints/frontend-integration/TEMPLATE.md
+++ 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 视图）。
--- a/docs/blueprints/frontend-integration/approval-center.md
+++ 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.
--- a/docs/blueprints/frontend-integration/biz-gov-05-roi-dashboard.md
+++ 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] 确保在多租户环境下，数据隔离边界绝对严密。
--- a/docs/blueprints/frontend-integration/biz-mkt-30-dynamic-pricing.md
+++ 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 叙述长文本能优雅折叠。
--- a/docs/blueprints/frontend-integration/biz-sup-15-sourcing-optimization.md
+++ 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/年）需有特殊高亮动画。
--- a/docs/blueprints/frontend-integration/carbon-credit-trading-ui.md
+++ 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)
+- [ ] 碳信用池数据的准实时性核对。
+- [ ] 碳抵消成本的财务对账报表。
+- [ ] 导出包含交易证明的绿色合规证书。
--- a/docs/blueprints/frontend-integration/carbon-pledge-ui.md
+++ 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)
+- [ ] 碳信用资产的锁定与释放逻辑界面。
+- [ ] 账期变动在财务模块的实时映射。
+- [ ] 导出包含绿色金融贡献的租户年度审计报告。
--- a/docs/blueprints/frontend-integration/cashflow-prediction.md
+++ 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` 展示可申请的贷款额度建议。
--- a/docs/blueprints/frontend-integration/circuit-breaker-ui.md
+++ 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 级别告警。
--- a/docs/blueprints/frontend-integration/compliance-certificate-ui.md
+++ 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 证书。
--- a/docs/blueprints/frontend-integration/courier-credit-ui.md
+++ 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)
+- [ ] 信用分变动的历史趋势曲线图。
+- [ ] 恶意差评的信用申诉处理界面。
+- [ ] 导出包含信用背景的配送员准入清单。
--- a/docs/blueprints/frontend-integration/crm-hub.md
+++ 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.
--- a/docs/blueprints/frontend-integration/cross-node-settlement-ui.md
+++ 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)
+- [ ] 跨节点网络延迟的实时监控。
+- [ ] 节点间身份握手证书的有效性校验。
+- [ ] 导出包含多节点路径的全球财务汇总。
--- a/docs/blueprints/frontend-integration/crowdsourced-logistics.md
+++ 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 的推送通知。
--- a/docs/blueprints/frontend-integration/did-settlement.md
+++ 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 身份的实名/实体认证校验。
+- [ ] 大额清算的二次确认机制。
+- [ ] 导出加密格式的清算审计流水。
--- a/docs/blueprints/frontend-integration/dispute-arbitration-ui.md
+++ 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)。
--- a/docs/blueprints/frontend-integration/dynamic-routing-failover.md
+++ 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 轨迹。
--- a/docs/blueprints/frontend-integration/finance-recon.md
+++ 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.
--- a/docs/blueprints/frontend-integration/fraud-shared-ui.md
+++ 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)。
+- [ ] 按钮防误触：拉黑操作需二次确认。
+- [ ] 举报来源匿名化处理。
--- a/docs/blueprints/frontend-integration/fx-hedging-risk.md
+++ 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%，预计损耗金额”。
--- a/docs/blueprints/frontend-integration/global-dispute-router-ui.md
+++ 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)。
+- [ ] 不同国家/地区仲裁法规的合规性提示。
+- [ ] 导出加密格式的跨节点仲裁决定书。
--- a/docs/blueprints/frontend-integration/green-supply-chain-ui.md
+++ 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)
+- [ ] 碳足迹计算模型的参数可配置界面。
+- [ ] 碳中和路径的长期跟踪看板。
+- [ ] 导出包含详细证据链的绿色供应链报告。
--- a/docs/blueprints/frontend-integration/intermodal-failover-ui.md
+++ 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)
+- [ ] 实时获取全球航道拥堵数据。
+- [ ] 支持针对大批量订单的一键批量切换。
+- [ ] 导出包含多式联运切换路径的物流报告。
--- a/docs/blueprints/frontend-integration/inventory-aging-ui.md
+++ 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)
--- a/docs/blueprints/frontend-integration/inventory-forecast-replenishment.md
+++ 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 “仓储成本增加额”。
--- a/docs/blueprints/frontend-integration/logistics-health-ui.md
+++ 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)
--- a/docs/blueprints/frontend-integration/membership-ltv-ui.md
+++ 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 预测报告的客户名单。
--- a/docs/blueprints/frontend-integration/multi-currency-recon.md
+++ 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）。
+- [ ] 汇损金额的货币格式化校验。
+- [ ] 导出包含汇率路径的对账明细。
--- a/docs/blueprints/frontend-integration/multi-touch-attribution.md
+++ 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 格式的归因分析报告。
--- a/docs/blueprints/frontend-integration/node-liquidity-forecast-ui.md
+++ 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)
+- [ ] 跨节点资金到账的实时追踪。
+- [ ] 调拨费用的动态核算。
+- [ ] 导出包含流动性分析的全球财务月报。
--- a/docs/blueprints/frontend-integration/node-resource-quota-ui.md
+++ 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%）。
+- [ ] 临时配额申请的自动化审批工作流。
+- [ ] 导出包含跨节点资源贡献的年度技术审计报告。
--- a/docs/blueprints/frontend-integration/oms-workbench.md
+++ 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.
--- a/docs/blueprints/frontend-integration/order-profit-analysis.md
+++ 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/单）。
--- a/docs/blueprints/frontend-integration/platform-fee-watcher-ui.md
+++ 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)
--- a/docs/blueprints/frontend-integration/private-lc-ui.md
+++ 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 证明的信用证正本。
--- a/docs/blueprints/frontend-integration/reputation-perks-ui.md
+++ 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)
+- [ ] 支持权益变动的实时消息推送通知。
+- [ ] 权益详情与计费模块、流量分配模块的最终一致性校验。
+- [ ] 导出包含声誉权益贡献的节点经营分析报告。
--- a/docs/blueprints/frontend-integration/sandbox-roi-ui.md
+++ 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)。
--- a/docs/blueprints/frontend-integration/sea-freight-advisor-ui.md
+++ 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)
--- a/docs/blueprints/frontend-integration/stock-planner-ui.md
+++ 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 提供兜底预测逻辑提示。
--- a/docs/blueprints/frontend-integration/style-war-ui.md
+++ 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)
--- a/docs/blueprints/frontend-integration/supplier-capacity-watch.md
+++ 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 延迟）。
+- [ ] 备选源的产能余量实时检查。
+- [ ] 导出包含风险预测的采购报告。
--- a/docs/blueprints/frontend-integration/supplier-risk-radar-ui.md
+++ 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)
--- a/docs/blueprints/frontend-integration/tax-routing-optimizer.md
+++ 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 延迟）。
+- [ ] 货币转换的实时汇率应用。
+- [ ] 导出包含税务路径选择理由的财务报表。
--- a/docs/blueprints/frontend-integration/trade-compliance-ui.md
+++ 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 类别的分级合规检查。
+- [ ] 导出包含详细证据链的合规审计报告。
--- a/docs/blueprints/frontend-integration/trade-insurance-ui.md
+++ 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)
+- [ ] 供应商风险评分的实时展示。
+- [ ] 投保成功后的电子保单下载。
+- [ ] 导出包含投保成本的利润核算报表。
--- a/docs/blueprints/global-business-blueprint.md
+++ 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
--- a/docs/blueprints/js-fullstack-architecture.md
+++ 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<OrderState>((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<Order[]>('/api/v1/orders', { params }),
+  });
+};
+
+export const useCreateOrder = () => {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (data: CreateOrderDTO) => 
+      request<Order>('/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<any>[];
+  providers: Type<any>[];
+  entities: Type<any>[];
+  routes: RouteConfig[];
+}
+
+// 动态模块加载器
+export class ModuleLoader {
+  private modules: Map<string, ModuleConfig> = new Map();
+  
+  async registerModule(config: ModuleConfig): Promise<void> {
+    this.modules.set(config.name, config);
+  }
+  
+  async loadModulesFromPath(path: string): Promise<void> {
+    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<AuthToken>;
+  refreshToken(token: AuthToken): Promise<AuthToken>;
+  
+  // 商品
+  fetchProducts(params: ProductQueryParams): Promise<Product[]>;
+  publishProduct(product: Product): Promise<string>;
+  
+  // 订单
+  fetchOrders(params: OrderQueryParams): Promise<Order[]>;
+  fulfillOrder(orderId: string, tracking: Tracking): Promise<void>;
+}
+
+// 插件注册
+@Injectable()
+export class PluginRegistry {
+  private plugins: Map<string, IPlatformPlugin> = 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<any> {
+    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  
+**状态**：已优化