feat(client): i18n copy + reco lang refresh + home polish

- 从仓库移除 __pycache__/ 与 *.pyc 等运行产物，避免 git pull 覆盖未跟踪文件导致合并失败
- 在 .gitignore 增加 Python 运行产物忽略规则

.cursor/commands/myspec.code.md

@@ -2,3 +2,4 @@
 客户端请按照标准的RN架构目录写代码
 后端请按照标准的python FastAPI 架构目录写代码
 现在多语言仅支持 EN / TC
+整个task.md执行完毕后需要在对应的overview.md标记，并且说明变更的文件名

.cursor/commands/myspec.task.md

@@ -2,3 +2,4 @@
 根据对应的plan.md 生成task.md
 任务清单详细可执行 
 执行完要标记
+整个task.md执行完毕后需要在对应的overview.md标记

.cursor/commands/myspec.test.md

@@ -0,0 +1 @@
+使用测试工具完成集成测试，并给我一份简单的测试报告

.cursor/rules/rule.mdc

@@ -28,4 +28,5 @@ modules/ 可嵌套 modules/，每层都独立规范。
 输出时根据这个结构生成内容时，请保持文件职责清晰。
 简短记录项目的该层每个spec的内容 ，每次编码完成后更新overview.md
 可以通过nvm 切换node版本
+在对数据库操作中，禁止执行破坏性操作，如果必须请让我同意，并回复：允许操作数据库
 

.gitignore

@@ -4,6 +4,10 @@
 .DS_Store
 *.pem
 
+# Python（运行产物）
+__pycache__/
+*.py[cod]
+
 # Node / JS
 node_modules/
 npm-debug.*

client/app.json

@@ -1,11 +1,11 @@
 {
   "expo": {
-    "name": "Hey Mama",
+    "name": "client",
-    "slug": "hey-mama",
+    "slug": "client",
     "version": "1.0.0",
     "orientation": "portrait",
     "icon": "./assets/images/icon.png",
-    "scheme": "heymama",
+    "scheme": "client",
     "userInterfaceStyle": "automatic",
     "newArchEnabled": true,
     "splash": {
@@ -15,7 +15,7 @@
     },
     "ios": {
       "supportsTablet": true,
-      "bundleIdentifier": "com.heymama.app"
+      "bundleIdentifier": "com.anonymous.client"
     },
     "android": {
       "adaptiveIcon": {

client/app/(app)/home.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useLayoutEffect, useMemo, useState, useCallback, useRef } from 'react';
-import { StyleSheet, View, Dimensions, Text, Pressable, PanResponder, Animated as RNAnimated } from 'react-native';
+import { StyleSheet, View, Dimensions, Text, Pressable, PanResponder, Animated as RNAnimated, ImageBackground } from 'react-native';
 import { useTranslation } from 'react-i18next';
 import { useNavigation, useFocusEffect } from 'expo-router';
 import Animated, {
@@ -18,9 +18,16 @@ import {
   getUserProfile,
   setReaction,
   setThemeMode,
+  getRecoFeedCache,
+  setRecoFeedCache,
+  getUserProfileScoring,
+  getRecoFeedHistory,
+  recordRecoFeedServed,
   type ThemeMode,
 } from '@/src/storage/appStorage';
 
+import { fetchRecoFeed } from '@/src/services/recoApi';
+
 import ProfileModal from '@/components/home/ProfileModal';
 import ThemeModal from '@/components/home/ThemeModal';
 
@@ -31,8 +38,46 @@ import LikeIcon from '@/assets/images/icon/like_icon.svg';
 
 const { height: SCREEN_HEIGHT } = Dimensions.get('window');
 
+// 预定义风景图列表
+const NATURE_IMAGES = [
+  require('@/assets/theme/nature/1.png'),
+  require('@/assets/theme/nature/2.png'),
+  require('@/assets/theme/nature/3.png'),
+  require('@/assets/theme/nature/4.png'),
+  require('@/assets/theme/nature/5.png'),
+  require('@/assets/theme/nature/6.png'),
+  require('@/assets/theme/nature/7.png'),
+  require('@/assets/theme/nature/8.png'),
+  require('@/assets/theme/nature/9.png'),
+  require('@/assets/theme/nature/10.png'),
+  require('@/assets/theme/nature/11.png'),
+  require('@/assets/theme/nature/12.png'),
+  require('@/assets/theme/nature/13.png'),
+  require('@/assets/theme/nature/14.png'),
+  require('@/assets/theme/nature/15.png'),
+  require('@/assets/theme/nature/17.png'),
+  require('@/assets/theme/nature/18.png'),
+  require('@/assets/theme/nature/19.png'),
+  require('@/assets/theme/nature/20.png'),
+  require('@/assets/theme/nature/22.png'),
+];
+
+// 预定义颜色列表
+const THEME_COLORS = [
+  '#F7D9BF',
+  '#CBF2D8',
+  '#F5CDDE',
+  '#F2ECCB',
+  '#E2CBF2',
+  '#CBD9F2',
+];
+
+type FeedItem = { content_id: string; text: string };
+
 export default function HomeScreen() {
-  const { t } = useTranslation();
+  const { t, i18n } = useTranslation();
+  const isEnglish = i18n.language?.startsWith('en');
+  const recoLang: 'en' | 'tc' = i18n.language?.toLowerCase().startsWith('zh') ? 'tc' : 'en';
   const navigation = useNavigation();
   const [index, setIndex] = useState(0);
   const [themeMode, setThemeModeState] = useState<ThemeMode>('scenery');
@@ -41,37 +86,137 @@ export default function HomeScreen() {
   const [profileName, setProfileName] = useState<string | undefined>(undefined);
   const [busy, setBusy] = useState(false);
   const [likeFilled, setLikeFilled] = useState(false);
+  const [feedItems, setFeedItems] = useState<FeedItem[]>([]);
+  const [isFetching, setIsFetching] = useState(false);
 
-  const item = useMemo(() => MOCK_CONTENT[index % MOCK_CONTENT.length], [index]);
+  // 解决语言切换时重复触发拉取/清空导致“文案不停跳动”的问题：
+  // 用 ref 持有最新状态，避免 useCallback 依赖 feedItems/isFetching 造成函数 identity 变化 → effect 重复执行
+  const feedItemsRef = useRef<FeedItem[]>([]);
+  const isFetchingRef = useRef(false);
+  useEffect(() => {
+    feedItemsRef.current = feedItems;
+  }, [feedItems]);
+  useEffect(() => {
+    isFetchingRef.current = isFetching;
+  }, [isFetching]);
 
   // 动画相关 Shared Values
   const translateY = useSharedValue(0);
   const opacity = useSharedValue(1);
   const likeScale = useSharedValue(1);
 
-  // 每次进入页面或页面获得焦点时刷新个人信息
+  // 统一文案对象结构
+  const currentFeed = useMemo(() => {
+    if (feedItems.length > 0) {
+      return feedItems;
+    }
+    return MOCK_CONTENT.map(item => ({
+      content_id: item.id,
+      text: t(item.textKey)
+    }));
+  }, [feedItems, t]);
+
+  const item = useMemo(() => {
+    const data = currentFeed[index % currentFeed.length];
+    return {
+      id: String(data.content_id),
+      text: data.text
+    };
+  }, [currentFeed, index]);
+
+  // 异步拉取新文案
+  const fetchNewFeed = useCallback(async () => {
+    if (isFetchingRef.current) return;
+    isFetchingRef.current = true;
+    setIsFetching(true);
+    try {
+      const scoringProfile = await getUserProfileScoring();
+      if (!scoringProfile) return;
+
+      const history = await getRecoFeedHistory();
+      
+      const { items, meta } = await fetchRecoFeed({
+        k: 30,
+        user_profile: scoringProfile,
+        already_recommended_ids: history.already_recommended_ids,
+        touched_or_viewed_ids: history.touched_or_viewed_ids,
+      });
+
+      if (items.length > 0) {
+        const wasEmpty = feedItemsRef.current.length === 0;
+        const newCache = {
+          saved_at: new Date().toISOString(),
+          lang: recoLang,
+          items: items.map((x) => ({ content_id: x.content_id, text: x.text })),
+          meta: meta as Record<string, unknown>,
+        };
+        await setRecoFeedCache(newCache);
+        await recordRecoFeedServed(items.map((x) => x.content_id));
+        setFeedItems(newCache.items.map((x) => ({ content_id: String(x.content_id), text: x.text })));
+        // 如果当前是 mock 数据，切换到新数据的第一条
+        if (wasEmpty) {
+          setIndex(0);
+        }
+      }
+    } catch (error) {
+      console.error('Failed to fetch new feed:', error);
+    } finally {
+      isFetchingRef.current = false;
+      setIsFetching(false);
+    }
+  }, [recoLang]);
+
+  // 每次进入页面或页面获得焦点时刷新个人信息和缓存文案
   useFocusEffect(
     useCallback(() => {
       let cancelled = false;
       (async () => {
         const mode = await getThemeMode();
         const profile = await getUserProfile();
+        const cache = await getRecoFeedCache();
+
         if (cancelled) return;
         setThemeModeState(mode);
         setProfileName(profile.name);
+        
+        // 语言切换时：旧语言缓存不复用，触发重新拉取
+        if (cache && cache.items.length > 0 && (cache.lang ?? 'en') === recoLang) {
+          setFeedItems(cache.items.map((x) => ({ content_id: String(x.content_id), text: x.text })));
+        } else {
+          // 语言不匹配或没有缓存：先清空回落到本地 mock（会立即随语言切换），再拉取对应语言的推荐文案
+          setFeedItems([]);
+          setIndex(0);
+          fetchNewFeed();
+        }
       })();
       return () => {
         cancelled = true;
       };
-    }, [])
+    }, [fetchNewFeed, recoLang])
   );
 
-  const backgroundColor = themeMode === 'color' ? '#F3D0E1' : '#F4D6C2';
+  const backgroundColor = useMemo(() => {
+    if (themeMode === 'color') {
+      const colorIndex = Math.floor(index / 10) % THEME_COLORS.length;
+      return THEME_COLORS[colorIndex];
+    }
+    return '#F4D6C2'; // 风景模式下的默认底色（图片加载前显示）
+  }, [themeMode, index]);
+
+  // 计算当前应该显示的风景图索引（滑动 10 次切换一张）
+  const natureImageIndex = useMemo(() => {
+    return Math.floor(index / 10) % NATURE_IMAGES.length;
+  }, [index]);
+
+  const currentNatureImage = NATURE_IMAGES[natureImageIndex];
 
   useLayoutEffect(() => {
     navigation.setOptions({
       headerShadowVisible: false,
-      headerStyle: { backgroundColor },
+      // 为了让风景/颜色两种主题下“文案的视觉居中位置”一致，统一使用透明 Header
+      // 颜色主题下 Header 透明也不会影响观感（背景就是纯色）
+      headerStyle: { backgroundColor: 'transparent' },
+      headerTransparent: true,
       headerRight: () => (
         <View style={styles.headerRight}>
           <CircleIconButton
@@ -89,7 +234,7 @@ export default function HomeScreen() {
         </View>
       ),
     });
-  }, [backgroundColor, navigation, t]);
+  }, [backgroundColor, themeMode, navigation, t]);
 
   const textAnimatedStyle = useAnimatedStyle(() => ({
     transform: [{ translateY: translateY.value }],
@@ -113,6 +258,11 @@ export default function HomeScreen() {
         runOnJS(setIndex)(index + 1);
         runOnJS(setLikeFilled)(false);
 
+        // 检查是否需要拉取新文案（当接近当前列表末尾时，例如还剩 5 条）
+        if (index + 5 >= currentFeed.length && !isFetching) {
+          runOnJS(fetchNewFeed)();
+        }
+
         // 3. 准备下一条文案：先瞬移到下方 40pt
         translateY.value = 40;
         
@@ -125,7 +275,7 @@ export default function HomeScreen() {
         });
       }
     });
-  }, [busy, index, translateY, opacity]);
+  }, [busy, index, currentFeed.length, isFetching, fetchNewFeed, translateY, opacity]);
 
   const lastTapRef = useRef<number>(0);
   
@@ -175,19 +325,28 @@ export default function HomeScreen() {
     const dateStr = `${now.getFullYear()}.${String(now.getMonth() + 1).padStart(2, '0')}.${String(now.getDate()).padStart(2, '0')}`;
 
     // 2. 保存到收藏夹，包含当前背景信息
-    await addFavorite({
+    const favItem = {
+      favId: String(Date.now()), // 生成唯一 ID
       id: item.id,
+      text: item.text,
       date: dateStr,
       themeMode: themeMode,
-      background: backgroundColor, // 目前存储的是颜色值
+      background: themeMode === 'scenery' ? String(natureImageIndex) : backgroundColor,
-    });
+    };
+    console.log('Home: Triggering addFavorite', JSON.stringify(favItem));
+    await addFavorite(favItem);
 
-    // 3. 爱心缩放动画
+    // 3. 记录到后端 Reaction（喜欢）
+    console.log('Home: Triggering setReaction', item.id);
+    await setReaction(item.id, 'like');
+
+    // 4. 爱心缩放动画
     likeScale.value = withSequence(
       withTiming(0.8, { duration: 100 }),
       withTiming(1.2, { duration: 150 }),
       withTiming(1, { duration: 100 }, (finished) => {
         if (finished) {
+          console.log('Home: Like animation finished, triggering next content');
           runOnJS(triggerNextContent)();
         }
       })
@@ -202,8 +361,17 @@ export default function HomeScreen() {
 
   return (
     <View style={[styles.container, { backgroundColor }]} {...panResponder.panHandlers}>
-      <Animated.View style={[styles.card, textAnimatedStyle]}>
+      {themeMode === 'scenery' && (
-        <Text style={styles.text}>{item.text}</Text>
+        <ImageBackground
+          source={currentNatureImage}
+          style={StyleSheet.absoluteFill}
+          resizeMode="cover"
+        />
+      )}
+      <Animated.View style={[styles.card, textAnimatedStyle, themeMode === 'scenery' && styles.sceneryCard]}>
+        <Text style={[styles.text, isEnglish && styles.textEnglish, themeMode === 'scenery' && styles.sceneryText]}>
+          {item.text}
+        </Text>
       </Animated.View>
 
       <View style={styles.actions}>
@@ -216,9 +384,13 @@ export default function HomeScreen() {
             style={styles.reactionInner}
           >
             {likeFilled ? (
-              <LikeFilledIcon width={35} height={36} />
+              <LikeFilledIcon width={35} height={36} style={{ color: '#EA6969' }} />
             ) : (
-              <LikeIcon width={35} height={36} />
+              <LikeIcon 
+                width={35} 
+                height={36} 
+                style={{ color: themeMode === 'scenery' ? '#FFFFFF' : '#5E2A28' }}
+              />
             )}
           </Pressable>
         </Animated.View>
@@ -277,9 +449,15 @@ const styles = StyleSheet.create({
     justifyContent: 'center',
   },
   card: {
-    paddingHorizontal: 30,
+    position: 'absolute',
-    alignItems: 'center',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
     justifyContent: 'center',
+    alignItems: 'center',
+    paddingHorizontal: 30,
+    zIndex: 5, // 降低层级，防止遮挡底部按钮
   },
   text: {
     fontSize: 22,
@@ -288,6 +466,21 @@ const styles = StyleSheet.create({
     fontWeight: '700',
     textAlign: 'center',
   },
+  textEnglish: {
+    fontFamily: 'STIXTwoText',
+    // 英文字体观感更细一点，避免过粗
+    fontWeight: '600',
+  },
+  sceneryCard: {
+    // 风景模式下稍微收窄文案宽度，增加呼吸感
+    paddingHorizontal: 50,
+  },
+  sceneryText: {
+    color: '#FFFFFF',
+    textShadowColor: 'rgba(0, 0, 0, 0.5)',
+    textShadowOffset: { width: 0, height: 1 },
+    textShadowRadius: 4,
+  },
   actions: {
     position: 'absolute',
     bottom: SCREEN_HEIGHT * 0.16,
@@ -295,6 +488,7 @@ const styles = StyleSheet.create({
     right: 0,
     flexDirection: 'row',
     justifyContent: 'center',
+    zIndex: 20, // 提升层级，确保在最顶层可点击
   },
   reactionButton: {
     alignItems: 'center',

client/app/(onboarding)/onboarding.tsx

@@ -1,76 +1,95 @@
-import { useState } from 'react';
+import { useMemo, useState } from 'react';
 import { useRouter } from 'expo-router';
 import * as Notifications from 'expo-notifications';
+import { useTranslation } from 'react-i18next';
 import { OnboardingLayout } from '@/components/onboarding/OnboardingLayout';
 import { NameInputStep } from '@/components/onboarding/NameInputStep';
 import { SelectionStep } from '@/components/onboarding/SelectionStep';
 import { ReminderStep } from '@/components/onboarding/ReminderStep';
-import { setOnboardingCompleted, setUserProfile, setDailyReminderSettings } from '@/src/storage/appStorage';
+import { buildUserProfileFromQuestionnaire, mapOnboardingSelectionsToQuestionnaireAnswers } from '@/src/features/userProfileScoring';
+import { fetchRecoFeed } from '@/src/services/recoApi';
+import {
+  recordRecoFeedServed,
+  setOnboardingCompleted,
+  setUserProfile,
+  setDailyReminderSettings,
+  setUserProfileScoring,
+  setRecoFeedCache,
+} from '@/src/storage/appStorage';
 
-const STEPS = [
+type Step =
-  { id: 'name', type: 'name', title: '我可以怎么称呼你？' },
+  | { id: 'name'; type: 'name' }
-  { 
+  | { id: 'status' | 'emotion' | 'influence' | 'support'; type: 'selection'; optionIds: string[] }
-    id: 'status', 
+  | { id: 'reminder'; type: 'reminder' };
-    type: 'selection', 
+
-    title: '媽媽的狀態？',
+const STEPS: Step[] = [
-    options: [
+  { id: 'name', type: 'name' },
-      { id: 'pregnant', label: '懷孕中／準備成為媽媽' },
+  { id: 'status', type: 'selection', optionIds: ['pregnant', 'has_kids', 'no_fill'] },
-      { id: 'has_kids', label: '已經有孩子' },
+  { id: 'emotion', type: 'selection', optionIds: ['happy', 'calm', 'stressed', 'low'] },
-      { id: 'no_fill', label: '不想填寫' },
+  { id: 'influence', type: 'selection', optionIds: ['family', 'work', 'relationship', 'friends', 'health'] },
-    ]
+  { id: 'support', type: 'selection', optionIds: ['emotional', 'parenting', 'self_worth', 'anxiety', 'balance'] },
-  },
+  { id: 'reminder', type: 'reminder' },
-  { 
-    id: 'emotion', 
-    type: 'selection', 
-    title: '當下情緒狀態？',
-    options: [
-      { id: 'happy', label: '愉悅、滿足' },
-      { id: 'calm', label: '平靜、安穩' },
-      { id: 'stressed', label: '被壓得有點喘不過氣' },
-      { id: 'low', label: '情緒低落' },
-    ]
-  },
-  { 
-    id: 'influence', 
-    type: 'selection', 
-    title: '是什麼影響了你最近的感受？',
-    options: [
-      { id: 'family', label: '家庭與孩子' },
-      { id: 'work', label: '工作或學習' },
-      { id: 'relationship', label: '親密關係' },
-      { id: 'friends', label: '朋友與人際' },
-      { id: 'health', label: '身心健康' },
-    ]
-  },
-  { 
-    id: 'support', 
-    type: 'selection', 
-    title: '最需要什麼支持?',
-    options: [
-      { id: 'emotional', label: '情緒支持' },
-      { id: 'parenting', label: '育兒壓力' },
-      { id: 'self_worth', label: '自我價值' },
-      { id: 'anxiety', label: '焦慮舒緩' },
-      { id: 'balance', label: '休息與平衡' },
-    ]
-  },
-  { id: 'reminder', type: 'reminder', title: '你需要每天几次提醒？' },
 ];
 
 export default function OnboardingScreen() {
   const router = useRouter();
+  const { t, i18n } = useTranslation();
   const [stepIndex, setStepIndex] = useState(0);
   const [name, setName] = useState('');
   const [selections, setSelections] = useState<Record<string, string[]>>({});
   const [reminderTimes, setReminderTimes] = useState(3);
 
   const currentStep = STEPS[stepIndex];
+  const currentTitle = useMemo(() => t(`onboardingSurvey.steps.${currentStep.id}.title`), [t, currentStep.id]);
+  const currentOptions = useMemo(() => {
+    if (currentStep.type !== 'selection') return [];
+    return currentStep.optionIds.map((optId) => ({
+      id: optId,
+      label: t(`onboardingSurvey.steps.${currentStep.id}.options.${optId}`),
+    }));
+  }, [t, currentStep]);
 
   async function onFinish() {
     // 请求推送权限
     const { status } = await Notifications.requestPermissionsAsync();
     const pushEnabled = status === 'granted';
 
+    // 将 Onboarding 选择映射为标准问卷枚举（允许跳过）
+    const answers = mapOnboardingSelectionsToQuestionnaireAnswers(selections);
+
+    // 生成用户画像（供推荐/Push/Widget 复用）
+    const scoringProfile = buildUserProfileFromQuestionnaire(answers);
+    await setUserProfileScoring(scoringProfile);
+
+    // Onboarding 结束后预拉取一次 Feed 文案（失败不阻塞进入首页）
+    try {
+      const lang = i18n.language?.toLowerCase().startsWith('zh') ? 'tc' : 'en';
+      const { items, meta } = await fetchRecoFeed({
+        k: 30,
+        user_profile: {
+          profile_version: scoringProfile.profile_version,
+          profile_source: scoringProfile.profile_source,
+          profile_generated_at: scoringProfile.profile_generated_at,
+          profile_confidence: scoringProfile.profile_confidence,
+          profile_answered: scoringProfile.profile_answered,
+          stage: scoringProfile.stage,
+          emotion_score: scoringProfile.emotion_score,
+          context: scoringProfile.context,
+          need: scoringProfile.need,
+        },
+      });
+
+      await setRecoFeedCache({
+        saved_at: new Date().toISOString(),
+        lang,
+        items: items.map((x) => ({ content_id: x.content_id, text: x.text })),
+        meta: meta as Record<string, unknown>,
+      });
+      await recordRecoFeedServed(items.map((x) => x.content_id));
+    } catch {
+      // 网络失败时使用首页本地 mock 兜底
+    }
+
     await setUserProfile({ 
       name, 
       intents: Object.values(selections).flat() 
@@ -97,10 +116,17 @@ export default function OnboardingScreen() {
     }
   };
 
-  const onSkip = () => {
+  const onSkip = async () => {
+    // 跳过整个 Onboarding：仍生成一个“全跳过”的最小画像，保证下游可用
+    const scoringProfile = buildUserProfileFromQuestionnaire({});
+    await setUserProfileScoring(scoringProfile);
+
+    // 标记已完成，避免下次启动再次进入 Onboarding
+    await setOnboardingCompleted(true);
     router.replace('/(app)/home');
   };
 
+  // 题目为多选：点击切换选中状态
   const handleToggleSelection = (id: string) => {
     setSelections(prev => {
       const currentIds = prev[currentStep.id] || [];
@@ -111,9 +137,14 @@ export default function OnboardingScreen() {
     });
   };
 
+  const handleSkipStep = () => {
+    setSelections((prev) => ({ ...prev, [currentStep.id]: [] }));
+    onNext();
+  };
+
   return (
     <OnboardingLayout
-      title={currentStep.title}
+      title={currentTitle}
       currentStep={stepIndex}
       totalSteps={STEPS.length - 1}
       onSkip={onSkip}
@@ -130,7 +161,7 @@ export default function OnboardingScreen() {
 
       {currentStep.type === 'selection' && (
         <SelectionStep
-          options={currentStep.options!}
+          options={currentOptions}
           selectedIds={selections[currentStep.id] || []}
           onToggle={handleToggleSelection}
           onNext={onNext}

client/app/_layout.tsx

@@ -34,7 +34,7 @@ SplashScreen.preventAutoHideAsync();
 
 export default function RootLayout() {
   const [loaded, error] = useFonts({
-    SpaceMono: require('../assets/fonts/SpaceMono-Regular.ttf'),
+    STIXTwoText: require('../assets/fonts/STIXTwoText-VariableFont_wght.ttf'),
     ...FontAwesome.font,
   });
   const [i18nReady, setI18nReady] = useState(false);
@@ -48,7 +48,7 @@ export default function RootLayout() {
     initI18n()
       .catch((e) => {
         // i18n 初始化失败不应阻塞 App 启动，先打印错误再继续
-        console.error('i18n 初始化失败', e);
+        console.error('i18n init failed', e);
       })
       .finally(() => setI18nReady(true));
   }, []);

client/app/index.tsx

@@ -1,9 +1,8 @@
 import { useEffect } from 'react';
 import { ActivityIndicator, StyleSheet, View } from 'react-native';
 import { useRouter } from 'expo-router';
-import AsyncStorage from '@react-native-async-storage/async-storage';
 
-import { getOnboardingCompleted, getConsentAccepted, setOnboardingCompleted, setConsentAccepted } from '@/src/storage/appStorage';
+import { getOnboardingCompleted, getConsentAccepted } from '@/src/storage/appStorage';
 
 /**
  * 启动分发：根据 consent 和 onboarding 状态跳转
@@ -14,10 +13,6 @@ export default function Index() {
   useEffect(() => {
     let cancelled = false;
     (async () => {
-      // 【完全重置】：清除本地存储的所有数据（收藏、设置、引导状态等）
-      await AsyncStorage.clear();
-      console.log('AsyncStorage has been cleared.');
-
       // 1. 检查是否同意协议
       const consentAccepted = await getConsentAccepted();
       if (cancelled) return;
@@ -27,9 +22,17 @@ export default function Index() {
         return;
       }
 
-      // 2. 检查 Onboarding
+      // 2. 检查 Onboarding 是否已完成
       const completed = await getOnboardingCompleted();
-      router.replace(completed ? '/(app)/home' : '/(onboarding)/onboarding');
+      if (cancelled) return;
+
+      if (completed) {
+        // 如果已经完成过流程，直接进 Home
+        router.replace('/(app)/home');
+      } else {
+        // 如果是首次进入（或未完成流程），进入 Onboarding
+        router.replace('/(onboarding)/onboarding');
+      }
     })();
     return () => {
       cancelled = true;
@@ -46,4 +49,3 @@ export default function Index() {
 const styles = StyleSheet.create({
   container: { flex: 1, alignItems: 'center', justifyContent: 'center' },
 });
-

client/assets/images/home/like.svg

@@ -1,3 +1,3 @@
 <svg width="32" height="27" viewBox="0 0 32 27" fill="none" xmlns="http://www.w3.org/2000/svg">
-<path d="M23.0879 1C24.9887 1 26.7592 1.93575 28.0762 3.42188C29.3956 4.91097 30.2001 6.88999 30.2002 8.84082C30.2002 13.2337 27.1054 17.3696 23.5225 20.499C21.7556 22.0422 19.9254 23.2909 18.4199 24.1494C17.6667 24.5789 17.0062 24.904 16.4863 25.1182C16.2262 25.2253 16.0121 25.3001 15.8467 25.3467C15.6728 25.3956 15.5993 25.4002 15.5996 25.4004C15.5928 25.3997 15.5178 25.3932 15.3525 25.3467C15.1871 25.3001 14.973 25.2253 14.7129 25.1182C14.193 24.904 13.5333 24.5788 12.7803 24.1494C11.2748 23.2909 9.44467 22.0423 7.67773 20.499C4.0947 17.3696 1 13.2338 1 8.84082C1.00008 6.89007 1.80381 4.91108 3.12207 3.42188C4.43787 1.93557 6.20587 1.00033 8.10059 1C9.51294 1.00117 10.8927 1.41742 12.0635 2.19434C12.7589 2.65582 13.3618 3.2322 13.8486 3.89355C14.2951 4.50017 15.0032 4.73135 15.5996 4.73145C16.1961 4.73144 16.905 4.5003 17.3516 3.89355C17.8376 3.23336 18.4389 2.65737 19.1328 2.19629C20.3012 1.4199 21.6779 1.00339 23.0879 1Z" stroke="#5E2A28" stroke-width="2"/>
+<path d="M23.0879 1C24.9887 1 26.7592 1.93575 28.0762 3.42188C29.3956 4.91097 30.2001 6.88999 30.2002 8.84082C30.2002 13.2337 27.1054 17.3696 23.5225 20.499C21.7556 22.0422 19.9254 23.2909 18.4199 24.1494C17.6667 24.5789 17.0062 24.904 16.4863 25.1182C16.2262 25.2253 16.0121 25.3001 15.8467 25.3467C15.6728 25.3956 15.5993 25.4002 15.5996 25.4004C15.5928 25.3997 15.5178 25.3932 15.3525 25.3467C15.1871 25.3001 14.973 25.2253 14.7129 25.1182C14.193 24.904 13.5333 24.5788 12.7803 24.1494C11.2748 23.2909 9.44467 22.0423 7.67773 20.499C4.0947 17.3696 1 13.2338 1 8.84082C1.00008 6.89007 1.80381 4.91108 3.12207 3.42188C4.43787 1.93557 6.20587 1.00033 8.10059 1C9.51294 1.00117 10.8927 1.41742 12.0635 2.19434C12.7589 2.65582 13.3618 3.2322 13.8486 3.89355C14.2951 4.50017 15.0032 4.73135 15.5996 4.73145C16.1961 4.73144 16.905 4.5003 17.3516 3.89355C17.8376 3.23336 18.4389 2.65737 19.1328 2.19629C20.3012 1.4199 21.6779 1.00339 23.0879 1Z" stroke="currentColor" stroke-width="2"/>
 </svg>

client/assets/images/home/like_filled.svg

@@ -1,4 +1,4 @@
 <svg width="32" height="27" viewBox="0 0 32 27" fill="none" xmlns="http://www.w3.org/2000/svg">
-<path d="M23.0879 1C24.9887 1 26.7592 1.93575 28.0762 3.42188C29.3956 4.91097 30.2001 6.88999 30.2002 8.84082C30.2002 13.2337 27.1054 17.3696 23.5225 20.499C21.7556 22.0422 19.9254 23.2909 18.4199 24.1494C17.6667 24.5789 17.0062 24.904 16.4863 25.1182C16.2262 25.2253 16.0121 25.3001 15.8467 25.3467C15.6728 25.3956 15.5993 25.4002 15.5996 25.4004C15.5928 25.3997 15.5178 25.3932 15.3525 25.3467C15.1871 25.3001 14.973 25.2253 14.7129 25.1182C14.193 24.904 13.5333 24.5788 12.7803 24.1494C11.2748 23.2909 9.44467 22.0423 7.67773 20.499C4.0947 17.3696 1 13.2338 1 8.84082C1.00008 6.89007 1.80381 4.91108 3.12207 3.42188C4.43787 1.93557 6.20587 1.00033 8.10059 1C9.51294 1.00117 10.8927 1.41742 12.0635 2.19434C12.7589 2.65582 13.3618 3.2322 13.8486 3.89355C14.2951 4.50017 15.0032 4.73135 15.5996 4.73145C16.1961 4.73144 16.905 4.5003 17.3516 3.89355C17.8376 3.23336 18.4389 2.65737 19.1328 2.19629C20.3012 1.4199 21.6779 1.00339 23.0879 1Z" fill="#5E2A28" stroke="#5E2A28" stroke-width="2"/>
+<path d="M23.0879 1C24.9887 1 26.7592 1.93575 28.0762 3.42188C29.3956 4.91097 30.2001 6.88999 30.2002 8.84082C30.2002 13.2337 27.1054 17.3696 23.5225 20.499C21.7556 22.0422 19.9254 23.2909 18.4199 24.1494C17.6667 24.5789 17.0062 24.904 16.4863 25.1182C16.2262 25.2253 16.0121 25.3001 15.8467 25.3467C15.6728 25.3956 15.5993 25.4002 15.5996 25.4004C15.5928 25.3997 15.5178 25.3932 15.3525 25.3467C15.1871 25.3001 14.973 25.2253 14.7129 25.1182C14.193 24.904 13.5333 24.5788 12.7803 24.1494C11.2748 23.2909 9.44467 22.0423 7.67773 20.499C4.0947 17.3696 1 13.2338 1 8.84082C1.00008 6.89007 1.80381 4.91108 3.12207 3.42188C4.43787 1.93557 6.20587 1.00033 8.10059 1C9.51294 1.00117 10.8927 1.41742 12.0635 2.19434C12.7589 2.65582 13.3618 3.2322 13.8486 3.89355C14.2951 4.50017 15.0032 4.73135 15.5996 4.73145C16.1961 4.73144 16.905 4.5003 17.3516 3.89355C17.8376 3.23336 18.4389 2.65737 19.1328 2.19629C20.3012 1.4199 21.6779 1.00339 23.0879 1Z" fill="currentColor" stroke="currentColor" stroke-width="2"/>
 </svg>
 

client/assets/images/icon/like_icon.svg

@@ -1,3 +1,3 @@
 <svg width="35" height="36" viewBox="0 0 35 36" fill="none" xmlns="http://www.w3.org/2000/svg">
-<path d="M25.0879 6C26.9887 6 28.7592 6.93575 30.0762 8.42188C31.3956 9.91097 32.2001 11.89 32.2002 13.8408C32.2002 18.2337 29.1054 22.3696 25.5225 25.499C23.7556 27.0422 21.9254 28.2909 20.4199 29.1494C19.6667 29.5789 19.0062 29.904 18.4863 30.1182C18.2262 30.2253 18.0121 30.3001 17.8467 30.3467C17.6728 30.3956 17.5993 30.4002 17.5996 30.4004C17.5928 30.3997 17.5178 30.3932 17.3525 30.3467C17.1871 30.3001 16.973 30.2253 16.7129 30.1182C16.193 29.904 15.5333 29.5788 14.7803 29.1494C13.2748 28.2909 11.4447 27.0423 9.67773 25.499C6.0947 22.3696 3 18.2338 3 13.8408C3.00008 11.8901 3.80381 9.91108 5.12207 8.42188C6.43787 6.93557 8.20587 6.00033 10.1006 6C11.5129 6.00117 12.8927 6.41742 14.0635 7.19434C14.7589 7.65582 15.3618 8.2322 15.8486 8.89355C16.2951 9.50017 17.0032 9.73135 17.5996 9.73145C18.1961 9.73144 18.905 9.5003 19.3516 8.89355C19.8376 8.23336 20.4389 7.65737 21.1328 7.19629C22.3012 6.4199 23.6779 6.00339 25.0879 6Z" stroke="#5E2A28" stroke-width="2"/>
+<path d="M25.0879 6C26.9887 6 28.7592 6.93575 30.0762 8.42188C31.3956 9.91097 32.2001 11.89 32.2002 13.8408C32.2002 18.2337 29.1054 22.3696 25.5225 25.499C23.7556 27.0422 21.9254 28.2909 20.4199 29.1494C19.6667 29.5789 19.0062 29.904 18.4863 30.1182C18.2262 30.2253 18.0121 30.3001 17.8467 30.3467C17.6728 30.3956 17.5993 30.4002 17.5996 30.4004C17.5928 30.3997 17.5178 30.3932 17.3525 30.3467C17.1871 30.3001 16.973 30.2253 16.7129 30.1182C16.193 29.904 15.5333 29.5788 14.7803 29.1494C13.2748 28.2909 11.4447 27.0423 9.67773 25.499C6.0947 22.3696 3 18.2338 3 13.8408C3.00008 11.8901 3.80381 9.91108 5.12207 8.42188C6.43787 6.93557 8.20587 6.00033 10.1006 6C11.5129 6.00117 12.8927 6.41742 14.0635 7.19434C14.7589 7.65582 15.3618 8.2322 15.8486 8.89355C16.2951 9.50017 17.0032 9.73135 17.5996 9.73145C18.1961 9.73144 18.905 9.5003 19.3516 8.89355C19.8376 8.23336 20.4389 7.65737 21.1328 7.19629C22.3012 6.4199 23.6779 6.00339 25.0879 6Z" stroke="currentColor" stroke-width="2"/>
 </svg>

client/components/home/FavoritesModal.tsx

@@ -4,7 +4,7 @@ import { useTranslation } from 'react-i18next';
 
 import SheetModal from '@/components/ui/SheetModal';
 import { MOCK_CONTENT } from '@/src/constants/mockContent';
-import { getFavorites } from '@/src/storage/appStorage';
+import { getFavorites, getRecoFeedCache, type FavoriteItem } from '@/src/storage/appStorage';
 
 type Props = {
   visible: boolean;
@@ -13,25 +13,50 @@ type Props = {
 
 export default function FavoritesModal({ visible, onClose }: Props) {
   const { t } = useTranslation();
-  const [ids, setIds] = useState<string[]>([]);
+  const [items, setItems] = useState<(FavoriteItem & { text: string })[]>([]);
 
   // 每次打开时刷新一次，确保展示最新“喜欢”
   useEffect(() => {
     if (!visible) return;
     let cancelled = false;
     (async () => {
-      const list = await getFavorites();
+      const [favList, cache] = await Promise.all([
-      if (!cancelled) setIds(list);
+        getFavorites(),
+        getRecoFeedCache()
+      ]);
+      console.log('FavoritesModal: Loaded favList', favList.length, 'items');
+      console.log('FavoritesModal: Loaded cache items', cache?.items?.length || 0);
+
+      if (cancelled) return;
+
+      // 建立文案查找表
+      const textMap = new Map<string, string>();
+      
+      // 1. 放入 Mock 数据
+      MOCK_CONTENT.forEach(c => textMap.set(String(c.id), t(c.textKey)));
+      
+      // 2. 放入缓存数据
+      if (cache?.items) {
+        cache.items.forEach(c => textMap.set(String(c.content_id), c.text));
+      }
+
+      // 3. 组装最终展示列表
+      const enriched = favList.map(fav => {
+        const favIdStr = String(fav.id);
+        const text = fav.text || textMap.get(favIdStr);
+        console.log(`FavoritesModal: Matching fav.id=${favIdStr}, found text=${!!text}, textValue=${text?.substring(0, 10)}...`);
+        return {
+          ...fav,
+          text: text || t('favorites.unknownText')
+        };
+      });
+
+      setItems(enriched);
     })();
     return () => {
       cancelled = true;
     };
-  }, [visible]);
+  }, [visible, t]);
-
-  const items = useMemo(() => {
-    const map = new Map(MOCK_CONTENT.map((c) => [c.id, c]));
-    return ids.map((id) => map.get(id)).filter(Boolean) as { id: string; text: string }[];
-  }, [ids]);
 
   return (
     <SheetModal visible={visible} title={t('profile.favorites')} onClose={onClose}>
@@ -41,7 +66,7 @@ export default function FavoritesModal({ visible, onClose }: Props) {
         ) : (
           <FlatList
             data={items}
-            keyExtractor={(it) => it.id}
+            keyExtractor={(it) => it.favId}
             contentContainerStyle={styles.list}
             renderItem={({ item }) => (
               <View style={styles.row}>

client/components/home/ProfileModal.tsx

@@ -22,6 +22,7 @@ import {
   getFavorites,
   setDailyReminderSettings,
   removeFavorite,
+  getRecoFeedCache,
   getUserProfile,
   type DailyReminderSettings,
   type FavoriteItem,
@@ -50,6 +51,29 @@ type Props = {
 type Page = 'root' | 'favorites' | 'dailyReminder' | 'widget' | 'language' | 'widgetHowTo';
 type NavDirection = 'forward' | 'back';
 
+const NATURE_IMAGES = [
+  require('@/assets/theme/nature/1.png'),
+  require('@/assets/theme/nature/2.png'),
+  require('@/assets/theme/nature/3.png'),
+  require('@/assets/theme/nature/4.png'),
+  require('@/assets/theme/nature/5.png'),
+  require('@/assets/theme/nature/6.png'),
+  require('@/assets/theme/nature/7.png'),
+  require('@/assets/theme/nature/8.png'),
+  require('@/assets/theme/nature/9.png'),
+  require('@/assets/theme/nature/10.png'),
+  require('@/assets/theme/nature/11.png'),
+  require('@/assets/theme/nature/12.png'),
+  require('@/assets/theme/nature/13.png'),
+  require('@/assets/theme/nature/14.png'),
+  require('@/assets/theme/nature/15.png'),
+  require('@/assets/theme/nature/17.png'),
+  require('@/assets/theme/nature/18.png'),
+  require('@/assets/theme/nature/19.png'),
+  require('@/assets/theme/nature/20.png'),
+  require('@/assets/theme/nature/22.png'),
+];
+
 export default function ProfileModal({ visible, name: propName, onClose }: Props) {
   const { t } = useTranslation();
 
@@ -248,23 +272,29 @@ function FavoritesPage({ visible, page }: { visible: boolean; page: Page }) {
 
   async function refreshFavorites() {
     const storedFavs = await getFavorites();
-    const map = new Map(MOCK_CONTENT.map((c) => [c.id, c.text]));
+    const textMap = new Map<string, string>();
 
-    const list = storedFavs
+    // 1) Mock 文案
-      .map((fav) => ({
+    MOCK_CONTENT.forEach((c) => textMap.set(String(c.id), t(c.textKey)));
-        ...fav,
+
-        text: map.get(fav.id) || ''
+    // 2) 后端推荐缓存文案（避免收藏后 cache 覆盖就丢文案）
-      }))
+    const cache = await getRecoFeedCache();
-      .filter(item => item.text !== '');
+    cache?.items?.forEach((c) => textMap.set(String(c.content_id), c.text));
+
+    // 3) 组装：优先使用收藏时写入的 text，其次从 map 回填
+    const list = storedFavs.map((fav) => ({
+      ...fav,
+      text: fav.text || textMap.get(String(fav.id)) || t('favorites.unknownText'),
+    }));
 
     setFavorites(list);
   }
 
-  async function handleRemove(id: string) {
+  async function handleRemove(favId: string) {
     // 1. 调用存储层移除收藏
-    await removeFavorite(id);
+    await removeFavorite(favId);
     // 2. 更新本地状态
-    setFavorites(prev => prev.filter(item => item.id !== id));
+    setFavorites(prev => prev.filter(item => item.favId !== favId));
   }
 
   return (
@@ -274,7 +304,7 @@ function FavoritesPage({ visible, page }: { visible: boolean; page: Page }) {
       ) : (
         <FlatList
           data={favorites}
-          keyExtractor={(it) => it.id}
+          keyExtractor={(it) => it.favId}
           contentContainerStyle={styles.favList}
           showsVerticalScrollIndicator={false}
           renderItem={({ item }) => (
@@ -290,11 +320,30 @@ function FavoritesPage({ visible, page }: { visible: boolean; page: Page }) {
               <View style={styles.favRight}>
                 <View style={[
                   styles.favThumb, 
-                  { backgroundColor: item.background } // 动态同步 Home 页的背景
+                  item.themeMode === 'scenery' ? {} : { backgroundColor: item.background }
                 ]}>
-                  <Text style={styles.favThumbText} numberOfLines={4}>{item.text}</Text>
+                  {item.themeMode === 'scenery' ? (
+                    <View style={StyleSheet.absoluteFill}>
+                      <Image 
+                        source={NATURE_IMAGES[parseInt(item.background)]} 
+                        style={{
+                          width: width * 0.6,
+                          height: 800, // 假设原图较高，设置一个较大的高度
+                          position: 'absolute',
+                          bottom: 0, // 关键：将图片底部对齐容器底部
+                        }}
+                        resizeMode="cover"
+                      />
+                    </View>
+                  ) : null}
+                  <Text style={[
+                    styles.favThumbText,
+                    item.themeMode === 'scenery' && { color: '#FFFFFF', textShadowColor: 'rgba(0,0,0,0.5)', textShadowOffset: {width:0, height:1}, textShadowRadius: 3 }
+                  ]} numberOfLines={4}>
+                    {item.text}
+                  </Text>
                   <Pressable 
-                    onPress={() => handleRemove(item.id)} 
+                    onPress={() => handleRemove(item.favId)} 
                     style={styles.favRemoveBtn}
                     hitSlop={10}
                   >
@@ -348,7 +397,7 @@ function DailyReminderPage({ visible, onDone }: { visible: boolean; onDone: () =
       if (settings.status === 'denied') {
         Alert.alert(
           t('common.notice'), 
-          "系统权限已被拒绝，请前往手机设置开启通知。"
+          t('permissions.notificationsDenied')
         );
         setPushEnabled(false);
         return;
@@ -565,12 +614,12 @@ function WidgetHowToPage() {
 }
 
 function LanguagePage() {
-  const { i18n } = useTranslation();
+  const { t, i18n } = useTranslation();
   const currentLang = i18n.language;
 
   const languages = [
-    { id: 'zh-TW', label: '繁体' },
+    { id: 'zh-TW', label: t('language.zhTW') },
-    { id: 'en', label: 'English' },
+    { id: 'en', label: t('language.en') },
   ];
 
   return (
@@ -765,6 +814,7 @@ const styles = StyleSheet.create({
     position: 'relative',
     borderWidth: 1,
     borderColor: 'rgba(119, 47, 0, 0.05)',
+    overflow: 'hidden',
   },
   favThumbText: {
     fontSize: 15,

client/components/onboarding/IntentSelectionStep.tsx

@@ -1,13 +1,14 @@
 import React from 'react';
 import { View, StyleSheet, TouchableOpacity } from 'react-native';
+import { useTranslation } from 'react-i18next';
 import { SerifText } from './SerifText';
 import { OnboardingColors } from '@/constants/OnboardingTheme';
 
 export const INTENTS = [
-  { id: 'love', label: '爱情', icon: '❤️' },
+  { id: 'love', labelKey: 'intent.love', icon: '❤️' },
-  { id: 'life', label: '生活', icon: '⛅' },
+  { id: 'life', labelKey: 'intent.life', icon: '⛅' },
-  { id: 'travel', label: '旅游', icon: '🌴' },
+  { id: 'travel', labelKey: 'intent.travel', icon: '🌴' },
-  { id: 'work', label: '职场', icon: '💼' },
+  { id: 'work', labelKey: 'intent.work', icon: '💼' },
 ];
 
 interface IntentSelectionStepProps {
@@ -16,9 +17,10 @@ interface IntentSelectionStepProps {
 }
 
 export function IntentSelectionStep({ selectedIds, onToggle }: IntentSelectionStepProps) {
+  const { t } = useTranslation();
   return (
     <View style={styles.container}>
-      <SerifText style={styles.title}>你希望得到什么帮助？</SerifText>
+      <SerifText style={styles.title}>{t('intent.title')}</SerifText>
       
       <View style={styles.grid}>
         {INTENTS.map((intent) => {
@@ -35,7 +37,7 @@ export function IntentSelectionStep({ selectedIds, onToggle }: IntentSelectionSt
             >
               <SerifText style={styles.icon}>{intent.icon}</SerifText>
               <SerifText style={[styles.label, isSelected && styles.labelSelected]}>
-                {intent.label}
+                {t(intent.labelKey)}
               </SerifText>
             </TouchableOpacity>
           );

client/components/onboarding/SelectionStep.tsx

@@ -18,9 +18,10 @@ interface SelectionStepProps {
   selectedIds: string[];
   onToggle: (id: string) => void;
   onNext: () => void;
+  onSkip?: () => void;
 }
 
-export function SelectionStep({ options, selectedIds, onToggle, onNext }: SelectionStepProps) {
+export function SelectionStep({ options, selectedIds, onToggle, onNext, onSkip }: SelectionStepProps) {
   const hasSelection = selectedIds.length > 0;
 
   return (
@@ -48,11 +49,7 @@ export function SelectionStep({ options, selectedIds, onToggle, onNext }: Select
 
       {/* 底部按钮：距离底部 12% 高度 */}
       <View style={styles.footer}>
-        <TouchableOpacity 
+        <TouchableOpacity onPress={onNext} disabled={!hasSelection} activeOpacity={0.8}>
-          onPress={onNext} 
-          disabled={!hasSelection}
-          activeOpacity={0.8}
-        >
           {hasSelection ? <BtnClicked width={87} height={57} /> : <BtnNotClicked width={87} height={57} />}
         </TouchableOpacity>
       </View>
@@ -99,5 +96,20 @@ const styles = StyleSheet.create({
     left: 0,
     right: 0,
     alignItems: 'center',
-  }
+  },
+  footerRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 16,
+  },
+  skipBtn: {
+    paddingVertical: 10,
+    paddingHorizontal: 14,
+    borderRadius: 12,
+    backgroundColor: 'rgba(0,0,0,0.04)',
+  },
+  skipText: {
+    fontSize: 16,
+    color: OnboardingColors.textMuted,
+  },
 });

client/components/ui/SheetModal.tsx

@@ -1,5 +1,6 @@
 import React, { useEffect, useMemo, useState, useRef } from 'react';
 import { Modal, Pressable, StyleSheet, Text, View, PanResponder, Animated as RNAnimated, Dimensions, Image, ImageSourcePropType } from 'react-native';
+import { useTranslation } from 'react-i18next';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import Animated, {
   Easing,
@@ -27,6 +28,7 @@ type Props = {
  * - 高度固定：默认距离顶部固定间距，也支持传入指定高度
  */
 export default function SheetModal({ visible, title, onClose, children, leftIcon, height: customHeight }: Props) {
+  const { t } = useTranslation();
   const insets = useSafeAreaInsets();
   const [mounted, setMounted] = useState(false);
   const progress = useSharedValue(0); // 0: 关闭, 1: 打开
@@ -121,7 +123,7 @@ export default function SheetModal({ visible, title, onClose, children, leftIcon
             </Text>
             <Pressable
               accessibilityRole="button"
-              accessibilityLabel={leftIcon ? "返回" : "关闭"}
+              accessibilityLabel={leftIcon ? t('common.back') : t('common.close')}
               onPress={onClose}
               hitSlop={10}
               style={styles.close}

client/ios/情绪小组件/EmotionWidget.swift

@@ -1,54 +1,28 @@
 import WidgetKit
 import SwiftUI
 
-// V2：纯色背景 + 随机文案小组件（Small/Medium/Large + 点击跳转 Home）
+// V1：写死文案的小组件（Small/Medium/Large + 点击跳转 Home）
 
 struct EmotionProvider: TimelineProvider {
-    private let quotes = [
-        "你已经很努力了，今天也值得被温柔对待。",
-        "轻轻呼吸，感受当下的每一刻。",
-        "所有的压力，都会在深呼吸中慢慢消散。",
-        "给生活一点留白，给自己一点温柔。",
-        "不要走得太快，等一等落下的灵魂。",
-        "世界虽嘈杂，但你可以拥有一颗宁静的心。",
-        "每一个瞬间，都是生命最好的安排。",
-        "抱抱自己，辛苦了，亲爱的。",
-        "慢一点也没关系，只要你在前行。",
-        "今天，你对自己微笑了吗？",
-        "愿你历经山河，仍觉得人间值得。",
-        "心简单，世界就简单；心平顺，生活就平顺。",
-        "即使生活偶尔晦暗，你也要成为自己的光。",
-        "别让琐事挤走生活的快乐，别让压力消磨奋斗的激情。"
-    ]
-
     func placeholder(in context: Context) -> EmotionEntry {
-        EmotionEntry(date: Date(), text: quotes[0])
+        EmotionEntry(date: Date())
     }
 
     func getSnapshot(in context: Context, completion: @escaping (EmotionEntry) -> ()) {
-        let entry = EmotionEntry(date: Date(), text: quotes.randomElement() ?? quotes[0])
+        completion(EmotionEntry(date: Date()))
-        completion(entry)
     }
 
     func getTimeline(in context: Context, completion: @escaping (Timeline<EmotionEntry>) -> ()) {
-        var entries: [EmotionEntry] = []
+        // V1：内容写死，不做数据更新；给一个较长的刷新间隔（系统仍可能自行调度）
-        let currentDate = Date()
+        let entry = EmotionEntry(date: Date())
-        
+        let nextUpdate = Calendar.current.date(byAdding: .day, value: 7, to: Date())
-        // 生成未来 24 小时的 6 个条目，每 4 小时更换一次随机文案
+            ?? Date().addingTimeInterval(60 * 60 * 24 * 7)
-        for hourOffset in 0..<6 {
+        completion(Timeline(entries: [entry], policy: .after(nextUpdate)))
-            let entryDate = Calendar.current.date(byAdding: .hour, value: hourOffset * 4, to: currentDate)!
-            let entry = EmotionEntry(date: entryDate, text: quotes.randomElement() ?? quotes[0])
-            entries.append(entry)
-        }
-
-        let timeline = Timeline(entries: entries, policy: .atEnd)
-        completion(timeline)
     }
 }
 
 struct EmotionEntry: TimelineEntry {
     let date: Date
-    let text: String
 }
 
 struct EmotionWidgetView: View {
@@ -56,37 +30,160 @@ struct EmotionWidgetView: View {
     @Environment(\.widgetFamily) var family
 
     private let title = "正念"
+    private let text = "你已经很努力了，今天也值得被温柔对待。"
     private let deepLink = URL(string: "client:///(app)/home")
 
-    // 背景色 #F7D9BF
-    private let backgroundColor = Color(red: 247/255, green: 217/255, blue: 191/255)
-    // 文本颜色（深咖色，适合搭配浅橘色背景）
-    private let textColor = Color(red: 74/255, green: 52/255, blue: 40/255)
-
     var body: some View {
-        VStack(alignment: .center, spacing: 0) {
+        switch family {
-            Spacer(minLength: 0)
+        case .systemSmall:
-            
+            smallView()
-            Text(entry.text)
+        case .systemMedium:
-                .font(.system(size: family == .systemSmall ? 17 : 20, weight: .medium))
+            mediumView()
-                .foregroundColor(textColor)
+        case .systemLarge:
-                .lineSpacing(6)
+            largeView()
-                .multilineTextAlignment(.center)
+        default:
-                .minimumScaleFactor(0.7)
+            smallView()
-                .fixedSize(horizontal: false, vertical: true)
+        }
-            
+    }
-            Spacer(minLength: 0)
+
-            
+    // 统一的“卡片背景”风格（iOS 15 兼容）
-            if family != .systemSmall {
+    private func cardBackground(colors: [Color]) -> some View {
-                Text("Hey Mama")
+        ZStack {
-                    .font(.system(size: 10, weight: .semibold))
+            LinearGradient(
-                    .foregroundColor(textColor.opacity(0.3))
+                colors: colors,
-                    .padding(.bottom, 4)
+                startPoint: .topLeading,
-            }
+                endPoint: .bottomTrailing
+            )
+            // 轻微光斑，增加层次
+            RadialGradient(
+                gradient: Gradient(colors: [Color.white.opacity(0.16), Color.white.opacity(0.0)]),
+                center: .topTrailing,
+                startRadius: 10,
+                endRadius: 180
+            )
+        }
+        .overlay(
+            RoundedRectangle(cornerRadius: 18, style: .continuous)
+                .stroke(Color.white.opacity(0.14), lineWidth: 1)
+        )
+        .cornerRadius(18)
+    }
+
+    private func chip(_ text: String) -> some View {
+        Text(text)
+            .font(.system(size: 12, weight: .semibold))
+            .foregroundColor(Color.white.opacity(0.9))
+            .padding(.horizontal, 10)
+            .padding(.vertical, 6)
+            .background(Color.white.opacity(0.14))
+            .cornerRadius(999)
+    }
+
+    private func smallView() -> some View {
+        ZStack {
+            cardBackground(colors: [
+                Color(red: 0.06, green: 0.08, blue: 0.12),
+                Color(red: 0.13, green: 0.16, blue: 0.22),
+            ])
+
+            VStack(alignment: .leading, spacing: 10) {
+                HStack {
+                    chip(title)
+                    Spacer(minLength: 0)
+                }
+
+                Text(text)
+                    .font(.system(size: 15, weight: .semibold))
+                    .foregroundColor(Color.white.opacity(0.92))
+                    .lineSpacing(2)
+                    .lineLimit(4)
+
+                Spacer(minLength: 0)
+
+                Text("点我回到 App")
+                    .font(.system(size: 11, weight: .medium))
+                    .foregroundColor(Color.white.opacity(0.65))
+            }
+            .padding(14)
+        }
+        .widgetURL(deepLink)
+    }
+
+    private func mediumView() -> some View {
+        ZStack {
+            cardBackground(colors: [
+                Color(red: 0.06, green: 0.08, blue: 0.12),
+                Color(red: 0.09, green: 0.11, blue: 0.17),
+            ])
+
+            HStack(alignment: .top, spacing: 14) {
+                VStack(alignment: .leading, spacing: 10) {
+                    chip(title)
+                    Text(text)
+                        .font(.system(size: 17, weight: .semibold))
+                        .foregroundColor(Color.white.opacity(0.92))
+                        .lineSpacing(3)
+                        .lineLimit(5)
+
+                    Spacer(minLength: 0)
+
+                    Text("轻轻呼吸，回到当下")
+                        .font(.system(size: 12, weight: .medium))
+                        .foregroundColor(Color.white.opacity(0.7))
+                }
+
+                // 右侧装饰区：让版面更饱满
+                VStack(alignment: .trailing, spacing: 8) {
+                    Text(entry.date, style: .time)
+                        .font(.system(size: 12, weight: .semibold))
+                        .foregroundColor(Color.white.opacity(0.8))
+                    Spacer(minLength: 0)
+                    Text("今日")
+                        .font(.system(size: 28, weight: .bold))
+                        .foregroundColor(Color.white.opacity(0.12))
+                }
+            }
+            .padding(16)
+        }
+        .widgetURL(deepLink)
+    }
+
+    private func largeView() -> some View {
+        ZStack {
+            cardBackground(colors: [
+                Color(red: 0.06, green: 0.08, blue: 0.12),
+                Color(red: 0.14, green: 0.18, blue: 0.28),
+            ])
+
+            VStack(alignment: .leading, spacing: 14) {
+                HStack {
+                    chip(title)
+                    Spacer(minLength: 0)
+                    Text(entry.date, style: .time)
+                        .font(.system(size: 12, weight: .semibold))
+                        .foregroundColor(Color.white.opacity(0.78))
+                }
+
+                Text(text)
+                    .font(.system(size: 20, weight: .semibold))
+                    .foregroundColor(Color.white.opacity(0.92))
+                    .lineSpacing(4)
+                    .lineLimit(8)
+
+                Spacer(minLength: 0)
+
+                HStack {
+                    Text("点我回到 Home")
+                        .font(.system(size: 12, weight: .medium))
+                        .foregroundColor(Color.white.opacity(0.7))
+                    Spacer(minLength: 0)
+                    Text("🌿")
+                        .font(.system(size: 18))
+                        .opacity(0.9)
+                }
+            }
+            .padding(18)
         }
-        .padding(family == .systemSmall ? 16 : 24)
-        .frame(maxWidth: .infinity, maxHeight: .infinity) // 强制撑开容器
-        .background(backgroundColor) // 将背景色直接应用到容器上
         .widgetURL(deepLink)
     }
 }
@@ -97,13 +194,7 @@ struct EmotionWidget: Widget {
 
     var body: some WidgetConfiguration {
         StaticConfiguration(kind: kind, provider: EmotionProvider()) { entry in
-            if #available(iOS 17.0, *) {
+            EmotionWidgetView(entry: entry)
-                EmotionWidgetView(entry: entry)
-                    .containerBackground(Color(red: 247/255, green: 217/255, blue: 191/255), for: .widget)
-            } else {
-                EmotionWidgetView(entry: entry)
-                    .background(Color(red: 247/255, green: 217/255, blue: 191/255))
-            }
         }
         .configurationDisplayName("情绪小组件")
         .description("一段温柔提醒，陪你回到当下。")

client/src/constants/env.ts

@@ -20,9 +20,26 @@ function getOptionalEnv(name: string, fallback: string): string {
   return process.env[name] ?? fallback;
 }
 
-export const APP_ENV = (getOptionalEnv('EXPO_PUBLIC_ENV', 'dev') as AppEnv) ?? 'dev';
+export type AppRuntimeEnv = 'local' | 'dev' | 'prod';
 
-export const API_BASE_URL = getRequiredEnv('EXPO_PUBLIC_API_BASE_URL');
+export const APP_ENV = (getOptionalEnv('EXPO_PUBLIC_ENV', 'local') as AppRuntimeEnv) ?? 'local';
+
+function getApiBaseUrl(env: AppRuntimeEnv): string {
+  // 向后兼容：若直接提供了 EXPO_PUBLIC_API_BASE_URL，则优先使用（不再强制要求 *_DEV/_PROD）
+  const direct = process.env.EXPO_PUBLIC_API_BASE_URL;
+  if (direct && String(direct).trim()) return String(direct).trim();
+
+  // 约定：local/dev/prod 三套域名分别配置，便于后续直接切环境而不改代码
+  if (env === 'local') {
+    return getOptionalEnv('EXPO_PUBLIC_API_BASE_URL_LOCAL', 'http://localhost:8000');
+  }
+  if (env === 'dev') {
+    return getOptionalEnv('EXPO_PUBLIC_API_BASE_URL_DEV', getOptionalEnv('EXPO_PUBLIC_API_BASE_URL_LOCAL', 'http://localhost:8000'));
+  }
+  return getOptionalEnv('EXPO_PUBLIC_API_BASE_URL_PROD', getOptionalEnv('EXPO_PUBLIC_API_BASE_URL_LOCAL', 'http://localhost:8000'));
+}
+
+export const API_BASE_URL = getApiBaseUrl(APP_ENV);
 
 /**
  * 默认语言策略：

client/src/constants/mockContent.ts

@@ -1,16 +1,16 @@
 export type MockContentItem = {
   id: string;
-  text: string;
+  textKey: string;
 };
 
 /**
  * 本地 mock 内容（后续接后端时可替换）
  */
 export const MOCK_CONTENT: MockContentItem[] = [
-  { id: 'c1', text: '你已经很努力了，今天也值得被温柔对待。' },
+  { id: 'c1', textKey: 'mock.c1' },
-  { id: 'c2', text: '深呼吸三次，把注意力带回当下。' },
+  { id: 'c2', textKey: 'mock.c2' },
-  { id: 'c3', text: '允许自己慢一点，情绪会像云一样飘过。' },
+  { id: 'c3', textKey: 'mock.c3' },
-  { id: 'c4', text: '你不需要完美，你已经足够好。' },
+  { id: 'c4', textKey: 'mock.c4' },
-  { id: 'c5', text: '把手放在心口，对自己说一句：辛苦了。' }
+  { id: 'c5', textKey: 'mock.c5' }
 ];
 

client/src/features/userProfileScoring/__tests__/onboarding-integration.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildUserProfileFromQuestionnaire } from '../index';
+import { mapOnboardingSelectionsToQuestionnaireAnswers } from '../onboardingMapping';
+
+describe('Onboarding → UserProfileScoring 集成', () => {
+  it('完整作答：Onboarding 选择能正确映射并生成画像', () => {
+    const selections = {
+      status: ['pregnant'],
+      emotion: ['calm'],
+      influence: ['work'],
+      support: ['balance'],
+    };
+
+    const answers = mapOnboardingSelectionsToQuestionnaireAnswers(selections);
+    expect(answers).toEqual({
+      mom_stage: 'expecting',
+      emotion: 'calm',
+      context: 'work',
+      need: 'rest_balance',
+    });
+
+    const p = buildUserProfileFromQuestionnaire(answers, {
+      generatedAt: '2026-01-30T00:00:00Z',
+      now: '2026-01-30T00:00:00Z',
+    });
+
+    expect(p.stage).toEqual({ expecting: 1, parenting: 0, unknown: 0 });
+    expect(p.emotion_score).toBe(0.8);
+    expect(p.context).toEqual({ work: 1 });
+    expect(p.need).toEqual({ rest_balance: 1 });
+    expect(p.profile_answered).toEqual({ stage: true, emotion: true, context: true, need: true });
+  });
+
+  it('全部跳过：仍能生成最小可计算画像（unknown=1）', () => {
+    const answers = mapOnboardingSelectionsToQuestionnaireAnswers({});
+    expect(answers).toEqual({ mom_stage: null, emotion: null, context: null, need: null });
+
+    const p = buildUserProfileFromQuestionnaire(answers, {
+      generatedAt: '2026-01-30T00:00:00Z',
+      now: '2026-01-30T00:00:00Z',
+    });
+
+    expect(p.stage).toEqual({ unknown: 1 });
+    expect(p.emotion_score).toBeNull();
+    expect(p.context).toEqual({});
+    expect(p.need).toEqual({});
+    expect(p.profile_answered).toEqual({ stage: false, emotion: false, context: false, need: false });
+  });
+});
+

client/src/features/userProfileScoring/index.ts

@@ -5,6 +5,8 @@ export type {
   UserProfileV1_2_Extended,
 } from './types';
 
+export type { OnboardingSelections } from './onboardingMapping';
+
 export {
   buildUserProfileFromQuestionnaire,
   computeProfileAnswered,
@@ -13,3 +15,5 @@ export {
   normalizeAnswers,
 } from './scoring';
 
+export { mapOnboardingSelectionsToQuestionnaireAnswers } from './onboardingMapping';
+

client/src/features/userProfileScoring/onboardingMapping.ts

@@ -0,0 +1,61 @@
+import type { QuestionnaireAnswersV1_2 } from './types';
+
+/**
+ * Onboarding UI 的选项 ID → 标准问卷枚举（可跳过）
+ *
+ * 说明：
+ * - UI 侧每题目前是单选，但数据结构是 string[]；这里取第 1 个作为答案
+ * - 不存在错误处理：未知/非法值统一按“跳过”处理（返回 null）
+ */
+export type OnboardingSelections = Record<string, string[] | undefined>;
+
+export function mapOnboardingSelectionsToQuestionnaireAnswers(
+  selections: OnboardingSelections
+): QuestionnaireAnswersV1_2 {
+  return {
+    mom_stage: mapMomStage(selections.status?.[0]),
+    emotion: mapEmotion(selections.emotion?.[0]),
+    context: mapContext(selections.influence?.[0]),
+    need: mapNeed(selections.support?.[0]),
+  };
+}
+
+function mapMomStage(raw: string | undefined): QuestionnaireAnswersV1_2['mom_stage'] {
+  // 跳过：null（显式跳过）
+  if (!raw) return null;
+  // UI id → 标准枚举
+  if (raw === 'pregnant') return 'expecting';
+  if (raw === 'has_kids') return 'parenting';
+  if (raw === 'no_fill') return 'unknown';
+  // 其他非法值：按跳过处理
+  return null;
+}
+
+function mapEmotion(raw: string | undefined): QuestionnaireAnswersV1_2['emotion'] {
+  if (!raw) return null;
+  // UI 当前选项：happy/calm/stressed/low
+  if (raw === 'happy') return 'joyful';
+  if (raw === 'calm') return 'calm';
+  if (raw === 'stressed') return 'overwhelmed';
+  if (raw === 'low') return 'low';
+  return null;
+}
+
+function mapContext(raw: string | undefined): QuestionnaireAnswersV1_2['context'] {
+  if (!raw) return null;
+  // UI id 已与标准枚举一致：family/work/relationship/friends/health
+  if (raw === 'family' || raw === 'work' || raw === 'relationship' || raw === 'friends' || raw === 'health') return raw;
+  return null;
+}
+
+function mapNeed(raw: string | undefined): QuestionnaireAnswersV1_2['need'] {
+  if (!raw) return null;
+  // UI id → 标准枚举
+  if (raw === 'emotional') return 'emotional_support';
+  if (raw === 'parenting') return 'parenting_pressure';
+  if (raw === 'self_worth') return 'self_worth';
+  if (raw === 'anxiety') return 'anxiety_relief';
+  if (raw === 'balance') return 'rest_balance';
+  return null;
+}
+

client/src/i18n/ALL_COPY.md

@@ -0,0 +1,22 @@
+## 应用文案总表（请在此文件对应的 JSON 中修改）
+
+**单一文案源文件**：`client/src/i18n/locales/all.json`
+
+- **English**：`all.json` 的 `en`
+- **繁体中文**：`all.json` 的 `zh-TW`
+
+> 说明：项目运行时只读取 `all.json`；请不要再改 `locales/en.json`、`locales/zh-TW.json`（它们已不再作为运行时数据源）。
+
+### 快速索引（高频文案）
+
+- **Home**：`home.*`
+- **Push 提示**：`push.*`
+- **主题**：`theme.*`
+- **我的/Profile**：`profile.*`
+- **收藏**：`favorites.*`
+- **设置**：`settings.*`
+- **Onboarding（问卷）**：`onboardingSurvey.steps.*`
+- **Onboarding（兴趣）**：`intent.*`
+- **Mock 文案**：`mock.*`
+
+

client/src/i18n/index.ts

@@ -3,8 +3,9 @@ import * as Localization from 'expo-localization';
 import i18n from 'i18next';
 import { initReactI18next } from 'react-i18next';
 
-import en from './locales/en.json';
+// 用 require 避免 TS 的 json module 配置差异导致无法编译
-import zhTW from './locales/zh-TW.json';
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const all = require('./locales/all.json') as { en: Record<string, unknown>; 'zh-TW': Record<string, unknown> };
 
 /**
  * 语言码约定：
@@ -83,8 +84,8 @@ export async function initI18n(): Promise<void> {
 
   await i18n.use(initReactI18next).init({
     resources: {
-      'zh-TW': { translation: zhTW },
+      'zh-TW': { translation: all['zh-TW'] as any },
-      en: { translation: en },
+      en: { translation: all.en as any },
     },
     lng: initialLang,
     fallbackLng: DEFAULT_FALLBACK_LANGUAGE,

client/src/i18n/locales/all.json

@@ -0,0 +1,314 @@
+{
+  "en": {
+    "common": {
+      "ok": "OK",
+      "cancel": "Cancel",
+      "error": "Error",
+      "openLinkError": "Cannot open link",
+      "back": "Back",
+      "close": "Close"
+    },
+    "onboarding": {
+      "title": "Welcome",
+      "progress": "{{current}}/{{total}}",
+      "next": "Next",
+      "skip": "Skip",
+      "skipAll": "Skip onboarding",
+      "q1Title": "How are you feeling lately?",
+      "q1Desc": "No right or wrong. You can skip and adjust later.",
+      "q2Title": "What kind of support do you want?",
+      "q2Desc": "For example: gentle reminders, mindfulness, emotional support.",
+      "q3Title": "When do you need comfort the most?",
+      "q3Desc": "Morning, afternoon, late night, or specific moments.",
+      "q4Title": "A gentle sentence for yourself",
+      "q4Desc": "You can skip. We’ll stay with you along the way."
+    },
+    "onboardingSurvey": {
+      "steps": {
+        "name": { "title": "What should I call you?" },
+        "status": {
+          "title": "Your current stage?",
+          "options": {
+            "pregnant": "Pregnant / preparing for motherhood",
+            "has_kids": "Already have kids",
+            "no_fill": "Prefer not to say"
+          }
+        },
+        "emotion": {
+          "title": "How are you feeling right now?",
+          "options": {
+            "happy": "Happy / satisfied",
+            "calm": "Calm / grounded",
+            "stressed": "Stressed / overwhelmed",
+            "low": "Down / low mood"
+          }
+        },
+        "influence": {
+          "title": "What has been affecting you lately?",
+          "options": {
+            "family": "Family & kids",
+            "work": "Work or study",
+            "relationship": "Intimate relationship",
+            "friends": "Friends & social life",
+            "health": "Mental & physical health"
+          }
+        },
+        "support": {
+          "title": "What support do you need most?",
+          "options": {
+            "emotional": "Emotional support",
+            "parenting": "Parenting stress",
+            "self_worth": "Self-worth",
+            "anxiety": "Anxiety relief",
+            "balance": "Rest & balance"
+          }
+        },
+        "reminder": { "title": "How many reminders do you want per day?" }
+      }
+    },
+    "intent": {
+      "title": "What kind of help do you want?",
+      "love": "Love",
+      "life": "Life",
+      "travel": "Travel",
+      "work": "Career"
+    },
+    "push": {
+      "title": "Notifications",
+      "cardTitle": "Turn on gentle reminders",
+      "cardDesc": "We’ll send a short mindful phrase when you may need it. You can change this anytime in Settings.",
+      "enable": "Enable",
+      "later": "Later",
+      "loading": "Working…",
+      "errorTitle": "Notice",
+      "errorDesc": "It’s okay if enabling fails. You can keep using the app."
+    },
+    "home": {
+      "title": "Mindfulness",
+      "like": "Like",
+      "dislike": "Dislike",
+      "favorites": "Favorites",
+      "settings": "Settings",
+      "theme": "Theme",
+      "profile": "Me"
+    },
+    "theme": {
+      "title": "Theme",
+      "scenery": "Scenery",
+      "color": "Color"
+    },
+    "profile": {
+      "title": "Me",
+      "favorites": "My Likes",
+      "widget": "Widget",
+      "dailyReminder": "Daily Reminder",
+      "privacy": "Privacy Policy",
+      "terms": "Terms of Use",
+      "language": "Language",
+      "todoTitle": "Notice",
+      "todoDesc": "This feature is a placeholder for this iteration."
+    },
+    "dailyReminder": {
+      "title": "Daily Reminder",
+      "timesUnit": "times",
+      "pushLabel": "Push Reminder",
+      "ok": "Ok",
+      "minus": "Decrease",
+      "plus": "Increase"
+    },
+    "widget": {
+      "lockScreen": "Lock Screen Widget",
+      "homeScreen": "Home Screen Widget",
+      "previewDate": "Thu, Jan 29",
+      "previewQuote": "I’m proud of who I am, even while becoming who I want to be."
+    },
+    "favorites": {
+      "title": "Favorites",
+      "empty": "No favorites yet.",
+      "unknownText": "This quote is no longer available."
+    },
+    "settings": {
+      "title": "Settings",
+      "language": "Language",
+      "version": "Version",
+      "widgetTitle": "iOS Widget",
+      "widgetDesc": "Put gentle reminders on your home screen: long-press → tap “+” → search “Mindfulness” → add a size you like."
+    },
+    "consent": {
+      "title": "You Are Perfect.",
+      "subtitle": "Everything Will Be Better.",
+      "agree": "Agree & Continue",
+      "privacy": "Privacy Policy",
+      "terms": "Terms of Use"
+    },
+    "permissions": {
+      "notificationsDenied": "Notifications are denied. Please enable them in Settings."
+    },
+    "language": {
+      "zhTW": "繁體中文",
+      "en": "English"
+    },
+    "mock": {
+      "c1": "You’ve been trying your best. You deserve kindness today.",
+      "c2": "Take three deep breaths and return to the present moment.",
+      "c3": "It’s okay to slow down. Emotions pass like clouds.",
+      "c4": "You don’t need to be perfect. You are enough.",
+      "c5": "Place a hand on your heart and say: You did well today."
+    }
+  },
+  "zh-TW": {
+    "common": {
+      "ok": "確定",
+      "cancel": "取消",
+      "back": "返回",
+      "close": "關閉"
+    },
+    "onboarding": {
+      "title": "歡迎",
+      "progress": "{{current}}/{{total}}",
+      "next": "下一步",
+      "skip": "跳過",
+      "skipAll": "跳過整個引導",
+      "q1Title": "你最近的感受更接近哪一種？",
+      "q1Desc": "沒有對錯，你可以跳過，之後也能慢慢調整。",
+      "q2Title": "你更希望獲得哪種支持？",
+      "q2Desc": "例如：溫柔提醒、正念練習、情緒陪伴。",
+      "q3Title": "你通常在什麼時候最需要被安慰？",
+      "q3Desc": "例如：清晨、午后、深夜，或某些特定時刻。",
+      "q4Title": "給自己一句溫柔的話",
+      "q4Desc": "你可以直接跳過，我們會在之後繼續陪你。"
+    },
+    "onboardingSurvey": {
+      "steps": {
+        "name": { "title": "我可以怎麼稱呼你？" },
+        "status": {
+          "title": "媽媽的狀態？",
+          "options": {
+            "pregnant": "懷孕中／準備成為媽媽",
+            "has_kids": "已經有孩子",
+            "no_fill": "不想填寫"
+          }
+        },
+        "emotion": {
+          "title": "當下情緒狀態？",
+          "options": {
+            "happy": "愉悅、滿足",
+            "calm": "平靜、安穩",
+            "stressed": "被壓得有點喘不過氣",
+            "low": "情緒低落"
+          }
+        },
+        "influence": {
+          "title": "是什麼影響了你最近的感受？",
+          "options": {
+            "family": "家庭與孩子",
+            "work": "工作或學習",
+            "relationship": "親密關係",
+            "friends": "朋友與人際",
+            "health": "身心健康"
+          }
+        },
+        "support": {
+          "title": "最需要什麼支持？",
+          "options": {
+            "emotional": "情緒支持",
+            "parenting": "育兒壓力",
+            "self_worth": "自我價值",
+            "anxiety": "焦慮舒緩",
+            "balance": "休息與平衡"
+          }
+        },
+        "reminder": { "title": "你需要每天幾次提醒？" }
+      }
+    },
+    "intent": {
+      "title": "你希望得到什麼幫助？",
+      "love": "愛情",
+      "life": "生活",
+      "travel": "旅遊",
+      "work": "職場"
+    },
+    "push": {
+      "title": "通知",
+      "cardTitle": "開啟溫柔提醒",
+      "cardDesc": "我們會在你需要的時候，送上一句正念短句或溫柔提醒（可隨時在設定中調整）。",
+      "enable": "立即開啟",
+      "later": "稍後",
+      "loading": "處理中…",
+      "errorTitle": "提示",
+      "errorDesc": "開啟失敗也沒關係，你仍然可以繼續使用應用。"
+    },
+    "home": {
+      "title": "正念",
+      "like": "喜歡",
+      "dislike": "不喜歡",
+      "favorites": "收藏",
+      "settings": "設定",
+      "theme": "主題",
+      "profile": "我的"
+    },
+    "theme": {
+      "title": "主題",
+      "scenery": "風景",
+      "color": "顏色"
+    },
+    "profile": {
+      "title": "我的",
+      "favorites": "我的喜歡",
+      "widget": "小工具",
+      "dailyReminder": "每日提醒",
+      "privacy": "隱私政策",
+      "terms": "使用條款",
+      "language": "語言",
+      "todoTitle": "提示",
+      "todoDesc": "此功能本期先占位，後續迭代補齊。"
+    },
+    "dailyReminder": {
+      "title": "每日提醒",
+      "timesUnit": "次",
+      "pushLabel": "推送提醒",
+      "ok": "確定",
+      "minus": "減少次數",
+      "plus": "增加次數"
+    },
+    "widget": {
+      "lockScreen": "鎖屏小工具",
+      "homeScreen": "桌面小工具",
+      "previewDate": "1月29日週四 · 已至臘月十一",
+      "previewQuote": "我也對現在的自己感到滿意，即使我仍在努力成為想成為的人。"
+    },
+    "favorites": {
+      "title": "收藏夾",
+      "empty": "這裡還沒有收藏內容。",
+      "unknownText": "這條文案暫時無法顯示。"
+    },
+    "settings": {
+      "title": "設定",
+      "language": "語言",
+      "version": "版本",
+      "widgetTitle": "iOS 小工具",
+      "widgetDesc": "把溫柔提醒放到桌面上：長按主畫面 → 點「+」 → 搜尋「正念」 → 添加你喜歡的尺寸。"
+    },
+    "consent": {
+      "agree": "同意並繼續",
+      "privacy": "隱私協議",
+      "terms": "用戶使用協議"
+    },
+    "permissions": {
+      "notificationsDenied": "系統權限已被拒絕，請前往手機設定開啟通知。"
+    },
+    "language": {
+      "zhTW": "繁體中文",
+      "en": "English"
+    },
+    "mock": {
+      "c1": "你已經很努力了，今天也值得被溫柔對待。",
+      "c2": "深呼吸三次，把注意力帶回當下。",
+      "c3": "允許自己慢一點，情緒會像雲一樣飄過。",
+      "c4": "你不需要完美，你已經足夠好。",
+      "c5": "把手放在心口，對自己說一句：辛苦了。"
+    }
+  }
+}
+
+

client/src/services/recoApi.ts

@@ -0,0 +1,64 @@
+import i18n from 'i18next';
+
+import { API_BASE_URL } from '@/src/constants/env';
+import type { UserProfileV1_2 } from '@/src/features/userProfileScoring';
+
+export type RecommendedItem = {
+  content_id: number;
+  text: string;
+  final_score: number;
+  fallback_level_final: number;
+  explanations?: Record<string, unknown> | null;
+};
+
+export type RecoMeta = Record<string, unknown>;
+
+export type RecoEngineResult = {
+  items: RecommendedItem[];
+  meta: RecoMeta;
+};
+
+export type RecoRequest = {
+  k?: number;
+  user_profile: UserProfileV1_2;
+  already_recommended_ids?: Array<string | number>;
+  touched_or_viewed_ids?: Array<string | number>;
+  now?: string; // ISO8601（可选）
+};
+
+function withTimeout(ms: number): AbortController {
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), ms);
+  return controller;
+}
+
+export async function fetchRecoFeed(req: RecoRequest): Promise<RecoEngineResult> {
+  const controller = withTimeout(12_000);
+  const url = `${API_BASE_URL}/v1/reco/feed`;
+  const acceptLanguage = i18n.language?.toLowerCase().startsWith('zh') ? 'tc' : 'en';
+
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      // 让后端做 locale 选择（目前后端只区分 en/tc）
+      'Accept-Language': acceptLanguage,
+    },
+    body: JSON.stringify({
+      k: req.k,
+      user_profile: req.user_profile,
+      already_recommended_ids: req.already_recommended_ids ?? [],
+      touched_or_viewed_ids: req.touched_or_viewed_ids ?? [],
+      now: req.now,
+    }),
+    signal: controller.signal,
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`推荐接口请求失败：${res.status} ${res.statusText} ${text}`.trim());
+  }
+
+  return (await res.json()) as RecoEngineResult;
+}
+

client/src/storage/appStorage.ts

@@ -1,4 +1,5 @@
 import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { UserProfileV1_2_Extended } from '@/src/features/userProfileScoring';
 
 /**
  * 本地存储 key 统一管理，避免 UI 里散落硬编码
@@ -9,6 +10,9 @@ const KEY_CONTENT_REACTIONS = 'content.reactions';
 const KEY_FAVORITES_ITEMS = 'favorites.items';
 const KEY_CONSENT_ACCEPTED = 'consent.accepted';
 const KEY_USER_PROFILE = 'user.profile';
+const KEY_USER_PROFILE_SCORING = 'user.profileScoring';
+const KEY_RECO_FEED_CACHE = 'reco.feedCache';
+const KEY_RECO_FEED_HISTORY = 'reco.feedHistory';
 const KEY_UI_THEME_MODE = 'ui.theme.mode';
 const KEY_DAILY_REMINDER_SETTINGS = 'dailyReminder.settings';
 
@@ -20,11 +24,48 @@ export type UserProfile = {
   name?: string;
   intents?: string[];
 };
+
+/**
+ * 用户画像（问卷打分输出）
+ * 说明：用于推荐/Push/Widget 统一复用；结构以 `src/features/userProfileScoring` 输出为准。
+ */
+export type UserProfileScoring = UserProfileV1_2_Extended;
 export type DailyReminderSettings = {
   timesPerDay: number;
   pushEnabled: boolean;
 };
 
+export type RecoFeedCacheItem = {
+  content_id: number;
+  text: string;
+};
+
+export type RecoFeedCache = {
+  saved_at: string; // ISO8601
+  /**
+   * 缓存文案的语言（后端目前只区分 en / tc）
+   * - en: English
+   * - tc: 繁体中文
+   */
+  lang?: 'en' | 'tc';
+  items: RecoFeedCacheItem[];
+  meta?: Record<string, unknown>;
+};
+
+/**
+ * Feed 链路可观测输入（用于下一次请求携带给后端）
+ *
+ * - already_recommended_ids：本设备已下发过的内容（避免重复下发）
+ * - touched_or_viewed_ids：本设备用户已看过/划过的内容（用于频控/去重/降重复）
+ *
+ * 说明：后端不需要“实时知道”，只要在下一次拉取时带上即可。
+ */
+export type RecoFeedHistory = {
+  updated_at: string; // ISO8601
+  already_recommended_ids: number[];
+  touched_or_viewed_ids: number[];
+};
+
 
 async function getJson<T>(key: string, fallback: T): Promise<T> {
   const raw = await AsyncStorage.getItem(key);
@@ -70,7 +111,12 @@ export async function setReaction(contentId: string, reaction: Reaction): Promis
 }
 
 export type FavoriteItem = {
+  favId: string; // 唯一标识，支持重复点赞同一文案
   id: string;
+  /**
+   * 收藏时的文案快照（强烈建议写入，避免后续 cache 覆盖导致无法还原文案）
+   */
+  text?: string;
   date: string;
   themeMode: ThemeMode;
   background: string; // 颜色值或图片路径
@@ -82,15 +128,15 @@ export async function getFavorites(): Promise<FavoriteItem[]> {
 
 export async function addFavorite(item: FavoriteItem): Promise<void> {
   const list = await getFavorites();
-  if (list.some(i => i.id === item.id)) return;
+  // 允许重复点赞，不再根据 id 去重
   const newList = [item, ...list];
-  console.log('Adding to favorites, new list size:', newList.length);
+  console.log('Adding to favorites:', JSON.stringify(item));
   await setJson(KEY_FAVORITES_ITEMS, newList);
 }
 
-export async function removeFavorite(contentId: string): Promise<void> {
+export async function removeFavorite(favId: string): Promise<void> {
   const list = await getFavorites();
-  const next = list.filter(item => item.id !== contentId);
+  const next = list.filter(item => item.favId !== favId);
   await setJson(KEY_FAVORITES_ITEMS, next);
 }
 
@@ -122,6 +168,103 @@ export async function setUserProfile(profile: UserProfile): Promise<void> {
   await setJson(KEY_USER_PROFILE, { ...current, ...profile });
 }
 
+export async function getUserProfileScoring(): Promise<UserProfileScoring | null> {
+  const raw = await AsyncStorage.getItem(KEY_USER_PROFILE_SCORING);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as UserProfileScoring;
+  } catch {
+    return null;
+  }
+}
+
+export async function setUserProfileScoring(profile: UserProfileScoring): Promise<void> {
+  await setJson(KEY_USER_PROFILE_SCORING, profile);
+}
+
+export async function getRecoFeedCache(): Promise<RecoFeedCache | null> {
+  const raw = await AsyncStorage.getItem(KEY_RECO_FEED_CACHE);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as RecoFeedCache;
+  } catch {
+    return null;
+  }
+}
+
+export async function setRecoFeedCache(cache: RecoFeedCache): Promise<void> {
+  await setJson(KEY_RECO_FEED_CACHE, cache);
+}
+
+export async function getRecoFeedHistory(): Promise<RecoFeedHistory> {
+  const raw = await AsyncStorage.getItem(KEY_RECO_FEED_HISTORY);
+  if (!raw) {
+    return {
+      updated_at: new Date().toISOString(),
+      already_recommended_ids: [],
+      touched_or_viewed_ids: [],
+    };
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<RecoFeedHistory>;
+    return {
+      updated_at: typeof parsed.updated_at === 'string' ? parsed.updated_at : new Date().toISOString(),
+      already_recommended_ids: Array.isArray(parsed.already_recommended_ids)
+        ? parsed.already_recommended_ids.filter((x) => Number.isFinite(x)).map((x) => Number(x))
+        : [],
+      touched_or_viewed_ids: Array.isArray(parsed.touched_or_viewed_ids)
+        ? parsed.touched_or_viewed_ids.filter((x) => Number.isFinite(x)).map((x) => Number(x))
+        : [],
+    };
+  } catch {
+    return {
+      updated_at: new Date().toISOString(),
+      already_recommended_ids: [],
+      touched_or_viewed_ids: [],
+    };
+  }
+}
+
+export async function setRecoFeedHistory(history: RecoFeedHistory): Promise<void> {
+  await setJson(KEY_RECO_FEED_HISTORY, history);
+}
+
+function uniqKeepLatest(list: number[], max: number): number[] {
+  const seen = new Set<number>();
+  const out: number[] = [];
+  for (let i = list.length - 1; i >= 0; i -= 1) {
+    const v = list[i];
+    if (!Number.isFinite(v)) continue;
+    if (seen.has(v)) continue;
+    seen.add(v);
+    out.push(v);
+    if (out.length >= max) break;
+  }
+  return out.reverse();
+}
+
+export async function recordRecoFeedServed(contentIds: number[]): Promise<void> {
+  if (!contentIds?.length) return;
+  const h = await getRecoFeedHistory();
+  const next = {
+    ...h,
+    updated_at: new Date().toISOString(),
+    already_recommended_ids: uniqKeepLatest([...h.already_recommended_ids, ...contentIds], 500),
+  };
+  await setRecoFeedHistory(next);
+}
+
+export async function recordRecoFeedTouched(contentId: number): Promise<void> {
+  if (!Number.isFinite(contentId)) return;
+  const h = await getRecoFeedHistory();
+  const next = {
+    ...h,
+    updated_at: new Date().toISOString(),
+    touched_or_viewed_ids: uniqKeepLatest([...h.touched_or_viewed_ids, contentId], 500),
+  };
+  await setRecoFeedHistory(next);
+}
+
 export async function getDailyReminderSettings(): Promise<DailyReminderSettings> {
   const s = await getJson<DailyReminderSettings>(KEY_DAILY_REMINDER_SETTINGS, {
     timesPerDay: 3,

server/app/api/limits.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Dict, Tuple
+
+from fastapi import HTTPException, Request
+
+
+@dataclass
+class FixedWindowRateLimiter:
+    """
+    固定窗口限流（内存版）。
+
+    约束：
+    - 适用于单进程/单实例；多进程/多实例下不共享计数（V1 可接受）
+    - 窗口粒度：按分钟 bucket（window_seconds 建议为 60）
+    """
+
+    limit: int
+    window_seconds: int
+    _counters: Dict[Tuple[str, int], int] = field(default_factory=dict)
+    _last_gc_bucket: int = 0
+
+    def _bucket(self, now_ts: float) -> int:
+        return int(now_ts // float(self.window_seconds))
+
+    def _gc(self, current_bucket: int) -> None:
+        # 每隔一段时间清理一次，避免 dict 无限增长（保留最近 3 个 bucket）
+        if self._last_gc_bucket == current_bucket:
+            return
+        self._last_gc_bucket = current_bucket
+        keep_from = current_bucket - 2
+        to_delete = [k for k in self._counters.keys() if k[1] < keep_from]
+        for k in to_delete:
+            self._counters.pop(k, None)
+
+    def allow(self, *, key: str, now_ts: float) -> None:
+        bucket = self._bucket(now_ts)
+        self._gc(bucket)
+
+        k = (str(key), int(bucket))
+        n = int(self._counters.get(k, 0)) + 1
+        self._counters[k] = n
+        if n > int(self.limit):
+            raise HTTPException(status_code=429, detail="rate_limited")
+
+
+_reco_rate_limiter = FixedWindowRateLimiter(limit=10, window_seconds=60)
+
+
+async def rate_limit_reco_by_ip(request: Request) -> None:
+    """
+    推荐接口限流：按 IP，1 分钟 10 次。
+    """
+
+    ip = "unknown"
+    if request.client and request.client.host:
+        ip = str(request.client.host)
+
+    _reco_rate_limiter.allow(key=ip, now_ts=time.time())
+

server/app/api/v1/reco.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from fastapi import APIRouter, Depends, Header
+from pydantic import BaseModel, Field
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.limits import rate_limit_reco_by_ip
+from app.db.session import get_db
+from app.features.personalized_reco.content_repository.interface import ContentRepository
+from app.features.personalized_reco.content_repository.sqlalchemy_repo import SqlAlchemyContentRepository
+from app.features.personalized_reco.reco_engine import recommend
+from app.features.personalized_reco.reco_engine.types import RecoConstraints, RecoEngineResult
+from app.features.user_profile_scoring.types import UserProfileV1_2
+
+router = APIRouter(
+    prefix="/v1/reco",
+    tags=["reco"],
+    dependencies=[Depends(rate_limit_reco_by_ip)],
+)
+
+
+class RecoRequest(BaseModel):
+    k: Optional[int] = None
+    user_profile: UserProfileV1_2
+    already_recommended_ids: list[Any] = Field(default_factory=list)
+    touched_or_viewed_ids: list[Any] = Field(default_factory=list)
+    now: Optional[datetime] = None
+
+
+def _parse_now_from_header(x_now: Optional[str]) -> Optional[datetime]:
+    if not x_now:
+        return None
+    raw = str(x_now).strip()
+    if not raw:
+        return None
+    # 支持 Z
+    if raw.endswith("Z"):
+        raw = raw[:-1] + "+00:00"
+    try:
+        dt = datetime.fromisoformat(raw)
+    except Exception:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+def _pick_now(*, header_now: Optional[str], body_now: Optional[datetime]) -> datetime:
+    dt = _parse_now_from_header(header_now)
+    if dt is not None:
+        return dt
+    if body_now is not None:
+        if body_now.tzinfo is None:
+            return body_now.replace(tzinfo=timezone.utc)
+        return body_now
+    return datetime.now(timezone.utc)
+
+
+def _pick_locale_from_accept_language(accept_language: Optional[str]) -> str:
+    """
+    从 Accept-Language 映射 locale：
+    - 缺失/空 -> en
+    - 含 zh-TW/zh-HK/tc -> tc
+    - 其他 -> en
+    """
+
+    raw = (accept_language or "").strip().lower()
+    if not raw:
+        return "en"
+    if "zh-tw" in raw or "zh-hk" in raw or "tc" in raw:
+        return "tc"
+    return "en"
+
+
+async def get_reco_repo(db: AsyncSession = Depends(get_db)) -> ContentRepository:
+    """
+    构造推荐 repo（可在测试中 override，避免依赖真实 DB）。
+    """
+
+    return SqlAlchemyContentRepository(db)
+
+
+@router.post("/feed", response_model=RecoEngineResult)
+async def reco_feed(
+    req: RecoRequest,
+    repo: ContentRepository = Depends(get_reco_repo),
+    x_now: Optional[str] = Header(default=None, alias="X-Now"),
+    accept_language: Optional[str] = Header(default=None, alias="Accept-Language"),
+) -> RecoEngineResult:
+    k_i = 30 if req.k is None else int(req.k)
+    now = _pick_now(header_now=x_now, body_now=req.now)
+    locale = _pick_locale_from_accept_language(accept_language)
+
+    return await recommend(
+        repo=repo,
+        scene="feed",
+        user_profile=req.user_profile,
+        already_recommended_ids=list(req.already_recommended_ids or []),
+        touched_or_viewed_ids=list(req.touched_or_viewed_ids or []),
+        k=k_i,
+        now=now,
+        locale=locale,
+        constraints=RecoConstraints(),
+    )
+
+
+@router.post("/push", response_model=RecoEngineResult)
+async def reco_push(
+    req: RecoRequest,
+    repo: ContentRepository = Depends(get_reco_repo),
+    x_now: Optional[str] = Header(default=None, alias="X-Now"),
+    accept_language: Optional[str] = Header(default=None, alias="Accept-Language"),
+) -> RecoEngineResult:
+    k_i = 1 if req.k is None else int(req.k)
+    now = _pick_now(header_now=x_now, body_now=req.now)
+    locale = _pick_locale_from_accept_language(accept_language)
+
+    return await recommend(
+        repo=repo,
+        scene="push",
+        user_profile=req.user_profile,
+        already_recommended_ids=list(req.already_recommended_ids or []),
+        touched_or_viewed_ids=list(req.touched_or_viewed_ids or []),
+        k=k_i,
+        now=now,
+        locale=locale,
+        constraints=RecoConstraints(),
+    )
+
+
+@router.post("/widget", response_model=RecoEngineResult)
+async def reco_widget(
+    req: RecoRequest,
+    repo: ContentRepository = Depends(get_reco_repo),
+    x_now: Optional[str] = Header(default=None, alias="X-Now"),
+    accept_language: Optional[str] = Header(default=None, alias="Accept-Language"),
+) -> RecoEngineResult:
+    k_i = 1 if req.k is None else int(req.k)
+    now = _pick_now(header_now=x_now, body_now=req.now)
+    locale = _pick_locale_from_accept_language(accept_language)
+
+    return await recommend(
+        repo=repo,
+        scene="widget",
+        user_profile=req.user_profile,
+        already_recommended_ids=list(req.already_recommended_ids or []),
+        touched_or_viewed_ids=list(req.touched_or_viewed_ids or []),
+        k=k_i,
+        now=now,
+        locale=locale,
+        constraints=RecoConstraints(),
+    )
+

server/app/features/personalized_reco/__init__.py

@@ -0,0 +1,6 @@
+"""
+Personalized Reco（个性化推荐）功能模块集合。
+
+该目录用于承载推荐引擎与其子模块（数据访问、打分、重排、可观测等）。
+"""
+

server/app/features/personalized_reco/content_repository/__init__.py

@@ -0,0 +1,8 @@
+"""
+Content Repository（候选查询与数据访问层）。
+
+说明：
+- 本模块为推荐引擎提供可注入的数据访问接口（与 ORM/SQL 解耦）。
+- 负责将 DB 存储形态规范化为上层稳定的 ContentProfile 结构。
+"""
+

server/app/features/personalized_reco/content_repository/interface.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from app.features.personalized_reco.content_repository.types import ContentProfileDTO
+
+
+class ContentRepository(Protocol):
+    """
+    推荐引擎依赖的内容数据访问抽象接口（用于解耦 ORM/SQL）。
+    """
+
+    async def fetch_candidates(
+        self,
+        *,
+        scene: str,
+        user_profile: object,
+        fallback_level: int,
+        limit: int,
+        locale: str,
+        exclude_content_ids: list[int] | None = None,
+    ) -> list[ContentProfileDTO]:
+        """
+        按场景与用户画像拉取候选内容画像（用于候选池）。
+        """
+
+    async def fetch_contents_by_ids(
+        self,
+        *,
+        content_ids: list[int],
+        locale: str,
+    ) -> list[ContentProfileDTO]:
+        """
+        按 content_id 批量获取内容画像（去重、按输入顺序返回；缺语言/缺记录的 id 跳过）。
+        """
+

server/app/features/personalized_reco/content_repository/normalization.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from typing import Any
+
+from app.features.personalized_reco.content_repository.types import Locale, normalize_locale
+
+
+CONTEXT_KEYS: tuple[str, ...] = ("family", "work", "relationship", "friends", "health")
+NEED_KEYS: tuple[str, ...] = (
+    "emotional_support",
+    "parenting_pressure",
+    "self_worth",
+    "anxiety_relief",
+    "rest_balance",
+)
+
+
+def _normalize_discrete_score(v: Any, *, default: float = 0.5) -> float:
+    """
+    将 suitability 的离散值规范化为 0/0.5/1。
+
+    非法值一律兜底 default（默认 0.5）。
+    """
+
+    try:
+        if v in (0, 0.0):
+            return 0.0
+        if v in (0.5,):
+            return 0.5
+        if v in (1, 1.0):
+            return 1.0
+        # 允许字符串形式的 "0"/"0.5"/"1"
+        if isinstance(v, str):
+            s = v.strip()
+            if s == "0":
+                return 0.0
+            if s == "0.5":
+                return 0.5
+            if s == "1":
+                return 1.0
+    except Exception:
+        return default
+    return default
+
+
+def normalize_suitability(raw: Any, *, keys: tuple[str, ...]) -> dict[str, float]:
+    """
+    解析 suitability JSON，缺失时补齐全 0.5。
+
+    raw 期望为 dict；否则视为缺失。
+    """
+
+    data: dict[str, Any] = raw if isinstance(raw, dict) else {}
+    return {k: _normalize_discrete_score(data.get(k), default=0.5) for k in keys}
+
+
+def normalize_review_confidence(raw: Any) -> float:
+    """
+    review_confidence 缺失/NULL 时兜底 0.7。
+    """
+
+    try:
+        if raw is None:
+            return 0.7
+        v = float(raw)
+        if 0.0 <= v <= 1.0:
+            return v
+    except Exception:
+        pass
+    return 0.7
+
+
+def normalize_personalization_power(raw: Any) -> float:
+    """
+    DB 约定存 0/5/10，读取层输出 0/0.5/1。
+    """
+
+    try:
+        if raw is None:
+            return 0.0
+        v = int(raw)
+        if v == 0:
+            return 0.0
+        if v == 5:
+            return 0.5
+        if v == 10:
+            return 1.0
+    except Exception:
+        pass
+    return 0.0
+
+
+_RISK_FLAG_MAP: dict[str, str] = {
+    "block_stage_unknown": "unsafe_for_stage_unknown",
+    "block_stage_parenting": "unsafe_for_stage_parenting",
+    "block_emotion_low": "unsafe_for_emotion_low",
+    "block_health_sensitive": "block_health_medical",
+}
+
+
+def normalize_risk_flags(raw_flags: list[str] | None) -> list[str]:
+    """
+    risk_flags 旧→新映射、去重、稳定排序（字典序）。
+    """
+
+    flags = raw_flags or []
+    mapped: set[str] = set()
+    for f in flags:
+        if not f:
+            continue
+        name = _RISK_FLAG_MAP.get(f, f)
+        mapped.add(name)
+    return sorted(mapped)
+
+
+def pick_text(*, text_en: str | None, text_tc: str | None, locale: str) -> str | None:
+    """
+    按 locale 选择输出文案文本。
+
+    当前仅支持 EN/TC，且不允许语言回退：
+    - locale=en*：必须使用 text_en
+    - locale=tc/zh-TW/zh-HK：必须使用 text_tc
+    """
+
+    loc: Locale = normalize_locale(locale)
+    if loc == "en":
+        return text_en if text_en else None
+    # loc == "tc"
+    return text_tc if text_tc else None
+

server/app/features/personalized_reco/content_repository/sqlalchemy_repo.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import Any, Iterable
+
+from sqlalchemy import Select, and_, desc, not_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db.models.content import Content
+from app.db.models.content_profile import ContentProfile
+from app.db.models.content_risk_flag import ContentRiskFlag
+from app.features.personalized_reco.content_repository.interface import ContentRepository
+from app.features.personalized_reco.content_repository.normalization import (
+    CONTEXT_KEYS,
+    NEED_KEYS,
+    normalize_personalization_power,
+    normalize_review_confidence,
+    normalize_risk_flags,
+    normalize_suitability,
+    pick_text,
+)
+from app.features.personalized_reco.content_repository.types import ContentProfileDTO
+
+
+@dataclass(frozen=True)
+class _UserSignals:
+    """
+    从 user_profile 中提取 repository 级别需要的最小信号。
+
+    注意：更复杂的规则（Hard Filter/Scoring/Rerank）不在本层处理。
+    """
+
+    missing_need: bool
+    missing_context: bool
+    missing_emotion: bool
+    stage: str | None  # expecting/parenting/unknown/general/None
+
+
+def _bool(v: Any) -> bool:
+    return bool(v)
+
+
+def _extract_user_signals(user_profile: object) -> _UserSignals:
+    """
+    兼容 pydantic model / dict / 其他对象的最小字段读取。
+    """
+
+    def _get(obj: Any, key: str, default: Any = None) -> Any:
+        if obj is None:
+            return default
+        if isinstance(obj, dict):
+            return obj.get(key, default)
+        return getattr(obj, key, default)
+
+    need = _get(user_profile, "need", {}) or {}
+    context = _get(user_profile, "context", {}) or {}
+    emotion_score = _get(user_profile, "emotion_score", None)
+
+    missing_need = len(need) == 0
+    missing_context = len(context) == 0
+    missing_emotion = emotion_score is None
+
+    # stage: from user_profile.stage (one-hot)
+    stage_obj = _get(user_profile, "stage", None)
+    stage: str | None = None
+    if stage_obj is not None:
+        expecting = _get(stage_obj, "expecting", None)
+        parenting = _get(stage_obj, "parenting", None)
+        unknown = _get(stage_obj, "unknown", None)
+        if _bool(expecting):
+            stage = "expecting"
+        elif _bool(parenting):
+            stage = "parenting"
+        elif _bool(unknown):
+            stage = "unknown"
+
+    return _UserSignals(
+        missing_need=missing_need,
+        missing_context=missing_context,
+        missing_emotion=missing_emotion,
+        stage=stage,
+    )
+
+
+def _dedupe_preserve_order(ids: Iterable[int]) -> list[int]:
+    seen: set[int] = set()
+    out: list[int] = []
+    for i in ids:
+        if i in seen:
+            continue
+        seen.add(i)
+        out.append(i)
+    return out
+
+
+class SqlAlchemyContentRepository(ContentRepository):
+    """
+    基于 SQLAlchemy AsyncSession 的 ContentRepository 实现。
+    """
+
+    def __init__(self, session: AsyncSession):
+        self._session = session
+
+    async def fetch_contents_by_ids(self, *, content_ids: list[int], locale: str) -> list[ContentProfileDTO]:
+        """
+        - 输入去重
+        - 输出顺序与输入一致（按首次出现顺序）
+        - 缺记录或缺目标语言文本：跳过
+        - 不产生 N+1（主体+画像一次，flags 一次）
+        """
+
+        unique_ids = _dedupe_preserve_order(content_ids)
+        if not unique_ids:
+            return []
+
+        # locale 文本存在性过滤（不允许语言回退）
+        # en -> 必须 text_en；tc -> 必须 text_tc
+        # 过滤在 DB 层做，避免后续组装无意义
+        from app.features.personalized_reco.content_repository.types import normalize_locale
+
+        loc = normalize_locale(locale)
+        text_filter = Content.text_en.is_not(None) if loc == "en" else Content.text_tc.is_not(None)
+
+        stmt: Select = (
+            select(Content, ContentProfile)
+            .join(ContentProfile, Content.content_id == ContentProfile.content_id)
+            .where(and_(Content.content_id.in_(unique_ids), text_filter))
+        )
+
+        rows = (await self._session.execute(stmt)).all()
+        if not rows:
+            return []
+
+        # 先组装主体+画像，后续再补 risk_flags
+        by_id: dict[int, dict[str, Any]] = {}
+        valid_ids: list[int] = []
+        for content, profile in rows:
+            cid = int(content.content_id)
+            text = pick_text(text_en=content.text_en, text_tc=content.text_tc, locale=locale)
+            if not text:
+                continue
+            by_id[cid] = {
+                "content": content,
+                "profile": profile,
+                "text": text,
+            }
+            valid_ids.append(cid)
+
+        if not by_id:
+            return []
+
+        # 批量取 flags（避免 join 行膨胀）
+        flags_stmt = select(ContentRiskFlag.content_id, ContentRiskFlag.flag).where(
+            ContentRiskFlag.content_id.in_(list(by_id.keys()))
+        )
+        flags_rows = (await self._session.execute(flags_stmt)).all()
+        flags_map: dict[int, list[str]] = defaultdict(list)
+        for cid, flag in flags_rows:
+            flags_map[int(cid)].append(str(flag))
+
+        result_by_id: dict[int, ContentProfileDTO] = {}
+        for cid, payload in by_id.items():
+            content: Content = payload["content"]
+            profile: ContentProfile = payload["profile"]
+            text: str = payload["text"]
+
+            dto = ContentProfileDTO(
+                content_id=cid,
+                text=text,
+                stage=profile.stage,  # type: ignore[arg-type]
+                emotion_score=float(profile.emotion_score) if profile.emotion_score is not None else None,
+                context_suitability=normalize_suitability(profile.context_suitability_json, keys=CONTEXT_KEYS),
+                need_suitability=normalize_suitability(profile.need_suitability_json, keys=NEED_KEYS),
+                personalization_power=normalize_personalization_power(profile.personalization_power),
+                risk_flags=normalize_risk_flags(flags_map.get(cid)),
+                author_id=content.author_id,
+                template_id=content.template_id,
+                review_confidence=normalize_review_confidence(profile.review_confidence),
+            )
+            result_by_id[cid] = dto
+
+        # 按输入顺序返回（跳过缺失/被过滤的）
+        out: list[ContentProfileDTO] = []
+        for cid in unique_ids:
+            dto = result_by_id.get(cid)
+            if dto is not None:
+                out.append(dto)
+        return out
+
+    async def fetch_candidates(
+        self,
+        *,
+        scene: str,
+        user_profile: object,
+        fallback_level: int,
+        limit: int,
+        locale: str,
+        exclude_content_ids: list[int] | None = None,
+    ) -> list[ContentProfileDTO]:
+        """
+        两段式候选召回：
+        1) 先查候选 content_id 列表（含粗过滤、locale 过滤、limit*multiplier）
+        2) 再批量补全字段（复用 fetch_contents_by_ids）
+        """
+
+        if limit <= 0:
+            return []
+
+        signals = _extract_user_signals(user_profile)
+        effective_fallback = int(fallback_level)
+        if signals.missing_need or signals.missing_context or signals.missing_emotion:
+            effective_fallback = max(effective_fallback, 1)
+
+        # locale 文本存在性过滤（不允许语言回退）
+        from app.features.personalized_reco.content_repository.types import normalize_locale
+
+        loc = normalize_locale(locale)
+        text_filter = Content.text_en.is_not(None) if loc == "en" else Content.text_tc.is_not(None)
+
+        filters: list[Any] = [text_filter]
+        if exclude_content_ids:
+            filters.append(not_(Content.content_id.in_(exclude_content_ids)))
+
+        # fallback 约束（repository 只做“降级约束”，不做 hard filter）
+        if effective_fallback >= 1:
+            # personalization_power <= 5 代表 <= 0.5
+            filters.append(ContentProfile.personalization_power <= 5)
+        if effective_fallback >= 2:
+            filters.append(ContentProfile.personalization_power == 0)
+            filters.append(ContentProfile.stage == "general")
+        if effective_fallback >= 3:
+            filters.append(ContentProfile.is_safe_pool.is_(True))
+            filters.append(ContentProfile.personalization_power == 0)
+            filters.append(ContentProfile.stage == "general")
+
+        # stage 粗过滤（仅 L0/L1 才做“用户阶段 + general”；L2/L3 已强制 general）
+        if effective_fallback < 2:
+            user_stage = signals.stage
+            if user_stage in {"expecting", "parenting"}:
+                filters.append(ContentProfile.stage.in_([user_stage, "general"]))
+            else:
+                # unknown 或无法判定：仅取 general，避免误推
+                filters.append(ContentProfile.stage == "general")
+
+        multiplier = 5
+        raw_limit = max(limit * multiplier, limit)
+
+        stmt_ids = (
+            select(Content.content_id)
+            .join(ContentProfile, Content.content_id == ContentProfile.content_id)
+            .where(and_(*filters))
+            .order_by(desc(ContentProfile.updated_at))
+            .limit(raw_limit)
+        )
+
+        candidate_ids_rows = (await self._session.execute(stmt_ids)).scalars().all()
+        candidate_ids = [int(x) for x in candidate_ids_rows]
+        if not candidate_ids:
+            return []
+
+        # 复用按 ID 批量补全（会再次做 locale 过滤，但成本可接受，且可保证一致行为）
+        items = await self.fetch_contents_by_ids(content_ids=candidate_ids, locale=locale)
+        return items[:limit]
+

server/app/features/personalized_reco/content_repository/types.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+# 当前阶段仅支持 EN / TC（繁体中文）
+Locale = Literal["en", "tc"]
+
+
+def normalize_locale(locale: str) -> Locale:
+    """
+    将客户端传入的 locale 归一化为内部枚举（仅 EN / TC）。
+
+    约定：
+    - 任何以 "en" 开头的 locale 归一化为 "en"（例如 en、en-US）
+    - "tc"/"zh-TW"/"zh-HK" 归一化为 "tc"
+    - 其他 locale 视为不支持
+    """
+
+    raw = (locale or "").strip()
+    if not raw:
+        raise ValueError("locale 不能为空（当前仅支持 en/tc）")
+
+    low = raw.lower()
+    if low.startswith("en"):
+        return "en"
+    if low in {"tc", "zh-tw", "zh-hk", "zh_tw", "zh_hk"}:
+        return "tc"
+
+    raise ValueError(f"不支持的 locale：{locale!r}（当前仅支持 en/tc）")
+
+
+ContentStage = Literal["general", "expecting", "parenting", "unknown"]
+
+
+class ContentProfileDTO(BaseModel):
+    """
+    推荐模块消费的内容画像（稳定字段契约）。
+
+    注意：
+    - text 已按 locale 选择，不允许语言回退（缺语言文本的内容不返回）
+    - emotion_score 为 None 表示 general
+    - personalization_power 对上统一为 0/0.5/1
+    - review_confidence 缺失时兜底 0.7
+    """
+
+    content_id: int
+    text: str
+    stage: ContentStage
+    emotion_score: Optional[float] = None
+
+    context_suitability: dict[str, float] = Field(default_factory=dict)
+    need_suitability: dict[str, float] = Field(default_factory=dict)
+
+    personalization_power: float
+    risk_flags: list[str] = Field(default_factory=list)
+
+    # 可选字段
+    author_id: Optional[str] = None
+    template_id: Optional[str] = None
+    review_confidence: float = 0.7
+

server/app/features/personalized_reco/observability/__init__.py

@@ -0,0 +1,20 @@
+"""
+个性化推荐｜Observability 子模块（可观测性与打点载荷）
+
+说明：
+- 只负责统一 `RecoMeta` 结构与构建（builder），不负责埋点 SDK/落库/上报实现。
+- `RecoMeta` 需要同时被 `reco-engine` 与 `integration-api-worker` 使用。
+"""
+
+from .builder import RecoMetaBuilder
+from .types import MissingFields, RecoMeta
+from .utils import compute_empty_reason, compute_missing_fields
+
+__all__ = [
+    "MissingFields",
+    "RecoMeta",
+    "RecoMetaBuilder",
+    "compute_empty_reason",
+    "compute_missing_fields",
+]
+

server/app/features/personalized_reco/observability/builder.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any, Optional
+
+from app.features.personalized_reco.observability.types import MissingFields, RecoMeta, Scene
+from app.features.personalized_reco.observability.utils import compute_empty_reason, compute_missing_fields
+
+logger = logging.getLogger(__name__)
+
+
+def _non_negative_int(value: Any, *, default: int = 0) -> int:
+    try:
+        n = int(value)
+    except Exception:
+        return int(default)
+    return max(0, int(n))
+
+
+class RecoMetaBuilder:
+    """
+    在推荐 pipeline 中逐阶段填充 RecoMeta，避免“散落字段/散落日志”。
+
+    说明（V1）：
+    - set 调用允许任意顺序；build 时会做防御式兜底与单调性修正
+    - 单调性约束：raw >= after_hard_filter >= after_dedup >= after_freqcap >= served_k
+    """
+
+    def __init__(self, *, scene: Scene, user_profile: object, k: int, now: Optional[datetime] = None) -> None:
+        self.scene: Scene = scene
+        self.user_profile = user_profile
+        self.k = _non_negative_int(k, default=0)
+        self.now = now
+
+        self._raw: Optional[int] = None
+        self._after_hard: Optional[int] = None
+        self._after_dedup: Optional[int] = None
+        self._after_freqcap: Optional[int] = None
+        self._served_k: Optional[int] = None
+        self._fallback_level_final: Optional[int] = None
+
+        self._risk_filtered_count_by_flag: dict[str, int] = {}
+        self._freqcap_filtered_counts: dict[str, int] = {}
+        self._config_snapshot: dict[str, Any] = {}
+
+    def set_candidate_pool_size_raw(self, n: Any) -> "RecoMetaBuilder":
+        self._raw = _non_negative_int(n)
+        return self
+
+    def set_after_hard_filter(self, n: Any, *, risk_filtered_count_by_flag: Optional[dict[str, Any]] = None) -> "RecoMetaBuilder":
+        self._after_hard = _non_negative_int(n)
+        if risk_filtered_count_by_flag:
+            self._risk_filtered_count_by_flag = {str(k): _non_negative_int(v) for k, v in risk_filtered_count_by_flag.items()}
+        return self
+
+    def set_after_dedup(self, n: Any) -> "RecoMetaBuilder":
+        self._after_dedup = _non_negative_int(n)
+        return self
+
+    def set_after_freqcap(self, n: Any, *, freqcap_filtered_counts: Optional[dict[str, Any]] = None) -> "RecoMetaBuilder":
+        self._after_freqcap = _non_negative_int(n)
+        if freqcap_filtered_counts:
+            self._freqcap_filtered_counts = {str(k): _non_negative_int(v) for k, v in freqcap_filtered_counts.items()}
+        return self
+
+    def set_fallback_level_final(self, level: Any, *, reason: Optional[str] = None) -> "RecoMetaBuilder":
+        # reason 预留，V1 先不入 meta（可放入 config_snapshot 或后续字段）
+        self._fallback_level_final = _non_negative_int(level, default=0)
+        if reason:
+            self._config_snapshot.setdefault("fallback_trigger_reason", str(reason))
+        return self
+
+    def set_served_k(self, n: Any) -> "RecoMetaBuilder":
+        self._served_k = _non_negative_int(n)
+        return self
+
+    def set_config_snapshot(self, snapshot: dict[str, Any]) -> "RecoMetaBuilder":
+        self._config_snapshot = dict(snapshot or {})
+        return self
+
+    def build(self) -> RecoMeta:
+        missing: MissingFields = compute_missing_fields(self.user_profile)
+        conf_u = getattr(self.user_profile, "profile_confidence", 1.0)
+        try:
+            conf_u_f = float(conf_u)
+        except Exception:
+            conf_u_f = 1.0
+        if conf_u_f != conf_u_f:
+            conf_u_f = 1.0
+
+        raw = self._raw if self._raw is not None else 0
+        after_hard = self._after_hard if self._after_hard is not None else raw
+        after_dedup = self._after_dedup if self._after_dedup is not None else after_hard
+        after_freqcap = self._after_freqcap if self._after_freqcap is not None else after_dedup
+        served_k = self._served_k if self._served_k is not None else 0
+
+        # 防御式单调性修正（以最保守值输出）
+        if after_hard > raw:
+            logger.debug("after_hard_filter(%s) > raw(%s)，已修正为 raw", after_hard, raw)
+            after_hard = raw
+        if after_dedup > after_hard:
+            logger.debug("after_dedup(%s) > after_hard_filter(%s)，已修正为 after_hard_filter", after_dedup, after_hard)
+            after_dedup = after_hard
+        if after_freqcap > after_dedup:
+            logger.debug("after_freqcap(%s) > after_dedup(%s)，已修正为 after_dedup", after_freqcap, after_dedup)
+            after_freqcap = after_dedup
+        if served_k > after_freqcap:
+            logger.debug("served_k(%s) > after_freqcap(%s)，已修正为 after_freqcap", served_k, after_freqcap)
+            served_k = after_freqcap
+
+        fallback_level_final = self._fallback_level_final if self._fallback_level_final is not None else 0
+
+        empty_reason = compute_empty_reason(
+            served_k=served_k,
+            candidate_pool_size_raw=raw,
+            candidate_pool_size_after_hard_filter=after_hard,
+            candidate_pool_size_after_freqcap=after_freqcap,
+        )
+
+        return RecoMeta(
+            scene=self.scene,
+            candidate_pool_size_raw=int(raw),
+            candidate_pool_size_after_hard_filter=int(after_hard),
+            candidate_pool_size_after_dedup=int(after_dedup),
+            candidate_pool_size_after_freqcap=int(after_freqcap),
+            fallback_level_final=int(fallback_level_final),
+            served_k=int(served_k),
+            empty_reason=empty_reason,
+            conf_U=float(conf_u_f),
+            missing_fields=missing,
+            risk_filtered_count_by_flag=dict(self._risk_filtered_count_by_flag),
+            freqcap_filtered_counts=dict(self._freqcap_filtered_counts),
+            config_snapshot=dict(self._config_snapshot),
+        )
+

server/app/features/personalized_reco/observability/types.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+Scene = Literal["feed", "push", "widget"]
+
+EmptyReason = Literal["hard_filter_all", "freqcap_all", "pool_empty", "unknown"]
+
+
+class MissingFields(BaseModel):
+    """
+    画像字段缺失情况（布尔结构）。
+    """
+
+    need: bool = False
+    context: bool = False
+    emotion: bool = False
+
+
+class RecoMeta(BaseModel):
+    """
+    推荐模块统一可观测载荷（返回给调用方；调用方负责上报/落库/打点）。
+    """
+
+    scene: Scene
+
+    candidate_pool_size_raw: int = 0
+    candidate_pool_size_after_hard_filter: int = 0
+    candidate_pool_size_after_dedup: int = 0
+    candidate_pool_size_after_freqcap: int = 0
+
+    fallback_level_final: int = 0
+    served_k: int = 0
+
+    # served_k=0 时必填；served_k>0 时建议为 None
+    empty_reason: Optional[EmptyReason] = None
+
+    conf_U: float = 1.0
+    missing_fields: MissingFields = Field(default_factory=MissingFields)
+
+    # 可选：Hard Filter 风险命中统计（按 flag 聚合）
+    risk_filtered_count_by_flag: dict[str, int] = Field(default_factory=dict)
+
+    # 可选：Freqcap 过滤统计（sentence/author/template）
+    freqcap_filtered_counts: dict[str, int] = Field(default_factory=dict)
+
+    # 可选：调参快照（V1 可先只在内部事件使用）
+    config_snapshot: dict[str, Any] = Field(default_factory=dict)
+

server/app/features/personalized_reco/observability/utils.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from app.features.personalized_reco.observability.types import EmptyReason, MissingFields
+
+
+def compute_missing_fields(user_profile: object) -> MissingFields:
+    """
+    判定用户画像缺失字段（对齐算法规则 V1.2 口径）。
+
+    规则：
+    - need：user_profile.need 为空对象 {} 或不存在
+    - context：user_profile.context 为空对象 {} 或不存在
+    - emotion：user_profile.emotion_score 为 None 或不存在
+    """
+
+    need = getattr(user_profile, "need", None)
+    context = getattr(user_profile, "context", None)
+    emotion_score = getattr(user_profile, "emotion_score", None)
+
+    need_missing = not bool(need)
+    context_missing = not bool(context)
+    emotion_missing = emotion_score is None
+
+    return MissingFields(need=need_missing, context=context_missing, emotion=emotion_missing)
+
+
+def compute_empty_reason(
+    *,
+    served_k: int,
+    candidate_pool_size_raw: int,
+    candidate_pool_size_after_hard_filter: int,
+    candidate_pool_size_after_freqcap: int,
+) -> Optional[EmptyReason]:
+    """
+    判定 empty_reason（served_k=0 必填）。
+
+    规则（对齐 plan）：
+    - served_k>0 -> None
+    - raw==0 -> pool_empty
+    - raw>0 且 after_hard_filter==0 -> hard_filter_all
+    - after_freqcap==0 -> freqcap_all
+    - 其他 -> unknown
+    """
+
+    if int(served_k) > 0:
+        return None
+
+    raw = int(candidate_pool_size_raw)
+    after_hard = int(candidate_pool_size_after_hard_filter)
+    after_freqcap = int(candidate_pool_size_after_freqcap)
+
+    if raw == 0:
+        return "pool_empty"
+    if raw > 0 and after_hard == 0:
+        return "hard_filter_all"
+    if after_freqcap == 0:
+        return "freqcap_all"
+    return "unknown"
+

server/app/features/personalized_reco/reco_engine/__init__.py

@@ -0,0 +1,11 @@
+"""
+Reco Engine（推荐引擎编排）。
+
+该模块负责将候选拉取、硬过滤、软打分、重排/频控、回退梯度串成一个稳定 Pipeline，
+并输出统一结构：items + meta（可观测字段）。
+"""
+
+from app.features.personalized_reco.reco_engine.orchestrator import recommend
+
+__all__ = ["recommend"]
+

server/app/features/personalized_reco/reco_engine/defaults.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from app.features.personalized_reco.reco_engine.types import RecoEngineConfig, Scene
+
+
+def get_default_engine_config(scene: Scene) -> RecoEngineConfig:
+    """
+    获取推荐引擎默认配置（返回副本，避免被意外修改）。
+    """
+
+    # V1：三种场景目前共用一套默认值；保留 scene 参数便于后续按场景拆分
+    base = RecoEngineConfig()
+    return RecoEngineConfig.model_validate(base.model_dump())
+

server/app/features/personalized_reco/reco_engine/hard_filter.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any, Iterable, Optional
+
+from app.features.personalized_reco.content_repository.types import ContentProfileDTO
+from app.features.personalized_reco.reco_engine.types import HardFilterResult, RecoConstraints, Scene
+
+
+def _user_stage_key(user_profile: object) -> str:
+    """
+    从 user_profile.stage(one-hot) 提取用户阶段。
+    约定：unknown 通常必填，但这里做防御。
+    """
+
+    stage_obj = getattr(user_profile, "stage", None)
+    if stage_obj is None:
+        return "unknown"
+    if getattr(stage_obj, "expecting", 0) == 1:
+        return "expecting"
+    if getattr(stage_obj, "parenting", 0) == 1:
+        return "parenting"
+    return "unknown"
+
+
+def _user_emotion_score(user_profile: object) -> Optional[float]:
+    v = getattr(user_profile, "emotion_score", None)
+    if v is None:
+        return None
+    try:
+        f = float(v)
+    except Exception:
+        return None
+    if f != f:
+        return None
+    return f
+
+
+def _count_hits(counter: dict[str, int], hits: Iterable[str]) -> None:
+    for h in hits:
+        counter[str(h)] += 1
+
+
+def hard_filter(
+    *,
+    scene: Scene,
+    user_profile: object,
+    candidates: list[ContentProfileDTO],
+    constraints: Optional[RecoConstraints] = None,
+) -> HardFilterResult:
+    """
+    Hard Filter（硬过滤）。
+
+    V1：仅实现硬规则集合（不做软惩罚，不做扩展 hard_rules）。
+    """
+
+    cons = constraints or RecoConstraints()
+
+    exclude_author_ids = set([a for a in (cons.exclude_author_ids or []) if a is not None and str(a).strip() != ""])
+    exclude_template_ids = set([t for t in (cons.exclude_template_ids or []) if t is not None and str(t).strip() != ""])
+    exclude_content_ids = set([int(x) for x in (cons.exclude_content_ids or []) if x is not None])
+
+    u_stage = _user_stage_key(user_profile)
+    u_emotion = _user_emotion_score(user_profile)
+    emotion_low = u_emotion is not None and float(u_emotion) <= 0.2
+
+    kept: list[ContentProfileDTO] = []
+    removed_count = 0
+
+    # 统计：按命中 key 聚合计数（risk_flags 直接用 flag 字符串；跨维度/约束用 rule:* / constraint:* 前缀）
+    hit_counts: dict[str, int] = defaultdict(int)
+    hits_by_content_id: dict[int, list[str]] = {}
+
+    for c in candidates or []:
+        cid = int(c.content_id)
+        hits: list[str] = []
+
+        # 约束：按 content_id/author_id/template_id 排除（视为硬过滤）
+        if cid in exclude_content_ids:
+            hits.append("constraint:exclude_content_id")
+        if c.author_id and c.author_id in exclude_author_ids:
+            hits.append("constraint:exclude_author_id")
+        if c.template_id and c.template_id in exclude_template_ids:
+            hits.append("constraint:exclude_template_id")
+
+        flags = set([str(x) for x in (c.risk_flags or []) if x is not None and str(x).strip() != ""])
+
+        # 全场景必挡
+        if "block_health_medical" in flags:
+            hits.append("block_health_medical")
+
+        # 与用户阶段相关
+        if u_stage == "unknown" and "unsafe_for_stage_unknown" in flags:
+            hits.append("unsafe_for_stage_unknown")
+        if u_stage == "parenting" and "unsafe_for_stage_parenting" in flags:
+            hits.append("unsafe_for_stage_parenting")
+
+        # 与用户情绪相关
+        if emotion_low and "unsafe_for_emotion_low" in flags:
+            hits.append("unsafe_for_emotion_low")
+
+        # 跨维度规则：unknown stage + parenting_pressure 强命中 + 高个性化
+        if u_stage == "unknown":
+            try:
+                need_val = float(c.need_suitability.get("parenting_pressure", 0.0))
+            except Exception:
+                need_val = 0.0
+            if need_val >= 1.0 and float(getattr(c, "personalization_power", 0.0)) >= 1.0:
+                hits.append("rule:unknown_stage_parenting_pressure_power1")
+
+        if hits:
+            removed_count += 1
+            # 单条去重后再计数，避免同 key 重复
+            uniq_hits = sorted(set(hits))
+            hits_by_content_id[cid] = uniq_hits
+            _count_hits(hit_counts, uniq_hits)
+            continue
+
+        hits_by_content_id[cid] = []
+        kept.append(c)
+
+    return HardFilterResult(
+        kept_items=kept,
+        removed_count=int(removed_count),
+        risk_filtered_count_by_flag=dict(hit_counts),
+        hits_by_content_id=hits_by_content_id,
+    )
+

server/app/features/personalized_reco/reco_engine/orchestrator.py

@@ -0,0 +1,396 @@
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from datetime import datetime
+from typing import Any, Optional
+
+from app.features.personalized_reco.content_repository.interface import ContentRepository
+from app.features.personalized_reco.content_repository.types import ContentProfileDTO, normalize_locale
+from app.features.personalized_reco.observability.builder import RecoMetaBuilder
+from app.features.personalized_reco.reco_engine.defaults import get_default_engine_config
+from app.features.personalized_reco.reco_engine.hard_filter import hard_filter
+from app.features.personalized_reco.reco_engine.types import RecoConstraints, RecoEngineConfig, RecoEngineResult, RecommendedItem, Scene
+from app.features.personalized_reco.reco_engine.utils import (
+    clamp_personalization_power,
+    merge_exclude_ids,
+    normalize_or_default_locale,
+)
+from app.features.personalized_reco.rerank_freqcap.rerank import rerank_and_freqcap
+from app.features.personalized_reco.rerank_freqcap.types import ScoredCandidate
+from app.features.personalized_reco.scoring.defaults import get_default_config as get_default_score_config
+from app.features.personalized_reco.scoring.score import score_content
+
+logger = logging.getLogger(__name__)
+
+
+def _safe_int(value: Any, *, default: int = 0) -> int:
+    try:
+        n = int(value)
+    except Exception:
+        return int(default)
+    return int(n)
+
+
+def _light_score_summary(score_result: Any) -> dict[str, Any]:
+    """
+    轻量 explanations：只保留少量关键字段，避免 payload 过大。
+    """
+
+    bd = getattr(score_result, "breakdown", None)
+    if bd is None:
+        return {}
+
+    def _get(name: str) -> Optional[float]:
+        v = getattr(bd, name, None)
+        if v is None:
+            return None
+        try:
+            f = float(v)
+        except Exception:
+            return None
+        if f != f:
+            return None
+        return f
+
+    out: dict[str, Any] = {
+        "missing_fields": list(getattr(bd, "missing_fields", []) or []),
+        "S_core": _get("S_core"),
+        "S_personal": _get("S_personal"),
+        "P_uncertainty": _get("P_uncertainty"),
+        "P_risk": _get("P_risk"),
+        "P_widget_emotion_out_of_range": _get("P_widget_emotion_out_of_range"),
+    }
+    # 删除 None，减少噪音
+    return {k: v for k, v in out.items() if v is not None and v != []}
+
+
+def _apply_fallback_level_to_content(content: ContentProfileDTO, *, fallback_level: int) -> ContentProfileDTO:
+    """
+    对内容做防御式一致性处理（与回退梯度一致）。
+    """
+
+    p2 = clamp_personalization_power(content.personalization_power, fallback_level=fallback_level)
+    if p2 == content.personalization_power:
+        return content
+    return content.model_copy(update={"personalization_power": float(p2)})
+
+
+def _merge_counter(dst: dict[str, int], src: dict[str, Any]) -> None:
+    for k, v in (src or {}).items():
+        try:
+            n = int(v)
+        except Exception:
+            n = 0
+        dst[str(k)] = int(dst.get(str(k), 0)) + max(0, int(n))
+
+
+async def recommend(
+    *,
+    repo: ContentRepository,
+    scene: Scene,
+    user_profile: object,
+    already_recommended_ids: list[Any],
+    touched_or_viewed_ids: list[Any],
+    k: int,
+    now: datetime,
+    locale: Optional[str] = None,
+    constraints: Optional[RecoConstraints] = None,
+    config: Optional[RecoEngineConfig] = None,
+) -> RecoEngineResult:
+    """
+    Reco Engine 主入口：编排候选→过滤→打分→重排→回退，并输出 items + meta。
+    """
+
+    cfg = config or get_default_engine_config(scene)
+    cons = constraints or RecoConstraints()
+
+    k_i = max(0, _safe_int(k, default=0))
+    meta_builder = RecoMetaBuilder(scene=scene, user_profile=user_profile, k=k_i, now=now)
+
+    if k_i <= 0:
+        meta_builder.set_candidate_pool_size_raw(0).set_after_hard_filter(0).set_after_dedup(0).set_after_freqcap(0).set_served_k(0).set_fallback_level_final(0)
+        meta_builder.set_config_snapshot({"engine_note": "k<=0，直接返回空结果"})
+        return RecoEngineResult(items=[], meta=meta_builder.build())
+
+    # locale：默认 en；严格校验仅支持 en/tc
+    raw_locale = normalize_or_default_locale(locale)
+    try:
+        effective_locale = normalize_locale(raw_locale)
+    except Exception as e:
+        meta_builder.set_config_snapshot({"error": str(e), "stage": "normalize_locale", "locale": raw_locale})
+        meta_builder.set_candidate_pool_size_raw(0).set_after_hard_filter(0).set_after_dedup(0).set_after_freqcap(0).set_served_k(0).set_fallback_level_final(0)
+        return RecoEngineResult(items=[], meta=meta_builder.build())
+
+    # 聚合统计（跨回退层级累加，确保 meta 单调性成立）
+    raw_total = 0
+    after_hard_total = 0
+    after_dedup_total = 0
+    after_freqcap_total = 0
+
+    risk_counts_total: dict[str, int] = defaultdict(int)
+    freqcap_counts_total: dict[str, int] = defaultdict(int)
+
+    fallback_trace: list[dict[str, Any]] = []
+    selected: list[ScoredCandidate] = []
+    selected_level_by_id: dict[int, int] = {}
+
+    last_fallback_level = 0
+    last_reason = None
+
+    for level in [0, 1, 2, 3]:
+        last_fallback_level = int(level)
+        k_remaining = max(0, k_i - len(selected))
+        if k_remaining <= 0:
+            break
+
+        # Feed：允许不足且不补齐时，拿到任何结果就停止
+        if scene == "feed" and cfg.feed_allow_partial and (not cfg.feed_fill_with_fallback) and len(selected) > 0:
+            break
+
+        # exclude_ids：already/touched + constraints.exclude + 已选内容（避免跨层重复）
+        exclude_ids = merge_exclude_ids(
+            already_recommended_ids=list(already_recommended_ids or []) + [int(x.content_id) for x in selected],
+            touched_or_viewed_ids=list(touched_or_viewed_ids or []),
+            extra_exclude_content_ids=list(cons.exclude_content_ids or []),
+        )
+
+        multiplier = int(cfg.candidate_multiplier_feed if scene == "feed" else cfg.candidate_multiplier_push_widget)
+        base_limit = max(int(cfg.min_candidates_per_level), int(k_remaining) * max(1, int(multiplier)))
+        if cons.max_candidates_limit is not None and int(cons.max_candidates_limit) > 0:
+            limit = min(base_limit, int(cons.max_candidates_limit))
+        else:
+            limit = base_limit
+
+        # 1) Candidate
+        try:
+            cands = await repo.fetch_candidates(
+                scene=scene,
+                user_profile=user_profile,
+                fallback_level=int(level),
+                limit=int(limit),
+                locale=str(effective_locale),
+                exclude_content_ids=exclude_ids,
+            )
+        except Exception as e:
+            logger.exception("fetch_candidates 失败：%s", e)
+            last_reason = "error:fetch_candidates"
+            fallback_trace.append(
+                {
+                    "level": int(level),
+                    "raw": 0,
+                    "after_hard": 0,
+                    "after_dedup": 0,
+                    "after_freqcap": 0,
+                    "served_total": len(selected),
+                    "error": str(e),
+                }
+            )
+            continue
+
+        raw_total += len(cands)
+
+        if not cands:
+            last_reason = "pool_empty"
+            fallback_trace.append(
+                {
+                    "level": int(level),
+                    "raw": 0,
+                    "after_hard": 0,
+                    "after_dedup": 0,
+                    "after_freqcap": 0,
+                    "served_total": len(selected),
+                    "reason": "pool_empty",
+                }
+            )
+            continue
+
+        # 2) Hard Filter
+        hf = hard_filter(scene=scene, user_profile=user_profile, candidates=cands, constraints=cons)
+        kept = [x for x in hf.kept_items if isinstance(x, ContentProfileDTO)]
+        after_hard_total += len(kept)
+        _merge_counter(risk_counts_total, hf.risk_filtered_count_by_flag)
+
+        if not kept:
+            last_reason = "hard_filter_all"
+            fallback_trace.append(
+                {
+                    "level": int(level),
+                    "raw": len(cands),
+                    "after_hard": 0,
+                    "after_dedup": 0,
+                    "after_freqcap": 0,
+                    "served_total": len(selected),
+                    "reason": "hard_filter_all",
+                }
+            )
+            continue
+
+        # 3) Soft Scoring
+        score_cfg = get_default_score_config(scene)
+        if scene == "push":
+            # Push：强制启用不确定性惩罚（与 spec 对齐）
+            score_cfg = score_cfg.model_copy(update={"enable_uncertainty_penalty": True})
+
+        scored: list[ScoredCandidate] = []
+        for c in kept:
+            c2 = _apply_fallback_level_to_content(c, fallback_level=int(level))
+            try:
+                s = score_content(scene=scene, user_profile=user_profile, content_profile=c2, config=score_cfg, pass_filters=True, now=now)
+            except Exception as e:
+                # 单条异常不影响整体
+                logger.exception("score_content 失败 content_id=%s：%s", getattr(c2, "content_id", None), e)
+                continue
+
+            cid = int(c2.content_id)
+            hits = hf.hits_by_content_id.get(cid, [])
+            extra: dict[str, Any] = {
+                "text": c2.text,
+                "fallback_level_used": int(level),
+            }
+            if cfg.enable_explanations:
+                extra["hard_filter_hits"] = hits
+                extra["score_summary"] = _light_score_summary(s)
+
+            scored.append(
+                ScoredCandidate(
+                    content_id=cid,
+                    final_score=float(getattr(s, "final_score", 0.0)),
+                    author_id=c2.author_id,
+                    template_id=c2.template_id,
+                    content_profile=c2,
+                    extra=extra,
+                )
+            )
+
+        if not scored:
+            last_reason = "empty_after_scoring"
+            fallback_trace.append(
+                {
+                    "level": int(level),
+                    "raw": len(cands),
+                    "after_hard": len(kept),
+                    "after_dedup": 0,
+                    "after_freqcap": 0,
+                    "served_total": len(selected),
+                    "reason": "empty_after_scoring",
+                }
+            )
+            continue
+
+        # 4) Rerank/Freqcap
+        try:
+            rer = rerank_and_freqcap(
+                scene=scene,
+                scored_candidates=scored,
+                already_recommended_ids=list(already_recommended_ids or []) + [int(x.content_id) for x in selected],
+                touched_or_viewed_ids=list(touched_or_viewed_ids or []),
+                k=int(k_remaining),
+                recent_author_ids=cons.recent_author_ids,
+                recent_template_ids=cons.recent_template_ids,
+            )
+        except Exception as e:
+            logger.exception("rerank_and_freqcap 失败：%s", e)
+            last_reason = "error:rerank_and_freqcap"
+            fallback_trace.append(
+                {
+                    "level": int(level),
+                    "raw": len(cands),
+                    "after_hard": len(kept),
+                    "after_dedup": 0,
+                    "after_freqcap": 0,
+                    "served_total": len(selected),
+                    "error": str(e),
+                }
+            )
+            continue
+
+        after_dedup_total += int(rer.meta.candidate_pool_size_after_dedup)
+        after_freqcap_total += int(rer.meta.candidate_pool_size_after_freqcap)
+        _merge_counter(freqcap_counts_total, rer.meta.freqcap_filtered_counts)
+
+        served_level = list(rer.ranked_items or [])[:k_remaining]
+        if not served_level:
+            last_reason = "freqcap_all"
+            fallback_trace.append(
+                {
+                    "level": int(level),
+                    "raw": len(cands),
+                    "after_hard": len(kept),
+                    "after_dedup": int(rer.meta.candidate_pool_size_after_dedup),
+                    "after_freqcap": int(rer.meta.candidate_pool_size_after_freqcap),
+                    "served_total": len(selected),
+                    "reason": "freqcap_all",
+                }
+            )
+            continue
+
+        for it in served_level:
+            cid = int(it.content_id)
+            selected.append(it)
+            selected_level_by_id[cid] = int(level)
+
+        last_reason = None
+        fallback_trace.append(
+            {
+                "level": int(level),
+                "raw": len(cands),
+                "after_hard": len(kept),
+                "after_dedup": int(rer.meta.candidate_pool_size_after_dedup),
+                "after_freqcap": int(rer.meta.candidate_pool_size_after_freqcap),
+                "served_total": len(selected),
+                "served_added": len(served_level),
+            }
+        )
+
+        if len(selected) >= k_i:
+            break
+
+    # 组装输出 items（按 selected 顺序）
+    items: list[RecommendedItem] = []
+    for c in selected[:k_i]:
+        cid = int(c.content_id)
+        text = ""
+        if isinstance(c.extra, dict):
+            text = str(c.extra.get("text") or "")
+
+        explanations = None
+        if cfg.enable_explanations and isinstance(c.extra, dict):
+            explanations = {
+                "fallback_level_used": c.extra.get("fallback_level_used"),
+                "hard_filter_hits": c.extra.get("hard_filter_hits"),
+                "score_summary": c.extra.get("score_summary"),
+            }
+
+        items.append(
+            RecommendedItem(
+                content_id=cid,
+                text=text,
+                final_score=float(c.final_score),
+                fallback_level_final=int(selected_level_by_id.get(cid, last_fallback_level)),
+                explanations=explanations,
+            )
+        )
+
+    served_k = len(items)
+
+    # meta：使用聚合统计，确保单调性约束成立（raw>=after_hard>=after_dedup>=after_freqcap>=served_k）
+    # 注意：聚合统计理论上可能出现 after_* > raw_total（例如 repo 返回重复/异常），此处交由 builder 防御修正
+    meta_builder.set_candidate_pool_size_raw(int(raw_total))
+    meta_builder.set_after_hard_filter(int(after_hard_total), risk_filtered_count_by_flag=dict(risk_counts_total))
+    meta_builder.set_after_dedup(int(after_dedup_total))
+    meta_builder.set_after_freqcap(int(after_freqcap_total), freqcap_filtered_counts=dict(freqcap_counts_total))
+    meta_builder.set_served_k(int(served_k))
+    meta_builder.set_fallback_level_final(int(last_fallback_level), reason=last_reason)
+
+    meta_builder.set_config_snapshot(
+        {
+            "fallback_trace": fallback_trace,
+            "engine_config": cfg.model_dump(),
+            "constraints": cons.model_dump(),
+            "locale": effective_locale,
+        }
+    )
+
+    return RecoEngineResult(items=items, meta=meta_builder.build())
+

server/app/features/personalized_reco/reco_engine/types.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from app.features.personalized_reco.observability.types import RecoMeta
+
+Scene = Literal["feed", "push", "widget"]
+
+
+class RecoConstraints(BaseModel):
+    """
+    推荐请求的可选约束（调用方可按需传入）。
+    """
+
+    exclude_content_ids: list[int] = Field(default_factory=list)
+    exclude_author_ids: list[str] = Field(default_factory=list)
+    exclude_template_ids: list[str] = Field(default_factory=list)
+
+    # 候选池上限（用于资源保护）
+    max_candidates_limit: Optional[int] = None
+
+    # Push/Widget 作者/模板冷却窗口内的历史集合（增强频控输入）
+    # 说明：若不提供（None），rerank_freqcap 会记录缺失并跳过该维度过滤
+    recent_author_ids: Optional[list[str]] = None
+    recent_template_ids: Optional[list[str]] = None
+
+
+class RecoEngineConfig(BaseModel):
+    """
+    引擎级配置（V1 可调参项）。
+    """
+
+    # Feed 是否允许 served_k < k（允许不足）
+    feed_allow_partial: bool = True
+    # Feed 是否在不足时继续回退补齐
+    feed_fill_with_fallback: bool = True
+
+    # 候选拉取倍率（limit = min(max_candidates_limit, k * multiplier)）
+    candidate_multiplier_feed: int = 10
+    candidate_multiplier_push_widget: int = 30
+
+    # 每层回退的最大候选数量下限（避免 k=1 但候选过少）
+    min_candidates_per_level: int = 30
+
+    # explanations 默认开启（但应保持轻量）
+    enable_explanations: bool = True
+
+
+class RecommendedItem(BaseModel):
+    """
+    引擎最终下发的推荐项。
+    """
+
+    content_id: int
+    text: str
+    final_score: float
+    fallback_level_final: int
+
+    # 解释信息：默认开启，但建议保持轻量（避免 payload 过大）
+    explanations: Optional[dict[str, Any]] = None
+
+
+class RecoEngineResult(BaseModel):
+    """
+    引擎输出容器：items + meta。
+    """
+
+    items: list[RecommendedItem] = Field(default_factory=list)
+    meta: RecoMeta
+
+
+class HardFilterResult(BaseModel):
+    """
+    Hard Filter 输出。
+    """
+
+    kept_items: list[Any] = Field(default_factory=list)
+    removed_count: int = 0
+    risk_filtered_count_by_flag: dict[str, int] = Field(default_factory=dict)
+    # 每条内容的命中信息（仅用于 explanations；默认可为空）
+    hits_by_content_id: dict[int, list[str]] = Field(default_factory=dict)
+
+
+class RecommendRequest(BaseModel):
+    """
+    内部便捷结构（单测/集成时可用）。
+    """
+
+    scene: Scene
+    user_profile: Any
+    already_recommended_ids: list[Any] = Field(default_factory=list)
+    touched_or_viewed_ids: list[Any] = Field(default_factory=list)
+    k: int = 1
+    now: datetime
+    locale: Optional[str] = None
+    constraints: Optional[RecoConstraints] = None
+    config: Optional[RecoEngineConfig] = None
+

server/app/features/personalized_reco/reco_engine/utils.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional
+
+
+def normalize_int_id_list(mixed_ids: Iterable[Any]) -> list[int]:
+    """
+    将混合类型的 id 列表归一化为 int 列表。
+
+    规则：
+    - int/可转 int 的 str -> int
+    - 其他（None/空字符串/不可解析）忽略
+    """
+
+    out: list[int] = []
+    for x in mixed_ids or []:
+        if x is None:
+            continue
+        if isinstance(x, bool):
+            # 避免 True/False 被当作 1/0
+            continue
+        try:
+            s = str(x).strip()
+            if s == "":
+                continue
+            out.append(int(s))
+        except Exception:
+            continue
+    return out
+
+
+def merge_exclude_ids(
+    *,
+    already_recommended_ids: Iterable[Any],
+    touched_or_viewed_ids: Iterable[Any],
+    extra_exclude_content_ids: Optional[Iterable[int]] = None,
+) -> list[int]:
+    """
+    合并并去重排除 id（保持首次出现顺序）。
+    """
+
+    merged = list(normalize_int_id_list(list(already_recommended_ids or []) + list(touched_or_viewed_ids or [])))
+    if extra_exclude_content_ids:
+        merged += [int(x) for x in extra_exclude_content_ids if x is not None]
+
+    seen: set[int] = set()
+    out: list[int] = []
+    for cid in merged:
+        if cid in seen:
+            continue
+        seen.add(cid)
+        out.append(cid)
+    return out
+
+
+def normalize_or_default_locale(locale: Optional[str]) -> str:
+    """
+    locale 防御式归一化：
+    - 未传/空 -> 默认 "en"
+    - 其他 -> 原样返回，由下游 normalize_locale 做严格校验
+    """
+
+    if locale is None:
+        return "en"
+    raw = str(locale).strip()
+    return raw or "en"
+
+
+def clamp_personalization_power(power: Any, *, fallback_level: int) -> float:
+    """
+    按回退层级对 personalization_power 做防御式约束。
+
+    - L0：不改
+    - L1：<= 0.5
+    - L2/L3：= 0
+    """
+
+    try:
+        p = float(power)
+    except Exception:
+        p = 0.0
+    if p != p:
+        p = 0.0
+
+    if int(fallback_level) >= 2:
+        return 0.0
+    if int(fallback_level) >= 1:
+        return min(p, 0.5)
+    return p
+

server/app/features/personalized_reco/rerank_freqcap/__init__.py

@@ -0,0 +1,22 @@
+"""
+个性化推荐｜Rerank & Freqcap 子模块（重排 / 去重 / 频控）
+
+说明（V1）：
+- 本模块在 Soft Scoring 后执行，消费候选的 `final_score`，输出可下发的排序结果。
+- 仅做 Dedup / Freqcap / Feed MMR，不做 Soft Scoring 与 Hard Filter。
+"""
+
+from .defaults import get_default_config
+from .rerank import rerank_and_freqcap
+from .types import RerankConfig, RerankMeta, RerankResult, ScoredCandidate, Scene
+
+__all__ = [
+    "RerankConfig",
+    "RerankMeta",
+    "RerankResult",
+    "ScoredCandidate",
+    "Scene",
+    "get_default_config",
+    "rerank_and_freqcap",
+]
+

server/app/features/personalized_reco/rerank_freqcap/defaults.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from app.features.personalized_reco.rerank_freqcap.types import RerankConfig, Scene
+
+
+_DEFAULTS: dict[Scene, RerankConfig] = {
+    # Feed：MMR λ=0.7；冷却参数不强制使用
+    "feed": RerankConfig(
+        mmr_lambda=0.7,
+        top_n_for_mmr=200,
+        cooldown_sentence_days=0,
+        cooldown_author_days=0,
+        cooldown_template_days=0,
+    ),
+    # Push：工程默认（来自算法规则的建议参数）
+    "push": RerankConfig(
+        mmr_lambda=0.7,
+        top_n_for_mmr=200,
+        cooldown_sentence_days=14,
+        cooldown_author_days=7,
+        cooldown_template_days=7,
+    ),
+    # Widget：工程默认
+    "widget": RerankConfig(
+        mmr_lambda=0.7,
+        top_n_for_mmr=200,
+        cooldown_sentence_days=7,
+        cooldown_author_days=7,
+        cooldown_template_days=7,
+    ),
+}
+
+
+def get_default_config(scene: Scene) -> RerankConfig:
+    """
+    获取指定场景的默认参数（返回副本，避免被意外修改）。
+    """
+
+    base = _DEFAULTS[scene]
+    return RerankConfig.model_validate(base.model_dump())
+

server/app/features/personalized_reco/rerank_freqcap/rerank.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional
+
+from app.features.personalized_reco.rerank_freqcap.defaults import get_default_config
+from app.features.personalized_reco.rerank_freqcap.types import RerankConfig, RerankMeta, RerankResult, ScoredCandidate, Scene
+from app.features.personalized_reco.rerank_freqcap.utils import as_finite_float, build_tags, clamp, jaccard, normalize_int_id_set
+
+
+def _sort_by_score_desc(cands: list[ScoredCandidate]) -> list[ScoredCandidate]:
+    return sorted(cands, key=lambda x: as_finite_float(x.final_score, default=float("-inf")), reverse=True)
+
+
+def _dedup_by_seen_ids(
+    cands: list[ScoredCandidate],
+    *,
+    seen_ids: set[int],
+) -> tuple[list[ScoredCandidate], int]:
+    kept: list[ScoredCandidate] = []
+    removed = 0
+    for c in cands:
+        if int(c.content_id) in seen_ids:
+            removed += 1
+            continue
+        kept.append(c)
+    return kept, removed
+
+
+def _apply_author_template_freqcap(
+    cands: list[ScoredCandidate],
+    *,
+    recent_author_ids: Optional[Iterable[str]],
+    recent_template_ids: Optional[Iterable[str]],
+) -> tuple[list[ScoredCandidate], dict[str, int], list[str]]:
+    """
+    V1 策略：
+    - 若 recent_*_ids 未提供（None），不执行该维度过滤，但在 meta 记录缺失
+    - 若提供，则执行硬过滤
+    """
+
+    filtered_counts: dict[str, int] = {"author": 0, "template": 0}
+    missing: list[str] = []
+
+    author_set: set[str] | None
+    if recent_author_ids is None:
+        author_set = None
+        missing.append("author")
+    else:
+        author_set = set([a for a in recent_author_ids if a is not None and str(a).strip() != ""])
+
+    template_set: set[str] | None
+    if recent_template_ids is None:
+        template_set = None
+        missing.append("template")
+    else:
+        template_set = set([t for t in recent_template_ids if t is not None and str(t).strip() != ""])
+
+    out: list[ScoredCandidate] = []
+    for c in cands:
+        if author_set is not None and c.author_id and c.author_id in author_set:
+            filtered_counts["author"] += 1
+            continue
+        if template_set is not None and c.template_id and c.template_id in template_set:
+            filtered_counts["template"] += 1
+            continue
+        out.append(c)
+
+    # 只返回真正生效的维度计数（避免 meta 噪音）
+    effective_counts: dict[str, int] = {}
+    if author_set is not None:
+        effective_counts["author"] = int(filtered_counts["author"])
+    if template_set is not None:
+        effective_counts["template"] = int(filtered_counts["template"])
+
+    missing_sorted = sorted(set(missing))
+    return out, effective_counts, missing_sorted
+
+
+def _sim(a: ScoredCandidate, b: ScoredCandidate, *, tags_a: set[str], tags_b: set[str]) -> float:
+    # 离散特征版（V1 推荐），对齐 plan.md
+    if int(a.content_id) == int(b.content_id):
+        return 1.0
+
+    sim = 0.0
+    if a.template_id and b.template_id and a.template_id == b.template_id:
+        sim += 0.6
+    if a.author_id and b.author_id and a.author_id == b.author_id:
+        sim += 0.3
+
+    sim += 0.1 * jaccard(tags_a, tags_b)
+    return clamp(sim, 0.0, 1.0)
+
+
+def _mmr_rerank(
+    *,
+    candidates: list[ScoredCandidate],
+    k: int,
+    lam: float,
+) -> list[ScoredCandidate]:
+    if k <= 0:
+        return []
+
+    if not candidates:
+        return []
+
+    lam_f = clamp(as_finite_float(lam, default=0.7), 0.0, 1.0)
+
+    # 预计算 tags，避免重复构造
+    tags_map: dict[int, set[str]] = {}
+    for c in candidates:
+        tags_map[int(c.content_id)] = build_tags(c)
+
+    remaining = _sort_by_score_desc(list(candidates))
+    selected: list[ScoredCandidate] = []
+
+    # Top1：最高分
+    selected.append(remaining.pop(0))
+
+    while remaining and len(selected) < k:
+        best_idx = 0
+        best_val = float("-inf")
+
+        for idx, c in enumerate(remaining):
+            rel = as_finite_float(c.final_score, default=float("-inf"))
+
+            tags_c = tags_map.get(int(c.content_id), set())
+            max_sim = 0.0
+            for s in selected:
+                tags_s = tags_map.get(int(s.content_id), set())
+                max_sim = max(max_sim, _sim(c, s, tags_a=tags_c, tags_b=tags_s))
+
+            val = lam_f * float(rel) - (1.0 - lam_f) * float(max_sim)
+            if val > best_val:
+                best_val = val
+                best_idx = idx
+
+        selected.append(remaining.pop(best_idx))
+
+    return selected
+
+
+def rerank_and_freqcap(
+    *,
+    scene: Scene,
+    scored_candidates: list[ScoredCandidate],
+    already_recommended_ids: list[Any],
+    touched_or_viewed_ids: list[Any],
+    k: int,
+    config: Optional[RerankConfig] = None,
+    recent_author_ids: Optional[list[str]] = None,
+    recent_template_ids: Optional[list[str]] = None,
+) -> RerankResult:
+    """
+    主入口：对 scored_candidates 做去重/频控/重排，输出最终可下发序列。
+
+    V1 约定：
+    - 冷却窗口“按天”由调用方保证输入集合已经裁剪到窗口内，本模块以“集合代表窗口内历史”为准
+    - Feed 默认只做 dedup + MMR；Push/Widget 做 dedup + freqcap + TopK
+    """
+
+    cfg = config or get_default_config(scene)
+
+    # seen_ids = already_recommended_ids ∪ touched_or_viewed_ids
+    seen_ids = normalize_int_id_set(list(already_recommended_ids) + list(touched_or_viewed_ids))
+
+    # 先按分数降序，保证 Top1 与 TopK 一致
+    base_sorted = _sort_by_score_desc(list(scored_candidates))
+
+    after_dedup, removed_sentence = _dedup_by_seen_ids(base_sorted, seen_ids=seen_ids)
+    candidate_pool_size_after_dedup = len(after_dedup)
+
+    missing_history_fields: list[str] = []
+    freqcap_counts: dict[str, int] = {"sentence": int(removed_sentence)}
+
+    after_freqcap = after_dedup
+
+    # Push/Widget：作者/模板冷却（增强项）
+    if scene in {"push", "widget"}:
+        after_freqcap, dim_counts, missing = _apply_author_template_freqcap(
+            after_freqcap,
+            recent_author_ids=recent_author_ids,
+            recent_template_ids=recent_template_ids,
+        )
+        missing_history_fields = missing
+        freqcap_counts.update(dim_counts)
+    else:
+        # Feed：不强制作者/模板冷却（V1 可选，这里默认跳过）
+        missing_history_fields = []
+
+    candidate_pool_size_after_freqcap = len(after_freqcap)
+
+    ranked: list[ScoredCandidate]
+    if scene == "feed":
+        # MMR 前截断，避免性能问题
+        top_n = int(cfg.top_n_for_mmr) if int(cfg.top_n_for_mmr) > 0 else len(after_freqcap)
+        mmr_pool = after_freqcap[:top_n]
+        ranked = _mmr_rerank(candidates=mmr_pool, k=int(k), lam=cfg.mmr_lambda)
+    else:
+        ranked = after_freqcap[: max(0, int(k))]
+
+    meta = RerankMeta(
+        candidate_pool_size_after_dedup=int(candidate_pool_size_after_dedup),
+        candidate_pool_size_after_freqcap=int(candidate_pool_size_after_freqcap),
+        missing_history_fields=missing_history_fields,
+        freqcap_filtered_counts=freqcap_counts,
+    )
+    return RerankResult(ranked_items=ranked, meta=meta)
+

server/app/features/personalized_reco/rerank_freqcap/types.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from app.features.personalized_reco.content_repository.types import ContentProfileDTO
+
+Scene = Literal["feed", "push", "widget"]
+
+
+class ScoredCandidate(BaseModel):
+    """
+    Soft Scoring 后的候选项（本模块消费的最小字段集合）。
+
+    说明：
+    - `content_profile` 用于 Feed 的标签/相似度计算；缺失时需降级为仅使用 author/template 等字段
+    """
+
+    content_id: int
+    final_score: float
+
+    author_id: Optional[str] = None
+    template_id: Optional[str] = None
+
+    content_profile: Optional[ContentProfileDTO] = None
+
+    # 允许透传额外字段（例如 text、breakdown 等），便于上层直接下发
+    extra: dict[str, Any] = Field(default_factory=dict)
+
+
+class RerankConfig(BaseModel):
+    """
+    重排/频控配置（可调参）。
+    """
+
+    # Feed：MMR
+    mmr_lambda: float = 0.7
+    top_n_for_mmr: int = 200
+
+    # Push/Widget：冷却窗口（V1 主要用于配置与可观测；真正按天需要带时间戳的历史）
+    cooldown_sentence_days: int = 14
+    cooldown_author_days: int = 7
+    cooldown_template_days: int = 7
+
+
+class RerankMeta(BaseModel):
+    candidate_pool_size_after_dedup: int
+    candidate_pool_size_after_freqcap: int
+
+    # 例如未提供 recent_author_ids/recent_template_ids 时记录 ["author","template"]
+    missing_history_fields: list[str] = Field(default_factory=list)
+
+    # 可选但建议：按维度统计被过滤数量
+    freqcap_filtered_counts: dict[str, int] = Field(default_factory=dict)
+
+
+class RerankResult(BaseModel):
+    ranked_items: list[ScoredCandidate] = Field(default_factory=list)
+    meta: RerankMeta
+

server/app/features/personalized_reco/rerank_freqcap/utils.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Iterable
+
+logger = logging.getLogger(__name__)
+
+
+def clamp(value: float, min_value: float, max_value: float) -> float:
+    if value != value:  # NaN
+        return min_value
+    return max(min_value, min(max_value, value))
+
+
+def as_finite_float(value: Any, *, default: float) -> float:
+    try:
+        f = float(value)
+    except Exception:
+        return float(default)
+    if f != f:
+        return float(default)
+    if f == float("inf") or f == float("-inf"):
+        return float(default)
+    return f
+
+
+def normalize_int_id_set(values: Iterable[Any]) -> set[int]:
+    """
+    将历史 ID 列表归一化为 int 集合（支持 str/int 混用）。
+
+    说明：
+    - 无法转换的值会被忽略，并记录 debug 日志（不影响主流程）
+    """
+
+    out: set[int] = set()
+    for v in values:
+        try:
+            if isinstance(v, bool):
+                # 避免 True/False 被当作 1/0
+                raise ValueError("bool 不是合法 id")
+            out.add(int(v))
+        except Exception:
+            logger.debug("历史 id 无法转为 int，已忽略：%r", v)
+    return out
+
+
+def jaccard(a: set[str], b: set[str]) -> float:
+    if not a and not b:
+        return 0.0
+    inter = len(a & b)
+    union = len(a | b)
+    return float(inter) / float(union) if union > 0 else 0.0
+
+
+def argmax_key(d: dict[str, Any] | None) -> str | None:
+    """
+    从 suitability 字典中取最大值 key（V1 用作代表标签）。
+    - 空字典/None -> None
+    - 值非法 -> 按 default=0 处理
+    """
+
+    if not d:
+        return None
+    best_k: str | None = None
+    best_v = float("-inf")
+    for k, v in d.items():
+        fv = as_finite_float(v, default=0.0)
+        if fv > best_v:
+            best_v = fv
+            best_k = k
+    return best_k
+
+
+def build_tags(candidate: Any) -> set[str]:
+    """
+    构造离散标签集合（V1 写死）：
+    - stage:<stage>
+    - need:<argmax_key>
+    - context:<argmax_key>
+
+    说明：
+    - candidate 可能是 ScoredCandidate 或具备 content_profile 的对象
+    - 字段缺失时自动降级（只返回可得标签）
+    """
+
+    tags: set[str] = set()
+
+    cp = getattr(candidate, "content_profile", None)
+    if cp is None:
+        return tags
+
+    stage = getattr(cp, "stage", None)
+    if stage:
+        tags.add(f"stage:{stage}")
+
+    need = getattr(cp, "need_suitability", None)
+    need_k = argmax_key(need)
+    if need_k:
+        tags.add(f"need:{need_k}")
+
+    ctx = getattr(cp, "context_suitability", None)
+    ctx_k = argmax_key(ctx)
+    if ctx_k:
+        tags.add(f"context:{ctx_k}")
+
+    return tags
+

server/app/features/personalized_reco/scoring/__init__.py

@@ -0,0 +1,22 @@
+"""
+个性化推荐｜Scoring 子模块（软打分与惩罚项）
+
+说明：
+- 本模块只做软打分与本模块定义的惩罚项（P_uncertainty、Widget 情绪软降权）。
+- Hard Filter / 频控重排 / 新鲜度等由其他模块产出，通过入参注入（缺省按 0）。
+"""
+
+from .defaults import get_default_config
+from .score import score_content
+from .types import ExternalTerms, Scene, ScoreBreakdown, ScoreConfig, ScoreResult
+
+__all__ = [
+    "ExternalTerms",
+    "Scene",
+    "ScoreBreakdown",
+    "ScoreConfig",
+    "ScoreResult",
+    "get_default_config",
+    "score_content",
+]
+

server/app/features/personalized_reco/scoring/defaults.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from app.features.personalized_reco.scoring.types import Scene, ScoreConfig
+
+
+_DEFAULTS: dict[Scene, ScoreConfig] = {
+    # 来源：设计说明文档/個性化推薦算法規則.md（V1 建议权重）
+    "feed": ScoreConfig(
+        w_need=0.35,
+        w_emotion=0.20,
+        w_stage=0.15,
+        w_context=0.30,
+        # Feed 默认不启用不确定性惩罚（可按需开启）
+        enable_uncertainty_penalty=False,
+    ),
+    "push": ScoreConfig(
+        w_need=0.45,
+        w_emotion=0.35,
+        w_stage=0.15,
+        w_context=0.05,
+        # Push 默认启用不确定性惩罚
+        enable_uncertainty_penalty=True,
+    ),
+    "widget": ScoreConfig(
+        w_need=0.25,
+        w_emotion=0.25,
+        w_stage=0.30,
+        w_context=0.20,
+        # Widget 默认不启用不确定性惩罚（可按需开启）
+        enable_uncertainty_penalty=False,
+        widget_emotion_soft_range=(0.4, 0.8),
+        widget_emotion_penalty_gamma=0.25,
+    ),
+}
+
+
+def get_default_config(scene: Scene) -> ScoreConfig:
+    """
+    获取指定场景的默认打分参数（返回副本，避免被意外修改）。
+    """
+
+    base = _DEFAULTS[scene]
+    return ScoreConfig.model_validate(base.model_dump())
+

server/app/features/personalized_reco/scoring/score.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from app.features.personalized_reco.content_repository.types import ContentProfileDTO
+from app.features.personalized_reco.scoring.defaults import get_default_config
+from app.features.personalized_reco.scoring.types import ExternalTerms, Scene, ScoreBreakdown, ScoreConfig, ScoreResult
+from app.features.personalized_reco.scoring.utils import as_finite_float, clamp, pick_one_hot_key
+from app.features.user_profile_scoring.types import UserProfileV1_2
+
+
+def _missing_fields(user_profile: UserProfileV1_2) -> list[str]:
+    missing: list[str] = []
+    if not user_profile.need:
+        missing.append("need")
+    if not user_profile.context:
+        missing.append("context")
+    if user_profile.emotion_score is None:
+        missing.append("emotion")
+    return missing
+
+
+def _score_need(user_profile: UserProfileV1_2, content: ContentProfileDTO) -> float:
+    key = pick_one_hot_key(user_profile.need)  # type: ignore[arg-type]
+    if key is None:
+        return 0.5
+    raw = content.need_suitability.get(key, 0.5)
+    return clamp(as_finite_float(raw, default=0.5), 0.0, 1.0)
+
+
+def _score_context(user_profile: UserProfileV1_2, content: ContentProfileDTO) -> float:
+    key = pick_one_hot_key(user_profile.context)  # type: ignore[arg-type]
+    if key is None:
+        return 0.5
+    raw = content.context_suitability.get(key, 0.5)
+    return clamp(as_finite_float(raw, default=0.5), 0.0, 1.0)
+
+
+def _score_emotion(user_profile: UserProfileV1_2, content: ContentProfileDTO) -> float:
+    # V1.2：用户情绪缺失 -> 0.8
+    if user_profile.emotion_score is None:
+        return 0.8
+
+    # 文案 general（emotion_score=None）-> 0.8
+    if content.emotion_score is None:
+        return 0.8
+
+    u = clamp(as_finite_float(user_profile.emotion_score, default=0.8), 0.0, 1.0)
+    c = clamp(as_finite_float(content.emotion_score, default=0.8), 0.0, 1.0)
+    return clamp(1.0 - abs(u - c), 0.0, 1.0)
+
+
+def _user_stage_key(user_profile: UserProfileV1_2) -> str:
+    # 约定：UserStageOneHot.unknown 必填；但这里仍做防御
+    stage = user_profile.stage
+    if getattr(stage, "expecting", 0) == 1:
+        return "expecting"
+    if getattr(stage, "parenting", 0) == 1:
+        return "parenting"
+    if getattr(stage, "unknown", 1) == 1:
+        return "unknown"
+    return "unknown"
+
+
+def _score_stage(user_profile: UserProfileV1_2, content: ContentProfileDTO) -> float:
+    # 对齐算法规则：
+    # - general=1；命中=1；unknown对非unknown=0.7；其余=0
+    if content.stage == "general":
+        return 1.0
+
+    u_stage = _user_stage_key(user_profile)
+    if content.stage == u_stage:
+        return 1.0
+
+    if u_stage == "unknown" and content.stage != "unknown":
+        return 0.7
+
+    return 0.0
+
+
+def _score_personal(alpha: float, personalization_power: float, s_need: float, s_context: float) -> float:
+    power = clamp(as_finite_float(personalization_power, default=0.0), 0.0, 1.0)
+    a = as_finite_float(alpha, default=0.0)
+    return float(a) * float(power) * max(float(s_need), float(s_context))
+
+
+def _penalty_uncertainty(beta: float, user_profile: UserProfileV1_2, content: ContentProfileDTO) -> float:
+    b = as_finite_float(beta, default=0.0)
+    power = clamp(as_finite_float(content.personalization_power, default=0.0), 0.0, 1.0)
+
+    # V1 约定：conf_U 缺失时按 1.0（避免过惩罚）
+    conf_u = clamp(as_finite_float(getattr(user_profile, "profile_confidence", 1.0), default=1.0), 0.0, 1.0)
+    conf_c = clamp(as_finite_float(getattr(content, "review_confidence", 0.7), default=0.7), 0.0, 1.0)
+
+    return float(b) * (1.0 - float(conf_u)) * (1.0 - float(conf_c)) * float(power)
+
+
+def _widget_emotion_penalty(scene: Scene, content: ContentProfileDTO, config: ScoreConfig) -> float:
+    if scene != "widget":
+        return 0.0
+    if content.emotion_score is None:
+        return 0.0
+
+    lo, hi = config.widget_emotion_soft_range
+    lo_f = as_finite_float(lo, default=0.4)
+    hi_f = as_finite_float(hi, default=0.8)
+    width = hi_f - lo_f
+    if width <= 0:
+        return 0.0
+
+    e = clamp(as_finite_float(content.emotion_score, default=0.6), 0.0, 1.0)
+    if e < lo_f:
+        d = lo_f - e
+    elif e > hi_f:
+        d = e - hi_f
+    else:
+        d = 0.0
+
+    gamma = as_finite_float(config.widget_emotion_penalty_gamma, default=0.25)
+    raw = float(gamma) * float(d) / float(width)
+    return clamp(raw, 0.0, float(gamma))
+
+
+def score_content(
+    *,
+    scene: Scene,
+    user_profile: UserProfileV1_2,
+    content_profile: ContentProfileDTO,
+    config: Optional[ScoreConfig] = None,
+    pass_filters: bool = True,
+    external_terms: Optional[ExternalTerms] = None,
+    now: Optional[datetime] = None,  # 预留：V1 不使用
+) -> ScoreResult:
+    """
+    主入口：对单条内容 Cᵢ 进行软打分，返回 final_score 与 breakdown。
+
+    说明（V1）：
+    - `pass_filters` 来自 Hard Filter（本模块不做硬过滤）
+    - `external_terms` 可注入 S_fresh / P_fatigue / P_repeat / P_risk（缺省按 0）
+    - `now` 预留给未来的 freshness/时间衰减（V1 不实现）
+    """
+
+    cfg = config or get_default_config(scene)
+    ext = external_terms or ExternalTerms()
+
+    missing = _missing_fields(user_profile)
+
+    s_need = _score_need(user_profile, content_profile)
+    s_context = _score_context(user_profile, content_profile)
+    s_emotion = _score_emotion(user_profile, content_profile)
+    s_stage = _score_stage(user_profile, content_profile)
+
+    w_need = as_finite_float(cfg.w_need, default=0.0)
+    w_emotion = as_finite_float(cfg.w_emotion, default=0.0)
+    w_stage = as_finite_float(cfg.w_stage, default=0.0)
+    w_context = as_finite_float(cfg.w_context, default=0.0)
+
+    s_core = float(w_need) * s_need + float(w_emotion) * s_emotion + float(w_stage) * s_stage + float(w_context) * s_context
+
+    s_personal = _score_personal(cfg.alpha, content_profile.personalization_power, s_need, s_context)
+
+    p_uncertainty = 0.0
+    if cfg.enable_uncertainty_penalty:
+        p_uncertainty = _penalty_uncertainty(cfg.beta, user_profile, content_profile)
+
+    p_widget = _widget_emotion_penalty(scene, content_profile, cfg)
+
+    s_fresh = as_finite_float(ext.S_fresh, default=0.0)
+    p_fatigue = as_finite_float(ext.P_fatigue, default=0.0)
+    p_repeat = as_finite_float(ext.P_repeat, default=0.0)
+    p_risk_external = as_finite_float(ext.P_risk, default=0.0)
+
+    # Widget 软降权并入 P_risk（但在 breakdown 中单独暴露，便于打点）
+    p_risk = float(p_risk_external) + float(p_widget)
+
+    raw_final = s_core + s_personal + float(s_fresh) - float(p_fatigue) - float(p_repeat) - float(p_risk) - float(p_uncertainty)
+    final_score = float(raw_final) if pass_filters else 0.0
+
+    breakdown = ScoreBreakdown(
+        scene=scene,
+        **{
+            "pass": bool(pass_filters),
+        },
+        missing_fields=missing,
+        S_need=float(s_need),
+        S_context=float(s_context),
+        S_stage=float(s_stage),
+        S_emotion=float(s_emotion),
+        S_core=float(s_core),
+        S_personal=float(s_personal),
+        S_fresh=float(s_fresh),
+        P_fatigue=float(p_fatigue),
+        P_repeat=float(p_repeat),
+        P_risk=float(p_risk),
+        P_uncertainty=float(p_uncertainty),
+        P_widget_emotion_out_of_range=float(p_widget),
+    )
+
+    return ScoreResult(final_score=float(final_score), breakdown=breakdown)
+

server/app/features/personalized_reco/scoring/types.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+Scene = Literal["feed", "push", "widget"]
+
+
+class ScoreConfig(BaseModel):
+    """
+    打分配置（可调参）。
+
+    说明：
+    - 默认值由 `defaults.get_default_config(scene)` 提供
+    - 本模块不负责回退梯度（fallback_level）策略；仅做防御式 clamp
+    """
+
+    w_need: float
+    w_emotion: float
+    w_stage: float
+    w_context: float
+
+    alpha: float = 0.15
+    beta: float = 0.30
+
+    enable_uncertainty_penalty: bool = False
+
+    # Widget 情绪软区间与软降权强度
+    widget_emotion_soft_range: tuple[float, float] = (0.4, 0.8)
+    widget_emotion_penalty_gamma: float = 0.25
+
+
+class ExternalTerms(BaseModel):
+    """
+    外部注入项（V1 可选）。
+
+    说明：
+    - 由 `rerank-freqcap` 或 `reco-engine` 产出
+    - 本模块缺省按 0，保证可排序与输出结构稳定
+    """
+
+    S_fresh: float = 0.0
+    P_fatigue: float = 0.0
+    P_repeat: float = 0.0
+    P_risk: float = 0.0
+
+
+class ScoreBreakdown(BaseModel):
+    """
+    可观测分解项（用于调参与回归测试）。
+    """
+
+    scene: Scene
+    passed: bool = Field(alias="pass")
+
+    missing_fields: list[str] = Field(default_factory=list)
+
+    S_need: float
+    S_context: float
+    S_stage: float
+    S_emotion: float
+
+    S_core: float
+    S_personal: float
+    S_fresh: float
+
+    P_fatigue: float
+    P_repeat: float
+    P_risk: float
+    P_uncertainty: float
+
+    # Widget 专用：区间外软降权（建议保留，便于打点）
+    P_widget_emotion_out_of_range: float = 0.0
+
+    model_config = {
+        "populate_by_name": True,
+    }
+
+
+class ScoreResult(BaseModel):
+    final_score: float
+    breakdown: ScoreBreakdown
+

server/app/features/personalized_reco/scoring/utils.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def clamp(value: float, min_value: float, max_value: float) -> float:
+    """
+    将值裁剪到区间内，并对 NaN 做兜底。
+    """
+
+    if value != value:  # NaN
+        return min_value
+    return max(min_value, min(max_value, value))
+
+
+def as_finite_float(value: Any, *, default: float) -> float:
+    """
+    将任意值尽量转为有限 float；失败则返回 default。
+    """
+
+    try:
+        f = float(value)
+    except Exception:
+        return float(default)
+
+    # NaN / inf 都视为不可用
+    if f != f:
+        return float(default)
+    if f == float("inf") or f == float("-inf"):
+        return float(default)
+    return f
+
+
+def pick_one_hot_key(one_hot: dict[str, Any] | None) -> str | None:
+    """
+    从稀疏 one-hot（{key: 1}）中取唯一 key。
+
+    约定：
+    - None / {} → 缺失，返回 None
+    - 单 key → 返回该 key
+    - 多 key → 取“字典序最小”的 key，并记录 debug 日志（避免静默歧义）
+    """
+
+    if not one_hot:
+        return None
+
+    keys = [k for k, v in one_hot.items() if v == 1 or v is True]
+    if not keys:
+        return None
+    if len(keys) == 1:
+        return keys[0]
+
+    chosen = sorted(keys)[0]
+    logger.debug("one-hot 出现多个 key=1，已按字典序选择：chosen=%s keys=%s", chosen, keys)
+    return chosen
+

server/app/main.py

@@ -1,6 +1,7 @@
 from fastapi import FastAPI
 
 from app.core.config import get_settings
+from app.api.v1.reco import router as reco_router
 from app.api.v1.user_profile_scoring import router as user_profile_router
 
 
@@ -17,6 +18,7 @@ def create_app() -> FastAPI:
 
     # 业务路由
     app.include_router(user_profile_router)
+    app.include_router(reco_router)
 
     @app.get("/healthz")
     async def healthz() -> dict:

server/app/tasks/reco.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from celery import shared_task
+
+from app.db.session import AsyncSessionLocal
+from app.features.personalized_reco.content_repository.sqlalchemy_repo import SqlAlchemyContentRepository
+from app.features.personalized_reco.content_repository.types import normalize_locale
+from app.features.personalized_reco.reco_engine import recommend
+from app.features.personalized_reco.reco_engine.types import RecoConstraints, RecoEngineResult, Scene
+from app.features.user_profile_scoring.types import UserProfileV1_2
+
+
+def _ensure_now(now: Optional[datetime]) -> datetime:
+    if now is None:
+        return datetime.now(timezone.utc)
+    if now.tzinfo is None:
+        return now.replace(tzinfo=timezone.utc)
+    return now
+
+
+def _ensure_locale(locale: Optional[str]) -> str:
+    raw = (locale or "").strip() or "en"
+    # 严格校验只支持 en/tc（允许 en-US 等在 normalize_locale 内归一化）
+    return str(normalize_locale(raw))
+
+
+async def _run_reco_async(
+    *,
+    scene: Scene,
+    user_profile: UserProfileV1_2,
+    already_recommended_ids: list[Any],
+    touched_or_viewed_ids: list[Any],
+    k: int,
+    now: datetime,
+    locale: str,
+) -> RecoEngineResult:
+    async with AsyncSessionLocal() as session:
+        repo = SqlAlchemyContentRepository(session)
+        return await recommend(
+            repo=repo,
+            scene=scene,
+            user_profile=user_profile,
+            already_recommended_ids=list(already_recommended_ids or []),
+            touched_or_viewed_ids=list(touched_or_viewed_ids or []),
+            k=int(k),
+            now=now,
+            locale=locale,
+            constraints=RecoConstraints(),
+        )
+
+
+def _run_reco_sync(
+    *,
+    scene: Scene,
+    user_profile: UserProfileV1_2,
+    already_recommended_ids: list[Any],
+    touched_or_viewed_ids: list[Any],
+    k: int,
+    now: Optional[datetime],
+    locale: Optional[str],
+) -> dict[str, Any]:
+    effective_now = _ensure_now(now)
+    effective_locale = _ensure_locale(locale)
+    result = asyncio.run(
+        _run_reco_async(
+            scene=scene,
+            user_profile=user_profile,
+            already_recommended_ids=already_recommended_ids,
+            touched_or_viewed_ids=touched_or_viewed_ids,
+            k=int(k),
+            now=effective_now,
+            locale=effective_locale,
+        )
+    )
+    # 默认不存结果，但返回值可用于开发调试（worker 通常 ignore_result）
+    return result.model_dump()
+
+
+@shared_task(name="tasks.reco.generate")
+def generate(
+    *,
+    scene: Scene,
+    user_profile: dict[str, Any],
+    already_recommended_ids: Optional[list[Any]] = None,
+    touched_or_viewed_ids: Optional[list[Any]] = None,
+    k: Optional[int] = None,
+    now: Optional[str] = None,
+    locale: Optional[str] = None,
+) -> dict[str, Any]:
+    """
+    推荐生成任务（通用入口）。
+
+    说明：
+    - 入参尽量保持小（避免 Redis 队列膨胀）
+    - 默认 worker 配置为 ignore_result，但这里仍返回结构，便于本地调试
+    """
+
+    # 解析 user_profile（严格按 V1.2）
+    u = UserProfileV1_2.model_validate(user_profile or {})
+
+    # k 默认按场景（与 API 一致）
+    if k is None:
+        k_i = 30 if scene == "feed" else 1
+    else:
+        k_i = int(k)
+
+    # now 支持 ISO 字符串
+    dt: Optional[datetime]
+    if not now:
+        dt = None
+    else:
+        raw = str(now).strip()
+        if raw.endswith("Z"):
+            raw = raw[:-1] + "+00:00"
+        try:
+            dt = datetime.fromisoformat(raw)
+        except Exception:
+            dt = None
+
+    return _run_reco_sync(
+        scene=scene,
+        user_profile=u,
+        already_recommended_ids=list(already_recommended_ids or []),
+        touched_or_viewed_ids=list(touched_or_viewed_ids or []),
+        k=k_i,
+        now=dt,
+        locale=locale,
+    )
+
+
+def _deliver_push_placeholder(payload: dict[str, Any]) -> None:
+    """
+    Push 下游写入占位函数（V1 不接真实推送系统）。
+    """
+
+    _ = payload
+    return None
+
+
+@shared_task(name="tasks.reco.push_once")
+def push_once(
+    *,
+    user_profile: dict[str, Any],
+    already_recommended_ids: Optional[list[Any]] = None,
+    touched_or_viewed_ids: Optional[list[Any]] = None,
+    now: Optional[str] = None,
+    locale: Optional[str] = None,
+) -> dict[str, Any]:
+    """
+    单次 Push 生成（占位任务）。
+    """
+
+    payload = generate(
+        scene="push",
+        user_profile=user_profile,
+        already_recommended_ids=already_recommended_ids,
+        touched_or_viewed_ids=touched_or_viewed_ids,
+        k=1,
+        now=now,
+        locale=locale,
+    )
+    _deliver_push_placeholder(payload)
+    return payload
+

server/requirements.txt

@@ -5,6 +5,7 @@ uvicorn[standard]>=0.27
 SQLAlchemy>=2.0
 aiomysql>=0.2
 greenlet>=3.0
+aiosqlite>=0.20
 
 # 配置
 pydantic>=2.6
@@ -19,3 +20,5 @@ redis>=5.0
 
 # 测试
 pytest>=8.0
+pytest-asyncio>=0.23
+httpx>=0.27

server/run.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# 一键启动 FastAPI 后端：
+# - 自动创建/复用虚拟环境（.venv）
+# - 自动安装 requirements.txt 依赖
+# - 自动启动 uvicorn（默认开启 --reload）
+#
+# 用法示例：
+#   ./run.sh                 # 默认 host=0.0.0.0 port=8000 env=dev reload=on
+#   ./run.sh --env prod      # 使用 .env.prod（若存在且可被 source）
+#   ./run.sh --port 9000     # 改端口
+#   ./run.sh --no-reload     # 关闭热更新
+#   ./run.sh --install-only  # 只安装依赖，不启动
+
+usage() {
+  cat <<'EOF'
+用法：
+  ./run.sh [--env dev|prod] [--host 0.0.0.0] [--port 8000] [--no-reload] [--skip-install] [--install-only]
+
+参数：
+  --env dev|prod     优先尝试加载 .env.dev 或 .env.prod（如果存在）。
+  --host <host>      uvicorn host（默认 0.0.0.0）
+  --port <port>      uvicorn port（默认 8000）
+  --no-reload        关闭 uvicorn --reload
+  --skip-install     跳过依赖安装（默认会安装/更新 requirements.txt）
+  --install-only     只安装依赖，不启动服务
+  -h, --help         显示帮助
+
+说明：
+  - 若你的 .env.* 不是 shell 可 source 的格式（例如包含空格/特殊字符未加引号），建议改成 KEY=value 形式。
+  - 启动后访问：
+      /healthz  健康检查
+      /docs     OpenAPI 文档
+EOF
+}
+
+# 始终从脚本所在目录运行（避免在别处执行导致路径错）
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+ENV_NAME="dev"
+HOST="0.0.0.0"
+PORT="8000"
+RELOAD="1"
+SKIP_INSTALL="0"
+INSTALL_ONLY="0"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --env)
+      ENV_NAME="${2:-}"
+      shift 2
+      ;;
+    --host)
+      HOST="${2:-}"
+      shift 2
+      ;;
+    --port)
+      PORT="${2:-}"
+      shift 2
+      ;;
+    --no-reload)
+      RELOAD="0"
+      shift 1
+      ;;
+    --skip-install)
+      SKIP_INSTALL="1"
+      shift 1
+      ;;
+    --install-only)
+      INSTALL_ONLY="1"
+      shift 1
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "未知参数：$1" >&2
+      echo "" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ "$ENV_NAME" != "dev" && "$ENV_NAME" != "prod" ]]; then
+  echo "--env 仅支持 dev 或 prod，当前：$ENV_NAME" >&2
+  exit 2
+fi
+
+ENV_FILE=".env.${ENV_NAME}"
+if [[ -f "$ENV_FILE" ]]; then
+  # 让 source 进来的变量自动 export（供 pydantic-settings/应用读取）
+  set -a
+  # shellcheck disable=SC1090
+  source "$ENV_FILE"
+  set +a
+fi
+
+# 选择 python 命令（优先 python3）
+PY_BIN=""
+if command -v python3 >/dev/null 2>&1; then
+  PY_BIN="python3"
+elif command -v python >/dev/null 2>&1; then
+  PY_BIN="python"
+else
+  echo "未找到 python/python3，请先安装 Python 3.11+。" >&2
+  exit 1
+fi
+
+VENV_DIR=".venv"
+if [[ ! -d "$VENV_DIR" ]]; then
+  echo "创建虚拟环境：$VENV_DIR"
+  "$PY_BIN" -m venv "$VENV_DIR"
+fi
+
+# 激活虚拟环境
+# shellcheck disable=SC1091
+source "$VENV_DIR/bin/activate"
+
+if [[ "$SKIP_INSTALL" == "0" ]]; then
+  if [[ -f "requirements.txt" ]]; then
+    echo "升级 pip 并安装依赖（requirements.txt）"
+    python -m pip install -U pip
+    python -m pip install -r requirements.txt
+  else
+    echo "未找到 requirements.txt，跳过依赖安装。" >&2
+  fi
+fi
+
+if [[ "$INSTALL_ONLY" == "1" ]]; then
+  echo "依赖安装完成（install-only），退出。"
+  exit 0
+fi
+
+UVICORN_ARGS=(app.main:app --host "$HOST" --port "$PORT")
+if [[ "$RELOAD" == "1" ]]; then
+  UVICORN_ARGS+=(--reload)
+fi
+
+echo "启动服务：uvicorn ${UVICORN_ARGS[*]}"
+exec uvicorn "${UVICORN_ARGS[@]}"
+

server/tests/conftest.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import AsyncIterator, Callable
+from urllib.parse import urlparse
+
+import pytest
+import pytest_asyncio
+import sqlalchemy as sa
+from alembic import command
+from alembic.config import Config
+from sqlalchemy import event
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+
+# 确保在任何 pytest rootdir 下都能 `import app.*`
+SERVER_DIR = Path(__file__).resolve().parents[1]  # .../server
+if str(SERVER_DIR) not in sys.path:
+    sys.path.insert(0, str(SERVER_DIR))
+
+
+def _read_env_kv(env_path: Path) -> dict[str, str]:
+    """
+    读取 .env 文件中的 KEY=VALUE（最小实现，避免引入额外依赖）。
+    """
+
+    data: dict[str, str] = {}
+    if not env_path.exists():
+        return data
+    for raw in env_path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        k = k.strip()
+        v = v.strip().strip('"').strip("'")
+        if k:
+            data[k] = v
+    return data
+
+
+def _get_database_url() -> str:
+    """
+    获取测试用数据库连接串。
+
+    约定（与 alembic/env.py 保持一致）：
+    - 优先读取环境变量 `DATABASE_URL`
+    - 若未设置，则按 `APP_ENV`（默认 dev）读取 `server/.env.dev` 或 `server/.env.prod`
+    """
+
+    env_url = (os.getenv("DATABASE_URL") or "").strip()
+    if env_url:
+        return env_url
+
+    server_dir = Path(__file__).resolve().parents[1]  # .../server
+    app_env = (os.getenv("APP_ENV") or "dev").strip() or "dev"
+    env_file = server_dir / (".env.prod" if app_env == "prod" else ".env.dev")
+    kv = _read_env_kv(env_file)
+    url = (kv.get("DATABASE_URL") or "").strip()
+    if url:
+        return url
+
+    raise RuntimeError(
+        "缺少 DATABASE_URL：请设置环境变量 DATABASE_URL，或在 server/.env.dev（或 .env.prod）中配置 DATABASE_URL。"
+    )
+
+
+def _assert_safe_mysql_test_db(url: str) -> None:
+    """
+    为了避免对开发库造成破坏性影响，集成测试只允许连接到“测试库”。
+
+    规则（V1）：
+    - 必须是 mysql+aiomysql://...
+    - 为避免误连生产库：不允许数据库名为 'mindfulness'（prod 默认库名）
+    - 建议使用独立测试库（例如 mindfulness_dev_test）
+    """
+
+    if not url.startswith("mysql+"):
+        raise RuntimeError(f"当前仅允许 MySQL 集成测试（mysql+aiomysql）。实际：{url!r}")
+
+    parsed = urlparse(url.replace("mysql+aiomysql://", "mysql://", 1))
+    db_name = (parsed.path or "").lstrip("/")
+    if db_name.lower() == "mindfulness":
+        raise RuntimeError(
+            "为避免误连生产库，集成测试不允许连接到数据库 'mindfulness'。"
+            "请改用 dev 测试库（例如 mindfulness_dev_test 或 mindfulness_dev）。"
+        )
+
+
+def _run_alembic_upgrade_head() -> None:
+    """
+    使用 Alembic 将测试库升级到最新 schema。
+
+    说明：
+    - 依赖 env.py 内部读取 DATABASE_URL
+    - 仅在 session 级别执行一次，避免每个测试都跑迁移
+    """
+
+    server_dir = Path(__file__).resolve().parents[1]  # .../server
+    alembic_ini = server_dir / "alembic.ini"
+    cfg = Config(str(alembic_ini))
+    # 确保脚本路径正确（alembic.ini 里一般已配置，这里兜底）
+    cfg.set_main_option("script_location", "alembic")
+    command.upgrade(cfg, "head")
+
+def _assert_schema_exists(url: str) -> None:
+    """
+    非破坏性检查：要求目标库已经存在所需表。
+
+    说明：
+    - 默认不在测试中运行 Alembic（避免任何 schema 变更）
+    - 若要自动迁移，请设置环境变量 ALLOW_SCHEMA_MIGRATION=1
+    """
+
+    allow_migration = (os.getenv("ALLOW_SCHEMA_MIGRATION") or "").strip() == "1"
+    if allow_migration:
+        _run_alembic_upgrade_head()
+        return
+
+    # 使用 PyMySQL 做同步检查，避免依赖 MySQLdb（不要求系统安装 mysqlclient）
+    sync_url = url.replace("mysql+aiomysql://", "mysql+pymysql://", 1)
+    engine = sa.create_engine(sync_url, future=True)
+    try:
+        insp = sa.inspect(engine)
+        tables = set(insp.get_table_names())
+        required = {"contents", "content_profiles", "content_risk_flags"}
+        missing = sorted(required - tables)
+        if missing:
+            raise RuntimeError(
+                "集成测试检测到 schema 不完整（缺少表："
+                + ", ".join(missing)
+                + "）。为避免破坏性操作，测试不会自动迁移。"
+                "请先手动在该库执行 `alembic upgrade head`，或设置 ALLOW_SCHEMA_MIGRATION=1 允许测试自动迁移。"
+            )
+    finally:
+        engine.dispose()
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _migrate_db_once() -> None:
+    """
+    Session 级 schema 检查（仅在配置了数据库连接时启用）。
+
+    说明：
+    - 纯函数单元测试不需要 MySQL；若未配置 DATABASE_URL，则跳过检查
+    - 集成测试（依赖 db_session/async_engine）仍会在获取 DATABASE_URL 时失败，从而提示用户配置
+    """
+
+    try:
+        url = _get_database_url()
+    except RuntimeError:
+        return
+
+    _assert_safe_mysql_test_db(url)
+    _assert_schema_exists(url)
+
+
+@pytest_asyncio.fixture
+async def async_engine() -> AsyncIterator[AsyncEngine]:
+    url = _get_database_url()
+    _assert_safe_mysql_test_db(url)
+    engine = create_async_engine(url, pool_pre_ping=True)
+    try:
+        yield engine
+    finally:
+        await engine.dispose()
+
+
+@pytest_asyncio.fixture
+async def db_session(async_engine: AsyncEngine) -> AsyncIterator[AsyncSession]:
+    """
+    提供一个干净的 AsyncSession。
+
+    清理策略：每个测试都在事务中执行，并在结束时回滚（不做 DELETE/TRUNCATE）。
+
+    说明：
+    - 用例里严禁调用 session.commit()，只允许 flush()
+    - 这样不会对测试库产生持久化写入，更不会影响开发库
+    """
+
+    SessionLocal: async_sessionmaker[AsyncSession] = async_sessionmaker(
+        bind=async_engine,
+        expire_on_commit=False,
+        autoflush=False,
+        autocommit=False,
+    )
+
+    async with SessionLocal() as session:
+        trans = await session.begin()
+        try:
+            yield session
+        finally:
+            await trans.rollback()
+
+
+@pytest.fixture
+def query_counter(async_engine: AsyncEngine) -> Callable[[], int]:
+    """
+    返回一个函数：调用可获得当前累计查询次数。
+    """
+
+    count = {"n": 0}
+
+    def before_cursor_execute(*args, **kwargs):  # type: ignore[no-untyped-def]
+        count["n"] += 1
+
+    event.listen(async_engine.sync_engine, "before_cursor_execute", before_cursor_execute)
+
+    def get_count() -> int:
+        return int(count["n"])
+
+    def fin() -> None:
+        event.remove(async_engine.sync_engine, "before_cursor_execute", before_cursor_execute)
+
+    # 用 yield 确保测试后移除监听，避免重复绑定导致统计偏大
+    try:
+        yield get_count  # type: ignore[misc]
+    finally:
+        fin()
+

server/tests/test_content_repository.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+import pytest
+
+from app.db.models.content import Content
+from app.db.models.content_profile import ContentProfile
+from app.db.models.content_risk_flag import ContentRiskFlag
+from app.features.personalized_reco.content_repository.sqlalchemy_repo import SqlAlchemyContentRepository
+
+
+def _ctx_json() -> dict:
+    return {"family": 0.5, "work": 0.5, "relationship": 0.5, "friends": 0.5, "health": 0.5}
+
+
+def _need_json() -> dict:
+    return {
+        "emotional_support": 0.5,
+        "parenting_pressure": 0.5,
+        "self_worth": 0.5,
+        "anxiety_relief": 0.5,
+        "rest_balance": 0.5,
+    }
+
+
+@pytest.mark.asyncio
+async def test_fetch_contents_by_ids_locale_no_fallback(db_session, query_counter):
+    # content 1: 只有英文
+    c1 = Content(text_en="hello", text_tc=None, author_id="a1", template_id="t1")
+    db_session.add(c1)
+    await db_session.flush()
+    db_session.add(
+        ContentProfile(
+            content_id=c1.content_id,
+            stage="general",
+            emotion_score=None,
+            context_suitability_json=_ctx_json(),
+            need_suitability_json=_need_json(),
+            personalization_power=10,
+            review_confidence=None,
+            is_safe_pool=False,
+        )
+    )
+    db_session.add(ContentRiskFlag(content_id=c1.content_id, flag="block_stage_unknown"))
+
+    # content 2: 只有繁中
+    c2 = Content(text_en=None, text_tc="繁體中文", author_id="a2", template_id="t2")
+    db_session.add(c2)
+    await db_session.flush()
+    db_session.add(
+        ContentProfile(
+            content_id=c2.content_id,
+            stage="general",
+            emotion_score=None,
+            context_suitability_json=_ctx_json(),
+            need_suitability_json=_need_json(),
+            personalization_power=0,
+            review_confidence=0.9,
+            is_safe_pool=True,
+        )
+    )
+    db_session.add(ContentRiskFlag(content_id=c2.content_id, flag="block_health_sensitive"))
+
+    await db_session.flush()
+
+    repo = SqlAlchemyContentRepository(db_session)
+    start = query_counter()
+
+    # en：只能拿到有 text_en 的内容（不允许回退到 text_tc）
+    en_items = await repo.fetch_contents_by_ids(content_ids=[c2.content_id, c1.content_id], locale="en")
+    assert [x.content_id for x in en_items] == [c1.content_id]
+    assert en_items[0].text == "hello"
+    assert en_items[0].personalization_power == 1.0
+    assert en_items[0].review_confidence == 0.7  # NULL -> 0.7
+    assert "unsafe_for_stage_unknown" in en_items[0].risk_flags
+    assert "block_stage_unknown" not in en_items[0].risk_flags
+
+    # tc：只能拿到有 text_tc 的内容（不允许回退到 text_en）
+    tc_items = await repo.fetch_contents_by_ids(content_ids=[c1.content_id, c2.content_id], locale="tc")
+    assert [x.content_id for x in tc_items] == [c2.content_id]
+    assert tc_items[0].text == "繁體中文"
+    assert tc_items[0].review_confidence == 0.9
+    assert "block_health_medical" in tc_items[0].risk_flags
+    assert "block_health_sensitive" not in tc_items[0].risk_flags
+
+    # 两次调用各自 2 次查询（主体+画像一次，flags 一次），总计应为常数级
+    end = query_counter()
+    assert (end - start) <= 4
+
+
+@pytest.mark.asyncio
+async def test_fetch_candidates_fallback_and_locale_filter(db_session, query_counter):
+    # 构造 4 条英文内容：power 0/5/10，安全池标记不同
+    contents = []
+    for i, (power, safe) in enumerate([(0, True), (5, False), (10, False), (0, False)], start=1):
+        c = Content(text_en=f"en_{i}", text_tc=None, author_id=f"a{i}", template_id=f"t{i}")
+        db_session.add(c)
+        await db_session.flush()
+        db_session.add(
+            ContentProfile(
+                content_id=c.content_id,
+                stage="general",
+                emotion_score=None,
+                context_suitability_json=_ctx_json(),
+                need_suitability_json=_need_json(),
+                personalization_power=power,
+                review_confidence=None,
+                is_safe_pool=safe,
+                # 让测试数据在候选排序中排到最前，避免依赖“库为空”
+                updated_at=datetime(2099, 1, 1, 0, 0, 0),
+            )
+        )
+        contents.append(c)
+    await db_session.flush()
+    inserted_ids = {int(c.content_id) for c in contents}
+
+    repo = SqlAlchemyContentRepository(db_session)
+
+    class _MinimalUser:
+        # need/context/emotion_score 全缺失 -> effective_fallback 至少 L1
+        need = {}
+        context = {}
+        emotion_score = None
+        stage = {"unknown": 1}
+
+    start = query_counter()
+
+    # 入参 L0，但因为缺失字段，effective_fallback=1 -> power<=5（排除 power=10）
+    items_l0 = await repo.fetch_candidates(
+        scene="feed",
+        user_profile=_MinimalUser(),
+        fallback_level=0,
+        limit=3,
+        locale="en-US",
+    )
+    powers = [x.personalization_power for x in items_l0]
+    assert 1.0 not in powers
+    assert all(x.text.startswith("en_") for x in items_l0)
+
+    # L2：强制 power=0 且 stage=general（这里都 general），只剩 power=0 的两条
+    items_l2 = await repo.fetch_candidates(
+        scene="feed",
+        user_profile=_MinimalUser(),
+        fallback_level=2,
+        limit=2,
+        locale="en",
+    )
+    assert all(x.personalization_power == 0.0 for x in items_l2)
+    assert all(x.text.startswith("en_") for x in items_l2)
+
+    # L3：只安全池（is_safe_pool=true）且 power=0
+    items_l3 = await repo.fetch_candidates(
+        scene="feed",
+        user_profile=_MinimalUser(),
+        fallback_level=3,
+        limit=1,
+        locale="en",
+    )
+    assert len(items_l3) == 1
+    assert items_l3[0].text.startswith("en_")
+    assert items_l3[0].personalization_power == 0.0
+
+    # locale 过滤：tc 请求下这些内容都没有 text_tc -> 返回空
+    items_tc = await repo.fetch_candidates(
+        scene="feed",
+        user_profile=_MinimalUser(),
+        fallback_level=0,
+        limit=10,
+        locale="tc",
+    )
+    # 不要求库为空：只断言“不会把本次插入的 en-only 测试数据返回出来”
+    assert not any(x.content_id in inserted_ids for x in items_tc)
+
+    end = query_counter()
+    # 期望为常数级（每次 fetch_candidates：1 次取 ids + 2 次补全），这里 4 次调用 -> <= 12
+    assert (end - start) <= 12
+