#!/usr/bin/env python3 """Generate release/README.md from actual artifacts in a release directory. Usage: python3 scripts/generate_release_readme.py [version_name] [version_code] """ import hashlib import os import sys import datetime FILES = [ ("qsmw-service.apk", "MCU SystemService APK，用于系统集成"), ("qsmw-sdk.aar", "业务应用侧 SDK 二进制包"), ("qsmw-contract.aar", "AIDL / Parcelable 契约二进制包"), ("qsmw-demos.zip", "Android Studio 示例工程源码包，包含 vehicle、radio、ota 三个接入示例"), ("qsmw-ota-demo.apk", "OTA 示例应用 APK，基于 qsmw-demos.zip 中的 ota-demo 工程构建"), ("qsmw-radio-demo.apk", "Radio 示例应用 APK，基于 qsmw-demos.zip 中的 radio-demo 工程构建"), ("qsmw-vehicle-demo.apk", "Vehicle/Key 示例应用 APK，基于 qsmw-demos.zip 中的 vehicle-demo 工程构建"), ] STATIC_DOC_DESCRIPTION = "APP 开发对接文档（Markdown 版本）" def sha256_file(path: str) -> str: h = hashlib.sha256() with open(path, "rb") as f: while True: chunk = f.read(8192) if not chunk: break h.update(chunk) return h.hexdigest() def main() -> int: if len(sys.argv) < 2: print(f"Usage: {sys.argv[0]} [version_name] [version_code]", file=sys.stderr) return 1 release_dir = sys.argv[1] version_name = sys.argv[2] if len(sys.argv) > 2 else "1.0.0-beta7" version_code = sys.argv[3] if len(sys.argv) > 3 else "107" doc_name = f"QSJNIC_MCU_SDK_开发对接文档_v{version_name}.md" static_files = [ (doc_name, STATIC_DOC_DESCRIPTION), ("API_REFERENCE.md", "SDK 接口与回调说明"), ("INTEGRATION_GUIDE.md", "系统集成步骤与验证命令"), ("INTERFACE_CONSISTENCY_REPORT.md", "协议/代码/文档一致性修订报告"), ("RELEASE_INFO.txt", "构建元数据与 SHA-256"), ("SHA256SUMS.txt", "校验文件"), ("VERSION.txt", "版本文件"), ("changes.patch", "自上一版本以来的完整代码变更 diff"), ] key_sha_files = [ "qsmw-service.apk", "qsmw-sdk.aar", "qsmw-contract.aar", "qsmw-demos.zip", "qsmw-ota-demo.apk", "qsmw-radio-demo.apk", "qsmw-vehicle-demo.apk", doc_name, "API_REFERENCE.md", "INTERFACE_CONSISTENCY_REPORT.md", "changes.patch", ] # AGP / SDK versions are read from the project root. project_root = os.path.join(os.path.dirname(__file__), "..") agp = "8.8.2" compile_sdk = "34" min_sdk = "26" try: toml = os.path.join(project_root, "gradle", "libs.versions.toml") with open(toml, "r", encoding="utf-8") as f: for line in f: line = line.strip() if line.startswith("agp") and "=" in line: agp = line.split("=")[-1].strip().strip('"') elif line.startswith("compileSdk") and "=" in line: compile_sdk = line.split("=")[-1].strip().strip('"') elif line.startswith("minSdk") and "=" in line: min_sdk = line.split("=")[-1].strip().strip('"') except Exception: pass file_entries = [] latest_mtime = 0.0 for name, desc in FILES + static_files: path = os.path.join(release_dir, name) if os.path.exists(path): size = os.path.getsize(path) mtime = os.path.getmtime(path) if mtime > latest_mtime: latest_mtime = mtime sha = sha256_file(path) file_entries.append((name, size, desc, sha)) tz = datetime.timezone(datetime.timedelta(hours=8)) build_time = datetime.datetime.fromtimestamp(latest_mtime, tz=tz).isoformat() sha_map = {name: sha for name, _, _, sha in file_entries} lines = [ "# QSJNIC MCU SystemService 交付说明", "", f"本目录为 `{version_name}` 对外交付产物集合。交付内容包含运行时二进制包、SDK 二进制包、接口契约二进制包、示例工程源码包及必要的集成说明文档。除 `qsmw-demos.zip` 中的示例工程源码外，不包含 SystemService、SDK、Contract 的实现源码或内部发版流程文档。", "", "## 版本信息", "", f"- 版本号：`{version_name}`", f"- Service `versionCode`：`{version_code}`", f"- Service `versionName`：`{version_name}`", f"- 构建时间：`{build_time}`", f"- AGP：`{agp}`", f"- compileSdk：`{compile_sdk}`", f"- minSdk：`{min_sdk}`", "", "## 交付清单", "", "| 文件 | 大小 | 说明 |", "|---|---:|---|", ] for name, size, desc, _ in file_entries: lines.append(f"| `{name}` | {size:,} bytes | {desc} |") lines += [ "", "> 注：`qsmw-demos.zip` 中同时包含示例工程源码，各示例工程已内置本版本 `qsmw-sdk.aar` 与 `qsmw-contract.aar`。", "", "`qsmw-demos.zip` 为交付用示例源码包，内部包含可直接导入 Android Studio 的示例工程。除该示例源码包外，交付目录不包含其他 Java/Kotlin/C/C++ 源码、Gradle 工程文件或内部版本管理文档。", "", "## 校验信息", "", "关键产物 SHA-256：", "", "```text", ] present_key_files = [name for name in key_sha_files if name in sha_map] for name in present_key_files: lines.append(f"{name:<48} {sha_map[name]}") checksum_cmd = "shasum -a 256 " + " ".join(present_key_files) lines += [ "```", "", "校验命令：", "", "```bash", checksum_cmd, "```", "", "## 签名说明", "", "本版本仓库构建统一使用 `docs/keystore/sim.jks` 签名，保证 `qsmw-service.apk` 与相关验证包使用一致的签名体系。", "", "证书 SHA-256：", "", "```text", "c8a2e9bccf597c2fb6dc66bee293fc13f2fc47ec77bc6b2b0d52c11f51192ab8", "```", "", "如最终系统镜像要求 platform 签名，应在甲方系统构建流程中对 `qsmw-service.apk` 重新签名后再预置。", "", "## 构建质量", "", "本版本在打包前已通过自动化单元测试门禁，覆盖 `service` 模块核心 Java 逻辑：", "", "- McuBinder 参数边界与链路状态测试", "- UpgradeManager 状态机与参数校验测试", "- KeyInjector 按键映射与事件注入测试", "- Feature 状态同步与并发安全测试", "- BootCompletedReceiver 生命周期测试", "", "测试命令：", "", "```bash", "./gradlew :service:testDebugUnitTest", "```", "", "`assembleRelease` 已自动依赖上述测试任务，每次 release 构建前会自动执行。", "", "## 系统集成", "", "1. 将 `qsmw-service.apk` 预置到 `/system/priv-app/QsmwService/QsmwService.apk`", "2. 确认 `/dev/ttyS7` 的 Linux 权限、SELinux 策略和服务启动策略已配置完成", "3. 如需 platform 签名，先完成重签，再纳入系统镜像", "4. 参考 `INTEGRATION_GUIDE.md` 完成安装、启动和权限验证", "5. 参考 `API_REFERENCE.md` 完成业务接口对接", "", "> **beta6 变更提示**：本版本在 `service/AndroidManifest.xml` 中为 `QsMcuSystemService` 和 `BootCompletedReceiver` 增加了 `android:singleUser=\"true\"`，确保服务仅在 user 0 中运行，防止多用户场景下串口竞争。", ">", "> **beta7 变更提示**：Key 域键值定义从 MC3 标准切换为帕杰罗映射表（Key.xlsx \"其它项目\"），新增 5 个扩展键值（0x0E/0x0F/0x18/0x19/0x25），校验范围放宽至 0x00-0x25。配套 MCU 固件更新至 PAJERO69XZA0120018 (SW: 0302_20260527)。", "", "## 业务应用接入", "", "1. 将 `qsmw-sdk.aar` 与 `qsmw-contract.aar` 放入业务工程 `libs/`", "2. 在业务工程中配置 `implementation(fileTree(\"libs\"))`", "3. 在业务应用 `AndroidManifest.xml` 中声明：", "", "```xml", '', "```", "", "4. 业务应用需使用与 SystemService 兼容的签名策略，否则受 `signature|privileged` 权限限制，可能无法绑定服务", "", "## 示例工程", "", "`qsmw-demos.zip` 包含以下 Android Studio 示例工程源码：", "", "1. `vehicle-demo`：车辆信息与 Key 域方控接口示例", "2. `radio-demo`：收音机接口示例", "3. `ota-demo`：OTA 接口示例", "", "各示例工程已内置本版本交付的 `qsmw-sdk.aar` 与 `qsmw-contract.aar`，用于验证 SDK 接入方式和基础调用流程。", "", "`qsmw-ota-demo.apk`、`qsmw-radio-demo.apk`、`qsmw-vehicle-demo.apk` 分别为三个示例工程的 release 构建产物，包名分别为 `com.qsjnic.demo.ota`、`com.qsjnic.demo.radio`、`com.qsjnic.demo.vehicle`，版本均为 `0.1.0`，使用 `docs/keystore/sim.jks` 签名。", "", "## 验收建议", "", "系统集成完成后，建议按以下顺序验证：", "", f"1. 校验 APK 版本：`versionCode={version_code}`，`versionName={version_name}`", "2. 校验预置路径：`/system/priv-app/QsmwService/QsmwService.apk`", "3. 校验权限声明：`cn.qsjnic.permission.MCU_ACCESS`", "4. 校验串口权限：`/dev/ttyS7`", "5. 启动服务并检查 `QsMcuSystemService`、`McuLink` 相关日志", "", "具体命令见 `INTEGRATION_GUIDE.md`。", "", ] out_path = os.path.join(release_dir, "README.md") with open(out_path, "w", encoding="utf-8") as f: f.write("\n".join(lines)) print(f"Generated {out_path}") return 0 if __name__ == "__main__": sys.exit(main())