Skip to content

CLAUDE.md

Latest commit

 

History

History
110 lines (79 loc) · 4.38 KB

CLAUDE.md

File metadata and controls

110 lines (79 loc) · 4.38 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

WeChat is a Ruby gem for integrating with WeChat Official Accounts Platform, WeChat Enterprise, and WeChat Mini Program APIs. It provides both Rails integrations (wechat_responder, wechat_api) and a standalone command-line interface.

Common Development Commands

# Run full test suite and linting
bundle exec rake

# Run only RSpec tests
bundle exec rake spec

# Run specific test file
bundle exec rspec spec/lib/wechat/http_client_spec.rb

# Run RuboCop linting
bundle exec rubocop

Code Architecture

Core Structure

The gem uses Zeitwerk autoloading (see lib/wechat.rb:4). The main components are:

  1. API Clients (lib/wechat/):

    • api.rb - Public account API (inherits from ApiBase)
    • corp_api.rb - Enterprise account API
    • mp_api.rb - Mini program API
    • api_base.rb - Shared base implementation

  2. HTTP & Token Management:

    • http_client.rb - HTTP client with retry logic and network settings
    • token/ - Access token management (PublicAccessToken, CorpAccessToken)
    • ticket/ - JSAPI ticket management (PublicJsapiTicket, CorpJsapiTicket)
    • api_loader.rb - Configuration and API instance management

  3. Message Handling:

    • responder.rb - DSL for handling incoming messages (see wechat_responder)
    • message.rb - Message formatting and templates
    • controller_api.rb - Rails controller helpers

  4. Rails Integration (lib/action_controller/):

    • wechat_responder.rb - Provides wechat_responder DSL
    • wechat_api.rb - Provides wechat_api method
    • callback.rb - Webhook callback handling

  5. Rails Generators (lib/generators/):

    • wechat/ - Generators for rails generate wechat:install, wechat:config, etc.

  6. Helpers & Utilities:

    • helpers.rb - View helpers like wechat_config_js
    • cipher.rb - Message encryption/decryption
    • signature.rb - WeChat signature verification
    • concern/ - Shared modules (Common, Draft, Qcloud)

Key Design Patterns

  • Multi-account support: Use Wechat.api(:account_name) to access different WeChat accounts. Configure via config/wechat.yml with environment-specific sections.
  • Token caching: Access tokens and tickets are cached in files or databases to avoid repeated API calls.
  • Responder DSL: Use on :text, with: 'help' do |request| syntax to define message handlers.
  • Error handling: ResponseError wraps WeChat API errors with error codes.

Configuration Flow

  1. Configuration loaded via ApiLoader (lib/wechat/api_loader.rb)
  2. Supports multiple sources: YAML files → Environment variables → Database records
  3. Configuration precedence: Database > YAML > Environment variables
  4. Reload with Wechat.reload_config! after database changes

Testing

The project uses RSpec with:

  • spec/spec_helper.rb - Test configuration and SimpleCov setup
  • spec/dummy/ - Minimal Rails app for integration tests
  • spec/support/ - Shared test helpers

Tests mirror the lib structure (e.g., spec/lib/wechat/http_client_spec.rb).

SimpleCov coverage reports are generated in coverage/index.html.

Code Style

  • Ruby 2.6+
  • Line length: 180 characters
  • RuboCop is authoritative - run before commits
  • Frozen string literals in all new files
  • Standard Ruby naming conventions (snake_case methods, CamelCase classes)

Known Important Files

  • config/wechat.yml - Generated by rails g wechat:install, holds account configurations
  • ~/.wechat.yml - CLI configuration for standalone wechat command
  • AGENTS.md - Project development guidelines
  • CHANGELOG.md - Recent changes
  • README.md - Full documentation

Development Tips

  • Enterprise accounts must use encrypt mode (encrypt_mode: true is default)
  • Multi-account setup mirrors Rails database.yml structure
  • Use rails g wechat:redis_store for distributed token/ticket storage
  • Access tokens are auto-refreshed; AccessTokenExpiredError is handled internally
  • The wechat command has different commands for public vs enterprise accounts
  • JS-SDK requires trusted_domain_fullname in development behind reverse proxies