神机阁 - AI驱动的智能命理分析平台

一个集成AI智能解读的中华传统命理分析平台，提供八字命理、紫微斗数、易经占卜等专业分析服务，支持多种AI模型深度解读。

✨ 核心功能

🔮 命理分析服务

• 🎯 八字命理分析 - 四柱排盘、五行分析、格局判断、大运流年
• 🌟 紫微斗数分析 - 星盘排布、十二宫位、四化飞星、详细解读
• 🔮 易经占卜分析 - 梅花易数、卦象解读、人生指导

🤖 AI智能解读

• 🧠 多模型支持 - OpenAI GPT、智谱AI、Azure OpenAI、Claude等主流AI模型
• 📝 深度解读 - 将传统命理术语转换为现代语言，提供实用人生指导
• ⚙️ 灵活配置 - 自定义API密钥、模型参数、提示词模板
• 💾 结果缓存 - 自动保存解读结果，避免重复调用节省费用
• 🔄 流式输出 - 支持实时流式显示，提升用户体验

💡 智能特性

• 📊 星曜强度解释 - 旺、得地、平、不得地、陷的详细说明
• 🎨 命宫位置详解 - 五行属性、深层含义、性格影响分析
• 📈 数据可视化 - 五行分布图表、运势趋势分析
• 📱 移动优化 - 完美适配手机端操作和显示

🛠️ 系统功能

• 👤 完整用户系统 - 注册登录、个人资料、分析历史管理
• 📊 历史记录分页 - 智能分页显示，支持大量历史数据浏览
• 📥 多格式导出 - 支持PDF、Markdown、TXT格式导出分析报告
• 📱 响应式设计 - 完美支持桌面端、平板和移动端
• 🎨 中国风UI - 传统文化与现代设计的完美融合
• 🔒 数据安全 - JWT认证、SQLite本地存储、数据持久化保护

🚀 快速开始

🐳 Docker 部署（推荐）

# 使用 Docker Compose 一键启动
git clone https://github.com/patdelphi/suanming.git
cd suanming
cp .env.example .env
# 编辑 .env 文件，设置 JWT_SECRET
docker-compose up -d

# 访问应用
# http://localhost:8000

📦 传统部署

环境要求

• Node.js >= 18.0.0
• npm >= 8.0.0

安装依赖

# 克隆项目
git clone https://github.com/patdelphi/suanming.git
cd suanming

# 安装依赖
npm install

启动开发服务器

# 启动开发服务器（前后端同时启动）
npm run dev

# 或分别启动
npm run server  # 后端服务器 (端口 3001)
npm run dev     # 前端开发服务器 (端口 5173)

配置AI解读功能（可选）

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，添加AI配置
# VITE_AI_API_KEY=your-openai-api-key
# VITE_AI_API_URL=https://api.openai.com/v1/chat/completions
# VITE_AI_MODEL_NAME=gpt-3.5-turbo

访问应用

• 🌐 前端应用: http://localhost:5173
• 🔌 后端API: http://localhost:3001/api
• 🏥 健康检查: http://localhost:3001/api/health

🏗️ 项目架构 (v3.1)

架构特点

• AI集成架构: 完整的AI解读服务集成，支持多种AI模型
• 容器化部署: Docker + Docker Compose 一键部署
• 云原生支持: Koyeb、Railway等云平台部署优化
• 数据持久化: SQLite + 持久化卷，确保数据安全
• 分离关注点: 分析计算与历史记录存储完全分离
• API去重: 防止重复调用的请求去重机制
• 性能优化: useMemo缓存和useEffect依赖优化
• 错误隔离: 历史记录保存失败不影响分析功能
• 安全防护: CSP策略、CORS配置、JWT认证

技术栈

前端技术

• React 18.3.1 + TypeScript 5.6.2
• Vite 6.0.1 (构建工具)
• Tailwind CSS 3.4.16 (中国风主题)
• React Router 6 (路由管理)
• Radix UI (组件库)
• React Hook Form + Zod (表单验证)
• Recharts (数据可视化)
• Lucide React (图标库)
• React Markdown (AI解读渲染)
• Sonner (通知组件)

后端技术

• Node.js + Express 4.18.2
• Better-SQLite3 12.2.0 (数据库)
• JWT + bcryptjs (身份认证)
• Helmet (安全中间件，CSP配置)
• CORS (跨域处理)
• 分层架构设计

AI集成

• OpenAI GPT 系列模型
• 智谱AI (GLM系列)
• Azure OpenAI Service
• Anthropic Claude
• Google Generative AI
• 流式响应支持

部署工具

• Docker + Docker Compose
• Koyeb 云部署配置
• 数据持久化卷
• 健康检查机制

开发工具

• ESLint + TypeScript ESLint (代码检查)
• Concurrently (并发运行)
• Nodemon (开发热重载)
• npm (包管理器)

目录结构

├── src/                    # 前端源码
│   ├── components/         # React组件
│   ├── pages/             # 页面组件
│   ├── lib/               # 工具库
│   ├── contexts/          # React Context
│   └── types/             # TypeScript类型
├── server/                # 后端源码
│   ├── routes/            # API路由
│   ├── services/          # 业务服务
│   ├── middleware/        # 中间件
│   └── database/          # 数据库配置
├── docs/                  # 项目文档
└── public/                # 静态资源

🔄 v3.1 重大更新

🆕 新增功能

1. AI智能解读系统 - 集成多种AI模型，提供深度个性化解读
2. Docker容器化部署 - 一键部署，环境一致性保障
3. 云平台部署支持 - Koyeb等云平台优化配置
4. 数据持久化保护 - 解决部署更新时数据丢失问题
5. 历史记录分页 - 支持大量历史数据的高效浏览
6. CSP安全策略 - 增强Web安全防护

🔧 核心改进

1. 重复历史记录: 一次分析产生多条记录 → 确保每次只产生1条记录
2. 架构耦合: 分析与存储混合 → 完全分离，职责清晰
3. 性能问题: 重复渲染和API调用 → 优化减少60%+重复调用
4. 部署复杂: 手动配置环境 → Docker一键部署
5. 数据丢失: 更新时数据重置 → 持久化卷保护
6. AI集成: 无AI功能 → 完整AI解读系统

版本对比

方面	v1.0 (初版)	v2.0 (重构)	v3.0 (优化)	v3.1 (当前)
分析接口	分析+存储耦合	纯分析计算	AI增强分析	多模型AI解读
历史记录	自动存储	专门接口存储	优化存储	分页+持久化
部署方式	手动部署	手动部署	手动部署	Docker+云部署
数据安全	基础保护	JWT认证	全面容错	持久化+CSP
AI功能	无	无	基础AI	完整AI系统
用户体验	术语晦涩	改进显示	详细解释	AI深度解读

📚 文档

• API文档 - 详细的API接口说明
• 本地部署指南 - 本地化部署和运行说明
• Docker部署指南 - Docker容器化部署完整指南
• Koyeb部署指南 - 云平台部署配置说明
• AI解读使用指南 - AI功能配置和使用教程
• 更新日志 - 版本更新记录

🧪 测试

# 运行前端测试
npm run test

# 运行后端测试
cd server && npm run test

# 运行端到端测试
npm run test:e2e

🚀 部署

🐳 Docker 部署（推荐）

# 使用 Docker Compose
docker-compose up -d

# 或使用 Docker 命令
docker build -t suanming-app .
docker run -d -p 8000:8000 \
  -e JWT_SECRET=your-secret-key \
  -v suanming-data:/app/data \
  suanming-app

☁️ 云平台部署

Koyeb 部署

# 推送到 master 分支，Koyeb 自动部署
git push origin master

其他云平台

• Railway: 支持自动检测和部署
• Render: 支持 Docker 部署
• Heroku: 支持 Node.js 应用部署

📦 传统部署

# 构建前端
npm run build

# 启动生产服务器
npm start

📖 详细指南

• Docker部署指南 - 完整的容器化部署说明
• Koyeb部署指南 - 云平台部署配置
• 本地部署指南 - 传统部署方式

🤝 贡献

我们欢迎所有形式的贡献！请查看 贡献指南 了解如何参与项目开发。

开发流程

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

• 感谢所有贡献者的辛勤工作
• 感谢开源社区提供的优秀工具和库
• 感谢中华传统文化的深厚底蕴

📞 联系我们

• 项目主页: GitHub Repository
• 问题反馈: GitHub Issues
• 在线演示: Koyeb部署版本
• 邮箱: contact@shenjige.com

---

神机阁 - 传承千年智慧，拥抱现代科技 🌟