kirukib
8fe6d58a09
Keep the living API sheet aligned with demo personas, avatars, ID-card QR scan, list filters, and Admin/Ecom coordination. Co-authored-by: Cursor <cursoragent@cursor.com>
99 lines
3.4 KiB
Markdown
99 lines
3.4 KiB
Markdown
# Coordination: Gishen-Ecom
|
|
|
|
How Gishen-B2B shares **customer identity**, **allowance visibility**, and **checkout entitlement split** with Gishen-Ecom.
|
|
|
|
**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`
|
|
|
|
## Shared customer identity
|
|
|
|
| Concept | Notes |
|
|
|---------|-------|
|
|
| `customer_id` | Single Gishen customer across Ecom, Mob, B2B member |
|
|
| `member_id` | B2B enrolment link; optional until member joins |
|
|
| Loyalty | Lives on customer identity — B2B shows summary pointer; Ecom/Mob own full loyalty UI |
|
|
|
|
When HR enrols a member with existing retail account (phone match), backend links `member.customer_id` without merging clinical history incorrectly.
|
|
|
|
## Allowance visibility
|
|
|
|
| Surface | Owner | Data |
|
|
|---------|-------|------|
|
|
| B2B `/me` | B2B | `allowance_remaining`, package summary |
|
|
| Ecom/Mob checkout | Ecom | Same allowance fetched from platform API at checkout time |
|
|
| B2B Finance | B2B | Spend aggregates — no basket detail |
|
|
|
|
B2B displays remaining allowance so members know coverage before shopping. **Actual payment split UI lives in Ecom checkout.**
|
|
|
|
## Checkout entitlement split (shared concern)
|
|
|
|
When a covered member checks out in Ecom or Mobile:
|
|
|
|
1. Platform calculates org-covered amount vs member co-pay / out-of-pocket.
|
|
2. Org credit applied up to allowance and category rules.
|
|
3. Member pays remainder via payment gateway (Chapa, etc.).
|
|
|
|
```
|
|
Basket total: 1,200 ETB
|
|
Org covered: 900 ETB (package rules)
|
|
Member pays: 300 ETB (co-pay + exclusions)
|
|
```
|
|
|
|
### Ownership (recommended)
|
|
|
|
| Component | Recommended owner |
|
|
|-----------|-------------------|
|
|
| Entitlement calculation API | Shared backend |
|
|
| Split UI in checkout | **Gishen-Ecom** (+ Mob reuses) |
|
|
| Allowance display pre-checkout | B2B `/me` + Ecom header widget |
|
|
| Finance reconciliation | B2B Finance + Admin billing |
|
|
|
|
See [`open-items.md`](open-items.md) for decision status.
|
|
|
|
## B2B does NOT build
|
|
|
|
- Product catalog browse (Ecom)
|
|
- Cart and payment UI (Ecom/Mob)
|
|
- Retail-only promotions
|
|
|
|
## B2B member paths to Ecom
|
|
|
|
Member portal should deep-link to Ecom storefront with session/SSO (future):
|
|
|
|
```
|
|
https://shop.gishenpharmacy.org/?customer_id=cus_01H...
|
|
```
|
|
|
|
Mock phase: static link + shared demo customer.
|
|
|
|
## Events (cross-repo)
|
|
|
|
| Event | Relevance |
|
|
|-------|-----------|
|
|
| `order.completed` | Updates allowance_used; feeds B2B finance spend |
|
|
| `prescription.review_updated` | Approved Rx may create Ecom refill cart |
|
|
| `org.activated` | Enables entitlement at checkout |
|
|
|
|
## API dependencies (future shared backend)
|
|
|
|
| Endpoint | Consumer |
|
|
|----------|----------|
|
|
| `GET /v1/customers/:id/allowance` | Ecom checkout, B2B `/me` |
|
|
| `POST /v1/checkout/entitlement-preview` | Ecom cart |
|
|
| `GET /v1/customers/:id/orders` | B2B `/me/orders` (member view) |
|
|
| Resolve pharmacy QR `gishen://member/{id}?v={verification_id}` | Admin POS / Ecom staff checkout → same entitlement preview |
|
|
|
|
Document exact shapes in Ecom spec sheet; B2B references via this coordination doc.
|
|
|
|
## Telegram Mini App
|
|
|
|
Telegram Mini App rides **Ecom's backend spec**, not B2B. No B2B action required.
|
|
|
|
## Integration checklist
|
|
|
|
- [ ] Shared `customer_id` linking on member enrolment
|
|
- [ ] Allowance API consumed by both B2B and Ecom
|
|
- [ ] Checkout split UI implemented once in Ecom
|
|
- [ ] Order events feed B2B finance aggregates (redacted)
|
|
- [ ] Confirm SSO/deep-link from B2B member portal to Ecom
|
|
- [ ] Staff / pharmacist flow accepts B2B pharmacy ID QR at checkout
|