Project Architecture - langningchen/miniapp GitHub Wiki

项目架构说明

本文档详细解释 miniapp 项目的整体架构、各模块功能和代码组织结构。

🏗️ 项目总览

miniapp 是一个为有道词典笔开发的应用程序，采用混合架构设计：

前端：基于 Vue.js 的用户界面
后端：C++ 编写的核心功能模块
桥接：JavaScript API 连接前后端

📁 目录结构详解

miniapp/
├── 📄 README.md                    # 项目说明文档
├── 📄 LICENSE                      # GPL v3.0 许可证
├── 📄 pnpm-lock.yaml              # pnpm 依赖锁定文件
├── 📄 pnpm-workspace.yaml         # pnpm 工作空间配置
├── 🗂️ jsapi/                       # C++ 后端核心模块
├── 🗂️ ui/                          # Vue.js 前端界面
├── 🗂️ tools/                       # 构建和部署脚本
└── 🗂️ wiki/                        # 项目文档

🔧 核心模块架构

jsapi/ - C++ 后端模块

jsapi/
├── 📄 CMakeLists.txt               # CMake 构建配置
├── 📄 rawdict_utf16_65105_freq.txt # 词典数据文件
├── 🗂️ src/                         # 源代码目录
│   ├── 📄 JSAPI.cpp               # JavaScript API 入口
│   ├── 📄 Fetch.cpp/.hpp          # 网络请求模块
│   ├── 📄 strUtils.cpp/.hpp       # 字符串工具
│   ├── 🗂️ AI/                      # AI 对话模块
│   ├── 🗂️ Database/               # 数据库操作模块
│   ├── 🗂️ IME/                    # 输入法模块
│   └── 🗂️ Exceptions/             # 异常处理模块
├── 🗂️ iot-miniapp-sdk/           # IoT SDK 库
├── 🗂️ toolchains/                # 交叉编译工具链
└── 🗂️ build/                     # 构建输出目录

主要 C++ 模块功能

1. AI 模块 (src/AI/)

AI.cpp/.hpp - AI 核心功能
JSAI.cpp/.hpp - JavaScript AI API 接口
ConversationManager.cpp/.hpp - 对话管理
ConversationNode.hpp - 对话节点定义
ConversationInfo.hpp - 对话信息结构

2. 数据库模块 (src/Database/)

Database.cpp/.hpp - 数据库核心操作
Select.cpp/.hpp - 查询操作
Insert.cpp/.hpp - 插入操作
Update.cpp/.hpp - 更新操作
Delete.cpp/.hpp - 删除操作
Table.cpp/.hpp - 表管理
Size.cpp/.hpp - 数据统计

3. 输入法模块 (src/IME/)

IME.cpp/.hpp - 输入法核心
JSIME.cpp/.hpp - JavaScript 输入法 API
rawdict_data.hpp - 词典数据结构

4. 网络模块 (src/Fetch.cpp/.hpp)

HTTP/HTTPS 请求处理
网络异常处理
响应数据解析

5. 异常处理 (src/Exceptions/)

Exception.hpp - 基础异常类
DatabaseError.hpp - 数据库异常
NetworkError.hpp - 网络异常
CurlError.hpp - CURL 异常
AssertFailed.hpp - 断言异常

ui/ - Vue.js 前端模块

ui/
├── 📄 package.json                # Node.js 项目配置
├── 📄 tsconfig.json              # TypeScript 配置
├── 📄 app_icon.png               # 应用图标
├── 🗂️ src/                        # 源代码目录
│   ├── 📄 app.js                 # 应用入口
│   ├── 📄 app.json               # 应用配置
│   ├── 📄 base-page.js           # 基础页面组件
│   ├── 🗂️ @types/               # TypeScript 类型定义
│   ├── 🗂️ components/           # Vue 组件
│   ├── 🗂️ editor/               # 编辑器组件
│   ├── 🗂️ pages/                # 页面组件
│   ├── 🗂️ styles/               # 样式文件
│   └── 🗂️ utils/                # 工具函数
├── 🗂️ images/                    # 图片资源
└── 🗂️ libs/                      # 编译后的库文件

前端架构特点

1. 组件化设计

components/ - 可复用的 UI 组件
pages/ - 页面级组件
editor/ - 编辑器相关组件

2. TypeScript 支持

@types/ - 自定义类型定义
tsconfig.json - TypeScript 编译配置

3. 样式管理

styles/ - 全局样式和主题
组件级样式隔离

🔄 数据流架构

┌─────────────────┐    JavaScript API    ┌─────────────────┐
│   Vue.js UI    │ ←------------------→ │   C++ Backend   │
│   (前端界面)     │                      │   (核心功能)      │
└─────────────────┘                      └─────────────────┘
         ↓                                         ↓
┌─────────────────┐                      ┌─────────────────┐
│   User Input    │                      │   Database      │
│   (用户输入)     │                      │   (SQLite)      │
└─────────────────┘                      └─────────────────┘
                                                   ↓
                                        ┌─────────────────┐
                                        │   Network API   │
                                        │   (外部服务)     │
                                        └─────────────────┘

🛠️ 构建系统架构

CMake 构建流程

CMakeLists.txt → 配置检查 → 编译源码 → 链接库文件 → 生成可执行文件
     ↓              ↓           ↓          ↓            ↓
  工具链检查    → 依赖检查 → C++编译 → ARM链接 → jsapi_langningchen

前端构建流程

package.json → pnpm install → TypeScript编译 → Vue编译 → 资源打包 → dist/
     ↓             ↓              ↓           ↓          ↓        ↓
  依赖配置   → 依赖下载 → .ts→.js → .vue→.js → 资源优化 → 前端资源

整体打包流程

C++ 编译 ──┐
           ├── 资源整合 → miniapp.amr → 设备部署
前端构建 ──┘

📊 模块依赖关系

graph TD
    A[Vue.js UI] --> B[JavaScript API]
    B --> C[C++ JSAPI Layer]
    C --> D[AI Module]
    C --> E[Database Module]  
    C --> F[IME Module]
    C --> G[Network Module]
    E --> H[SQLite Library]
    G --> I[Curl Library]
    F --> J[Dictionary Data]
    D --> K[Conversation Manager]

🔧 编译依赖架构

系统依赖

Ubuntu/WSL2
    ├── build-essential (GCC/G++)
    ├── cmake (构建系统)
    ├── nodejs (JavaScript运行时)
    ├── pnpm (包管理器)
    └── adb (设备调试)

交叉编译依赖

ARM Toolchain
    ├── arm-buildroot-linux-gnueabihf-gcc
    ├── arm-buildroot-linux-gnueabihf-g++
    └── ARM Sysroot

运行时依赖

有道词典笔系统
    ├── libcurl.so (网络库)
    ├── libsqlite3.so (数据库库)
    └── miniapp运行环境

🚀 启动流程

应用启动序列

系统加载 - 词典笔系统启动应用
C++ 初始化 - 加载 C++ 核心模块
JavaScript 引擎 - 启动 JS 运行环境
前端渲染 - 加载 Vue.js 界面
API 绑定 - 建立前后端通信
用户交互 - 应用准备就绪

模块加载顺序

1. 系统库加载 (libcurl, libsqlite3)
2. C++ 核心模块初始化
3. JavaScript API 层启动
4. 前端资源加载
5. 组件注册和挂载
6. 事件监听器绑定
7. 应用状态初始化

📝 API 设计架构

JavaScript API 层

C++ 功能通过 JavaScript API 暴露给前端：

// AI 功能 API
window.AI = {
    startConversation: function(config) { /* ... */ },
    sendMessage: function(message) { /* ... */ },
    getHistory: function() { /* ... */ }
};

// 数据库 API
window.Database = {
    query: function(sql) { /* ... */ },
    insert: function(table, data) { /* ... */ },
    update: function(table, data, where) { /* ... */ }
};

// 输入法 API
window.IME = {
    getSuggestions: function(input) { /* ... */ },
    selectCandidate: function(index) { /* ... */ }
};

🔒 安全架构

数据安全

SQLite 数据库加密
网络传输 HTTPS
本地存储权限控制

代码安全

输入验证和清理
异常处理机制
内存安全管理

🚀 下一步

了解项目架构后，请继续：

编译流程详解 - 学习如何编译整个项目
设备连接和调试 - 连接设备进行开发

需要深入了解特定模块？ 查看源代码或参考编译流程详解获取更多技术细节。