diff --git a/.ecrc b/.ecrc new file mode 100644 index 000000000..57a3c082d --- /dev/null +++ b/.ecrc @@ -0,0 +1,7 @@ +{ + "Exclude": [ + "Website/htdocs/mpmanager/packages/inensus/", + "Website/htdocs/mpmanager/database/dummyData/dummy_data.sql", + "composer.phar" + ] +} \ No newline at end of file diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 000000000..30e849c62 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,6 @@ +# EditorConfig is awesome: https://EditorConfig.org + +[*] +# Ensure consistent file encoding in UNIX style +charset = utf-8 +end_of_line = lf diff --git a/.github/workflows/check-generic.yaml b/.github/workflows/check-generic.yaml new file mode 100644 index 000000000..2d8e8319f --- /dev/null +++ b/.github/workflows/check-generic.yaml @@ -0,0 +1,40 @@ +# Generic checks to ease collaboration: +# - consistent file encoding in UNIX style +# - whitespaces in all purposes files like markdown, yaml, etc +name: Check Generic + +on: + push: + branches: + - main + pull_request: + branches: + - main + +jobs: + editorconfig-checker: + name: Run editorconfig-checker + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Run editorconfig-checker + run: docker run --rm --volume=$PWD:/check mstruebing/editorconfig-checker + + markdownlint: + name: Run markdownlint + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Run markdownlint-cli2 + uses: DavidAnson/markdownlint-cli2-action@v13 + + yamllint: + name: Run yamllint + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Run yamllint + run: yamllint . diff --git a/.github/workflows/php_linter.yml b/.github/workflows/php_linter.yml index b4dc55469..a068aede1 100644 --- a/.github/workflows/php_linter.yml +++ b/.github/workflows/php_linter.yml @@ -35,7 +35,7 @@ jobs: run: ./vendor/bin/phpcbf --standard=PSR12 --tab-width=4 app/ working-directory: ./Website/htdocs/mpmanager continue-on-error: true - + - name: Run PHPStan run: ./vendor/bin/phpstan analyze app/Http app/Services --memory-limit=4G --level=1 working-directory: ./Website/htdocs/mpmanager diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 000000000..4bf1716e5 --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,17 @@ +# Disable some built-in rules +config: + line-length: false + no-inline-html: false + first-line-h1: false + code-block-style: false # conflicts with MkDocs Admontions: https://squidfunk.github.io/mkdocs-material/reference/admonitions/ + code-fence-style: + style: backtick + +# Define glob expressions to use (only valid at root) +globs: + - "**/*.md" + +ignores: + - Website/ui/src/docs/source/index.md + - Website/ui/src/docs/source/.compare.md + - Website/htdocs/mpmanager/packages/ diff --git a/.yamllint b/.yamllint new file mode 100644 index 000000000..7f2054cbc --- /dev/null +++ b/.yamllint @@ -0,0 +1,13 @@ +extends: default + +rules: + document-start: disable + indentation: + spaces: 2 + line-length: disable + quoted-strings: + quote-type: double + required: only-when-needed + allow-quoted-quotes: true + truthy: + check-keys: false diff --git a/Documentation/about.md b/Documentation/about.md index f3f294d25..e22bf5108 100644 --- a/Documentation/about.md +++ b/Documentation/about.md @@ -16,43 +16,49 @@ - **Tarriff:** The combination of energy(kWh) price and the fixed price(access rate). -- **Target:** It is a goal for a Mini-Grid/ Cluster that the company wants to reach at a given time. +- **Target:** It is a goal for a Mini-Grid/ Cluster that the company wants to reach at a given time. - **Asset Type:** An object, that could be sold to locals to help/improve their productivity or live quality. - **Maintenance:** This is the place where external contractors are assigned to predefined jobs like "connect a new house-hold to the grid", "replacing not working meters, etc.". - ## Before using MPManager The key component(s) of the system is a mixture of meter/customer. That means both melts into each other a bit. The only way to register a customer or a meter is to register them both at the same time. For that reason from now on, every registered person will be mentioned as a **customer**. ### Register a customer & meter + There is an additional [Android Application](https://github.com/inensus/Customer-Meter-Registration) that should be used to register a customer with a meter together. The application allows you to select the village where the customer lives, the meter manufacturer, and the energy tariff that should be assigned to the meter. ### Tariffs + Its basically the energy price per kWh with an optional access rate/subscription fee. The operator is free to define the period of that fee. Ex: Every 7 days. ### Payment Channels + or now, the system supports only incoming payments from Airtel Tanzania and Vodacom Tanzania. Both providers are accepting Mobile Money and notify the MPManager over a secure tunnel. ### Payments + Each incoming payment has to contain the meter number. That is the unique number that is used to identify the other channels where the money could spend. After payment is been received the system automatically checks these further points; + 1. Missing Asset Type Rates 2. Not paid Access Rates - 3. Convert the money to energy and generate an STS-Token for the calculated energy amount. At the end of the payment process, the customer will be notified about each step. + 3. Convert the money to energy and generate an STS-Token for the calculated energy amount. At the end of the payment process, the customer will be notified about each step. At the end of the payment process the customer will be notified about each step. If the entered meter number is not valid the system refuses the payment automatically. ### Selling an Asset + The system supports to sell assets to customers on a rate basis plan. A water pump or a milling machine will be a good example of that. ## Targets -A target can be assigned to a whole cluster or for a single Mini-Grid. The important thing by assigning a target is; -If the target is assigned to a cluster, the manager will see only that target on the cluster dashboard. However, if a single Mini-Grid or all Mini-Grids in a cluster has a defined target. The manager will see the calculated sum of these targets. +A target can be assigned to a whole cluster or for a single Mini-Grid. The important thing by assigning a target is; + +If the target is assigned to a cluster, the manager will see only that target on the cluster dashboard. However, if a single Mini-Grid or all Mini-Grids in a cluster has a defined target. The manager will see the calculated sum of these targets. Example: Cluster 1 has following Mini-Grids; MG-1 MG-2 and MG-3 @@ -62,50 +68,55 @@ Example: Cluster 1 has following Mini-Grids; MG-1 MG-2 and MG-3 The result of the cluster overview page would be 800 for expected new connections. - ## MPManager **Note: The pages that contain only a `List of X` and a `Add new X` button without any other key feature are not explained below.** ### Clusters Dashboard + It is basically the whole overview of the business. It shows some quick information like total revenue, registered meters and the number of registered clusters. - + There are also more sections; -1. **Financial overview:** That breaks the total revenue to Mini-Grid level. The manager can see/analyse each Mini-Grid with that. -2. **Cluster Map:** The maps shows graphically where the clusters are located. The clusters on the map are clickable and forwards the manager to the next level dashboard **Cluster Dashboard** -To register a new cluster find the red plus button on the right bottom corner of the screen. +1. **Financial overview:** That breaks the total revenue to Mini-Grid level. The manager can see/analyse each Mini-Grid with that. +2. **Cluster Map:** The maps shows graphically where the clusters are located. The clusters on the map are clickable and forwards the manager to the next level dashboard **Cluster Dashboard** +To register a new cluster find the red plus button on the right bottom corner of the screen. ## Cluster Dashboard -The cluster dashboard is built similar to the clusters dashboard. There are small informative boxes at the top of the screen. -The financial overview and the map are based on Mini-Grids instead of clusters. + +The cluster dashboard is built similar to the clusters dashboard. There are small informative boxes at the top of the screen. +The financial overview and the map are based on Mini-Grids instead of clusters. There are two new sections available; -1. Revenue Analysis: That is the place where all targets of MiniGrids are shown together. + +1. Revenue Analysis: That is the place where all targets of MiniGrids are shown together. 2. Revenue Trends: That is a chart that breaks down the revenue to customer groups. ## Mini-Grid Dashboard + Mini-grids are the building blocks of clusters. This dashboard provides information about the selected Mini-Grid, such as **revenue per customer**, **targeted revenue per customer type**, **energy sold**, **actual payment** ,and **the daily weather forecast** is the area where it can observe and analyze the income distribution of the selected Mini-Grid. Also on this page, the status of **tickets** created by customers in the related Mini-Grid can be observed. ## Customers + MPManager customers are listed under `Customers` in the sidebar. This table contains the customers' name, phone number, city, and meter number. The search function also includes all those fields. By clicking on a customer, will load the details of that specific customer. - This `customer details` page shows all information about that customer. - - Such as - - Basic Details: Name, Surname, Birth Date, etc. - - Payment flow: Is a chart that shows how often the customer makes payments - - Addresses: A list of the addresses that belong to the customer. - - Sold Assets: The assets, that bought by the customer. - - A detailed list of the payments. - - Payment types: Shows how the sent money is neem spent (Energy, Access Rate payment, etc.). - - List of tickets that belong to the customer. - - A list of the meters which belong to the customer and a map where the meters are visually displayed. + This `customer details` page shows all information about that customer. + + Such as + +- Basic Details: Name, Surname, Birth Date, etc. +- Payment flow: Is a chart that shows how often the customer makes payments +- Addresses: A list of the addresses that belong to the customer. +- Sold Assets: The assets, that bought by the customer. +- A detailed list of the payments. +- Payment types: Shows how the sent money is neem spent (Energy, Access Rate payment, etc.). +- List of tickets that belong to the customer. +- A list of the meters which belong to the customer and a map where the meters are visually displayed. Some of the elments are editable (ex:name,surname) or addable (ex:ticket, address). @@ -113,57 +124,53 @@ Some of the elments are editable (ex:name,surname) or addable (ex:ticket, addres The `Meters` link on the sidebar loads a list that contains all registered meters with some additional details such as its serial number, assigned tariff, etc.. The search area on the page searches in `serial_number` and `tariff name`. - By clicking on a meter in the list, a new `meter detail` page will be loaded. This page, contains `basic information`, `meter details`, and `meter transactions`. If the meter can send its usage data it also shows it in an additional `meter reading` section. The `Basic Information` section contains the total revenue that the meter made, the owner, when the last payment occurs, and the registration date. `Meter Details` are meter specified details such as the manufacturer name, the serial number, assigned tariff, and its connection type. `Meter transactions` is a basic list that contains all transactions that hit the meter. - ## Targets - By clicking on `Targets` in the sidebar will load a page with already set targets. The list shows only the key fields of each target. To see the details of a target, click on the `Expand` button. +## Targets (Sidebar) - -To add a **new Target** just click on the `New Target` on the right top side. After clicking on that button, a new page will be loaded. Firstly the manager/admin should assign a Cluster or a Mini-Grid (The difference is already explained [here](#Information-before-using-MPManager)). Then, the date until that target is valid should be selected. + By clicking on `Targets` in the sidebar will load a page with already set targets. The list shows only the key fields of each target. To see the details of a target, click on the `Expand` button. -When these two steps are done; Its time to define our target with some fields like `New connections`, `Revenue per Month`,... None of these fields are marked as required. That means the manager/admin is free to enter or not to enter a value for each goal. +To add a **new Target** just click on the `New Target` on the right top side. After clicking on that button, a new page will be loaded. Firstly the manager/admin should assign a Cluster or a Mini-Grid. +Then, the date until that target is valid should be selected. +When these two steps are done; Its time to define our target with some fields like `New connections`, `Revenue per Month`,... None of these fields are marked as required. That means the manager/admin is free to enter or not to enter a value for each goal. ## Transactions -The page contains two main sections. + +The page contains two main sections. 1. The comparison section; gives a quick overview of the situation. That section contains; Total incoming transactions, Confirmed Transactions, Cancelled Transactions, and the Revenue. The part which makes that information a bit interesting is the availability of comparison. The manager/admin can compare the day with; yesterday, same day last week, or the current week with last week or the current month with last month. 2. A basic list with incoming transactions. The list has an advanced filtering option instead of a basic search as in other pages. - - By clicking on a Transaction, the `Transaction detail` page will load. The detail page contains the `Mobile Provider-specific data`, `Basic Data`, `Sent Sms`, and `Transaction Processing`. - **Mobile Money Provider-specific data:** The name of the provider and the transaction details. This information is required by the mobile money provider in case of an issue. **Transaction Processing:** A detailed list that shows how the incoming money is been used by the system. Ex: 100$ for Energy, 20$ for Access Rate, and 400$ for Milling Machine Rate Payment. - ## Tickets + MPManager is using [Trello](https://trello.com) as a ticketing platform. All tickets are basically Trello cards. The database is only holding references to the tickets. The ticketing system aims to resolve requests and complaints from customers as quickly as possible. It is important to assign a ticket to the correct category to maintain tickets easily. Therefore, there are some ticket categories. To add/ list category please click on `Categories` that is listed under `Tickets` in the sidebar. ### Adding User to Ticketing System -As already mentioned, the ticketing system is using Trello. To be able to assign tickets internally, all the staff has to be registered on [Trello](https://trello.com). The user name is been used to associate the Trello user to MPManager users. +As already mentioned, the ticketing system is using Trello. To be able to assign tickets internally, all the staff has to be registered on [Trello](https://trello.com). The user name is been used to associate the Trello user to MPManager users. To add a user click on `Users` in the list below `Tickets`. It will ask you the `Ticketing System Tag`. That is the name that begins with an **@** in the Trello user profile. ## Maintenance + In some cases, it is wiser to use external resources to solve small problems. Maintenance is exactly for that there. The maintenance users are some experts who are not working for the company but works per contract. - There is a form to create a **New Maintenance Request**. That page asks the manager/admin about the job todo, the deadline for the task, the person who is responsible to do that, and the price for the task. The created task will be sent out to the external person via SMS. The created maintenance job/task is also saved as a ticket. The gain by saving that task as a ticket is, in case of a problem the person who is assigned to that job can reply to the initial SMS. The incoming SMS will automatically add to the ticket as a response. - - ## Sms + Sms is the key communication infrastructure. It is used by `Transactions` and `Maintenance`. But what if the company wants to send some inform their customers about something like an unplanned electricity cut. That is the reason why `Sms`is listed in the sidebar as an extra service. The manager/admin can send SMS's to a specific Mini-Grid, to a specific customer group/type or single customers. - ## Reports -MPManager has a reports page where managers can download reports. This page contains weekly, monthly, and payment requests. \ No newline at end of file + +MPManager has a reports page where managers can download reports. This page contains weekly, monthly, and payment requests. diff --git a/README.md b/README.md index 304c98ecc..06beac047 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ > GitHub Workflow Status - On the GitHub page, you can find instructions for downloading and installing Docker Compose on Linux. Be sure to check for the latest release. @@ -80,20 +80,20 @@ install it separately. --- -The development environment is served under http://mpmanager.local To reach the site over the given url; enter the +The development environment is served under To reach the site over the given url; enter the following lines to your hosts file. -#### For Linux/Mac Users +### For Linux/Mac Users -``` +```sh /etc/hosts 127.0.0.1 mpmanager.local 127.0.0.1 db.mpmanager.local ``` -#### For Windows Users +### For Windows Users -``` +```sh c:\windows\system32\drivers\etc\hosts 127.0.0.1 mpmanager.local 127.0.0.1 db.mpmanager.local @@ -101,12 +101,12 @@ c:\windows\system32\drivers\etc\hosts ## Frontend -The frontend is served under http://mpmanager.local. You can find frontend files under `Website/ui`. +The frontend is served under . You can find frontend files under `Website/ui`. The frontend is built with Vue.js. After first run with `docker-compose up` dependencies will be installed automatically. If you want to install dependencies manually, you can run `npm install` under `Website/ui` folder. -#### Folder Structure +### Folder Structure When adding new files to the project, please adhere to the following folder structure: @@ -114,7 +114,7 @@ When adding new files to the project, please adhere to the following folder stru Modules are the components used in pages. For example, the Client module holds components related to clients. Every component associated with clients should be placed under the Client module. -``` +```sh Website/ui ├── src │ ├── modules @@ -127,7 +127,7 @@ Website/ui are not using nuxt.js, routes need to be defined manually. You can find the routes in the `Website/ui/src/ExportedRoutes.js` file. -``` +```sh Website/ui ├── src │ ├── pages @@ -142,7 +142,7 @@ Plugins are additional components developed as separate packages to enhance our main codebase clean. Each plugin should reside in its own folder under the `Website/ui/src/plugins` directory. Additionally, each plugin should have its own backend code, which will be explained in the backend section. -``` +```sh Website/ui ├── src │ ├── plugins @@ -153,7 +153,7 @@ In the backend section, you'll find instructions on how to create a plugin. ## Backend -The backend is built with Laravel. The backend is served under http://api.mpmanager.local/api. You can find backend +The backend is built with Laravel. The backend is served under . You can find backend files under `Website/htdocs/mpmanager`. After the first run with `docker-compose up`, dependencies will be installed automatically. If you prefer to install dependencies manually or need to add additional packages, follow these steps: @@ -163,6 +163,7 @@ automatically. If you prefer to install dependencies manually or need to add add docker exec -it laravel bash cd mpmanager ``` + 2. Run the following command to install dependencies, replacing {package-name} with the actual name of the package: ```bash @@ -218,7 +219,7 @@ These commands will create the central database and the first company database. dummy data. You can use the following credentials to login to the application: -``` +```sh username: dummy@user.com password: 123123 ``` @@ -235,7 +236,8 @@ docker exec -it laravel bash cd mpmanager php artisan migrator:create {migration-name} ``` -This command creates a migration file in Micropower Manager's core migration files location: `Website/htdocs/mpmanager/database/migrations/micropowermanager + +This command creates a migration file in Micropower Manager's core migration files location: `Website/htdocs/mpmanager/database/migrations/micropowermanager` After creating the migration file, you can shift it to other company databases using the following command: @@ -244,6 +246,7 @@ docker exec -it laravel bash cd mpmanager php artisan migrator:copy ``` + This command syncs the migration files in the core migration folder for other company migrations. To migrate the database, use the following command: @@ -262,26 +265,26 @@ cd mpmanager php shard:migrate {company_id} {--force} ``` -#### Plugins +### Install Plugins + We have a custom plugin creator command that generates a template. Use the following command to create a new plugin: ```bash docker exec -it laravel bash cd mpmanager php artisan micropowermanager:new-package {package-name} -``` +``` This command creates a plugin template in the Website/htdocs/mpmanager/packages/inensus folder. Upon creation, you can proceed with plugin development. You can check other plugins for reference. Additionally, this command will create UI folders for the newly created plugin. Move the created UI folder to the Website/ui/src/plugins folder. - ### phpMyAdmin To project also includes phpMyAdmin which enables quick database operations without installing third-party software or writing any single line into the terminal. -The default credentials for the database are; - -``` +The default credentials for the database are: + +```sh username: root password: wF9zLp2qRxaS2e -``` \ No newline at end of file +``` diff --git a/Website/htdocs/mpmanager/database/seeders/ShardingDatabaseSeeder.php b/Website/htdocs/mpmanager/database/seeders/ShardingDatabaseSeeder.php index 3fdad626e..0e3e48bac 100644 --- a/Website/htdocs/mpmanager/database/seeders/ShardingDatabaseSeeder.php +++ b/Website/htdocs/mpmanager/database/seeders/ShardingDatabaseSeeder.php @@ -11,4 +11,4 @@ public function run() $this->call(MpmPluginsSeeder::class); $this->call(ProtectedPagesSeeder::class); } -} \ No newline at end of file +} diff --git a/Website/htdocs/mpmanager/public/css/app.css b/Website/htdocs/mpmanager/public/css/app.css index bb4924aef..fc145ff0b 100644 --- a/Website/htdocs/mpmanager/public/css/app.css +++ b/Website/htdocs/mpmanager/public/css/app.css @@ -4,4 +4,4 @@ .dd { max-width: 100% !important; -} \ No newline at end of file +} diff --git a/Website/ui/src/docs/source/includes/_errors.md b/Website/ui/src/docs/source/includes/_errors.md index 38dc98984..aa2ef6ca2 100644 --- a/Website/ui/src/docs/source/includes/_errors.md +++ b/Website/ui/src/docs/source/includes/_errors.md @@ -4,7 +4,6 @@ The Kittn API uses the following error codes: - Error Code | Meaning ---------- | ------- 400 | Bad Request -- Your request sucks diff --git a/docker-compose.yml b/docker-compose.yml index 70a98b397..e6912c95b 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,4 +1,4 @@ -version: '3.1' +version: "3.1" services: 'laravel': @@ -64,7 +64,7 @@ services: build: context: Docker/ dockerfile: DockerfileComposer - restart: 'no' + restart: "no" command: install volumes: - ./Website/htdocs/mpmanager:/app @@ -82,7 +82,7 @@ services: volumes: - ./DB/mysql:/var/lib/mysql ports: - - "3307:3306" + - 3307:3306 'phpmyadmin': image: phpmyadmin/phpmyadmin:latest @@ -97,9 +97,9 @@ services: container_name: nginx-proxy image: jwilder/nginx-proxy:latest ports: - - "80:80" - - "443:443" - - "6379:6379" + - 80:80 + - 443:443 + - 6379:6379 environment: VIRTUAL_PROTO: https volumes: