@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.
- package/LICENSE +202 -0
- package/NOTICE +9 -0
- package/README.md +48 -2
- package/package.json +145 -4
- package/src/action-designer.ts +267 -0
- package/src/attachment-open.ts +574 -0
- package/src/attachment-url.ts +235 -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 +532 -0
- package/src/editor-frame.ts +625 -0
- package/src/editor-session.ts +1214 -0
- package/src/editor-testing.ts +838 -0
- package/src/editor.ts +1720 -0
- package/src/frame-transport.ts +516 -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 +125 -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 +591 -0
- package/src/print.ts +393 -0
- package/src/surface.ts +310 -0
- package/src/theme-mocks.ts +140 -0
- package/src/theme.ts +125 -0
- package/src/ui-fixtures/attachment.ts +24 -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 +17 -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 +264 -0
- package/src/ui.ts +491 -0
- package/src/workflow-designer.ts +475 -0
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
// 组织架构取人前端契约(IM 前端插件等使用)。
|
|
2
|
+
//
|
|
3
|
+
// 定位:IM 的"通讯录" = 组织架构树(不是好友列表),插件要渲染部门树 + 成员,
|
|
4
|
+
// 但**插件不碰组织表**——本契约只是对宿主既有 IAM 接口(org-units/tree、
|
|
5
|
+
// org-units/{id}/users、directory/users 等)的薄封装类型定义,真正的查询/鉴权仍在宿主,
|
|
6
|
+
// 插件侧不重新实现任何组织查询逻辑。
|
|
7
|
+
//
|
|
8
|
+
// 与 page.ts 的 PageRecordListClient 同一惯例:本文件只定义类型契约(Host 实现、经
|
|
9
|
+
// hostBridge/props 注入给插件),本身不构成安全边界——列表能拿到哪些部门/成员仍由宿主
|
|
10
|
+
// 后端裁决(如权限框架的数据范围),插件只管调用。
|
|
11
|
+
|
|
12
|
+
/** 部门树节点(对照宿主 OrgUnitNode 类型,仅摘取 IM 通讯录渲染需要的字段)。 */
|
|
13
|
+
export interface OrgDept {
|
|
14
|
+
id: string;
|
|
15
|
+
parentId: string | null;
|
|
16
|
+
name: string;
|
|
17
|
+
/** 物化路径(形如 "1/3/7"),供前端就地判断层级关系,不代表可以据此自行展开子部门。 */
|
|
18
|
+
path: string;
|
|
19
|
+
/** 子部门数(渲染展开箭头用;listDepartments 是 lazy 分层拉取,不代表本节点已含子节点数据)。 */
|
|
20
|
+
childCount?: number;
|
|
21
|
+
/** 部门直属成员数(渲染角标用)。 */
|
|
22
|
+
memberCount?: number;
|
|
23
|
+
/** active 可选取;inactive 仅供历史值解析为“已停用”展示。 */
|
|
24
|
+
statusCode?: string;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** 部门成员(对照宿主 DirectoryUser 类型的精简视图)。 */
|
|
28
|
+
export interface OrgMember {
|
|
29
|
+
userId: string;
|
|
30
|
+
userNo?: string;
|
|
31
|
+
loginName?: string;
|
|
32
|
+
displayName: string;
|
|
33
|
+
/** 受宿主会话保护、可直接交给 img.src 的头像地址。 */
|
|
34
|
+
avatar?: string;
|
|
35
|
+
mobile?: string;
|
|
36
|
+
email?: string;
|
|
37
|
+
/** 该用户的主部门 id;无主部门(理论上不应发生)时为 null。 */
|
|
38
|
+
primaryOrgUnitId?: string | null;
|
|
39
|
+
/** 用户的全部明确部门归属;同一用户可在多个部门节点出现。 */
|
|
40
|
+
memberships: readonly OrgMembership[];
|
|
41
|
+
statusCode?: string;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** 用户在一个明确部门的归属。全局搜索以 userId 去重,展示此数组而非丢弃兼任部门。 */
|
|
45
|
+
export interface OrgMembership {
|
|
46
|
+
readonly orgUnitId: string;
|
|
47
|
+
readonly orgUnitName?: string;
|
|
48
|
+
readonly primary: boolean;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* 组织架构取人客户端(hostBridge['org-directory'],IM 插件通讯录面板用)。
|
|
53
|
+
*
|
|
54
|
+
* 🔴 `listMembers` 只返回目标部门的**直属成员,不含子部门**——对应"部门群不含子部门"的
|
|
55
|
+
* 产品规则。宿主实现必须直接薄封装 `GET /api/v1/iam/org-units/{id}/users`
|
|
56
|
+
* (该端点本就只查直属成员),**不得自作主张递归**
|
|
57
|
+
* 拼出"含子部门"的语义。
|
|
58
|
+
*/
|
|
59
|
+
export interface OrgDirectoryClient {
|
|
60
|
+
/** 拉组织树(部门层级)。lazy:只拉 parentId 这一层,展开时再拉子层;parentId 缺省=拉根部门。 */
|
|
61
|
+
listDepartments(parentId?: string): Promise<OrgDept[]>;
|
|
62
|
+
/** 拉某部门的直属成员(⚠️ 不含子部门——见上方接口注释)。 */
|
|
63
|
+
listMembers(deptId: string, options?: { readonly includeChildren?: false }): Promise<OrgMember[]>;
|
|
64
|
+
/** 按名字/拼音搜人(IM 的"搜联系人"用);结果必须按 userId 去重,memberships 保留全部部门。 */
|
|
65
|
+
searchUsers(keyword: string, limit?: number): Promise<OrgMember[]>;
|
|
66
|
+
/**
|
|
67
|
+
* 按稳定 userId 批量解析当前可见实体。未返回的 id 表示已删除或超出当前数据权限,
|
|
68
|
+
* 调用方必须保留原 id 并显示悬空态,不得把它静默清空。
|
|
69
|
+
*/
|
|
70
|
+
resolveUsers?(userIds: readonly string[]): Promise<OrgMember[]>;
|
|
71
|
+
/**
|
|
72
|
+
* 按稳定部门 id 批量解析当前可见实体。inactive 部门仍可返回供历史值展示,
|
|
73
|
+
* 但不得作为新选择候选;未返回的 id 由调用方显示悬空态。
|
|
74
|
+
*/
|
|
75
|
+
resolveDepartments?(deptIds: readonly string[]): Promise<OrgDept[]>;
|
|
76
|
+
/** 当前用户自己的信息(IM 面板展示"我"这一行)。 */
|
|
77
|
+
me(): Promise<OrgMember>;
|
|
78
|
+
}
|
|
@@ -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
|
+
}
|