@kimposoft/plugin-sdk 0.0.0-stage → 1.1.0-tp.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +9 -0
  3. package/README.md +48 -2
  4. package/package.json +145 -4
  5. package/src/action-designer.ts +267 -0
  6. package/src/attachment-open.ts +574 -0
  7. package/src/attachment-url.ts +235 -0
  8. package/src/auth/index.ts +6 -0
  9. package/src/auth/qrcode.ts +519 -0
  10. package/src/auth/types.ts +261 -0
  11. package/src/display-style.ts +532 -0
  12. package/src/editor-frame.ts +625 -0
  13. package/src/editor-session.ts +1214 -0
  14. package/src/editor-testing.ts +838 -0
  15. package/src/editor.ts +1720 -0
  16. package/src/frame-transport.ts +516 -0
  17. package/src/frontend-routes.ts +99 -0
  18. package/src/hooks.ts +48 -0
  19. package/src/host-caps.ts +93 -0
  20. package/src/i18n.ts +238 -0
  21. package/src/im-panel.ts +132 -0
  22. package/src/image-tools.ts +91 -0
  23. package/src/index.ts +125 -0
  24. package/src/interactive-session.ts +94 -0
  25. package/src/nahida-im.ts +391 -0
  26. package/src/nahida-ws.ts +23 -0
  27. package/src/org-directory.ts +78 -0
  28. package/src/oz-realtime.ts +144 -0
  29. package/src/page.ts +591 -0
  30. package/src/print.ts +393 -0
  31. package/src/surface.ts +310 -0
  32. package/src/theme-mocks.ts +140 -0
  33. package/src/theme.ts +125 -0
  34. package/src/ui-fixtures/attachment.ts +24 -0
  35. package/src/ui-fixtures/confirm.ts +16 -0
  36. package/src/ui-fixtures/entity-picker.ts +24 -0
  37. package/src/ui-fixtures/expression-editor.ts +52 -0
  38. package/src/ui-fixtures/image-cropper.ts +23 -0
  39. package/src/ui-fixtures/index.ts +17 -0
  40. package/src/ui-fixtures/org-tri-picker.ts +19 -0
  41. package/src/ui-fixtures/prompt.ts +19 -0
  42. package/src/ui-fixtures/record-picker.ts +17 -0
  43. package/src/ui-fixtures/template-picker.ts +13 -0
  44. package/src/ui-mocks.ts +264 -0
  45. package/src/ui.ts +491 -0
  46. package/src/workflow-designer.ts +475 -0
package/src/page.ts ADDED
@@ -0,0 +1,591 @@
1
+ // page-slot 类插件契约——把宿主内置"模板历史记录列表页"(历史记录页)
2
+ // 容器化为可被插件替换的挂载点后,插件前端消费的 props / hostBridge 能力面类型定义于此。
3
+ //
4
+ // 安全权威说明(务必遵守):真正的鉴权/校验闸门始终在宿主后端(权限框架的后端闸门)。
5
+ // 本文件定义的各 Client(PageRecordListClient / PageNavigationClient / PagePermissionClient)
6
+ // 都只是对宿主 REST 接口的薄封装,本身不构成安全边界——插件不能假设这些 client 已经做了
7
+ // 权限裁决,任何写操作最终仍由宿主后端二次校验并可能拒绝。
8
+ //
9
+ // 字段结构对照宿主前端的
10
+ // Template / TemplateDataTable / TemplateField / RuntimeRecordListPayload /
11
+ // RuntimeRecordListResult / RuntimeRecord 等类型原样照抄(加 Page 前缀避免与宿主类型混淆)。
12
+ // SDK 包不能 import 宿主代码,因此这里必须自含定义,不能复用宿主类型。
13
+
14
+ /** 页面级插件 props(宿主经 SurfaceCreateInput.props 注入)。 */
15
+ export interface TemplateRecordsPageProps {
16
+ /** 所属应用 ID。 */
17
+ appId: string;
18
+ /** 当前模板 ID。 */
19
+ templateId: string;
20
+ }
21
+
22
+ /** 宿主请求视图刷新的起因。 */
23
+ export type TemplateRecordsRefreshReason =
24
+ /** 页签被重新激活(宿主 KeepAlive 缓存命中)。视图应按自己的 TTL 决定刷不刷。 */
25
+ | 'activated'
26
+ /** 本模板的记录数据确已变更(填报态保存等)。视图应立即刷新,不受 TTL 约束。 */
27
+ | 'dirty';
28
+
29
+ export interface TemplateRecordsRefreshOptions {
30
+ /** 起因。缺省按 'activated' 处理(保守档:受 TTL 约束)。 */
31
+ reason?: TemplateRecordsRefreshReason;
32
+ /** true 表示模板结构(字段/设置)可能已变,视图应连列定义一起重建,而非只重拉数据。 */
33
+ structural?: boolean;
34
+ }
35
+
36
+ /**
37
+ * 页面级插件对宿主暴露的方法(宿主经 `ref` 调用,沿用 workflow-designer 的 expose 范式)。
38
+ *
39
+ * refresh 的语义刻意是「激活了,你自己看着办」而不是「你去刷」——**刷新策略归视图,不归宿主**
40
+ * 宿主只负责发信号(页签激活 / 数据已变更),由视图自己决定:
41
+ * - reason='dirty' → 立即刷新,不看 TTL(数据确实变了);
42
+ * - reason='activated'→ 距上次成功刷新超过视图自己的 TTL 才刷,否则直接忽略。
43
+ * 这样宿主零策略,TTL、请求节流、数据指纹比对全部收在实现方手里,内置视图与插件视图
44
+ * 各自持有同一套判据而互不依赖。
45
+ *
46
+ * 全部方法都是可选的:宿主一律以 `surfaceRef.value?.refresh?.(...)` 方式调用,
47
+ * 未实现的旧版本插件静默降级(不刷新,但不报错)。
48
+ */
49
+ export interface TemplateRecordsSurfaceExpose {
50
+ refresh?: (options?: TemplateRecordsRefreshOptions) => void | Promise<void>;
51
+ }
52
+
53
+ /** 模板基础信息(对照宿主 Template 类型,仅摘取列表页需要的字段)。 */
54
+ export interface PageTemplateInfo {
55
+ template_id: string;
56
+ template_code: string;
57
+ template_name: string;
58
+ template_description: string;
59
+ designer_type: string;
60
+ active_version_no: string;
61
+ latest_version_no: string;
62
+ status_code: string;
63
+ /** false 表示模板已停用;历史页必须保留 view,但隐藏/禁用全部写入口。 */
64
+ is_enabled?: boolean;
65
+ version_no: number;
66
+ }
67
+
68
+ /** 模板下数据表信息(对照宿主 TemplateDataTable 类型)。 */
69
+ export interface PageDataTableInfo {
70
+ data_table_id: string;
71
+ table_code: string;
72
+ table_name: string;
73
+ physical_table_name: string;
74
+ /** 后端权威角色:'main'=主表,其余(如 'extension')=明细/扩展表;勿靠 sort_no 猜。 */
75
+ table_role?: string;
76
+ extension_mode?: string;
77
+ /** 扩展表设为「历史记录中隐藏」时为 true;缺省 / false = 显示,主表恒不下发。 */
78
+ history_hidden?: boolean;
79
+ sort_no: number;
80
+ field_count: number;
81
+ version_no: number;
82
+ }
83
+
84
+ /** 字段定义(对照宿主 TemplateField 类型)。 */
85
+ export interface PageFieldInfo {
86
+ field_id: string;
87
+ field_code: string;
88
+ field_name: string;
89
+ data_type: string;
90
+ control_type?: string;
91
+ display_style: string;
92
+ sort_no: number;
93
+ /**
94
+ * 以下四项宿主当前不下发:缺省时按“可搜索 / 可筛选 / 可排序 /
95
+ * 列表可见”处理,插件不要依赖它们做必选判定(否则按 is_list_visible 选列会一列都不显示)。
96
+ */
97
+ is_searchable?: boolean;
98
+ is_filterable?: boolean;
99
+ is_sortable?: boolean;
100
+ is_list_visible?: boolean;
101
+ format_rule_json?: Record<string, unknown> | string | null;
102
+ option_source_json?: Record<string, unknown> | string | null;
103
+ /** 字段是否唯一(宿主下发;老宿主缺席按 false)。导入「判定字段」默认取主表的唯一字段。 */
104
+ is_unique?: boolean;
105
+ /** 字段是否必填(宿主下发;老宿主缺席按 false)。 */
106
+ is_required?: boolean;
107
+ }
108
+
109
+ /** 记录列表排序项(对照宿主 RuntimeRecordSort 类型)。 */
110
+ export interface PageRecordSort {
111
+ field_id?: string;
112
+ field_code?: string;
113
+ system_column?: string;
114
+ desc?: boolean;
115
+ }
116
+
117
+ /**
118
+ * 单据锁定状态只读投影。
119
+ * source 区分手动锁定(右键菜单)与自动锁定(模板属性里的判断表达式);locked_by/locked_by_name/
120
+ * locked_at 只在 locked=true 时有意义。locked_at 是后端下发的 UTC RFC3339 字符串,展示前必须按
121
+ * 当前用户时区本地化换算(不得墙钟字面展示,与业务日期字段的 formatFieldDateTime 区分对待)。
122
+ */
123
+ export interface PageRecordLockState {
124
+ locked: boolean;
125
+ source?: 'manual' | 'auto';
126
+ locked_by?: number;
127
+ locked_by_name?: string;
128
+ locked_at?: string;
129
+ }
130
+
131
+ /** 锁定状态筛选值:'locked'/'unlocked' 二选一,缺省不筛选。 */
132
+ export type PageRecordLockStatusFilter = 'locked' | 'unlocked';
133
+
134
+ /**
135
+ * 记录列表条件项。
136
+ * field_id / field_code 与 system_column 二选一,同时出现或都缺 → 宿主 RUNTIME_FILTER_INVALID。
137
+ * system_column 为 created_by/updated_by 时 op 仅 '=' / 'IS_EMPTY',value 为用户 id;
138
+ * 为 created_at/updated_at 时 op 取 '>=' / '<' / '=' / 'IS_EMPTY',value 为 RFC3339 带偏移的时刻串(后端换 UTC 比较)。
139
+ * 条件指向当前用户隐藏字段 → 400 RUNTIME_FIELD_HIDDEN。
140
+ */
141
+ export interface PageRecordFilter {
142
+ field_id?: string;
143
+ field_code?: string;
144
+ system_column?: 'created_by' | 'updated_by' | 'created_at' | 'updated_at';
145
+ /** '=', '!=', '>', '>=', '<', '<=', 'CONTAINS', 'STARTS_WITH', 'ENDS_WITH', 'IS_EMPTY', 'IS_NOT_EMPTY' */
146
+ op: string;
147
+ value?: unknown;
148
+ }
149
+
150
+ /** 流程状态筛选值:not_started/running/ended 子集,空数组/缺省 = 不筛选。 */
151
+ export type PageWorkflowStatusFilter = Array<'not_started' | 'running' | 'ended'>;
152
+
153
+ /**
154
+ * 「我的关系」筛选值:'pending_mine'=当前待办人含操作人;'initiated_by_me'=记录创建人
155
+ * 是操作人(口径退化);空串/缺省=不筛选。与流程状态筛选同一生效条件(仅模板主表且已绑定流程)。
156
+ */
157
+ export type PageWorkflowMyRelationFilter = '' | 'pending_mine' | 'initiated_by_me';
158
+
159
+ /** 记录列表查询入参(对照宿主 RuntimeRecordListPayload 类型)。 */
160
+ export interface PageRecordListPayload {
161
+ template_version_no?: string;
162
+ /** true=查回收站(已软删除)记录。 */
163
+ deleted?: boolean;
164
+ keyword?: string;
165
+ /** 条件列表;老宿主忽略。 */
166
+ filters?: PageRecordFilter[];
167
+ sorts?: PageRecordSort[];
168
+ /** 流程状态筛选子集;仅模板主表且已绑定流程时后端生效,其余场景忽略。 */
169
+ workflow_status?: PageWorkflowStatusFilter;
170
+ /** 「我的关系」筛选;同 workflow_status 生效条件,空串/缺省=不筛选。 */
171
+ workflow_my_relation?: PageWorkflowMyRelationFilter;
172
+ /** 锁定状态筛选;缺省不过滤。 */
173
+ lock_status?: PageRecordLockStatusFilter;
174
+ limit: number;
175
+ offset: number;
176
+ }
177
+
178
+ export type PageRecordExportPayload = Omit<PageRecordListPayload, 'limit' | 'offset'> & {
179
+ /** 只导这些主记录(与筛选、数据范围求交);缺省按筛选导出全部。老宿主忽略。 */
180
+ record_ids?: string[];
181
+ /**
182
+ * 工作簿版式:主表首列「记录编号」、extension_table_ids 中的扩展表各占一张工作表、另带隐藏表记录列身份,
183
+ * 导出文件可改后经 startImport 直接导回。缺省为单表版式。老宿主忽略(仍出单表)。
184
+ */
185
+ workbook?: boolean;
186
+ /** 工作簿版式下一并导出的扩展表。 */
187
+ extension_table_ids?: string[];
188
+ };
189
+
190
+ /** 导出数据转后台任务的主表单据数阈值:超过即应改走 createDataExportTask。 */
191
+ export const PAGE_RECORD_DATA_EXPORT_ASYNC_THRESHOLD = 1000;
192
+
193
+ /** 导入选项:重复数据三档(不检查 / 跳过 / 覆盖已有单据)+ 判定字段 + 出错处理。 */
194
+ export interface PageRecordImportOptions {
195
+ duplicate_mode: 'none' | 'skip' | 'overwrite';
196
+ /** 判定字段:主表字段 ID,或 'record_id'(记录编号);duplicate_mode 为 skip/overwrite 时必填。 */
197
+ key_field_ids?: string[];
198
+ /** rollback_all 整批回滚 / skip_failed 跳过出错单据。 */
199
+ error_mode: 'rollback_all' | 'skip_failed';
200
+ }
201
+
202
+ /** 导入问题(预检或写入时发现);message 已按用户语言翻译。 */
203
+ export interface PageRecordImportIssue {
204
+ sheet: string;
205
+ row: number;
206
+ ref?: string;
207
+ column?: string;
208
+ code: string;
209
+ message: string;
210
+ }
211
+
212
+ /** 导入作业(getImportJob 轮询返回)。status:prechecking → ready → executing → done;failed 为整作业失败。 */
213
+ export interface PageRecordImportJob {
214
+ job_id: string;
215
+ status: 'prechecking' | 'ready' | 'executing' | 'done' | 'failed';
216
+ /** 当前阶段:read 读取文件 / validate 校验 / write 写入单据 / index 更新索引。 */
217
+ stage: 'read' | 'validate' | 'write' | 'index';
218
+ /** 当前阶段已处理 / 总数(按主表单据计),用于真实进度条。 */
219
+ processed: number;
220
+ total: number;
221
+ options: PageRecordImportOptions;
222
+ summary: {
223
+ main_records: number;
224
+ to_create: number;
225
+ to_overwrite: number;
226
+ duplicates_skipped: number;
227
+ error_records: number;
228
+ issue_count: number;
229
+ extension_rows: Array<{ data_table_id: string; table_name: string; rows: number }> | null;
230
+ created: number;
231
+ overwritten: number;
232
+ failed: number;
233
+ extension_written: number;
234
+ rolled_back: boolean;
235
+ };
236
+ /** 前 500 条问题(全部问题在错误报告里)。 */
237
+ issues: PageRecordImportIssue[] | null;
238
+ ignored_columns: Array<{ sheet: string; column: string; code: string; message: string }> | null;
239
+ error_message?: string;
240
+ file_name?: string;
241
+ created_at: string;
242
+ started_at?: string;
243
+ finished_at?: string;
244
+ }
245
+
246
+ /** 单条运行态记录(对照宿主 RuntimeRecord 类型)。 */
247
+ export interface PageRuntimeRecord {
248
+ record_id: string;
249
+ created_at?: string;
250
+ created_by?: string | number | null;
251
+ created_by_name?: string | null;
252
+ updated_at?: string;
253
+ updated_by?: string | number | null;
254
+ updated_by_name?: string | null;
255
+ version_no: number;
256
+ values: Record<string, unknown>;
257
+ /**
258
+ * 锁定状态:从未锁定过的记录该字段缺席,视为未锁定——不得把「缺席」误当作
259
+ * 「已知未锁定」以外的任何含义(例如误判为加载失败)。
260
+ */
261
+ lock?: PageRecordLockState;
262
+ /**
263
+ * 保存后动作链最近一次运行的未完成 / 异常状态:只有该记录最新一次运行不是成功时
264
+ * 才下发;从未运行、最新一次已成功、回收站 / 非主表列表、老宿主均缺席——缺席即「无需提示」。
265
+ */
266
+ action_run?: PageRecordActionRun;
267
+ }
268
+
269
+ /**
270
+ * 保存后动作链运行状态码(对照宿主 action_chain_run.status_code;succeeded 不下发)。
271
+ * foreground=前台执行中;background=后台执行中;failed/canceled/timed_out/rolled_back 为终态异常。
272
+ * 宿主后续可能新增状态码,插件对未知值应按中性样式展示原文,不得报错。
273
+ */
274
+ export type PageRecordActionRunStatus =
275
+ | 'foreground'
276
+ | 'background'
277
+ | 'failed'
278
+ | 'canceled'
279
+ | 'timed_out'
280
+ | 'rolled_back'
281
+ | (string & {});
282
+
283
+ /** 记录列表上的保存后动作链运行状态(对照宿主 RuntimeRecordActionRun)。 */
284
+ export interface PageRecordActionRun {
285
+ status: PageRecordActionRunStatus;
286
+ /** 触发该动作链的事件键(如保存后事件)。 */
287
+ event_key: string;
288
+ error_code?: string;
289
+ /** 失败原因原文,供悬浮提示展示。 */
290
+ error_message?: string;
291
+ failed_node_id?: string;
292
+ /** 开始时间,RFC3339 UTC;展示时按宿主时间格式化换算到用户时区。 */
293
+ started_at: string;
294
+ /** 结束时间,RFC3339 UTC;仍在执行中时缺席。 */
295
+ finished_at?: string;
296
+ /**
297
+ * 动作链事务模式:global=整链一个事务(失败已整体回滚,重试天然可重复);
298
+ * individual=逐节点各自提交(失败前的节点已落库,重试会从头再执行所有动作)。
299
+ * 老宿主不下发该字段,缺席时插件应按 individual 处理(宁可多问一次确认)。
300
+ */
301
+ transaction_mode?: 'global' | 'individual';
302
+ /**
303
+ * 本次运行是由哪次运行重试而来:被重试的那次运行的 mutation_id;
304
+ * 首次运行或老宿主缺席。仅用于展示溯源,不可作为重试入参。
305
+ */
306
+ retry_of_mutation_id?: string;
307
+ }
308
+
309
+ /** 记录列表查询结果(对照宿主 RuntimeRecordListResult 类型)。 */
310
+ export interface PageRecordListResult {
311
+ items: PageRuntimeRecord[];
312
+ total: number;
313
+ limit: number;
314
+ offset: number;
315
+ /**
316
+ * 查询上下文读票据:assetId → 票据,宿主对本页结果里出现的
317
+ * 图片 / 附件条目签发(短期、只读、绑定当前用户)。插件把它原样交给 SDK `attachmentItemUrls` 的
318
+ * `tickets` 选项取地址,不自行拼接宿主路径;老宿主不下发时缺席,地址不带票据。
319
+ */
320
+ asset_tickets?: Record<string, string>;
321
+ }
322
+
323
+ // ── 分组计数 ───────────────────────────────────────────────────────────────
324
+
325
+ /** 分组方式:按值 / 按年 / 按月 / 按日(日期类)/ 按数值区间。mode 须与字段类型匹配,否则 RUNTIME_GROUP_MODE_INVALID。 */
326
+ export type PageRecordGroupMode = 'value' | 'year' | 'month' | 'day' | 'range';
327
+
328
+ /** 单个分组维度;field_id 与 system_column 二选一。range 模式须给 range_width(>0)。 */
329
+ export interface PageRecordGroupBy {
330
+ field_id?: string;
331
+ system_column?: 'created_by' | 'updated_by' | 'created_at' | 'updated_at';
332
+ mode: PageRecordGroupMode;
333
+ /** 仅 mode='range':区间宽度,必须 > 0。 */
334
+ range_width?: number;
335
+ }
336
+
337
+ /** 分组计数请求:列表请求去掉分页与排序,另加分组维度;label_contains 仅单分组项时生效。 */
338
+ export interface PageRecordGroupCountPayload extends Omit<PageRecordListPayload, 'limit' | 'offset' | 'sorts'> {
339
+ group_by: PageRecordGroupBy[];
340
+ label_contains?: string;
341
+ }
342
+
343
+ /**
344
+ * 分组键。empty=true 为空值组(其余字段为空);按值时 value 为原始值(成员/部门/填报人/更新人为标识,
345
+ * 另给 label 显示名);year/month/day 时 value 为桶起点,range_start/range_end 为可直接作列表条件的边界
346
+ * (墙钟字段为 'YYYY-MM-DD HH:mm:ss',按 UTC 存的列为 RFC3339 带偏移);range 时为数值,含起不含止。
347
+ */
348
+ export interface PageRecordGroupKey {
349
+ empty: boolean;
350
+ value?: string | number | null;
351
+ range_start?: string | number | null;
352
+ range_end?: string | number | null;
353
+ label?: string;
354
+ }
355
+
356
+ /** 一个分组:每个分组维度一个 key,加命中记录数。 */
357
+ export interface PageRecordGroup {
358
+ keys: PageRecordGroupKey[];
359
+ count: number;
360
+ }
361
+
362
+ /** 分组计数结果;最多 200 组,超出时 truncated=true 并给剩余组数与记录数。 */
363
+ export interface PageRecordGroupCountResult {
364
+ groups: PageRecordGroup[];
365
+ truncated: boolean;
366
+ rest_group_count: number;
367
+ rest_record_count: number;
368
+ }
369
+
370
+ // ── 插件模板级配置 ─────────────────────────────────────────────────────────
371
+
372
+ /** 插件模板级配置快照(hostBridge['plugin-config'].get 返回);从未保存时 config=null、version=0。 */
373
+ export interface PagePluginConfigSnapshot {
374
+ config: unknown | null;
375
+ /** 乐观并发版本号,保存时原样回传。 */
376
+ version: number;
377
+ /** 当前用户是否可编辑(=应用设计权限);仅用于 UI 置灰,不是安全边界。 */
378
+ can_edit: boolean;
379
+ updated_by_name: string;
380
+ /** RFC3339 UTC 字符串;从未保存为 null。 */
381
+ updated_at: string | null;
382
+ /**
383
+ * 当前用户能否保存个人配置(没有应用设计权限的用户为 true)。老宿主不带此项,按 false 处理。
384
+ * 仅用于 UI,不是安全边界(后端另判)。
385
+ */
386
+ can_personalize?: boolean;
387
+ /** 当前用户的个人配置;没有、不能个人化或老宿主时为 null / 缺省。上面的 config 是管理员默认。 */
388
+ personal?: PagePluginPersonalConfig | null;
389
+ }
390
+
391
+ /**
392
+ * 当前用户在本模板下的个人配置(宿主不解读;如何覆盖管理员默认由插件决定)。
393
+ * version 是个人配置自己的乐观并发版本号,与默认配置的 version 无关。
394
+ */
395
+ export interface PagePluginPersonalConfig {
396
+ config: unknown;
397
+ version: number;
398
+ /** RFC3339 UTC 字符串。 */
399
+ updated_at: string | null;
400
+ }
401
+
402
+ /** 个人配置保存结果。 */
403
+ export interface PagePluginPersonalSaveResult {
404
+ version: number;
405
+ updated_at: string | null;
406
+ }
407
+
408
+ /** 保存结果:新版本号与最近更新人信息。 */
409
+ export interface PagePluginConfigSaveResult {
410
+ version: number;
411
+ updated_by_name: string;
412
+ updated_at: string | null;
413
+ }
414
+
415
+ /** 宿主桥抛出的错误带 code(如 'PLUGIN_CONFIG_VERSION_CONFLICT' / 'PLUGIN_CONFIG_TOO_LARGE' / 'PLUGIN_CONFIG_INVALID')。 */
416
+ export interface PageHostError extends Error {
417
+ code?: string;
418
+ }
419
+
420
+ /**
421
+ * 插件模板级配置客户端(hostBridge['plugin-config'])。
422
+ * 配置按「当前模板 + 当前挂载插件」存取,插件标识由宿主桥填入,插件不传。
423
+ * 配置体上限 64 KB;保存时 version 传读到的版本(首次保存传 0),冲突抛 PLUGIN_CONFIG_VERSION_CONFLICT。
424
+ *
425
+ * 两层配置:save 写管理员默认(需应用设计权限,每模板一份);没有应用设计权限的用户可用
426
+ * savePersonal / deletePersonal 维护自己的个人配置(每人每模板一份)。个人配置方法在老宿主上缺省,
427
+ * 调用前先判断是否存在。有应用设计权限的人调用 savePersonal 抛 PLUGIN_CONFIG_PERSONAL_NOT_ALLOWED。
428
+ */
429
+ export interface PagePluginConfigClient {
430
+ get(): Promise<PagePluginConfigSnapshot>;
431
+ save(config: unknown, version: number): Promise<PagePluginConfigSaveResult>;
432
+ /** 保存当前用户的个人配置;version 传读到的 personal.version(没有个人配置传 0)。 */
433
+ savePersonal?(config: unknown, version: number): Promise<PagePluginPersonalSaveResult>;
434
+ /** 删除当前用户的个人配置(恢复默认);幂等。 */
435
+ deletePersonal?(): Promise<void>;
436
+ }
437
+
438
+ /**
439
+ * 记录列表数据客户端(hostBridge['record-list'])。
440
+ * 薄封装宿主 REST 接口(fetchTemplate/fetchTemplateTables/fetchTemplateFields/
441
+ * fetchRuntimeRecords/fetchBatch*RuntimeRecords 等),插件只管调用,不感知具体 URL。
442
+ * 再次强调:这里不做权限判断,删除/恢复等写操作是否被允许,最终由宿主后端 C2 闸门裁决,
443
+ * 插件侧调用失败需自行捕获异常并给用户合理提示。
444
+ */
445
+ export interface PageRecordListClient {
446
+ /** 获取当前模板基础信息(含 template_name/active_version_no/designer_type)。 */
447
+ getTemplate(): Promise<PageTemplateInfo>;
448
+ /** 获取当前模板下全部数据表(含 data_table_id/table_code/table_role)。
449
+ * 顺序承诺:主表恒首位,其后为扩展表按设计器拖动排序位(sort_no)升序;
450
+ * 插件按返回序展示即可,不必自排。 */
451
+ getTables(): Promise<PageDataTableInfo[]>;
452
+ /** 获取指定数据表的字段定义列表。 */
453
+ getFields(dataTableId: string): Promise<PageFieldInfo[]>;
454
+ /** 分页查询记录列表(支持关键字/排序/回收站过滤)。 */
455
+ listRecords(dataTableId: string, payload: PageRecordListPayload): Promise<PageRecordListResult>;
456
+ /** 按列表当前筛选/排序导出全部命中记录;宿主负责生成文件与触发下载。 */
457
+ exportRecords(
458
+ dataTableId: string,
459
+ payload: PageRecordExportPayload
460
+ ): Promise<{ rowCount: number; fieldPermissionMode: string }>;
461
+ /**
462
+ * 记录分组计数。可选方法:老宿主未实现时缺席,依赖它的界面
463
+ * (如左侧分类树)插件应降级为不显示,不报错、不 polyfill。权限闸与 listRecords 完全相同。
464
+ */
465
+ groupCount?(dataTableId: string, payload: PageRecordGroupCountPayload): Promise<PageRecordGroupCountResult>;
466
+ /** 软删除(移入回收站);单条删除也统一走此批量接口(传单元素数组)。 */
467
+ deleteRecords(dataTableId: string, recordIds: string[], templateVersionNo?: string): Promise<void>;
468
+ /** 彻底删除(物理删除,不可恢复),仅作用于回收站中已软删除的记录。 */
469
+ permanentDeleteRecords(dataTableId: string, recordIds: string[], templateVersionNo?: string): Promise<void>;
470
+ /** 从回收站恢复记录。 */
471
+ restoreRecords(dataTableId: string, recordIds: string[], templateVersionNo?: string): Promise<void>;
472
+ /**
473
+ * 批量锁定/解锁单据(手动锁定链路)。可选方法:老宿主未实现时插件应静默隐藏
474
+ * 锁定/解锁入口(不报错、不 polyfill)。与 delete/restore 不同,锁定不是对业务数据本身的
475
+ * 修改,不走「业务记录变更会话」(编辑租约)那条路径,天然支持批量、无需逐条加锁。
476
+ * recordIds 1~200 条;返回按幂等口径拆分 changedRecordIds(状态确有变化)与
477
+ * unchangedRecordIds(请求前状态已同 locked,不计入变更但也不算失败)。
478
+ */
479
+ setRecordsLocked?(
480
+ recordIds: string[],
481
+ locked: boolean
482
+ ): Promise<{ locked: boolean; changedRecordIds: string[]; unchangedRecordIds: string[] }>;
483
+ /**
484
+ * 重新执行某条记录最近一次未成功的保存后动作链(「重试」)。可选方法:老宿主未实现时
485
+ * 缺席,插件应静默隐藏重试入口(不报错、不 polyfill)。
486
+ * 仅对 action_run 处于终态异常(failed / canceled / timed_out / rolled_back)的记录可用;
487
+ * 执行中(foreground / background)或无 action_run 的记录宿主会拒绝。
488
+ * 宿主以新的 mutation_id 重新派发,返回新运行的 mutation_id 与受理时的状态码:链在宿主前台等待窗口内跑完时
489
+ * status 为新运行终态(succeeded / failed / timed_out / canceled / rolled_back);超窗时为 'running'——链已转
490
+ * 宿主服务端继续执行,终态经宿主通知送达(插件宜提示「已开始执行」并刷新列表)。
491
+ * 失败按宿主标准错误信封抛出(错误对象带原因文本)。
492
+ */
493
+ retryActionRun?(recordId: string): Promise<{ mutation_id: string; status: string }>;
494
+ /**
495
+ * 导出数据(后台任务)。可选方法:老宿主未实现时缺席。主表单据超过
496
+ * PAGE_RECORD_DATA_EXPORT_ASYNC_THRESHOLD 时调用,入参同 exportRecords 的工作簿版式;完成后宿主发站内通知,
497
+ * 文件在下载中心。宿主按「查看 + 导出」操作位与数据范围裁决。
498
+ */
499
+ createDataExportTask?(dataTableId: string, payload: PageRecordExportPayload): Promise<{ taskId: string; totalCount: number }>;
500
+ /**
501
+ * 以下为历史记录导入(均为可选方法,老宿主未实现时缺席,插件应隐藏导入入口)。导入按「新建」操作位裁决,
502
+ * 覆盖已有单据另需「修改」操作位且单据在修改范围内(宿主逐张核对并在预检里报出)。写入不经编辑器,
503
+ * 经宿主表单数据权威层的写前围栏判定;不触发保存后动作、通知与流程。
504
+ */
505
+ /** 下载空白导入模板(主表 + 所选扩展表);下载动作由宿主执行。 */
506
+ downloadImportTemplate?(dataTableId: string, extensionTableIds: string[]): Promise<void>;
507
+ /** 上传文件建导入作业并开始预检(预检不写库),返回作业,之后用 getImportJob 轮询。 */
508
+ startImport?(dataTableId: string, file: File, options: PageRecordImportOptions): Promise<PageRecordImportJob>;
509
+ /** 查询导入作业。 */
510
+ getImportJob?(jobId: string): Promise<PageRecordImportJob>;
511
+ /** 预检完成后开始写入(整批回滚且预检有问题时宿主拒绝)。 */
512
+ executeImport?(jobId: string): Promise<PageRecordImportJob>;
513
+ /** 下载错误报告(原行 + 错误原因列)。 */
514
+ downloadImportReport?(jobId: string): Promise<void>;
515
+ /** 丢弃未写入的作业。 */
516
+ cancelImport?(jobId: string): Promise<void>;
517
+ }
518
+
519
+ /**
520
+ * 页面导航客户端(hostBridge['navigation'])。
521
+ * 路由细节(如具体的 apps_sheet 路由名/query 结构)留在宿主内部,插件不感知,
522
+ * 只表达「打开某条记录」「新建一条记录」的业务意图,由宿主决定具体跳转方式。
523
+ */
524
+ export interface PageNavigationClient {
525
+ /** 打开某条已有记录(查看或编辑)。 */
526
+ openRecord(recordId: string, mode: 'view' | 'edit'): void;
527
+ /** 打开新增记录页面。 */
528
+ openCreate(): void;
529
+ }
530
+
531
+ /** 模板级权限矩阵摘要(对照宿主 CanonTemplatePermission 精简出的按钮开关)。 */
532
+ export interface PageTemplatePermissionSummary {
533
+ create: boolean;
534
+ view: boolean;
535
+ modify: boolean;
536
+ delete: boolean;
537
+ export: boolean;
538
+ print: boolean;
539
+ exportPdf: boolean;
540
+ // 单据导出 Excel 独立授权位(导出拆三项:export=导出表数据、exportXlsx=单据导出 Excel、
541
+ // exportPdf=单据导出 PDF)。可选:旧宿主未注入该字段时,插件应回落到 `export` 判定
542
+ // (即 `exportXlsx ?? export`),保持与拆分前一致的行为。
543
+ exportXlsx?: boolean;
544
+ // 单据锁定与解锁独立授权位。可选:兼容尚未升级到本版本 SDK 的旧宿主
545
+ // (未注入该字段时插件应视为未知/不可用,不擅自猜测为 true)。
546
+ lock?: boolean;
547
+ }
548
+
549
+ /**
550
+ * 权限摘要客户端(hostBridge['permission'])。
551
+ * 摘要来自权限框架下发给前端的权限矩阵,仅用于按钮置灰等体验优化,
552
+ * 不是安全边界——真正的裁决权威始终在宿主后端闸门,插件不能仅凭此摘要判定操作合法。
553
+ */
554
+ export interface PagePermissionClient {
555
+ /** 取当前模板的权限矩阵摘要(create/view/modify/delete)。 */
556
+ templatePermission(): PageTemplatePermissionSummary;
557
+ }
558
+
559
+ // 注意:此处曾声明 PageBatchPdfResult / PageBatchPdfClient 两个类型,对应 hostBridge['batch-pdf']。
560
+ // 批量打印功能未完成,宿主已下线该能力键(不再注入),故这两个类型一并移除——
561
+ // 保留一个宿主永不提供的 bridge 键契约,只会误导插件作者去消费一个拿不到的能力。
562
+ // 功能重启时连同宿主注入一起重新声明。
563
+
564
+ /**
565
+ * 单条字段修改痕迹(供历史记录页展示)。
566
+ * 对照宿主 FieldTraceItem:taskId 非空表示审批中修改(数据侧只记流程期),
567
+ * fieldName/actorName 由宿主批量补齐,查不到时分别回退 fieldId 本身/空字符串。
568
+ */
569
+ export interface PageFieldTraceItem {
570
+ fieldId: string;
571
+ fieldName: string;
572
+ dataTableId: string;
573
+ rowKey: string;
574
+ oldValue: unknown;
575
+ newValue: unknown;
576
+ actorUserId: number;
577
+ actorName: string;
578
+ taskId: string;
579
+ changedAt: string;
580
+ }
581
+
582
+ /**
583
+ * 字段修改痕迹只读客户端(hostBridge['field-trace'])。
584
+ * append-only 表按 record 时序线(changed_at DESC,最新在前)查询;权限复用记录查看闸,
585
+ * 能看该记录才能看其变更史,本客户端本身不构成安全边界。
586
+ * 是增强能力:宿主未接线该 cap 时插件应静默隐藏对应入口,而非报错阻断(与 record-list 不同)。
587
+ */
588
+ export interface PageFieldTraceClient {
589
+ /** 按 recordId 查询变更明细,limit 缺省 50、钳制 ≤200,offset 支持分页/「加载更多」。 */
590
+ list(recordId: string, params?: { limit?: number; offset?: number }): Promise<{ items: PageFieldTraceItem[]; total: number }>;
591
+ }