微光录
← 返回列表

「仓库」库存管理系统 — 项目架构分析

#harmonyos#arkts#库存系统

📁 项目概览

项目 信息
应用名称 仓库 (com.example.cangku)
版本 1.0.0
SDK HarmonyOS (API级别待确认, 使用 @kit.* 新API)
设备类型 Phone
包类型 entry (单一HAP)

🏗️ 整体目录结构

cangku/
├── AppScope/
│   └── app.json5                   # 应用级配置 (bundleName, version等)
├── entry/
│   ├── src/main/
│   │   ├── module.json5            # 模块配置 (权限、abilities)
│   │   ├── resources/base/profile/
│   │   │   └── main_pages.json     # 页面路由注册表
│   │   └── ets/
│   │       ├── entryability/
│   │       │   └── EntryAbility.ets # 应用入口 (UIAbility)
│   │       ├── pages/               # 页面层 (16个页面)
│   │       │   ├── Index.ets        # 主界面 (4 Tab 容器)
│   │       │   ├── HomeTab.ets      # Tab1: 首页概览
│   │       │   ├── InventoryTab.ets # Tab2: 库存管理
│   │       │   ├── InventoryCheckTab.ets # Tab3: 库存盘点
│   │       │   ├── SettingsTab.ets  # Tab4: 设置
│   │       │   ├── AddItem.ets      # 添加物品
│   │       │   ├── EditItem.ets     # 编辑物品
│   │       │   ├── ItemDetail.ets   # 物品详情
│   │       │   ├── CategoryList.ets # 分类列表
│   │       │   ├── CategoryItems.ets# 分类下物品
│   │       │   ├── PhotoImport.ets  # 扫码/拍照导入
│   │       │   ├── JlcscImport.ets  # 嘉立创商城导入
│   │       │   ├── JlcscApiConfig.ets # 嘉立创API配置
│   │       │   └── (TestPage*.ets)  # 测试页面 (约9个)
│   │       └── common/
│   │           ├── config/
│   │           │   └── AppConfig.ets        # 全局配置 (单例)
│   │           ├── theme/
│   │           │   └── Theme.ets            # 设计系统 (318行)
│   │           ├── mock/
│   │           │   └── MockData.ets         # 模拟数据层 (594行)
│   │           ├── model/
│   │           │   ├── JlcscProduct.ets     # 嘉立创商品模型
│   │           │   └── JlcscConfig.ets      # 嘉立创配置模型
│   │           ├── network/
│   │           │   └── HttpClient.ets       # HTTP封装
│   │           ├── service/
│   │           │   ├── JlcscAuthService.ets # 嘉立创鉴权 (283行)
│   │           │   └── JlcscService.ets     # 嘉立创API业务 (274行)
│   │           └── ui/
│   │               └── AppComponents.ets    # 通用UI组件库 (881行)
│   └── hvigorfile.ts              # Hvigor构建脚本
├── build-profile.json5            # 项目级构建配置
└── .hvigor / .idea / .workbuddy  # IDE/构建缓存

🧩 分层架构

采用 4层架构 设计，职责清晰：

┌─────────────────────────────────────────────────────┐
│                   页面层 (Pages)                      │
│  Index, HomeTab, InventoryTab, AddItem, ItemDetail  │
│  PhotoImport, JlcscImport, SettingsTab ...          │
├─────────────────────────────────────────────────────┤
│               通用UI组件层 (common/ui)                │
│  AppComponents (AppPage, AppHeader, AppGroup, ...)  │
├─────────────────────────────────────────────────────┤
│                业务服务层 (common/)                   │
│  ├─ service/    JlcscAuthService, JlcscService      │
│  ├─ network/    HttpClient                          │
│  ├─ mock/       MockData (内存数据 + CRUD操作)       │
│  ├─ model/      JlcscProduct, JlcscConfig           │
│  └─ config/     AppConfig (单例)                    │
├─────────────────────────────────────────────────────┤
│               基础设施层 (common/theme)               │
│  Theme.ets — 完整的设计系统 (颜色/间距/圆角/字号)     │
└─────────────────────────────────────────────────────┘

📄 页面路由 (main_pages.json)

已注册 20个页面路由：

路由 功能
Index 主界面 — 4 Tab 容器 (首页/库存/盘点/设置)
HomeTab 首页概览 (部件为 Tab 内嵌组件)
InventoryTab 库存管理 (Tab 内嵌)
InventoryCheckTab 库存盘点 (Tab 内嵌)
SettingsTab 设置 (Tab 内嵌)
AddItem 添加库存物品
EditItem 编辑库存物品
ItemDetail 物品详情
CategoryList 分类列表
CategoryItems 分类下物品列表
PhotoImport 扫码/拍照导入物品
JlcscImport 嘉立创商城API导入
JlcscApiConfig 嘉立创API密钥配置
TestPage* × 9 测试页面

🔑 核心设计亮点

1. 🎨 响应式主题系统 (Theme.ets)

  • 3种模式: system | light | dark
  • 通过 @StorageLink('themeState') 全局共享，切换无需重启
  • 完全组件化配色: 所有颜色/圆角/间距/字号/边框/透明度以令牌(token)形式集中管理
  • 组件禁止直接写 #xxxxxx，统一通过 this.theme.colors.xxx 引用
  • Edge-to-Edge 状态栏跟随主题

2. 🧩 底部导航栏 — 光追动效

  • Index.ets 中实现 4 Tab 底部导航栏
  • 创新性 光追效果 (light tracing)：Touch 位置磁吸 + 液体阻尼动画
  • 导航项使用 HarmonyOS System Symbol (Vector图标)

3. 📦 库存数据模型 (MockData.ets)

  • 双存储模型:
    • grid (盒装): 盒子按 rows × columns 划分格子，一格一物
    • bag (袋装): 每个袋子独立存储单元
  • 当前使用 内存模拟数据 (标注后续替换为本地数据库)
  • 公开完整 CRUD 操作函数 (addItem, updateBox, deleteBox 等)

4. 🔒 嘉立创鉴权安全设计 (JlcscAuthService.ets)

  • App ID / AccessKey: Preferences 明文存储
  • SecretKey: HUKS AES-256 GCM 加密后存储 (安全硬件管理密钥)
  • 每次加密生成随机 IV，Base64(IV + 密文 + AuthTag) 持久化

5. 🚀 页面导航方式

  • Tab 内页面使用 组件嵌入 (结构体)
  • 独立页面使用 router.pushUrl 导航 (如 AddItem, ItemDetail)
  • 页面间传参通过 router.getParams() 获取

🔌 外部集成

集成 状态 详情
嘉立创商城 API ✅ 已实现 商品查询 (JlcscService), 鉴权 (JlcscAuthService), 签名 (JlcscSignature)
扫码/拍照 ✅ 已实现 scanBarcode, scanCore (ScanKit)，需 Camera 权限
网络请求 ✅ 已实现 HttpClient.postJson 封装
本地持久化 🔄 部分 Preferences (主题设置/API配置)，MockData 仍为内存数据
数据库 ❌ 待实现 MockData 注释标注 "后续替换为本地数据库"

📋 module.json5 权限清单

权限 用途
ohos.permission.INTERNET 嘉立创API网络请求
ohos.permission.CAMERA 扫码拍照 (仅前台使用)

⚠️ 架构中可改进的方面

  1. 数据层 — MockData 使用内存数组，缺乏持久化，注释已标注待替换为本地数据库
  2. 状态管理 — 未使用 @Provide/@Consume 层级传递，部分组件直接依赖 AppStorage
  3. 测试页面 — 存在大量 TestPage 残留，可在发布前清理
  4. JlcscSignature.ets — 文件引用但不存在 (路径差异，可能在 utils/ 下)
  5. 模块粒度 — 当前为单 entry HAP，后续可拆分为 feature HAP 或 HAR 共享组件

以上就是项目的整体架构分析。您希望对哪一层或哪个模块做深入探讨吗？