# 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 条空状态场景；新增模板变量结构参考（首页 + 内容详情页）。 |