===================================
Odoo 微信生态集成套件
Odoo WeChat Integration Suite
===================================

.. contents::
   :depth: 3

概述
----

本套件为 Odoo 18 提供完整的微信生态集成方案，包含 5 个独立模块，覆盖：

- **公众号**（订阅号/服务号）消息收发、自动回复、模板消息
- **微信支付**（JSAPI / Native / H5 / APP）
- **微信扫码登录**（OAuth + PC 端扫码确认）
- **企业微信**（通讯录同步、消息推送、外部联系人）

所有模块依赖 ``wechat_base`` 公共层，统一管理 Access Token、公司级凭证和消息记录。

安装顺序
~~~~~~~~

::

    pip install wechatpy>=1.8 qrcode pillow cryptography

    # Odoo addons path 中加入本目录，然后按以下顺序安装：
    1. wechat_base      ← 公共层（必须最先安装）
    2. wechat_mp        ← 公众号（可选）
    3. wechat_payment   ← 微信支付（可选）
    4. wechat_login     ← 扫码登录（可选）
    5. wechat_work      ← 企业微信（可选）


架构图
~~~~~~

::

    ┌─────────────────────────────────────────────────┐
    │                   Odoo 18                       │
    └──────────────────────┬──────────────────────────┘
                           │
                    ┌──────▼──────┐
                    │ wechat_base  │  ← 公共层
                    │              │
                    │  • Token管理  │
                    │  • Webhook   │
                    │  • 消息存储   │
                    │  • 用户Mixin │
                    └──────┬──────┘
                           │
        ┌──────────┬───────┼───────┬──────────┐
        │          │       │       │          │
   ┌────▼───┐ ┌────▼───┐ ┌▼────┐ ┌▼──────┐ ┌▼───────┐
   │wechat_ │ │wechat_ │ │ base│ │wechat_ │ │wechat_ │
   │  _mp   │ │payment │ │hook │ │ _login │ │  _work │
   └────────┘ └────────┘ └─────┘ └───────┘ └────────┘


模块列表
--------

+------------+------------------------+----------+----------------------------------+
| 模块名     | 名称                   | 依赖      | 描述                             |
+============+========================+==========+==================================+
| wechat_base     | 微信基础模块          | base     | Token管理、Webhook、消息存储      |
+-------------+------------------------+----------+----------------------------------+
| wechat_mp       | 微信公众平台          | base     | 自动回复、菜单、模板消息、用户    |
+-------------+------------------------+----------+----------------------------------+
| wechat_payment  | 微信支付              | base     | JSAPI/Native/H5/APP 支付接入     |
+-------------+------------------------+----------+----------------------------------+
| wechat_login    | 微信扫码登录          | base,    | OAuth授权、PC端扫码登录          |
|               |                    | auth_oauth |                                  |
+-------------+------------------------+----------+----------------------------------+
| wechat_work     | 企业微信              | base     | 通讯录同步、消息推送、外部联系人 |
+-------------+------------------------+----------+----------------------------------+


数据模型一览
------------

wechat_base
~~~~~~~~~~~

.. code-block:: text

    res.company                    ← 扩展：AppID, AppSecret, Token, AESKey
    wechat.message                 ← 微信消息记录（入站/出站）
    wechat.user.mixin              ← Mixin：OpenID, UnionID, 关注状态（给 res.partner）
    wechat.request.mixin           ← Mixin：提供 get/post 方法 + Token自动刷新

wechat_mp
~~~~~~~~~

.. code-block:: text

    wechat.mp.message.rule         ← 关键词自动回复规则
    wechat.mp.menu                 ← 自定义菜单配置
    wechat.mp.template.message    ← 模板消息定义
    wechat.mp.mass.message         ← 群发消息
    wechat.mp.user                 ← 公众号用户（继承 wechat.user.mixin）
    wechat.mp.message.log          ← 公众号消息日志（继承 wechat.message）

wechat_payment
~~~~~~~~~~~~~~

.. code-block:: text

    payment.provider               ← 扩展：wechat_mch_id, api_key, cert路径等
    payment.transaction            ← 扩展：wechat_transaction_id, total_fee等
    payment.token                  ← 扩展：wechat_openid, 微信代扣令牌

wechat_login
~~~~~~~~~~~~

.. code-block:: text

    wechat.login.qr.session        ← PC扫码登录会话
    res.partner                    ← 扩展：wechat_last_login, login_count
    res.users                      ← 扩展：wechat_openid, unionid（关联）
    auth.oauth.provider            ← 扩展：wechat_app_id, scope等

wechat_work
~~~~~~~~~~~

.. code-block:: text

    wechat.work.department         ← 企业微信部门
    wechat.work.user               ← 企业微信成员
    wechat.work.tag                ← 企业微信标签
    wechat.work.external.contact   ← 外部联系人（客户）
    wechat.work.message            ← 出站消息记录
    wechat.work.mass.message       ← 群发消息
    wechat.work.message.log        ← 消息日志


HTTP 路由一览
-------------

+--------------------------------+----------+----------------------------+
| 路由                           | 方法     | 说明                        |
+================================+==========+============================+
| wechat_base                                            |
+--------------------------------+----------+----------------------------+
| /wechat/webhook/<company_id>    | GET/POST | 公众号/通用Webhook入口      |
+--------------------------------+----------+----------------------------+
| /wechat/callback/<company_id>   | GET/POST | 备用回调路由                |
+--------------------------------+----------+----------------------------+
| /wechat/health                 | GET      | 健康检查                    |
+--------------------------------+----------+----------------------------+
| wechat_mp                                              |
+--------------------------------+----------+----------------------------+
| /wechat/mp/webhook/<company_id> | GET/POST | 公众号事件回调              |
+--------------------------------+----------+----------------------------+
| /api/wechat/mp/send            | POST     | 发送模板消息                |
+--------------------------------+----------+----------------------------+
| /api/wechat/mp/users           | GET      | 获取关注用户列表            |
+--------------------------------+----------+----------------------------+
| /api/wechat/mp/menu/push       | POST     | 同步菜单到微信              |
+--------------------------------+----------+----------------------------+
| /api/wechat/mp/qrcode          | POST     | 生成带参数二维码            |
+--------------------------------+----------+----------------------------+
| /api/wechat/mp/media/upload    | POST     | 上传临时素材                |
+--------------------------------+----------+----------------------------+
| wechat_payment                                         |
+--------------------------------+----------+----------------------------+
| /wechat/payment/notify/<mch_id>| GET/POST | 微信支付回调通知            |
+--------------------------------+----------+----------------------------+
| /wechat/payment/h5/<provider>  | GET      | H5支付跳转                  |
+--------------------------------+----------+----------------------------+
| wechat_login                                           |
+--------------------------------+----------+----------------------------+
| /wechat/login/auth             | GET      | 发起OAuth授权               |
+--------------------------------+----------+----------------------------+
| /wechat/login/callback         | GET      | OAuth回调处理               |
+--------------------------------+----------+----------------------------+
| /wechat/login/qr               | GET      | PC端显示扫码页面            |
+--------------------------------+----------+----------------------------+
| /wechat/login/qr/<state>        | GET      | 扫码后触发（微信内打开）     |
+--------------------------------+----------+----------------------------+
| /wechat/login/qr/confirm       | POST     | 确认登录                    |
+--------------------------------+----------+----------------------------+
| /wechat/login/qr/poll          | GET      | PC端轮询扫码状态            |
+--------------------------------+----------+----------------------------+
| /wechat/login/qr/image         | GET      | 二维码图片生成              |
+--------------------------------+----------+----------------------------+
| wechat_work                                             |
+--------------------------------+----------+----------------------------+
| /wechat/work/callback/<company> | GET/POST | 企业微信事件回调            |
+--------------------------------+----------+----------------------------+
| /api/wechat/work/message/send   | POST     | 发送应用消息                |
+--------------------------------+----------+----------------------------+
| /api/wechat/work/message/batch | POST     | 批量发送消息                |
+--------------------------------+----------+----------------------------+
| /api/wechat/work/users         | GET      | 获取成员列表                |
+--------------------------------+----------+----------------------------+
| /api/wechat/work/departments   | GET      | 获取部门列表                |
+--------------------------------+----------+----------------------------+
| /api/wechat/work/contacts/sync  | POST     | 触发通讯录同步              |
+--------------------------------+----------+----------------------------+
| /api/wechat/work/external_contact/<id> | GET | 获取外部联系人详情   |


微信后台配置指南
----------------

公众号（订阅号/服务号）
~~~~~~~~~~~~~~~~~~~~~~

1. 登录 mp.weixin.qq.com
2. 设置 → 基本配置 → 服务器配置：

   - URL: ``https://your-domain.com/wechat/webhook/<company_id>``
   - Token: 与 Odoo 公司表单中填写的 Token 一致
   - EncodingAESKey: 点击随机生成，填入 Odoo
   - 消息加解密方式: **安全模式（推荐）**

3. 获取 AppID 和 AppSecret：设置 → 基本配置 → 公众号设置

微信支付
~~~~~~~~

1. 登录 pay.weixin.qq.com
2. 获取商户号（mch_id）和 API 密钥
3. 配置支付回调 URL: ``https://your-domain.com/wechat/payment/notify/<mch_id>``
4. 将证书文件（apiclient_cert.pem / apiclient_key.pem）放到服务器

开放平台（扫码登录 / UnionID）
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. 登录 open.weixin.qq.com
2. 创建网站应用 → 获取 AppID 和 AppSecret
3. 配置授权回调域: ``your-domain.com``
4. 将公众号/小程序绑定到同一开放平台账号，可获取 UnionID 统一用户标识

企业微信
~~~~~~~~

1. 登录 work.weixin.qq.com
2. 应用管理 → 创建应用 → 获取 AgentID 和 Secret
3. 接收消息 → 设置应用回调 URL:

   - URL: ``https://your-domain.com/wechat/work/callback/<company_id>``
   - 配置 Token 和 EncodingAESKey

4. 通讯录 → 开启「API同步」→ 获取通讯录 Secret


安全注意事项
------------

- 生产环境必须使用 **HTTPS**
- AppSecret、AESKey 等密钥不要提交到代码仓库，使用环境变量或公司配置
- 微信支付 API 证书妥善保管，路径配置在 provider 表单中
- 建议配置防火墙，仅允许微信服务器 IP 访问回调接口
- 定期轮换 API 密钥（商户平台可更换 API 密钥）


Python 依赖
-----------

::

    wechatpy>=1.8      # 微信 API SDK
    qrcode            # 二维码生成
    pillow            # 图片处理
    cryptography      # 微信支付 v3 签名


Odoo 版本
---------

- 最低版本: Odoo 18.0
- Python: 3.8+


许可证
------

LGPL-3 - 详见各模块 LICENSE 文件