287 lines
9.9 KiB
Markdown
287 lines
9.9 KiB
Markdown
# 指摘管理系统 · 开发指南
|
||
|
||
## 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 问题则在群里反馈。
|