JX-BPOS/packages/contracts/src/api/governance.ts

/**
 * 治理台路由契约(编码规范 §8.1 / §9.1)。
 * 治理台九功能不设后端 governance 模块:每个功能是对应模块的管理用例 + 本文件的路由组装(§3)。
 */
import { z } from 'zod';
import type { RouteContract } from './http.ts';
import { disableCheckSchema, grantSchema, positionSchema, staffSchema, workGroupSchema } from '../org.ts';
import { positionIdSchema, staffIdSchema, taskIdSchema } from '../id.ts';
import { closureReportSchema, processPackageSchema, triggerConfigSchema } from '../process-package.ts';
import { controlSemanticSchema, taskRuntimeStateSchema, terminalStateSchema, workflowStateSchema } from '../terminal.ts';
import { activityManifestSchema, paradigmSchema } from '../manifest.ts';
import { reportMetricsSchema, reportPeriodSchema } from './workbench.ts';

/* ── 员工管理 ─────────────────────────────────────────────────────────── */

export const listStaffRoute = {
  method: 'GET',
  path: '/api/gov/staff',
  output: z.object({
    staff: z.array(staffSchema.extend({ position: positionSchema })),
    positions: z.array(positionSchema),
  }),
} as const satisfies RouteContract;

export const createStaffRoute = {
  method: 'POST',
  path: '/api/gov/staff',
  body: z.object({
    account: z.string().min(1),
    name: z.string().min(1),
    positionId: positionIdSchema,
  }),
  output: staffSchema,
} as const satisfies RouteContract;

export const disableStaffCheckRoute = {
  method: 'GET',
  path: '/api/gov/staff/:staffId/disable-check',
  params: z.object({ staffId: staffIdSchema }),
  output: disableCheckSchema,
} as const satisfies RouteContract;

export const disableStaffRoute = {
  method: 'POST',
  path: '/api/gov/staff/:staffId/disable',
  params: z.object({ staffId: staffIdSchema }),
  output: z.object({ ok: z.boolean(), check: disableCheckSchema }),
} as const satisfies RouteContract;

export const listGrantsRoute = {
  method: 'GET',
  path: '/api/gov/positions/:positionId/grants',
  params: z.object({ positionId: positionIdSchema }),
  output: z.object({ grants: z.array(grantSchema) }),
} as const satisfies RouteContract;

export const setGrantsRoute = {
  method: 'POST',
  path: '/api/gov/positions/:positionId/grants',
  params: z.object({ positionId: positionIdSchema }),
  body: z.object({ grants: z.array(grantSchema) }),
  output: z.object({ grants: z.array(grantSchema) }),
} as const satisfies RouteContract;

/* ── 系统管理 · LLM 实例(四元绑定) ────────────────────────────────── */

export const LLM_PROVIDERS = ['openai-compatible', 'openai', 'deepseek', 'anthropic', 'qwen'] as const;
export const llmProviderSchema = z.enum(LLM_PROVIDERS);
export type LlmProvider = z.infer<typeof llmProviderSchema>;

/** 活动只见自定义模型名;Provider / URL / API-Key / Model 四元在系统侧绑定,活动不触厂商与密钥 */
export const llmInstanceViewSchema = z.object({
  id: z.string(),
  /** 自定义模型名(逻辑名)—— 活动以此声明引用 */
  name: z.string().min(1),
  provider: llmProviderSchema,
  baseUrl: z.string().min(1),
  model: z.string().min(1),
  /** 密钥不出治理台:只回是否已绑定,永不回明文(OS 7.3 凭证隔离) */
  apiKeyBound: z.boolean(),
  /** 系统用途绑定:叙述性小结 / 汇报生成 / 蒸馏钩子,计量入系统账 */
  systemUse: z.boolean().default(false),
  enabled: z.boolean().default(true),
});
export type LlmInstanceView = z.infer<typeof llmInstanceViewSchema>;

export const listLlmInstancesRoute = {
  method: 'GET',
  path: '/api/gov/llm',
  output: z.object({ instances: z.array(llmInstanceViewSchema) }),
} as const satisfies RouteContract;

export const upsertLlmInstanceRoute = {
  method: 'POST',
  path: '/api/gov/llm',
  body: z.object({
    id: z.string().optional(),
    name: z.string().min(1),
    provider: llmProviderSchema,
    /** 留空 = 取该 provider 的默认端点(openai-compatible 没有默认,必须自填) */
    baseUrl: z.string().default(''),
    model: z.string().min(1),
    /** 只写不读:留空表示保持原值 */
    apiKey: z.string().optional(),
    systemUse: z.boolean().default(false),
    enabled: z.boolean().default(true),
  }),
  output: llmInstanceViewSchema,
} as const satisfies RouteContract;

export const probeLlmInstanceRoute = {
  method: 'POST',
  path: '/api/gov/llm/:id/probe',
  params: z.object({ id: z.string() }),
  output: z.object({ ok: z.boolean(), latencyMs: z.number().int().optional(), error: z.string().optional() }),
} as const satisfies RouteContract;

/* ── 任务管理:在途监控 · 控制事件 · 改派 ─────────────────────────────── */

export const govTaskRowSchema = z.object({
  id: taskIdSchema,
  title: z.string(),
  activityId: z.string(),
  paradigm: paradigmSchema,
  ownerName: z.string(),
  runtime: taskRuntimeStateSchema,
  terminal: terminalStateSchema.optional(),
  workflowId: z.string().optional(),
  usedSteps: z.number().int(),
  capSteps: z.number().int(),
  startedAt: z.string(),
});
export type GovTaskRow = z.infer<typeof govTaskRowSchema>;

export const listGovTasksRoute = {
  method: 'GET',
  path: '/api/gov/tasks',
  output: z.object({
    tasks: z.array(govTaskRowSchema),
    workflows: z.array(
      z.object({
        id: z.string(),
        subject: z.string(),
        state: workflowStateSchema,
        packageId: z.string(),
        startedAt: z.string(),
      }),
    ),
  }),
} as const satisfies RouteContract;

/** 控制三语义:暂停 / 叫停 / 终止 —— 治理台的干预面(OS 06) */
export const controlTaskRoute = {
  method: 'POST',
  path: '/api/gov/tasks/:taskId/control',
  params: z.object({ taskId: taskIdSchema }),
  body: z.object({ semantic: controlSemanticSchema, reason: z.string().optional() }),
  output: z.object({ ok: z.boolean(), resumable: z.boolean() }),
} as const satisfies RouteContract;

export const resumeTaskRoute = {
  method: 'POST',
  path: '/api/gov/tasks/:taskId/resume',
  params: z.object({ taskId: taskIdSchema }),
  output: z.object({ ok: z.boolean(), runtime: taskRuntimeStateSchema }),
} as const satisfies RouteContract;

/** 改派 —— 在途任务的负责人变更,留痕并通知双方 */
export const reassignTaskRoute = {
  method: 'POST',
  path: '/api/gov/tasks/:taskId/reassign',
  params: z.object({ taskId: taskIdSchema }),
  body: z.object({ to: staffIdSchema }),
  output: z.object({ ok: z.boolean(), ownerId: staffIdSchema }),
} as const satisfies RouteContract;

/** 任务日志 —— 治理台可查看任意任务的任务日志(OS 02) */
export const govTaskLogRoute = {
  method: 'GET',
  path: '/api/gov/tasks/:taskId/log',
  params: z.object({ taskId: taskIdSchema }),
  output: z.object({
    log: z.array(z.object({ id: z.string(), at: z.string(), sideLabel: z.string(), title: z.string() })),
  }),
} as const satisfies RouteContract;

/* ── 工作流管理:流程包编排与版本 ─────────────────────────────────────── */

export const listProcessPackagesRoute = {
  method: 'GET',
  path: '/api/gov/process',
  output: z.object({ packages: z.array(processPackageSchema) }),
} as const satisfies RouteContract;

/**
 * 保存流程包 —— **严格检查 + 保存即生效**,没有发布这一道门。
 *
 * 不闭合即拒存(412 带闭合报告):存下来的就是能起单的。
 * 保存**恒产生新版本号**,由服务端算 —— body 里的 `version` 只用于「改的是哪一版」的溯源,
 * 服务端不采信它当目标版本号。在途工作流按 (包id, 版本) 读定义,就地覆盖会改掉它们读的东西。
 * 返回的 `pkg.version` 是**实际落的新版本**,`report` 是这一版的闭合报告(必然 closed)。
 */
export const saveProcessRoute = {
  method: 'PUT',
  path: '/api/gov/process',
  /**
   * 编辑即其身:pkg.version 已存在 → 就地写回该版(号不变)。
   * `asNew: true`(或版本不存在,如新流程首版)→ 产生新版本号(服务端算,不生效)。
   * 就地写回的两道闸:在途钉版 409;写回生效版不闭合 412(带整份报告)。
   */
  body: z.object({ pkg: processPackageSchema, asNew: z.boolean().optional() }),
  output: z.object({ pkg: processPackageSchema, report: closureReportSchema }),
} as const satisfies RouteContract;

/**
 * 版本启停 —— 运行时开关,不改定义一个字。
 * 激活某版:同流其余版本一并停用(一条流恰一个生效版本);停用生效版:整条流下线,新起单被拒。
 * 在途工作流按启动时钉住的版本跑完,启停对它们零影响。
 * 返回这条流启停后的全部版本(新→旧),界面直接以它刷新版本列表。
 */
export const setProcessStateRoute = {
  method: 'POST',
  path: '/api/gov/process/:id/:version/state',
  params: z.object({ id: z.string(), version: z.string() }),
  body: z.object({ state: z.enum(['active', 'retired']) }),
  output: z.object({ packages: z.array(processPackageSchema) }),
} as const satisfies RouteContract;

/** 画图即校验 —— 与前端画布同源;保存前随手看还差几条,不改任何状态 */

export const validateProcessRoute = {
  method: 'POST',
  path: '/api/gov/process/validate',
  body: z.object({ pkg: processPackageSchema }),
  output: closureReportSchema,
} as const satisfies RouteContract;

/* ── 触发器配置 ──────────────────────────────────────────────────────── */

export const listTriggersRoute = {
  method: 'GET',
  path: '/api/gov/triggers',
  output: z.object({ triggers: z.array(triggerConfigSchema) }),
} as const satisfies RouteContract;

export const toggleTriggerRoute = {
  method: 'POST',
  path: '/api/gov/triggers/:id/toggle',
  params: z.object({ id: z.string() }),
  body: z.object({ enabled: z.boolean() }),
  output: z.object({ ok: z.boolean() }),
} as const satisfies RouteContract;

/**
 * 调起规则的**定义面**(设计中心):新建 / 改规则 / 改起单装配。
 *
 * 与 `toggleTriggerRoute` 分开是有意的:定义归设计,启停归运营 ——
 * 同一个触发器,「它按什么规则调起」和「今天开不开」是两个人在两个台面上做的两件事。
 * 触发器与流程包平级:改它**不动任何包版本**。
 */
export const upsertTriggerRoute = {
  method: 'PUT',
  path: '/api/gov/triggers',
  body: z.object({ trigger: triggerConfigSchema }),
  output: z.object({ trigger: triggerConfigSchema }),
} as const satisfies RouteContract;

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

/**
 * 工作组 = 一组「岗位 → 员工」的绑定,**起单时装载、随工作流走**。
 *
 * 它是**绑定先于策略**,不是第五种负责人策略:起单人有组,整条流的岗位就按组指人;
 * 没有组才回落四策略。装进工作流的是**快照** —— 改组不改已起的单。
 */
export const listWorkGroupsRoute = {
  method: 'GET',
  path: '/api/gov/work-groups',
  /** `ownerName` 是组长姓名的呈现补充,读表时一并带出,免得前端再对一次 id */
  output: z.object({ groups: z.array(workGroupSchema.extend({ ownerName: z.string() })) }),
} as const satisfies RouteContract;

/** 一人一组:按 `ownerId` 落,已有即更新、没有即新建 */
export const saveWorkGroupRoute = {
  method: 'PUT',
  path: '/api/gov/work-groups',
  body: z.object({
    ownerId: staffIdSchema,
    name: z.string().min(1),
    /** 岗位 code → 员工 id;留空的岗位不绑定,那一位仍走四策略 */
    members: z.record(z.string().min(1), staffIdSchema),
  }),
  output: z.object({ group: workGroupSchema }),
} as const satisfies RouteContract;

/* ── 活动库 · 装入 / 换版(安装通道) ─────────────────────────────── */

/**
 * 经安装通道装入活动包 —— **无代码通道**(ADR-004):交的是清单 + .js 产物,都是数据。
 *
 * 安装两审在服务端跑:静态审读清单(工具契约在否、模型名绑没绑、模版有没有脚本、
 * 声明与已物化的台账冲不冲),回放审重演历史(首装无历史即免,以样例集替代)。
 * **恒为新增、版本并存**:装入不覆盖旧版本,在途任务按其启动时版本跑完。
 */
export const installActivityRoute = {
  method: 'POST',
  path: '/api/gov/activities',
  body: z.object({
    /** 清单六区:身份 / 七件契约 / 声明 / 资产初始版 / 样例集 / 代码入口 */
    manifest: activityManifestSchema,
    /** .js 产物原文 —— 只当数据存,不 import、不 eval */
    artifact: z.string().min(1),
  }),
  output: z.object({
    accepted: z.boolean(),
    activityId: z.string(),
    packageVersion: z.string(),
    staticFindings: z.array(z.object({ code: z.string(), severity: z.string(), message: z.string() })),
    replay: z.object({
      oldPassStillPass: z.boolean(),
      checked: z.number().int(),
      skippedNoHistory: z.boolean(),
      regressions: z.array(z.object({ taskId: z.string(), detail: z.string() })),
    }),
  }),
} as const satisfies RouteContract;

/* ── 工具管理 · 导入自定义工具 ─────────────────────────────────────── */

/**
 * 导入自定义工具 —— 与第一方工具走**同一条门**:静态审 + 试运行审。
 *
 * 工具承载权力,约束严于活动包:契约对活动、实现对系统、凭证对治理台(OS 7.3)。
 * 连接配置**只声明键**;值随本次导入送到治理台加密落库,此后只读得到「是否已绑定」。
 */
export const registerToolRoute = {
  method: 'POST',
  path: '/api/gov/tools',
  body: z.object({
    contract: z.object({
      name: z.string().min(1),
      version: z.string().min(1),
      description: z.string().min(1),
      input: z.record(z.string(), z.unknown()),
      output: z.record(z.string(), z.unknown()),
      effect: z.enum(['read', 'write']),
      errors: z
        .array(z.object({ code: z.string(), retryable: z.boolean(), message: z.string() }))
        .default([]),
      idempotent: z.boolean().default(true),
      timeoutMs: z.number().int().positive().default(10_000),
      retries: z.number().int().min(0).default(1),
      connectionKeys: z.array(z.string()).default([]),
    }),
    /** 连接值只写不读 —— 键在契约里,值密封在治理台 */
    connectionValues: z.record(z.string(), z.string()).optional(),
    /** 契约测试集:没有样例就没有试运行审,门形同虚设 */
    samples: z.array(z.object({ input: z.record(z.string(), z.unknown()) })).min(1),
  }),
  output: z.object({
    accepted: z.boolean(),
    findings: z.array(z.object({ code: z.string(), severity: z.string(), message: z.string() })),
    trialRun: z.object({ ran: z.number().int(), passed: z.number().int(), failures: z.array(z.string()) }),
  }),
} as const satisfies RouteContract;

/* ── 活动库管理:两维分类 × 包版本 × 资产版本 ─────────────────────────── */

export const listActivitiesRoute = {
  method: 'GET',
  path: '/api/gov/activities',
  output: z.object({
    activities: z.array(
      z.object({
        activityId: z.string(),
        name: z.string(),
        category: z.string(),
        paradigm: paradigmSchema,
        enabled: z.boolean(),
        packageVersions: z.array(z.object({ version: z.string(), state: z.string(), installedAt: z.string() })),
        assetVersions: z.array(z.object({ kind: z.string(), version: z.number().int(), effective: z.boolean() })),
        /**
         * 契约面 —— 开发这个活动要照着的东西:吃什么、吐什么、用谁的工具、动哪些域对象。
         * 治理台不给这一层,「编排定契约」就只是句口号:编排的人看不到自己引用的活动要什么。
         */
        contract: z.object({
          requiredInputs: z.array(z.string()),
          inputFields: z.array(z.object({ name: z.string(), type: z.string(), required: z.boolean() })),
          outputPorts: z.array(z.object({ name: z.string(), description: z.string().optional(), fields: z.array(z.string()) })),
          tools: z.array(z.string()),
          models: z.array(z.string()),
          objects: z.array(z.string()),
          roles: z.array(z.string()),
          humanCallBudget: z.number().int(),
        }),
      }),
    ),
  }),
} as const satisfies RouteContract;

/* ── 工具管理 ────────────────────────────────────────────────────────── */

export const listToolsRoute = {
  method: 'GET',
  path: '/api/gov/tools',
  output: z.object({
    tools: z.array(
      z.object({
        name: z.string(),
        version: z.string(),
        description: z.string(),
        effect: z.enum(['read', 'write']),
        pure: z.boolean(),
        connectionKeys: z.array(z.string()),
      }),
    ),
  }),
} as const satisfies RouteContract;

/* ── 数据管理:域 / 对象目录 + 记录浏览 ───────────────────────────────── */

export const listLedgerObjectsRoute = {
  method: 'GET',
  path: '/api/gov/data/objects',
  /** `label` 是人读名(落在表注释上);缺省即没登记,呈现退回对象键 */
  output: z.object({
    objects: z.array(z.object({ domain: z.string(), object: z.string(), label: z.string().optional() })),
  }),
} as const satisfies RouteContract;

export const browseLedgerRoute = {
  method: 'GET',
  path: '/api/gov/data/:domain/:object',
  params: z.object({ domain: z.string(), object: z.string() }),
  output: z.object({
    label: z.string().optional(),
    columns: z.array(z.object({ name: z.string(), type: z.string(), label: z.string().optional() })),
    primaryKey: z.array(z.string()),
    rows: z.array(z.record(z.string(), z.unknown())),
    total: z.number().int(),
  }),
} as const satisfies RouteContract;

/* ── 记忆管理:活动记忆四层 ──────────────────────────────────────────── */

export const listActivityMemoryRoute = {
  method: 'GET',
  path: '/api/gov/memory/:activityId',
  params: z.object({ activityId: z.string() }),
  output: z.object({
    entries: z.array(
      z.object({
        id: z.string(),
        layer: z.string(),
        statement: z.string(),
        evidenceCount: z.number().int(),
        incrementState: z.string().optional(),
        createdAt: z.string(),
      }),
    ),
  }),
} as const satisfies RouteContract;

/* ── 系统管理 · 通道实例 ──────────────────────────────────────────────── */

/** 通道配置里本就没有凭证字段(凭证只在治理台的连接配置中,ADR-009);此处整体可回 */
export const listChannelsRoute = {
  method: 'GET',
  path: '/api/gov/channels',
  output: z.object({
    channels: z.array(
      z.object({
        id: z.string(),
        name: z.string(),
        kind: z.enum(['mail', 'im']),
        address: z.string(),
        enabled: z.boolean(),
        extractCount: z.number().int(),
        mappingCount: z.number().int(),
        fallbackPosition: z.string().optional(),
        addressWindowMs: z.number().int(),
      }),
    ),
  }),
} as const satisfies RouteContract;

/* ── 任务管理 · 审批单 ────────────────────────────────────────────────── */

/** 审批单不是任务:没有预算、没有任务日志,只有批不批(卡在审批人工位的验收工单) */
export const listApprovalsRoute = {
  method: 'GET',
  path: '/api/gov/approvals',
  output: z.object({
    approvals: z.array(
      z.object({
        id: z.string(),
        workflowId: z.string(),
        workflowSubject: z.string(),
        title: z.string(),
        approverName: z.string(),
        state: z.enum(['pending', 'passed', 'rejected']),
        issuedAt: z.string(),
      }),
    ),
  }),
} as const satisfies RouteContract;

/* ── 工作流下钻:实例 × 节点 ──────────────────────────────────────────── */

export const govWorkflowRoute = {
  method: 'GET',
  path: '/api/gov/workflows/:id',
  params: z.object({ id: z.string() }),
  output: z.object({
    workflow: z.object({
      id: z.string(),
      subject: z.string(),
      state: workflowStateSchema,
      packageId: z.string(),
      packageVersion: z.number().int(),
      source: z.object({ kind: z.string(), ref: z.string(), by: z.string().optional() }),
      startedAt: z.string(),
      finishedAt: z.string().optional(),
    }),
    pkg: processPackageSchema,
    instances: z.array(
      z.object({
        nodeId: z.string(),
        instance: z.number().int(),
        running: z.boolean(),
        waiting: z.boolean(),
        activated: z.boolean(),
        terminal: terminalStateSchema.optional(),
      }),
    ),
    tasks: z.array(z.object({ id: taskIdSchema, nodeId: z.string(), title: z.string(), ownerName: z.string() })),
  }),
} as const satisfies RouteContract;

/* ── 记忆管理 · 度量仪表 ──────────────────────────────────────────────── */

/**
 * 度量八指标(OS 8.3)—— 运营驾驶舱的仪表读数。
 *
 * 出参直接复用 `reportMetricsSchema`:**与工作台汇报同源同口径**。
 * 治理台若另算一套,同一个组织会读出两个自主率 —— 那时候争的就不是数,是谁的表准。
 * 自主率与纠正率**成对读**,复合为有效自主率 —— 单看自主率会奖励「猛冲后返工」。
 */
export const govMetricsRoute = {
  method: 'GET',
  path: '/api/gov/metrics',
  /** 统计窗口 —— 不传按月;驾驶舱可切日/周/月/年 */
  query: z.object({ period: reportPeriodSchema.optional() }),
  /** `period` 原样回声:客户端不传时,由它知道服务端用的是哪个窗口 */
  output: reportMetricsSchema.extend({ taskCount: z.number().int(), period: reportPeriodSchema }),
} as const satisfies RouteContract;

/* ── 出参类型:契约自己命名,消费方不再 `z.infer` ──────────────────────── */

export type GovTasksOutput = z.infer<typeof listGovTasksRoute.output>;
export type GovWorkGroupsOutput = z.infer<typeof listWorkGroupsRoute.output>;
export type GovApprovalsOutput = z.infer<typeof listApprovalsRoute.output>;
export type GovStaffOutput = z.infer<typeof listStaffRoute.output>;
export type GovGrantsOutput = z.infer<typeof listGrantsRoute.output>;
export type GovPackagesOutput = z.infer<typeof listProcessPackagesRoute.output>;
export type GovTriggersOutput = z.infer<typeof listTriggersRoute.output>;
export type GovActivitiesOutput = z.infer<typeof listActivitiesRoute.output>;
export type GovToolsOutput = z.infer<typeof listToolsRoute.output>;
export type GovObjectsOutput = z.infer<typeof listLedgerObjectsRoute.output>;
export type GovLedgerPageOutput = z.infer<typeof browseLedgerRoute.output>;
export type GovMemoryOutput = z.infer<typeof listActivityMemoryRoute.output>;
export type GovMetricsOutput = z.infer<typeof govMetricsRoute.output>;
export type GovChannelsOutput = z.infer<typeof listChannelsRoute.output>;
export type GovLlmOutput = z.infer<typeof listLlmInstancesRoute.output>;
export type GovWorkflowOutput = z.infer<typeof govWorkflowRoute.output>;
export type GovTaskLogOutput = z.infer<typeof govTaskLogRoute.output>;