# 八字排盘

**Repository Path**: teampanel/bazipaipan

## Basic Information

- **Project Name**: 八字排盘
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-31
- **Last Updated**: 2026-11-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 干支历 · Ganzhi Calendar

> 传统历法与干支文化工具 —— Go 后端 + uni-app 前端，一套代码同时支持 **H5 网页** 与 **微信小程序**。

「干支历」提供公历/农历换算、节气查询、真太阳时校正、四柱干支（年月日时）、大运流年推步、五行统计等传统历法计算能力，并由 AI 提供干支文化知识讲解（名词解释与文化背景，**不含任何预测服务**）。

**核心原则：所有历法数据均为确定性天文硬算（寿星天文历算法），AI 只做文化科普，不参与任何计算。**

## 📸 应用截图

| 输入页（公历/农历 · 真太阳时 · 服务端历史记录） | 全中文日期时间滚轮 |
|---|---|
| ![输入页](docs/screenshots/01-input.png) | ![日期滚轮](docs/screenshots/02-wheel-picker.png) |

| 四柱排盘（十神 · 藏干 · 纳音 · 五行） | 大运流年 · AI 干支文化讲解（SSE 流式） |
|---|---|
| ![四柱排盘](docs/screenshots/03-result-pillars.png) | ![AI 文化讲解](docs/screenshots/04-ai-explain.png) |

<p align="center">
  <img src="docs/screenshots/05-city-picker.png" width="420" alt="全国 345 城市搜索"><br/>
  <sub>全国 345 个地级行政区城市搜索（示例：河池 108.09°E）</sub>
</p>

---

## ✨ 功能特性

- **历法计算（纯天文硬算）**
  - 公历 / 农历双向输入（农历含闰月自动识别、大小月自动收敛）
  - 四柱干支：立春精确时刻定年柱、十二节定月柱（五虎遁）、五鼠遁定时柱
  - 晚子时流派：23:00 起日柱进位（与主流排盘软件一致）
  - 真太阳时：经度修正 + 均时差（NOAA/Spencer 公式），支持全国 345 个地级行政区城市搜索
  - 十神（天干 + 藏干）、纳音、旬空、胎元、生肖、五行加权统计
  - 大运（阳男阴女顺排 / 阴男阳女逆排，起运数 = 距节天数 ÷ 3）与 81 年流年（地支相冲标记）
- **AI 干支文化讲解**（可配置 DeepSeek 或任意 OpenAI 兼容接口，SSE 流式输出）
  - 只讲名词含义与文化背景，prompt 层硬性禁止预测与断言类输出
  - 未配置 API Key 自动进入 Mock 模式，前端联调不受影响
- **数据持久化**：每次排盘自动存入 SQLite，历史记录一键复用、删除
- **双端一致**：H5（vite 代理联调）与微信小程序（enableChunked 流式）共用同一套后端
- **工程化**：24 个回归测试锚定公开历法/天文数据；配置外置、AI Key 热重载；一键启停脚本

## 🧮 算法说明

| 层 | 实现 |
|---|---|
| 天文层 | [lunar-go](https://github.com/6tail/lunar-go)（寿星天文历 Go 实现）：公农历互转、节气精确时刻、日柱锚点 |
| 业务层 | 自研：真太阳时（NOAA 均时差）、立春定年、五虎遁/五鼠遁、晚子时进日、十神、大运流年、五行加权、纳音/旬空/胎元 |
| 质量保障 | 回归测试锚定公开万年历/天文数据（如 2024 立春 16:26、2000-01-01 戊午日、2023 闰二月 384 天），含 JSON 输出结构兼容性测试 |

流派约定详见下文[排盘规则](#排盘规则与流派约定)。

## 🏗️ 技术栈

| 端 | 技术 |
|---|---|
| 后端 | Go 1.22+、Gin 风格 net/http 路由、[lunar-go](https://github.com/6tail/lunar-go)、SQLite（modernc.org/sqlite 纯 Go 驱动，无 cgo） |
| 前端 | uni-app（Vue 3 + TypeScript + Vite），一套代码编译 H5 与 mp-weixin |
| AI | DeepSeek（OpenAI 兼容协议，SSE 流式），可替换任意兼容服务 |

## 🚀 快速开始

### 一键启动（推荐）

```bash
git clone <你的仓库地址> bazi && cd bazi
./start.sh    # 自动编译 Go 后端(:8000) + H5 前端(:5173)，浏览器打开 http://localhost:5173
./stop.sh     # 停止服务
```

日志见 `logs/`。后端源码变化后重跑 `./start.sh` 会自动重新编译。

### 手动启动

```bash
# 后端（需要 Go 1.22+）
cd backend-go && go build -o bazi-server . && ./bazi-server -config config.yaml

# 前端（需要 Node.js 18+）
cd frontend && npm install && npm run dev:h5
```

## ⚙️ 配置

配置文件 `backend-go/config.yaml`（可复制为多环境使用）：

```yaml
server:
  port: 8000                # 改后需重启
  cors_origins: ["*"]
ai:
  base_url: "https://api.deepseek.com"   # 任意 OpenAI 兼容接口
  api_key: ""               # 留空 = Mock 模式；填入后即时生效，无需重启
  model: "deepseek-chat"
database:
  path: "bazi.db"           # SQLite 文件，改后需重启
```

- **AI Key 热重载**：修改 `api_key` / `model` 保存即生效（运行时检测文件变更），无需重启服务
- 环境变量覆盖（优先级更高）：`BAZI_SERVER_PORT`、`BAZI_AI_API_KEY`、`BAZI_AI_BASE_URL`、`BAZI_AI_MODEL`、`BAZI_DATABASE_PATH`

## 🗄️ 数据库

SQLite（WAL 模式，纯 Go 驱动零 cgo 依赖），每次排盘自动落库：

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/records?limit=20` | 历史记录列表 |
| GET | `/api/records/{id}` | 取某条记录的原始入参 |
| DELETE | `/api/records/{id}` | 删除单条 |
| DELETE | `/api/records` | 清空全部 |

## 📡 API 一览

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/paipan` | 排盘：公/农历 + 时间 + 性别 + 经度 + 真太阳时开关 |
| POST | `/api/interpret` | AI 文化讲解（SSE 流式），支持直接传 `recordId` |
| GET | `/api/lunar-calendar/{year}` | 农历年月表（闰月、大小月），供农历选择器 |
| GET | `/api/cities?keyword=` | 全国 345 个地级行政区经度表（搜索过滤） |
| GET | `/api/ping` | 健康检查 |

## 📱 微信小程序

```bash
cd frontend
npm run dev:mp-weixin       # 开发构建
npm run build:mp-weixin     # 发布构建
```

1. 微信开发者工具导入 `frontend/dist/dev/mp-weixin`
2. 调试阶段用测试号（touristappid），勾选「不校验合法域名」
3. 正式发布：在 `frontend/src/manifest.json` 填入 AppID，并把 `src/api/index.ts` 中 MP-WEIXIN 的 `BASE_URL` 改为线上 https 域名

## 🧪 测试

```bash
cd backend-go
go test ./...    # 24 个回归测试（算法锚点）+ 服务层集成测试（API/SQLite/SSE 全链路）
```

## 排盘规则与流派约定

| 项目 | 采用规则 |
|---|---|
| 年柱 | 以**立春精确时刻**为界（非正月初一） |
| 月柱 | 以十二**节**（立春/惊蛰/清明…）为界，月干五虎遁 |
| 日柱 | 23:00 起进位为次日（**晚子时进日**） |
| 时柱 | 五鼠遁，时辰按真太阳时划分 |
| 真太阳时 | 北京时间 + 4分钟×(经度−120°) + 均时差；开启后影响全部柱的节气边界判定 |
| 大运 | 阳年男/阴年女顺排，阴年男/阳年女逆排；起运数 = 距最近「节」天数 ÷ 3 |

## ⚖️ 合规定位与免责声明

- 本项目定位为**传统历法文化工具**（微信小程序类目：工具 → 日历/信息查询），排盘数据是纯天文历法计算
- AI 模块仅输出干支名词解释与文化背景，系统提示词硬性禁止预测吉凶、断言命运、人生建议等内容
- 个人主体上架前置：注册小程序 + 微信认证 + ICP 备案；平台对命理类内容管控严格，工具定位也不保证过审
- **本项目仅供传统文化学习与研究，所有输出不构成任何预测、医疗、投资或其他人生建议**

## 📂 目录结构

```
bazi/
├── start.sh / stop.sh        # 一键启动 / 停止
├── backend-go/               # Go 后端
│   ├── main.go               # 入口（-config 指定配置，默认 ./config.yaml）
│   ├── config.yaml           # 外置配置
│   ├── bazi.db               # SQLite（运行时生成）
│   └── internal/
│       ├── bazi/             # 核心算法 + 回归测试
│       ├── config/           # 配置加载 + 热重载
│       ├── store/            # SQLite 存储层
│       ├── ai/               # DeepSeek 流式客户端
│       └── server/           # 路由 / CORS / SSE / 记录接口 + 集成测试
└── frontend/                 # uni-app 前端（H5 + 微信小程序）
    └── src/
        ├── pages/            # 输入页 / 结果页
        ├── components/       # WheelPicker 日期滚轮 / CityPicker 城市搜索
        ├── api/              # 请求封装 + SSE（H5 fetch / 小程序 enableChunked）
        └── utils/            # 状态 / 城市(345城) / 格式化
```

## 📮 联系方式

如有问题或交流需求，欢迎联系：

- **QQ / 微信同号：467643531**

欢迎 Star ⭐ 与 Fork！