更新维修记录、精工车间开发流程，新增文档和物料采购进度功能

2026-06-11 15:24:22 +08:00
parent d0c6ee299c
commit d523c57057
8 changed files with 2261 additions and 3 deletions
--- a/docs/JY1.0-AI助手知识库与DeepSeek对接设计文档.md
+++ b/docs/JY1.0-AI助手知识库与DeepSeek对接设计文档.md
@@ -0,0 +1,756 @@
+# JY1.0 AI 助手、知识库与 DeepSeek 对接设计文档
+
+## 1. 文档目标
+
+本文档用于设计面向「景耀 JY1.0」MES 项目的 AI 助手。该助手应具备项目知识问答、业务功能解释、代码定位、开发辅助、排障分析、规范检查和可选业务数据查询能力，并通过 MCP 服务读取项目上下文，通过知识库检索长期知识，通过 DeepSeek 模型生成答案。
+
+## 2. AI 助手定位
+
+AI 助手面向三类用户：
+
+| 用户 | 主要诉求 |
+| --- | --- |
+| 前端开发 | 快速理解页面、定位 API、生成符合项目规范的 Vue 2 代码 |
+| 实施/运维 | 查询功能入口、解释业务流程、排查请求和权限问题 |
+| 管理/业务人员 | 了解系统模块、查询功能说明、按权限查询只读业务状态 |
+
+助手边界：
+
+- 可以解释项目、检索代码、生成建议。
+- 可以在授权后读取只读业务数据。
+- 不默认执行生产写操作。
+- 不保存用户密码、Cookie、token。
+- 不绕过现有系统权限。
+
+## 3. 总体架构
+
+推荐架构：
+
+```mermaid
+flowchart LR
+  U["用户"] --> UI["AI 助手界面"]
+  UI --> API["AI 助手服务"]
+  API --> LLM["DeepSeek API"]
+  API --> RAG["知识库检索服务"]
+  API --> MCP["JY1.0 MCP 服务"]
+  MCP --> Code["项目代码/文档"]
+  MCP --> Meta["项目索引"]
+  RAG --> VDB["向量库"]
+  RAG --> Doc["文档与代码片段"]
+  API --> Audit["审计日志"]
+  API -.可选只读.-> Biz["MES 业务只读接口"]
+```
+
+核心组件：
+
+| 组件 | 职责 |
+| --- | --- |
+| AI 助手界面 | 聊天入口、问题输入、引用展示、审批确认 |
+| AI 助手服务 | 会话管理、工具编排、RAG 编排、权限控制 |
+| DeepSeek API | 自然语言理解、推理、答案生成 |
+| MCP 服务 | 项目代码、结构、页面、API、规范工具 |
+| 知识库 | 项目文档、代码摘要、业务流程、接口说明 |
+| 向量库 | 语义检索 |
+| 审计日志 | 记录工具调用、数据访问、用户问题 |
+| 业务只读接口 | 可选，查询订单、库存、设备、任务等状态 |
+
+## 4. DeepSeek 对接方案
+
+### 4.1 模型选择
+
+建议按任务选择模型：
+
+| 任务 | 推荐模型 |
+| --- | --- |
+| 日常项目问答、代码解释 | `deepseek-chat` |
+| 复杂设计、技术路线、长链路排障 | `deepseek-reasoner` |
+| 低成本批量摘要 | `deepseek-chat` |
+
+DeepSeek API 兼容 OpenAI 风格的 Chat Completions 接口。建议在服务端使用 OpenAI SDK 兼容方式接入，避免前端暴露 API Key。
+
+### 4.2 配置方式
+
+环境变量：
+
+```bash
+DEEPSEEK_API_KEY=你的密钥
+DEEPSEEK_BASE_URL=https://api.deepseek.com
+DEEPSEEK_MODEL=deepseek-chat
+```
+
+Node.js 示例：
+
+```js
+import OpenAI from 'openai'
+
+const client = new OpenAI({
+  apiKey: process.env.DEEPSEEK_API_KEY,
+  baseURL: process.env.DEEPSEEK_BASE_URL || 'https://api.deepseek.com'
+})
+
+export function chat(messages) {
+  return client.chat.completions.create({
+    model: process.env.DEEPSEEK_MODEL || 'deepseek-chat',
+    messages: messages,
+    temperature: 0.2
+  })
+}
+```
+
+### 4.3 调用策略
+
+- 业务问答：先检索知识库，再调用 DeepSeek。
+- 代码定位：先调用 MCP 工具，再让模型汇总。
+- 复杂问题：先让模型生成检索计划，再调用 MCP/RAG，再二次回答。
+- 代码生成：必须注入 `AGENTS.md` 规范和相似页面代码片段。
+- 排障：必须附带请求链路、文件路径、后端 `name`、参数。
+
+### 4.4 Prompt 基线
+
+系统提示词建议：
+
+```text
+你是景耀 JY1.0 MES 项目的 AI 助手。项目使用 Vue 2、Element UI、Vuex、Vue Router、Axios、Webpack 4，不使用 Vue 3、TypeScript、Composition API。业务请求统一通过 MESCommonBase.ashx，使用 CreateData 和 ExecDatabase 构造请求。数据库字段和页面字段多为中文，回答和代码必须保留中文字段名。你必须优先根据知识库和 MCP 工具返回的项目事实回答；不确定时说明需要检索或确认。不得建议绕过权限、不得生成生产写库脚本、不得暴露密钥。
+```
+
+开发辅助提示词应补充：
+
+```text
+生成代码时遵循现有页面结构：div.app-container > el-card > 搜索栏 + el-table。使用 Vue 2 Options API、Element UI、.then().catch()，不新增第三方库。新增/编辑/删除优先使用全局工具方法。表格字段和请求参数使用后端中文字段名。
+```
+
+## 5. 知识库设计
+
+### 5.1 知识库目标
+
+知识库用于解决模型“不知道项目细节”的问题。它应覆盖：
+
+- 项目规则。
+- 业务模块说明。
+- 页面与 API 映射。
+- 后端过程名说明。
+- 常见问题。
+- 新增页面范式。
+- 部署和配置说明。
+- 历史变更与版本记录。
+
+### 5.2 知识来源
+
+| 来源 | 内容 | 入库方式 |
+| --- | --- | --- |
+| `AGENTS.md` | 项目 Agent 规则、代码规范 | 原文切片 |
+| `docs/` | 设计文档、实施文档 | 原文切片 |
+| `package.json` | 依赖和脚本 | 结构化摘要 |
+| `src/router` | 路由机制 | 代码摘要 |
+| `src/utils/request.js` | 请求封装 | 代码摘要 |
+| `src/utils/curd.js` | 全局 CRUD 方法 | 代码摘要 |
+| `src/views` | 页面功能、字段、后端调用 | 自动抽取摘要 |
+| `src/api` | API 函数和后端 `name` | 自动抽取摘要 |
+| `static/config.js` | 服务地址类型 | 脱敏摘要 |
+| `static/项目档案.docx` | 项目档案 | docx 转文本后入库 |
+
+### 5.3 知识分类
+
+建议知识库分为以下集合：
+
+| 集合 | 内容 |
+| --- | --- |
+| `project_rules` | AGENTS、编码规范、技术栈 |
+| `architecture` | 路由、请求、状态、构建、部署 |
+| `business_modules` | 模块和页面说明 |
+| `api_operations` | 后端 `name`、参数、调用页面 |
+| `fields` | 中文字段、表格列、表单项 |
+| `faq` | 常见问题和排障 |
+| `change_logs` | 提交记录、变更说明 |
+
+### 5.4 文档切片规则
+
+Markdown：
+
+- 按标题层级切片。
+- 每片 500 到 1200 中文字。
+- 保留标题路径。
+- 保留文件路径。
+
+Vue 文件：
+
+- template 摘要：页面结构、表格列、弹窗。
+- script 摘要：data、methods、CreateData 调用。
+- style 摘要：仅记录特殊样式。
+- 大文件不整篇入库，使用结构化抽取。
+
+API 文件：
+
+- 每个导出函数作为一个知识单元。
+- 提取函数名、type、name、param、UserID、ModularID。
+
+后端过程：
+
+- 每个 `name` 一个知识单元。
+- 汇总调用文件和参数。
+
+### 5.5 知识条目结构
+
+```json
+{
+  "id": "api:仓储管理_采购件入库_循环执行",
+  "collection": "api_operations",
+  "title": "仓储管理_采购件入库_循环执行",
+  "content": "该后端操作由采购件入库页面 submitInStorage 调用，用于批量执行采购件入库...",
+  "metadata": {
+    "source": "src/views/WarehouseManagement/PurchasePartsStorage/index.vue",
+    "module": "WarehouseManagement",
+    "type": "backend_name",
+    "operationType": "12",
+    "fields": ["物料流水号组", "实际到货数量组", "入库人员流水号"],
+    "updatedAt": "2026-06-10"
+  }
+}
+```
+
+### 5.6 向量库选型
+
+本地/内网优先：
+
+| 方案 | 适用场景 |
+| --- | --- |
+| Chroma | 快速原型、本地部署简单 |
+| Qdrant | 生产部署、性能和过滤较好 |
+| Milvus | 大规模、多项目知识库 |
+| SQLite + sqlite-vec | 单机轻量化 |
+
+推荐路线：
+
+- 原型阶段：Chroma 或 SQLite。
+- 内网生产：Qdrant。
+- 多系统统一知识库：Milvus。
+
+### 5.7 Embedding 模型
+
+DeepSeek 主要用于对话，不建议假设其提供可用的 embedding 服务。中文项目建议：
+
+| 模型 | 特点 |
+| --- | --- |
+| `BAAI/bge-m3` | 中英多语、长文本、综合能力好 |
+| `bge-large-zh-v1.5` | 中文语义检索效果好 |
+| `text2vec-large-chinese` | 中文轻量方案 |
+
+部署方式：
+
+- 内网 GPU：本地 embedding 服务。
+- 无 GPU：CPU 量化模型或商用 embedding API。
+
+## 6. RAG 检索流程
+
+标准流程：
+
+1. 用户提问。
+2. 意图识别：项目问答、代码定位、业务查询、开发生成、排障。
+3. 查询改写：补充同义词，如“入库”扩展到“采购件入库、外协入库、自制件入库”。
+4. 多路检索：
+   - 向量检索文档。
+   - BM25/关键词检索中文字段和后端 `name`。
+   - MCP 工具检索代码结构。
+5. 重排：优先同模块、同页面、同后端 `name`。
+6. 构造上下文。
+7. DeepSeek 生成答案。
+8. 输出引用来源。
+9. 记录审计。
+
+回答必须包含：
+
+- 结论。
+- 文件/模块来源。
+- 如果是代码建议，说明需修改哪些文件。
+- 如果不确定，说明缺少什么信息。
+
+## 7. AI 助手功能设计
+
+### 7.1 项目问答
+
+示例问题：
+
+- “这个项目怎么新增一个页面？”
+- “`CreateData` 参数怎么传？”
+- “仓储管理有哪些页面？”
+- “菜单权限是怎么生成路由的？”
+
+实现：
+
+- 检索 `project_rules`、`architecture`。
+- 调用 MCP `list_business_modules` 或 `analyze_vue_page`。
+
+### 7.2 业务功能解释
+
+示例问题：
+
+- “采购件入库页面做了什么？”
+- “装配执行的开始、暂停、完成分别调用哪个后端过程？”
+- “零件追溯在哪个页面？”
+
+实现：
+
+- MCP 分析页面。
+- 检索 `business_modules`、`api_operations`。
+- 输出操作流程、后端调用、关键字段。
+
+### 7.3 代码定位
+
+示例问题：
+
+- “查找所有调用 `装配执行_完成装配` 的地方。”
+- “哪个页面用了字段 `订单编号`？”
+- “库存查询页面在哪里？”
+
+实现：
+
+- MCP `trace_backend_name`。
+- MCP `find_chinese_field`。
+- MCP `find_pages_by_keyword`。
+
+### 7.4 新功能开发辅助
+
+示例问题：
+
+- “新增一个库存预警页面。”
+- “给采购订单查询增加供应商筛选。”
+- “新增一个导出按钮。”
+
+实现：
+
+- 检索相似页面。
+- 注入项目规范。
+- 生成最小改动方案。
+- 调用规范检查工具。
+
+输出：
+
+- 修改文件。
+- 代码片段。
+- 后端需要提供的 `name` 和字段。
+- 测试清单。
+
+### 7.5 排障分析
+
+示例问题：
+
+- “登录后页面空白。”
+- “接口提示账号登录失效。”
+- “新增页面菜单点不开。”
+- “入库按钮点了没反应。”
+
+实现：
+
+- 检索 FAQ。
+- MCP 分析页面请求。
+- 检查路由、Cookie、后端 `name`、参数、返回结构。
+
+### 7.6 规范检查
+
+示例问题：
+
+- “检查这个页面是否符合项目规范。”
+- “这次改动有没有用了 Vue 3 写法？”
+
+实现：
+
+- MCP `check_jy_conventions`。
+- 输出问题等级、路径、行号、修复建议。
+
+### 7.7 只读业务查询
+
+可选能力：
+
+- 查询订单状态。
+- 查询库存汇总。
+- 查询设备状态。
+- 查询装配任务。
+- 查询采购到货。
+
+要求：
+
+- 使用独立业务只读代理。
+- 不允许任意 SQL。
+- 绑定当前登录用户。
+- 记录审计日志。
+- 对敏感字段脱敏。
+
+## 8. AI 助手服务接口设计
+
+### 8.1 聊天接口
+
+`POST /api/ai/chat`
+
+请求：
+
+```json
+{
+  "sessionId": "s001",
+  "userId": "10001",
+  "message": "采购件入库页面在哪里？",
+  "context": {
+    "currentRoute": "/WarehouseManagement/PurchasePartsStorage"
+  }
+}
+```
+
+响应：
+
+```json
+{
+  "answer": "采购件入库页面位于 ...",
+  "citations": [
+    {
+      "type": "code",
+      "path": "src/views/WarehouseManagement/PurchasePartsStorage/index.vue"
+    }
+  ],
+  "toolCalls": [
+    {
+      "name": "find_pages_by_keyword",
+      "status": "success"
+    }
+  ]
+}
+```
+
+### 8.2 知识库检索接口
+
+`POST /api/knowledge/search`
+
+```json
+{
+  "query": "动态路由",
+  "collections": ["architecture", "project_rules"],
+  "topK": 5
+}
+```
+
+### 8.3 知识库重建接口
+
+`POST /api/knowledge/rebuild`
+
+```json
+{
+  "scope": "all",
+  "force": false
+}
+```
+
+### 8.4 页面分析接口
+
+`POST /api/project/analyze-page`
+
+```json
+{
+  "path": "src/views/AssemblyManagement/AssemblyExecution/index.vue"
+}
+```
+
+## 9. 数据库与存储设计
+
+### 9.1 会话表
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 会话 ID |
+| `user_id` | 用户 ID |
+| `title` | 会话标题 |
+| `created_at` | 创建时间 |
+| `updated_at` | 更新时间 |
+
+### 9.2 消息表
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 消息 ID |
+| `session_id` | 会话 ID |
+| `role` | user/assistant/tool |
+| `content` | 内容 |
+| `metadata` | 引用、工具调用、token |
+| `created_at` | 创建时间 |
+
+### 9.3 知识文档表
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 文档 ID |
+| `source_path` | 来源路径 |
+| `collection` | 集合 |
+| `title` | 标题 |
+| `content_hash` | 内容哈希 |
+| `metadata` | 元数据 |
+| `updated_at` | 更新时间 |
+
+### 9.4 工具审计表
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 审计 ID |
+| `user_id` | 用户 |
+| `tool_name` | 工具名 |
+| `input` | 输入，敏感字段脱敏 |
+| `output_summary` | 输出摘要 |
+| `status` | success/error |
+| `created_at` | 时间 |
+
+## 10. 权限与安全设计
+
+### 10.1 用户认证
+
+可选方案：
+
+- 与现有 MES 登录态集成。
+- 独立 AI 助手账号。
+- 内网单点登录。
+
+建议：
+
+- 前期使用独立账号和角色。
+- 后期接入 MES Cookie/session，并复用角色权限。
+
+### 10.2 权限矩阵
+
+| 功能 | 开发 | 实施 | 业务 |
+| --- | --- | --- | --- |
+| 项目文档问答 | 允许 | 允许 | 部分允许 |
+| 代码检索 | 允许 | 部分允许 | 禁止 |
+| 代码生成 | 允许 | 禁止 | 禁止 |
+| 业务功能解释 | 允许 | 允许 | 允许 |
+| 只读业务查询 | 部分允许 | 允许 | 按角色 |
+| 写业务数据 | 禁止 | 禁止 | 禁止 |
+| 知识库重建 | 允许 | 禁止 | 禁止 |
+
+### 10.3 防护措施
+
+- API Key 只放服务端环境变量。
+- 日志脱敏。
+- 工具调用白名单。
+- 禁止任意 SQL。
+- 禁止任意 shell。
+- 业务数据查询按角色过滤。
+- 生产写操作默认禁用。
+
+## 11. 前端集成方案
+
+### 11.1 独立 AI 助手页面
+
+在现有项目新增：
+
+```text
+src/views/AIAssistant/index.vue
+```
+
+功能：
+
+- 左侧会话列表。
+- 中间聊天窗口。
+- 右侧引用来源。
+- 支持复制答案、查看文件路径。
+- 支持按模块选择上下文。
+
+页面仍使用 Vue 2 + Element UI。
+
+### 11.2 嵌入式浮窗
+
+在 `src/views/layout/components/Navbar.vue` 增加 AI 入口，点击打开右侧抽屉。
+
+适合：
+
+- 当前页面上下文问答。
+- “解释当前页面”。
+- “检查当前页面问题”。
+
+### 11.3 权限菜单
+
+后端菜单需新增：
+
+- AI 助手。
+- AI 知识库管理。
+- AI 审计日志。
+
+对应路由仍通过动态菜单注入。
+
+## 12. 知识库更新机制
+
+### 12.1 手动更新
+
+开发者点击“重建知识库”或执行脚本：
+
+```bash
+node scripts/build-knowledge.js --root D:/景耀/JY1.0
+```
+
+### 12.2 Git Hook 更新
+
+在提交或部署后触发：
+
+- 检测变更文件。
+- 只重建变更页面/API/文档。
+- 更新向量库和索引。
+
+### 12.3 定时更新
+
+每天夜间：
+
+- 扫描 `docs`、`src/views`、`src/api`。
+- 对比 hash。
+- 增量更新。
+
+## 13. 技术路线
+
+### 阶段 1：文档与代码知识库
+
+周期：1 到 2 周。
+
+任务：
+
+- 建立知识库目录。
+- 编写项目规则、功能矩阵、API 映射文档。
+- 搭建向量库。
+- 实现 Markdown、Vue、JS 文件切片。
+- 接入 DeepSeek 基础问答。
+
+验收：
+
+- 能回答项目技术栈、目录结构、请求规范。
+- 能根据关键词找到页面。
+- 回答带来源。
+
+### 阶段 2：MCP 工具接入
+
+周期：2 到 3 周。
+
+任务：
+
+- 实现 MCP 服务。
+- 提供项目结构、页面分析、后端 `name` 反查工具。
+- AI 助手支持工具调用。
+
+验收：
+
+- 能分析指定 Vue 页面。
+- 能列出页面后端调用。
+- 能检查代码规范。
+
+### 阶段 3：开发辅助能力
+
+周期：2 周。
+
+任务：
+
+- 新增页面生成 Prompt。
+- 相似页面检索。
+- 代码规范检查。
+- 生成测试清单。
+
+验收：
+
+- 能生成符合 Vue 2 + Element UI + `CreateData` 风格的页面骨架。
+- 能解释需要后端配置的菜单和过程名。
+
+### 阶段 4：业务只读查询
+
+周期：3 到 4 周。
+
+任务：
+
+- 梳理只读业务查询白名单。
+- 建立业务查询代理。
+- 接入用户权限。
+- 增加审计。
+
+验收：
+
+- 能查询订单状态、库存概况、设备状态。
+- 无任意 SQL 能力。
+- 数据按用户权限过滤。
+
+### 阶段 5：系统化运营
+
+周期：持续。
+
+任务：
+
+- 增加问题反馈。
+- 建立 FAQ。
+- 统计高频问题。
+- 自动生成模块文档。
+- 结合提交记录生成变更说明。
+
+## 14. 推荐代码仓库结构
+
+建议在项目中新增：
+
+```text
+docs/
+  JY1.0-MCP服务设计文档.md
+  JY1.0-AI助手知识库与DeepSeek对接设计文档.md
+  功能矩阵.md
+  后端过程清单.md
+  常见问题.md
+
+mcp-server/
+  package.json
+  src/
+    server.js
+    tools/
+      project.js
+      vue.js
+      api.js
+      conventions.js
+    resources/
+      project.js
+    indexer/
+      scan.js
+      parseVue.js
+      parseApi.js
+
+ai-assistant-server/
+  package.json
+  src/
+    app.js
+    llm/deepseek.js
+    rag/search.js
+    rag/ingest.js
+    mcp/client.js
+    auth/
+    audit/
+```
+
+是否放在同一仓库取决于部署策略：
+
+- 开发阶段可放同仓库，便于读取代码。
+- 生产阶段建议 MCP/AI 服务独立仓库，JY1.0 仓库只保留文档和客户端入口。
+
+## 15. 关键风险与应对
+
+| 风险 | 影响 | 应对 |
+| --- | --- | --- |
+| 源码存在编码异常 | 解析中文字段困难 | 逐步 UTF-8 规范化，索引器容错 |
+| 后端过程无正式文档 | AI 难以准确解释参数 | 从前端调用自动抽取，后续人工补全 |
+| 页面内直接写请求较多 | API 映射分散 | MCP 扫描 `CreateData` 调用 |
+| 任意 SQL 调用历史存在 | 安全风险 | AI 工具不暴露任意 SQL |
+| DeepSeek 输出幻觉 | 错误建议 | 强制 RAG 引用和工具来源 |
+| 生产数据敏感 | 合规风险 | 只读白名单、脱敏、审计 |
+
+## 16. 验收清单
+
+AI 助手上线前应验证：
+
+- 能回答项目结构和技术栈。
+- 能解释统一请求机制。
+- 能检索所有主要业务模块。
+- 能定位指定页面路径。
+- 能反查后端 `name` 调用点。
+- 能抽取页面表格字段。
+- 能按项目规范生成 Vue 2 页面建议。
+- 能接入 DeepSeek 且 API Key 不出现在前端。
+- 知识库回答包含来源。
+- 审计日志可查看。
+- 默认不具备生产写库能力。
+
+## 17. 参考资料
+
+- Model Context Protocol 官方文档：https://modelcontextprotocol.io/
+- DeepSeek API 官方文档：https://api-docs.deepseek.com/