# 知识迭代模块 Bug 修复报告

> **日期**: 2026-07-11  
> **修复人**: 寇豆码（工程师） / 严过关（QA验证）  
> **团队**: `software-bugfix-ki-bugs`  
> **测试**: 21/21 通过  
> **部署状态**: ⏳ 待部署（`docker compose restart backend`）

---

## 修复概览

| # | 优先级 | 问题 | 修复文件 | 状态 |
|---|--------|------|---------|------|
| 8 | P1 | `POST /suggestions` 返回 405 | `knowledge_iteration.py` | ✅ |
| 7 | P2 | Neo4j 关系创建重复 | `neo4j_client.py` | ✅ |
| 6 | P2 | 过期建议状态永不更新 | `main.py` | ✅ |

---

## #8 P1: POST /suggestions 端点缺失

### 问题描述
- 前端 `KnowledgeIteration.vue:626` 发送 `POST /api/admin/knowledge-iteration/suggestions`
- 后端 `knowledge_iteration.py` 只有 `GET /suggestions`（行80），无 POST 根端点
- 返回 405 Method Not Allowed，手动创建建议功能完全不可用

### 修复方案
- **文件**: `backend/app/api/knowledge_iteration.py:168`
- **新增**: `create_suggestion` 端点
- **接收**: `KnowledgeSuggestionCreate` body（校验 title/content/source_type 必填）
- **创建**: 记录 status=pending
- **返回**: `KnowledgeSuggestionResponse`

### 代码变更
```python
@router.post("/suggestions", response_model=KnowledgeSuggestionResponse)
async def create_suggestion(
    suggestion: KnowledgeSuggestionCreate,
    db: Session = Depends(get_db),
    current_user = Depends(require_admin)
):
    """手动创建知识建议"""
    db_suggestion = KnowledgeSuggestion(
        title=suggestion.title,
        content=suggestion.content,
        source_type=suggestion.source_type,
        status="pending",
        created_by=current_user.id
    )
    db.add(db_suggestion)
    db.commit()
    db.refresh(db_suggestion)
    return db_suggestion
```

---

## #7 P2: Neo4j 关系创建重复

### 问题描述
- `neo4j_client.py:526` 使用 `CREATE` 而非 `MERGE`
- 重复审批会产生重复关系边，污染知识图谱

### 修复方案
- **文件**: `backend/app/services/neo4j_client.py:526`
- **变更**: Cypher 关键词 `CREATE` → `MERGE`（一词之差）
- 效果：关系创建幂等化，重复审批不再产生重复边

---

## #6 P2: 过期建议状态永不更新

### 问题描述
- `enums.py:34,53` 定义了 `expired` 状态
- `main.py:133-161` APScheduler 只注册了 `check_unreplied_sessions`
- 无 expired 检查 job，stats 中 expired 永远 = 0

### 修复方案
- **文件**: `backend/app/main.py`
- **新增函数**: `expire_pending_suggestions()`（行133）
- **注册定时任务**: APScheduler（行199），interval=1小时
- **SQL**: `UPDATE knowledge_suggestions SET status='expired' WHERE status='pending' AND created_at < NOW() - INTERVAL '72 hours'`

### 代码变更
```python
async def expire_pending_suggestions():
    """每小时检查并过期超过72小时未处理的pending建议"""
    async with AsyncSessionLocal() as db:
        await db.execute(text(
            "UPDATE knowledge_suggestions "
            "SET status='expired' "
            "WHERE status='pending' "
            "AND created_at < NOW() - INTERVAL '72 hours'"
        ))
        await db.commit()

# APScheduler 注册
scheduler.add_job(
    expire_pending_suggestions,
    trigger="interval",
    hours=1,
    id="expire_pending_suggestions",
    name="Expire pending knowledge suggestions"
)
```

---

## 测试覆盖

| 测试项 | 用例数 | 状态 |
|--------|--------|------|
| #8 POST /suggestions | 11 | ✅ |
| #7 MERGE 幂等 | 3 | ✅ |
| #6 过期检查 | 7 | ✅ |
| **合计** | **21** | **全部通过** |

测试文件: `backend/tests/test_bugfix_ki_suggestions.py`

---

## 预存 Bug（非本次修复）

> `backend/app/services/itsm_service.py:33`  
> `httpx.Timeout(connect=10.0, read=30.0)` 缺 write/pool 参数  
> 当前 httpx 版本要求四参数全传或传 default  
> QA 在 conftest.py 加了兼容补丁，生产环境仍需修复  
> **建议**: 改为 `httpx.Timeout(timeout=30.0, connect=10.0, read=30.0)`

---

## 部署指南

```bash
# 1. 确认代码已在服务器（bind mount ./app:/app/app）
# 2. 重启后端容器
docker compose restart backend

# 3. 验证
# 检查 POST /suggestions 端点
curl -sk -X POST https://localhost/api/admin/knowledge-iteration/suggestions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"test","content":"test","source_type":"manual"}'

# 检查 APScheduler 注册
docker logs wecom_it_backend 2>&1 | grep "expire_pending"
```