# 指摘管理系统（IMS）设计文档

| 文档版本 | 修订日期 | 修订内容 |
| :--- | :--- | :--- |
| V1.0 | 2026-08-31 | 中期成果物：场景与价值、开发范式流程图、Agent 架构图、架构说明、工具/API 清单 |

> 配套文档：`docs/design-spec-v6.0.md`（概要设计说明书 V6.0，含完整需求与接口细节）、`docs/ims-tech-overview.md`（技术构成简要说明）。
> 本文档中的架构描述与 `src` 源码一一对应（评审交叉验证依据）。

---

## 1. 场景与价值

### 1.1 业务场景

在项目开发、文档审查、流程管理等环节中，质量问题（指摘）的发现、分配、整改、验证长期依赖人工跟进，普遍存在以下痛点：

| 痛点 | 现状问题 |
| :--- | :--- |
| 流程割裂 | 指摘创建、指派、催办、状态变更分散在多个表单/页面，操作繁琐、易遗漏 |
| 知识复用差 | 历史问题的根因分析与整改经验散落在个人手中，无法沉淀复用 |
| 统计耗时 | 周报、逾期清单、优先级统计依赖人工汇总 |
| 责任不清 | 指摘长期待办无人跟进，逾期无人催办 |
| 决策主观 | 根因分析、整改建议依赖个人经验，缺乏历史案例支撑 |

### 1.2 解决方案

构建 **AI Agent 驱动的质量问题全生命周期管理系统（IMS）**：用户通过自然语言指令即可让 Agent 自主完成指摘查询、分配、状态更新、催办、周报统计、知识检索等业务操作；高风险写操作由 Agent 发起、人工审批后执行（Human-in-the-loop）；Agent 具备长期记忆，可检索历史相似案例辅助决策；知识库文档全流程本地化存储与向量化，数据不出内网。

### 1.3 价值与效果总结

| 维度 | 价值 | 客观指标（源码可验证） |
| :--- | :--- | :--- |
| 提效 | 自然语言直达业务闭环，替代多表单手工操作 | 8 个 Agent 工具覆盖查询/新建/更新/分配/催办/周报/分析/检索 |
| 人机协同 | 高风险操作强制人工审批，低风险操作自动执行 | 5 个写操作工具全部挂接审批流（`agent_plans.approval_status`） |
| 知识沉淀 | 成功案例向量化入库，新问题自动检索相似案例 | `agent_memories` 表 1536 维 pgvector + ivfflat 索引 |
| 可观测 | 思考链、工具调用、执行结果全程可审计 | SSE 实时推送 6 类事件；`tool_executions`、`ai_call_logs` 全量审计 |
| 成本可控 | 本地 Ollama 推理 + DeepSeek API 自动降级 | `ModelRoutingService` 双引擎路由与自动降级 |

> 说明：核心功能量化对比数据（如人工作业耗时 vs Agent 作业耗时）正在实测收集中，最终评审前补充（中期阶段进行中）。

### 1.4 项目性质

**项目性质：新规**（从零开发的新作品，非存量系统改造）。

---

## 2. 开发范式流程图

团队采用 **"需求分析 → AI生成方案 → 人工审核 → AI编码 → 测试验证 → Bug修复 → 代码清理 → 提交部署"** 的 AI 辅助开发范式。范式图各步骤名称与根目录 `_AI_USAGE_LOG.md` 的"范式步骤"列逐条对应，供评审对照验证。

```mermaid
flowchart LR
    A[需求分析] --> B[AI生成方案]
    B --> C[人工审核]
    C -->|审核通过| D[AI编码]
    C -->|审核驳回| B
    D --> E[测试验证]
    E -->|发现缺陷| F[Bug修复]
    F --> E
    E -->|通过| G[代码清理]
    G --> H[提交部署]
    H --> I[反馈迭代]
    I -.-> A
```

| 范式步骤 | 说明 | 人工角色 |
| :--- | :--- | :--- |
| 需求分析 | 梳理业务痛点，输出需求清单与验收标准 | 产品/架构师主导 |
| AI生成方案 | AI 生成技术方案、数据库设计与接口设计 | AI 辅助 |
| 人工审核 | 对 AI 方案进行评审，驳回则迭代重生成 | 人工主导 |
| AI编码 | AI 按方案编写代码，人工确认技术选型 | AI 主导 |
| 测试验证 | 编写并执行测试（后端单元测试 + 前端 E2E），验证业务闭环 | 人工主导 |
| Bug修复 | 对测试发现的缺陷由 AI 定位修复 | AI 辅助 |
| 代码清理 | 清理未使用 import/字段/方法，保持代码整洁 | AI 辅助 |
| 提交部署 | 代码评审后合入 main 分支，构建部署验证 | 人工主导 |

---

## 3. Agent 架构图（感知-规划-行动-记忆）

### 3.1 总体架构图

```mermaid
graph TB
    User[用户 / 前端界面] -->|自然语言指令 + SSE 实时流| Orbit[AgentOrchestratorService 编排器]

    subgraph Perception[感知层]
        Ctx[buildIssueContext 指摘上下文] 
        Mem[MemoryService.searchSimilar 相似历史案例检索]
        KB[SearchService.search 知识库相似案例检索]
        Ctx --> Merge[上下文合并]
        Mem --> Merge
        KB --> Merge
    end

    subgraph Planning[规划层]
        PTE[PromptTemplateEngine 模板渲染<br/>SYS_ROLE_001 / PLAN_001 存库可版本化]
        Route[ModelRoutingService 模型路由<br/>Ollama 本地 / DeepSeek 云端 / 自动降级]
        Merge --> PTE --> Route
        Route -->|ToolCallResult 工具调用计划| Plan[AgentPlan 计划落库<br/>planSteps JSONB / status pending]
    end

    subgraph Action[行动层]
        Reg[ToolRegistry 8 个工具注册表]
        Plan --> Reg
        Reg -->|只读工具| Exec[runTool 执行]
        Reg -->|写工具| Approve{人工审批<br/>AgentApprovalRequest}
        Approve -->|批准| Exec
        Approve -->|拒绝| Reject[plan 置 rejected]
        Exec -->|ToolExecution 审计<br/>running/success/failed| Audit[全链路审计<br/>ai_call_logs + SSE 事件]
    end

    subgraph Memory[记忆层]
        Exec -->|完成| Save[MemoryService.add<br/>摘要+步骤向量化 1536维]
        Save --> VDB[(agent_memories<br/>pgvector + ivfflat)]
        VDB --> Mem
    end

    Audit --> User
```

### 3.2 感知（Perception）

Agent 执行时先收集四类上下文（`AgentOrchestratorService.runPlan()`）：

1. **指摘上下文**：`buildIssueContext()` 拼接指摘编号/标题/描述/状态/优先级/阶段等字段；
2. **历史记忆检索**：`MemoryService.searchSimilar(title, 3)` 从 `agent_memories` 表按向量相似度（1536 维，余弦距离）检索历史成功案例；
3. **知识库检索**：`SearchService.search()` 对 `knowledge_chunks` 表执行 pgvector 向量检索（`1 - (embedding <=> ?) AS score`），召回相似领域案例；
4. **系统上下文**：`SystemContextBuilder.build()` 注入当前用户、部门、角色及可用工具描述。

### 3.3 规划（Planning）

- 由 `PromptTemplateEngine` 渲染存库模板（`SYS_ROLE_001` 系统角色、`PLAN_001` 规划任务），模板支持版本管理（`prompt_template_versions`）与渲染日志（`prompt_render_logs`）；
- 经 `ModelRoutingService.callWithTools()` 调用 AI 引擎：provider 为 `ollama` 时走 Spring AI 原生 tool calling（模型只声明调用、不内部执行），provider 为 `deepseek` 时退化为纯文本调用；
- 模型返回的工具调用计划（`ToolCallInfo`）落库为 `AgentPlan`（`planSteps` JSONB、`status=pending`、记录 `modelProvider`），并在线程池中异步执行；
- 每分钟每用户限流 10 次（Redis `agent:limit:{userId}:{mm}`）。

### 3.4 行动（Action）

- **工具注册表**：`ToolRegistry` 按名称注册全部 8 个工具（见 §5.1），未知工具抛业务异常；
- **写操作保护**：`ToolRegistry.isWrite()` 判定为写操作（`update_issue`、`create_issue`、`assign_pending`、`notify_overdue`）且未开启 `agent.auto-execute-high-risk` 时，plan 进入 `awaiting_approval` 状态，由人工在「Agent 管理 / 审批中心」批准（`approve`）或拒绝（`reject`）后执行；
- **执行审计**：每次工具执行写入 `tool_executions`（入参、状态、耗时 `executionTimeMs`），同时通过 SSE 向前端推送 `thought / action / observation / result / prompt_info / model_info / error` 事件，思考过程全程可见。

### 3.5 记忆（Memory）

- 计划完成后 `finishPlan()` 调用 `MemoryService.add()`，将目标摘要与解决步骤经嵌入模型向量化（1536 维）写入 `agent_memories`；
- 后续同类问题再次执行时，感知层自动检索这些历史案例，实现"经验越用越准"的长期记忆闭环。

### 3.6 异常恢复

| 异常场景 | 处理机制 |
| :--- | :--- |
| 主模型调用失败 | `ModelRoutingService` 自动降级至另一 provider（`auto-fallback-enabled=true`） |
| DeepSeek 未配置 Key | 抛出业务异常并提示配置，不阻塞本地 Ollama 链路 |
| 工具执行失败 | `ToolExecution` 记录 `failed` 状态，结果经 SSE 推送，plan 状态可追溯 |
| 工具参数非法 | `parseArguments()` 解析失败即终止该步骤，不静默跳过 |
| 超长任务 | 线程池（2 线程）异步执行，SSE 连接 10 分钟超时自动断开 |

---

## 4. 架构说明

### 4.1 技术栈

| 层级 | 技术选型 | 说明 |
| :--- | :--- | :--- |
| 前端 | React 19 + TypeScript + Vite + Ant Design 6 | SPA，Redux Toolkit 状态管理 |
| 后端 | Java 17 + Spring Boot 3.5 + Spring Security 6 | Maven 多模块（ims-common / ims-api / ims-service / ims-web） |
| AI 框架 | Spring AI（ChatModel / EmbeddingModel 接口抽象） | 原生 tool calling 接入 Ollama |
| AI 引擎 | Ollama（本地，默认）+ DeepSeek API（备选） | 双引擎自动降级，配置存 Redis 可热更新 |
| 数据库 | PostgreSQL 16 + pgvector | 向量检索 ivfflat（lists=100，1536 维） |
| 缓存 | Redis 7 | 限流、AI 配置热更新、JWT 会话 |
| 对象存储 | MinIO | 知识库文档原文（bucket `ims-attachments`） |
| 数据迁移 | Flyway | V1.0 ~ V2.10 共 22 个版本脚本 |
| 文档解析 | Apache Tika / POI | pdf / docx / xls 文本抽取，chunk 200 / overlap 40 切片 |

### 4.2 前后端交互

| 界面 | 路径 | Agent 能力 |
| :--- | :--- | :--- |
| 指摘详情页 | `/issues/:id` | Agent 指令输入 + SSE 流式执行面板、审批/拒绝、切换人工模式 |
| 工作台 | `/dashboard` | Agent 指令输入 + 执行流展示 |
| AI 智能分析 | `/ai-analysis` | AI 根因分析生成/查询、未分析指摘清单 |
| 知识库管理 | `/knowledge-base` | 文档上传（MinIO + 向量化）、检索 |
| Agent 管理/审批中心 | `/system/agent-admin` | 待审批计划列表、批准/拒绝 |
| 批量输入 | `/batch-input` | 指摘批量登记 |

### 4.3 部署架构

数据库（PostgreSQL/Redis/MinIO/Ollama）全部容器化（`docker-compose.yml`），数据与向量索引全部本地部署，AI 推理默认本地 Ollama，资料不出内网（详见 `docs/design-spec-v6.0.md` §2）。

---

## 5. 工具 / API 清单

### 5.1 Agent 工具清单（`backend/ims-service/.../agent/tool/`）

| 工具类 | 工具名 | 功能 | 写操作 | 关键参数 |
| :--- | :--- | :--- | :--- | :--- |
| IssueQueryTool | `query_issue` | 查询指摘详情 | 否 | issue_id |
| IssueUpdateTool | `update_issue` | 更新指摘字段（状态/优先级/阶段/内容等） | 是 | issue_id, field, value |
| IssueCreateTool | `create_issue` | 新建指摘 | 是 | title, description, phase, priority 等 |
| AssignPendingTool | `assign_pending` | 批量分配待处理指摘 | 是 | assignee_name |
| NotifyOverdueTool | `notify_overdue` | 催办逾期指摘 | 是 | content |
| WeeklyReportTool | `weekly_report` | 生成周报统计（新增/关闭/逾期/高优先级） | 否 | — |
| AiAnalysisTool | `ai_analysis` | AI 根因分析与整改建议 | 否 | issue_id |
| KnowledgeSearchTool | `search_knowledge` | 知识库向量检索 | 否 | query, top_k |

### 5.2 主要 REST API

| 模块 | 端点（前缀 `/api/v1`） | 说明 |
| :--- | :--- | :--- |
| 认证 | `POST /auth/login`、`/auth/refresh` | JWT 登录 / 刷新令牌 |
| 指摘 | `GET/POST /issues`、`GET/PUT /issues/{id}`、`DELETE` | 指摘 CRUD + 状态流转 |
| Agent | `POST /agent/execute`、`GET /agent/plan/{planId}/stream`（SSE）、`POST /agent/approval/{planId}/approve\|reject`、`POST /agent/suggest` | Agent 执行、实时流、审批、字段建议 |
| AI 分析 | `POST /ai-analysis/generate`、`GET /ai-analysis` | 根因分析生成与查询 |
| 知识库 | `POST /knowledge/documents/upload`、`GET /knowledge/search` | 文档上传、向量检索 |
| Prompt | `GET/PUT /prompt-templates` | 模板查看与热更新 |
| 系统 | `GET /system/users`、`/system/roles`、`/system/agent-config` | 用户、角色、Agent 配置 |

### 5.3 AI 配置项（`application.yml`）

```yaml
ai:
  provider: ollama              # 默认推理引擎（可经 Redis ai:config 热切换）
  auto-fallback-enabled: true   # 主引擎失败自动降级
ollama:
  base-url: http://localhost:11434
  chat: { model: llama3.1:8b }
  embedding: { model: nomic-embed-text }
deepseek:
  api: { key: "" }              # DeepSeek API Key（经环境变量/Redis 配置注入，不硬编码）
agent:
  max-steps: 10
  auto-execute-high-risk: false # 写操作默认需人工审批
  user-rate-limit: 10           # 每用户每分钟执行上限
```

---

## 6. 安全与合规

| 项目 | 措施 |
| :--- | :--- |
| 认证授权 | Spring Security + JWT（access + refresh 双令牌）、RBAC 角色权限、数据权限范围 |
| 敏感信息 | DeepSeek API Key 不落仓库（空值占位，经 Redis 配置热注入）；仓库无密钥/token/.env |
| 高风险操作 | Agent 写操作强制人工审批（Human-in-the-loop） |
| 审计 | `ai_call_logs`（模型调用审计）、`tool_executions`（工具调用审计）、`knowledge_search_logs`（检索审计）、`prompt_render_logs`（Prompt 渲染审计） |
| 数据安全 | 知识库原文与向量全部本地部署，数据不出内网 |