@kimposoft/plugin-sdk 0.0.0-stage → 1.1.0-tp.20
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.
- package/LICENSE +202 -0
- package/NOTICE +9 -0
- package/README.md +48 -2
- package/package.json +141 -4
- package/src/action-designer.ts +250 -0
- package/src/attachment-url.ts +195 -0
- package/src/auth/index.ts +6 -0
- package/src/auth/qrcode.ts +519 -0
- package/src/auth/types.ts +261 -0
- package/src/display-style.ts +250 -0
- package/src/editor-frame.ts +623 -0
- package/src/editor-session.ts +1214 -0
- package/src/editor-testing.ts +838 -0
- package/src/editor.ts +1641 -0
- package/src/frame-transport.ts +491 -0
- package/src/frontend-routes.ts +99 -0
- package/src/hooks.ts +48 -0
- package/src/host-caps.ts +93 -0
- package/src/i18n.ts +238 -0
- package/src/im-panel.ts +132 -0
- package/src/image-tools.ts +91 -0
- package/src/index.ts +118 -0
- package/src/interactive-session.ts +94 -0
- package/src/nahida-im.ts +391 -0
- package/src/nahida-ws.ts +23 -0
- package/src/org-directory.ts +78 -0
- package/src/oz-realtime.ts +144 -0
- package/src/page.ts +404 -0
- package/src/print.ts +393 -0
- package/src/surface.ts +281 -0
- package/src/theme-mocks.ts +140 -0
- package/src/theme.ts +125 -0
- package/src/ui-fixtures/confirm.ts +16 -0
- package/src/ui-fixtures/entity-picker.ts +24 -0
- package/src/ui-fixtures/expression-editor.ts +52 -0
- package/src/ui-fixtures/image-cropper.ts +23 -0
- package/src/ui-fixtures/index.ts +16 -0
- package/src/ui-fixtures/org-tri-picker.ts +19 -0
- package/src/ui-fixtures/prompt.ts +19 -0
- package/src/ui-fixtures/record-picker.ts +17 -0
- package/src/ui-fixtures/template-picker.ts +13 -0
- package/src/ui-mocks.ts +250 -0
- package/src/ui.ts +479 -0
- package/src/workflow-designer.ts +475 -0
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
// 宿主实时订阅通道的前端 host-cap 契约。导出名里的 `Oz` 前缀(OzRealtimeClient、OZ_TOPIC_*)是历史命名,
|
|
2
|
+
// 作为公开接口保留。
|
|
3
|
+
//
|
|
4
|
+
// 背景:如果每个需要服务端推送的插件功能各自开一条 SSE(表格编辑器的开单进度、kimpo-ai 的对话轮次
|
|
5
|
+
// 与方案构建),加上宿主自己的会话事件流,一个浏览器页面会挂出多条常驻长连接。明文 HTTP
|
|
6
|
+
// 即 HTTP/1.1,浏览器对同一 host:port 只有 6 条并发连接且**跨标签共享**——连开几张填报单据就
|
|
7
|
+
// 把连接池占满,此后所有普通请求排队至超时,页面误报「无法连接后端服务」。
|
|
8
|
+
//
|
|
9
|
+
// 实时订阅通道把这些推送收敛进**一条** WebSocket(宿主持有的 /ws/realtime),插件按「主题 + key」订阅。
|
|
10
|
+
// WebSocket 不占 HTTP 连接池。
|
|
11
|
+
//
|
|
12
|
+
// 🔴 连接由宿主持有,本契约只是"视图":没有 connect()/disconnect()——插件不拥有连接生命周期。
|
|
13
|
+
// 这一点与 nahida-ws.ts 的 NahidaWSClient 是同一条纪律,照它的先例设计。
|
|
14
|
+
//
|
|
15
|
+
// 🔴 插件只能订阅宿主开放给它的主题(表格编辑器 → sheet.open-progress;kimpo-ai → kimpoai.*),
|
|
16
|
+
// 且**不得直连 /ws/realtime**。服务端对每次订阅仍逐次鉴权,宿主侧白名单是角色分离的第二道闸。
|
|
17
|
+
//
|
|
18
|
+
// 🔴 第三方沙箱档(iframe)不可用(1.1.0-tp.18 起如实标注,已知限制 KL-51):宿主没有任何对第三方开放的主题,
|
|
19
|
+
// 编辑器沙箱桥与历史记录页等沙箱桥都不装配 `realtime`,manifest 声明 `editor.realtime` 也不会下发。
|
|
20
|
+
// 第三方前端请用 requireHostRealtime 取通道:拿不到时抛具名错误 OzRealtimeUnavailableError
|
|
21
|
+
// (沙箱档 code = OZ_REALTIME_SANDBOX_UNAVAILABLE),据此降级到轮询或不确定进度;
|
|
22
|
+
// 需要服务端推送的第三方功能目前只能由插件后端经宿主现有通道(如 Mirror 写回触发的 mirror.patch)间接驱动。
|
|
23
|
+
|
|
24
|
+
/** 连接状态。插件据此决定是否降级到轮询/兜底动画。 */
|
|
25
|
+
export type OzRealtimeState = 'connecting' | 'open' | 'disconnected';
|
|
26
|
+
|
|
27
|
+
/** 订阅回调集合。四个都可选,但不给 onEvent 的订阅通常没有意义。 */
|
|
28
|
+
export interface OzSubscriptionHandlers {
|
|
29
|
+
/**
|
|
30
|
+
* 一条业务事件。event 是主题内事件名(如 'progress'),data 是该主题约定的载荷。
|
|
31
|
+
*
|
|
32
|
+
* 🔴 meta.seq 只用于**比较**(判断是否已处理过),**不得做差值、计数或推断"丢了几条"**:
|
|
33
|
+
* 序号在服务端是每个主题内全局递增的,同一个 key 上的序号稀疏不连续。
|
|
34
|
+
*/
|
|
35
|
+
onEvent?: (event: string, data: unknown, meta: { seq: number }) => void;
|
|
36
|
+
/** 主题结束(开单完成、轮次完成、构建终态)。收到后该订阅不会再有任何回调。 */
|
|
37
|
+
onEnd?: (reason: string, data: unknown) => void;
|
|
38
|
+
/** 订阅级错误(鉴权失败、主题不存在、超限)。该订阅已终止,不会自动重试。 */
|
|
39
|
+
onError?: (code: string, message: string) => void;
|
|
40
|
+
/**
|
|
41
|
+
* 服务端缓冲已越界或发生背压,客户端与服务端的事件序列可能已经对不上。
|
|
42
|
+
* 订阅仍然存活,但插件应当按自己主题的约定对账(如重新拉一次终态、或放弃增量显示)。
|
|
43
|
+
*/
|
|
44
|
+
onResync?: (reason: string) => void;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* 宿主实时订阅通道能力面(hostCaps `editor.realtime` → bridge 属性 `realtime`)。
|
|
49
|
+
*
|
|
50
|
+
* 可选能力:老宿主不注入时插件必须优雅降级(例如表格编辑器退回不确定进度动画),
|
|
51
|
+
* 被订阅的功能本身不得依赖这条通道才能完成。
|
|
52
|
+
*/
|
|
53
|
+
export interface OzRealtimeClient {
|
|
54
|
+
/**
|
|
55
|
+
* 订阅一个主题的一个 key,返回注销函数(幂等)。
|
|
56
|
+
*
|
|
57
|
+
* 连接是懒建的:宿主在第一个订阅到来时才握手,最后一个订阅注销后延迟断开。
|
|
58
|
+
* 插件不需要(也不应该)关心这些。
|
|
59
|
+
*/
|
|
60
|
+
subscribe(topic: string, key: string, handlers: OzSubscriptionHandlers): () => void;
|
|
61
|
+
/** 当前连接状态。 */
|
|
62
|
+
getState(): OzRealtimeState;
|
|
63
|
+
/** 订阅连接状态变化。返回取消订阅函数。 */
|
|
64
|
+
onStateChange(handler: (state: OzRealtimeState) => void): () => void;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** 主题名常量(与宿主后端注册的主题一一对应)。 */
|
|
68
|
+
export const OZ_TOPIC_SHEET_OPEN_PROGRESS = 'sheet.open-progress';
|
|
69
|
+
export const OZ_TOPIC_KIMPOAI_TURN = 'kimpoai.turn';
|
|
70
|
+
export const OZ_TOPIC_KIMPOAI_RUN = 'kimpoai.run';
|
|
71
|
+
|
|
72
|
+
// ── 可用性判定(1.1.0-tp.18)──────────────────────────────────────────────
|
|
73
|
+
|
|
74
|
+
/** 沙箱档(第三方 iframe)里拿不到实时通道:宿主不为第三方开放任何主题,桥上也不装配 realtime。 */
|
|
75
|
+
export const OZ_REALTIME_SANDBOX_UNAVAILABLE = 'OZ_REALTIME_SANDBOX_UNAVAILABLE';
|
|
76
|
+
/** 同源档里宿主没有注入实时通道(老宿主、或该挂载点 / 插件未被开放主题)。 */
|
|
77
|
+
export const OZ_REALTIME_NOT_PROVIDED = 'OZ_REALTIME_NOT_PROVIDED';
|
|
78
|
+
|
|
79
|
+
/** 实时通道不可用的具名错误;插件捕获后按 code 降级,不要重试。 */
|
|
80
|
+
export class OzRealtimeUnavailableError extends Error {
|
|
81
|
+
readonly code: typeof OZ_REALTIME_SANDBOX_UNAVAILABLE | typeof OZ_REALTIME_NOT_PROVIDED;
|
|
82
|
+
constructor(code: typeof OZ_REALTIME_SANDBOX_UNAVAILABLE | typeof OZ_REALTIME_NOT_PROVIDED) {
|
|
83
|
+
super(
|
|
84
|
+
code === OZ_REALTIME_SANDBOX_UNAVAILABLE
|
|
85
|
+
? 'host realtime channel is not available to sandboxed (iframe) plugin frontends'
|
|
86
|
+
: 'host realtime channel is not provided on this bridge'
|
|
87
|
+
);
|
|
88
|
+
this.name = 'OzRealtimeUnavailableError';
|
|
89
|
+
this.code = code;
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/** 是否运行在宿主沙箱框架里(与 frame-transport isKimpoFrameContext 同口径;此处内联避免循环依赖)。 */
|
|
94
|
+
function inSandboxFrame(): boolean {
|
|
95
|
+
if (typeof window === 'undefined' || typeof document === 'undefined') return false;
|
|
96
|
+
let framed = false;
|
|
97
|
+
try {
|
|
98
|
+
framed = window.parent !== window;
|
|
99
|
+
} catch {
|
|
100
|
+
framed = true;
|
|
101
|
+
}
|
|
102
|
+
try {
|
|
103
|
+
return framed && !!document.querySelector('meta[name="kimpo-frame"]');
|
|
104
|
+
} catch {
|
|
105
|
+
return false;
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** 从宿主桥读实时通道;读未声明键被裁剪 Proxy 抛错、或形状不对时按缺席处理。 */
|
|
110
|
+
function readRealtimeOf(hostBridge: unknown): OzRealtimeClient | null {
|
|
111
|
+
try {
|
|
112
|
+
const rt = (hostBridge as { realtime?: OzRealtimeClient } | null | undefined)?.realtime;
|
|
113
|
+
return rt && typeof rt.subscribe === 'function' ? rt : null;
|
|
114
|
+
} catch {
|
|
115
|
+
return null;
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* 取宿主实时通道,拿不到时抛 OzRealtimeUnavailableError:
|
|
121
|
+
* - 沙箱档(第三方前端)恒抛 code = OZ_REALTIME_SANDBOX_UNAVAILABLE(即使桥上意外出现同名键也不采用);
|
|
122
|
+
* - 同源档桥上没有通道时抛 code = OZ_REALTIME_NOT_PROVIDED。
|
|
123
|
+
* options.sandboxed 可显式指定挂载档(单测 / 非浏览器环境用),缺省按当前文档判定。
|
|
124
|
+
*/
|
|
125
|
+
export function requireHostRealtime(hostBridge: unknown, options: { sandboxed?: boolean } = {}): OzRealtimeClient {
|
|
126
|
+
const sandboxed = options.sandboxed ?? inSandboxFrame();
|
|
127
|
+
if (sandboxed) throw new OzRealtimeUnavailableError(OZ_REALTIME_SANDBOX_UNAVAILABLE);
|
|
128
|
+
const rt = readRealtimeOf(hostBridge);
|
|
129
|
+
if (!rt) throw new OzRealtimeUnavailableError(OZ_REALTIME_NOT_PROVIDED);
|
|
130
|
+
return rt;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/** requireHostRealtime 的不抛错版本:可用返回通道,不可用返回 null 与具名原因。 */
|
|
134
|
+
export function probeHostRealtime(
|
|
135
|
+
hostBridge: unknown,
|
|
136
|
+
options: { sandboxed?: boolean } = {}
|
|
137
|
+
): { client: OzRealtimeClient | null; code: OzRealtimeUnavailableError['code'] | null } {
|
|
138
|
+
try {
|
|
139
|
+
return { client: requireHostRealtime(hostBridge, options), code: null };
|
|
140
|
+
} catch (error) {
|
|
141
|
+
if (error instanceof OzRealtimeUnavailableError) return { client: null, code: error.code };
|
|
142
|
+
throw error;
|
|
143
|
+
}
|
|
144
|
+
}
|
package/src/page.ts
ADDED
|
@@ -0,0 +1,404 @@
|
|
|
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
|
+
sort_no: number;
|
|
78
|
+
field_count: number;
|
|
79
|
+
version_no: number;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** 字段定义(对照宿主 TemplateField 类型)。 */
|
|
83
|
+
export interface PageFieldInfo {
|
|
84
|
+
field_id: string;
|
|
85
|
+
field_code: string;
|
|
86
|
+
field_name: string;
|
|
87
|
+
data_type: string;
|
|
88
|
+
control_type?: string;
|
|
89
|
+
display_style: string;
|
|
90
|
+
sort_no: number;
|
|
91
|
+
/**
|
|
92
|
+
* 以下四项宿主当前不下发:缺省时按“可搜索 / 可筛选 / 可排序 /
|
|
93
|
+
* 列表可见”处理,插件不要依赖它们做必选判定(否则按 is_list_visible 选列会一列都不显示)。
|
|
94
|
+
*/
|
|
95
|
+
is_searchable?: boolean;
|
|
96
|
+
is_filterable?: boolean;
|
|
97
|
+
is_sortable?: boolean;
|
|
98
|
+
is_list_visible?: boolean;
|
|
99
|
+
format_rule_json?: Record<string, unknown> | string | null;
|
|
100
|
+
option_source_json?: Record<string, unknown> | string | null;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/** 记录列表排序项(对照宿主 RuntimeRecordSort 类型)。 */
|
|
104
|
+
export interface PageRecordSort {
|
|
105
|
+
field_id?: string;
|
|
106
|
+
field_code?: string;
|
|
107
|
+
system_column?: string;
|
|
108
|
+
desc?: boolean;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* 单据锁定状态只读投影。
|
|
113
|
+
* source 区分手动锁定(右键菜单)与自动锁定(模板属性里的判断表达式);locked_by/locked_by_name/
|
|
114
|
+
* locked_at 只在 locked=true 时有意义。locked_at 是后端下发的 UTC RFC3339 字符串,展示前必须按
|
|
115
|
+
* 当前用户时区本地化换算(不得墙钟字面展示,与业务日期字段的 formatFieldDateTime 区分对待)。
|
|
116
|
+
*/
|
|
117
|
+
export interface PageRecordLockState {
|
|
118
|
+
locked: boolean;
|
|
119
|
+
source?: 'manual' | 'auto';
|
|
120
|
+
locked_by?: number;
|
|
121
|
+
locked_by_name?: string;
|
|
122
|
+
locked_at?: string;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** 锁定状态筛选值:'locked'/'unlocked' 二选一,缺省不筛选。 */
|
|
126
|
+
export type PageRecordLockStatusFilter = 'locked' | 'unlocked';
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* 记录列表条件项。
|
|
130
|
+
* field_id / field_code 与 system_column 二选一,同时出现或都缺 → 宿主 RUNTIME_FILTER_INVALID。
|
|
131
|
+
* system_column 为 created_by/updated_by 时 op 仅 '=' / 'IS_EMPTY',value 为用户 id;
|
|
132
|
+
* 为 created_at/updated_at 时 op 取 '>=' / '<' / '=' / 'IS_EMPTY',value 为 RFC3339 带偏移的时刻串(后端换 UTC 比较)。
|
|
133
|
+
* 条件指向当前用户隐藏字段 → 400 RUNTIME_FIELD_HIDDEN。
|
|
134
|
+
*/
|
|
135
|
+
export interface PageRecordFilter {
|
|
136
|
+
field_id?: string;
|
|
137
|
+
field_code?: string;
|
|
138
|
+
system_column?: 'created_by' | 'updated_by' | 'created_at' | 'updated_at';
|
|
139
|
+
/** '=', '!=', '>', '>=', '<', '<=', 'CONTAINS', 'STARTS_WITH', 'ENDS_WITH', 'IS_EMPTY', 'IS_NOT_EMPTY' */
|
|
140
|
+
op: string;
|
|
141
|
+
value?: unknown;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** 流程状态筛选值:not_started/running/ended 子集,空数组/缺省 = 不筛选。 */
|
|
145
|
+
export type PageWorkflowStatusFilter = Array<'not_started' | 'running' | 'ended'>;
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* 「我的关系」筛选值:'pending_mine'=当前待办人含操作人;'initiated_by_me'=记录创建人
|
|
149
|
+
* 是操作人(口径退化);空串/缺省=不筛选。与流程状态筛选同一生效条件(仅模板主表且已绑定流程)。
|
|
150
|
+
*/
|
|
151
|
+
export type PageWorkflowMyRelationFilter = '' | 'pending_mine' | 'initiated_by_me';
|
|
152
|
+
|
|
153
|
+
/** 记录列表查询入参(对照宿主 RuntimeRecordListPayload 类型)。 */
|
|
154
|
+
export interface PageRecordListPayload {
|
|
155
|
+
template_version_no?: string;
|
|
156
|
+
/** true=查回收站(已软删除)记录。 */
|
|
157
|
+
deleted?: boolean;
|
|
158
|
+
keyword?: string;
|
|
159
|
+
/** 条件列表;老宿主忽略。 */
|
|
160
|
+
filters?: PageRecordFilter[];
|
|
161
|
+
sorts?: PageRecordSort[];
|
|
162
|
+
/** 流程状态筛选子集;仅模板主表且已绑定流程时后端生效,其余场景忽略。 */
|
|
163
|
+
workflow_status?: PageWorkflowStatusFilter;
|
|
164
|
+
/** 「我的关系」筛选;同 workflow_status 生效条件,空串/缺省=不筛选。 */
|
|
165
|
+
workflow_my_relation?: PageWorkflowMyRelationFilter;
|
|
166
|
+
/** 锁定状态筛选;缺省不过滤。 */
|
|
167
|
+
lock_status?: PageRecordLockStatusFilter;
|
|
168
|
+
limit: number;
|
|
169
|
+
offset: number;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
export type PageRecordExportPayload = Omit<PageRecordListPayload, 'limit' | 'offset'>;
|
|
173
|
+
|
|
174
|
+
/** 单条运行态记录(对照宿主 RuntimeRecord 类型)。 */
|
|
175
|
+
export interface PageRuntimeRecord {
|
|
176
|
+
record_id: string;
|
|
177
|
+
created_at?: string;
|
|
178
|
+
created_by?: string | number | null;
|
|
179
|
+
created_by_name?: string | null;
|
|
180
|
+
updated_at?: string;
|
|
181
|
+
updated_by?: string | number | null;
|
|
182
|
+
updated_by_name?: string | null;
|
|
183
|
+
version_no: number;
|
|
184
|
+
values: Record<string, unknown>;
|
|
185
|
+
/**
|
|
186
|
+
* 锁定状态:从未锁定过的记录该字段缺席,视为未锁定——不得把「缺席」误当作
|
|
187
|
+
* 「已知未锁定」以外的任何含义(例如误判为加载失败)。
|
|
188
|
+
*/
|
|
189
|
+
lock?: PageRecordLockState;
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/** 记录列表查询结果(对照宿主 RuntimeRecordListResult 类型)。 */
|
|
193
|
+
export interface PageRecordListResult {
|
|
194
|
+
items: PageRuntimeRecord[];
|
|
195
|
+
total: number;
|
|
196
|
+
limit: number;
|
|
197
|
+
offset: number;
|
|
198
|
+
/**
|
|
199
|
+
* 查询上下文读票据:assetId → 票据,宿主对本页结果里出现的
|
|
200
|
+
* 图片 / 附件条目签发(短期、只读、绑定当前用户)。插件把它原样交给 SDK `attachmentItemUrls` 的
|
|
201
|
+
* `tickets` 选项取地址,不自行拼接宿主路径;老宿主不下发时缺席,地址不带票据。
|
|
202
|
+
*/
|
|
203
|
+
asset_tickets?: Record<string, string>;
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
// ── 分组计数 ───────────────────────────────────────────────────────────────
|
|
207
|
+
|
|
208
|
+
/** 分组方式:按值 / 按年 / 按月 / 按日(日期类)/ 按数值区间。mode 须与字段类型匹配,否则 RUNTIME_GROUP_MODE_INVALID。 */
|
|
209
|
+
export type PageRecordGroupMode = 'value' | 'year' | 'month' | 'day' | 'range';
|
|
210
|
+
|
|
211
|
+
/** 单个分组维度;field_id 与 system_column 二选一。range 模式须给 range_width(>0)。 */
|
|
212
|
+
export interface PageRecordGroupBy {
|
|
213
|
+
field_id?: string;
|
|
214
|
+
system_column?: 'created_by' | 'updated_by' | 'created_at' | 'updated_at';
|
|
215
|
+
mode: PageRecordGroupMode;
|
|
216
|
+
/** 仅 mode='range':区间宽度,必须 > 0。 */
|
|
217
|
+
range_width?: number;
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/** 分组计数请求:列表请求去掉分页与排序,另加分组维度;label_contains 仅单分组项时生效。 */
|
|
221
|
+
export interface PageRecordGroupCountPayload extends Omit<PageRecordListPayload, 'limit' | 'offset' | 'sorts'> {
|
|
222
|
+
group_by: PageRecordGroupBy[];
|
|
223
|
+
label_contains?: string;
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* 分组键。empty=true 为空值组(其余字段为空);按值时 value 为原始值(成员/部门/填报人/更新人为标识,
|
|
228
|
+
* 另给 label 显示名);year/month/day 时 value 为桶起点,range_start/range_end 为可直接作列表条件的边界
|
|
229
|
+
* (墙钟字段为 'YYYY-MM-DD HH:mm:ss',按 UTC 存的列为 RFC3339 带偏移);range 时为数值,含起不含止。
|
|
230
|
+
*/
|
|
231
|
+
export interface PageRecordGroupKey {
|
|
232
|
+
empty: boolean;
|
|
233
|
+
value?: string | number | null;
|
|
234
|
+
range_start?: string | number | null;
|
|
235
|
+
range_end?: string | number | null;
|
|
236
|
+
label?: string;
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/** 一个分组:每个分组维度一个 key,加命中记录数。 */
|
|
240
|
+
export interface PageRecordGroup {
|
|
241
|
+
keys: PageRecordGroupKey[];
|
|
242
|
+
count: number;
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/** 分组计数结果;最多 200 组,超出时 truncated=true 并给剩余组数与记录数。 */
|
|
246
|
+
export interface PageRecordGroupCountResult {
|
|
247
|
+
groups: PageRecordGroup[];
|
|
248
|
+
truncated: boolean;
|
|
249
|
+
rest_group_count: number;
|
|
250
|
+
rest_record_count: number;
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
// ── 插件模板级配置 ─────────────────────────────────────────────────────────
|
|
254
|
+
|
|
255
|
+
/** 插件模板级配置快照(hostBridge['plugin-config'].get 返回);从未保存时 config=null、version=0。 */
|
|
256
|
+
export interface PagePluginConfigSnapshot {
|
|
257
|
+
config: unknown | null;
|
|
258
|
+
/** 乐观并发版本号,保存时原样回传。 */
|
|
259
|
+
version: number;
|
|
260
|
+
/** 当前用户是否可编辑(=应用设计权限);仅用于 UI 置灰,不是安全边界。 */
|
|
261
|
+
can_edit: boolean;
|
|
262
|
+
updated_by_name: string;
|
|
263
|
+
/** RFC3339 UTC 字符串;从未保存为 null。 */
|
|
264
|
+
updated_at: string | null;
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
/** 保存结果:新版本号与最近更新人信息。 */
|
|
268
|
+
export interface PagePluginConfigSaveResult {
|
|
269
|
+
version: number;
|
|
270
|
+
updated_by_name: string;
|
|
271
|
+
updated_at: string | null;
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/** 宿主桥抛出的错误带 code(如 'PLUGIN_CONFIG_VERSION_CONFLICT' / 'PLUGIN_CONFIG_TOO_LARGE' / 'PLUGIN_CONFIG_INVALID')。 */
|
|
275
|
+
export interface PageHostError extends Error {
|
|
276
|
+
code?: string;
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/**
|
|
280
|
+
* 插件模板级配置客户端(hostBridge['plugin-config'])。
|
|
281
|
+
* 配置按「当前模板 + 当前挂载插件」存取,插件标识由宿主桥填入,插件不传。
|
|
282
|
+
* 配置体上限 64 KB;保存时 version 传读到的版本(首次保存传 0),冲突抛 PLUGIN_CONFIG_VERSION_CONFLICT。
|
|
283
|
+
*/
|
|
284
|
+
export interface PagePluginConfigClient {
|
|
285
|
+
get(): Promise<PagePluginConfigSnapshot>;
|
|
286
|
+
save(config: unknown, version: number): Promise<PagePluginConfigSaveResult>;
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* 记录列表数据客户端(hostBridge['record-list'])。
|
|
291
|
+
* 薄封装宿主 REST 接口(fetchTemplate/fetchTemplateTables/fetchTemplateFields/
|
|
292
|
+
* fetchRuntimeRecords/fetchBatch*RuntimeRecords 等),插件只管调用,不感知具体 URL。
|
|
293
|
+
* 再次强调:这里不做权限判断,删除/恢复等写操作是否被允许,最终由宿主后端 C2 闸门裁决,
|
|
294
|
+
* 插件侧调用失败需自行捕获异常并给用户合理提示。
|
|
295
|
+
*/
|
|
296
|
+
export interface PageRecordListClient {
|
|
297
|
+
/** 获取当前模板基础信息(含 template_name/active_version_no/designer_type)。 */
|
|
298
|
+
getTemplate(): Promise<PageTemplateInfo>;
|
|
299
|
+
/** 获取当前模板下全部数据表(含 data_table_id/table_code/table_role)。
|
|
300
|
+
* 顺序承诺:主表恒首位,其后为扩展表按设计器拖动排序位(sort_no)升序;
|
|
301
|
+
* 插件按返回序展示即可,不必自排。 */
|
|
302
|
+
getTables(): Promise<PageDataTableInfo[]>;
|
|
303
|
+
/** 获取指定数据表的字段定义列表。 */
|
|
304
|
+
getFields(dataTableId: string): Promise<PageFieldInfo[]>;
|
|
305
|
+
/** 分页查询记录列表(支持关键字/排序/回收站过滤)。 */
|
|
306
|
+
listRecords(dataTableId: string, payload: PageRecordListPayload): Promise<PageRecordListResult>;
|
|
307
|
+
/** 按列表当前筛选/排序导出全部命中记录;宿主负责生成文件与触发下载。 */
|
|
308
|
+
exportRecords(
|
|
309
|
+
dataTableId: string,
|
|
310
|
+
payload: PageRecordExportPayload
|
|
311
|
+
): Promise<{ rowCount: number; fieldPermissionMode: string }>;
|
|
312
|
+
/**
|
|
313
|
+
* 记录分组计数。可选方法:老宿主未实现时缺席,依赖它的界面
|
|
314
|
+
* (如左侧分类树)插件应降级为不显示,不报错、不 polyfill。权限闸与 listRecords 完全相同。
|
|
315
|
+
*/
|
|
316
|
+
groupCount?(dataTableId: string, payload: PageRecordGroupCountPayload): Promise<PageRecordGroupCountResult>;
|
|
317
|
+
/** 软删除(移入回收站);单条删除也统一走此批量接口(传单元素数组)。 */
|
|
318
|
+
deleteRecords(dataTableId: string, recordIds: string[], templateVersionNo?: string): Promise<void>;
|
|
319
|
+
/** 彻底删除(物理删除,不可恢复),仅作用于回收站中已软删除的记录。 */
|
|
320
|
+
permanentDeleteRecords(dataTableId: string, recordIds: string[], templateVersionNo?: string): Promise<void>;
|
|
321
|
+
/** 从回收站恢复记录。 */
|
|
322
|
+
restoreRecords(dataTableId: string, recordIds: string[], templateVersionNo?: string): Promise<void>;
|
|
323
|
+
/**
|
|
324
|
+
* 批量锁定/解锁单据(手动锁定链路)。可选方法:老宿主未实现时插件应静默隐藏
|
|
325
|
+
* 锁定/解锁入口(不报错、不 polyfill)。与 delete/restore 不同,锁定不是对业务数据本身的
|
|
326
|
+
* 修改,不走「业务记录变更会话」(编辑租约)那条路径,天然支持批量、无需逐条加锁。
|
|
327
|
+
* recordIds 1~200 条;返回按幂等口径拆分 changedRecordIds(状态确有变化)与
|
|
328
|
+
* unchangedRecordIds(请求前状态已同 locked,不计入变更但也不算失败)。
|
|
329
|
+
*/
|
|
330
|
+
setRecordsLocked?(
|
|
331
|
+
recordIds: string[],
|
|
332
|
+
locked: boolean
|
|
333
|
+
): Promise<{ locked: boolean; changedRecordIds: string[]; unchangedRecordIds: string[] }>;
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
/**
|
|
337
|
+
* 页面导航客户端(hostBridge['navigation'])。
|
|
338
|
+
* 路由细节(如具体的 apps_sheet 路由名/query 结构)留在宿主内部,插件不感知,
|
|
339
|
+
* 只表达「打开某条记录」「新建一条记录」的业务意图,由宿主决定具体跳转方式。
|
|
340
|
+
*/
|
|
341
|
+
export interface PageNavigationClient {
|
|
342
|
+
/** 打开某条已有记录(查看或编辑)。 */
|
|
343
|
+
openRecord(recordId: string, mode: 'view' | 'edit'): void;
|
|
344
|
+
/** 打开新增记录页面。 */
|
|
345
|
+
openCreate(): void;
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
/** 模板级权限矩阵摘要(对照宿主 CanonTemplatePermission 精简出的按钮开关)。 */
|
|
349
|
+
export interface PageTemplatePermissionSummary {
|
|
350
|
+
create: boolean;
|
|
351
|
+
view: boolean;
|
|
352
|
+
modify: boolean;
|
|
353
|
+
delete: boolean;
|
|
354
|
+
export: boolean;
|
|
355
|
+
print: boolean;
|
|
356
|
+
exportPdf: boolean;
|
|
357
|
+
// 单据锁定与解锁独立授权位。可选:兼容尚未升级到本版本 SDK 的旧宿主
|
|
358
|
+
// (未注入该字段时插件应视为未知/不可用,不擅自猜测为 true)。
|
|
359
|
+
lock?: boolean;
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
/**
|
|
363
|
+
* 权限摘要客户端(hostBridge['permission'])。
|
|
364
|
+
* 摘要来自权限框架下发给前端的权限矩阵,仅用于按钮置灰等体验优化,
|
|
365
|
+
* 不是安全边界——真正的裁决权威始终在宿主后端闸门,插件不能仅凭此摘要判定操作合法。
|
|
366
|
+
*/
|
|
367
|
+
export interface PagePermissionClient {
|
|
368
|
+
/** 取当前模板的权限矩阵摘要(create/view/modify/delete)。 */
|
|
369
|
+
templatePermission(): PageTemplatePermissionSummary;
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
// 注意:此处曾声明 PageBatchPdfResult / PageBatchPdfClient 两个类型,对应 hostBridge['batch-pdf']。
|
|
373
|
+
// 批量打印功能未完成,宿主已下线该能力键(不再注入),故这两个类型一并移除——
|
|
374
|
+
// 保留一个宿主永不提供的 bridge 键契约,只会误导插件作者去消费一个拿不到的能力。
|
|
375
|
+
// 功能重启时连同宿主注入一起重新声明。
|
|
376
|
+
|
|
377
|
+
/**
|
|
378
|
+
* 单条字段修改痕迹(供历史记录页展示)。
|
|
379
|
+
* 对照宿主 FieldTraceItem:taskId 非空表示审批中修改(数据侧只记流程期),
|
|
380
|
+
* fieldName/actorName 由宿主批量补齐,查不到时分别回退 fieldId 本身/空字符串。
|
|
381
|
+
*/
|
|
382
|
+
export interface PageFieldTraceItem {
|
|
383
|
+
fieldId: string;
|
|
384
|
+
fieldName: string;
|
|
385
|
+
dataTableId: string;
|
|
386
|
+
rowKey: string;
|
|
387
|
+
oldValue: unknown;
|
|
388
|
+
newValue: unknown;
|
|
389
|
+
actorUserId: number;
|
|
390
|
+
actorName: string;
|
|
391
|
+
taskId: string;
|
|
392
|
+
changedAt: string;
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
/**
|
|
396
|
+
* 字段修改痕迹只读客户端(hostBridge['field-trace'])。
|
|
397
|
+
* append-only 表按 record 时序线(changed_at DESC,最新在前)查询;权限复用记录查看闸,
|
|
398
|
+
* 能看该记录才能看其变更史,本客户端本身不构成安全边界。
|
|
399
|
+
* 是增强能力:宿主未接线该 cap 时插件应静默隐藏对应入口,而非报错阻断(与 record-list 不同)。
|
|
400
|
+
*/
|
|
401
|
+
export interface PageFieldTraceClient {
|
|
402
|
+
/** 按 recordId 查询变更明细,limit 缺省 50、钳制 ≤200,offset 支持分页/「加载更多」。 */
|
|
403
|
+
list(recordId: string, params?: { limit?: number; offset?: number }): Promise<{ items: PageFieldTraceItem[]; total: number }>;
|
|
404
|
+
}
|