Multi-Branch Package Creation (Group Login)

1. Document purpose

This document is the business and product source for allowing Group Login staff to create and manage one shared package across multiple restaurants.

2. Problem and outcome

Group Login staff currently need to repeat package creation for each restaurant. The result is multiple disconnected package records and repeated future edits.

The desired outcome is one shared package definition attached to the selected restaurants. Staff submit the package once, and the system creates the package and all restaurant associations atomically.

3. Terminology

• Group Login staff: staff with access to multiple restaurants. The FE may expose this as loginAsGroup === true.
• Single-restaurant staff: staff with access to one restaurant.
• Shared package: one Package with more than one non-deleted RestaurantPackage.
• RestaurantPackage: the restaurant-specific association that owns active, start-date, and end-date behavior.
• Branches field: the FE multi-select used only on Create Package for Group Login.

4. Final business decisions

4.1 Create behavior

1. Group Login staff can select one, several, or all accessible restaurants.
2. The FE sends one create request with the selected restaurant IDs.
3. The backend creates one shared Package and one RestaurantPackage per selected restaurant.
4. Package creation is all-or-nothing. If any part fails, no package, restaurant package, or creation submission remains.
5. The create writes one approved new_package submission, anchored to the staff default restaurant for the existing audit and admin-review context.
6. New packages remain auto-approved and published according to the existing create flow.
7. Single-restaurant create remains unchanged and does not send the new restaurant selection field.

4.2 View and edit behavior

Additional rules:

• Group staff with access to only some restaurants attached to a shared package may still edit the whole package.
• The Edit Package form does not include a new restaurant selector.
• Edit remains in the existing approval workflow.
• FE restrictions are for usability; backend authorization is mandatory.

4.3 Restaurant-specific behavior

• active, start_date, and end_date remain per RestaurantPackage.
• Deactivating one restaurant association must not implicitly deactivate every association.
• The partner package API has no delete route; this feature does not add one.
• Expiry continues to use the existing restaurant-package logic.

4.4 Defaults and currency

• Existing package-creation service logic remains the source of truth for payment, commission, pricing, and other defaults.
• The staff default restaurant is the reference/fallback when the existing service needs a restaurant context.
• No new per-restaurant payment, commission, or pricing rules are introduced by this feature.
• Mixed currency is not a new multi-branch decision or validation flow; existing service/default behavior remains authoritative.

4.5 Notifications

• New package creation remains auto-approved, so it does not enter the pending-review email flow.
• Edit notifications continue to target only the staff member who submitted the edit.
• If a create-confirmation email is added later, it must go once to the creating staff member, not once per restaurant.
• There is no group-wide email broadcast requirement.

5. Functional requirements

Flow A — Group Login creates a shared package

1. Staff opens Create Package.
2. FE displays the Branches multi-select.
3. Staff selects one or more accessible restaurants, optionally using All Branches.
4. FE sends one request with restaurant_ids.
5. Backend validates access, builds one shared package, and commits all records in one transaction.
6. FE shows one success state and refreshes the package list.

Flow B — Single-restaurant create remains unchanged

1. Staff opens Create Package.
2. FE does not show the Branches field.
3. FE submits the existing payload without restaurant_ids.
4. Existing behavior and defaults remain unchanged.

Flow C — Single staff views a shared package

1. Staff opens a shared package attached to their restaurant.
2. API permits the read.
3. FE displays package details.
4. Edit and deactivate actions are unavailable or disabled.
5. Direct mutation attempts still receive 403 from the API.

Flow D — Group staff edits a shared package

1. Group staff opens a shared package through any accessible attached restaurant.
2. FE opens the existing package edit form without a Branches field.
3. Staff submits one package-level edit.
4. Backend creates the existing edit submission and approval draft.
5. After approval, the shared package change is visible for all attached restaurants.

6. API-level contract

Create request

POST /api/partner/v1/restaurant_packages

For Group Login:

{
  "package_type": "ayce",
  "restaurant_ids": [101, 102, 103],
  "package": {
    "name_en": "Shared package",
    "restaurant_packages_attributes": {
      "0": {
        "start_date": "2026-09-18",
        "end_date": "2026-12-31"
      }
    }
  }
}

The success response preserves the legacy singular restaurant-package ID, returns all selected associations, and returns the one creation submission:

{
  "success": true,
  "restaurant_package_id": 9001,
  "restaurant_package_ids": [9001, 9002, 9003],
  "submission_id": 7001
}

Mutation contract

• Read requests are allowed when the staff member can access the requested restaurant package.
• Group staff may mutate a shared package through the existing package update flow.
• Single-restaurant staff receive 403 for shared-package edit or deactivate.
• There is no partner destroy endpoint for packages.
• Existing validation and approval errors remain unchanged unless a new permission error is required.

7. Explicit non-goals

• No client-side fan-out into N independent package creates.
• No partial-success or retry-failed-branches flow.
• No batch_id migration.
• No batch-level admin approval UI.
• No partner package delete route.
• No same-currency guard introduced by this feature.
• No package-specific branch selector on Edit Package.
• No group-wide email notification.
• No mobile app implementation.

8. Success measures

• Group Login staff can create one package across multiple restaurants without repeating the form.
• No partial package creation occurs after a failed transaction.
• Single-restaurant staff can see shared packages without receiving unauthorized mutation access.
• Group staff can edit shared packages without repeating edits per restaurant.
• Existing single-restaurant creation, defaults, approval, expiry, and notification behavior does not regress.

9. Related implementation documents

• Frontend implementation plan
• Backend contract and plan
• QA test plan
• Existing package creation
• Group Login Partner Portal