zijunchiang
ba31caaa38
- AppUpdateManager: releases/latest 改用 gitea.kasugano.cn API - KtvJsBridge: JS 热更新改用 Gitea raw(/raw/branch/master/...) - MainActivity/SongApiClient/DatabaseBootstrapper/MuseDbSync: 文案与注释更新 - README.md/README.en.md: 标注本仓库地址(Gitea), 保留上游框架归属链接 - AGENTS.md: 运行时端点迁移状态
77 lines
3.6 KiB
Markdown
77 lines
3.6 KiB
Markdown
# 麦动 KTV — 项目开发约定
|
||
|
||
> 本文件供后续开发（含 AI 助手会话）遵循，优先级高于默认习惯。
|
||
|
||
## 一、代码同步策略（2026-09-11 更新）
|
||
|
||
**代码主仓库已迁移至 Gitea：https://gitea.kasugano.cn/zijunchiang/maidong-ktv**
|
||
|
||
| 远端 | 地址 | 状态 |
|
||
|---|---|---|
|
||
| `origin` | `https://gitea.kasugano.cn/zijunchiang/maidong-ktv.git` | ✅ 主仓库，**同步目标** |
|
||
| `gitee` | `https://gitee.com/zijunchiang/maidong-ktv.git` | ⛔ 已停用（推送被钩子拦截） |
|
||
|
||
- ✅ 预期动作：完成改动 → 本地 `git commit` → `git push origin master`（同步到 Gitea）
|
||
- ⛔ 禁止：推送到 Gitee（`pre-push` 钩子会拦截，避免误推送）
|
||
- 凭据：Gitea 访问令牌 `dsh-sync`（可在 Gitea「设置 → 应用 → 访问令牌」随时吊销），
|
||
存放于 `~/.git-credentials-gitea`（权限 600），由本仓库级 `credential.helper` 引用；
|
||
账号密码不写入仓库配置。
|
||
|
||
### 推送方式
|
||
|
||
```bash
|
||
cd /home/zijun/dsh/maidongktv/maidong-ktv
|
||
git push origin master # origin = Gitea（主仓库）
|
||
git push --no-verify gitee master # 仅在确需回推 Gitee 时使用
|
||
```
|
||
|
||
### 运行时端点（已全部迁移到 Gitea）
|
||
|
||
App 内部两处端点已指向 Gitea（随本版 APK 生效）：
|
||
|
||
- `AppUpdateManager.kt`：`gitea.kasugano.cn/api/v1/repos/zijunchiang/maidong-ktv/releases/latest`（App 内检查更新）
|
||
- `KtvJsBridge.kt`：`gitea.kasugano.cn/zijunchiang/maidong-ktv/raw/branch/master/app/src/main/assets/mobile/ktv_api.js`（JS 热更新）
|
||
|
||
> 注意：Gitea 的 raw 规范路径是 `/raw/branch/<分支>/<文件>`；`/raw/<分支>/<文件>` 会 303 跳转。
|
||
> 发布新版本时需在 Gitea 创建 Release 并上传 `.apk` 附件（Gitea Release API 的 `assets[].browser_download_url` 供 App 下载）。
|
||
|
||
## 二、构建与产物
|
||
|
||
### 构建（release，双 ABI）
|
||
|
||
```bash
|
||
cd /home/zijun/dsh/maidongktv/maidong-ktv
|
||
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
|
||
export ANDROID_HOME=/home/zijun/Android/Sdk
|
||
export ANDROID_SDK_ROOT=/home/zijun/Android/Sdk
|
||
./gradlew assembleRelease
|
||
```
|
||
|
||
产物：`app/build/outputs/apk/release/app-release.apk`（已由 `app/build.gradle` 的 signingConfig 签名）
|
||
|
||
### 签名与校验（单独签名/改名时）
|
||
|
||
```bash
|
||
BT=/home/zijun/Android/Sdk/build-tools/36.0.0
|
||
$BT/apksigner sign --ks /home/zijun/dsh/maidongktv/ktv_keystore.jks \
|
||
--ks-key-alias ktv --ks-pass pass:123456 --key-pass pass:123456 \
|
||
--out 目标名.apk app/build/outputs/apk/release/app-release.apk
|
||
$BT/apksigner verify 目标名.apk
|
||
```
|
||
|
||
- 密钥：`/home/zijun/dsh/maidongktv/ktv_keystore.jks`（仓库外，勿入库）
|
||
- APK 命名约定：`麦动KTV-V<版本号>-release.apk`（对外发布）/ `maidong-ktv-<版本>-<改动说明>-双ABI-release.apk`（内部测试）
|
||
|
||
### 版本号
|
||
|
||
- `app/build.gradle`：`versionName "1.2.5"` / `versionCode 5`
|
||
- App 内显示统一用纯版本号（不加 `(versionCode)` 括号）
|
||
|
||
## 三、关键实现约束（避免踩坑）
|
||
|
||
- **歌曲源**：`app/src/main/assets/mobile/ktv_api.js` 的 `CONFIG.HOSTS`（多源自动排序，失败源沉底）
|
||
- **JS 热更新**：改动 `ktv_api.js` 必须同步提升 `KTV_BRIDGE_API: N` 标记（JS 与 `KtvJsBridge.kt` 两处校验），否则设备仍用缓存旧脚本
|
||
- **曲库**：只走官方 Muse 同步（`MuseDbSync`），不再依赖代码仓库数据库文件
|
||
- **麦克风**：`MicActivator` 常驻占用输入通道（TV/投影需占用后才有演唱声音输出），外接设备热插拔会自动重建
|
||
- **仓库可见性**：Gitea 仓库保持 **public**（若后续把 App 更新/热更新端点迁到 Gitea，非 public 会导致 403）
|