npm package: @lee_miranda/hy-chat-result
Description: 紅楹智能問答結果展示組件 - 支持指標卡片、參數設置、數據圖表展示
Latest version: 1.0.1

# hy-chat-result

紅楹智能問答結果展示組件 - 支持指標卡片、參數設置、數據圖表展示

## 📦 安裝

```bash
# 使用 npm
npm install @lee_miranda/hy-chat-result

# 使用 yarn
yarn add @lee_miranda/hy-chat-result

# 使用 pnpm
pnpm add @lee_miranda/hy-chat-result
```

### 如果遇到依賴衝突

如果安裝時提示 `ERESOLVE unable to resolve dependency tree` 錯誤，使用以下命令：

```bash
# 方式1：忽略 peer 依賴檢查（推薦）
npm install @lee_miranda/hy-chat-result --legacy-peer-deps

# 方式2：強制安裝
npm install @lee_miranda/hy-chat-result --force
```

### 依賴要求

此組件依賴以下庫，請確保你的項目已安裝：

| 依賴 | 版本要求 |
|------|----------|
| vue | ^2.6.0 或 ^2.7.0 |
| element-ui | ^2.13.0+ |
| echarts | ^4.0.0 或 ^5.0.0 |
| markdown-it | ^12.0.0 或 ^13.0.0 |
| highlight.js | ^10.0.0 或 ^11.0.0 |
| dompurify | ^2.0.0 或 ^3.0.0 |
| marked | ^4.0.0 或 ^5.0.0 |

## 🚀 快速開始

### 方式一：全局註冊（推薦）

```javascript
// main.js
import Vue from 'vue'
import ElementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'
import HyChatResult from '@lee_miranda/hy-chat-result'
import '@lee_miranda/hy-chat-result/dist/hy-chat-result.css'

Vue.use(ElementUI)

// 使用插件（默認會自動讀取 window.APIURL.hwchatHost）
Vue.use(HyChatResult)

// 或者手動指定 API 地址
// Vue.use(HyChatResult, {
//   apiHost: 'https://your-api-server.com'
// })
```

### API 地址配置說明

組件會按以下優先級獲取 API 地址：

1. **手動設置**：通過 `apiHost` prop 或 `setApiHost()` 方法設置
2. **全局配置**：自動讀取 `window.APIURL.hwchatHost`
3. **代理配置**：開發環境可配置 `/hwchatHost` 代理

```javascript
// 方式1：在項目中配置全局變量（推薦）
window.APIURL = {
  hwchatHost: 'https://your-api-server.com'
}

// 方式2：組件 prop 傳入
<HyChatResult api-host="https://your-api-server.com" />

// 方式3：直接調用 API
import { setApiHost } from 'hy-chat-result'
setApiHost('https://your-api-server.com')
```

### 方式二：局部引入

```vue
<template>
  <div class="chat-container">
    <HyChatResult
      ref="chatResult"
      :api-host="apiHost"
      :question="question"
      @request-complete="onComplete"
      @request-error="onError"
    />
  </div>
</template>

<script>
import { HyChatResult } from 'hy-chat-result'
import 'hy-chat-result/dist/hy-chat-result.css'

export default {
  components: {
    HyChatResult
  },
  data() {
    return {
      apiHost: 'https://your-api-server.com',
      question: ''
    }
  },
  methods: {
    // 發送問題
    sendQuestion(query) {
      this.question = query
      // 或直接調用組件方法
      // this.$refs.chatResult.sendQuestion(query)
    },
    onComplete(data) {
      console.log('請求完成:', data)
    },
    onError(error) {
      console.error('請求錯誤:', error)
    }
  }
}
</script>
```

## 📖 API 文檔

### HyChatResult 主組件

這是主要的聊天結果展示組件，集成了所有子組件和 API 調用邏輯。

#### Props

| 參數 | 說明 | 類型 | 默認值 |
|------|------|------|--------|
| `apiHost` | API 服務器地址 | `String` | `''` |
| `showUserQuestion` | 是否顯示用戶問題 | `Boolean` | `true` |
| `token` | 認證 Token（可選） | `String` | `''` |
| `question` | 初始問題（設置後自動發起請求） | `String` | `''` |
| `chatId` | 會話 ID（用於繼續已有對話） | `String` | `''` |

#### Events

| 事件名 | 說明 | 回調參數 |
|--------|------|----------|
| `request-start` | 請求開始時觸發 | `{ type, query?, params?, index? }` |
| `request-complete` | 請求完成時觸發 | `{ type, chatId, chatData }` |
| `request-error` | 請求錯誤時觸發 | `{ error, type }` |
| `request-stop` | 用戶停止請求時觸發 | - |
| `chat-clear` | 對話清空時觸發 | - |
| `chat-id-update` | 會話 ID 更新時觸發 | `chatId` |
| `chunk-received` | 收到流式數據塊時觸發 | `{ data, ctx }` |

#### Methods

| 方法名 | 說明 | 參數 |
|--------|------|------|
| `sendQuestion(query)` | 發送問題 | `query: String` |
| `stopRequest()` | 停止當前請求 | - |
| `clearChat()` | 清空對話 | - |
| `getChatData()` | 獲取當前對話數據 | 返回 `{ chatId, chatData }` |

### HyIndicators 指標卡片組件

用於展示和選擇指標的卡片組件。

#### Props

| 參數 | 說明 | 類型 | 默認值 |
|------|------|------|--------|
| `IndicatorsData` | 指標數據 | `Object` | `{}` |
| `chatIndex` | 當前聊天索引 | `Number` | `0` |
| `loading` | 是否顯示加載狀態 | `Boolean` | `false` |

#### Events

| 事件名 | 說明 | 回調參數 |
|--------|------|----------|
| `next` | 點擊下一步時觸發 | `(params, chatIndex)` |

### HyParamSet 參數設置組件

用於設置查詢參數的表單組件。

#### Props

| 參數 | 說明 | 類型 | 默認值 |
|------|------|------|--------|
| `paramsSetData` | 參數配置數據 | `Object` | `{}` |
| `chatIndex` | 當前聊天索引 | `Number` | `0` |
| `loading` | 是否顯示加載狀態 | `Boolean` | `false` |
| `disabled` | 是否禁用表單 | `Boolean` | `false` |

#### Events

| 事件名 | 說明 | 回調參數 |
|--------|------|----------|
| `confirm` | 點擊確認時觸發 | `(params, chatIndex)` |
| `prev` | 點擊上一步時觸發 | `(chatIndex)` |

### HyMarkdownEcharts Markdown 圖表組件

用於渲染 Markdown 內容和 ECharts 圖表的組件。

#### Props

| 參數 | 說明 | 類型 | 默認值 |
|------|------|------|--------|
| `content` | Markdown 內容（支持嵌入 ECharts 配置） | `String` | `''` |

## 🔧 API 方法

除了組件，還可以直接使用 API 方法：

```javascript
import {
  setApiHost,
  getApiHost,
  hwChatStream,
  indexSetStream,
  paramSetStream,
  cancelStreamRequest,
  cancelAllStreamRequests
} from 'hy-chat-result'

// 設置 API 地址
setApiHost('https://your-api-server.com')

// 發起聊天流式請求
const cancelFn = hwChatStream(
  { chatID: '', query: '分析比亞迪的盈利能力' },
  (chunk) => console.log('收到數據:', chunk),
  (result) => console.log('完成:', result),
  (error) => console.error('錯誤:', error)
)

// 取消請求
cancelFn()
// 或
cancelStreamRequest('hwChatStream_request')
```

## 📋 數據結構

### 聊天記錄結構

```typescript
interface ChatItem {
  userQuestion: string;      // 用戶問題
  sysAnswers: AnswerItem[];  // 系統回答列表
}

interface AnswerItem {
  id: string;
  answerType: number;        // 0=普通文本, 1=指標卡片, 2=參數設置, 3=數據結果, 5=已停止
  content: string;           // 內容（JSON 字符串或普通文本）
  showType: 'TEXT' | 'CARD'; // 顯示類型
  describeAnswer?: string;   // 描述數據（用於圖表展示）
  statusContent?: string;    // 狀態信息（如"正在分析..."）
}
```

### 指標數據結構

```typescript
interface IndicatorsData {
  Action: '下一步' | '確認' | '完成';
  Components: ComponentItem[];
  HasPreStep: boolean;
  PlanText: string;
  Title: string;
}

interface ComponentItem {
  Name: string;
  Operable: boolean;
  Component: {
    Title: string;
    FieldType: string;
    DataType: string;
    CompType: string;
    SelValue: string[];
    SelValue1: string[];
    Value: string[];
  }[];
}
```

## 🎨 樣式自定義

組件使用 SCSS 編寫樣式，你可以通過以下方式自定義：

### 方式一：覆蓋 CSS 變量（如支持）

```css
:root {
  --hy-primary-color: #409eff;
  --hy-text-color: #333;
  --hy-border-color: #e8e8e8;
}
```

### 方式二：覆蓋類名

```scss
.hy-chat-result {
  // 自定義樣式
}

.hy-indicators-card {
  .card-header {
    background: linear-gradient(135deg, #your-color 0%, #your-color2 100%);
  }
}
```

## 📝 完整示例

```vue
<template>
  <div class="app">
    <!-- 輸入框 -->
    <div class="input-area">
      <el-input
        v-model="inputText"
        placeholder="請輸入問題"
        @keyup.enter.native="handleSend"
      />
      <el-button type="primary" @click="handleSend">發送</el-button>
      <el-button @click="handleStop">停止</el-button>
      <el-button @click="handleClear">清空</el-button>
    </div>

    <!-- 聊天結果展示 -->
    <div class="chat-area">
      <HyChatResult
        ref="chatResult"
        :api-host="apiHost"
        :show-user-question="true"
        @request-start="onStart"
        @request-complete="onComplete"
        @request-error="onError"
        @chat-id-update="onChatIdUpdate"
      />
    </div>
  </div>
</template>

<script>
import { HyChatResult } from 'hy-chat-result'
import 'hy-chat-result/dist/hy-chat-result.css'

export default {
  components: { HyChatResult },

  data() {
    return {
      apiHost: 'https://your-api-server.com',
      inputText: '',
      chatId: ''
    }
  },

  methods: {
    handleSend() {
      if (!this.inputText.trim()) return
      this.$refs.chatResult.sendQuestion(this.inputText)
      this.inputText = ''
    },

    handleStop() {
      this.$refs.chatResult.stopRequest()
    },

    handleClear() {
      this.$refs.chatResult.clearChat()
      this.chatId = ''
    },

    onStart(data) {
      console.log('請求開始:', data.type)
    },

    onComplete(data) {
      console.log('請求完成:', data)
      // 可以保存聊天記錄
      localStorage.setItem('chatData', JSON.stringify(data.chatData))
    },

    onError({ error, type }) {
      this.$message.error(error.message || '請求失敗')
    },

    onChatIdUpdate(chatId) {
      this.chatId = chatId
    }
  }
}
</script>

<style scoped>
.app {
  max-width: 800px;
  margin: 0 auto;
  padding: 20px;
}

.input-area {
  display: flex;
  gap: 10px;
  margin-bottom: 20px;
}

.chat-area {
  background: #f5f7fa;
  padding: 20px;
  border-radius: 8px;
  min-height: 400px;
}
</style>
```

## 🔨 本地開發

```bash
# 進入組件目錄
cd packages/hy-chat-result

# 安裝依賴
npm install

# 構建
npm run build
```

## 📄 License

MIT