# hk

**Repository Path**: xiak/hk

## Basic Information

- **Project Name**: hk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-04-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 物联网获客系统 Lead Generation System（V4）

## 项目概述

自动化采集千里马招标网数据，为物联网（智慧园区、梯控、停车等）行业销售团队提供高质量招标线索。

### 核心功能

- **招标数据采集**：关键词可后台配置 + 30天范围 + 质量评分筛选
- **定时任务**：Celery Beat 每天凌晨自动采集
- **管理后台**：招标列表 / 数据看板 / 爬虫控制 / 关键词管理 (v2.0)
- **AI 评分**：本地规则引擎优先，边界 case 调 Claude API，零外部依赖规则引擎

## 项目结构

```
lead-generation-system/
├── common/            # 公共基础模块（MySQL/Redis/Logging/Config/Exceptions）
├── backend/           # 后端（FastAPI + Celery + uv）      → backend/README.md
├── ai/                # 独立 AI 服务（排版 + 评分）        → ai/README.md
├── frontend/          # 前端（Vue 3 + Tailwind CSS）        → frontend/README.md
├── crawler/           # 爬虫（Scrapy + Playwright）        → crawler/README.md
├── docs/
│   ├── api/
│   └── design/
├── pyproject.toml     # uv 项目配置
└── Makefile           # 统一命令入口
```

### common/ 公共模块说明

| 模块 | 用途 |
|------|------|
| `common.config` | 统一 `.env` 加载，`getenv()` 全项目共享 |
| `common.logging` / `common.logging_config` | 统一日志初始化，`setup_logging()` |
| `common.mysql_client` | MySQL 连接池，`get_db()` 上下文管理器 |
| `common.redis_client` | Redis 连接 + 队列/Pub/Sub 封装 |
| `common.exceptions` | 统一异常类：`DatabaseError` / `RedisError` 等 |
| `common.__init__` | 统一导出所有 Redis 键名常量 |

## 快速启动

### 1. 环境准备

```bash
# 安装 uv（跨平台 Python 包管理器）
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### 2. 后端（推荐方式）

```bash
# 安装依赖
make install-dev

# 启动 API 服务（热重载）
make dev

# 启动 Celery Worker（单独终端）
make celery

# 启动定时调度（单独终端）
make celery-beat
```

### 3. 前端

```bash
cd frontend
npm install
npm run dev      # http://localhost:3000
```

### 4. 爬虫本地调试

```bash
cd crawler
scrapy crawl qianlima -a keywords="智慧园区" -a days=7 -a console_only="true"
```

## 项目文档

| 文档 | 说明 | 适用场景 |
|------|------|----------|
| [`docs/local-dev.md`](docs/local-dev.md) | 本地开发指南（环境配置 + 各模块启动验证） | 新人上手 |
| [`docs/tech-stack.md`](docs/tech-stack.md) | 技术栈汇总（语言/中间件/基础设施） | 了解全貌 |
| [`docs/celery-guide.md`](docs/celery-guide.md) | Celery 使用指南（任务队列 + 定时调度） | 后台任务开发 |
| [`docs/dev-rules.md`](docs/dev-rules.md) | 开发规范 + 经验教训 + 详细部署手册 | 编码规范 |
| [`docs/uv-tutorial.md`](docs/uv-tutorial.md) | uv 使用教程 | 包管理 |
| [`docs/data-sources/government-platforms.md`](docs/data-sources/government-platforms.md) | 全国政府招标平台 URL 列表 | 数据源索引 |
| [`docs/data-sources/government-platforms-detail.md`](docs/data-sources/government-platforms-detail.md) | 各平台搜索结构、参数、爬取难度分析 | 爬虫开发 |

> **规范**：相同内容不重复写到多个文件。启动脚本写进 `start-all.bat` 及 `docs/dev-rules.md`，不在 `local-dev.md` 再写一遍。

## 技术栈

完整技术栈与中间件说明见 [`docs/tech-stack.md`](docs/tech-stack.md)。

| 模块 | 技术 |
|------|------|
| 前端 web | Vue 3 + Tailwind CSS 3.4 + Vite + Pinia + Vue Router |
| 后端 api | FastAPI + SQLAlchemy + Celery + **uv** 包管理 |
| 爬虫 crawler | Scrapy 2.11 + Playwright + lxml |
| AI 服务 | httpx + pymysql + redis-py（独立进程，与 backend 同级） |
| 公共模块 | pymysql + redis-py + logging（全部下沉 `common/`） |
| 数据库 | MySQL 5.7（`hk` 数据库） |
| 缓存/队列 | Redis 7.x |

## 数据质量规则

- 质量分 < 50 → 过滤不入库
- 发布年份 < 2018 → 过滤不入库
- 内容中文字符 < 50 → 过滤不入库
- 标题含"恭贺/恭喜"前缀 → 自动清洗

## 许可证

内部使用