docs: reorganize documentation and add architecture document

Changes: - Create docs/ directory for centralized documentation - Move DEVELOPMENT_GUIDE.md from root to docs/ - Add comprehensive ARCHITECTURE.md with: - System overview and architecture diagrams (ASCII) - Microservices responsibilities (6 services) - Technology stack details - Data flow diagrams (user conversation, admin evolution) - Production deployment architecture - Kong API routing table - Port mapping reference - Database schema overview (PostgreSQL, Neo4j, MinIO) - Security design notes - Update README.md with documentation index table Documentation structure: docs/ ├── ARCHITECTURE.md - System architecture reference └── DEVELOPMENT_GUIDE.md - Development guide and code examples Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-22 23:05:41 -08:00 · 2026-01-22 23:05:41 -08:00 · 4dbd6f075f
parent e6e69f15ce
commit 4dbd6f075f
3 changed files with 448 additions and 2 deletions
--- a/README.md
+++ b/README.md
@ -138,9 +138,13 @@ WECHAT_APP_ID=xxx

 完整配置请参考 `.env.example`

-## 开发指南
+## 文档

-详细的开发指导请参考 [DEVELOPMENT_GUIDE.md](./DEVELOPMENT_GUIDE.md)
+| 文档 | 说明 |
+|------|------|
+| [架构文档](./docs/ARCHITECTURE.md) | 系统整体架构、服务职责、数据流、部署配置 |
+| [开发指南](./docs/DEVELOPMENT_GUIDE.md) | 详细开发指导、代码示例、API 设计 |
+| [MinIO 配置](./infrastructure/minio/README.md) | 对象存储配置说明 |

 ## 开发进度

--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@ -0,0 +1,442 @@
+# iConsulting 系统架构文档
+
+## 目录
+
+- [系统概述](#系统概述)
+- [整体架构](#整体架构)
+- [服务架构](#服务架构)
+- [技术栈](#技术栈)
+- [数据流](#数据流)
+- [部署架构](#部署架构)
+- [API 路由](#api-路由)
+- [数据存储](#数据存储)
+
+---
+
+## 系统概述
+
+iConsulting 是一个基于 Claude AI 的香港移民智能咨询系统，采用微服务架构，支持：
+
+- **智能对话**: 基于 Claude API 的多模态 AI 对话
+- **知识增强**: RAG + Neo4j 知识图谱
+- **自我进化**: 从对话中学习经验，持续优化
+- **文件处理**: 支持图片、PDF 等文件上传与 AI 分析
+
+---
+
+## 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              客户端层                                        │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   ┌─────────────────────┐           ┌─────────────────────┐                │
+│   │    Web Client       │           │   Admin Client      │                │
+│   │  (React + TS)       │           │  (React + Ant)      │                │
+│   │                     │           │                     │                │
+│   │  • 用户咨询界面     │           │  • 知识库管理       │                │
+│   │  • 多模态文件上传   │           │  • 经验库管理       │                │
+│   │  • 实时流式对话     │           │  • 系统配置         │                │
+│   └─────────────────────┘           └─────────────────────┘                │
+│            │                                   │                            │
+└────────────┼───────────────────────────────────┼────────────────────────────┘
+             │                                   │
+             ▼                                   ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         Nginx 反向代理 (SSL 终止)                            │
+│                                                                             │
+│   /           → Web Client (SPA)                                           │
+│   /admin      → Admin Client (SPA)                                         │
+│   /api/v1/*   → Kong API Gateway                                           │
+│   /ws/*       → WebSocket (Conversation Service)                           │
+│   /storage/*  → MinIO (文件存储)                                            │
+└─────────────────────────────────────────────────────────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        Kong API Gateway (DB-less)                           │
+│                                                                             │
+│   • 请求路由           • CORS 处理          • 请求限流                      │
+│   • 超时控制           • 负载均衡                                           │
+└─────────────────────────────────────────────────────────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              微服务层                                        │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
+│  │ User Service │  │ Conversation │  │  Knowledge   │  │   Payment    │    │
+│  │    :3001     │  │   Service    │  │   Service    │  │   Service    │    │
+│  │              │  │    :3004     │  │    :3003     │  │    :3002     │    │
+│  │ • 匿名认证   │  │ • Claude AI  │  │ • RAG 检索   │  │ • 支付宝    │    │
+│  │ • JWT 管理   │  │ • 流式响应   │  │ • 向量搜索   │  │ • 微信支付  │    │
+│  │ • 用户信息   │  │ • WebSocket  │  │ • Neo4j 图谱 │  │ • Stripe    │    │
+│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘    │
+│                                                                             │
+│  ┌──────────────┐  ┌──────────────┐                                        │
+│  │  Evolution   │  │    File      │                                        │
+│  │   Service    │  │   Service    │                                        │
+│  │    :3005     │  │    :3006     │                                        │
+│  │              │  │              │                                        │
+│  │ • 经验提取   │  │ • 文件上传   │                                        │
+│  │ • 管理员认证 │  │ • MinIO 存储 │                                        │
+│  │ • 自我进化   │  │ • 缩略图生成 │                                        │
+│  └──────────────┘  └──────────────┘                                        │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              基础设施层                                      │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
+│  │  PostgreSQL  │  │    Redis     │  │    Neo4j     │  │    MinIO     │    │
+│  │    :5432     │  │    :6379     │  │ :7474/:7687  │  │ :9000/:9001  │    │
+│  │              │  │              │  │              │  │              │    │
+│  │ • 用户数据   │  │ • 会话缓存   │  │ • 知识图谱   │  │ • 文件存储   │    │
+│  │ • 对话历史   │  │ • 限流计数   │  │ • 用户记忆   │  │ • 图片/PDF   │    │
+│  │ • 订单数据   │  │ • 分布式锁   │  │ • 关系网络   │  │ • 缩略图     │    │
+│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘    │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              外部服务                                        │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                      │
+│  │  Claude API  │  │  OpenAI API  │  │  支付网关    │                      │
+│  │  (Anthropic) │  │  (Embedding) │  │              │                      │
+│  │              │  │              │  │ • 支付宝     │                      │
+│  │ • 对话生成   │  │ • 向量化     │  │ • 微信支付   │                      │
+│  │ • 多模态理解 │  │              │  │ • Stripe     │                      │
+│  └──────────────┘  └──────────────┘  └──────────────┘                      │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 服务架构
+
+### 服务职责
+
+| 服务 | 端口 | 职责 |
+|------|------|------|
+| **user-service** | 3001 | 用户认证（匿名/手机）、JWT 管理、用户信息 |
+| **payment-service** | 3002 | 订单管理、支付宝/微信/Stripe 支付集成 |
+| **knowledge-service** | 3003 | RAG 检索、向量搜索、Neo4j 知识图谱 |
+| **conversation-service** | 3004 | Claude AI 对话、WebSocket 实时通信、流式响应 |
+| **evolution-service** | 3005 | 管理员认证、经验提取、系统进化、经验库管理 |
+| **file-service** | 3006 | 文件上传/下载、MinIO 存储、缩略图生成 |
+
+### 服务依赖关系
+
+```
+conversation-service
+    ├── knowledge-service (RAG 检索)
+    ├── file-service (多模态文件)
+    ├── PostgreSQL (对话存储)
+    ├── Redis (会话缓存)
+    └── Claude API (AI 生成)
+
+evolution-service
+    ├── conversation-service (经验来源)
+    ├── PostgreSQL (经验存储)
+    └── Claude API (经验分析)
+
+knowledge-service
+    ├── PostgreSQL (文档存储)
+    ├── Neo4j (知识图谱)
+    └── OpenAI API (向量化)
+
+file-service
+    ├── MinIO (对象存储)
+    └── PostgreSQL (文件元数据)
+```
+
+---
+
+## 技术栈
+
+### 前端
+
+| 技术 | 用途 |
+|------|------|
+| React 18 | UI 框架 |
+| TypeScript | 类型安全 |
+| TailwindCSS | 样式 |
+| Zustand | 状态管理 |
+| React Query | 数据获取 |
+| Socket.IO Client | WebSocket |
+| Ant Design | Admin UI 组件 |
+
+### 后端
+
+| 技术 | 用途 |
+|------|------|
+| NestJS | 微服务框架 |
+| TypeORM | ORM |
+| Socket.IO | WebSocket |
+| Anthropic SDK | Claude API |
+| bcrypt | 密码加密 |
+| JWT | 认证令牌 |
+
+### 基础设施
+
+| 技术 | 用途 |
+|------|------|
+| PostgreSQL 15 | 主数据库 |
+| Redis 7 | 缓存 |
+| Neo4j 5 | 图数据库 |
+| MinIO | 对象存储 |
+| Kong | API 网关 |
+| Nginx | 反向代理 |
+| Docker Compose | 容器编排 |
+
+---
+
+## 数据流
+
+### 用户对话流程
+
+```
+用户输入 (文本/图片/文件)
+         │
+         ▼
+┌─────────────────┐
+│   Web Client    │
+│  (上传文件到    │
+│   file-service) │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│     Nginx       │
+│  (SSL + 路由)   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   Kong Gateway  │
+│  (认证 + 限流)  │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐         ┌─────────────────┐
+│  Conversation   │────────▶│   Knowledge     │
+│    Service      │  RAG    │    Service      │
+│                 │  检索   │                 │
+└────────┬────────┘         └─────────────────┘
+         │
+         │ 构建上下文 (系统提示 + RAG 结果 + 历史消息 + 文件)
+         ▼
+┌─────────────────┐
+│   Claude API    │
+│  (流式响应)     │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   WebSocket     │
+│  (实时推送)     │
+└────────┬────────┘
+         │
+         ▼
+      用户看到回复
+```
+
+### 管理员进化流程
+
+```
+管理员指令
+    │
+    ▼
+┌─────────────────┐
+│  Admin Client   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   Evolution     │
+│    Service      │
+│                 │
+│ 1. 分析历史对话 │
+│ 2. 提取经验     │
+│ 3. 更新知识库   │
+│ 4. 调整系统提示 │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   Knowledge     │
+│    Service      │
+│  (更新 RAG)     │
+└─────────────────┘
+```
+
+---
+
+## 部署架构
+
+### 生产环境
+
+```
+                         ┌───────────────────┐
+                         │   用户请求        │
+                         │ iconsulting.      │
+                         │ szaiai.com        │
+                         └─────────┬─────────┘
+                                   │
+                         ┌─────────▼─────────┐
+                         │   系统 Nginx      │
+                         │   (SSL 终止)      │
+                         │   :443 → :8080    │
+                         └─────────┬─────────┘
+                                   │
+              ┌────────────────────┼────────────────────┐
+              │                    │                    │
+    ┌─────────▼─────────┐ ┌───────▼───────┐ ┌─────────▼─────────┐
+    │   Docker Nginx    │ │     Kong      │ │   MinIO Console   │
+    │      :8080        │ │    :8000      │ │      :9001        │
+    └───────────────────┘ └───────────────┘ └───────────────────┘
+```
+
+### 网络配置
+
+- **对外网卡**: 14.215.128.96 (用户访问)
+- **出口网卡**: 154.84.135.121 (Claude API 调用，绕过国内限制)
+- **Docker 网络**: 172.20.0.0/16 (内部服务通信)
+
+### 端口映射
+
+| 服务 | 容器端口 | 宿主机端口 |
+|------|----------|------------|
+| PostgreSQL | 5432 | 5432 |
+| Redis | 6379 | 6379 |
+| Neo4j HTTP | 7474 | 7474 |
+| Neo4j Bolt | 7687 | 7687 |
+| MinIO API | 9000 | 9000 |
+| MinIO Console | 9001 | 9001 |
+| Kong Proxy | 8000 | 8000 |
+| Kong Admin | 8001 | 8001 |
+| Nginx | 80 | 8080 |
+| user-service | 3001 | 3001 |
+| payment-service | 3002 | 3002 |
+| knowledge-service | 3003 | 3003 |
+| conversation-service | 3004 | 3004 |
+| evolution-service | 3005 | 3005 |
+| file-service | 3006 | 3006 |
+
+---
+
+## API 路由
+
+### Kong 路由配置
+
+| 路径前缀 | 目标服务 | 说明 |
+|----------|----------|------|
+| `/api/v1/users`, `/api/v1/auth` | user-service:3001 | 用户认证 |
+| `/api/v1/payments`, `/api/v1/orders` | payment-service:3002 | 支付订单 |
+| `/api/v1/knowledge`, `/api/v1/memory` | knowledge-service:3003 | 知识库 |
+| `/api/v1/conversations`, `/api/v1/messages` | conversation-service:3004 | 对话 |
+| `/api/v1/evolution`, `/api/v1/admin` | evolution-service:3005 | 进化/管理 |
+| `/api/v1/files` | file-service:3006 | 文件 |
+
+### 前端路由
+
+| 路径 | 说明 |
+|------|------|
+| `/` | 用户咨询界面 (web-client) |
+| `/admin/` | 管理后台 (admin-client) |
+| `/admin/login` | 管理员登录 |
+| `/admin/knowledge` | 知识库管理 |
+| `/admin/experience` | 经验库管理 |
+
+---
+
+## 数据存储
+
+### PostgreSQL 主要表
+
+| 表名 | 说明 |
+|------|------|
+| `users` | 用户信息（匿名/注册） |
+| `conversations` | 对话会话 |
+| `messages` | 对话消息 |
+| `files` | 文件元数据 |
+| `orders` | 支付订单 |
+| `admins` | 管理员账户 |
+| `experiences` | 提取的经验 |
+| `knowledge_documents` | 知识文档 |
+| `system_configs` | 系统配置 |
+
+### Neo4j 图模型
+
+```cypher
+(:User)-[:HAS_MEMORY]->(:Memory)
+(:User)-[:ASKED_ABOUT]->(:Knowledge)
+(:Knowledge)-[:RELATED_TO]->(:Knowledge)
+(:Experience)-[:DERIVED_FROM]->(:Conversation)
+```
+
+### MinIO Bucket 结构
+
+```
+iconsulting/
+├── uploads/           # 用户上传
+│   ├── images/
+│   ├── documents/
+│   └── temp/
+├── processed/         # 处理后文件
+│   ├── thumbnails/
+│   └── extracted/
+└── exports/           # 导出文件
+```
+
+---
+
+## 安全设计
+
+### 认证机制
+
+1. **用户认证**: 匿名 fingerprint → JWT
+2. **管理员认证**: 用户名密码 → bcrypt 验证 → JWT
+3. **API 认证**: JWT Bearer Token
+
+### 安全措施
+
+- HTTPS (SSL/TLS)
+- CORS 白名单
+- 请求限流
+- SQL 注入防护 (TypeORM 参数化)
+- XSS 防护 (React 自动转义)
+- 文件类型验证
+- MinIO 预签名 URL (临时访问)
+
+---
+
+## 扩展性设计
+
+### 水平扩展
+
+- 微服务无状态设计，支持多实例部署
+- Redis 分布式会话
+- Kong 负载均衡
+
+### 垂直扩展
+
+- 数据库读写分离（预留）
+- 消息队列（Kafka 已预留）
+- 缓存分层
+
+---
+
+## 相关文档
+
+- [开发指南](./DEVELOPMENT_GUIDE.md) - 详细的开发文档和代码示例
+- [MinIO 配置](../infrastructure/minio/README.md) - 对象存储配置说明
--- a/docs/DEVELOPMENT_GUIDE.md
+++ b/docs/DEVELOPMENT_GUIDE.md