Multi-Branch Package Creation (Group Login)
Business and implementation hub for shared package creation and package access rules for Group Login staff. For the detailed FE plan and API contract, see the linked documents below.
Authoritative source-of-truth PRD (ClickUp): Multi-Branch Selection for Package Creation (Group Login). The documents in this KB are the extraction for engineering planning. If they ever disagree with the upstream PRD, the upstream PRD wins.
Design: Figma — Partner Portal Desktop, Group Login — covers the Branches field on the Create Package form header.
Read by role
| You are… | Start here |
|---|---|
| Product / Business / Engineering — what we’re building and the final decisions | PRD — src/PRD/Multi_Branch_Package_Creation_20260909000000.md |
| Frontend (book-bite) — UI components, Branches field, create/edit permissions, and submit flow | FE Spec — src/PRD/FE_Multi_Branch_Package_Creation_20260909000000.md |
| Backend (hh-server) — API contracts, access rules, transaction behavior, and existing approval flow | BE Spec — src/PRD/BE_Multi_Branch_Package_Creation_20260909000000.md |
| QA — test matrix, critical test cases, pre-rollout checklist | QA Spec — src/PRD/QA_Multi_Branch_Package_Creation_20260909000000.md |
v1 in one paragraph
Group Login staff get a Branches multi-select field on the Create Package form — visible only for staff with access to multiple restaurants — and submit once to create one shared package attached to every selected restaurant. The backend creates one HhPackage::Package, one RestaurantPackage per selected restaurant, and one approved creation PackageSubmission in one all-or-nothing transaction. The submission is anchored to the staff default restaurant for the existing audit and admin-review context; it does not represent a submission per branch. Group staff may edit a shared package and the package-level change applies to all attached restaurants; a single-restaurant staff member may view it but cannot edit or deactivate it. Existing per-restaurant active and expiry behavior remains unchanged. Non-group accounts keep the existing single-restaurant create flow. Partner Portal web only; mobile app is out of scope.
Glossary
- Group Login — login mode where a staff member has access to multiple restaurants; the FE may represent this as
loginAsGroup === true - Branches Field — new multi-select dropdown on the Create Package form, reusing
SelectMultipleBranch.vue - All Branches — shortcut that resolves to every restaurant in
userStore.restaurantsat submit time - Shared Package — one package record with more than one non-deleted
RestaurantPackage - Single-Restaurant Staff — staff member with access to one restaurant; may view a shared package but may not mutate it
- Package-Level Edit — an edit submitted from one accessible branch updates the shared package through the existing approval workflow
Cross-references
- Package Creation (existing single-branch flow):
src/Features/Package_creation.md - ClickUp PRD: Multi-Branch Selection for Package Creation (Group Login)
- ClickUp Task: 86d47c9ug
Final business decisions
| Area | Decision |
|---|---|
| Create | Group staff can select one or more accessible restaurants and create one shared package. |
| Atomicity | The package, all restaurant packages, and the one creation submission succeed or fail together. |
| Group edit | Group staff can edit a shared package; the existing approval workflow applies the package-level change to all attached restaurants. |
| Single-staff access | Single-restaurant staff can view a shared package, but edit and deactivate are blocked; the partner API has no package delete route. |
| Partial group access | A group staff member can edit the shared package even when they can access only some of its attached restaurants. |
| Active and expiry state | Remains per RestaurantPackage and follows the existing logic. |
| Defaults | Existing package-creation default resolution remains the source of truth. The staff default restaurant is the reference/fallback; no new per-restaurant payment or commission rules are introduced. |
| Currency | Mixed currency is not treated as a new multi-branch rule. Existing service/default behavior remains authoritative. |
| Auto-approved creates do not enter the pending-review email flow. Existing edit notifications target the submitting staff member; a future create-confirmation must be sent once, not once per restaurant. | |
| Submission status | New package submissions remain auto-approved; edits remain in the existing approval workflow. |
Explicitly not part of this version
batch_idmigration or batch-level submission UI.- A partner package delete route.
- Partial-success behavior; create is one transaction.
- A restaurant selector on the Edit Package form.
- Broadcast email to every staff member in a restaurant group.
- Mobile package creation.
Status
- Source-of-truth PRD: ClickUp PRD. Final business decisions are recorded above.
- Implementation: the backend contract was merged into the local
hh-engineeringcheckout on Sep 23, 2026; the focusedhh-serverRSpec suite passed before that merge. This KB update is not a release record. - Figma: Reviewed Sep 09, 2026 — covers Branches field on Create Package form header.