# Team Joyful Developer Documentation

## Introduction

## Coding Conventions

## App Set-up

### **Download Android Studio**
Download: https://developer.android.com/studio?gclid=CjwKCAjwjMiiBhA4EiwAZe6jQzI-W5Pd7FLDvBRVDgoU1vGSg_05aiwN-qmXHHCkBpIiGdoYLP0CzhoC9RwQAvD_BwE&gclsrc=aw.ds

### **Dart & Flutter Installation**
1. Flutter Version 3.3.2 (Please make sure you use this version)
Download: https://docs.flutter.dev/release/archive?tab=windows
2. Dart Version 2.18.1
Download: https://dart.dev/get-dart/archive

## Version Control History

### 1.0.0 (2022 S1)
- Initial release in 2022 S1.

### 2.0.0 (2023 S1 - March)
- Brand new API path for website.
- Introduced new authentication system (JWT).

### 2.0.1 (2023 S1 - Late March)
- Bug fixes for search functionality.
- Bug fixes for language changing.
- Register API shift to JWT.

### 2.1.0 (2023 S1 - April)
- Minor changes to the UI.
- Login and profile API shift to JWT

### 2.2.0 (2023 S1 - Early May)
- Added product posting function.

### 3.0.0 (2023 S2 - Early August)
- Change to a new server Wordpress
- Set the settings of new server
- Change the project code to connect with the server

### 3.0.1 (2023 S2 - Middle August)
- Fix register function and adding email address pin code authentication function
- Fix login function

### 3.1.0 (2023 S2 - Late August)
- Allow users to update their billing and shipping address
- Retrieve product data and fix the display on the homepage and product details

### 3.2.0 (2023 S2 - Early September)
- Add recommend section in product detail page
- Adjust the layout of product detail page
- Update message page

### 3.3.0 (2023 S2 - Late September)
- Update the layout of main page
- Change the advertisement pictures
- Fix the checkout botton of cart page
- Link cart page to the product detail page by clicking the picture

### 3.4.0 (2023 S2 - Early October)
- Update layout of order list page
- Add price and color in upload page

## **Android Studio Configuration**
1. Flutter
2. Dart

## **Code Structure**

### Architecture Diagram

Here is a C4 architecture diagram for you convenience. Note that the UML diagram for classes is missing, as there is no tool that we can use to generate such one. It is one of the goals for next semester to manually create one.

[link to the C4 architecture diagram](https://app.diagrams.net/#G1GB__ENodwQG_5qktCma4obqBYf2xDQ_j)


### Software Design Patterns

We use MVC


- lib
- main.dart
- models
- user_model.dart
- ...
- views
- home_view.dart
- ...
- controllers
- user_controller.dart
- ...
- repositories
- user_repository.dart
- ...

Description of each directory and file:

main.dart: The entry point of your Flutter application where you initialize the app and configure routes.

models: This directory contains your data models. Each model represents a specific data entity in your app. For example, user_model.dart could define a User class.

views: This directory contains your UI components. Each view represents a specific screen or page in your app. For example, home_view.dart could define the home screen of your app.

controllers: This directory contains your controllers, which handle the business logic of your app. Controllers are responsible for managing state, making API calls, and handling user interactions. For example, user_controller.dart could define a UserController class that handles user-related operations.

repositories: This directory contains your repositories, which handle data fetching and manipulation. Repositories abstract away the data sources and provide a unified interface for accessing and modifying data. For example, user_repository.dart could define a UserRepository class that handles CRUD operations related to the User model.

## **Branching Strategy** ####

Main Branch (main or master): The main branch represents the production-ready state of the application. It should only contain stable, tested, and approved code.

Development Branch (Dev): The development branch serves as the integration branch for ongoing development work. It should contain features that are being actively developed and tested.

Feature Branches: Feature branches are created from the development branch and are used for implementing new features or making changes to existing ones. Each feature branch should have a descriptive name and be prefixed with "feature/". Example: feature/user-registration.

Bug Fix Branches: Bug fix branches are created from the development branch to address specific bugs or issues. Each bug fix branch should have a descriptive name and be prefixed with "bugfix/". Example: bugfix/authentication-issue.

Release Branches: Release branches are created from the development branch when preparing for a new release. They serve as a stabilization branch where final testing, bug fixing, and release-related tasks are performed. Each release branch should have a version number or a release name. Example: release/1.2.0 or release/summer-update.

Hotfix Branches: Hotfix branches are created from the main branch to address critical issues in the production environment. They should be used sparingly and merged back into both the main branch and the development branch once the fix is completed.

Commit Guidelines

Use descriptive commit messages that succinctly describe the changes made.
Start commit messages with a verb in the imperative form (e.g., "Add," "Update," "Fix," "Refactor").
Keep commits focused and avoid mixing unrelated changes.
Use branches for separate features, bug fixes, or enhancements.
Regularly push commits to the remote repository to enable collaboration and backup.

Pull Request Workflow

Create a new branch from the appropriate base branch (develop for features, main for hotfixes, etc.).
Implement the desired changes in the branch, committing and pushing regularly.
When the changes are ready for review, open a pull request (PR) on the repository.
Assign reviewers to the PR and provide a clear description of the changes made.
Reviewers should carefully inspect the code, provide feedback, and suggest any necessary changes.
Once the changes are approved, the PR can be merged into the base branch.
Delete the branch after merging to keep the repository clean.

Version Tagging

Use semantic versioning (e.g., v1.0.0) to tag releases in the main branch.
Tag releases after merging the release branch into the main branch.
Annotate tags with a brief description of the release.

Additional Tips

Regularly update your local repository with the latest changes from the remote repository (git pull) before starting new work.
Use .gitignore files to exclude unnecessary files or directories from version control.
Utilize Git hooks to automate tasks like code linting, formatting, and running tests before commits or pushes.

## How to Version

A version follows such a format:
`MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]`

### MAJOR Version

Increment the MAJOR version when you make incompatible API changes or introduce significant new features.

Examples: `1.0.0`, `2.0.0`, `3.0.0`

### MINOR Version

Increment the MINOR version when you add functionality in a backwards-compatible manner.

Examples: `1.1.0`, `1.2.0`, `2.1.0`

### PATCH Version

Increment the PATCH version when you make backwards-compatible bug fixes.

Examples: `1.0.1`, `1.0.2`, `1.1.1`

### Pre-release Version (-PRERELEASE) (optional)

Use a hyphen followed by a pre-release identifier to indicate a pre-release version.

Examples: `1.0.0-alpha`, `1.0.0-beta`, `2.0.0-rc.1`

### Build Metadata (+BUILD) (optional)

Use a plus sign followed by a build identifier to denote build metadata.

Example: `1.0.0+20130313144700`

Remember to increment the least significant version component necessary to reflect the nature of the changes.

Please note that this guideline provides a general template, and you can adapt it based on your specific needs or conventions.

## Work as a Back-end Developer

### **Shadow Website Setup**
The shadow Website we used is NOT free (Billing: US$30/month)
1. Host of server: https://my.vultr.com/
2. You have to register a new account for it. Currently we use team leader's personal account to hold. For next semester, we recommend to create a team account to hold it.

### Introduction to Server Configuration
You may need to access to server files to, for example, turn on/off a Wordpress plugin. In this case, you will need to find the `.hwaccess` file which is allocated in the root directory.

Before you edit a server file, MAKE SURE you ask the back-end team leader.

### Introduction to Code structure of our project
Before you start programming, you can review the structure of the program in general to make sure you have a general idea of what to expect.
https://github.com/JoyfulTechLauncher/docs/blob/dev/Code/Code-Structure.md

### Introduction to Code conventions
When you start contributing to projects, you need to know how to write code to make it more efficient and how to write code with fewer errors, and these simple rules can help you program better.
https://github.com/JoyfulTechLauncher/docs/blob/dev/Code/Code-Conventions.md

### Introduction to Our API(s)
Before you take steps into this section, you should make sure that you have learned basic knowledge about network programming. You need to at least know how HTTP requests work.

There are many excellent example online that help you get in handy quickly.

If you are more comfortable using English, just search for it on YouTube.

If you are more comfortable using Chinese, you can use this one: [网络编程懒人入门(一)：快速理解网络通信协议（上篇）](https://zhuanlan.zhihu.com/p/29963231)

1. The wp Server address is locate in common-values-constants.dart


### **Wordpress RESTful API**
Guide:
1. **Get current user's ID**
Endpoint: `/wp-json/wp/v2/users/me`
Method: GET
Header Authorization: JWT-Auth token
Response: the current id

Postman example:

    GET https://joyfulteams.shop/wp-json/wp/v2/users/me
    Header key - Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2pveWZ1bHRlYW1zLnNob3AiLCJpYXQiOjE2ODI1NTk5MzksIm5iZiI6MTY4MjU1OTkzOSwiZXhwIjoxNjgzMTY0NzM5LCJkYXRhIjp7InVzZXIiOnsiaWQiOiIzMSJ9fX0.Ab-cljC3wp-FGCflaq3ocpgburf4Bw2ArdLgDaV1bYc

Response:

    {
    "id": 31,
    "name": "tom",
    "url": "",
    "description": "",
    "link": "https://joyfulteams.shop/author/tom/",
    "slug": "tom",
    "avatar_urls": {
        "24": "https://secure.gravatar.com/avatar/533b6d6e9099b9dff649570aeec8c9a0?s=24&d=mm&r=g",
        "48": "https://secure.gravatar.com/avatar/533b6d6e9099b9dff649570aeec8c9a0?s=48&d=mm&r=g",
        "96": "https://secure.gravatar.com/avatar/533b6d6e9099b9dff649570aeec8c9a0?s=96&d=mm&r=g"
    },
    "meta": [],
    "is_super_admin": true,
    "woocommerce_meta": {
        "wc_payments_overview_inbox_last_read": "",
        "activity_panel_inbox_last_read": "",
        "activity_panel_reviews_last_read": "",
        "categories_report_columns": "",
        "coupons_report_columns": "",
        "customers_report_columns": "",
        "orders_report_columns": "",
        "products_report_columns": "",
        "revenue_report_columns": "",
        "taxes_report_columns": "",
        "variations_report_columns": "",
        "dashboard_sections": "",
        "dashboard_chart_type": "",
        "dashboard_chart_interval": "",
        "dashboard_leaderboard_rows": "",
        "homepage_layout": "",
        "homepage_stats": "",
        "task_list_tracked_started_tasks": "",
        "help_panel_highlight_shown": "",
        "android_app_banner_dismissed": ""
    },
    "_links": {
        "self": [
            {
                "href": "https://joyfulteams.shop/wp-json/wp/v2/users/31"
            }
        ],
        "collection": [
            {
                "href": "https://joyfulteams.shop/wp-json/wp/v2/users"
            }
        ]
    }
 

### **Woocommerce RESTful API**
Guide: https://woocommerce.github.io/woocommerce-rest-api-docs/##introduction

1. Product listing
GET /wp-json/wc/v3/products
Issue: The Api connection is fully set up, however the App is not appropriate showing the product.The problem might be the json file reading. The model for product is locate in common-models-woo-product_model-product_model.dart

2. Product Posting
The UI is in ready but the back-end need to adopt it

3. Registration
Endpoint: `/wp-json/wc/v3/customers`
Method: POST
Header:
'Content-Type': 'application/json',
'Authorization': basicAuth
Response: the created user profile

4. Login
Endpoint: `/wp-json/jwt-auth/v1/token`
Method: POST
Body: username and password
Response: a JWT-Auth token

Postman example:

    POST https://joyfulteams.shop/wp-json/jwt-auth/v1/token
    Body:
    {
        "username":"tom",
        "password":"password" 
    }

Response:

    {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2pveWZ1bHRlYW1zLnNob3AiLCJpYXQiOjE2ODM2ODYzNDIsIm5iZiI6MTY4MzY4NjM0MiwiZXhwIjoxNjg0MjkxMTQyLCJkYXRhIjp7InVzZXIiOnsiaWQiOiIzMSJ9fX0.iB4dwFryi9-spqotNJN9gHT4EXJRo6yDDS3rG3yNK1U",
        "user_email": "[e-mail]",
        "user_nicename": "tom",
        "user_display_name": "tom"
    }

5. Get Profile
Endpoint: `/wp-json/wc/v3/customers/$id`
Method: GET
Header Authorization: JWT-Auth token
Response: profile

Postman example:

    GET https://joyfulteams.shop/wp-json/wc/v3/customers/31
    Header key - Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2pveWZ1bHRlYW1zLnNob3AiLCJpYXQiOjE2ODI1NTk5MzksIm5iZiI6MTY4MjU1OTkzOSwiZXhwIjoxNjgzMTY0NzM5LCJkYXRhIjp7InVzZXIiOnsiaWQiOiIzMSJ9fX0.Ab-cljC3wp-FGCflaq3ocpgburf4Bw2ArdLgDaV1bYc

Response:

    {
    "id": 31,
    "date_created": "2023-04-18T06:26:12",
    "date_created_gmt": "2023-04-18T06:26:12",
    "date_modified": "2023-04-29T04:39:07",
    "date_modified_gmt": "2023-04-29T04:39:07",
    "email": "[e-mail]",
    "first_name": "Junhua",
    "last_name": "situ",
    "role": "customer",
    "username": "tom",
    "billing": {
        "first_name": "J",
        "last_name": "S",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "postcode": "94103",
        "country": "US",
        "state": "CA",
        "email": "[e-mail]",
        "phone": "[phone]"
    },
    "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "postcode": "94103",
        "country": "US",
        "state": "CA",
        "phone": ""
    },
    "is_paying_customer": false,
    "avatar_url": "https://secure.gravatar.com/avatar/533b6d6e9099b9dff649570aeec8c9a0?s=96&d=mm&r=g",
    "_links": {
        "self": [
            {
                "href": "https://joyfulteams.shop/wp-json/wc/v3/customers/31"
            }
        ],
        "collection": [
            {
                "href": "https://joyfulteams.shop/wp-json/wc/v3/customers"
            }
        ]
    }

7. Edit Profile
Current Issue is the address is not be able to retrieve

## Work as a Front-end Developer

### UX Design
##### User testing
###### Interview question of user interview
1. User Experience Evaluation:
* How was your overall experience using our shopping app?
* Did you encounter any issues or inconveniences while browsing products, adding items to the cart, or checking out, etc.?
* Do you find the interface design of the shopping app intuitive and user-friendly?

2. User Interface Design:
* Is the interface of the shopping app aesthetically pleasing? Is there room for improvement?
* What are your thoughts on the visual elements such as menus, buttons, and icons in the shopping app?
* Can you easily find and access the features you need?

3. Interaction Experience:
* Did you find the interaction process of the shopping app smooth? Were there any steps that felt less intuitive or natural?
* Did you easily understand the actions required in each step of the shopping process?

###### Summary of user comments and suggestions
1. For the **main page**, it is not attractive enough, especially the lack of attractive offers.
2. For the new features part, it would be better to show these products in large size instead of showing lots of products in a small size.
3. For the **product page**, the bottom half of the cart page is blank. It would be better to display some relevant products.
4. For the **cart page**, after adding an item to the cart, some users want to recheck the specific information of the items in the cart before checking out.
5. For the **message page**, almost empty. It lacks delivery information access and discount access. Besides, it is quite necessary to have the function as a reminder that reminds you of some important information.

For more information about user testing: https://docs.google.com/document/d/1Kd6DI5RirfDrut6hwYnBH2v1rnaqGXM7/edit

### UI Design

#### Development tool
**[Mockplus](https://rp.mockplus.com/team/crzvfwqikp/appSet/xsx34zBhd)** is a user interface (UI) and user experience (UX) design and prototyping tool that enables designers and developers to create interactive prototypes for web and mobile applications. It simplifies the design process and allows for the rapid creation of mockups and prototypes, making it a popular choice for professionals in the field of user interface and user experience design. Mockplus offers a range of features to help streamline the design process, including drag-and-drop functionality, a variety of pre-designed UI elements, and the ability to create interactive animations and transitions.

Click to start:
[Mockplus](https://rp.mockplus.com/editor/8hRT_82xf/0lklyMvjG)

Why Mockplus?
* Open Source and User Friendly
* Easy Team Collaboration and Online Sharing
* Rapid Prototyping: Mockplus offers a rich set of pre-built UI elements and interactive components, enabling users to quickly create high-fidelity prototypes and reducing design and development cycles.

Overall, Mockplus provides solutions for rapid prototype creation, interactive effect demonstration, and team collaboration. Therefore, we choose Mockplus as the user experience (UX) and user interface (UI) design tool.

#### 2023 S1 version:
1. Appearance Design & Change
Changed the font and font size

2. New Remove Functions
In the original version, you need to select the item you want to delete and then click the delete button in the upper right corner to delete it. In the new version, we added the function that can clear the item by swiping left.

3. New Display Functions
(1)Account Display
Extra showing the number of successful transactions and the period of account registration.

(2)Order Management
Adding the “Delivery” button to support the “reminding the delivery” function, and the “Address” button to offer the “changing shipping address” function.
Issue:Only the front-end interface design has been completed, the function has not been fully realized.

4. Other Changes
(1)Password Confirmation
Adding the repeated Password Confirmation sheet to prevent wrong registering passwords.

(2)About Me
Adding another entrance of the “About Me” through "Settings" page.

5. New Upload Page

The brand new Product Upload Page can be found in the Profile Page, as the graph shown above. Once the user login, the Uploading function is active to be used.
If users want to upload a product, he or she must fill out all the forms including images, title, description, size, and tag. When uploading the image of product, user can choose either existing or on-site shooting photos. A series of customized text tags can be added by users in order to let the product more searchable.

#### 2023 S2 version:

1. Main Page
1.1 Change the advertisement pictures
1.2 Adjust the layout of this page
1.3 Change the icons of categories
1.4 Add Hot highlight on popular icon

2. Message Page
2.1 Add access to the delivery
2.2 Display dialog box

3. Cart Page
3.1 Fix the checkout button
3.2 Add access to the product page by clicking the product picture

4. Product Page
4.1 Adjust the layout of this page
4.2 Add "You May Like" Feature

5. Upload Page
5.1 Add 'price' and 'color'