chore(docs): docs/ 目录全面重新编号 + 重组
**重构前**（旧编号 02-11）： - docs/02-产品需求/ → 00 产品规划/PRD - docs/03-技术架构/ → 01-05 子目录散落 - docs/04-原型设计/ → 01-02 产品设计（HTML 原型） - docs/05-原型设计/ → screens/ - docs/06-测试素材/ → 02-E2E / 03-功能 / 04-版本测试 - docs/07-项目管理/ → 任务说明书/日报/计划 - docs/08-安全审计/ → 审计报告 - docs/09-堡垒运维/ → toolbox / deploy - docs/10-项目管理/ → 任务说明书（重复） - docs/11-历史归档/ → deploy-nas-archived **重构后**（新编号 00-07，语义化）： - docs/00-产品开发流程与文档管理规范.md - docs/00-版本迭代总览.md - docs/01-产品文档/ （PRD/原型/认证/会话/AI 服务/坐席/集成） - docs/02-技术文档/ （技术方案/架构图/重构记录/前端改造/实现配置） - docs/03-测试文档/ （E2E/功能用例/版本报告/缺陷单） - docs/04-运维文档/ （部署运维/运维指南） - docs/05-运营文档/ （品牌推广/用户手册） - docs/06-安全审计/ （审计报告） - docs/07-项目管理/ （任务说明书/日报/计划/看板） **净收益**： - 目录编号与产品文档管理规范对齐（按文档阶段 01-07 编号） - 消除 02-产品需求 与 10-项目管理 的编号重叠 - 子目录按文档类型分组（如 01-产品文档/00-产品规划、01-产品文档/01-认证与登录） - 把运维/安全/项目管理从 0X 散落改为 04/06/07 合计 494 文件 + 78495 行 / - 14076 行
This commit is contained in:
Simon
@@ -0,0 +1,149 @@
|
||||
# 知识迭代模块 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"
|
||||
```
|
||||
Reference in New Issue
Block a user