QuestionProject/hy_qa_asset_backend/README.md

大本营答疑资产后台系统 MVP

这是一个用于沉淀“大本营每周三答疑内容”的后台系统 MVP。第一阶段跑通闭环：资料进入、系统发现、AI 清洗、数据库沉淀、人工审核、标准问答入库、人工标记可调用。

系统架构

• 前端：Next.js + React + TypeScript + TailwindCSS，提供独立网页后台。
• 后端：FastAPI + SQLAlchemy + Pydantic + APScheduler。
• 数据库：优先 PostgreSQL；未配置 DATABASE_URL 时自动使用本地 SQLite。
• AI：兼容 OpenAI Chat Completions API；没有 OPENAI_API_KEY 时走 mock AI。
• 飞书：保留真实 API 适配器；没有飞书密钥时走 mock mode。

第一阶段功能

• 答疑场次管理，支持手动创建测试场次。
• 手动触发或定时触发黑灯任务。
• mock 飞书扫描与 mock 转写稿读取。
• AI 清洗模块，真实 OpenAI 兼容 API 与 mock 输出双通道。
• 原始问答拆解、标签、课程阶段、风险等级、脱敏状态入库。
• 待审核卡片页，支持通过入库、修改后通过、需修改、不入库、禁止使用、标记高风险、标记需脱敏。
• 标准问答库，审核通过后默认 not_callable，必须人工标记后才能进入可调用库。
• 智能体可调用库接口只返回 approved + callable + low/medium + 已脱敏/无需脱敏 的标准问答。
• 任务日志和审核日志可追溯。

不做什么

• 不做正式“千问千答智能体”。
• 不做学员端问答界面。
• 不绕过人工审核。
• 不让未审核内容进入标准问答库或可调用库。
• 不把 AI 生成内容伪装成院长或辅导老师原话。
• 不做心理诊断、医疗建议、法律判断或课程效果承诺。

本地启动

后端：

cd hy_qa_asset_backend/backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

前端：

cd hy_qa_asset_backend/frontend
npm install
npm run dev

访问：

• 前端后台：http://localhost:3000
• 后端 API：http://127.0.0.1:8000/docs

环境变量

复制 .env.example 为 .env，按需填写：

• DATABASE_URL：为空时使用 SQLite；PostgreSQL 示例：postgresql+psycopg://hyqa:hyqa@localhost:5432/hyqa
• OPENAI_API_KEY：为空时使用 mock AI。
• OPENAI_BASE_URL：OpenAI 兼容服务地址，可选。
• MODEL_NAME：默认 gpt-4.1-mini。
• FEISHU_APP_ID、FEISHU_APP_SECRET、FEISHU_APP_TOKEN、FEISHU_TABLE_ID_SESSION、FEISHU_TABLE_ID_RAW_QA、FEISHU_TABLE_ID_STANDARD_QA：真实飞书接入所需。若多维表格 URL 是 /wiki/<token>，可以填写 FEISHU_WIKI_NODE_TOKEN 代替 FEISHU_APP_TOKEN，后台会自动解析真实 bitable app_token。
• SCHEDULE_CRON：默认 0 1 * * *。
• SCHEDULE_TIMEZONE：默认 Asia/Shanghai。
• MOCK_MODE：默认 true。

敏感密钥只从环境变量读取，不写入数据库，也不会在设置页明文展示。

Mock 模式测试

没有飞书和 OpenAI 密钥也可以跑通：

1. 启动后端和前端。
2. 打开 /dashboard，点击“手动触发处理任务”。
3. 后端会创建 mock 场次，读取 backend/app/seed/sample_transcript_001.txt。
4. ai_cleaner 在没有 OPENAI_API_KEY 时返回 mock 拆解结果。
5. 进入 /review 查看待审核问答卡片。

也可以在 /sessions 手动创建场次，填写转写稿，再点击“处理”或“重跑”。

手动触发黑灯任务

前端：在 /dashboard 点击“手动触发处理任务”。

API：

curl -X POST http://127.0.0.1:8000/api/tasks/run-now

定时任务由 APScheduler 在后端启动时注册，默认每天 Asia/Shanghai 凌晨 1 点运行一次。

审核流程

1. /review 展示 review_status=pending 的原始问答。
2. 点击“通过入库”后，原始问答变为 approved。
3. 若 suggested_to_standard_qa=true，且不是高风险/禁止、且无需脱敏或已完成脱敏，系统创建 standard_qa_items。
4. 标准问答默认 audit_status=approved、call_status=not_callable。
5. 审核人进入 /standard-qa，手动点击“可调用”。
6. /callable-qa 只展示满足强制筛选规则的内容。

高风险内容、禁止内容、未脱敏内容不会自动进入可调用库。

风险边界

系统逻辑和 Prompt 共同遵守：

1. AI 只能辅助清洗、拆解、打标签、风险初筛，不能替代人工审核。
2. 原始问题和问题整理版分开保存。
3. 原始回答、回答整理版、标准回答分开保存。
4. 未审核内容不能进入标准问答库。
5. 未审核内容不能被未来智能体调用。
6. 高风险内容必须人工复审。
7. 涉及学员隐私必须标记脱敏。
8. 不做心理诊断、医疗建议、法律判断或课程效果承诺。
9. 涉及孩子、婚姻、家庭矛盾、姓名、电话、城市、学校、单位等信息，默认标记风险。
10. 不确定是否有风险时，默认中风险并进入人工审核。

飞书接入说明

第一版 backend/app/services/feishu_client.py 已预留：

• scan_unprocessed_sessions
• fetch_transcript
• update_session_status
• write_raw_qa_items
• write_standard_qa_items

真实飞书 API 已接入：后台会获取 tenant_access_token，扫描多维表格场次表，读取 转写稿 字段或尝试通过 docx 纯文本接口读取 飞书资料链接，处理完成后回写场次状态、原始问答表和标准问答表。

建议在飞书多维表格中建立 3 张表：

• 答疑场次：场次编号、标题、日期、答疑老师、飞书资料链接、转写稿、处理状态、问答总数、待审核数、已审核数、已入库数、失败原因
• 原始问答：问答编号、场次编号、原始问题、问题整理版、原始回答、回答整理版、AI建议标准问题、AI建议标准回答、回答人、一级主题、问题标签、课程阶段、适用人群、情绪强度、风险等级、风险类型、风险说明、是否需脱敏、脱敏状态、审核状态、建议入库、来源时间戳、审核备注
• 标准问答：标准编号、来源原始问答ID、来源场次ID、标准问题、标准回答、相似问法、一级主题、问题标签、课程阶段、适用人群、回答边界、禁止表达、风险等级、审核状态、调用状态、禁用原因

可打开 GET /api/feishu/setup-guide 查看字段模板，打开 GET /api/feishu/status 检查飞书 token 是否可用。应用需要具备多维表格读写、文档读取等权限；如果要读取已有飞书文档，需要将飞书应用/机器人加入该文档协作者。

AI 接入说明

backend/app/services/ai_cleaner.py 会读取 backend/app/prompts/qa_cleaning_prompt.md，调用 OpenAI 兼容 /chat/completions，解析 JSON 数组并校验字段。

接入真实 OpenAI 兼容 API 时，填写：

• OPENAI_API_KEY
• MODEL_NAME
• OPENAI_BASE_URL，如果使用非官方兼容服务

如果 AI 返回非法 JSON，任务会记录失败原因。

Docker

cd hy_qa_asset_backend
docker compose up --build

包含 PostgreSQL、backend、frontend 三个服务。默认仍使用 mock mode。

后续迭代建议

• 接入真实飞书多维表格和文档 API。
• 增加登录鉴权与角色权限。
• 增加更完整的标准问答编辑表单和批量审核。
• 增加脱敏处理工作台。
• 增加 AI 结果二次校验和人工差异对比。
• 增加迁移工具 Alembic、测试用例和生产部署配置。