# 微信公众号API参考文档

## 认证模块 (Auth)

### 初始化参数

| 参数                | 类型     | 必填 | 说明                         |
| ------------------- | -------- | ---- | ---------------------------- |
| app_id              | str      | 否   | 微信公众号AppID              |
| app_secret          | str      | 否   | 微信公众号AppSecret          |
| proxy               | str      | 否   | 代理服务器地址               |
| callback_first      | bool     | 否   | 获取token策略，默认True      |
| expire_offset       | int      | 否   | token提前过期时间，默认100秒 |
| access_token_getter | callable | 否   | 自定义token获取回调函数      |

### 方法

#### get_access_token()

获取access_token，自动处理缓存和刷新。

```python
auth = Auth(app_id="xxx", app_secret="xxx")
token = auth.get_access_token()
```

#### from_env(account=None)

从环境变量智能加载配置，支持多账号。

```python
# 使用默认账号（账号1）
auth = Auth.from_env()

# 指定账号
auth2 = Auth.from_env("2")
```

## 草稿模块 (Draft)

### 便捷方法（推荐）

#### add_news_article() - 快速创建图文消息

最便捷的创建草稿方法，自动处理封面图上传：

```python
draft = Draft(auth)

# 最简单方式 - 自动上传封面并创建草稿
result = draft.add_news_article(
    title="文章标题",
    content="文章内容",
    thumb_image_path="cover.jpg",  # 自动上传封面图
    author="作者",
    digest="摘要",
    auto_draft=True  # 自动创建草稿
)
```

**参数说明：**

| 参数                  | 类型               | 必填   | 说明                                                                          |
| --------------------- | ------------------ | ------ | ----------------------------------------------------------------------------- |
| title                 | str                | **是** | 标题，不超过32字                                                              |
| content               | str                | 否\*   | 正文内容，不超过2万字符，支持文件路径或直接内容                               |
| content_file          | str                | 否\*   | 内容文件路径（与 content 二选一）                                             |
| thumb_media_id        | str                | 否\*\* | 封面图媒体ID                                                                  |
| thumb_image_path      | str                | 否\*\* | 封面图片文件路径（自动上传）                                                  |
| thumb_image_content   | bytes              | 否\*\* | 封面图片二进制内容（自动上传）                                                |
| thumb_image_url       | str                | 否\*\* | 封面图片URL（自动下载并上传）                                                 |
| author                | str                | 否     | 作者，不超过8字                                                               |
| digest                | str                | 否     | 摘要，不超过128字                                                             |
| content_source_url    | str                | 否     | 原文链接                                                                      |
| need_open_comment     | bool               | 否     | 是否打开评论                                                                  |
| only_fans_can_comment | bool               | 否     | 是否仅粉丝可评论                                                              |
| auto_draft            | bool               | 否     | 是否自动创建草稿，默认True                                                    |
| content_processor     | bool/callable      | 否     | 内容处理器：True自动去HTML注释，False不启用，callable自定义处理               |
| validate              | bool               | 否     | 是否启用参数校验，默认False                                                   |
| replace_image_links   | bool               | 否     | 是否替换图片链接为图文消息图片链接，默认False                                 |
| skip_domains          | tuple              | 否     | 要跳过的域名，默认("qpic.cn", ) |
| custom_image_pattern  | str/tuple/callable | 否     | 自定义图片匹配规则：正则表达式字符串、(pattern, flags)元组、或回调函数        |

> \*正文参数 content 和 content_file 二选一
> \*\*封面图参数四选一，如果都不提供会报错

### 其他方法

#### create_multi_article_draft_from_dir()

从目录批量创建多图文草稿。读取目录下所有HTML文件，从文件头提取元数据，创建包含多篇文章的草稿。

```python
from xqcwechat import Auth
from xqcwechat.wechat import Draft

auth = Auth.from_env()
draft = Draft(auth)

result = draft.create_multi_article_draft_from_dir(
    dir_path="path/to/articles/directory",
    replace_image_links=True,
    auto_publish=False
)
```

**参数说明：**

| 参数 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| dir_path | str | **是** | 目录路径，目录下应包含多个HTML文件 |
| skip_domains | tuple | 否 | 要跳过的域名元组，默认 ("qpic.cn", "qlogo.cn") |
| content_processor | bool/callable | 否 | 内容处理器：True自动去HTML注释，False不启用，callable自定义处理 |
| validate | bool | 否 | 是否启用参数校验，默认False |
| replace_image_links | bool | 否 | 是否替换图片链接为图文消息图片链接，默认True |
| verbose | bool | 否 | 是否打印详细信息，默认True |
| sort_key | bool/callable | 否 | 排序规则：False不排序，True按文件名开头数字排序，callable自定义排序函数 |

**返回结果：**

| 字段 | 类型 | 说明 |
| ---- | ---- | ---- |
| success | bool | 是否成功 |
| media_id | str | 草稿media_id（成功时） |
| articles_count | int | 文章数量 |
| articles | list | 每篇文章的详细信息列表 |
| error | str | 错误信息（失败时） |

**HTML文件头元数据格式：**

```html
<!--
title：文章标题
author：作者名
cover_url：封面图片URL
digest：摘要
is_xiaoqiangclub：true
thumb_media_id：封面图片media_id
cover_local_path：本地封面图片路径
-->
```

#### upload_article_image()

上传图文消息内的图片，返回图片URL（用于文章正文中的图片）

**此方法位于 Draft 类中**，直接通过 Draft 实例调用：

```python
from xqcwechat import Auth
from xqcwechat.wechat import Draft

auth = Auth.from_env()
draft = Draft(auth)

result = draft.upload_article_image(image_path="path/to/image.jpg")
# 返回 {'url': 'https://mmbiz.qpic.cn/...'}
```

| 参数 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| image_path | str | 否\* | 图片文件路径 |
| image_content | bytes | 否\* | 图片二进制内容 |
| image_url | str | 否\* | 图片URL（会自动下载并上传） |

> \* 三选一

#### get_draft_list(offset=0, count=20, no_content=False)

获取草稿列表

#### create_draft(articles)

创建草稿

**参数 articles 中的字段说明：**

| 字段               | 类型 | 必填           | 说明                                                              |
| ------------------ | ---- | -------------- | ----------------------------------------------------------------- |
| title              | str  | **是**         | 标题，不超过32字                                                  |
| content            | str  | **是**         | 正文内容，不超过2万字符                                           |
| thumb_media_id     | str  | **是**（图文） | 封面图媒体ID，使用 `asset.add_material("image", path)` 上传后获取 |
| author             | str  | 否             | 作者，不超过8字                                                   |
| digest             | str  | 否             | 摘要，不超过128字                                                 |
| content_source_url | str  | 否             | 原文链接                                                          |
| show_cover_pic     | int  | 否             | 是否显示封面，1为显示，0为不显示，默认1                           |

> ⚠️ **注意**：`thumb_media_id` 是创建图文消息草稿的**必填参数**。如需创建无封面图片的草稿，请先调用素材上传接口：
>
> ```python
> asset = Asset(auth)
> cover = asset.add_material("image", "cover.jpg")
> thumb_media_id = cover["media_id"]
> ```

#### update_draft(media_id, articles)

更新草稿

#### delete_draft(media_id)

删除草稿

#### get_draft_count()

获取草稿总数

**底层方法（微信官方API名称）：**

- `draft_batchget` - 获取草稿列表
- `draft_add` - 创建草稿
- `draft_update` - 更新草稿
- `draft_delete` - 删除草稿
- `draft_count` - 获取草稿总数

## 发布模块 (Publish)

### 方法

**推荐使用以下直观的方法名：**

#### publish_draft(media_id, title=None)

发布草稿

| 参数     | 类型 | 必填 | 说明                   |
| -------- | ---- | ---- | ---------------------- |
| media_id | str  | 是   | 要发布的草稿的media_id |
| title    | str  | 否   | 用来指定本次发布的标题 |

#### get_publish_status(publish_id)

查询发布状态

#### get_article(article_id)

获取已发布图文信息

#### delete_article(article_id)

删除已发布文章

#### get_published_articles(offset=0, count=20, no_content=False)

获取已发布的消息列表

**底层方法（微信官方API名称）：**

- `freepublish_submit` - 发布草稿
- `freepublish_get` - 查询发布状态
- `freepublish_getarticle` - 获取已发布图文信息
- `freepublish_delete` - 删除已发布文章
- `freepublish_batchget` - 获取已发布消息列表

## 素材模块 (Asset)

### 方法

#### upload_image(file_path)

上传图文消息内的图片，返回图片URL（用于文章正文中的图片）

#### add_material(media_type, media_path)

上传永久素材，返回media_id（用于草稿的 thumb_media_id）

| 参数       | 类型 | 说明                                |
| ---------- | ---- | ----------------------------------- |
| media_type | str  | 素材类型：image, video, voice, news |
| media_path | str  | 文件路径                            |

#### batch_get_material(material_type, offset=0, count=20)

获取永久素材列表

#### del_material(media_id)

删除素材

## 留言模块 (Comment)

### 方法

#### open_article_comment(msg_data_id, index)

打开已群发文章评论

| 参数        | 类型 | 必填 | 说明                              |
| ----------- | ---- | ---- | --------------------------------- |
| msg_data_id | str  | 是   | 群发返回的msg_data_id             |
| index       | int  | 是   | 多图文时指定是哪一篇图文，从0开始 |

#### close_comment(msg_data_id, index)

关闭已群发文章评论

#### list_comment(msg_data_id, index, begin=0, count=50, type=0)

查看指定文章的评论数据

| 参数        | 类型 | 必填 | 说明                                      |
| ----------- | ---- | ---- | ----------------------------------------- |
| msg_data_id | str  | 是   | 群发返回的msg_data_id                     |
| index       | int  | 是   | 多图文时指定是哪一篇图文                  |
| begin       | int  | 否   | 起始位置，从0开始，默认0                  |
| count       | int  | 否   | 获取数目，最大50，默认50                  |
| type        | int  | 否   | 评论类型，0为精选评论，1为普通评论，默认0 |

#### elect_comment(msg_data_id, index, user_comment_id)

评论标记精选

#### unelect_comment(msg_data_id, index, user_comment_id)

评论取消精选

#### del_comment(msg_data_id, index, user_comment_id)

删除评论

#### reply_comment(msg_data_id, index, user_comment_id, content)

回复评论

| 参数            | 类型 | 必填 | 说明                     |
| --------------- | ---- | ---- | ------------------------ |
| msg_data_id     | str  | 是   | 群发返回的msg_data_id    |
| index           | int  | 是   | 多图文时指定是哪一篇图文 |
| user_comment_id | str  | 是   | 用户评论id               |
| content         | str  | 是   | 回复内容                 |
