2026Technology-Competition/README.md

指摘管理系统（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) 终端执行：

# 停掉 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
2. 账号：minioadmin / 密码：minioadmin
3. 左侧 Buckets → Create Bucket → 输入 ims-attachments → 确认

3. 拉取 AI 模型（仅第一次需要）

Ollama 容器启动时不包含任何模型，需要手动拉取。拉取的模型保存在 Docker 数据卷 ollama_data 中，后续重启容器无需重新拉取。

第一次启动顺序：

# 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)：启动后端

# 进入后端目录（路径按实际修改）
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）：启动前端

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 下载安装
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/	待补充