Wang Chao - Project Portfolio

PROJECT: Inventory Manager

1. Overview

This portfolio aims to showcases my ability to work in a software development team. It also documents my contribution to the project of our team, the Inventory Manager. There are mainly two part of my contributions, codes and documentations.

Inventory Manager is for Small to Medium Enterprises (SMEs) who prefer to use a desktop app to manage their shop inventory. More importantly, it is optimized for those who prefer to work with a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI). It has mainly three core features, including item management, sales management and reporting module. It also has two other special features including user authentication and purchase order management.

For Inventory Manager, I have designed and implemented the Reporting Module of the product. It mainly provides the users with the ability to export and import the data of Inventory Manager to and from the outer system.

2. Summary of Contributions

Below is a summary of the contributions I have made to the Inventory Manager.

Major enhancement: Added the Reporting Module of Inventory Manager.
- What it does: This feature allows the user to to export and import data for report analysis.
- Justification: This feature is critical for Inventory Manager. Without this feature, users will not be able to have further analysis of the data using other applications.
- Highlights: The file format that this feature support is CSV file, which can be interacted directly with Excel.
Minor enhancement:
- Improved the structure of existing Model and Storage Component.
- Added the table views of different elements in the Inventory Manager.
- Added support for undo/redo feature for the Reporting Module.
Code contributed: [Reposense]
Other contributions:
- Project management:
  - Called for several meetings for the project.
  - Managed release v1.3.1 on GitHub [GitHub]
- Documentation:
  - Added the section on Reporting Module to the User Guide (Pull requests #18)
  - Added the use cases of Reporting Module to the Developer Guide (Pull requests #18)
  - Added the implementation of Export Command to the Developer Guide (Pull requests #77)
  - Edited the existing implementation of undo/redo feature in the Developer Guide (Pull requests #191)
- Community:
  - Reviewed Pull Requests of my teammates[Pull Requests]
  - Reported bugs for other teams in the class [Issues]

3. Contributions to the User Guide

Given below are sections I contributed to the User Guide. They showcase my ability to write documentation targeting end-users.

3.1. Reporting Module

The following commands are mainly used to export and import data for report analysis.
All the commands in this section are available to admin only.

3.1.1. Exporting data to CSV: `export-csv`

This command exports the data to the file specified by FILEPATH.
FILEPATH must end with an extension of .csv.
FILEPATH can be a relative path and the data will be exported to a location relative to the Inventory Manager installation directory.
Existing data file at FILEPATH will be overwritten.
The parent directories will be created if they do not exist.
A table view of the exported data will appear.
CSV files can be opened and edited by Excel.

Exporting sales report to CSV: `export-csv-sales`

The export-csv-sales command exports the sales report in CSV format to the file path given.

Format: export-csv-sales f/FILEPATH

Example: export-csv-sales f/E:/out/sales.csv

Exporting list of items to CSV : `export-csv-items`

The export-csv-items command exports the list of items in CSV format to the file path given.

Format: export-csv-items f/FILEPATH

Example: export-csv-items f/E:/out/items.csv

Following screenshot showcases what will happen when you enter the correct export-csv-items command:

Figure 1. Export successful prompt will be shown upon completion of export.

Exporting list of users to CSV: `export-csv-staffs`

The export-csv-staffs command exports the list of users in CSV format to the file path given.

Format: export-csv-staffs f/FILEPATH

Example: export-csv-staffs f/E:/out/staffs.csv

Exporting list of purchase orders to CSV: `export-csv-orders`

The export-csv-orders command exports the list of purchase orders in CSV format to the filepath given.

Format: export-csv-orders f/FILEPATH

Example: export-csv-orders f/E:/out/orders.csv

3.1.2. Importing data from CSV: `import-csv`

This command imports the data from the file specified by FILEPATH.
FILEPATH must end with an extension of .csv.
FILEPATH can be a relative path and the data will be imported from a location relative to the Inventory Manager installation directory.
Original data in Inventory Manager will be overwritten.
Data in the CSV file must be recognizable by Inventory Manager.

Importing sales report from CSV: `import-csv-sales`

The import-csv-sales command imports the sales report in CSV format from the file path given.

Format: import-csv-sales f/FILEPATH

Example: import-csv-sales f/E:/in/sales.csv

Following screenshot showcases what will happen when you enter the correct import-csv-sales command:

Figure 2. Import successful prompt will be shown upon completion of import.

Importing list of items from CSV : `import-csv-items`

The import-csv-items command imports the list of items in CSV format from the file path given.

Format: import-csv-items f/FILEPATH

Example: import-csv-items f/E:/in/items.csv

Importing list of users from CSV: `import-csv-staffs`

The import-csv-staffs command imports the list of users in CSV format from the file path given.

Format: import-csv-staffs f/FILEPATH

Example: import-csv-staffs f/E:/in/staffs.csv

Importing list of purchase orders from CSV: `import-csv-orders`

The import-csv-orders command imports the list of purchase orders in CSV format from the file path given.

Format: import-csv-orders f/FILEPATH

Example: import-csv-orders f/E:/in/orders.csv

4. Contributions to the Developer Guide

Given below are sections I contributed to the Developer Guide. They showcase my ability to write technical documentation and the technical depth of my contributions to the project.

4.1. Export CSV mechanism

In order to enable users to have further analysis of the data in Inventory Manager, we support several export-csv commands to export the data in Inventory Manager to CSV files. We are using export-csv-items, export-csv-sales, export-csv-staffs, export-csv-orders to support exporting of Inventory Manager data through CSV files.

In the following sections, we will focus on how these commands depend on the Model and Storage component to retrieve external data and where to validate the given file path.

4.1.1. Implementation

Data access

In order to achieve their tasks, all export commands require direct access to the data and output to the external environment. Unlike other commands, these commands highly depend on the Storage component. However, if we only directly set a Storage for the command and manipulate on the Storage in export command, we also need Storage component to directly access the data in Model component which will violate Single Responsibility Principle.

So we decide to use the same method as other command use to export data. When executing the export commands, a DataExportEvent will be raised in the EventsCenter through Model component. Since Logic directly has Model as one field, it will not violate the Single Responsibility Principle. Then, the handler function in Storage component will catch this DataExportingEvent and export data to the external environment.

File path validation

File paths, as required by export commands, need to be validated during the execution of the commands. However, where to implement it can be decided. It can be implemented in CommandParser or Command or even in Storage.

In our implementation, we choose to validate the file path during the execution of export Command. A static method in FileUtil will be called to test whether the given file path is valid when executing the command. In doing so, we are able to make sure that the path parameter passed to Model component and Storage component is a valid file path. Also, it is easier for the implementation of command feedback to the users. Further details can be found in the sequence diagram of the next section.

Sequence diagram

Considering that all the export commands have similar sequence diagrams. So we will just show the sequence diagrams for export-csv-items command to illustrate how the export commands work.

The Sequence Diagram below shows how the components interact for the scenario where the user issues the command export-csv-items f/items.csv.

Figure 3. Component interactions for export-csv-items f/items.csv command (part 1)

The diagram below shows how the EventsCenter reacts to that event, which eventually results in the item list being exported and the alert window of the UI being popped up to reflect the success of exporting.

Figure 4. Component interactions for export-csv-items f/items.csv command (part 2)

The diagram below is the lower level sequence diagram for export-csv-items f/items.csv command inside Logic component.

Figure 5. Lower level sequence diagram for export-csv-items f/items.csv command inside Logic component

4.1.2. Design considerations

Aspect: How `export` commands interact with `Storage` component and `Logic` component

Alternative 1 (current choice): Raises a DataExportEvent in the EventsCenter through Model and handles it in Storage.
- Pros: Avoids direct access of Storage from export commands. Does not violate the Single Responsibility Principle.
- Cons: Needs a middle Component to achieve the goal. Needs to raise an additional event.
Alternative 2: Couples Command with Storage
- Pros: Provides direct access to Storage for commands that is highly depend it.
- Cons: Needs directly access of data in Model component for Storage which will violate the Single Responsibility Principle.

Aspect: Location for implementation of file path validation and location to check file path validation

Alternative 1 (current choice): Implements in FileUtil and checks in export command.
- Pros: It’s sure that the path passed to Model component and Storage component is a valid file path. The implementation of command feedback is easier. File Validation is reusable in other component.
- Cons: File Validation needs to interact with Commons component.
Alternative 2: Implements in CommandParser and checks in CommandParser class.
- Pros: There is no need to interact with other component.
- Cons: File Validation is not reusable in other component.
Alternative 3: Implements in Storage and checks in Storage.
- Pros: There is no need to interact with other component. File Validation is reusable in other method of Storage.
- Cons: The path passed to Storage component may not be valid. The implementation of command feedback is more difficult. Storage needs to raise an additional event for invalid file path.

4.1.3. CSV file recognizing

Since Csv file do not have standardized format for storing objects. So we designed a format that need to be followed when importing csv files. If the process of importing fails due to unrecognizable failure, do check the file to import meets the requirement.

An example of recognizable csv file storing the items is reproduced below: (Opened with a Plain Text Editor,not Excel)

Item,,,,,
name,price,quantity,sku,image,tags
iPhone XR,1500.00,30,apple-iphone-xr,/images/iphone.jpg,"apple,iphone"
LG G7,1250.50,90,lg-g7,/images/lg.jpg,"smartphone,lg"
Samsung S9,1499.99,14,samsung-s9,/images/samsung.jpg,"samsung,smartphone"
HTC U6 ,999.00,88,htc-u6,/images/htc.jpg,"samsung,phablet"
Google Pixel XL,1435.90,3,google-pixel-xl,/images/google.jpg,google

The first two lines are headers to determine which kind of object is this csv file storing. Following lines are the details of the objects. Empty lines are not allowed. If a cell contains commas(,), it must be surrounded by double quotation marks(" ").

The required format can be gotten by simply exporting each kind of objects first.