bidding_watcher/widget/looker/frontend/src/shared/README.md

# 共享代码使用说明

## 概述

本共享包提供了HTTP和IPC框架兼容的统一代码实现，包括数据模型、API适配器和共享组件。

## 目录结构

```
shared/
├── models/           # 数据模型定义
│   └── bid-item.ts
├── api/              # API适配器层
│   ├── bid-api.ts      # 统一API接口
│   ├── http-adapter.ts # HTTP适配器实现
│   ├── ipc-adapter.ts  # IPC适配器实现
│   ├── api-factory.ts  # API工厂（环境检测）
│   └── index.ts        # 导出文件
├── components/        # 共享Vue组件
│   ├── BaseBidList.vue
│   ├── BaseAiRecommendations.vue
│   ├── BaseCrawlInfo.vue
│   └── index.ts
├── package.json
└── README.md
```

## 快速开始

### 1. 构建共享包

在项目根目录执行：

```bash
npm run build:shared
```

这将把shared目录的内容复制到两个前端项目中：
- `frontend/src/shared/`
- `widget/looker/frontend/src/shared/`

### 2. 在HTTP前端中使用

```typescript
import { getAPI } from './shared/api'

const api = getAPI()

// 使用API
const bids = await api.getPinnedBids()
```

### 3. 在IPC前端中使用

```typescript
import { getAPI } from './shared/api'

const api = getAPI()

// 使用API（自动检测到Wails环境）
const bids = await api.getPinnedBids()
```

### 4. 使用共享组件

```vue
<script setup>
import { getAPI } from './shared/api'
import BaseBidList from './shared/components/BaseBidList.vue'

const api = getAPI()
</script>

<template>
  <BaseBidList :api="api" title="置顶项目" />
</template>
```

## API接口

### BidAPI接口

```typescript
interface BidAPI {
  // 投标相关
  getPinnedBids(): Promise<BidItem[]>
  getRecentBids(limit?: number): Promise<BidItem[]>
  getBidsByDateRange(startDate: string, endDate: string): Promise<BidItem[]>
  getBidsByParams(params: BidQueryParams): Promise<PaginatedResponse<BidItem>>
  updatePinStatus(title: string, pin: boolean): Promise<void>
  getSources(): Promise<string[]>
  
  // AI推荐相关
  getAiRecommendations(): Promise<AiRecommendation[]>
  saveAiRecommendations(recommendations: AiRecommendation[]): Promise<void>
  getLatestRecommendations(): Promise<AiRecommendation[]>
  
  // 关键词相关
  getKeywords(): Promise<Keyword[]>
  addKeyword(word: string, weight?: number): Promise<Keyword>
  deleteKeyword(id: string): Promise<void>
  
  // 爬虫相关
  getCrawlStats(): Promise<CrawlInfoStat[]>
  runCrawler(): Promise<void>
  runCrawlerBySource(sourceName: string): Promise<void>
  getCrawlerStatus(): Promise<{ status: string; lastRun: string }>
}
```

## 数据模型

### BidItem

```typescript
interface BidItem {
  id: string
  title: string
  url: string
  publishDate: string
  source: string
  pin: boolean
  createdAt: string
  updatedAt: string
}
```

### AiRecommendation

```typescript
interface AiRecommendation {
  id: string
  title: string
  confidence: number
  createdAt: string
}
```

### CrawlInfoStat

```typescript
interface CrawlInfoStat {
  source: string
  count: number
  latestUpdate: string
  latestPublishDate: string
  error: string
}
```

## 环境检测

API工厂会自动检测运行环境：

- **HTTP环境**: 浏览器环境，使用HTTP适配器
- **IPC环境**: Wails桌面应用环境，使用IPC适配器

可以通过以下方式手动检测：

```typescript
import { getEnvironment } from './shared/api'

const env = getEnvironment() // 'http' | 'ipc'
```

## 开发命令

### 构建共享包

```bash
npm run build:shared
```

### 开发HTTP前端

```bash
npm run dev:frontend
```

### 开发IPC前端

```bash
npm run dev:widget
```

### 构建所有

```bash
npm run build:all
```

## 注意事项

1. **环境变量**: HTTP前端需要配置`VITE_API_BASE_URL`环境变量
2. **数据库配置**: IPC前端需要确保`.env`文件配置正确
3. **类型定义**: 确保TypeScript配置正确引用共享包
4. **组件导入**: 使用相对路径导入共享组件

## 故障排除

### 问题：API调用失败

**解决方案**：
1. 检查环境变量配置
2. 确认后端服务运行状态
3. 查看浏览器控制台错误信息

### 问题：组件样式不生效

**解决方案**：
1. 确认组件作用域样式正确
2. 检查CSS导入顺序
3. 清除浏览器缓存

### 问题：环境检测错误

**解决方案**：
1. 检查`window.go`对象是否存在
2. 确认Wails运行时环境
3. 使用`getEnvironment()`函数调试

## 扩展指南

### 添加新的API方法

1. 在`shared/api/bid-api.ts`中添加接口定义
2. 在`shared/api/http-adapter.ts`中实现HTTP版本
3. 在`shared/api/ipc-adapter.ts`中实现IPC版本
4. 在`widget/looker/app.go`中添加Go后端方法（如需要）

### 添加新的共享组件

1. 在`shared/components/`目录创建新组件
2. 使用`api` prop接收API实例
3. 在`shared/components/index.ts`中导出组件
4. 在前端项目中导入使用

## 技术支持

如有问题，请参考：
- 技术方案文档: [`../plans/http-ipc-compatibility-plan.md`](../plans/http-ipc-compatibility-plan.md)
- 项目README: [`../README.md`](../README.md)