task-059: req-eng's tank balance UI

17 files changed, 106 insertions, 31 deletions

diff --git a/requirements/assumptions/ass-020.md b/requirements/assumptions/ass-020.md
index e641760..e7d8afe 100644
--- a/requirements/assumptions/ass-020.md
+++ b/requirements/assumptions/ass-020.md
@@ -1,8 +1,17 @@
 # ass-020
 
-Suppose a user can create, update and delete their buckets and pipes, and
-suppose that when they do so, they see a prominent number which they know
-summarises what the long-term difference between their incomings and outgoings
-will be if they stick to the intentions expressed in their buckets and pipes.
-Then the user will create, update and delete their buckets and pipes so that the
-number is close to zero.
+Suppose that:
+
+- The user can create, update and delete their buckets and pipes
+- When the user creates, updates and deletes their buckets and pipes, they see a
+  prominent number which they know summarises what the long-term difference
+  between their incomings and outgoings will be if they stick to the intentions
+  expressed in their buckets and pipes
+- When the user creates, updates and deletes their buckets and pipes, they see a
+  prominent number which they know summarises what the difference between their
+  incomings and outgoings has actually been in the past
+
+Then the user will create, update and delete their buckets and pipes so that:
+
+- The first number remains close to zero
+- The second number remains small and positive
diff --git a/requirements/catalogue/req-000.md b/requirements/catalogue/req-000.md
index bc98fcc..1d7b69b 100644
--- a/requirements/catalogue/req-000.md
+++ b/requirements/catalogue/req-000.md
@@ -5,6 +5,6 @@ that I don't go bankrupt.
 
 Source: need-000
 
-Satisfied by: req-068, req-069, req-085, ass-020
+Satisfied by: req-068, req-069, req-085, req-001, req-091, ass-020
 
 Relates to: req-086, req-087
diff --git a/requirements/catalogue/req-025.md b/requirements/catalogue/req-025.md
index 16faad9..c2be0cb 100644
--- a/requirements/catalogue/req-025.md
+++ b/requirements/catalogue/req-025.md
@@ -5,6 +5,6 @@ that I can use my money well.
 
 Source: need-001
 
-Satisfied by: req-068, req-069, req-085, ass-020
+Satisfied by: req-068, req-069, req-085, req-001, req-091, ass-020
 
 Relates to: req-086, req-087
diff --git a/requirements/catalogue/req-085.md b/requirements/catalogue/req-085.md
index c8ce9af..c40e2c7 100644
--- a/requirements/catalogue/req-085.md
+++ b/requirements/catalogue/req-085.md
@@ -1,9 +1,10 @@
 # req-085
 
 As a user, when I'm creating, updating and deleting my buckets and pipes, I want
-to see a prominent number which summarises the long-term difference between my
-planned incomings and outgoings, so that my incomings and outgoings are roughly
-equal in the long run.
+to see a prominent number which summarises what the long-term difference between
+what my incomings and outgoings will be in the future if I control what I do
+with my money, so that my incomings and outgoings are roughly equal in the
+long run.
 
 Sources: req-025, req-000
 
diff --git a/requirements/catalogue/req-088.md b/requirements/catalogue/req-088.md
index a1791fa..7998b45 100644
--- a/requirements/catalogue/req-088.md
+++ b/requirements/catalogue/req-088.md
@@ -3,8 +3,9 @@
 As a user, when I'm creating, updating and deleting my buckets and pipes, I want
 to see the result of the procedure,
 `calculate_long_term_expected_monthly_tank_change`, described below,
-prominently, so that I see a prominent number which summarises the long-term
-difference between my planned incomings and outgoings.
+prominently, so that I see a prominent number which I know summarises what
+the long-term difference between what my incomings and outgoings will be in
+the future if I control what I do with my money.
 
 Source: req-085
 
diff --git a/requirements/catalogue/req-089.md b/requirements/catalogue/req-089.md
index 349d4d9..fb86ace 100644
--- a/requirements/catalogue/req-089.md
+++ b/requirements/catalogue/req-089.md
@@ -3,8 +3,9 @@
 As a user, when I'm creating, updating and deleting my buckets and pipes in
 Schist's desktop UI, I want to see the result of the procedure,
 `calculate_long_term_expected_monthly_tank_change`, as described in req-088,
-prominently, so that I see a prominent number which summarises the long-term
-difference between my planned incomings and outgoings.
+prominently, so that I see a prominent number which I know summarises the long-term
+difference between what my incomings and outgoings will be in the future if I
+control what I do with my money.
 
 Source: req-088
 
diff --git a/requirements/catalogue/req-090.md b/requirements/catalogue/req-090.md
index 5b72fca..8a574cd 100644
--- a/requirements/catalogue/req-090.md
+++ b/requirements/catalogue/req-090.md
@@ -3,8 +3,9 @@
 As a user, when I'm creating, updating and deleting my buckets and pipes in
 Schist's Web UI, I want to see the result of the procedure,
 `calculate_long_term_expected_monthly_tank_change`, as described in req-088,
-prominently, so that I see a prominent number which summarises the long-term
-difference between my planned incomings and outgoings.
+prominently, so that I see a prominent number which I know summarises the long-term
+difference between what my incomings and outgoings will be in the future if I
+control what I do with my money.
 
 Source: req-088
 
diff --git a/requirements/catalogue/req-091.md b/requirements/catalogue/req-091.md
new file mode 100644
index 0000000..f718eb8
--- /dev/null
+++ b/requirements/catalogue/req-091.md
@@ -0,0 +1,12 @@
+# req-091
+
+As a user, when I'm creating, updating and deleting my buckets and pipes, I want
+to see a prominent number which I know summarises what the difference between
+my incomings and outgoings has actually been in the past, so that my incomings
+and outgoings are roughly equal in the long run.
+
+Sources: req-025, req-000
+
+Satisfied by: req-092
+
+Relates to: req-085
diff --git a/requirements/catalogue/req-092.md b/requirements/catalogue/req-092.md
new file mode 100644
index 0000000..cde945e
--- /dev/null
+++ b/requirements/catalogue/req-092.md
@@ -0,0 +1,21 @@
+# req-092
+
+As a user, when I'm creating, updating and deleting my buckets and pipes, I want
+to see the result of the procedure,
+`calculate_tank_balance`, described below,
+so that I see a prominent number which I know summarises what the difference
+between my incomings and outgoings has actually been in the past, so that my
+incomings and outgoings are roughly equal in the long run.
+
+Source: req-091
+
+Satisfied by: dml-drip, dml-transaction, dml-bucket, ass-009, ass-021, req-093, req-094
+
+## calculate_tank_balance
+
+1. Let `drip_sum` be the sum of all `drip.amount` for all drips `drip`.
+2. Let `transaction_sum` be the sum of all `transaction.amount` for all
+   transactions `transaction`.
+3. Let `bucket_overdraw_sum` be the sum of all `bucket.balance` for all buckets
+   `bucket` such that `bucket.balance < 0`.
+4. Return `transaction_sum + bucket_overdraw_sum - drip_sum`.
diff --git a/requirements/catalogue/req-093.md b/requirements/catalogue/req-093.md
new file mode 100644
index 0000000..b150fb7
--- /dev/null
+++ b/requirements/catalogue/req-093.md
@@ -0,0 +1,11 @@
+# req-093
+
+As a user, when I'm creating, updating and deleting my buckets and pipes in
+Schist's desktop UI, I want to see the result of the procedure,
+`calculate_tank_balance`, as described in req-092, prominently, so that I see a
+prominent number which I know summarises what the difference between my
+incomings and outgoings has actually been in the past.
+
+Source: req-092
+
+Satisfied by: req-068, req-069, task-0
diff --git a/requirements/catalogue/req-094.md b/requirements/catalogue/req-094.md
new file mode 100644
index 0000000..ef6ee43
--- /dev/null
+++ b/requirements/catalogue/req-094.md
@@ -0,0 +1,11 @@
+# req-094
+
+As a user, when I'm creating, updating and deleting my buckets and pipes in
+Schist's Web UI, I want to see the result of the procedure,
+`calculate_tank_balance`, as described in req-092, prominently, so that I see a
+prominent number which I know summarises what the difference between my
+incomings and outgoings has actually been in the past.
+
+Source: req-092
+
+Satisfied by: req-068, req-069, task-058
diff --git a/requirements/data_models/dml-bucket.md b/requirements/data_models/dml-bucket.md
index 858f013..b7a3166 100644
--- a/requirements/data_models/dml-bucket.md
+++ b/requirements/data_models/dml-bucket.md
@@ -16,4 +16,4 @@ Notes:
 
 - `balance_cache_key` must be of the format: `<drip_id>:<transaction_id>`.
 
-Sources: req-027, req-028, req-030
+Sources: req-027, req-028, req-030, req-092
diff --git a/requirements/data_models/dml-drip.md b/requirements/data_models/dml-drip.md
index 127c73e..aa0ed11 100644
--- a/requirements/data_models/dml-drip.md
+++ b/requirements/data_models/dml-drip.md
@@ -12,4 +12,4 @@ result of a pipe.
 | amount    | number | The amount of money which dripped.                            |
 | timestamp | number | The time on which this drip was inserted as a Unix timestamp. |
 
-Sources: req-030, req-037
+Sources: req-030, req-037, req-092
diff --git a/requirements/data_models/dml-transaction.md b/requirements/data_models/dml-transaction.md
index b6b76f7..bea2b75 100644
--- a/requirements/data_models/dml-transaction.md
+++ b/requirements/data_models/dml-transaction.md
@@ -12,4 +12,4 @@ a wage slip. It may be associated with at most one bucket.
 | bucket_id    | string? | The bucket associated with the transaction.                |
 | timestamp    | number  | The time the transaction was inserted as a Unix timestamp. |
 
-Source: req-010, req-017
+Source: req-010, req-017, req-092
diff --git a/requirements/tasks/task-028.md b/requirements/tasks/task-028.md
index 5e97b0e..a023f3a 100644
--- a/requirements/tasks/task-028.md
+++ b/requirements/tasks/task-028.md
@@ -13,6 +13,7 @@ The designs should include interfaces for:
 - [ ] Updating buckets
 - [ ] Deleting buckets
 - [ ] Viewing the long-term expected monthly tank change
+- [ ] Viewing the tank balance
 
 Sources: task-029, task-030, task-058
 
diff --git a/requirements/tasks/task-057.md b/requirements/tasks/task-057.md
index 46db06c..1af09b9 100644
--- a/requirements/tasks/task-057.md
+++ b/requirements/tasks/task-057.md
@@ -1,10 +1,13 @@
 # task-057
 
-Schist's desktop UI should display prominently the result of the procedure,
-`calculate_long_term_expected_monthly_tank_change`, as described in req-088, in
-any view from which the user may be thinking about how to create, update or
-delete their buckets or pipes.
+Schist's desktop UI should display prominently the results of the procedures,
+`calculate_long_term_expected_monthly_tank_change`, as described in req-088,
+and `calculate_tank_balance`, as described in req-092, in any view from which
+the user may be thinking about how to create, update or delete their buckets or
+pipes.
 
-Source: req-089
+Sources: req-089, req-093
 
 Epic: epic-000
+
+Relates to: req-088, req-092, task-028
diff --git a/requirements/tasks/task-058.md b/requirements/tasks/task-058.md
index a4fc2fb..e75b8a2 100644
--- a/requirements/tasks/task-058.md
+++ b/requirements/tasks/task-058.md
@@ -1,10 +1,13 @@
-# task-057
+# task-058
 
-Schist's Web UI should display prominently the result of the procedure,
-`calculate_long_term_expected_monthly_tank_change`, as described in req-088, in
-any view from which the user may be thinking about how to create, update or
-delete their buckets or pipes.
+Schist's Web UI should display prominently the results of the procedures,
+`calculate_long_term_expected_monthly_tank_change`, as described in req-088,
+and `calculate_tank_balance`, as described in req-092, in any view from which
+the user may be thinking about how to create, update or delete their buckets or
+pipes.
 
-Source: req-088
+Sources: req-088, req-094
 
 Epic: epic-005
+
+Relates to: req-088, req-092