docs: add export preview feature design spec

2026-04-28 12:02:00 +08:00
parent f3233e2374
commit e3aeee0af2
1 changed files with 104 additions and 0 deletions
@@ -0,0 +1,104 @@
+# 导出预览功能设计
+
+## 需求
+
+在方案详情页提供「预览」功能，让用户在选择模板后能立即看到套用模板导出后的最终效果（所见即所得），无需实际下载文件。
+
+## 核心思路
+
+复用现有模板渲染逻辑，在后端完成 `{placeholder}` 替换后返回 HTML，前端用 CSS 镜像 PDF 视觉效果。
+
+## 技术方案
+
+### 后端
+
+**新增 API：**
+```
+GET /api/plans/<plan_id>/preview?template_id=<id>
+```
+
+**响应：** 返回 HTML 片段
+```html
+<div class="preview-content">
+  <!-- 渲染后的模板内容 -->
+</div>
+```
+
+**实现步骤：**
+1. 复用 `export_pdf` 的模板渲染逻辑（`report_template` + 所有占位符替换）
+2. 模板内容中 `{ai_report}` 已经是 Markdown 格式，替换后得到完整 Markdown
+3. 后端调用 `markdown.markdown()` 把 Markdown 转成 HTML（安装 markdown 包）
+4. 返回 HTML 片段
+
+**注意：** 不在水印层面处理——水印效果由前端 CSS 实现。
+
+### 前端
+
+**模态框：**
+```html
+<!-- 预览模态框 -->
+<div class="modal fade" id="previewModal" ...>
+  <div class="modal-dialog modal-xl"> <!-- 超大模态框保证PDF效果可见 -->
+    <div class="modal-content">
+      <div class="modal-header">
+        <h5 class="modal-title">导出预览</h5>
+        <button type="button" class="btn-close" data-bs-dismiss="modal"></button>
+      </div>
+      <div class="modal-body">
+        <div class="preview-watermark-overlay" id="previewWatermark"></div>
+        <div class="preview-content" id="previewContent"></div>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+**预览区域 CSS（镜像 PDF 样式）：**
+- 字体：Microsoft YaHei, sans-serif
+- h1: 24px, bold
+- h2: 20px, bold
+- h3: 16px, bold
+- body: 12px, line-height 1.6
+- 表格：1px solid border, collapse, td padding 4px 8px
+- 列表：left padding, list-style disc
+- **水印：** CSS fixed overlay，45度旋转，半透明灰色大字 "机构名称"
+
+**水印配置：**
+- 从 `/api/config` 获取 `watermark_text` 配置
+- 前端在模态框 body 内叠加水印层（`position: relative` + fixed watermark div）
+
+**交互流程：**
+1. 点击「预览」按钮
+2. 读取当前选中的 `reportTemplateSelect` 值
+3. `fetch('/api/plans/{id}/preview?template_id={tid}')`
+4. 填充到 `#previewContent`，显示模态框
+5. 如果配置了水印，在模态框内叠加水印效果
+
+### 依赖
+
+- `markdown` Python 包：后端 Markdown→HTML 转换（pip install markdown）
+- `marked` JS 库：前端已有（plan_detail.html 已引入 CDN）
+- Bootstrap 5 模态框：前端已有
+
+### 页面改动
+
+**plan_detail.html 导出按钮区：**
+```html
+[模板选择]  [下载PDF] [预览] [下载MD]
+```
+
+## 文件变更
+
+| 文件 | 改动 |
+|------|------|
+| `app/routes/plans.py` | 新增 `/api/plans/<id>/preview` 路由 |
+| `app/templates/plan_detail.html` | 新增预览按钮 + 模态框 + CSS |
+| `requirements.txt` | 添加 `markdown` 包 |
+
+## 实现顺序
+
+1. 安装 markdown 包到 venv
+2. 后端：新增 preview 路由，复用模板渲染逻辑
+3. 前端：添加模态框 HTML 和 CSS
+4. 前端：添加预览按钮和 JS 逻辑
+5. 测试：选择不同模板，预览效果与 PDF 一致