feat(activity-ops): 启动表单两格按芯片类型联动 —— 候选带分组键,先填的那格是锚

契约:launchOption 加 group/groupLabel(x-options.group 从字典表现读人读名)、
launchParam 加 linkGroup(x-link 结组);api-report 已随 --update 入库。
前端 launch-link.ts 纯函数管三条口径:锚摆全量、其余按锚的分组键收窄
(未标类型殿后一组,新增照走);锚粘着 —— 清空只解除收窄不换锚,人改得了主意。
服务端不据此立墙:combo 本就收候选之外的值,类型一致归 S1 收步判据
sub_eval_part_distinct_chip_type_id = 1(数得出来的门)。
W05 清单两格挂上 x-link: chip-type;文档同步。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LKMZDwMbyKzjw6Hembwvet

apps/api/src/app/__tests__/activity-ops-launch-params.test.ts

@@ -208,3 +208,88 @@ describe('validateLaunchParams', () => {
     expect(nan.ok).toBe(false);
   });
 });
+
+/* ── 按分组键联动(2026-08-31 用户定:原料号 / 候选料号按芯片类型互相收窄)────────────
+   派生层只负责把两样东西送到前端:①候选带上它的分组键与人读名(`x-options.group`);
+   ②这一格属于哪个联动组(`x-link`)。收窄怎么摆是前端的事,**服务端不据此立墙**。 */
+describe('x-options.group / x-link', () => {
+  const LINKED = {
+    type: 'object',
+    required: ['originalInternalPn', 'candidateInternalPn'],
+    properties: {
+      originalInternalPn: {
+        type: 'string',
+        title: '原内部料号',
+        'x-control': 'combo',
+        'x-options': {
+          ledger: 'parts.profile',
+          value: 'internal_pn',
+          label: 'internal_pn',
+          group: { column: 'chip_type_id', ledger: 'parts.chip_type', value: 'type_id', label: 'type_name' },
+        },
+        'x-link': 'chip-type',
+        'x-order': 1,
+      },
+      candidateInternalPn: {
+        type: 'string',
+        title: '候选内部料号',
+        'x-control': 'combo',
+        'x-options': { ledger: 'parts.profile', value: 'internal_pn', label: 'internal_pn', group: 'chip_type_id' },
+        'x-link': 'chip-type',
+        'x-order': 2,
+      },
+    },
+  };
+
+  it('分组键两种写法都认:整份声明(带字典)与只写列名;x-link 读成联动组名', () => {
+    const specs = fieldSpecsOf(LINKED);
+    expect(specs[0]?.optionsSource?.group).toEqual({ column: 'chip_type_id', dict: { ledger: 'parts.chip_type', value: 'type_id', label: 'type_name' } });
+    // 只写列名 = 有分组键、没有人读名字典
+    expect(specs[1]?.optionsSource?.group).toEqual({ column: 'chip_type_id', dict: undefined });
+    expect(specs.map((s) => s.linkGroup)).toEqual(['chip-type', 'chip-type']);
+  });
+
+  it('分组键写残(没有 column,或字典缺 ledger/value)就当没声明 —— 候选照出,只是不联动', () => {
+    const bad = fieldSpecsOf({
+      properties: {
+        a: { type: 'string', 'x-control': 'combo', 'x-options': { ledger: 'l.o', value: 'v', group: {} } },
+        b: { type: 'string', 'x-control': 'combo', 'x-options': { ledger: 'l.o', value: 'v', group: { column: 'c', ledger: 'd.t' } } },
+      },
+    });
+    expect(bad[0]?.optionsSource).toEqual({ ledger: 'l.o', value: 'v', label: 'v', group: undefined });
+    // 字典写残 → 只留分组键,人读名没有(不炸)
+    expect(bad[1]?.optionsSource?.group).toEqual({ column: 'c', dict: undefined });
+  });
+
+  it('候选带 group / groupLabel 原样交给前端;有候选才给 linkGroup(一个候选都没有,联动无从谈起)', async () => {
+    const params = await launchParamsOf(LINKED, async (src) =>
+      src.group === undefined
+        ? [{ value: 'AMS1117-3.3', label: 'AMS1117-3.3' }]
+        : [
+            { value: 'LM2596S-5.0', label: 'LM2596S-5.0', group: '1', groupLabel: 'DC-DC 降压稳压器' },
+            { value: 'OLD-001', label: 'OLD-001', group: '' },
+          ],
+    );
+    expect(params[0]).toMatchObject({
+      key: 'originalInternalPn',
+      linkGroup: 'chip-type',
+      options: [
+        { value: 'LM2596S-5.0', label: 'LM2596S-5.0', group: '1', groupLabel: 'DC-DC 降压稳压器' },
+        { value: 'OLD-001', label: 'OLD-001', group: '' },
+      ],
+    });
+    // 候选读不到 → 仍是 combo,但不摆联动组(前端没有可收窄的东西)
+    const empty = await launchParamsOf(LINKED, noResolve);
+    expect(empty[0]?.linkGroup).toBeUndefined();
+    expect(empty[0]?.type).toBe('combo');
+  });
+
+  it('服务端不据分组立墙:两格填不同类型的料号照样收(类型一致归活动的收步判据管)', async () => {
+    const params = await launchParamsOf(LINKED, async () => [
+      { value: 'LM2596S-5.0', label: 'LM2596S-5.0', group: '1' },
+      { value: 'AMS1117-3.3', label: 'AMS1117-3.3', group: '2' },
+    ]);
+    const out = validateLaunchParams(params, { originalInternalPn: 'LM2596S-5.0', candidateInternalPn: 'AMS1117-3.3' }, fieldSpecsOf(LINKED));
+    expect(out).toEqual({ ok: true, data: { originalInternalPn: 'LM2596S-5.0', candidateInternalPn: 'AMS1117-3.3' } });
+  });
+});

apps/api/src/app/__tests__/activity-ops-service.test.ts

@@ -374,6 +374,80 @@ describe('启动', () => {
     expect(table?.params[0]?.options).toEqual([{ value: 'CU-0142', label: 'Itelma' }, { value: 'CU-0001', label: 'CU-0001' }]);
   });
 
+  /* 联动(2026-08-31 用户定):候选行上多取一列当分组键,再从字典表换人读名交给前端 */
+  const LINKED_MANIFEST = (): ManifestFace =>
+    manifest({
+      contract: {
+        input: {
+          data: {
+            type: 'object',
+            required: ['originalInternalPn', 'candidateInternalPn'],
+            properties: {
+              originalInternalPn: {
+                type: 'string',
+                title: '原内部料号',
+                'x-control': 'combo',
+                'x-options': { ledger: 'parts.profile', value: 'internal_pn', label: 'internal_pn', group: { column: 'chip_type_id', ledger: 'parts.chip_type', value: 'type_id', label: 'type_name' } },
+                'x-order': 1,
+                'x-link': 'chip-type',
+              },
+              candidateInternalPn: {
+                type: 'string',
+                title: '候选内部料号',
+                'x-control': 'combo',
+                'x-options': { ledger: 'parts.profile', value: 'internal_pn', label: 'internal_pn', group: { column: 'chip_type_id', ledger: 'parts.chip_type', value: 'type_id', label: 'type_name' } },
+                'x-order': 2,
+                'x-link': 'chip-type',
+              },
+            },
+          },
+        },
+      },
+    });
+  const PARTS: Record<string, Record<string, unknown>[]> = {
+    'parts.profile': [
+      { internal_pn: 'AMS1117-3.3', chip_type_id: '2' },
+      { internal_pn: 'LM2596S-5.0', chip_type_id: '1' },
+      { internal_pn: 'OLD-001', chip_type_id: null },
+    ],
+    'parts.chip_type': [
+      { type_id: '1', type_name: 'DC-DC 降压稳压器' },
+      { type_id: '2', type_name: 'LDO 线性稳压器' },
+    ],
+  };
+  const partsLedger = (over: Partial<ActivityOpsDeps['ledger']> = {}): ActivityOpsDeps['ledger'] => ({
+    describe: async (address) => {
+      const rows = PARTS[`${address.domain}.${address.object}`];
+      return rows === undefined ? undefined : { columns: Object.keys(rows[0] ?? {}).map((name) => ({ name })) };
+    },
+    query: async (q) => ({ rows: PARTS[`${q.address.domain}.${q.address.object}`] ?? [] }),
+    ...over,
+  });
+
+  it('候选带分组键 + 字典换来的人读名;那一列没值就是空串(未标类型),联动组名随参数下发', async () => {
+    const { ops } = harness({ manifest: LINKED_MANIFEST(), ledger: partsLedger() });
+    const table = await ops.launchParams(W05);
+    expect(table?.params.map((p) => p.linkGroup)).toEqual(['chip-type', 'chip-type']);
+    expect(table?.params[0]?.options).toEqual([
+      { value: 'AMS1117-3.3', label: 'AMS1117-3.3', group: '2', groupLabel: 'LDO 线性稳压器' },
+      { value: 'LM2596S-5.0', label: 'LM2596S-5.0', group: '1', groupLabel: 'DC-DC 降压稳压器' },
+      { value: 'OLD-001', label: 'OLD-001', group: '' },
+    ]);
+  });
+
+  it('分组那一列不存在 / 字典读不到 → 候选照出,只是没有键或没有名(不炸)', async () => {
+    const noColumn = harness({
+      manifest: LINKED_MANIFEST(),
+      ledger: partsLedger({ describe: async (a) => (a.object === 'profile' ? { columns: [{ name: 'internal_pn' }] } : { columns: [{ name: 'type_id' }, { name: 'type_name' }] }) }),
+    });
+    const t1 = await noColumn.ops.launchParams(W05);
+    expect(t1?.params[0]?.options?.every((o) => o.group === undefined)).toBe(true);
+    // 分组键在、字典表没物化 → 有键没名
+    const noDict = harness({ manifest: LINKED_MANIFEST(), ledger: partsLedger({ describe: async (a) => (a.object === 'chip_type' ? undefined : { columns: [{ name: 'internal_pn' }, { name: 'chip_type_id' }] }) }) });
+    const t2 = await noDict.ops.launchParams(W05);
+    expect(t2?.params[0]?.options?.[0]).toEqual({ value: 'AMS1117-3.3', label: 'AMS1117-3.3', group: '2' });
+  });
+
   it('禁用 412 / 责任人不在职 400 / 参数不合 400 —— 都不起单', async () => {
     const { ops, started } = harness({ enabled: false });
     expect((await ops.launch(W05, launchInput(), ME)).kind).toBe('disabled');

apps/api/src/app/activity-ops/launch-params.ts

@@ -7,6 +7,10 @@
  *   · `x-control`:`text | textarea | select | combo` —— 不写就按类型推:enum → select、`array<string>` → list、string → text;
  *     **数组字段也可以标 combo / select**(表单只选一颗,提交单个字符串,后端包成一元数组;传数组也照收)
  *   · `x-options`:`{ ledger: '域.对象', value: '列', label: '列' }` —— combo / select 的候选从正式台账现读(客户 / 料号这类「台账里可能有」的)
+ *   · `x-options.group`:候选的**分组键**(2026-08-31 用户定)—— 只写列名(`'chip_type_id'`)= 有键没名;
+ *     整份写 `{ column, ledger, value, label }` 再从字典表换人读名(`parts.chip_type.type_id → type_name`)
+ *   · `x-link`:联动组名 —— 同名的几格按候选的分组键互相收窄(组内先填的那格是锚,其余按锚的键收窄)。
+ *     **服务端不据此立墙**:combo 本就收候选之外的值(新增料号),类型一致归活动自己的收步判据管
  *   · `format: 'file'` 的字段**本期不上表单**(文档没有文件控件;W05 的 datasheet 在数据工单里传)
  *   · `x-order`:表单里的次序(数字,小的在前)。**必须声明**才有稳定次序 —— 清单存在 jsonb 里,
  *     PG 按键长再按字节序重排对象键,`properties` 的书写顺序到不了这里(实测:原料号跑到了客户需求前面)
@@ -17,7 +21,13 @@
 import type { LaunchOption, LaunchParam, LaunchParamType } from '@contracts';
 import { LAUNCH_PARAM_TYPES } from '@contracts';
 
-export type OptionsSource = { readonly ledger: string; readonly value: string; readonly label: string };
+/**
+ * 候选的**分组键**(2026-08-31 用户定的联动):`column` 是候选行上取哪一列当键(如 `chip_type_id`),
+ * `dict` 是把这枚键换成人读名的字典表(如 `parts.chip_type.type_id → type_name`);
+ * 字典没声明 / 写残 → 只有键没有名(界面退回摆键本身,不炸)。
+ */
+export type GroupSource = { readonly column: string; readonly dict: { readonly ledger: string; readonly value: string; readonly label: string } | undefined };
+export type OptionsSource = { readonly ledger: string; readonly value: string; readonly label: string; readonly group: GroupSource | undefined };
 
 /** 一个入参字段的规格 —— JSON Schema 里我们认的那几个词 */
 export type FieldSpec = {
@@ -34,6 +44,8 @@ export type FieldSpec = {
   readonly example: unknown;
   readonly defaultValue: unknown;
   readonly optionsSource: OptionsSource | undefined;
+  /** 联动组名(`x-link`);同名的几格按候选的分组键互相收窄 —— 摆法在前端,服务端不据此立墙 */
+  readonly linkGroup: string | undefined;
   /** 表单次序(`x-order`);没声明的排在声明了的后面、彼此保持读到的顺序 */
   readonly order: number | undefined;
 };
@@ -46,6 +58,24 @@ function asString(value: unknown): string | undefined {
   return typeof value === 'string' ? value : undefined;
 }
 
+/** `x-options.group`:只写列名(字符串)= 有键没名;整份声明 = 键 + 换名字典。写残当没声明 —— 候选照出,只是不联动 */
+function groupSourceOf(value: unknown): GroupSource | undefined {
+  const asColumn = asString(value);
+  if (asColumn !== undefined) return asColumn === '' ? undefined : { column: asColumn, dict: undefined };
+  const raw = asRecord(value);
+  if (raw === undefined) return undefined;
+  const column = asString(raw['column']);
+  if (column === undefined || column === '') return undefined;
+  const ledger = asString(raw['ledger']);
+  const valueCol = asString(raw['value']);
+  const labelCol = asString(raw['label']);
+  const dict =
+    ledger === undefined || !ledger.includes('.') || valueCol === undefined || valueCol === ''
+      ? undefined
+      : { ledger, value: valueCol, label: labelCol === undefined || labelCol === '' ? valueCol : labelCol };
+  return { column, dict };
+}
+
 function optionsSourceOf(value: unknown): OptionsSource | undefined {
   const raw = asRecord(value);
   if (raw === undefined) return undefined;
@@ -53,7 +83,7 @@ function optionsSourceOf(value: unknown): OptionsSource | undefined {
   const valueCol = asString(raw['value']);
   const labelCol = asString(raw['label']);
   if (ledger === undefined || !ledger.includes('.') || valueCol === undefined || valueCol === '') return undefined;
-  return { ledger, value: valueCol, label: labelCol === undefined || labelCol === '' ? valueCol : labelCol };
+  return { ledger, value: valueCol, label: labelCol === undefined || labelCol === '' ? valueCol : labelCol, group: groupSourceOf(raw['group']) };
 }
 
 /** `input.data` 的 properties 逐个读成规格,保属性序(表单顺序就是清单顺序) */
@@ -81,6 +111,7 @@ export function fieldSpecsOf(inputSchema: Readonly<Record<string, unknown>>): Fi
       example: Array.isArray(examples) ? examples[0] : undefined,
       defaultValue: spec['default'],
       optionsSource: optionsSourceOf(spec['x-options']),
+      linkGroup: asString(spec['x-link']) === '' ? undefined : asString(spec['x-link']),
       order: typeof spec['x-order'] === 'number' && Number.isFinite(spec['x-order']) ? spec['x-order'] : undefined,
     };
   });
@@ -159,6 +190,8 @@ export function launchParamOf(spec: FieldSpec, resolved: readonly LaunchOption[]
     ...(placeholder === undefined ? {} : { placeholder }),
     ...(withOptions ? { options } : {}),
     ...(fallback === undefined ? {} : { default: fallback }),
+    /* 联动只在真有候选时才谈得上 —— 一个候选都没有的 combo 摆了组名,前端也没有可收窄的东西 */
+    ...(withOptions && spec.linkGroup !== undefined ? { linkGroup: spec.linkGroup } : {}),
   };
 }
 

apps/api/src/app/activity-ops/service.ts

@@ -38,7 +38,7 @@ import type { StartTaskInput } from '@modules/task';
 import { MIME_OF } from '../file-compose.ts';
 import type { FileFormat } from '../file-compose.ts';
 import { fieldSpecsOf, launchParamsOf, validateLaunchParams } from './launch-params.ts';
-import type { FieldSpec, LaunchIssue, OptionsSource } from './launch-params.ts';
+import type { FieldSpec, GroupSource, LaunchIssue, OptionsSource } from './launch-params.ts';
 import { instanceStateOf, verdictFactOf } from './instance-state.ts';
 import type { StateVerdict } from './instance-state.ts';
 import { followRes, stepsOf } from './instance-steps.ts';
@@ -229,6 +229,34 @@ export function createActivityOps(deps: ActivityOpsDeps): ActivityOps {
     return { ...rest, desc: profile?.description ?? '', view: hasView ? { url: `/api/gov/activities/${card.activityId}/view` } : null };
   }
 
+  /**
+   * 分组键的人读名字典(`x-options.group.dict`)—— 键 → 名。
+   * 表没物化 / 列不在 / 查不动 → 空表(候选仍带键、只是没有名;界面退回摆键本身,不炸)。
+   */
+  async function groupLabels(dict: NonNullable<GroupSource['dict']>): Promise<ReadonlyMap<string, string>> {
+    const [domain, object] = dict.ledger.split('.', 2);
+    if (domain === undefined || object === undefined || domain === '' || object === '') return new Map();
+    const address = { domain, object };
+    const described = await deps.ledger.describe(address).catch(() => undefined);
+    if (described === undefined || !described.columns.some((c) => c.name === dict.value) || !described.columns.some((c) => c.name === dict.label)) {
+      warn(`[activity-ops] 分组人读名读不到:${dict.ledger} 未物化或没有列 ${dict.value} / ${dict.label}`);
+      return new Map();
+    }
+    const page = await deps.ledger.query({ address, where: {}, orderBy: [], limit: OPTIONS_CAP, offset: 0 }).catch((error: unknown) => {
+      warn(`[activity-ops] 分组人读名查询失败:${dict.ledger} —— ${error instanceof Error ? error.message : String(error)}`);
+      return undefined;
+    });
+    const out = new Map<string, string>();
+    for (const row of page?.rows ?? []) {
+      const key = row[dict.value];
+      const name = row[dict.label];
+      if (key === undefined || key === null || String(key) === '') continue;
+      if (name === undefined || name === null || String(name) === '') continue;
+      out.set(String(key), String(name));
+    }
+    return out;
+  }
+
   /** combo / select 的候选从正式台账现读;表没物化、列不存在、查询失败 → 没有候选(不炸,说一声) */
   async function resolveOptions(source: OptionsSource): Promise<readonly LaunchOption[] | undefined> {
     const [domain, object] = source.ledger.split('.', 2);
@@ -251,13 +279,22 @@ export function createActivityOps(deps: ActivityOpsDeps): ActivityOps {
         return undefined;
       });
     if (page === undefined) return undefined;
+    /* 分组键(联动用):声明了、且候选表真有这一列才取 —— 列不在就当没声明(候选照出,只是不联动) */
+    const group = source.group !== undefined && columns.has(source.group.column) ? source.group : undefined;
+    if (source.group !== undefined && group === undefined) warn(`[activity-ops] 分组键读不到:${source.ledger} 没有列 ${source.group.column}`);
+    const names = group?.dict === undefined ? new Map<string, string>() : await groupLabels(group.dict);
     return page.rows
       .map((row) => {
         const value = row[source.value];
         const label = row[source.label];
         const v = value === undefined || value === null ? '' : String(value);
         const l = label === undefined || label === null || String(label) === '' ? v : String(label);
-        return { value: v, label: l };
+        if (group === undefined) return { value: v, label: l };
+        const raw = row[group.column];
+        /* 那一列没值 = 「未标类型」:空串是它自己的一档,不是「没有分组键这回事」 */
+        const key = raw === undefined || raw === null ? '' : String(raw);
+        const name = names.get(key);
+        return { value: v, label: l, group: key, ...(name === undefined ? {} : { groupLabel: name }) };
       })
       .filter((o) => o.value !== '');
   }