# 指摘管理系统（IMS）

基于 AI Agent 驱动的质量问题全生命周期管理系统。

## 技术栈

| 层级 | 技术选型 |
|------|---------|
| 前端 | 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（备选） |

## 目录结构

```
├── backend/             后端（Maven 多模块）
│   ├── ims-common/      公共模块（工具类、统一返回结构）
│   ├── ims-api/         API 模块（Controller 定义、DTO）
│   ├── ims-service/     业务模块（Entity、Repository、Security）
│   └── ims-web/         Web 启动模块
├── frontend/            前端（Vite + React）
├── docs/                设计文档
└── docker-compose.yml   数据库层（PostgreSQL + Redis + MinIO）
```

## 快速启动

**说明**：数据库（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` 后重启 |

## 分支说明

- `master` — 项目骨架，各组基于此分支创建功能分支
- 各功能模块在独立分支上开发，完成后合并回 master