zj-plugin-intelligent 1.2.8 → 1.2.9

package/README.md

@@ -1,2 +1,126 @@
-# zjkj-npm-intelligent
-
+# 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 → 渲染 → 校验 → 提交 → 审批 → 遮罩 |
+
+---
+
+## 开发注意事项（重要）
+
+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)。