Appearance
开发文档概述
简介
欢迎来到日志APP开发文档。本文档提供了完整的技术细节,帮助开发者理解、维护和扩展日志APP系统。
面向读者
本文档面向以下人员:
- 🔧 后端开发者: 了解API设计、数据库结构、服务端逻辑
- 📱 Android开发者: 了解应用架构、UI组件、业务逻辑
- 🧪 测试工程师: 了解功能模块、测试要点
- 🚀 运维工程师: 了解部署流程、服务器配置
- 📊 技术管理者: 了解整体架构、技术选型
技术栈总览
Android端
yaml
语言: Kotlin 1.9.0
最小SDK: 26 (Android 8.0)
目标SDK: 34 (Android 14.0)
核心框架:
- Jetpack Compose 1.5.0 # 声明式UI
- Kotlin Coroutines 1.7.3 # 异步编程
- Kotlin Flow # 响应式流
架构组件:
- Hilt 2.48 # 依赖注入
- Room 2.6.0 # 本地数据库
- Navigation 2.7.0 # 页面导航
- DataStore 1.0.0 # 数据存储
- Lifecycle 2.6.0 # 生命周期管理
网络层:
- Retrofit 2.9.0 # HTTP客户端
- OkHttp 4.11.0 # HTTP引擎
- Gson 2.10.1 # JSON序列化
图片加载:
- Coil 2.4.0 # 图片加载库
推送服务:
- Firebase Messaging # Firebase推送
- Huawei Push Kit # 华为推送
- Xiaomi Push SDK # 小米推送
- OPPO Push SDK # OPPO推送
- Vivo Push SDK # Vivo推送
- Honor Push SDK # 荣耀推送
第三方集成:
- DingTalk SDK # 钉钉集成
- Baidu Map SDK # 百度地图后端
yaml
运行环境: Node.js 18.x
包管理: npm
核心框架:
- Express 4.18.0 # Web框架
- Socket.IO 4.6.0 # WebSocket
数据库:
- MySQL 8.0 # 关系型数据库
- mysql2 3.3.0 # MySQL驱动
认证授权:
- jsonwebtoken 9.0.0 # JWT Token
- bcrypt 5.1.0 # 密码加密
文件处理:
- multer 1.4.5 # 文件上传
- sharp 0.32.0 # 图片处理
HTTP客户端:
- axios 1.4.0 # HTTP请求
推送服务:
- firebase-admin 11.x # Firebase Admin SDK
工具库:
- dotenv 16.0.3 # 环境变量
- cors 2.8.5 # 跨域处理
- morgan 1.10.0 # 日志记录基础设施
yaml
服务器:
- 阿里云ECS
- CentOS 7
- 2核4G配置
数据库:
- 阿里云RDS MySQL 8.0
- 主从复制(计划中)
域名:
- bjbmkj.cn # 主域名
- API: 8.147.129.77:3003 # API地址
进程管理:
- nohup # 后台运行
- PM2 (计划中) # 进程守护
反向代理:
- Nginx (计划中) # 负载均衡
监控:
- 日志监控 (计划中)
- 性能监控 (计划中)核心功能模块
1. 认证授权模块
- 钉钉企业认证
- JWT Token管理
- 角色权限控制
- 会话管理
2. 工作日志模块
- 日志创建/编辑/删除
- 照片上传和压缩
- 项目关联
- 接收人管理
- 可见性控制
3. 任务管理模块
- 待办任务管理
- 任务状态流转
- 优先级设置
- 工时估算
- 截止时间提醒
4. 实时消息模块
- WebSocket连接
- 即时消息收发
- 已读回执
- 离线消息
- 消息推送
5. 项目管理模块
- 项目创建/编辑
- GPS定位
- 项目类型管理
- 项目成员管理
6. 车辆签到模块
- GPS轨迹跟踪
- 签到记录
- 里程统计
- 停靠点识别
7. 数据统计模块
- 月度报告
- Excel导出
- 工时统计
- 项目统计
8. 推送通知模块
- 多厂商推送
- Token管理
- 消息去重
- 推送历史
9. 管理员模块
- 用户管理
- 任务分配
- 系统日志
- 权限配置
架构设计
Android架构
采用Clean Architecture + MVVM:
┌─────────────────────────────────────────┐
│ Presentation Layer │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Composables │◄───│ ViewModels │ │
│ └──────────────┘ └──────────────┘ │
└──────────────────┬──────────────────────┘
│
┌──────────────────▼──────────────────────┐
│ Domain Layer │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Use Cases │ │ Models │ │
│ └──────────────┘ └──────────────┘ │
└──────────────────┬──────────────────────┘
│
┌──────────────────▼──────────────────────┐
│ Data Layer │
│ ┌────────────┐ ┌────────┐ ┌───────┐ │
│ │Repositories│ │ Room │ │Network│ │
│ └────────────┘ └────────┘ └───────┘ │
└─────────────────────────────────────────┘优势:
- ✅ 清晰的职责分离
- ✅ 易于测试
- ✅ 可维护性高
- ✅ 易于扩展
后端架构
采用经典的MVC模式:
┌─────────────────────────────────────────┐
│ Routes (Controller) │
│ ┌──────────┐ ┌──────────┐ ┌────────┐│
│ │ /api/logs│ │/api/tasks│ │/api/...││
│ └─────┬────┘ └─────┬────┘ └────┬───┘│
└────────┼─────────────┼────────────┼────┘
│ │ │
┌────────▼─────────────▼────────────▼────┐
│ Business Logic (Services) │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Auth Service │ │ Push Service │ │
│ └──────────────┘ └──────────────┘ │
└────────────────┬────────────────────────┘
│
┌────────────────▼────────────────────────┐
│ Data Access (Database) │
│ MySQL Queries │
└─────────────────────────────────────────┘数据流
请求流程
User Action
↓
Composable UI
↓
ViewModel
↓
UseCase
↓
Repository
↓
API Service / Local Database
↓
Backend Server
↓
MySQL Database响应流程
MySQL Database
↓
Backend Response
↓
Repository (Cache)
↓
Flow/LiveData
↓
ViewModel State
↓
Composable Recompose
↓
UI Update关键技术点
1. 响应式编程
使用Kotlin Flow实现响应式数据流:
kotlin
// Repository层返回Flow
fun getLogs(): Flow<List<Log>> = flow {
// 先发送缓存数据
emit(localDataSource.getLogs())
// 再获取网络数据
val remoteLogs = remoteDataSource.getLogs()
localDataSource.saveLogs(remoteLogs)
emit(remoteLogs)
}
// ViewModel层收集
viewModelScope.launch {
repository.getLogs()
.catch { handleError(it) }
.collect { logs ->
_uiState.update { it.copy(logs = logs) }
}
}2. 依赖注入
使用Hilt简化依赖管理:
kotlin
@Module
@InstallIn(SingletonComponent::class)
object NetworkModule {
@Provides
@Singleton
fun provideRetrofit(): Retrofit {
return Retrofit.Builder()
.baseUrl(Constants.BASE_URL)
.addConverterFactory(GsonConverterFactory.create())
.build()
}
}3. 状态管理
使用UiState模式管理UI状态:
kotlin
data class LogListUiState(
val logs: List<Log> = emptyList(),
val isLoading: Boolean = false,
val error: String? = null
)
// ViewModel中
private val _uiState = MutableStateFlow(LogListUiState())
val uiState: StateFlow<LogListUiState> = _uiState.asStateFlow()4. 错误处理
统一的错误处理机制:
kotlin
sealed class Result<out T> {
data class Success<T>(val data: T) : Result<T>()
data class Error(val exception: Exception) : Result<Nothing>()
object Loading : Result<Nothing>()
}开发环境搭建
Android开发环境
安装Android Studio
- 下载Android Studio Hedgehog或更高版本
- 安装Android SDK 26-34
配置Gradle
- JDK 17
- Gradle 8.0+
克隆项目
bash
git clone <repository-url>
cd android_app同步依赖
- 打开Android Studio
- 等待Gradle同步完成
运行应用
- 连接Android设备或启动模拟器
- 点击Run按钮
后端开发环境
安装Node.js
- 下载Node.js 18.x LTS版本
- 验证安装:
node --version
克隆项目
bash
git clone <repository-url>
cd backend- 安装依赖
bash
npm install配置环境变量
- 复制
.env.example为.env - 填写数据库连接信息
- 配置Firebase等第三方服务
- 复制
启动服务
bash
npm run dev # 开发模式
npm start # 生产模式文档导航
获取帮助
如果在开发过程中遇到问题:
- 查阅本文档相关章节
- 查看代码注释和示例
- 联系项目负责人
- 提交Issue (如果使用Git管理)
贡献指南
参与项目开发请遵循:
- 遵守代码规范
- 编写单元测试
- 更新相关文档
- 提交清晰的Commit信息
- Code Review后合并代码
