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

@@ -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
 
 ### 新增

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
+git clone https://github.com/patdelphi/suanming.git
-cd ai-numerology-refactored
+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
+```bash
-- 后端API: http://localhost:3001/api
+# 复制环境变量模板
+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时间戳和本地化显示
+4. **部署复杂**: 手动配置环境 → Docker一键部署
-5. **分析深度**: 基础解释不够详细 → AI增强的个性化分析
+5. **数据丢失**: 更新时数据重置 → 持久化卷保护
-6. **用户体验**: 术语难懂 → 详细的星曜强度和命宫位置解释
+6. **AI集成**: 无AI功能 → 完整AI解读系统
 
 ### 版本对比
 
-| 方面 | v1.0 (初版) | v2.0 (重构) | v3.0 (当前) |
+| 方面 | v1.0 (初版) | v2.0 (重构) | v3.0 (优化) | v3.1 (当前) |
-|------|-------------|-------------|-------------|
+|------|-------------|-------------|-------------|-------------|
-| 分析接口 | 分析+存储耦合 | 纯分析计算 | AI增强分析 |
+| 分析接口 | 分析+存储耦合 | 纯分析计算 | AI增强分析 | 多模型AI解读 |
-| 历史记录 | 自动存储 | 专门接口存储 | 优化存储 |
+| 历史记录 | 自动存储 | 专门接口存储 | 优化存储 | 分页+持久化 |
-| 重复记录 | 3-5条/次 | 1条/次 | 1条/次 |
+| 部署方式 | 手动部署 | 手动部署 | 手动部署 | Docker+云部署 |
-| API调用 | 频繁重复 | 去重优化 | 智能缓存 |
+| 数据安全 | 基础保护 | JWT认证 | 全面容错 | 持久化+CSP |
-| 错误处理 | 耦合失败 | 隔离容错 | 全面容错 |
+| AI功能 | 无 | 无 | 基础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 Repository](https://github.com/patdelphi/suanming)
-- 问题反馈: [GitHub Issues](https://github.com/your-repo/shenjige-numerology/issues)
+- 问题反馈: [GitHub Issues](https://github.com/patdelphi/suanming/issues)
+- 在线演示: [Koyeb部署版本](https://suanming-app-patdelphi.koyeb.app)
 - 邮箱: contact@shenjige.com
 
 ---