设计取舍与边界

本页如实记录 SDK 的关键设计决策——包括不那么「完美」的部分，接入前请先了解。

包名与品牌不同名

仓库品牌为 partake，但 @partake npm scope 已被第三方占用，发布名定为 @pidaqing/uploader。repository / homepage 元数据均指向 gitee.com/pidaqing/partake，命名冲突不影响包内容与后续升级路径。

源码分发（v1.0 前）

v1.0 前 tarball 携带 TypeScript 源码（exports 直接指向 .ts）：

• 收益：声明能力天然完整、源码可读、无构建产物与源码漂移；
• 代价：需要带 TS 支持的打包器（Vite / webpack 5 / esbuild）。

v1.0 将切换为编译产物 + 类型声明双通道。

适配层模式：Vue 与 React 同构、core 零依赖

• 框架无关 core（PartakeUploadManager + UploadEngine）不依赖任何框架；
• Vue / React 适配层共享同一套 hooks 语义（usePartakeUpload），迁移心智成本低；
• React 侧基于 useSyncExternalStore，Next.js SSR 开箱即用。

UI 组件层：零 UI 库依赖

• 组件仅依赖 Vue 3（peer），不捆绑任何 UI 库；
• 主题基于 CSS 变量（--partake-* token），业务方可整体覆写；
• labels 文案支持 DeepPartial 任意层级深合并定制；
• 组件层仅做 Vue 版（React 版 v1.0 前不做，React 用户以 hooks API 自组 UI）。

扫描语义与后端契约

• 上传过程中的病毒扫描语义由后端决定：partake 网关为同步扫描（complete 响应携终态），主项目 mxtd2026 files 模块为异步 scanning / scan_pending；
• SDK 的任务事件面按 complete 响应字段驱动，接入异构后端时以双方契约文档为准。

版本锚点与双仓同步

• SDK 源码同时存在于主仓（mxtd2026 monorepo）与独立仓（gitee.com/pidaqing/partake），保持同步；
• 发布版本锚点：主仓 tag sdk/v0.2.0，锚定内容与 npm 发布物逐字节一致。

版本策略

里程碑	内容
v0.1	core 状态机 + Vue composable（38 测试 / 95.9% 行覆盖）
v0.2（当前）	React 适配层 + 传输控制六项 + 组件层 + playground（90 测试 / 97.3% 行 / 95.0% 函数）
v1.0（规划）	编译产物 + 类型声明双通道；API 参考手册补全签名；React 版组件层评估
v0.3+（候选）	IndexedDB 加速层插件（@pidaqing/uploader/accelerator 子路径）