# 大本营答疑资产后台系统 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、测试用例和生产部署配置。