docs: add export preview implementation plan
This commit is contained in:
@@ -0,0 +1,430 @@
|
|||||||
|
# 导出预览功能实现计划
|
||||||
|
|
||||||
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||||
|
|
||||||
|
**Goal:** 在方案详情页新增「预览」功能，用户选择模板后可即时看到套用模板导出后的最终效果（所见即所得，接近 PDF 视觉效果）
|
||||||
|
|
||||||
|
**Architecture:** 后端新增 preview 路由，复用 export_pdf 的模板渲染逻辑，将 Markdown 转 HTML 后返回；前端用模态框 + CSS 镜像 PDF 样式，包括水印效果
|
||||||
|
|
||||||
|
**Tech Stack:** Flask, markdown (Python), marked.js, Bootstrap 5
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 文件变更总览
|
||||||
|
|
||||||
|
| 文件 | 改动 |
|
||||||
|
|------|------|
|
||||||
|
| `requirements.txt` | 添加 `markdown` 包 |
|
||||||
|
| `app/routes/plans.py` | 新增 `/api/plans/<id>/preview` 路由 |
|
||||||
|
| `app/templates/plan_detail.html` | 新增预览按钮 + 模态框 + CSS |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task 1: 安装 markdown 包
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `requirements.txt`
|
||||||
|
|
||||||
|
- [ ] **Step 1: 添加 markdown 到 requirements.txt**
|
||||||
|
|
||||||
|
在 requirements.txt 末尾添加：
|
||||||
|
```
|
||||||
|
markdown>=3.4
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 2: 安装到 venv**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd "D:\F\NewI\opencode\daily-workspace\projects\青年钢琴集体课\练习方案系统"
|
||||||
|
venv\Scripts\pip install markdown
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 3: 验证安装**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
venv\Scripts\python -c "import markdown; print(markdown.__version__)"
|
||||||
|
```
|
||||||
|
|
||||||
|
预期输出类似：`3.4.3`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task 2: 新增后端 preview 路由
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `app/routes/plans.py` (在 `export_md` 函数之后添加新路由)
|
||||||
|
|
||||||
|
- [ ] **Step 1: 找到 export_md 函数的位置**
|
||||||
|
|
||||||
|
在 plans.py 中找到 `def export_md(plan_id):` 和它结束的位置（下一个 `@main_bp.route` 之前）
|
||||||
|
|
||||||
|
- [ ] **Step 2: 在 export_md 结束后添加 preview 路由**
|
||||||
|
|
||||||
|
在 `export_md` 路由结束处（`@main_bp.route("/plans/<int:plan_id>/wechat"` 之前）添加：
|
||||||
|
|
||||||
|
```python
|
||||||
|
@main_bp.route("/api/plans/<int:plan_id>/preview", methods=["GET"])
|
||||||
|
@login_required_json
|
||||||
|
def preview_report(plan_id):
|
||||||
|
"""预览报告模板渲染结果 - 返回HTML片段"""
|
||||||
|
import markdown
|
||||||
|
from app.models import Template
|
||||||
|
|
||||||
|
plan = PracticePlan.query.get_or_404(plan_id)
|
||||||
|
content = json.loads(plan.content)
|
||||||
|
student_name = plan.student.name if plan.student else "未知学员"
|
||||||
|
|
||||||
|
# 获取选中的报告模板
|
||||||
|
template_id = request.args.get('template_id', type=int)
|
||||||
|
report_template = None
|
||||||
|
try:
|
||||||
|
if template_id:
|
||||||
|
tmpl = Template.query.get(template_id)
|
||||||
|
if tmpl and tmpl.type == "report":
|
||||||
|
report_template = tmpl.content
|
||||||
|
else:
|
||||||
|
tmpl = Template.query.filter_by(type="report").order_by(Template.sort_order.asc()).first()
|
||||||
|
if tmpl:
|
||||||
|
report_template = tmpl.content
|
||||||
|
except:
|
||||||
|
pass
|
||||||
|
|
||||||
|
if not report_template:
|
||||||
|
return "<div class='text-muted'>无可用模板</div>", 200
|
||||||
|
|
||||||
|
# 占位符替换（复用 export_pdf 逻辑）
|
||||||
|
rendered = report_template
|
||||||
|
rendered = rendered.replace("{student_name}", student_name)
|
||||||
|
rendered = rendered.replace("{practice_time}", content.get('practice_time', 'N/A'))
|
||||||
|
rendered = rendered.replace("{total_minutes}", str(content.get('total_daily_minutes', 0)))
|
||||||
|
rendered = rendered.replace("{generated_at}", content.get('generated_at', ''))
|
||||||
|
|
||||||
|
from app.models import User
|
||||||
|
user_id = session.get('user_id')
|
||||||
|
user_name = '未知'
|
||||||
|
if user_id:
|
||||||
|
user = User.query.get(user_id)
|
||||||
|
if user and user.name:
|
||||||
|
user_name = user.name
|
||||||
|
rendered = rendered.replace("{generated_by}", user_name)
|
||||||
|
|
||||||
|
if content.get('ai_report'):
|
||||||
|
rendered = rendered.replace("{ai_report}", content['ai_report'])
|
||||||
|
else:
|
||||||
|
rendered = rendered.replace("{ai_report}", "（未生成AI报告）")
|
||||||
|
|
||||||
|
problem_tags = ""
|
||||||
|
for problem in content.get('problems', []):
|
||||||
|
problem_tags += f"- **{problem.get('name', '')}** ({problem.get('severity', '')})\n"
|
||||||
|
rendered = rendered.replace("{problem_tags}", problem_tags or "（无）")
|
||||||
|
|
||||||
|
# 学员目标
|
||||||
|
from app.models import StudentGoal
|
||||||
|
student_goals_list = StudentGoal.query.filter_by(student_id=plan.student_id).all() if plan.student_id else []
|
||||||
|
goals_text_parts = []
|
||||||
|
for g in student_goals_list:
|
||||||
|
if g.status != "已完成":
|
||||||
|
goals_text_parts.append(f"- **{g.goal.name}**\n {g.goal.content if g.goal else '未提供具体内容'}")
|
||||||
|
goals_text = "\n".join(goals_text_parts) if goals_text_parts else "（无）"
|
||||||
|
rendered = rendered.replace("{student_goals}", goals_text)
|
||||||
|
|
||||||
|
# Markdown 转 HTML
|
||||||
|
html_content = markdown.markdown(rendered, extensions=['tables', 'fenced_code'])
|
||||||
|
|
||||||
|
return html_content, 200, {'Content-Type': 'text/html; charset=utf-8'}
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 3: 验证路由语法正确**
|
||||||
|
|
||||||
|
运行开发服务器检查是否有语法错误：
|
||||||
|
```bash
|
||||||
|
cd "D:\F\NewI\opencode\daily-workspace\projects\青年钢琴集体课\练习方案系统"
|
||||||
|
venv\Scripts\python -c "from app import create_app; app = create_app(); print('OK')"
|
||||||
|
```
|
||||||
|
|
||||||
|
预期输出：`OK`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task 3: 前端添加预览模态框
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `app/templates/plan_detail.html` (在文件末尾 `</div>` 之前添加模态框)
|
||||||
|
|
||||||
|
- [ ] **Step 1: 在 plan_detail.html 末尾添加预览模态框**
|
||||||
|
|
||||||
|
在 `</div>` (最后一个 closing div) 之前添加：
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- 导出预览模态框 -->
|
||||||
|
<div class="modal fade" id="previewModal" tabindex="-1" aria-labelledby="previewModalLabel" aria-hidden="true">
|
||||||
|
<div class="modal-dialog modal-xl modal-dialog-scrollable">
|
||||||
|
<div class="modal-content">
|
||||||
|
<div class="modal-header">
|
||||||
|
<h5 class="modal-title" id="previewModalLabel">导出预览</h5>
|
||||||
|
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="关闭"></button>
|
||||||
|
</div>
|
||||||
|
<div class="modal-body" style="position: relative; overflow: hidden;">
|
||||||
|
<div id="previewWatermark" class="preview-watermark-overlay"></div>
|
||||||
|
<div id="previewContent" class="preview-content"></div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 2: 添加预览区域的 CSS 样式**
|
||||||
|
|
||||||
|
在 `plan_detail.html` 的 `<style>` 区块中添加（如果页面没有 `<style>` 区块，需要在 `<head>` 中添加）：
|
||||||
|
|
||||||
|
```css
|
||||||
|
/* 导出预览样式 - 镜像PDF效果 */
|
||||||
|
.preview-content {
|
||||||
|
font-family: "Microsoft YaHei", "微软雅黑", sans-serif;
|
||||||
|
font-size: 12px;
|
||||||
|
line-height: 1.6;
|
||||||
|
color: #333;
|
||||||
|
padding: 20px;
|
||||||
|
background: white;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-content h1 {
|
||||||
|
font-size: 24px;
|
||||||
|
font-weight: bold;
|
||||||
|
margin: 0 0 16px 0;
|
||||||
|
text-align: center;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-content h2 {
|
||||||
|
font-size: 20px;
|
||||||
|
font-weight: bold;
|
||||||
|
margin: 16px 0 12px 0;
|
||||||
|
border-bottom: 1px solid #ddd;
|
||||||
|
padding-bottom: 4px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-content h3 {
|
||||||
|
font-size: 16px;
|
||||||
|
font-weight: bold;
|
||||||
|
margin: 12px 0 8px 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-content p {
|
||||||
|
margin: 8px 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-content ul, .preview-content ol {
|
||||||
|
margin: 8px 0;
|
||||||
|
padding-left: 24px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-content li {
|
||||||
|
margin: 4px 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-content table {
|
||||||
|
border-collapse: collapse;
|
||||||
|
width: 100%;
|
||||||
|
margin: 12px 0;
|
||||||
|
font-size: 12px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-content table th,
|
||||||
|
.preview-content table td {
|
||||||
|
border: 1px solid #ddd;
|
||||||
|
padding: 4px 8px;
|
||||||
|
text-align: left;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-content table th {
|
||||||
|
background: #f5f5f5;
|
||||||
|
font-weight: bold;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-content strong {
|
||||||
|
font-weight: bold;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-content em {
|
||||||
|
font-style: italic;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-content code {
|
||||||
|
font-family: Consolas, monospace;
|
||||||
|
background: #f5f5f5;
|
||||||
|
padding: 1px 4px;
|
||||||
|
border-radius: 3px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-content blockquote {
|
||||||
|
border-left: 3px solid #ddd;
|
||||||
|
margin: 8px 0;
|
||||||
|
padding-left: 12px;
|
||||||
|
color: #666;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-watermark-overlay {
|
||||||
|
position: absolute;
|
||||||
|
top: 0;
|
||||||
|
left: 0;
|
||||||
|
right: 0;
|
||||||
|
bottom: 0;
|
||||||
|
pointer-events: none;
|
||||||
|
z-index: 10;
|
||||||
|
overflow: hidden;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-watermark-overlay::before {
|
||||||
|
content: attr(data-watermark);
|
||||||
|
position: absolute;
|
||||||
|
top: 50%;
|
||||||
|
left: 50%;
|
||||||
|
transform: translate(-50%, -50%) rotate(-45deg);
|
||||||
|
font-size: 48px;
|
||||||
|
font-weight: bold;
|
||||||
|
color: rgba(200, 200, 200, 0.3);
|
||||||
|
white-space: nowrap;
|
||||||
|
z-index: 11;
|
||||||
|
display: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.preview-watermark-overlay.watermark-active::before {
|
||||||
|
display: block;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task 4: 添加预览按钮
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `app/templates/plan_detail.html` (在导出按钮区)
|
||||||
|
|
||||||
|
- [ ] **Step 1: 在导出按钮区添加「预览」按钮**
|
||||||
|
|
||||||
|
找到导出按钮区（应该有 `downloadPDFWithTemplate` 和 `downloadMDWithTemplate` 按钮），在 PDF 按钮之后、MD 按钮之前添加预览按钮：
|
||||||
|
|
||||||
|
```html
|
||||||
|
<button onclick="downloadPDFWithTemplate()" class="btn btn-sm btn-primary">
|
||||||
|
<i class="bi bi-download"></i> 下载PDF
|
||||||
|
</button>
|
||||||
|
<button onclick="showPreview()" class="btn btn-sm btn-outline-success">
|
||||||
|
<i class="bi bi-eye"></i> 预览
|
||||||
|
</button>
|
||||||
|
<button onclick="downloadMDWithTemplate()" class="btn btn-sm btn-outline-primary">
|
||||||
|
<i class="bi bi-file-markdown"></i> 下载MD
|
||||||
|
</button>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task 5: 添加预览 JS 逻辑
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `app/templates/plan_detail.html` (在 `<script>` 区块中添加 JS 函数)
|
||||||
|
|
||||||
|
- [ ] **Step 1: 添加 showPreview 函数**
|
||||||
|
|
||||||
|
在 `downloadMDWithTemplate` 函数之后添加：
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
async function showPreview() {
|
||||||
|
const templateId = document.getElementById('reportTemplateSelect')?.value;
|
||||||
|
const planId = currentPlanId;
|
||||||
|
const suffix = templateId ? `?template_id=${templateId}` : '';
|
||||||
|
|
||||||
|
try {
|
||||||
|
const resp = await fetch(`/api/plans/${planId}/preview${suffix}`);
|
||||||
|
if (!resp.ok) {
|
||||||
|
alert('预览加载失败');
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
const html = await resp.text();
|
||||||
|
document.getElementById('previewContent').innerHTML = html;
|
||||||
|
|
||||||
|
// 加载水印配置
|
||||||
|
try {
|
||||||
|
const cfgResp = await fetch('/api/config');
|
||||||
|
if (cfgResp.ok) {
|
||||||
|
const cfg = await cfgResp.json();
|
||||||
|
const wmText = cfg.watermark_text || '';
|
||||||
|
const wmEl = document.getElementById('previewWatermark');
|
||||||
|
if (wmText) {
|
||||||
|
wmEl.setAttribute('data-watermark', wmText);
|
||||||
|
wmEl.classList.add('watermark-active');
|
||||||
|
} else {
|
||||||
|
wmEl.classList.remove('watermark-active');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
} catch (e) {
|
||||||
|
console.log('水印配置加载失败', e);
|
||||||
|
}
|
||||||
|
|
||||||
|
// 显示模态框
|
||||||
|
const modal = new bootstrap.Modal(document.getElementById('previewModal'));
|
||||||
|
modal.show();
|
||||||
|
} catch (err) {
|
||||||
|
console.error('预览错误:', err);
|
||||||
|
alert('预览加载失败');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 2: 确保 marked.js 可用**
|
||||||
|
|
||||||
|
检查 `plan_detail.html` 是否已引入 marked.js。如果没有，在 `<head>` 中添加：
|
||||||
|
|
||||||
|
```html
|
||||||
|
<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
|
||||||
|
```
|
||||||
|
|
||||||
|
（注意：marked 已经用于渲染 AI 报告区域，如果页面已有引入则跳过此步）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task 6: 验证完整功能
|
||||||
|
|
||||||
|
- [ ] **Step 1: 启动开发服务器**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd "D:\F\NewI\opencode\daily-workspace\projects\青年钢琴集体课\练习方案系统"
|
||||||
|
venv\Scripts\python run.py
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 2: 打开方案详情页测试**
|
||||||
|
|
||||||
|
访问 http://127.0.0.1:5001/plan/26（选择一个有内容的方案）
|
||||||
|
|
||||||
|
- [ ] **Step 3: 测试预览功能**
|
||||||
|
|
||||||
|
1. 选择一个报告模板
|
||||||
|
2. 点击「预览」按钮
|
||||||
|
3. 确认模态框显示的内容与 PDF 导出效果一致
|
||||||
|
4. 确认水印显示（如已配置）
|
||||||
|
|
||||||
|
- [ ] **Step 4: 验证 Markdown 渲染正确**
|
||||||
|
|
||||||
|
检查预览中的：
|
||||||
|
- 标题层级（# ## ###）
|
||||||
|
- 粗体（**text**）
|
||||||
|
- 列表（- item）
|
||||||
|
- 表格（| col |）
|
||||||
|
- 水印（如已配置）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task 7: 提交代码
|
||||||
|
|
||||||
|
- [ ] **Step 1: 检查变更**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd "D:\F\NewI\opencode\daily-workspace\projects\青年钢琴集体课\练习方案系统"
|
||||||
|
git status
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 2: 提交**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add requirements.txt app/routes/plans.py app/templates/plan_detail.html
|
||||||
|
git commit -m "feat: add export preview with template rendering and watermark support"
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user