rapport_step1.md

title	First architecture ISA
author	Equipe C (FALCOZ Alban, GALLI Evan, GRIPARI Alexandre, LASSAUNIERE Theo, LUBRAT Jilian, MICHELOZZI Antoine-Marie)

I. Hypothesis

• For the moment, there is no points system to utilize the advantages and discounts. It simply depends on whether you have access or not. For example, if the customer is a VFP, they can only use one VFP advantage per week. However, this system may evolve in the future.
• To become a VFP member, the customer must make at least three purchases at a partner business within the last 7 days.
• The service is a monthly subscription service.
• The discounts are automatically deducted at the payment, but the advantages must be activated by the customer before the payment to be used.

II. Use Case

A. Primary actors

• Pierre (Customer)
• Laura (Partner)
• Laurence (Partner)

B. Secondary actors

• HappyKids (Affiliated Business)
• Bank

C. Use case diagram

Explanations

• Subscribe to service: Customers can subscribe to the service in order to obtain their own card to take advantage of the benefits. There is a charge for this subscription, which involves communicating with the Bank.
• Consult benefits: Customers can view all the benefits available with the card, whether they have VFP status or not.
• Activate benefits: Once a customer has selected a benefit, he can activate it if it is not a pre-activated benefit.
• Consult transactions history: A user, customer or partner must be able to obtain a list of the services they have received/applied respectively.
• Get order price: Partners need to retrieve the price of a new order before the customer proceeds with payment.
• Simulate benefits: Customers can simulate their potential benefits to determine what they might receive. Before paying an order, partners and affiliated business use this simulation to calculate the order price. However, some partners or affiliated business prefer to calculate the order's new price within their own system.

III. Components

• PartnerRegistery: The PartnerRegistry component manages the registration of partners. It serves as the link between the PartnerRepository, the TransactionHandler, and the PartnerController, enabling the PartnerController and the TransactionHandler to find a partner in the repository.
• TransactionHandler: This component handles the transactions. It receives demands from the TransactionController to get the benefits with the interface TransactionProcessor and uses the interface Payment, BenefitsGetter, PartnerFinder and ItemFinder to get respectivly : the payment, the benefits that can be applied, the partner and the items.
• Benefits: This component handles the benefits. It receives demands from the BenefitsController to get the benefits with the interface BenefitsGetter and uses the interface Benefits, CustomerStatusGetter, ItemFinder and AffiliatedBusiness to get respectivly : the benefits of the affiliated business, the customer status (subscribed / vfp / not subscribed), the offered item and ordered item and the affiliated business.
• Cashier: This component save a transaction. He receives demands and the Payment from the TransactionHandler. It uses the interface HistoryAdder to be able to add the transaction to the history and the AffiliatedBusiness to get the price to pay.
• ItemRegistry: The ItemRegistry component manages the registration of items. It serves as the link between the ItemRepository, the TransactionHandler, the Benefits and the ItemController enabling the ItemRepository and the TransactionHandler, the Benefits and the ItemController to find a item in the repository.
• BenefitsHistoryService: This component is used to manage the benefits history. It uses the History interface of the TransactionHistoryRepository to obtain history data. It allows the Cashier component to add transactions to the history via the HistoryAdder interface and to search the history via the HistoryFinder interface.
• CustomerStatus: This component receives information from both the HistoryController and the SubscriptionController, using the HistoryFinder and SubscriptionStatus interfaces respectively. It uses the information obtained to identify the customer's status and calculate the benefits accordingly.
• CustomerSubscription: This component enables a customer to be subscribed, and the status of a customer to be obtained (subscribed or not). To subscribe a customer, it will receive the customer via the CustomerFinder interface from CustomerController, and make the payment via the Bank interface. Then, to retrieve the status of the customer, it will obtain the information from the Subscruption interface from the SubscriptionRepository.
• CustomerService: This component manages customers, making it possible to respond to requests to search for and register a customer. It receives customers via the Customer interface of the CustomerRepository and uses the CustomerFinder and CustomerRegistration interfaces respectively to respond to registration requests and customer searches.

IV. Interfaces

/** Provides methods to retrieve a customer by their ID or retrieve all customers in the system */
public interface CustomerFinder {
    Customer findById(Long customerId) throws CustomerNotFoundException;
    List<Customer> findAll();
}

/** Handles the registration of new customers. */
public interface CustomerRegistration {
    void registerCustomer(String name) throws CustomerAlreadyExistsException;
}

/** Provides methods to retrieve a partner by their ID or retrieve all partners in the system */
public interface PartnerFinder {
    Partner findById(Long partnerId) throws PartnerNotFoundException;
    List<Partner> findAll();
}

/** Subscribe a customer to the fidelity service */
public interface Subscribe {
    Subscription subscribeCustomer(Long customerId) throws CustomerNotFoundException;
}

/** Check if the customer is subscribed and retrieves their subscribtion details */
public interface SubscriptionStatus {
    boolean isSubscribed(Long customerId);
    Subscription getSubscription(Long customerId) throws SubscriptionNotFoundException;
}

/** Add a transaction to the history */
public interface TransactionProcessor {
    void addTransaction(Transaction transaction) throws PartnerNotFoundException, SubscriptionNotFoundException;
}

/** Retrieves the transaction history for a specific customer or partner */
public interface HistoryFinder {
    List<Transaction> getTransactionHistory(Long customerId) throws CustomerNotFoundException;
    List<Transaction> getPartnerTransactionHistory(Long partnerId) throws PartnerNotFoundException;
}

/** Finds items by ID or retrieves the list of item of a partner */
public interface ItemFinder {
    Item findById(Long itemId) throws ItemNotFoundException;
    List<Item> findByPartnerId(Long partnerId);
    List<Item> findAll();
}

/** Adds a transaction to the history */
public interface HistoryAdder {
    void addTransactionToHistory(Transaction transaction) throws CustomerNotFoundException;
}

/** Retrieves all the benefits, all  available for a specific customer, the benefits applicable for a transaction */
public interface BenefitsGetter {
     List<Benefit> getAllBenefits();
     List<Benefit> getAvailableBenefits(Long customerId) throws CustomerNotFoundException;
     Benefit getBenefitForTransaction(Transaction transaction);
}

/** Activate the benefits if the customer has requested it */
public interface BenefitsActivator {
     void activateBenefit(Long customerId, Long benefitId) throws CustomerNotFoundException, BenefitNotFoundException, BenefitUnavailableExecption;
}

/** Check if a customer is subscribed or has a VFP status */
public interface CustomerStatusGetter {
    boolean isVFP(Long customerId);
    boolean isSubscribed(Long customerId);
}

/** Retrieves all subscriptions or a subscription for a specific customer */
public interface Subscription {
    List<Subscription> findAll();
    Subscription findByCustomerId(Long customerId);
    void addSubscription(Subscription subscription);
}

/** Processes payment transactions using a card number and amount, throwing an exception if payment fails */
public interface Bank {
    boolean processPayment(String cardNumber, double amount) throws PaymentFailedException;
}

/** Calculates the price and adds the transaction to the history */
public interface Payment {
    void markAsPayed(Transaction transaction, Benefit benefit);
}

/** Manages customer data, including retrieving, adding, and searching customers */
public interface Customer {
    List<Customer> findAll();
    Customer findById(Long customerId);
    void addCustomer(Customer customer);
}

/** Transfers the transaction and the benefits to the affiliated business, allowing it to calculate the transaction price */
public interface AffiliatedBusiness {
    double getPriceToPay(Transaction transaction, Benefit benefit);
}

/** Retrieve or add transaction to the history */
public interface History {
    List<Transaction> getCustomerHistory(Long customerId);
    List<Transaction> getPartnerHistory(Long partnerId);
    void addTransaction(Transaction transaction);
}

/** Retrieve all the benefits or a specific beneit*/
public interface Benefits {
    List<Benefit> findAll();
    Benefit findById(Long benefitId);
}

V. Business objects

classDiagram
    class Customer {
        id : Long
        name : String
        cardNumber : String
    }
    
    class Partner {
        id : Long
        name : String
        distantServer : String
    }
    
    class Transaction {
        id: Long
        date : LocalDateTime
        price : double
        subPrice : double
    }

    class Benefit {
        id : Long
        discount: double
        description: String
    }
    
    class Subscription {
        id : Long
        endDate : LocalDateTime
        barcode : String
    }
    
    class Item {
        id : Long
        name : String
        price : double
    }
    
    class TypeOfBenefits {
        <<enumeration>>
        FLAT_REDUCTION
        REDUCTION
        FREE_ITEM
    }
    
    Item "*" --> "partner 1" Partner : belongs to ▸
    Customer "customer 1" <-- "*" Transaction : performs ▸
    Customer "customer 1" <--* "1" Subscription : has ▸
    Transaction "*" --> "partner 1" Partner : associated with ▸
    Transaction "*" --> "benefit *" Benefit : applies ▸
    Transaction "*" --> "item 1..*" Item : contains ▸
    Benefit "*" --> "item *" Item : references ▸
    Benefit "*" --> "1 type" TypeOfBenefits : has type ▸

Loading

Explanations

• The Customer class represents a user of the application who has subscribed to our service. It contains attributes such as id, name, and the cardNumber of the customer. Customers are the central actors in the system. In the "Subscribe to service" use case, a customer is registered and linked to a subscription. Additionally, the customer is involved in the "Consult transactions history" and "Consult benefits" use cases to review their past activity and available advantages.
• The Subscription class models the registration of a customer. Each subscription is uniquely identified by its id and contains attributes such as endDate to indicate the validity period, which is typically one month from the subscription date, and the barCode of the multi-fidelity card. The use case ‘Subscription to a service’ involves the creation of a subscription for the customer during the registration process.
• The Transaction class represents a record of a customer’s purchase or operation within the system. It contains attributes such as date for the timestamp of the transaction, price for the total amount before discounts, and subPrice for the final amount after applying benefits. Each transaction involves a specific customer, one or more items purchased, and any applicable benefits. Transactions are also linked to a partner, representing the business facilitating the purchase. This class is necessary to the "Consult transactions history" use case, where customers can review their previous purchases.
• The Partner class represents the company that proposes benefits for a multi fidelity card user. They are identified by a unique id and characterized by a name. Each partner offers a multitude of items, and is linked to all transactions carried out in its company.
• The Item class represents the products or services that customers can purchase or receive as benefits. Each item is characterized by attributes such as id, name, and price. Items belong to a specific partner and are also referenced in benefits, enabling features like discounts or free products.
• The Benefit class encapsulates advantages available to customers, such as discounts or free items. It includes attributes like id, discount, and description to describe the benefit and its conditions. Each benefit is associated with a single type from the TypeOfBenefits enumeration, which defines whether the benefit offers a flat reduction, percentage reduction, or free item. Additionally, benefits may reference specific items to apply targeted offers. Benefits are integral to use cases like "Consult benefits," "Simulate benefits," and "Activate benefits," where customers explore, calculate, and apply their advantages.
• The TypeOfBenefits class is an enumeration that defines the available types of benefits in the system: FLAT_REDUCTION for fixed discounts, REDUCTION for percentage-based discounts, and FREE_ITEM for free products.

VI. Scenarios

Customer Subscription

(CLI -> SubscriptionController -> CustomerSubscription -> SubscriptionRepository)

• A customer subscribes to the service and obtains his multi-fidelity card.

Checking the benefits with an affiliated business

(CLI -> BenefitController -> TransactionHandler -> Benefits -> AffiliatedBusinessProxy -> AffiliatedBusinessSystem)

• The customer enters the requested information.
• The system queries the HappyKids partner to verify the information and get the reduction.

Checking the benefits without affiliated businesses

(CLI -> BenefitController -> TransactionHandler -> Benefits)

• The customer checks if a 10% discount is applicable after 6:30 PM, without interaction with an external partner.

Activation of an advantage at the time of payment

Payment at HappyKids

(CLI -> BenefitController -> TransactionHandler -> Cashier -> AffiliatedBusinessProxy -> AffiliatedBusinessSystem)

• The customer presents their multi-fidelity card to the partner.
• The partner requests the system to calculate the amount to be paid, considering the discounts defined by HappyKids.

Payment at the Bakery

(CLI -> BenefitController -> TransactionHandler -> Cashier)

• The customer presents their multi-fidelity card to the partner.
• The partner directly obtains the reduced price to be paid without external interaction.

Viewing the advantages used by the customer

(CLI -> HistoryController -> BenefitsHistoryService -> TransactionHistoryRepository)

• The customer views the list of advantages they have benefited from.

Viewing the advantages used by a partner's customers

For HappyKids

(HistoryController -> BenefitsHistoryService)

• The partner views the number of free childcare hours used to analyze their distribution.

For the Bakery

(HistoryController -> BenefitsHistoryService)

• The partner reviews purchases made after 6:30 PM to evaluate their impact on losses.