# 指摘管理系统_概要设计说明书_V6.0（Ollama混合架构升级版） | 文档版本 | 修订日期 | 修订内容 | 修订人 | | :--- | :--- | :--- | :--- | | V4.2 | 2026-07-21 | Prompt工程专项升级：全链路Prompt模板体系化、领域知识注入、伪专项训练策略落地、新增Prompt版本管理、动态模板加载、输出结构化约束 | 系统架构师 | | V5.0 | 2026-07-23 | Ollama混合架构升级：引入本地Ollama作为首选推理与嵌入引擎，DeepSeek作为外接高性能算力备选；适配Ollama ChatML格式；新增Spring AI Ollama配置类；调整Prompt模板渲染与工具调用方式；优化知识库向量化流程；新增模型切换与容错机制 | 系统架构师 | | **V6.0** | **2026-07-23** | **技术栈版本号范围化、Ollama 70B硬件评估+降级方案、Spring AI适配层抽象、双引擎调参策略、pgvector大数据集扩展说明** | **系统架构师** | ## 1. 引言 ### 1.1 编写目的 本文档为"指摘管理系统"的概要设计说明书，定义系统的整体架构、功能模块、技术选型、数据模型、接口规范、安全策略及部署方案。系统以 **Agent（智能体）** 为核心，实现从用户意图感知到业务闭环执行的自动化与智能化。本版本（V6.0）在V4.2的Prompt工程体系基础上，**升级AI算力层为混合架构**：以本地Ollama为默认推理与嵌入引擎，确保数据隐私与低延迟，同时保留DeepSeek API作为高性能外接算力备选，实现灵活、可控、安全的AI服务。 ### 1.2 项目背景 为提升团队在项目开发、文档审查、流程管理等环节中发现和跟踪问题的效率，需构建一套集指摘创建、分配、整改、验证、智能分析于一体的全生命周期管理系统。系统引入 Agent 作为核心决策与执行单元，能够自主理解用户自然语言指令，调用业务工具完成指摘分配、催办、状态变更、知识检索等操作，并在高风险场景下请求人工审批，实现"人机协同"的闭环管理。 **AI部署策略（V6.0升级）**： - **资料库与向量库**：全部部署于本地服务器，文档原文和向量索引永不外传。 - **推理与嵌入算力**： - **默认**：使用本地Ollama服务（`llama3.1:70b` / `nomic-embed-text`），数据不出内网，延迟低。 > **硬件要求**：llama3.1:70b 需至少 48GB VRAM（4bit量化），如GPU显存不足可降级至 `qwen2.5:32b`（需24GB VRAM）或 `llama3.1:8b`（需16GB VRAM）。 - **备选**：通过配置切换至DeepSeek API（`deepseek-v4-pro` + `text-embedding-3-small`），用于高性能复杂任务或负载分担。 - **Prompt工程策略**：继续采用"伪专项训练"模式，通过系统化Prompt模板注入领域知识，并适配Ollama的ChatML消息格式，确保跨模型输出一致性与可控性。 ### 1.3 设计原则 - **Agent优先**：所有业务操作均可通过Agent自然语言指令触发，Agent具备感知、规划、行动、反思能力。 - **目标驱动**：用户表达意图，Agent自主解析并生成执行计划。 - **Human‑in‑the‑loop**：高风险操作必须经过人工审批，确保安全可控。 - **长期记忆**：Agent具备向量化记忆能力，可检索历史成功案例，持续优化决策。 - **知识本地化**：所有知识库文档及向量索引存储于本地，数据不出内网。 - **可观测性**：Agent的思考链、工具调用、执行结果全程可视可审计。 - **前后端分离**：前端React SPA，后端Spring Boot RESTful API。 - **安全优先**：全链路安全防护，最小权限原则，全量操作审计。 - **Prompt工程驱动**：通过结构化Prompt模板体系实现领域专业化，所有AI输出强制结构化，禁止自由发挥。 - **AI算力灵活化**：支持本地Ollama与云端DeepSeek无缝切换，兼顾隐私、成本与性能。 ## 2. 总体架构设计 系统采用 B/S 架构，前端为 React SPA，后端为 Spring Boot 微服务，Agent决策引擎作为核心编排层，知识库与向量库全部本地化部署。AI算力层采用 **Ollama（本地）主 + DeepSeek API（外接）备** 的混合模式。 ### 2.1 架构分层 | 层级 | 说明 | 主要技术组件 | | :--- | :--- | :--- | | **客户端层** | 用户浏览器 | Chrome / Edge / Firefox | | **接入层** | 反向代理、HTTPS终结、限流 | Nginx 1.27.x | | **前端应用层** | React SPA | React ^19.0.0, TypeScript ^5.8.0, Vite ^7.0.0, Ant Design ^6.0.0, Redux Toolkit ^2.0.0, React Router ^6.30.0 | | **Agent决策编排层** | Agent核心：规划器、执行器、观察器、记忆检索器、**Prompt模板引擎** | Spring AI (ChatModel/EmbeddingModel接口), 自定义ReAct框架, **Ollama/DeepSeek双引擎** | | **后端业务服务层** | 业务逻辑与工具实现 | Java 17/21, Spring Boot ^3.5.0, Spring Security ^6.5.0, Spring Data JPA ^3.5.0 | | **知识库处理层** | 文档解析、切片、向量化调用（通过EmbeddingModel）、本地存储、**Query改写引擎** | Apache Tika / PDFBox, HanLP 1.8.x | | **异步任务层** | 长耗时任务（Agent规划、文档向量化、导入导出、**Prompt批量渲染**） | Spring Async + ThreadPoolTaskExecutor | | **数据与向量层** | 关系数据、缓存、对象存储、**本地向量库**、**Prompt模板库** | PostgreSQL 16.14 + pgvector, Redis 7.4.9, MinIO（全部本地部署） | | **AI算力层（混合）** | **主：Ollama（本地推理+嵌入），备：DeepSeek API（外接高性能）** | Ollama（llama3.1:70b ≥48GB VRAM / qwen2.5:32b ≥24GB VRAM / llama3.1:8b ≥16GB VRAM, nomic-embed-text）, Deepseek API（deepseek-v4-pro, text-embedding-3-small） | | **运维监控层** | 监控、日志、CI/CD | Prometheus 3.1.x, Grafana 11.3.x, ELK, Jenkins 2.440.x, Docker 27.x | ### 2.2 Agent核心工作流程（ReAct循环 + Prompt工程层 + 混合AI引擎） ```mermaid graph TD User[用户/系统触发] -->|自然语言目标| PromptRouter[Prompt路由器 意图识别+模板匹配] PromptRouter -->|加载领域Prompt| DomainContext[领域上下文注入器 术语映射+规则约束] DomainContext -->|注入上下文| MemoryRetriever[长期记忆检索器 pgvector] MemoryRetriever -->|相似案例| Planner[ReAct 规划器 通过ChatModel接口调用AI引擎] Planner -->|生成步骤序列| Executor[工具执行器] Executor --> Tool1[assign_issue 带专用Prompt模板] Executor --> Tool2[send_reminder 带专用Prompt模板] Executor --> Tool3[search_knowledge Query改写+检索Prompt] Executor --> Tool4[update_status 带专用Prompt模板] Executor --> Tool5[create_comment 带专用Prompt模板] Executor --> Tool6[request_human_approval 强制触发Prompt] Tool1 & Tool2 & Tool3 & Tool4 & Tool5 -->|执行结果| OutputFormatter[输出结构化格式化器 JSON Schema约束] OutputFormatter -->|格式化结果| Observer[观察器] Observer -->|结果反馈| Planner Observer -->|成功经验| MemoryUpdater[记忆更新器 含Prompt优化反馈] Tool6 -->|挂起等待| HumanApprovalGate[人工审批闸门] HumanApprovalGate -->|批准/拒绝| Planner Planner -->|任务完成| ResultPresenter[结果展示 结构化输出渲染] subgraph AI引擎选择 A[配置决定] -->|ai.provider=ollama| Ollama[本地Ollama服务] A -->|ai.provider=deepseek| DeepSeek[外接DeepSeek API] end Planner -.->|调用ChatModel接口| AI引擎选择 Executor -.->|向量化调用EmbeddingModel接口| AI引擎选择 ``` ## 3. Prompt工程体系设计（V6.0适配） ### 3.1 设计目标 1. **领域专业化**：Agent行为表现等同于经过指摘管理领域专项训练的模型。 2. **输出可控性**：所有AI输出强制符合预定义JSON Schema，禁止自由发挥。 3. **行为一致性**：相同输入在不同时间、不同场景下输出稳定一致。 4. **可维护性**：Prompt模板独立管理、版本控制、热更新，无需重启服务。 5. **可审计性**：每次Prompt渲染全过程持久化，支持回溯与优化。 6. **跨模型兼容**：Prompt模板与渲染逻辑需同时支持Ollama和DeepSeek，保证输出一致性。 ### 3.2 Prompt模板分层架构 ``` Prompt Template Engine ├── Layer 4: 动态上下文层 (Dynamic Context Layer) │ - 当前用户角色/权限/部门 │ - 当前指摘上下文 (issue_id, status, phase等) │ - 实时数据注入 (用户列表、部门树、有效工程阶段) ├── Layer 3: 领域知识层 (Domain Knowledge Layer) │ - 指摘管理术语词典 (术语映射表) │ - 业务规则约束 (审批规则、状态流转规则) │ - 最佳实践库 (历史成功案例模式) ├── Layer 2: 任务专用层 (Task-Specific Layer) │ - 系统角色Prompt (System Role) │ - 工具专用Prompt (Tool Prompts) │ - 分析专用Prompt (Analysis Prompts) │ - 校验专用Prompt (Validation Prompts) │ - 记忆检索Prompt (Memory Retrieval Prompts) └── Layer 1: 基础约束层 (Base Constraint Layer) - 输出格式约束 (JSON Schema / Markdown模板) - 安全策略约束 (禁止内容、敏感词过滤) - 语言风格约束 (正式/简洁/结构化) ``` ### 3.3 Prompt模板类型定义 | 模板类型 | 标识前缀 | 用途 | 更新频率 | 存储位置 | | :--- | :--- | :--- | :--- | :--- | | **系统角色模板** | `SYS_ROLE_` | 定义Agent身份、知识边界、行为准则 | 低频（季度） | 数据库 + 本地文件 | | **工具调用模板** | `TOOL_` | 每个业务工具的专用Prompt，含参数生成规则 | 中频（月度） | 数据库 | | **ReAct规划模板** | `PLAN_` | 指导思考-行动-观察循环的结构化Prompt | 中频（月度） | 数据库 | | **Query改写模板** | `QUERY_` | 将用户自然语言改写为领域检索查询 | 中频（月度） | 数据库 | | **AI分析模板** | `ANALYSIS_` | 指摘深度分析的专用Prompt（根因/建议/分类） | 高频（周度） | 数据库 | | **批量校验模板** | `VALIDATE_` | Excel导入数据智能校验的专用Prompt | 中频（月度） | 数据库 | | **记忆重排序模板** | `MEMORY_` | 历史案例相关性评估与重排序Prompt | 低频（季度） | 数据库 | | **输出格式化模板** | `FORMAT_` | 各类输出的JSON Schema/Markdown模板定义 | 中频（月度） | 数据库 | | **快捷指令模板** | `QUICK_` | 工作台快捷指令的Prompt模板 | 高频（周度） | 数据库 + Redis缓存 | ### 3.4 核心Prompt模板详细定义 #### 3.4.1 系统角色Prompt模板（`SYS_ROLE_001`） ```markdown # 角色定义 你是「指摘管理专家Agent」，专精于制造业与软件工程领域的质量问题跟踪与整改管理。 你的知识边界严格限定于以下范围： - 指摘全生命周期管理（创建 → 分配 → 整改 → 验证 → 关闭） - 工程质量管理标准（ISO 9001、CMMI、企业内部QA规范） - 历史成功案例与失败教训（来自本地知识库检索） - 项目工程阶段管理（需求/设计/编码/测试/部署/运维） # 身份标识 - 系统名称：指摘管理系统（Issue Tracking System） - 你的名称：指摘助手（Issue Assistant） - 当前版本：V6.0 # 行为约束（强制遵守，违反将导致操作被拒绝） 1. 【术语强制】所有输入输出必须使用标准指摘管理术语： - 使用"对应者"而非"负责人"、"处理人" - 使用"PGM"指代项目编号，格式为 PGM-XXXX - 使用"指摘"而非"问题"、"缺陷"、"bug" - 使用"对应内容"而非"解决方案"、"修复方案" - 使用"确认者"而非"审核人"、"验收人" - 使用"对应完了日"而非"完成日期" - 使用"review工数"和"对应工数"计量工作量 - 状态术语：draft（草稿）/ open（待处理）/ in_progress（进行中）/ resolved（已解决）/ verified（已验证）/ closed（已关闭）/ rejected（已驳回） 2. 【审批强制】涉及以下高风险操作必须调用 request_human_approval 工具： - 关闭指摘（close_issue） - 删除指摘（delete_issue） - 跨部门分配指摘（assignee部门 ≠ 当前指摘部门） - 修改已验证状态的指摘 - 批量操作超过10条指摘 - 任何涉及数据删除或不可逆变更的操作 3. 【知识优先】生成整改建议时，必须遵循以下优先级： - 第一优先：引用本地知识库中的历史成功案例（需标注案例ID） - 第二优先：引用企业内部QA规范 - 第三优先：基于通用工程管理最佳实践 - 禁止：提供与指摘管理无关的建议（如财务、人事、市场等） 4. 【上下文依赖】当用户意图模糊时，必须优先询问以下信息以明确上下文： - 指摘ID（issue_id） - 工程阶段（phase） - 归属部门（department_id） - 当前状态（status） 禁止在上下文不明的情况下执行操作。 5. 【输出结构化】所有输出必须严格符合预定义JSON Schema或Markdown模板，禁止自由发挥。 - 分析类输出 → JSON格式 - 对话类输出 → Markdown格式，含结构化标题 - 工具调用 → 严格参数格式 6. 【安全边界】禁止执行以下行为： - 生成、传播或协助创建恶意代码 - 泄露其他用户的敏感信息（密码、个人联系方式等） - 执行超出指摘管理范畴的系统操作 - 伪造或篡改审计日志 # 当前环境信息 - 当前用户：{{currentUserName}}（{{currentUserRole}}） - 所属部门：{{currentUserDepartment}} - Agent自动执行权限：{{agentAutoExecuteEnabled}} - 可用工具列表（格式：工具名 - 描述）： {{#each availableTools}} - {{this.name}}：{{this.description}} {{/each}} - 当前时间：{{currentTime}} # 工具调用规则（适用于当前AI引擎：{{modelProvider}}） - 当你需要调用工具时，请在你的回复中输出一个 JSON 对象，格式为： { "tool": "工具名", "parameters": { ... } } - 不要用自然语言额外解释，直接输出该 JSON。 - 如果目标已完成，输出 { "tool": "goal_completed", "parameters": {} }。 ``` #### 3.4.2 ReAct规划Prompt模板（`PLAN_001`） ```markdown # 任务 基于用户目标和当前上下文，生成结构化的执行计划（ReAct循环）。 # 输入 用户目标：{{userGoal}} 当前指摘上下文：{{issueContext}} 历史相似案例：{{similarCases}} 可用工具列表：{{availableTools}} 已执行步骤：{{executedSteps}} 当前步数：{{currentStep}} / 最大步数：{{maxSteps}} # 思考格式（必须严格遵循） 你必须按以下结构输出思考过程，**且最终必须输出一个 JSON 对象**，其中 `action` 字段包含下一步的工具调用。 [思考] 1. 用户意图解析：将自然语言目标转化为明确的业务操作 2. 上下文评估：当前已掌握的信息是否足够执行 3. 工具选择：从可用工具中选择最合适的工具（仅限1个） 4. 参数生成：为选定工具生成所需参数 5. 风险评估：判断是否需要人工审批 6. 输出格式：确认输出符合JSON Schema [行动] ```json { "action": { "tool_name": "工具名称（必须从可用工具列表中选择）", "parameters": { "param1": "值1", "param2": "值2" }, "reasoning": "选择此工具的理由（一句话）", "requires_approval": true/false, "approval_reason": "如需要审批，写明原因" } } ``` # 约束 - 每步只能调用一个工具。 - 如需审批，必须调用 request_human_approval 工具，不得直接执行目标操作。 - 参数中的ID类字段必须为数字，禁止传递字符串ID。 - 如用户目标已完成，输出 tool_name 为 "goal_completed"。 - 如达到最大步数仍未完成，输出 tool_name 为 "max_steps_reached" 并说明原因。 ``` #### 3.4.3 工具调用Prompt模板（以 `TOOL_ASSIGN_ISSUE` 为例） ```markdown # 工具：assign_issue（将指摘分配给指定负责人） ## 适用场景 - 新建指摘后的首次分配 - 责任人变更（原负责人离职、调岗、负载过高） - Agent自动分配（基于负载均衡算法） ## 输入参数 - issue_id: 指摘ID（数字） - assignee_id: 目标对应者ID（数字） ## 执行前检查清单（必须全部确认） 1. 目标指摘是否存在且状态允许分配（status ∈ [draft, open, in_progress]） 2. 目标对应者是否存在于用户表中且状态为启用 3. 目标对应者所属部门是否与指摘归属部门一致 4. 如不一致（跨部门分配），必须调用 request_human_approval 5. 目标对应者当前进行中指摘数是否 < 5（负载检查） ## 输出格式 ```json { "tool_call": { "name": "assign_issue", "parameters": { "issue_id": {{issueId}}, "assignee_id": {{assigneeId}} } }, "pre_check": { "issue_exists": true/false, "assignee_exists": true/false, "same_department": true/false, "workload_ok": true/false, "requires_approval": true/false, "approval_reason": "如需要，说明原因" }, "execution_confidence": "high/medium/low", "reasoning": "分配决策的详细理由" } ``` ## 历史案例参考 {{similarAssignmentCases}} ``` 其他工具模板（`TOOL_SEND_REMINDER`、`TOOL_SEARCH_KNOWLEDGE`、`TOOL_REQUEST_APPROVAL`）内容与V4.2完全相同，不再重复。 #### 3.4.4 Query改写Prompt模板（`QUERY_REWRITE_001`） （与V4.2完全一致，内容不变） #### 3.4.5 AI分析Prompt模板（`ANALYSIS_ROOT_CAUSE_001`） （与V4.2完全一致，内容不变） #### 3.4.6 批量校验Prompt模板（`VALIDATE_BATCH_001`） （与V4.2完全一致，内容不变） #### 3.4.7 记忆重排序Prompt模板（`MEMORY_RERANK_001`） （与V4.2完全一致，内容不变） #### 3.4.8 输出格式化模板（`FORMAT_JSON_001`） （与V4.2完全一致，内容不变） ### 3.5 快捷指令Prompt模板（`QUICK_`系列） | 模板ID | 标签 | 描述 | 审批要求 | 目标工具 | | :--- | :--- | :--- | :--- | :--- | | `QUICK_REMINDER_OVERDUE_001` | 催办逾期指摘 | 自动查找并催办所有逾期指摘 | 否 | search_issues, send_reminder | | `QUICK_WEEKLY_REPORT_001` | 生成本周报告 | 生成本周指摘处理统计报告 | 否 | search_issues, generate_report | | `QUICK_AUTO_ASSIGN_001` | 分配待处理指摘 | 自动将草稿状态指摘分配给合适人员 | 是 | search_issues, assign_issue, request_human_approval | | `QUICK_KNOWLEDGE_SEARCH_001` | 检索知识库 | 在本地知识库中检索相关信息 | 否 | search_knowledge | ### 3.6 Prompt版本管理与热更新机制 #### 3.6.1 版本控制策略 | 版本号格式 | 示例 | 含义 | 升级策略 | | :--- | :--- | :--- | :--- | | `MAJOR`变更 | `001` → `002` | 架构级变更，不兼容旧格式 | 需回归测试，逐步灰度发布 | | `MINOR`变更 | 模板内容优化 | 功能增强，兼容旧格式 | 可直接热更新，记录A/B测试数据 | | `PATCH`变更 | 错别字修正 | 无功能影响 | 即时热更新 | #### 3.6.2 热更新流程 1. 管理员提交新模板版本到数据库 2. 数据库进行版本校验和语法检查 3. 发布到Redis缓存（带生效时间） 4. Prompt引擎每30秒轮询检查更新 5. 如版本变更，清空本地缓存并加载新模板 6. 后续请求使用最新模板 #### 3.6.3 数据库表设计 （同V4.2，含 `prompt_templates`, `prompt_template_versions`, `prompt_render_logs`） ### 3.7 跨模型输出一致性策略 **背景**：Ollama（ChatML格式）与DeepSeek（OpenAI兼容格式）的Prompt渲染结果和模型行为可能存在差异，影响Agent决策稳定性。 **应对策略**： 1. **格式适配**（由 `PromptFormatter` 实现）：统一通过格式适配器将同一套模板内容转换为各模型所需的消息格式。 2. **行为调参**：必要时对两个模型分别调整 `temperature`、`top_p` 等参数，确保输出质量接近。建议在测试环境中建立双模型评测流水线，定期对比输出一致性。 3. **A/B测试机制**：利用模板管理后台的A/B测试功能，收集两个模型在实际任务中的效果数据，指导调优。 ### 3.8 Prompt渲染格式适配器（V6.0新增） ```java @Component public class PromptFormatter { @Value("${ai.provider:ollama}") private String provider; public String format(String systemPrompt, String userPrompt) { if ("ollama".equalsIgnoreCase(provider)) { // ChatML 格式 return "<|im_start|>system\n" + systemPrompt + "\n<|im_end|>\n" + "<|im_start|>user\n" + userPrompt + "\n<|im_end|>\n" + "<|im_start|>assistant\n"; } else if ("deepseek".equalsIgnoreCase(provider)) { // DeepSeek 原始格式（系统角色+用户指令） return systemPrompt + "\n\n---\n\n" + userPrompt; } // 默认（通用） return systemPrompt + "\n\n" + userPrompt; } } ``` ### 3.8 Prompt引擎核心实现（V6.0调整） ```java @Service public class PromptTemplateEngine { @Autowired private PromptTemplateRepository templateRepo; @Autowired private StringRedisTemplate redisTemplate; @Autowired private PromptFormatter formatter; private final ConcurrentHashMap localCache = new ConcurrentHashMap<>(); @Value("${ai.provider:ollama}") private String provider; public String render(String templateId, Map variables) { // 1. 加载模板 PromptTemplate template = loadTemplate(templateId); // 2. 变量校验 validateVariables(template, variables); // 3. 自动注入modelProvider variables.putIfAbsent("modelProvider", provider); // 4. 渲染模板（使用Mustache） String rendered = Mustache.compiler().compile(template.getContent()).execute(variables); // 5. 注入系统角色Prompt（如非系统角色模板） if (!templateId.startsWith("SYS_ROLE_")) { String systemPrompt = render("SYS_ROLE_001", variables); String formatConstraint = loadTemplate("FORMAT_JSON_001").getContent(); String fullPrompt = systemPrompt + "\n\n---\n\n" + rendered + "\n\n---\n\n" + formatConstraint; // 6. 应用格式适配 return formatter.format(fullPrompt, ""); } else { return formatter.format(rendered, ""); } } @Scheduled(fixedRate = 30000) public void checkForUpdates() { List activeTemplates = templateRepo.findAllActive(); for (PromptTemplate template : activeTemplates) { String cacheKey = template.getTemplateId(); PromptTemplate cached = localCache.get(cacheKey); if (cached == null || cached.getVersion() < template.getVersion()) { localCache.put(cacheKey, template); } } } } ``` ## 4. 功能模块设计 ### 4.1 系统管理模块 #### 4.1.1 用户管理（`/system/users`） - **组织架构树**：以树形结构展示部门层级，点击节点可筛选该部门下的用户列表。 - **用户列表**：展示账号、姓名、所属部门、绑定角色、状态（启用/禁用）、**Agent自动执行权限**，支持按姓名/账号搜索。 - **新增/编辑用户**：弹窗形式，可设置账号、姓名、所属部门、绑定角色（多选）、启用状态开关，以及**Agent自动执行高风险操作**开关（仅超级管理员可见）。 - **启用/禁用用户**：在表格行内操作，切换用户状态。 - **导出用户列表**：将当前筛选结果导出为 Excel 文件。 **权限要求**： - 查看列表及搜索：所有已登录用户。 - 新增、编辑、启用/禁用、导出：仅超级管理员及部门管理员（部门管理员仅可管理本部门及其下级部门用户）。 - 部门树查看：所有已登录用户。 #### 4.1.2 角色权限管理（`/system/roles`） - **角色列表**：左侧展示所有预设角色（超级管理员、部门管理员、指摘录入员、整改担当、验证人员、只读用户），支持新建、编辑、删除角色。 - **权限配置面板**：右侧展示选中角色的权限配置，包括： - **功能权限**：菜单权限（工作台、指摘列表、批量录入、AI智能分析管理、用户管理、角色权限、系统日志、Agent管理）和按钮权限，以复选框形式呈现。 - **数据权限**：下拉选择数据范围（仅本人、本部门、全部门）。 - **Agent工具权限**：以复选框列出所有可用工具（`assign_issue`, `send_reminder`, `close_issue`, `delete_issue`, `search_knowledge`, `create_comment`, `request_human_approval`, `export_excel`等），每个工具可独立授予或收回。 - **Prompt模板权限**：可查看/可编辑的Prompt模板分类列表。 - **保存权限配置**：将当前角色的权限设置持久化。 **权限要求**：所有操作仅限超级管理员。 #### 4.1.3 预设角色权限矩阵 | 角色 | 功能权限摘要 | 数据权限范围 | Agent可用工具 | Agent自动执行 | Prompt模板权限 | | :--- | :--- | :--- | :--- | :--- | :--- | | **超级管理员** | 全部功能 | 全部数据 | 全部工具 | 是（可配置） | 全部模板可编辑 | | **部门管理员** | 除"角色权限管理"外的所有菜单 | 本部门及下级部门 | 除`delete_issue`外的全部工具 | 否（需审批） | 可查看全部，可编辑工具类模板 | | **指摘录入员** | 工作台、指摘列表、批量录入 | 自己创建的指摘 | `send_reminder`, `search_knowledge`, `create_comment` | 否 | 仅查看 | | **整改担当** | 工作台、指摘列表、被分配指摘详情 | 分配给自己或协办的指摘 | `send_reminder`, `search_knowledge`, `request_human_approval` | 否 | 仅查看 | | **验证人员** | 工作台、指摘列表、被指定为验证人的指摘详情 | 被指定为验证人的指摘 | `send_reminder`, `search_knowledge` | 否 | 仅查看 | | **只读用户** | 工作台、指摘列表（仅查看） | 本部门 | `search_knowledge`（仅检索） | 否 | 仅查看 | #### 4.1.4 系统日志（`/system/logs`） - **Tab切换**：操作日志 / 系统错误日志 / **Prompt渲染日志**。 - **操作日志**：记录所有用户及Agent的操作行为，支持按操作人、时间、操作类型（含"Agent操作"）、资源类型筛选，可导出筛选结果。 - **系统错误日志**：记录系统运行异常，支持按级别、时间、模块、关键字搜索，可标记已读/已解决。 - **Prompt渲染日志**：记录每次Prompt渲染的完整信息（模板ID、版本、变量、输入token、输出token、耗时），支持按模板、时间、操作人筛选，可导出审计报告。 **权限要求**：超级管理员、部门管理员。 ### 4.2 指摘全生命周期管理模块 #### 4.2.1 工作台（`/dashboard`） - **统计卡片**：展示待处理、进行中、本月已完成、今日新增的数量及环比变化，每张卡片底部显示Agent生成的动态建议。 - **Agent快捷指令输入框**：用户可在此输入自然语言指令（如"新建指摘 '传感器故障' 分配给张三"），Agent解析后执行相应操作；下方提供快捷指令标签（催办逾期指摘、生成本周报告、分配待处理指摘、检索知识库）。 - **快捷操作**："新建指摘"和"批量导入"按钮。 - **Agent洞察面板**：展示Agent自动生成的三类洞察——高风险警报、自动对应建议、任务提醒。 - **最新动态**：展示系统内最近的用户操作和Agent自动操作记录。 - **指摘处理趋势图**：折线图展示新增指摘与已解决指摘的日趋势。 - **指摘状态分布图**：环形图展示各状态指摘的数量占比。 - **通知铃铛**：顶部栏显示未读消息数，点击展示消息列表（含Agent发起的审批请求通知）。 **权限要求**：所有已登录用户。 #### 4.2.2 指摘列表（`/issues`） - **筛选栏**：支持下拉选择状态、工程阶段、整改负责人、归属部门，以及日期范围筛选。 - **操作按钮**：新建指摘、跳转批量录入、导出Excel、**Agent批量处理**（选中多条指摘后统一分配或催办）。 - **表格**：展示指摘 ID、标题、状态、优先级、工程阶段、子工程、对应者、截止日期、**Agent建议**，每行提供"查看详情"链接。 **权限要求**：所有已登录用户（数据权限过滤）；Agent批量处理仅部门管理员及超级管理员。 #### 4.2.3 指摘详情（`/issues/:id`）—— Agent驾驶舱集成 - **布局**：页面分为左（基础信息+附件）右（Agent驾驶舱）两栏。 - **左侧基础信息区域**：展示创建人、部门、review者、对应者、确认者、指摘日、关联PGM、影响度、影响工程、部署、区分、review工数、对应内容、NG原因等（只读）。 - **左侧附件列表**：可上传新附件，支持预览、下载、删除。 - **右侧 Agent 驾驶舱**： - **对话式交互**：用户输入自然语言指令（如"催办此指摘并询问是否需要技术支持"）。 - **思考链展示**：实时流式显示 Agent 的 `[思考]`、`[行动]`（含工具名和参数）、`[观察]`（执行结果）卡片。 - **Prompt模板展示**：可展开查看当前Agent使用的Prompt模板ID、版本、关键变量（脱敏）。 - **AI引擎信息展示**：显示当前使用的模型提供商（Ollama/DeepSeek）及模型名称。 - **审批请求面板**：当Agent调用`request_human_approval`时，自动弹出审批按钮（批准/拒绝）。 - **转人工按钮**：切换至纯人工模式。 - **时间线切换**：可展开/折叠传统状态流转时间线（仅作审计参考）。 **权限要求**：所有已登录用户（须在数据权限范围内）；上传附件需具备编辑权限。 #### 4.2.4 新建指摘（`/issues/new`） - **表单字段**：标题、工程阶段、子工程、区分、指摘内容、指摘日、关联PGM、影响度、影响工程、部署、review者、review工数、对应者、对应工数、对应内容、NG原因、对应完了日、确认者、确认日（标*为必填）。 - **右侧快速设置**：状态、优先级、归属部门、创建人（只读）、整改截止日期。 - **附件上传**：支持点击或拖拽上传，可上传多个文件。 - **操作按钮**：清空重置、保存指摘。 - **Agent辅助**：页面右侧提供"Agent辅助"按钮，可让Agent根据标题自动填充部分字段（基于`ANALYSIS_`系列Prompt模板）。 **权限要求**：指摘录入员、部门管理员、超级管理员。 #### 4.2.5 编辑指摘（`/issues/:id/edit`） - **页面复用**：与新建指摘页面（`/issues/new`）共用同一套表单组件，通过路由参数区分模式。 - 预填充现有数据，部分字段（如创建人、创建日期）只读。 - 支持附件新增、预览、下载、删除。 - 操作按钮：恢复初始、保存修改、删除指摘、查看修改历史。 - 提供"Agent建议修改"按钮（基于当前指摘上下文调用`ANALYSIS_`系列Prompt）。 **权限要求**：拥有编辑权限的用户。 #### 4.2.6 批量录入（`/batch-input`） - **上传区域**：支持点击或拖拽上传 Excel 文件（.xlsx, .xls），并提供标准导入模板下载。 - **Agent智能校验**：上传后，Agent自动扫描错误（空字段、格式错误），并给出修正建议，提供"应用Agent修正"按钮（基于`VALIDATE_BATCH_001` Prompt模板）。 - **预览与校验面板**：显示上传文件的数据预览，标出校验错误行。 - **确认导入**：将校验通过的数据批量写入数据库。 - **历史导入记录**：展示以往的导入记录（时间、操作人、总条数、成功/失败、可下载错误日志）。 **权限要求**：指摘录入员、部门管理员、超级管理员。 ### 4.3 通知与消息模块 | 触发场景 | 通知方式 | 实现策略 | | :--- | :--- | :--- | | Agent发起的审批请求 | 站内消息 + 邮件 | 创建通知记录，异步发送邮件 | | 新指摘分配 | 站内消息 + 邮件 | Spring Async异步任务发送 | | 指摘被驳回 | 站内消息 + 邮件 | Spring Async异步任务发送 | | 整改即将超时 | 站内消息 + 邮件 | Spring @Scheduled定时任务扫描 | | 指摘关闭 | 站内消息 | 写入消息记录 | | Prompt模板更新 | 站内消息（仅管理员） | 模板热更新后通知相关管理员 | | **AI引擎切换** | **站内消息（管理员）** | **配置变更后通知** | ### 4.4 AI智能分析管理（`/ai-analysis`） 此模块作为独立页面存在，用于人工触发指摘的深度AI分析，与Agent并行存在。 - **筛选栏**：按指摘ID、归属部门、日期范围、分析状态筛选。 - **操作按钮**："生成AI分析"（弹窗多选指摘）、"导出AI分析记录"。 - **列表展示**：指摘ID、提取关键词、问题分类、根因分析、AI整改建议、用户反馈、操作（查看详情/重新生成）。 - **生成AI分析弹窗**：支持多选指摘，含筛选条件（指摘状态、工程阶段、归属部门、搜索、创建时间），确认后对选中指摘批量生成AI分析（基于`ANALYSIS_ROOT_CAUSE_001` Prompt模板）。 - **Prompt模板查看**：分析结果详情页可查看生成该分析使用的Prompt模板ID、版本、关键输入变量。 - **AI引擎信息**：显示生成分析时使用的模型提供商及模型名称。 **权限要求**：查看列表所有已登录用户；生成分析及导出仅部门管理员、超级管理员。 ### 4.5 Agent管理（`/system/agent-admin`） 专门管理Agent全局配置、审批、工具、记忆和审计的后台模块。 - **运行状态统计**：总任务数、待审批数、执行成功率、记忆条目数、**Prompt模板总数/活跃数**、**当前AI引擎状态**。 - **全局配置**： - **AI模型配置（V6.0新增）**： - **AI提供商选择**：下拉选择 `ollama` 或 `deepseek`，切换后立即生效。 - **Ollama参数**：服务地址、推理模型、嵌入模型、温度、最大输出tokens。 - **DeepSeek参数**：API Key（加密存储）、推理模型、嵌入模型。 - **自动降级开关**：当主引擎不可用时，是否自动切换至备用引擎。 - **Agent行为配置**：最大推理步数（默认10，范围5-20）、是否允许自动执行高风险操作（仅超级管理员可开启）、单用户Agent调用限流（默认每分钟10次）。 - **知识库切片配置**：切片大小（Token，默认500）、重叠比例（%，默认10）、最大上传大小（MB，默认50）。 - **Prompt工程配置**：系统角色Prompt版本选择、输出格式化强制开关、Query改写引擎开关、Prompt渲染日志保留天数（默认30天）。 - **待审批队列**：Agent发起的需人工决策的操作列表，提供"批准"和"拒绝"按钮。 - **工具列表**：展示所有已注册工具及其状态（"启用"或"需审批"），支持启用/禁用。 - **执行记录**：分页展示所有Agent任务（时间、指摘、工具、状态、操作人）。 - **记忆库管理**：列表展示所有向量记忆条目（问题摘要、解决方案步骤、有效性评分），支持新增、编辑、删除、反馈有效性。 - **Prompt模板管理**： - 模板列表：按分类展示所有Prompt模板，显示模板ID、名称、版本、状态、最近更新时间。 - 模板编辑：在线编辑模板内容，支持变量自动补全、实时预览。 - 版本历史：查看模板的所有历史版本，支持回滚到任意版本。 - A/B测试：对同一模板的不同版本配置流量分配比例，收集效果数据。 - 渲染测试：输入测试变量，查看渲染后的完整Prompt。 - 批量发布：选择多个模板统一发布新版本。 **权限要求**：超级管理员、部门管理员（部门管理员仅可编辑工具类和分析类模板）。 ### 4.6 本地知识库管理（`/knowledge-base`） #### 4.6.1 知识库文档管理 - **文档上传**：支持拖拽或点击上传 PDF、Word（.docx）、TXT、Markdown 格式文件，单文件限制 50MB。 - **文档列表**：展示文件名、上传人、上传时间、处理状态（待处理/处理中/已完成/失败）、分块数量、操作按钮。 - **解析与向量化流程**： 1. 上传后，后端调用本地解析库（Apache Tika / PDFBox）提取纯文本。 2. 按 **500 Token** 大小切分（含 10% 重叠）。 3. 调用当前选中的 **EmbeddingModel**（Ollama 或 DeepSeek）将每个分块转为向量。 4. 向量及原文存入本地 PostgreSQL（pgvector），源文件存入本地 MinIO。 5. **全程无任何数据上传至云端存储（若使用Ollama则完全不外传，若使用DeepSeek仅API调用传输文本片段）。** - **重新向量化**：支持对已上传文档重新生成向量（用于嵌入模型升级时）。 - **删除文档**：同时删除 MinIO 中的源文件和 pgvector 中的向量数据。 - **批量操作**：支持多选文档进行批量删除或重新向量化。 #### 4.6.2 Agent 知识库检索工具 - Agent 内置 `search_knowledge(query: string, top_k: int)` 工具。 - 调用流程（V6.0增强）： 1. 用户原始问题通过 **Query改写引擎**（基于`QUERY_REWRITE_001` Prompt模板）转换为领域专业查询。 2. 改写后的查询通过当前EmbeddingModel向量化。 3. 在本地 pgvector 中执行余弦相似度检索。 4. 检索结果通过 **记忆重排序引擎**（基于`MEMORY_RERANK_001` Prompt模板）进行相关性重排序。 5. 返回 Top K 相关原文片段给 Agent。 - 用途：辅助 Agent 进行根因分析、整改建议生成、历史案例参考。 - **权限控制**：仅授予"超级管理员"、"部门管理员"、"指摘录入员"、"整改担当"角色的 Agent 可调用此工具。 #### 4.6.3 知识库检索审计 - **检索日志**：记录每次 Agent 或人工检索的关键词、**改写后查询**、返回片段数、耗时、关联的指摘ID。 - **统计看板**：展示"热门检索词 Top 50"、"低效文档"（从未被检索到的文档）、"文档命中率排行"、**"Query改写成功率"**。 - **日志导出**：支持按时间范围导出检索审计日志（Excel）。 **权限要求**： - 上传、删除、重新向量化文档：仅超级管理员、部门管理员。 - 查看文档列表及检索审计：超级管理员、部门管理员。 - Agent 调用检索工具：受角色工具权限控制（默认除只读用户外均可）。 ## 5. 数据库架构与设计 ### 5.1 ER图 ```mermaid erDiagram departments ||--o{ users : "包含" users ||--o{ issues : "创建/负责/验证" issues ||--o{ attachments : "拥有" issues ||--o{ issue_logs : "产生" issues ||--o{ ai_analysis : "关联" ai_analysis ||--o{ ai_feedback : "收集反馈" users ||--o{ user_roles : "拥有" roles ||--o{ user_roles : "关联" roles ||--o{ role_permissions : "分配" permissions ||--o{ role_permissions : "被包含" issues ||--o{ agent_plans : "触发" agent_plans ||--o{ tool_executions : "包含" users ||--o{ agent_plans : "创建" agent_memories ||--o{ issues : "参考" knowledge_documents ||--o{ knowledge_chunks : "包含" users ||--o{ knowledge_documents : "上传" knowledge_search_logs ||--o{ users : "关联" knowledge_search_logs ||--o{ issues : "关联" prompt_templates ||--o{ prompt_template_versions : "版本历史" prompt_templates ||--o{ prompt_render_logs : "渲染记录" agent_plans ||--o{ prompt_render_logs : "关联" ``` ### 5.2 核心表结构 #### 5.2.1 基础表 **`departments`（部门表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | ID | | name | VARCHAR(100) | NOT NULL | 部门名称 | | parent_id | BIGINT | FOREIGN KEY | 上级部门ID | | sort_order | INT | DEFAULT 0 | 排序权重 | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 | | updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 更新时间 | **`users`（用户表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | ID | | userid | VARCHAR(50) | NOT NULL, UNIQUE | 登录账号 | | username | VARCHAR(50) | NOT NULL, UNIQUE | 用户姓名 | | email | VARCHAR(100) | | 邮箱 | | password_hash | VARCHAR(255) | NOT NULL | bcrypt加密密码 | | department_id | BIGINT | FOREIGN KEY, NOT NULL | 所属部门 | | is_active | BOOLEAN | DEFAULT TRUE | 是否启用 | | agent_auto_execute | BOOLEAN | DEFAULT FALSE | 是否允许Agent自动执行高风险操作 | | last_login_at | TIMESTAMP | | 最后登录时间 | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 | | updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 更新时间 | **`roles`（角色表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | ID | | name | VARCHAR(50) | NOT NULL, UNIQUE | 角色名称 | | description | VARCHAR(255) | | 角色描述 | | agent_auto_execute | BOOLEAN | DEFAULT FALSE | 是否允许该角色Agent自动执行高风险操作 | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 | **`permissions`（权限表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | ID | | code | VARCHAR(100) | NOT NULL, UNIQUE | 权限编码 | | name | VARCHAR(100) | NOT NULL | 权限名称 | | resource | VARCHAR(50) | NOT NULL | 所属资源 | | description | VARCHAR(255) | | 权限描述 | **`user_roles`（用户-角色关联表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | user_id | BIGINT | FOREIGN KEY, PRIMARY KEY (复合) | 用户ID | | role_id | BIGINT | FOREIGN KEY, PRIMARY KEY (复合) | 角色ID | **`role_permissions`（角色-权限关联表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | role_id | BIGINT | FOREIGN KEY, PRIMARY KEY (复合) | 角色ID | | permission_id | BIGINT | FOREIGN KEY, PRIMARY KEY (复合) | 权限ID | #### 5.2.2 核心业务表 **`issues`（指摘主表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 指摘ID | | issue_no | VARCHAR(20) | NOT NULL, UNIQUE | 业务编号 | | title | VARCHAR(200) | NOT NULL | 指摘标题 | | description | TEXT | | 问题详细描述 | | status | VARCHAR(30) | NOT NULL, DEFAULT 'draft' | 状态 | | priority | VARCHAR(10) | NOT NULL, DEFAULT 'medium' | 优先级 | | deadline | TIMESTAMP | | 整改截止时间 | | phase | VARCHAR(50) | | 工程阶段 | | sub_project | VARCHAR(100) | | 子工程 | | category | VARCHAR(50) | | 区分 | | impact_level | VARCHAR(10) | | 影响度 | | impact_scope | VARCHAR(200) | | 影响工程/范围 | | deployment | VARCHAR(100) | | 部署位置 | | pgm_no | VARCHAR(50) | | 关联PGM编号 | | review_workload | DECIMAL(5,1) | | review工数 | | response_workload | DECIMAL(5,1) | | 对应工数 | | response_content | TEXT | | 对应内容 | | ng_reason | VARCHAR(200) | | NG原因 | | response_completed_at | TIMESTAMP | | 对应完了日 | | confirm_at | TIMESTAMP | | 确认日 | | creator_id | BIGINT | FOREIGN KEY, NOT NULL | 创建人ID | | assignee_id | BIGINT | FOREIGN KEY | 整改负责人ID | | department_id | BIGINT | FOREIGN KEY, NOT NULL | 归属部门ID | | reviewer_id | BIGINT | FOREIGN KEY | review者ID | | validator_id | BIGINT | FOREIGN KEY | 验证人ID | | ai_analysis_id | BIGINT | FOREIGN KEY | 最新AI分析结果ID | | agent_last_plan_id | BIGINT | FOREIGN KEY | 关联最新Agent规划ID | | agent_status | VARCHAR(20) | DEFAULT 'human_driven' | Agent驱动状态 | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 | | updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 更新时间 | | closed_at | TIMESTAMP | | 关闭时间 | | is_deleted | BOOLEAN | DEFAULT FALSE | 软删除标记 | **`issue_logs`（指摘操作日志表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 日志ID | | issue_id | BIGINT | FOREIGN KEY, NOT NULL | 指摘ID | | user_id | BIGINT | FOREIGN KEY, NOT NULL | 操作人ID | | action | VARCHAR(30) | NOT NULL | 操作类型 | | from_status | VARCHAR(30) | | 原状态 | | to_status | VARCHAR(30) | | 目标状态 | | remark | VARCHAR(500) | | 备注 | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 操作时间 | **`attachments`（附件表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 附件ID | | issue_id | BIGINT | FOREIGN KEY, NOT NULL | 关联指摘ID | | file_name | VARCHAR(200) | NOT NULL | 原始文件名 | | file_path | VARCHAR(500) | NOT NULL | 存储路径 | | file_size | BIGINT | NOT NULL | 文件大小 | | mime_type | VARCHAR(100) | | MIME类型 | | uploaded_by | BIGINT | FOREIGN KEY, NOT NULL | 上传人ID | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 上传时间 | #### 5.2.3 AI与任务表 **`ai_analysis`（AI分析结果表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 分析ID | | issue_id | BIGINT | FOREIGN KEY, NOT NULL | 关联指摘ID | | category | VARCHAR(100) | | AI分类结果 | | keywords | VARCHAR(500) | | 提取关键词 | | root_cause | VARCHAR(1000) | | 根因分析 | | suggestion | TEXT | | 整改建议 | | status | VARCHAR(20) | DEFAULT 'pending' | 状态 | | helpful_count | INT | DEFAULT 0 | 有帮助计数 | | prompt_template_id | VARCHAR(100) | | 使用的Prompt模板ID | | prompt_version | INT | | 使用的Prompt版本 | | **model_provider** | **VARCHAR(20)** | | **【V6.0新增】使用的AI提供商** | | **model_name** | **VARCHAR(50)** | | **【V6.0新增】使用的模型名称** | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 | **`ai_feedback`（AI反馈表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 反馈ID | | ai_analysis_id | BIGINT | FOREIGN KEY, NOT NULL | AI分析ID | | user_id | BIGINT | FOREIGN KEY, NOT NULL | 反馈人ID | | is_helpful | BOOLEAN | NOT NULL | 是否有帮助 | | comment | VARCHAR(500) | | 反馈备注 | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 反馈时间 | **`task_executions`（异步任务执行表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 任务ID | | task_id | VARCHAR(64) | NOT NULL, UNIQUE | 业务任务唯一标识 | | task_type | VARCHAR(30) | NOT NULL | 任务类型 | | status | VARCHAR(20) | NOT NULL, DEFAULT 'pending' | 状态 | | result_url | VARCHAR(500) | | 结果文件URL | | error_message | TEXT | | 错误信息 | | created_by | BIGINT | FOREIGN KEY, NOT NULL | 触发人ID | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 | | started_at | TIMESTAMP | | 开始执行时间 | | completed_at | TIMESTAMP | | 完成时间 | | retry_count | INT | DEFAULT 0 | 已重试次数 | #### 5.2.4 Agent相关表 **`agent_plans`（Agent规划表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 规划ID | | issue_id | BIGINT | FOREIGN KEY, NOT NULL | 关联指摘ID | | goal | TEXT | NOT NULL | 用户目标 | | plan_steps | JSONB | NOT NULL | 执行步骤数组 | | status | VARCHAR(20) | DEFAULT 'pending' | 状态 | | requires_approval | BOOLEAN | DEFAULT FALSE | 是否需人工审批 | | approval_status | VARCHAR(20) | | 审批状态 | | approval_comment | VARCHAR(500) | | 审批备注 | | created_by | BIGINT | FOREIGN KEY | 发起人ID | | **model_provider** | **VARCHAR(20)** | | **【V6.0新增】使用的AI提供商** | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 | | completed_at | TIMESTAMP | | 完成时间 | **`agent_memories`（Agent长期记忆表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 记忆ID | | issue_summary | TEXT | NOT NULL | 问题摘要 | | solution_steps | JSONB | NOT NULL | 成功解决方案步骤 | | effectiveness_score | DECIMAL(3,2) | DEFAULT 0.00 | 有效性评分 | | embedding | VECTOR(1536) | | 向量化嵌入 | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 | | updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 更新时间 | **`tool_executions`（工具执行明细表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 执行ID | | plan_id | BIGINT | FOREIGN KEY | 关联规划ID | | tool_name | VARCHAR(50) | NOT NULL | 工具名称 | | input_params | JSONB | NOT NULL | 输入参数 | | output_result | TEXT | | 执行结果 | | status | VARCHAR(20) | DEFAULT 'success' | 执行状态 | | execution_time_ms | BIGINT | | 执行耗时 | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 执行时间 | **`notifications`（通知表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 通知ID | | user_id | BIGINT | FOREIGN KEY, NOT NULL | 接收人ID | | title | VARCHAR(200) | NOT NULL | 通知标题 | | content | VARCHAR(1000) | NOT NULL | 通知内容 | | type | VARCHAR(30) | NOT NULL | 通知类型 | | link | VARCHAR(500) | | 跳转链接 | | is_read | BOOLEAN | DEFAULT FALSE | 是否已读 | | issue_id | BIGINT | FOREIGN KEY | 关联指摘ID | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 | #### 5.2.5 知识库相关表（本地部署） **`knowledge_documents`（知识库文档主表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 文档ID | | name | VARCHAR(255) | NOT NULL | 原始文件名 | | file_path | VARCHAR(500) | NOT NULL | MinIO存储路径 | | file_size | BIGINT | NOT NULL | 文件大小（字节） | | file_type | VARCHAR(20) | NOT NULL | 文件类型（pdf/docx/txt/md） | | chunk_count | INT | DEFAULT 0 | 切片总数 | | status | VARCHAR(20) | DEFAULT 'pending' | 状态（pending/processing/completed/failed） | | error_message | TEXT | | 失败原因 | | uploaded_by | BIGINT | FOREIGN KEY, NOT NULL | 上传人ID | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 上传时间 | | updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 更新时间 | **`knowledge_chunks`（知识库向量切片表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 切片ID | | doc_id | BIGINT | FOREIGN KEY, NOT NULL | 所属文档ID | | content | TEXT | NOT NULL | 切片原文 | | embedding | VECTOR(1536) | NOT NULL | 向量化嵌入（本地存储） | | metadata | JSONB | | 附加元数据 | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 | **`knowledge_search_logs`（知识库检索审计表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 日志ID | | user_id | BIGINT | FOREIGN KEY | 检索人ID | | issue_id | BIGINT | FOREIGN KEY | 关联指摘ID | | query | TEXT | NOT NULL | 检索关键词 | | rewritten_query | TEXT | | 改写后的查询 | | top_k | INT | DEFAULT 5 | 返回条数 | | total_matches | INT | | 实际命中数 | | duration_ms | INT | | 检索耗时（毫秒） | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 检索时间 | #### 5.2.6 Prompt模板相关表 **`prompt_templates`（Prompt模板主表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 模板ID | | template_id | VARCHAR(100) | NOT NULL, UNIQUE | 模板标识（如 SYS_ROLE_001） | | name | VARCHAR(200) | NOT NULL | 模板名称 | | category | VARCHAR(50) | NOT NULL | 分类（system/tool/analysis/validation/memory/format/quick） | | version | INT | NOT NULL, DEFAULT 1 | 版本号 | | content | TEXT | NOT NULL | 模板内容（支持{{变量}}占位符） | | variables | JSONB | | 模板变量定义（名称、类型、是否必填、默认值） | | output_schema | JSONB | | 输出JSON Schema定义 | | is_active | BOOLEAN | DEFAULT TRUE | 是否启用 | | is_default | BOOLEAN | DEFAULT FALSE | 是否为默认版本 | | created_by | BIGINT | FOREIGN KEY | 创建人 | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 | | updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 更新时间 | **`prompt_template_versions`（Prompt模板版本历史表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 版本记录ID | | template_id | VARCHAR(100) | NOT NULL | 关联模板标识 | | version | INT | NOT NULL | 版本号 | | content | TEXT | NOT NULL | 该版本内容 | | change_log | VARCHAR(500) | | 变更说明 | | created_by | BIGINT | FOREIGN KEY | 修改人 | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 记录时间 | **`prompt_render_logs`（Prompt渲染审计表）** | 字段名 | 类型 | 约束 | 说明 | | :--- | :--- | :--- | :--- | | id | BIGSERIAL | PRIMARY KEY | 日志ID | | request_id | VARCHAR(64) | NOT NULL | 关联请求ID | | template_id | VARCHAR(100) | NOT NULL | 使用的模板标识 | | template_version | INT | NOT NULL | 使用的模板版本 | | rendered_prompt | TEXT | NOT NULL | 渲染后的完整Prompt（用于审计） | | variables_used | JSONB | | 实际使用的变量值（脱敏后） | | tokens_input | INT | | 输入token数 | | tokens_output | INT | | 输出token数 | | execution_time_ms | INT | | 执行耗时 | | llm_model | VARCHAR(50) | | 使用的模型 | | **model_provider** | **VARCHAR(20)** | | **【V6.0新增】使用的AI提供商** | | created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 记录时间 | ### 5.3 索引策略汇总 | 表名 | 索引字段 | 类型 | 说明 | | :--- | :--- | :--- | :--- | | issues | (department_id, status, created_at DESC) | 复合索引 | 工作台/列表页过滤排序 | | issues | (assignee_id, status) | 复合索引 | 按负责人查询待办 | | issues | (deadline) | B-tree | 定时任务扫描超时 | | issues | (issue_no) | UNIQUE | 业务编号快速查询 | | issue_logs | (issue_id, created_at DESC) | 复合索引 | 详情页时间线 | | attachments | (issue_id) | B-tree | 查询附件 | | ai_analysis | (issue_id, created_at DESC) | 复合索引 | 获取最新分析 | | notifications | (user_id, is_read, created_at DESC) | 复合索引 | 通知列表 | | task_executions | (task_id) | UNIQUE | 按任务ID查询 | | agent_plans | (issue_id, created_at DESC) | 复合索引 | 按指摘获取规划 | | tool_executions | (plan_id) | B-tree | 按规划ID查询 | | agent_memories | (embedding) | ivfflat | 向量相似度检索 | | knowledge_chunks | (embedding) | ivfflat | 知识库向量检索 | | knowledge_documents | (uploaded_by, created_at DESC) | 复合索引 | 按上传人查询 | | knowledge_search_logs | (user_id, created_at DESC) | 复合索引 | 检索审计查询 | | prompt_templates | (template_id, is_active) | 复合索引 | 模板查询 | | prompt_templates | (category, is_active) | 复合索引 | 按分类查询 | | prompt_render_logs | (request_id) | B-tree | 按请求查询 | | prompt_render_logs | (template_id, created_at DESC) | 复合索引 | 模板使用统计 | ### 5.4 数据迁移与版本管理 - **工具**：Flyway - **目录结构**：`src/main/resources/db/migration` - `V1.0__init_schema.sql` —— 基础表结构 - `V1.1__agent_tables.sql` —— Agent相关表及pgvector扩展 - `V1.2__knowledge_tables.sql` —— 知识库相关表 - `V1.3__insert_default_data.sql` —— 默认角色与权限 - `V1.4__prompt_template_tables.sql` —— Prompt模板相关表 - `V1.5__insert_default_prompts.sql` —— 默认Prompt模板数据 - **`V1.6__add_model_provider_columns.sql`** —— **【V6.0新增】为ai_analysis、agent_plans、prompt_render_logs增加model_provider字段** ### 5.5 软删除与数据生命周期 - **软删除**：`issues` 表使用 `is_deleted` 字段标记。 - **归档策略**：超过3年的已关闭指摘迁移至 `issues_archive` 表。 - **清理策略**： - `issue_logs`保留2年。 - `notifications`保留1年。 - `tool_executions`保留1年。 - `knowledge_search_logs`保留6个月。 - `prompt_render_logs`保留30天（可配置）。 ## 6. 异步任务与Agent执行架构（V6.0调整） ### 6.1 线程池配置 ```java @Configuration @EnableAsync public class AsyncConfig implements AsyncConfigurer { @Override public Executor getAsyncExecutor() { ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor(); executor.setCorePoolSize(10); executor.setMaxPoolSize(50); executor.setQueueCapacity(1000); executor.setKeepAliveSeconds(60); executor.setThreadNamePrefix("async-exec-"); executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy()); executor.initialize(); return executor; } } ``` ### 6.2 Agent执行流程（V6.0：基于Spring AI ChatModel接口） ```java @Service public class AgentOrchestratorService { @Autowired private ChatModel chatModel; // 由配置注入（Ollama或DeepSeek） @Autowired private EmbeddingModel embeddingModel; // 同上 @Autowired private PromptTemplateEngine promptEngine; @Autowired private MemoryService memoryService; @Autowired private ToolRegistry toolRegistry; @Autowired private AgentPlanRepository planRepo; @Async("asyncExecutor") public CompletableFuture executeGoal(Long issueId, String goal, Long userId) { // 1. 创建规划记录 AgentPlan plan = createPlan(issueId, goal, userId); // 记录当前使用的AI提供商 plan.setModelProvider(provider); // provider从配置获取 // 2. 检索相似记忆 List similarCases = memoryService.findSimilar(goal, 3); // 3. 渲染系统角色+规划Prompt（包含格式适配） String systemPrompt = promptEngine.render("SYS_ROLE_001", buildSystemContext(userId)); String planPrompt = promptEngine.render("PLAN_001", Map.of( "userGoal", goal, "issueContext", buildIssueContext(issueId), "similarCases", formatCases(similarCases), "availableTools", listAvailableTools(userId), "executedSteps", "[]", "currentStep", 1, "maxSteps", 10 )); // promptEngine.render() 已返回经过格式适配的完整Prompt String fullPrompt = systemPrompt + "\n\n---\n\n" + planPrompt; // 4. ReAct循环 int maxSteps = 10; String context = fullPrompt; while (maxSteps-- > 0) { // 4.1 调用AI引擎（ChatModel） String response = chatModel.call(context); // 记录输入输出token（如有） // 4.2 解析工具调用（从文本JSON提取） ToolCallRequest toolCall = parseToolCall(response); // 4.3 判断是否需要审批 if ("request_human_approval".equals(toolCall.getToolName())) { plan.setStatus(PlanStatus.HUMAN_REVIEW); plan.setRequiresApproval(true); planRepo.save(plan); createApprovalTask(plan.getId(), toolCall.getArgs()); break; } // 4.4 加载工具专用Prompt并执行 String toolPromptId = "TOOL_" + toolCall.getToolName().toUpperCase(); // 渲染工具模板（预检查用） promptEngine.render(toolPromptId, Map.of( "goal", goal, "issueId", issueId, "parameters", toolCall.getArgs(), "similarCases", formatCases(similarCases) )); // 执行工具 ToolExecutionResult result = toolRegistry.execute(toolCall); saveToolExecution(plan.getId(), toolCall, result); // 4.5 格式化输出（结构化） String formattedResult = formatOutput(result, toolCall.getToolName()); // 4.6 观察结果追加到上下文（用于下一轮） context += "\n\n观察结果：" + formattedResult; // 4.7 判断是否完成 if (result.isGoalCompleted()) { plan.setStatus(PlanStatus.DONE); plan.setCompletedAt(LocalDateTime.now()); planRepo.save(plan); memoryService.saveMemory(issueId, plan); break; } } return CompletableFuture.completedFuture(plan.getId().toString()); } private ToolCallRequest parseToolCall(String response) { // 从响应中提取JSON，解析出tool和parameters // 使用Jackson或正则 // ... } } ``` ### 6.3 Spring AI Ollama配置类（V6.0新增） ```java @Configuration public class AiProviderConfig { @Value("${ai.provider:ollama}") private String provider; @Value("${ollama.base-url:http://localhost:11434}") private String ollamaBaseUrl; @Value("${ollama.chat.model:llama3.1:70b}") private String ollamaChatModel; @Value("${ollama.embedding.model:nomic-embed-text}") private String ollamaEmbeddingModel; @Value("${deepseek.api.key:}") private String deepseekApiKey; @Value("${deepseek.model:deepseek-v4-pro}") private String deepseekModel; @Value("${deepseek.embedding-model:text-embedding-3-small}") private String deepseekEmbeddingModel; @Bean @Primary @ConditionalOnProperty(name = "ai.provider", havingValue = "ollama", matchIfMissing = true) public ChatModel ollamaChatModel() { OllamaApi api = new OllamaApi(ollamaBaseUrl); return new OllamaChatModel(api, OllamaOptions.create() .withModel(ollamaChatModel) .withTemperature(0.3) .withNumPredict(4096)); } @Bean @Primary @ConditionalOnProperty(name = "ai.provider", havingValue = "ollama", matchIfMissing = true) public EmbeddingModel ollamaEmbeddingModel() { OllamaApi api = new OllamaApi(ollamaBaseUrl); return new OllamaEmbeddingModel(api, OllamaOptions.create() .withModel(ollamaEmbeddingModel) .withNumPredict(512)); } @Bean @ConditionalOnProperty(name = "ai.provider", havingValue = "deepseek") public ChatModel deepseekChatModel() { OpenAiApi api = new OpenAiApi("https://api.deepseek.com/v1", deepseekApiKey); return new OpenAiChatModel(api, OpenAiOptions.builder() .model(deepseekModel) .temperature(0.3) .build()); } @Bean @ConditionalOnProperty(name = "ai.provider", havingValue = "deepseek") public EmbeddingModel deepseekEmbeddingModel() { OpenAiApi api = new OpenAiApi("https://api.deepseek.com/v1", deepseekApiKey); return new OpenAiEmbeddingModel(api, OpenAiEmbeddingOptions.builder() .model(deepseekEmbeddingModel) .build()); } } ``` > **注意事项**： > - Spring AI 目前仍处于快速发展阶段，API 可能随版本升级发生变化。建议在实际代码中增加 `AiModelAdapter` 适配层接口，将 Spring AI 的 ChatModel/EmbeddingModel 调用封装在适配器之后，当 Spring AI 版本升级时只需修改适配器实现，不影响上层 AgentOrchestrator。 > - `AiProviderConfig` 仅为示例代码，实际项目中需根据所选 Spring AI 版本调整具体 API 调用方式。 ### 6.4 前端流式展示（V6.0增强） 前端通过 **Server-Sent Events (SSE)** 接收Agent思考链，新增AI引擎信息展示： ```typescript const eventSource = new EventSource(`/api/v1/agent/plan/${planId}/stream`); eventSource.onmessage = (event) => { const data = JSON.parse(event.data); // data.type: 'thought' | 'action' | 'observation' | 'result' | 'prompt_info' | 'model_info'【V6.0新增】 switch(data.type) { case 'thought': appendThought(data.content); break; case 'action': appendAction(data.tool, data.params); break; case 'observation': appendObservation(data.result); break; case 'result': appendResult(data.content); break; case 'prompt_info': showPromptInfo({ templateId: data.templateId, version: data.version, variables: data.variables }); break; case 'model_info': // V6.0新增 showModelInfo({ provider: data.provider, // 'ollama' 或 'deepseek' model: data.model, endpoint: data.endpoint }); break; } }; ``` ### 6.5 监控指标（V6.0新增） | 指标名称 | 类型 | 说明 | | :--- | :--- | :--- | | `async.executor.queue.size` | Gauge | 队列大小 | | `async.executor.active.count` | Gauge | 活跃线程数 | | `agent.task.duration` | Histogram | Agent任务执行耗时 | | `agent.tool.success.rate` | Gauge | 工具调用成功率 | | `knowledge.search.duration` | Histogram | 知识库检索耗时 | | `prompt.render.duration` | Histogram | Prompt模板渲染耗时 | | `prompt.render.count` | Counter | Prompt渲染次数（按模板ID分维度） | | `prompt.token.usage` | Histogram | 单次Prompt消耗的token数 | | `prompt.version.mismatch` | Counter | 缓存版本与数据库版本不一致次数 | | `llm.output.parse.error` | Counter | LLM输出JSON解析失败次数 | | **【V6.0新增】`ai.provider.current`** | **Gauge** | **当前使用的AI提供商（0=ollama, 1=deepseek）** | | **【V6.0新增】`ai.ollama.request.duration`** | **Histogram** | **Ollama请求耗时** | | **【V6.0新增】`ai.deepseek.request.duration`** | **Histogram** | **DeepSeek API请求耗时** | | **【V6.0新增】`ai.provider.switch.count`** | **Counter** | **提供商切换次数（自动降级）** | ## 7. 接口设计 ### 7.1 API 规范 - **协议与域名**：`https://api.domain.com` - **版本控制**：`/api/v1/` - **认证方式**：JWT（access_token 30min，refresh_token 7d） - **请求头**：`Authorization: Bearer ` - **统一返回结构**： ```json { "code": 200, "message": "success", "data": {}, "timestamp": "2026-07-23T10:00:00Z" } ``` ### 7.2 接口列表 | 模块 | 方法 | URL | 描述 | | :--- | :--- | :--- | :--- | | **认证** | POST | `/api/v1/auth/login` | 用户登录 | | | POST | `/api/v1/auth/refresh` | 刷新令牌 | | | GET | `/api/v1/auth/me` | 获取当前用户信息 | | **用户部门** | GET | `/api/v1/users` | 用户列表 | | | GET | `/api/v1/departments` | 部门树 | | **指摘** | POST | `/api/v1/issues` | 创建指摘 | | | GET | `/api/v1/issues` | 指摘列表 | | | GET | `/api/v1/issues/{id}` | 指摘详情 | | | PUT | `/api/v1/issues/{id}` | 更新指摘 | | | POST | `/api/v1/issues/{id}/attachments` | 上传附件 | | **AI分析** | POST | `/api/v1/ai/batch-generate` | 批量生成AI分析 | | | GET | `/api/v1/ai/records` | 分析记录列表 | | | POST | `/api/v1/ai/records/{id}/feedback` | 提交反馈 | | **知识库** | GET | `/api/v1/knowledge/documents` | 文档列表 | | | POST | `/api/v1/knowledge/documents` | 上传文档 | | | DELETE | `/api/v1/knowledge/documents/{id}` | 删除文档 | | | POST | `/api/v1/knowledge/documents/{id}/reindex` | 重新向量化 | | | GET | `/api/v1/knowledge/search` | 测试检索 | | | GET | `/api/v1/knowledge/logs` | 检索审计日志 | | **导入导出** | GET | `/api/v1/issues/export` | 导出Excel | | | POST | `/api/v1/import/excel` | 上传校验Excel | | | POST | `/api/v1/import/confirm` | 确认导入 | | **Agent执行** | POST | `/api/v1/agent/execute` | 提交Agent目标 | | | GET | `/api/v1/agent/plan/{planId}/stream` | SSE流式思考链 | | | GET | `/api/v1/agent/plan/{planId}/status` | 查询状态 | | **Agent审批** | POST | `/api/v1/agent/approval/{planId}/approve` | 审批通过 | | | POST | `/api/v1/agent/approval/{planId}/reject` | 审批拒绝 | | **Agent记忆** | GET | `/api/v1/agent/memories` | 记忆列表 | | | POST | `/api/v1/agent/memories` | 新增记忆 | | | DELETE | `/api/v1/agent/memories/{id}` | 删除记忆 | | **Agent配置** | GET | `/api/v1/agent/config` | 获取配置 | | | PUT | `/api/v1/agent/config` | 更新配置 | | **通知** | GET | `/api/v1/notifications` | 通知列表 | | | PATCH | `/api/v1/notifications/{id}/read` | 标记已读 | | **Prompt模板** | GET | `/api/v1/prompts` | 模板列表 | | | GET | `/api/v1/prompts/{templateId}` | 模板详情 | | | POST | `/api/v1/prompts` | 创建模板 | | | PUT | `/api/v1/prompts/{templateId}` | 更新模板（创建新版本） | | | POST | `/api/v1/prompts/{templateId}/rollback` | 回滚到指定版本 | | | POST | `/api/v1/prompts/{templateId}/test` | 渲染测试 | | | GET | `/api/v1/prompts/{templateId}/versions` | 版本历史 | | **Prompt渲染日志** | GET | `/api/v1/prompts/logs` | 渲染日志列表 | | | GET | `/api/v1/prompts/logs/{logId}` | 渲染日志详情（含完整Prompt） | | | GET | `/api/v1/prompts/stats` | 模板使用统计 | | **【V6.0新增】AI配置** | GET | `/api/v1/ai/config` | 获取当前AI配置 | | | PUT | `/api/v1/ai/config` | 更新AI配置（模型、参数等） | | | POST | `/api/v1/ai/test` | 测试当前AI连接 | ## 8. 安全设计 ### 8.1 传输与接入安全 - 全站强制 HTTPS。 - Nginx 限流（`limit_req_zone`），防暴力破解和 CC 攻击。 ### 8.2 认证与授权 - JWT 短令牌（30min）+ 长刷新令牌（7d）。 - Spring Security 过滤器验证 JWT，`@PreAuthorize` 进行功能权限校验。 - AOP 注入数据权限过滤条件（部门隔离）。 - Agent 工具调用权限基于角色动态过滤。 - Prompt模板编辑权限基于角色分级控制。 - **AI配置修改权限仅限超级管理员**。 ### 8.3 攻击防护 - **XSS**：React 自动转义 + OWASP Java HTML Sanitizer。 - **CSRF**：JWT 机制天然防 CSRF。 - **SQL注入**：Spring Data JPA 参数化查询。 - **Prompt注入防护**： - 用户输入变量必须经过转义和长度限制。 - 禁止用户输入中包含`{{}}`模板语法（防止模板注入）。 - 敏感变量（密码、token等）禁止注入Prompt。 - 所有用户输入变量在渲染日志中记录（脱敏后）。 - **Ollama安全**：Ollama默认无认证，需通过Nginx反向代理增加Basic Auth或API Key验证，限制内网访问。 ### 8.4 数据安全 - 密码使用 `BCryptPasswordEncoder`（强度10）加盐哈希存储。 - 知识库文档原文与向量：全部存储于本地 PostgreSQL + MinIO，永不外传。 - DeepSeek API 调用：仅传输待向量化的文本片段或推理 Prompt，云端不留存任何数据。 - **Ollama调用**：数据完全不出本地服务器，安全性最高。 - Prompt渲染日志安全： - 完整Prompt仅保留30天（可配置）。 - 日志中的敏感变量自动脱敏（正则匹配身份证号、手机号、密码等模式）。 - 仅超级管理员可查看完整渲染日志。 ### 8.5 Agent安全策略 - **工具调用白名单**：基于角色动态过滤。 - **高风险操作审批**：`close_issue`、`delete_issue`、跨部门 `assign_issue` 必须触发 `request_human_approval`。 - **执行限流**：单用户每分钟最多 10 个 Agent 目标。 - **思考链审计**：所有 Agent 推理过程持久化存储，保留 2 年。 - **环境隔离**：生产环境默认禁止高风险自动执行。 - **Prompt模板安全**： - 模板内容必须经过语法校验（防止模板语法错误导致渲染失败）。 - 模板发布前必须经过审批（测试环境验证通过）。 - 禁止模板中包含硬编码的API密钥、数据库连接串等敏感信息。 - 模板变量必须进行类型校验（防止类型错误导致LLM输出异常）。 ## 9. 非功能需求 ### 9.1 性能优化 - 前端：路由懒加载，Ant Design 按需引入。 - 后端：Redis 缓存热点数据，数据库联合索引，耗时操作异步化。 - 数据库：定期 `VACUUM` 和 `ANALYZE`，慢查询日志分析。 - 知识库检索：pgvector IVFFlat 索引，单次检索 < 200ms。 > **注意事项**：pgvector 的 IVFFlat 索引在数据量超过 100 万条时召回率可能下降。初期数据量小可正常使用；后期若数据量增长较大，建议评估升级至 pgvectorscale 或迁移至专用向量数据库（如 Milvus、Qdrant）。 - Prompt模板渲染：本地缓存 + Redis分布式缓存，渲染耗时 < 10ms。 - Query改写：异步预渲染常用查询模板，减少LLM调用延迟。 - **Ollama推理性能**： - 首次调用可能冷启动（~5-30s），建议保持模型常驻内存（`ollama serve`）。 - 后续推理延迟取决于模型大小，70B模型约1-5s/token，需结合硬件（GPU）调优。 - 可配置并发请求数，监控资源使用。 ### 9.2 可用性与容错 - Deepseek API 调用失败自动重试（最多3次，指数退避）。 - **Ollama调用失败**：自动重试2次，若仍失败，记录错误并尝试切换到DeepSeek（若启用自动降级）。 - 超过最大步数的 Agent 任务自动终止并记录错误。 - 人工审批超时（48小时无响应）自动触发通知升级。 - Prompt模板加载失败容错： - 如数据库模板加载失败，使用本地文件系统备份模板。 - 如指定版本模板不存在，自动回退到最新稳定版本。 - 如模板渲染失败，记录错误并使用通用Fallback模板。 - LLM输出解析失败容错： - JSON解析失败时，尝试使用正则提取关键字段。 - 如仍失败，标记为"low confidence"并请求人工确认。 - 记录解析失败案例，用于优化Prompt模板。 - **模型切换容错**：支持热切换，无需重启服务。 ### 9.3 可观测性 - Prometheus + Grafana：JVM、应用性能、数据库连接池、Agent 任务指标、Ollama服务状态。 - ELK：集中日志管理（含 Agent 思考链日志）。 - Sentry：异常捕获与告警。 - Prompt工程专项监控： - 各Prompt模板的使用频率、成功率、平均耗时。 - LLM输出结构化成功率（按模板分维度）。 - Query改写成功率与改写质量评分。 - A/B测试效果对比（不同模板版本的输出质量）。 - **Ollama专项监控**： - 服务可用性（通过`/api/tags`端点探活）。 - 响应时间分布。 - 并发请求数。 - 模型加载/卸载事件。 ## 10. 运维、部署与CI/CD ### 10.1 环境与部署 - **开发环境**：Docker Compose 一键启动（PostgreSQL+Redis+MinIO+Ollama+Spring Boot+React）。 - **测试/生产环境**：Docker Compose + Nginx 负载均衡，Ollama可单独部署在多台GPU服务器。 - **对象存储**：MinIO（全部本地部署）。 ### 10.2 环境变量（V6.0） ```properties # AI 提供商选择（ollama 或 deepseek） AI_PROVIDER=ollama # Ollama 配置 OLLAMA_BASE_URL=http://192.168.1.100:11434 OLLAMA_CHAT_MODEL=llama3.1:70b OLLAMA_EMBEDDING_MODEL=nomic-embed-text OLLAMA_CHAT_OPTIONS_TEMPERATURE=0.3 OLLAMA_CHAT_OPTIONS_NUM_PREDICT=4096 # DeepSeek 配置（当 AI_PROVIDER=deepseek 时生效） DEEPSEEK_API_KEY=sk-xxx DEEPSEEK_MODEL=deepseek-v4-pro DEEPSEEK_EMBEDDING_MODEL=text-embedding-3-small # 自动降级开关 AI_AUTO_FALLBACK_ENABLED=true # Agent 配置 AGENT_MAX_STEPS=10 AGENT_AUTO_EXECUTE_HIGH_RISK=false # 知识库切片参数 KNOWLEDGE_CHUNK_SIZE=500 KNOWLEDGE_CHUNK_OVERLAP=50 KNOWLEDGE_MAX_UPLOAD_SIZE=52428800 # Prompt工程配置 PROMPT_TEMPLATE_CACHE_TTL=3600 PROMPT_RENDER_LOG_RETENTION_DAYS=30 PROMPT_DEFAULT_SYSTEM_TEMPLATE=SYS_ROLE_001 PROMPT_OUTPUT_FORMAT_ENFORCED=true PROMPT_QUERY_REWRITE_ENABLED=true PROMPT_AB_TEST_ENABLED=true ``` ### 10.3 CI/CD（Jenkins） 1. 代码提交触发构建。 2. 执行 Lint、单元测试。 3. Prompt模板语法校验（自动化测试）。 4. 构建 Docker 镜像，推送至 Harbor。 5. Ansible 更新测试环境。 6. **部署前检查Ollama服务是否可达**。 7. Prompt模板自动化测试（渲染测试、变量校验）。 8. 生产环境蓝绿部署。 ### 10.4 监控告警 - Prometheus + Grafana 监控应用与Ollama服务健康状态。 - 当Ollama响应时间超过阈值或错误率 >5% 触发告警。 - Prompt模板异常告警：模板渲染失败率 > 1% 触发告警；LLM输出解析失败率 > 5% 触发告警。 - **模型切换事件告警**：当自动降级触发时，发送告警通知管理员。 ## 11. 项目计划与团队分工（V6.0调整） 项目周期：**2026年7月6日 至 2026年8月7日**（5周），团队7人。 ### 11.1 团队分组 | 组别 | 成员数 | 负责模块 | |------|--------|----------| | **第一组（核心业务组）** | 3人 | 登录、工作台（含Agent快捷指令）、指摘列表（含Agent批量处理）、指摘详情（Agent驾驶舱）、附件、状态流转 | | **第二组（业务支撑组）** | 2人 | 批量录入（含Agent智能校验）、用户管理（含Agent自动执行权限）、角色权限（含Agent工具权限）、**Prompt模板管理后台**、**AI配置管理界面（V6.0新增）** | | **第三组（知识库与后台组）** | 2人 | AI智能分析管理（分析记录）、知识库管理（文档上传/解析/向量化/检索审计）、**Prompt引擎核心实现**、**Spring AI集成与Ollama适配（V6.0新增）**、**向量化服务重构（V6.0新增）**、系统日志（含Agent操作日志分类） | ### 11.2 里程碑 | 阶段 | 时间 | 主要任务 | |------|------|----------| | **阶段1：设计** | 7/6-7/10 | 统一技术栈、接口文档、数据库设计（含pgvector）、Prompt模板体系设计、**Ollama部署方案设计、Spring AI配置设计**、项目骨架 | | **阶段2：开发** | 7/13-7/24 | 各组并行开发；第一组实现AgentOrchestrator及核心工具；第二组实现Prompt模板管理后台、**AI配置管理界面**；**第三组重点实现Ollama集成、嵌入模型切换、格式适配器** | | **阶段3：联调** | 7/27-7/31 | 前后端联调、Agent端到端测试（含Ollama和DeepSeek双模式）、Prompt模板A/B测试、知识库检索准确性测试 | | **阶段4：交付** | 8/3-8/7 | 全流程回归、性能优化、Prompt模板效果评估与调优、**Ollama性能调优**、用户手册、部署演示环境 | ## 12. 最终交付物清单（V6.0） 1. ✅ 全部源代码（前端 React + 后端 Spring Boot） 2. ✅ 数据库建表脚本（含 pgvector、Agent表、知识库表、Prompt模板表） 3. ✅ 数据库 ER 图 4. ✅ 接口文档（OpenAPI 3.0） 5. ✅ 部署说明文档（Docker Compose、环境变量配置、**Ollama部署手册**） 6. ✅ 用户操作手册（含 Agent 指令示例） 7. ✅ 测试报告（单元测试、集成测试、端到端测试） 8. ✅ Agent 工具集文档 9. ✅ Prompt模板体系文档（含所有模板定义、变量说明、使用场景） 10. ✅ Prompt工程最佳实践手册（含模板设计规范、A/B测试方法、效果评估指标） 11. ✅ Agent 人工审批操作手册 12. ✅ 知识库管理操作手册（含文档上传、向量化、检索测试说明） 13. ✅ UI交互原型文件（静态HTML演示，含10个核心页面 + Prompt模板管理后台 + **AI配置页面**） 14. ✅ **Ollama+DeepSeek混合架构配置与运维指南（新增）** 15. ✅ **模型切换与容灾演练报告（新增）** --- **文档结束**