Wechat Work External Contact Stats Bundle Laravel Package

Getting Started

This is a very early release (0.0.1) of tourze/wechat-work-external-contact-stats-bundle — treat it as a preview, not something to drop into a production Laravel app without a spike first.

1. Install: composer require tourze/wechat-work-external-contact-stats-bundle:^0.0.1. Expect Doctrine ORM, a PSR HTTP client, and one or more tourze/wechat-work-* sibling packages to come along as transitive dependencies.
2. Check the framework fit first. The -bundle suffix and the tourze namespace strongly suggest a Symfony bundle (Bundle class, DI extension, Doctrine entities/repositories), not a Laravel package. Before writing any app code, open composer.json and look for symfony/framework-bundle, doctrine/orm, and whether a *Bundle.php class exists. There is very likely no ServiceProvider, no config/*.php publishable config, and no facade.
3. Where to look after install:
   • src/ for the Bundle class, Entity/, Repository/, Command/, and any DependencyInjection/ config tree — the DI config is the real "documentation" for this package at 0.0.1.
   • The migrations/schema the entities expect (or the Resources/config/doctrine mapping), since you will need equivalent tables in your Laravel database.
   • The upstream 企业微信 (WeChat Work) API endpoints it wraps — most likely externalcontact/get_follow_user_list and externalcontact/get_user_behavior style stats calls.
4. First use case: a scheduled job that pulls external-contact statistics (add/delete counts, chat behaviour, follow-user coverage) for a date range and persists a daily snapshot you can report on. Start by instantiating the stats service directly in a one-off php artisan tinker / test script and dumping the raw response before wiring persistence.

Implementation Patterns

Because the package is framework-coupled to Symfony/Doctrine, the realistic patterns for a Laravel codebase are either bridge or wrap.

Bridge (Symfony bundle inside Laravel):

• Register the bundle's services manually in a StatsServiceProvider — re-declare the classes you need with $this->app->bind() and pass config (corp ID, secret, agent ID) from config/services.php.
• Map Doctrine entities to Eloquent models you own; use the package for HTTP + DTO work only, and let Eloquent own persistence. This keeps migrations, casts, and relationships in familiar territory.
• If the bundle exposes console Command classes, don't expect them under php artisan; either port the logic into an Artisan command or invoke via Artisan::call on a thin wrapper.

Scheduled ingestion (the core workflow):

• One command per stats dimension, run on a ->dailyAt() / ->hourly() schedule, keyed by stat_date + userid + corp_id for idempotent upserts (updateOrCreate or upsert on a unique index).
• Always backfill by explicit date range, not "yesterday only" — the WeChat Work stats endpoints have retention windows and you will want re-pull capability after a failed run.
• Store the raw JSON alongside the parsed columns (json column). At 0.0.1 the parsing shape is unproven; raw payloads let you re-derive numbers without re-hitting the rate-limited API.

Integration tips:

• Wrap the client in your own ExternalContactStats service interface so the package is swappable — high probability you outgrow a 0.0.1 dependency.
• Cache the access token aggressively (WeChat Work tokens are ~7200s and shared across all endpoints); a per-request token fetch will get you throttled fast.
• Push aggregation into queued jobs per department/user to parallelise and isolate failures; keep a stats_sync_runs table with status and error text for observability.
• Feed the snapshots into reporting via a small read-model table rather than querying the raw ingestion table from dashboards.

Gotchas and Tips

• Version 0.0.1 = no BC promises. Pin the exact version ("0.0.1", not ^0.0.1) and expect breaking changes on every bump. Review the diff before upgrading; there is no changelog beyond the commit list.
• Framework mismatch is the headline risk. Confirm it's a Symfony bundle before planning; if it is, you're paying an integration tax for what is essentially an API client. Consider calling the WeChat Work endpoints directly with Http::withToken() if the bundle only saves you a few DTOs.
• Documentation is effectively absent. The release notes are a bare changelog link. Read DependencyInjection/Configuration.php (or equivalent) for required config keys — corp ID, secret, agent ID, and any cache/token adapter are the usual suspects.
• Doctrine coupling. If entities use annotations/attributes with Doctrine types, you cannot reuse them as Eloquent models; plan the mapping early or you'll end up with two schema sources of truth.
• API-side quirks to expect: per-second and daily call quotas on 企业微信, userid values that no longer exist after staff turnover (handle gracefully, don't 500 the job), and stats that lag — "today" is usually incomplete, so schedule the definitive pull after midnight with a re-check window.
• Timezone discipline. The WeChat Work API returns dates in the corp's configured timezone; store stat_date as a plain date and keep timestamps in UTC to avoid off-by-one-day reporting bugs.
• Debugging approach: since there's no service provider, failures surface as container/DI errors ("cannot autowire…") or Doctrine connection errors, not package-specific exceptions. Log the raw HTTP request/response in the package's client (temporarily) rather than guessing.
• Extension points to prefer: keep your own repository/reporting layer on top, avoid extending the package's entities, and never reference its classes from controllers — confine the dependency to one ingestion service so a later swap to a first-party integration is a one-file change.