# 全局搜索与高级检索方案

> 状态：已确认，开始实施
> 创建日期：2026-08-14
> 推进顺序：P1 → F1 → F2 → F3 → F4 → 测试

## 一、需求最终确认

### 1. 数据模型新增

| 字段 | 类型 | 适用对象 | 默认值 | 可改 |
|------|------|---------|--------|------|
| `organization_id` | 外键 → organizations | 主案/子案/附件 | 创建者当前 `organization_id` | ✅ |
| `organization_name` | 字符串（冗余） | 同上 | 创建者当前 `organization_name` | ✅（联动 id 改名） |

> 与现有的"创建者"字段独立维护。用户调岗不影响历史文档归属。

### 2. 检索条件矩阵

| 条件 | 控件 | 匹配字段 | 默认值 | 行为 |
|------|------|---------|--------|------|
| 简单关键词 | 顶部全局文本框 | 标题（主案/子案/附件） | 空=不过滤 | 模糊匹配 |
| 正文关键词 | 高级检索文本框 | `contentText`/`searchText` | 空=不过滤 | 模糊匹配 |
| 密级 | 高级检索多选框 | `securityLevel` | 不勾=不过滤 | 勾选项内 OR |
| 所属部门 | 高级检索文本框 | `organization_name` | 空=不过滤 | 模糊匹配 |

**叠加**：四条件全部 AND。

### 3. 列表行为

**主案列表**（顶部表格）：
- 简单关键词命中标题 → 入列表
- 简单关键词未命中主案标题，但命中其下可见子案/附件标题 → 主案入列表，显示徽章
  - `📄 子案 N` / `📎 附件 N`（同时命中同时显示）
- 高级检索条件（正文/密级/部门）只过滤主案本身——主案不满足则不入列表（即便其下子案/附件满足）
- 主案标题中的简单关键词 → 高亮

**子案/附件 Tab**（选中主案后）：
- 应用全部四条件到该主案下的子案/附件
  - 简单关键词匹配标题
  - 正文关键词匹配正文
  - 密级匹配密级
  - 所属部门匹配所属部门
- 仅显示满足全部条件的子案/附件
- 无满足项 → 完全空白
- 标题中的简单关键词 → 高亮
- 正文关键词命中 → 行下方延展 `contentSnippet` 片段并高亮（沿用现有样式）

### 4. UI 结构

```
┌──────────────────────────────────────────────────────────┐
│ 🔍 [ 全局关键词（匹配标题）                    ] [🔍] [⚙高级检索] │
│ ┌─高级检索（折叠态默认隐藏）────────────────────────────┐ │
│ │ 正文: [             ]  密级: ☐公开 ☐内部 ☐秘密 ☐机密 ☐绝密 │ │
│ │ 部门: [             ]                                  │ │
│ └─────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────┤
│ 主案列表（含命中徽章）                                    │
│ ┌────┬──────────────┬──────┬────┬────┬───────┐         │
│ │序号│ 名称         │ 类型 │密级│部门│更新   │         │
│ │ 1  │ 2026**作战** │ 秘密 │秘密│作战│07-12  │         │
│ │ 2  │ 训练方案  📄📎│ 内部 │内部│训练│06-30  │         │
│ └────┴──────────────┴──────┴────┴────┴───────┘         │
├──────────────────────────────────────────────────────────┤
│ [子案(N)] [附件(N)]                                       │
│ ┌────┬──────────────┬──────┬─────────────┐              │
│ │序号│ 名称         │ 密级 │ 部门        │              │
│ │ 1  │ 南路**作战** │ 秘密 │ 作战部      │              │
│ │    │ └ 📝 "...**作战**分队由..."      │ ← 正文片段    │
│ └────┴──────────────┴──────┴─────────────┘              │
└──────────────────────────────────────────────────────────┘
```

---

## 二、实施计划

### P1. 后端数据模型与迁移（约 3h）

| 步骤 | 文件 | 说明 |
|------|------|------|
| P1.1 | `backend/dms/models/document.py` | `Document` 模型新增 `organization_id` 外键 + `organization_name` 冗余字段（参照现有 `category_id`/`category_name` 模式） |
| P1.2 | `backend/migrations/versions/0006_document_organization.py` | down_revision=`0005_category_flat_mode`；添加列；按 `creator_id → users.organization_id` 回填历史；回填 `organization_name` |
| P1.3 | `backend/dms/services/document_query_service.py` `document_summary` | 响应 DTO 新增 `organizationId`/`organizationName`；`document_mutation_service.py` 创建/更新分支接收 `organizationId`（缺省取 `AuthContext.organization_id`） |
| P1.4 | `backend/dms/services/organization_service.py` `update_organization` | 在第 381-395 行附近追加 Document 的 `organization_name` 批量刷新（与 User 刷新一致） |

### P2. 后端接口扩展（约 4h）

| 步骤 | 文件 | 说明 |
|------|------|------|
| P2.1 | `backend/dms/api/v1/documents.py` | `list` 接口新增查询参数：`content_keyword`、`security_levels`（多选）、`organization_keyword` |
| P2.2 | 同上 | 新增 `list_aggregated` 端点或扩展现有 `list`：返回主案时附带 `subHitCount`、`attachmentHitCount`、`titleHit`（主案本身是否命中） |
| P2.3 | `backend/dms/api/v1/documents.py` | `sub-plans/{main_id}` 与 `attachments` 接口同步扩展四条件参数 |
| P2.4 | `backend/dms/api/v1/documents.py` | 文档创建：`organization_id` 缺省取 `current_user.organization_id`；更新：管理员可改 |

### P3. 后端服务层（约 3h）

| 步骤 | 文件 | 说明 |
|------|------|------|
| P3.1 | `backend/dms/services/document_service.py` | `list_documents` 增加高级检索过滤分支（与现有 `keyword` 标题匹配并存） |
| P3.2 | 同上 | 新增 `list_main_documents_aggregated`：处理"主案或其下子案/附件命中"的并集逻辑，返回主案列表 + 命中计数 |
| P3.3 | 同上 | 命中计数来源：按主案 ID 批量查询可见子案/附件的标题命中数 |

### F1. 前端类型与 API 客户端（约 2h）

| 步骤 | 文件 | 说明 |
|------|------|------|
| F1.1 | `frontend/src/features/documents/documentTypes.ts` | `DocumentSummary` 新增 `organizationId`、`organizationName`、`subHitCount?`、`attachmentHitCount?`、`titleHit?` |
| F1.2 | `frontend/src/features/documents/documentApi.ts` | 查询参数类型扩展；新增 `searchAggregated` 方法（或扩展现有 `list`） |
| F1.3 | `frontend/src/features/attachments/attachmentApi.ts` | 同步扩展查询参数 |

### F2. 前端检索栏（约 3h）

| 步骤 | 文件 | 说明 |
|------|------|------|
| F2.1 | `frontend/src/features/documents/GlobalSearchBar.tsx`（新） | 顶部全局检索栏：含简单关键词输入 + 高级检索折叠行 |
| F2.2 | `frontend/src/app/App.tsx` | 删除 `RealMainPage` / `RealAdminPage` 中三处 `DocumentSearchToolbar` 调用 |
| F2.3 | 同 F2.1 | 高级检索折叠行：正文关键词 + 密级多选 + 所属部门；密级选项来自 `shared/api/enums.ts` 的 `SecurityLevel` |

### F3. 前端列表渲染（约 3h）

| 步骤 | 文件 | 说明 |
|------|------|------|
| F3.1 | `frontend/src/app/App.tsx` `F4DocumentTable` | 名称列高亮渲染（接收 `highlightKeyword`）；命中徽章列（`subHitCount`/`attachmentHitCount`）；新增"所属部门"列 |
| F3.2 | 同上 | 选中主案后，子案/附件 Tab 调用扩展接口传入四条件 |
| F3.3 | 同上 | 行下方延展沿用现有 `contentSnippet` 样式 |

### F4. 前端状态管理（约 2h）

| 步骤 | 文件 | 说明 |
|------|------|------|
| F4.1 | `frontend/src/features/documents/documentState.ts` | 新增全局检索状态：`simpleKeyword`、`advancedFilters`（contentKeyword、securityLevels、organizationKeyword） |
| F4.2 | `frontend/src/app/App.tsx` | 主案查询使用全局状态；选中主案后子案/附件查询复用全局状态 |
| F4.3 | 同上 | 关键词防抖沿用 300ms |

### 测试（约 4h）

| 步骤 | 文件 | 说明 |
|------|------|------|
| T1.1 | `backend/tests/dms/test_global_search.py` | 后端：覆盖 6 种命中组合（主案命中、子案命中、附件命中、混合、空、高级检索过滤） |
| T1.2 | `backend/tests/dms/test_document_organization.py` | 后端：默认值取创建者组织、可修改、不联动调岗 |
| T2.1 | `frontend/src/features/documents/__tests__/GlobalSearchBar.test.tsx` | 前端：折叠/展开、条件生效、密级多选 |
| T2.2 | `frontend/src/app/__tests__/F4DocumentTable.test.tsx` | 前端：徽章显示、高亮渲染、所属部门列 |

---

## 三、风险与缓解

| 编号 | 风险 | 缓解 |
|------|------|------|
| R1 | 聚合查询在大数据量下慢 | 在 `title`、`organization_name`、`security_level` 上加索引；必要时切全文索引 |
| R2 | 历史数据密级为空 | 迁移中给默认值（最低密级） |
| R3 | 组织改名时冗余字段不同步 | 沿用 `move organization` 级联策略：移动组织时同步刷新所有文档的 `organization_name` |
| R4 | 简单关键词匹配标题但子案不可见 | 聚合时按 ACL 校验子案/附件可见性，不可见的命中不计入计数 |
| R5 | 索引膨胀 | 仅在 `title`、`organization_name` 上加 BTREE 索引；`contentText` 不加索引（按需切全文） |

---

## 四、工作量估算

| 阶段 | 工作量 |
|------|-------|
| P1 后端模型+迁移 | ~3h |
| P2 后端接口扩展 | ~4h |
| P3 后端服务层 | ~3h |
| F1 前端类型与API | ~2h |
| F2 前端检索栏 | ~3h |
| F3 前端列表渲染 | ~3h |
| F4 前端状态管理 | ~2h |
| 测试 | ~4h |
| 联调与回归 | ~2h |
| **合计** | **~26h** |

---

## 五、推进顺序

按用户要求：**P1 → F1 → F2 → F3 → F4 → 测试**

- P1 完成后即可推进 F1（前端类型可基于后端 DTO 设计提前确定）
- P2/P3 在 F 阶段并行推进（前端先用 mock 数据，后端接口 ready 后切换）
- 测试阶段：后端测试在 P3 完成后立即写；前端测试在 F4 完成后立即写
- 联调与回归：所有阶段完成后做一次完整联调