# NovaStorage 使用规则（cc 编程工具）

面向 cc 的编程规则，帮助你在任意页面仅通过 `cid` 即可加载与使用存储工具，无需关注 Provider 细节。

## 快速约定
- 仅需 `cid`：使用 `NovaStorage.withCid(cid)` 自动选择企业账套 Provider。
- 统一返回：上传结果为 `NovaFile`，含 `key`, `url`, `name`, `type`, `size`, `metadata`, `md5` 等。
- 生成 Key：默认格式 `storage/company/<cid>/<prefixKey?>/<YYYYMMDD>/<HHmmss-rand>-<name>`。
- 可选前缀：通过 `prefixKey` 在公司段后、日期目录前插入自定义目录（自动去除首尾斜杠）。
- 查重与保存：封装 `getAttachmentByMd5` 与 `saveAttachment`，避免重复上传并统一写入 `Attachment`。

## 依赖导入
```ts
import { NovaStorage, NovaFile } from 'fmode-ng/core';
```

## 初始化（仅凭 cid）
```ts
const cid = localStorage.getItem('company')!; // 或服务获取
const storage = await NovaStorage.withCid(cid);
```

## 上传文件（含进度与 prefixKey）
```ts
const file = (event.target as HTMLInputElement).files![0];
const uploaded: NovaFile = await storage.upload(file, {
  prefixKey: 'project/pid/', // 项目页需要加项目前缀
  onProgress: (p) => console.log('progress %', p.total.percent),
});
console.log(uploaded.key, uploaded.url);
```