Overview
The field-rep master is the Core roster behind rep orders and collection claims. It connects one active rep to the channel identity they use, the customers they may work for, and (when they use the mobile app) their login account. It is always on; it is not an installable Capability.
Where to find it
There is no standalone /field-reps page. The mounted fieldRep admin procedures provide the roster, channel-handle, assignment, and linked-login actions; /intake-review currently exposes the field-rep attribution picker. The order-consent panel is registered in Settings as field-rep.consent and is described in Rep order consent. The rep mobile view starts at /m/rep/home after an active login is linked.
Key concepts
- Active rep — a rep whose
field_reps.stateisactive. Archived reps cannot send rep orders or create collection claims. - Channel identity / whitelist — a WhatsApp full-number handle or a verified Telegram chat ID. WhatsApp matching uses the full E.164 digit string: locally entered Indian rep phones are seeded as
91plus the stored 10 digits, while foreign senders keep their own country code. Matching never falls back to the last 10 digits. - Assignment — an active link between a rep and a customer. It is the allow-list for rep order drafts and collection claims; an unassigned customer does not appear in the rep's scoped data.
- FIELD_REP login — a Better Auth user linked to the rep row. Linking grants the tenant's
FIELD_REPsystem role; unlinking removes that role.
Common workflows
field-rep.create with a name and valid Indian mobile number. The number must be unique among active reps. Add an optional code, email, territory, or attributes; changing the phone revokes the old WhatsApp handle and seeds the new one.91 plus the stored 10-digit phone. For Telegram, use fieldRep.channelHandles.mintTelegramBindCode; the rep sends the short-lived signed code to the tenant bot, which binds that exact chat ID. Bind codes are valid for 15 minutes and fail closed when FIELD_REP_BIND_SECRET is not provisioned.field-rep.assign to add an active customer to the rep's assignment list, or unassign it when the beat changes. The same customer can be assigned again after an unassignment; every rep write checks the active assignment at write time.field-rep.link-user to link a same-tenant Better Auth account. The account receives FIELD_REP; one active rep may use one login. Unlinking removes only the FIELD_REP grant, not any other role the account has.field-rep.archive with a reason. Active assignments are released and the linked user's FIELD_REP grant is revoked. The channel-handle rows remain as tombstones, so an ex-rep's number is rejected rather than onboarded as a customer. Reactivation re-checks conflicts and restores the role when a login remains linked.Operations must provision both FIELD_REP_BIND_SECRET (Telegram bind codes) and REP_ORDER_ACK_LINK_SECRET (signed customer acknowledgement links). These secrets are operational configuration, not tenant settings.
Role notes
- Owner — full master control through
field-rep.read,field-rep.create,field-rep.update,field-rep.archive,field-rep.reactivate,field-rep.assign, andfield-rep.link-user. - Manager — can view, create, update, and assign through
field-rep.read,field-rep.create,field-rep.update, andfield-rep.assign. Archive, reactivate, and link-user procedures are Owner-only. - Field rep — does not maintain the master. Their mobile reads use
field-rep.me.read; order drafts and collection claims are separate rep-scoped permissions.
Tips & time-savers
Gotchas
Archiving is not deleting. It releases active assignments and access, but keeps rep history and channel-handle conflict protection.