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

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

.cursor/commands/myspec.code.md

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

.cursor/commands/myspec.split-spec.md

@@ -9,6 +9,6 @@
    - 输入/输出定义
    - 验收标准（可验证）
 3. 拆分后输出一个 `modules/` 目录结构列表，并为每个模块生成对应 spec 内容。
-4. 保留大 spec.md 的高层背景/总览到 overview 部分。
+4. 保留大 spec.md 的高层背景/总览到 overview 部分，并标明各个模块的实现顺序。
 5. 子模块之间按逻辑关系关联。
-6. 不生成 plan.md 或 tasks.md，仅拆出子模块 spec。
+6. 不生成 plan.md 或 tasks.md，仅拆出子模块 spec。

.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",
-    "slug": "hey-mama",
+    "name": "client",
+    "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]}>
-        <Text style={styles.text}>{item.text}</Text>
+      {themeMode === 'scenery' && (
+        <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,
-    alignItems: 'center',
+    position: 'absolute',
+    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 = [
-  { id: 'name', type: 'name', title: '我可以怎么称呼你？' },
-  { 
-    id: 'status', 
-    type: 'selection', 
-    title: '媽媽的狀態？',
-    options: [
-      { id: 'pregnant', label: '懷孕中／準備成為媽媽' },
-      { id: 'has_kids', label: '已經有孩子' },
-      { id: 'no_fill', label: '不想填寫' },
-    ]
-  },
-  { 
-    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: '你需要每天几次提醒？' },
+type Step =
+  | { id: 'name'; type: 'name' }
+  | { id: 'status' | 'emotion' | 'influence' | 'support'; type: 'selection'; optionIds: string[] }
+  | { id: 'reminder'; type: 'reminder' };
+
+const STEPS: Step[] = [
+  { id: 'name', type: 'name' },
+  { id: 'status', type: 'selection', optionIds: ['pregnant', 'has_kids', 'no_fill'] },
+  { id: 'emotion', type: 'selection', optionIds: ['happy', 'calm', 'stressed', 'low'] },
+  { 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' },
 ];
 
 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();
-      if (!cancelled) setIds(list);
+      const [favList, cache] = await Promise.all([
+        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]);
-
-  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]);
+  }, [visible, t]);
 
   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 list = storedFavs
-      .map((fav) => ({
-        ...fav,
-        text: map.get(fav.id) || ''
-      }))
-      .filter(item => item.text !== '');
-      
+    const textMap = new Map<string, string>();
+
+    // 1) Mock 文案
+    MOCK_CONTENT.forEach((c) => textMap.set(String(c.id), t(c.textKey)));
+
+    // 2) 后端推荐缓存文案（避免收藏后 cache 覆盖就丢文案）
+    const cache = await getRecoFeedCache();
+    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: 'en', label: 'English' },
+    { id: 'zh-TW', label: t('language.zhTW') },
+    { 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: 'life', label: '生活', icon: '⛅' },
-  { id: 'travel', label: '旅游', icon: '🌴' },
-  { id: 'work', label: '职场', icon: '💼' },
+  { id: 'love', labelKey: 'intent.love', icon: '❤️' },
+  { id: 'life', labelKey: 'intent.life', icon: '⛅' },
+  { id: 'travel', labelKey: 'intent.travel', 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 
-          onPress={onNext} 
-          disabled={!hasSelection}
-          activeOpacity={0.8}
-        >
+        <TouchableOpacity 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(entry)
+        completion(EmotionEntry(date: Date()))
     }
 
     func getTimeline(in context: Context, completion: @escaping (Timeline<EmotionEntry>) -> ()) {
-        var entries: [EmotionEntry] = []
-        let currentDate = Date()
-        
-        // 生成未来 24 小时的 6 个条目，每 4 小时更换一次随机文案
-        for hourOffset in 0..<6 {
-            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)
+        // V1：内容写死，不做数据更新；给一个较长的刷新间隔（系统仍可能自行调度）
+        let entry = EmotionEntry(date: Date())
+        let nextUpdate = Calendar.current.date(byAdding: .day, value: 7, to: Date())
+            ?? Date().addingTimeInterval(60 * 60 * 24 * 7)
+        completion(Timeline(entries: [entry], policy: .after(nextUpdate)))
     }
 }
 
 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) {
-            Spacer(minLength: 0)
-            
-            Text(entry.text)
-                .font(.system(size: family == .systemSmall ? 17 : 20, weight: .medium))
-                .foregroundColor(textColor)
-                .lineSpacing(6)
-                .multilineTextAlignment(.center)
-                .minimumScaleFactor(0.7)
-                .fixedSize(horizontal: false, vertical: true)
-            
-            Spacer(minLength: 0)
-            
-            if family != .systemSmall {
-                Text("Hey Mama")
-                    .font(.system(size: 10, weight: .semibold))
-                    .foregroundColor(textColor.opacity(0.3))
-                    .padding(.bottom, 4)
-            }
+        switch family {
+        case .systemSmall:
+            smallView()
+        case .systemMedium:
+            mediumView()
+        case .systemLarge:
+            largeView()
+        default:
+            smallView()
+        }
+    }
+
+    // 统一的“卡片背景”风格（iOS 15 兼容）
+    private func cardBackground(colors: [Color]) -> some View {
+        ZStack {
+            LinearGradient(
+                colors: colors,
+                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)
-                    .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))
-            }
+            EmotionWidgetView(entry: entry)
         }
         .configurationDisplayName("情绪小组件")
         .description("一段温柔提醒，陪你回到当下。")

client/package.json

@@ -6,7 +6,8 @@
     "start": "expo start",
     "android": "expo run:android",
     "ios": "expo run:ios",
-    "web": "expo start --web"
+    "web": "expo start --web",
+    "test": "vitest run"
   },
   "dependencies": {
     "@expo/vector-icons": "^15.0.3",
@@ -41,7 +42,8 @@
   "devDependencies": {
     "@types/react": "~19.1.0",
     "react-test-renderer": "19.1.0",
-    "typescript": "~5.9.2"
+    "typescript": "~5.9.2",
+    "vitest": "^4.0.18"
   },
   "private": true
 }

client/src/constants/env.ts

@@ -20,14 +20,31 @@ 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);
 
 /**
  * 默认语言策略：
- * - auto：优先设备语言（支持列表内时），否则回退 zh-CN
- * - zh-CN/en/es/pt/zh-TW：固定默认语言（仍允许用户在设置中手动切换并持久化）
+ * - auto：优先设备语言（支持列表内时），否则回退 en
+ * - en/zh-TW：固定默认语言（仍允许用户在设置中手动切换并持久化）
  */
 export const DEFAULT_LANGUAGE = getOptionalEnv('EXPO_PUBLIC_DEFAULT_LANGUAGE', 'auto');
 

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: 'c2', text: '深呼吸三次，把注意力带回当下。' },
-  { id: 'c3', text: '允许自己慢一点，情绪会像云一样飘过。' },
-  { id: 'c4', text: '你不需要完美，你已经足够好。' },
-  { id: 'c5', text: '把手放在心口，对自己说一句：辛苦了。' }
+  { id: 'c1', textKey: 'mock.c1' },
+  { id: 'c2', textKey: 'mock.c2' },
+  { id: 'c3', textKey: 'mock.c3' },
+  { id: 'c4', textKey: 'mock.c4' },
+  { 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/__tests__/scoring.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildUserProfileFromQuestionnaire,
+  computeProfileConfidence,
+  computeTimeConfidence,
+  normalizeAnswers,
+} from '../index';
+
+describe('userProfileScoring V1.2', () => {
+  it('normalizeAnswers: 非法值按跳过处理', () => {
+    // @ts-expect-error: 模拟非法输入
+    const out = normalizeAnswers({ mom_stage: 'xxx', emotion: 'yyy', context: 'zzz', need: 'ooo' });
+    expect(out).toEqual({ mom_stage: undefined, emotion: undefined, context: undefined, need: undefined });
+  });
+
+  it('computeTimeConfidence: 分段衰减', () => {
+    const gen = new Date('2026-01-01T00:00:00Z');
+
+    // 0–7 天：1.0
+    expect(computeTimeConfidence(gen, new Date('2026-01-05T00:00:00Z'))).toBe(1.0);
+
+    // 30 天以上：0.5
+    expect(computeTimeConfidence(gen, new Date('2026-02-15T00:00:00Z'))).toBe(0.5);
+  });
+
+  it('computeProfileConfidence: 完整度因子 + clamp', () => {
+    const confTime = 1.0;
+
+    // 全部跳过：completion=0 → completionFactor=0.5 → 0.5
+    expect(
+      computeProfileConfidence(confTime, { stage: false, emotion: false, context: false, need: false })
+    ).toBe(0.5);
+
+    // 全部作答：completion=1 → completionFactor=1 → 1
+    expect(computeProfileConfidence(confTime, { stage: true, emotion: true, context: true, need: true })).toBe(1.0);
+  });
+
+  it('buildUserProfileFromQuestionnaire: 全部跳过输出最小可计算画像', () => {
+    const p = buildUserProfileFromQuestionnaire({}, { generatedAt: '2026-01-30T00:00:00Z', now: '2026-01-30T00:00:00Z' });
+
+    expect(p.profile_version).toBe('v1.2');
+    expect(p.profile_source).toBe('questionnaire');
+
+    expect(p.profile_answered).toEqual({ stage: false, emotion: false, context: false, need: false });
+    expect(p.stage).toEqual({ unknown: 1 });
+    expect(p.emotion_score).toBeNull();
+    expect(p.context).toEqual({});
+    expect(p.need).toEqual({});
+
+    // conf_time=1，completionFactor=0.5
+    expect(p.profile_confidence).toBe(0.5);
+
+    // unknown 会命中 unsafe_for_stage_unknown，并带跨维度谓词
+    expect(p.hard_rules.forbidden_risk_flags).toContain('unsafe_for_stage_unknown');
+    expect(p.hard_rules.forbidden_content_predicates.some((x) => x.id === 'unknown_block_parenting_pressure_personalized')).toBe(
+      true
+    );
+  });
+
+  it('buildUserProfileFromQuestionnaire: emotion<=0.2 命中 unsafe_for_emotion_low', () => {
+    const p = buildUserProfileFromQuestionnaire(
+      { mom_stage: 'expecting', emotion: 'overwhelmed', context: 'health', need: 'anxiety_relief' },
+      { generatedAt: '2026-01-30T00:00:00Z', now: '2026-01-30T00:00:00Z' }
+    );
+    expect(p.emotion_score).toBe(0.2);
+    expect(p.hard_rules.forbidden_risk_flags).toContain('unsafe_for_emotion_low');
+  });
+});
+

client/src/features/userProfileScoring/index.ts

@@ -0,0 +1,19 @@
+export type {
+  BuildUserProfileOptions,
+  QuestionnaireAnswersV1_2,
+  UserProfileV1_2,
+  UserProfileV1_2_Extended,
+} from './types';
+
+export type { OnboardingSelections } from './onboardingMapping';
+
+export {
+  buildUserProfileFromQuestionnaire,
+  computeProfileAnswered,
+  computeProfileConfidence,
+  computeTimeConfidence,
+  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/features/userProfileScoring/scoring.ts

@@ -0,0 +1,233 @@
+/**
+ * 用户画像打分（User Profile Scoring）V1.2
+ *
+ * 规则来源：
+ * - `spec_kit/User Profile Scoring/spec.md`
+ * - `设计说明文档/客戶端問卷打分規則.md`（V1.2）
+ */
+
+import type {
+  BuildUserProfileOptions,
+  ContextAnswer,
+  EmotionAnswer,
+  HardRules,
+  MomStageAnswer,
+  NeedAnswer,
+  ProfileAnswered,
+  QuestionnaireAnswersV1_2,
+  SparseOneHot,
+  UserProfileV1_2_Extended,
+  UserStageOneHot,
+} from './types';
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+function clamp(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(max, Math.max(min, value));
+}
+
+function toDate(value: Date | string | undefined): Date | null {
+  if (!value) return null;
+  if (value instanceof Date) return Number.isFinite(value.getTime()) ? value : null;
+  const d = new Date(value);
+  return Number.isFinite(d.getTime()) ? d : null;
+}
+
+function isMomStageAnswer(v: unknown): v is MomStageAnswer {
+  return v === 'expecting' || v === 'parenting' || v === 'unknown';
+}
+
+function isEmotionAnswer(v: unknown): v is EmotionAnswer {
+  return (
+    v === 'low' ||
+    v === 'overwhelmed' ||
+    v === 'tired' ||
+    v === 'neutral' ||
+    v === 'calm' ||
+    v === 'joyful'
+  );
+}
+
+function isContextAnswer(v: unknown): v is ContextAnswer {
+  return v === 'family' || v === 'work' || v === 'relationship' || v === 'friends' || v === 'health';
+}
+
+function isNeedAnswer(v: unknown): v is NeedAnswer {
+  return (
+    v === 'emotional_support' ||
+    v === 'parenting_pressure' ||
+    v === 'self_worth' ||
+    v === 'anxiety_relief' ||
+    v === 'rest_balance'
+  );
+}
+
+/**
+ * 归一化答案：非法值按“跳过”处理（归一化为 undefined）
+ * - `null` 保留，表示显式跳过/无值
+ */
+export function normalizeAnswers(raw: QuestionnaireAnswersV1_2): QuestionnaireAnswersV1_2 {
+  const mom_stage =
+    raw.mom_stage === null ? null : isMomStageAnswer(raw.mom_stage) ? raw.mom_stage : undefined;
+  const emotion = raw.emotion === null ? null : isEmotionAnswer(raw.emotion) ? raw.emotion : undefined;
+  const context = raw.context === null ? null : isContextAnswer(raw.context) ? raw.context : undefined;
+  const need = raw.need === null ? null : isNeedAnswer(raw.need) ? raw.need : undefined;
+
+  return { mom_stage, emotion, context, need };
+}
+
+export function computeProfileAnswered(normalized: QuestionnaireAnswersV1_2): ProfileAnswered {
+  return {
+    stage: normalized.mom_stage !== undefined && normalized.mom_stage !== null,
+    emotion: normalized.emotion !== undefined && normalized.emotion !== null,
+    context: normalized.context !== undefined && normalized.context !== null,
+    need: normalized.need !== undefined && normalized.need !== null,
+  };
+}
+
+/**
+ * 时间衰减置信度（conf_time）
+ * - 0–7 天：1.0
+ * - 7–30 天：线性衰减到 0.7（含第 30 天）
+ * - 30 天以上：0.5
+ */
+export function computeTimeConfidence(generatedAt: Date, now: Date): number {
+  const deltaMs = now.getTime() - generatedAt.getTime();
+  if (!Number.isFinite(deltaMs) || deltaMs <= 0) return 1.0;
+
+  const days = deltaMs / MS_PER_DAY;
+  if (days <= 7) return 1.0;
+  if (days <= 30) {
+    const t = (days - 7) / (30 - 7); // 0..1
+    return 1.0 - 0.3 * t; // 1 -> 0.7
+  }
+  return 0.5;
+}
+
+/**
+ * V1.2：profile_confidence（conf_U）
+ * conf = clamp(conf_time * (0.5 + 0.5 * completion), 0.2, 1.0)
+ */
+export function computeProfileConfidence(confTime: number, answered: ProfileAnswered): number {
+  const answeredCount =
+    (answered.stage ? 1 : 0) + (answered.emotion ? 1 : 0) + (answered.context ? 1 : 0) + (answered.need ? 1 : 0);
+  const completion = answeredCount / 4;
+  const completionFactor = 0.5 + 0.5 * completion;
+  return clamp(confTime * completionFactor, 0.2, 1.0);
+}
+
+function buildStageOneHot(momStage: MomStageAnswer | null | undefined): UserStageOneHot {
+  // V1.2：mom_stage 跳过按安全策略输出 unknown=1
+  if (momStage === null || momStage === undefined) {
+    return { unknown: 1 };
+  }
+
+  return {
+    expecting: momStage === 'expecting' ? 1 : 0,
+    parenting: momStage === 'parenting' ? 1 : 0,
+    unknown: momStage === 'unknown' ? 1 : 0,
+  };
+}
+
+function mapEmotionScore(emotion: EmotionAnswer | null | undefined): number | null {
+  if (emotion === null || emotion === undefined) return null;
+  switch (emotion) {
+    case 'low':
+      return 0.0;
+    case 'overwhelmed':
+      return 0.2;
+    case 'tired':
+      return 0.4;
+    case 'neutral':
+      return 0.6;
+    case 'calm':
+      return 0.8;
+    case 'joyful':
+      return 1.0;
+  }
+}
+
+function buildSparseOneHot(value: string | null | undefined): SparseOneHot {
+  if (value === null || value === undefined) return {};
+  return { [value]: 1 };
+}
+
+function computeRuleHitsAndHardRules(profile: {
+  stage: UserStageOneHot;
+  emotion_score: number | null;
+}): { rule_hits: string[]; hard_rules: HardRules } {
+  const rule_hits: string[] = [];
+  const forbidden_risk_flags: string[] = [];
+
+  const stageUnknown = profile.stage.unknown === 1;
+  const stageParenting = profile.stage.parenting === 1;
+
+  if (stageUnknown) {
+    rule_hits.push('unsafe_for_stage_unknown');
+    forbidden_risk_flags.push('unsafe_for_stage_unknown');
+  }
+
+  if (stageParenting) {
+    rule_hits.push('unsafe_for_stage_parenting');
+    forbidden_risk_flags.push('unsafe_for_stage_parenting');
+  }
+
+  if (profile.emotion_score !== null && profile.emotion_score <= 0.2) {
+    rule_hits.push('unsafe_for_emotion_low');
+    forbidden_risk_flags.push('unsafe_for_emotion_low');
+  }
+
+  const forbidden_content_predicates = [];
+  if (stageUnknown) {
+    forbidden_content_predicates.push({
+      id: 'unknown_block_parenting_pressure_personalized',
+      when_user: { stage_unknown: true },
+      forbid_content: { need: 'parenting_pressure', personalization_power: 1 },
+    });
+  }
+
+  return {
+    rule_hits,
+    hard_rules: {
+      forbidden_risk_flags,
+      forbidden_content_predicates,
+    },
+  };
+}
+
+export function buildUserProfileFromQuestionnaire(
+  rawAnswers: QuestionnaireAnswersV1_2,
+  options: BuildUserProfileOptions = {}
+): UserProfileV1_2_Extended {
+  const normalized = normalizeAnswers(rawAnswers);
+  const profile_answered = computeProfileAnswered(normalized);
+
+  const now = toDate(options.now) ?? new Date();
+  const generatedAt = toDate(options.generatedAt) ?? now;
+
+  const confTime = computeTimeConfidence(generatedAt, now);
+  const profile_confidence = computeProfileConfidence(confTime, profile_answered);
+
+  const stage = buildStageOneHot(normalized.mom_stage);
+  const emotion_score = mapEmotionScore(normalized.emotion);
+  const context = buildSparseOneHot(normalized.context);
+  const need = buildSparseOneHot(normalized.need);
+
+  const { rule_hits, hard_rules } = computeRuleHitsAndHardRules({ stage, emotion_score });
+
+  return {
+    profile_version: 'v1.2',
+    profile_source: 'questionnaire',
+    profile_generated_at: generatedAt.toISOString(),
+    profile_confidence,
+    profile_answered,
+    stage,
+    emotion_score,
+    context,
+    need,
+    rule_hits,
+    hard_rules,
+  };
+}
+

client/src/features/userProfileScoring/types.ts

@@ -0,0 +1,95 @@
+/**
+ * 用户画像打分（User Profile Scoring）V1.2 类型定义
+ *
+ * 说明：
+ * - 本模块用于：问卷答案（可跳过）→ 用户画像（可计算、可观测、可版本化）
+ * - 字段与规则以 `spec_kit/User Profile Scoring/spec.md`（V1.2）为准
+ */
+
+export type MomStageAnswer = 'expecting' | 'parenting' | 'unknown';
+export type EmotionAnswer = 'low' | 'overwhelmed' | 'tired' | 'neutral' | 'calm' | 'joyful';
+export type ContextAnswer = 'family' | 'work' | 'relationship' | 'friends' | 'health';
+export type NeedAnswer =
+  | 'emotional_support'
+  | 'parenting_pressure'
+  | 'self_worth'
+  | 'anxiety_relief'
+  | 'rest_balance';
+
+/**
+ * V1.2：每题可跳过
+ * - `undefined`：字段缺失（可能是“没传”）
+ * - `null`：显式跳过/无值（例如 UI 明确传 null）
+ */
+export type QuestionnaireAnswersV1_2 = {
+  mom_stage?: MomStageAnswer | null;
+  emotion?: EmotionAnswer | null;
+  context?: ContextAnswer | null;
+  need?: NeedAnswer | null;
+};
+
+export type ProfileAnswered = {
+  stage: boolean;
+  emotion: boolean;
+  context: boolean;
+  need: boolean;
+};
+
+export type UserStageOneHot = {
+  expecting?: 0 | 1;
+  parenting?: 0 | 1;
+  unknown: 0 | 1;
+};
+
+export type SparseOneHot = Record<string, 1>;
+
+export type UserProfileV1_2 = {
+  profile_version: 'v1.2';
+  profile_source: 'questionnaire';
+  profile_generated_at: string; // ISO8601
+  profile_confidence: number; // 0–1
+  profile_answered: ProfileAnswered;
+  stage: UserStageOneHot;
+  emotion_score: number | null;
+  context: SparseOneHot;
+  need: SparseOneHot;
+};
+
+export type ForbiddenContentPredicate = {
+  /**
+   * 谓词 ID：用于可观测与回归测试
+   */
+  id: string;
+  /**
+   * 触发条件（用户侧）
+   * 说明：这里刻意保持为 object，便于未来接入规则引擎时做 schema 对齐。
+   */
+  when_user: Record<string, unknown>;
+  /**
+   * 禁推条件（内容侧）
+   * 说明：本模块不判断内容的 `personalization_power`，只输出可执行条件。
+   */
+  forbid_content: Record<string, unknown>;
+};
+
+export type HardRules = {
+  forbidden_risk_flags: string[];
+  forbidden_content_predicates: ForbiddenContentPredicate[];
+};
+
+export type UserProfileV1_2_Extended = UserProfileV1_2 & {
+  rule_hits: string[];
+  hard_rules: HardRules;
+};
+
+export type BuildUserProfileOptions = {
+  /**
+   * 画像生成时间；不传则使用当前时间
+   */
+  generatedAt?: Date | string;
+  /**
+   * 当前时间（用于计算 time decay）；不传则使用当前时间
+   */
+  now?: Date | string;
+};
+

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,31 +3,23 @@ import * as Localization from 'expo-localization';
 import i18n from 'i18next';
 import { initReactI18next } from 'react-i18next';
 
-import en from './locales/en.json';
-import es from './locales/es.json';
-import pt from './locales/pt.json';
-import zhCN from './locales/zh-CN.json';
-import zhTW from './locales/zh-TW.json';
+// 用 require 避免 TS 的 json module 配置差异导致无法编译
+// 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> };
 
 /**
  * 语言码约定：
- * - 简体中文：zh-CN
  * - 繁体中文：zh-TW
  * - 英语：en
- * - 西班牙语：es
- * - 葡萄牙语：pt
  */
-export type AppLanguage = 'zh-CN' | 'zh-TW' | 'en' | 'es' | 'pt';
+export type AppLanguage = 'zh-TW' | 'en';
 
 export const SUPPORTED_LANGUAGES: readonly AppLanguage[] = [
-  'zh-CN',
   'zh-TW',
   'en',
-  'es',
-  'pt',
 ] as const;
 
-const DEFAULT_FALLBACK_LANGUAGE: AppLanguage = 'zh-CN';
+const DEFAULT_FALLBACK_LANGUAGE: AppLanguage = 'en';
 const STORAGE_KEY_LANGUAGE = 'settings.language';
 
 function isSupportedLanguage(lang: string): lang is AppLanguage {
@@ -37,19 +29,13 @@ function isSupportedLanguage(lang: string): lang is AppLanguage {
 function normalizeDeviceLanguageTagToAppLanguage(languageTag: string): AppLanguage {
   const tag = languageTag.toLowerCase();
 
-  // 中文：优先区分繁简
+  // 中文：当前仅支持繁体中文（zh-TW）
   if (tag.startsWith('zh')) {
-    // 常见繁体标记：zh-TW / zh-HK / zh-Hant
-    if (tag.includes('tw') || tag.includes('hk') || tag.includes('hant')) {
-      return 'zh-TW';
-    }
-    return 'zh-CN';
+    return 'zh-TW';
   }
 
-  // 其他语言：按前缀匹配
+  // 其他语言：按前缀匹配（当前仅支持英文）
   if (tag.startsWith('en')) return 'en';
-  if (tag.startsWith('es')) return 'es';
-  if (tag.startsWith('pt')) return 'pt';
 
   return DEFAULT_FALLBACK_LANGUAGE;
 }
@@ -87,7 +73,7 @@ export async function clearLanguagePreference(): Promise<void> {
  * 语言选择优先级：
  * 1) 用户设置（若存在）
  * 2) 设备语言（在支持列表内时生效；否则会被 normalize 到默认回退）
- * 3) 默认回退（zh-CN）
+  * 3) 默认回退（en）
  */
 export async function initI18n(): Promise<void> {
   if (i18n.isInitialized) return;
@@ -98,11 +84,8 @@ export async function initI18n(): Promise<void> {
 
   await i18n.use(initReactI18next).init({
     resources: {
-      'zh-CN': { translation: zhCN },
-      'zh-TW': { translation: zhTW },
-      en: { translation: en },
-      es: { translation: es },
-      pt: { translation: pt },
+      'zh-TW': { translation: all['zh-TW'] as any },
+      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/.env.dev

@@ -7,13 +7,13 @@ APP_HOST=0.0.0.0
 APP_PORT=8000
 
 # 数据库（dev 指向 mindfulness_dev；prod 指向 mindfulness）
-DATABASE_URL=mysql+aiomysql://<用户名>:<密码>@<MYSQL_HOST>:3306/mindfulness_dev?charset=utf8mb4
+DATABASE_URL=mysql+aiomysql://damer:damer@43.163.242.87:3306/mindfulness_dev?charset=utf8mb4
 
 # Redis（使用 ACL 用户；并确保应用侧 key 带 dev:/pro: 前缀）
-REDIS_URL=redis://<REDIS_USER>:<REDIS_PASSWORD>@<REDIS_HOST>:6379/0
+REDIS_URL=redis://dev_damer:damer@43.163.242.87:6379/0
 
 # Celery（默认不启用结果存储，避免 Redis 内存压力）
-CELERY_BROKER_URL=redis://<REDIS_USER>:<REDIS_PASSWORD>@<REDIS_HOST>:6379/0
+CELERY_BROKER_URL=redis://dev_damer:damer@43.163.242.87:6379/0
 # CELERY_RESULT_BACKEND=redis://<REDIS_USER>:<REDIS_PASSWORD>@<REDIS_HOST>:6379/0
 
 # 推送（Expo）

server/.env.prod

@@ -0,0 +1,20 @@
+# 运行环境：dev 或 prod
+APP_ENV=prod
+
+# Web 服务
+APP_NAME=mindfulness-server
+APP_HOST=0.0.0.0
+APP_PORT=8000
+
+# 数据库（dev 指向 mindfulness_dev；prod 指向 mindfulness）
+DATABASE_URL=mysql+aiomysql://damer:damer@43.163.242.87:3306/mindfulness?charset=utf8mb4
+
+# Redis（使用 ACL 用户；并确保应用侧 key 带 dev:/pro: 前缀）
+REDIS_URL=redis://prod_damer:damer@43.163.242.87:6379/0
+
+# Celery（默认不启用结果存储，避免 Redis 内存压力）
+CELERY_BROKER_URL=redis://prod_damer:damer@43.163.242.87:6379/0
+# CELERY_RESULT_BACKEND=redis://<REDIS_USER>:<REDIS_PASSWORD>@<REDIS_HOST>:6379/0
+
+# 推送（Expo）
+# EXPO_ACCESS_TOKEN=

server/alembic.ini

@@ -0,0 +1,39 @@
+[alembic]
+script_location = alembic
+
+# 注意：实际连接串由 alembic/env.py 从环境变量 DATABASE_URL 注入
+sqlalchemy.url = driver://user:pass@localhost/dbname
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+

server/alembic/README.md

@@ -0,0 +1,40 @@
+# Alembic（数据库迁移）
+
+## 1. 前置
+
+- 在 `server/` 下准备 `.env.dev`（或系统环境变量），至少包含：
+  - `DATABASE_URL=mysql+aiomysql://...`
+
+> 注意：本仓库推荐使用 Python 虚拟环境（venv）。示例以 `server/.venv` 为准。
+
+---
+
+## 2. 安装依赖（一次性）
+
+在仓库根目录：
+
+```bash
+python3 -m venv server/.venv
+source server/.venv/bin/activate
+pip install -r server/requirements.txt
+```
+
+---
+
+## 3. 常用命令
+
+在 `server/` 目录运行：
+
+```bash
+source .venv/bin/activate
+alembic -c alembic.ini history
+alembic -c alembic.ini upgrade head
+```
+
+---
+
+## 4. 说明
+
+- 连接串由 `alembic/env.py` 从环境变量 `DATABASE_URL`（或 `app/core/config.py`）读取。
+- 初始迁移版本为：`0001_init_content_tables`（创建推荐系统最小内容表与画像表）。
+

server/alembic/env.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from logging.config import fileConfig
+from pathlib import Path
+
+from alembic import context
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+# 让 alembic 在 `server/` 下运行时也能 import app.*
+SERVER_DIR = Path(__file__).resolve().parents[1]  # .../server/alembic -> .../server
+sys.path.append(str(SERVER_DIR))
+
+from app.db.base import Base  # noqa: E402
+import app.db.models  # noqa: F401,E402  # 确保模型被导入，metadata 完整
+
+# Alembic Config 对象
+config = context.config
+
+# 配置日志
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# 目标 metadata（autogenerate 依赖）
+target_metadata = Base.metadata
+
+
+def _read_env_kv(env_path: Path) -> dict[str, str]:
+    """
+    读取 .env 文件中的 KEY=VALUE。
+
+    说明：
+    - 迁移阶段只需要 DATABASE_URL，不应因为 Redis/Celery 等配置缺失而失败
+    - 这里不依赖 pydantic-settings 的 Settings 校验，避免“缺字段导致迁移不可用”
+    """
+
+    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:
+    """
+    获取数据库连接串。
+
+    约定：
+    - 优先读取环境变量 `DATABASE_URL`
+    - 若未设置，则按 `APP_ENV`（默认 dev）读取 `server/.env.dev` 或 `server/.env.prod`
+
+    注意：迁移阶段仅依赖 DATABASE_URL；不应强制要求 REDIS_URL / CELERY_BROKER_URL 等配置存在。
+    """
+
+    # 允许在 alembic 命令时临时覆盖
+    env_url = os.getenv("DATABASE_URL")
+    if env_url:
+        return env_url
+
+    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")
+    if url:
+        return url
+
+    raise RuntimeError(
+        "缺少 DATABASE_URL：请设置环境变量 DATABASE_URL，或在 server/.env.dev（或 .env.prod）中配置 DATABASE_URL。"
+    )
+
+
+def run_migrations_offline() -> None:
+    """离线模式：生成 SQL 脚本，不连接数据库。"""
+
+    url = _get_database_url()
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    """在线模式：在已有连接上执行迁移。"""
+
+    context.configure(
+        connection=connection,
+        target_metadata=target_metadata,
+        compare_type=True,
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_migrations_online() -> None:
+    """在线模式：使用异步引擎执行迁移。"""
+
+    url = _get_database_url()
+    config.set_main_option("sqlalchemy.url", url)
+
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section) or {},
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    asyncio.run(run_migrations_online())
+

server/alembic/script.py.mako

@@ -0,0 +1,27 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}
+

server/alembic/versions/0001_init_content_tables.py

@@ -0,0 +1,147 @@
+"""init content tables
+
+Revision ID: 0001_init_content_tables
+Revises:
+Create Date: 2026-02-01
+
+"""
+
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import mysql
+
+
+# revision identifiers, used by Alembic.
+revision = "0001_init_content_tables"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "contents",
+        sa.Column(
+            "content_id",
+            mysql.BIGINT(unsigned=True),
+            primary_key=True,
+            autoincrement=True,
+            comment="文案唯一 ID（自增；文案微调时保持不变）",
+        ),
+        sa.Column("text_en", sa.Text(), nullable=True, comment="英文文案（可空；若为空则必须提供 text_tc）"),
+        sa.Column("text_tc", sa.Text(), nullable=True, comment="繁体中文文案（可空；若为空则必须提供 text_en）"),
+        sa.Column("author_id", sa.String(length=255), nullable=True, comment="作者/来源 ID（可空；用于多样性与频控）"),
+        sa.Column("template_id", sa.String(length=255), nullable=True, comment="模板 ID（可空；用于多样性与频控）"),
+        sa.Column("created_at", sa.DateTime(), server_default=sa.func.now(), nullable=False, comment="创建时间"),
+        sa.Column("updated_at", sa.DateTime(), server_default=sa.func.now(), nullable=False, comment="更新时间"),
+        sa.CheckConstraint(
+            "(text_en IS NOT NULL) OR (text_tc IS NOT NULL)",
+            name="chk_contents_text_present",
+        ),
+        mysql_charset="utf8mb4",
+    )
+    op.create_index("idx_contents_author_id", "contents", ["author_id"], unique=False)
+    op.create_index("idx_contents_template_id", "contents", ["template_id"], unique=False)
+
+    op.create_table(
+        "content_profiles",
+        sa.Column(
+            "content_id",
+            mysql.BIGINT(unsigned=True),
+            sa.ForeignKey("contents.content_id", ondelete="CASCADE"),
+            primary_key=True,
+            comment="FK -> contents.content_id",
+        ),
+        sa.Column(
+            "stage",
+            sa.Enum("general", "expecting", "parenting", "unknown", name="content_stage"),
+            server_default="general",
+            nullable=False,
+            comment="母职阶段定位（general/expecting/parenting/unknown）",
+        ),
+        sa.Column("emotion_score", sa.Numeric(3, 2), nullable=True, comment="情绪调性 0~1；NULL 表示 general"),
+        sa.Column(
+            "context_suitability_json",
+            sa.JSON(),
+            nullable=False,
+            comment="各 context 的适配度（JSON：0/0.5/1；必须包含 5 个 key）",
+        ),
+        sa.Column(
+            "need_suitability_json",
+            sa.JSON(),
+            nullable=False,
+            comment="各 need 的适配度（JSON：0/0.5/1；必须包含 5 个 key）",
+        ),
+        sa.Column(
+            "personalization_power",
+            sa.SmallInteger(),
+            server_default="0",
+            nullable=False,
+            comment="个性化力度（约定只允许 0/5/10，分别映射 0/0.5/1）",
+        ),
+        sa.Column(
+            "review_confidence",
+            sa.Numeric(3, 2),
+            nullable=True,
+            comment="标注置信度 0~1；NULL 表示由推荐侧按 0.7 兜底",
+        ),
+        sa.Column(
+            "is_safe_pool",
+            sa.Boolean(),
+            server_default=sa.text("0"),
+            nullable=False,
+            comment="是否属于通用安全池（L3 兜底）",
+        ),
+        sa.Column("updated_at", sa.DateTime(), server_default=sa.func.now(), nullable=False, comment="画像更新时间"),
+        mysql_charset="utf8mb4",
+    )
+    op.create_index("idx_profiles_is_safe_pool", "content_profiles", ["is_safe_pool"], unique=False)
+    op.create_index("idx_profiles_personalization_power", "content_profiles", ["personalization_power"], unique=False)
+    op.create_index("idx_profiles_stage", "content_profiles", ["stage"], unique=False)
+
+    op.create_table(
+        "content_risk_flags",
+        sa.Column(
+            "id",
+            mysql.BIGINT(unsigned=True),
+            primary_key=True,
+            autoincrement=True,
+            comment="主键",
+        ),
+        sa.Column(
+            "content_id",
+            mysql.BIGINT(unsigned=True),
+            sa.ForeignKey("contents.content_id", ondelete="CASCADE"),
+            nullable=False,
+            comment="FK -> contents.content_id",
+        ),
+        sa.Column(
+            "flag",
+            sa.String(length=64),
+            nullable=False,
+            comment="风险标记（unsafe_for_* / block_* / soft_*）",
+        ),
+        sa.Column("created_at", sa.DateTime(), server_default=sa.func.now(), nullable=False, comment="创建时间"),
+        sa.UniqueConstraint("content_id", "flag", name="uniq_content_flag"),
+        mysql_charset="utf8mb4",
+    )
+    op.create_index("idx_content_id", "content_risk_flags", ["content_id"], unique=False)
+    op.create_index("idx_flag", "content_risk_flags", ["flag"], unique=False)
+
+
+def downgrade() -> None:
+    op.drop_index("idx_flag", table_name="content_risk_flags")
+    op.drop_index("idx_content_id", table_name="content_risk_flags")
+    op.drop_table("content_risk_flags")
+
+    op.drop_index("idx_profiles_stage", table_name="content_profiles")
+    op.drop_index("idx_profiles_personalization_power", table_name="content_profiles")
+    op.drop_index("idx_profiles_is_safe_pool", table_name="content_profiles")
+    op.drop_table("content_profiles")
+
+    op.drop_index("idx_contents_template_id", table_name="contents")
+    op.drop_index("idx_contents_author_id", table_name="contents")
+    op.drop_table("contents")
+

server/app/api/__init__.py

@@ -0,0 +1,6 @@
+"""
+API 路由入口
+
+说明：按 FastAPI 常见工程结构拆分 api/v1/* 路由模块。
+"""
+

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/__init__.py

@@ -0,0 +1,4 @@
+"""
+V1 API 路由集合
+"""
+

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/api/v1/user_profile_scoring.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from app.features.user_profile_scoring.scoring import build_user_profile_from_questionnaire
+from app.features.user_profile_scoring.types import BuildUserProfileRequest, UserProfileV1_2_Extended
+
+router = APIRouter(prefix="/v1/user-profile", tags=["user-profile"])
+
+
+@router.post("/score", response_model=UserProfileV1_2_Extended)
+async def score_user_profile(req: BuildUserProfileRequest) -> UserProfileV1_2_Extended:
+    """
+    根据问卷答案生成用户画像（V1.2）
+
+    说明：
+    - 问卷题目允许跳过
+    - 允许注入 generated_at/now，用于回归测试或离线批处理
+    """
+
+    return build_user_profile_from_questionnaire(
+        req.answers,
+        generated_at=req.generated_at,
+        now=req.now,
+    )
+

server/app/db/models/__init__.py

@@ -0,0 +1,14 @@
+"""
+数据库 ORM 模型集合。
+
+说明：
+- 该包用于集中定义 SQLAlchemy ORM models，供 Alembic autogenerate 扫描。
+- 需要在此处导入所有模型，确保 `Base.metadata` 完整。
+"""
+
+from app.db.models.content import Content
+from app.db.models.content_profile import ContentProfile
+from app.db.models.content_risk_flag import ContentRiskFlag
+
+__all__ = ["Content", "ContentProfile", "ContentRiskFlag"]
+

server/app/db/models/content.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import CheckConstraint, DateTime, Index, Text, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class Content(Base):
+    """
+    文案主体表。
+
+    多语言约束：
+    - 当前仅支持 EN / TC（繁体中文）
+    - 至少需要提供 `text_en` 或 `text_tc` 之一
+    """
+
+    __tablename__ = "contents"
+
+    __table_args__ = (
+        CheckConstraint(
+            "(text_en IS NOT NULL) OR (text_tc IS NOT NULL)",
+            name="chk_contents_text_present",
+        ),
+        Index("idx_contents_author_id", "author_id"),
+        Index("idx_contents_template_id", "template_id"),
+    )
+
+    content_id: Mapped[int] = mapped_column(
+        primary_key=True,
+        autoincrement=True,
+        comment="文案唯一 ID（自增；文案微调时保持不变）",
+    )
+
+    text_en: Mapped[str | None] = mapped_column(
+        Text,
+        nullable=True,
+        comment="英文文案（可空；若为空则必须提供 text_tc）",
+    )
+    text_tc: Mapped[str | None] = mapped_column(
+        Text,
+        nullable=True,
+        comment="繁体中文文案（可空；若为空则必须提供 text_en）",
+    )
+
+    author_id: Mapped[str | None] = mapped_column(
+        nullable=True,
+        comment="作者/来源 ID（可空；用于多样性与频控）",
+    )
+    template_id: Mapped[str | None] = mapped_column(
+        nullable=True,
+        comment="模板 ID（可空；用于多样性与频控）",
+    )
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        nullable=False,
+        server_default=func.now(),
+        comment="创建时间",
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        nullable=False,
+        server_default=func.now(),
+        server_onupdate=func.now(),
+        comment="更新时间",
+    )
+

server/app/db/models/content_profile.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal, Optional
+
+from sqlalchemy import (
+    JSON,
+    Boolean,
+    DateTime,
+    Enum,
+    ForeignKey,
+    Index,
+    Numeric,
+    func,
+)
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+ContentStage = Literal["general", "expecting", "parenting", "unknown"]
+
+
+class ContentProfile(Base):
+    """
+    内容画像表（Content Profile / Cᵢ）。
+
+    字段语义必须严格对齐：
+    - `设计说明文档/句子文案打分規則.md`
+    """
+
+    __tablename__ = "content_profiles"
+
+    __table_args__ = (
+        Index("idx_profiles_stage", "stage"),
+        Index("idx_profiles_personalization_power", "personalization_power"),
+        Index("idx_profiles_is_safe_pool", "is_safe_pool"),
+    )
+
+    content_id: Mapped[int] = mapped_column(
+        ForeignKey("contents.content_id", ondelete="CASCADE"),
+        primary_key=True,
+        comment="FK -> contents.content_id",
+    )
+
+    stage: Mapped[ContentStage] = mapped_column(
+        Enum("general", "expecting", "parenting", "unknown", name="content_stage"),
+        nullable=False,
+        server_default="general",
+        comment="母职阶段定位（general/expecting/parenting/unknown）",
+    )
+
+    emotion_score: Mapped[Optional[float]] = mapped_column(
+        Numeric(3, 2),
+        nullable=True,
+        comment="情绪调性 0~1；NULL 表示 general",
+    )
+
+    context_suitability_json: Mapped[dict] = mapped_column(
+        JSON,
+        nullable=False,
+        comment="各 context 的适配度（JSON：0/0.5/1；必须包含 5 个 key）",
+    )
+    need_suitability_json: Mapped[dict] = mapped_column(
+        JSON,
+        nullable=False,
+        comment="各 need 的适配度（JSON：0/0.5/1；必须包含 5 个 key）",
+    )
+
+    personalization_power: Mapped[int] = mapped_column(
+        nullable=False,
+        server_default="0",
+        comment="个性化力度（约定只允许 0/5/10，分别映射 0/0.5/1）",
+    )
+
+    review_confidence: Mapped[Optional[float]] = mapped_column(
+        Numeric(3, 2),
+        nullable=True,
+        comment="标注置信度 0~1；NULL 表示由推荐侧按 0.7 兜底",
+    )
+
+    is_safe_pool: Mapped[bool] = mapped_column(
+        Boolean,
+        nullable=False,
+        server_default="0",
+        comment="是否属于通用安全池（L3 兜底）",
+    )
+
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        nullable=False,
+        server_default=func.now(),
+        server_onupdate=func.now(),
+        comment="画像更新时间",
+    )
+

server/app/db/models/content_risk_flag.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Index, UniqueConstraint, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class ContentRiskFlag(Base):
+    """
+    内容风险标记（risk_flags）关联表。
+
+    命名约束（语义来源：句子文案打分规则）：
+    - 仅允许 `unsafe_for_*` / `block_*` / `soft_*` 前缀
+    - 旧 flag（如 `block_stage_unknown`）需在写入/读取层做映射
+    """
+
+    __tablename__ = "content_risk_flags"
+
+    __table_args__ = (
+        UniqueConstraint("content_id", "flag", name="uniq_content_flag"),
+        Index("idx_flag", "flag"),
+        Index("idx_content_id", "content_id"),
+    )
+
+    id: Mapped[int] = mapped_column(
+        primary_key=True,
+        autoincrement=True,
+        comment="主键",
+    )
+
+    content_id: Mapped[int] = mapped_column(
+        ForeignKey("contents.content_id", ondelete="CASCADE"),
+        nullable=False,
+        comment="FK -> contents.content_id",
+    )
+
+    flag: Mapped[str] = mapped_column(
+        nullable=False,
+        comment="风险标记（unsafe_for_* / block_* / soft_*）",
+    )
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        nullable=False,
+        server_default=func.now(),
+        comment="创建时间",
+    )
+

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",
+]
+