# 公告订阅推送 API Skill

深交所公告订阅推送服务，支持按公司、类别订阅上市公司公告，并通过邮件/钉钉/飞书实时推送结构化提取结果。

**服务地址：** `http://39.104.68.74:8452`

## 快速开始

**Base URL:** `http://39.104.68.74:8452/api/v1`

**认证方式：** 所有 API 请求需要在请求头中携带 API Key

```bash
X-API-Key: your_api_key_here
```

**获取 API Key：** 访问 http://39.104.68.74:8452 注册账号后获取

## 核心功能

### 1. 创建订阅

订阅某公司的某类别公告：

```bash
curl -X POST "http://39.104.68.74:8452/api/v1/subscriptions" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sub_type": "company_category",
    "notify_method": "email",
    "notify_target": "user@example.com",
    "company_code": "000001",
    "company_name": "平安银行",
    "category_code": "ctb_company_0081",
    "category_name": "董事会决议"
  }'
```

**订阅类型 (sub_type)：**
- `company` - 订阅某公司所有已开放类别
- `category` - 订阅所有公司的某类别
- `company_category` - 精准订阅某公司某类别
- `daily_digest` - 每日聚合推送

**通知方式 (notify_method)：**
- `email` - 邮件推送
- `dingtalk` - 钉钉机器人
- `feishu` - 飞书机器人

### 2. 查询订阅列表

```bash
curl "http://39.104.68.74:8452/api/v1/subscriptions?page=1&page_size=20" \
  -H "X-API-Key: your_api_key"
```

### 3. 更新订阅

```bash
curl -X PUT "http://39.104.68.74:8452/api/v1/subscriptions/{subscription_id}" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": true,
    "notify_target": "new@example.com"
  }'
```

### 4. 删除订阅

```bash
curl -X DELETE "http://39.104.68.74:8452/api/v1/subscriptions/{subscription_id}" \
  -H "X-API-Key: your_api_key"
```

### 5. 查询可订阅类别

```bash
curl "http://39.104.68.74:8452/api/v1/subscriptions/available-categories" \
  -H "X-API-Key: your_api_key"
```

### 6. 查询可订阅公司

```bash
curl "http://39.104.68.74:8452/api/v1/subscriptions/available-companies?keyword=平安&page=1&page_size=20" \
  -H "X-API-Key: your_api_key"
```

## 使用示例

### 订阅所有公司的董事会决议

```bash
curl -X POST "http://39.104.68.74:8452/api/v1/subscriptions" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sub_type": "category",
    "notify_method": "dingtalk",
    "notify_target": "https://oapi.dingtalk.com/robot/send?access_token=xxx",
    "category_code": "ctb_company_0081",
    "category_name": "董事会决议"
  }'
```

### 每日聚合推送

```bash
curl -X POST "http://39.104.68.74:8452/api/v1/subscriptions" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sub_type": "daily_digest",
    "notify_method": "email",
    "notify_target": "user@example.com",
    "digest_time": "09:00"
  }'
```

## 推送内容格式

推送消息包含：
- 公告标题
- 公司名称和代码
- 公告类别
- 公告日期
- 公告链接
- 结构化提取结果（JSON 格式）

## 更多可用能力（来自 /docs）

### 公告与提取结果查询

#### 1) 按日期范围查询公告提取结果

```bash
curl "http://39.104.68.74:8452/api/v1/announcements?start_date=2026-03-01&end_date=2026-03-05&page=1&page_size=20" \
  -H "X-API-Key: your_api_key"
```

可选参数：
- `infotype`：公告类别名筛选
- `page` / `page_size`：分页

#### 2) 按证券代码查询公告

```bash
curl "http://39.104.68.74:8452/api/v1/stock/000001/announcements?start_date=2026-03-01&end_date=2026-03-05" \
  -H "X-API-Key: your_api_key"
```

#### 3) 按公告链接获取结构化提取结果

```bash
curl "http://39.104.68.74:8452/api/v1/met_link?met_link=https://example.com/announcement.pdf" \
  -H "X-API-Key: your_api_key"
```

### 元信息查询

#### 4) 按 UUID 查询元信息

```bash
curl "http://39.104.68.74:8452/api/met_uuid?met_uuid=your_uuid"
```

#### 5) 按公告链接查询元信息

```bash
curl "http://39.104.68.74:8452/api/met_link_meta?met_link=https://example.com/announcement.pdf"
```

### 认证与账户能力

#### 6) 注册并获取 API Key

```bash
curl -X POST "http://39.104.68.74:8452/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"your_password"}'
```

#### 7) 密码登录

```bash
curl -X POST "http://39.104.68.74:8452/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"your_password"}'
```

#### 8) 查看当前 API Key 信息

```bash
curl "http://39.104.68.74:8452/api/v1/api-key/info" \
  -H "X-API-Key: your_api_key"
```

### 平台统计与配额

#### 9) 获取公开统计

```bash
curl "http://39.104.68.74:8452/api/v1/public/stats"
```

#### 10) 查询订阅配额

```bash
curl "http://39.104.68.74:8452/api/v1/subscriptions/quota" \
  -H "X-API-Key: your_api_key"
```

## 注意事项

⚠️ **重要提示：**
1. API Key 请妥善保管，不要泄露
2. 每个用户可创建多个订阅
3. 重复订阅会返回错误
4. 推送失败会自动重试（最多 3 次）
5. 订阅删除为软删除，实际是禁用订阅

💡 **最佳实践：**
- 建议先查询可订阅类别和公司列表
- 测试时可使用邮件方式，生产环境推荐使用机器人
- 钉钉/飞书机器人需要配置加签密钥以提高安全性

## 技术支持

- 官网：http://39.104.68.74:8452
- API 文档：http://39.104.68.74:8452/api-docs