# 任务书：开发 agent-2 —— P2 BFF 集成/API + 批量导入工具

## 前置必读
1. docs/docgen_team_context.md（服务器环境事实 + 团队纪律，全部遵守）
2. 本任务书 + 【跨模块契约】；P1 模块由 dev1 开发，你只按契约 import，不替 dev1 写服务层

## 职责范围（只改这些文件，不越界）
A. sdk/app/config.py（改动）—— Settings 加：docgen_root、docgen_artifact_ttl_days=30、docgen_quota_gb=50、vstore_base_url（默认 http://127.0.0.1:8094）、docgen_llm_base_url（默认 deepseek）、docgen_llm_api_key、docgen_llm_model、docgen_llm_timeout=300
B. sdk/app/schemas.py（改动）—— Block 联合加 ArtifactBlock（type:"artifact"、artifact_id/title/template_name/status）；新增 ArtifactOut、DocgenGenerateRequest、DocgenEditRequest、DocgenExportRequest 等 pydantic 模型（schemas.py 是明文白名单，pydantic 只能放这里）
C. sdk/app/db.py（改动）—— _SCHEMA 加两表（幂等 CREATE IF NOT EXISTS，try/except 不阻断启动）：
   - doc_library：id TEXT PK、name、category、tags、description、as_template INTEGER、enc_path、embed_sha、active、created_at
   - doc_artifacts：id TEXT PK、session_id、status、title、template_name、md_path、docx_path、pdf_path、error、created_at
D. sdk/app/main.py（改动）—— 挂载 docgen.router
E. 新增 sdk/app/routers/docgen.py —— BFF 端点（向 UI 暴露；对 vstore 全部经 services/docgen/client.py 透传；错误信封沿用现有格式，参考 sdk/app/routers/qa.py 等现有路由写法）：
   - POST /api/docgen/library（multipart）：上传入库（用户拖拽即走此路）→ 透传 vstore /ingest → {ok, items:[{library_id, name, size, as_template}]}
   - POST /api/docgen/generate（JSON {description, session_id, library_ids[], template_id?}）：同步生成（600s 兜底）→ {ok, artifact:{...}}
   - GET /api/docgen/artifacts/{id}/content（md 原文）；PATCH …/content（保存编辑 body {markdown}）
   - POST /api/docgen/artifacts/{id}/edit：{instruction} → {ok, markdown}
   - POST /api/docgen/artifacts/{id}/export：{format:"pdf"|"docx"} → {ok, download_url}
   - GET /api/docgen/artifacts/{id}/download?format=：FileResponse attachment（RFC 5987 文件名）
   - 主库管理（透传 vstore）：GET /api/docgen/library?q=&category=&as_template=、GET/DELETE /api/docgen/library/{id}、PATCH /api/docgen/library/{id}（改 meta/as_template）、POST /api/docgen/library/rebuild-index
   - 意图护栏：generate/edit/export 在 BFF 侧跑 services/docgen/intent.py 同规则校验（非 docgen 意图 → 422 提示走 QA）
   - vstore 失败兜底：入库失败 → 错误返回（前端 chips 标红可重试）；检索失败 → 空模版集合（生成跳过模版）；document 拉取失败 → 该资料缺失占位提示（不阻断）
F. 新增 tooling/scripts/docgen_import.py（不进编译链，直连 vstore HTTP）—— 读目录/CSV 批量 ingest（并发 8），as_template=true 默认；rebuild-index 原子切换；--dry-run 先例；导入完成删除源明文目录（--keep-source 可保留）
G. 新增 sdk/app/routers/test_docgen_api.py —— 路由层测试（TestClient + mock pipeline/client，不依赖真实 vstore/LLM）

## 【跨模块契约】（与 dev1 对齐）
- 服务层只 import：services/docgen/client.py、pipeline.py、editor.py、intent.py（dev1 提供；若 dev1 尚未交付，先用最小接口桩并标记 TODO，交 TL 协调）
- db 两表字段如上；服务层以 dict 读写，不引 pydantic
- BFF->vstore 全部经 client.py；router 不直接 httpx 调 vstore
- 用户消息/会话落库：generate 只负责生成与 artifact 落库；聊天消息落库由前端 chat.js 走现有机制（你不用改 sessions/messages）

## 【纪律再强调】
- 不碰生产运行中的服务（8090/8091 等）；不自行部署；测试用 TestClient + mock，不连真实 vstore/ollama/LLM
- 只动本任务书列出的文件；发现需要改其他文件（如 capabilities.py、qa.py）→ 记入报告交 TL 裁决
- 不 commit、不 push、不 touch 部署树
- db.py 加表只追加 _SCHEMA，不改现有表定义

## 【自测要求】
- cd /home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new && /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-venv/bin/python -m pytest sdk/app/routers/test_docgen_api.py -q
- config/schemas 改动能 import 通过；db 加表在 tmp sqlite 上执行验证幂等
- 自测结果写入 docs/team/report_dev2.md

## 【完成标准】
最终回复中明确写「DEV2 P2 完成」+ 报告路径 docs/team/report_dev2.md + 自测通过数