source: docs/P4-Prototype/wiki/UseCase0007Implementation.md

= Use-case 0007 Implementation - Manage watchlist =

'''Initiating actor:''' Trader

'''Other actors:''' —

A logged-in Trader keeps a list of crypto assets they want to monitor, with the last
price of each. The first time the watchlist is opened the system creates a default
watchlist named "Favorites" for the Trader. From a sub-menu the Trader can list the
watchlist, add a crypto or remove one. The Trader never types a symbol: for adding, the
system lists, numbered, only the cryptos that are not on the watchlist yet, and for
removing, only the cryptos that are on it; the Trader picks one by its number. Adding
a crypto that is already on the list is a no-op (idempotent), and a number that is not
in the list is refused without touching the database.

Original use-case description (P3): [wiki:UseCase0007].
Implementation: `server/watchlist.go`, functions
`ManageWatchlist`, `ensureDefaultWatchlist`, `listWatchlist`, `addToWatchlist` and
`removeFromWatchlist`, with `pickNumber` from
`server/market.go` (the code is shown at the end of this page).

All statements run on the `project` schema (the connection sets
`search_path=project,public` in `server/db/db.go`). The SQL below is copied from the
Go code; only the Go source indentation is removed.

The run shown is user `alice` on the seed data, whose watchlist contains BTC, ETH and
SOL. She lists it, adds ADA, tries to remove a number that is not in the list, removes
SOL and lists the result.

== Scenario ==

 1. '''Trader''' chooses `[8] Manage watchlist` in the authenticated menu (types `8`).
 2. '''System''' makes sure the Trader has a watchlist and takes the id of the oldest one
    (`ensureDefaultWatchlist`; `$1` = the logged-in user's id):

{{{
SELECT id FROM watchlists WHERE user_id = $1 ORDER BY created_at LIMIT 1
}}}

Only if this returns no row, it creates the default watchlist and uses its id:

{{{
INSERT INTO watchlists (user_id, name) VALUES ($1, 'Favorites') RETURNING id
}}}

(alice already has the seed watchlist "Favorites", so only the `SELECT` runs.) The
watchlist id is kept in Go and used as `$1` in all statements below.

 3. '''System''' shows the sub-menu `-- Watchlist --` with `[1] List items`,
    `[2] Add crypto`, `[3] Remove crypto` and `[0] Back`.

[[Image(uc0007_1_3_menu.png)]]

=== List items ===

 4. '''Trader''' chooses `[1] List items`.
 5. '''System''' lists the cryptos on the watchlist with their last price against USD
    (`listWatchlist`; `$1` = watchlist id):

{{{
SELECT c.symbol, c.name, COALESCE(lp.price, 0)
  FROM watchlist_items wi
  JOIN crypto  c  ON c.id = wi.crypto_id
  LEFT JOIN markets       m  ON m.crypto_id = c.id AND m.quote_currency = 'USD'
  LEFT JOIN v_latest_prices lp ON lp.market_id = m.id
 WHERE wi.watchlist_id = $1
 ORDER BY c.symbol
}}}

For alice it prints `BTC Bitcoin 67140.000000`, `ETH Ethereum 3520.000000` and
`SOL Solana 166.100000` (an empty watchlist prints `(watchlist is empty)`), then
shows the sub-menu again.

[[Image(uc0007_list.png)]]

=== Add a crypto ===

 6. '''Trader''' chooses `[2] Add crypto`.
 7. '''System''' lists, numbered, the cryptos that are not on the watchlist yet
    (`addToWatchlist`; `$1` = watchlist id):

{{{
SELECT c.id, c.symbol, c.name
  FROM crypto c
 WHERE NOT EXISTS (SELECT 1 FROM watchlist_items wi
                    WHERE wi.watchlist_id = $1 AND wi.crypto_id = c.id)
 ORDER BY c.symbol
}}}

For alice it prints `1 ADA Cardano` and `2 DOGE Dogecoin` and asks
`Crypto # to add:`. Go keeps each row's crypto id in memory. (If every crypto is
already on the watchlist, it prints `Every crypto is already on your watchlist.`
instead.)

[[Image(uc0007_add_1_list.png)]]

 8. '''Trader''' picks the crypto by its number in the list: `1` (ADA).
 9. '''System''' adds the crypto of row 1 to the watchlist (`$1` = watchlist id,
    `$2` = the chosen crypto's id); thanks to the unique constraint and
    `ON CONFLICT ... DO NOTHING`, adding a crypto that is already there changes
    nothing:

{{{
INSERT INTO watchlist_items (watchlist_id, crypto_id)
 VALUES ($1, $2)
 ON CONFLICT (watchlist_id, crypto_id) DO NOTHING
}}}

It prints `Added ADA.` and shows the sub-menu again.

[[Image(uc0007_add_2_added.png)]]

=== Remove a crypto ===

 10. '''Trader''' chooses `[3] Remove crypto`.
 11. '''System''' lists, numbered, the cryptos that are on the watchlist
     (`removeFromWatchlist`; `$1` = watchlist id):

{{{
SELECT c.id, c.symbol, c.name
  FROM watchlist_items wi
  JOIN crypto c ON c.id = wi.crypto_id
 WHERE wi.watchlist_id = $1
 ORDER BY c.symbol
}}}

For alice it now prints `1 ADA Cardano`, `2 BTC Bitcoin`, `3 ETH Ethereum` and
`4 SOL Solana` and asks `Crypto # to remove:`. Go keeps each row's crypto id in
memory. (If the watchlist is empty, it prints `Your watchlist is empty.` instead.)

[[Image(uc0007_remove_1_list.png)]]

 12. '''Trader''' picks the crypto by its number in the list: `4` (SOL).
 13. '''System''' removes the crypto of row 4 from the watchlist (`$1` = watchlist id,
     `$2` = the chosen crypto's id):

{{{
DELETE FROM watchlist_items WHERE watchlist_id = $1 AND crypto_id = $2
}}}

It prints `Removed SOL.` and shows the sub-menu again.

[[Image(uc0007_remove_2_removed.png)]]

==== Alternate flow 12a — number not in the list ====

Before removing SOL, alice first chose `[3] Remove crypto` and, at step 12, entered `5`
while only numbers 1–4 were listed. `pickNumber` prints
`Invalid choice, enter a number from 1 to 4.`, the `DELETE` is not run and the sub-menu
is shown again; she then chose `[3]` once more, which returned the scenario to step 11.
The same check applies to the number entered at step 8.

[[Image(uc0007_remove_invalid.png)]]

=== Verification — list after the changes ===

Choosing `[1] List items` again runs the query from step 5, which now returns
`ADA Cardano 0.453750`, `BTC Bitcoin 67140.000000` and `ETH Ethereum 3520.000000`:
ADA was added and SOL removed. `[0] Back` returns to the authenticated menu.

[[Image(uc0007_list_after.png)]]

== Source code ==

`server/watchlist.go` — `ManageWatchlist`, `ensureDefaultWatchlist`, `listWatchlist`, `addToWatchlist` and `removeFromWatchlist`:

{{{
// ManageWatchlist - UC0007
// Ensures the user has a default watchlist, then allows listing, adding,
// removing entries.
func ManageWatchlist(s *Session) {
        wlID, err := ensureDefaultWatchlist(s.UserID)
        if err != nil {
                fmt.Println("Error:", err)
                return
        }
        for {
                fmt.Println("\n-- Watchlist --")
                fmt.Println("[1] List items")
                fmt.Println("[2] Add crypto")
                fmt.Println("[3] Remove crypto")
                fmt.Println("[0] Back")
                switch prompt("> ") {
                case "1":
                        listWatchlist(wlID)
                case "2":
                        addToWatchlist(wlID)
                case "3":
                        removeFromWatchlist(wlID)
                case "0":
                        return
                default:
                        fmt.Println("Unknown option.")
                }
        }
}

func ensureDefaultWatchlist(userID string) (string, error) {
        var id string
        err := db.DB.QueryRow(
                `SELECT id FROM watchlists WHERE user_id = $1 ORDER BY created_at LIMIT 1`,
                userID,
        ).Scan(&id)
        if err == sql.ErrNoRows {
                err = db.DB.QueryRow(
                        `INSERT INTO watchlists (user_id, name) VALUES ($1, 'Favorites') RETURNING id`,
                        userID,
                ).Scan(&id)
                return id, err
        }
        return id, err
}

func listWatchlist(wlID string) {
        rows, err := db.DB.Query(`
                SELECT c.symbol, c.name, COALESCE(lp.price, 0)
                  FROM watchlist_items wi
                  JOIN crypto  c  ON c.id = wi.crypto_id
                  LEFT JOIN markets       m  ON m.crypto_id = c.id AND m.quote_currency = 'USD'
                  LEFT JOIN v_latest_prices lp ON lp.market_id = m.id
                 WHERE wi.watchlist_id = $1
                 ORDER BY c.symbol`, wlID)
        if err != nil {
                fmt.Println("Error:", err)
                return
        }
        defer rows.Close()

        fmt.Println()
        fmt.Printf("  %-8s  %-20s  %15s\n", "Symbol", "Name", "Last price")
        fmt.Println("  --------------------------------------------------")
        empty := true
        for rows.Next() {
                var sym, name string
                var price float64
                if err := rows.Scan(&sym, &name, &price); err != nil {
                        fmt.Println("scan error:", err)
                        return
                }
                fmt.Printf("  %-8s  %-20s  %15.6f\n", sym, name, price)
                empty = false
        }
        if empty {
                fmt.Println("  (watchlist is empty)")
        }
}

// addToWatchlist lists the cryptos that are not on the watchlist yet,
// numbered, and adds the one the user picks.
func addToWatchlist(wlID string) {
        rows, err := db.DB.Query(`
                SELECT c.id, c.symbol, c.name
                  FROM crypto c
                 WHERE NOT EXISTS (SELECT 1 FROM watchlist_items wi
                                    WHERE wi.watchlist_id = $1 AND wi.crypto_id = c.id)
                 ORDER BY c.symbol`, wlID)
        if err != nil {
                fmt.Println("Error:", err)
                return
        }
        type option struct{ id, symbol, name string }
        var list []option
        for rows.Next() {
                var o option
                if err := rows.Scan(&o.id, &o.symbol, &o.name); err != nil {
                        rows.Close()
                        fmt.Println("scan error:", err)
                        return
                }
                list = append(list, o)
        }
        rows.Close()
        if len(list) == 0 {
                fmt.Println("Every crypto is already on your watchlist.")
                return
        }
        fmt.Println()
        fmt.Printf("  %-4s  %-8s  %s\n", "#", "Symbol", "Name")
        fmt.Println("  ------------------------------")
        for i, o := range list {
                fmt.Printf("  %-4d  %-8s  %s\n", i+1, o.symbol, o.name)
        }
        k, err := pickNumber("Crypto # to add: ", len(list))
        if err != nil {
                fmt.Println(err)
                return
        }
        _, err = db.DB.Exec(
                `INSERT INTO watchlist_items (watchlist_id, crypto_id)
                 VALUES ($1, $2)
                 ON CONFLICT (watchlist_id, crypto_id) DO NOTHING`,
                wlID, list[k].id,
        )
        if err != nil {
                fmt.Println("Error:", err)
                return
        }
        fmt.Printf("Added %s.\n", list[k].symbol)
}

// removeFromWatchlist lists the watchlist's cryptos, numbered, and removes
// the one the user picks.
func removeFromWatchlist(wlID string) {
        rows, err := db.DB.Query(`
                SELECT c.id, c.symbol, c.name
                  FROM watchlist_items wi
                  JOIN crypto c ON c.id = wi.crypto_id
                 WHERE wi.watchlist_id = $1
                 ORDER BY c.symbol`, wlID)
        if err != nil {
                fmt.Println("Error:", err)
                return
        }
        type option struct{ id, symbol, name string }
        var list []option
        for rows.Next() {
                var o option
                if err := rows.Scan(&o.id, &o.symbol, &o.name); err != nil {
                        rows.Close()
                        fmt.Println("scan error:", err)
                        return
                }
                list = append(list, o)
        }
        rows.Close()
        if len(list) == 0 {
                fmt.Println("Your watchlist is empty.")
                return
        }
        fmt.Println()
        fmt.Printf("  %-4s  %-8s  %s\n", "#", "Symbol", "Name")
        fmt.Println("  ------------------------------")
        for i, o := range list {
                fmt.Printf("  %-4d  %-8s  %s\n", i+1, o.symbol, o.name)
        }
        k, err := pickNumber("Crypto # to remove: ", len(list))
        if err != nil {
                fmt.Println(err)
                return
        }
        if _, err := db.DB.Exec(
                `DELETE FROM watchlist_items WHERE watchlist_id = $1 AND crypto_id = $2`,
                wlID, list[k].id,
        ); err != nil {
                fmt.Println("Error:", err)
                return
        }
        fmt.Printf("Removed %s.\n", list[k].symbol)
}
}}}

`server/market.go` — `pickNumber`:

{{{
// pickNumber reads a 1-based choice from a list of n items.
func pickNumber(label string, n int) (int, error) {
        if n == 0 {
                return 0, fmt.Errorf("Nothing to choose from.")
        }
        k, err := strconv.Atoi(prompt(label))
        if err != nil || k < 1 || k > n {
                return 0, fmt.Errorf("Invalid choice, enter a number from 1 to %d.", n)
        }
        return k - 1, nil
}
}}}