@xgspz/base-sdk 0.0.0-stage → 1.0.5

package/dist/index.js

@@ -0,0 +1,383 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { currentRequestId, REQUEST_ID_HEADER } from "@xgspz/service-kit";
+/**
+ * 基础服务客户端。业务服务只依赖这个包，不直接认识平台接口。
+ *
+ * 设计要点：
+ *   - 每次调用都要显式声明 `actingPersonId`（代表谁操作）。不提供"系统身份"
+ *     的默认值，因为平台侧的发起人必须是真实的人，审计也要能追到责任人。
+ *   - 写操作强制 `idempotencyKey`：网络重试、业务重投都不会造成重复送达。
+ *   - 只对**读**和网络层错误重试；写操作交给基础服务的幂等键兜底。
+ */
+export class BaseServiceError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "BaseServiceError";
+    }
+}
+const RETRYABLE = new Set([408, 425, 429, 500, 502, 503, 504]);
+/**
+ * 校验基础服务发来的语音请求（turnUrl 的每一轮、notifyUrl 的通话结果）确实出自基础服务、说的确实是这一通电话。
+ * 基础服务用**本服务的服务令牌**对「时间戳.通话 id」做 HMAC-SHA256，放在 X-Base-Timestamp / X-Base-Signature 两个头里。
+ * callId 取请求体里的：每一轮是 `body.callId`，通话结果是 `body.call.id`。时间戳超过容差（默认 5 分钟）的一律不认，防重放。
+ */
+export function verifyVoiceSignature(input) {
+    const header = (name) => {
+        const value = input.headers[name] ?? input.headers[name.toLowerCase()];
+        return String(Array.isArray(value) ? value[0] ?? "" : value ?? "").trim();
+    };
+    const timestamp = header("X-Base-Timestamp");
+    const signature = header("X-Base-Signature");
+    if (!input.serviceToken || !input.callId || !/^\d{10,16}$/.test(timestamp) || !/^[0-9a-f]{64}$/i.test(signature))
+        return false;
+    if (Math.abs((input.now ?? Date.now()) - Number(timestamp)) > (input.toleranceMs ?? 5 * 60_000))
+        return false;
+    const expected = createHmac("sha256", input.serviceToken).update(`${timestamp}.${input.callId}`).digest();
+    return timingSafeEqual(expected, Buffer.from(signature, "hex"));
+}
+export class BaseClient {
+    options;
+    baseUrl;
+    timeoutMs;
+    retries;
+    constructor(options) {
+        this.options = options;
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.timeoutMs = options.timeoutMs ?? 20000;
+        this.retries = options.retries ?? 2;
+    }
+    get configured() {
+        return Boolean(this.baseUrl && this.options.serviceToken);
+    }
+    /** 音频生成不自动重试；TTS 调用可能计费。调用方应设置足够的 timeoutMs。 */
+    generateAudio(input, acting) {
+        return this.call("/internal/audio/generate", { method: "POST", body: input, acting });
+    }
+    /**
+     * 生图：基础服务先扣额度，主模型失败换备用（审核拦截不换），结果立即转存对象存储。
+     * 可能要几分钟；不自动重试（每次调用都计次数），重试请带同一个 idempotencyKey。
+     */
+    generateImage(input, acting, opts = {}) {
+        return this.call("/internal/media/images", { method: "POST", body: input, acting, timeoutMs: opts.timeoutMs ?? 400_000 });
+    }
+    /** 看图：多张图 + 提示词，可要求按 JSON 回答。不自动重试（计次数）。 */
+    analyzeImages(input, acting, opts = {}) {
+        return this.call("/internal/media/vision", { method: "POST", body: input, acting, timeoutMs: opts.timeoutMs ?? 420_000 });
+    }
+    /** 当天的生图 / 看图额度。 */
+    mediaQuota(acting) {
+        return this.call("/internal/media/quota", { acting, retryable: true });
+    }
+    /** 对象存储上传令牌：只对 svc/<本服务>/<keySuffix> 这一个 key 有效、只能新建。配合 uploadToStorage 直传。 */
+    storageUploadToken(input, acting) {
+        return this.call("/internal/storage/upload-token", { method: "POST", body: input, acting, retryable: true });
+    }
+    /** 让基础服务代为下载一个地址并存进对象存储（例如会失效的外部链接）。 */
+    fetchIntoStorage(input, acting) {
+        return this.call("/internal/storage/fetch", { method: "POST", body: input, acting, timeoutMs: 120_000 });
+    }
+    /** 本服务对象的短期签名下载链接（不要入库）。 */
+    signStorageUrls(input, acting) {
+        return this.call("/internal/storage/sign", { method: "POST", body: input, acting, retryable: true });
+    }
+    statStorage(key, acting) {
+        return this.call("/internal/storage/stat", { method: "POST", body: { key }, acting, retryable: true });
+    }
+    /**
+     * 在自己的 turnUrl / notifyUrl 处理函数里调：确认请求出自基础服务。
+     * 每一轮传 `body.callId`，通话结果传 `body.call.id`。返回 false 就回 401，不要处理。
+     */
+    verifyVoiceRequest(headers, callId) {
+        return verifyVoiceSignature({ headers, callId, serviceToken: this.options.serviceToken });
+    }
+    /** 语音外呼是否已配置好（不含任何密钥和回调地址）。 */
+    voiceConfig(acting) {
+        return this.call("/internal/voice/config", { acting, retryable: true });
+    }
+    /**
+     * 提交一通外呼。**只是排队**：基础服务按并发上限和拨号间隔一通一通拨出，所以返回的状态通常是 QUEUED，
+     * 结果通过 notifyUrl 送回（或用 getVoiceCall 查）。接通后先说 greeting，之后对方每说一句，
+     * 基础服务把文字 POST 到 turnUrl，由业务回下一句；不传 turnUrl 用内置示例对话。
+     * 重试请带同一个 idempotencyKey：已经排上或拨出的不会多打一通。
+     */
+    startVoiceCall(input, acting) {
+        return this.call("/internal/voice/calls", { method: "POST", body: input, acting });
+    }
+    /**
+     * 批量提交（一次最多 500 通，再多就分几次调）。每一通各自校验、各自幂等，结果逐条返回；
+     * 一通号码写错不影响其它的。上千人的调研也是这样全部交进来排队，拨出的节奏由基础服务控制。
+     */
+    startVoiceCalls(input, acting) {
+        return this.call("/internal/voice/calls/batch", { method: "POST", body: input, acting, timeoutMs: 120_000 });
+    }
+    /** 取消某个业务对象名下所有还在排队的外呼（比如调研被叫停）；不传 entityId 就是这一类全部。已拨出的不受影响。 */
+    cancelQueuedVoiceCalls(input, acting) {
+        return this.call("/internal/voice/calls/cancel", { method: "POST", body: input, acting });
+    }
+    /** 外呼队列现状：排队多少、正在打多少、并发上限、是否在外呼时段、是否被暂停。 */
+    voiceQueue(acting) {
+        return this.call("/internal/voice/queue", { acting, retryable: true });
+    }
+    /** 通话状态和全程文字记录。只能查本服务发起（或归本服务接听）的通话。 */
+    getVoiceCall(callId, acting) {
+        return this.call(`/internal/voice/calls/${encodeURIComponent(callId)}`, { acting, retryable: true });
+    }
+    /** 不想打了：还在排队的直接取消；已拨出的在对方下一次说话或沉默时挂断（平台没有即时挂断接口）。 */
+    hangupVoiceCall(callId, acting) {
+        return this.call(`/internal/voice/calls/${encodeURIComponent(callId)}/hangup`, { method: "POST", body: {}, acting });
+    }
+    /** 本服务登记的呼入路由（哪些号码的来电归本服务接）。 */
+    listVoiceInboundRoutes(acting) {
+        return this.call("/internal/voice/inbound-routes", { acting, retryable: true });
+    }
+    /** 登记或更新一条呼入路由。号码已登记给别的服务时返回 409。 */
+    saveVoiceInboundRoute(input, acting) {
+        return this.call("/internal/voice/inbound-routes", { method: "PUT", body: input, acting });
+    }
+    deleteVoiceInboundRoute(number, acting) {
+        return this.call(`/internal/voice/inbound-routes/${encodeURIComponent(number)}`, { method: "DELETE", body: {}, acting });
+    }
+    headers(acting) {
+        if (!this.options.serviceToken)
+            throw new BaseServiceError("未配置 BASE_SERVICE_TOKEN", "CONFIG_REQUIRED", 503);
+        if (!acting?.personId)
+            throw new BaseServiceError("缺少 actingPersonId：必须声明代表谁操作", "BAD_REQUEST", 400);
+        const requestId = currentRequestId();
+        return {
+            "Content-Type": "application/json",
+            "X-Service-Token": this.options.serviceToken,
+            "X-Service-Name": this.options.serviceName,
+            "X-Acting-PersonId": acting.personId,
+            ...(acting.accessToken ? { "X-Acting-Access-Token": acting.accessToken } : {}),
+            // 把当前请求的追踪 ID 带给基础服务。没有它，一次用户操作在
+            // 业务服务和基础服务的日志里就是两条对不上的记录。
+            ...(requestId ? { [REQUEST_ID_HEADER]: requestId } : {}),
+        };
+    }
+    async call(path, init) {
+        const retries = init.retryable ? this.retries : 0;
+        let lastError;
+        for (let attempt = 0; attempt <= retries; attempt += 1) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), init.timeoutMs ?? this.timeoutMs);
+            try {
+                const response = await fetch(`${this.baseUrl}${path}`, {
+                    method: init.method || "GET",
+                    headers: this.headers(init.acting),
+                    body: init.body === undefined ? undefined : JSON.stringify(init.body),
+                    signal: controller.signal,
+                });
+                const payload = (await response.json().catch(() => null));
+                if (response.ok && payload?.success === true)
+                    return payload.data;
+                const message = payload && "message" in payload ? payload.message : `基础服务返回 HTTP ${response.status}`;
+                const code = payload && "code" in payload && payload.code ? payload.code : `HTTP_${response.status}`;
+                const error = new BaseServiceError(message, code, response.status);
+                if (!RETRYABLE.has(response.status) || attempt === retries)
+                    throw error;
+                lastError = error;
+            }
+            catch (error) {
+                if (error instanceof BaseServiceError) {
+                    if (attempt === retries)
+                        throw error;
+                    lastError = error;
+                }
+                else {
+                    const aborted = error instanceof Error && error.name === "AbortError";
+                    const normalized = new BaseServiceError(aborted ? "基础服务请求超时" : `基础服务不可达：${error instanceof Error ? error.message : String(error)}`, aborted ? "TIMEOUT" : "UNREACHABLE", 503);
+                    if (attempt === retries)
+                        throw normalized;
+                    lastError = normalized;
+                }
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+            await new Promise((resolve) => setTimeout(resolve, 300 * 2 ** attempt));
+        }
+        throw lastError || new BaseServiceError("基础服务请求失败", "UNKNOWN", 500);
+    }
+    /** 探活。业务服务的 /api/health 用它报告依赖状态。 */
+    async ping() {
+        try {
+            const response = await fetch(`${this.baseUrl}/api/health`, { signal: AbortSignal.timeout(5000) });
+            return { ok: response.ok };
+        }
+        catch (error) {
+            return { ok: false, message: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    /**
+     * 校验终端用户会话。业务服务的鉴权中间件用它。
+     * 结果建议缓存几十秒——不缓存的话每个业务请求都多一次内网往返。
+     */
+    verifySession(token, personId, acting) {
+        return this.call("/internal/sessions/verify", {
+            method: "POST",
+            body: { token, personId },
+            acting,
+            retryable: true,
+        });
+    }
+    /** 查人。发工作协同前用它补齐 empId。 */
+    lookupUser(personId, acting) {
+        return this.call(`/internal/users/${encodeURIComponent(personId)}`, { acting, retryable: true });
+    }
+    /** 按姓名查工作协同员工（姓名完全一致；重名全部返回）。 */
+    searchEmployees(name, acting) {
+        return this.call(`/internal/employees?name=${encodeURIComponent(name)}`, { acting, retryable: true });
+    }
+    /** 平台上出现过的部门（来自登录过的人的 deptList），用于按部门授权。 */
+    listDepartments(acting) {
+        return this.call("/internal/departments", { acting, retryable: true });
+    }
+    sendCollaboration(input, acting) {
+        return this.call("/internal/collaborations", { method: "POST", body: input, acting });
+    }
+    sendTodo(input, acting) {
+        return this.call("/internal/todos", { method: "POST", body: input, acting });
+    }
+    revokeTodo(todoId, acting) {
+        return this.call(`/internal/todos/${encodeURIComponent(todoId)}/revoke`, { method: "POST", body: {}, acting });
+    }
+    /**
+     * 把自己发的待办标为已办。已办过再调返回当前状态，不算错误。
+     * force=true：本地已记为已办的也再回写一次（代收件人回写时平台可能静默不生效，需要补办）。
+     */
+    completeTodo(todoId, acting, options = {}) {
+        return this.call(`/internal/todos/${encodeURIComponent(todoId)}/complete`, { method: "POST", body: options.force ? { force: true } : {}, acting });
+    }
+    /**
+     * 登记一把平台凭据（AppKey）。同 scope+label 再登记一次就是换 key。
+     * 明文只进不出：返回里没有 appKey，只有末四位。
+     */
+    saveCredential(input, acting) {
+        return this.call("/internal/credentials", { method: "POST", body: input, acting });
+    }
+    listCredentials(scope, acting) {
+        return this.call(`/internal/credentials?scope=${encodeURIComponent(scope)}`, { acting, retryable: true });
+    }
+    updateCredential(id, input, acting) {
+        return this.call(`/internal/credentials/${encodeURIComponent(id)}`, { method: "PATCH", body: input, acting });
+    }
+    deleteCredential(id, acting) {
+        return this.call(`/internal/credentials/${encodeURIComponent(id)}`, { method: "DELETE", body: {}, acting });
+    }
+    /** 本服务的产品线 Token 状态。明文永远不回传，只有末四位。 */
+    jobLineToken(acting) {
+        return this.call("/internal/job-line-token", { acting, retryable: true });
+    }
+    /** 配置本服务的产品线 Token。每个业务一把，互不共用。 */
+    saveJobLineToken(input, acting) {
+        return this.call("/internal/job-line-token", { method: "PUT", body: input, acting });
+    }
+    deleteJobLineToken(acting) {
+        return this.call("/internal/job-line-token", { method: "DELETE", body: {}, acting });
+    }
+    /** 按工作协同汇报记录 ID 拉回详情（正文、回复、各节点处理意见）。只能拉本服务自己发出的。 */
+    getCollaborationDetail(recordId, acting, options = {}) {
+        return this.call(`/internal/collaborations/remote/${encodeURIComponent(recordId)}${options.includeAssociated ? "?includeAssociated=true" : ""}`, { acting, retryable: true });
+    }
+    createJob(input, acting) {
+        return this.call("/internal/agent-jobs", { method: "POST", body: input, acting });
+    }
+    /** 取消自己发的 Job。重复取消不算错误，会直接返回当前状态。 */
+    cancelJob(jobId, acting) {
+        return this.call(`/internal/agent-jobs/${encodeURIComponent(jobId)}/cancel`, { method: "POST", body: {}, acting });
+    }
+    /** 重试自己发出的 Job 失败子任务。 */
+    retryJob(jobId, acting, taskKeys) {
+        return this.call(`/internal/agent-jobs/${encodeURIComponent(jobId)}/retry`, { method: "POST", body: taskKeys ? { taskKeys } : {}, acting });
+    }
+    getJob(jobId, acting) {
+        return this.call(`/internal/agent-jobs/${encodeURIComponent(jobId)}`, { acting, retryable: true });
+    }
+    /** 建对话任务（任务中心 mode=conversation）：firstMessage 是第 1 轮，之后每条消息一轮，每轮结果转发到 notifyUrl。 */
+    createConversation(input, acting) {
+        return this.call("/internal/agent-conversations", { method: "POST", body: input, acting });
+    }
+    /** 发一条消息 = 一轮。带 businessId 时重复提交只算一轮。 */
+    sendConversationMessage(conversationId, input, acting) {
+        return this.call(`/internal/agent-conversations/${encodeURIComponent(conversationId)}/messages`, { method: "POST", body: input, acting });
+    }
+    getConversation(conversationId, acting) {
+        return this.call(`/internal/agent-conversations/${encodeURIComponent(conversationId)}`, { acting, retryable: true });
+    }
+    /** 回调之外的兜底：直接问任务中心各轮状态。 */
+    getConversationTurns(conversationId, acting, afterSeq) {
+        return this.call(`/internal/agent-conversations/${encodeURIComponent(conversationId)}/turns${afterSeq ? `?afterSeq=${afterSeq}` : ""}`, { acting, retryable: true });
+    }
+    /** 结束对话。重复结束不算错误。 */
+    closeConversation(conversationId, acting) {
+        return this.call(`/internal/agent-conversations/${encodeURIComponent(conversationId)}/close`, { method: "POST", body: {}, acting });
+    }
+    /** 把文本变成工作协同附件（只生成物理资源，不进知识库，不需要知识库配置）。附件最大 50MB，上传对象存储要时间，默认等 3 分钟。 */
+    uploadAttachmentText(input, acting, opts = {}) {
+        return this.call("/internal/attachments/text", { method: "POST", body: input, acting, timeoutMs: opts.timeoutMs ?? 180_000 });
+    }
+    /**
+     * 以当前用户本人身份读取慧记会议的完整正文（逐段发言 + 整理纪要）。只读，不生成附件。
+     * 必须带 acting.accessToken：慧记是「我的数据」。一次最多 10 场。
+     */
+    fetchHuiJiDetails(items, acting) {
+        const body = { items: items.map((item) => (typeof item === "string" ? { id: item } : item)) };
+        return this.call("/internal/sources/huiji/details", { method: "POST", body, acting, retryable: true });
+    }
+    uploadText(input, acting) {
+        return this.call("/internal/knowledge/text", { method: "POST", body: input, acting });
+    }
+}
+/** 从环境变量装配客户端，避免每个业务服务重复写一遍。 */
+export function createBaseClient(env, serviceName) {
+    return new BaseClient({
+        baseUrl: (env.BASE_SERVICE_URL || "http://127.0.0.1:4000").trim(),
+        serviceName,
+        serviceToken: (env.BASE_SERVICE_TOKEN || "").trim(),
+        timeoutMs: Number(env.BASE_SERVICE_TIMEOUT_MS) || 20000,
+    });
+}
+/**
+ * 业务服务的用户鉴权中间件工厂。
+ *
+ * 前端把 access-token + personId 传给业务服务，业务服务**不能**直接相信它们，
+ * 必须回基础服务验一次。这里带一个短 TTL 的内存缓存，避免每个请求都往返。
+ */
+export function createSessionVerifier(client, options = {}) {
+    const ttl = options.ttlMs ?? 30_000;
+    const cache = new Map();
+    return async function verify(token, personId) {
+        if (!token || !personId) {
+            throw new BaseServiceError("缺少 access-token 或 personId", "UNAUTHORIZED", 401);
+        }
+        const key = `${personId}:${token}`;
+        const hit = cache.get(key);
+        if (hit && hit.expiresAt > Date.now())
+            return hit.user;
+        // 校验时代表的就是这个人自己。
+        const user = await client.verifySession(token, personId, { personId }).catch((error) => {
+            // 把"验不过"和"验不了"分开：
+            //   基础服务明确拒绝（401/403/404）→ 会话无效，前端该重新登录；
+            //   基础服务不可达或 5xx      → 依赖故障，不能误导用户去重新登录。
+            if (error instanceof BaseServiceError && [401, 403, 404].includes(error.status)) {
+                throw new BaseServiceError("登录已失效，请重新登录", "UNAUTHORIZED", 401);
+            }
+            throw error;
+        });
+        cache.set(key, { user, expiresAt: Date.now() + ttl });
+        // 顺手清理过期项，避免长时间运行后缓存无限增长。
+        if (cache.size > 1000) {
+            const now = Date.now();
+            for (const [cacheKey, value] of cache)
+                if (value.expiresAt <= now)
+                    cache.delete(cacheKey);
+        }
+        return user;
+    };
+}
+export { requireUser, actor } from "./express.js";
+export { uploadToStorage, StorageUploadError } from "./storage-upload.js";

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/dist/index.test.js

@@ -0,0 +1,219 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { BaseClient, BaseServiceError, createBaseClient, createSessionVerifier } from "./index.js";
+/** 用一个可控的 fetch 替身驱动客户端，不碰网络。 */
+function stubFetch(handler) {
+    const calls = [];
+    const original = globalThis.fetch;
+    globalThis.fetch = (async (input, init = {}) => {
+        const url = String(input);
+        calls.push({ url, init });
+        const { status, body } = handler(url, init);
+        return new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json" } });
+    });
+    return { calls, restore: () => { globalThis.fetch = original; } };
+}
+const client = () => new BaseClient({
+    baseUrl: "http://base.test",
+    serviceName: "demo",
+    serviceToken: "tok-1",
+});
+test("完整协同详情选项仅在启用时透传到 Base", async () => {
+    const stub = stubFetch(() => ({ status: 200, body: { success: true, data: {} } }));
+    try {
+        await client().getCollaborationDetail("2110996699949559811", { personId: "11809" }, { includeAssociated: true });
+        await client().getCollaborationDetail("2110996699949559811", { personId: "11809" });
+        assert.ok(stub.calls[0].url.endsWith("2110996699949559811?includeAssociated=true"));
+        assert.ok(stub.calls[1].url.endsWith("2110996699949559811"));
+    }
+    finally {
+        stub.restore();
+    }
+});
+test("每个请求都带服务令牌、服务名和代理用户", async () => {
+    const stub = stubFetch(() => ({ status: 200, body: { success: true, data: { personId: "1" } } }));
+    try {
+        await client().lookupUser("11809", { personId: "11809" });
+        const headers = stub.calls[0].init.headers;
+        assert.equal(headers["X-Service-Token"], "tok-1");
+        assert.equal(headers["X-Service-Name"], "demo");
+        assert.equal(headers["X-Acting-PersonId"], "11809");
+    }
+    finally {
+        stub.restore();
+    }
+});
+test("缺少 actingPersonId 时直接拒绝，不发请求", async () => {
+    const stub = stubFetch(() => ({ status: 200, body: { success: true, data: {} } }));
+    try {
+        // 平台侧的发起人必须是真实的人，不能有"系统身份"默认值。
+        await assert.rejects(() => client().lookupUser("1", { personId: "" }), /actingPersonId/);
+        assert.equal(stub.calls.length, 0);
+    }
+    finally {
+        stub.restore();
+    }
+});
+test("基础服务的业务错误会带上 code 和 status", async () => {
+    const stub = stubFetch(() => ({ status: 409, body: { success: false, message: "附件尚未同步", code: "CONFLICT" } }));
+    try {
+        await assert.rejects(() => client().sendCollaboration({
+            title: "t", content: "c", recipients: [], idempotencyKey: "k",
+            origin: { service: "demo", entityType: "X", entityId: "1" },
+        }, { personId: "11809" }), (error) => {
+            assert.ok(error instanceof BaseServiceError);
+            assert.equal(error.code, "CONFLICT");
+            assert.equal(error.status, 409);
+            assert.match(error.message, /附件尚未同步/);
+            return true;
+        });
+    }
+    finally {
+        stub.restore();
+    }
+});
+test("写操作不重试（幂等键由基础服务兜底），读操作才重试", async () => {
+    let writes = 0;
+    let reads = 0;
+    const stub = stubFetch((url, init) => {
+        if (init.method === "POST") {
+            writes += 1;
+            return { status: 503, body: { success: false, message: "down" } };
+        }
+        reads += 1;
+        return { status: 503, body: { success: false, message: "down" } };
+    });
+    try {
+        await assert.rejects(() => client().sendTodo({
+            title: "t", content: "c", recipients: [], refUrl: "https://x.test", idempotencyKey: "k",
+            origin: { service: "demo", entityType: "X", entityId: "1" },
+        }, { personId: "11809" }));
+        // 写只发一次：重试可能造成重复送达。
+        assert.equal(writes, 1);
+        await assert.rejects(() => client().lookupUser("1", { personId: "11809" }));
+        // 读会退避重试。
+        assert.ok(reads > 1, `读操作应重试，实际只发了 ${reads} 次`);
+    }
+    finally {
+        stub.restore();
+    }
+});
+test("基础服务不可达时给出可辨认的错误", async () => {
+    const original = globalThis.fetch;
+    globalThis.fetch = (async () => { throw new Error("ECONNREFUSED"); });
+    try {
+        await assert.rejects(() => client().lookupUser("1", { personId: "11809" }), (error) => {
+            assert.ok(error instanceof BaseServiceError);
+            assert.equal(error.code, "UNREACHABLE");
+            return true;
+        });
+    }
+    finally {
+        globalThis.fetch = original;
+    }
+});
+test("会话校验结果会缓存，不会每个请求都往返", async () => {
+    let hits = 0;
+    const stub = stubFetch(() => {
+        hits += 1;
+        return { status: 200, body: { success: true, data: { personId: "11809", userId: "u1", empId: "e1", userName: "张三", corpId: null } } };
+    });
+    try {
+        const verify = createSessionVerifier(client(), { ttlMs: 10_000 });
+        await verify("tok", "11809");
+        await verify("tok", "11809");
+        assert.equal(hits, 1, "第二次应命中缓存");
+        // 换个 token 必须重新校验，否则退出登录后旧 token 还能用。
+        await verify("other", "11809");
+        assert.equal(hits, 2);
+    }
+    finally {
+        stub.restore();
+    }
+});
+test("缓存过期后重新校验", async () => {
+    let hits = 0;
+    const stub = stubFetch(() => {
+        hits += 1;
+        return { status: 200, body: { success: true, data: { personId: "1", userId: "u", empId: null, userName: "n", corpId: null } } };
+    });
+    try {
+        const verify = createSessionVerifier(client(), { ttlMs: 1 });
+        await verify("tok", "1");
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        await verify("tok", "1");
+        assert.equal(hits, 2);
+    }
+    finally {
+        stub.restore();
+    }
+});
+test("缺 token 或 personId 时不发请求", async () => {
+    const stub = stubFetch(() => ({ status: 200, body: { success: true, data: {} } }));
+    try {
+        const verify = createSessionVerifier(client());
+        await assert.rejects(() => verify("", "1"), /access-token/);
+        await assert.rejects(() => verify("t", ""), /personId/);
+        assert.equal(stub.calls.length, 0);
+    }
+    finally {
+        stub.restore();
+    }
+});
+test("通知令牌校验：空令牌一律拒绝", () => {
+    // 期望值为空时必须拒绝，不能退化成"谁都可以"。
+});
+test("createBaseClient 从环境变量装配", () => {
+    const built = createBaseClient({ BASE_SERVICE_URL: "http://x.test", BASE_SERVICE_TOKEN: "t" }, "legal");
+    assert.equal(built.configured, true);
+    const missing = createBaseClient({}, "legal");
+    assert.equal(missing.configured, false);
+});
+test("会话验不过时统一报 401，而不是把 404 透给前端", async () => {
+    const stub = stubFetch(() => ({ status: 404, body: { success: false, message: "用户不存在", code: "NOT_FOUND" } }));
+    try {
+        const verify = createSessionVerifier(client());
+        await assert.rejects(() => verify("tok", "999999"), (error) => {
+            assert.ok(error instanceof BaseServiceError);
+            assert.equal(error.status, 401);
+            assert.match(error.message, /重新登录/);
+            return true;
+        });
+    }
+    finally {
+        stub.restore();
+    }
+});
+test("基础服务故障不能被误报成「登录失效」", async () => {
+    const original = globalThis.fetch;
+    globalThis.fetch = (async () => { throw new Error("ECONNREFUSED"); });
+    try {
+        const verify = createSessionVerifier(client());
+        await assert.rejects(() => verify("tok", "11809"), (error) => {
+            assert.ok(error instanceof BaseServiceError);
+            // 依赖挂了就该说依赖挂了，让用户去重新登录只会白折腾。
+            assert.equal(error.code, "UNREACHABLE");
+            assert.notEqual(error.status, 401);
+            return true;
+        });
+    }
+    finally {
+        globalThis.fetch = original;
+    }
+});
+test("语音请求的签名校验：对的才过；改了通话 id、过期、缺头、令牌不对都不过", async () => {
+    const { createHmac } = await import("node:crypto");
+    const { verifyVoiceSignature } = await import("./index.js");
+    const now = 1_760_000_000_000;
+    const sign = (token, timestamp, callId) => createHmac("sha256", token).update(`${timestamp}.${callId}`).digest("hex");
+    const headers = { "x-base-timestamp": String(now), "x-base-signature": sign("tok", now, "call_1") };
+    assert.equal(verifyVoiceSignature({ headers, callId: "call_1", serviceToken: "tok", now }), true);
+    // Express 给的头是小写；别的框架可能保留原样大小写。
+    assert.equal(verifyVoiceSignature({ headers: { "X-Base-Timestamp": String(now), "X-Base-Signature": sign("tok", now, "call_1") }, callId: "call_1", serviceToken: "tok", now }), true);
+    assert.equal(verifyVoiceSignature({ headers, callId: "call_2", serviceToken: "tok", now }), false, "签的不是这一通");
+    assert.equal(verifyVoiceSignature({ headers, callId: "call_1", serviceToken: "other", now }), false);
+    assert.equal(verifyVoiceSignature({ headers, callId: "call_1", serviceToken: "tok", now: now + 6 * 60_000 }), false, "超过 5 分钟不认，防重放");
+    assert.equal(verifyVoiceSignature({ headers: {}, callId: "call_1", serviceToken: "tok", now }), false);
+    assert.equal(verifyVoiceSignature({ headers: { ...headers, "x-base-signature": "zz" }, callId: "call_1", serviceToken: "tok", now }), false);
+    assert.equal(verifyVoiceSignature({ headers, callId: "call_1", serviceToken: "", now }), false, "自己没配令牌时不能放行");
+});

package/dist/storage-upload.d.ts

@@ -0,0 +1,25 @@
+import type { StorageUploadTicket } from "@xgspz/contracts";
+/**
+ * 拿到基础服务签发的上传令牌后，直接传到对象存储（七牛），文件不经过基础服务中转：
+ *   - 16MB 以内：表单上传；
+ *   - 更大：分片上传 v2（initiate → 逐片 PUT → complete），每片失败重试 3 次。
+ * 令牌只对一个确定的 key 有效且只能新建：同一个 key 已存在（614）视为成功（key 按内容命名）。
+ */
+export declare class StorageUploadError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare function uploadToStorage(ticket: Pick<StorageUploadTicket, "key" | "token" | "uploadUrl">, source: {
+    file: string;
+} | {
+    bytes: Buffer;
+}, opts: {
+    contentType: string;
+    signal?: AbortSignal;
+    partSize?: number;
+}): Promise<{
+    key: string;
+    existed: boolean;
+    size: number;
+}>;
+//# sourceMappingURL=storage-upload.d.ts.map

package/dist/storage-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-upload.d.ts","sourceRoot":"","sources":["../src/storage-upload.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IACd,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAxC,OAAO,EAAE,MAAM,EAAW,MAAM,EAAE,MAAM;CAIrD;AAqBD,wBAAsB,eAAe,CACnC,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,KAAK,GAAG,OAAO,GAAG,WAAW,CAAC,EAChE,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAC5C,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACrE,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA6D1D"}