@qmuse/cloud-client 1.0.2 → 1.0.3-dev.0

package/README.md

@@ -1,5 +1,8 @@
 # @qmuse/cloud-client
 
+用户名密码登录请先读 [认证接入契约与完整示例](docs/auth.md)：包含输入字段、用户返回值、恢复会话、注册后登录和退出。
+下方 SDK 示例使用宿主已初始化的客户端；QMuse 生成项目通过 `src/services/cloud` 接入，项目接入说明由 CLI 同步此认证契约。
+
 Unified Web/PC/mini-program client for QMuse Cloud services. Business APIs use
 the single `qmuse-cloud-api` AppBase Function. File policy uses that Function as
 its control plane while large file bytes use a platform-specific Storage data

package/docs/auth.md

@@ -0,0 +1,31 @@
+## 用户名密码认证
+
+`register` / `login` 接收 `{ username: string, password: string }`，输入类型为 `CloudRegisterInput` / `CloudLoginInput`。表单、Hook 和调用对象统一使用 `username`，不是 `email`。
+
+成功返回的 `CloudAuthUser` 是用户对象本身，不需要再取 `.data` 或 `.user`：
+
+| 字段 | 类型 | 用途 |
+| --- | --- | --- |
+| `id` | `string` | 应用用户 ID，不是数据库行的 `$id` |
+| `username` | `string` | 用户名；显示名称使用此字段，不假设存在 `name` 或 `email` |
+| `avatarUrl` | `string` | 可直接用于图片的头像 URL |
+| `role` | `'user' \| 'admin'` | 应用角色；业务权限仍由服务端校验 |
+
+```ts
+import { getQMuseClient, type CloudAuthUser, type CloudLoginInput } from '@qmuse/cloud-client';
+
+const authService = getQMuseClient().auth;
+
+export const restoreUser = (): Promise<CloudAuthUser | null> => authService.restoreSession();
+export const signOut = (): Promise<void> => authService.logout();
+export async function submitAuth(mode: 'login' | 'register', username: string, password: string): Promise<CloudAuthUser> {
+  const input: CloudLoginInput = { username, password };
+  if (mode === 'register') await authService.register(input);
+  return authService.login(input);
+}
+```
+
+- 页面启动先等待 `restoreUser()`；返回用户后才加载私有数据，返回 `null` 时展示登录表单。异常应展示服务错误，不等同于未登录。
+- `register()` 只创建账号，不建立或替换 Session。只有 `submitAuth()` 登录成功后才更新已登录状态、加载私有数据；注册成功而登录失败时，提示账号已创建并引导登录，不自动重新注册。
+- 退出成功后清空页面用户和私有数据缓存；恢复会话为空时同样清空旧状态。
+- 请求失败通过异常返回，私有 API 的 401 按未登录处理；网络错误和 5xx 保留服务异常语义。不记录密码或 Session，不从页面传入角色或用户 ID 代替服务端鉴权。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qmuse/cloud-client",
-  "version": "1.0.2",
+  "version": "1.0.3-dev.0",
   "description": "Narrow HTTP-style client for the single QMuse Cloud API Function",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,6 +23,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md",
     "LEGAL.md"
   ],