@jzwd/vnd-design 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,260 @@
-# Temporary Holding Version
+# Vnd design（简称 Vnd）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+公司业务组件库。**Vnd design 继承 antd 的全部组件**：业务方只需从一个入口引入，即可同时拿到 antd 组件与 Vnd 自有业务组件，不必再从 antd 单独引一次。
+
+当前已封装的业务模块：**文件中心（FileCenter）**。
+
+## 安装
+
+```bash
+npm install @jzwd/vnd-design
+```
+
+对等依赖（业务项目需自行安装）：`react >= 17`、`antd >= 5`、`@ant-design/icons >= 5`、`dayjs >= 1.11`。
+
+## 一个入口，拿到 antd 全部组件 + Vnd 业务组件
+
+`@jzwd/vnd-design` 的主入口已 `export * from 'antd'`，所以 antd 的组件、类型可以直接从这里引入：
+
+```tsx
+// antd 组件：Vnd design 已全量再导出，不需要再 from 'antd'
+import { Button, Table, Form, message, ConfigProvider } from '@jzwd/vnd-design';
+
+// Vnd 自有业务组件：同一个入口
+import { FcUpload, FcImage, FcFileList } from '@jzwd/vnd-design';
+```
+
+> 移动端子路径 `@jzwd/vnd-design/mobile` 提供基于 antd-mobile 的业务组件。
+> 若也需要「一个入口拿到 antd-mobile 全部组件」，在该子入口加一行 `export * from 'antd-mobile'` 即可。
+
+## 文件中心模块
+
+对应《文件中心需求文档》第九章「业务组件库」的对接约定：业务项目**零接口开发**接入文件中心，只需把项目注册后拿到的 AppKey 传给组件，换令牌、上传、秒传、进度、失败重试、私有签名刷新、引用登记全部由组件内部完成。
+
+### 第一步：传入 appKey
+
+无需在应用根部包任何 Provider，直接在组件上传 `appKey` 即可；`baseUrl` 已内置默认值 `https://upload.yydslgd.cn`，一般不用传：
+
+```tsx
+import { FcUpload } from '@jzwd/vnd-design';
+
+// 最简：只传 appKey
+<FcUpload appKey="你的项目AppKey" listType="picture-card" />;
+
+// 特殊环境（联调 / 私有化部署）才需覆盖 baseUrl
+<FcUpload appKey="你的项目AppKey" baseUrl="https://upload.yydslgd.cn" />;
+```
+
+> 令牌获取默认走文件中心 OPEN-1 接口（AppKey 换令牌，组件内部自动缓存与刷新）。
+> 如果后续服务端要求更高安全性（AppKey + AppSecret 在业务服务端换令牌），
+> 可通过组件的 `getToken` prop 覆盖，其他代码不用改：
+>
+> ```tsx
+> <FcUpload
+>   appKey="你的项目AppKey"
+>   getToken={appKey => fetch(`/api/my-server/fc-token?appKey=${appKey}`).then(r => r.json())}
+> />
+> ```
+
+### FcUpload 上传组件
+
+三种形态：图片卡片墙（默认）、文件列表、拖拽上传。
+
+```tsx
+import { Form } from 'antd';
+import { FcUpload } from '@jzwd/vnd-design';
+
+// 图片卡片墙（头像、商品图场景），可直接放进 antd Form
+<Form.Item name="images" label="商品图">
+  <FcUpload
+    appKey="你的项目AppKey"     // 项目 AppKey（baseUrl 不传则走内置默认地址）
+    listType="picture-card"
+    maxCount={5}
+    maxSizeMB={20}
+    accept="image/*"
+    compress                      // 上传前自动压缩图片
+    bizType="goodsImage"          // 业务标签
+    bizId={goodsId}               // 传了 bizId 时，上传成功自动登记业务引用（OPEN-12）
+    bizUrl={`/goods/${goodsId}`}
+  />
+</Form.Item>
+
+// 文件列表 + 拖拽形态（附件、文档场景）
+<FcUpload appKey="你的项目AppKey" listType="text" drag multiple maxCount={10} buttonText="上传附件" />
+```
+
+主要能力：
+
+| 能力         | 说明                                                                                                                                           |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| 秒传         | 上传前算 MD5 调 OPEN-4，同文件已存在时直接返回，不传实体                                                                                       |
+| 分片上传     | 超过 10MB 自动走 OPEN-5 分片（初始化 → 逐片 → 合并），支持断点续传                                                                             |
+| 失败重试     | 普通上传与每个分片自动重试 2 次                                                                                                                |
+| 进度展示     | MD5 校验占 10%、上传占 90%，卡片形态有环形进度、列表形态有进度条                                                                               |
+| 图片压缩     | `compress` 开启，gif/svg 与小于 100KB 的图片自动跳过                                                                                           |
+| 取消上传     | 上传中点删除即中断请求                                                                                                                         |
+| 引用溯源删除 | `deleteOnRemove` 开启后，删除时若文件存在业务引用，弹窗展示全部引用（项目 / 业务类型 / 业务记录 / 可点击链接），勾选「我已知晓影响范围」才能删 |
+| 复制 URL     | 上传成功后悬浮卡片或行操作里一键复制                                                                                                           |
+
+`value` / `onChange` 与 antd Form 完全兼容，文件项上额外带 `fileId`（文件中心文件 ID）与 `fileInfo`（完整元数据），业务表里存哪个都行。
+
+### FcImage 图片回显组件
+
+```tsx
+import { FcImage } from '@jzwd/vnd-design';
+
+// 业务表存的是文件 ID：组件自动调 OPEN-9 换取可访问 URL
+<FcImage appKey="你的项目AppKey" fileId={record.avatarFileId} width={80} height={80} />
+
+// 业务表存的是 URL：直接回显
+<FcImage appKey="你的项目AppKey" src={record.avatarUrl} width={80} />
+```
+
+私有文件签名 URL 过期导致加载失败时，自动调 OPEN-11 刷新签名并重试一次，业务方无感。其余属性与 antd `Image` 一致（预览、占位、圆角等直接透传）。
+
+### FcFileList 文件列表组件
+
+对应需求 3.2.3 的核心页面能力，适合嵌到业务系统内部管理页：
+
+```tsx
+import { FcFileList } from '@jzwd/vnd-design';
+
+<FcFileList
+  appKey="你的项目AppKey"
+  bizTypes={[
+    { label: '商品图', value: 'goodsImage' },
+    { label: '内容图', value: 'contentImage' }
+  ]}
+  defaultView="table"
+/>;
+```
+
+- 查询本项目文件（OPEN-7），支持名称模糊、业务标签、文件类型、时间范围筛选，分页；
+- **表格 / 图片宫格**两种视图切换；
+- 行操作：预览（图片灯箱 / 视频播放 / PDF 内嵌）、复制 URL、下载、刷新签名（私有文件）、删除；
+- 删除时展示该文件的全部业务引用（OPEN-14），勾选确认后才能删除（OPEN-10）。
+
+### uploadFile 无界面上传函数
+
+需要完全自定义 UI 时，可直接使用上传函数，能力与 `FcUpload` 内部一致：
+
+```tsx
+import { uploadFile } from '@jzwd/vnd-design';
+
+const fileInfo = await uploadFile({
+  file, // File 对象
+  appKey: '你的AppKey', // baseUrl 不传则走内置默认地址
+  bizType: 'goodsImage',
+  bizInfo: { bizType: 'goodsImage', bizId: '1001', bizUrl: '/goods/1001' },
+  compress: true,
+  onProgress: ({ percent, stage }) => console.log(stage, percent),
+  signal: controller.signal // 可取消
+});
+console.log(fileInfo.id, fileInfo.url);
+```
+
+## 目录结构
+
+```
+src/
+├── index.ts                        # 组件库总入口
+└── file-center/                    # 文件中心模块
+    ├── context.ts                  # 组件 props → 请求上下文解析（内置 baseUrl 默认值）
+    ├── types.ts                    # 类型契约（按需求文档预定义）
+    ├── upload.ts                   # 上传编排：压缩→MD5→秒传→分片/普通→登记引用
+    ├── api/                        # 接口契约层
+    │   ├── endpoints.ts            # OPEN-1~14 接口路径表（服务端定稿后只改这里）
+    │   ├── error.ts                # FcError 错误类
+    │   ├── token.ts                # 令牌缓存/并发去重/可插拔适配器
+    │   ├── request.ts              # JSON 请求（401 自动刷新重试）
+    │   └── index.ts                # 各开放接口函数 + 表单上传（XHR 带进度）
+    ├── components/
+    │   ├── FcUpload/               # 上传组件
+    │   ├── FcImage/                # 回显组件
+    │   └── FcFileList/             # 文件列表组件
+    └── utils/                      # MD5、图片压缩、复制/下载/重试等工具
+```
+
+## 开发
+
+```bash
+npm install       # 安装依赖
+npm run typecheck # 类型检查
+npm run build     # 构建产物到 dist（ESM + 类型声明）
+```
+
+## 移动端组件（H5）
+
+同一包内通过子路径提供基于 **antd-mobile** 的移动端组件，与 PC 端共用同一套接口契约与上传编排（压缩 → MD5 → 秒传 → 分片/普通上传 → 引用登记）：
+
+```bash
+# 移动端额外需要安装（纯 PC 项目不用装，已声明为可选对等依赖）
+npm install antd-mobile antd-mobile-icons
+```
+
+```tsx
+import { FcUpload, FcImage } from '@jzwd/vnd-design/mobile';
+
+const APP_KEY = '你的AppKey';
+
+{
+  /* 图片宫格：支持调起相机、压缩、引用自动登记 */
+}
+<FcUpload appKey={APP_KEY} listType="picture-card" capture compress bizType="goodsImage" bizId="1001" />;
+{
+  /* 文件列表形态 */
+}
+<FcUpload appKey={APP_KEY} listType="text" multiple deleteOnRemove />;
+{
+  /* 按文件 ID 回显，点按全屏预览，签名失效自动刷新 */
+}
+<FcImage appKey={APP_KEY} fileId="文件ID" width={72} height={72} />;
+```
+
+移动端与 PC 端差异点：`capture` 属性可直接调起相机；图片预览用 antd-mobile 的全屏预览器；引用溯源确认弹窗为移动端交互（底部勾选知晓后删除）。
+
+## 本地联调（不发包即可在浏览器里跑通全链路）
+
+仓库内置了一个**模拟文件中心服务端**和**演示应用**，不依赖真实后端、不依赖发布：
+
+```bash
+npm run mock        # 终端一：启动模拟文件中心（端口 4000，实现 OPEN-1~14 全部契约）
+npm run playground  # 终端二：启动演示应用（端口 5173）
+```
+
+打开 http://localhost:5173 即可体验三个组件的全部形态；http://localhost:5173/mobile.html 是移动端演示页（手机框内展示移动端组件）。演示应用通过别名直接引用组件库**源码**（见 `vite.playground.config.ts`），改 `src` 下任何组件代码都会即时热更新，联调效率等同在业务项目里改代码。
+
+- 模拟服务端的数据存在 `mock/storage/`（已加入忽略清单），重启不丢失，想清空直接删该目录；
+- 验证分片上传：选一个大于 10MB 的文件；验证秒传：同一文件传第二次；验证引用溯源删除：删除卡片墙传上去的文件（上传时已自动登记演示引用）。
+
+### 在真实业务项目里本地引用（发包前的过渡方案）
+
+**方式一（推荐，Vite 业务项目）**：在业务项目的 Vite 配置里加别名，直接指向组件库源码或 dist：
+
+```ts
+// 业务项目 vite.config.ts
+resolve: {
+  alias: {
+    '@jzwd/vnd-design': '/路径/到/busComponent/src/index.ts',
+  },
+  dedupe: ['react', 'react-dom', 'antd'],
+}
+```
+
+**方式二（npm link，不限构建工具）**：
+
+```bash
+# 组件库目录执行（先构建一次）
+npm run build && npm link
+# 业务项目目录执行
+npm link @jzwd/vnd-design
+```
+
+注意：npm link 会让组件库解析到自己目录下的依赖副本，可能出现 React 双实例报错（hooks 报错）；遇此情况在业务项目里把 react/react-dom 也做别名或 dedupe 指向业务项目自己的副本即可。
+
+## 与服务端的对接说明
+
+文件中心服务端（FileCenterApi）尚在开发中。本库按需求文档 v1.1 预先定义了接口契约
+（`src/file-center/types.ts` 与 `src/file-center/api/endpoints.ts`），
+服务端实现时按此契约开发即可无缝对接；若有出入，只需调整 `api` 目录内少量代码，
+组件调用方不受影响。

package/dist/file-center/api/endpoints.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 文件中心开放接口路径表（对应需求文档 OPEN-1 ~ OPEN-14）
+ * 服务端接口定稿后如有出入，仅需修改此文件。
+ */
+export declare const FC_ENDPOINTS: {
+    /** OPEN-1 获取访问令牌 */
+    readonly auth: "/open/auth/token";
+    /** OPEN-2 普通上传 */
+    readonly upload: "/open/files/upload";
+    /** OPEN-3 批量上传 */
+    readonly uploadBatch: "/open/files/upload-batch";
+    /** OPEN-4 秒传校验 */
+    readonly instant: "/open/files/instant";
+    /** OPEN-5 分片上传：初始化 */
+    readonly chunkInit: "/open/files/chunk/init";
+    /** OPEN-5 分片上传：传分片 */
+    readonly chunkUpload: "/open/files/chunk/upload";
+    /** OPEN-5 分片上传：合并 */
+    readonly chunkMerge: "/open/files/chunk/merge";
+    /** OPEN-7 文件列表 */
+    readonly list: "/open/files";
+    /** OPEN-8 文件详情（拼接 /{id}） */
+    readonly detail: "/open/files";
+    /** OPEN-9 批量取 URL */
+    readonly urls: "/open/files/urls";
+    /** OPEN-10 删除文件（拼接 /{id}） */
+    readonly remove: "/open/files";
+    /** OPEN-11 刷新签名（拼接 /{id}/refresh-sign） */
+    readonly refreshSign: "/open/files";
+    /** OPEN-12 登记引用 */
+    readonly refAdd: "/open/references";
+    /** OPEN-13 解除引用 */
+    readonly refRemove: "/open/references";
+    /** OPEN-14 查询文件引用（拼接 /{fileId}） */
+    readonly refList: "/open/references";
+};
+/** 默认大文件分片阈值：10MB */
+export declare const DEFAULT_CHUNK_THRESHOLD: number;
+/** 默认分片大小：5MB */
+export declare const DEFAULT_CHUNK_SIZE: number;
+/** 令牌过期提前量（毫秒）：到期前 1 分钟即视为过期 */
+export declare const TOKEN_EXPIRE_AHEAD: number;

package/dist/file-center/api/endpoints.js

@@ -0,0 +1,45 @@
+/**
+ * 文件中心开放接口路径表（对应需求文档 OPEN-1 ~ OPEN-14）
+ * 服务端接口定稿后如有出入，仅需修改此文件。
+ */
+export var FC_ENDPOINTS = {
+  /** OPEN-1 获取访问令牌 */
+  auth: '/open/auth/token',
+  /** OPEN-2 普通上传 */
+  upload: '/open/files/upload',
+  /** OPEN-3 批量上传 */
+  uploadBatch: '/open/files/upload-batch',
+  /** OPEN-4 秒传校验 */
+  instant: '/open/files/instant',
+  /** OPEN-5 分片上传：初始化 */
+  chunkInit: '/open/files/chunk/init',
+  /** OPEN-5 分片上传：传分片 */
+  chunkUpload: '/open/files/chunk/upload',
+  /** OPEN-5 分片上传：合并 */
+  chunkMerge: '/open/files/chunk/merge',
+  /** OPEN-7 文件列表 */
+  list: '/open/files',
+  /** OPEN-8 文件详情（拼接 /{id}） */
+  detail: '/open/files',
+  /** OPEN-9 批量取 URL */
+  urls: '/open/files/urls',
+  /** OPEN-10 删除文件（拼接 /{id}） */
+  remove: '/open/files',
+  /** OPEN-11 刷新签名（拼接 /{id}/refresh-sign） */
+  refreshSign: '/open/files',
+  /** OPEN-12 登记引用 */
+  refAdd: '/open/references',
+  /** OPEN-13 解除引用 */
+  refRemove: '/open/references',
+  /** OPEN-14 查询文件引用（拼接 /{fileId}） */
+  refList: '/open/references'
+};
+
+/** 默认大文件分片阈值：10MB */
+export var DEFAULT_CHUNK_THRESHOLD = 10 * 1024 * 1024;
+
+/** 默认分片大小：5MB */
+export var DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024;
+
+/** 令牌过期提前量（毫秒）：到期前 1 分钟即视为过期 */
+export var TOKEN_EXPIRE_AHEAD = 60 * 1000;

package/dist/file-center/api/error.d.ts

@@ -0,0 +1,6 @@
+/** 文件中心接口/上传过程错误 */
+export declare class FcError extends Error {
+    /** 业务错误码；HTTP 层错误时为 HTTP 状态码；主动取消时为 'ABORT' */
+    code: number | string;
+    constructor(message: string, code?: number | string);
+}

package/dist/file-center/api/error.js

@@ -0,0 +1,34 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+function _defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, _toPropertyKey(descriptor.key), descriptor); } }
+function _createClass(Constructor, protoProps, staticProps) { if (protoProps) _defineProperties(Constructor.prototype, protoProps); if (staticProps) _defineProperties(Constructor, staticProps); Object.defineProperty(Constructor, "prototype", { writable: false }); return Constructor; }
+function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
+function _inherits(subClass, superClass) { if (typeof superClass !== "function" && superClass !== null) { throw new TypeError("Super expression must either be null or a function"); } subClass.prototype = Object.create(superClass && superClass.prototype, { constructor: { value: subClass, writable: true, configurable: true } }); Object.defineProperty(subClass, "prototype", { writable: false }); if (superClass) _setPrototypeOf(subClass, superClass); }
+function _createSuper(Derived) { var hasNativeReflectConstruct = _isNativeReflectConstruct(); return function _createSuperInternal() { var Super = _getPrototypeOf(Derived), result; if (hasNativeReflectConstruct) { var NewTarget = _getPrototypeOf(this).constructor; result = Reflect.construct(Super, arguments, NewTarget); } else { result = Super.apply(this, arguments); } return _possibleConstructorReturn(this, result); }; }
+function _possibleConstructorReturn(self, call) { if (call && (_typeof(call) === "object" || typeof call === "function")) { return call; } else if (call !== void 0) { throw new TypeError("Derived constructors may only return object or undefined"); } return _assertThisInitialized(self); }
+function _assertThisInitialized(self) { if (self === void 0) { throw new ReferenceError("this hasn't been initialised - super() hasn't been called"); } return self; }
+function _wrapNativeSuper(Class) { var _cache = typeof Map === "function" ? new Map() : undefined; _wrapNativeSuper = function _wrapNativeSuper(Class) { if (Class === null || !_isNativeFunction(Class)) return Class; if (typeof Class !== "function") { throw new TypeError("Super expression must either be null or a function"); } if (typeof _cache !== "undefined") { if (_cache.has(Class)) return _cache.get(Class); _cache.set(Class, Wrapper); } function Wrapper() { return _construct(Class, arguments, _getPrototypeOf(this).constructor); } Wrapper.prototype = Object.create(Class.prototype, { constructor: { value: Wrapper, enumerable: false, writable: true, configurable: true } }); return _setPrototypeOf(Wrapper, Class); }; return _wrapNativeSuper(Class); }
+function _construct(Parent, args, Class) { if (_isNativeReflectConstruct()) { _construct = Reflect.construct.bind(); } else { _construct = function _construct(Parent, args, Class) { var a = [null]; a.push.apply(a, args); var Constructor = Function.bind.apply(Parent, a); var instance = new Constructor(); if (Class) _setPrototypeOf(instance, Class.prototype); return instance; }; } return _construct.apply(null, arguments); }
+function _isNativeReflectConstruct() { if (typeof Reflect === "undefined" || !Reflect.construct) return false; if (Reflect.construct.sham) return false; if (typeof Proxy === "function") return true; try { Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {})); return true; } catch (e) { return false; } }
+function _isNativeFunction(fn) { try { return Function.toString.call(fn).indexOf("[native code]") !== -1; } catch (e) { return typeof fn === "function"; } }
+function _setPrototypeOf(o, p) { _setPrototypeOf = Object.setPrototypeOf ? Object.setPrototypeOf.bind() : function _setPrototypeOf(o, p) { o.__proto__ = p; return o; }; return _setPrototypeOf(o, p); }
+function _getPrototypeOf(o) { _getPrototypeOf = Object.setPrototypeOf ? Object.getPrototypeOf.bind() : function _getPrototypeOf(o) { return o.__proto__ || Object.getPrototypeOf(o); }; return _getPrototypeOf(o); }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+/** 文件中心接口/上传过程错误 */
+export var FcError = /*#__PURE__*/function (_Error) {
+  _inherits(FcError, _Error);
+  var _super = _createSuper(FcError);
+  function FcError(message) {
+    var _this;
+    var code = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : -1;
+    _classCallCheck(this, FcError);
+    _this = _super.call(this, message);
+    /** 业务错误码；HTTP 层错误时为 HTTP 状态码；主动取消时为 'ABORT' */
+    _defineProperty(_assertThisInitialized(_this), "code", void 0);
+    _this.name = 'FcError';
+    _this.code = code;
+    return _this;
+  }
+  return _createClass(FcError);
+}( /*#__PURE__*/_wrapNativeSuper(Error));

package/dist/file-center/api/index.d.ts

@@ -0,0 +1,64 @@
+import type { FcRequestContext } from './request';
+import type { FcBizInfo, FcDeleteResult, FcFileListQuery, FcFileInfo, FcFileReference, FcInstantUploadResult, FcPageResult } from '../types';
+export { FC_ENDPOINTS, DEFAULT_CHUNK_SIZE, DEFAULT_CHUNK_THRESHOLD } from './endpoints';
+export { FcError } from './error';
+export { fcRequest } from './request';
+export type { FcRequestContext } from './request';
+export { ensureToken, invalidateToken } from './token';
+/** 带表单体的请求（上传类接口共用）：自动携带令牌，401 刷新重试一次 */
+export declare function fcFormRequest<T>(ctx: FcRequestContext, path: string, form: FormData, options?: {
+    signal?: AbortSignal;
+    onProgress?: (percent: number) => void;
+}): Promise<T>;
+export declare function checkInstantUpload(ctx: FcRequestContext, params: {
+    md5: string;
+    name: string;
+    size: number;
+    bizType?: string;
+}): Promise<FcInstantUploadResult>;
+export declare function initChunkUpload(ctx: FcRequestContext, params: {
+    md5: string;
+    name: string;
+    size: number;
+    totalParts: number;
+    bizType?: string;
+}): Promise<{
+    uploadId: string;
+    chunkSize?: number;
+    doneParts?: number[];
+}>;
+export declare function uploadChunk(ctx: FcRequestContext, params: {
+    uploadId: string;
+    partNumber: number;
+    blob: Blob;
+}, options?: {
+    signal?: AbortSignal;
+    onProgress?: (percent: number) => void;
+}): Promise<void>;
+export declare function mergeChunkUpload(ctx: FcRequestContext, params: {
+    uploadId: string;
+}): Promise<FcFileInfo>;
+export declare function fetchFileList(ctx: FcRequestContext, query?: FcFileListQuery): Promise<FcPageResult<FcFileInfo>>;
+export declare function fetchFileDetail(ctx: FcRequestContext, fileId: string): Promise<FcFileInfo>;
+/** OPEN-9 批量取可访问 URL（私有文件返回带签名的临时 URL），回显图片核心接口 */
+export declare function fetchFileUrls(ctx: FcRequestContext, fileIds: string[]): Promise<Record<string, string>>;
+/** OPEN-10 删除文件（逻辑删除）；存在业务引用时返回引用列表要求二次确认 */
+export declare function deleteFile(ctx: FcRequestContext, fileId: string, options?: {
+    force?: boolean;
+}): Promise<FcDeleteResult>;
+/** OPEN-11 刷新私有文件签名 URL */
+export declare function refreshFileSign(ctx: FcRequestContext, fileId: string): Promise<{
+    url: string;
+}>;
+/** OPEN-12 登记引用（支持批量） */
+export declare function addReferences(ctx: FcRequestContext, refs: Array<FcBizInfo & {
+    fileId: string;
+}>): Promise<void>;
+/** OPEN-13 解除引用 */
+export declare function removeReference(ctx: FcRequestContext, params: {
+    fileId: string;
+    bizType: string;
+    bizId: string;
+}): Promise<void>;
+/** OPEN-14 查询文件的全部引用记录 */
+export declare function fetchReferences(ctx: FcRequestContext, fileId: string): Promise<FcFileReference[]>;