Metadata-Version: 2.1
Name: seven_cloudapp_frame
Version: 1.2.159
Summary: seven cloudapp frame
Home-page: http://gitlab.tdtech.gao7.com/TaoBaoCloud/seven_cloudapp_frame.git
Author: seven
Author-email: tech@gao7.com
License: MIT
Description: # seven_cloudapp_frame 框架说明
        
        > 本文档整合了 README.md、rule.md 和 config.md 的内容，提供完整的框架使用指南
        
        ---
        
        ## 目录
        
        - [1. 项目概述](#1-项目概述)
        - [2. 技术栈与依赖](#2-技术栈与依赖)
        - [3. 项目架构](#3-项目架构)
        - [4. 目录结构](#4-目录结构)
        - [5. 安装与初始化](#5-安装与初始化)
        - [6. 配置管理](#6-配置管理)
        - [7. Handler 处理器](#7-handler-处理器)
        - [8. 数据模型](#8-数据模型)
        - [9. 业务逻辑层](#9-业务逻辑层)
        - [10. 核心功能规范](#10-核心功能规范)
        - [11. 第三方接口](#11-第三方接口)
        - [12. 缓存系统](#12-缓存系统)
        - [13. 排队系统](#13-排队系统)
        - [14. ActionHelper 执行助手](#14-actionhelper-执行助手)
        - [15. 心跳监控](#15-心跳监控)
        - [16. 开发规范](#16-开发规范)
        - [17. 项目运行方式](#17-项目运行方式)
        - [18. 部署说明](#18-部署说明)
        
        ---
        
        ## 1. 项目概述
        
        天志互联 Python 云应用框架库，提供活动管理、任务系统、用户服务、订单支付、资产管理等电商营销类业务的基础能力框架。
        
        ### 1.1 主要功能
        
        | 功能模块 | 说明 |
        |---------|------|
        | **活动管理** | 活动创建、奖品配置、价格档位、模块管理、主题皮肤管理 |
        | **任务系统** | 任务配置、任务进度追踪、任务奖励发放 |
        | **用户服务** | 用户登录、用户管理、黑名单、收货地址 |
        | **订单支付** | 订单创建、支付回调、退款处理、物流同步 |
        | **资产管理** | 用户资产、资产管理、资产流水、资产预警 |
        | **统计报表** | 用户行为日志、活动数据报表 |
        | **内容管理** | CMS 内容配置、广告位管理、文章发布 |
        | **第三方对接** | 淘宝、微信、支付宝、抖音、抖店、京东 |
        
        ### 1.2 包信息
        
        | 属性 | 值 |
        |------|-----|
        | 包名 | `seven-cloudapp_frame` |
        | 版本 | `1.2.138` |
        | Python 要求 | `~=3.8` (即 >=3.8, <4.0) |
        
        ---
        
        ## 2. 技术栈与依赖
        
        ### 2.1 技术栈
        
        | 类别 | 技术 | 版本要求 |
        |------|------|----------|
        | 开发语言 | Python | ~=3.8 |
        | Web 框架 | Tornado | 内置支持 |
        | 关系型数据库 | MySQL | 5.7 / 8.0 |
        | 缓存 | Redis | 4.0+ |
        | 配置中心 | Nacos | 可选 |
        | 基础框架 | seven-framework | >=1.2.3 |
        | 淘宝 API | seven-top | >=1.0.28 |
        
        ### 2.2 核心依赖
        
        ```
        seven-framework>=1.2.3
        seven-top>=1.0.28
        asq==1.3
        emoji==1.6.1
        xmltodict==0.12.0
        requests==2.32.3
        mmh3==3.0.0
        bce-python-sdk==0.8.61
        ```
        
        ---
        
        ## 3. 项目架构
        
        ### 3.1 架构图
        
        ```
        ┌─────────────────────────────────────────────────────────────┐
        │                        客户端层                              │
        │         微信小程序 / H5 / 淘宝小程序 / 抖音 / Web             │
        └─────────────────────────────────────────────────────────────┘
                                      │
        ┌─────────────────────────────────────────────────────────────┐
        │                      Handler 层                              │
        │  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐   │
        │  │ client/      │  │ server/      │  │ filter_base.py  │   │
        │  │ C端接口      │  │ 管理端接口   │  │ 请求过滤        │   │
        │  └──────────────┘  └──────────────┘  └─────────────────┘   │
        └─────────────────────────────────────────────────────────────┘
                                      │
        ┌─────────────────────────────────────────────────────────────┐
        │                      业务逻辑层                              │
        │  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐   │
        │  │ *_base_model │  │ console_models│  │ seven_model.py  │   │
        │  │ 业务基类     │  │ 控制台模型   │  │ 基础实体        │   │
        │  └──────────────┘  └──────────────┘  └─────────────────┘   │
        └─────────────────────────────────────────────────────────────┘
                                      │
        ┌─────────────────────────────────────────────────────────────┐
        │                       数据访问层                             │
        │  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐   │
        │  │ db_models/   │  │ CacheModel   │  │ FrameDbModel    │   │
        │  │ 数据库模型   │  │ 缓存模型     │  │ 数据库基类      │   │
        │  └──────────────┘  └──────────────┘  └─────────────────┘   │
        └─────────────────────────────────────────────────────────────┘
                                      │
        ┌─────────────────────────────────────────────────────────────┐
        │                       基础设施层                             │
        │  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐   │
        │  │ MySQL        │  │ Redis        │  │ Nacos           │   │
        │  │ 主从支持     │  │ 缓存/队列    │  │ 配置中心        │   │
        │  └──────────────┘  └──────────────┘  └─────────────────┘   │
        └─────────────────────────────────────────────────────────────┘
        ```
        
        ---
        
        ## 4. 目录结构
        
        ```
        seven_cloudapp_frame/
        ├── handlers/                    # 请求处理层
        │   ├── client/                  # C端接口（用户端）
        │   │   ├── act.py               # 活动相关接口
        │   │   ├── app.py               # 应用相关接口
        │   │   ├── goods.py             # 商品相关接口
        │   │   ├── order.py             # 订单相关接口
        │   │   ├── pay.py               # 支付相关接口
        │   │   ├── stat.py              # 统计相关接口
        │   │   ├── task.py              # 任务相关接口
        │   │   ├── theme.py             # 主题皮肤接口
        │   │   └── user.py              # 用户相关接口
        │   ├── server/                  # 管理端接口（B端）
        │   │   ├── act_s.py             # 活动管理
        │   │   ├── app_s.py             # 应用管理
        │   │   ├── goods_s.py           # 商品管理
        │   │   ├── order_s.py           # 订单管理
        │   │   ├── prize_s.py           # 奖品管理
        │   │   ├── task_s.py            # 任务管理
        │   │   └── user_s.py            # 用户管理
        │   ├── core.py                  # 核心路由注册
        │   ├── filter_base.py           # 请求过滤器基类
        │   └── frame_base.py            # Handler基类
        ├── libs/                        # 工具库
        │   ├── common/                  # 通用组件
        │   │   ├── frame_console.py     # 控制台框架
        │   │   ├── frame_db.py          # 数据库操作封装
        │   │   ├── frame_helper.py      # 框架辅助工具
        │   │   ├── frame_tornado.py     # Tornado框架封装
        │   │   └── share_config.py      # 全局配置管理
        │   └── customize/               # 自定义工具类
        │       ├── alipay_helper.py     # 支付宝工具
        │       ├── content_censor_helper.py # 内容审核
        │       ├── cryptography_helper.py # 加密解密
        │       ├── email_helper.py      # 邮件工具
        │       ├── excel_helper.py      # Excel处理
        │       ├── file_helper.py       # 文件处理
        │       ├── queue_up_helper.py   # 排队系统
        │       ├── redis_helper.py      # Redis工具
        │       ├── safe_helper.py       # 安全工具
        │       ├── seven_helper.py      # 七维通用工具
        │       ├── sms_helper.py        # 短信工具
        │       ├── tiktok_helper.py     # 抖音工具
        │       ├── wechat_helper.py     # 微信工具
        │       └── locales/             # 国际化
        │           ├── translation_helper.py # 翻译工具
        │           └── zh_EN.json       # 英文翻译文件
        ├── models/                      # 数据模型层
        │   ├── db_models/               # 数据库表模型
        │   │   ├── act/                 # 活动相关表
        │   │   ├── asset/               # 资产相关表
        │   │   ├── cms/                 # CMS内容表
        │   │   ├── pay/                 # 支付相关表
        │   │   ├── prize/               # 奖品订单表
        │   │   ├── stat/                # 统计报表表
        │   │   ├── task/                # 任务相关表
        │   │   └── user/                # 用户相关表
        │   ├── console_models/          # 控制台业务模型
        │   │   ├── asset_console_model.py   # 资产控制台
        │   │   ├── erp_console_model.py     # ERP控制台
        │   │   ├── stat_console_model.py    # 统计控制台
        │   │   ├── task_console_model.py    # 任务控制台
        │   │   └── timing_work_model.py     # 定时作业
        │   ├── cache_model.py           # 缓存模型基类
        │   ├── enum.py                  # 枚举定义
        │   ├── frame_base_model.py      # 框架业务基类
        │   └── *_base_model.py          # 各业务基类
        ├── locales/                     # 国际化翻译文件
        └── route.py                     # 路由注册
        ```
        
        ---
        
        ## 5. 安装与初始化
        
        ### 5.1 安装
        
        ```bash
        pip install seven-cloudapp_frame
        ```
        
        或本地安装：
        
        ```bash
        git clone http://gitlab.tdtech.gao7.com/TaoBaoCloud/seven_cloudapp_frame.git
        cd seven_cloudapp_frame
        pip install -e .
        ```
        
        ### 5.2 Handler初始化必须导入
        
        ```python
        from seven_cloudapp_frame.libs.common.frame_tornado import *
        from seven_framework.web_tornado.monitor import MonitorHandler
        ```
        
        ### 5.3 路由注册（自动）
        
        ```python
        from seven_cloudapp_frame.route import seven_cloudapp_frame_route
        
        handlers = []
        handlers.extend(seven_cloudapp_frame_route())
        ```
        
        ### 5.4 作业服务初始化
        
        ```python
        from seven_cloudapp_frame.libs.common.frame_console import *
        ```
        
        ---
        
        ## 6. 配置管理
        
        ### 6.1 配置系统概述
        
        框架使用两套配置系统：
        1. **框架基础配置** (`seven_framework.config`) - 通过 `config.get_value()` 读取
        2. **项目共享配置** (`share_config`) - 通过 `share_config.get_value()` 读取
        
        **配置读取优先级**：
        `share_config.get_value()` 内部会先调用 `config.get_value()`，如果 `config` 中没有该配置项，才会从 `share_config` 中读取。建议统一使用 `share_config.get_value()` 来读取配置。
        
        ### 6.2 配置加载方式
        
        #### 本地配置文件
        
        ```python
        from seven_cloudapp_frame.libs.common.share_config import init_config
        init_config("config_dev.json")
        ```
        
        #### Nacos配置中心
        
        ```python
        from seven_cloudapp_frame.libs.common.share_config import init_config_from_nacos
        init_config_from_nacos(config_file, config_content)
        ```
        
        ### 6.3 基础应用配置
        
        | 配置Key | 类型 | 默认值 | 说明 |
        |---------|------|--------|------|
        | `app_id` | string | - | 应用标识，小程序唯一ID |
        | `app_key` | string | - | 应用Key（淘宝/京东平台） |
        | `app_secret` | string | - | 应用密钥 |
        | `project_name` | string | "" | 项目名称，用于Redis key隔离 |
        | `plat_type` | int | 1 | 平台类型：1-淘宝 2-微信 3-京东 4-Web |
        | `client_template_id` | string/list | - | 客户端模板ID |
        | `is_app_relation` | bool | False | 是否开启应用关联（仅对淘宝平台生效） |
        | `is_saas` | bool | False | 是否SaaS模式，主要用于微信小程序 |
        
        ### 6.4 加密安全配置
        
        | 配置Key | 类型 | 默认值 | 说明 |
        |---------|------|--------|------|
        | `encrypt_key` | string | "r8C1JpyAXxrFV26V" | AES加密密钥 |
        | `client_encrypt_type` | int | 0 | 客户端加密类型：0-无 1-AES |
        | `server_encrypt_type` | int | 0 | 服务端加密类型：0-无 1-AES |
        | `encrypt_limit_time` | int | 10 | 加密请求超时时间（秒） |
        
        > **重要**：正式环境必须设置 `client_encrypt_type=1` 开启加密
        
        ### 6.5 安全控制配置 (safe_config)
        
        | 子配置Key | 类型 | 默认值 | 说明 |
        |-----------|------|--------|------|
        | `is_check_referer` | bool | False | 是否检查Referer(用于微信小程序) |
        | `is_current_control` | bool | False | 是否开启流量控制 |
        | `current_limit_count` | int | 100000 | 每分钟请求限制次数（全局） |
        | `current_limit_user_count` | int | 500 | 用户每分钟请求限制次数 |
        | `flow_limit_api_count` | int | 1000 | API流量每秒限制次数 |
        | `is_authenticat_app_id` | bool | True | 是否校验app_id一致性 |
        | `sensitive_encrypt_key` | string | - | 敏感数据加密密钥 |
        
        ### 6.6 数据库配置
        
        #### 基础数据库配置
        
        | 配置Key | 类型 | 说明 |
        |---------|------|------|
        | `db_cloudapp` | dict | 主数据库配置 |
        | `sub_table_config` | dict | 分表配置 |
        
        #### 业务模块数据库配置
        
        | 配置Key | 说明 | 使用模块 |
        |---------|------|----------|
        | `db_asset` / `redis_asset` | 资产数据库/Redis | asset_log_model等 |
        | `db_order` / `redis_order` | 订单数据库/Redis | prize_order_model等 |
        | `db_task` / `redis_task` | 任务数据库/Redis | task_info_model等 |
        | `db_stat` / `redis_stat` | 统计数据库/Redis | stat_log_model等 |
        | `db_user` / `redis_user` | 用户数据库/Redis | user_info_model等 |
        | `db_cms` / `redis_cms` | CMS数据库/Redis | cms_info_model等 |
        
        **配置示例**：
        
        ```json
        {
            "db_asset": {
                "host": "127.0.0.1",
                "port": 3306,
                "user": "root",
                "password": "password",
                "db": "cloudapp_asset",
                "charset": "utf8mb4"
            },
            "redis_asset": {
                "host": "127.0.0.1",
                "port": 6379,
                "password": "",
                "db": 3,
                "is_cluster": false
            }
        }
        ```
        
        ### 6.7 Redis配置
        
        | 配置Key | 类型 | 说明 |
        |---------|------|------|
        | `redis` | dict | 基础Redis配置 |
        | `redis_safe` | dict | 安全控制Redis配置 |
        | `redis_queueup` | dict | 排队系统Redis配置 |
        | `redis_cache` | dict | 缓存专用Redis配置 |
        | `platform_redis` | dict | 中台Redis配置 |
        
        ### 6.8 缓存配置
        
        | 配置Key | 类型 | 默认值 | 说明 |
        |---------|------|--------|------|
        | `is_redis_cache` | bool | True | 是否启用Redis缓存 |
        | `cache_limit_size` | int | 512 | 缓存值大小限制（KB） |
        | `log_redis_cache` | bool | True | 是否记录Redis缓存日志 |
        | `dependency_cache_expire` | int | 86400 | 依赖键缓存过期时间（秒） |
        | `is_cache_empty` | bool | False | 是否缓存空值 |
        | `cache_expire` | int | 0 | 全局缓存过期时间（秒） |
        
        ### 6.9 支付配置
        
        #### 微信支付配置 (wechat_pay)
        
        | 配置Key | 说明 |
        |---------|------|
        | `app_id` | 微信小程序AppID |
        | `mch_id` | 商户号 |
        | `api_key` | API密钥 |
        | `serial_no` | 证书序列号 |
        | `certificate_url` | 证书URL |
        | `private_key_url` | 私钥URL |
        | `pay_notify_url` | 支付回调URL |
        | `public_key_id` | 公钥ID(v3支付) |
        | `public_key_url` | 公钥URL/秘钥(v3支付) |
        
        #### 抖音支付配置 (tiktok_pay)
        
        | 配置Key | 说明 |
        |---------|------|
        | `app_id` | 抖音小程序AppID |
        | `merchant_id` | 商户号 |
        | `salt` | 加密盐值 |
        | `token` | 接口调用token |
        | `pay_notify_url` | 支付回调URL |
        
        ### 6.10 其他配置
        
        #### 对象存储配置
        
        | 配置Key | 说明 |
        |---------|------|
        | `oss_config` | 阿里云OSS配置 |
        | `cos_config` | 腾讯云COS配置 |
        | `bos_config` | 百度云BOS配置 |
        
        #### 内容审核配置
        
        | 配置Key | 说明 |
        |---------|------|
        | `censor_bos_config` | 百度云内容审核配置 |
        | `censor_cos_config` | 腾讯云内容审核配置 |
        
        #### 排队系统配置
        
        | 配置Key | 类型 | 默认值 | 说明 |
        |---------|------|--------|------|
        | `queue_is_log` | bool | False | 是否记录排队日志 |
        | `queue_confirm_time` | int | 8 | 排队确认时间（秒） |
        | `queue_operate_time` | int | 300 | 排队操作时间（秒） |
        | `queue_up_query_gear` | list | - | 排队查询档位配置 |
        
        #### 国际化翻译配置 (translate_config)
        
        | 配置Key | 类型 | 默认值 | 说明 |
        |---------|------|--------|------|
        | `locales_dir` | string | - | 翻译文件目录路径 |
        | `default_locale` | string | zh_CN | 默认语言环境 |
        
        #### 用户系统配置 (user_config)
        
        | 子配置Key | 类型 | 默认值 | 说明 |
        |-----------|------|--------|------|
        | `user_system_ver` | int | 1 | 用户系统版本：1-基础版 2-增强版，性能更高，用于高并发项目 |
        
        #### HTTP响应配置 (reponse_config)
        
        | 子配置Key | 类型 | 默认值 | 说明 |
        |-----------|------|--------|------|
        | `return_log_id` | bool | false | 请求标识，便于排查问题，联调的时候前端告知，直接在日志系统通过log_id查询，测试环境默认开启，生产环境默认关闭。 |
        
        #### 日志与调试配置
        
        | 配置Key | 类型 | 默认值 | 说明 |
        |---------|------|--------|------|
        | `log_plain` | bool | True | 是否记录明文日志 |
        | `default_error_message` | string | "系统异常" | 默认错误提示 |
        | `allow_origin_list` | list | - | 允许跨域来源列表，用于后台项目调用 | 
        
        ### 6.11 完整配置文件示例
        
        ```json
        {
            "project_name": "my_cloudapp",
            "app_id": "wx1234567890abcdef",
            "app_secret": "your_app_secret",
            "plat_type": 2,
            
            "safe_config": {
                "is_current_control": true,
                "current_limit_count": 100000,
                "is_authenticat_app_id": true,
                "sensitive_encrypt_key": "your_key"
            },
            
            "redis": {
                "host": "127.0.0.1",
                "port": 6379,
                "password": "",
                "db": 0
            },
            
            "db_cloudapp": {
                "host": "127.0.0.1",
                "port": 3306,
                "user": "root",
                "password": "password",
                "db": "cloudapp",
                "charset": "utf8mb4"
            },
            
            "wechat_pay": {
                "app_id": "wx1234567890abcdef",
                "mch_id": "1234567890",
                "api_key": "your_api_key",
                "pay_notify_url": "https://your-domain.com/pay/notify"
            },
            
            "client_encrypt_type": 1,
            "log_plain": true
        }
        ```
        
        ---
        
        ## 7. Handler 处理器
        
        ### 7.1 Handler 继承体系
        
        ```
        BaseApiHandler (seven-framework)
            │
            └── FrameBaseApiHandler (frame_base.py)
                    │
                    ├── ClientBaseHandler (client/*.py)
                    │       └── 用户端接口Handler（大部分接口）
                    │
                    └── FrameBaseHandler (frame_base.py)
                            └── 无需加密/第三方调用接口
        ```
        
        ### 7.2 核心 Handler 基类
        
        #### ClientBaseHandler
        
        - **功能**: C端接口基类，server/ 目录下接口也继承此类
        - **特性**: 
          - 自动获取 app_id、act_id、user_id
          - 支持用户登录态校验
          - 支持接口签名验证
        
        #### FrameBaseHandler
        
        - **功能**: 无需加密或给第三方调用的接口基类
        - **特性**:
          - 不自动获取用户信息
          - 不强制签名验证
          - 适用于开放接口或回调接口
        
        ### 7.3 路由命名规范
        
        | 接口类型 | URL 前缀 | 示例 |
        |----------|----------|------|
        | 小程序端 (C端) | `/client/` | `/client/login` |
        | 后台管理 (B端) | `/server/` | `/server/user_list` |
        
        ### 7.4 过滤器 (Filter)
        
        #### filter_base.py
        
        提供请求过滤装饰器：
        
        ```python
        @filter_check_sign(sign_key="your_key", expired_seconds=300)
        def post_async(self):
            # 自动验证请求签名
            pass
        ```
        
        | 装饰器 | 功能 |
        |--------|------|
        | filter_check_sign | HTTP请求签名验证 |
        
        ---
        
        ## 8. 数据模型
        
        ### 8.1 模型继承体系
        
        ```
        FrameDbModel (seven-framework)
            │
            └── CacheModel (cache_model.py)
                    │
                    ├── ActInfoModel (db_models/act/*.py)
                    ├── UserInfoModel (db_models/user/*.py)
                    ├── PrizeOrderModel (db_models/prize/*.py)
                    └── ...
        ```
        
        ### 8.2 CacheModel 缓存模型
        
        - **功能**: MySQL数据自动同步到Redis缓存
        - **特性**:
          - 查询结果自动缓存
          - 更新操作自动清除缓存
          - 支持依赖缓存（dependency_cache）
          - 支持空值缓存（is_cache_empty）
        
        ### 8.3 业务基类模型
        
        | 基类 | 文件 | 功能 |
        |------|------|------|
        | FrameBaseModel | frame_base_model.py | 框架通用业务逻辑 |
        | ActBaseModel | act_base_model.py | 活动业务逻辑 |
        | UserBaseModel | user_base_model.py | 用户业务逻辑 |
        | OrderBaseModel | order_base_model.py | 订单业务逻辑 |
        | PrizeBaseModel | prize_base_model.py | 奖品业务逻辑 |
        | TaskBaseModel | task_base_model.py | 任务业务逻辑 |
        | AssetBaseModel | asset_base_model.py | 资产业务逻辑 |
        
        ### 8.4 分表支持
        
        以下表支持分表模式：
        
        - `stat_log_tb` - 统计日志
        - `stat_report_tb` - 统计报表
        - `asset_log_tb` - 资产流水
        - `user_asset_tb` - 用户资产
        - `task_count_tb` - 任务计数
        - `user_info_tb` - 用户信息
        - `prize_order_tb` - 奖品订单
        - `prize_roster_tb` - 中奖名单
        
        **使用方式**：
        
        ```python
        prize_order_model = PrizeOrderModel().set_sub_table(app_id)
        ```
        
        ### 8.5 常用查询方法
        
        ```python
        # 查询单条（带缓存）
        model.get_cache_entity(where="id=%s", params=[1])
        model.get_cache_entity_by_id(primary_key_id=1)
        
        # 查询列表（带缓存）
        model.get_cache_list(where="status=%s", params=[1])
        
        # 分页查询（带缓存）
        model.get_cache_page_list(
            field="*", 
            page_index=0, 
            page_size=20,
            page_count_mode='next'  # C端必须用next模式
        )
        
        # 查询数量（带缓存）
        model.get_cache_total(where="status=%s", params=[1])
        ```
        
        **分页模式**：
        - C端接口：`page_count_mode='next'`（游标分页）
        - B端接口：可使用 `page_count_mode='total'`（总数分页）
        
        ### 8.6 数据库查询优化
        
        #### 参数类型一致（重要）
        
        - 参数的数据类型必须和数据库一致
        - 数据库字段为整数，查询参数必须加 `int()`
        - 数据库字段为字符串，查询参数必须加 `str()`
        - 否则容易导致索引失效
        
        #### 索引使用规范
        
        - 避免在索引字段上使用函数（如 `DATE(create_date)`）
        - 避免前导模糊查询（如 `LIKE '%keyword'`）
        - IN 子句元素数量不宜过多（建议不超过50个）
        
        ### 8.7 读写分离
        
        **使用场景**：数据及时性要求不高的场景，如后台查询、导出类接口
        
        **使用方法**：
        
        ```python
        # is_auto = True 开启读库
        read_model = MyModel(is_auto=True)
        ```
        
        **连接串配置**：
        
        ```json
        {
            "db": "数据库名",
            "host": "主库ip地址",
            "port": "端口",
            "user": "账号",
            "passwd": "密码",
            "charset": "utf8",
            "auto_host": "读库或自动读写代理ip地址"
        }
        ```
        
        ---
        
        ## 9. 业务逻辑层
        
        ### 9.1 控制台模型 (Console Models)
        
        控制台模型用于处理定时任务和后台业务逻辑：
        
        | 模型 | 文件 | 功能 |
        |------|------|------|
        | ErpConsoleModel | erp_console_model.py | ERP订单推送与物流拉取 |
        | TaskConsoleModel | task_console_model.py | 任务定时处理 |
        | AssetConsoleModel | asset_console_model.py | 资产定时发放 |
        | StatConsoleModel | stat_console_model.py | 统计数据汇总 |
        | LaunchConsoleModel | launch_console_model.py | 投放计划执行 |
        | TokenConsoleModel | token_console_model.py | Token刷新管理 |
        | TimingWork | timing_work_model.py | 定时作业基类 |
        
        ### 9.2 ERP 控制台示例
        
        ```python
        class ErpConsoleModel:
            def console_erp(self, mod_count=1, process_type=1, 
                            pull_time_range="", push_time_range=""):
                """
                启动订单推送和物流拉取任务
                :param mod_count: 队列数（分片数）
                :param process_type: 1-Redis模式 2-API模式
                :param pull_time_range: 拉取时间段，如 "09:00-22:00"
                :param push_time_range: 推送时间段，如 "09:00-22:00"
                """
        ```
        
        ### 9.3 定时作业基类
        
        ```python
        class TimingWork:
            """定时作业基类"""
            def execute(self):
                """执行业务逻辑，子类重写此方法"""
                pass
        ```
        
        ---
        
        ## 10. 核心功能规范
        
        ### 10.1 代码规范
        
        - 使用 UTF-8 编码
        - 遵循 PEP 8 代码风格
        - 类名使用驼峰命名法（PascalCase）
        - 方法名和变量名使用小写下划线命名法（snake_case）
        - 常量使用全大写下划线命名法（UPPER_SNAKE_CASE）
        
        ### 10.2 注释规范
        
        ```python
        def method_name(self, param1, param2):
            """
            :description: 方法描述
            :param param1: 参数1说明
            :param param2: 参数2说明
            :return: 返回值说明
            :last_editors: 最后编辑人
            """
            pass
        ```
        
        ### 10.3 请求参数规范
        
        #### Post请求规范
        
        - Content-Type 必须为 `application/json`
        - 参数需序列化为 JSON 字符串
        
        #### 参数校验装饰器
        
        ```python
        @filter_check_params("参数名1,参数名2,参数名3")
        def post_async(self):
            pass
        ```
        
        #### 列表查询条数限制
        
        ```python
        page_size = self.get_param_int(
            "page_size", 
            default=20, 
            range_list=[1,200],  # 必须在1-200之间
            is_positive=True
        )
        ```
        
        #### 参数获取方法
        
        **字符串参数**：
        ```python
        param = self.get_param(
            param_name='param_1',
            default='',
            strip=True,
            max_length=100
        )
        ```
        
        **整数参数**：
        ```python
        param = self.get_param_int(
            param_name='param_1',
            default=0,
            contain_list=[1,2,3],
            range_list=[1,10],
            is_positive=True
        )
        ```
        
        **金额参数（Decimal）**：
        ```python
        param = self.get_param_decimal('param_1', default=0)
        ```
        
        **日期时间参数**：
        ```python
        param = self.get_param_datetime(
            'param_1',
            fmt='%Y-%m-%d %H:%M:%S'
        )
        ```
        
        ### 10.4 数据安全规范
        
        #### 接口加解密架构
        
        ```
        客户端请求                                    服务端处理
            │                                              │
            ▼                                              ▼
        ┌──────────┐                               ┌──────────────┐
        │ 明文数据  │                               │ 接收加密数据  │
        └────┬─────┘                               └──────┬───────┘
             │                                            │
             ▼                                            ▼
        ┌──────────┐                               ┌──────────────┐
        │ AES加密   │─────── 网络传输(加密数据) ─────▶│ AES解密       │
        │ (CBC模式)│                               │ (CBC模式)     │
        └────┬─────┘                               └──────┬───────┘
             │                                            │
             ▼                                            ▼
        ┌──────────┐                               ┌──────────────┐
        │ Base64   │                               │ 明文数据      │
        │ 编码     │                               │ (业务处理)    │
        └──────────┘                               └──────┬───────┘
                                                          │
                                                          ▼
                                                   ┌──────────────┐
                                                   │ 响应数据加密  │
                                                   │ AES+Base64   │
                                                   └──────┬───────┘
                                                          │
                                                          ▼
                                                   ┌──────────────┐
                                                   │ 返回加密响应  │
                                                   └──────────────┘
        ```
        
        #### 加密规范
        
        - **加密方式**: AES-128-CBC、无填充、UTF-8、输出 Base64
        - **正式环境**: 必须开启加密模式，`client_encrypt_type`为客户端加密类型 0-无，1-aes加密
        - **敏感字段**: 必须使用框架提供的加密功能，使用 `FrameBaseModel` 的 `sensitive_encrypt` 和 `sensitive_decrypt` 方法
        
        #### 加密流程说明
        
        1. **请求加密**: 客户端使用 AES-128-CBC 算法加密请求数据，输出 Base64 格式
        2. **数据传输**: 网络传输的是加密后的 Base64 字符串，确保数据安全
        3. **服务端解密**: 服务端接收到数据后，使用相同密钥进行 AES 解密
        4. **业务处理**: 服务端处理明文数据
        5. **响应加密**: 服务端将响应数据加密后返回给客户端
        6. **客户端解密**: 客户端解密响应数据，获取明文结果
        
        #### 敏感字段加密示例
        
        ```python
        # 加密
        encrypted = model.sensitive_encrypt("敏感数据")
        # 解密
        decrypted = model.sensitive_decrypt(encrypted)
        ```
        
        ### 10.5 限流规范
        
        #### 限流配置
        
        ```json
        {
            "safe_config": {
                "is_current_control": true,
                "current_limit_count": 100000,
                "flow_limit_api_count": 1000,
                "current_limit_user_count": 500
            }
        }
        ```
        
        #### Handler装饰器使用
        
        ```python
        @filter_check_current_limit()  # 应用级限流
        @filter_check_flow_limit()     # 接口级限流
        def post_async(self):
            pass
        ```
        
        ### 10.6 用户系统规范
        
        #### 核心概念
        
        - `user_id` 与 `open_id` 一一对应，跨活动不变
        - `user_id` 对应 `user_account_tb` 表的主键 `id`
        
        #### 必须使用框架提供的Handler
        
        - `LoginHandler` - 用户登录
        - `UpdateUserInfoHandler` - 更新用户信息
        
        #### 高并发登录配置（V2）
        
        ```python
        {"user_config": {"user_system_ver": 2}}
        ```
        
        ### 10.7 资产系统规范
        
        #### 资产核心特性
        
        - 每条数据都有资产检验码
        - 正式环境禁止直接修改数据库
        - 测试环境可配置 `is_check_asset` 关闭校验
        
        #### 资产更新示例
        
        ```python
        from seven_cloudapp_frame.models.asset_base_model import *
        
        asset_base_model = AssetBaseModel(context=self)
        invoke_result_data = asset_base_model.update_user_asset(
            app_id=app_id,
            user_id=user_id,
            asset_type=int(asset_object["asset_type"]),
            asset_value=int(asset_object["asset_value"]),
            source_type=3,
            log_title="手动配置",
            handler_name=self.__class__.__name__,
            request_code=self.request_code,
        )
        if invoke_result_data.success == False:
            return self.response_json_error(
                invoke_result_data.error_code, 
                invoke_result_data.error_message
            )
        ```
        
        ### 10.8 任务系统规范
        
        - **必须使用**: `get_client_task_list_v2` 接口（新标准）
        - 支持自动领取和手动领取两种模式
        
        ### 10.9 核心功能 - 业务执行事件
        
        #### business_process_executing 功能
        
        - 自动校验活动信息、模块信息、用户信息
        - 支持同一用户连续请求限制
        - 支持流量削峰
        - 支持分布式锁
        
        #### 使用场景
        
        抽奖、兑换、领取奖励等核心操作，安全系数要求高的场景
        
        #### 代码示例
        
        ```python
        try:
            frame_base_model = FrameBaseModel(context=self)
            invoke_result_data = frame_base_model.business_process_executing(
                self, app_id, act_id, module_id, user_id,
                login_token, self.__class__.__name__,
                request_code=self.request_code,
                check_new_user=False,
                check_user_nick=True,
                acquire_lock_name="",
                request_limit_num=0,
                execute_lock_expire=90
            )
            if invoke_result_data.success == False:
                return invoke_result_data
            
            # 执行业务逻辑...
        finally:
            frame_base_model.business_process_executed()
        ```
        
        ### 10.10 作业规范
        
        #### 必须导入
        
        ```python
        from seven_cloudapp_frame.libs.common.frame_console import *
        ```
        
        #### 核心作业必须使用心跳检测
        
        ```python
        heart_beat_monitor("具体作业名")
        threading.Thread(target=heart_beat_check).start()
        ```
        
        #### 代码必须包裹try except
        
        ```python
        try:
            time.sleep(0.1)  # 必须至少0.1秒休眠
            # 作业代码
        except Exception as e:
            print(f"作业异常: {e}")
            # 发送报警通知、记录日志
        ```
        
        ### 10.11 条件拼接
        
        ```python
        from seven_cloudapp_frame.models.seven_model import ConditionWhere
        
        # 查询条件
        condition_where_query = ConditionWhere()
        condition_where_query.add_condition("status", 1)
        condition_where_query.add_condition_in("id", true, [1, 2, 3])
        act_info_model.get_dict(
            condition_where_query.to_string(), 
            params=condition_where_query.params
        )
        
        # 更新条件
        condition_where_update = ConditionWhere()
        condition_where_update.add_condition("status", 1)
        condition_where_update.add_condition("modify_time", SevenHelper.get_now_datetime())
        act_info_model.update_table(
            condition_where_update.to_string(','), 
            where='id=%s', 
            params=[1]
        )
        ```
        
        ---
        
        ## 11. 第三方接口
        
        ### 11.1 原则
        
        尽量使用封装好的类，避免直接调用三方接口
        
        ### 11.2 淘宝/天猫接口
        
        ```python
        from seven_cloudapp_frame.models.top_base_model import TopBaseModel
        
        class MyTopModel(TopBaseModel):
            pass
        ```
        
        ### 11.3 抖店接口
        
        ```python
        from seven_cloudapp_frame.models.third.shakeshop_base_model import ShakeShopBaseModel
        
        class MyShakeModel(ShakeShopBaseModel):
            pass
        ```
        
        ### 11.4 京东接口
        
        ```python
        from seven_cloudapp_frame.models.third.jd_base_model import JdBaseModel
        
        class MyJdModel(JdBaseModel):
            pass
        ```
        
        ### 11.5 微信小程序接口
        
        ```python
        from seven_cloudapp_frame.libs.customize.wechat_helper import WeChatHelper
        
        WeChatHelper.get_web_authorize_url(redirect_uri)
        WeChatHelper.decrypt_data(encrypted_data, session_key, iv)
        WeChatHelper.get_qrcode(access_token, scene, page)
        ```
        
        ### 11.6 微信支付接口
        
        ```python
        from seven_cloudapp_frame.libs.customize.wechat_helper import WeChatPayV3Request
        
        pay_request = WeChatPayV3Request(app_id, mchid, private_key, serial_no)
        pay_request.create_order(body, out_trade_no, total_fee, notify_url, openid)
        ```
        
        ### 11.7 抖音支付接口
        
        ```python
        from seven_cloudapp_frame.libs.customize.tiktok_helper import TikTokPayRequest
        
        pay_request = TikTokPayRequest(app_id, salt, token)
        pay_request.create_order(out_order_no, total_amount, subject, body, notify_url)
        ```
        
        ### 11.8 支付宝接口
        
        ```python
        from seven_cloudapp_frame.libs.customize.alipay_helper import AliPayRequest
        
        pay_request = AliPayRequest(app_id, private_key, public_key)
        pay_request.create_order(out_trade_no, total_amount, subject, notify_url)
        ```
        
        ### 11.9 文件存储
        
        #### 阿里云 OSS
        
        ```python
        from seven_cloudapp_frame.libs.customize.file_helper import OSSHelper
        
        oss = OSSHelper(access_key, secret_key, bucket, endpoint)
        oss.upload_file(file_path, object_name)
        ```
        
        #### 腾讯云 COS
        
        ```python
        from seven_cloudapp_frame.libs.customize.file_helper import COSHelper
        
        cos = COSHelper(secret_id, secret_key, region, bucket)
        cos.upload_file(file_path, object_name)
        ```
        
        #### 百度云 BOS
        
        ```python
        from seven_cloudapp_frame.libs.customize.file_helper import BOSHelper
        
        bos = BOSHelper(access_key, secret_key, endpoint, bucket)
        bos.upload_file(file_path, object_name)
        ```
        
        ### 11.10 短信服务
        
        | 厂商 | 类名 |
        |------|------|
        | 百度智能云 | `BceSmsHelper` |
        | 阿里云 | `AliSmsHelper` |
        | 腾讯云 | `TencentSmsHelper` |
        
        ```python
        from seven_cloudapp_frame.libs.customize.sms_helper import AliSmsHelper
        
        sms = AliSmsHelper(access_key, secret_key, sign_name)
        sms.send_sms(phone, template_code, params)
        ```
        
        ### 11.11 内容审核
        
        | 厂商 | 类名 |
        |------|------|
        | 百度云 | `BOSCensorHelper` |
        | 腾讯云 | `COSCensorHelper` |
        
        ```python
        censor = BOSCensorHelper(access_key, secret_key)
        result = censor.image_censor(img_list=["url1", "url2"])
        result = censor.text_censor(text="待审核文本")
        ```
        
        ---
        
        ## 12. 缓存系统
        
        ### 12.1 缓存架构
        
        ```
        业务查询
            │
            ▼
        ┌─────────────┐
        │  查询Redis  │────命中────► 直接返回
        └─────────────┘
            │ 未命中
            ▼
        ┌─────────────┐
        │  查询MySQL  │
        └─────────────┘
            │
            ▼
        ┌─────────────┐
        │  写入Redis  │
        └─────────────┘
            │
            ▼
          返回结果
        ```
        
        ### 12.2 缓存前缀
        
        前缀：`data_cache`
        
        ### 12.3 缓存键结构
        
        ```
        # 依赖键
        data_cache[:cache_sub_table]:dependency_[dependency_key]
        
        # 缓存键
        data_cache[:cache_sub_table]:[md5(dependency_key+cache_key)]
        ```
        
        ### 12.4 缓存值结构
        
        ```json
        {
          "dep_ver": "依赖键版本号",
          "data": "缓存数据",
          "savetime": "保存时间"
        }
        ```
        
        ### 12.5 缓存使用建议
        
        - 批量删除依赖键，减少 Redis 请求
        - 数据大的表禁止用默认依赖键
        - 大表自定义依赖键提高缓存使用率
        - 数据及时性要求不高的场景使用缓存
        
        ### 12.6 缓存清理方法
        
        ```python
        # 删除缓存依赖键
        model.delete_dependency_key(dependency_key="my_key")
        
        # 批量删除缓存依赖键
        model.delete_dependency_keys(dependency_keys=["key1", "key2"])
        
        # 根据前缀删除
        model.delete_dependency_keys_by_pattern(pattern="my_pattern")
        ```
        
        ### 12.7 注意事项
        
        - 依赖键缓存时间默认24小时，普通缓存默认30分钟
        - 查询结果是None和0不会被缓存，除非配置文件设置`is_cache_empty=True`
        - 支持Redis集群模式
        - 支持缓存预热，批量将数据预加载到缓存
        - 缓存键使用MD5加密，确保唯一性
        - 支持延迟删除和重试机制，提高缓存操作的可靠性
        
        ---
        
        ## 13. 排队系统
        
        ### 13.1 排队系统架构
        
        ```
        用户请求加入排队
                │
                ▼
        ┌───────────────┐
        │  检查队列状态  │
        └───────────────┘
                │
           ┌────┴────┐
           ▼         ▼
        ┌──────┐  ┌──────┐
        │可加入 │  │已满  │
        └──┬───┘  └──┬───┘
           │         │
           ▼         ▼
        ┌──────┐  ┌──────┐
        │加入队列│  │返回排队│
        │       │  │人数过多│
        └──┬───┘  └──────┘
           │
           ▼
        ┌───────────────┐
        │  等待排队排到  │
        └───────────────┘
                │
                ▼
        ┌───────────────┐
        │  执行业务操作  │
        └───────────────┘
                │
           ┌────┴────┐
           ▼         ▼
        ┌──────┐  ┌──────┐
        │完成  │  │退出  │
        └──────┘  └──────┘
        ```
        
        ### 13.2 核心功能
        
        - **加入排队**: 用户加入指定队列等待
        - **排队查询**: 查询当前排队位置和预计等待时间
        - **排队排到**: 当轮到用户时，通知用户进行业务操作
        - **退出排队**: 用户主动退出或超时自动退出
        - **批量管理**: 支持批量查询、批量踢出过期用户
        
        ### 13.3 配置说明
        
        | 配置Key | 类型 | 默认值 | 说明 |
        |---------|------|--------|------|
        | `queue_is_log` | bool | False | 是否记录排队日志 |
        | `queue_confirm_time` | int | 8 | 排队确认时间（秒） |
        | `queue_operate_time` | int | 300 | 排队操作时间（秒） |
        | `queue_operate_total_time` | int | 0 | 排队总操作时间 |
        | `queue_up_query_gear` | list | - | 排队查询档位配置 |
        
        **queue_up_query_gear 配置示例**:
        
        ```json
        {
          "queue_up_query_gear": [
            {"start": 1, "end": 3, "rate": 2},
            {"start": 3, "end": 6, "rate": 3},
            {"start": 7, "end": 100, "rate": 5}
          ]
        }
        ```
        
        ### 13.4 使用示例
        
        ```python
        from seven_cloudapp_frame.libs.customize.queue_up_helper import QueueUpHelper
        
        # 查询用户排队情况
        result = QueueUpHelper.query(app_id, queue_name, user_id)
        
        # 查询用户排队数量
        num = QueueUpHelper.get_user_queue_num(app_id, user_id)
        
        # 查询用户正在办理中的队列
        result = QueueUpHelper.get_process_user_queue(app_id, user_id)
        
        # 退出排队
        result = QueueUpHelper.pop(app_id, queue_name, user_id)
        
        # 指定用户退出参与的队列
        QueueUpHelper.pop_by_user_id(app_id, user_id, progress_status=1)
        
        # 批量查询用户排队情况(只包含已排队)
        result = QueueUpHelper.muti_user_query(app_id, user_id)
        
        # 批量查询用户排队情况(包含已排队和未排队)
        result = QueueUpHelper.muti_queue_query(app_id, queue_name_list, user_id)
        
        # 查询指定队列的所有用户信息
        result = QueueUpHelper.query_list(app_id, queue_name, user_id, limit=10)
        
        # 批量踢掉过期用户
        QueueUpHelper.muti_expire_user_pop(app_id)
        
        # 更新可操作时间
        QueueUpHelper.update_time(app_id, queue_name, user_id, operate_time=300)
        ```
        
        ### 13.5 注意事项
        
        - 排队系统基于Redis实现，默认走redis,如果要切可以配置redis_queueup
        - 每个队列有最大人数限制，超过限制将无法加入
        - 排队排到后需要在规定时间内确认，否则自动退出
        - 支持多档位查询频率控制，减少服务器压力
        
        ---
        
        ## 14. ActionHelper 执行助手
        
        ActionHelper 提供了方法执行的异常重试机制，支持无限循环执行和限制次数执行两种模式。
        
        ### 14.1 架构说明
        
        ```
        ┌─────────────────────────────────────────────────────────┐
        │                    ActionHelper                         │
        ├─────────────────────────────────────────────────────────┤
        │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
        │  │ run_action   │  │ run_func     │  │ api_func     │  │
        │  │ _while       │  │ _while       │  │              │  │
        │  │ (无限循环)    │  │ (无限循环)    │  │ (API专用)    │  │
        │  └──────────────┘  └──────────────┘  └──────────────┘  │
        │  ┌──────────────┐  ┌──────────────┐                     │
        │  │ run_action   │  │ run_func     │                     │
        │  │ (限制次数)    │  │ (限制次数)    │                     │
        │  └──────────────┘  └──────────────┘                     │
        └─────────────────────────────────────────────────────────┘
                                   │
                                   ▼
                      ┌──────────────────────┐
                      │   异常重试机制        │
                      │  - 可配置重试次数     │
                      │  - 可配置间隔时间     │
                      │  - 支持日志记录       │
                      │  - 批量方法执行       │
                      └──────────────────────┘
        ```
        
        ### 14.2 方法说明
        
        | 方法名 | 返回值 | 执行模式 | 适用场景 |
        |--------|--------|----------|----------|
        | `run_action_while` | None | 无限循环 | 后台任务、守护进程 |
        | `run_func_while` | 结果数据 | 无限循环 | 需要返回值的循环任务 |
        | `run_action` | bool | 限制次数 | 普通操作重试 |
        | `run_func` | 结果数据 | 限制次数 | 需要返回值的普通操作 |
        | `api_func` | InvokeResultData/bool | 限制次数 | 外部API调用 |
        
        ### 14.3 通用参数说明
        
        | 参数名 | 类型 | 默认值 | 说明 |
        |--------|------|--------|------|
        | `action`/`func` | callable/list | 必填 | 要执行的方法或方法列表 |
        | `sleep_time` | float | 0.5 | 异常后的等待时间（秒） |
        | `retry_run_count` | int | 10 | 最大重试次数（限制次数模式） |
        | `is_log` | bool | False | 是否记录错误日志 |
        | `error_count_log` | int | 10/100 | 每多少次错误记录一次日志 |
        | `title` | str | "" | 错误日志标题 |
        
        ### 14.4 基础使用示例
        
        #### 单个方法执行
        
        ```python
        from seven_cloudapp_frame.libs.customize.action_helper import ActionHelper
        
        # 限制次数执行（最多重试10次）
        result = ActionHelper.run_func(
            func=lambda: user_model.get_by_id(user_id),
            sleep_time=0.5,
            retry_run_count=10,
            is_log=True,
            title="获取用户信息"
        )
        ```
        
        #### 批量方法执行
        
        ```python
        # 批量执行多个方法（事务场景）
        results = ActionHelper.run_func(
            func=[
                lambda: order_model.add_entity(order),
                lambda: inventory_model.decrease(goods_id, quantity),
                lambda: log_model.add_operation_log("下单", user_id)
            ],
            sleep_time=0.5,
            retry_run_count=5,
            title="订单创建"
        )
        ```
        
        #### 无限循环执行
        
        ```python
        # 无限循环执行（直到成功）
        ActionHelper.run_action_while(
            action=lambda: message_queue.process_pending_messages(),
            sleep_time=1.0,
            is_log=True,
            error_count_log=100,
            title="消息处理"
        )
        ```
        
        ### 14.5 API调用专用
        
        `api_func` 专门用于调用外部API，支持对 `InvokeResultData` 和 `bool` 类型的结果进行智能判断：
        
        ```python
        from seven_cloudapp_frame.libs.customize.action_helper import ActionHelper
        
        # 调用外部API（自动处理InvokeResultData）
        def query_member_point():
            return third_party_api.create_order(order_data)
                                
        result = ActionHelper.api_func(
            func=query_member_point,
            sleep_time=1,
            retry_run_count=3,
            is_log=True,
            title="创建第三方订单",
            retry_messages=["NETWORK_ERROR", "TIMEOUT"]  # 仅对这些错误码重试
        )
        
        # 返回 InvokeResultData 对象
        if result.success:
            print(f"订单创建成功: {result.data}")
        else:
            print(f"订单创建失败: {result.error_code}")
        ```
        
        **api_func 特性：**
        - 自动识别 `InvokeResultData` 类型的返回结果
        - 根据 `success` 字段判断是否成功
        - 支持配置 `retry_messages` 指定可重试的错误码
        - 对于不可重试的错误会立即返回，避免无效重试
        
        ### 14.6 注意事项
        
        1. **方法参数**: 使用 `lambda` 或 `functools.partial` 包装带参数的方法
        2. **异常处理**: 所有方法内部异常都会被捕获并触发重试
        3. **日志记录**: 建议生产环境开启 `is_log`，便于排查问题
        4. **重试次数**: 根据业务场景合理设置，避免无限重试导致资源浪费
        5. **API专用**: 调用外部接口优先使用 `api_func`，支持更智能的错误处理
        
        ---
        
        ## 15. 心跳监控
        
        心跳监控用于实时监控定时作业的运行状态，及时发现作业异常停止的情况。
        
        ### 15.1 架构说明
        
        ```
        ┌─────────────────────────────────────────────────────────────┐
        │                      心跳监控系统                             │
        ├─────────────────────────────────────────────────────────────┤
        │                                                             │
        │   ┌─────────────┐      Redis      ┌─────────────┐          │
        │   │  作业进程A   │ ───────────────→│  心跳记录   │          │
        │   │ (定时上报)   │   heart_beat    │  Key-Value  │          │
        │   └─────────────┘   _monitor()    └──────┬──────┘          │
        │                                           │                 │
        │   ┌─────────────┐                         │                 │
        │   │  作业进程B   │ ────────────────────────┤                 │
        │   │ (定时上报)   │   heart_beat_monitor()  │                 │
        │   └─────────────┘                         │                 │
        │                                           │                 │
        │   ┌─────────────┐      Redis      ┌───────▼───────┐        │
        │   │  检测进程    │ ←───────────────│ heart_beat    │        │
        │   │ (独立运行)   │   scan/读取     │ _check()      │        │
        │   │             │                 │ 每分钟检测    │        │
        │   │ 异常告警    │ ───────────────→│ 超时预警      │        │
        │   │ (日志/微信)  │                 │               │        │
        │   └─────────────┘                 └───────────────┘        │
        │                                                             │
        │   Key格式: heart_beat_monitor:{work_name}                   │
        │   Value: {"process_date": "时间", "check_time": 分钟, "data": {}} │
        │                                                             │
        └─────────────────────────────────────────────────────────────┘
        ```
        
        ### 15.2 核心方法
        
        | 方法名 | 作用 | 调用位置 | 说明 |
        |--------|------|----------|------|
        | `heart_beat_monitor` | 上报心跳 | 作业循环体内 | 定期上报作业运行状态 |
        | `heart_beat_delete` | 删除心跳 | 作业结束/退出时 | 清理心跳记录，避免误报 |
        | `heart_beat_check` | 检测心跳 | 独立检测进程 | 监控所有作业心跳状态 |
        
        ### 15.3 方法详解
        
        #### heart_beat_monitor - 心跳上报
        
        ```python
        from seven_cloudapp_frame.libs.common.frame_console import heart_beat_monitor
        
        # 在作业循环中定期调用
        heart_beat_monitor(
            work_name="order_sync_job",      # 作业名称（唯一标识）
            interval_time=30,                 # 上报间隔（秒），默认30
            data={"count": 100, "status": "running"},  # 附加数据
            check_time=5,                     # 预警阈值（分钟），默认60
            redis_config_dict=None            # 自定义Redis配置
        )
        ```
        
        **参数说明：**
        
        | 参数名 | 类型 | 默认值 | 说明 |
        |--------|------|--------|------|
        | `work_name` | str | 必填 | 作业唯一名称 |
        | `interval_time` | int | 30 | 上报间隔（秒），控制写入Redis频率 |
        | `data` | dict | {} | 附加数据，可记录作业状态信息 |
        | `check_time` | int | 60 | 预警阈值（分钟），超过此时间未上报则告警 |
        | `redis_config_dict` | dict | None | 自定义Redis配置 |
        
        **上报机制：**
        - 本地缓存控制：使用 `work_process_date_dict` 控制实际写入频率
        - 默认30秒写入一次Redis，避免频繁写入
        - 数据保存30天（30 * 24 * 3600秒）
        
        #### heart_beat_delete - 删除心跳
        
        ```python
        from seven_cloudapp_frame.libs.common.frame_console import heart_beat_delete
        
        # 作业正常结束时调用
        heart_beat_delete(
            work_name="order_sync_job",      # 作业名称
            redis_config_dict=None            # 自定义Redis配置
        )
        ```
        
        **使用场景：**
        - 作业正常退出时清理心跳记录
        - 避免已停止的作业触发误报
        - 同时清理本地缓存和Redis记录
        
        #### heart_beat_check - 心跳检测
        
        ```python
        from seven_cloudapp_frame.libs.common.frame_console import heart_beat_check
        import threading
        
        # 在独立线程中启动检测
        threading.Thread(
            target=heart_beat_check,
            kwargs={
                "redis_config_dict": None,     # 自定义Redis配置
                "wx_send_key": "xxxxx"          # 企业微信群机器人key
            },
            daemon=True
        ).start()
        ```
        
        **检测机制：**
        - 每分钟扫描一次所有心跳记录
        - 对比 `process_date` 和当前时间
        - 超过 `check_time` 分钟未上报则触发告警
        - 支持日志告警和企业微信告警
        
        **告警方式：**
        - `wx_send_key` 为空：仅记录错误日志
        - `wx_send_key` 有值：发送企业微信消息
        
        ### 15.4 配置说明
        
        在 `share_config.json` 中配置：
        
        ```json
        {
          "heart_beat_name": "prod",           // 命名空间，用于区分环境
          "is_heart_beat_monitor": true        // 是否开启心跳监控，默认true
        }
        ```
        
        **命名空间作用：**
        - 不同环境（prod/dev/test）使用不同前缀
        - Key格式变为：`heart_beat_monitor:{heart_beat_name}:{work_name}`
        - 避免不同环境的心跳记录冲突
        
        ### 15.5 完整使用示例
        
        #### 作业代码示例
        
        ```python
        from seven_cloudapp_frame.libs.common.frame_console import heart_beat_monitor, heart_beat_delete
        
        def my_background_job():
            work_name = "data_sync_job"
            try:
                while True:
                    try:
                        # 执行业务逻辑
                        process_data()
                        
                        # 上报心跳（每30秒实际写入一次）
                        heart_beat_monitor(
                            work_name=work_name,
                            interval_time=30,
                            data={"last_sync": TimeHelper.get_now_format_time()},
                            check_time=5  # 5分钟未上报则告警
                        )
                        
                        time.sleep(0.1)  # 必须包含
                        
                    except Exception as ex:
                        logger_error.error(f"作业异常:{ex}")
                        time.sleep(5)
                        
            finally:
                # 作业退出时清理心跳
                heart_beat_delete(work_name)
        ```
        
        #### 检测进程示例
        
        ```python
        from seven_cloudapp_frame.libs.common.frame_console import heart_beat_check
        import threading
        
        # 启动心跳检测（通常在服务启动时执行）
        def start_heart_beat_monitor():
            threading.Thread(
                target=heart_beat_check,
                kwargs={
                    "wx_send_key": "693axxx6-7xxx-4xxx-8xxx-xxxxxxxxxxxx"  # 企业微信key
                },
                daemon=True
            ).start()
        
        # 在服务启动时调用
        start_heart_beat_monitor()
        ```
        
        ### 15.6 注意事项
        
        1. **必须调用 delete**: 作业正常退出时必须调用 `heart_beat_delete`，否则会产生误报
        2. **独立检测进程**: `heart_beat_check` 需要在独立线程/进程中运行
        3. **合理设置阈值**: `check_time` 根据作业执行频率设置，避免过于敏感或迟钝
        4. **命名空间隔离**: 多环境部署时务必配置 `heart_beat_name`
        5. **上报频率控制**: `interval_time` 控制本地缓存，实际写入频率由框架控制
        6. **异常处理**: 作业内部异常不应影响心跳上报，需单独捕获
        
        ---
        
        ## 16. 开发规范
        
        ### 16.1 模型开发规范
        
        1. **数据库模型**: 继承 `CacheModel`，使用 `FrameDbModel` 能力
        2. **业务模型**: 继承 `FrameBaseModel` 或对应业务基类
        3. **Handler**: 继承 `ClientBaseHandler` 或 `FrameBaseHandler`
        
        ### 16.2 国际化规范
        
        - 错误消息使用 `translation_helper` 进行翻译
        - 翻译文件放置在 `locales/` 目录
        - 支持 `zh_CN` 和 `zh_EN` 两种语言
        - 翻译文件使用 JSON 格式，以中文为 key
        
        ```python
        from seven_cloudapp_frame.libs.customize.locales.translation_helper import translation_helper
        
        error_msg = translation_helper.translate("用户不存在")
        ```
        
        ### 16.3 红线规范（必须遵守）
        
        1. ✅ Handler必须继承 `ClientBaseHandler` 或 `FrameBaseHandler`
        2. ✅ 请求参数必须使用 `get_param*` 方法获取
        3. ✅ 列表查询必须限制 `page_size` 在 1-200 之间
        4. ✅ 核心操作必须使用 `business_process_executing`
        5. ✅ 数据库查询参数类型必须与字段类型一致
        6. ✅ 作业代码必须包裹 try except
        7. ✅ 作业必须包含 `time.sleep(0.1)`
        8. ✅ 正式环境必须开启加密
        9. ✅ 敏感字段必须使用框架加密方法
        10. ✅ 资产操作必须使用 `AssetBaseModel`
        
        ---
        
        ## 17. 项目运行方式
        
        ### 17.1 启动服务
        
        ```python
        from seven_cloudapp_frame.route import seven_cloudapp_frame_route
        from seven_framework.web_tornado import start_web
        
        handlers = []
        handlers.extend(seven_cloudapp_frame_route())
        
        # 启动Tornado服务
        start_web(handlers, port=8080)
        ```
        
        ### 17.2 启动控制台任务
        
        ```python
        from seven_cloudapp_frame.models.console_models.erp_console_model import ErpConsoleModel
        
        erp_console = ErpConsoleModel()
        
        # 启动订单推送和物流拉取
        erp_console.console_erp(
            mod_count=10,
            process_type=2,
            pull_time_range="09:00-22:00",
            push_time_range="09:00-22:00"
        )
        ```
        
        ### 17.3 启动定时作业
        
        ```python
        from seven_cloudapp_frame.models.console_models.timing_work_model import TimingWork
        
        class MyTimingWork(TimingWork):
            def execute(self):
                # 执行业务逻辑
                pass
        
        work = MyTimingWork()
        work.execute()
        ```
        
        ---
        
        ## 18. 部署说明
        
        ### 18.1 环境要求
        
        | 组件 | 版本 | 说明 |
        |------|------|------|
        | Python | 3.8+ | 运行环境 |
        | MySQL | 5.7 / 8.0 | 主数据库 |
        | Redis | 4.0+ | 缓存和队列 |
        | Nacos | 可选 | 配置中心 |
        
        ### 18.2 数据库配置
        
        - **主库配置**: 默认 `db_cloudapp`
        - **主从支持**: 支持读写分离
        - **分表支持**: 8张表支持分表模式
        - **字符集**: 推荐使用 `utf8mb4`
        
        ### 18.3 缓存配置
        
        - **Redis 缓存**: 用于数据缓存，默认 30 分钟过期
        - **依赖缓存**: 用于关联数据缓存，默认 24 小时过期
        - **缓存失败重试**: 支持缓存失效后的重试机制
        
        ### 18.4 配置中心
        
        - **Nacos 配置**: 生产环境推荐使用 Nacos 进行配置管理
        - **本地配置**: 开发环境可使用本地 JSON 配置文件
        - **远程配置**: 支持通过 HTTP URL 加载配置文件
        
        ### 18.5 语言翻译
        
        - 设置 `is_translate` 为 `true` 开启翻译
        - 配置 `locales_dir` 指向翻译文件目录
        - 支持 `zh_CN` 和 `zh_EN` 两种语言
        
        ### 18.6 监控与日志
        
        - 内置心跳监控机制（`heart_beat_monitor`）
        - 支持操作日志记录（`operation_log_model`）
        - 异常日志自动记录到错误日志文件
        
        ---
        
        
        ## 附录：常用模块引用速查
        
        | 功能 | 引用路径 |
        |------|----------|
        | Handler 基类 | `seven_cloudapp_frame.handlers.frame_base.FrameBaseHandler` |
        | 客户端 Handler | `seven_cloudapp_frame.handlers.frame_base.ClientBaseHandler` |
        | 模型基类 | `seven_cloudapp_frame.models.frame_base_model.FrameBaseModel` |
        | 缓存模型 | `seven_cloudapp_frame.models.cache_model.CacheModel` |
        | 全局配置 | `seven_cloudapp_frame.libs.common.share_config` |
        | 核心帮助类 | `seven_cloudapp_frame.libs.customize.seven_helper.SevenHelper` |
        | Redis 帮助类 | `seven_cloudapp_frame.libs.customize.redis_helper.RedisHelper` |
        | 枚举定义 | `seven_cloudapp_frame.models.enum` |
        | 条件拼接 | `seven_cloudapp_frame.models.seven_model.ConditionWhere` |
        | 文件存储 (OSS) | `seven_cloudapp_frame.libs.customize.file_helper.OSSHelper` |
        | 文件存储 (COS) | `seven_cloudapp_frame.libs.customize.file_helper.COSHelper` |
        | 文件存储 (BOS) | `seven_cloudapp_frame.libs.customize.file_helper.BOSHelper` |
        | 短信 (百度) | `seven_cloudapp_frame.libs.customize.sms_helper.BceSmsHelper` |
        | 短信 (阿里) | `seven_cloudapp_frame.libs.customize.sms_helper.AliSmsHelper` |
        | 短信 (腾讯) | `seven_cloudapp_frame.libs.customize.sms_helper.TencentSmsHelper` |
        | 内容审核 (百度) | `seven_cloudapp_frame.libs.customize.content_censor_helper.BOSCensorHelper` |
        | 内容审核 (腾讯) | `seven_cloudapp_frame.libs.customize.content_censor_helper.COSCensorHelper` |
        | 物流查询 | `seven_cloudapp_frame.libs.customize.logistics_helper.AliLogisticsHelper` |
        | 邮件服务 | `seven_cloudapp_frame.libs.customize.email_helper.EmailHelper` |
        | 加密帮助类 | `seven_cloudapp_frame.libs.customize.cryptography_helper.CryptographyHelper` |
        | 计数器 | `seven_cloudapp_frame.libs.customize.counter_helper.CounterHelper` |
        | Excel 操作 | `seven_cloudapp_frame.libs.customize.excel_helper.ExcelExHelper` |
        | 排队系统 | `seven_cloudapp_frame.libs.customize.queue_up_helper.QueueUpHelper` |
        
        ---
        
        ## 版本信息
        
        - **当前版本**: 1.2.138
        - **作者**: 267
        
Platform: UNKNOWN
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: ~=3.4
Description-Content-Type: text/markdown
