@h-ai/cli 0.1.0-alpha9 → 1.0.0-beta.2

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/pages/roles.svelte.hbs

@@ -0,0 +1,77 @@
+<script lang="ts">
+  import type { AdminPermissionPolicy, AdminRole } from '{{fullstack.contractPackageName}}'
+  import type { ManagementStore } from '../stores/management-store.svelte.js'
+  import { err, HaiCommonError } from '@h-ai/core'
+  import { SensitiveOperationsForm } from '@h-ai/ui/components/scenes/iam/index'
+  import { Card, Modal, PageHeader, Pagination } from '@h-ai/ui/components/compounds/index'
+  import { Badge, Button, Textarea } from '@h-ai/ui/components/primitives/index'
+  import { roleCapabilities, roleLabel } from '../security/role-label.js'
+  import * as m from '../paraglide/messages.js'
+
+  interface Props { store: ManagementStore }
+  const { store }: Props = $props()
+  let editing = $state<AdminRole | null>(null)
+  let description = $state('')
+  let permission = $state<AdminPermissionPolicy | null>(null)
+  async function savePolicy(operations: string[]) {
+    return permission ? store.savePermissionPolicy(permission.id, operations) : err(HaiCommonError.CONFLICT, m.home_error())
+  }
+  function edit(role: AdminRole) {
+    editing = role
+    description = role.description ?? ''
+    store.error = ''
+  }
+  async function save(event: SubmitEvent) {
+    event.preventDefault()
+    if (editing && await store.saveRole(editing.id, description))
+      editing = null
+  }
+</script>
+
+<section class="space-y-3" data-testid="roles-page">
+  <PageHeader title={m.nav_roles()} description={m.roles_description()} class='mb-0'>
+    {#snippet actions()}<Button size='sm' variant='outline' loading={store.loading} onclick={() => void store.loadRoles()}>{m.home_refresh()}</Button>{/snippet}
+  </PageHeader>
+  <div class="grid gap-3 md:grid-cols-2">
+    {#each store.roles as role (role.id)}
+      <Card bordered shadow={false}>
+        <div class="flex items-center justify-between gap-3"><h2 class="text-lg font-semibold">{roleLabel(role.code)}</h2><Badge variant={role.code === 'admin' ? 'primary' : 'ghost'}>{role.code}</Badge></div>
+        <p class="mt-3 text-sm leading-6 text-base-content/60">{roleCapabilities(role.code)}</p>
+        <p class="mt-4 text-xs text-base-content/45">{m.role_members({ count: String(role.userCount) })}</p>
+        {#if role.description}<p class="mt-3 text-sm text-base-content/70">{role.description}</p>{/if}
+        {#if role.code === 'admin' || role.code === 'user'}<div class="mt-5"><Button variant="outline" size="sm" onclick={() => edit(role)}>{m.role_edit()}</Button></div>{/if}
+      </Card>
+    {/each}
+  </div>
+  {#if store.authConfig?.reauthentication?.enabled}
+    <Card bordered shadow={false}>
+      <h2 class="mb-4 text-lg font-semibold">{m.security_sensitive_operations()}</h2>
+      <div class="divide-y divide-base-content/8">
+        {#each store.permissionPolicies as item (item.id)}
+          <div class="flex items-center justify-between gap-4 py-3">
+            <div class="min-w-0"><p class="break-all font-mono text-sm">{item.code}</p><p class="mt-1 break-all text-xs text-base-content/60">{item.sensitiveOperations.join(', ') || '—'}</p></div>
+            <Button size="sm" variant="outline" onclick={() => { permission = item }}>{m.security_sensitive_operations()}</Button>
+          </div>
+        {/each}
+      </div>
+      <Pagination page={store.permissionPolicyPage} total={store.permissionPolicyTotal} pageSize={store.pageSize} onchange={page => void store.loadPermissionPolicies(page)} />
+    </Card>
+  {/if}
+</section>
+
+<Modal open={!!editing} title={m.role_edit()} onclose={() => { editing = null }} closeOnBackdrop={!store.saving} closeOnEscape={!store.saving}>
+  <form class="space-y-4" onsubmit={save}>
+    <label class="block text-sm font-medium" for="role-description">{m.role_description()}</label>
+    <Textarea id="role-description" bind:value={description} rows={4} data-testid="role-description" />
+    <div class="flex justify-end gap-2"><Button variant="ghost" disabled={store.saving} onclick={() => { editing = null }}>{m.cancel()}</Button><Button type="submit" variant="primary" loading={store.saving}>{m.save()}</Button></div>
+  </form>
+</Modal>
+
+<Modal open={!!permission} title={m.security_sensitive_operations()} onclose={() => { permission = null }}>
+  {#if permission}
+    {#key permission.id}
+      <p class="mb-3 break-all font-mono text-sm">{permission.code}</p>
+      <SensitiveOperationsForm operations={permission.sensitiveOperations} onsubmit={savePolicy} ondone={() => { permission = null }} />
+    {/key}
+  {/if}
+</Modal>

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/pages/settings.svelte.hbs

@@ -0,0 +1,44 @@
+<script lang='ts'>
+  import type { ManagementStore } from '../stores/management-store.svelte.js'
+  import { Card, FormField, FormLayout, PageHeader } from '@h-ai/ui/components/compounds/index'
+  import { Badge, Select } from '@h-ai/ui/components/primitives/index'
+  import { ChangePasswordForm, UserProfile } from '@h-ai/ui/components/scenes/iam/index'
+  import { getThemeInfo } from '@h-ai/ui/theme'
+  import { roleLabel } from '../security/role-label.js'
+  import * as m from '../paraglide/messages.js'
+  import { locales } from '../paraglide/runtime.js'
+  import { AVAILABLE_THEMES, themeStore } from '../stores/theme-store.svelte.js'
+
+  interface Props { store: ManagementStore }
+  const { store }: Props = $props()
+  const languageOptions = $derived(locales.filter(locale => store.info?.supportedLocales.includes(locale)).map(locale => ({ value: locale, label: locale === 'zh-CN' ? '简体中文' : locale === 'ja-JP' ? '日本語' : 'English' })))
+  const themeOptions = $derived(AVAILABLE_THEMES.map(theme => ({ value: theme, label: theme === 'high-contrast' ? m.theme_high_contrast() : theme === 'formal' ? m.theme_formal() : getThemeInfo(theme)?.name ?? theme })))
+</script>
+
+<section class='grid w-full min-w-0 gap-4 xl:grid-cols-2' data-testid='settings-page'>
+  <PageHeader title={m.settings_title()} description={m.settings_description()} class='mb-0 xl:col-span-2' />
+  {#if store.user}
+    <Card class='xl:row-span-2' title={m.profile_title()} bordered shadow={false} data-guide='admin-profile-form'>
+      <div class='mb-5 flex flex-wrap items-center gap-3 border-b border-base-content/8 pb-4'>
+        <p class='min-w-0 break-all text-sm text-base-content/55'>@{store.user.username}</p>
+        <Badge size='sm' variant='ghost'>{store.user.roles.filter((code): code is import('{{fullstack.contractPackageName}}').AdminRoleCode => ['admin', 'audit_admin', 'config_admin', 'business_operator', 'user'].includes(code)).map(roleLabel).join(', ')}</Badge>
+      </div>
+      <UserProfile columns={2} user={store.user} editable alwaysEditable fields={['avatar', 'displayName', 'email']} avatarAccept='image/png,image/jpeg,image/webp' avatarHint={m.avatar_hint()} loading={store.saving} onsubmit={data => store.saveProfile(data)} onavatarchange={file => void store.uploadAvatar(file)} data-testid='profile-form' />
+    </Card>
+    <Card title={m.preferences_title()} bordered shadow={false} data-guide='admin-preferences'>
+      <p class='mb-5 text-sm text-base-content/50'>{m.preferences_description()}</p>
+      <FormLayout columns={2}>
+        <FormField label={m.settings_language()} for='profile-language'>
+          <Select id='profile-language' value={store.locale} options={languageOptions} disabled={store.saving} onchange={locale => void store.savePreferences({ locale })} data-testid='profile-language' />
+        </FormField>
+        <FormField label={m.settings_theme()} for='profile-theme'>
+          <Select id='profile-theme' value={themeStore.current} options={themeOptions} disabled={store.saving} onchange={theme => void store.savePreferences({ theme })} data-testid='profile-theme' />
+        </FormField>
+      </FormLayout>
+    </Card>
+    <Card title={m.password_title()} bordered shadow={false} data-guide='admin-password'>
+      <p class='mb-5 text-sm text-base-content/50'>{m.password_rules()}</p>
+      <ChangePasswordForm loading={store.saving} passwordPolicy={store.authConfig?.password} minPasswordLength={store.authConfig?.password.minLength ?? 8} onsubmit={data => store.changePassword(data)} data-testid='password-form' />
+    </Card>
+  {/if}
+</section>

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/pages/users.svelte.hbs

@@ -0,0 +1,216 @@
+<script lang='ts'>
+  import type { ChangePasswordFormData } from '@h-ai/ui'
+  import type { AdminRoleCode, AdminUser } from '{{fullstack.contractPackageName}}'
+  import type { ManagementStore } from '../stores/management-store.svelte.js'
+  import { Card, DataTable, FilterBar, FormField, FormLayout, Modal, PageHeader, Pagination, Skeleton } from '@h-ai/ui/components/compounds/index'
+  import { Avatar, Badge, BareInput, Button, Input, Select } from '@h-ai/ui/components/primitives/index'
+  import { ChangePasswordForm, PasswordInput } from '@h-ai/ui/components/scenes/iam/index'
+  import { AdminRoleCodeSchema } from '{{fullstack.contractPackageName}}'
+  import * as m from '../paraglide/messages.js'
+  import { roleLabel } from '../security/role-label.js'
+
+  interface Props { store: ManagementStore }
+  const { store }: Props = $props()
+
+  let editorOpen = $state(false)
+  let editing = $state<AdminUser | null>(null)
+  let deleting = $state<AdminUser | null>(null)
+  let resetting = $state<AdminUser | null>(null)
+  let username = $state('')
+  let displayName = $state('')
+  let email = $state('')
+  let password = $state('')
+  let invitation = $state(false)
+  let phone = $state('')
+  let role = $state<AdminRoleCode>('user')
+  let accountType = $state<'permanent' | 'temporary'>('permanent')
+  let accountStatus = $state<'active' | 'dormant' | 'closed'>('active')
+  let expiresAt = $state('')
+  const columns = $derived([
+    { key: 'username', sortable: true, label: m.user_account() },
+    { key: 'email', sortable: true, label: m.user_email() },
+    { key: 'roles', label: m.user_role() },
+    { key: 'accountStatus', sortable: true, label: m.account_state() },
+    { key: 'createdAt', sortable: true, label: m.created_at() },
+  ])
+  const roleOptions = $derived(AdminRoleCodeSchema.options.map(value => ({ value, label: roleLabel(value) })))
+  const statusOptions = $derived([{ value: 'all', label: m.all_statuses() }, { value: 'active', label: m.account_active() }, { value: 'dormant', label: m.account_dormant() }, { value: 'closed', label: m.account_closed() }])
+
+  function openEditor(user: AdminUser | null, useInvitation = false) {
+    editing = user
+    username = user?.username ?? ''
+    displayName = user?.displayName ?? ''
+    email = user?.email ?? ''
+    password = ''
+    invitation = useInvitation
+    phone = ''
+    role = user?.roles[0] ?? 'user'
+    accountType = user?.accountType ?? 'permanent'
+    accountStatus = user?.accountStatus ?? 'active'
+    expiresAt = user?.accountExpiresAt ? store.localDateTime(user.accountExpiresAt) : ''
+    store.error = ''
+    editorOpen = true
+  }
+
+  async function submit(event: SubmitEvent) {
+    event.preventDefault()
+    const fields = { displayName: displayName.trim(), role, accountType, accountStatus, accountExpiresAt: expiresAt ? new Date(expiresAt).toISOString() : null }
+    const saved = invitation && !editing
+      ? await store.inviteUser({ username: username.trim(), email: email.trim() || undefined, phone: phone.trim() || undefined, ...fields, accountStatus: 'active' })
+      : await store.saveUser(editing ? { id: editing.id, email: email.trim(), ...fields } : { username: username.trim(), password, email: email.trim() || undefined, ...fields })
+    if (saved) {
+      editorOpen = false
+      password = ''
+    }
+  }
+
+  async function confirmDelete() {
+    if (deleting && await store.deleteUser(deleting))
+      deleting = null
+  }
+
+  async function confirmReset(data: ChangePasswordFormData) {
+    if (resetting && await store.resetUserPassword(resetting, data.newPassword))
+      resetting = null
+  }
+
+  function upload(user: AdminUser, event: Event & { currentTarget: HTMLInputElement }) {
+    const file = event.currentTarget.files?.[0]
+    if (file)
+      void store.uploadAvatar(file, user.id)
+    event.currentTarget.value = ''
+  }
+</script>
+
+<section class='flex min-h-0 flex-1 flex-col gap-3' data-testid='users-page'>
+  <PageHeader title={m.nav_users()} description={m.users_description()} class='mb-0 shrink-0'>
+    {#snippet actions()}
+      {#if store.authConfig?.initialCredentials?.enabled}<Button variant='outline' size='sm' onclick={() => openEditor(null, true)} data-testid='invite-user'>{m.invitation_title()}</Button>{/if}
+      <Button variant='primary' size='sm' onclick={() => openEditor(null)} data-testid='create-user'>{m.user_create()}</Button>
+    {/snippet}
+  </PageHeader>
+  <div class='flex min-h-0 flex-1 flex-col overflow-hidden rounded-xl border border-base-content/8 bg-base-100'>
+    <form class='shrink-0 border-b border-base-content/8 p-3' onsubmit={(event) => {
+      event.preventDefault()
+      void store.queryUsers()
+    }}>
+      <FilterBar activeCount={store.usersStatus === 'all' ? 0 : 1} onreset={() => {
+        store.usersSearch = ''
+        store.usersStatus = 'all'
+        store.usersSortBy = 'createdAt'
+        store.usersSortDirection = 'desc'
+        void store.queryUsers()
+      }} data-testid='users-filters'>
+        {#snippet leading()}<div class='min-w-0 flex-1'><Input type='search' size='sm' bind:value={store.usersSearch} placeholder={m.users_search()} data-testid='users-search' /></div>{/snippet}
+        {#snippet actions()}<Button type='submit' submitHint size='sm' variant='outline' disabled={store.loading}>{m.search()}</Button>{/snippet}
+        <div class='w-full sm:w-40'><Select size='sm' bind:value={store.usersStatus} options={statusOptions} /></div>
+      </FilterBar>
+    </form>
+    <div class='hidden min-h-0 flex-1 overflow-auto md:flex md:flex-col'>
+      <DataTable data={store.users} {columns} keyField='id' loading={store.loading} striped={false} sortKey={store.usersSortBy} sortDir={store.usersSortDirection} onsort={(key, direction) => void store.sortUsers(key, direction)} class='min-h-0 flex-1 overflow-auto'>
+        {#snippet cell(user, key)}
+          {#if key === 'username'}
+            <div class='flex items-center gap-3'>
+              <Avatar name={user.displayName || user.username} src={user.avatarUrl} size='sm' />
+              <div><p class='font-medium'>{user.displayName || user.username}</p><p class='text-xs text-base-content/45'>@{user.username}</p></div>
+            </div>
+          {:else if key === 'roles'}
+            <Badge variant={user.roles.includes('admin') ? 'primary' : 'ghost'}>{user.roles.map(roleLabel).join(', ')}</Badge>
+          {:else if key === 'accountStatus'}
+            <Badge variant={user.accountStatus === 'active' ? 'success' : user.accountStatus === 'dormant' ? 'warning' : 'ghost'}>{user.accountStatus === 'active' ? m.account_active() : user.accountStatus === 'dormant' ? m.account_dormant() : m.account_closed()}</Badge>
+          {:else if key === 'createdAt'}
+            <span class='whitespace-nowrap text-xs text-base-content/60'>{store.formatDate(user.createdAt)}</span>
+          {:else if key === 'email'}
+            {user.email || '—'}
+          {/if}
+        {/snippet}
+        {#snippet actions(user)}
+          {@render userActions(user)}
+        {/snippet}
+      </DataTable>
+    </div>
+    <div class='min-h-0 flex-1 space-y-3 overflow-auto p-4 md:hidden' data-testid='user-cards'>
+      {#if store.loading}
+        <Skeleton count={3} />
+      {:else if store.users.length === 0}
+        <p class='py-8 text-center text-sm text-base-content/50'>{m.users_empty()}</p>
+      {:else}
+        {#each store.users as user (user.id)}
+          <Card bordered shadow={false}>
+            <div class='flex items-center gap-3'>
+              <Avatar name={user.displayName || user.username} src={user.avatarUrl} size='sm' />
+              <div class='min-w-0 flex-1'><p class='truncate font-medium'>{user.displayName || user.username}</p><p class='truncate text-xs text-base-content/45'>@{user.username}</p></div>
+              <Badge size='sm' variant={user.accountStatus === 'active' ? 'success' : user.accountStatus === 'dormant' ? 'warning' : 'ghost'}>{user.accountStatus === 'active' ? m.account_active() : user.accountStatus === 'dormant' ? m.account_dormant() : m.account_closed()}</Badge>
+            </div>
+            <p class='mt-3 truncate text-xs text-base-content/60' title={user.email}>{user.email || '—'}</p>
+            <div class='mt-3 flex flex-wrap items-center justify-between gap-2'>
+              <Badge size='sm' variant={user.roles.includes('admin') ? 'primary' : 'ghost'}>{user.roles.map(roleLabel).join(', ')}</Badge>
+              {@render userActions(user)}
+            </div>
+          </Card>
+        {/each}
+      {/if}
+    </div>
+    <div class='mt-auto shrink-0 border-t border-base-content/8 px-3 py-2'>
+      <Pagination page={store.usersPage} total={store.usersTotal} pageSize={store.pageSize} onchange={page => void store.loadUsers(page)} />
+    </div>
+  </div>
+</section>
+
+<Modal bind:open={editorOpen} title={editing ? m.user_edit() : invitation ? m.invitation_title() : m.user_create()} closeOnBackdrop={!store.saving} closeOnEscape={!store.saving} size='3xl' data-testid='user-editor'>
+  <form onsubmit={submit}>
+    {#if invitation}<p class='mb-4 text-sm text-base-content/60'>{m.invitation_hint()}</p>{/if}
+    <FormLayout columns={2} labelPosition='left' labelWidth='6rem'>
+      <FormField label={m.user_username()} required>
+        <Input bind:value={username} name='username' readonly={!!editing} required minlength={3} maxlength={64} pattern='[\w\-]+' autocomplete='off' data-testid='user-username' />
+      </FormField>
+      <FormField label={m.user_display_name()}><Input bind:value={displayName} maxlength={100} data-testid='user-display-name' /></FormField>
+      <FormField label={m.user_email()}><Input type='email' bind:value={email} data-testid='user-email' /></FormField>
+      {#if !editing && !invitation}
+        <FormField label={m.user_password()} hint={m.initial_password_rules({ min: store.authConfig?.password.minLength ?? 8 })} required><PasswordInput required bind:value={password} autocomplete='new-password' minLength={store.authConfig?.password.minLength ?? 8} data-testid='user-password' /></FormField>
+      {/if}
+      {#if invitation && store.authConfig?.passwordReset.mode === 'phone'}<FormField label={m.invitation_phone()} required><Input type='tel' bind:value={phone} required maxlength={32} data-testid='invite-phone' /></FormField>{/if}
+      <FormField label={m.account_type()}><Select bind:value={accountType} options={[{ value: 'permanent', label: m.account_permanent() }, { value: 'temporary', label: m.account_temporary() }]} data-testid='account-type' /></FormField>
+      <FormField label={m.account_state()}><Select bind:value={accountStatus} disabled={invitation || editing?.id === store.user?.id} options={[{ value: 'active', label: m.account_active() }, { value: 'dormant', label: m.account_dormant() }, { value: 'closed', label: m.account_closed() }]} data-testid='account-state' /></FormField>
+      <FormField label={m.account_expires()} required={accountType === 'temporary'}><Input type='datetime-local' bind:value={expiresAt} required={accountType === 'temporary'} data-testid='account-expires' /></FormField>
+      <FormField label={m.user_role()}><Select bind:value={role} options={roleOptions} disabled={editing?.id === store.user?.id} data-testid='user-role' /></FormField>
+      <div class='flex justify-end gap-2 border-t border-base-content/8 pt-4'>
+        <Button variant='ghost' disabled={store.saving} onclick={() => { editorOpen = false }}>{m.cancel()}</Button>
+        <Button type='submit' variant='primary' loading={store.saving} disabled={!editing && !invitation && password.length < (store.authConfig?.password.minLength ?? 8)} data-testid='user-save'>{m.save()}</Button>
+      </div>
+    </FormLayout>
+  </form>
+</Modal>
+
+{#snippet userActions(user: AdminUser)}
+  <div class='flex items-center gap-1' data-testid='user-actions' data-user={user.username}>
+    <Button size='xs' variant='ghost' disabled={store.saving} onclick={() => openEditor(user)}>{m.edit()}</Button>
+    <Button size='xs' variant='ghost' disabled={store.saving} onclick={() => { resetting = user }} data-testid='reset-user-password'>{m.user_password_reset()}</Button>
+    <label class='cursor-pointer rounded-lg px-2 py-1.5 text-xs text-primary hover:bg-primary/5'>
+      {m.avatar_upload()}
+      <BareInput type='file' class='sr-only' accept='image/png,image/jpeg,image/webp' disabled={store.saving} onchange={event => upload(user, event)} data-testid='user-avatar-input' />
+    </label>
+    <Button size='xs' variant='ghost' class='text-error' disabled={user.id === store.user?.id || store.saving} onclick={() => { deleting = user }}>{m.delete()}</Button>
+  </div>
+{/snippet}
+
+<Modal open={!!deleting} title={m.user_delete_title()} onclose={() => { deleting = null }} closeOnBackdrop={!store.saving} closeOnEscape={!store.saving}>
+  <p class='text-sm leading-6 text-base-content/70'>{m.user_delete_confirm({ name: deleting?.displayName || deleting?.username || '' })}</p>
+  {#snippet footer()}
+    <Button variant='ghost' disabled={store.saving} onclick={() => { deleting = null }}>{m.cancel()}</Button>
+    <Button variant='error' loading={store.saving} onclick={confirmDelete} data-testid='confirm-delete-user'>{m.delete()}</Button>
+  {/snippet}
+</Modal>
+
+<Modal open={!!resetting} title={m.user_password_reset()} onclose={() => { resetting = null }} closeOnBackdrop={!store.saving} closeOnEscape={!store.saving} data-testid='password-reset-dialog'>
+  {#if resetting}
+    {#key resetting.id}
+      <p class='text-sm leading-6 text-base-content/70'>{m.user_password_reset_hint({ name: resetting?.displayName || resetting?.username || '' })}</p>
+      {#if store.authConfig?.password.requireInitialChange}<p class='text-sm leading-6 text-base-content/70'>{m.user_password_reset_initial_hint()}</p>{/if}
+      <ChangePasswordForm requireOldPassword={false} loading={store.saving} passwordPolicy={store.authConfig?.password} minPasswordLength={store.authConfig?.password.minLength ?? 8} submitText={m.user_password_reset()} onsubmit={confirmReset} class='mt-4' data-testid='admin-password-reset-form' />
+    {/key}
+  {/if}
+  {#snippet footer()}
+    <Button variant='ghost' disabled={store.saving} onclick={() => { resetting = null }}>{m.cancel()}</Button>
+  {/snippet}
+</Modal>

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/security/role-label.ts.hbs

@@ -0,0 +1,12 @@
+import type { AdminRoleCode } from '{{fullstack.contractPackageName}}'
+import * as m from '../paraglide/messages.js'
+
+export function roleLabel(code: AdminRoleCode): string {
+  const labels = { admin: m.role_admin, audit_admin: m.role_audit, config_admin: m.role_config, business_operator: m.role_operator, user: m.role_user }
+  return labels[code]()
+}
+
+export function roleCapabilities(code: AdminRoleCode): string {
+  const labels = { admin: m.role_admin_capabilities, audit_admin: m.role_audit_capabilities, config_admin: m.role_config_capabilities, business_operator: m.role_operator_capabilities, user: m.role_user_capabilities }
+  return labels[code]()
+}

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/stores/guide-store.ts.hbs

@@ -0,0 +1,55 @@
+import type { NavAdapter } from '@h-ai/ui'
+import type { ManagementStore } from './management-store.svelte.js'
+import { createGuide } from '@h-ai/ui/guide'
+import * as m from '../paraglide/messages.js'
+
+/** Web/App/Desktop 共用内容；宿主只提供当前页面和平台持久化方式。 */
+export function createManagementGuide(store: ManagementStore, platform: 'web' | 'app' | 'desktop') {
+  const nav: NavAdapter = {
+    get pathname() {
+      return `/${store.page}`
+    },
+    navigate(route) {
+      if (route === '/settings')
+        return store.navigate('settings')
+    },
+  }
+  return createGuide({
+    nav,
+    persistKey: '{{projectName}}-guide',
+    persistence: platform === 'web' ? 'cookie' : 'localStorage',
+    tours: [{
+      id: 'overview',
+      title: () => m.guide_overview_title(),
+      description: () => m.guide_overview_description(),
+      steps: [
+        { target: 'admin-content', title: () => m.guide_content_title(), description: () => m.guide_content_description() },
+        { target: 'admin-profile', title: () => m.guide_profile_title(), description: () => m.guide_profile_description() },
+        { target: 'admin-help', title: () => m.guide_help_title(), description: () => m.guide_help_description() },
+      ],
+    }, {
+      id: 'profile',
+      title: () => m.guide_profile_tour_title(),
+      description: () => m.guide_profile_tour_description(),
+      route: '/settings',
+      steps: [
+        { target: 'admin-profile-form', title: () => m.guide_profile_title(), description: () => m.guide_profile_form_description() },
+        { target: 'admin-preferences', title: () => m.preferences_title(), description: () => m.guide_preferences_description() },
+        { target: 'admin-password', title: () => m.guide_password_title(), description: () => m.guide_password_description() },
+      ],
+    }],
+    articles: [{
+      id: 'overview',
+      title: () => m.guide_overview_title(),
+      description: () => m.guide_overview_description(),
+      content: () => m.guide_overview_article(),
+      tourId: 'overview',
+    }, {
+      id: 'profile',
+      title: () => m.guide_profile_tour_title(),
+      description: () => m.guide_profile_tour_description(),
+      content: () => m.guide_profile_article(),
+      tourId: 'profile',
+    }],
+  })
+}