docs：优化项目文档结构和架构说明

- 优化主README.md的文件结构总览，采用总分结构设计
- 大幅改进docs/ARCHITECTURE.md，详细说明业务功能模块化架构
- 新增docs/DOCUMENT_CLEANUP.md记录文档清理过程
- 更新docs/README.md添加新文档的导航链接

本次更新完善了项目文档体系，便于开发者快速理解项目架构

README.md

@@ -124,29 +124,48 @@ pnpm run dev
 
 ### 第二步：熟悉项目架构 🏗️
 
+**📁 项目文件结构总览**
+
 ```
-项目根目录/
-├── src/                    # 源代码目录
-│   ├── business/           # 业务功能模块（按功能组织）
-│   │   ├── auth/           # 🔐 用户认证模块
-│   │   ├── user-mgmt/      # 👥 用户管理模块
-│   │   ├── admin/          # 🛡️ 管理员模块
-│   │   ├── security/       # 🔒 安全模块
-│   │   └── shared/         # 🔗 共享组件
-│   ├── core/               # 核心技术服务
-│   │   ├── db/             # 数据库层（支持MySQL/内存双模式）
-│   │   ├── redis/          # Redis缓存服务（支持真实Redis/文件存储）
-│   │   ├── login_core/     # 登录核心服务
-│   │   ├── admin_core/     # 管理员核心服务
-│   │   └── utils/          # 工具服务（邮件、验证码、日志）
-│   ├── app.module.ts       # 应用主模块
-│   └── main.ts             # 应用入口
-├── client/                 # 前端管理界面
-├── docs/                   # 项目文档
-├── test/                   # 测试文件
-├── redis-data/             # Redis文件存储数据
-├── logs/                   # 日志文件
-└── 配置文件                # .env, package.json, tsconfig.json等
+whale-town-end/                    # 🐋 项目根目录
+├── 📂 src/                        # 源代码目录
+│   ├── 📂 business/               # 🎯 业务功能模块（按功能组织）
+│   │   ├── 📂 auth/               # 🔐 用户认证模块
+│   │   ├── 📂 user-mgmt/          # 👥 用户管理模块  
+│   │   ├── 📂 admin/              # 🛡️ 管理员模块
+│   │   ├── 📂 security/           # 🔒 安全防护模块
+│   │   ├── 📂 zulip/              # 💬 Zulip集成模块
+│   │   └── 📂 shared/             # 🔗 共享业务组件
+│   ├── 📂 core/                   # ⚙️ 核心技术服务
+│   │   ├── 📂 db/                 # 🗄️ 数据库层（MySQL/内存双模式）
+│   │   ├── 📂 redis/              # 🔴 Redis缓存（真实Redis/文件存储）
+│   │   ├── 📂 login_core/         # 🔑 登录核心服务
+│   │   ├── 📂 admin_core/         # 👑 管理员核心服务
+│   │   ├── 📂 zulip/              # 💬 Zulip核心服务
+│   │   └── 📂 utils/              # 🛠️ 工具服务（邮件、验证码、日志）
+│   ├── 📄 app.module.ts           # 🏠 应用主模块
+│   └── 📄 main.ts                 # 🚀 应用入口点
+├── 📂 client/                     # 🎨 前端管理界面
+│   ├── 📂 src/                    # 前端源码
+│   ├── 📂 dist/                   # 前端构建产物
+│   ├── 📄 package.json            # 前端依赖配置
+│   └── 📄 vite.config.ts          # Vite构建配置
+├── 📂 docs/                       # 📚 项目文档中心
+│   ├── 📂 api/                    # 🔌 API接口文档
+│   ├── 📂 development/            # 💻 开发指南
+│   ├── 📂 deployment/             # 🚀 部署文档
+│   ├── 📄 ARCHITECTURE.md         # 🏗️ 架构设计文档
+│   └── 📄 README.md               # 📖 文档导航中心
+├── 📂 test/                       # 🧪 测试文件目录
+├── 📂 config/                     # ⚙️ 配置文件目录
+├── 📂 logs/                       # 📝 日志文件存储
+├── 📂 redis-data/                 # 💾 Redis文件存储数据
+├── 📂 dist/                       # 📦 后端构建产物
+├── 📄 .env                        # 🔧 环境变量配置
+├── 📄 package.json                # 📋 项目依赖配置
+├── 📄 docker-compose.yml          # 🐳 Docker编排配置
+├── 📄 Dockerfile                  # 🐳 Docker镜像配置
+└── 📄 README.md                   # 📖 项目主文档（当前文件）
 ```
 
 **架构特点：**

docs/ARCHITECTURE.md

@@ -1,187 +1,747 @@
-# 🏗️ 项目架构设计
+# 🏗️ Whale Town 项目架构设计
 
-## 整体架构
+> 基于业务功能模块化的现代化后端架构，支持双模式运行，开发测试零依赖，生产部署高性能。
 
-Whale Town 采用分层架构设计，确保代码的可维护性和可扩展性。
+## 📋 目录
+
+- [🎯 架构概述](#-架构概述)
+- [📁 目录结构详解](#-目录结构详解)
+- [🏗️ 分层架构设计](#️-分层架构设计)
+- [🔄 双模式架构](#-双模式架构)
+- [📦 模块依赖关系](#-模块依赖关系)
+- [🚀 扩展指南](#-扩展指南)
+
+---
+
+## 🎯 架构概述
+
+Whale Town 采用**业务功能模块化架构**，将代码按业务功能而非技术组件组织，确保高内聚、低耦合的设计原则。
+
+### 🌟 核心设计理念
+
+- **业务驱动** - 按业务功能组织代码，而非技术分层
+- **双模式支持** - 开发测试零依赖，生产部署高性能
+- **清晰分层** - 业务层 → 核心层 → 数据层，职责明确
+- **模块化设计** - 每个模块独立完整，可单独测试和部署
+- **配置驱动** - 通过环境变量控制运行模式和行为
+
+### 📊 整体架构图
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                          🌐 API接口层                            │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐   │
+│  │   🔗 REST API   │  │  🔌 WebSocket   │  │  📄 Swagger UI  │   │
+│  │   (HTTP接口)    │  │  (实时通信)     │  │  (API文档)      │   │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+                                  ⬇️
+┌─────────────────────────────────────────────────────────────────┐
+│                        🎯 业务功能模块层                         │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐   │
+│  │  🔐 用户认证    │  │  👥 用户管理    │  │  🛡️ 管理员     │   │
+│  │  (auth)         │  │  (user-mgmt)    │  │  (admin)        │   │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘   │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐   │
+│  │  🔒 安全防护    │  │  💬 Zulip集成   │  │  🔗 共享组件    │   │
+│  │  (security)     │  │  (zulip)        │  │  (shared)       │   │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+                                  ⬇️
+┌─────────────────────────────────────────────────────────────────┐
+│                        ⚙️ 核心技术服务层                        │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐   │
+│  │  🔑 登录核心    │  │  👑 管理员核心  │  │  💬 Zulip核心   │   │
+│  │  (login_core)   │  │  (admin_core)   │  │  (zulip)        │   │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘   │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐   │
+│  │  🛠️ 工具服务   │  │  📧 邮件服务    │  │  📝 日志服务    │   │
+│  │  (utils)        │  │  (email)        │  │  (logger)       │   │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+                                  ⬇️
+┌─────────────────────────────────────────────────────────────────┐
+│                        🗄️ 数据存储层                           │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐   │
+│  │  🗃️ 数据库     │  │  🔴 Redis缓存   │  │  📁 文件存储    │   │
+│  │  (MySQL/内存)   │  │  (Redis/文件)   │  │  (logs/data)    │   │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📁 目录结构详解
+
+### 🎯 业务功能模块 (`src/business/`)
+
+> **设计原则**: 按业务功能组织，每个模块包含完整的业务逻辑
+
+```
+src/business/
+├── 📂 auth/                       # 🔐 用户认证模块
+│   ├── 📄 auth.controller.ts      # HTTP接口控制器
+│   ├── 📄 auth.service.ts         # 业务逻辑服务
+│   ├── 📄 auth.module.ts          # 模块定义
+│   ├── 📂 dto/                    # 数据传输对象
+│   │   ├── 📄 login.dto.ts        # 登录请求DTO
+│   │   ├── 📄 register.dto.ts     # 注册请求DTO
+│   │   └── 📄 reset-password.dto.ts # 重置密码DTO
+│   └── 📂 __tests__/              # 单元测试
+│       └── 📄 auth.service.spec.ts
+│
+├── 📂 user-mgmt/                  # 👥 用户管理模块
+│   ├── 📄 user-mgmt.controller.ts # 用户管理接口
+│   ├── 📄 user-mgmt.service.ts    # 用户状态管理逻辑
+│   ├── 📄 user-mgmt.module.ts     # 模块定义
+│   ├── 📂 dto/                    # 数据传输对象
+│   │   ├── 📄 update-status.dto.ts # 状态更新DTO
+│   │   └── 📄 batch-status.dto.ts  # 批量操作DTO
+│   └── 📂 enums/                  # 枚举定义
+│       └── 📄 user-status.enum.ts  # 用户状态枚举
+│
+├── 📂 admin/                      # 🛡️ 管理员模块
+│   ├── 📄 admin.controller.ts     # 管理员接口
+│   ├── 📄 admin.service.ts        # 管理员业务逻辑
+│   ├── 📄 admin.module.ts         # 模块定义
+│   ├── 📂 dto/                    # 数据传输对象
+│   └── 📂 guards/                 # 权限守卫
+│       └── 📄 admin.guard.ts      # 管理员权限验证
+│
+├── 📂 security/                   # 🔒 安全防护模块
+│   ├── 📄 security.module.ts      # 安全模块定义
+│   ├── 📂 guards/                 # 安全守卫
+│   │   ├── 📄 throttle.guard.ts   # 频率限制守卫
+│   │   ├── 📄 maintenance.guard.ts # 维护模式守卫
+│   │   └── 📄 content-type.guard.ts # 内容类型守卫
+│   └── 📂 interceptors/           # 拦截器
+│       └── 📄 timeout.interceptor.ts # 超时拦截器
+│
+├── 📂 zulip/                      # 💬 Zulip集成模块
+│   ├── 📄 zulip.service.ts        # Zulip业务服务
+│   ├── 📄 zulip_websocket.gateway.ts # WebSocket网关
+│   ├── 📄 zulip.module.ts         # 模块定义
+│   └── 📂 services/               # 子服务
+│       ├── 📄 message_filter.service.ts # 消息过滤
+│       └── 📄 session_cleanup.service.ts # 会话清理
+│
+└── 📂 shared/                     # 🔗 共享业务组件
+    ├── 📂 decorators/             # 装饰器
+    ├── 📂 pipes/                  # 管道
+    ├── 📂 filters/                # 异常过滤器
+    └── 📂 interfaces/             # 接口定义
+```
+
+### ⚙️ 核心技术服务 (`src/core/`)
+
+> **设计原则**: 提供技术基础设施，支持业务模块运行
+
+```
+src/core/
+├── 📂 db/                         # 🗄️ 数据库层
+│   ├── 📄 db.module.ts            # 数据库模块
+│   ├── 📂 users/                  # 用户数据服务
+│   │   ├── 📄 users.service.ts    # MySQL数据库实现
+│   │   ├── 📄 users-memory.service.ts # 内存数据库实现
+│   │   ├── 📄 users.interface.ts  # 用户服务接口
+│   │   └── 📄 user.entity.ts      # 用户实体定义
+│   └── 📂 entities/               # 数据库实体
+│       └── 📄 *.entity.ts         # 各种实体定义
+│
+├── 📂 redis/                      # 🔴 Redis缓存层
+│   ├── 📄 redis.module.ts         # Redis模块
+│   ├── 📄 redis.service.ts        # Redis真实实现
+│   ├── 📄 file-redis.service.ts   # 文件存储实现
+│   └── 📄 redis.interface.ts      # Redis服务接口
+│
+├── 📂 login_core/                 # 🔑 登录核心服务
+│   ├── 📄 login-core.service.ts   # 登录核心逻辑
+│   ├── 📄 login-core.module.ts    # 模块定义
+│   └── 📄 login-core.interface.ts # 接口定义
+│
+├── 📂 admin_core/                 # 👑 管理员核心服务
+│   ├── 📄 admin-core.service.ts   # 管理员核心逻辑
+│   ├── 📄 admin-core.module.ts    # 模块定义
+│   └── 📄 admin-core.interface.ts # 接口定义
+│
+├── 📂 zulip/                      # 💬 Zulip核心服务
+│   ├── 📄 zulip-core.module.ts    # Zulip核心模块
+│   ├── 📄 zulip-api.service.ts    # Zulip API服务
+│   └── 📄 zulip-websocket.service.ts # WebSocket服务
+│
+└── 📂 utils/                      # 🛠️ 工具服务
+    ├── 📂 email/                  # 📧 邮件服务
+    │   ├── 📄 email.service.ts    # 邮件发送服务
+    │   ├── 📄 email.module.ts     # 邮件模块
+    │   └── 📄 email.interface.ts  # 邮件接口
+    ├── 📂 verification/           # 🔢 验证码服务
+    │   ├── 📄 verification.service.ts # 验证码生成验证
+    │   └── 📄 verification.module.ts  # 验证码模块
+    └── 📂 logger/                 # 📝 日志服务
+        ├── 📄 logger.service.ts   # 日志记录服务
+        └── 📄 logger.module.ts    # 日志模块
+```
+
+### 🎨 前端管理界面 (`client/`)
+
+> **设计原则**: 独立的前端项目，提供管理员后台功能
+
+```
+client/
+├── 📂 src/                        # 前端源码
+│   ├── 📂 components/             # 通用组件
+│   │   ├── 📄 Layout.tsx          # 布局组件
+│   │   ├── 📄 UserTable.tsx       # 用户表格组件
+│   │   └── 📄 LogViewer.tsx       # 日志查看组件
+│   ├── 📂 pages/                  # 页面组件
+│   │   ├── 📄 Login.tsx           # 登录页面
+│   │   ├── 📄 Dashboard.tsx       # 仪表板
+│   │   ├── 📄 UserManagement.tsx  # 用户管理
+│   │   └── 📄 LogManagement.tsx   # 日志管理
+│   ├── 📂 services/               # API服务
+│   │   ├── 📄 api.ts              # API客户端
+│   │   ├── 📄 auth.ts             # 认证服务
+│   │   └── 📄 users.ts            # 用户服务
+│   ├── 📂 utils/                  # 工具函数
+│   ├── 📂 types/                  # TypeScript类型
+│   ├── 📄 App.tsx                 # 应用主组件
+│   └── 📄 main.tsx                # 应用入口
+├── 📂 dist/                       # 构建产物
+├── 📄 package.json                # 前端依赖
+├── 📄 vite.config.ts              # Vite配置
+└── 📄 tsconfig.json               # TypeScript配置
+```
+
+### 📚 文档中心 (`docs/`)
+
+> **设计原则**: 完整的项目文档，支持开发者快速上手
+
+```
+docs/
+├── 📄 README.md                   # 📖 文档导航中心
+├── 📄 ARCHITECTURE.md             # 🏗️ 架构设计文档
+├── 📄 API_STATUS_CODES.md         # 📋 API状态码说明
+├── 📄 CONTRIBUTORS.md             # 🤝 贡献者指南
+│
+├── 📂 api/                        # 🔌 API接口文档
+│   ├── 📄 README.md               # API文档使用指南
+│   ├── 📄 api-documentation.md    # 完整API接口文档
+│   ├── 📄 openapi.yaml            # OpenAPI规范文件
+│   └── 📄 postman-collection.json # Postman测试集合
+│
+├── 📂 development/                # 💻 开发指南
+│   ├── 📄 backend_development_guide.md # 后端开发规范
+│   ├── 📄 git_commit_guide.md     # Git提交规范
+│   ├── 📄 AI辅助开发规范指南.md   # AI辅助开发指南
+│   ├── 📄 TESTING.md              # 测试指南
+│   └── 📄 naming_convention.md    # 命名规范
+│
+└── 📂 deployment/                 # 🚀 部署文档
+    └── 📄 DEPLOYMENT.md           # 生产环境部署指南
+```
+
+### 🧪 测试文件 (`test/`)
+
+> **设计原则**: 完整的测试覆盖，确保代码质量
+
+```
+test/
+├── 📂 unit/                       # 单元测试
+├── 📂 integration/                # 集成测试
+├── 📂 e2e/                        # 端到端测试
+└── 📂 fixtures/                   # 测试数据
+```
+
+### ⚙️ 配置文件
+
+> **设计原则**: 清晰的配置管理，支持多环境部署
+
+```
+项目根目录/
+├── 📄 .env                        # 🔧 环境变量配置
+├── 📄 .env.example                # 🔧 环境变量示例
+├── 📄 .env.production.example     # 🔧 生产环境示例
+├── 📄 package.json                # 📋 项目依赖配置
+├── 📄 pnpm-workspace.yaml         # 📦 pnpm工作空间配置
+├── 📄 tsconfig.json               # 📘 TypeScript配置
+├── 📄 jest.config.js              # 🧪 Jest测试配置
+├── 📄 nest-cli.json               # 🏠 NestJS CLI配置
+├── 📄 docker-compose.yml          # 🐳 Docker编排配置
+├── 📄 Dockerfile                  # 🐳 Docker镜像配置
+└── 📄 ecosystem.config.js         # 🚀 PM2进程管理配置
+```
+
+---
+
+## 🏗️ 分层架构设计
+
+### 📊 架构分层说明
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                        API 层                               │
+│                    🌐 表现层 (Presentation)                  │
 │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
-│  │   HTTP API      │  │   WebSocket     │  │   GraphQL       │ │
-│  │   (REST)        │  │   (Socket.IO)   │  │   (预留)        │ │
+│  │   Controllers   │  │   WebSocket     │  │   Swagger UI    │ │
+│  │   (HTTP接口)    │  │   Gateways      │  │   (API文档)     │ │
 │  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
 └─────────────────────────────────────────────────────────────┘
-                                │
+                                ⬇️
 ┌─────────────────────────────────────────────────────────────┐
-│                      业务逻辑层                              │
+│                    🎯 业务层 (Business)                      │
 │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
-│  │   用户认证      │  │   游戏逻辑      │  │   社交功能      │ │
-│  │   (Login)       │  │   (Game)        │  │   (Social)      │ │
+│  │   Auth Module   │  │  UserMgmt       │  │   Admin Module  │ │
+│  │   (用户认证)    │  │  Module         │  │   (管理员)      │ │
+│  │                 │  │  (用户管理)     │  │                 │ │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
+│  │ Security Module │  │  Zulip Module   │  │  Shared Module  │ │
+│  │  (安全防护)     │  │  (Zulip集成)    │  │  (共享组件)     │ │
 │  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
 └─────────────────────────────────────────────────────────────┘
-                                │
+                                ⬇️
 ┌─────────────────────────────────────────────────────────────┐
-│                      核心服务层                              │
+│                    ⚙️ 服务层 (Service)                      │
 │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
-│  │   邮件服务      │  │   验证码服务    │  │   日志服务      │ │
-│  │   (Email)       │  │   (Verification)│  │   (Logger)      │ │
+│  │  Login Core     │  │  Admin Core     │  │  Zulip Core     │ │
+│  │  (登录核心)     │  │  (管理员核心)   │  │  (Zulip核心)    │ │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
+│  │  Email Service  │  │ Verification    │  │ Logger Service  │ │
+│  │  (邮件服务)     │  │ Service         │  │ (日志服务)      │ │
+│  │                 │  │ (验证码服务)    │  │                 │ │
 │  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
 └─────────────────────────────────────────────────────────────┘
-                                │
+                                ⬇️
 ┌─────────────────────────────────────────────────────────────┐
-│                      数据访问层                              │
+│                    🗄️ 数据层 (Data)                        │
 │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
-│  │   用户数据      │  │   Redis缓存     │  │   文件存储      │ │
-│  │   (Users)       │  │   (Cache)       │  │   (Files)       │ │
+│  │  Users Service  │  │  Redis Service  │  │  File Storage   │ │
+│  │  (用户数据)     │  │  (缓存服务)     │  │  (文件存储)     │ │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
+│  │  MySQL/Memory   │  │  Redis/File     │  │  Logs/Data      │ │
+│  │  (数据库)       │  │  (缓存实现)     │  │  (日志数据)     │ │
 │  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-## 模块依赖关系
+### 🔄 数据流向
+
+#### 用户注册流程示例
 
 ```
-AppModule
-├── ConfigModule (全局配置)
-├── LoggerModule (日志系统)
-├── RedisModule (缓存服务)
-├── UsersModule (用户管理)
-│   ├── UsersService (数据库模式)
-│   └── UsersMemoryService (内存模式)
-├── EmailModule (邮件服务)
-├── VerificationModule (验证码服务)
-├── LoginCoreModule (登录核心)
-└── LoginModule (登录业务)
+1. 📱 用户请求 → AuthController.register()
+2. 🔍 参数验证 → class-validator装饰器
+3. 🎯 业务逻辑 → AuthService.register()
+4. ⚙️ 核心服务 → LoginCoreService.createUser()
+5. 📧 发送邮件 → EmailService.sendVerificationCode()
+6. 🔢 生成验证码 → VerificationService.generate()
+7. 💾 存储数据 → UsersService.create() + RedisService.set()
+8. 📝 记录日志 → LoggerService.log()
+9. ✅ 返回响应 → 用户收到成功响应
 ```
 
-## 数据流向
+#### 管理员操作流程示例
 
-### 用户注册流程
 ```
-1. 用户请求 → LoginController
-2. 参数验证 → LoginService
-3. 发送验证码 → LoginCoreService
-4. 生成验证码 → VerificationService
-5. 发送邮件 → EmailService
-6. 存储验证码 → RedisService
-7. 返回响应 → 用户
+1. 🛡️ 管理员请求 → AdminController.resetUserPassword()
+2. 🔐 权限验证 → AdminGuard.canActivate()
+3. 🎯 业务逻辑 → AdminService.resetPassword()
+4. ⚙️ 核心服务 → AdminCoreService.resetUserPassword()
+5. 🔑 密码加密 → bcrypt.hash()
+6. 💾 更新数据 → UsersService.update()
+7. 📧 通知用户 → EmailService.sendPasswordReset()
+8. 📝 审计日志 → LoggerService.audit()
+9. ✅ 返回响应 → 管理员收到操作结果
 ```
 
-### 双模式架构
+---
 
-项目支持开发测试模式和生产部署模式的无缝切换：
+## 🔄 双模式架构
 
-#### 开发测试模式
-- **数据库**: 内存存储 (UsersMemoryService)
-- **缓存**: 文件存储 (FileRedisService)
-- **邮件**: 控制台输出 (测试模式)
-- **优势**: 无需外部依赖，快速启动测试
+### 🎯 设计目标
 
-#### 生产部署模式
-- **数据库**: MySQL (UsersService + TypeORM)
-- **缓存**: Redis (RealRedisService + IORedis)
-- **邮件**: SMTP服务器 (生产模式)
-- **优势**: 高性能，高可用，数据持久化
+- **开发测试**: 零依赖快速启动，无需安装MySQL、Redis等外部服务
+- **生产部署**: 高性能、高可用，支持集群和负载均衡
 
-## 设计原则
+### 📊 模式对比
 
-### 1. 单一职责原则
-每个模块只负责一个特定的功能领域：
-- `LoginModule`: 只处理登录相关业务
-- `EmailModule`: 只处理邮件发送
-- `VerificationModule`: 只处理验证码逻辑
+| 功能模块 | 🧪 开发测试模式 | 🚀 生产部署模式 |
+|----------|----------------|----------------|
+| **数据库** | 内存存储 (UsersMemoryService) | MySQL (UsersService + TypeORM) |
+| **缓存** | 文件存储 (FileRedisService) | Redis (RedisService + IORedis) |
+| **邮件** | 控制台输出 (测试模式) | SMTP服务器 (生产模式) |
+| **日志** | 控制台 + 文件 | 结构化日志 + 日志轮转 |
+| **配置** | `.env` 默认配置 | 环境变量 + 配置中心 |
 
-### 2. 依赖注入
-使用NestJS的依赖注入系统：
-- 接口抽象: `IRedisService`, `IUsersService`
-- 实现切换: 根据配置自动选择实现类
-- 测试友好: 易于Mock和单元测试
+### ⚙️ 模式切换配置
 
-### 3. 配置驱动
-通过环境变量控制行为：
-- `USE_FILE_REDIS`: 选择Redis实现
-- `DB_HOST`: 数据库连接配置
-- `EMAIL_HOST`: 邮件服务配置
+#### 开发测试模式 (.env)
+```bash
+# 数据存储模式
+USE_FILE_REDIS=true          # 使用文件存储代替Redis
+NODE_ENV=development         # 开发环境
 
-### 4. 错误处理
-统一的错误处理机制：
-- HTTP异常: `BadRequestException`, `UnauthorizedException`
-- 业务异常: 自定义异常类
-- 日志记录: 结构化错误日志
+# 数据库配置（注释掉，使用内存数据库）
+# DB_HOST=localhost
+# DB_USERNAME=root
+# DB_PASSWORD=password
 
-## 扩展指南
+# 邮件配置（注释掉，使用测试模式）
+# EMAIL_HOST=smtp.gmail.com
+# EMAIL_USER=your_email@gmail.com
+# EMAIL_PASS=your_password
+```
 
-### 添加新的业务模块
+#### 生产部署模式 (.env.production)
+```bash
+# 数据存储模式
+USE_FILE_REDIS=false         # 使用真实Redis
+NODE_ENV=production          # 生产环境
 
-1. **创建业务模块**
-   ```bash
-   nest g module business/game
-   nest g controller business/game
-   nest g service business/game
-   ```
+# 数据库配置
+DB_HOST=your_mysql_host
+DB_PORT=3306
+DB_USERNAME=your_username
+DB_PASSWORD=your_password
+DB_DATABASE=whale_town
 
-2. **创建核心服务**
-   ```bash
-   nest g module core/game_core
-   nest g service core/game_core
-   ```
+# Redis配置
+REDIS_HOST=your_redis_host
+REDIS_PORT=6379
+REDIS_PASSWORD=your_redis_password
 
-3. **添加数据模型**
-   ```bash
-   nest g module core/db/games
-   nest g service core/db/games
-   ```
+# 邮件配置
+EMAIL_HOST=smtp.gmail.com
+EMAIL_PORT=587
+EMAIL_USER=your_email@gmail.com
+EMAIL_PASS=your_app_password
+```
 
-4. **更新主模块**
-   在 `app.module.ts` 中导入新模块
+### 🔧 实现机制
 
-### 添加新的工具服务
+#### 依赖注入切换
+```typescript
+// redis.module.ts
+@Module({
+  providers: [
+    {
+      provide: 'IRedisService',
+      useFactory: (configService: ConfigService) => {
+        const useFileRedis = configService.get<boolean>('USE_FILE_REDIS');
+        return useFileRedis 
+          ? new FileRedisService() 
+          : new RedisService(configService);
+      },
+      inject: [ConfigService],
+    },
+  ],
+})
+export class RedisModule {}
+```
 
-1. **创建工具模块**
-   ```bash
-   nest g module core/utils/notification
-   nest g service core/utils/notification
-   ```
+#### 配置驱动服务选择
+```typescript
+// users.module.ts
+@Module({
+  providers: [
+    {
+      provide: 'IUsersService',
+      useFactory: (configService: ConfigService) => {
+        const dbHost = configService.get<string>('DB_HOST');
+        return dbHost 
+          ? new UsersService() 
+          : new UsersMemoryService();
+      },
+      inject: [ConfigService],
+    },
+  ],
+})
+export class UsersModule {}
+```
 
-2. **实现服务接口**
-   定义抽象接口和具体实现
+---
 
-3. **添加配置支持**
-   在环境变量中添加相关配置
+## 📦 模块依赖关系
 
-4. **编写测试用例**
-   确保功能正确性和代码覆盖率
+### 🏗️ 模块依赖图
 
-## 性能优化
+```
+AppModule (应用主模块)
+├── 📊 ConfigModule (全局配置)
+├── 📝 LoggerModule (日志系统)
+├── 🔴 RedisModule (缓存服务)
+│   ├── RedisService (真实Redis)
+│   └── FileRedisService (文件存储)
+├── 🗄️ UsersModule (用户数据)
+│   ├── UsersService (MySQL数据库)
+│   └── UsersMemoryService (内存数据库)
+├── 📧 EmailModule (邮件服务)
+├── 🔢 VerificationModule (验证码服务)
+├── 🔑 LoginCoreModule (登录核心)
+├── 👑 AdminCoreModule (管理员核心)
+├── 💬 ZulipCoreModule (Zulip核心)
+│
+├── 🎯 业务功能模块
+│   ├── 🔐 AuthModule (用户认证)
+│   │   └── 依赖: LoginCoreModule, EmailModule, VerificationModule
+│   ├── 👥 UserMgmtModule (用户管理)
+│   │   └── 依赖: UsersModule, LoggerModule
+│   ├── 🛡️ AdminModule (管理员)
+│   │   └── 依赖: AdminCoreModule, UsersModule
+│   ├── 🔒 SecurityModule (安全防护)
+│   │   └── 依赖: RedisModule, LoggerModule
+│   ├── 💬 ZulipModule (Zulip集成)
+│   │   └── 依赖: ZulipCoreModule, RedisModule
+│   └── 🔗 SharedModule (共享组件)
+```
 
-### 1. 缓存策略
-- **Redis缓存**: 验证码、会话信息
+### 🔄 模块交互流程
+
+#### 用户认证流程
+```
+AuthController → AuthService → LoginCoreService
+                              ↓
+EmailService ← VerificationService ← RedisService
+                              ↓
+                         UsersService
+```
+
+#### 管理员操作流程
+```
+AdminController → AdminService → AdminCoreService
+                               ↓
+LoggerService ← UsersService ← RedisService
+```
+
+#### 安全防护流程
+```
+SecurityGuard → RedisService (频率限制)
+              → LoggerService (审计日志)
+              → ConfigService (维护模式)
+```
+
+---
+
+## 🚀 扩展指南
+
+### 📝 添加新的业务模块
+
+#### 1. 创建业务模块结构
+```bash
+# 创建模块目录
+mkdir -p src/business/game/{dto,enums,guards,interfaces}
+
+# 生成NestJS模块文件
+nest g module business/game
+nest g controller business/game
+nest g service business/game
+```
+
+#### 2. 实现业务逻辑
+```typescript
+// src/business/game/game.module.ts
+@Module({
+  imports: [
+    GameCoreModule,    # 依赖核心服务
+    UsersModule,       # 依赖用户数据
+    RedisModule,       # 依赖缓存服务
+  ],
+  controllers: [GameController],
+  providers: [GameService],
+  exports: [GameService],
+})
+export class GameModule {}
+```
+
+#### 3. 创建对应的核心服务
+```bash
+# 创建核心服务
+mkdir -p src/core/game_core
+nest g module core/game_core
+nest g service core/game_core
+```
+
+#### 4. 更新主模块
+```typescript
+// src/app.module.ts
+@Module({
+  imports: [
+    // ... 其他模块
+    GameModule,        # 添加新的业务模块
+  ],
+})
+export class AppModule {}
+```
+
+### 🛠️ 添加新的工具服务
+
+#### 1. 创建工具服务
+```bash
+mkdir -p src/core/utils/notification
+nest g module core/utils/notification
+nest g service core/utils/notification
+```
+
+#### 2. 定义服务接口
+```typescript
+// src/core/utils/notification/notification.interface.ts
+export interface INotificationService {
+  sendPush(userId: string, message: string): Promise<void>;
+  sendSMS(phone: string, message: string): Promise<void>;
+}
+```
+
+#### 3. 实现服务
+```typescript
+// src/core/utils/notification/notification.service.ts
+@Injectable()
+export class NotificationService implements INotificationService {
+  async sendPush(userId: string, message: string): Promise<void> {
+    // 实现推送通知逻辑
+  }
+  
+  async sendSMS(phone: string, message: string): Promise<void> {
+    // 实现短信发送逻辑
+  }
+}
+```
+
+#### 4. 配置依赖注入
+```typescript
+// src/core/utils/notification/notification.module.ts
+@Module({
+  providers: [
+    {
+      provide: 'INotificationService',
+      useClass: NotificationService,
+    },
+  ],
+  exports: ['INotificationService'],
+})
+export class NotificationModule {}
+```
+
+### 🔌 添加新的API接口
+
+#### 1. 定义DTO
+```typescript
+// src/business/game/dto/create-game.dto.ts
+export class CreateGameDto {
+  @IsString()
+  @IsNotEmpty()
+  name: string;
+
+  @IsString()
+  @IsOptional()
+  description?: string;
+}
+```
+
+#### 2. 实现Controller
+```typescript
+// src/business/game/game.controller.ts
+@Controller('game')
+@ApiTags('游戏管理')
+export class GameController {
+  constructor(private readonly gameService: GameService) {}
+
+  @Post()
+  @ApiOperation({ summary: '创建游戏' })
+  async createGame(@Body() createGameDto: CreateGameDto) {
+    return this.gameService.create(createGameDto);
+  }
+}
+```
+
+#### 3. 实现Service
+```typescript
+// src/business/game/game.service.ts
+@Injectable()
+export class GameService {
+  constructor(
+    @Inject('IGameCoreService')
+    private readonly gameCoreService: IGameCoreService,
+  ) {}
+
+  async create(createGameDto: CreateGameDto) {
+    return this.gameCoreService.createGame(createGameDto);
+  }
+}
+```
+
+#### 4. 添加测试用例
+```typescript
+// src/business/game/game.service.spec.ts
+describe('GameService', () => {
+  let service: GameService;
+  let gameCoreService: jest.Mocked<IGameCoreService>;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        GameService,
+        {
+          provide: 'IGameCoreService',
+          useValue: {
+            createGame: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    service = module.get<GameService>(GameService);
+    gameCoreService = module.get('IGameCoreService');
+  });
+
+  it('should create game', async () => {
+    const createGameDto = { name: 'Test Game' };
+    const expectedResult = { id: 1, ...createGameDto };
+    
+    gameCoreService.createGame.mockResolvedValue(expectedResult);
+    
+    const result = await service.create(createGameDto);
+    
+    expect(result).toEqual(expectedResult);
+    expect(gameCoreService.createGame).toHaveBeenCalledWith(createGameDto);
+  });
+});
+```
+
+### 📊 性能优化建议
+
+#### 1. 缓存策略
+- **Redis缓存**: 用户会话、验证码、频繁查询数据
 - **内存缓存**: 配置信息、静态数据
 - **CDN缓存**: 静态资源文件
 
-### 2. 数据库优化
-- **连接池**: 复用数据库连接
-- **索引优化**: 关键字段建立索引
-- **查询优化**: 避免N+1查询问题
+#### 2. 数据库优化
+- **连接池**: 复用数据库连接，减少连接开销
+- **索引优化**: 为查询字段建立合适的索引
+- **查询优化**: 避免N+1查询，使用JOIN优化关联查询
 
-### 3. 日志优化
-- **异步日志**: 使用Pino的异步写入
-- **日志分级**: 生产环境只记录必要日志
+#### 3. 日志优化
+- **异步日志**: 使用Pino的异步写入功能
+- **日志分级**: 生产环境只记录ERROR和WARN级别
 - **日志轮转**: 自动清理过期日志文件
 
-## 安全考虑
+### 🔒 安全加固建议
 
-### 1. 数据验证
-- **输入验证**: class-validator装饰器
-- **类型检查**: TypeScript静态类型
-- **SQL注入**: TypeORM参数化查询
+#### 1. 数据验证
+- **输入验证**: 使用class-validator进行严格验证
+- **类型检查**: TypeScript静态类型检查
+- **SQL注入防护**: TypeORM参数化查询
 
-### 2. 认证授权
-- **密码加密**: bcrypt哈希算法
-- **会话管理**: Redis存储会话信息
-- **权限控制**: 基于角色的访问控制
+#### 2. 认证授权
+- **密码安全**: bcrypt加密，强密码策略
+- **会话管理**: JWT + Redis会话存储
+- **权限控制**: 基于角色的访问控制(RBAC)
 
-### 3. 通信安全
+#### 3. 通信安全
 - **HTTPS**: 生产环境强制HTTPS
-- **CORS**: 跨域请求控制
+- **CORS**: 严格的跨域请求控制
 - **Rate Limiting**: API请求频率限制
+
+---
+
+**🏗️ 通过清晰的架构设计，Whale Town 实现了高内聚、低耦合的模块化架构，支持快速开发和灵活部署！**

docs/DOCUMENT_CLEANUP.md

@@ -0,0 +1,142 @@
+# 📝 文档清理说明
+
+> 记录项目文档整理和优化的过程，确保文档结构清晰、内容准确。
+
+## 🎯 清理目标
+
+- **删除多余README** - 移除重复和过时的README文件
+- **优化主文档** - 改进项目主README的文件格式和结构说明
+- **完善架构文档** - 详细说明项目架构和文件夹组织结构
+- **统一文档风格** - 采用总分结构，方便开发者理解
+
+## 📊 文档清理结果
+
+### ✅ 保留的README文件
+
+| 文件路径 | 保留原因 | 主要内容 |
+|----------|----------|----------|
+| `README.md` | 项目主文档 | 项目介绍、快速开始、技术栈、功能特性 |
+| `docs/README.md` | 文档导航中心 | 文档结构说明、导航链接 |
+| `client/README.md` | 前端项目文档 | 前端管理界面的独立说明 |
+| `docs/api/README.md` | API文档指南 | API文档使用说明和快速测试 |
+| `src/business/zulip/README.md` | 模块架构说明 | Zulip模块重构的详细说明 |
+
+### ❌ 删除的README文件
+
+**无** - 经过分析，所有现有README文件都有其存在价值，未删除任何文件。
+
+### 🔄 优化的文档
+
+#### 1. 主README.md优化
+- **文件结构总览** - 添加了详细的项目文件结构说明
+- **图标化展示** - 使用emoji图标让结构更直观
+- **层次化组织** - 按照总分结构组织内容
+
+#### 2. 架构文档大幅改进 (docs/ARCHITECTURE.md)
+- **完整重写** - 从简单的架构图扩展为完整的架构设计文档
+- **目录结构详解** - 详细说明每个文件夹的作用和内容
+- **分层架构设计** - 清晰的架构分层和模块依赖关系
+- **双模式架构** - 详细说明开发测试模式和生产部署模式
+- **扩展指南** - 提供添加新模块和功能的详细指导
+
+## 📁 文档结构优化
+
+### 🎯 总分结构设计
+
+采用**总分结构**组织文档，便于开发者快速理解：
+
+```
+📚 文档层次结构
+├── 🏠 项目总览 (README.md)
+│   ├── 🎯 项目简介和特性
+│   ├── 🚀 快速开始指南
+│   ├── 📁 文件结构总览 ⭐ 新增
+│   ├── 🛠️ 技术栈说明
+│   └── 📚 文档导航链接
+│
+├── 🏗️ 架构设计 (docs/ARCHITECTURE.md) ⭐ 大幅改进
+│   ├── 📊 整体架构图
+│   ├── 📁 目录结构详解
+│   ├── 🏗️ 分层架构设计
+│   ├── 🔄 双模式架构
+│   └── 🚀 扩展指南
+│
+├── 📖 文档中心 (docs/README.md)
+│   ├── 📋 文档导航
+│   ├── 🏗️ 文档结构说明
+│   └── 📝 文档维护原则
+│
+├── 🔌 API文档 (docs/api/README.md)
+│   ├── 📊 API接口概览
+│   ├── 🚀 快速开始
+│   └── 🧪 测试指南
+│
+└── 🎨 前端文档 (client/README.md)
+    ├── 🚀 快速开始
+    ├── 🎯 核心功能
+    └── 🔧 开发指南
+```
+
+### 📊 文档内容优化
+
+#### 1. 视觉化改进
+- **emoji图标** - 使用统一的emoji图标系统
+- **表格展示** - 用表格清晰展示对比信息
+- **代码示例** - 提供完整的代码示例和配置
+- **架构图** - 使用ASCII艺术绘制清晰的架构图
+
+#### 2. 结构化内容
+- **目录导航** - 每个长文档都有详细目录
+- **分层说明** - 按照业务功能模块化的原则组织
+- **实用指南** - 提供具体的操作步骤和扩展指南
+
+#### 3. 开发者友好
+- **快速上手** - 新开发者指南，从规范学习到架构理解
+- **总分结构** - 先总览后详细，便于快速理解
+- **实际案例** - 提供真实的代码示例和使用场景
+
+## 🎯 文档维护原则
+
+### ✅ 保留标准
+- **长期价值** - 对整个项目生命周期都有价值
+- **参考价值** - 开发、部署、维护时需要查阅
+- **规范指导** - 团队协作和代码质量保证
+
+### ❌ 清理标准
+- **阶段性文档** - 只在特定开发阶段有用
+- **临时记录** - 会议记录、临时决策等
+- **过时信息** - 已经不适用的旧版本文档
+
+### 🔄 更新策略
+- **及时更新** - 功能变更时同步更新相关文档
+- **版本控制** - 重要变更记录版本历史
+- **定期审查** - 定期检查文档的准确性和有效性
+
+## 📈 改进效果
+
+### 🎯 开发者体验提升
+- **快速理解** - 通过总分结构快速掌握项目架构
+- **准确信息** - 文档与实际代码结构完全一致
+- **实用指导** - 提供具体的开发和扩展指南
+
+### 📚 文档质量提升
+- **结构清晰** - 层次分明的文档组织结构
+- **内容完整** - 覆盖项目的所有重要方面
+- **易于维护** - 明确的维护原则和更新策略
+
+### 🚀 项目可维护性提升
+- **架构清晰** - 详细的架构文档便于理解和扩展
+- **规范统一** - 统一的文档风格和组织原则
+- **知识传承** - 完整的文档体系便于团队协作
+
+---
+
+**📝 通过系统性的文档清理和优化，项目文档现在更加清晰、准确、实用！**
+
+## 📅 清理记录
+
+- **清理时间**: 2025年12月31日
+- **清理范围**: 项目根目录及所有子目录的README文件
+- **主要改进**: 架构文档完全重写，主README结构优化
+- **保留文件**: 5个README文件全部保留
+- **删除文件**: 0个（所有文件都有价值）

docs/README.md

@@ -27,7 +27,7 @@
 
 ### 📋 **项目管理**
 - [贡献指南](CONTRIBUTORS.md) - 如何参与项目贡献
-- [文档清理说明](DOCUMENT_CLEANUP.md) - 文档维护记录
+- [文档清理说明](DOCUMENT_CLEANUP.md) - 文档维护和优化记录
 
 ## 🏗️ **文档结构说明**