49 lines
2.3 KiB
Markdown
49 lines
2.3 KiB
Markdown
# cfw-attachment
|
||
|
||
独立 Cloudflare 附件管理服务。认证通过 `AUTH` service binding 调用 `cfw-auth`，附件业务数据保存在本服务自己的 D1/R2。
|
||
|
||
附件表（元数据、分类、标签、业务关联、审计）全部归属当前登录用户：所有 D1 查询都带 `user_id` 条件，R2 object key 也按 `users/{userId}/...` 隔离。
|
||
|
||
## 架构边界
|
||
|
||
- `cfw-auth`：只负责登录鉴权，本服务不修改它。
|
||
- `cfw-attachment`：独立 Worker，绑定自己的 D1（`DB`）/ R2（`ATTACHMENTS`），通过 `AUTH` service binding 调 `cfw-auth` 的 `/api/auth/get-session` 获取当前用户。
|
||
- `cfw-gateway`：只把 `/api/attachments*`、`/api/attachment-categories*`、`/api/attachment-tags*` 代理到本服务，并把本服务 OpenAPI 纳入聚合。
|
||
|
||
## 本地检查
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm db:apply:local
|
||
pnpm ready
|
||
```
|
||
|
||
`pnpm ready` 会跑 `typecheck` 和 `test`。测试用内存 fake D1（`node:sqlite` 跑真实 SQL）和内存 fake R2，不需要 Cloudflare 连接。
|
||
|
||
## 关键接口
|
||
|
||
附件：
|
||
|
||
- `POST /api/attachments`：创建附件元数据，返回 `upload_pending`
|
||
- `PUT /api/attachments/:id/content`：经 Worker 代理上传文件内容到 R2
|
||
- `POST /api/attachments/:id/finalize`：确认上传，状态变为 `available`
|
||
- `GET /api/attachments/:id`：读取详情
|
||
- `PATCH /api/attachments/:id`：更新 filename / visibility / description / categoryId / tagIds
|
||
- `DELETE /api/attachments/:id`：软删除，并尽力删 R2 object
|
||
- `GET /api/attachments/:id/download`：仅 `available` 可下载，否则 `409 object-not-available`
|
||
- `GET /api/attachments/search?page=1&pageSize=20&q=&categoryId=&tag=&status=`：分页检索当前用户附件
|
||
|
||
分类与标签：
|
||
|
||
- `POST /api/attachment-categories`、`GET /api/attachment-categories`、`PATCH /api/attachment-categories/:id`、`DELETE /api/attachment-categories/:id`
|
||
- `POST /api/attachment-tags`、`GET /api/attachment-tags`、`PATCH /api/attachment-tags/:id`、`DELETE /api/attachment-tags/:id`
|
||
|
||
分类/标签以 `user_id + slug` 唯一。删除分类会把当前用户下引用它的附件 `category_id` 置空；删除标签会先删当前用户下的标签关联再删标签。
|
||
|
||
## 部署
|
||
|
||
```bash
|
||
pnpm db:apply:remote # 远端 D1 应用 schema
|
||
pnpm deploy # 部署 Worker（含 AUTH service binding 到 cfw-auth）
|
||
```
|