玄空数术工具集

玄空数术传统文化工具集，包含六爻起卦和择日万年历两个核心应用。

当前工程策略是“React 负责体验，静态 HTML 负责 SEO”：页面先输出可被搜索引擎直接读取的正文、标题、描述和结构化数据，再由 React 接管交互体验。

📁 项目结构

├── liuyao_qigua/         # 六爻起卦应用源码
│   ├── AppPC.tsx         # PC 端主组件
│   ├── AppMobile.tsx     # 移动端主组件
│   ├── ConfigPage.tsx    # 配置页面
│   ├── HistoryPage.tsx   # 历史记录页面
│   ├── ResultPage.tsx    # 结果展示页面
│   └── logic.ts          # 六爻推算逻辑
│
├── Calendar_zeri/        # 择日万年历应用源码
│   ├── CalendarView.tsx  # 日历视图
│   ├── IntentionsView.tsx# 意向查询
│   ├── RelationshipsView.tsx # 关系分析
│   └── metaphysics_config.ts # 玄学配置
│
├── server/               # 后端 API
│   └── api.ts            # Express API 服务（端口 3001）
│
├── scripts/              # 工具脚本
│   └── db.ts             # 数据库连接模块
│
├── prisma/               # 数据库配置
│   ├── schema.prisma     # 数据模型定义
│   └── dev.db            # SQLite 数据库文件
│
├── dist/                 # 前端构建输出
│
├── Dockerfile            # Docker 镜像构建
├── docker-compose.yml    # Docker Compose 配置
├── nginx.conf            # Nginx 配置（监听 9982）
├── supervisord.conf      # 进程管理配置
├── build-push.sh         # 一键构建推送脚本
│
├── index.html            # 导航页入口
├── liuyao-qigua.html     # 六爻起卦（PC）
├── liuyao-paipan.html    # 排盘页面
├── liuyao-history.html   # 历史记录
├── m-liuyao-*.html       # 移动端页面
├── calendar.html         # 择日万年历（PC）
├── m-calendar.html       # 择日万年历（移动端）
│
├── vite.config.ts        # Vite 构建配置
├── tsconfig.json         # TypeScript 配置
└── package.json          # 依赖管理

🚀 快速开始

环境要求

• Node.js 20+
• npm 9+

安装依赖

npm install

本地开发

# 同时启动前端和后端
npm run dev:full

访问地址：

页面	地址
导航页	http://localhost:3000/
六爻起卦	http://localhost:3000/liuyao-qigua.html
择日万年历	http://localhost:3000/calendar.html
API 接口	http://localhost:3001/

前端构建

npm run build       # 只执行 Vite 构建
npm run build:full  # 生产推荐：Vite 构建 + 日历静态页生成

生产部署应使用 npm run build:full。该命令会在 dist/ 中生成：

• /calendar.html：择日万年历入口页
• /calendar/YYYY-MM.html：月份聚合页
• /calendar/YYYY-MM-DD.html：具体日期静态页
• /relationships.html：刑冲合会页面
• /intentions.html：意向解析页面
• /sitemap.xml 和 /robots.txt：搜索引擎入口

🐳 Docker 部署

方式一：一键构建推送

./build-push.sh

该脚本会：

1. 构建前端
2. 构建 Docker 镜像
3. 推送到阿里云镜像仓库

方式二：服务器直接部署

上传 docker-compose.yml 到服务器，然后执行：

mkdir -p data
docker-compose pull
docker-compose up -d

访问：http://服务器IP:9982

📋 命令说明

命令	说明
npm run dev	启动前端开发服务器
npm run api	启动后端 API（自动同步数据库）
npm run dev:full	同时启动前后端
npm run build	构建前端到 dist/
npm run build:static	生成择日静态 HTML
npm run build:full	生产构建入口，包含前端构建和静态页生成
npm run db:studio	打开 Prisma Studio 查看数据库
./build-push.sh	一键构建并推送 Docker 镜像

🔧 技术栈

层级	技术
前端	React 19 + TypeScript + Vite
后端	Node.js + Express
数据库	SQLite + Prisma ORM
部署	Docker + Nginx + Supervisor

📦 镜像仓库

registry.cn-hongkong.aliyuncs.com/mewtwo_zero/xuan:latest

📝 API 接口

接口	方法	说明
/api/auth/register	POST	用户注册
/api/auth/login	POST	用户登录

📱 应用功能

六爻起卦

• 支持数字、时间、卦名、手动等多种起卦方式
• 自动适配移动端和 PC 端
• 支持历史记录保存和导出

择日万年历

• 快速查询吉日
• 分析刑冲合会生旺库
• 支持农历/阳历转换
• 支持日期页和月份页静态化，便于 SEO 收录

🧭 迭代记录

本项目的 SEO 静态化和一键解卦改造记录见：

docs/LIUYAO_SEO_ITERATION.md

后续重要目标、已知 bug、阶段拆解和验收口径会持续写入该文档，方便长周期迭代。