feat(recommendations): collect demographics and advance age cohorts

apps/mobile/src/app/(tabs)/index.tsx

@@ -9,6 +9,7 @@ import { player } from '../../player/controller';
 import { usePlayerState } from '../../player/hooks';
 import { useColors } from '../../theme';
 import { ErrorBox, Icon, Screen, useErrorText, type IconName } from '../../ui/kit';
+import { OnboardingGate } from '../../ui/Onboarding';
 import { WaveOrb } from '../../ui/wave/WaveOrb';
 
 /** Имена из /wave/options (Material Symbols) → MaterialIcons. */
@@ -22,6 +23,10 @@ function iconFor(name: string): IconName {
  * На Android спектр недоступен, поэтому пульс берётся из BPM и energy трека (docs/mobile.md).
  */
 export default function HomeScreen() {
+  return <OnboardingGate><WaveHome /></OnboardingGate>;
+}
+
+function WaveHome() {
   const colors = useColors();
   const { t } = useTranslation();
   const tr = t as unknown as (k: string) => string;

apps/mobile/src/app/(tabs)/profile.tsx

@@ -15,6 +15,7 @@ import { player } from '../../player/controller';
 import { radius, useColors } from '../../theme';
 import { Button, H1, Icon, Muted, Screen, Segmented } from '../../ui/kit';
 import { useDownloads } from '../../ui/downloads';
+import { RecommendationSettings } from '../../ui/Onboarding';
 import { PasswordSheet, QualitySheet, useQualityPrefs } from '../../ui/settings';
 import { useUpdateState } from '../../ui/UpdateDialog';
 
@@ -74,6 +75,8 @@ export default function ProfileScreen() {
           @{user.username} · {t(`roles.${user.role}`)}
         </Muted>
 
+        <RecommendationSettings />
+
         <Section>
           <Row label={t('language.label')}>
             <Segmented<Locale>

apps/mobile/src/ui/Onboarding.tsx

@@ -0,0 +1,85 @@
+import type { components } from '@pipu/api-client';
+import { AGE_GROUPS, GENDERS, unwrap } from '@pipu/core';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useState, type ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+import { ActivityIndicator, Pressable, ScrollView, Text, View } from 'react-native';
+
+import { useSession, useSessionCtx, useUser } from '../lib/session';
+import { useColors } from '../theme';
+import { Button, ErrorBox, H1, Muted, Screen, useErrorText } from './kit';
+
+type Options = components['schemas']['Onboarding'];
+type Choice = components['schemas']['OnboardingChoice'];
+
+function useOnboarding() {
+  const session = useSession();
+  const user = useUser();
+  const { server } = useSessionCtx();
+  return useQuery({ queryKey: ['onboarding', server, user.id],
+    queryFn: async () => unwrap(await session.client.GET('/api/v1/onboarding')),
+    staleTime: 0, refetchInterval: 30_000 });
+}
+
+export function OnboardingGate({ children }: { children: ReactNode }) {
+  const query = useOnboarding();
+  const client = useQueryClient();
+  if (query.isPending) return <Screen><ActivityIndicator /></Screen>;
+  if (!query.data?.required) return <>{children}</>;
+  return <Screen><ScrollView contentContainerStyle={{ padding: 16 }}>
+    <Onboarding options={query.data} onDone={() => void client.invalidateQueries({ queryKey: ['onboarding'] })} />
+  </ScrollView></Screen>;
+}
+
+export function RecommendationSettings() {
+  const { t } = useTranslation();
+  const query = useOnboarding();
+  const client = useQueryClient();
+  const [editing, setEditing] = useState(false);
+  const errorText = useErrorText();
+  return <View>
+    {editing && query.data ? <Onboarding key={JSON.stringify(query.data.choice)} options={query.data} editing onDone={() => {
+      setEditing(false); void client.invalidateQueries({ queryKey: ['onboarding'] });
+    }} /> : <Button title={t('onboarding.edit')} variant="secondary" busy={query.isFetching} onPress={() => { void query.refetch().then((result) => { if (result.data && !result.error) setEditing(true); }); }} />}
+    <ErrorBox>{query.error ? errorText(query.error) : null}</ErrorBox>
+  </View>;
+}
+
+function Onboarding({ options, onDone, editing = false }: { options: Options; onDone: () => void; editing?: boolean }) {
+  const { t } = useTranslation();
+  const session = useSession();
+  const errorText = useErrorText();
+  const [choice, setChoice] = useState<Choice>(options.choice ?? { artist_ids: [], genres: [], gender: null, age_group: null });
+  const save = useMutation({ mutationFn: async (skip: boolean) => unwrap(await session.client.PUT('/api/v1/me/onboarding', {
+    body: skip ? { artist_ids: [], genres: [], gender: null, age_group: null } : choice,
+  })), onSuccess: onDone });
+  const toggle = (key: 'artist_ids' | 'genres', value: string) => setChoice((old) => ({ ...old,
+    [key]: old[key].includes(value) ? old[key].filter((x) => x !== value) : [...old[key], value],
+  }));
+  return <View style={{ gap: 20 }}>
+    <H1>{t('onboarding.title')}</H1><Muted>{t('onboarding.subtitle')}</Muted>
+    <Choices title={t('onboarding.gender')} items={[{ value: '', label: t('onboarding.unspecified') }, ...GENDERS.map((g) => ({ value: g, label: t(`onboarding.genders.${g}`) }))]}
+      selected={[choice.gender ?? '']} onPick={(v) => setChoice((old) => ({ ...old, gender: (v || null) as Choice['gender'] }))} />
+    <Choices title={t('onboarding.age_group')} items={[{ value: '', label: t('onboarding.unspecified') }, ...AGE_GROUPS.map((g) => ({ value: g, label: t(`onboarding.ages.${g}`) }))]}
+      selected={[choice.age_group ?? '']} onPick={(v) => setChoice((old) => ({ ...old, age_group: (v || null) as Choice['age_group'] }))} />
+    <Muted>{t('onboarding.age_hint')}</Muted>
+    <Choices title={t('onboarding.artists')} items={options.artists.map((a) => ({ value: a.id, label: a.name }))} selected={choice.artist_ids} onPick={(v) => toggle('artist_ids', v)} />
+    <Choices title={t('onboarding.genres')} items={options.genres.map((g) => ({ value: g.name, label: g.name }))} selected={choice.genres} onPick={(v) => toggle('genres', v)} />
+    <ErrorBox>{save.error ? errorText(save.error) : null}</ErrorBox>
+    <Button title={t(editing ? 'settings.save' : 'onboarding.done')} busy={save.isPending} onPress={() => save.mutate(false)} />
+    <Button title={t(editing ? 'form.cancel' : 'onboarding.skip')} variant="ghost" disabled={save.isPending} onPress={() => editing ? onDone() : save.mutate(true)} />
+  </View>;
+}
+
+function Choices({ title, items, selected, onPick }: { title: string; items: { value: string; label: string }[]; selected: string[]; onPick: (value: string) => void }) {
+  const colors = useColors();
+  return <View style={{ gap: 10 }}><Text style={{ color: colors.text, fontWeight: '600' }}>{title}</Text>
+    <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 8 }}>{items.map((item) => {
+      const on = selected.includes(item.value);
+      return <Pressable key={item.value} accessibilityRole="button" accessibilityState={{ selected: on }} onPress={() => onPick(item.value)}
+        style={{ padding: 12, borderRadius: 20, backgroundColor: on ? colors['accent-fill'] : colors.surface2 }}>
+        <Text style={{ color: on ? '#fff' : colors.text }}>{item.label}</Text>
+      </Pressable>;
+    })}</View>
+  </View>;
+}

apps/web/e2e/scenarios.spec.ts

@@ -48,6 +48,15 @@ test('settings expose crossfade and loudness normalization', async ({ page }) =>
   const slider = page.getByRole('slider', { name: /Кроссфейд/ });
   await slider.fill('4');
   await expect(page.getByText('Кроссфейд, 4 с')).toBeVisible();
+  await page.getByRole('button', { name: 'Настроить рекомендации' }).click();
+  await page.getByRole('button', { name: 'Мужской', exact: true }).click();
+  await page.getByRole('button', { name: '13–19', exact: true }).click();
+  const form = page.getByRole('heading', { name: 'Что вы любите слушать?' }).locator('../..');
+  await form.getByRole('button', { name: 'Сохранить', exact: true }).click();
+  await page.getByRole('button', { name: 'Настроить рекомендации' }).click();
+  await expect(page.getByRole('button', { name: 'Мужской', exact: true })).toHaveAttribute('aria-pressed', 'true');
+  await expect(page.getByRole('button', { name: '13–19', exact: true })).toHaveAttribute('aria-pressed', 'true');
+
 });
 test('9. login page switches between Russian and English', async ({ page }) => {
   await page.goto('/login');

apps/web/src/App.test.tsx

@@ -479,3 +479,30 @@ describe('playlists', () => {
     expect(api.playlists.get(item.id)?.name).toBe('Другое устройство');
   });
 });
+
+
+describe('recommendation preferences', () => {
+  it('saves demographics, edits the age group and asks again after an admin reset', async () => {
+    const admin = makeUser('owner', 'admin');
+    const { user, api, router, session } = await renderApp([admin], '/settings', { signedInAs: admin });
+    await user.click(await screen.findByRole('button', { name: 'Настроить рекомендации' }));
+    await user.click(await screen.findByRole('button', { name: 'Мужской' }));
+    await user.click(screen.getByRole('button', { name: '13–19' }));
+    await user.click(screen.getAllByRole('button', { name: 'Сохранить' }).find((b) => !b.hasAttribute('disabled'))!);
+    await screen.findByRole('button', { name: 'Настроить рекомендации' });
+    expect(api.calls.filter((c) => c.path === '/api/v1/me/onboarding').at(-1)?.body).toMatchObject({ gender: 'male', age_group: '13_19' });
+    await user.click(screen.getByRole('button', { name: 'Настроить рекомендации' }));
+    expect(await screen.findByRole('button', { name: '13–19' })).toHaveAttribute('aria-pressed', 'true');
+    await user.click(screen.getByRole('button', { name: '20–29' }));
+    await user.click(screen.getAllByRole('button', { name: 'Сохранить' }).find((b) => !b.hasAttribute('disabled'))!);
+    await screen.findByRole('button', { name: 'Настроить рекомендации' });
+    await session.client.POST('/api/v1/admin/users/{id}/reset-recommendations', { params: { path: { id: admin.id } } });
+    await router.navigate({ to: '/' });
+    await screen.findByRole('heading', { name: 'Что вы любите слушать?' });
+    expect(screen.getByRole('button', { name: 'Мужской' })).toHaveAttribute('aria-pressed', 'false');
+    expect(screen.getByRole('button', { name: '20–29' })).toHaveAttribute('aria-pressed', 'false');
+    await user.click(screen.getByRole('button', { name: 'Пропустить' }));
+    await screen.findByRole('button', { name: 'Запустить «Мою волну»' });
+    expect(api.calls.filter((c) => c.path === '/api/v1/me/onboarding').at(-1)?.body).toEqual({ artist_ids: [], genres: [], gender: null, age_group: null });
+  });
+});

apps/web/src/pages/HomePage.tsx

@@ -52,7 +52,8 @@ export function HomePage() {
   const onboarding = useQuery({
     queryKey: ['onboarding'],
     queryFn: async () => unwrap(await session.client.GET('/api/v1/onboarding')),
-    staleTime: Infinity,
+    staleTime: 0,
+    refetchInterval: 30_000,
   });
   if (onboarding.isPending) {
     return (

apps/web/src/pages/Onboarding.tsx

@@ -1,5 +1,5 @@
 import type { components } from '@pipu/api-client';
-import { unwrap } from '@pipu/core';
+import { AGE_GROUPS, GENDERS, unwrap } from '@pipu/core';
 import { useMutation } from '@tanstack/react-query';
 import { useState } from 'react';
 import { useTranslation } from 'react-i18next';
@@ -20,17 +20,19 @@ const MIN_ARTISTS = 3;
  * Онбординг вкуса (docs/recommendations.md#7): исполнители и жанры библиотеки — начальный вкус «Моей волны»,
  * пока своей истории почти нет. Пропуск тоже запоминается: второй раз не спросим.
  */
-export function Onboarding({ options, onDone }: { options: Options; onDone: () => void }) {
+export function Onboarding({ options, onDone, editing = false }: { options: Options; onDone: () => void; editing?: boolean }) {
   const { t } = useTranslation();
   const session = useSession();
   const errorText = useErrorText();
-  const [artists, setArtists] = useState<Set<string>>(new Set());
-  const [genres, setGenres] = useState<Set<string>>(new Set());
+  const [artists, setArtists] = useState<Set<string>>(new Set(options.choice?.artist_ids));
+  const [genres, setGenres] = useState<Set<string>>(new Set(options.choice?.genres));
+  const [gender, setGender] = useState(options.choice?.gender ?? null);
+  const [ageGroup, setAgeGroup] = useState(options.choice?.age_group ?? null);
   const save = useMutation({
     mutationFn: async (skip: boolean) =>
       unwrap(
         await session.client.PUT('/api/v1/me/onboarding', {
-          body: skip ? { artist_ids: [], genres: [] } : { artist_ids: [...artists], genres: [...genres] },
+          body: skip ? { artist_ids: [], genres: [], gender: null, age_group: null } : { artist_ids: [...artists], genres: [...genres], gender, age_group: ageGroup },
         }),
       ),
     onSuccess: onDone,
@@ -43,7 +45,7 @@ export function Onboarding({ options, onDone }: { options: Options; onDone: () =
       else next.add(key);
       return next;
     });
-  const enough = artists.size >= MIN_ARTISTS || (artists.size > 0 && genres.size > 0);
+  const enough = editing || artists.size >= MIN_ARTISTS || (artists.size > 0 && genres.size > 0) || !!gender || !!ageGroup || options.artists.length === 0;
 
   return (
     <div className={s.page}>
@@ -52,6 +54,21 @@ export function Onboarding({ options, onDone }: { options: Options; onDone: () =
         <p>{t('onboarding.subtitle')}</p>
       </header>
 
+      <section aria-label={t('onboarding.gender')}>
+        <h2 className={s.label}>{t('onboarding.gender')}</h2>
+        <div className={s.genres}>
+          <button type="button" className={s.genre} aria-pressed={!gender} onClick={() => setGender(null)}>{t('onboarding.unspecified')}</button>
+          {GENDERS.map((g) => <button type="button" key={g} className={s.genre} aria-pressed={gender === g} onClick={() => setGender(g)}>{t(`onboarding.genders.${g}`)}</button>)}
+        </div>
+      </section>
+      <section aria-label={t('onboarding.age_group')}>
+        <h2 className={s.label}>{t('onboarding.age_group')}</h2>
+        <p>{t('onboarding.age_hint')}</p>
+        <div className={s.genres}>
+          <button type="button" className={s.genre} aria-pressed={!ageGroup} onClick={() => setAgeGroup(null)}>{t('onboarding.unspecified')}</button>
+          {AGE_GROUPS.map((g) => <button type="button" key={g} className={s.genre} aria-pressed={ageGroup === g} onClick={() => setAgeGroup(g)}>{t(`onboarding.ages.${g}`)}</button>)}
+        </div>
+      </section>
       <section aria-label={t('onboarding.artists')}>
         <h2 className={s.label}>{t('onboarding.artists')}</h2>
         <div className={s.artists}>
@@ -101,11 +118,11 @@ export function Onboarding({ options, onDone }: { options: Options; onDone: () =
 
       <FormError>{save.error ? errorText(save.error) : null}</FormError>
       <div className={s.actions}>
-        <Button variant="ghost" busy={save.isPending && save.variables} onClick={() => save.mutate(true)}>
-          {t('onboarding.skip')}
+        <Button variant="ghost" disabled={save.isPending} busy={save.isPending && save.variables} onClick={() => editing ? onDone() : save.mutate(true)}>
+          {t(editing ? 'form.cancel' : 'onboarding.skip')}
         </Button>
-        <Button variant="primary" busy={save.isPending && !save.variables} disabled={!enough} onClick={() => save.mutate(false)}>
-          {enough ? t('onboarding.done') : t('onboarding.pick_more', { count: MIN_ARTISTS - artists.size })}
+        <Button variant="primary" busy={save.isPending && !save.variables} disabled={!enough || save.isPending} onClick={() => save.mutate(false)}>
+          {enough ? t(editing ? 'settings.save' : 'onboarding.done') : t('onboarding.pick_more', { count: MIN_ARTISTS - artists.size })}
         </Button>
       </div>
     </div>

apps/web/src/pages/SettingsPage.tsx

@@ -12,6 +12,7 @@ import { formatDateTime } from '../shared/lib/format';
 import { Button, Field, FormError, Segmented } from '../shared/ui/ui';
 import { LanguageSwitch } from '../widgets/LanguageSwitch';
 import s from './page.module.css';
+import { Onboarding } from './Onboarding';
 
 type Theme = NonNullable<components['schemas']['UiPrefs']['theme']>;
 type WaveVariant = NonNullable<components['schemas']['UiPrefs']['wave_variant']>;
@@ -24,6 +25,7 @@ export function SettingsPage() {
         <h1>{t('settings.title')}</h1>
       </div>
       <ProfileSection />
+      <RecommendationSettings />
       <AppearanceSection />
       <PasswordSection />
       <SessionsSection />
@@ -357,3 +359,17 @@ function SessionsSection() {
     </section>
   );
 }
+
+function RecommendationSettings() {
+  const { t } = useTranslation();
+  const session = useSession();
+  const queryClient = useQueryClient();
+  const [editing, setEditing] = useState(false);
+  const errorText = useErrorText();
+  const options = useQuery({ queryKey: ['onboarding'], queryFn: async () => unwrap(await session.client.GET('/api/v1/onboarding')), staleTime: 0 });
+  return <section className={s.section}>
+    {editing && options.data ? <Onboarding key={JSON.stringify(options.data.choice)} options={options.data} editing onDone={() => { setEditing(false); void queryClient.invalidateQueries({ queryKey: ['onboarding'] }); }} />
+      : <Button busy={options.isFetching} onClick={() => { void options.refetch().then((result) => { if (result.data && !result.error) setEditing(true); }); }}>{t('onboarding.edit')}</Button>}
+    <FormError>{options.error ? errorText(options.error) : null}</FormError>
+  </section>;
+}

apps/web/src/test/fakeApi.ts

@@ -70,6 +70,7 @@ export function makeUser(username: string, role: Role, extra: Partial<FakeUser>
  */
 export function fakeApi(initial: FakeUser[]) {
   const users = new Map(initial.map((u) => [u.id, { ...u }]));
+  const onboarding = new Map<string, components['schemas']['OnboardingChoice'] | null>();
   const prefs = new Map<string, components['schemas']['UiPrefs']>();
   let current: string | null = null; // id вошедшего (одна сессия на тест)
   let token = 0;
@@ -206,7 +207,10 @@ export function fakeApi(initial: FakeUser[]) {
       case 'POST /api/v1/uploads/seen':
         return new Response(null, { status: 204 });
       case 'GET /api/v1/onboarding':
-        return json({ required: false, artists: [], genres: [] });
+        return json({ required: onboarding.get(user!.id) === null, artists: [], genres: [], choice: onboarding.get(user!.id) ?? undefined });
+      case 'PUT /api/v1/me/onboarding':
+        onboarding.set(user!.id, body as components['schemas']['OnboardingChoice']);
+        return new Response(null, { status: 204 });
       case 'GET /api/v1/me/likes':
       case 'GET /api/v1/me/dislikes':
       case 'GET /api/v1/me/history':
@@ -285,8 +289,10 @@ export function fakeApi(initial: FakeUser[]) {
       case `GET /api/v1/artists/${kino.id}/albums`:
         return json({ items: [albumSummary] });
     }
-    if (req.method === 'POST' && /^\/api\/v1\/admin\/users\/[^/]+\/reset-recommendations$/.test(path))
+    if (req.method === 'POST' && /^\/api\/v1\/admin\/users\/[^/]+\/reset-recommendations$/.test(path)) {
+      onboarding.set(path.split('/')[5]!, null);
       return new Response(null, { status: 204 });
+    }
     const userPath = /^\/api\/v1\/admin\/users\/([^/]+)$/.exec(path);
     if (userPath && req.method === 'PATCH') {
       if (!user || user.role === 'user') return problem(403, 'auth.forbidden');