# 星座/八字/数字能量引入心维度 · 先天画像体系设计

**日期**: 2026-08-28
**状态**: 已确认
**版本**: v1.0

**关联文档:**
- [五维能量系统设计](./2026-06-05-five-dimension-energy-design.md) — 五维能量体系
- [五行哲学体系](./2026-06-08-five-dimension-wuxing-philosophy.md) — 心=火，五行生克
- [LangGraph 迁移设计](./2026-07-20-langgraph-migration-design.md) — AI 服务架构
- [用户画像 prompt 设计](./2026-08-24-user-portrait-prompt-design.md) — AI 画像注入

---

## 一、背景与目标

### 1.1 现状

项目已有分散的"传统文化镜像"基础设施，各玄学来源各自有配置表和展示：

| 来源 | 配置表 | 先天分字段 | 服务 |
|------|--------|-----------|------|
| 星座 | `zodiac_config` | `mind_base`/`wisdom_base` | `ZodiacAnnualEnergyService` |
| 八字 | `bazi_config` | `mind_base`/`wisdom_base` | `BaziConfigService` |
| 血型 | `blood_type_config` | `mind_base`/`wisdom_base` | `BloodTypeConfigService` |
| 数字能量 | `numsoul_config`（灵数1-9） | — | `FamilyMemberAttributeService.getNumSoulConfig()` |

成员先天属性存于 `family_member_attributes` 表（八字四柱/五行/生肖/血型/`mind_base_score`/`wisdom_base_score`/`behavior_modifier`含灵数）。

已有接口：`/api/mind/traditional/mirror`、`/family-dashboard`、`/compatibility`、`/api/zodiac/energy`、`/api/tianpan/*`。

已有前端：`pages/mind-detail/` 下 `traditional-mirror.vue`、`duo-compatibility.vue`、`family-dashboard.vue`、`index.vue`。

### 1.2 问题

1. **分散**：各玄学来源各自展示，无统一"先天画像"聚合
2. **数字能量薄弱**：只有灵数1-9基础配置，缺天赋数/生日数/命运数
3. **先天后天未打通**：`mind_base_score`（先天）与 `energy_balance`（后天）未打通展示成长轨迹
4. **无 AI 个性化解读**：目前只有 `bazi_reading_template` 模板文案
5. **管理端不可配置**：各来源权重/启停/文案模板无法配置

### 1.3 目标

在现有基础上**深化/整合**，将星座/八字/数字能量统一为"心维度先天画像"体系：

1. **统一先天画像 + AI 解读**：聚合各来源，AI 主导生成个性化解读
2. **补强数字能量**：生日数字体系（生命灵数/天赋数/生日数/命运数）
3. **先天+后天打通**：展示先天起点 → 后天成长轨迹
4. **管理端可配置化**：各来源权重/启停/AI开关

### 1.4 产品定位（已确认）

**服务于五维能量体系**——星座/八字/数字能量作为心维度先天基础分来源，最终汇入五维能量，强调与后天能量打通、成长轨迹。

### 1.5 AI 定位（已确认）

**AI 主导生成**——先天画像和解读主要由 AI 生成，后端只提供原始数据。AI 服务不可用时降级为模板文案。

---

## 二、架构总览

```
┌─────────────────────────────────────────────────────────────┐
│                    数据源（现有，不动）                        │
│  zodiac_config / bazi_config / blood_type_config /          │
│  numsoul_config / life_number_relationship /                │
│  bazi_reading_template                                      │
└──────────────────────────┬──────────────────────────────────┘
                           │ 读取
┌──────────────────────────▼──────────────────────────────────┐
│          先天画像聚合层（新增 InnatePortraitService）          │
│  · 聚合八字/五行/星座/血型/灵数/天赋数/命运数                  │
│  · 复用 calcInnateScore 计算 mind_base_score                 │
│  · 数字能量补强（天赋数/生日数/命运数计算）                    │
└──────────────┬───────────────────────────┬─────────────────┘
               │ 原始数据                    │ 先天画像
┌──────────────▼──────────┐   ┌─────────────▼─────────────────┐
│  LangGraph AI graph     │   │  五维能量体系（现有）           │
│  (innate_portrait_graph)│   │  mind_base_score → energy_balance│
│  AI 主导生成解读文案     │   │  先天+后天成长轨迹              │
└──────────────┬──────────┘   └─────────────┬─────────────────┘
               │ AI解读                     │ 展示
┌──────────────▼───────────────────────────▼─────────────────┐
│              小程序心维度页面（增强）                         │
│  · 先天画像报告（AI解读）                                    │
│  · 先天+后天成长轨迹                                         │
└─────────────────────────────────────────────────────────────┘
```

---

## 三、数据模型设计

### 3.1 新增表：`innate_portrait_config`（先天画像来源权重配置）

管理端可配置各玄学来源对 `mind_base_score` 的权重、启停开关、AI 解读开关。

> **与现有硬编码权重的关系**：现有 `FamilyMemberAttributeService.calcInnateScore()` 硬编码 zodiac×50% + bazi×30% + blood×20%。本表权重将**替换**该硬编码逻辑——`calcInnateScore` 改为读取本表权重（详见 §7.5）。数字能量（numsoul）作为第 4 个来源参与加权。

```sql
CREATE TABLE IF NOT EXISTS innate_portrait_config (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    source_type VARCHAR(20) NOT NULL COMMENT '来源: zodiac/bazi/blood/numsoul',
    source_name VARCHAR(50) NOT NULL COMMENT '来源名称',
    weight INT DEFAULT 25 COMMENT '权重(基点,2500=25%)',
    enabled TINYINT(1) DEFAULT 1 COMMENT '是否启用',
    ai_enabled TINYINT(1) DEFAULT 1 COMMENT '是否启用AI解读',
    sort_order INT DEFAULT 0 COMMENT '排序',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_source (source_type)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='先天画像来源权重配置';
```

### 3.2 新增表：`innate_portrait_report`（先天画像报告缓存）

AI 解读结果缓存，避免重复调用 LLM。

> **职责边界**：本表只存 `portrait_json`（画像数据）+ `ai_reading`（AI解读）。**不重复存 `mind_base_score`**——先天分从 `family_member_attributes.mind_base_score` 读取，避免职责重叠。

```sql
CREATE TABLE IF NOT EXISTS innate_portrait_report (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    member_id BIGINT NOT NULL COMMENT '成员ID',
    member_type VARCHAR(10) NOT NULL COMMENT '成员类型: child/parent',
    family_id BIGINT NOT NULL COMMENT '家庭ID',
    portrait_json TEXT COMMENT '先天画像数据JSON',
    ai_reading TEXT COMMENT 'AI解读文案',
    generated_at DATETIME COMMENT '生成时间',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_member (member_id, member_type)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='先天画像报告缓存';
```

### 3.3 新增表：`numsoul_detail_config`（数字能量详细配置）

覆盖所有数字类型（生命灵数/天赋数/生日数/命运数），每个类型每个数字都有解读文案。

> **与现有 `numsoul_config` 的关系**：`numsoul_config`（灵数1-9基础配置）**保留不动**，兼容现有 `getNumSoulConfig()` 调用。`numsoul_detail_config` 是**扩展**，覆盖更细的数字类型（生命灵数/天赋数/生日数/命运数），并新增 `mind_base` 字段使数字能量参与 `mind_base_score` 加权计算。

```sql
CREATE TABLE IF NOT EXISTS numsoul_detail_config (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    number_type VARCHAR(20) NOT NULL COMMENT '类型: life_path/talent/birthday/destiny',
    number_value INT NOT NULL COMMENT '数字值 1-9 或主数 11/22/33',
    title VARCHAR(50) COMMENT '称号',
    keywords VARCHAR(200) COMMENT '性格关键词',
    mind_base INT DEFAULT 0 COMMENT '心先天基础分(百分位)',
    mind_advice TEXT COMMENT '心维度成长建议',
    color_hex VARCHAR(10) COMMENT '代表色',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_type_num (number_type, number_value)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='数字能量详细配置表';
```

### 3.4 数字能量计算规则（后端 Service 实现）

从出生日期推导：
- **生命灵数**（life_path）：年月日所有数字相加直至个位（主数 11/22/33 保留）
- **天赋数**（talent）：生命灵数计算过程中化简前的两位数
- **生日数**（birthday）：出生日化简至个位
- **命运数**（destiny）：出生年月日总和化简（简化版，不含姓名）

---

## 四、后端服务层设计

### 4.1 新增 `InnatePortraitService`（先天画像聚合服务）

核心服务，职责：
1. **聚合先天画像**：从 `family_member_attributes` + 各配置表聚合出完整先天画像（八字/五行/星座/血型/灵数/天赋数/生日数/命运数）
2. **复用 `calcInnateScore` 计算 mind_base_score**：**不重复实现**加权逻辑，直接调用现有 `FamilyMemberAttributeService.calcInnateScore()`（该服务已实现 zodiac×50% + bazi×30% + blood×20% 加权并缓存到 `mind_base_score`）
3. **数字能量计算**：从出生日期推导生命灵数/天赋数/生日数/命运数
4. **AI 解读编排**：调用 LangGraph graph 生成解读，结果缓存到 `innate_portrait_report`

> **关键决策**：`mind_base_score` 的计算逻辑**已存在于** `FamilyMemberAttributeService.calcInnateScore()`（zodiac×50% + bazi×30% + blood×20%，已缓存）。`InnatePortraitService` **复用**该方法，不重复实现。管理端可配置权重（`innate_portrait_config`）将**替换** `calcInnateScore` 中的硬编码权重（详见 §7.5）。

```java
@Service
public class InnatePortraitService {

    @Resource
    private FamilyMemberAttributeService familyMemberAttributeService;

    @Resource
    private InnatePortraitConfigMapper innatePortraitConfigMapper;

    @Resource
    private InnatePortraitReportMapper innatePortraitReportMapper;

    @Resource
    private NumSoulDetailConfigMapper numSoulDetailConfigMapper;

    @Resource
    private AiGateway aiGateway;

    /**
     * 聚合先天画像 + 复用 calcInnateScore 计算 mind_base_score
     */
    public InnatePortraitVO getInnatePortrait(Long memberId, String memberType) {
        // 1. 读取 family_member_attributes
        // 2. 聚合各来源数据（八字/五行/星座/血型/灵数）
        // 3. 计算数字能量（生命灵数/天赋数/生日数/命运数）
        // 4. 复用 familyMemberAttributeService.calcInnateScore(memberId, memberType, "mind")
        // 5. 返回完整画像
    }

    /**
     * 生成 AI 解读（缓存到 innate_portrait_report）
     */
    public InnatePortraitReportVO generateAiReading(Long memberId, String memberType) {
        // 1. 检查缓存，未过期直接返回
        // 2. 聚合先天画像
        // 3. 调用 AiGateway 生成 AI 解读
        // 4. 缓存结果
    }

    /**
     * 数字能量计算
     */
    public NumSoulDetailVO calculateNumSoul(Date birthDatetime) {
        // 生命灵数/天赋数/生日数/命运数
    }

    /**
     * 先天+后天成长轨迹
     */
    public InnateTrajectoryVO getTrajectory(Long memberId, String memberType, Long familyId) {
        // 1. 读取先天画像 + mind_base_score
        // 2. 读取 energy_balance（后天当前能量）
        // 3. 计算先天 vs 后天的差值/趋势
        // 4. 结合 AI 解读生成成长建议
    }
}
```

### 4.2 新增 DTO

- `InnatePortraitVO`：完整先天画像（八字/五行/星座/血型/灵数/天赋数/生日数/命运数 + mind_base_score）
- `NumSoulDetailVO`：数字能量详情（各类型数字 + 配置解读）
- `InnatePortraitReportVO`：AI 解读报告（画像 + AI 文案 + 分数）
- `InnateTrajectoryVO`：先天+后天成长轨迹

### 4.3 新增 Controller

`InnatePortraitController`（`/api/mind/innate`）：
- `POST /api/mind/innate/portrait` — 获取先天画像
- `POST /api/mind/innate/reading` — 生成/获取 AI 解读
- `POST /api/mind/innate/numsoul` — 获取数字能量详情
- `POST /api/mind/innate/trajectory` — 获取先天+后天成长轨迹

### 4.4 新增 Mapper

- `InnatePortraitConfigMapper`
- `InnatePortraitReportMapper`
- `NumSoulDetailConfigMapper`

---

## 五、AI 解读（LangGraph graph）设计

### 5.1 新增 `innate_portrait_graph`（先天画像解读 graph）

在 `cfc-langgraph/app/graphs/` 新增 `innate_portrait_graph.py`，接收先天画像原始数据，AI 主导生成个性化解读。

```
┌─────────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│ 收集画像数据  │ → │ 组装解读Prompt│ → │ LLM生成解读   │ → │ 结构化输出    │
│ (portrait)  │   │ (prompt)     │   │ (解读文案)    │   │ (JSON)       │
└─────────────┘   └──────────────┘   └──────────────┘   └──────────────┘
```

**graph 节点设计**：
1. **build_prompt**：接收先天画像数据（八字四柱/五行/星座/血型/灵数/天赋数/生日数/命运数），组装解读 prompt（含角色设定：家庭教育/成长陪伴语境）
2. **generate**：调用 LLM 生成解读（心维度特质 + 成长建议 + 亲子互动建议）
3. **parse**：解析 LLM 输出为结构化 JSON

**输出结构**：
```json
{
  "mindTraits": "心维度特质描述（基于五行/星座/灵数综合分析）",
  "strengths": ["先天优势1", "先天优势2"],
  "growthAdvice": "心维度成长建议",
  "parentAdvice": "家长互动建议",
  "wuxingBalance": "五行平衡提示"
}
```

### 5.2 新增 FastAPI 端点

在 `app/api/adapter.py` 或新增 `app/api/innate.py`：
- `POST /api/v1/innate/reading` — 接收先天画像数据，返回 AI 解读

### 5.3 AiGateway 扩展

在 `AiGateway.java` 新增方法：
```java
public Map<String, Object> generateInnateReading(Map<String, Object> portrait) {
    // POST baseUrl + "/api/v1/innate/reading"
    // 熔断 + fallback（fallback 返回模板文案）
}
```

**Fallback 策略**（关键）：
- AI 服务不可用时，降级为 `bazi_reading_template` 模板文案 + `numsoul_detail_config` 静态文案拼接
- 保证功能可用，AI 是增强不是依赖

### 5.4 Prompt 设计要点

解读 prompt 需：
- 角色设定：家庭教育成长陪伴师
- 结合五行哲学（心=火）与五维能量体系
- 强调"先天特质 + 后天成长"视角
- 避免宿命论措辞，强调"了解先天特质 → 针对性培养"
- 输出限定 JSON 结构

---

## 六、先天+后天打通设计

### 6.1 数据流打通

现有五维能量体系用 `energy_balance`（当前能量）+ `energy_log`（流水）。先天基础分（`mind_base_score`）需要与后天能量打通，展示成长轨迹。

**设计思路**：
- **先天**：`mind_base_score`（0-100）作为心维度的"起点基线"
- **后天**：`energy_balance`（当前能量值）作为心维度的"当前状态"
- **成长轨迹**：先天 vs 后天对比，展示"天赋起点 → 后天成长"

### 6.2 新增接口：`POST /api/mind/innate/trajectory`

返回某成员的先天画像 + 后天成长轨迹：

```json
{
  "innatePortrait": { "mindBaseScore": 72, "zodiac": "狮子座", "lifeNumber": 3, "..." },
  "innateDimensionScores": { "body": 65, "mind": 72, "wisdom": 68, "action": 60, "wealth": 55 },
  "currentEnergy": { "mindBalance": 120, "mindTotalEarned": 350, "..." },
  "trajectory": {
    "innateVsCurrent": { "mindInnate": 72, "mindCurrent": 81, "growth": "+9" },
    "growthTrend": "先天心能量充沛，后天通过情绪打卡/家庭互动持续成长",
    "advice": "保持当前情绪打卡频率，建议增加家庭共处时间..."
  }
}
```

### 6.3 打通逻辑

`InnatePortraitService.getTrajectory(memberId, memberType, familyId)`：
1. 读取先天画像 + `mind_base_score`
2. 读取 `energy_balance`（后天当前能量）
3. 计算先天 vs 后天的差值/趋势
4. 结合 AI 解读生成成长建议

### 6.4 展示位置

小程序 `pages/mind-detail/index.vue` 心维度首页，新增"先天画像"卡片：
- 显示先天心能量基础分 + 后天当前能量分
- 先天数字能量画像（生命灵数/天赋数等）
- 点击进入 AI 解读报告页

---

## 七、管理端可配置化设计

### 7.1 新增管理端页面：`InnatePortraitConfig.vue`

在 `cfc-web/src/views/admin/` 新增，管理先天画像来源权重配置：

**功能**：
- 各来源（星座/八字/血型/数字能量）的权重配置（基点）
- 启停开关（enabled）
- AI 解读开关（ai_enabled）
- 排序

### 7.2 新增管理端页面：`NumSoulDetailConfig.vue`

管理数字能量详细配置（`numsoul_detail_config`）：

**功能**：
- 按数字类型（生命灵数/天赋数/生日数/命运数）筛选
- 每个数字（1-9 + 主数11/22/33）的称号/关键词/心维度成长建议/代表色
- 增删改查

### 7.3 新增管理端 Controller

- `InnatePortraitConfigController`（`/api/admin/innate-portrait-config`）：list/create/update/delete
- `NumSoulDetailConfigController`（`/api/admin/numsoul-detail-config`）：list/create/update/delete

### 7.4 菜单接入

在管理端菜单（`SysMenuController` / 前端路由）新增入口：
- 先天画像配置
- 数字能量配置

### 7.5 权重替换硬编码逻辑（缺陷修复）

**现有逻辑**：`FamilyMemberAttributeService.calcInnateScore()` 硬编码：
```java
Integer result = (zodiacScore * 5000 + baziScore * 3000 + bloodScore * 2000) / 10000;
```

**改造**：`calcInnateScore()` 改为读取 `innate_portrait_config` 表权重：
```java
// 读取配置（默认 zodiac/bazi/blood/numsoul 各 25%）
// 只累加 enabled=1 的来源
// 权重未配置时回退到现有硬编码 50/30/20
Integer result = (zodiacScore * wZodiac + baziScore * wBazi + bloodScore * wBlood + numsoulScore * wNumsoul) / 10000;
```

**要求**：
- 权重未配置（表空）时回退到现有 50/30/20 硬编码，保证存量数据不变化
- `numsoul_score` 从 `numsoul_detail_config.life_path.mind_base` 读取（按生命灵数匹配）
- 启用的来源权重之和不足 100% 时按比例归一化，超过则按比例缩放

---

## 八、前端小程序展示设计

### 8.1 新增页面：`pages/mind-detail/innate-portrait.vue`（先天画像报告页）

展示 AI 解读报告：
- **头部**：成员头像 + 先天心能量基础分
- **先天画像**：八字四柱 / 五行能量 / 星座 / 血型 / 数字能量（生命灵数/天赋数/生日数/命运数）
- **AI 解读**：心维度特质 / 先天优势 / 成长建议 / 家长互动建议
- **五行平衡**：五行能量条

### 8.2 新增页面：`pages/mind-detail/innate-trajectory.vue`（先天+后天成长轨迹页）

展示成长轨迹：
- **先天 vs 后天**：心维度先天基础分 vs 当前能量分对比
- **成长趋势**：趋势图/文案
- **成长建议**：AI 生成的针对性建议

### 8.3 心维度首页增强：`pages/mind-detail/index.vue`

在现有首页新增"先天画像"入口卡片：
- 显示先天心能量基础分
- 点击进入先天画像报告页
- 显示数字能量画像（生命灵数等）

### 8.4 小程序限制遵守

- 禁止可选链 `?.`（用 `&&` 替代）
- 禁止 CSS Grid（用 flexbox）
- 禁止 `:key` 表达式（用方法调用）
- 禁止直接 `new Date(string)`（用 `parseDate()`）
- Vue 2 Options API

---

## 九、数据库迁移

在 `DatabaseInitializer.runMigrations()` 新增迁移（编号从 267 开始）：

1. **迁移267**：创建 `innate_portrait_config` 表 + 种子数据（4 来源默认权重 25%）
2. **迁移268**：创建 `innate_portrait_report` 表
3. **迁移269**：创建 `numsoul_detail_config` 表 + 种子数据（4 类型 × 数字 1-9 + 主数，含 `mind_base` 字段）

同步更新 `schema.sql` 的 CREATE TABLE 定义。

> **注意**：`numsoul_detail_config` 的 `mind_base` 字段是数字能量参与 `mind_base_score` 加权计算的关键。种子数据需为每个数字类型（life_path/talent/birthday/destiny）的每个数字（1-9 + 主数 11/22/33）配置 `mind_base` 值。

---

## 十、测试策略

### 10.1 后端单元测试

- `InnatePortraitServiceTest`：数字能量计算（生命灵数/天赋数/生日数/命运数）、先天画像聚合
- `NumSoulDetailConfigMapperTest`：配置表 CRUD
- `FamilyMemberAttributeServiceTest`（扩展）：`calcInnateScore` 权重替换后——配置表权重生效、表空时回退硬编码 50/30/20、numsoul 参与加权、权重归一化

### 10.2 后端集成测试

- `InnatePortraitControllerTest`：portrait/reading/numsoul/trajectory 接口
- AI 解读 fallback 测试（AI 不可用时降级模板文案）
- `calcInnateScore` 权重替换回归测试（存量数据 mind_base_score 不因权重替换而变化）

### 10.3 前端测试

- 小程序页面渲染测试（先天画像报告页/成长轨迹页）
- 管理端配置页 CRUD 测试

---

## 十一、非目标（YAGNI）

- 不重构现有 `zodiac_config`/`bazi_config`/`blood_type_config` 表结构
- 不新增手机号/车牌号等后天数字能量分析
- 不重构现有天盘/合盘/镜像页面
- 不引入新的中间件或依赖