From 7d747fd33a1fcbf155ce5eb3e111d64ce493aca0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=B0=8F=E7=99=BD?= <xiaobai@openclaw.ai>
Date: Sun, 15 Mar 2026 13:31:07 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E9=97=AE=E9=A2=98?=
 =?UTF-8?q?=E8=AE=B0=E5=BD=95=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 docs/ISSUES.md 问题记录文档
- 记录问题 #001：新建机器人报 Failed to fetch 错误
- 包含问题现象、原因分析、解决方案
- 提供问题记录模板
---
 docs/ISSUES.md | 166 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 166 insertions(+)
 create mode 100644 docs/ISSUES.md

diff --git a/docs/ISSUES.md b/docs/ISSUES.md
new file mode 100644
index 0000000..b49e569
--- /dev/null
+++ b/docs/ISSUES.md
@@ -0,0 +1,166 @@
+# 问题记录文档
+
+> 记录智队中枢项目开发过程中发现的问题、原因分析和解决方案
+
+---
+
+## 问题 #001：新建机器人报 "Failed to fetch" 错误
+
+### 问题现象
+
+**发现时间**：2026-03-15
+
+**发现版本**：v0.9.8
+
+**问题描述**：
+用户在智队中枢 Web 页面点击「新建机器人」按钮，填写表单提交后，前端报错：
+```
+Failed to fetch
+```
+
+**影响范围**：
+- 新建机器人功能
+- 所有 `/api/bots` 相关请求
+
+---
+
+### 问题原因
+
+**根本原因**：Flask 路由尾部斜杠不一致导致 301 重定向
+
+**详细分析**：
+
+| 组件 | 路径 | 说明 |
+|------|------|------|
+| Flask 蓝图注册 | `url_prefix='/api/bots'` | 无尾部斜杠 |
+| Flask 路由定义 | `@bots_bp.route('/')` | 有前导斜杠 |
+| 实际完整路径 | `/api/bots/` | **有尾部斜杠** |
+| 前端请求路径 | `fetch('/api/bots')` | **无尾部斜杠** |
+
+**错误流程**：
+
+```
+1. 前端发送 POST /api/bots（无尾部斜杠）
+         ↓
+2. Flask 返回 301 重定向 → /api/bots/（有尾部斜杠）
+         ↓
+3. POST 请求被重定向时：
+   - 某些浏览器会将 POST 改为 GET
+   - fetch API 无法正确处理重定向
+         ↓
+4. 前端报错 "Failed to fetch"
+```
+
+**验证结果**：
+
+```bash
+# 不带尾部斜杠 → 301 重定向
+curl -X POST http://localhost:9000/api/bots
+# 返回: Redirecting to /api/bots/
+
+# 带尾部斜杠 → 正常响应
+curl -X POST http://localhost:9000/api/bots/
+# 返回: {"msg": "Not enough segments"}  # 正常的 JWT 错误
+```
+
+---
+
+### 解决方案
+
+**方案一：前端修改（推荐）**
+
+修改 `frontend/src/components/chat/CreateBotModal.vue`：
+
+```typescript
+// 修改前
+const response = await fetch('/api/bots', {
+
+// 修改后
+const response = await fetch('/api/bots/', {
+```
+
+**方案二：后端修改**
+
+修改 `app/routes/bots.py`：
+
+```python
+# 修改前
+@bots_bp.route('/', methods=['POST'])
+
+# 修改后
+@bots_bp.route('', methods=['POST'])
+```
+
+**方案三：Flask 配置（全局生效）**
+
+在 `app/__init__.py` 中添加：
+
+```python
+app.url_map.strict_slashes = False
+```
+
+---
+
+### 解决状态
+
+| 状态 | 日期 |
+|------|------|
+| ⏳ 待修复 | - |
+
+---
+
+## 问题记录模板
+
+```markdown
+## 问题 #XXX：[问题标题]
+
+### 问题现象
+
+**发现时间**：YYYY-MM-DD
+
+**发现版本**：vX.X.X
+
+**问题描述**：
+[描述问题现象]
+
+**影响范围**：
+- [影响的功能模块]
+
+---
+
+### 问题原因
+
+**根本原因**：[一句话概括]
+
+**详细分析**：
+[详细的原因分析]
+
+---
+
+### 解决方案
+
+**方案**：[解决方案描述]
+
+**代码修改**：
+```语言
+// 修改前
+[代码]
+
+// 修改后
+[代码]
+```
+
+---
+
+### 解决状态
+
+| 状态 | 日期 |
+|------|------|
+| ✅ 已修复 | YYYY-MM-DD |
+
+---
+```
+
+---
+
+_文档创建时间：2026-03-15 | 维护者：小白 🐶_