|
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+# 妙果系统服务端架构文档
|
|
|
2
|
+
|
|
|
3
|
+## 1. 系统概述
|
|
|
4
|
+
|
|
|
5
|
+妙果系统服务端是一个基于 Node.js 和 Koa 框架构建的后端服务，提供多种教育相关 API 服务，包括拼音、汉字、数学计算、自然拼读等多个教育领域的功能支持。系统采用模块化设计，支持多种微信小程序应用的后端服务需求。
|
|
|
6
|
+
|
|
|
7
|
+## 2. 技术栈
|
|
|
8
|
+
|
|
|
9
|
+- **运行环境**: Node.js v24.1.0
|
|
|
10
|
+- **Web 框架**: Koa v2.13.4
|
|
|
11
|
+- **路由**: @koa/router v13.1.0, koa-router v13.0.1
|
|
|
12
|
+- **数据库**: MySQL (mysql2 v3.14.1)
|
|
|
13
|
+- **会话管理**: koa-session v7.0.2
|
|
|
14
|
+- **文件处理**: @koa/multer v3.0.2, multer v1.4.5-lts.1
|
|
|
15
|
+- **HTTP 客户端**: axios v1.9.0
|
|
|
16
|
+- **工具库**: lodash v4.17.21, moment v2.30.1
|
|
|
17
|
+- **云服务集成**: 腾讯云 OCR、腾讯云对象存储
|
|
|
18
|
+- **其他工具**: pdfkit v0.17.1, gm v1.25.1 (图像处理)
|
|
|
19
|
+
|
|
|
20
|
+## 3. 系统架构
|
|
|
21
|
+
|
|
|
22
|
+### 3.1 目录结构
|
|
|
23
|
+
|
|
|
24
|
+```
|
|
|
25
|
+miaoguo_system_server/
|
|
|
26
|
+├── src/ # 源代码目录
|
|
|
27
|
+│ ├── api/ # API 模块目录
|
|
|
28
|
+│ │ ├── common/ # 通用 API
|
|
|
29
|
+│ │ ├── hanzi/ # 汉字学习 API
|
|
|
30
|
+│ │ ├── mathcalculate/ # 数学计算 API
|
|
|
31
|
+│ │ ├── mps/ # MPS 相关 API
|
|
|
32
|
+│ │ ├── phonics/ # 自然拼读 API
|
|
|
33
|
+│ │ ├── pinyin/ # 拼音学习 API
|
|
|
34
|
+│ │ ├── web/ # Web 相关 API
|
|
|
35
|
+│ │ └── yjbdc/ # 英语百词斩 API
|
|
|
36
|
+│ ├── config/ # 配置文件目录
|
|
|
37
|
+│ │ ├── dev.js # 开发环境配置
|
|
|
38
|
+│ │ ├── env.js # 环境变量配置
|
|
|
39
|
+│ │ ├── index.js # 主配置文件
|
|
|
40
|
+│ │ └── prod.js # 生产环境配置
|
|
|
41
|
+│ ├── middleware/ # 中间件目录
|
|
|
42
|
+│ │ ├── queryParamSanitizer.js # 查询参数清理中间件
|
|
|
43
|
+│ │ └── upload.js # 文件上传中间件
|
|
|
44
|
+│ ├── model/ # 数据模型目录
|
|
|
45
|
+│ │ ├── BufferMemoryClass.js # 缓存管理类
|
|
|
46
|
+│ │ ├── commonModel.js # 通用模型
|
|
|
47
|
+│ │ ├── hanzi.js # 汉字学习模型
|
|
|
48
|
+│ │ ├── mathcalculate.js # 数学计算模型
|
|
|
49
|
+│ │ ├── mathstar.js # 数学之星模型
|
|
|
50
|
+│ │ ├── mps.js # MPS 模型
|
|
|
51
|
+│ │ ├── phonics.js # 自然拼读模型
|
|
|
52
|
+│ │ ├── pinyin.js # 拼音学习模型
|
|
|
53
|
+│ │ └── yjbdc.js # 英语百词斩模型
|
|
|
54
|
+│ ├── util/ # 工具类目录
|
|
|
55
|
+│ │ ├── db.js # 数据库工具
|
|
|
56
|
+│ │ ├── GlobalCache.js # 全局缓存工具
|
|
|
57
|
+│ │ ├── stringClass.js # 字符串处理工具
|
|
|
58
|
+│ │ ├── WXBizDataCrypt.js # 微信数据解密工具
|
|
|
59
|
+│ │ ├── constant/ # 常量定义
|
|
|
60
|
+│ │ └── crypto/ # 加密解密工具
|
|
|
61
|
+│ ├── test/ # 测试目录
|
|
|
62
|
+│ └── app.js # 应用入口文件
|
|
|
63
|
+├── public/ # 静态资源目录
|
|
|
64
|
+├── scripts/ # 脚本目录
|
|
|
65
|
+├── doc/ # 文档目录
|
|
|
66
|
+└── package.json # 项目依赖配置
|
|
|
67
|
+```
|
|
|
68
|
+
|
|
|
69
|
+### 3.2 核心组件
|
|
|
70
|
+
|
|
|
71
|
+#### 3.2.1 应用入口 (app.js)
|
|
|
72
|
+
|
|
|
73
|
+应用入口文件负责初始化 Koa 应用实例，配置中间件，注册路由，并启动 HTTP 服务器。主要功能包括：
|
|
|
74
|
+
|
|
|
75
|
+- 配置 bodyParser 解析请求体
|
|
|
76
|
+- 配置静态文件服务
|
|
|
77
|
+- 设置错误处理中间件
|
|
|
78
|
+- 配置会话管理
|
|
|
79
|
+- 注册各模块路由
|
|
|
80
|
+- 启动服务器监听
|
|
|
81
|
+
|
|
|
82
|
+#### 3.2.2 API 模块
|
|
|
83
|
+
|
|
|
84
|
+每个 API 模块通常包含两个主要文件：
|
|
|
85
|
+- **routes.js**: 定义路由和 URL 映射
|
|
|
86
|
+- **xxxController.js**: 实现具体的业务逻辑和请求处理
|
|
|
87
|
+
|
|
|
88
|
+API 模块按功能领域划分，包括：
|
|
|
89
|
+- **common**: 通用功能，如文件上传、内容安全检查等
|
|
|
90
|
+- **hanzi**: 汉字学习相关功能
|
|
|
91
|
+- **mathcalculate**: 数学计算相关功能
|
|
|
92
|
+- **mps**: MPS 相关功能
|
|
|
93
|
+- **phonics**: 自然拼读相关功能
|
|
|
94
|
+- **pinyin**: 拼音学习相关功能
|
|
|
95
|
+- **web**: Web 端相关功能
|
|
|
96
|
+- **yjbdc**: 英语百词斩相关功能
|
|
|
97
|
+
|
|
|
98
|
+#### 3.2.3 配置管理
|
|
|
99
|
+
|
|
|
100
|
+配置管理采用环境分离的方式，通过 `process.env.NODE_ENV` 区分开发环境和生产环境：
|
|
|
101
|
+- **dev.js**: 开发环境特定配置
|
|
|
102
|
+- **prod.js**: 生产环境特定配置
|
|
|
103
|
+- **index.js**: 主配置文件，包含通用配置和环境特定配置的整合
|
|
|
104
|
+
|
|
|
105
|
+配置内容包括：
|
|
|
106
|
+- 服务器端口
|
|
|
107
|
+- 数据库连接参数
|
|
|
108
|
+- 会话配置
|
|
|
109
|
+- 微信应用配置（多个小程序的 appid 和 secret）
|
|
|
110
|
+- 云服务配置（腾讯云、百度云等）
|
|
|
111
|
+
|
|
|
112
|
+#### 3.2.4 中间件
|
|
|
113
|
+
|
|
|
114
|
+系统使用多个中间件增强功能和安全性：
|
|
|
115
|
+- **queryParamSanitizer.js**: 查询参数清理，防止注入攻击
|
|
|
116
|
+- **upload.js**: 文件上传处理
|
|
|
117
|
+- **decryptUrlMiddle**: URL 解密中间件（来自 crypto 工具）
|
|
|
118
|
+
|
|
|
119
|
+#### 3.2.5 数据模型
|
|
|
120
|
+
|
|
|
121
|
+数据模型层负责与数据库交互和业务数据处理：
|
|
|
122
|
+- **BufferMemoryClass.js**: 内存缓存管理
|
|
|
123
|
+- **commonModel.js**: 通用数据模型
|
|
|
124
|
+- 各功能模块特定模型（hanzi.js, phonics.js 等）
|
|
|
125
|
+
|
|
|
126
|
+#### 3.2.6 工具类
|
|
|
127
|
+
|
|
|
128
|
+系统包含多个工具类，提供通用功能：
|
|
|
129
|
+- **db.js**: 数据库连接和操作
|
|
|
130
|
+- **GlobalCache.js**: 全局缓存管理
|
|
|
131
|
+- **stringClass.js**: 字符串处理工具
|
|
|
132
|
+- **WXBizDataCrypt.js**: 微信数据解密
|
|
|
133
|
+- **crypto/**: 加密解密工具
|
|
|
134
|
+
|
|
|
135
|
+## 4. 数据流
|
|
|
136
|
+
|
|
|
137
|
+1. 客户端发送 HTTP 请求到服务器
|
|
|
138
|
+2. Koa 中间件链处理请求（body 解析、参数清理、会话管理等）
|
|
|
139
|
+3. 路由匹配将请求分发到对应的控制器方法
|
|
|
140
|
+4. 控制器调用模型层处理业务逻辑和数据操作
|
|
|
141
|
+5. 模型层与数据库或外部 API 交互
|
|
|
142
|
+6. 控制器接收处理结果，构造响应
|
|
|
143
|
+7. 中间件链处理响应
|
|
|
144
|
+8. 响应返回给客户端
|
|
|
145
|
+
|
|
|
146
|
+## 5. 安全机制
|
|
|
147
|
+
|
|
|
148
|
+- 使用 queryParamSanitizer 中间件防止 SQL 注入和 XSS 攻击
|
|
|
149
|
+- 会话管理使用签名 cookie 和 httpOnly 标志
|
|
|
150
|
+- 生产环境使用 secure cookie（仅 HTTPS）
|
|
|
151
|
+- 微信数据解密工具保护用户数据安全
|
|
|
152
|
+- URL 解密中间件增强 API 安全性
|
|
|
153
|
+
|
|
|
154
|
+## 6. 扩展性设计
|
|
|
155
|
+
|
|
|
156
|
+系统采用模块化设计，便于扩展新功能：
|
|
|
157
|
+1. 创建新的 API 模块目录
|
|
|
158
|
+2. 实现路由和控制器
|
|
|
159
|
+3. 创建相应的数据模型
|
|
|
160
|
+4. 在 app.js 中注册新路由
|
|
|
161
|
+
|
|
|
162
|
+## 7. 部署架构
|
|
|
163
|
+
|
|
|
164
|
+系统支持开发和生产两种环境部署：
|
|
|
165
|
+- 开发环境：使用 `npm run dev` 启动，加载开发配置
|
|
|
166
|
+- 生产环境：使用 `npm start` 启动，加载生产配置
|
|
|
167
|
+
|
|
|
168
|
+服务器要求：
|
|
|
169
|
+- Node.js v24.1.0
|
|
|
170
|
+- MySQL 数据库
|
|
|
171
|
+- 适当的网络访问权限（用于访问外部 API）
|
|
|
172
|
+
|
|
|
173
|
+## 8. 依赖服务
|
|
|
174
|
+
|
|
|
175
|
+- MySQL 数据库：存储应用数据
|
|
|
176
|
+- 腾讯云 OCR：文字识别服务
|
|
|
177
|
+- 腾讯云对象存储：文件存储服务
|
|
|
178
|
+- 微信开放平台：小程序授权和服务
|
|
|
179
|
+- 百度 AI 平台：AI 相关服务
|
|
|
180
|
+
|
|
|
181
|
+## 9. 监控与日志
|
|
|
182
|
+
|
|
|
183
|
+系统使用 console.log 进行基本日志记录，关键点包括：
|
|
|
184
|
+- 服务器启动信息
|
|
|
185
|
+- 错误处理和异常捕获
|
|
|
186
|
+- API 调用错误
|
|
|
187
|
+
|
|
|
188
|
+## 10. 未来优化方向
|
|
|
189
|
+
|
|
|
190
|
+1. 引入专业日志系统，替代 console.log
|
|
|
191
|
+2. 增强错误处理和监控机制
|
|
|
192
|
+3. 实现更完善的缓存策略
|
|
|
193
|
+4. 考虑引入 TypeScript 增强类型安全
|
|
|
194
|
+5. 增加自动化测试覆盖
|
|
|
195
|
+6. 优化数据库连接池管理
|
|
|
196
|
+7. 考虑引入容器化部署
|
