Getting Started

Install with composer require tourze/wechat-work-external-contact-model. There is no service provider, config file, or migration set to publish — this is a data-model package, not a Laravel integration.
Look first at src/ for the model/entity classes and any enum types. Expect the domain objects for WeChat Work 客户联系: external contacts, follow users (跟进成员), contact ways (联系我), tags, and group-chat-ish payloads. Confirm whether the models extend a tourze/model base class or are plain PHP objects before assuming Eloquent compatibility.
First use case: after calling the WeChat Work externalcontact APIs with your own HTTP client, hydrate the JSON response into these models and persist them locally so you can query contacts by external_userid, follow user, or tag without re-hitting the rate-limited API.
Minimal loop: fetch → ExternalContact::from(...)/hydrate → upsert into your own table (or the package's ORM, if wired) → query. If the package has no persistence layer, treat the models as typed DTOs and own the storage yourself.

Implementation Patterns

Sync job + upsert. Run a queued/scheduled command that pages through the WeChat contact list, maps each payload to the package model, and upserts on (corp_id, external_userid). Keep the API client separate from the models so you can retry and rate-limit independently.
Multi-corp safety. WeChat external_userid is scoped per corp. Put corp_id (or tenant id) on every row and make it part of the unique key; never key on external_userid alone.
Wrap, don't leak. Keep package models behind a repository/service and map into your own Eloquent models or resources. This isolates you from model-shape changes in a 0.x package and from the package's ORM assumptions.
Use the enums. Gender, add_way, follow-user status, and tag types are safer as enum comparisons than raw ints from the API.
Idempotent handling of lifecycle events. External contacts get added, followed by multiple members, and deleted/unfollowed. Model the follow-user relation as a join (contact ↔ member) and soft-delete rather than hard-delete on del_follow_user events.
Hydration from webhooks/events. The same models are useful when processing 客户联系 change callbacks — hydrate the callback payload and upsert, reusing the sync code path.
Migrations. Generate your own schema from the model fields; don't expect the package to ship migrations. Add casts for timestamps (WeChat sends unix seconds) and JSON columns for tags/follow_user arrays.

0.1.0 has no usable release notes — only a 0.0.4...0.1.0 compare link. In 0.x, a minor bump is frequently breaking. Diff the two tags before upgrading, pin the exact version, and add a smoke test that hydrates a real API sample.
Don't expect Laravel affordances. No facade, no config, no auto-discovery, likely no Eloquent. Check composer.json for a Laravel service provider before assuming otherwise.
Field coverage lags the WeChat API. Hydration may silently drop unknown JSON keys (new API fields, unionid, custom fields). Log the raw payload next to the hydrated model when debugging "missing data" bugs.
unionid is optional and only present under certain corp/binding conditions — never make it required or a primary key.
Timestamps are unix seconds, not Carbon. Cast explicitly; don't let a datetime column guess.
ORM coupling. If models depend on tourze/model/tourze/orm attributes, registering those attributes or bootstrapping that ORM is a prerequisite. If you only want Eloquent, subclass the model and re-declare fields with your own casts.
Extension points: subclass the model classes to add accessors/casts, override the hydration/fromArray method if present to retain raw payloads, and keep custom mapping in your own layer rather than forking the package.
Debugging tip: keep a raw_payload JSON column on your synced table. It makes API-version drift and hydration regressions obvious and lets you backfill without re-calling WeChat.