# TANRAIL ONE — Functional Requirements

## 1. Overview
This document outlines the core functional requirements of the TANRAIL ONE platform. Requirements are grouped by module. All implementation must trace back to these defined requirements.

## 2. Authentication & Authorization (AUTH)

### FR-AUTH-001: Centralized Login
- **Purpose:** Provide a single login portal for all employees.
- **Actor:** Any User
- **Main flow:** User enters email/password. System authenticates and returns available Business Unit (BU) contexts based on their assigned roles.
- **Business rules:** Passwords must be hashed. Failed attempts must lock out after 5 tries.

### FR-AUTH-002: Context Switching
- **Purpose:** Allow users assigned to multiple BUs to switch their active operational context without logging out.
- **Actor:** Cross-BU User
- **Main flow:** User clicks "Switch Context" -> selects target BU -> UI and data scope updates to reflect the new BU.

## 3. Business Unit Management (BU)

### FR-BU-001: BU Creation
- **Purpose:** Define a new Business Unit within the organization.
- **Actor:** System Admin
- **Main flow:** Admin creates BU, defining name, code, default currency, and enabled modules.
- **Acceptance criteria:** The BU exists. Users can be assigned to it.

## 4. Master Data (MD)

### FR-MD-001: Global vs Local Customers
- **Purpose:** Support customers that interact with the whole organization or just one BU.
- **Actor:** Manager
- **Business rules:** If a customer is created at the Organization level, all BUs can sell to them. If created within a BU context, they are hidden from other BUs.

## 5. Inventory & Warehouse (INV)

### FR-INV-001: Multi-Branch Stock Tracking
- **Purpose:** Track inventory quantities accurately across different physical locations.
- **Actor:** System
- **Main flow:** When stock is received, it must specify the target Branch and Location (e.g., Restaurant -> Main Branch -> Kitchen Fridge).
- **Business rules:** Negative stock should be configurable (allowed or blocked).

### FR-INV-002: Internal Stock Transfer
- **Purpose:** Move stock between branches or locations within the same BU.
- **Actor:** Inventory Manager
- **Main flow:** Create transfer request -> Dispatch from Source -> Receive at Destination.

## 6. Sales & Orders (SALES)

### FR-SALES-001: Unified Order Processing
- **Purpose:** Provide a standard schema for all types of sales.
- **Actor:** Cashier, Sales Rep
- **Main flow:** Create Order -> Add Items -> Calculate Tax/Total -> Confirm Order -> Trigger Inventory Deduction -> Generate Invoice.
- **Alternative flow (Restaurant):** Create Order -> Send to Kitchen -> Fulfill -> Pay.

## 7. Finance (FIN)

### FR-FIN-001: BU-Scoped Invoicing
- **Purpose:** Ensure revenue is attributed to the correct BU.
- **Actor:** System
- **Business rules:** Every generated invoice must permanently record the `business_unit_id` and `branch_id`.

### FR-FIN-002: Consolidated Expense Reporting
- **Purpose:** Allow executives to see total organizational spend.
- **Actor:** Executive
- **Main flow:** System queries all Expenses across all BUs and presents aggregated totals.

## 8. Business Extensions (EXT)

### FR-EXT-REST-001: Table Status Management
- **Purpose:** Track the occupancy of physical tables in the Restaurant BU.
- **Actor:** Waiter
- **State transitions:** Available -> Seated -> Ordered -> Billed -> Cleaning -> Available.

### FR-EXT-CATER-001: Event Costing
- **Purpose:** Calculate the projected profitability of a catering event before confirming.
- **Actor:** Event Manager
- **Dependencies:** Core Inventory (for raw material costs).