meijiali/hot_comment_radar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 初始化项目，添加文档

Browse Source
This commit is contained in:
meijiali
2026-07-01 16:59:59 +08:00
commit 289d7e2c82
9 changed files with 4447 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/UIDesign.md
+958
View File
@@ -0,0 +1,958 @@
# UIDesign.md：小红书 / 抖音热榜评论抓取 + AI 分析报告工具
> 版本：v1.1
> 状态：MVP 设计稿（已审阅）
> 最后更新：2025-07-10
> 关联文档：DevelopmentPlan.md / FeatureSummary.md
## 1. 文档信息
- 文档阶段：UIDesign（界面与交互设计文档）
- 需求与技术依据：`PRD.md`、`FeatureSummary.md`、`DevelopmentPlan.md`
- 视觉风格：工程化、简洁、信息密度高，以数据看板、表格和轻量报告为主
- 技术实现前提：FastAPI Jinja2 模板 + Bootstrap 5 CDN + 简单 CSS + 原生 JS；HTMX 作为 P1 局部刷新增强方案
- 目标用户：内部演示、开发联调、产品/数据分析同事查看抓取与分析结果
## 2. 设计原则与全局规范
### 2.1 设计原则
- 信息优先：核心数据，包括进度、状态、评论样本数、情绪分布和导出入口，必须在第一视觉层级。
- 状态透明：任务的等待、运行、成功、失败、AI 样本不足和分析失败必须通过统一 Badge、颜色和文案展示。
- 极简交互：避免复杂弹窗和多步引导，抓取、查看、导出等操作入口扁平化呈现。
- 调试友好：MVP 是工程演示工具，允许在详情页保留原始 JSON 调试入口，但不作为正式用户功能。
- 移动端可读：不依赖 Hover 作为主信息通道，错误原因和状态说明应直接可见。
### 2.2 全局样式规范
推荐直接使用 Bootstrap 5 CDN，降低 4 天 MVP 开发复杂度。
主色调：
- Primary（主要操作/高亮）：`#0d6efd`
- Success（成功/正向情绪）：`#198754`
- Danger（失败/负向情绪/错误）：`#dc3545`
- Warning（运行中/中性情绪/分析不足）：`#ffc107`
- Secondary（次要信息/未知状态）：`#6c757d`
版式：
- 顶部固定导航栏。
- 主体内容区居中，最大宽度建议 `1200px`。
- 页面主体使用 Bootstrap `.container`。
- 模块使用 Card、Table、Accordion、Alert、Badge、Progress Bar 等基础组件。
- 不做复杂营销式视觉设计，优先保证密集信息下的可读性和操作效率。
## 3. 路由与接口总表
### 页面路由（返回 HTML，由 Jinja2 渲染）
| 方法 | 路径 | 用途 | 对应模板 |
|---|---|---|---|
| GET | `/` | 首页 / 任务列表页 | `index.html` |
| GET | `/tasks/{task_id}` | 任务详情页（热点与内容条目列表） | `tasks/detail.html` |
| GET | `/hotspots/{hotspot_id}/report` | 热点级汇总报告页 | `hotspots/report.html` |
| GET | `/items/{item_id}` | 内容条目详情页 | `items/detail.html` |
### API 接口（返回 JSON，供前端 JS 调用）
| 方法 | 路径 | 用途 | 返回格式 |
|---|---|---|---|
| POST | `/api/tasks` | 创建抓取任务 | JSON `{task_id, status}` |
| GET | `/api/tasks/{task_id}` | 查询任务最新状态 | JSON |
### 局部刷新接口（返回 HTML Fragment，供 HTMX 调用）
| 方法 | 路径 | 用途 | 返回格式 |
|---|---|---|---|
| GET | `/partials/tasks` | 刷新任务列表表格行 | HTML Fragment（`task_rows.html`） |
### 导出接口（返回文件流）
| 方法 | 路径 | 用途 | 返回格式 |
|---|---|---|---|
| GET | `/api/export/items/{item_id}/comments.csv` | 导出内容条目评论明细 CSV | File |
| GET | `/api/export/items/{item_id}/report.md` | 导出内容条目分析报告 Markdown | File |
| GET | `/api/export/hotspots/{hotspot_id}/report.md` | 导出热点汇总报告 Markdown | File |
| GET | `/api/export/hotspots/{hotspot_id}/comments.csv` | 导出热点下全部评论汇总 CSV | File |
## 4. 状态枚举与 UI 映射规范
所有模板中的状态展示统一依据以下枚举值映射，禁止在模板中硬编码中文状态文案。
### Task.status
| 后端值 | 中文展示 | Badge 样式 |
|---|---|---|
| `pending` | 等待中 | `bg-secondary` |
| `running` | 运行中 | `bg-warning text-dark` |
| `success` | 已完成 | `bg-success` |
| `failed` | 失败 | `bg-danger` |
### Task.analysis_status
| 后端值 | 中文展示 | Badge 样式 | 说明 |
|---|---|---|---|
| `normal` | — | 不展示 | 正常，无需提示 |
| `insufficient` | ⚠️ AI 样本不足 | `bg-warning text-dark` | 展示 Alert 提示 |
| `failed` | ⚠️ AI 分析失败 | `bg-danger` | 展示 Alert 提示 |
### Item.status
| 后端值 | 中文展示 | 样式 |
|---|---|---|
| `pending` | 等待抓取 | `text-secondary` |
| `crawling` | 抓取中 | `text-warning` |
| `analyzing` | 分析中 | `text-info` |
| `success` | 已分析 | `text-success` |
| `crawl_failed` | 抓取失败 | `text-danger` |
| `analysis_failed` | 分析失败 | `text-danger` |
### Comment.analysis_status
| 后端值 | 中文展示 | 说明 |
|---|---|---|
| `success` | — | 正常，无需特殊标注 |
| `insufficient` | 样本不足 | 灰色斜体提示 |
| `failed` | 解析失败 | 红色文字 |
| `skipped` | 未分析 | 灰色文字 |
### sentiment（情绪倾向）
| 后端值 | 中文展示 | Badge 样式 |
|---|---|---|
| `positive` | 正向 | `bg-success` |
| `neutral` | 中性 | `bg-warning text-dark` |
| `negative` | 负向 | `bg-danger` |
| `unknown` | 未知 | `bg-secondary` |
## 5. 面包屑导航与页面标题规范
### 各页面面包屑路径
| 页面 | 面包屑层级 |
|---|---|
| `/` | 首页 |
| `/tasks/{task_id}` | 首页 › 任务 \#{task_id} |
| `/hotspots/{hotspot_id}/report` | 首页 › 任务 \#{task_id} › 热点 \#{rank}：{title} › 汇总报告 |
| `/items/{item_id}` | 首页 › 任务 \#{task_id} › 热点 \#{rank}：{title} › {item_title} |
面包屑使用 Bootstrap 的 `<nav aria-label="breadcrumb">` 组件，放置于页面 `<main>` 容器顶部、页面标题之上。
### 浏览器标签页 `<title>` 格式
| 页面 | `<title>` 格式 |
|---|---|
| `/` | `任务列表 - 热榜评论分析工具` |
| `/tasks/{task_id}` | `任务 \#{task_id} - 热榜评论分析工具` |
| `/hotspots/{hotspot_id}/report` | `{hotspot_title} 汇总报告 - 热榜评论分析工具` |
| `/items/{item_id}` | `{item_title} 详情 - 热榜评论分析工具` |
在 `base.html` 中使用 Jinja2 block：
```jinja2
<title>{% block title %}热榜评论分析工具{% endblock %}</title>
```
各子页面覆盖：
```jinja2
{% block title %}任务列表 - 热榜评论分析工具{% endblock %}
```
## 6. 全局布局（Global Layout）
所有页面共享 `base.html` 布局。
```text
+-------------------------------------------------------------+
| [Logo/Title] 抓取与分析工具 [首页/任务列表] |
+-------------------------------------------------------------+
| |
| Breadcrumb: 首页 > 任务 #1234 > 热点分析 |
| |
| [ 主体内容区域 ] |
| |
+-------------------------------------------------------------+
| Footer: 内部演示工具 | 仅供学习参考 |
+-------------------------------------------------------------+
```
基础结构：
- Navbar：左侧为产品名「热榜评论分析工具」，右侧保留「任务列表」入口。
- Breadcrumb：每个页面放在标题上方。
- Main：页面核心内容，使用 `.container py-4`。
- Footer：简短说明「内部演示工具 | 仅供学习参考」。
## 7. 核心页面设计
### 7.1 首页 / 任务列表页（`/`）
页面目标：提供配置入口触发抓取；查看历史与当前任务进度。
#### 区域 A：创建任务表单
使用 Bootstrap Card 承载表单，字段紧凑排列。
字段控件：
- 平台选择：Radio Buttons 或 Select，选项为「小红书」「抖音」。
- 热点数量上限：Number Input，默认 `5`，范围 `1-10`。
- 每热点内容上限：Number Input，默认 `5`，范围 `1-10`。
- 每内容评论上限：Number Input，默认 `50`，范围 `10-100`。
- 操作按钮：`开始抓取`，Primary Button。
#### 表单提交交互（异步 JS 模式）
- 表单**不使用** HTML `<form action="..." method="POST">` 同步提交，改用 JavaScript `fetch()` 异步提交。
- 点击「开始抓取」按钮后的流程：
```javascript
// static/app.js
async function submitTask() {
const btn = document.getElementById("submit-btn");
const errorBox = document.getElementById("form-error");
// 1. 读取表单值
const payload = {
platform: document.getElementById("platform").value,
hotspot_limit: parseInt(document.getElementById("hotspot_limit").value),
item_limit: parseInt(document.getElementById("item_limit").value),
comment_limit: parseInt(document.getElementById("comment_limit").value),
};
// 2. 禁用按钮，显示 Loading
btn.disabled = true;
btn.innerHTML = `<span class="spinner-border spinner-border-sm"></span> 提交中...`;
errorBox.classList.add("d-none");
try {
const resp = await fetch("/api/tasks", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(payload),
});
if (resp.ok) {
// 3. 成功：跳转至新任务详情页
const data = await resp.json();
window.location.href = `/tasks/${data.task_id}`;
} else if (resp.status === 422) {
// 4. 校验失败：在表单上方渲染错误 Alert
const data = await resp.json();
const messages = data.detail.map(e => e.msg).join("；");
errorBox.textContent = `参数错误：${messages}`;
errorBox.classList.remove("d-none");
} else {
errorBox.textContent = "服务器错误，请稍后重试。";
errorBox.classList.remove("d-none");
}
} catch (e) {
errorBox.textContent = "网络异常，请检查连接后重试。";
errorBox.classList.remove("d-none");
} finally {
btn.disabled = false;
btn.innerHTML = "开始抓取";
}
}
```
- 表单顶部须预留错误展示区：
```html
<div id="form-error" class="alert alert-danger d-none" role="alert"></div>
```
- **表单提交成功后**：直接跳转至 `/tasks/{new_task_id}`，用户可立即在任务详情页看到初始 `pending` 状态。
#### 规模预估提示（表单底部）
在三个配置输入框下方，实时展示预估抓取规模：
```html
<div class="form-text text-muted mt-2" id="scale-hint">
预计最多抓取：<strong id="scale-calc">1250</strong> 条评论
（实际数量可能受平台返回数量、去重、失败、限流影响）
</div>
```
```javascript
// 三个输入框 oninput 时实时更新
function updateScaleHint() {
const h = parseInt(document.getElementById("hotspot_limit").value) || 0;
const i = parseInt(document.getElementById("item_limit").value) || 0;
const c = parseInt(document.getElementById("comment_limit").value) || 0;
document.getElementById("scale-calc").textContent = (h * i * c).toLocaleString();
}
```
#### 区域 B：任务列表
使用 Table 展示任务。
表头：
```text
任务 ID / 平台 / 创建时间 / 配置规模 / 进度 / 状态 / 操作
```
进度展示：
- 已成功内容条目数 / 总内容条目数。
- 可同时展示 Bootstrap Progress Bar。
- 如果任务刚创建且 `started_at` 为空，进度列显示「等待开始...」灰色文字。
#### 任务列表状态列与错误信息展示
- 状态列展示 `status` 对应的 Badge（见状态枚举规范章节）。
- 若 `analysis_status != 'normal'`，在 Badge 后追加 ⚠️ 图标。
- **错误信息展示层级**：
- 任务列表中，仅在状态 Badge 下方以灰色小字直接展示 `error_stage` / `error_type`（不使用 Hover tooltip，Hover 不支持移动端且不适合长文本）：
```html
<span class="badge bg-danger">失败</span>
<br>
<small class="text-muted">{{ task.error_stage }} / {{ task.error_type }}</small>
```
- 完整 `error_message` 仅在 `/tasks/{task_id}` 任务详情页展示。
- Tooltip 可作为 `error_type` 的辅助说明（限 50 字以内），不作为主信息通道。
#### 配置规模列展示格式
```html
<small class="text-muted">热点 {{ task.hotspot_limit }} / 内容 {{ task.item_limit }} / 评论 {{ task.comment_limit }}</small>
```
#### P1 方案：HTMX 任务列表自动轮询
HTMX 通过 `/partials/tasks` 接口获取 HTML Fragment（服务端渲染 `task_rows.html`），每 5 秒更新一次 `<tbody>` 内容，无需手写 DOM 操作。
```html
<!-- index.html 任务列表区域 -->
<div class="d-flex justify-content-between align-items-center mb-2">
<span class="text-muted small">
<span id="refresh-spinner" class="htmx-indicator">⟳ 刷新中...</span>
</span>
<button
class="btn btn-sm btn-outline-secondary"
hx-get="/partials/tasks"
hx-target="#task-table-body"
hx-swap="innerHTML"
hx-indicator="#refresh-spinner">
↻ 手动刷新
</button>
</div>
<table class="table table-hover align-middle">
<thead>
<tr>
<th>任务 ID</th>
<th>平台</th>
<th>创建时间</th>
<th>配置规模</th>
<th>进度</th>
<th>状态</th>
<th>操作</th>
</tr>
</thead>
<tbody
id="task-table-body"
hx-get="/partials/tasks"
hx-trigger="every 5s [document.querySelector('.badge.bg-warning') !== null]"
hx-swap="innerHTML"
hx-indicator="#refresh-spinner">
{% include "partials/task_rows.html" %}
</tbody>
</table>
```
说明：
- `hx-trigger="every 5s [condition]"` 中的条件判断页面上是否存在 `running` 状态的任务（Badge 为 `bg-warning`）。所有任务完成后条件为 false，自动停止轮询，避免无效请求。
- `hx-indicator` 在请求进行中显示「⟳ 刷新中...」提示。
- `/partials/tasks` 返回纯 HTML Fragment（`<tr>` 行集合），不是 JSON。
#### P0 方案：原生 JS 定时轮询（HTMX 不可用时降级）
```javascript
// static/app.js
function startPolling() {
const interval = setInterval(async () => {
const resp = await fetch("/partials/tasks");
const html = await resp.text();
document.getElementById("task-table-body").innerHTML = html;
// 若页面上已无 running 状态，停止轮询
if (!document.querySelector(".badge.bg-warning")) {
clearInterval(interval);
}
}, 5000);
}
if (document.querySelector(".badge.bg-warning")) startPolling();
```
### 7.2 热点与内容条目列表页（`/tasks/{task_id}`）
页面目标：展示任务宏观执行结果，作为进入具体报告的路由中枢。
#### 区域 A：任务概览看板
使用 Card + Bootstrap `row + col` 网格排列。
#### 任务概览看板字段清单
| 字段 | 数据来源 | 展示位置 |
|---|---|---|
| 任务 ID | `task.id` | 左上 |
| 平台 | `task.platform`（小红书 / 抖音） | 左上并排 |
| 创建时间 | `task.created_at` | 第二行左 |
| 任务耗时 | `task.finished_at - task.started_at`（运行中显示「进行中」） | 第二行右 |
| 任务状态 | `task.status` Badge | 第三行左 |
| AI 分析状态 | `task.analysis_status` Badge（normal 时不展示） | 第三行右 |
| 内容条目进度 | 成功 {success_count} / 共 {total_count} 条 | 第四行 |
| 失败条目数 | `task.failed_items_count`（大于 0 时显示红色） | 第四行并排 |
| 错误阶段 / 类型 | `task.error_stage` / `task.error_type`（仅 `status=failed` 时展示） | 第五行，红色 Alert |
| 完整错误信息 | `task.error_message`（仅 `status=failed` 时，折叠展示） | 第五行，可展开 |
#### 区域 B：热点手风琴列表
按 `rank` 排序展示热点。
```text
▼ 热点 #1: [热点标题] (热度: 120w) -------------------- [ 查看热点级汇总报告 ↗ ]
|
|-- [视频/笔记] 标题摘要 1 | 状态: 已分析 | [ 查看详情 ↗ ]
|-- [视频/笔记] 标题摘要 2 | 状态: 抓取失败 (API限流)
|-- [视频/笔记] 标题摘要 3 | 状态: 已分析 | [ 查看详情 ↗ ]
▶ 热点 #2: [热点标题] (热度: 98w) --------------------- [ 查看热点级汇总报告 ↗ ]
```
#### 手风琴默认展开状态
- 默认展开 `rank=1` 的第一个热点，其余折叠。
- 若热点下所有内容条目均为 `crawl_failed`，该热点的「查看汇总报告」按钮置灰，`disabled`，Tooltip 文本：「暂无报告（该热点内容全部抓取失败）」。
#### 任务 running 时内容列表空状态
若 `task.status = running` 且 `hotspots` 列表为空（抓取尚未返回任何热点），展示：
```html
<div class="text-center text-muted py-5">
<div class="spinner-border text-warning mb-3" role="status"></div>
<p>正在抓取热点数据，请稍候...</p>
<small>页面将每 5 秒自动刷新</small>
</div>
```
### 7.3 热点级汇总报告页（`/hotspots/{hotspot_id}/report`）
页面目标：展示跨内容条目的聚合分析结果。
#### 热点报告页面包屑
```html
<nav aria-label="breadcrumb">
<ol class="breadcrumb">
<li class="breadcrumb-item"><a href="/">首页</a></li>
<li class="breadcrumb-item"><a href="/tasks/{{ task.id }}">任务 #{{ task.id }}</a></li>
<li class="breadcrumb-item"><a href="/tasks/{{ task.id }}">热点 #{{ hotspot.rank }}：{{ hotspot.title }}</a></li>
<li class="breadcrumb-item active">汇总报告</li>
</ol>
</nav>
```
#### 顶部操作栏
右上角提供：
- `导出 Markdown 报告`
- `导出热点下全部评论 CSV`
导出按钮可用状态遵循「导出交互规范」章节。
#### 数据看板
基础统计卡片：
- 关联内容条目数。
- 评论样本总量。
- 成功分析评论数。
- AI 分析状态。
#### 情绪分布展示规范
情绪分布不能只展示百分比，必须并列展示具体条数：
```html
<!-- 正向情绪行示例 -->
<div class="d-flex justify-content-between mb-1">
<span>🟩 正向</span>
<span class="text-muted">{{ positive_count }} 条（{{ positive_pct }}%）</span>
</div>
<div class="progress mb-3" style="height: 12px;">
<div class="progress-bar bg-success" style="width: {{ positive_pct }}%"></div>
</div>
```
三种情绪（正向 / 中性 / 负向）均按此格式展示，数据来源为 `report.metrics_json` 中的情绪统计字段。
#### 标签与总结
- Top 5 标签云：例如 `[ 价格实惠 (15) ] [ 质量好 (12) ] [ 物流慢 (8) ]`。
- AI 热点总结：使用浅蓝色 Callout 展示，不超过 300 字。
- 如果 `analysis_status = insufficient`，展示样本不足 Alert。
- 如果 `analysis_status = failed`，展示「总结生成失败，请查看上方统计数据。」灰色文本。
#### 典型评论
按情绪分列展示：
- 正向代表：1-2 条，显示点赞数。
- 中性代表：1-2 条，显示点赞数。
- 负向代表：1-2 条，显示点赞数。
### 7.4 内容条目详情页（`/items/{item_id}`）
页面目标：单条内容的深度报告与评论明细展示。
#### 顶部操作栏
- `导出 Markdown 报告`
- `导出 CSV 评论明细`
#### 原始内容链接
在内容条目基础信息区域末尾展示：
```html
{% if item.url %}
<a href="{{ item.url }}" target="_blank" rel="noopener noreferrer" class="btn btn-sm btn-outline-secondary">
🔗 查看原始内容
</a>
{% else %}
<button class="btn btn-sm btn-outline-secondary" disabled title="原始链接不可用">
🔗 查看原始内容
</button>
{% endif %}
```
#### 区域 A：内容条目级分析报告
结构与热点级报告一致，但范围限定为单个内容条目：
- 样本评论数量。
- 情绪条数和占比。
- Top 5 标签。
- AI 总结，建议 200 字以内。
- 典型评论。
如果报告尚未生成，展示 Spinner +「报告生成中，请稍候...」。
#### 原始 JSON 调试入口（原生折叠，零 JS）
```html
<details class="mt-3">
<summary class="btn btn-sm btn-outline-secondary" style="display: inline-block; cursor: pointer;">
🐞 查看原始 JSON（调试）
</summary>
<div class="mt-2 p-3 bg-light rounded border">
<pre class="mb-0" style="max-height: 400px; overflow-y: auto; font-size: 0.8em;">{{ item.raw_data | tojson(indent=2) }}</pre>
</div>
</details>
```
优点：
- 零 JS 依赖，使用 HTML5 原生 `<details>/<summary>` 元素。
- 自动支持长内容滚动，不存在 Modal 在小屏幕溢出的问题。
- 点击展开 / 再点收起，体验如手风琴折叠。
#### 区域 B：评论明细列表
#### 评论明细展示策略
- MVP 阶段评论明细**一次性展示，不做后端分页**。
- 最多展示 100 条评论，按**点赞数降序**排列；点赞数相同时按**评论时间降序**。
- 若评论总数超过 50 条，在表格上方展示数量提示：
```html
<div class="d-flex justify-content-between align-items-center mb-2">
<span class="text-muted small">共 {{ total_comment_count }} 条评论，展示前 {{ comments | length }} 条</span>
<span class="text-muted small">如需查看全部，请导出 CSV</span>
</div>
```
表头：
```text
评论 ID / 评论内容 / 情绪倾向 / 方向标签 / 点赞数 / 评论时间
```
展示逻辑：
- 情绪倾向：使用 `sentiment_badge` Macro。
- 方向标签：将 JSON Array 解析为多个独立的小 Tag 块；为空显示 `-`。
- 评论内容：长文本使用 CSS `text-truncate`，可在详情或 tooltip 中查看完整内容。
- 若 `comment.analysis_status == 'failed'`，情绪列显示「解析失败」红色文字，不影响其他行。
- 若评论为空，展示「暂无评论数据（该内容无评论或评论抓取为空）」。
## 8. 表单校验、交互状态与空状态
### 8.1 表单校验行为
前端拦截：
- 热点数量范围：`1-10`。
- 每热点内容上限范围：`1-10`。
- 每内容评论上限范围：`10-100`。
- 输入非法值时，Input 边框变红，失去焦点及提交时显示提示文本，例如「最大值为 10」。
- 非法输入阻止提交。
后端双重校验：
- 若绕过前端提交，FastAPI 返回 HTTP 422。
- 页面通过异步 JS 将错误信息渲染到 `#form-error` Alert。
### 8.2 空状态场景
| 场景 | 页面 | 展示内容 |
|---|---|---|
| 任务列表无任何任务 | 首页 | 「还没有任何任务，请在上方创建第一个任务 🚀」 |
| 任务 running 但热点列表为空 | 任务详情页 | Spinner + 「正在抓取热点数据，请稍候...」 |
| 热点下评论数为 0 | 内容详情页评论区 | 「暂无评论数据（该内容无评论或评论抓取为空）」 |
| 任务刚创建未开始（`started_at` 为空） | 任务列表进度列 | 「等待开始...」灰色文字 |
| AI 样本不足（`analysis_status = insufficient`） | 报告页总结区域 | ⚠️ Alert：「当前有效评论样本不足，AI 总结暂不可用。建议增加评论抓取数量后重新分析。」 |
| AI 总结生成失败（`analysis_status = failed`） | 报告页总结区域 | 「总结生成失败，请查看上方统计数据。」灰色文字 |
| 报告尚未生成（内容条目分析中） | 内容详情页报告区 | Spinner + 「报告生成中，请稍候...」 |
| 导出文件内容为空 | 导出按钮点击后 | `alert("当前暂无可导出评论数据")` |
### 8.3 单条目失败不阻塞
如果某个视频或笔记抓取失败：
- 手风琴列表中该条目置灰。
- 不可点击详情。
- 状态列显示失败原因，例如「API 限流」。
- 其他成功条目仍可查看报告和评论明细。
如果 AI 总结生成失败：
- 页面不应 500。
- 总结区域展示「总结生成失败，请查看上方统计数据。」。
- 结构化统计和评论明细仍正常展示。
## 9. 导出交互规范
### 导出按钮可用/置灰前提条件
| 场景 | 按钮状态 | Tooltip 文本 |
|---|---|---|
| `task.status = running` | `disabled` | 任务运行中，请等待完成后导出 |
| `task.status = failed` 且无成功内容条目 | `disabled` | 任务失败，无可导出数据 |
| `item.status = crawl_failed` | `disabled` | 内容抓取失败，无评论数据 |
| 可导出（任务已完成且有数据） | 可点击 | — |
| 评论数为 0 | `disabled` | 当前暂无可导出评论数据 |
### 导出交互实现（增强型 JS Blob 下载）
```javascript
// static/app.js
async function downloadExport(url, defaultFilename) {
const btn = event.currentTarget;
const originalText = btn.innerHTML;
// 1. 按钮置灰，显示 Loading
btn.disabled = true;
btn.innerHTML = `<span class="spinner-border spinner-border-sm"></span> 生成中...`;
try {
const resp = await fetch(url);
if (!resp.ok) {
alert("导出失败，请稍后重试。");
return;
}
// 2. 从响应头获取文件名
const disposition = resp.headers.get("Content-Disposition");
const filenameMatch = disposition && disposition.match(/filename\*?=(?:UTF-8'')?["']?([^"';\n]+)/i);
const filename = filenameMatch ? decodeURIComponent(filenameMatch[1]) : defaultFilename;
// 3. 触发浏览器下载
const blob = await resp.blob();
const blobUrl = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = blobUrl;
a.download = filename;
document.body.appendChild(a);
a.click();
document.body.removeChild(a);
URL.revokeObjectURL(blobUrl);
} catch (e) {
alert("网络异常，请检查连接后重试。");
} finally {
// 4. 恢复按钮状态
btn.disabled = false;
btn.innerHTML = originalText;
}
}
```
### 导出按钮 HTML 示例
```html
<!-- 内容条目详情页导出区域 -->
<div class="d-flex gap-2 mt-3">
<button
class="btn btn-outline-primary"
onclick="downloadExport('/api/export/items/{{ item.id }}/comments.csv', 'comments.csv')"
{% if item.status != 'success' %}disabled title="内容抓取失败，无评论数据"{% endif %}>
⬇️ 导出评论 CSV
</button>
<button
class="btn btn-outline-secondary"
onclick="downloadExport('/api/export/items/{{ item.id }}/report.md', 'report.md')"
{% if not report %}disabled title="报告尚未生成"{% endif %}>
⬇️ 导出 Markdown 报告
</button>
</div>
```
### CSV 导出安全处理（防 Excel 公式注入）
后端 `export_service.py` 导出 CSV 时，若评论内容首字符为 `=`、`+`、`-`、`@`，须在该字符前添加单引号前缀：
```python
def sanitize_csv_field(value: str) -> str:
"""防止 CSV 公式注入"""
if value and value[0] in ('=', '+', '-', '@'):
return f"'{value}"
return value
```
此项为后端实现规范，在 UIDesign 中作为说明记录。
## 10. 实施建议
### 10.1 模板复用
模板结构建议使用 Jinja2 的 `{% extends "base.html" %}` 和 `{% block content %}` 减少重复代码。
页面级模板仅负责布局和数据展示，状态 Badge、情绪 Badge、标签列表等重复结构应抽成 Macro。
### 10.2 样式框架
为了在 4 天 MVP 周期内完成，建议在 `base.html` 中直接引入 Bootstrap 5（CSS + JS bundle）。Accordion、Badge、Progress Bar、Alert、Table、Button 等组件开箱即用。
### 10.3 Jinja2 自定义 Filter 注册（必须在 main.py 中完成）
原生 Jinja2 **没有** `from_json` Filter，直接在模板中使用 `{{ value | from_json }}` 会抛出 `TemplateAssertionError`。须在 FastAPI 初始化时手动注册：
```python
# app/main.py
import json
from fastapi.templating import Jinja2Templates
templates = Jinja2Templates(directory="templates")
def from_json_filter(value):
"""将 JSON 字符串解析为 Python 对象，用于 Jinja2 模板"""
try:
return json.loads(value) if value else []
except (json.JSONDecodeError, TypeError):
return []
templates.env.filters["from_json"] = from_json_filter
```
注册后，模板中可安全使用：
```jinja2
{% for label in comment.labels | from_json %}
<span class="badge bg-secondary">{{ label }}</span>
{% else %}
<span class="text-muted">-</span>
{% endfor %}
```
### 10.4 base.html CDN 引入顺序
HTMX 必须在 Bootstrap JS Bundle 之后引入，避免事件冲突。推荐的 `<head>` 结构：
```html
<!-- ① Bootstrap 5 CSS -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
<!-- ② 自定义样式 -->
<link href="/static/app.css" rel="stylesheet">
<!-- ③ Bootstrap 5 JS Bundle（含 Popper，须在 HTMX 之前） -->
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
<!-- ④ HTMX（P1 轮询方案，可选） -->
<script src="https://unpkg.com/htmx.org@1.9.12"></script>
<!-- ⑤ 自定义 JS（defer 确保 DOM 加载完成后执行） -->
<script src="/static/app.js" defer></script>
```
### 10.5 Jinja2 `|safe` Filter 使用约束
- Jinja2 默认对所有变量启用 HTML 转义，**禁止随意使用 `|safe`**。
- 仅在以下场景允许使用 `|safe`：由后端程序生成、非用户输入的可信 HTML 片段（如报告 Markdown 渲染后的 HTML）。
- 所有来源于外部平台的评论内容、热点标题、用户昵称等字段，严禁使用 `|safe`，必须经过 Jinja2 默认转义。
- 外部链接须添加安全属性：`<a href="..." target="_blank" rel="noopener noreferrer">`。
## 11. 模板目录结构与 Jinja2 组件规范
### 模板目录结构
```text
templates/
├── base.html # 全局布局：导航栏、面包屑、CSS/JS 引入
├── index.html # 首页 / 任务列表页
├── tasks/
│ └── detail.html # 任务详情页（热点手风琴）
├── hotspots/
│ └── report.html # 热点级汇总报告页
├── items/
│ └── detail.html # 内容条目详情页
└── partials/
├── task_rows.html # 任务列表表格行（HTMX 局部刷新片段）
├── status_badge.html # 任务状态 Badge 组件
├── sentiment_badge.html # 情绪倾向 Badge 组件
└── label_tags.html # 标签 Badge 列表组件
```
### Jinja2 Macro 组件规范
#### status_badge（任务状态 Badge）
在 `partials/status_badge.html` 中定义：
```jinja2
{% macro status_badge(status) %}
{% set config = {
"pending": ("等待中", "bg-secondary"),
"running": ("运行中", "bg-warning text-dark"),
"success": ("已完成", "bg-success"),
"failed": ("失败", "bg-danger"),
} %}
{% set label, style = config.get(status, ("未知", "bg-secondary")) %}
<span class="badge {{ style }}">{{ label }}</span>
{% endmacro %}
```
使用方式：
```jinja2
{% from "partials/status_badge.html" import status_badge %}
{{ status_badge(task.status) }}
```
#### sentiment_badge（情绪倾向 Badge）
```jinja2
{% macro sentiment_badge(sentiment) %}
{% set config = {
"positive": ("正向", "bg-success"),
"neutral": ("中性", "bg-warning text-dark"),
"negative": ("负向", "bg-danger"),
} %}
{% set label, style = config.get(sentiment, ("未知", "bg-secondary")) %}
<span class="badge {{ style }}">{{ label }}</span>
{% endmacro %}
```
#### label_tags（标签列表）
```jinja2
{% macro label_tags(labels_json) %}
{% for label in labels_json | from_json %}
<span class="badge bg-secondary me-1">{{ label }}</span>
{% else %}
<span class="text-muted">-</span>
{% endfor %}
{% endmacro %}
```
## 12. 模板变量结构参考
以下为各页面 Jinja2 模板的后端数据结构示例，供模板开发对照使用。
### 首页（index.html）
```python
{
"tasks": [
{
"id": 123,
"platform": "xhs", # "xhs" | "douyin"
"created_at": "2025-01-01 10:00:00",
"hotspot_limit": 5,
"item_limit": 5,
"comment_limit": 50,
"total_items_count": 25,
"successful_items_count": 18,
"failed_items_count": 3,
"status": "running", # 见状态枚举
"analysis_status": "normal", # 见状态枚举
"error_stage": None,
"error_type": None,
"error_message": None,
}
]
}
```
### 内容条目详情页（items/detail.html）
```python
{
"task": { "id": 123, "platform": "douyin" },
"hotspot": { "id": 456, "rank": 1, "title": "热点标题" },
"item": {
"id": 789,
"title": "视频标题",
"platform": "douyin",
"url": "https://www.douyin.com/video/xxx",
"status": "success",
"raw_data": { ... }, # 调试用，通过 | tojson 渲染
},
"report": {
"comment_count": 100,
"sentiment": {
"positive": { "count": 60, "pct": 60.0 },
"neutral": { "count": 20, "pct": 20.0 },
"negative": { "count": 20, "pct": 20.0 },
},
"top_labels": [
{ "name": "价格实惠", "count": 15 },
{ "name": "质量好", "count": 12 },
],
"summary": "该内容评论整体偏正向，用户对价格和质量满意度较高...",
"analysis_status": "success",
},
"comments": [
{
"id": 1,
"content": "这个产品不错",
"sentiment": "positive",
"labels": "[\"质量好\", \"价格实惠\"]", # JSON 字符串，模板用 | from_json 解析
"like_count": 20,
"created_at": "2025-01-01 11:00:00",
"analysis_status": "success",
}
],
"total_comment_count": 150, # 数据库实际总数，用于"展示前 N 条"提示
}
```
---
## 变更日志
| 日期 | 版本 | 变更内容 |
|---|---|---|
| 2025-07-10 | v1.0 | 初始版本 |
| 2025-07-10 | v1.1 | 基于双审阅报告合并修订（共 17 条指令）：补充文档元数据；新增完整路由总表（页面路由 / API 接口 / HTMX 局部刷新 / 导出接口）；新增状态枚举与 UI 映射规范（Task / Item / Comment / sentiment 四层）；新增面包屑路径与 `<title>` 命名规范；表单提交改为异步 JS fetch 模式，422 错误表单内渲染；新增表单规模预估实时计算提示；任务列表错误信息从 Hover 改为直接展示 error_stage / error_type；修复 HTMX 代码片段截断问题，补全含条件触发的完整轮询示例；补充任务概览看板字段清单、手风琴默认展开规则和热点报告按钮置灰条件；情绪分布改为数值+百分比并列展示；评论明细限制 100 条 + 总数提示 + 按点赞数降序；新增原始内容 URL 跳转入口；JSON 调试入口从 Modal 改为原生 `<details>` 折叠；导出交互改为增强型 JS Blob 下载 + 补充按钮可用/置灰前提条件 + CSV 公式注入防护；补充 Jinja2 from_json filter 注册规范；补充 CDN 引入顺序和 `|safe` 使用约束；新增模板目录结构与三个 Jinja2 Macro 组件规范（status_badge / sentiment_badge / label_tags）；补充 8 条空状态场景；新增模板变量结构参考（首页 + 内容详情页）。 |