# 指摘管理系统 · 开发指南

## 1. 当前已完成（master 骨架）

### 后端
| 组件 | 状态 | 说明 |
|------|------|------|
| Maven 多模块结构 | ✅ | ims-common / ims-api / ims-service / ims-web |
| 数据库表 & Flyway 迁移 | ✅ | 22 张表，7 个迁移脚本 |
| JPA Entity + Repository | ✅ | 22 Entity + 22 Repository |
| Spring Security + JWT | ✅ | 登录接口真实实现 |
| 所有 Controller 定义 | ✅ | 11 个 Controller，接口签名已定义 |
| 统一返回结构 | ✅ | ApiResponse / PageResult / 全局异常处理 |
| CRUD DTO 类 | ✅ | 26 个请求/响应类 |
| docker-compose | ✅ | PostgreSQL+pgvector / Redis / MinIO |
| 配置文件 | ✅ | application.yml / dev / prod |

### 前端
| 组件 | 状态 | 说明 |
|------|------|------|
| Vite + React + TypeScript | ✅ | 项目初始化 |
| Ant Design 主题 | ✅ | 品牌色、圆角已配置 |
| 路由表 | ✅ | 全部 13 个页面路由 + 懒加载 + 路由守卫 |
| 登录页 | ✅ | 表单 + API 调用 + token 存储 + 跳转 |
| 全局 Layout | ✅ | 侧边栏菜单树 + 顶栏（用户/通知） |
| axios 封装 | ✅ | 请求拦截器（自动带 token）+ 响应拦截器（401 跳登录） |
| Redux Store | ✅ | auth slice + 各模块 slice 空壳 |

---

## 2. 开发流程

### 两阶段

```
Phase 1（你 ─ 当前阶段）
  master
  └── 实现知识库模块（后端 Service + 前端页面）
      完成后合并到 master，通知其他组

Phase 2（各组 ─ 知识库完成后）
  master（含知识库模块）
  ├── feature/group1   指摘 CRUD + 工作台 + 驾驶舱
  ├── feature/group2   批量录入 + 系统管理
  └── feature/group3   AI 分析 + Prompt + Agent
      各组从 master 拉分支 → 独立开发 → PR → 合入 master
```

### 分支策略
```
master ── 骨架 + 知识库模块，各组以此为基线
  ├── feature/group1
  ├── feature/group2
  └── feature/group3
```

### 合并规则
| 阶段 | 操作 |
|------|------|
| 日常开发 | 各组在自己分支上提交，不往 master 推 |
| 功能完成 | 发起 Pull Request，指定 reviewer 审核 |
| 审核通过 | 通过 PR 合入 master，禁止直接 push |

### 不冲突保障
各组修改范围完全不重叠：

```
backend/ims-api/src/main/java/com/ims/api/controller/
  ├── IssueController.java          ← 一组
  ├── UserController.java           ← 二组
  ├── KnowledgeController.java      ← 你
  ├── AiAnalysisController.java     ← 三组
  └── ...其余 Controller 同理       ← 各组对应

frontend/src/pages/
  ├── issues/          ← 一组
  ├── dashboard/       ← 一组
  ├── batch-input/     ← 二组
  ├── ai-analysis/     ← 三组
  ├── knowledge-base/  ← 你
  └── system/          ← 二组

backend/ims-service/src/main/java/com/ims/service/
  ├── entity/          ← 仅 master 改，各组不能动
  ├── repository/      ← 仅 master 改，各组不能动
  └── security/        ← 仅 master 改，各组不能动
```

**核心原则**：Entity 和 Repository 是共享契约，任何人不得修改 master 上的 Entity 字段和 Repository 方法签名。

---

## 3. 各组分工

### 高优先级功能定义

| 优先级 | 功能 | 说明 |
|--------|------|------|
| **P0** | 批量上传 | 历史评审数据与新增数据的快速录入 |
| **P0** | AI 自动分析 | 针对上传数据实时提取风险点、改进项 |
| **P1** | 问题一览管理 | 对 AI 分析结果统一管理，支持进度追踪 |
| **P1** | 基础仪表盘 | 图表展示质量趋势与风险分布 |
| **P1** | 对策状况登记 | 针对问题登记解决方案，含负责人与期限 |

### 优先级 vs 现有模块映射

| 优先级 | 对应模块 | 归属 |
|--------|---------|------|
| P0 批量上传 | 批次录入 + 导入导出 | 二组 |
| P0 AI 自动分析 | AI 智能分析 | 三组 |
| P1 问题一览管理 | 指摘列表 + 详情 | 一组 |
| P1 基础仪表盘 | 工作台 | 一组 |
| P1 对策状况登记 | 指摘状态流转 + 编辑 | 一组 |

### 你 — 知识库模块（Phase 1 实施人）

**前置依赖**：无

| # | 任务 | 涉及文件 | 说明 |
|---|------|---------|------|
| 1 | 文档上传 API | KnowledgeController + KnowledgeService | 接收文件，存入 MinIO，记录到 knowledge_documents |
| 2 | 文档解析 + 切片 | DocumentParserService | 使用 Apache Tika 解析 PDF/Word/TXT，按 500 Token 切片 |
| 3 | 向量化 + 写入 pgvector | VectorizationService | 调用 Ollama nomic-embed-text 向量化，写入 knowledge_chunks |
| 4 | 语义检索 | SearchService | 向量化 → pgvector 余弦相似度检索 → 重排序 |
| 5 | 检索审计 | SearchLogService | 记录每次检索的 query、耗时、命中数 |
| 6 | 知识库管理页面 | frontend/pages/knowledge-base/ | 文档列表、上传、删除、重新向量化 |
| 7 | EmbeddingService 接口 | ims-service 新增 | **供三组调用** |

**EmbeddingService 接口契约（供三组调用）：**
```java
public interface EmbeddingService {
    List<Float> embed(String text);
    List<SearchResult> search(String query, int topK);
}
```

### 一组 — 指摘 CRUD + 工作台 + 驾驶舱

**前置依赖**：等 master 含知识库后拉分支

| # | 任务 | 前端页面 | 后端接口 |
|---|------|---------|---------|
| 1 | 指摘列表查询 | issues/list.tsx | GET /api/v1/issues |
| 2 | 创建指摘 | issues/new.tsx | POST /api/v1/issues |
| 3 | 指摘详情 | issues/detail.tsx | GET /api/v1/issues/{id} |
| 4 | 编辑指摘 | issues/edit.tsx | PUT /api/v1/issues/{id} |
| 5 | 状态流转 | 详情页内 | PATCH /api/v1/issues/{id}/status |
| 6 | 附件管理 | 详情页内 | POST /issues/{id}/attachments |
| 7 | 工作台仪表盘 | dashboard/index.tsx | GET /api/v1/dashboard/stats |
| 8 | 通知 | 顶栏铃铛 | GET /api/v1/notifications |
| 9 | Agent 指令 | 工作台 + 详情页 | POST /api/v1/agent/execute |
| 10 | Agent 审批 | 详情页 | POST /api/v1/agent/approval/* |

### 二组 — 批量录入 + 系统管理

**前置依赖**：等 master 含知识库后拉分支

| # | 任务 | 前端页面 | 后端接口 |
|---|------|---------|---------|
| 1 | 批量导入 Excel | batch-input/index.tsx | POST /api/v1/import/excel |
| 2 | 模板下载 | 批量录入页 | GET /api/v1/import/template |
| 3 | 用户管理 | system/users.tsx | GET/POST /api/v1/users |
| 4 | 部门树 | 用户管理页 | GET /api/v1/departments |
| 5 | 角色权限 | system/roles.tsx | GET/POST /api/v1/roles |
| 6 | 系统日志 | system/logs.tsx | GET /api/v1/logs |
| 7 | Agent 管理 | system/agent-admin.tsx | GET/PUT /api/v1/agent/config |
| 8 | Prompt 模板管理 | Agent 管理页内 | GET/POST /api/v1/prompts |
| 9 | AI 配置管理 | Agent 管理页内 | GET/PUT /api/v1/ai/config |

### 三组 — AI 分析 + Prompt 引擎 + Agent 核心

**前置依赖**：
- 等知识库模块的 EmbeddingService 接口就绪后对接
- 可以先写 Mock 实现，不阻塞开发

| # | 任务 | 前端页面 | 后端实现 |
|---|------|---------|---------|
| 1 | AI 分析列表 | ai-analysis/index.tsx | GET /api/v1/ai/records |
| 2 | 批量生成分析 | AI 分析页 | POST /api/v1/ai/batch-generate |
| 3 | 分析反馈 | 分析详情 | POST /api/v1/ai/records/{id}/feedback |
| 4 | Prompt 模板引擎 | — | PromptTemplateEngine |
| 5 | Prompt 格式适配 | — | PromptFormatter |
| 6 | Spring AI 集成 | — | AiProviderConfig |
| 7 | 模型切换 + 容错 | — | ModelRoutingService |
| 8 | Agent ReAct 循环 | — | AgentOrchestrator |
| 9 | Agent 长期记忆 | — | MemoryService |
| 10 | 工具注册中心 | — | ToolRegistry |

---

## 4. 开发约定

### 后端
- Service 类放在 `com.ims.service.{模块名}`，接口在 `ims-api`，实现在 `ims-service`
- 类名格式：`{模块名}Service`
- API 路径（已定义，不要修改）：
  ```
  /api/v1/issues       ← 一组
  /api/v1/users        ← 二组
  /api/v1/knowledge    ← 你
  /api/v1/ai           ← 三组
  /api/v1/agent        ← 一组
  /api/v1/prompts      ← 三组
  ```

### 前端
- 统一使用 `src/request.ts` 的 axios 实例
- 组件 PascalCase 命名

### 数据库
- Entity 字段任何人不得修改
- 如需新增字段，加 Flyway 迁移脚本（版本号格式 `V{版本}__{说明}.sql`），通知其他组

### 代码风格
- Java：Lombok `@Data` / `@Builder`，不写注释
- TypeScript：使用类型定义，避免 `any`

---

## 5. 启动指南

```bash
# 1. 启动数据库
docker compose up -d

# 2. 编译后端
cd backend
mvn install -DskipTests

# 3. 启动后端（端口 8080）
mvn spring-boot:run -pl ims-web -am

# 4. 启动前端（新开终端）
cd frontend
npm install && npm run dev

# 5. 浏览器打开 http://localhost:5173，用 admin / Admin@2026 登录
```

---

## 6. 知识库模块详细设计

### 6.1 数据流
```
用户上传文档 (PDF/Word/TXT/MD)
    ↓
KnowledgeController.upload()
    ↓
MinIO 存储源文件 → knowledge_documents 记录
    ↓
DocumentParserService 解析文本 (Tika)
    ↓
TextSplitter 切片 (500 Token, 10% 重叠)
    ↓
VectorizationService
    ├── Ollama nomic-embed-text 向量化
    └→ 每个切片写入 knowledge_chunks (content + embedding)
    ↓
knowledge_documents.status = 'completed'
```

### 6.2 检索流程
```
用户输入 query
    ↓
SearchService.search(query, topK)
    ├── EmbeddingModel.embed() 将 query 转为向量
    ├── pgvector 余弦相似度检索 (IVFFlat)
    └→ 返回 Top K 结果
    ↓
SearchLogService 记录审计日志
```

---

## 7. 常见问题

**Q: 我改了 Entity 字段，别人不知道怎么办？**
A: 不要改。如需加字段，在群里通知所有人后各自 rebase。

**Q: 前端页面路由冲突怎么办？**
A: 路由表已按路径隔离，各组只关心自己的页面路径。

**Q: 后端编译报错怎么办？**
A: 先 `mvn clean compile` 检查。确认是 master 问题则在群里反馈。