235 lines
10 KiB
Markdown
235 lines
10 KiB
Markdown
# 指摘管理系统（IMS）
|
||
|
||
**项目性质：新规**（从零开发的新作品）
|
||
|
||
基于 AI Agent 驱动的质量问题全生命周期管理系统。
|
||
|
||
## 项目概述
|
||
|
||
针对项目开发、文档审查、流程管理中质量问题跟踪效率低、知识无法沉淀复用、高风险操作缺乏管控等痛点，本系统以 **Agent（智能体）** 为核心决策与执行单元：用户通过自然语言指令即可让 Agent 自主完成指摘查询、新建、分配、状态更新、逾期催办、周报统计、根因分析、知识检索等业务操作；高风险写操作由 Agent 发起、人工审批后执行；Agent 具备长期记忆（pgvector 向量检索历史案例）；知识库文档本地化存储与向量化，数据不出内网。
|
||
|
||
## 整体功能说明
|
||
|
||
| 模块 | 功能 |
|
||
|------|------|
|
||
| 指摘管理 | 指摘全生命周期（创建/分配/整改/验证/关闭）、状态流转、优先级/阶段/影响等级管理、附件、批量登记 |
|
||
| Agent 引擎 | 自然语言指令驱动业务闭环：感知（上下文+记忆+知识检索）→ 规划（LLM 工具调用计划）→ 行动（8 个工具，写操作人工审批）→ 记忆（案例向量化入库），SSE 实时流展示思考/行动/结果 |
|
||
| AI 智能分析 | 根因分析、整改建议、未分析指摘清单 |
|
||
| 知识库 | 文档上传（Tika/POI 解析 + 切片 + 1536 维向量化）、pgvector 相似检索 |
|
||
| 工作台 | 指标看板、Agent 指令快速入口 |
|
||
| 系统管理 | 用户/角色权限、Agent 管理审批中心、Prompt 模板热更新、系统日志 |
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术选型 |
|
||
|------|---------|
|
||
| 前端 | React 19 + TypeScript + Vite + Ant Design 6 |
|
||
| 后端 | Java 17 + Spring Boot 3.5 + Spring Security |
|
||
| 数据库 | PostgreSQL 16 + pgvector |
|
||
| 缓存 | Redis 7 |
|
||
| 对象存储 | MinIO |
|
||
| AI 引擎 | Ollama（本地，默认）/ DeepSeek API（备选） |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
├── README.md 01 项目说明（本文件）
|
||
├── DESIGN.md 02 设计文档（范式图 + Agent 架构图）
|
||
├── AGENTS.md AI 协作方式与项目说明
|
||
├── backend/ 后端（Maven 多模块）
|
||
│ ├── ims-common/ 公共模块（工具类、统一返回结构）
|
||
│ ├── ims-api/ API 模块（Controller 定义、DTO）
|
||
│ ├── ims-service/ 业务模块（Entity、Repository、Security）
|
||
│ └── ims-web/ Web 启动模块
|
||
├── frontend/ 前端（Vite + React）
|
||
├── tests/ 04 实验报告（测试代码 + 覆盖率报告，进行中）
|
||
├── data/ 样本数据（进行中）
|
||
├── docs/ 设计文档、演示视频（demo.mp4 待录制）
|
||
└── docker-compose.yml 数据库层（PostgreSQL + Redis + MinIO + Ollama）
|
||
```
|
||
|
||
## 快速启动
|
||
|
||
**说明**：数据库（PostgreSQL/Redis/MinIO）运行在 Docker 中，Docker 在 WSL2 (Ubuntu) 里。后端必须在 WSL2 里运行，前端可在 Windows 运行。
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ Windows │
|
||
│ ├─ WSL2 (Ubuntu) — Docker 数据库 │
|
||
│ ├─ WSL2 (Ubuntu) — 后端 (Spring Boot 8080) │
|
||
│ └─ Windows — 前端 (Vite 5173) │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 环境要求
|
||
|
||
| 组件 | 版本要求 | 安装确认 |
|
||
|------|---------|---------|
|
||
| Java | 17+ | `java -version` |
|
||
| Maven | 3.8+ | `mvn -version` |
|
||
| Node.js | 18+ | `node -v` |
|
||
| npm | 9+ | `npm -v` |
|
||
| Docker | 24+ | `docker --version` |
|
||
| Docker Compose | V2 | `docker compose version` |
|
||
| WSL2 (Ubuntu) | 22.04+ | `wsl -l -v` |
|
||
|
||
### 准备工作（只需做一次）
|
||
|
||
#### 1. 启动基础设施（PostgreSQL + Redis + MinIO + Ollama）
|
||
|
||
Ollama 作为 Docker 容器运行，无需单独安装。首次执行以下命令时，Docker 会自动从镜像仓库拉取所有服务。
|
||
|
||
在 WSL2 (Ubuntu) 终端执行：
|
||
|
||
```bash
|
||
# 停掉 WSL2 自带的 Redis（避免端口冲突）
|
||
sudo systemctl stop redis-server 2>/dev/null
|
||
|
||
# 进入项目目录（注意：你的项目路径可能不同，按实际修改）
|
||
cd /path/to/ims-master-test
|
||
|
||
# 启动所有基础设施（含 Ollama）
|
||
docker compose up -d
|
||
|
||
# 确认所有容器正常运行
|
||
docker compose ps
|
||
```
|
||
|
||
#### 2. 初始化 MinIO Bucket（知识库上传需要）
|
||
|
||
1. 浏览器打开 [http://localhost:9001](http://localhost:9001)
|
||
2. 账号：`minioadmin` / 密码：`minioadmin`
|
||
3. 左侧 Buckets → Create Bucket → 输入 `ims-attachments` → 确认
|
||
|
||
#### 3. 拉取 AI 模型（仅第一次需要）
|
||
|
||
Ollama 容器启动时**不包含任何模型**，需要手动拉取。拉取的模型保存在 Docker 数据卷 `ollama_data` 中，后续重启容器无需重新拉取。
|
||
|
||
**第一次启动顺序：**
|
||
```bash
|
||
# 1. 启动所有服务（含 Ollama 容器）
|
||
docker compose up -d
|
||
|
||
# 2. 拉取向量化模型（知识库检索需要）
|
||
docker exec ims-ollama ollama pull nomic-embed-text
|
||
|
||
# 3. 拉取对话模型（AI Agent 分析需要）
|
||
docker exec ims-ollama ollama pull llama3.1:8b
|
||
|
||
# 4. 确认模型已拉取
|
||
docker exec ims-ollama ollama list
|
||
```
|
||
|
||
**后续启动：** 只需执行 `docker compose up -d`，之前拉取的模型自动可用，无需再执行 `docker exec ollama pull`。
|
||
|
||
> 模型文件较大（`llama3.1:8b` 约 4.9GB），拉取时间取决于网络，看到 `success` 即完成。
|
||
|
||
### 启动项目
|
||
|
||
需要同时开两个终端：
|
||
|
||
**终端 1 — WSL2 (Ubuntu)**：启动后端
|
||
|
||
```bash
|
||
# 进入后端目录（路径按实际修改）
|
||
cd /path/to/ims-master-test/backend
|
||
|
||
# 首次或改过代码后执行（编译打包）
|
||
mvn install -DskipTests -U
|
||
|
||
# 启动后端
|
||
cd ims-web && mvn spring-boot:run -Dspring-boot.run.profiles=dev
|
||
```
|
||
|
||
> 首次启动会下载大量依赖，可能需要几分钟。看到 `Started IMSApplication` 即启动成功。
|
||
|
||
**终端 2 — Windows PowerShell（或 WSL）**：启动前端
|
||
|
||
```powershell
|
||
cd /path/to/ims-master-test/frontend
|
||
|
||
# 首次或改过 package.json 后执行
|
||
npm install
|
||
|
||
# 启动前端
|
||
npm run dev
|
||
```
|
||
|
||
> 看到 `VITE v6.x.x ready in xxx ms` 即启动成功。
|
||
|
||
### 登录系统
|
||
|
||
浏览器访问 **http://localhost:5173**，使用以下账号登录：
|
||
|
||
| 账号 | 密码 | 角色 |
|
||
|------|------|------|
|
||
| admin | Admin@2026 | 超级管理员 |
|
||
|
||
### 验证启动是否正常
|
||
|
||
登录后：
|
||
1. 左侧菜单→**工作台**，页面正常显示即前后端通
|
||
2. 左侧菜单→**知识库管理**，页面能正常打开
|
||
3. 尝试上传一个 `.txt` 文件，状态变为 `completed` 即全链路正常
|
||
|
||
### 常见问题
|
||
|
||
| 问题 | 原因 | 解决 |
|
||
|------|------|------|
|
||
| 端口 6379 被占用 | WSL2 自带的 Redis 在运行 | `sudo systemctl stop redis-server` |
|
||
| 数据库连接失败 | 容器未就绪 | `docker compose ps` 检查，等几秒后再试 |
|
||
| MinIO bucket 不存在 | 未创建 | 打开 `http://localhost:9001` 创建 `ims-attachments` |
|
||
| Ollama 连不上 | Ollama 容器未运行或未就绪 | `docker compose ps` 检查 ollama 状态，`docker logs ims-ollama` 查看日志 |
|
||
| mvn: command not found | Java/Maven 未安装 | `sudo apt install openjdk-17-jdk maven -y` |
|
||
| npm: command not found | Node.js 未安装 | 从 [nodejs.org](https://nodejs.org) 下载安装 |
|
||
| Token 过期 403/跳登录 | 超过 30 分钟未操作 | 自动刷新 token，重新登录即可 |
|
||
| 上传文件报 500 | 依赖版本冲突 | 执行 `mvn install -DskipTests -U` 后重启 |
|
||
|
||
## 分支说明
|
||
|
||
- `main` — 成果物主分支（评审系统按此分支拉取），持续提交演进
|
||
|
||
## 效果总结（核心指标摘要）
|
||
|
||
| 指标 | 数值 | 状态 |
|
||
|------|------|------|
|
||
| Agent 工具 | 8 个（查询/新建/更新/分配/催办/周报/分析/知识检索） | 已完成 |
|
||
| 写操作审批保护 | 5 个写工具全部挂接人工审批流 | 已完成 |
|
||
| 后端模块 | Maven 4 模块，22 个 Flyway 迁移版本（V1.0~V2.10） | 已完成 |
|
||
| 知识库向量检索 | pgvector 1536 维 + ivfflat 索引，余弦相似度召回 | 已完成 |
|
||
| Agent 闭环成功率 | 实测数据收集中 | 进行中（最终评审前补齐） |
|
||
| 人工作业 vs Agent 作业耗时对比 | 实测数据收集中 | 进行中（最终评审前补齐） |
|
||
| 测试用例与覆盖率 | 后端单元测试 + 前端 Playwright E2E（9 个 spec） | 进行中（测试执行报告后续补充） |
|
||
|
||
## 团队分工
|
||
|
||
| 成员 | 角色 | 职责 |
|
||
|------|------|------|
|
||
| （待填写） | 产品/架构 | 需求分析、总体设计、方案评审 |
|
||
| （待填写） | 后端开发 | Spring Boot 业务实现、Agent 引擎、知识库 |
|
||
| （待填写） | 前端开发 | React 界面、SSE 交互、E2E 测试 |
|
||
| （待填写） | 测试/文档 | 测试执行、实验报告、演示视频 |
|
||
|
||
## 规模与技术难度自我评估
|
||
|
||
| 评估项 | 说明 |
|
||
|--------|------|
|
||
| 代码规模 | 后端 ~100 个 Java 类（实体/仓库/服务/控制器/Agent 工具），前端 10+ 页面组件 |
|
||
| 技术难点 | ① Agent 感知-规划-行动-记忆闭环设计；② Ollama/DeepSeek 双引擎路由与自动降级；③ pgvector 向量检索与 ivfflat 索引调优；④ Spring AI 原生 tool calling 与人工审批（Human-in-the-loop）集成；⑤ SSE 实时流式交互；⑥ Prompt 模板存库版本化热更新 |
|
||
| 集成复杂度 | PostgreSQL + pgvector、Redis、MinIO、Ollama、DeepSeek 五类外部依赖统一编排（docker-compose） |
|
||
| 团队规模 | 4 人小组，2~3 周内完成骨架到可运行闭环 |
|
||
|
||
## 中期提交状态说明
|
||
|
||
按《参赛成果物提交规范·赛道一》§1，本仓库为中期提交（2026-08-31），以下成果物状态：
|
||
|
||
| 成果物 | 状态 |
|
||
|--------|------|
|
||
| 01 README.md | 已完成 |
|
||
| 02 DESIGN.md | 已完成 |
|
||
| 03 源码（Agent + 界面 + 存储 + 工具） | 已完成，可运行 |
|
||
| 04 tests/ + coverage/ | 测试已开发，执行报告/覆盖率报告后续提交 |
|
||
| 05 _AI_USAGE_LOG.md | 持续更新 |
|
||
| 06 演示视频 demo.mp4 | 待录制（最终评审前提交） |
|
||
| 样本数据 data/ | 待补充 |
|