fix(sharing): write the sharing-rule help text for the admin who reads it (#3821)

baozhoutao · claude · baozhoutao · commit bc9e94549759 · 2026-07-28T08:02:13.000-07:00
The field `description`s on `sys_sharing_rule` render as help text under each
input in Setup. They were written as notes for the next engineer:

  接收访问权限的主体类型——求值时会展开为用户授权。`business_unit` 会沿
  parent_business_unit_id 树展开；`team` 为扁平结构（better-auth）；`position`
  展开为该岗位的任职人（岗位为扁平结构，ADR-0090 D3）…（ADR-0057 D5）。

ADR numbers, table and column names, a third-party library, and enum machine
values the dropdown never displays — it shows 用户 / 团队 / 业务单元 / 岗位.

Several were also stale, some of them because of this very issue's UI work:
`recipient_id` still said "fill in a business-unit id / team id / position name"
after it became a record picker; `object_name` still said "short object name
(e.g. opportunity, account)" after it became an object picker; `criteria_json`
still described hand-written `FilterCondition` JSON after it became a visual
builder — and carried "(FilterCondition JSON)" in its LABEL.

All of it rewritten for the reader who actually sees it, in en / zh-CN / ja-JP /
es-ES. The engine detail was already in the object's doc comment, which is where
it stays; a comment on the first field now says so, so the next author doesn't
put it back. `active` can finally state what it does — turning it off withdraws
the access — which only became true with the reconcile fix in this branch. The
list page's subtitle and the `managed_by` / `customized` help got the same
treatment.

Browser-verified in the showcase Console: no ADR, table, column, enum or library
name survives anywhere in the create dialog, the detail page or the list header.

Co-Authored-By: Claude Opus 5 &lt;noreply@anthropic.com&gt;
diff --git a/.changeset/sharing-rule-unknown-sort-and-stale-help.md b/.changeset/sharing-rule-unknown-sort-and-stale-help.md
@@ -43,6 +43,19 @@ through the plain data API used to orphan its grants. Seeding and package
 bootstrap write with `isSystem` and are skipped; `kernel:bootstrapped` already
 backfills those. Reconciliation is best-effort and never fails the write.
 
+**The dialog's help text was engineering notes, shown to tenant admins.** The
+field descriptions on `sys_sharing_rule` render under each input in Setup, and
+they cited ADR numbers, table and column names (`parent_business_unit_id`,
+`sys_business_unit`), enum machine values the dropdown never shows
+(`business_unit`, `team`), a third-party library (better-auth), and engine
+vocabulary ("evaluation", "lifecycle"). Several were also stale: they still told
+admins to type an id or hand-write a `FilterCondition` after those inputs became
+a record picker and a visual builder. Rewritten for the reader who actually sees
+them — the implementation detail was already in the object's doc comment, which
+is where it stays. `criteria_json`'s LABEL loses its "(FilterCondition JSON)"
+suffix for the same reason, and `active` can finally say what it now does:
+turning it off withdraws the access.
+
 Also refreshes the `sys_sharing_rule` help text in the zh-CN / ja-JP / es-ES
 translation bundles, which still described `recipient_type` in terms of
 `department` (the enum value is `business_unit`) and told admins to enter a
diff --git a/packages/plugins/plugin-sharing/src/objects/sys-sharing-rule.object.ts b/packages/plugins/plugin-sharing/src/objects/sys-sharing-rule.object.ts
@@ -37,7 +37,7 @@ export const SysSharingRule = ObjectSchema.create({
   // We still recommend `defineSharingRule({...})` for repo-controlled
   // baselines, but admins can safely create/edit/delete from the UI.
   userActions: { create: true, edit: true, delete: true, import: false },
-  description: 'Declarative sharing rule that auto-materialises sys_record_share grants. Authored via defineSharingRule() in code or the Studio criteria builder.',
+  description: 'Grants a group of people access to the records that match a condition.',
   displayNameField: 'name',
   nameField: 'name', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
   titleFormat: '{label}',
@@ -99,7 +99,13 @@ export const SysSharingRule = ObjectSchema.create({
       label: 'Name',
       required: true,
       maxLength: 100,
-      description: 'Unique snake_case rule name',
+      // Field `description`s on this object are ADMIN-FACING help text rendered
+      // under each input in Setup — not notes for the next engineer. They must
+      // not name tables, columns, enum values, ADRs or third-party libraries:
+      // the reader is a tenant admin who sees only the labels in the dropdown
+      // (objectstack#3821). Implementation detail belongs in the doc comments
+      // above, where it already is.
+      description: 'Identifies the rule. Lowercase letters, digits and underscores only.',
       group: 'Identity',
     }),
 
@@ -124,20 +130,20 @@ export const SysSharingRule = ObjectSchema.create({
       // instead of a free-text machine-name input. Falls back to a text input
       // when the `field:object-ref` widget is unavailable.
       widget: 'object-ref',
-      description: 'Short object name (e.g. opportunity, account)',
+      description: 'The object whose records this rule shares.',
       group: 'Target',
     }),
 
     criteria_json: Field.textarea({
-      label: 'Criteria (FilterCondition JSON)',
+      label: 'Criteria',
       required: false,
       // Rendered as a visual criteria builder scoped to the selected object's
       // fields (dependsOn: object_name), storing the same JSON FilterCondition.
       // An "Edit as JSON" fallback keeps hand-authored / advanced filters
       // editable. Falls back to a textarea when the widget is unavailable.
       widget: 'filter-condition',
       dependsOn: ['object_name'],
-      description: 'JSON FilterCondition matched against records of object_name. Empty = match all.',
+      description: 'Which records to share. Leave empty to share every record of the object.',
       group: 'Target',
     }),
 
@@ -150,7 +156,9 @@ export const SysSharingRule = ObjectSchema.create({
         label: 'Recipient Type',
         required: true,
         defaultValue: 'business_unit',
-        description: 'Kind of principal that receives access — expanded to user grants at evaluation time. `business_unit` walks the parent_business_unit_id tree; `team` is flat (better-auth); `position` expands the position\'s holders (positions are flat, ADR-0090 D3); `unit_and_subordinates` expands the named business unit PLUS every descendant unit\'s members via the sys_business_unit tree (ADR-0057 D5).',
+        // The engine detail this used to spell out (which tree is walked, which
+        // expansion is flat, the ADRs behind each) lives in the class doc above.
+        description: 'Who receives access. Picking a team, business unit or position gives access to everyone in it. "Business unit and subordinates" also covers every unit below the one you pick.',
         group: 'Recipient',
       },
     ),
@@ -166,7 +174,7 @@ export const SysSharingRule = ObjectSchema.create({
       // back to a text input when the widget is unavailable.
       widget: 'recipient-picker',
       dependsOn: ['recipient_type'],
-      description: 'business-unit id / team id / position name / user id depending on recipient_type',
+      description: 'The specific user, team, business unit or position that receives access.',
       group: 'Recipient',
     }),
 
@@ -184,7 +192,7 @@ export const SysSharingRule = ObjectSchema.create({
       label: 'Active',
       required: false,
       defaultValue: true,
-      description: 'Only active rules participate in lifecycle evaluation',
+      description: 'Turn off to withdraw the access this rule granted, without deleting the rule.',
       group: 'Lifecycle',
     }),
 
@@ -203,8 +211,7 @@ export const SysSharingRule = ObjectSchema.create({
       readonly: true,
       defaultValue: 'admin',
       description:
-        'Record provenance (unified tri-state, A4 #2920): platform = framework built-in / ' +
-        'package = app/package-declared (boot-seeded) / admin = tenant-created in Setup.',
+        'Where this rule came from: built into the platform, installed with an app, or created here in Setup.',
       options: [
         { value: 'platform', label: 'Platform' },
         { value: 'package', label: 'Package' },
@@ -219,8 +226,7 @@ export const SysSharingRule = ObjectSchema.create({
       readonly: true,
       defaultValue: false,
       description:
-        'Set when an admin edits a package-declared rule; boot seeding will no longer ' +
-        'overwrite the row (deactivations survive redeploys). Meaningless on admin rows.',
+        'Set once you edit a rule that came with an app, so your changes are kept when the app is updated.',
       group: 'System',
     }),
 
diff --git a/packages/plugins/plugin-sharing/src/translations/en.objects.generated.ts b/packages/plugins/plugin-sharing/src/translations/en.objects.generated.ts
@@ -102,7 +102,7 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
   sys_sharing_rule: {
     label: "Sharing Rule",
     pluralLabel: "Sharing Rules",
-    description: "Declarative sharing rule that auto-materialises sys_record_share grants. Authored via defineSharingRule() in code or the Studio criteria builder.",
+    description: "Grants a group of people access to the records that match a condition.",
     fields: {
       id: {
         label: "Rule ID"
@@ -113,7 +113,7 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       },
       name: {
         label: "Name",
-        help: "Unique snake_case rule name"
+        help: "Identifies the rule. Lowercase letters, digits and underscores only."
       },
       label: {
         label: "Display Label"
@@ -123,15 +123,15 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       },
       object_name: {
         label: "Object",
-        help: "Short object name (e.g. opportunity, account)"
+        help: "The object whose records this rule shares."
       },
       criteria_json: {
-        label: "Criteria (FilterCondition JSON)",
-        help: "JSON FilterCondition matched against records of object_name. Empty = match all."
+        label: "Criteria",
+        help: "Which records to share. Leave empty to share every record of the object."
       },
       recipient_type: {
         label: "Recipient Type",
-        help: "Kind of principal that receives access — expanded to user grants at evaluation time. `business_unit` walks the parent_business_unit_id tree; `team` is flat (better-auth); `position` expands the position's holders (positions are flat, ADR-0090 D3); `unit_and_subordinates` expands the named business unit PLUS every descendant unit's members via the sys_business_unit tree (ADR-0057 D5).",
+        help: "Who receives access. Picking a team, business unit or position gives access to everyone in it. \"Business unit and subordinates\" also covers every unit below the one you pick.",
         options: {
           user: "user",
           team: "team",
@@ -142,7 +142,7 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       },
       recipient_id: {
         label: "Recipient",
-        help: "business unit id / team id / position name / user id depending on recipient_type"
+        help: "The specific user, team, business unit or position that receives access."
       },
       access_level: {
         label: "Access Level",
@@ -154,11 +154,11 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       },
       active: {
         label: "Active",
-        help: "Only active rules participate in lifecycle evaluation"
+        help: "Turn off to withdraw the access this rule granted, without deleting the rule."
       },
       managed_by: {
         label: "Managed By",
-        help: "Record provenance (unified tri-state, A4 #2920): platform = framework built-in / package = app/package-declared (boot-seeded) / admin = tenant-created in Setup.",
+        help: "Where this rule came from: built into the platform, installed with an app, or created here in Setup.",
         options: {
           platform: "Platform",
           package: "Package",
@@ -167,7 +167,7 @@ export const enObjects: NonNullable<TranslationData['objects']> = {
       },
       customized: {
         label: "Customized",
-        help: "Set when an admin edits a package-declared rule; boot seeding will no longer overwrite the row (deactivations survive redeploys). Meaningless on admin rows."
+        help: "Set once you edit a rule that came with an app, so your changes are kept when the app is updated."
       },
       created_at: {
         label: "Created At"
diff --git a/packages/plugins/plugin-sharing/src/translations/es-ES.objects.generated.ts b/packages/plugins/plugin-sharing/src/translations/es-ES.objects.generated.ts
@@ -102,7 +102,7 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
   sys_sharing_rule: {
     label: "Regla de compartición",
     pluralLabel: "Reglas de compartición",
-    description: "Regla de compartición declarativa que materializa automáticamente concesiones de sys_record_share. Se define mediante defineSharingRule() en código o con el generador de criterios de Studio.",
+    description: "Da acceso a un grupo de personas a los registros que cumplen una condición.",
     fields: {
       id: {
         label: "ID de regla"
@@ -113,7 +113,7 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
       },
       name: {
         label: "Nombre",
-        help: "Nombre de regla snake_case único."
+        help: "Identifica la regla. Solo minúsculas, dígitos y guiones bajos."
       },
       label: {
         label: "Nombre visible"
@@ -123,15 +123,15 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
       },
       object_name: {
         label: "Objeto",
-        help: "Nombre corto del objeto (p. ej. opportunity, account)."
+        help: "El objeto cuyos registros comparte esta regla."
       },
       criteria_json: {
-        label: "Criterios (JSON de FilterCondition)",
-        help: "FilterCondition JSON comparado con los registros de object_name. Vacío = coincide con todos."
+        label: "Criterios",
+        help: "Qué registros se comparten. Déjalo vacío para compartir todos los registros del objeto."
       },
       recipient_type: {
         label: "Tipo de destinatario",
-        help: "Tipo de principal que recibe acceso; se expande a concesiones de usuario durante la evaluación. `business_unit` recorre el árbol parent_business_unit_id; `team` es plano (better-auth); `position` se expande a quienes ocupan el puesto (los puestos son planos, ADR-0090 D3); `unit_and_subordinates` expande la unidad de negocio indicada MÁS los miembros de todas sus unidades descendientes a través del árbol sys_business_unit (ADR-0057 D5).",
+        help: "Quién recibe el acceso. Al elegir un equipo, una unidad de negocio o un puesto, lo reciben todas las personas que lo integran. «Unidad de negocio y subordinadas» abarca además todas las unidades por debajo de la elegida.",
         options: {
           user: "Usuario",
           team: "Equipo",
@@ -142,7 +142,7 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
       },
       recipient_id: {
         label: "Destinatario",
-        help: "ID de unidad de negocio / ID de equipo / nombre del puesto / ID del usuario según recipient_type."
+        help: "El usuario, equipo, unidad de negocio o puesto concreto que recibe el acceso."
       },
       access_level: {
         label: "Nivel de acceso",
@@ -154,11 +154,11 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
       },
       active: {
         label: "Activo",
-        help: "Solo las reglas activas participan en la evaluación del ciclo de vida."
+        help: "Desactívala para retirar el acceso que concedió, sin eliminar la regla."
       },
       managed_by: {
         label: "Gestionado por",
-        help: "Procedencia del registro (tri-estado unificado, A4 #2920): platform = integrado en el framework / package = declarado por app o paquete (sembrado al arrancar) / admin = creado por el inquilino en Setup.",
+        help: "De dónde viene esta regla: integrada en la plataforma, instalada con una app o creada aquí.",
         options: {
           platform: "Plataforma",
           package: "Paquete",
@@ -167,7 +167,7 @@ export const esESObjects: NonNullable<TranslationData['objects']> = {
       },
       customized: {
         label: "Personalizado",
-        help: "Se establece cuando un administrador edita una regla declarada por un paquete; a partir de entonces el sembrado de arranque deja de sobrescribir la fila (las desactivaciones sobreviven a los redespliegues). Sin sentido en filas admin."
+        help: "Se marca al editar una regla que vino con una app, para conservar tus cambios cuando la app se actualice."
       },
       created_at: {
         label: "Creado el"
diff --git a/packages/plugins/plugin-sharing/src/translations/ja-JP.objects.generated.ts b/packages/plugins/plugin-sharing/src/translations/ja-JP.objects.generated.ts
@@ -102,7 +102,7 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
   sys_sharing_rule: {
     label: "共有ルール",
     pluralLabel: "共有ルール",
-    description: "sys_record_share 付与を自動マテリアライズする宣言的共有ルール。コードの defineSharingRule() または Studio の条件ビルダーで作成します。",
+    description: "条件に一致するレコードへのアクセスを、指定した人たちに与えます。",
     fields: {
       id: {
         label: "ルール ID"
@@ -113,7 +113,7 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
       },
       name: {
         label: "名前",
-        help: "一意の snake_case ルール名"
+        help: "ルールの識別名。半角小文字・数字・アンダースコアのみ使用できます。"
       },
       label: {
         label: "表示名"
@@ -123,15 +123,15 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
       },
       object_name: {
         label: "オブジェクト",
-        help: "短いオブジェクト名（例: opportunity、account）"
+        help: "どのオブジェクトのレコードを共有するか。"
       },
       criteria_json: {
-        label: "条件（FilterCondition JSON）",
-        help: "object_name のレコードに対してマッチする JSON FilterCondition。空 = すべてにマッチ。"
+        label: "条件",
+        help: "どのレコードを共有するか。空欄にすると、そのオブジェクトのすべてのレコードを共有します。"
       },
       recipient_type: {
         label: "受信者タイプ",
-        help: "アクセスを受け取るプリンシパルの種別 — 評価時にユーザー付与に展開されます。`business_unit` は parent_business_unit_id ツリーをたどります。`team` はフラット（better-auth）。`position` はそのポジションの在任者に展開されます（ポジションはフラット、ADR-0090 D3）。`unit_and_subordinates` は指定したビジネスユニットに加え、sys_business_unit ツリー上の全下位ユニットのメンバーにも展開されます（ADR-0057 D5）。",
+        help: "誰にアクセスを与えるか。チーム・事業単位・役職を選ぶと、そこに属する全員がアクセスできます。「事業単位と下位組織」を選ぶと、その配下のすべての単位も対象になります。",
         options: {
           user: "ユーザー",
           team: "チーム",
@@ -142,7 +142,7 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
       },
       recipient_id: {
         label: "受信者",
-        help: "recipient_type に応じたビジネスユニット ID / チーム ID / ポジション名 / ユーザー ID"
+        help: "アクセスを与える具体的なユーザー・チーム・事業単位・役職。"
       },
       access_level: {
         label: "アクセスレベル",
@@ -154,11 +154,11 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
       },
       active: {
         label: "有効",
-        help: "有効なルールのみがライフサイクル評価に参加します"
+        help: "オフにすると、このルールが与えたアクセスをただちに取り消します（ルール自体は残ります）。"
       },
       managed_by: {
         label: "管理元",
-        help: "レコードの出所（統一三状態、A4 #2920）: platform = フレームワーク組み込み / package = アプリ・パッケージ宣言（起動時シード）/ admin = テナントが Setup で作成。",
+        help: "このルールの出所：プラットフォーム内蔵、アプリと一緒に導入、またはここで作成。",
         options: {
           platform: "プラットフォーム",
           package: "パッケージ",
@@ -167,7 +167,7 @@ export const jaJPObjects: NonNullable<TranslationData['objects']> = {
       },
       customized: {
         label: "カスタマイズ済み",
-        help: "管理者がパッケージ宣言のルールを編集すると設定されます。以後、起動時シードはこの行を上書きしません（無効化は再デプロイ後も保持）。admin 行では意味を持ちません。"
+        help: "アプリ付属のルールを編集すると設定され、アプリ更新時も変更内容が保持されます。"
       },
       created_at: {
         label: "作成日時"
diff --git a/packages/plugins/plugin-sharing/src/translations/zh-CN.objects.generated.ts b/packages/plugins/plugin-sharing/src/translations/zh-CN.objects.generated.ts
