# zj-plugin-intelligent

> 智能客服 / 智能体客户端 Vue 2 插件库。
> 通过 npm 包（`zj-plugin-intelligent`）方式发布，宿主项目引入后挂载全局组件 `ZjkjIntelligent`，提供 AI 会话、TokUI 动态表单、文件上传、语音交互等能力。

---

## 技术栈

| 类别 | 技术 |
|---|---|
| 框架 | Vue 2.6 + Vuex 3 |
| 构建 | Vue CLI 4（`vue-cli-service`），`--target lib` 打 UMD 库 |
| UI | Element UI 2.15（部分），大量自研组件 |
| 表单 DSL | `@jboltai/tokui`（第三方 TokUI 引擎） |
| 富文本 | `markdown-it` |
| 网络 | `axios`（两套封装，见架构文档）+ 原生 `EventSource`（SSE） |
| 通信 | `reconnecting-websocket`（旧 IM，当前未启用）+ `pako`（压缩） |
| 加密 | `crypto-js`（HmacSHA256 签名）、`spiderHack`（响应解密） |
| 上传 | `obs-upload`（华为 OBS） |
| 截图 | `html2canvas` |
| 样式 | Sass（`sass` + `sass-loader`） |

---

## 目录结构

```
zjkj-npm-intelligent/
├── src/
│   ├── lib/                        # ★ 插件库源码（npm 包主体）
│   │   ├── index.js                # 插件入口，导出 install
│   │   ├── layout/                 # 根组件 ZjkjIntelligent
│   │   ├── components/
│   │   │   └── chatMain/           # 聊天主界面（ChatMain/ChatDetail/...）
│   │   ├── tokui-validator/        # TokUI 表单校验 + 事件桥接（核心）
│   │   ├── api/                    # 接口定义（apichat/apiObs/apiintelligent）
│   │   ├── http/                   # 旧 axios 封装（供 apiObs 等使用）
│   │   ├── utils/                  # 工具（request/cookie/message/...）
│   │   ├── socket/                 # 旧 WebSocket IM 通信层（保留未启用）
│   │   ├── store/                  # 插件内部 Vuex 模块（ZJAIModule）
│   │   ├── env/                    # 多环境配置（dev/pre/prod）
│   │   ├── config/setting.js       # 插件常量配置
│   │   ├── constant/index.js       # 命令/消息类型常量
│   │   └── style/                  # Sass 样式
│   ├── store/                      # demo 宿主自己的 Vuex（与 lib/store 独立）
│   ├── App.vue                     # demo 宿主根组件
│   └── main.js                     # demo 宿主入口
├── public/                         # demo 宿主静态资源
├── docs/                           # 项目文档
├── lib/                            # ★ 打包产物（npm run lib 生成）
├── package.json
└── vue.config.js
```

> 关键区分：`src/lib/**` 是发布到 npm 的插件库代码；`src/main.js`、`src/App.vue`、`src/store/**`、`public/**` 只是本地调试用的 demo 宿主。改功能时主要在 `src/lib/**` 内改。

---

## 快速开始

```bash
# 安装依赖
npm install

# 本地开发（启动 demo 宿主）
npm run serve

# 打包插件库（输出到 lib/，入口 src/lib/index.js）
npm run lib

# 打包插件库（test 环境）
npm run lib:test
```

> 注意：项目使用 `NODE_OPTIONS=--openssl-legacy-provider` 兼容旧版 Node / webpack。

### 作为插件集成到宿主

```js
import Intelligent from 'zj-plugin-intelligent'

Vue.use(Intelligent)
```

插件内部会注册全局组件 `<ZjkjIntelligent>`，宿主通过 props 传入账号、公司、token 等信息（见 `src/lib/layout/main.vue` 的 props 定义）。

---

## 核心模块一览

| 模块 | 路径 | 职责 |
|---|---|---|
| 插件入口 | `src/lib/index.js` | 导出 `install`，注册根组件 |
| 根组件 | `src/lib/layout/main.vue` | 挂载 `ChatMain`，处理 props 与显隐 |
| 聊天主界面 | `src/lib/components/chatMain/index.vue` | 智能体列表 / 会话列表 / 聊天详情编排 |
| 聊天详情 | `src/lib/components/chatMain/ChatDetail.vue` | 消息渲染、SSE 流式对话、TokUI 表单 DSL、上传/语音 |
| TokUI 表单 | `src/lib/tokui-validator/` | DSL → DOM 渲染补丁 + 校验 + 提交 + 审批流程 |
| 新接口层 | `src/lib/api/apichat.js` | 智能体会话 REST + SSE 签名 |
| 新请求封装 | `src/lib/utils/request.js` | 带 HmacSHA256 签名的 axios 封装 |
| 旧接口/请求 | `src/lib/api/apiObs.js`、`src/lib/http/index.js` | OBS 上传、语音转文字（旧 axios 封装） |
| WebSocket | `src/lib/socket/` | 旧 IM 客服通信（当前主流程未启用） |
| Vuex | `src/lib/store/` | 插件内部状态（ZJAIModule） |
| 环境配置 | `src/lib/env/` | dev / pre / prod 三套环境变量 |

---

## 文档索引

### 核心文档

| 文档 | 说明 |
|---|---|
| [docs/project-architecture.md](./docs/project-architecture.md) | 项目总体架构、模块关系、新旧架构说明、调用链、环境配置、已知隐患 |
| [docs/tokui-form-flow.md](./docs/tokui-form-flow.md) | TokUI 表单完整流程：DSL → 渲染 → 校验 → 提交 → 审批 → 遮罩 |

### DSL 生成参考 ⭐

**AI 生成表单 DSL 时使用：**

| 文档 | 说明 |
|---|---|
| **[README_DSL.md](./README_DSL.md)** | **快速入口（推荐）** |
| [docs/DSL_AI_REFERENCE.md](./docs/DSL_AI_REFERENCE.md) | AI 生成 DSL 专用参考文档 |

> **说明**：包含补卡、请假两个完整示例，核心规则（5件套、3种变量、级联选择），输出格式要求，生成检查清单。AI 参考示例按统一格式生成新的表单 DSL。

---

## 开发注意事项（重要）

1. **两套架构并存**：当前主流程走「REST + SSE」（`apichat.js` + `utils/request.js`）；`socket/` 目录是旧 WebSocket IM，`layout/main.vue` 中 `openIM/closeIM` 已被注释，未启用。
2. **两套 HTTP 封装**：`utils/request.js`（新，带签名）与 `http/index.js`（旧，带 spiderHack 解密），分别被不同 api 文件使用，不要混用。
3. **两套 Vuex store**：`src/lib/store/`（插件内部 `ZJAIModule`）与 `src/store/`（demo 宿主）是独立的，互不影响。
4. **硬编码地址**：`apichat.createStreamUrl` 与 `utils/request.js` 中 `BASE`/`baseURL` 当前硬编码为 `http://localhost:8080`，生产环境需改为走环境变量或 `setBaseURL`。
5. **路径别名**：`@` → `src`，`@lib` → `src/lib`，`@style` → `src/lib/style`（见 `vue.config.js`）。
6. **`.mjs` 处理**：`vue.config.js` 已针对 `markdown-it` 等 node_modules 内 `.mjs` 做兼容处理，勿删除相关配置。

更详细的架构、调用关系与历史遗留问题见 [docs/project-architecture.md](./docs/project-architecture.md)。