Release v0.2.0 archive and space API update

服务参考_临时/Brisk Unity SDK接入文档.md

@@ -2,17 +2,18 @@
 
 ## 1. 这份文档适合做什么
 
-这份文档用于在 Unity 侧封装 Brisk SDK。
+这份文档用于说明当前 Brisk Unity SDK 的接入结构与推荐调用方式。
 
-建议把 SDK 拆成以下层次：
+当前 SDK 已采用静态总入口：
 
-- `BriskClient`
-- `BriskAuth`
-- `BriskConfig`
-- `BriskAnnouncements`
-- `BriskRanks`
-- `BriskArchives`
-- `BriskSpaces`
+- `Brisk.InitializeAsync(...)`
+- `Brisk.Auth.xxx`
+- `Brisk.Player.xxx`
+- `Brisk.Config.xxx`
+- `Brisk.Announcements.xxx`
+- `Brisk.Leaderboard.xxx`
+- `Brisk.Archive.xxx`
+- `Brisk.Space.xxx`
 
 ## 2. 初始化模型
 
@@ -141,16 +142,31 @@ Task LikeSpaceByLoginIdentityAsync(string loginProvider, string loginUserId)
   - msgpack bytes
   - 压缩后的存档二进制
 
-Unity SDK 建议提供：
+当前 SDK 已提供：
 
 - `GetArchiveSlotsAsync()`
 - `GetArchiveMetaAsync(slotNo)`
-- `UploadArchiveAsync(slotNo, baseVersion, checksum, byte[])`
+- `UploadAsync(slotNo, byte[], baseVersion, checksum)`
+- `UploadTextAsync(slotNo, text, baseVersion, checksum)`
+- `UploadJsonAsync(slotNo, payload, baseVersion, checksum)`
 - `DownloadArchiveAsync(slotNo)`
+- `DownloadTextAsync(slotNo)`
+- `DownloadJsonAsync(slotNo)`
+
+推荐上层使用策略：
+
+- 文本存档：优先直接用 `UploadTextAsync / DownloadTextAsync`
+- JSON 存档：优先直接用 `UploadJsonAsync / DownloadJsonAsync`
+- 二进制存档：继续用 `UploadAsync / DownloadAsync`
+
+其中：
+
+- SDK 会自动计算上传用 `checksum`
+- 手动传 `checksum` 时也可以带 `sha256:` 前缀，SDK 会自动归一化
 
 ## 9. 玩家空间模块建议
 
-玩家空间适合承载公开展示数据，不建议放主存档。
+玩家空间适合承载公开展示数据或空间自定义内容，不再限制为 JSON。
 
 推荐放：
 
@@ -158,16 +174,48 @@ Unity SDK 建议提供：
 - 头像展示字段
 - 成就展示摘要
 - 公开资料卡
+- 小型二进制空间内容
+- 文本、JSON、protobuf、msgpack 等自定义格式
 
-当前接口核心是：
+当前 SDK / 接口核心是：
 
-- `UpdateMySpaceAsync(payloadJson)`
+- `UploadMySpaceContentAsync(baseVersion, contentType, checksum, byte[])`
+- `DownloadSpaceContentByPlayerIdAsync(playerId)`
+- `DownloadSpaceContentByLoginIdentityAsync(loginProvider, loginUserId)`
 - `GetSpaceByPlayerIdAsync(playerId)`
 - `GetSpaceByLoginIdentityAsync(loginProvider, loginUserId)`
 - `LikeSpaceAsync(playerId)`
 - `LikeSpaceByLoginIdentityAsync(loginProvider, loginUserId)`
 - `GetMyVisitsAsync(limit)`
 
+当前 SDK 额外提供了一个极简便捷入口：
+
+- `Brisk.Space.UpdateMyAsync(payload, baseVersion, contentType, checksum)`
+
+它的行为是：
+
+- `payload` 为 `string` 时，自动按 `text/plain` 上传
+- `payload` 为 `byte[]` 时，自动按 `application/octet-stream` 上传
+- `payload` 为其他对象时，自动序列化为 JSON 并按 `application/json` 上传
+
+建议 SDK 暴露两层模型：
+
+- 空间主信息：
+  - `ContentExists`
+  - `ContentVersion`
+  - `ContentType`
+  - `ContentSizeBytes`
+  - `ContentChecksum`
+  - `LikeCount`
+  - `VisitCount`
+- 空间内容本体：
+  - 原始 `byte[]`
+  - 下载响应头中的 `X-Space-Version`
+  - 下载响应头中的 `X-Space-Checksum`
+
+如果上层业务追求最省事，可以直接用 `UpdateMyAsync(string)` 或 `UpdateMyAsync(object)`；
+如果业务自己管理编码、压缩、protobuf、msgpack 等格式，则继续走 `byte[]` 上传下载接口。
+
 ## 10. 动态配置建议
 
 动态配置拆为两层：