forked from hesabix/arc
90 lines
4.7 KiB
Markdown
90 lines
4.7 KiB
Markdown
# به‌روزرسانی خودکار اندروید (Forgejo Releases)
|
||
|
||
## هدف
|
||
|
||
کاربران APK خارج از مارکت، هنگام انتشار نسخهٔ جدید در
|
||
[ریلیزهای مخزن](https://source.hesabix.ir/hesabix/arc/releases) اعلان بگیرند،
|
||
APK را دانلود کنند و نصب را آغاز کنند. **وب تحت تأثیر قرار نمی‌گیرد**
|
||
(مسیر `version.json` / `web/index.html` دست‌نخورده می‌ماند).
|
||
|
||
## معیار نسخه (قرارداد الزامی از این پس)
|
||
|
||
| مورد | مقدار |
|
||
|------|--------|
|
||
| منبع حقیقت | تگ ریلیز Forgejo (`tag_name`) |
|
||
| قالب | `MAJOR.MINOR.PATCH` — سه عدد صحیح نامنفی، مثلاً `70.9.911` |
|
||
| `versionName` در APK | **همان** تگ ریلیز |
|
||
| `versionCode` پیشنهادی | `MAJOR * 1_000_000 + MINOR * 1_000 + PATCH` (مثلاً `70009911`) |
|
||
| مقایسه | تاپل `(MAJOR, MINOR, PATCH)`؛ نسخهٔ جدیدتر = بزرگ‌تر بودن تاپل |
|
||
| ریلیز معتبر | `draft=false` و `prerelease=false` |
|
||
| فایل APK | اولین asset با پسوند `.apk`؛ در صورت چندتایی، اولویت با نام شامل `app-release` |
|
||
|
||
در `pubspec.yaml` باید همان نسخه تنظیم شود، مثلاً:
|
||
|
||
```yaml
|
||
version: 70.9.911+70009911
|
||
```
|
||
|
||
یا هنگام بیلد:
|
||
|
||
```bash
|
||
flutter build apk --build-name=70.9.911 --build-number=70009911
|
||
```
|
||
|
||
## سناریوی کاربر
|
||
|
||
1. اپ اندروید پس از اتمام splash (با تأخیر کوتاه) آخرین ریلیز را از API Forgejo می‌خواند.
|
||
2. اگر نسخهٔ ریموت از نسخهٔ نصب‌شده بزرگ‌تر باشد و کاربر آن را «بعداً» نزده باشد:
|
||
- اعلان درون‌برنامه‌ای (دیالوگ) با changelog نمایش داده می‌شود.
|
||
- در صورت فعال بودن دانلود خودکار، دانلود APK شروع می‌شود.
|
||
3. پس از اتمام دانلود، نصب‌کنندهٔ سیستم باز می‌شود (تأیید کاربر الزامی است؛ محدودیت اندروید).
|
||
4. در **تنظیمات حساب کاربری → به‌روزرسانی برنامه**:
|
||
- نمایش نسخهٔ فعلی / آخرین نسخه
|
||
- بررسی دستی
|
||
- دانلود و نصب
|
||
- تنظیمات: بررسی خودکار هنگام شروع، دانلود خودکار
|
||
- در صورت نیاز، هدایت به تنظیمات «نصب از منابع ناشناس»
|
||
|
||
## فازهای اجرایی
|
||
|
||
| فاز | شرح | وضعیت |
|
||
|-----|------|--------|
|
||
| ۱ | هسته: پارس نسخه، کلاینت Forgejo، گیت پلتفرم | پیاده‌سازی‌شده |
|
||
| ۲ | نیتیو: FileProvider + MethodChannel نصب APK | پیاده‌سازی‌شده |
|
||
| ۳ | سرویس: چک / دانلود با progress / نصب | پیاده‌سازی‌شده |
|
||
| ۴ | اعلان استارت‌آپ + صفحه تنظیمات حساب | پیاده‌سازی‌شده |
|
||
| ۵ | l10n و ایزوله‌سازی از وب | پیاده‌سازی‌شده |
|
||
|
||
## API مصرف‌شده
|
||
|
||
- `GET https://source.hesabix.ir/api/v1/repos/hesabix/arc/releases/latest`
|
||
- دانلود از `assets[].browser_download_url`
|
||
|
||
## نکات امنیتی / عملیاتی
|
||
|
||
- APK باید با **همان keystore** قبلی امضا شود.
|
||
- مخزن ریلیز عمومی است؛ کلاینت اپ برای خواندن `releases/latest` توکن لازم ندارد.
|
||
- حجم APK حدود ۱۳۰MB+ است؛ progress در UI و اعلان سیستم نمایش داده می‌شود و دانلود در پس‌زمینه ادامه می‌یابد.
|
||
- وب و دسکتاپ این ماژول را اجرا نمی‌کنند (`supportsAndroidApkUpdate`).
|
||
- ریلیزهای مشترک می‌توانند هم‌زمان asset اندروید و ویندوز داشته باشند؛ کلاینت اندروید فقط `.apk` را برمی‌دارد. جزئیات ویندوز: [`WINDOWS_AUTO_UPDATE.md`](./WINDOWS_AUTO_UPDATE.md).
|
||
|
||
## انتشار خودکار ریلیز اندروید
|
||
|
||
پس از بیلد APK، از ریشهٔ مخزن:
|
||
|
||
```bash
|
||
# ترجیحاً با توکن API
|
||
FORGEJO_TOKEN='...' ./release_android_forgejo.sh
|
||
|
||
# یا با یوزر/پسورد
|
||
FORGEJO_USER='...' FORGEJO_PASSWORD='...' ./release_android_forgejo.sh
|
||
|
||
# پیش‌نمایش بدون آپلود
|
||
./release_android_forgejo.sh --dry-run
|
||
|
||
# جایگزینی ریلیز هم‌تگ
|
||
FORGEJO_TOKEN='...' ./release_android_forgejo.sh --force
|
||
```
|
||
|
||
اسکریپت نسخه را از `pubspec.yaml` می‌خواند، ریلیز با تگ `MAJOR.MINOR.PATCH` می‌سازد و
|
||
`app-release.<version>.apk` را آپلود می‌کند. جزئیات: `./release_android_forgejo.sh --help`
|