BPOS-TMP-REPO/apps/api/src/app/routes/governance.ts

/**
 * 治理台路由组装(编码规范 §3:治理台九功能不设后端 governance 模块 ——
 * 每个功能是对应模块的管理用例 + 本文件的路由组装)。
 * 端级授权由 server.ts 的鉴权中间件按路由归属统一判(ADR-012),这里不再各写守卫。
 */
import type { Hono } from 'hono';
import type { ApiError } from '@contracts';
import {
  deleteLlmInstanceRoute,
  deleteRoleAccessRoute,
  listLlmInstancesRoute,
  listLlmProvidersRoute,
  listRoleAccessRoute,
  listStaffRoute,
  listWorkGroupsRoute,
  LLM_PROVIDERS,
  probeLlmDraftRoute,
  probeLlmInstanceRoute,
  saveWorkGroupRoute,
  setRoleAccessRoute,
  setStaffPositionRoute,
  staffIdSchema,
  staffInFlightRoute,
  syncStaffRoute,
  upsertLlmInstanceRoute,
} from '@contracts';
import { AccessLockoutError, PositionNotFoundError, StaffNotFoundError } from '@modules/org';
import { PROVIDER_PROFILES } from '@modules/llm';
import type { Container } from '../container.ts';
import type { AppEnv } from '../http-env.ts';

export function registerGovernanceRoutes(app: Hono<AppEnv>, container: Container): void {
  /* ── 员工管理:名册来自鉴权中心,这里只管岗位与同步(ADR-012) ─────────── */

  app.get(listStaffRoute.path, async (c) => c.json(await container.org.listStaff()));

  /**
   * 从 Keycloak Admin API 同步名册;没配 provisioning 就回 configured:false(界面不撒谎)。
   * 409:这一次同步会把最后一个能进运营中心的人也停了 —— 整体拒绝,一条都没写
   * (与「角色 → 端」那两条同款,理由不同、话不同)。
   */
  app.post(syncStaffRoute.path, async (c) => {
    try {
      return c.json(await container.org.syncRoster());
    } catch (error) {
      if (error instanceof AccessLockoutError) {
        const body: ApiError = { code: 'conflict', message: error.message };
        return c.json(body, 409);
      }
      throw error;
    }
  });

  app.put(setStaffPositionRoute.path, async (c) => {
    const staffId = staffIdSchema.parse(c.req.param('staffId'));
    const parsed = setStaffPositionRoute.body.safeParse(await c.req.json());
    if (!parsed.success) {
      const body: ApiError = { code: 'validation-failed', message: '入参不合法', detail: parsed.error.issues };
      return c.json(body, 400);
    }
    try {
      return c.json(await container.org.setPosition(staffId, parsed.data.positionId));
    } catch (error) {
      if (error instanceof StaffNotFoundError || error instanceof PositionNotFoundError) {
        const body: ApiError = { code: 'not-found', message: error.message };
        return c.json(body, 404);
      }
      throw error;
    }
  });

  /** 此人身上还挂着什么 —— 原「停用前置检查」降为只读信息;停用在 Keycloak 做 */
  app.get(staffInFlightRoute.path, async (c) => {
    const staffId = staffIdSchema.parse(c.req.param('staffId'));
    try {
      return c.json(await container.org.inFlightOf(staffId));
    } catch (error) {
      if (error instanceof StaffNotFoundError) {
        const body: ApiError = { code: 'not-found', message: error.message };
        return c.json(body, 404);
      }
      throw error;
    }
  });

  /* ── 角色 → 端(ADR-012) ─────────────────────────────────────────────── */

  app.get(listRoleAccessRoute.path, async (c) => c.json(await container.org.listRoleAccess()));

  /** 锁死不变量不过(改完没人能进运营中心)→ 409 */
  app.put(setRoleAccessRoute.path, async (c) => {
    const role = c.req.param('role');
    const parsed = setRoleAccessRoute.body.safeParse(await c.req.json());
    if (!parsed.success) {
      const body: ApiError = { code: 'validation-failed', message: '入参不合法', detail: parsed.error.issues };
      return c.json(body, 400);
    }
    try {
      return c.json(await container.org.setRoleAccess(role, parsed.data.ends));
    } catch (error) {
      if (error instanceof AccessLockoutError) {
        const body: ApiError = { code: 'conflict', message: error.message };
        return c.json(body, 409);
      }
      throw error;
    }
  });

  app.delete(deleteRoleAccessRoute.path, async (c) => {
    try {
      await container.org.deleteRoleAccess(c.req.param('role'));
      return c.json({ ok: true });
    } catch (error) {
      if (error instanceof AccessLockoutError) {
        const body: ApiError = { code: 'conflict', message: error.message };
        return c.json(body, 409);
      }
      throw error;
    }
  });

  /* ── 员工管理 · 工作组(ADR-011) ──────────────────────────────────── */

  /**
   * 全部工作组 —— 一人至多一组,按员工遍历取。
   * `ownerName` 一并带出:前端要显示的是「柴浩的组」,不是一串 id。
   */
  app.get(listWorkGroupsRoute.path, async (c) => {
    const { staff } = await container.org.listStaff();
    const found = await Promise.all(
      staff.map(async (s) => {
        const group = await container.org.workGroupOf(s.id);
        return group === undefined ? undefined : { ...group, ownerName: s.name };
      }),
    );
    return c.json({ groups: found.filter((g) => g !== undefined) });
  });

  /**
   * 建组 / 改组 —— 按 `ownerId` 落:已有即更新(复用 id),没有即新建。
   * 与 `workGroupOf` 的取组口径一致(一人一组),不给同一个人建出两个组来。
   * 改组**不影响在途**:装进工作流的是起单时的快照。
   */
  app.put(saveWorkGroupRoute.path, async (c) => {
    const parsed = saveWorkGroupRoute.body.safeParse(await c.req.json());
    if (!parsed.success) {
      const body: ApiError = { code: 'validation-failed', message: '工作组不合 schema', detail: parsed.error.issues };
      return c.json(body, 400);
    }
    const existing = await container.org.workGroupOf(parsed.data.ownerId);
    const group = await container.org.saveWorkGroup({
      ...(existing === undefined ? {} : { id: existing.id }),
      name: parsed.data.name,
      ownerId: parsed.data.ownerId,
      members: parsed.data.members,
    });
    return c.json({ group });
  });

  /* ── 系统管理 · LLM 实例 ──────────────────────────────────────────── */

  /** Provider 档案:默认端点与出参口径 —— 建实例的表单据它预填(唯一真相在服务端) */
  app.get(listLlmProvidersRoute.path, (c) =>
    c.json({
      providers: LLM_PROVIDERS.map((provider) => {
        const profile = PROVIDER_PROFILES[provider];
        return {
          provider,
          label: profile.label,
          defaultBaseUrl: profile.defaultBaseUrl,
          structuredOutput: profile.structuredOutput,
        };
      }),
    }),
  );

  app.get(listLlmInstancesRoute.path, async (c) => c.json({ instances: await container.llm.list() }));

  app.post(upsertLlmInstanceRoute.path, async (c) => {
    const parsed = upsertLlmInstanceRoute.body.safeParse(await c.req.json());
    if (!parsed.success) {
      const body: ApiError = { code: 'validation-failed', message: '入参不合法', detail: parsed.error.issues };
      return c.json(body, 400);
    }
    return c.json(await container.llm.upsert(parsed.data));
  });

  /** 删实例:被活动声明着的用途名不许删(409)—— 反查放这一层,llm 不该知道活动的存在 */
  app.delete(deleteLlmInstanceRoute.path, async (c) => {
    const id = c.req.param('id');
    const target = (await container.llm.list()).find((i) => i.id === id);
    if (target === undefined) {
      const body: ApiError = { code: 'not-found', message: '实例不存在' };
      return c.json(body, 404);
    }
    const cards = await container.registry.list();
    const manifests = await Promise.all(cards.map((a) => container.registry.manifestOf(a.activityId)));
    const users = manifests.filter((m) => m.declarations.models.includes(target.name));
    if (users.length > 0) {
      const body: ApiError = {
        code: 'conflict',
        message: `还有 ${users.length} 个活动声明着用途名「${target.name}」—— 先改那些活动的声明再删`,
      };
      return c.json(body, 409);
    }
    await container.llm.remove(id);
    return c.json({ ok: true });
  });

  /** 测试连接(草稿):只测不存 —— 必须排在 `/:id/probe` 之前,否则会被那条路由吃掉 */
  app.post(probeLlmDraftRoute.path, async (c) => {
    const parsed = probeLlmDraftRoute.body.safeParse(await c.req.json());
    if (!parsed.success) {
      const body: ApiError = { code: 'validation-failed', message: '入参不合法', detail: parsed.error.issues };
      return c.json(body, 400);
    }
    return c.json(await container.llm.probeDraft(parsed.data));
  });

  app.post(probeLlmInstanceRoute.path, async (c) => c.json(await container.llm.probe(c.req.param('id'))));
}