feat: add batch person metrics endpoint (#41)

Allows fetching metrics for multiple people in a single request
instead of N individual calls, reducing HTTP overhead for consumers
like the chatbot agent.

POST /api/modules/team-tracker/person/metrics/batch
Body: { "names": ["Alice", "Bob"] }
Returns: { "results": { "Alice": {...}, "Bob": null } }

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: jangel97

modules/team-tracker/__tests__/server/batch-person-metrics.test.js

@@ -0,0 +1,157 @@
+import { describe, it, expect, vi } from 'vitest'
+
+
+function makeStorage(initial = {}) {
+  const data = { ...initial }
+  return {
+    async readFromStorage(key) { return data[key] ? JSON.parse(JSON.stringify(data[key])) : null },
+    writeToStorage: vi.fn(async (key, val) => { data[key] = JSON.parse(JSON.stringify(val)) }),
+    listStorageFiles: vi.fn(async (dir) => {
+      return Object.keys(data)
+        .filter(k => k.startsWith(dir + '/') && k.endsWith('.json'))
+        .map(k => k.split('/').pop())
+    }),
+    deleteStorageDirectory: vi.fn().mockResolvedValue(),
+    _data: data
+  }
+}
+
+async function setupRoutes(storageData) {
+  const handlers = {}
+  const mockRouter = {
+    get(path, ...args) { handlers[`GET ${path}`] = args[args.length - 1] },
+    post(path, ...args) { handlers[`POST ${path}`] = args[args.length - 1] },
+    put(path, ...args) { handlers[`PUT ${path}`] = args[args.length - 1] },
+    patch(path, ...args) { handlers[`PATCH ${path}`] = args[args.length - 1] },
+    delete(path, ...args) { handlers[`DELETE ${path}`] = args[args.length - 1] }
+  }
+
+  const storage = makeStorage(storageData)
+  const context = {
+    storage,
+    requireAdmin: (req, res, next) => next(),
+    requireTeamAdmin: (req, res, next) => next(),
+    requireScope: () => (req, res, next) => next(),
+    roleStore: {
+      getRoles: vi.fn(() => []),
+      isAdmin: vi.fn(() => false),
+      isTeamAdmin: vi.fn(() => false)
+    },
+    registerScopes: vi.fn()
+  }
+
+  const registerRoutes = require('../../server/index.js')
+  await registerRoutes(mockRouter, context)
+
+  return { handlers, storage }
+}
+
+function mockRes() {
+  const res = {
+    _status: 200,
+    _body: null,
+    status(code) { res._status = code; return res },
+    json(body) { res._body = body; return res }
+  }
+  return res
+}
+
+function baseStorageData() {
+  return {
+    'team-data/registry.json': {
+      meta: { generatedAt: '2026-01-01', provider: 'test', orgRoots: ['org1'] },
+      people: {}
+    },
+    'team-data/teams.json': { teams: {} },
+    'team-data/field-definitions.json': { personFields: [], teamFields: [] },
+    'team-data/config.json': { orgRoots: [], teamDataSource: 'in-app' },
+    'audit-log.json': { entries: [] },
+    'people/alice_smith.json': {
+      jiraDisplayName: 'Alice Smith',
+      fetchedAt: '2026-01-01T00:00:00.000Z',
+      resolved: { count: 10, storyPoints: 20, issues: [] },
+      inProgress: { count: 2, storyPoints: 5, issues: [] },
+      cycleTime: { avgDays: 3.0, medianDays: 2.5 }
+    },
+    'people/bob_jones.json': {
+      jiraDisplayName: 'Bob Jones',
+      fetchedAt: '2026-01-01T00:00:00.000Z',
+      resolved: { count: 5, storyPoints: 8, issues: [] },
+      inProgress: { count: 1, storyPoints: 3, issues: [] },
+      cycleTime: { avgDays: 4.0, medianDays: 3.0 }
+    }
+  }
+}
+
+describe('POST /person/metrics/batch', () => {
+  it('returns metrics for valid names', async () => {
+    const { handlers } = await setupRoutes(baseStorageData())
+    const res = mockRes()
+    const req = { body: { names: ['Alice Smith', 'Bob Jones'] } }
+
+    await handlers['POST /person/metrics/batch'](req, res)
+
+    expect(res._status).toBe(200)
+    expect(res._body.results['Alice Smith'].jiraDisplayName).toBe('Alice Smith')
+    expect(res._body.results['Alice Smith'].resolved.count).toBe(10)
+    expect(res._body.results['Bob Jones'].jiraDisplayName).toBe('Bob Jones')
+    expect(res._body.results['Bob Jones'].resolved.count).toBe(5)
+  })
+
+  it('returns null for unknown names', async () => {
+    const { handlers } = await setupRoutes(baseStorageData())
+    const res = mockRes()
+    const req = { body: { names: ['Alice Smith', 'Nobody'] } }
+
+    await handlers['POST /person/metrics/batch'](req, res)
+
+    expect(res._status).toBe(200)
+    expect(res._body.results['Alice Smith']).not.toBeNull()
+    expect(res._body.results['Nobody']).toBeNull()
+  })
+
+  it('rejects non-array input', async () => {
+    const { handlers } = await setupRoutes(baseStorageData())
+    const res = mockRes()
+    const req = { body: { names: 'not an array' } }
+
+    await handlers['POST /person/metrics/batch'](req, res)
+
+    expect(res._status).toBe(400)
+    expect(res._body.error).toMatch(/must be an array/)
+  })
+
+  it('rejects array with non-string elements', async () => {
+    const { handlers } = await setupRoutes(baseStorageData())
+    const res = mockRes()
+    const req = { body: { names: ['Alice Smith', 123, null] } }
+
+    await handlers['POST /person/metrics/batch'](req, res)
+
+    expect(res._status).toBe(400)
+    expect(res._body.error).toMatch(/must be an array/)
+  })
+
+  it('rejects oversized input', async () => {
+    const { handlers } = await setupRoutes(baseStorageData())
+    const res = mockRes()
+    const names = Array.from({ length: 201 }, (_, i) => `Person ${i}`)
+    const req = { body: { names } }
+
+    await handlers['POST /person/metrics/batch'](req, res)
+
+    expect(res._status).toBe(400)
+    expect(res._body.error).toMatch(/Too many names/)
+  })
+
+  it('returns empty results for empty array', async () => {
+    const { handlers } = await setupRoutes(baseStorageData())
+    const res = mockRes()
+    const req = { body: { names: [] } }
+
+    await handlers['POST /person/metrics/batch'](req, res)
+
+    expect(res._status).toBe(200)
+    expect(res._body.results).toEqual({})
+  })
+})

modules/team-tracker/server/index.js

@@ -3558,6 +3558,68 @@ module.exports = async function registerRoutes(router, context) {
     }
   });
 
+  /**
+   * @openapi
+   * /api/modules/team-tracker/person/metrics/batch:
+   *   post:
+   *     tags: ['TT: Metrics']
+   *     summary: Get metrics for multiple people in a single request
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             required: [names]
+   *             properties:
+   *               names:
+   *                 type: array
+   *                 items:
+   *                   type: string
+   *                 description: List of Jira display names
+   *     responses:
+   *       200:
+   *         description: Batch person metrics results
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 results:
+   *                   type: object
+   *                   description: Map of name to metrics object (null if not found)
+   */
+  router.post('/person/metrics/batch', requireScope('metrics:read'), async function(req, res) {
+    try {
+      const { names } = req.body;
+      if (!Array.isArray(names) || !names.every(n => typeof n === 'string')) {
+        return res.status(400).json({ error: '"names" must be an array of strings' });
+      }
+      if (names.length > 200) {
+        return res.status(400).json({ error: `Too many names (${names.length}). Maximum is 200.` });
+      }
+
+      const results = {};
+      await Promise.all(names.map(async (name) => {
+        const key = sanitizeFilename(name);
+        const cached = await readFromStorage(`people/${key}.json`);
+        if (cached) {
+          if (!cached.jiraAccountId && jiraNameCache[name]?.accountId) {
+            cached.jiraAccountId = jiraNameCache[name].accountId;
+          }
+          results[name] = cached;
+        } else {
+          results[name] = null;
+        }
+      }));
+
+      res.json({ results });
+    } catch (error) {
+      console.error('Batch person metrics error:', error);
+      res.status(500).json({ error: error.message });
+    }
+  });
+
   /**
    * @openapi
    * /api/modules/team-tracker/team/{teamKey}/metrics: