feat(admin): view a user's shard footprint at /admin/users/:id

Add a "View" action beside Edit in the users table that opens a dedicated,
read-only page showing everything the uo-link shard knows about a user,
scoped to their linked game accounts: character rosters, currently-online
characters, houses (IDOC-first), and recent vendor sales.

Backend (admin-only, under the existing /users adminOnly gate):
- GET /admin/users/:id — single sanitized user (page is deep-linkable)
- GET /admin/users/:id/shard/{accounts,sales,houses,online}
- shardState: listHousesByAccounts / listOnlineByAccounts (+ model shapers)
- Extract salesForAccounts into utils/shardSales; reuse in player getSales
- Live rosters reuse the existing admin-bypass /admin/shard/* endpoints,
  so no new routes for roster/vendors/char

Frontend:
- UserDetail page reusing CharacterStats / GameAccounts / VendorSales
- GameAccounts gains a readOnly prop (drops link form + self-voice copy)
- api.admin.getUser + api.admin.userShard(id) scope; route + layout title

Tests: adminUserShard.test.js (404, account scoping, empty accounts,
salesForAccounts cap/filter). Full server suite 164 pass; client builds.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0114TpmrNW4wNXsHq5CR72jQ

server/src/model/shardState/shardState.db.js

@@ -33,6 +33,18 @@ async function countOnline() {
 const listOnline = () =>
   query(`SELECT ${ONLINE_COLS} FROM shard_online ORDER BY name ASC`)
 
+// Online players on any of the given game accounts (admin: a user's linked
+// accounts). Empty list short-circuits so we never emit `IN ()`.
+const listOnlineByAccounts = (accounts) =>
+  accounts.length === 0
+    ? Promise.resolve([])
+    : query(
+        `SELECT ${ONLINE_COLS} FROM shard_online
+          WHERE acct IN (${accounts.map(() => '?').join(', ')})
+          ORDER BY name ASC`,
+        accounts,
+      )
+
 // Staff roles whose online presence is shown on the public Shard page. Players
 // who link an account are NOT surfaced publicly — only staff opt into visibility
 // by virtue of being staff.
@@ -89,6 +101,18 @@ async function upsertHouse(serial, fields) {
 const listIdocHouses = () =>
   query(`SELECT ${HOUSE_COLS} FROM shard_houses WHERE is_idoc = 1 ORDER BY updated_at DESC`)
 
+// Houses owned by any of the given game accounts (admin: a user's linked
+// accounts). IDOC houses first, then newest-refreshed. Empty list short-circuits.
+const listHousesByAccounts = (accounts) =>
+  accounts.length === 0
+    ? Promise.resolve([])
+    : query(
+        `SELECT ${HOUSE_COLS} FROM shard_houses
+          WHERE owner_acct IN (${accounts.map(() => '?').join(', ')})
+          ORDER BY is_idoc DESC, updated_at DESC`,
+        accounts,
+      )
+
 module.exports = {
   upsertOnline,
   removeOnline,
@@ -96,9 +120,11 @@ module.exports = {
   countOnline,
   listOnline,
   listOnlineLinked,
+  listOnlineByAccounts,
   insertEconomy,
   listEconomy,
   latestEconomy,
   upsertHouse,
   listIdocHouses,
+  listHousesByAccounts,
 }

server/src/model/shardState/shardState.model.js

@@ -136,9 +136,8 @@ async function upsertHouse(data) {
   await db.upsertHouse(data.serial, fields)
 }
 
-async function listIdoc() {
-  const rows = await db.listIdocHouses()
-  return rows.map((r) => ({
+function shapeHouse(r) {
+  return {
     serial: r.serial,
     stage: r.stage,
     map: r.map,
@@ -153,7 +152,24 @@ async function listIdoc() {
     lastRefreshed: r.last_refreshed,
     isIdoc: Boolean(r.is_idoc),
     updatedAt: r.updated_at,
-  }))
+  }
+}
+
+async function listIdoc() {
+  const rows = await db.listIdocHouses()
+  return rows.map(shapeHouse)
+}
+
+// Houses owned by the given game accounts (admin: a user's linked accounts).
+async function listHousesForAccounts(accounts) {
+  const rows = await db.listHousesByAccounts(accounts)
+  return rows.map(shapeHouse)
+}
+
+// Online players on the given game accounts (admin: a user's linked accounts).
+async function listOnlineForAccounts(accounts) {
+  const rows = await db.listOnlineByAccounts(accounts)
+  return rows.map(shapeOnline)
 }
 
 module.exports = {
@@ -163,9 +179,11 @@ module.exports = {
   onlineCount,
   listOnline,
   listOnlineLinked,
+  listOnlineForAccounts,
   addEconomySample,
   listEconomy,
   latestEconomy,
   upsertHouse,
   listIdoc,
+  listHousesForAccounts,
 }

server/src/router/v1/admin/admin.routes.js

@@ -12,6 +12,7 @@ const authProviders = require('./authProviders.controller')
 const discordBot = require('./discordBot.controller')
 const emailConfig = require('./emailConfig.controller')
 const uoLink = require('./uoLink.controller')
+const usersShard = require('./usersShard.controller')
 const selfShard = require('../player/shard.controller')
 const moderation = require('./moderation.controller')
 const pagesCtrl = require('./pages.controller')
@@ -1082,6 +1083,72 @@ adminRouter.delete(
   ctrl.deleteUser,
 )
 
+// ── User → shard (uo-link) footprint (admin only) ─────────────────────
+// Backs the /admin/users/:id detail page: a user's linked game accounts and,
+// scoped to those accounts, their vendor sales / houses / online characters.
+// Live character rosters are fetched by the client through /admin/shard/* (which
+// already grants admins a bypass to any account), so no routes for them here.
+adminRouter.get(
+  '/users/:id',
+  // #swagger.tags = ['Admin · Users']
+  // #swagger.summary = 'Get a single user (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' }
+  /* #swagger.responses[200] = { description: 'The user', content: { "application/json": { schema: { $ref: "#/components/schemas/User" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  usersShard.getUser,
+)
+adminRouter.get(
+  '/users/:id/shard/accounts',
+  // #swagger.tags = ['Admin · Users']
+  // #swagger.summary = 'A user’s linked game accounts (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' }
+  /* #swagger.responses[200] = { description: 'Linked accounts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardLink" } } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  usersShard.listAccounts,
+)
+adminRouter.get(
+  '/users/:id/shard/sales',
+  // #swagger.tags = ['Admin · Users']
+  // #swagger.summary = 'Recent vendor sales on a user’s accounts (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' }
+  /* #swagger.responses[200] = { description: 'Vendor sales', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardVendorSale" } } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  usersShard.getSales,
+)
+adminRouter.get(
+  '/users/:id/shard/houses',
+  // #swagger.tags = ['Admin · Users']
+  // #swagger.summary = 'Houses owned by a user’s accounts (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' }
+  /* #swagger.responses[200] = { description: 'Houses (IDOC first)', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  usersShard.getHouses,
+)
+adminRouter.get(
+  '/users/:id/shard/online',
+  // #swagger.tags = ['Admin · Users']
+  // #swagger.summary = 'A user’s characters currently online (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' }
+  /* #swagger.responses[200] = { description: 'Online characters', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  usersShard.getOnline,
+)
+
 // ── uo-link sidecar control (admin only) ──────────────────────────────────
 // Connection config (base/ws URL + token + protocol + enabled) and the town
 // crier. The token is write-only (SECURITY note in uoLink.controller.js).

server/src/router/v1/admin/usersShard.controller.js

@@ -0,0 +1,86 @@
+// ── Admin: a single user's shard (uo-link) footprint ──────────────────────────
+//
+// Backs the /admin/users/:id detail page. Every read is scoped to the target
+// user's linked game accounts (from the local shard_account_links mirror): their
+// vendor sales, houses, and currently-online characters. The live character
+// rosters are fetched separately by the client through the existing admin-bypass
+// /admin/shard/* endpoints, so nothing here round-trips the sidecar — these are
+// fast, DB-backed reads. Admin-only (registered under adminOnly in the router).
+
+const users = require('../../../model/users/users.model')
+const shardLinks = require('../../../model/shardLinks/shardLinks.model')
+const shardState = require('../../../model/shardState/shardState.model')
+const { salesForAccounts } = require('../../../utils/shardSales')
+
+const log = require('../../../utils/logger')('admin-user-shard')
+
+// Resolve the target user's linked game accounts, or null if the user id is
+// unknown (so the handler can 404 rather than silently returning an empty set).
+async function accountsForUser(id) {
+  const user = await users.getById(id)
+  if (!user) return null
+  const links = await shardLinks.listForUser(id)
+  return { user, links, accounts: links.map((l) => l.account) }
+}
+
+// GET /admin/users/:id — the sanitized user (so the detail page is refresh-safe).
+async function getUser(req, res) {
+  try {
+    const user = await users.getById(Number(req.params.id))
+    if (!user) return res.status(404).json({ message: 'Not found' })
+    return res.json(user)
+  } catch (err) {
+    log.error('getUser', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /admin/users/:id/shard/accounts — the user's linked game accounts.
+async function listAccounts(req, res) {
+  try {
+    const ctx = await accountsForUser(Number(req.params.id))
+    if (!ctx) return res.status(404).json({ message: 'Not found' })
+    return res.json(ctx.links)
+  } catch (err) {
+    log.error('listAccounts', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /admin/users/:id/shard/sales — recent vendor sales on the user's accounts.
+async function getSales(req, res) {
+  try {
+    const ctx = await accountsForUser(Number(req.params.id))
+    if (!ctx) return res.status(404).json({ message: 'Not found' })
+    return res.json(await salesForAccounts(ctx.accounts))
+  } catch (err) {
+    log.error('getSales', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /admin/users/:id/shard/houses — houses owned by the user's accounts.
+async function getHouses(req, res) {
+  try {
+    const ctx = await accountsForUser(Number(req.params.id))
+    if (!ctx) return res.status(404).json({ message: 'Not found' })
+    return res.json(await shardState.listHousesForAccounts(ctx.accounts))
+  } catch (err) {
+    log.error('getHouses', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /admin/users/:id/shard/online — the user's characters currently online.
+async function getOnline(req, res) {
+  try {
+    const ctx = await accountsForUser(Number(req.params.id))
+    if (!ctx) return res.status(404).json({ message: 'Not found' })
+    return res.json(await shardState.listOnlineForAccounts(ctx.accounts))
+  } catch (err) {
+    log.error('getOnline', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+module.exports = { getUser, listAccounts, getSales, getHouses, getOnline }

server/src/router/v1/player/shard.controller.js

@@ -9,7 +9,7 @@
 
 const uoLinkClient = require('../../../utils/uoLinkClient')
 const shardLinks = require('../../../model/shardLinks/shardLinks.model')
-const shardEvents = require('../../../model/shardEvents/shardEvents.model')
+const { salesForAccounts } = require('../../../utils/shardSales')
 const activity = require('../../../model/activity/activity.model')
 
 const log = require('../../../utils/logger')('player-shard')
@@ -120,21 +120,8 @@ async function getChar(req, res) {
 async function getSales(req, res) {
   try {
     const links = await shardLinks.listForUser(req.user.id)
-    const accounts = new Set(links.map((l) => l.account))
-    if (accounts.size === 0) return res.json([])
-    const events = await shardEvents.list({ kind: 'vendor.sale', limit: 500 })
-    const mine = events
-      .filter((e) => e.payload && accounts.has(e.payload.ownerAcct))
-      .slice(0, 50)
-      .map((e) => ({
-        t: e.t,
-        itemType: e.payload.itemType,
-        amount: e.payload.amount,
-        price: e.payload.price,
-        commission: e.payload.commission,
-        ownerAcct: e.payload.ownerAcct,
-      }))
-    return res.json(mine)
+    const accounts = links.map((l) => l.account)
+    return res.json(await salesForAccounts(accounts))
   } catch (err) {
     log.error('player.shard.getSales', err)
     return res.status(500).json({ message: 'Internal Server Error' })

server/src/utils/shardSales.js

@@ -0,0 +1,26 @@
+// Recent player-vendor sales for a set of game accounts. Shared by the player
+// self endpoint (the caller's linked accounts) and the admin user-detail
+// endpoint (a target user's linked accounts). Reads the site's own ingested
+// event log — no sidecar round-trip — and filters to sales whose owning account
+// is in the set. Newest 50, already newest-first from shardEvents.list.
+
+const shardEvents = require('../model/shardEvents/shardEvents.model')
+
+async function salesForAccounts(accounts) {
+  const set = accounts instanceof Set ? accounts : new Set(accounts)
+  if (set.size === 0) return []
+  const events = await shardEvents.list({ kind: 'vendor.sale', limit: 500 })
+  return events
+    .filter((e) => e.payload && set.has(e.payload.ownerAcct))
+    .slice(0, 50)
+    .map((e) => ({
+      t: e.t,
+      itemType: e.payload.itemType,
+      amount: e.payload.amount,
+      price: e.payload.price,
+      commission: e.payload.commission,
+      ownerAcct: e.payload.ownerAcct,
+    }))
+}
+
+module.exports = { salesForAccounts }