# 数字能量学智能体（Digital Energy Numerology Agent）

基于数字能量学理论的 AI 分析与咨询系统。结合数字能量学知识库与 LLM 能力，提供数字命理分析、AI 解读、分销推广等服务。

## 技术栈

| 层 | 技术 |
|---|------|
| **前端** | uni-app (Vue 3 + Pinia + SCSS), 微信小程序 |
| **注册** | 微信一键登录 + 生日性别等资料完善 |
| **后端** | Spring Boot 2.7.18 + JPA + Redis |
| **AI** | Dify Workflow（命盘解读）+ Dify Chatflow（AI问答）+ 知识库（RAG） |
| **支付** | 微信支付 |
| **构建** | Maven |

## 项目结构

```
num/
├── client/                    # 微信小程序前端 (uni-app)
│   ├── components/            # 公共组件
│   │   └── TriangleChart.vue  # 数字能量三角图组件
│   ├── pages/
│   │   ├── index/index.vue    # 首页（生日输入 → 发起咨询）
│   │   ├── chart/index.vue    # 命盘展示 + AI 问答
│   │   ├── records/index.vue  # 历史咨询记录
│   │   ├── login/index.vue    # 微信登录
│   │   ├── register/index.vue # 注册资料完善（生日/性别/社交资料）
│   │   ├── payment/index.vue  # 支付
│   │   ├── profile/index.vue  # 个人中心
│   │   ├── subscribe/index.vue # 订阅
│   │   └── relations/          # 🔗 关系能量分析（超级会员专属）
│   │       ├── index.vue       # 关系首页（分类入口+关系人列表）
│   │       ├── add-relation.vue # 添加关系人
│   │       ├── chart-compare.vue # 双命盘对比
│   │       └── number-analysis.vue # 八星号码分析
│   ├── stores/
│   │   ├── chart.js           # 命盘状态管理
│   │   └── user.js            # 用户状态管理
│   └── utils/
│       ├── api.js             # 后端 API 封装
│       └── calculator.js      # 命盘计算（已移至后端）
│
├── num-server/                # Java 后端 (Spring Boot)
│   └── src/main/java/com/etotem/num/
│       ├── controller/        # REST 控制器
│       │   ├── ChartController.java    # 命盘 CRUD + 咨询发起
│       │   ├── ChatController.java     # AI 问答
│       │   ├── AuthController.java     # 微信登录
│       │   ├── PayController.java      # 微信支付
│       │   ├── ProfileController.java  # 用户信息
│       │   ├── CommissionController.java # 佣金
│       │   ├── AdminController.java    # 管理后台
│       │   └── ...
│   ├── service/
│   │   ├── CalculatorService.java  # 命盘计算引擎
│   │   ├── ChartService.java       # 咨询会话管理
│   │   ├── ChatService.java        # AI 问答 + 配额控制
│   │   ├── UserService.java        # 用户/登录/配额
│   │   ├── DifyService.java        # Dify LLM 调用
│   │   ├── OrderService.java       # 订单/佣金结算
│   │   └── ...
│   ├── commerce/                   # 商城接口层（lilishop预留）
│   │   ├── CommerceService.java    # 商城核心接口
│   │   ├── StubCommerceService.java# Phase 1 桩实现
│   │   └── dto/                    # 订单/商品/结算 DTO
│       ├── entity/            # JPA 实体
│       ├── repository/        # 数据访问层
│       └── config/            # 配置
│
├── docs/                      # 项目文档
│   ├── phase1-user-stories.md # Phase 1 用户故事与验收标准
│   ├── style-guide.md         # 前端样式指南
│   ├── system-spec.md         # 系统需求规格
│   ├── distribution-model.md  # 分销模式设计
│   ├── phase1-product-plan.md # 产品规划
│   └── requirements-changelog.md # 需求版本变更日志
│
└── AGENTS.md                  # AI 智能体项目定义
```

## 快速开始

### 环境要求

- JDK 1.8+
- Maven 3.6+
- MySQL 8.0
- Redis
- Node.js 16+（前端构建）
- 微信小程序开发者工具

### 后端启动

```bash
# 1. 创建数据库
mysql -u root -p -e "CREATE DATABASE num_energy DEFAULT CHARACTER SET utf8mb4"

# 2. 修改配置
# 编辑 num-server/src/main/resources/application.yml
# 配置 MySQL、Redis、微信支付、Dify API 等

# 3. 启动
cd num-server
mvn spring-boot:run
# 默认端口 8186
```

### 前端启动

```bash
# 1. 安装依赖
cd client
npm install

# 2. 修改 API 地址
# 编辑 client/utils/api.js 中的 API_BASE_URL

# 3. 在微信开发者工具中打开 client/ 目录
#   或使用 HBuilderX 导入并运行
```

## 功能模块

| 模块 | 说明 | 状态 |
|------|------|------|
| **命盘生成** | 输入生日，后台计算 24 个数字位置（三角命盘） | ✅ 已完成 |
| **AI 解读** | LLM 自动生成命盘解读，支持追问互动 | ✅ 已完成 |
| **付费订阅** | 能量师年费 ¥1,314/¥1,986，C端年费 ¥131，超级会员 ¥1,314 | ✅ 已完成 |
| **注册完善** | 微信登录 → 选昵称头像 + 填生日性别 + 社交资料 | ✅ 已完成 |
| **分销推广** | 推广码 + 上下级绑定 + 两级佣金（固定/比例） | ✅ 已完成 |
| **分销面板** | 佣金统计、团队数据、推广码展示 | 🚧 Phase 1 |
| **管理后台** | 系统配置、订单管理、佣金查看 | 🚧 Phase 1 |
| **C端分销** | C 端用户推广 C 端年费，40%+5% 分成 | 🚧 Phase 1 |
| **学业方向AI** | 家长为孩子选学业方向，AI深度解读天赋倾向 | 🚧 EPIC 9 |
| **人工方案** | 申请能量师出方案 + 价格协商 + 在线支付 | 🚧 EPIC 9 |
| **🔗 关系能量分析** | 夫妻/亲子/同事/朋友/上下级命盘对比 + 八星号码分析（超级会员专属） | 🚧 EPIC 10 |
| **超级会员** | ¥1,314/年，含关系能量分析+分销权限 | 🚧 EPIC 10 |
| **提现管理** | 佣金提现功能 | 📅 Phase 2 |
| **lilishop商城** | B2B2C电商底座，预留接口，暂不实现支付 | 📅 Phase 2+ |

## 命盘位置命名

项目采用 **A-X** 24 位置命名体系：

```
输入层: A B C D（年） E F（月） G H（日）
内部层: I J K L（底层） M N（中层） O（顶层/主性格）
外部层: P Q R（左侧/21-40岁） S T U（右侧/61+岁） V W X（顶部/41-60岁）
```

详见 `docs/phase1-user-stories.md` 中 **US-1.3** 完整对照表。

## 核心 API

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/auth/login` | POST | 微信登录/注册 |
| `/api/consultation/start` | POST | 发起咨询（含查重） |
| `/api/chart/create` | POST | 创建命盘记录 |
| `/api/chart/list` | POST | 咨询历史列表 |
| `/api/chart/detail` | POST | 咨询详情 |
| `/api/chat/send` | POST | AI 问答 |
| `/api/chat/history` | POST | 聊天历史 |
| `/api/pay/create` | POST | 创建支付订单 |
| `/api/profile/quota` | POST | 查询当日配额 |
| `/api/commission/list` | POST | 佣金明细 |
| `/api/admin/config/list` | POST | 系统配置列表 |
| `/api/admin/config/update` | POST | 更新系统配置 |

## 定价方案

| 角色 | 种子价 | 标准价 | 权益 |
|------|--------|--------|------|
| 能量师 | ¥1,314（创始人码+有效期+名额） | ¥1,986 | 完整命盘+AI解读+客户管理+分销推广 |
| **超级会员** | **—（固定价）** | **¥1,314/年** | **完整AI+关系能量分析+八星号码+分销推广** |
| C端会员 | — | ¥131/年 | AI互动问答+分销权限 |

## 文档索引

- [Phase 1 用户故事](docs/phase1-user-stories.md) — 所有功能需求、验收标准、排期
- [前端样式指南](docs/style-guide.md) — 品牌色/字体/组件/动效规范
- [系统需求规格](docs/system-spec.md) — 整体系统设计
- [分销模式设计](docs/distribution-model.md) — 佣金规则、推广流程
- [需求版本日志](docs/requirements-changelog.md) — 需求变更历史
- [产品规划](docs/phase1-product-plan.md) — Phase 1 产品方案
- [Dify AI 架构](docs/phase1-user-stories.md#附录bdify-ai-架构设计) — Dify 工作流/知识库/Java集成说明

## 定价与佣金参数

所有定价和佣金参数通过管理后台动态配置（`sys_config` 表），无需硬编码。
详见 US-8.1 系统配置管理。