# Prompt 详情页测试 CSRF 初始化缺失 + 博客详情页评论空态文案优化

> **版本**: v1.0  
> **日期**: 2026-05-24  
> **状态**: 📝 待评审

---

## 一、背景与目标

本次 PRD 合并处理两个独立但都较明确的问题：

1. **Prompt 详情页测试功能首次使用时报 CSRF token 验证失败**  
   用户在已登录状态下访问公开提示词详情页（如 `/prompts/{key}`），在测试面板中选择模型、填写 user 输入后点击“开始测试”，首次请求可能直接返回 `CSRF token 验证失败`。但如果先进入 `/admin/settings` 页面并执行一次“测试模型连通性”，再回到相同提示词详情页，使用完全相同输入重新点击“开始测试”，则请求又可以正常成功。

2. **博客详情页无评论时的空态文案不符合期望**  
   当前 `/posts/{slug}` 页面在无评论时会显示：
   `💬 暂无评论，来发表第一条评论吧！`
   需求是：**博客详情页不要显示这句话**。

这两个问题都属于前端展示/交互层的可预期缺陷，适合在同一轮小修中一起纳入。

---

## 二、问题一：Prompt 详情页首次测试触发 CSRF 校验失败

### 2.1 现象

以页面：
`https://prompt.ephron.ren/prompts/prompt-20260508110413`
为例，在已登录状态下：

1. 打开提示词详情页
2. 切换到“测试”标签
3. 正确选择模型
4. 输入 user 内容
5. 点击“开始测试”

**实际行为**：返回 `CSRF token 验证失败`

随后：

1. 访问 `https://prompt.ephron.ren/admin/settings`
2. 点击测试模型连通性
3. 页面提示 `连接成功！模型: deepseek-v4-flash`
4. 再返回刚才的提示词详情页
5. 保持完全相同的模型与输入，再次点击“开始测试”

**实际行为**：此时请求成功，模型可以正常调用。

### 2.2 影响范围

- 影响所有带“测试”面板的公开提示词详情页：`/prompts/{key}`
- 影响所有已登录但**首次从公开详情页直接发起测试**的用户
- 若用户此前访问过某些会设置 CSRF cookie 的后台页面，问题可能被“掩盖”
- 不影响仅浏览正文、不使用测试功能的用户

### 2.3 已定位的源码

#### 详情页路由
文件：`prompt/src/routes/pages.py`

```python
@router.get("/prompts/{key}", response_class=HTMLResponse)
async def prompt_detail(request: Request, key: str):
    prompt = get_prompt(key)
    ...
    return templates.TemplateResponse(
        "public/detail.html",
        {
            "request": request,
            "prompt": prompt,
            "split_csv": _split_csv,
            "models": models,
        },
    )
```

当前实现直接渲染详情页，但**没有为该页面生成并下发 CSRF cookie**。

#### 详情页测试前端
文件：`prompt/static/js/test-prompt.js`

```javascript
const csrfToken = document.cookie.match(/ephron_csrf=([^;]+)/)?.[1] || '';
const response = await fetch(`/api/prompts/${this.promptKey}/test`, {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-CSRF-Token": csrfToken,
    },
    body: JSON.stringify(body),
    signal: this.abortController.signal,
});
```

前端完全依赖 `document.cookie` 中存在 `ephron_csrf`。如果 cookie 不存在，就会发送空字符串。

#### 测试接口后端
文件：`prompt/src/routes/api.py`

```python
csrf_cookie = request.cookies.get("ephron_csrf")
csrf_header = request.headers.get("X-CSRF-Token")
if not verify_csrf_token(csrf_header, csrf_cookie):
    raise HTTPException(status_code=403, detail="CSRF token 验证失败")
```

后端要求：
- cookie 中有 `ephron_csrf`
- header 中有 `X-CSRF-Token`
- 两者一致

否则直接返回 403。

#### admin/settings 页面为何会“治好”问题
文件：`prompt/src/routes/admin.py`

```python
@router.get("/settings", response_class=HTMLResponse)
async def settings_page(...):
    ...
    csrf_token = generate_csrf_token()
    response = templates.TemplateResponse(...)
    set_csrf_cookie(response, csrf_token, is_development=IS_DEVELOPMENT)
    return response
```

即：访问 `/admin/settings` 时，服务端会显式生成 token 并设置 `ephron_csrf` cookie。  
因此用户访问过后台设置页后，详情页测试 JS 才终于能从 `document.cookie` 里读到 token，于是测试恢复正常。

### 2.4 根因分析

根因不是模型配置问题，也不是测试接口本身偶发失败，而是：

> **公开提示词详情页的测试功能依赖 CSRF cookie，但详情页自身没有负责初始化这个 cookie。**

换言之：

- **依赖方**：`/prompts/{key}` 页面的“开始测试”功能
- **提供方**：当前却变成了 `/admin/settings` 这类后台管理页面
- **结果**：首次从公开详情页直接测试时，前置条件不满足，导致必现/高概率出现 403

这是一个**初始化时机错误**问题：
- 测试功能属于公开详情页的一部分
- 因此其所依赖的 CSRF token 也应由详情页自身在 GET 阶段准备好
- 不应要求用户先访问后台页面“预热”环境

### 2.5 解决方案

#### 方案 A：在公开详情页 GET 路由中补发 CSRF cookie（推荐）

在 `prompt/src/routes/pages.py` 的 `prompt_detail()` 中：

1. 生成新的 CSRF token
2. 用 `TemplateResponse` 组装响应对象
3. 调用共享的 `set_csrf_cookie(response, csrf_token, is_development=IS_DEVELOPMENT)`
4. 返回 response

参考后台页面已有模式，保持站点内 CSRF 初始化策略一致。

**优点**：
- 根因级修复
- 用户首次进入详情页即可直接测试
- 行为与后台页面一致，代码路径清晰
- 不需要新增 API，不引入额外异步初始化流程

#### 方案 B：前端在缺 token 时给出明确提示（推荐作为兜底，而不是主修复）

在 `prompt/static/js/test-prompt.js` 中：

- 若 `document.cookie` 中取不到 `ephron_csrf`
- 不要直接发请求
- 改为在界面中提示：
  - `安全令牌未初始化，请刷新页面后重试`
  - 或更温和的错误提示文案

**说明**：这只能改善体验，不能替代 A。因为没有根修复时，刷新也不一定能拿到 token；只有详情页本身负责种 cookie，刷新才有意义。

### 2.6 实现建议

#### 后端改动
文件：`prompt/src/routes/pages.py`

- 增加对共享 CSRF 工具的导入：
  - `generate_csrf_token`
  - `set_csrf_cookie`
- 在 `prompt_detail()` 中：
  - 先生成 token
  - 再构造 `TemplateResponse`
  - 再对 response 调用 `set_csrf_cookie()`

实现形态建议与 `admin.py` 保持一致，避免两套风格。

#### 前端改动
文件：`prompt/static/js/test-prompt.js`

在执行 `fetch()` 前增加判断：

```javascript
const csrfToken = document.cookie.match(/ephron_csrf=([^;]+)/)?.[1] || '';
if (!csrfToken) {
    throw new Error('安全令牌未初始化，请刷新页面后重试');
}
```

这样至少避免把“空 token”静默发到后端。

### 2.7 验收标准

#### 功能验收
1. 已登录用户首次直接访问任意公开提示词详情页
2. 不访问任何后台页面
3. 直接进入“测试”标签
4. 选择模型、输入 user 内容后点击“开始测试”
5. 请求成功，页面正常流式返回模型输出

#### 回归验收
1. 后台 `admin/settings` 的连通性测试功能不受影响
2. 详情页在未登录状态下仍保持原有鉴权行为（如测试接口要求登录则仍返回 401）
3. 详情页正文、标签、示例、模型下拉等渲染不受影响

#### 失败场景验收
1. 若前端在极端情况下仍未读取到 token，应展示可理解错误提示，而不是只有通用“请求失败”
2. 不应再出现“访问后台设置页后才恢复”的异常依赖关系

### 2.8 测试补齐建议

现有测试中，很多 API case 是直接手动塞入：
- `ephron_auth`
- `ephron_csrf`
- `X-CSRF-Token`

这验证了 API 校验本身，但掩盖了“公开详情页没有负责初始化 cookie”的集成缺口。

建议新增测试：

#### 集成测试 1：详情页 GET 应设置 CSRF cookie
文件建议：`prompt/tests/test_prompt_service_api.py` 或更适合的 pages 路由测试文件

步骤：
1. 创建一个可访问的 active prompt
2. 使用已登录 client 访问 `/prompts/{key}`
3. 断言响应或 client cookies 中出现 `ephron_csrf`

#### 集成测试 2：首次访问详情页后可直接调用测试接口
步骤：
1. 已登录 client 先 GET `/prompts/{key}`
2. 从 client cookies 中读取 `ephron_csrf`
3. 直接 POST `/api/prompts/{key}/test`
4. header 中传同一 token
5. 断言不返回 403 CSRF 错误

---

## 三、问题二：博客详情页无评论时不要显示“暂无评论，来发表第一条评论吧！”

### 3.1 现象

当前博客详情页 `/posts/{slug}` 在评论列表为空时，会显示带图标的空态提示：

```text
💬
暂无评论，来发表第一条评论吧！
```

需求是：

> **博客详情页不要显示这句话。**

### 3.2 已定位的源码

文件：`blog/templates/post.html`

```javascript
function renderComments(comments) {
    if (comments.length === 0) {
        commentsList.innerHTML = '<div class="no-comments"><div class="no-comments-icon">💬</div><p>暂无评论，来发表第一条评论吧！</p></div>';
        return;
    }

    commentsList.innerHTML = comments.map(comment => renderComment(comment)).join('');
}
```

### 3.3 根因分析

这是一个纯展示层文案问题：
- 当前空态提示写死在前端模板 JS 中
- 文案过于主动，不符合当前页面的简洁展示要求

### 3.4 解决方案

有两种可选实现：

#### 方案 A：保留空态容器，但移除该句文案（推荐）

将空评论时的 HTML 改为：
- 不显示这句“暂无评论，来发表第一条评论吧！”
- 可以仅保留空容器
- 或仅保留图标
- 或改成空字符串

推荐最保守方案：
- 直接将 `commentsList.innerHTML = ''`
- 让评论区在无评论时不额外渲染提示文本

这样最符合“不要显示这句话”的字面要求，也最干净。

#### 方案 B：替换为更中性的极简文案

例如仅显示：
- `暂无评论`

但由于需求明确说“不要显示这句话”，且没有明确要求保留任何替代文案，因此不建议自行引入新文案。

### 3.5 验收标准

1. 任意无评论博客详情页打开后
2. 评论区域不再显示：`暂无评论，来发表第一条评论吧！`
3. 不影响有评论时的正常渲染
4. 不影响评论数统计、评论提交、回复渲染等现有逻辑

---

## 四、实施范围

### Prompt 侧
- `prompt/src/routes/pages.py`
- `prompt/static/js/test-prompt.js`
- `prompt/tests/...`（补测试）

### Blog 侧
- `blog/templates/post.html`

---

## 五、风险与注意事项

### 5.1 Prompt CSRF 修复风险

- 若详情页每次 GET 都生成并覆盖 CSRF cookie，需要确认不会破坏站内其他表单/接口的当前交互流程
- 但现有后台页已经是同样模式，因此风险较低
- 需要注意与 `shared/csrf.py` 的有效期和 secure/domain 配置保持一致

### 5.2 评论空态调整风险

- 若直接清空评论区，需要确认样式和布局不会出现异常留白
- 这是低风险前端调整，但建议实际看一眼无评论页面效果

---

## 六、上线后预期结果

### Prompt 详情页
用户首次直接进入公开提示词详情页测试时即可成功调用模型，不再依赖先访问 `/admin/settings` 页面“激活”环境。

### 博客详情页
无评论文章页将更干净，不再出现“暂无评论，来发表第一条评论吧！”的提示。

---

## 七、建议提交拆分

虽然本 PRD 合并记录了两个问题，但实际开发提交建议可按以下粒度：

1. `fix(prompt): initialize csrf cookie on public prompt detail page`
2. `fix(blog): remove no-comments prompt text on post detail page`

如果实现量很小，也可合并成一次小修提交，但 PR 描述中应明确包含两个修复点。