1. Introduction

1.1 Purpose & Objectives

This Software Requirements Specification (SRS) establishes the authoritative, definitive technical and functional requirements for the EV Power Mobile Application (internal package identifier com.evpower.chargingapp, repository moniker evp-app). The EV Power Mobile Application is an enterprise-grade mobile client designed specifically for Electric Vehicle (EV) drivers, commercial fleet operators, and charging station hosts operating across Vietnam.

The primary objective of this document is to provide an unambiguous, rigorous contractual specification governing the mobile client application's user interface flows, hardware interactions (camera QR recognition, geolocation, secure enclave storage), communications with the backend Cloud Edge API Gateway, coordination with the Central Charge Point Management System (CPMS) executing Open Charge Point Protocol (OCPP) versions 1.6-J and 2.0.1, and financial transactions via the internal EVP point wallet.

1.2 Document Conventions

This document adheres strictly to the requirement conformance guidelines defined in RFC 2119. The following normative keywords dictate contractual obligations:

• SHALL / MUST: An absolute, non-negotiable requirement of the engineering specification.
• SHALL NOT / MUST NOT: An absolute, non-negotiable prohibition of behavior.
• SHOULD / RECOMMENDED: A strong recommendation where valid engineering justifications may exist in particular circumstances to deviate, subject to architecture review.
• MAY / OPTIONAL: A truly discretionary capability.

1.2.1 Requirement Identification Taxonomy

Requirements are uniquely cataloged using hierarchical prefixes corresponding to system domains:

1.2.2 Units of Measurement and Currency Standard

All quantitative requirements and system computations comply with the following standardized units:

• Internal Platform Currency (EVP): The point currency unit is the EVP (EV Power Point). The conversion rate between Vietnamese Dong (VND) and EVP is strictly invariant across the entire system:
  INVARIANT: 1 EVP = 1,000 VND (1,000 Vietnamese Dong equals exactly 1 EVP Point).
  All user financial balances, connector charging tariffs, and transaction records SHALL adhere to this conversion factor. For example, a driver topping up 500,000 VND SHALL be credited exactly 500 EVP; a charging session consuming 120 EVP represents a financial cost of 120,000 VND.
• Electrical Power: Measured in Kilowatts (kW), representing instantaneous charging capacity delivered by alternating current (AC) or direct current (DC) Electric Vehicle Supply Equipment (EVSE).
• Electrical Energy: Measured internally in Watt-hours (Wh) at the hardware and telemetry abstraction layer, and formatted as Kilowatt-hours (kWh, where 1 kWh = 1,000 Wh) for user display and billing reconciliation.
• Battery State-of-Charge (SoC): Expressed as a percentage integer from 0% to 100%, representing the current usable capacity of the EV battery pack.
• Time & Latency: Expressed in milliseconds (ms) for network operations, polling cadences, and hardware interlocks, and in seconds (s) or formatted strings (hh:mm:ss) for elapsed session durations.

1.3 Intended Audience & Reading Suggestions

This document is structured for multiple engineering and operational disciplines:

• Mobile Engineering Team: Focus on Part 3.A (External Interface Requirements, Screen Hierarchy, Hardware Interfaces), Part 3.B (System Features 3.1 through 3.8), and Part 3.C (Non-Functional Requirements: State Stores, Caching, and 401 Mutex Interceptors).
• Cloud & Backend API Engineers: Review Section 3.A.3 (REST API Catalog), Section 3.B (Business Rules, Invariant Rate: 1 EVP = 1,000 VND, Ledger Schemas), and Section 4.2 (Canonical Domain Data Models).
• CPMS & Hardware Firmware Engineers: Review Section 3.2 (Charging Stations & Connectors), Section 3.3 (5-Phase Charging State Machine, Telemetry Polling, Emergency Stop Interlocking), and Section 4.3 (Connector Status Enumerations).
• QA, Security & Compliance Auditors: Focus on RFC 2119 requirement clauses, Section 3.C.3 (Security & Mutex Protections), Section 3.7 (Statutory Electronic VAT Invoicing), and verification protocols.
• Fleet Operations & Product Management: Review Section 2 (Overall Description, User Persona Hierarchy, Constraints) and Section 3.4 (Vehicle Garage & Spending Caps).

1.4 Project Scope & System Boundaries

The EV Power Mobile Application is the client interface connecting individual drivers and enterprise fleet drivers to physical charging stations across the Vietnamese national transportation corridor.

1.4.1 Functional Inclusions

• Driver Lifecycle & Security: Secure phone OTP onboarding, dual-tab login (phone+password or phone+OTP), 24-hour lockout defenses, profile avatar management, and outstanding negative balance tracking.
• Station Discovery & Navigation: High-performance interactive map with marker clustering, multi-standard connector filters (Type 2, CCS 2, CHAdeMO, GB/T AC, GB/T DC), real-time connector availability, and external map routing (Google Maps, Apple Maps).
• Optical QR Scanning & Session Configuration: Fast camera barcode scanning with torch and photo gallery support, manual code entry, and preset charging budget selection (100k, 200k, 300k, 500k, 800k, 1M VND).
• 5-Phase Charging State Machine: Real-time progression through plug, connecting (with 1,800 ms hardware stabilization delay), charging (with 10-second telemetry polling: kW, kWh, battery SoC %, accrued cost, elapsed duration), and graceful termination (success or canceled).
• Vehicle Garage & Fleet Constraints: Vehicle registration linked to Vehicle Identification Numbers (VIN), status indicators, and driver-configured per-session spending caps (maxPointPerSession).
• Physical RFID Charge Cards: Management of physical RFID charge cards (charge-card) across life cycle tabs (ALL, ACTIVE, EXPIRING_SOON, USED_UP, EXPIRED), and instant balance redemption via physical scratch card codes (POST /api/v1/wallet/cards/activate).
• Financial Wallet & Ledger: EVP digital point wallet adhering strictly to 1 EVP = 1,000 VND, multi-channel top-ups via VNPay in-app webviews, transaction history, and double-entry ledger audits.
• Statutory VAT Invoicing: Corporate and personal electronic VAT invoice profile management (compliant with Vietnamese tax regulations), automated invoice generation against top-up events, and binary PDF streaming and sharing.
• Communications & Engagement: REST-based notification inbox with unread tracking, and native Expo Push Notification channels (default, charging).

1.4.2 Functional Exclusions

• Zero Retail Operations: The application does NOT support physical goods purchasing, merchant portals, or parcel logistics.
• Streamlined Communications: The application does NOT utilize legacy WebSocket messaging channels; real-time updates are driven exclusively by disciplined HTTP REST polling and native Expo Push Notifications.

1.5 References & Industry Standards

The system design conforms to the following standards, protocols, and regulatory statutes:

• IEEE Std 830-1998: IEEE Recommended Practice for Software Requirements Specifications.
• OCPP 1.6-J & OCPP 2.0.1: Open Charge Point Protocol JSON over WebSockets, Open Charge Alliance.
• RFC 6749: The OAuth 2.0 Authorization Framework.
• RFC 7519: JSON Web Token (JWT) Architecture.
• RFC 2119: Key words for use in RFCs to Indicate Requirement Levels.
• Expo SDK 54 / React Native 0.81.5: Modern mobile cross-platform framework utilizing the New Architecture (Fabric Renderer and TurboModules).
• Decree 123/2020/ND-CP & Circular 78/2021/TT-BTC: Legal regulations governing electronic invoices, tax codes, and digital financial reporting in the Socialist Republic of Vietnam.

2. Overall Description

2.1 Product Perspective & System Topology

The EV Power Mobile Application operates as a critical node within a distributed, high-availability electric mobility ecosystem. Built upon Expo SDK 54 and React Native 0.81.5 with the New Architecture enabled, the mobile client connects securely over HTTPS / TLS 1.3 to the cloud-native EV Power Edge API Gateway using RFC 6750 Bearer JSON Web Tokens (JWT).

Downstream from the API Gateway, the system orchestrates charging hardware via the Central Charge Point Management System (CPMS) executing OCPP 1.6-J and 2.0.1 protocols over WebSockets, coordinates financial transactions with third-party payment gateways (VNPAY), pushes critical charging alerts via the Expo Push Notification Service (APNs/FCM), and interfaces with the General Department of Taxation for statutory electronic VAT invoice dispatch.

2.2 Product Functions Summary

The following matrix summarizes the 8 primary functional areas of the EV Power mobile application, mapping each capability to its business purpose, targeted user personas, and engineering priority:

2.3 User Classes & Persona Hierarchy

The system defines four distinct user classes with specific privileges and system access boundaries:

2.3.1 Guest (Unauthenticated EV Driver)

An unregistered or logged-out user launching the mobile application. Guests have read-only access to public station infrastructure data.

• Permissions: Browse interactive map, search stations by location and connector standard, view station operating hours, hotline, and tariffs. Access language preferences (en, vi, zh-Hans) and Help Center FAQs.
• Restrictions: Cannot initiate optical QR scans, cannot configure charging sessions, cannot access digital wallet or vehicle garage. Attempting protected actions presents an authenticated login modal.

2.3.2 Authenticated EV Driver (Individual User)

A verified consumer EV driver with an active phone number and authenticated session.

• Permissions: Full access to all 8 functional areas. Can register personal electric vehicles, initiate camera QR scanning, configure charging sessions, monitor live telemetry, execute VNPay wallet top-ups, link RFID Charge Cards, activate scratch cards, manage personal VAT invoice profiles, and receive push notifications.
• Restrictions: Cannot initiate a session if wallet balance is below 100 EVP or if account is flagged with chargingBlocked: true due to unsettled negative debt.

2.3.3 Commercial Fleet Driver / Operator

A professional corporate driver or fleet manager operating enterprise-owned electric vehicles (taxis, delivery vans, corporate fleet).

• Permissions: Inherits all Authenticated EV Driver privileges. Additionally utilizes corporate VAT invoice profiles with enterprise tax codes (buyerTaxCode) for centralized tax deduction, and configures strict per-vehicle spending caps (maxPointPerSession) to enforce corporate energy allowances.
• Restrictions: Charging sessions automatically terminate if the session energy cost reaches the vehicle's assigned maxPointPerSession ceiling.

2.3.4 System Administrator & CPMS Operator (External Boundary)

Centralized back-office engineering and operations personnel interacting through enterprise web consoles (outside mobile client boundary).

• Capabilities: Provision charge boxes, configure connector tariffs (VND per kWh), review OCPP heartbeat logs, manage RFID point lots, and inspect double-entry financial ledger records.

2.4 Operating Environment & Runtime Architecture

The EV Power Mobile Application is built on modern cross-platform mobile standards to ensure native performance, hardware security, and long-term maintainability:

2.5 Design & Implementation Constraints

The system is governed by strict architectural, mathematical, and security invariants:

• Strict Conversion Rate Invariant: The rate 1 EVP = 1,000 VND is immutable across the entire software ecosystem. No user or screen may apply alternative ratios.
• Minimum Balance Charging Gate: A driver MUST maintain a minimum balance of 100 EVP (100,000 VND) in their digital wallet to authorize the initiation of a charging session.
• Single Active Session per Connector: An EVSE connector can service exactly one vehicle at any time. If a connector reports status other than AVAILABLE, session initiation is rejected.
• Strict Polling Cadence: During pre-charge (plug step), connector status is polled every 5,000 ms (connectorStatusMs). During active charging, session telemetry is polled every 10,000 ms (transactionDetailMs). The physical handshake delay enforces a minimum wait of 1,800 ms (connectingMinDurationMs) to prevent hardware race conditions.
• 401 JWT Refresh Mutex Lock: If multiple concurrent API requests receive HTTP 401 Unauthorized, an interceptor mutex lock ensures that exactly ONE token refresh request is dispatched to POST /api/v1/auth/refresh, while all other requests are queued in a Promise array until the new token is acquired.
• 24-Hour Account Lockout Defense: If a user fails OTP or password verification 5 consecutive times within a 15-minute window, the account is locked for 24 hours to prevent brute-force credential stuffing.

2.6 Assumptions & Upstream Dependencies

• CPMS & Charger Hardware SLA: The Central Charge Point Management System communicates with physical chargers via OCPP 1.6-J / 2.0.1 over cellular/Ethernet. Charger heartbeat latency is assumed ≤ 2,000 ms, and remote start/stop acknowledgment latency is assumed ≤ 3,000 ms.
• Expo Push Notification Delivery: Remote charging lifecycle push notifications (ORDER_CREATED, CHARGING_STOPPED) rely on Apple Push Notification service (APNs) and Google Firebase Cloud Messaging (FCM). Device network connectivity is assumed.
• Payment Gateway Availability: VNPAY payment processing and instant payment notification (IPN) webhooks operate with an assumed 99.9% uptime SLA.
• Tax Authority Invoicing Engine: Electronic VAT invoice XML signing and verification comply with Vietnam General Department of Taxation digital certificate infrastructure.

3. Specific Requirements

Part 3.A: External Interface Requirements

3.A.1 User Interfaces & Screen Hierarchy

The EV Power mobile client user interface is structured using Expo Router v6 file-based routing. All application routes, screens, and authentication guards are cataloged below:

3.A.2 Hardware & Physical Device Interfaces

The mobile application interacts directly with mobile device hardware peripherals:

• Camera Hardware Subsystem (expo-camera): The application accesses the device camera sensor with hardware-accelerated 2D optical barcode recognition configured strictly for qr types. Provides real-time viewfinder rendering, hardware LED torch control for low-light charging environments, camera lens flipping, and photo library optical decoding via expo-image-picker.
• Geolocation Hardware Subsystem (expo-location): Utilizes balanced-power and high-accuracy GPS positioning sensors to compute current driver coordinates. Coordinates are used to calculate Haversine great-circle distances to nearby stations, cluster pins within bounding viewports, and launch native external navigation apps (Apple Maps, Google Maps) via Linking.openURL().
• Secure Enclave Subsystem (expo-secure-store): Hardware-backed cryptographic storage utilizing the iOS Keychain Services and Android KeyStore System with AES-256 encryption. Stores accessToken, refreshToken, and password recovery resetToken. Prevents extraction via device backup or filesystem inspection.
• Network Radio Sensing (@react-native-community/netinfo): Monitors active cellular (4G/5G) and Wi-Fi radio states. Automatically presents a non-intrusive offline status indicator when reachability is lost, and immediately triggers TanStack Query cache re-synchronization upon network reconnection.

3.A.3 Software / REST API Catalog

The EV Power mobile client interfaces with 10 backend domain microservices via 50+ strongly-typed REST endpoints over HTTPS. Every endpoint adheres to strict request/response schemas:

3.A.4 Communications Interfaces

• Transport Protocol: All client-to-gateway traffic SHALL transmit over HTTPS / TLS 1.3 on TCP port 443 with strict cipher suite enforcement. Unencrypted HTTP traffic is rejected.
• Authentication Tokens: All protected API requests MUST carry an RFC 6750 Bearer JSON Web Token in the Authorization request header.
• Asynchronous Push Messaging: Event-driven charging milestone notifications (ORDER_CREATED, CHARGING_STOPPED, TOPUP_SUCCESS, CARD_ACTIVATED) are pushed via Apple APNs and Google FCM through the Expo Push Notification broker.

Part 3.B: System Features & Functional Requirements

3.1 User Authentication, Session & Driver Profile

Governs driver identity verification, dual-channel credentials, session token lifecycles, profile metadata, and financial debt checks.

3.2 Charging Stations & Connectors Discovery

Governs geospatial station discovery, marker clustering, connector standard filtering, station amenities, and real-time connector status monitoring.

3.3 QR Code Scanning & 5-Step Charging Session Flow

Specifies the core operational workflow of the application: optical QR recognition, pre-charge session budgeting, the 5-phase charging state machine, live telemetry monitoring, and order receipt reconciliation.

3.4 Vehicle Garage & Fleet Management

Governs the registration of driver electric vehicles, Vehicle Identification Number (VIN) binding, vehicle operational status, and per-session spending caps.

3.5 RFID Charge Cards (charge-card / Thẻ sạc RFID)

Governs the lifecycle of physical RFID charge cards, category status filtering, point lot expiration tracking, and balance top-up via physical scratch card activation codes.

3.6 EVP Wallet & Financial Transactions

Specifies the digital point wallet, the strict 1 EVP = 1,000 VND conversion standard, VNPay payment gateway integration, transaction logs, and the double-entry point ledger audit trail.

3.7 Invoices & VAT Invoice Profiles

Governs statutory electronic Value-Added Tax (VAT) invoice profiles, automated invoice generation linked to top-up transactions under Vietnamese tax law, and digitally-signed PDF export.

3.8 Notifications (Push & In-App Alerts)

Governs the REST notification feed, unread counters, and native Expo Push Notification channels for charging milestones.

Part 3.C: Non-Functional Requirements

3.C.1 Performance Requirements

3.C.2 Safety Requirements

3.C.3 Security & Cryptographic Requirements

3.C.4 Software Quality Attributes

4. Appendices, Canonical Data Models & Enums

4.1 Technical Glossary & Domain Acronyms

4.2 Canonical Domain Data Models (TypeScript Interfaces)

The following canonical TypeScript interfaces represent the core entities utilized across services, state stores, and UI components:

4.2.1 Station & Connector Models

/**
 * Core charging station specifications and facility details.
 */
export interface StationDetail {
  stationId: string;
  code: string;
  name: string;
  address: string;
  latitude: number;
  longitude: number;
  status: 'ACTIVE' | 'INACTIVE' | 'MAINTENANCE';
  is24h: boolean;
  images: string[];
  operator: {
    name: string;
    hotline: string;
  };
  amenities: ('RESTROOM' | 'COFFEE' | 'CONVENIENCE_STORE' | 'WIFI' | 'PARKING_FEE')[];
  chargingPoints: ChargePointSummary[];
  pricingSummary: StationPricingItem[];
}

/**
 * Individual physical connector hardware specifications.
 */
export interface ConnectorDetail {
  connectorId: string;
  chargeBoxCode: string;
  connectorNo: number;
  stationName: string;
  connectorType: 'TYPE_2' | 'CCS_2' | 'CHADEMO' | 'GB_T_AC' | 'GB_T_DC' | 'TYPE_1';
  powerType: 'AC' | 'DC';
  maxPowerKw: number;
  status: 'AVAILABLE' | 'PREPARING' | 'IN_USE' | 'RESERVED' | 'UNAVAILABLE' | 'FAULTED' | 'OFFLINE';
  unitPrice: number; // in EVP per kWh
  currency: 'EVP';
  pricingPlanId: string;
  priceDescription: string;
}

4.2.2 Charging Session & Order Models

/**
 * Real-time telemetry payload during active charging.
 */
export interface TransactionDetailResponse {
  transactionId: string;
  orderId: string;
  chargeBoxCode: string;
  connectorNo: number;
  socPercent: number; // 0 to 100% (null or 0 on AC stations lacking BMS telemetry; triggers BR-CHG-06 fallback)
  energyWh: number;   // Watt-hours consumed
  maxPowerKw: number; // Instantaneous charging speed
  powerType: 'AC' | 'DC';
  estimatedPoint: number; // Accrued cost in EVP
  estimatedFinishAt: string; // ISO timestamp
  durationSeconds: number;
  status: 'PREPARING' | 'CHARGING' | 'SUSPENDED_EV' | 'SUSPENDED_EVSE' | 'STOPPED';
}

/**
 * Finalized historical charging session order record.
 */
export interface ChargingOrder {
  id: string;
  orderCode: string;
  stationName: string;
  chargeBoxCode: string;
  connectorNo: number;
  connectorType: string;
  startAt: string;
  stopAt: string;
  durationMinutes: number;
  energyWh: number;
  totalPoint: number; // Total points billed
  paidPoint: number;  // Points settled from wallet
  outstandingPoint: number; // Negative debt points if any
  status: 'CHARGING' | 'COMPLETED' | 'FAILED' | 'CANCELED';
}

4.2.3 Vehicle & RFID Charge Card Models

/**
 * Electric vehicle entity registered in driver garage.
 */
export interface Vehicle {
  id: string;
  userId: string;
  vin: string; // 17-character ISO 3779 identifier
  label: string; // License plate or custom moniker
  status: 'active' | 'inactive' | 'blocked';
  maxPointPerSession: number; // Spending ceiling in EVP
  chargeable: boolean;
  blockedReason?: string | null;
  createdAt: string;
}

/**
 * Physical RFID Charge Card entity (charge-card).
 */
export interface ChargeCard {
  cardId: number;
  serial: string;
  cardMasked: string; // e.g., "•••• 8821"
  batchName: string;
  facePoint: number;
  activatedAt: string;
  pointLotId: number;
  pointUsed: number;
  pointRemaining: number;
  pointExpired: number;
  pointExpireAt: string;
  state: 'ACTIVE' | 'EXPIRING_SOON' | 'USED_UP' | 'EXPIRED';
  daysToExpire: number;
}

4.2.4 Wallet, Ledger & VAT Invoice Models

/**
 * Double-entry financial point ledger audit record.
 */
export interface LedgerEntry {
  id: number;
  entryType: 'TOPUP' | 'CHARGE_DEDUCT' | 'CARD_ACTIVATE';
  pointChange: number; // Positive for credits, negative for debits
  balanceAfter: number; // Post-transaction balance in EVP
  orderId?: number; // Linked charging session order ID
  topupId?: number; // Linked VNPay top-up ID
  createdAt: string;
}

/**
 * Statutory electronic VAT invoice billing profile.
 * Note: buyerName and buyerTaxCode represent legal statutory tax fields.
 */
export interface InvoiceProfile {
  id: string;
  userId: string;
  profileType: 'PERSONAL' | 'COMPANY';
  buyerName: string;      // Legal individual or corporate name
  buyerTaxCode?: string;  // Enterprise tax identification number
  buyerAddress: string;   // Registered fiscal address
  buyerEmail: string;     // E-invoice delivery email
  buyerPhone: string;     // Contact telephone number
  isDefault: boolean;
  createdAt: string;
  updatedAt: string;
}

/**
 * Electronic VAT tax invoice response model.
 */
export interface InvoiceDetailResponse {
  id: string;
  invoiceNo: string;
  topupId: string;
  createdAt: string;
  subtotal: number;       // Amount in VND excluding VAT
  taxAmount: number;      // Calculated VAT in VND
  totalAmount: number;    // Gross amount paid in VND
  currency: 'VND';
  buyerName: string;
  buyerTaxCode?: string;
  buyerAddress: string;
  buyerEmail: string;
  buyerPhone: string;
  taxLines: {
    taxCode: string;
    taxRate: number; // e.g., 0.10 for 10%
    taxableAmount: number;
    taxAmount: number;
  }[];
  displayStatus: 'ISSUED' | 'PROCESSING' | 'NEEDS_SUPPORT';
  downloadable: boolean;
}

4.3 Status Enumerations & State Machines

4.3.1 Connector Operational Status (ConnectorStatus)

4.3.2 Charge Card Lifecycle State (ChargeCardState)

4.4 Vector Architecture & Sequence Diagrams