From 768befec028c59c88b45c50895df2357bf0d332b Mon Sep 17 00:00:00 2001 From: patdelphi Date: Fri, 22 Aug 2025 17:20:39 +0800 Subject: [PATCH] docs: Update project documentation to v3.1.0 - Updated README.md with latest features and deployment options - Added AI interpretation system documentation - Updated Docker and cloud deployment instructions - Added comprehensive CHANGELOG.md for v3.1.0 - Updated GitHub repository links and contact information - Reflected all new features: AI integration, Docker support, pagination, etc. - Enhanced quick start guide with multiple deployment methods --- CHANGELOG.md | 64 +++++++++++++++++ README.md | 193 ++++++++++++++++++++++++++++++++++++++------------- 2 files changed, 210 insertions(+), 47 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index efb1e72..4bd2828 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,70 @@ 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)， 并且本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 +## [3.1.0] - 2025-08-22 + +### 🆕 新增功能 +- **AI智能解读系统**: 完整的AI解读功能集成 + - 支持多种AI模型：OpenAI GPT、智谱AI、Azure OpenAI、Claude、Google AI + - 灵活的配置系统：自定义API密钥、模型参数、提示词模板 + - 流式响应支持：实时显示AI解读过程 + - 结果缓存机制：避免重复调用，节省API费用 + - 专业提示词模板：针对八字、紫微、易经的专门优化 +- **Docker容器化部署**: 完整的容器化解决方案 + - Docker + Docker Compose 一键部署 + - 优化的镜像构建流程 + - 数据持久化卷配置 + - 健康检查机制 +- **云平台部署支持**: 多种云平台部署优化 + - Koyeb 云平台专门配置 + - 自动部署流程 + - 环境变量管理 + - CSP安全策略配置 +- **历史记录分页**: 高效的历史数据管理 + - 每页10条记录的智能分页 + - 页码导航和快速跳转 + - 记录总数和分页信息显示 + - 移动端优化的分页控件 + +### 🔧 核心改进 +- **数据持久化保护**: 解决部署更新时数据丢失问题 + - 智能数据库初始化：只在必要时创建数据 + - 生产环境数据保护：跳过示例数据创建 + - 持久化卷配置：确保数据在容器重启后保留 +- **安全性增强**: 全面的Web安全防护 + - CSP内容安全策略：允许AI API调用 + - CORS跨域配置：支持多域名部署 + - JWT认证优化：更安全的用户认证 +- **性能优化**: 多方面性能提升 + - API调用去重：减少重复请求 + - 前端缓存优化：提升页面响应速度 + - 数据库查询优化：更高效的数据访问 +- **用户体验提升**: 全面的界面和交互优化 + - AI解读界面：美观的Markdown渲染 + - 移动端适配：完美的响应式设计 + - 加载状态优化：更好的用户反馈 + - 错误处理改进：友好的错误提示 + +### 🐛 问题修复 +- **TypeScript编译错误**: 修复ChineseButton组件variant类型问题 +- **数据库连接问题**: 修复better-sqlite3 API调用方式 +- **CSP策略错误**: 修复AI API调用被阻止的问题 +- **分页显示问题**: 修复历史记录只能显示20条的限制 +- **容器启动问题**: 优化Docker启动流程 + +### 📚 文档更新 +- **Docker部署指南**: 完整的容器化部署文档 +- **Koyeb部署指南**: 云平台部署配置说明 +- **AI解读使用指南**: AI功能配置和使用教程 +- **README更新**: 反映最新功能和部署方式 +- **API文档完善**: 更详细的接口说明 + +### 🔄 技术栈更新 +- **前端依赖**: 添加React Markdown、Sonner等新组件 +- **后端优化**: 改进数据库操作和API响应 +- **部署工具**: 集成Docker、Koyeb等部署方案 +- **开发工具**: 优化开发和构建流程 + ## [3.0.0] - 2025-08-20 ### 新增 diff --git a/README.md b/README.md index e622e79..34db7df 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,14 @@ -# 神机阁 - AI命理分析平台 +# 神机阁 - AI驱动的智能命理分析平台 -[![Version](https://img.shields.io/badge/version-3.0.0-blue.svg)](https://github.com/your-repo/shenjige-numerology) +[![Version](https://img.shields.io/badge/version-3.1.0-blue.svg)](https://github.com/patdelphi/suanming) [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/) [![React](https://img.shields.io/badge/react-18.3.1-blue.svg)](https://reactjs.org/) [![TypeScript](https://img.shields.io/badge/typescript-5.6.2-blue.svg)](https://www.typescriptlang.org/) -[![Vite](https://img.shields.io/badge/vite-6.0.1-646CFF.svg)](https://vitejs.dev/) +[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://www.docker.com/) +[![Koyeb](https://img.shields.io/badge/deploy-koyeb-green.svg)](https://www.koyeb.com/) -一个纯AI生成的中华传统命理分析平台，提供八字命理、紫微斗数、易经占卜等专业分析服务。 +一个集成AI智能解读的中华传统命理分析平台，提供八字命理、紫微斗数、易经占卜等专业分析服务，支持多种AI模型深度解读。 ## ✨ 核心功能 @@ -16,63 +17,102 @@ - 🌟 **紫微斗数分析** - 星盘排布、十二宫位、四化飞星、详细解读 - 🔮 **易经占卜分析** - 梅花易数、卦象解读、人生指导 +### 🤖 AI智能解读 +- 🧠 **多模型支持** - OpenAI GPT、智谱AI、Azure OpenAI、Claude等主流AI模型 +- 📝 **深度解读** - 将传统命理术语转换为现代语言，提供实用人生指导 +- ⚙️ **灵活配置** - 自定义API密钥、模型参数、提示词模板 +- 💾 **结果缓存** - 自动保存解读结果，避免重复调用节省费用 +- 🔄 **流式输出** - 支持实时流式显示，提升用户体验 + ### 💡 智能特性 -- 🧠 **AI增强分析** - 个性化理财建议、事业发展指导、现代职业建议 - 📊 **星曜强度解释** - 旺、得地、平、不得地、陷的详细说明 - 🎨 **命宫位置详解** - 五行属性、深层含义、性格影响分析 +- 📈 **数据可视化** - 五行分布图表、运势趋势分析 +- 📱 **移动优化** - 完美适配手机端操作和显示 ### 🛠️ 系统功能 -- 👤 **完整用户系统** - 注册登录、个人资料、分析历史 +- 👤 **完整用户系统** - 注册登录、个人资料、分析历史管理 +- 📊 **历史记录分页** - 智能分页显示，支持大量历史数据浏览 +- 📥 **多格式导出** - 支持PDF、Markdown、TXT格式导出分析报告 - 📱 **响应式设计** - 完美支持桌面端、平板和移动端 - 🎨 **中国风UI** - 传统文化与现代设计的完美融合 -- 🔒 **数据安全** - JWT认证、SQLite本地存储、隐私保护 +- 🔒 **数据安全** - JWT认证、SQLite本地存储、数据持久化保护 ## 🚀 快速开始 -### 环境要求 +### 🐳 Docker 部署（推荐） +```bash +# 使用 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 -### 安装依赖 +#### 安装依赖 ```bash # 克隆项目 -git clone https://github.com/your-repo/ai-numerology-refactored.git -cd ai-numerology-refactored +git clone https://github.com/patdelphi/suanming.git +cd suanming -# 安装前端依赖 +# 安装依赖 npm install - -# 安装后端依赖 -cd server && npm install && cd .. ``` -### 启动开发服务器 +#### 启动开发服务器 ```bash -# 启动后端服务器 (端口 3001) -npm run server - -# 启动前端开发服务器 (端口 5173) +# 启动开发服务器（前后端同时启动） npm run dev + +# 或分别启动 +npm run server # 后端服务器 (端口 3001) +npm run dev # 前端开发服务器 (端口 5173) ``` -### 访问应用 +#### 配置AI解读功能（可选） -- 前端应用: http://localhost:5173 -- 后端API: http://localhost:3001/api +```bash +# 复制环境变量模板 +cp .env.example .env -## 🏗️ 项目架构 (v3.0) +# 编辑 .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依赖优化 - **错误隔离**: 历史记录保存失败不影响分析功能 -- **智能增强**: AI驱动的个性化分析和现代化建议 -- **用户体验**: 详细的星曜强度解释和命宫位置分析 +- **安全防护**: CSP策略、CORS配置、JWT认证 ### 技术栈 @@ -85,20 +125,36 @@ npm run dev - 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 (安全中间件) +- 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 (开发热重载) -- PNPM 9.0.0 (包管理器) +- npm (包管理器) ### 目录结构 @@ -118,33 +174,44 @@ npm run dev └── public/ # 静态资源 ``` -## 🔄 v3.0 重构亮点 +## 🔄 v3.1 重大更新 -### 解决的核心问题 +### 🆕 新增功能 + +1. **AI智能解读系统** - 集成多种AI模型，提供深度个性化解读 +2. **Docker容器化部署** - 一键部署，环境一致性保障 +3. **云平台部署支持** - Koyeb等云平台优化配置 +4. **数据持久化保护** - 解决部署更新时数据丢失问题 +5. **历史记录分页** - 支持大量历史数据的高效浏览 +6. **CSP安全策略** - 增强Web安全防护 + +### 🔧 核心改进 1. **重复历史记录**: 一次分析产生多条记录 → 确保每次只产生1条记录 2. **架构耦合**: 分析与存储混合 → 完全分离，职责清晰 3. **性能问题**: 重复渲染和API调用 → 优化减少60%+重复调用 -4. **时间显示**: 时区问题 → 统一ISO时间戳和本地化显示 -5. **分析深度**: 基础解释不够详细 → AI增强的个性化分析 -6. **用户体验**: 术语难懂 → 详细的星曜强度和命宫位置解释 +4. **部署复杂**: 手动配置环境 → Docker一键部署 +5. **数据丢失**: 更新时数据重置 → 持久化卷保护 +6. **AI集成**: 无AI功能 → 完整AI解读系统 ### 版本对比 -| 方面 | v1.0 (初版) | v2.0 (重构) | v3.0 (当前) | -|------|-------------|-------------|-------------| -| 分析接口 | 分析+存储耦合 | 纯分析计算 | AI增强分析 | -| 历史记录 | 自动存储 | 专门接口存储 | 优化存储 | -| 重复记录 | 3-5条/次 | 1条/次 | 1条/次 | -| API调用 | 频繁重复 | 去重优化 | 智能缓存 | -| 错误处理 | 耦合失败 | 隔离容错 | 全面容错 | -| 分析深度 | 基础解释 | 标准分析 | AI个性化 | -| 用户体验 | 术语晦涩 | 改进显示 | 详细解释 | +| 方面 | v1.0 (初版) | v2.0 (重构) | v3.0 (优化) | v3.1 (当前) | +|------|-------------|-------------|-------------|-------------| +| 分析接口 | 分析+存储耦合 | 纯分析计算 | AI增强分析 | 多模型AI解读 | +| 历史记录 | 自动存储 | 专门接口存储 | 优化存储 | 分页+持久化 | +| 部署方式 | 手动部署 | 手动部署 | 手动部署 | Docker+云部署 | +| 数据安全 | 基础保护 | JWT认证 | 全面容错 | 持久化+CSP | +| AI功能 | 无 | 无 | 基础AI | 完整AI系统 | +| 用户体验 | 术语晦涩 | 改进显示 | 详细解释 | AI深度解读 | ## 📚 文档 - [API文档](docs/API.md) - 详细的API接口说明 - [本地部署指南](docs/LOCAL_DEPLOYMENT.md) - 本地化部署和运行说明 +- [Docker部署指南](DOCKER_DEPLOYMENT.md) - Docker容器化部署完整指南 +- [Koyeb部署指南](KOYEB_DEPLOYMENT.md) - 云平台部署配置说明 +- [AI解读使用指南](AI_INTERPRETATION_GUIDE.md) - AI功能配置和使用教程 - [更新日志](CHANGELOG.md) - 版本更新记录 ## 🧪 测试 @@ -162,17 +229,48 @@ npm run test:e2e ## 🚀 部署 -### 生产环境部署 +### 🐳 Docker 部署（推荐） + +```bash +# 使用 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 部署** +```bash +# 推送到 master 分支，Koyeb 自动部署 +git push origin master +``` + +**其他云平台** +- Railway: 支持自动检测和部署 +- Render: 支持 Docker 部署 +- Heroku: 支持 Node.js 应用部署 + +### 📦 传统部署 ```bash # 构建前端 npm run build # 启动生产服务器 -npm run start +npm start ``` -详细部署说明请参考 [本地部署指南](docs/LOCAL_DEPLOYMENT.md)。 +### 📖 详细指南 + +- [Docker部署指南](DOCKER_DEPLOYMENT.md) - 完整的容器化部署说明 +- [Koyeb部署指南](KOYEB_DEPLOYMENT.md) - 云平台部署配置 +- [本地部署指南](docs/LOCAL_DEPLOYMENT.md) - 传统部署方式 ## 🤝 贡献 @@ -198,8 +296,9 @@ npm run start ## 📞 联系我们 -- 项目主页: [GitHub Repository](https://github.com/your-repo/shenjige-numerology) -- 问题反馈: [GitHub Issues](https://github.com/your-repo/shenjige-numerology/issues) +- 项目主页: [GitHub Repository](https://github.com/patdelphi/suanming) +- 问题反馈: [GitHub Issues](https://github.com/patdelphi/suanming/issues) +- 在线演示: [Koyeb部署版本](https://suanming-app-patdelphi.koyeb.app) - 邮箱: contact@shenjige.com ---