应用包管理API

引用文件

本文档引用的文件

简介

本文件面向应用包管理API，系统性梳理应用安装查询接口、应用包名管理接口、应用安装统计接口等核心能力。重点说明应用包数据结构、安装状态跟踪、包名匹配规则、统计分析接口，并提供查询示例、安装流程说明与数据同步机制。

项目结构

应用包管理API位于设备模块（device）中，采用“API接口 + 控制器 + 业务服务 + 数据对象”的分层设计，配合数据分析模块的安装统计表，形成“实时上报 + 离线聚合”的完整链路。

Mermaid Diagram Code:

graph TB
subgraph "设备模块"
API["AppPackageNameApi 接口"]
API_IMPL["AppPackageNameApiImpl 实现"]
SVC["AppPackageNameService 服务接口"]
SVC_IMPL["AppPackageNameServiceImpl 服务实现"]
CTRL["AppPackageNameController 控制器"]
DTO1["AppPackageNameDTO"]
DTO2["AppInstallCountPackageDTO"]
DTO3["AppInstallPackageDTO"]
end
subgraph "数据分析模块"
DOC1["app-install-list 文档"]
end
API --> API_IMPL
API_IMPL --> SVC
SVC_IMPL --> SVC
CTRL --> SVC
API_IMPL --> DTO1
API_IMPL --> DTO2
API_IMPL --> DTO3
SVC_IMPL -.-> DOC1

图表来源

章节来源

核心组件

包名管理接口层：提供REST风格RPC接口，供内部模块或外部系统调用，包括“快速插入/获取包名”、“基础信息查询”、“按版本分组查询”、“包名模糊查询”等。
包名业务服务层：负责包名的创建、更新、删除、分页查询、基础信息查询、快速插入/获取、包名到应用名映射等。
控制器层：管理后台提供包名的增删改查、分页、导出Excel等能力。
数据传输对象（DTO/VO）：封装包名、安装统计、安装明细等数据结构，支撑接口返回与前端展示。
数据分析层：提供安装列表的实时与离线处理流程，支撑包名统计与设备统计两类视图。

章节来源

架构总览

应用包管理API采用“接口层 + 业务层 + 控制器层 + 数据层”的分层架构，结合数据分析模块的实时与离线处理，形成完整的应用包生命周期管理闭环。

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant API as "AppPackageNameApiImpl"
participant Svc as "AppPackageNameService"
participant SvcBiz as "AppPackageNameServiceImpl"
participant StatSvc as "AppInstallCountPackageService"
Client->>API : GET /appPackageName/quick-insert?packageName=...
API->>Svc : insertOrGet(packageName)
Svc->>SvcBiz : insertOrGet(packageName)
SvcBiz-->>Svc : AppPackageNameDO
Svc-->>API : AppPackageNameDO
API-->>Client : AppPackageNameDTO
Client->>API : GET /appPackageName/allBaseInfoQuery
API->>Svc : allBaseInfoQuery(...)
Svc->>SvcBiz : allBaseInfoQuery(...)
SvcBiz->>StatSvc : getLastOneByPackageName(...)
SvcBiz-->>Svc : List<AppPackageNameRespVO>
Svc-->>API : List<AppPackageNameRespVO>
API-->>Client : List<AppPackageNameDTO>

图表来源

章节来源

详细组件分析

包名管理接口层（Feign RPC）

快速插入/获取包名：若不存在则创建并返回，存在则直接返回，便于设备侧快速识别与落库。
基础信息查询：支持按包名模糊查询、按使用场景（运行记录/安装列表）过滤。
按版本分组查询：支持按版本号分组或不分组，返回包名+版本维度的统计信息。
包名模糊查询：根据APP名称模糊匹配返回包名列表。
最近一条安装统计查询：按包名查询最近一条安装统计记录。

Mermaid Diagram Code:

classDiagram
class AppPackageNameApi {
+insertOrGet(packageName) CommonResult~AppPackageNameDTO~
+allBaseInfoQuery(packageName, useAppRuntime, useAppInstall) CommonResult~AppPackageNameDTO[]~
+getBaseInfoGroupByVersionCode(useAppRuntime, useAppInstall) CommonResult~AppInstallPackageDTO[]~
+getPackageName(useAppRuntime, useAppInstall) CommonResult~String[]~
+baseInfoAddAppName(packageNames) CommonResult~AppInstallPackageDTO[]~
+getLastOneAppInstallCountPackageByPackageName(packageName) CommonResult~AppInstallCountPackageDTO~
+getPackageNamesLikeAppName(appName) CommonResult~String[]~
}

图表来源

AppPackageNameApi.java

章节来源

AppPackageNameApi.java

包名业务服务层

创建/更新/删除：校验包名唯一性，更新时避免重复；删除时同步清理缓存。
分页查询：支持按APP名称（模糊匹配包名）、状态位过滤（运行记录/安装列表）。
基础信息查询：支持按包名模糊查询与状态位过滤，同时补充应用名（从安装统计表取最新值）。
快速插入/获取：不存在则创建，状态位默认启用“运行记录”和“安装列表”，并写入缓存。
包名到应用名映射：从安装统计表取最新一条记录的应用名。

Mermaid Diagram Code:

flowchart TD
Start(["进入 insertOrGet"]) --> Q["按包名查询是否存在"]
Q --> |存在| Return["直接返回"]
Q --> |不存在| Build["构造新包名对象<br/>设置状态位为启用运行记录与安装列表"]
Build --> Insert["插入数据库"]
Insert --> Cache["写入缓存"]
Cache --> End(["返回"])
Return --> End

图表来源

AppPackageNameServiceImpl.java

章节来源

管理后台控制器

提供包名的增删改查、分页、导出Excel等能力，权限控制严格，支持按包名/APP名称/使用场景筛选。

章节来源

AppPackageNameController.java

数据传输对象（DTO/VO）

包名DTO：包含包名、应用名、描述、创建/更新时间、使用场景标记等。
安装统计DTO：包含包名、应用名、启动类名、统计月份、版本信息、设备数量、创建时间等。
安装明细DTO：包含包名、应用名、版本号、创建/更新时间等。

章节来源

安装统计接口与数据同步机制

包名统计接口：支持按APP名称、包名、版本号、版本名称、统计月份、是否按版本号分组等条件查询，支持导出。
设备统计接口：支持按MAC/CPU、APP名称/包名/版本名称、统计月份等条件查询，支持导出。
数据同步机制：采用“实时入库 + 离线聚合”的架构，设备上报数据先写入设备维度表，再由离线任务转换为包名维度并生成包名统计表。

Mermaid Diagram Code:

flowchart TD
Dev["设备终端"] --> MQ["Kafka 消息队列"]
MQ --> C1["实时消费层<br/>AppInstallListConsumer"]
C1 --> T1["设备维度表 app_install_device_MM"]
T1 --> J1["离线任务 appInstallDeviceToPackage"]
J1 --> T2["包名维度表 app_install_package_MM"]
T2 --> J2["离线任务 appinstallCountByPackageName"]
J2 --> T3["包名统计表 app_install_count_package_MM"]
style C1 fill:#e1f5fe,stroke:#01579b
style J1 fill:#fff3e0,stroke:#e65100
style J2 fill:#fff3e0,stroke:#e65100
style T1 fill:#f1f8e9,stroke:#33691e
style T2 fill:#f1f8e9,stroke:#33691e
style T3 fill:#f1f8e9,stroke:#33691e

图表来源

app-install-list.md

章节来源

app-install-list.md

依赖关系分析

接口层依赖业务服务层，实现层依赖服务接口与DAO层。
业务服务层依赖安装统计服务，用于从统计表获取应用名与最新记录。
控制器层依赖业务服务层，提供管理后台能力。
数据对象层贯穿接口、服务、控制器与DAO层。

Mermaid Diagram Code:

graph LR
API["AppPackageNameApi"] --> IMPL["AppPackageNameApiImpl"]
IMPL --> SVC["AppPackageNameService"]
IMPL --> STAT_SVC["AppInstallCountPackageService"]
CTRL["AppPackageNameController"] --> SVC
SVC --> IMPL
IMPL --> DTO1["AppPackageNameDTO"]
IMPL --> DTO2["AppInstallCountPackageDTO"]
IMPL --> DTO3["AppInstallPackageDTO"]

图表来源

章节来源

性能考虑

包名快速插入/获取：通过数据库唯一约束与状态位位运算，减少重复创建与复杂判断。
分页查询优化：支持按APP名称模糊匹配包名，结合安装统计服务获取应用名，避免多次跨表查询。
缓存策略：创建/更新/删除包名时同步写入/删除缓存，降低重复查询成本。
离线聚合：安装统计采用离线任务聚合，避免高频查询对实时表造成压力。

[本节为通用性能建议，无需具体文件引用]

故障排除指南

包名重复创建：创建时会校验包名唯一性，若已存在则抛出异常；请确认包名是否正确。
包名不存在：删除后可能影响其他模块识别，请谨慎操作。
包名状态位：默认启用“运行记录”和“安装列表”，如需调整请通过更新接口修改。
缓存一致性：删除包名后采用延时双删策略，确保缓存与数据库一致。

章节来源

结论

应用包管理API围绕“包名管理 + 安装统计 + 数据同步”三大能力构建，既满足实时场景的快速识别需求，又通过离线聚合提供稳定高效的统计分析能力。通过清晰的分层设计与完善的缓存策略，系统在可用性与性能之间取得良好平衡。

[本节为总结性内容，无需具体文件引用]

附录

接口清单与示例路径

快速插入/获取包名
- 接口：GET /appPackageName/quick-insert
- 示例路径：AppPackageNameApi.java
基础信息查询
- 接口：GET /appPackageName/allBaseInfoQuery
- 示例路径：AppPackageNameApi.java
按版本分组查询
- 接口：GET /appPackageName/getBaseInfoGroupByVersionCode
- 示例路径：AppPackageNameApi.java
包名模糊查询
- 接口：GET /appPackageName/getPackageNamesLikeAppName
- 示例路径：AppPackageNameApi.java
最近一条安装统计
- 接口：GET /appPackageName/getLastOneAppInstallCountPackageByPackageName
- 示例路径：AppPackageNameApi.java

包名匹配规则

包名唯一性：创建时校验包名唯一，避免重复。
状态位过滤：支持按“是否用于APP运行记录/安装列表”进行过滤。
应用名映射：从安装统计表取最新记录的应用名，确保展示准确性。

章节来源

安装流程说明

设备上报：设备定时采集非系统APP列表或通过事件上报接口发送APP_INSTALL事件。
实时入库：监听Kafka主题，按月分表写入设备维度表。
离线转换：将设备维度数据转换为包名维度数据。
统计聚合：按包名维度统计安装设备数量，生成包名统计表。

章节来源

app-install-list.md

数据同步机制

实时层：Kafka消费 + 设备维度表（app_install_device_MM）。
离线层：维度转换任务（appInstallDeviceToPackage） + 包名维度表（app_install_package_MM）。
统计层：聚合任务（appinstallCountByPackageName） + 包名统计表（app_install_count_package_MM）。

章节来源

app-install-list.md

目录​

简介​

项目结构​

核心组件​

架构总览​

详细组件分析​

包名管理接口层（Feign RPC）​

包名业务服务层​

管理后台控制器​

数据传输对象（DTO/VO）​

安装统计接口与数据同步机制​

依赖关系分析​

性能考虑​

故障排除指南​

结论​

附录​

接口清单与示例路径​

包名匹配规则​

安装流程说明​

数据同步机制​

目录

简介

项目结构

核心组件

架构总览

详细组件分析

包名管理接口层（Feign RPC）

包名业务服务层

管理后台控制器

数据传输对象（DTO/VO）

安装统计接口与数据同步机制

依赖关系分析

性能考虑

故障排除指南

结论

附录

接口清单与示例路径

包名匹配规则

安装流程说明

数据同步机制