Simon
facc04aa65
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交 （5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。 一、docs 结构整改（整改 #14） 根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入， 随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录 树并存于 docs/，共 791 文件、双分类体系冲突。 修复动作： - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除（新结构已有内容副本） - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维 结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。 残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。 二、compose 双目录对齐（消除踩坑 A） - docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist（h5 / agent / admin / terminal） - docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/ - 效果：本地 docker compose up 不再把根目录 stale dist 挂回， 与线上一致，分叉隐患消除（已 docker compose config 校验通过） 防复发铁律： - 重构须提交；仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交，避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
150 lines
4.4 KiB
Markdown
150 lines
4.4 KiB
Markdown
# 知识迭代模块 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"
|
||
```
|