1. 页面概览
情报报告页（/gotham/reports）是 LightGotham 的书面分析产出中心：支持手动创建、从数据生成、从模板创建三类建报方式；报告按 draft → published → archived 流转，可查看 HTML 渲染、导出 PDF/DOCX；内置「报告工作台」（TAD-10）提供富文本编辑、嵌入图/地图/时间轴快照、版本管理。一句话总结：本页把情报结论沉淀为可编辑、可导出、可发布归档的正式报告。
2. 访问入口
2.1 路由与菜单
path /gotham/reports、name GothamReports、title Gotham 情报报告，子路由挂在父路由 /gotham（GothamLayout）下，侧边栏菜单项「情报报告」。源码 action/web/src/views/GothamReportsPage.vue。
2.2 认证与权限
子路由 meta requiresAuth: true；请求经 gothamClient.js 附带 aip_token，401 用 gotham_refresh_token 换新重放。
2.3 端口与 API 前缀
Gotham 后端 18083，前缀 /gotham-api（baseURL /gotham-api/v1，Vite 代理重写为 /api/v1）。
3. 界面布局
Gotham 情报报告 [刷新]
[操作结果提示 alert（可关闭）]
创建报告卡 | 从数据生成卡 | 从模板创建卡 ← 三列并列
报告列表（ID/标题/类型/状态/版本/作者/更新时间/操作）
[报告 HTML 查看模态] [报告工作台模态]- 顶部：标题 + 「刷新」重拉报告与模板。
- 创建区：三卡并列（创建报告 / 从数据生成 / 从模板创建）。
- 报告列表：逐行操作；空态「暂无报告，请创建或生成。」。
- 模态层：查看模态 iframe srcdoc 渲染 HTML；工作台模态含三标签页。
4. 交互元素
| 控件 | 位置 | 含义与作用 |
|---|---|---|
| 输入「标题 *」「概要」+ 类型下拉 | 创建报告卡 | 标题必填；类型 analysis/incident/entity/general |
| 按钮「创建」 | 创建报告卡 | POST /reports 建草稿并刷新列表 |
| 输入「实体 rid」+ 按钮「生成报告」 | 从数据生成卡 | 填实体 rid（如 graph:person:zhy），POST /reports/generate 用 entity 节生成 |
| 下拉模板 + 按钮「从模板创建」 | 从模板创建卡 | POST /reports/from-template，可按需附实体 rid |
| 行内「查看/工作台/复制/PDF/DOCX」 | 报告列表 | 查看=拉 HTML 渲染；工作台=打开编辑模态；PDF/DOCX=blob 下载 |
| 按钮「发布」「归档」 | 报告列表 | 按状态显隐：非 published/archived 显示「发布」，published 显示「归档」 |
| 标签页「富文本编辑/嵌入对象/版本管理」 | 工作台 | 三个子面板；工具栏提供 B/I/H2/列表/撤销/重做 |
| 按钮「保存内容」 | 工作台·富文本 | 把文本序列化为 paragraph 块 PUT /reports/:id，版本 +1 |
| 按钮「添加嵌入对象」「刷新全部快照」 | 工作台·嵌入对象 | 添加 graph/map/timeline 对象（查询参数 JSON，如 {"entity_id":"graph:person:zhy","depth":2}）；刷新重生成快照 |
| 按钮「恢复此版本」 | 工作台·版本管理 | POST /reports/:id/versions/:version/restore，回滚再 +1 版本 |
5. 后端关联
端点表（源码 action/products/gotham/server/server.go，处理器 handlers_reports.go）：
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /reports | 报告列表 |
| POST | /reports | 创建草稿（title/report_type/summary/description） |
| PUT | /reports/:id | 更新标题/内容，保存后版本 +1 |
| POST | /reports/:id/publish、/archive | 状态流转 draft→published→archived |
| POST | /reports/generate | 按 sections（entity 节）生成 |
| GET | /reports/:id/html | 报告 HTML 文本（axios 带 JWT 拉取） |
| GET | /reports/:id/pdf、/docx | blob 导出下载 |
| GET | /reports/templates、POST /reports/from-template | 模板列表与从模板创建 |
| POST | /reports/:id/duplicate | 复制报告 |
| GET/POST | /reports/:id/objects、DELETE /reports/:id/objects/:object_id、POST /reports/:id/objects/refresh | 嵌入对象管理 |
| GET | /reports/:id/versions、POST /reports/:id/versions/:version/restore | 版本历史与回滚 |
- 状态机：
draft → published → archived。发布要求 draft、归档要求 published；列表按钮按状态显隐。 - 版本机制：每次保存（PUT）自动生成版本快照；恢复旧版本不是覆盖而是再产生新版本（确认框提示「回滚本身会再 +1 版本」）。
- 富文本：Tiptap（StarterKit）编辑，保存时
editor.getText()序列化为[{type:"paragraph",data:{text}}]；回填时blocksToText把各类块转纯文本。 - 嵌入对象：以「类型 + 查询参数」登记，添加时生成快照，可「刷新全部快照」重生成。
6. 权限与安全
- 页面与全部接口均在受保护路由（JWT Bearer），无公开端点。
- 创建/生成/发布/归档等写操作经 ABAC PEP 写门（
server/abac_pep.go），deny 策略命中返回 403。 - 查看/导出 HTML 走 axios 携带 Authorization 头，URL 不暴露 token；导出由前端 blob URL 触发下载，服务端生成后即弃。
7. 常见问题与排错
- 查看模态提示「HTML 渲染失败」：点「查看」后模态内显示红色错误文本；原因是
GET /reports/:id/html失败（token 失效、后端未起、报告不存在）；处理：看 Network 该请求状态，401 重新登录，404 确认报告存在。 - 导出的 PDF/DOCX 文件打不开或为空：下载成功但文件损坏或空白；原因是后端导出异常返回（空内容被当 blob 下载）；处理：查后端日志
handleReportPDF/Docx，确认报告有内容并已保存。 - 保存内容后版本没有 +1：版本历史最新版号未变化；原因是
PUT /reports/:id失败（401/字段缺失）；处理：看是否提示「保存失败」，确认已登录且报告存在，重试保存。 - 从模板创建时模板下拉为空：「选择模板…」无可选项；原因是
GET /reports/templates返回空（后端未预置）；处理：查 Network 该接口返回，确认后端模板种子数据存在。
8. 已知缺陷与边界
| 项 | 说明 |
|---|---|
| 富文本结构丢失 | 保存仅序列化为单个 paragraph 文本块，列表/表格等格式回读后以纯文本呈现 |
| 版本恢复非覆盖 | 回滚生成新版本，历史版本全部保留 |
| 导出格式有限 | 仅 PDF/DOCX 两种；HTML 查看为整页 iframe 渲染，大报告加载慢 |
| 模板依赖后端 | 模板下拉空时「从模板创建」不可用 |