海妈家电商 AI 产品技术文档

核心设计思想

规则基线AI 增强人工复核过程留痕失败可回退

不是让大模型直接替代业务负责人，而是把 AI 放在“信息提取、风险识别、建议生成、证据整理”环节，把退款、降价、加量、录用等高风险动作保留给责任人。

产品闭环

组件职责与版本

端到端时序

三个应用均为 Dify Workflow 模式，DSL 版本 0.6.0，当前结构为 Start → Python Code → End。这样可以先保证规则稳定和输出结构固定，再渐进加入知识检索与 LLM。

Dify 调用协议

POST http://host.docker.internal:8083/v1/workflows/run
Authorization: Bearer <app-api-key>
Content-Type: application/json

{
  "inputs": {
    "ticket_id": "CS-20260714-E2E",
    "platform": "天猫",
    "issue": "质量售后",
    "summary": "同款 SKU 第 3 起掉色投诉",
    "same_sku_recent_count": 3,
    "overdue": "是"
  },
  "response_mode": "blocking",
  "user": "haimajia-n8n"
}

n8n 使用每个应用独立的 Header Auth 凭据，避免三个应用共用同一密钥。返回值从 data.outputs 读取，并保留 workflow_run_id 与耗时。

当前实现与目标实现

每条工作流共 13 个节点，包含一条本地手动测试支路和一条正式 Webhook 端到端支路。三条流程结构一致，只替换输入字段、FastAPI 地址、Dify 凭据和 Baserow 日志摘要。

正式 Webhook 支路

手动支路

异常字段包含 backend_status、dify_status、logging_status、errors[]、failed_node、error_code、retryable 和上游 HTTP 状态。

三条工作流配置

Baserow 通过 host.docker.internal:8081 访问，同时设置 Host: localhost:8081，适配本机 Baserow Caddy 的站点域名校验。

FastAPI 接口总表

Webhook 请求示例

POST http://127.0.0.1:5678/webhook/haimajia/customer-service-risk
Content-Type: application/json

{
  "request_id": "customer-550e8400-e29b-41d4-a716-446655440000",
  "ticket_id": "CS-20260714-E2E",
  "platform": "天猫",
  "issue": "质量售后",
  "summary": "同款SKU第3起掉色投诉，当前工单已超时",
  "same_sku_recent_count": 3,
  "overdue": "是"
}

POST http://127.0.0.1:5678/webhook/haimajia/product-opportunity
Content-Type: application/json

{
  "request_id": "product-550e8400-e29b-41d4-a716-446655440000",
  "sku": "HMJ-TZ-2607-BL-140",
  "product_name": "男童速干运动套装",
  "ctr": 5.8,
  "cvr": 4.6,
  "margin": 31.2,
  "return_rate": 8.4,
  "stock_days": 16
}

POST http://127.0.0.1:5678/webhook/haimajia/recruiting-assessment
Content-Type: application/json

{
  "request_id": "recruit-550e8400-e29b-41d4-a716-446655440000",
  "job_key": "ai",
  "job_name": "AI应用工程师",
  "resume_text": "脱敏候选人具备 Python、FastAPI、API、RAG、Dify 与工作流交付经验。"
}

{
  "request_id": "customer-550e8400-e29b-41d4-a716-446655440000",
  "idempotent_replay": false,
  "backend_result": { "score": 98, "risk_label": "高" },
  "dify_outputs": { "risk_level": "高", "risk_score": 98 },
  "backend_status": "succeeded",
  "dify_status": "succeeded",
  "logging_status": "succeeded",
  "integration_status": "succeeded",
  "http_status": 200,
  "errors": [],
  "dify_workflow_run_id": "...",
  "dify_elapsed_time_ms": 1200,
  "human_review_required": true,
  "decision_boundary": "关键动作必须由责任人确认。"
}

FastAPI 幂等处理

处理中状态有 5 分钟超时恢复，避免进程异常结束后请求永久卡死。招聘流程仅保存请求哈希和分析结果，不把简历正文写入运行摘要。

部分成功返回示例

HTTP/1.1 207 Multi-Status
{
  "request_id": "product-550e8400-e29b-41d4-a716-446655440000",
  "backend_status": "succeeded",
  "dify_status": "failed",
  "logging_status": "succeeded",
  "integration_status": "partial_success",
  "backend_result": { "score": 88, "tier": "潜力款" },
  "dify_outputs": null,
  "errors": [{
    "stage": "dify",
    "code": "DIFY_REQUEST_FAILED",
    "message": "Dify 请求失败",
    "http_status": 400,
    "retryable": false
  }],
  "human_review_required": true
}

Baserow 回写接口

POST http://host.docker.internal:8081/api/database/rows/table/861/?user_field_names=true
Authorization: Token <baserow-token>
Host: localhost:8081
Content-Type: application/json

{
  "运行编号": "customer-550e8400-e29b-41d4-a716-446655440000",
  "应用编码": "customer_service",
  "触发来源": "n8n_dify_webhook",
  "业务记录": "CS-20260714-E2E",
  "输入摘要": "天猫/质量售后：同款SKU第3起掉色投诉",
  "输出摘要": "succeeded；高风险 98 分；立即人工接管...",
  "风险等级": "高",
  "是否人工审核": "是",
  "运行状态": "success",
  "耗时毫秒": "1200",
  "创建时间": "2026-07-14T10:00:00+08:00"
}

SQLite：本地业务数据底座

数据库启用 WAL；初始化使用 CREATE TABLE IF NOT EXISTS 和 INSERT OR IGNORE，保证重复启动不覆盖已有数据。关键查询使用参数占位符，表名与字段名使用代码白名单。

Baserow：业务人员可读的数据与审计层

为什么同时保留 SQLite 和 Baserow？

生产安全路线

交付包命令

# 必须使用项目 .venv，democtl 会初始化数据、启动/复用服务并检查依赖
cd /Users/hejunkai/工作中枢/01_AI工具链/Codex/与chatGPT联动/haimajia-ai-demo-suite
scripts/democtl.sh start
scripts/democtl.sh status
scripts/democtl.sh smoke
scripts/democtl.sh logs
scripts/democtl.sh stop

Python 项目固定使用根目录 .venv，当前依赖为 FastAPI 0.116.1 与 Uvicorn 0.35.0；不使用系统全局 Python。

浏览器验收入口：http://127.0.0.1:8787/ops.html。页面通过 /api/readiness 检查核心依赖，并展示 SQLite 计数和最近 FastAPI 留痕。

运行时配置

n8n 容器关键配置

已验证结果

目前缺失的可观测能力

• 已有 request_id，但缺少集中日志中对 correlation_id 的统一索引和搜索界面。
• 缺少 Prometheus 指标、Grafana 看板、结构化集中日志和告警阈值。
• 缺少业务 SLA：成功率、P95 延迟、Dify 成本、人工接管率、建议采纳率。

优先级建议

3 分钟版本

10 分钟讲解顺序

1. 业务问题：多平台信息分散、人工判断口径不一、动作缺少留痕。
2. 产品拆分：客服降风险、商品提经营质量、招聘提信息整理效率。
3. 架构分层：体验层、n8n 编排层、Dify 智能层、FastAPI 业务层、数据审计层。
4. 核心逻辑：讲一个公式，建议讲商品评分，因为能体现增长与利润/退货/库存约束。
5. 工作流：讲清 Dify 管智能应用，n8n 管跨系统；演示 Webhook → FastAPI → Dify → Baserow。
6. 工程细节：Pydantic、SQLite WAL、request_id + SHA-256 幂等、加密 Credentials、最小权限 Token、招聘正文不落日志。
7. 诚实边界：当前是规则版 PoC、没有真实平台数据、没有自动高风险动作。
8. 演进路线：先可靠性和真实数据，再上 RAG/LLM，而不是一开始堆模型。

最值得强调的技术取舍