万朱浩 / Venue-Ops

Go to a project
Toggle navigation Toggle navigation pinning
Switch branch/tag
venue-operations-research-project-memory.md 7.78 KB

场馆运营反馈调研平台项目记忆

版本：V1.0
状态：Active
更新时间：2026-03-26

本文档用于保存当前项目的稳定上下文，作为后续继续重构、交接和回溯的统一基线。对于需要长期记住的事实，应优先更新本文件。

1. 项目当前定位

  • 项目基座：开源项目 BettaFish
  • 当前重构目标：从“舆情分析平台”转为“面向博物馆、艺术馆、数字展馆等场馆的运营市场反馈调研平台”
  • 核心价值：通过前端触发式爬虫、多引擎分析和最终报告，帮助场馆识别优点、待改进点、改进建议与竞品参考
  • 当前原则：保留三引擎分析界面与最终输出界面，不做完全推倒重写，而是在既有架构上逐步重构语义、数据模型和交互

2. 用户明确要求与工作偏好

  • 使用中文沟通。
  • 默认直接修改，不只停留在方案讨论。
  • 每次代码更新后要重建当前 Docker 镜像。
  • 整个项目统一采用 Docker 容器启动。
  • 保留原有三个引擎分析功能界面 UI 和最终输出界面 UI。
  • 页面需要可滚动，并持续优化为极简主义、精致交互、高分辨率适配的工作台风格。
  • 允许使用本地自建模型，不依赖云端密钥。

3. 当前运行架构

3.1 服务编排

  • infra/docker/docker-compose.yml 暴露：
    • 5000:5000 主 Flask 工作台
    • 8501:8501
    • 8502:8502
    • 8503:8503
  • infra/docker/docker-compose.override.yml 使用本地构建镜像 bettafish-local:latest
  • 当前主要容器：
    • bettafish
    • bettafish-db

3.2 前端与主站

  • 当前主入口：frontend/（Vue 3 + Vite + TypeScript）
  • 构建产物目录：static/frontend/
  • 兜底模板：templates/index.html
  • 后端主应用：app.py
  • app.py 当前优先返回 static/frontend/index.html
  • 当前首页标题已改为“场馆运营反馈调研平台”
  • 已保留三引擎与报告模块主界面，并围绕场馆研究任务组织内容
  • 当前主工作台已拆分为以下核心组件：
    • components/layout/AppHeader.vue
    • components/layout/WorkspaceOverview.vue
    • components/research/*
    • components/crawler/*
    • components/engines/*
    • components/report/*
    • components/settings/ConfigDrawer.vue

3.3 爬虫控制层

  • canonical 目录：backend/crawler/
  • 兼容入口：crawler_web.py
  • 已提供前端可调用接口：
    • /api/crawler/options
    • /api/crawler/state
    • /api/crawler/login/check
    • /api/crawler/login/start
    • /api/crawler/login/cancel
    • /api/crawler/start
    • /api/crawler/stop
  • 支持平台：
    • 小红书
    • 抖音
    • 快手
    • B站
    • 微博
    • 贴吧
    • 知乎
  • 支持登录方式：
    • 二维码登录
    • 手机号登录
    • Cookie 登录
  • 支持采集模式：
    • 关键词搜索
    • 指定内容详情
    • 创作者主页

3.4 分析与报告层

  • 保留的核心模块：
    • InsightEngine
    • QueryEngine
    • MediaEngine
    • ForumEngine
    • ReportEngine
  • ReportEngine 已接入场馆专用模板：ReportEngine/report_template/场馆运营反馈调研报告模板.md
  • 模板选择节点已优先识别场馆运营反馈类查询：ReportEngine/nodes/template_selection_node.py

4. 已完成的关键改造

4.1 产品语义与入口改造

  • 首页语义已从“舆情分析”转为“场馆运营反馈调研”
  • 已新增场馆研究任务表单，字段包含：
    • 场馆名称
    • 城市
    • 场馆类型
    • 研究重点
    • 时间范围
    • 竞品 / 标杆场馆
  • 系统会根据场馆任务自动生成研究指令，并支持同步到爬虫控制台

4.2 本地模型与空 key 兼容

  • 当前默认模型服务：http://192.168.220.11
  • 当前默认模型：qwen3.5:27b
  • 允许空 key 运行本地 OpenAI 兼容服务
  • 已新增 OpenAI 兼容封装：utils/openai_compat.py
  • Insight / Query / Media / Report 多处 LLM Base 已接入空 key 归一化处理

4.3 QueryEngine 去 Tavily 强依赖

  • QueryEngine/tools/search.py 已改造成可选加载 Tavily
  • 在未配置 Tavily 或未安装 tavily-python 时，不会在导入阶段直接阻塞 QueryEngine 启动
  • 当前搜索工具策略可优先走 Anspire 或 Bocha，再按配置回退

4.4 前端状态保持

  • 前端已使用本地存储恢复页面状态
  • 关键本地存储键：
    • bettafish.frontendState.v2
    • bettafish.crawlerState.v2
    • bettafish.workspaceState.v2
    • bettafish.reportState.v2
    • bettafish.reportTemplate.v1
  • 已覆盖恢复内容：
    • 场馆研究表单
    • 搜索指令
    • 爬虫配置
    • 自定义报告模板
    • 当前页签
    • 报告当前 / 历史任务查看态

4.5 任务持久化与历史恢复

场馆研究任务

  • 存储文件：var/logs/venue_research_tasks.json
  • 主接口：
    • GET /api/research/tasks
    • POST /api/research/tasks
    • POST /api/research/tasks/<task_id>/activate

报告任务

  • 报告接口：
    • GET /api/report/status
    • GET /api/report/tasks
    • GET /api/report/result/<task_id>/json
  • 当前报告任务持久化目录：var/reports/final/.task_registry/
  • 启动时支持从历史 var/reports/final/report_state__*.json 兜底恢复
  • 已支持从已落盘 HTML 回读报告内容，避免仅依赖内存态

4.6 Docker 验证现状

  • 最近已多次执行：docker compose -f infra/docker/docker-compose.yml -f infra/docker/docker-compose.override.yml up -d --build
  • 最近已验证通过：
    • bettafish 容器运行正常
    • bettafish-db 健康检查正常
    • /api/report/status
    • /api/report/tasks
    • /api/report/result/report_20250827_121059/json
  • 当前运行期报告任务缓存示例：
    • var/reports/final/.task_registry/report_20250827_121059.json

5. 关键文件清单

  • 主站与任务编排：app.py
  • 前端工程：frontend/
  • 前端构建产物：static/frontend/
  • 爬虫 Web 控制：backend/crawler/（根目录 crawler_web.py 为兼容入口）
  • 报告接口与任务恢复：ReportEngine/flask_interface.py
  • 兜底模板：templates/index.html
  • Docker 编排：infra/docker/docker-compose.yml
  • 本地覆盖构建：infra/docker/docker-compose.override.yml
  • 场馆 PRD：docs/venue-operations-research-prd.md
  • 场馆实施计划：docs/venue-operations-research-platform-plan.md
  • 场馆 Backlog：docs/venue-operations-research-backlog.md

6. 已知问题与风险

  • 报告页签当前仍受“三引擎需先完成最新分析”的原有锁定逻辑影响，直接点击页签的交互还需要继续收口。
  • 文档在当前 PowerShell 环境中偶尔会出现中文乱码显示，但文件本身通常仍是 UTF-8，修改前后都应优先使用 UTF-8 方式读取。
  • 仓库当前是脏工作区，存在用户已有改动；后续继续修改时不能直接回退未知改动。
  • 结构化数据模型仍未完整落库，当前更多依赖任务快照、日志和报告文件。
  • 当前历史任务列表中可能存在旧数据遗留的乱码标题，这属于既有历史数据质量问题，不是本轮 Vue 前端重构引入的问题。

7. 下一轮建议优先级

  1. 收口报告页签与三引擎完成态之间的交互逻辑，确保用户可以稳定查看历史报告。
  2. 推进 Venue、证据、标签、问题、建议等结构化数据模型。
  3. 将竞品对比与标杆场馆分析纳入首个结构化版本。
  4. 继续优化高分辨率布局、滚动体验和极简主义视觉细节。
  5. 在保证 Docker 统一运行的前提下，完善任务看板、历史复盘与趋势视图。

8. 后续协作约定

  • 继续修改代码前，先读取本文件和三份业务文档，确认当前上下文。
  • 每次完成代码改动后，都执行一次 Docker 重建验证。
  • 若新增重要接口、状态文件、持久化路径或用户要求，应优先补写到本文件。