feat: publish Dever core with project scaffolding and versioned AI skills

2026-10-04 13:37:30 +00:00
1 parent 70fa73cdc2
commit ac458ffa7f
@@ -0,0 +1,24 @@
+# 媒体本地适配器
+
+本地适配器使用受控 data/upload 路径保存上传内容。
+
+- 包：`media.asset.adapter`
+- 公开类型：无
+- 公开方法：无
+- 使用：无
+
+## 本地存储
+
+适配器实现媒体存储端口。
+
+- 函数：`port.store`
+- 输入：
+  - `file: Upload`：上传文件
+- 输出：
+  - `key: Uuid`：存储键
+
+```dever
+port.store(file: Upload) (key: Uuid) {
+  key = dever.storage.put(file)
+}
+```
@@ -0,0 +1,18 @@
+# 后台媒体接口
+
+后台媒体接口只开放上传动作。
+
+- 包：`media.asset.api.admin.manage`
+- 公开类型：无
+- 公开方法：无
+- 使用：无
+
+## 上传媒体
+
+上传请求委托给媒体应用。
+
+- 声明：`post upload`
+
+```dever
+post upload = app.store
+```
@@ -0,0 +1,107 @@
+# 媒体资源应用
+
+媒体应用通过 Storage Port 接收上传并保存元数据。
+
+- 包：`media.asset.app`
+- 公开类型：
+  - `StoreResult`
+- 公开方法：
+  - `store`
+  - `require_ready`
+  - `ready`
+- 使用：
+  - `media.asset.store(file)`
+  - `media.asset.require_ready(id)`
+  - `media.asset.ready(available)`
+
+## 保存结果
+
+返回资源公开元数据。
+
+- 类型：`StoreResult`
+- 字段：
+  - `id: model.id`：记录标识
+  - `storage_key: Uuid`：该声明的业务值
+  - `filename: Text`：该声明的业务值
+  - `content_type: Text`：该声明的业务值
+  - `size: Int`：受限页大小
+
+```dever
+type StoreResult {
+  id: model.id
+  storage_key: Uuid
+  filename: Text
+  content_type: Text
+  size: Int
+}
+```
+
+## 保存上传
+
+文件内容只能通过 Port 交给 Adapter。
+
+- 函数：`store`
+- 输入：
+  - `file: Upload`：该声明的业务值
+- 输出：
+  - `result: StoreResult`：该声明的业务值
+
+```dever
+store(file: Upload) (result: StoreResult) {
+  filename = dever.api.upload_filename(file)
+  content_type = dever.api.upload_content_type(file)
+  size = dever.api.upload_size(file)
+  key = port.store(file)
+  asset = model.create(
+    {
+      storage_key = key
+      filename = filename
+      content_type = content_type
+      size = size
+    }
+  )
+  audit.operation.record(audit.operation.model.OperationKind.Upload, "asset", filename)
+  result = StoreResult {
+    id = asset.id
+    storage_key = asset.storage_key
+    filename = asset.filename
+    content_type = asset.content_type
+    size = asset.size
+  }
+}
+```
+
+## require_ready
+
+媒体应用通过 Storage Port 接收上传并保存元数据。
+
+- 函数：`require_ready`
+- 输入：
+  - `id: media.asset.model.id?`：记录标识
+- 输出：无
+
+```dever
+require_ready(id: model.id) () {
+  stored = model.get(id)
+  ready(stored.status == model.AssetStatus.Ready)
+}
+
+require_ready(id: null) () {}
+```
+
+## ready
+
+媒体应用通过 Storage Port 接收上传并保存元数据。
+
+- 函数：`ready`
+- 输入：
+  - `available: Bool`：该声明的业务值
+- 输出：无
+
+```dever
+ready(available: true) () {}
+
+ready(available: false) () {
+  fail(dever.api.Error.Conflict)
+}
+```
@@ -0,0 +1,48 @@
+# 媒体资源模型
+
+媒体模型只保存受控存储键和文件元数据。
+
+- 包：`media.asset.model`
+- 公开类型：
+  - `AssetStatus`
+  - `Asset`
+- 公开方法：无
+- 使用：无
+
+## 资源状态
+
+资源生命周期状态。
+
+- 类型：`AssetStatus`
+- 分支：
+  - `Ready`：就绪
+  - `Removed`：已删除
+
+```dever
+type AssetStatus {
+  Ready = "就绪"
+  Removed = "已删除"
+}
+```
+
+## 资源记录
+
+资源元数据不包含上传内容本身。
+
+- 类型：`Asset`
+- 字段：
+  - `storage_key: Uuid`：存储键
+  - `filename: Text(1, 255)`：文件名
+  - `content_type: Text(1, 160)`：内容类型
+  - `size: Int`：大小
+  - `status: AssetStatus`：状态
+
+```dever
+type Asset {
+  storage_key: Uuid unique
+  filename: Text(1, 255)
+  content_type: Text(1, 160)
+  size: Int
+  status: AssetStatus default AssetStatus.Ready index
+}
+```
@@ -0,0 +1,23 @@
+# 媒体存储端口
+
+媒体应用通过端口隔离存储实现。
+
+- 包：`media.asset.port`
+- 公开类型：无
+- 公开方法：无
+- 使用：无
+
+## 保存上传
+
+端口只声明上传内容到存储的契约。
+
+- 函数：`store`
+- 输入：
+  - `file: Upload`：上传文件
+- 输出：
+  - `key: Uuid`：存储键
+- 允许失败：`dever.storage.PutResult`
+
+```dever
+store(file: Upload) (key: Uuid) fails dever.storage.PutResult
+```