神机阁 - AI命理分析平台

一个纯AI生成的中华传统命理分析平台，提供八字命理、紫微斗数、易经占卜等专业分析服务。

✨ 核心功能

🔮 命理分析服务

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

💡 智能特性

• 🧠 AI增强分析 - 个性化理财建议、事业发展指导、现代职业建议
• 📊 星曜强度解释 - 旺、得地、平、不得地、陷的详细说明
• 🎨 命宫位置详解 - 五行属性、深层含义、性格影响分析

🛠️ 系统功能

• 👤 完整用户系统 - 注册登录、个人资料、分析历史
• 📱 响应式设计 - 完美支持桌面端、平板和移动端
• 🎨 中国风UI - 传统文化与现代设计的完美融合
• 🔒 数据安全 - JWT认证、SQLite本地存储、隐私保护

🚀 快速开始

环境要求

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

安装依赖

# 克隆项目
git clone https://github.com/your-repo/ai-numerology-refactored.git
cd ai-numerology-refactored

# 安装前端依赖
npm install

# 安装后端依赖
cd server && npm install && cd ..

启动开发服务器

# 启动后端服务器 (端口 3001)
npm run server

# 启动前端开发服务器 (端口 5173)
npm run dev

访问应用

• 前端应用: http://localhost:5173
• 后端API: http://localhost:3001/api

🏗️ 项目架构 (v3.0)

架构特点

• 分离关注点: 分析计算与历史记录存储完全分离
• API去重: 防止重复调用的请求去重机制
• 性能优化: useMemo缓存和useEffect依赖优化
• 错误隔离: 历史记录保存失败不影响分析功能
• 智能增强: AI驱动的个性化分析和现代化建议
• 用户体验: 详细的星曜强度解释和命宫位置分析

技术栈

前端技术

• 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 (图标库)

后端技术

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

开发工具

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

目录结构

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

🔄 v3.0 重构亮点

解决的核心问题

1. 重复历史记录: 一次分析产生多条记录 → 确保每次只产生1条记录
2. 架构耦合: 分析与存储混合 → 完全分离，职责清晰
3. 性能问题: 重复渲染和API调用 → 优化减少60%+重复调用
4. 时间显示: 时区问题 → 统一ISO时间戳和本地化显示
5. 分析深度: 基础解释不够详细 → AI增强的个性化分析
6. 用户体验: 术语难懂 → 详细的星曜强度和命宫位置解释

版本对比

方面	v1.0 (初版)	v2.0 (重构)	v3.0 (当前)
分析接口	分析+存储耦合	纯分析计算	AI增强分析
历史记录	自动存储	专门接口存储	优化存储
重复记录	3-5条/次	1条/次	1条/次
API调用	频繁重复	去重优化	智能缓存
错误处理	耦合失败	隔离容错	全面容错
分析深度	基础解释	标准分析	AI个性化
用户体验	术语晦涩	改进显示	详细解释

📚 文档

• API文档 - 详细的API接口说明
• 本地部署指南 - 本地化部署和运行说明
• 更新日志 - 版本更新记录

🧪 测试

# 运行前端测试
npm run test

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

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

🚀 部署

生产环境部署

# 构建前端
npm run build

# 启动生产服务器
npm run start

详细部署说明请参考 本地部署指南。

🤝 贡献

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

开发流程

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
• 邮箱: contact@shenjige.com

---

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