# hcp-server

**Repository Path**: zh-self-skills/hcp-server

## Basic Information

- **Project Name**: hcp-server
- **Description**: FastAPI 后端服务，用于向 RabbitMQ 推送 PAD 设备通知消息。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## hcp-server

FastAPI 后端服务，用于向 RabbitMQ 推送 PAD 设备通知消息。

## 1. 项目介绍

使用 Python 3.12 + uv 管理 FastAPI 后端服务，调用接口完成对 RabbitMQ 消息的推送。

- **RabbitMQ 交换机**: `pad.notify.exchange`
- **Routing Key**: `pad.notify.设备ID`
- **消息结构体**: `PadNotifyMessage`

### 消息结构体

```json
{
  "messageType": "CALLER_NOTIFY",
  "deviceId": "PAD001",
  "winId": "WIN001",
  "winNum": "1",
  "callType": 1,
  "ticketNumber": "A001",
  "loginUsr": 1001,
  "deptCode": "DEPT001",
  "callerId": "CALLER001",
  "timestamp": 1234567890123,
  "extraInfo": "{\"key\": \"value\"}"
}
```

字段说明：
- `messageType`: 消息类型，默认 "CALLER_NOTIFY"
- `deviceId`: 目标 PAD 设备 ID（必填）
- `winId`: 窗口 ID（可选）
- `winNum`: 窗口编号（可选）
- `callType`: 叫号类型（1-开始叫号，2-重新叫号，3-评价）（可选）
- `ticketNumber`: 票号（可选）
- `loginUsr`: 办理人员 ID（可选）
- `deptCode`: 部门编码（可选）
- `callerId`: 叫号器 ID（可选）
- `timestamp`: 消息时间戳（毫秒），默认自动生成
- `extraInfo`: 额外信息（JSON 格式）（可选）

## 2. 环境要求

- Python 3.12+
- [uv](https://github.com/astral-sh/uv) 包管理器
- RabbitMQ 服务器

## 3. 快速开始

### 3.1 克隆项目

```bash
cd /Users/zhenghui/xa-work/hcp/hcp-server
```

### 3.2 安装依赖

```bash
uv sync
```

### 3.3 配置环境变量

复制 `.env.example` 到 `.env` 并修改配置：

```bash
cp .env.example .env
```

编辑 `.env` 文件，配置 RabbitMQ 连接信息：

```env
# RabbitMQ Configuration
RABBITMQ_HOST=localhost
RABBITMQ_PORT=5672
RABBITMQ_USER=guest
RABBITMQ_PASS=guest
RABBITMQ_VHOST=/

# Exchange Configuration
EXCHANGE_NAME=pad.notify.exchange
ROUTING_KEY_PREFIX=pad.notify.
```

### 3.4 启动服务

```bash
uv run main.py
```

或使用 uvicorn：

```bash
uv run uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

服务启动后访问：
- API 文档: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
- OpenAPI JSON: http://localhost:8000/openapi.json

## 4. API 接口

### 4.1 发送通知消息（URL 指定设备 ID）

**接口**: `POST /api/v1/notify/{device_id}`

**请求体**:
```json
{
  "deviceId": "PAD001",
  "winId": "WIN001",
  "winNum": "1",
  "callType": 1,
  "ticketNumber": "A001",
  "loginUsr": 1001,
  "deptCode": "DEPT001",
  "callerId": "CALLER001",
  "extraInfo": "{\"key\": \"value\"}"
}
```

**响应**:
```json
{
  "status": "success",
  "message": "Message sent successfully",
  "device_id": "PAD001",
  "routing_key": "pad.notify.PAD001",
  "message": {...}
}
```

### 4.2 发送通知消息（Body 指定设备 ID）

**接口**: `POST /api/v1/notify`

**请求体**: 同 4.1，但 `deviceId` 为必填字段

### 4.3 健康检查

**接口**: `GET /api/v1/health`

**响应**:
```json
{
  "status": "healthy",
  "service": "hcp-server"
}
```

## 5. 测试示例

### 使用 curl

```bash
# 发送通知到设备 PAD001
curl -X POST "http://localhost:8000/api/v1/notify/PAD001" \
  -H "Content-Type: application/json" \
  -d '{
    "winId": "WIN001",
    "winNum": "1",
    "callType": 1,
    "ticketNumber": "A001",
    "loginUsr": 1001,
    "deptCode": "DEPT001",
    "callerId": "CALLER001"
  }'
```

### 使用 Python requests

```python
import requests

url = "http://localhost:8000/api/v1/notify/PAD001"
data = {
    "winId": "WIN001",
    "winNum": "1",
    "callType": 1,
    "ticketNumber": "A001",
    "loginUsr": 1001,
    "deptCode": "DEPT001",
    "callerId": "CALLER001"
}

response = requests.post(url, json=data)
print(response.json())
```

## 6. 项目结构

```
hcp-server/
├── app/
│   ├── __init__.py       # 包初始化
│   ├── models.py          # Pydantic 模型定义
│   ├── rabbitmq.py        # RabbitMQ 客户端
│   └── api.py             # FastAPI 路由
├── main.py                # 主应用入口
├── pyproject.toml         # 项目配置和依赖
├── .env                   # 环境变量配置（不提交到 git）
├── .env.example           # 环境变量示例
├── .gitignore             # Git 忽略文件
└── README.md              # 项目文档
```

## 7. 开发

### 7.1 安装开发依赖

```bash
uv sync --all-extras
```

### 7.2 运行测试

```bash
uv run pytest
```

### 7.3 代码格式化

```bash
uv run black .
uv run isort .
```

## 8. 许可证

MIT License