Skip to content

docs(android): A4 收官——README 双语同步、MOBILE-PLAN 进度与 PR Template 平台化 - #29

Merged
Qiyuanqiii merged 4 commits into
mainfrom
docs/android-a4-readme-sync
Aug 16, 2026
Merged

Qiyuanqiii merged 4 commits into
mainfrom
docs/android-a4-readme-sync

Conversation

@Qiyuanqiii

Copy link
Copy Markdown
Member

描述

#16 文档同步(A4 收官的最后一块):让文档与代码实际状态一致。

android/README.md / android/README.zh-CN.md

  • 删除过期表述:"(milestone A3)"、"(planned)"、"(规划)"、"(开发中)"、"目标功能";
  • 功能清单更新:前台轮询跟随生命周期(15s~10min)、WorkManager 后台刷新(唯一周期任务/≥15min/网络约束)、低余额通知(0<余额<1.0 币种单位、去重、纯本地)、debug 测试通知入口;
  • 结构树补充:background/(Worker+Scheduler)、notification/(LowBalanceNotifier)、MainActivity 生命周期桥接说明;
  • 构建命令统一为 :core:test :app:assembleDebug,注明 PR CI 上传 debug APK 工件;
  • 隐私段改为已完成语气("is stored" / "使用"),补充 Token 不进 WorkManager 输入数据/日志/界面;
  • 对照表更新:Keystore(AES/GCM)仅密文、WebView + popup 承接、后台刷新与通知的对应关系;
  • 进度行:A1 ✅ A2 ✅ A3 ✅ A4 ✅(含真机 QA) A5 规划中。

MOBILE-PLAN.md

  • Android 进度更新为 A4 ✅(前台轮询生命周期、WorkManager 后台刷新(D6 已决策)、低余额通知+权限三态+去重、WebView popup、PR CI 构建 App、真机 QA 矩阵 22 项通过)。

.github/pull_request_template.md

  • 「未改变 Token 存储方式(保持 UserDefaults)」→ 平台规范表述(macOS UserDefaults / iOS Keychain / Android Keystore);
  • 「本地验证」段按平台拆分(macOS / Android / iOS 各一行),不再只有 macOS 命令。

关联

变更类型

  • 📝 文档

本地验证

  • 仅文档改动,无构建影响(CI 全绿即通过)

边界检查

  • 未引入任何第三方依赖
  • 未改动平台接口契约(URL / 参数 / 响应结构)
  • 未在代码 / 日志 / 截图 / 提交中夹带真实 Token 或凭据
  • 未提交构建产物
  • 未改变 Token 存储方式(macOS 为 UserDefaults;iOS 为 Keychain;Android 为 Keystore)
  • 注释与文案中文;文档遵循双语惯例(README 双语同步更新)
  • 提交信息符合 Conventional Commits + 中文描述

备注

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

一句话总结

本 PR 为 Android A4 里程碑收官,主要更新了 MOBILE-PLAN.md 进度、android/README 双语文档,并将 PR 模板平台化(macOS/Android/iOS 三端勾选项),纯文档与模板改动,未触碰任何红线。

🔴 红线 / 严重问题

未发现红线问题。但需注意以下两点:

  1. PR 模板中 Android 构建命令与 AGENTS.md 第 2 节不一致(.github/pull_request_template.md:24)

    • 模板新增:cd android && ./gradlew :core:test :app:assembleDebug
    • AGENTS.md 第 2 节 Android 验证命令为:cd android && ./gradlew :core:test
    • 建议:同步更新 AGENTS.md 第 2 节,补充 :app:assembleDebug 命令,保持仓库规范与 PR 模板一致,避免贡献者困惑。
  2. MOBILE-PLAN.md 中 A4 完成状态与红线 11 的 WorkManager 准入记录存在潜在不一致(MOBILE-PLAN.md:6)

    • 文中提到「WorkManager 后台刷新(D6 已决策)」,但 AGENTS.md 红线 11 明确记录 WorkManager 准入是「Issue #11」讨论通过,且仅限 :app 层。
    • 建议:在 MOBILE-PLAN.md 中补充引用 Issue #11 或明确 D6 决策与红线 11 的对应关系,确保文档可追溯。

🟡 建议改进

  1. PR 模板边界检查项可更精确(.github/pull_request_template.md:37)

    • 当前「未改变 Token 存储方式」已按平台区分(macOS UserDefaults / iOS Keychain / Android Keystore),但未提及 Windows 版(DPAPI)。
    • 建议:补充 Windows 版 Token 存储方式(DPAPI),保持三端文档一致性。
  2. android/README 双语版本存在轻微不一致(android/README.md 与 android/README.zh-CN.md)

    • 英文版「Progress」段落使用「A5 planned (widget, store distribution)」,中文版为「A5 规划中(桌面小组件、商店分发)」——「桌面小组件」表述可能引起歧义(Android 无桌面概念)。
    • 建议:中文版改为「主屏幕小组件」或「App Widget」,与 Android 平台术语一致。

🔵 小问题 / 风格

  1. MOBILE-PLAN.md 进度行过长(MOBILE-PLAN.md:6)

    • 单行包含 M1-M5、A1-A4 全部状态,可读性较差。建议按平台拆分为多行(macOS/iOS 一行、Android 一行),便于后续 A5 更新。
  2. android/README 结构注释中「薄壳」表述(android/README.zh-CN.md:32)

    • app/ Compose App(薄壳) 与后续列出的 MainActivity/HomeScreen/LoginScreen 等 7 个文件略显矛盾(薄壳通常指极简壳)。建议改为「Compose App(UI 层)」更准确。
  3. PR 模板中 iOS 验证命令可补充(.github/pull_request_template.md:25)

    • 模板仅写「bash Scripts/run-ios-tests.sh + 模拟器构建通过」,但 AGENTS.md 第 2 节还包含 python3 Scripts/check-ios-project.py 结构校验。建议补充该命令,与仓库规范完全对齐。

审查结论

建议合并。本 PR 为纯文档与模板更新,内容准确反映了 Android A4 的实际完成状态,双语文档质量良好,未触碰任何红线。上述建议均为非阻塞性改进,可在后续 PR 中逐步完善。合并前请确认 MOBILE-PLAN.md 中 WorkManager 决策与红线 11 的引用关系(建议项 2),其余建议可择机处理。

@Qiyuanqiii
Qiyuanqiii merged commit 18e6703 into main Aug 16, 2026
5 checks passed
@Qiyuanqiii
Qiyuanqiii deleted the docs/android-a4-readme-sync branch August 16, 2026 16:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

test+docs(android): A4 QA 矩阵执行与 README/MOBILE-PLAN/PR Template 同步

1 participant