Initial MVP for QA asset backend
This commit is contained in:
172
hy_qa_asset_backend/README.md
Normal file
172
hy_qa_asset_backend/README.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# 大本营答疑资产后台系统 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 生成内容伪装成院长或辅导老师原话。
|
||||
- 不做心理诊断、医疗建议、法律判断或课程效果承诺。
|
||||
|
||||
## 本地启动
|
||||
|
||||
后端：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
前端：
|
||||
|
||||
```bash
|
||||
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：
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
cd hy_qa_asset_backend
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
包含 PostgreSQL、backend、frontend 三个服务。默认仍使用 mock mode。
|
||||
|
||||
## 后续迭代建议
|
||||
|
||||
- 接入真实飞书多维表格和文档 API。
|
||||
- 增加登录鉴权与角色权限。
|
||||
- 增加更完整的标准问答编辑表单和批量审核。
|
||||
- 增加脱敏处理工作台。
|
||||
- 增加 AI 结果二次校验和人工差异对比。
|
||||
- 增加迁移工具 Alembic、测试用例和生产部署配置。
|
||||
Reference in New Issue
Block a user