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. 构建共享包

在项目根目录执行：

npm run build:shared

这将把shared目录的内容复制到两个前端项目中：

• frontend/src/shared/
• widget/looker/frontend/src/shared/

2. 在HTTP前端中使用

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

const api = getAPI()

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

3. 在IPC前端中使用

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

const api = getAPI()

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

4. 使用共享组件

<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接口

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

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

AiRecommendation

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

CrawlInfoStat

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

环境检测

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

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

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

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

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

开发命令

构建共享包

npm run build:shared

开发HTTP前端

npm run dev:frontend

开发IPC前端

npm run dev:widget

构建所有

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
• 项目README: ../README.md