Skip to content

开发文档概述 ​

简介 ​

欢迎来到日志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开发环境 ​

  1. 安装Android Studio

    • 下载Android Studio Hedgehog或更高版本
    • 安装Android SDK 26-34
  2. 配置Gradle

    • JDK 17
    • Gradle 8.0+
  3. 克隆项目

bash
git clone <repository-url>
cd android_app
  1. 同步依赖

    • 打开Android Studio
    • 等待Gradle同步完成
  2. 运行应用

    • 连接Android设备或启动模拟器
    • 点击Run按钮

后端开发环境 ​

  1. 安装Node.js

    • 下载Node.js 18.x LTS版本
    • 验证安装: node --version
  2. 克隆项目

bash
git clone <repository-url>
cd backend
  1. 安装依赖
bash
npm install
  1. 配置环境变量

    • 复制.env.example为.env
    • 填写数据库连接信息
    • 配置Firebase等第三方服务
  2. 启动服务

bash
npm run dev  # 开发模式
npm start    # 生产模式

文档导航 ​

获取帮助 ​

如果在开发过程中遇到问题:

  1. 查阅本文档相关章节
  2. 查看代码注释和示例
  3. 联系项目负责人
  4. 提交Issue (如果使用Git管理)

贡献指南 ​

参与项目开发请遵循:

  1. 遵守代码规范
  2. 编写单元测试
  3. 更新相关文档
  4. 提交清晰的Commit信息
  5. Code Review后合并代码

炳明一企通正式版 · 企业服务与协同管理