refactor: move totalvnd into meta.invested for extensibility

Portfolio schema now uses meta object: { currency, assets, meta: { invested } }.
Migrates old totalvnd field automatically on load. The meta object provides
a clean place for future per-user metadata without polluting the top level.

src/modules/trading/README.md

@@ -6,7 +6,7 @@ Paper-trading system where each Telegram user manages a virtual portfolio. Curre
 
 | Command | Action |
 |---------|--------|
-| `/trade_topup <amount>` | Add VND to account. Tracks cumulative invested via `totalvnd`. |
+| `/trade_topup <amount>` | Add VND to account. Tracks cumulative invested in `meta.invested`. |
 | `/trade_buy <qty> <TICKER>` | Buy VN stock at market price, deducting VND. Integer quantities only. |
 | `/trade_sell <qty> <TICKER>` | Sell stock holdings back to VND at market price. |
 | `/trade_convert` | Currency exchange (coming soon). |
@@ -38,14 +38,14 @@ KV namespace prefix: `trading:`
 {
   "currency": { "VND": 5000000 },
   "assets": { "TCB": 10, "FPT": 5, "VNM": 100 },
-  "totalvnd": 10000000
+  "meta": { "invested": 10000000 }
 }
 ```
 
 - `currency` — fiat balances (VND only for now)
 - `assets` — flat map of stock quantities keyed by ticker
-- `totalvnd` — cumulative VND value of all top-ups (cost basis for P&L)
-- Migrates old 4-category format (`stock`/`crypto`/`others`) automatically on load
+- `meta.invested` — cumulative VND value of all top-ups (cost basis for P&L)
+- Migrates old formats automatically on load (`totalvnd` → `meta.invested`, `stock`/`crypto`/`others` → `assets`)
 
 ### Schema: `sym:<TICKER>`
 

src/modules/trading/handlers.js

@@ -39,7 +39,7 @@ export async function handleTopup(ctx, db) {
 
   const p = await getPortfolio(db, uid(ctx));
   addCurrency(p, "VND", amount);
-  p.totalvnd += amount;
+  p.meta.invested += amount;
   await savePortfolio(db, uid(ctx), p);
   await ctx.reply(`Topped up ${formatVND(amount)}.\nBalance: ${formatVND(p.currency.VND)}`);
 }

src/modules/trading/portfolio.js

@@ -2,20 +2,23 @@
  * @file Portfolio CRUD — per-user KV read/write and balance operations.
  * All mutations are in-memory; caller must savePortfolio() to persist.
  *
- * Schema: { currency: { VND, USD }, assets: { SYMBOL: qty }, totalvnd }
+ * Schema: { currency: { VND }, assets: { SYMBOL: qty }, meta: { invested } }
  * Assets are stored in a flat map — category is derived from symbol resolution.
  */
 
 /**
+ * @typedef {Object} PortfolioMeta
+ * @property {number} invested — cumulative VND value of all top-ups (cost basis for P&L)
+ *
  * @typedef {Object} Portfolio
  * @property {{ [currency: string]: number }} currency
  * @property {{ [symbol: string]: number }} assets
- * @property {number} totalvnd
+ * @property {PortfolioMeta} meta
  */
 
 /** @returns {Portfolio} */
 export function emptyPortfolio() {
-  return { currency: { VND: 0 }, assets: {}, totalvnd: 0 };
+  return { currency: { VND: 0 }, assets: {}, meta: { invested: 0 } };
 }
 
 /**
@@ -29,20 +32,19 @@ export async function getPortfolio(db, userId) {
   const raw = await db.getJSON(`user:${userId}`);
   if (!raw) return emptyPortfolio();
 
-  // migrate old format: merge stock/crypto/others into flat assets
-  if (raw.stock || raw.crypto || raw.others) {
-    const assets = { ...raw.stock, ...raw.crypto, ...raw.others, ...raw.assets };
-    return {
-      currency: { VND: 0, ...raw.currency },
-      assets,
-      totalvnd: raw.totalvnd ?? 0,
-    };
-  }
+  // migrate: merge old stock/crypto/others into flat assets
+  const assets =
+    raw.stock || raw.crypto || raw.others
+      ? { ...raw.stock, ...raw.crypto, ...raw.others, ...raw.assets }
+      : (raw.assets ?? {});
+
+  // migrate: totalvnd → meta.invested
+  const invested = raw.meta?.invested ?? raw.totalvnd ?? 0;
 
   return {
     currency: { VND: 0, ...raw.currency },
-    assets: raw.assets ?? {},
-    totalvnd: raw.totalvnd ?? 0,
+    assets,
+    meta: { invested },
   };
 }
 

src/modules/trading/stats-handler.js

@@ -44,7 +44,7 @@ export async function handleStats(ctx, db) {
   }
 
   lines.push(`\nTotal value: ${formatVND(totalValue)}`);
-  lines.push(`Invested: ${formatVND(p.totalvnd)}`);
-  lines.push(`P&L: ${formatPnL(totalValue, p.totalvnd)}`);
+  lines.push(`Invested: ${formatVND(p.meta.invested)}`);
+  lines.push(`P&L: ${formatPnL(totalValue, p.meta.invested)}`);
   await ctx.reply(lines.join("\n"));
 }