0

arch.md

@@ -1,196 +0,0 @@
-# 妙果系统服务端架构文档
-
-## 1. 系统概述
-
-妙果系统服务端是一个基于 Node.js 和 Koa 框架构建的后端服务，提供多种教育相关 API 服务，包括拼音、汉字、数学计算、自然拼读等多个教育领域的功能支持。系统采用模块化设计，支持多种微信小程序应用的后端服务需求。
-
-## 2. 技术栈
-
-- **运行环境**: Node.js v24.1.0
-- **Web 框架**: Koa v2.13.4
-- **路由**: @koa/router v13.1.0, koa-router v13.0.1
-- **数据库**: MySQL (mysql2 v3.14.1)
-- **会话管理**: koa-session v7.0.2
-- **文件处理**: @koa/multer v3.0.2, multer v1.4.5-lts.1
-- **HTTP 客户端**: axios v1.9.0
-- **工具库**: lodash v4.17.21, moment v2.30.1
-- **云服务集成**: 腾讯云 OCR、腾讯云对象存储
-- **其他工具**: pdfkit v0.17.1, gm v1.25.1 (图像处理)
-
-## 3. 系统架构
-
-### 3.1 目录结构
-
-```
-miaoguo_system_server/
-├── src/                    # 源代码目录
-│   ├── api/                # API 模块目录
-│   │   ├── common/         # 通用 API
-│   │   ├── hanzi/          # 汉字学习 API
-│   │   ├── mathcalculate/  # 数学计算 API
-│   │   ├── mps/            # MPS 相关 API
-│   │   ├── phonics/        # 自然拼读 API
-│   │   ├── pinyin/         # 拼音学习 API
-│   │   ├── web/            # Web 相关 API
-│   │   └── yjbdc/          # 英语百词斩 API
-│   ├── config/             # 配置文件目录
-│   │   ├── dev.js          # 开发环境配置
-│   │   ├── env.js          # 环境变量配置
-│   │   ├── index.js        # 主配置文件
-│   │   └── prod.js         # 生产环境配置
-│   ├── middleware/         # 中间件目录
-│   │   ├── queryParamSanitizer.js  # 查询参数清理中间件
-│   │   └── upload.js       # 文件上传中间件
-│   ├── model/              # 数据模型目录
-│   │   ├── BufferMemoryClass.js    # 缓存管理类
-│   │   ├── commonModel.js          # 通用模型
-│   │   ├── hanzi.js                # 汉字学习模型
-│   │   ├── mathcalculate.js        # 数学计算模型
-│   │   ├── mathstar.js             # 数学之星模型
-│   │   ├── mps.js                  # MPS 模型
-│   │   ├── phonics.js              # 自然拼读模型
-│   │   ├── pinyin.js               # 拼音学习模型
-│   │   └── yjbdc.js                # 英语百词斩模型
-│   ├── util/               # 工具类目录
-│   │   ├── db.js           # 数据库工具
-│   │   ├── GlobalCache.js  # 全局缓存工具
-│   │   ├── stringClass.js  # 字符串处理工具
-│   │   ├── WXBizDataCrypt.js # 微信数据解密工具
-│   │   ├── constant/       # 常量定义
-│   │   └── crypto/         # 加密解密工具
-│   ├── test/               # 测试目录
-│   └── app.js              # 应用入口文件
-├── public/                 # 静态资源目录
-├── scripts/                # 脚本目录
-├── doc/                    # 文档目录
-└── package.json            # 项目依赖配置
-```
-
-### 3.2 核心组件
-
-#### 3.2.1 应用入口 (app.js)
-
-应用入口文件负责初始化 Koa 应用实例，配置中间件，注册路由，并启动 HTTP 服务器。主要功能包括：
-
-- 配置 bodyParser 解析请求体
-- 配置静态文件服务
-- 设置错误处理中间件
-- 配置会话管理
-- 注册各模块路由
-- 启动服务器监听
-
-#### 3.2.2 API 模块
-
-每个 API 模块通常包含两个主要文件：
-- **routes.js**: 定义路由和 URL 映射
-- **xxxController.js**: 实现具体的业务逻辑和请求处理
-
-API 模块按功能领域划分，包括：
-- **common**: 通用功能，如文件上传、内容安全检查等
-- **hanzi**: 汉字学习相关功能
-- **mathcalculate**: 数学计算相关功能
-- **mps**: MPS 相关功能
-- **phonics**: 自然拼读相关功能
-- **pinyin**: 拼音学习相关功能
-- **web**: Web 端相关功能
-- **yjbdc**: 英语百词斩相关功能
-
-#### 3.2.3 配置管理
-
-配置管理采用环境分离的方式，通过 `process.env.NODE_ENV` 区分开发环境和生产环境：
-- **dev.js**: 开发环境特定配置
-- **prod.js**: 生产环境特定配置
-- **index.js**: 主配置文件，包含通用配置和环境特定配置的整合
-
-配置内容包括：
-- 服务器端口
-- 数据库连接参数
-- 会话配置
-- 微信应用配置（多个小程序的 appid 和 secret）
-- 云服务配置（腾讯云、百度云等）
-
-#### 3.2.4 中间件
-
-系统使用多个中间件增强功能和安全性：
-- **queryParamSanitizer.js**: 查询参数清理，防止注入攻击
-- **upload.js**: 文件上传处理
-- **decryptUrlMiddle**: URL 解密中间件（来自 crypto 工具）
-
-#### 3.2.5 数据模型
-
-数据模型层负责与数据库交互和业务数据处理：
-- **BufferMemoryClass.js**: 内存缓存管理
-- **commonModel.js**: 通用数据模型
-- 各功能模块特定模型（hanzi.js, phonics.js 等）
-
-#### 3.2.6 工具类
-
-系统包含多个工具类，提供通用功能：
-- **db.js**: 数据库连接和操作
-- **GlobalCache.js**: 全局缓存管理
-- **stringClass.js**: 字符串处理工具
-- **WXBizDataCrypt.js**: 微信数据解密
-- **crypto/**: 加密解密工具
-
-## 4. 数据流
-
-1. 客户端发送 HTTP 请求到服务器
-2. Koa 中间件链处理请求（body 解析、参数清理、会话管理等）
-3. 路由匹配将请求分发到对应的控制器方法
-4. 控制器调用模型层处理业务逻辑和数据操作
-5. 模型层与数据库或外部 API 交互
-6. 控制器接收处理结果，构造响应
-7. 中间件链处理响应
-8. 响应返回给客户端
-
-## 5. 安全机制
-
-- 使用 queryParamSanitizer 中间件防止 SQL 注入和 XSS 攻击
-- 会话管理使用签名 cookie 和 httpOnly 标志
-- 生产环境使用 secure cookie（仅 HTTPS）
-- 微信数据解密工具保护用户数据安全
-- URL 解密中间件增强 API 安全性
-
-## 6. 扩展性设计
-
-系统采用模块化设计，便于扩展新功能：
-1. 创建新的 API 模块目录
-2. 实现路由和控制器
-3. 创建相应的数据模型
-4. 在 app.js 中注册新路由
-
-## 7. 部署架构
-
-系统支持开发和生产两种环境部署：
-- 开发环境：使用 `npm run dev` 启动，加载开发配置
-- 生产环境：使用 `npm start` 启动，加载生产配置
-
-服务器要求：
-- Node.js v24.1.0
-- MySQL 数据库
-- 适当的网络访问权限（用于访问外部 API）
-
-## 8. 依赖服务
-
-- MySQL 数据库：存储应用数据
-- 腾讯云 OCR：文字识别服务
-- 腾讯云对象存储：文件存储服务
-- 微信开放平台：小程序授权和服务
-- 百度 AI 平台：AI 相关服务
-
-## 9. 监控与日志
-
-系统使用 console.log 进行基本日志记录，关键点包括：
-- 服务器启动信息
-- 错误处理和异常捕获
-- API 调用错误
-
-## 10. 未来优化方向
-
-1. 引入专业日志系统，替代 console.log
-2. 增强错误处理和监控机制
-3. 实现更完善的缓存策略
-4. 考虑引入 TypeScript 增强类型安全
-5. 增加自动化测试覆盖
-6. 优化数据库连接池管理
-7. 考虑引入容器化部署