MBE 营销系统调试指南

基于 MBE SDK 开发的营销自动化系统，包含落地页生成、智能咨询、内容创作、销售流程等。

一、架构概览

营销 API (marketing_events.py)
    ├── /api/marketing/landing-page/ai-designed  → landing_page_generator.py
    ├── /api/marketing/chat                      → mbe_client.ask_expert
    ├── /api/marketing/lead                      → 线索收集
    ├── /api/marketing/events                    → 营销事件
    └── ...

mbe_client.py (MBE SDK 封装)
    └── ask_expert() → knowledge.expert_router.get_expert_router().route_and_answer()

核心依赖：knowledge.expert_router 位于 private/core/src/knowledge/expert_router.py，需正确配置 PYTHONPATH。

二、环境准备

2.1 PYTHONPATH（必须）

$env:PYTHONPATH = "private\platform\src;shared\src;private\core\src"

2.2 基础服务（完整功能需要）

• PostgreSQL：数据库（用于存储、用户等）
• Redis：事件存储、工作流分发

2.3 可选环境变量

三、调试方式

3.1 使用调试脚本（推荐）

cd d:\Mises\mbe-monorepo
$env:PYTHONPATH = "private\platform\src;shared\src;private\core\src"
python scripts/debug_marketing.py --all

选项：

• --mbe-client：测试 ask_expert（MBE 专家调用）
• --landing：测试落地页生成
• --chat：测试营销聊天逻辑
• --list-experts：列出可用专家
• --all：运行全部测试

3.2 启动完整服务

.\scripts\run_marketing.ps1

• 端口：8001
• 落地页：http://127.0.0.1:8001/
• API 文档：http://127.0.0.1:8001/docs

3.3 极简 standalone（无 DB/Redis/MBE）

.\scripts\run_marketing.ps1 -Standalone

• 端口：8002
• 仅模板预览，秒级启动

3.4 Docker 开发环境

docker-compose -f docker-compose.dev.yml up

• API：http://localhost:8000
• 支持热重载

四、API 调试示例

4.1 落地页生成（GET）

GET http://127.0.0.1:8001/api/marketing/landing-page/ai-designed?keywords=MBE&target_audience=企业决策者

4.2 落地页生成（POST，创意专家）

POST /api/marketing/landing-page/generate
Content-Type: application/json

{
  "keywords": "MBE 米塞斯行为引擎",
  "target_audience": "企业决策者",
  "selling_points": "AI 驱动、智能决策"
}

4.3 营销聊天

POST /api/marketing/chat
Content-Type: application/json

{
  "question": "MBE 企业版有什么功能？",
  "user_type": "enterprise",
  "user_id": "marketing_anon"
}

4.4 专家映射

GET http://127.0.0.1:8001/api/marketing/mapping

五、常见问题排查

5.1 ask_expert 失败 / 超时

• 原因：ExpertRouter 初始化慢（加载 MIRAS 嵌入模型等），或 LLM 不可用
• 处理：
  1. 检查 knowledge.expert_router 能否导入：from knowledge.expert_router import get_expert_router
  2. 落地页可先用 MBE_LANDING_MODE=template 快速预览
  3. 落地页有 5 秒超时，超时后自动降级为模板

5.2 list_experts 返回空或报错

• 已修复：mbe_client.list_experts 此前将 ExpertProfile 当作 dict 使用 .get()，已改为 getattr(cfg, "name", eid)
• 若仍异常，检查 router.experts 是否已加载（需先调用过一次 get_expert_router()）

5.3 模块导入失败

• 确认 PYTHONPATH 包含：private/core/src、shared/src、private/platform/src
• 工作目录应为 monorepo 根目录

5.4 落地页显示「模板预览」横幅

• 正常：当 MBE_LANDING_MODE=template 或 MBE 专家调用超时/失败时，会使用模板
• 去掉横幅：取消 MBE_LANDING_MODE，并确保 MBE 专家服务可用

六、自动化测试

6.1 pytest 全流程测试（推荐）

cd d:\Mises\mbe-monorepo
.\scripts\run_marketing_tests.ps1

或直接：

$env:PYTHONPATH = "private\platform\src;shared\src;private\core\src"
$env:MBE_LANDING_MODE = "template"
python -m pytest tests/integration/test_marketing_api_full_flow.py -v --no-cov

覆盖：健康检查、落地页、聊天、留资、落地页生成、营销事件等 8 个 API。

6.2 独立脚本（需服务已运行）

先启动服务 .\scripts\run_marketing.ps1，再运行：

python scripts/test_marketing_api_full_flow.py
# 或指定地址
python scripts/test_marketing_api_full_flow.py http://localhost:8081

七、相关文件