add readme

cx-Zh · cx-Zh · commit 4d182fb43240 · 2021-08-20T16:17:23.000+08:00
diff --git a/README.md b/README.md
@@ -0,0 +1,301 @@
+# Welcome to PowerDale
+
+PowerDale is a small town with around 100 residents. Most houses have a smart meter installed that can save and send
+information about how much power a house is drawing/using.
+
+There are three major providers of energy in town that charge different amounts for the power they supply.
+
+- _Dr Evil's Dark Energy_
+- _The Green Eco_
+- _Power for Everyone_
+
+# Introducing JOI Energy
+
+JOI Energy is a new start-up in the energy industry. Rather than selling energy they want to differentiate themselves
+from the market by recording their customers' energy usage from their smart meters and recommending the best supplier to
+meet their needs.
+
+You have been placed into their development team, whose current goal is to produce an API which their customers and
+smart meters will interact with.
+
+Unfortunately, two members of the team are on annual leave, and another one has called in sick! You are left with
+another ThoughtWorker to progress with the current user stories on the story wall. This is your chance to make an impact
+on the business, improve the code base and deliver value.
+
+## Story Wall
+
+At JOI energy the development team use a story wall or Kanban board to keep track of features or "stories" as they are
+worked on.
+
+The wall you will be working from today has 7 columns:
+
+- Backlog
+- Ready for Dev
+- In Dev
+- Ready for Testing
+- In Testing
+- Ready for sign off
+- Done
+
+Examples can be found
+here [https://leankit.com/learn/kanban/kanban-board/](https://leankit.com/learn/kanban/kanban-board/)
+
+## Users
+
+To trial the new JOI software 5 people from the JOI accounts team have agreed to test the service and share their energy
+data.
+
+| User    | Smart Meter ID  | Power Supplier        |
+| ------- | --------------- | --------------------- |
+| Sarah   | `smart-meter-0` | Dr Evil's Dark Energy |
+| Peter   | `smart-meter-1` | The Green Eco         |
+| Charlie | `smart-meter-2` | Dr Evil's Dark Energy |
+| Andrea  | `smart-meter-3` | Power for Everyone    |
+| Alex    | `smart-meter-4` | The Green Eco         |
+
+These values are used in the code and in the following examples too.
+
+## Requirements
+
+The project requires [Java 1.8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) or
+higher.
+
+The project makes use of Gradle and uses
+the [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html), which means you don't need Gradle
+installed.
+
+## Useful Gradle commands
+
+The project makes use of Gradle and uses the Gradle wrapper to help you out carrying some common tasks such as building
+the project or running it.
+
+### Build the project
+
+Compiles the project, runs the test and then creates an executable JAR file
+
+```console
+$ ./conan install
+```
+
+Run the application using Java and the executable JAR file produced by the Gradle `build` task. The application will be
+listening to port `8080`.
+
+```console
+$ java -jar build/libs/joi-energy.jar
+```
+
+### Run the tests
+
+There are two types of tests, the unit tests and the functional tests. These can be executed as follows.
+
+- Run unit tests only
+
+  ```console
+  $ ./gradlew test
+  ```
+
+- Run functional tests only
+
+  ```console
+  $ ./gradlew functionalTest
+  ```
+
+- Run both unit and functional tests
+
+  ```console
+  $ ./gradlew check
+  ```
+
+### Run the application
+  ```console
+  $ ....
+  ```              
+
+Run the application which will be listening on port `8080`.
+
+```console
+$ ./gradlew bootRun
+```
+
+## API
+
+Below is a list of API endpoints with their respective input and output. Please note that the application needs to be
+running for the following endpoints to work. For more information about how to run the application, please refer
+to [run the application](#run-the-application) section above.
+
+### Store Readings
+
+Endpoint
+
+```text
+POST /readings/store
+```
+
+Example of body
+
+```json
+{
+  "smartMeterId": <smartMeterId>,
+  "electricityReadings": [
+    {
+      "time": <time>,
+      "reading": <reading>
+    }
+  ]
+}
+```
+
+Parameters
+
+| Parameter      | Description                                           |
+| -------------- | ----------------------------------------------------- |
+| `smartMeterId` | One of the smart meters' id listed above              |
+| `time`         | The date/time (as epoch) when the _reading_ was taken |
+| `reading`      | The consumption in `kW` at the _time_ of the reading  |
+
+Example readings
+
+| Date (`GMT`)      | Epoch timestamp | Reading (`kW`) |
+| ----------------- | --------------: | -------------: |
+| `2020-11-29 8:00` |      1606636800 |         0.0503 |
+| `2020-11-29 8:01` |      1606636860 |         0.0621 |
+| `2020-11-29 8:02` |      1606636920 |         0.0222 |
+| `2020-11-29 8:03` |      1606636980 |         0.0423 |
+| `2020-11-29 8:04` |      1606637040 |         0.0191 |
+
+In the above example, the smart meter sampled readings, in `kW`, every minute. Note that the reading is in `kW` and
+not `kWH`, which means that each reading represents the consumption at the reading time. If no power is being consumed
+at the time of reading, then the reading value will be `0`. Given that `0` may introduce new challenges, we can assume
+that there is always some consumption, and we will never have a `0` reading value. These readings are then sent by the
+smart meter to the application using REST. There is a service in the application that calculates the `kWH` from these
+readings.
+
+The following POST request, is an example request using CURL, sends the readings shown in the table above.
+
+```console
+$ curl \
+  -X POST \
+  -H "Content-Type: application/json" \
+  "http://localhost:8080/readings/store" \
+  -d '{"smartMeterId":"smart-meter-0","electricityReadings":[{"time":1606636800,"reading":0.0503},{"time":1606636860,"reading":0.0621},{"time":1606636920,"reading":0.0222},{"time":1606636980,"reading":0.0423},{"time":1606637040,"reading":0.0191}]}'
+```
+
+The above command does not return anything.
+
+### Get Stored Readings
+
+Endpoint
+
+```text
+GET /readings/read/<smartMeterId>
+```
+
+Parameters
+
+| Parameter      | Description                              |
+| -------------- | ---------------------------------------- |
+| `smartMeterId` | One of the smart meters' id listed above |
+
+Retrieving readings using CURL
+
+```console
+$ curl "http://localhost:8080/readings/read/smart-meter-0"
+```
+
+Example output
+
+```json
+{
+    "readings": [
+        {
+            "reading": 0.4,
+            "time": "2021-08-20T07:04:49"
+        },
+        {
+            "reading": 0.123,
+            "time": "2021-08-20T07:07:49"
+        },
+        {
+            "reading": 0.23,
+            "time": "2021-08-20T07:10:49"
+        },
+        {
+            "reading": 0.432,
+            "time": "2021-08-20T07:13:49"
+        },
+        {
+            "reading": 0.44,
+            "time": "2021-08-20T07:16:49"
+        }
+    ]
+}
+```
+
+### View Current Price Plan and Compare Usage Cost Against all Price Plans
+
+Endpoint
+
+```text
+GET /price-plans/compare-all/<smartMeterId>
+```
+
+Parameters
+
+| Parameter      | Description                              |
+| -------------- | ---------------------------------------- |
+| `smartMeterId` | One of the smart meters' id listed above |
+
+Retrieving readings using CURL
+
+```console
+$ curl "http://localhost:8080/price-plans/compare-all/smart-meter-0"
+```
+
+Example output
+
+```json
+{
+    "pricePlanComparisons": {
+        "price-plan-0": 4.0,
+        "price-plan-1": 0.8,
+        "price-plan-2": 0.4
+    },
+    "pricePlanId": "price-plan-1"
+}
+```
+
+### View Recommended Price Plans for Usage
+
+Endpoint
+
+```text
+GET /price-plans/recommend/<smartMeterId>[?limit=<limit>]
+```
+
+Parameters
+
+| Parameter      | Description                                          |
+| -------------- | ---------------------------------------------------- |
+| `smartMeterId` | One of the smart meters' id listed above             |
+| `limit`        | (Optional) limit the number of plans to be displayed |
+
+Retrieving readings using CURL
+
+```console
+$ curl "http://localhost:8080/price-plans/recommend/smart-meter-0?limit=2"
+```
+
+Example output
+
+```json
+{
+    "recommend": [
+        {
+            "price-plan-2": 0.4
+        },
+        {
+            "price-plan-1": 0.8
+        }
+    ]
+}
+```
diff --git a/rest/controller/MeterReadingController.h b/rest/controller/MeterReadingController.h
@@ -33,7 +33,7 @@ namespace detail {
 
     auto renderReadingAsJson(const ElectricityReading &r) {
         return nlohmann::json{{"time",    toRfc3339(r.getTime())},
-                              {"reading", r.getReading()}};
+                              {"reading", double(r.getReading()) / 10000}};
     }
 }  // namespace detail
 
diff --git a/rest/controller/PricePlanComparatorController.h b/rest/controller/PricePlanComparatorController.h
@@ -33,9 +33,9 @@ class PricePlanComparatorController {
         res.set(http::field::content_type, "application/json");
         res.keep_alive(req.keep_alive());
         nlohmann::json j;
-        j["pricePlanComparisons"] = {{"price-plan-0", double(costs.value()["price-plan-0"])/10000},
-                                     {"price-plan-1", double(costs.value()["price-plan-1"])/10000},
-                                     {"price-plan-2", double(costs.value()["price-plan-2"])/10000}};
+        j["pricePlanComparisons"] = {{"price-plan-0", double(costs.value()["price-plan-0"]) / 10000},
+                                     {"price-plan-1", double(costs.value()["price-plan-1"]) / 10000},
+                                     {"price-plan-2", double(costs.value()["price-plan-2"]) / 10000}};
         j["pricePlanId"] = current_price_plans[meterId];
         res.body() = j.dump();
         res.prepare_payload();
@@ -63,7 +63,7 @@ class PricePlanComparatorController {
         res.keep_alive(req.keep_alive());
         auto results = nlohmann::json::array();
         std::transform(ordered_costs.begin(), ordered_costs.end(), std::back_inserter(results),
-                       [](auto &cost) { return nlohmann::json{{cost.first, cost.second}}; });
+                       [](auto &cost) { return nlohmann::json{{cost.first, double(cost.second) / 10000}}; });
         nlohmann::json j;
         j["recommend"] = results;
         res.body() = j.dump();

Original file line number	Diff line number	Diff line change
`@@ -33,7 +33,7 @@ namespace detail {`
`33`	`33`
`34`	`34`	`auto renderReadingAsJson(const ElectricityReading &r) {`
`35`	`35`	`return nlohmann::json{{"time", toRfc3339(r.getTime())},`
`36`		`- {"reading", r.getReading()}};`
	`36`	`+ {"reading", double(r.getReading()) / 10000}};`
`37`	`37`	`}`
`38`	`38`	`} // namespace detail`
`39`	`39`