# 数字能量学智能体 — 需求与设计文档

**创建日期:** 2026-05-22
**更新日期:** 2026-05-22
**状态:** 设计确认，待实现

## 1. 项目概述

数字能量学智能体 — 基于数字能量学理论，结合规则引擎与 AI 的综合分析咨询系统。

### 核心理念

- **规则引擎 → Dify Python 节点实现**：所有数字能量学确定性知识（八星分类、五行生克、81灵数）在 Dify Workflow 中以 Python 节点实现，保证计算确定性
- **LLM 处理 → Dify LLM 节点**：解读生成由 Dify 的 LLM 节点完成，Prompt 和供应商路由在 Dify 内管理
- **小程序 → 直连 Dify API**：聊天对话类请求直接调用 Dify API，跳过后端
- **轻量后端仅保留微信生态必须能力**：微信登录、数据持久化、API Key 代理

### 整体数据流

```
用户输入（号码/问题）
    ↓
微信小程序
    ├── 聊天/分析咨询类 → Dify API → Dify Workflow
    │                     ├── [Python 节点] 规则引擎计算
    │                     │   ├── 八星分类匹配
    │                     │   ├── 五行属性计算
    │                     │   ├── 吉凶评分
    │                     │   └── 输出结构化 JSON
    │                     ├── [LLM 节点] AI 解读
    │                     │   ├── 注入规则结果作为事实依据
    │                     │   ├── 知识库 RAG 检索
    │                     │   └── 生成自然语言报告
    │                     └── 返回最终结果
    │
    └── 登录/支付/历史记录 → 轻量后端 API
                              └── MySQL（用户/记录）
```

## 2. 技术架构

```
微信小程序 (uni-app)                   轻量后端 (Spring Boot)
      │                                        │
      ├── Dify API (聊天/分析)                 ├── POST /api/auth/login
      │                                        ├── GET/PUT /api/user/profile
      │   Dify Workflow 内部:                   ├── GET /api/records
      │   ┌──────────────────────┐              ├── POST /api/dify/proxy
      │   │ Python 节点: 规则引擎 │              └── POST /api/pay/*
      │   │ LLM 节点: AI 解读    │
      │   └──────────────────────┘
      │
      └── 轻量后端 API (登录/记录)
```

### Maven 模块

| 模块 | 职责 | 说明 |
|------|------|------|
| `num-server` | Spring Boot 应用（统一模块） | 仅含 common + wechat + api |
| `num-common` | 统一响应体 `Result<T>`、异常、工具类 | 公共依赖 |

**无需独立模块的职责**（已移入 Dify）：
- ~~规则引擎~~ → Dify Python 节点
- ~~AI 处理~~ → Dify LLM 节点
- ~~报告生成~~ → Dify Workflow 输出

## 3. 轻量后端 API

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/auth/login` | 微信登录（code → openId → JWT） |
| POST | `/api/auth/refresh` | 刷新 Token |
| POST | `/api/user/profile` | 获取用户信息 |
| POST | `/api/user/profile/update` | 更新用户信息 |
| POST | `/api/records` | 查询分析历史（分页） |
| POST | `/api/records/detail` | 单条记录详情 |
| POST | `/api/records/save` | 保存分析记录（Dify 回调或小程序主动上报） |
| POST | `/api/dify/proxy` | Dify API 代理（保护 API Key 免暴露给小程序） |
| POST | `/api/pay/unified-order` | 微信支付下单 |

统一返回格式：`{ code: int, message: string, data: T }`
认证方式：JWT Bearer Token（`Authorization` Header）

## 4. 数据模型

```sql
-- 用户表
user
├── id          BIGINT PK AUTO_INCREMENT
├── open_id     VARCHAR(64) UNIQUE   -- 微信 openId
├── nick_name   VARCHAR(64)
├── avatar_url  VARCHAR(512)
└── create_time DATETIME

-- 分析记录表
analysis_record
├── id          BIGINT PK AUTO_INCREMENT
├── user_id     BIGINT FK → user
├── type        VARCHAR(32)           -- NUMBER / LIFE_CHART / CONSULT
├── input       TEXT                  -- 原始输入（号码/生日/问题）
├── dify_result JSON                  -- Dify 返回的完整结果
├── summary     VARCHAR(256)          -- 简要结论（用于列表展示）
└── create_time DATETIME
```

## 5. Dify 工作流设计

### 工作流：号码分析

```
输入参数: { phoneNumber: "138xxxx" }
  ↓
[Python 节点: number_engine]
  ├── 输入: phoneNumber
  ├── 逻辑:
  │   1. 拆分 2 位数字组合 ["13","38","8x","xx","xx"]
  │   2. 查八星对照表 → 每组合的 star/element/score
  │   3. 聚合: 评分总和、五行分布、吉凶结论
  └── 输出: { parts: [...], overall_score: 75, element_balance: {...}, conclusion: "吉" }
  ↓
[LLM 节点: generate_interpretation]
  ├── System Prompt: "你是一位数字能量学专家。以下是规则引擎计算的号码分析结果，请基于此为用户生成详细的号码解读报告..."
  ├── 注入变量: {{node.number_engine.output}}
  ├── 知识库: RAG 检索相关八星含义、案例参考
  └── 输出: 自然语言分析报告
  ↓
输出: { engine_result: {...}, ai_interpretation: "..." }
```

### 工作流：AI 对话咨询

```
输入参数: { query: "...", history: [...], context_phone: "" }
  ↓
[Python 节点: context_parser]
  ├── 检查 query 中是否包含号码/数字
  ├── 如果有 → 调 number_engine 逻辑（复用函数）
  └── 输出: { needs_engine: true/false, engine_result?: {...} }
  ↓
[LLM 节点: chat]
  ├── 注入规则结果（如有）
  ├── 带历史上下文的对话
  └── 输出: AI 回复
```

### Python 规则引擎设计要点

- **无外部依赖**：仅用 Python 标准库，避免 Dify Python 沙箱限制
- **数据驱动**：八星对照表、五行表等用 Python dict/JSON 硬编码在代码中
- **纯函数式**：输入 → 输出，无副作用，便于 Dify 节点调试和复用
- **输出格式固定一致**：始终输出相同结构的 JSON，方便下游 LLM 节点消费

```python
# 示例骨架 — Dify Python 节点代码
STAR_MAP = {
    "13": {"star": "天医", "element": "木", "score": 90, "description": "主财富、姻缘"},
    "68": {"star": "天医", "element": "木", "score": 85, "description": "主财富、贵人"},
    "14": {"star": "生气", "element": "火", "score": 80, "description": "主贵人、人脉"},
    # ... 全部 81 组对照
}

def main(phone_number: str) -> dict:
    parts = []
    for i in range(len(phone_number) - 1):
        pair = phone_number[i:i+2]
        info = STAR_MAP.get(pair, {"star": "未知", "element": "未知", "score": 0})
        parts.append({"digits": pair, **info})

    scores = [p["score"] for p in parts if p["score"] > 0]
    overall = sum(scores) / len(scores) if scores else 0
    conclusion = "大吉" if overall >= 80 else "吉" if overall >= 60 else "凶"

    return {
        "parts": parts,
        "overall_score": overall,
        "conclusion": conclusion,
        "element_balance": {...}
    }
```

## 6. 前端（微信小程序 — uni-app）

### 页面结构

```
pages/
├── index/          # 首页（功能入口 + 号码快速输入）
├── analysis/       # 号码分析结果展示
├── life-chart/     # 命盘展示
├── chat/           # AI 对话（直连 Dify 对话 API）
├── records/        # 历史记录列表
├── record-detail/  # 单条记录详情
└── mine/           # 个人中心（登录/设置）
```

### 小程序数据流

```
分析类请求:
  小程序 → Dify API (Workflow) → Python规则引擎 + LLM解读 → 返回结果
                                    ↓
                              小程序收到结果 → 显示 → 同步保存到后端API

聊天类请求:
  小程序 → Dify API (对话应用) ↔ 流式对话

登录/记录:
  小程序 → 后端API → MySQL
```

## 7. 项目目录结构

```
num/
├── AGENTS.md
├── num-server/              # Spring Boot 轻量后端
│   ├── pom.xml
│   └── src/main/java/com/num/
│       ├── NumApplication.java
│       ├── controller/      # auth, user, record, dify proxy, pay
│       ├── service/
│       ├── entity/
│       ├── repository/
│       ├── config/          # JWT, 微信, Dify 配置
│       └── common/
│           ├── Result.java
│           └── GlobalExceptionHandler.java
├── dify/                    # Dify 工作流设计文档
│   ├── workflows/
│   │   ├── number-analysis.md     # 号码分析工作流
│   │   ├── ai-consult.md          # AI 对话工作流
│   │   └── python-engine/         # Python 节点代码
│   │       ├── number_engine.py   # 规则引擎主逻辑
│   │       ├── star_map.py        # 八星对照表
│   │       └── elements.py        # 五行计算
│   └── knowledge-base/           # 知识库资料清单
│       └── sources.md
├── client/                  # uni-app 微信小程序
│   ├── pages/
│   ├── api/                 # Dify API + 后端API 封装
│   ├── App.vue
│   └── manifest.json
└── docs/
    └── superpowers/specs/
```

## 8. 不作的事情（Scope Exclusion）

- ❌ 不在后端实现数字能量学规则 — 全部在 Dify Python 节点
- ❌ 不做 LLM Prompt 管理 — Dify Workflow 负责
- ❌ 不做 Android/iOS 原生 App — 仅微信小程序
- ❌ 不接入非微信支付渠道
- ❌ 不维护数字能量学「理论创新」，只做已有知识的工程化

## 9. 待确认/后续

- Dify 部署地址 / API Key / Workflow ID
- 微信小程序 AppID / 支付商户号
- 部署环境（服务器配置、域名、SSL）