BPOS-TMP-REPO/packages/contracts/src/process-package.ts

/**
 * 流程包 DSL 与触发器配置(编码规范 §8.1;语义出处 OS 03)。
 *
 * 流程包 = 调用接口 + 两种活动(声明)+ 审批点 + 两种网关;工作流 = 其运行时实例。
 * 触发器与流程包**平级**:不入流程包结构、不随流程包版本,配置独立存放。
 *
 * 编排铁律:**连线即映射,画图即校验,不闭合不得发布** —— 存在未完成边、未满足必填
 * 或类型冲突的流程包可存草稿、不得发布。校验算法在 `process` 的 domain,本文件只定形状。
 */
import { z } from 'zod';
import {
  activityIdSchema,
  nodeIdSchema,
  processPackageIdSchema,
  staffIdSchema,
  triggerIdSchema,
} from './id.ts';
import { jsonSchemaSchema } from './contract7.ts';

/* ── 负责人四策略(OS 03) ──────────────────────────────────────────── */

export const OWNER_STRATEGIES = ['assigned', 'sole', 'rotation', 'follow-source'] as const;
export const ownerStrategySchema = z.enum(OWNER_STRATEGIES);
export type OwnerStrategy = z.infer<typeof ownerStrategySchema>;

export const OWNER_STRATEGY_LABEL: Readonly<Record<OwnerStrategy, string>> = {
  assigned: '指定人',
  sole: '岗位唯一人',
  rotation: '轮值',
  'follow-source': '来源跟随',
};

export const ownerSpecSchema = z.object({
  /** 编排声明岗位,起单时确定性解析 */
  position: z.string().min(1),
  strategy: ownerStrategySchema.default('sole'),
  /** strategy = assigned 时直接绑定员工(慎用) */
  staffId: staffIdSchema.optional(),
});
export type OwnerSpec = z.infer<typeof ownerSpecSchema>;

/* ── 边与载荷映射 ────────────────────────────────────────────────────── */

/**
 * 映射来源四类:上游输出口载荷字段 / 流程变量 / 起单载荷 / 常量;
 * 允许 S-FEEL 表达式做转换(与触发器字段映射同一形式)。
 */
export const mappingSourceSchema = z.discriminatedUnion('from', [
  z.object({ from: z.literal('output-port'), port: z.string().min(1), path: z.string().min(1) }),
  z.object({ from: z.literal('workflow-var'), name: z.string().min(1) }),
  z.object({ from: z.literal('initiation'), path: z.string().min(1) }),
  z.object({ from: z.literal('constant'), value: z.unknown() }),
  z.object({ from: z.literal('expression'), sfeel: z.string().min(1) }),
]);
export type MappingSource = z.infer<typeof mappingSourceSchema>;

export const fieldMappingSchema = z.object({
  /** 下游活动契约 data 的字段路径 */
  target: z.string().min(1),
  source: mappingSourceSchema,
});
export type FieldMapping = z.infer<typeof fieldMappingSchema>;

export const edgeSchema = z.object({
  id: z.string().min(1),
  from: nodeIdSchema,
  to: nodeIdSchema,
  /** XOR 网关出边的条件(S-FEEL);AND 出边留空 */
  condition: z.string().optional(),
  /** 连一条边即须完成该边映射 —— 必填未映射 = 边未完成 */
  mapping: z.array(fieldMappingSchema).default([]),
  /** 边标签:画布上的出口名(如「TYPE-A」「通过」) */
  label: z.string().optional(),
  /** 边标签色调(呈现):ok = 绿(通过类) / bad = 红(驳回类) */
  tone: z.enum(['ok', 'bad']).optional(),
  /** 回边标记:人裁决后重开新任务实例(同节点、新任务 ID、留痕关联) */
  reopen: z.boolean().default(false),
});
export type Edge = z.infer<typeof edgeSchema>;

/* ── 失败走向四选一(OS 03) ────────────────────────────────────────── */

export const failureDispositionSchema = z.discriminatedUnion('kind', [
  z.object({ kind: z.literal('terminate') }),
  z.object({ kind: z.literal('reroute'), edgeId: z.string().min(1) }),
  z.object({ kind: z.literal('escalate'), approvalNodeId: nodeIdSchema }),
  /** 仅限 AND 分支;静态校验其下游映射不得依赖该分支的必填字段 */
  z.object({ kind: z.literal('tolerate') }),
]);
export type FailureDisposition = z.infer<typeof failureDispositionSchema>;

export const FAILURE_DISPOSITION_LABEL: Readonly<Record<FailureDisposition['kind'], string>> = {
  terminate: '终止流',
  reroute: '改道',
  escalate: '升审批',
  tolerate: '容忍',
};

/* ── 催办阶梯(时限机制复用) ────────────────────────────────────────── */

export const nudgeLadderSchema = z.object({
  /** ISO-8601 duration */
  deadline: z.string().min(2),
  steps: z.array(z.object({ after: z.string().min(2), action: z.enum(['nudge', 'escalate']) })).default([]),
});
export type NudgeLadder = z.infer<typeof nudgeLadderSchema>;

/* ── 节点 ─────────────────────────────────────────────────────────────── */

/*
 * 节点只分**活动点**与**审批点**(产品决策 2026-07-28 第二轮),外加结构件起点/终点。
 * 没有网关:分支 = 源节点的条件出边,汇合 = 多入边异或(schema 级保证,不是校验项)。
 * 库中数据已随外科手术清空,历史读取无包袱;AND 并行待「并行组」声明(debt M5-4)。
 */
const nodeBase = {
  id: nodeIdSchema,
  label: z.string().min(1),
  /** 画布上的第二行小字(如「照谱执行 / 临场演绎」)—— 呈现注记,不影响语义 */
  sub: z.string().optional(),
  /**
   * 画布坐标 —— 布局引擎的输入;不影响语义。
   * row/col = 编译布局的行列;x/y = **手绘几何**(编辑器保存后,手绘成为呈现真相)。
   */
  layout: z
    .object({
      row: z.number().int(),
      col: z.number().int(),
      x: z.number().optional(),
      y: z.number().optional(),
    })
    .optional(),
};

export const processNodeSchema = z.discriminatedUnion('kind', [
  z.object({ ...nodeBase, kind: z.literal('start') }),
  z.object({
    ...nodeBase,
    kind: z.literal('end'),
    /** 流程包显式终点的输出声明 */
    output: jsonSchemaSchema.optional(),
  }),
  z.object({
    ...nodeBase,
    kind: z.literal('activity'),
    /** 以声明入流:引用活动库中已安装的活动 */
    activityId: activityIdSchema,
    /**
     * 契约注记(编排定契约,AM 03):这个节点**声明**吃什么、吐什么。
     * 是「导出依赖文件」的骨架 —— 开发者对着声明在系统外开发活动;
     * 闭合校验的机检仍以边映射与活动契约面为准,注记是给人读的那一层。
     */
    in: z.array(z.string()).optional(),
    out: z.array(z.string()).optional(),
    /** 版本约束:留空 = 装配时取最新生效版 */
    activityVersion: z.string().optional(),
    /*
     * **不带负责人岗位**(产品决策 2026-07-28 第三轮):谁来干是运营的事,
     * 编排契约只管干什么、什么顺序。运营分派机制未建前,运行时默认全员轮值(最闲者先);
     * 审批点例外 —— 「卡到人的工位」是它的功能语义,approver 留在声明里。
     */
    failure: failureDispositionSchema.default({ kind: 'terminate' }),
    /** 委托消息模板,可插值载荷字段;缺省为空 */
    message: z.string().optional(),
  }),
  z.object({
    ...nodeBase,
    kind: z.literal('approval'),
    /** 审批点功能属性四件:审批岗位 / 输入装配映射 / 驳回走向 / 催办阶梯 */
    approver: ownerSpecSchema,
    /** 驳回走向:声明式,不由临场决定 */
    reject: z.discriminatedUnion('kind', [
      z.object({ kind: z.literal('reopen'), nodeId: nodeIdSchema, mapping: z.array(fieldMappingSchema).default([]) }),
      z.object({ kind: z.literal('terminate') }),
    ]),
    nudge: nudgeLadderSchema.optional(),
    message: z.string().optional(),
  }),
]);
export type ProcessNode = z.infer<typeof processNodeSchema>;

/* ── 调用接口:流程包的唯一出入口 ───────────────────────────────────── */

export const callInterfaceSchema = z.object({
  input: jsonSchemaSchema,
  /** 显式终点的输出声明 —— 末端输出载荷按此交付、按来源回执 */
  output: jsonSchemaSchema,
});
export type CallInterface = z.infer<typeof callInterfaceSchema>;

/* ── 流程包 ───────────────────────────────────────────────────────────── */

/**
 * 流程包状态 —— **没有草稿态,也没有发布态**。
 *
 * 「严格检查 + 保存生效」:保存时跑闭合校验,不闭合直接拒存;存下来的就是生效的。
 * 生效与否由**运行时**决定 —— 新工作流起单时取最新版,在途的按启动时快照的版本跑完。
 * 所以不需要「已发布」这个标记:能存进来的版本都能起单。
 *
 * 保存**恒产生新版本号**(服务端算):工作流按 (包id, 版本) 读定义,
 * 就地覆盖会改掉在途任务正在读的东西 —— 那正是「旧任务走完旧版本」要防的。
 * `retired` 留给「这一版不再可起单」,起单时拒。
 */
export const PROCESS_PACKAGE_STATES = ['active', 'retired'] as const;
export const processPackageStateSchema = z.enum(PROCESS_PACKAGE_STATES);
export type ProcessPackageState = z.infer<typeof processPackageStateSchema>;

export const processPackageSchema = z.object({
  id: processPackageIdSchema,
  name: z.string().min(1),
  version: z.number().int().min(1),
  state: processPackageStateSchema,
  callInterface: callInterfaceSchema,
  nodes: z.array(processNodeSchema).min(2),
  edges: z.array(edgeSchema),
  /** 流程变量声明:边映射的 workflow-var 来源 */
  variables: z.array(z.object({ name: z.string().min(1), schema: jsonSchemaSchema })).default([]),
  description: z.string().optional(),
  /**
   * 手绘图存证(可空):编辑器保存的 FlowGraph 原样落此 —— **手绘几何即呈现真相**。
   * 语义(节点/边/映射)永远以上面的 nodes/edges 为准,流转判断不读它;
   * 它只承载语义装不下的画布事实:卡点、行分组、锚定、折线点。
   */
  diagram: z.record(z.string(), z.unknown()).optional(),
});
export type ProcessPackage = z.infer<typeof processPackageSchema>;

/* ── 编排校验的报告形状(前端画布即时预览与后端裁决同源) ───────────── */

export const CLOSURE_VIOLATION_KINDS = [
  'edge-unmapped',
  'required-unmapped',
  'type-conflict',
  'dangling-node',
  /** 多出边的无条件默认兜底超过一条 —— 第二条默认永远走不到 */
  'multi-default-edge',
  'tolerate-required-dependency',
  'unknown-activity',
  'missing-owner-position',
] as const;
export const closureViolationKindSchema = z.enum(CLOSURE_VIOLATION_KINDS);
export type ClosureViolationKind = z.infer<typeof closureViolationKindSchema>;

export const closureViolationSchema = z.object({
  kind: closureViolationKindSchema,
  nodeId: nodeIdSchema.optional(),
  edgeId: z.string().optional(),
  field: z.string().optional(),
  message: z.string(),
});
export type ClosureViolation = z.infer<typeof closureViolationSchema>;

export const closureReportSchema = z.object({
  /** 边是否闭合 —— 不闭合即**拒存**(从前叫 publishable,那时闭合只拦发布) */
  closed: z.boolean(),
  violations: z.array(closureViolationSchema),
});
export type ClosureReport = z.infer<typeof closureReportSchema>;

/* ── 触发器三类(OS 3.1) ──────────────────────────────────────────── */

export const TRIGGER_KINDS = ['periodic', 'event', 'registration'] as const;
export const triggerKindSchema = z.enum(TRIGGER_KINDS);
export type TriggerKind = z.infer<typeof triggerKindSchema>;

export const TRIGGER_KIND_LABEL: Readonly<Record<TriggerKind, string>> = {
  periodic: '周期触发',
  event: '事件触发',
  registration: '登记触发',
};

export const triggerConfigSchema = z.object({
  id: triggerIdSchema,
  name: z.string().min(1),
  enabled: z.boolean().default(true),
  /** 触发器只知道调用接口,不知流程内部 */
  processPackageId: processPackageIdSchema,
  /** 起单载荷装配:事件信封与载荷字段 → 调用接口的 data 字段;缺必填即起单失败入死信 */
  mapping: z.array(fieldMappingSchema).default([]),
  /**
   * 判别式取**四个互斥值**:周期触发的两型(日历 / 数据日历)在此展开 ——
   * `TRIGGER_KINDS` 仍是三类分类学(周期 / 事件 / 登记),两者以 `triggerKindOf()` 对应。
   */
  spec: z.discriminatedUnion('kind', [
    z.object({
      kind: z.literal('periodic-calendar'),
      /** cron 风格的日历表达式 */
      calendar: z.string().min(1),
    }),
    z.object({
      kind: z.literal('periodic-data'),
      /** 数据日历型:按台账日期字段 + 偏移 + 过滤条件逐行起单 */
      domain: z.string().min(1),
      object: z.string().min(1),
      dateField: z.string().min(1),
      /** 偏移:如 -P3D 表示日期字段前 3 天 */
      offset: z.string().min(2),
      filter: z.string().optional(),
    }),
    z.object({
      kind: z.literal('event'),
      /** 命中规则:S-FEEL,对事件信封与载荷字段求值 */
      rule: z.string().min(1),
      eventType: z.enum(['data', 'time', 'human', 'control']).default('data'),
    }),
    z.object({
      kind: z.literal('registration'),
      /** 登记表单由调用接口 schema 自动渲染 */
      formHint: z.string().optional(),
    }),
  ]),
});
export type TriggerConfig = z.infer<typeof triggerConfigSchema>;

/** 四个判别值 → 三类分类学(OS 3.1) */
export function triggerKindOf(spec: TriggerConfig['spec']): TriggerKind {
  return spec.kind === 'event' ? 'event' : spec.kind === 'registration' ? 'registration' : 'periodic';
}