@h-ai/cli 0.1.0-alpha.54 → 0.1.0-alpha.56

package/templates/skills/hai-iam/SKILL.md

@@ -1,381 +1,37 @@
 ---
 name: hai-iam
-description: 使用 @h-ai/iam 进行身份认证（密码/OTP/LDAP/API Key）、统一 Bearer Token 管理（TokenPair/refresh/revoke）与 RBAC 授权；当需求涉及登录、注册、权限检查、角色管理、Token 认证或通过 @h-ai/api-contract 暴露 IAM API 时使用。
+description: "使用 @h-ai/iam 实现登录、注册、会话、OTP/LDAP/API Key 和 RBAC。"
 ---
 
 # hai-iam
 
 ## 能力契约
 
-角色成员数使用 `getRoleUserCounts(roleIds)`，一次聚合返回 `HaiResult<Map<string, number>>`；成功时无关联为 0，失败必须展示错误，不能伪造零值。
-
-角色资料和权限必须通过 `createRole({ ..., permissionIds })` / `updateRole(id, { ..., permissionIds })` 一次事务保存，禁止在应用层并行增删权限模拟替换。空数组清空、未传保持、未知权限失败、重复 ID 去重；并发以最后提交的完整集合为准。自管事务提交后同步会话，外部事务由调用方提交后同步。
-
-管理界面自动创建角色时使用 `role_${core.id.generate()}` 生成 code，显示名称独立保存；不要通过移除中文、表情或折叠大小写生成标识。重命名不重建 code。
-
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | 使用 @h-ai/iam 进行身份认证（密码/OTP/LDAP/API Key）、统一 Bearer Token 管理（TokenPair/refresh/revoke）与 RBAC 授权；当需求涉及登录、注册、权限检查、角色管理、Token 认证或通过 @h-ai/api-contract 暴露 IAM API 时使用。 |
-| 适用场景 | 当任务与 `hai-iam` 的能力描述匹配，并且需要遵循本 Skill 的流程和边界时 |
-| 输入 | 模块配置、类型化业务参数、依赖初始化状态和目标运行环境 |
-| 输出 | 符合模块公共 API 的实现或示例；业务结果使用 HaiResult，并同步必要测试与文档 |
-| 限制 | 遵守 init → use → close 生命周期与运行环境边界；不绕过类型、授权、输入校验或敏感信息保护 |
-
-> `@h-ai/iam` 是统一的身份与访问管理模块，支持多种认证策略（密码/OTP/LDAP/API Key）、Bearer Token 管理和 RBAC 授权。依赖 `@h-ai/reldb`（持久化）、`@h-ai/cache`（Token + 权限缓存）、`@h-ai/crypto`（密码哈希）、`@h-ai/audit`（审计日志）。
-
----
-
-## 运行环境
-
-> ⚠️ **服务端模块（Node.js only）。** 浏览器端通过 `@h-ai/api-client` 的 typed client 调用 IAM API，例如 `apiClient.iam.auth.login()`。HTTP 契约统一来自 `@h-ai/api-contract`。
-
----
-
-## 依赖
-
-| 模块 | 用途 | 是否必需 | 初始化要求 |
-| --- | --- | --- | --- |
-| `@h-ai/reldb` | 数据库（用户/角色/权限持久化） | **必需** | 需在 `iam.init()` 前初始化 |
-| `@h-ai/cache` | 缓存（会话/OTP/重置令牌/权限缓存） | **必需** | 需在 `iam.init()` 前初始化 |
-| `@h-ai/crypto` | 密码哈希 | 内部使用 | 自动初始化 |
-| `@h-ai/audit` | 审计日志（RBAC 关键操作记录） | 内部使用 | 已初始化时自动写入 |
-
-## 适用场景
-
-- 用户注册与登录（密码/OTP/LDAP/API Key）
-- Bearer Token 认证与管理（TokenPair: accessToken + refreshToken）
-- Token 刷新（rotation 策略）与吊销
-- RBAC 角色/权限的创建、分配与检查
-- API Key 管理（创建、吊销、验证）
-- 密码重置流程
-- 与 kit 集成的认证守卫
-- 通过 `@h-ai/api-contract` 暴露 IAM HTTP contract
-
----
-
-## 使用步骤
-
-### 1. 配置
-
-```yaml
-# config/_iam.yml
-password:
-  minLength: 8
-  requireUppercase: true
-  requireNumber: true
-session:
-  maxAge: 86400
-  refreshTokenMaxAge: 604800 # 7 天
-  sliding: true
-  singleDevice: false
-login:
-  password: true
-  otp: false
-register:
-  enabled: true
-security:
-  maxLoginAttempts: 5
-  lockoutDuration: 900
-rbac:
-  defaultRole: user
-  superAdminRole: super_admin
-```
-
-约定环境变量优先于 YAML，例如 `HAI_IAM_PASSWORD_MINLENGTH`、
-`HAI_IAM_SESSION_MAXAGE`、`HAI_IAM_SECURITY_MAXLOGINATTEMPTS`。
-
-### 2. 初始化
-
-```typescript
-import { cache } from '@h-ai/cache'
-import { reldb } from '@h-ai/reldb'
-import { iam } from '@h-ai/iam'
-
-// 必须先初始化 reldb 和 cache
-await reldb.init(core.config.get('db'))
-await cache.init(core.config.get('cache'))
-
-// IAM 自动使用已初始化的 reldb 和 cache 单例
-await iam.init({
-  ...core.config.get('iam'),
-  seedDefaultData: true,
-})
-```
-
-`iam.config` 返回的是脱敏后的配置快照；LDAP `url` / `bindPassword` 等敏感值会自动隐藏。
-
-初始化时自动创建数据库表（5 张）：`hai_iam_users`、`hai_iam_roles`、`hai_iam_permissions`、`hai_iam_role_permissions`、`hai_iam_user_roles`。
-
-Token 和 OTP 存储在 cache 中（不落库）。refreshToken 使用独立的 cache key 存储。
-
----
-
-## 核心 API
-
-### 认证 — `iam.auth`
-
-| 方法               | 签名                                                        | 说明                               |
-| ------------------ | ----------------------------------------------------------- | ---------------------------------- |
-| `login`            | `({ identifier, password }) => Promise<HaiResult<AuthResult>>` | 密码登录（用户名/邮箱/手机号）     |
-| `loginWithOtp`     | `({ identifier, code }) => Promise<HaiResult<AuthResult>>`     | OTP 验证码登录                     |
-| `loginWithLdap`    | `({ username, password }) => Promise<HaiResult<AuthResult>>`   | LDAP 登录                          |
-| `loginWithApiKey`  | `({ key }) => Promise<HaiResult<AuthResult>>`                  | API Key 登录                       |
-| `sendOtp`          | `(identifier) => Promise<HaiResult<{ expiresAt }>>`            | 发送 OTP 验证码                    |
-| `verifyToken`      | `(token) => Promise<HaiResult<Session>>`                       | 验证令牌（推荐入口，委托 session） |
-| `logout`           | `(token) => Promise<HaiResult<void>>`                          | 登出                               |
-| `registerAndLogin` | `(options: RegisterOptions) => Promise<HaiResult<AuthResult>>`  | 注册并登录（一站式）               |
-
-**AuthResult**（已改造为 TokenPair）：
-
-```typescript
-interface AuthResult {
-  user: User
-  tokens: TokenPair
-  roles: string[]
-  permissions: string[]
-  agreements?: AgreementDisplay
-}
-
-interface TokenPair {
-  accessToken: string
-  refreshToken: string
-  expiresIn: number
-  tokenType: 'Bearer'
-}
-```
-
-### 会话管理 — `iam.session`
-
-| 方法                | 签名                                                                 | 说明                                    |
-| ------------------- | -------------------------------------------------------------------- | --------------------------------------- |
-| `create`            | `({ userId, username, roles, source? }) => Promise<HaiResult<Session>>` | 创建会话（返回含 TokenPair 的 session） |
-| `get`               | `(token) => Promise<HaiResult<Session \| null>>`                        | 获取会话（滑动续期自动延长）            |
-| `verifyToken`       | `(token) => Promise<HaiResult<Session>>`                                | 验证令牌                                |
-| `update`            | `(token, data) => Promise<HaiResult<void>>`                             | 更新会话字段（浅合并 data）             |
-| `delete`            | `(token) => Promise<HaiResult<void>>`                                   | 删除会话                                |
-| `deleteByUserId`    | `(userId) => Promise<HaiResult<number>>`                                | 删除用户所有会话（返回删除数量）        |
-| `refresh`           | `(refreshToken) => Promise<HaiResult<TokenPair>>`                       | 刷新 Token（rotation：旧 Token 失效）   |
-| `revokeRefresh`     | `(refreshToken) => Promise<HaiResult<void>>`                            | 吊销 refreshToken                       |
-| `patchUserSessions` | `(userId, updates: SessionFieldUpdates) => Promise<HaiResult<void>>`    | 批量更新用户所有会话的 roles/permissions |
-
-**Token 刷新（rotation 策略）**：
-
-- `refresh()` 会删除旧的 accessToken + refreshToken
-- 创建全新的 session，返回新的 TokenPair
-- 旧 refreshToken 立即失效，防止重放攻击
-
-### 一次性票据 — `iam.ticket`
-
-短期、一次性能力票据，用于无法携带 Bearer Token 的通道（如 WebSocket URL）。密码学安全随机、TTL、原子单次消费、用途绑定。
-
-| 方法       | 签名                                                                                   | 说明                                  |
-| ---------- | -------------------------------------------------------------------------------------- | ------------------------------------- |
-| `issue`    | `({ subjectId, purpose, grant?, ttlMs? }) => Promise<HaiResult<{ ticket, expiresAt }>>` | 签发（默认 30s）                      |
-| `consume`  | `(ticket, { purpose? }?) => Promise<HaiResult<{ subjectId, purpose, grant }>>`          | 原子消费（单次有效，用途不符拒绝）   |
-
-```ts
-const issued = await iam.ticket.issue({ subjectId, purpose: 'ai-audio', grant: { operation: 'transcribe' } })
-const consumed = await iam.ticket.consume(ticket, { purpose: 'ai-audio' }) // 并发消费仅一个成功
-```
-
-错误码：`TICKET_INVALID`(hai:iam:110) / `TICKET_EXPIRED`(hai:iam:111) / `TICKET_ISSUE_FAILED`(hai:iam:112)。
-
-### 用户管理 — `iam.user`
-
-| 方法                       | 签名                                                                    | 说明                                 |
-| -------------------------- | ----------------------------------------------------------------------- | ------------------------------------ |
-| `register`                 | `(input) => Promise<HaiResult<RegisterResult>>`                            | 用户注册                             |
-| `getUser`                  | `(id, options?) => Promise<HaiResult<User \| null>>`                       | 获取用户（可选 include: ['roles']）  |
-| `getCurrentUser`           | `(token) => Promise<HaiResult<User>>`                                      | 通过令牌获取当前用户                 |
-| `updateCurrentUser`        | `(token, data: UpdateCurrentUserInput) => Promise<HaiResult<User>>`        | 当前用户修改个人资料（白名单字段）   |
-| `listUsers`                | `(options?: ListUsersOptions) => Promise<HaiResult<PaginatedResult<User>>>` | 用户列表（分页 + 搜索 + 过滤 + 白名单排序） |
-| `updateUser`               | `(id, data) => Promise<HaiResult<User>>`                                   | 更新用户信息                         |
-| `deleteUser`               | `(id) => Promise<HaiResult<void>>`                                         | 删除用户（自动清除会话）             |
-| `changePassword`           | `(id, old, new) => Promise<HaiResult<void>>`                               | 修改密码（自动清除会话）             |
-| `changeCurrentUserPassword`| `(token, old, new) => Promise<HaiResult<void>>`                            | 当前用户修改密码（通过令牌识别）     |
-| `requestPasswordReset`     | `(email) => Promise<HaiResult<void>>`                                      | 请求密码重置（防枚举）               |
-| `confirmPasswordReset`     | `(token, newPassword) => Promise<HaiResult<void>>`                         | 确认密码重置（自动清除会话）         |
-| `adminResetPassword`       | `(userId, newPassword) => Promise<HaiResult<void>>`                        | 管理员直接重置密码                   |
-| `validatePassword`         | `(password) => HaiResult<void>`                                  | 验证密码强度（**同步方法**）         |
-
-### RBAC 授权 — `iam.authz`
-
-| 方法                       | 签名                                                                             | 说明                                         |
-| -------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------- |
-| `checkPermission`          | `(userId, permission) => Promise<HaiResult<boolean>>`                               | 检查权限（超管自动通过，支持通配符）         |
-| `getUserPermissions`       | `(userId) => Promise<HaiResult<Permission[]>>`                                      | 获取用户权限列表（通过角色聚合去重）         |
-| `getUserRoles`             | `(userId) => Promise<HaiResult<Role[]>>`                                            | 获取用户角色列表                             |
-| `getUserRolesForMany`      | `(userIds) => Promise<HaiResult<Map<string, Role[]>>>`                              | 批量获取多用户角色（避免 N+1）               |
-| `assignRole`               | `(userId, roleId, tx?) => Promise<HaiResult<void>>`                                 | 分配角色给用户                               |
-| `removeRole`               | `(userId, roleId, tx?) => Promise<HaiResult<void>>`                                 | 移除用户角色                                 |
-| `syncRoles`                | `(userId, roleIds, tx?) => Promise<HaiResult<void>>`                                | 同步用户角色（替换为目标列表）               |
-| `createRole`               | `({ code, name, description? }, tx?) => Promise<HaiResult<Role>>`                   | 创建角色                                     |
-| `getRole`                  | `(roleId) => Promise<HaiResult<Role \| null>>`                                      | 获取角色                                     |
-| `getRoleByCode`            | `(code) => Promise<HaiResult<Role \| null>>`                                        | 根据代码获取角色                             |
-| `getAllRoles`              | `(options?) => Promise<HaiResult<PaginatedResult<Role>>>`                           | 获取所有角色（分页）                         |
-| `updateRole`               | `(roleId, data, tx?) => Promise<HaiResult<Role>>`                                   | 更新角色                                     |
-| `deleteRole`               | `(roleId, tx?) => Promise<HaiResult<void>>`                                         | 删除角色（级联清理关联 + 会话同步）          |
-| `createPermission`         | `({ code, name, type?, resource?, action? }, tx?) => Promise<HaiResult<Permission>>`| 创建权限                                     |
-| `getPermission`            | `(permissionId) => Promise<HaiResult<Permission \| null>>`                          | 获取权限                                     |
-| `getPermissionByCode`      | `(code) => Promise<HaiResult<Permission \| null>>`                                  | 根据代码获取权限                             |
-| `getAllPermissions`         | `(options?: PermissionQueryOptions) => Promise<HaiResult<PaginatedResult<Permission>>>` | 获取所有权限（分页 + 类型/关键字筛选）   |
-| `deletePermission`         | `(permissionId, tx?) => Promise<HaiResult<void>>`                                   | 删除权限（级联清理关联 + 会话同步）          |
-| `assignPermissionToRole`   | `(roleId, permId, tx?) => Promise<HaiResult<void>>`                                 | 分配权限给角色                               |
-| `removePermissionFromRole` | `(roleId, permId, tx?) => Promise<HaiResult<void>>`                                 | 移除角色权限                                 |
-| `getRolePermissions`       | `(roleId) => Promise<HaiResult<Permission[]>>`                                      | 获取角色的权限列表                           |
-| `getRolePermissionsForMany`| `(roleIds) => Promise<HaiResult<Map<string, Permission[]>>>`                        | 批量获取多角色权限（避免 N+1）               |
-
-**通配符规则**：`admin:*` 匹配 `admin:read`、`admin:write` 等。超管角色自动拥有所有权限。
-
-### API Key 管理 — `iam.apiKey`
-
-| 方法           | 签名                                                                    | 说明                                   |
-| -------------- | ----------------------------------------------------------------------- | -------------------------------------- |
-| `createApiKey` | `(userId, options: CreateApiKeyOptions) => Promise<HaiResult<CreateApiKeyResult>>` | 创建 API Key（明文密钥仅返回一次） |
-| `listApiKeys`  | `(userId, options?) => Promise<HaiResult<PaginatedResult<ApiKey>>>`        | 分页列出用户的 API Key                 |
-| `getApiKey`    | `(keyId) => Promise<HaiResult<ApiKey \| null>>`                            | 获取 API Key 详情                      |
-| `revokeApiKey` | `(keyId) => Promise<HaiResult<void>>`                                      | 吊销/删除 API Key                      |
-| `verifyApiKey` | `(rawKey) => Promise<HaiResult<ApiKey>>`                                   | 验证 API Key 并返回实体（含用户 ID）   |
-
-> 需在 `login.apikey: true` 时才会初始化此子模块，否则访问返回 `NOT_INITIALIZED` 错误。
-
----
-
-## HTTP API 契约
-
-IAM HTTP API 统一由 `@h-ai/api-contract` 的 `apiContract.iam` 定义，由 `@h-ai/serv/features/iam` 绑定到本模块。
-
-```typescript
-import { apiClient } from '@h-ai/api-client'
-
-const result = await apiClient.iam.auth.login({ identifier: username, password })
-```
-
----
-
-## 错误码 — `HaiIamError`
-
-| 错误码 | code | 说明 |
-|--------|------|------|
-| `HaiIamError.AUTH_FAILED` | `hai:iam:001` | 认证失败 |
-| `HaiIamError.INVALID_CREDENTIALS` | `hai:iam:002` | 凭证无效 |
-| `HaiIamError.USER_NOT_FOUND` | `hai:iam:003` | 用户不存在 |
-| `HaiIamError.USER_DISABLED` | `hai:iam:004` | 用户已禁用 |
-| `HaiIamError.USER_LOCKED` | `hai:iam:005` | 用户已锁定 |
-| `HaiIamError.USER_ALREADY_EXISTS` | `hai:iam:006` | 用户已存在 |
-| `HaiIamError.PASSWORD_EXPIRED` | `hai:iam:007` | 密码已过期 |
-| `HaiIamError.PASSWORD_POLICY_VIOLATION` | `hai:iam:008` | 密码不符合策略 |
-| `HaiIamError.OTP_INVALID` | `hai:iam:009` | 验证码无效 |
-| `HaiIamError.NOT_INITIALIZED` | `hai:iam:010` | 未初始化 |
-| `HaiIamError.OTP_RESEND_TOO_FAST` | `hai:iam:011` | 发送过于频繁 |
-| `HaiIamError.LOGIN_DISABLED` | `hai:iam:012` | 登录方式已禁用 |
-| `HaiIamError.REGISTER_DISABLED` | `hai:iam:013` | 注册已禁用 |
-| `HaiIamError.STRATEGY_NOT_SUPPORTED` | `hai:iam:014` | 认证策略不支持 |
-| `HaiIamError.APIKEY_INVALID` | `hai:iam:015` | API Key 无效 |
-| `HaiIamError.APIKEY_EXPIRED` | `hai:iam:016` | API Key 已过期 |
-| `HaiIamError.APIKEY_DISABLED` | `hai:iam:017` | API Key 已禁用 |
-| `HaiIamError.APIKEY_NOT_FOUND` | `hai:iam:018` | API Key 不存在 |
-| `HaiIamError.RESET_TOKEN_INVALID` | `hai:iam:019` | 重置令牌无效 |
-| `HaiIamError.RESET_TOKEN_EXPIRED` | `hai:iam:020` | 重置令牌已过期 |
-| `HaiIamError.RESET_TOKEN_MAX_ATTEMPTS` | `hai:iam:021` | 重置验证次数超限 |
-| `HaiIamError.OTP_EXPIRED` | `hai:iam:022` | 验证码已过期 |
-| `HaiIamError.SESSION_NOT_FOUND` | `hai:iam:101` | 会话不存在 |
-| `HaiIamError.SESSION_EXPIRED` | `hai:iam:102` | 会话已过期 |
-| `HaiIamError.SESSION_INVALID` | `hai:iam:103` | 会话无效 |
-| `HaiIamError.SESSION_CREATE_FAILED` | `hai:iam:104` | 会话创建失败 |
-| `HaiIamError.TOKEN_EXPIRED` | `hai:iam:105` | 令牌已过期 |
-| `HaiIamError.TOKEN_INVALID` | `hai:iam:106` | 令牌无效 |
-| `HaiIamError.TOKEN_REFRESH_FAILED` | `hai:iam:107` | 令牌刷新失败 |
-| `HaiIamError.PERMISSION_DENIED` | `hai:iam:201` | 权限不足 |
-| `HaiIamError.ROLE_NOT_FOUND` | `hai:iam:202` | 角色不存在 |
-| `HaiIamError.PERMISSION_NOT_FOUND` | `hai:iam:203` | 权限不存在 |
-| `HaiIamError.ROLE_ALREADY_EXISTS` | `hai:iam:204` | 角色已存在 |
-| `HaiIamError.PERMISSION_ALREADY_EXISTS` | `hai:iam:205` | 权限已存在 |
-| `HaiIamError.LDAP_CONNECTION_FAILED` | `hai:iam:301` | LDAP 连接失败 |
-| `HaiIamError.LDAP_BIND_FAILED` | `hai:iam:302` | LDAP 绑定失败 |
-| `HaiIamError.LDAP_SEARCH_FAILED` | `hai:iam:303` | LDAP 搜索失败 |
-| `HaiIamError.REPOSITORY_ERROR` | `hai:iam:401` | 存储层操作错误 |
-| `HaiIamError.NOT_FOUND` | `hai:iam:402` | 资源不存在 |
-| `HaiIamError.CONFLICT` | `hai:iam:403` | 资源冲突 |
-| `HaiIamError.FORBIDDEN` | `hai:iam:501` | 禁止访问 |
-| `HaiIamError.INVALID_ARGUMENT` | `hai:iam:502` | 参数无效 |
-| `HaiIamError.CONFIG_ERROR` | `hai:iam:901` | 配置错误 |
-| `HaiIamError.INTERNAL_ERROR` | `hai:iam:999` | 内部错误 |
-
----
-
-## 常见模式
-
-### 与 kit 集成（hooks.server.ts）
-
-```typescript
-import { iam } from '$lib/server/init'
-import { kit } from '@h-ai/kit'
-
-const haiHandle = kit.createHandle({
-  validateSession: async (token) => {
-    const result = await iam.auth.verifyToken(token)
-    if (!result.success)
-      return null
-    const roles = await iam.authz.getUserRoles(result.data.userId)
-    return {
-      userId: result.data.userId,
-      roles: roles.success ? roles.data.map(r => r.code) : [],
-      permissions: [],
-    }
-  },
-  guards: [
-    {
-      guard: kit.guard.auth({ apiMode: true }),
-      paths: ['/api/*'],
-      exclude: ['/api/auth/*'],
-    },
-  ],
-})
-
-export const handle = kit.sequence(haiHandle)
-```
-
-### 客户端认证流程
-
-```typescript
-// 登录 → 保存 Token
-const login = await apiClient.iam.auth.login({ identifier: username, password })
-if (login.success) {
-  await apiClient.auth.setTokens(login.data.tokens)
-}
-
-// 获取当前用户
-const me = await apiClient.iam.auth.currentUser()
-if (me.success) {
-  // 返回 User + 服务端当前会话的 roles/permissions。
-  // 身份资料与访问范围可在状态层拆开，但不要持久化权限快照。
-  const { roles, permissions, ...user } = me.data
-}
-
-// Token 过期时，api-client 自动调用 refreshPath 刷新
-// 刷新失败时，清除 Token 并跳转登录页
-
-// 登出
-await apiClient.iam.auth.logout({})
-await apiClient.auth.clear()
-```
-
-### 自动会话失效
-
-以下操作自动清除受影响用户的所有活跃会话：
-
-- `deleteUser` / `updateUser({ enabled: false })` / `changePassword` / `confirmPasswordReset`
-- `assignRole` / `removeRole` / `deleteRole` 会同步更新活跃会话中的角色列表
-
----
-
-## 相关 Skills
-
-- `hai-build`：模块初始化顺序（db → cache → iam）
-- `hai-kit`：SvelteKit 集成（Bearer Token + 契约处理）
-- `hai-api-client`：客户端契约调用
-- `hai-reldb`：底层数据存储
-- `hai-cache`：Token 与权限缓存
-- `hai-crypto`：密码哈希（内部依赖）
-- `hai-ui`：IAM 场景组件（LoginForm/RegisterForm 等）
+| 能力 | 使用 @h-ai/iam 实现登录、注册、会话、OTP/LDAP/API Key 和 RBAC |
+| 适用场景 | 应用身份认证、会话失效或角色权限管理 |
+| 输入 | IamConfigInput、已初始化依赖、凭据、用户/角色/权限 ID |
+| 输出 | 认证、会话与授权操作的 HaiResult |
+| 限制 | 仅服务端，先初始化 reldb/cache（crypto 未初始化时由 IAM 初始化）；公开认证入口是 iam.auth。客户端经 contract/API 调用，不能暴露密码或完整 token。 |
+
+## 使用路径
+
+- `_iam.yml` 只传 IamConfigInput；不把 reldb/cache 句柄混入配置。
+- 角色资料与 permissionIds 一次保存：未传保持、空数组清空、未知 ID 失败；人数查询失败不能显示为 0。
+- IAM 服务端是 iam.auth；typed HTTP client 的路径是 apiClient.iam.auth。
+- OTP/API Key 等先核对 login 开关；不把未启用能力的 NOT_INITIALIZED 当认证失败。
+
+## 按需参考
+
+详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
+
+- 运行环境
+- 依赖
+- 适用场景
+- 使用步骤
+- 核心 API
+- HTTP API 契约
+- 错误码 — `HaiIamError`
+- 常见模式
+- 相关 Skills