PlantAI-rag-new/ui/src/api/docgen.js

// api/docgen.js —— 文档生成端点（P3/dev3 归属）
// 端点契约：P2 任务书 sdk/app/routers/docgen.py（dev2 开发中，联调后生效）。
// 全部经 http.js 封装；默认读超时 600s 兜底（生成/编辑最长路径不早于 BFF 超时自断）。
import { get, post, patch, del } from './http.js';

// 缺陷 #52：generate 兼容 200（旧同步契约）/202（新异步契约）两种响应形态。
// 202 由 http.js 返回 payload（202 在 fetch 语义下非错误，body 直接透传）；
// 旧 BFF 无 202 时直接返回同步产物——两者统一经 generate() 归一，
// chat.sendDocgen 按 `payload.task_id` 有无区分走轮询还是直接落块。

/**
 * 上传入库（用户拖拽即走此路）：multipart → vstore /ingest，入库主向量库持久可用。
 * @param {File} file
 * @param {{ name?: string, category?: string, description?: string, tags?: string, as_template?: boolean }} meta
 * @param {{ onUploadProgress?: (e: {loaded:number, total:number, pct:number}) => void }} [opts]
 *   onUploadProgress：真实上传字节进度（http.js XHR 分支回调）
 * @returns {Promise<{ok:boolean, items:[{library_id, name, size, as_template}]}>}
 */
export function uploadLibrary(file, meta = {}, opts = {}) {
  const form = new FormData();
  form.append('file', file);
  if (meta.name != null && meta.name !== '') form.append('name', meta.name);
  if (meta.category != null && meta.category !== '') form.append('category', meta.category);
  if (meta.description != null && meta.description !== '') form.append('description', meta.description);
  if (meta.tags != null && meta.tags !== '') form.append('tags', meta.tags);
  if (meta.as_template != null) form.append('as_template', meta.as_template ? 'true' : 'false');
  return post('/api/docgen/library', form, opts);
}

/**
 * 生成（600s 兜底读超时；兼容 200 同步 / 202 异步两种响应）。
 * @returns {Promise<{ok, task_id?, status?, artifact?, progress?, markdown?}>}
 *   202 → {ok, task_id, status:"queued"}；200 → 旧同步产物（artifact 内嵌）。
 */
export function generate(payload) {
  return post('/api/docgen/generate', payload);
}

/** 缺陷 #52：任务状态轮询（GET /api/docgen/tasks/{task_id}）
 *  → 200 {ok, task:{id, session_id, status, progress:[{section,title,state}], artifact|null, error}} */
export function getTask(taskId) {
  return get(`/api/docgen/tasks/${encodeURIComponent(taskId)}`);
}

/** 缺陷 #52：会话级任务列表（GET /api/docgen/tasks?session_id=）——会话恢复时兜底查询 */
export function listTasks(sessionId) {
  return get('/api/docgen/tasks', { session_id: sessionId });
}

/** 取 artifact 的 md 原文 */
export function getArtifactContent(artifactId) {
  return get(`/api/docgen/artifacts/${encodeURIComponent(artifactId)}/content`);
}

/** 取 artifact 的模版 HTML（{html, css, template_key}，预览与导出同源） */
export function getArtifactHtml(artifactId) {
  return get(`/api/docgen/artifacts/${encodeURIComponent(artifactId)}/html`);
}

/** 保存编辑后的 markdown（debounce PATCH）；letterhead 为红头文字（2026-09-04 就地编辑持久化） */
export function saveArtifactContent(artifactId, markdown, letterhead) {
  return patch(`/api/docgen/artifacts/${encodeURIComponent(artifactId)}/content`, { markdown, letterhead });
}

/** 「用 prompt 修改」：后端按 instruction 返回完整新 md */
export function editArtifact(artifactId, instruction) {
  return post(`/api/docgen/artifacts/${encodeURIComponent(artifactId)}/edit`, { instruction });
}

/** 导出：后端生成产物并返回 download_url（PDF/DOCX） */
export function exportArtifact(artifactId, format) {
  return post(`/api/docgen/artifacts/${encodeURIComponent(artifactId)}/export`, { format });
}

/** 主库管理（透传 vstore；批量导入/模版浏览用） */
export function listLibrary({ q, category, as_template } = {}) {
  return get('/api/docgen/library', { q, category, as_template });
}

/** 删除资料（FR-PRIV-006）：BFF DELETE 返回 204 空体——http.del 解析不出 JSON 时
 *  返回 null，此处兜底为 {ok:true}（假设 10：不抛 JSON 解析错）；信封错误仍抛 ApiError。 */
export async function removeLibrary(id) {
  const res = await del(`/api/docgen/library/${encodeURIComponent(id)}`);
  return res == null ? { ok: true } : res;
}

/** 下载地址（附件导出：后端带 RFC 5987 文件名） */
export function downloadUrl(artifactId, format) {
  return `/api/docgen/artifacts/${encodeURIComponent(artifactId)}/download?format=${encodeURIComponent(format)}`;
}