kirukib
3778801ef5
Deliver role-aware shell (sidebar, breadcrumbs, quick search, tables, detail/create layouts), locale-ready pages, shared backend/feature docs, and Vercel project config so HR, finance, and members can demo against typed mocks. Co-authored-by: Cursor <cursoragent@cursor.com>
163 lines
3.7 KiB
Markdown
163 lines
3.7 KiB
Markdown
# Entity: Org registration
|
|
|
|
Captures self-serve signup and assisted “request to register” flows before Admin activates commercial terms.
|
|
|
|
**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`
|
|
|
|
## Sub-entities
|
|
|
|
| Entity | Purpose |
|
|
|--------|---------|
|
|
| `OrgRegistration` | Full self-register submission + first SUPER_USER |
|
|
| `OrgRegistrationRequest` | Lightweight lead capture (email or phone) |
|
|
|
|
## OrgRegistration
|
|
|
|
| Field | Type | Required | Notes |
|
|
|-------|------|----------|-------|
|
|
| `id` | `string` | ✓ | `oreg_*` |
|
|
| `org_id` | `string` | ✓ | Created org in `pending_activation` |
|
|
| `submitted_at` | `Timestamp` | ✓ | |
|
|
| `company` | `RegistrationCompany` | ✓ | Mirrors org fields at submit |
|
|
| `super_user` | `RegistrationUser` | ✓ | First admin account |
|
|
| `status` | `RegistrationStatus` | ✓ | |
|
|
| `admin_notes` | `string` | | Admin-only (not in B2B API) |
|
|
|
|
### RegistrationCompany
|
|
|
|
| Field | Type |
|
|
|-------|------|
|
|
| `legal_name` | `string` |
|
|
| `tin` | `string` |
|
|
| `billing_contact` | `Contact` |
|
|
| `approx_headcount` | `integer` |
|
|
|
|
### RegistrationUser
|
|
|
|
| Field | Type |
|
|
|-------|------|
|
|
| `full_name` | `string` |
|
|
| `email` | `string` |
|
|
| `phone` | `Phone` |
|
|
| `password_hash` | `string` | Server-side only; never returned |
|
|
|
|
### RegistrationStatus
|
|
|
|
```
|
|
submitted | under_review | activated | rejected
|
|
```
|
|
|
|
## OrgRegistrationRequest
|
|
|
|
| Field | Type | Required | Notes |
|
|
|-------|------|----------|-------|
|
|
| `id` | `string` | ✓ | `orreq_*` |
|
|
| `contact_name` | `string` | ✓ | |
|
|
| `company_name` | `string` | | Optional |
|
|
| `channel` | `RequestChannel` | ✓ | Preferred contact method |
|
|
| `email` | `string` | conditional | Required if `channel=email` |
|
|
| `phone` | `Phone` | conditional | Required if `channel=phone` |
|
|
| `message` | `string` | | Free text |
|
|
| `status` | `RequestStatus` | ✓ | |
|
|
| `created_at` | `Timestamp` | ✓ | |
|
|
|
|
### RequestChannel
|
|
|
|
```
|
|
email | phone
|
|
```
|
|
|
|
### RequestStatus
|
|
|
|
```
|
|
new | contacted | converted | closed
|
|
```
|
|
|
|
## Validation rules
|
|
|
|
| Rule | Error code |
|
|
|------|------------|
|
|
| Unique `tin` on self-register | `DUPLICATE_ORG` |
|
|
| Password min 8 chars, 1 upper, 1 digit | `WEAK_PASSWORD` |
|
|
| Email unique for super_user | `DUPLICATE_USER` |
|
|
| Request must have email OR phone per channel | `VALIDATION_FAILED` |
|
|
|
|
## Clinical withhold
|
|
|
|
No clinical data in registration entities.
|
|
|
|
## Sample: self-register submit
|
|
|
|
**Request:**
|
|
|
|
```json
|
|
{
|
|
"company": {
|
|
"legal_name": "Gamma Industries PLC",
|
|
"tin": "0011223344",
|
|
"billing_contact": {
|
|
"name": "Hanna T.",
|
|
"email": "hanna@gamma.et",
|
|
"phone": "+251922334455"
|
|
},
|
|
"approx_headcount": 200
|
|
},
|
|
"super_user": {
|
|
"full_name": "Hanna Tadesse",
|
|
"email": "hanna@gamma.et",
|
|
"phone": "+251922334455",
|
|
"password": "SecurePass1"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Response (201):**
|
|
|
|
```json
|
|
{
|
|
"registration_id": "oreg_01HABC",
|
|
"org_id": "org_01HNEW",
|
|
"status": "submitted",
|
|
"org_status": "pending_activation",
|
|
"session": {
|
|
"user_id": "usr_01HNEW",
|
|
"roles": ["SUPER_USER"],
|
|
"org_id": "org_01HNEW"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Sample: request to register
|
|
|
|
```json
|
|
{
|
|
"contact_name": "Daniel Kebede",
|
|
"company_name": "Delta Embassy",
|
|
"channel": "phone",
|
|
"phone": "+251911998877",
|
|
"message": "We need coverage for ~40 staff"
|
|
}
|
|
```
|
|
|
|
**Response (201):**
|
|
|
|
```json
|
|
{
|
|
"request_id": "orreq_01HXYZ",
|
|
"status": "new",
|
|
"message": "A Gishen representative will contact you."
|
|
}
|
|
```
|
|
|
|
## Events
|
|
|
|
| Event | When |
|
|
|-------|------|
|
|
| `org.registration_submitted` | Self-register completes |
|
|
| `org.registration_requested` | Request form submitted |
|
|
| `org.activated` | Admin activates org (see Organisation) |
|
|
|
|
## Related endpoints
|
|
|
|
- [`../endpoints/org.md`](../endpoints/org.md) — registration routes
|