# Sort Parcle

**Repository Path**: shuzhen83/sort-parcle

## Basic Information

- **Project Name**: Sort Parcle
- **Description**: 单机包裹整理App（Android）
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-17
- **Last Updated**: 2026-10-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="docs/express-ICON.png" width="120" alt="包裹整理图标" />
</p>

<h1 align="center">包裹整理（Sort Parcel）</h1>

<p align="center">多平台快递 · 一处整理</p>

「包裹整理」是一款本地优先的 Android 快递管理应用：把淘宝、京东、拼多多等不同平台的包裹统一记录下来，按取件码、地址、快递公司和平台分类查看，取件后一键归档。

仓库地址：<https://gitee.com/shuzhen83/sort-parcle>

## 功能

- **包裹记录**：取件码、取件地址、快递公司、电商平台、商品名称、运单号
- **取件流程**：待取 / 已取两种状态，已取包裹独立归档页
- **分类浏览**：默认、按取件地址、按快递公司、按电商平台
- **搜索**：按取件码、运单号、商品名称快速查找
- **卡片交互**：商品图片、左滑编辑 / 删除、详情面板
- **备注**：每条包裹可记录多条短备注
- **常用地址**：内置取件地址管理，录入时联动选择
- **数据本地**：Room 数据库 + 应用私有目录图片，不申请网络权限，数据不上传

## 技术栈

| 类别 | 选型 |
|---|---|
| 语言 | Kotlin 2.3.20 |
| UI | Jetpack Compose + Material 3 |
| 导航 | Navigation 3 |
| 持久化 | Room 2.8.5（KSP）、DataStore Preferences |
| 图片 | Coil 3 |
| 序列化 | kotlinx.serialization |
| 构建 | Android Gradle Plugin 9.0.1 / Gradle Wrapper / JDK 17 |

最低支持 Android 7.0（API 24），编译与目标版本为 API 36。

## 项目结构

```text
.
├── app/
│   └── src/
│       ├── main/java/com/example/express/
│       │   ├── data/        # Room 实体、DAO、仓库、图片存储、设置
│       │   ├── ui/          # 首页、编辑、备注、搜索、已取、设置等界面
│       │   ├── theme/       # Material 3 主题与排版
│       │   ├── MainActivity.kt
│       │   ├── Navigation.kt
│       │   └── NavigationKeys.kt
│       ├── test/            # ViewModel 单元测试
│       └── androidTest/     # Compose 界面测试
├── docs/
│   ├── ICON/                # 平台与快递图标素材
│   └── specs/               # 功能规格文档
├── tools/                   # 图标生成、真机 UI 回归脚本
└── gradle/                  # 版本目录与 Wrapper
```

## 构建与运行

### 环境要求

- JDK 17
- Android SDK Platform 36
- Android 7.0+ 设备或模拟器

### 构建 Debug 包

```bash
# Linux / macOS
./gradlew :app:assembleDebug

# Windows
gradlew.bat :app:assembleDebug
```

产物位于 `app/build/outputs/apk/debug/app-debug.apk`。

也可以直接用 Android Studio 打开项目运行，首次打开会自动生成指向本机 SDK 的 `local.properties`。

### Release 签名

Release 构建读取根目录的 `keystore.properties`（已被 `.gitignore` 排除，严禁提交）：

```properties
storeFile=keystore/your-release.jks
storePassword=...
keyAlias=...
keyPassword=...
```

然后执行 `./gradlew :app:assembleRelease`。升级安装需沿用同一签名，否则无法覆盖安装。

## 测试

```bash
# JVM 单元测试
./gradlew testDebugUnitTest

# 设备端 Compose 界面测试（需连接设备）
./gradlew connectedDebugAndroidTest
```

真机回归可使用 `tools/run_ui_tests.sh`：脚本以 release 变体构建，通过 `adb install` 安装并运行仪器测试，适配 MIUI 对分片安装的限制。

## 文档

功能规格与迭代记录位于 [`docs/specs`](docs/specs/README.md)，采用 spec 驱动开发：先写规格，再实现功能。

## 开源协议

本项目基于 [GNU General Public License v3.0](LICENSE) 开源。

Copyright © 2026 数阵（[shuzhen83](https://gitee.com/shuzhen83)）