# KMP-Goods

**Repository Path**: fireice2048/kmp-goods

## Basic Information

- **Project Name**: KMP-Goods
- **Description**: 演示KMP跨平台能力，特别演示鸿蒙 KMP-Native/AKInterop 交互接口开发示范
- **Primary Language**: Kotlin
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-13
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KMP-Goods

KMP 跨平台商品管理演示。`goodsmanagersdk` 共享商品模型、异步 CRUD、复制、内置商品与 JSON 持久化；Android、iOS、HarmonyOS 分别使用原生 UI。

## 模块

- `goodsmanagersdk/`：Kotlin Multiplatform SDK；公开接口统一返回泛型 `KXPromise<T>`。
- `androidApp/`：Android View/XML。
- `iosApp/`：SwiftUI（`project.yml` 可由 XcodeGen 生成工程）。
- `harmonyApp/`：ArkUI + AKInterop KSP compact 模式。
- `build-logic/akinterop-typed-dts/`：可复制的本地 Gradle 插件，恢复 AKInterop DTS 中被擦除的 `KXPromise<T>`。

## 构建

```bash
export JAVA_HOME=/Applications/DevEco-Studio.app/Contents/jbr/Contents/Home
./gradlew :goodsmanagersdk:allTests :androidApp:assembleDebug
./gradlew :goodsmanagersdk:linkDebugSharedOhosArm64
(cd harmonyApp && devecocli build --modules entry@default)
(cd harmonyApp && devecocli run --module entry@default --device 127.0.0.1:5555 --uninstall)
```

iOS：先运行 `./gradlew :goodsmanagersdk:linkDebugFrameworkIosSimulatorArm64`，然后在 `iosApp` 执行 `xcodegen generate` 并用 Xcode 构建。

SDK 首次读取空存储时写入一条内置商品。调用方启动时必须先用应用私有目录执行 `GoodsManager.configure(...)`。

## Harmony 泛型声明生成

AKInterop `0.5.0-15` 能在 KSP 元数据中保留 `KXPromise<List<Product>>` 等完整 Kotlin 类型，但生成的 DTS 会将它擦除为裸 `KXPromise`。本项目不修改 AKInterop 二进制，也不要求 ArkTS 业务代码使用 wrapper，而是在构建期生成最终声明：

```text
AKInterop KSP metadata + Index.raw.d.ts
                    ↓ dev.akinterop.typed-dts
harmonyApp/entry/src/main/cpp/types/libgoods/Index.d.ts
```

例如最终接口为：

```ts
static listProducts(): KXPromise<Array<Product>>
static getProduct(id: bigint): KXPromise<Product>
static deleteProduct(id: bigint): KXPromise<boolean>
```

`Index.raw.d.ts` 位于 `goodsmanagersdk/build/akinterop-dts/`，仅用于转换和排查，不提交、不发布、不被业务代码引用。ArkTS 仍照常从 `libgoods.so` import；`.so` 运行时入口没有变化。

插件会根据 `KNapiGenerated_MetaData.kt` 中的 `typeOf<KXPromise<...>>()` 自动推导所有异步方法，不需要维护方法类型表。转换结果若无法和原始声明一一对应，或仍存在裸 promise 返回类型，构建会直接失败。

### 在其他项目复用

1. 整体复制 `build-logic/akinterop-typed-dts`。
2. 在根 `settings.gradle.kts` 的 `pluginManagement` 中加入 `includeBuild("build-logic/akinterop-typed-dts")`。
3. SDK 模块应用 `id("dev.akinterop.typed-dts")`。
4. 将 AKInterop `ffi.dtsOutput` 指向模块 `build/` 下的 `Index.raw.d.ts`。
5. 在 `akInteropTypedDts` 中配置 raw DTS、`KNapiGenerated_MetaData.kt` 和最终 `Index.d.ts` 路径。

完整可复制配置见 [`build-logic/akinterop-typed-dts/README.md`](build-logic/akinterop-typed-dts/README.md)。

### 排查声明问题

```bash
export JAVA_HOME=/Applications/DevEco-Studio.app/Contents/jbr/Contents/Home
./gradlew :goodsmanagersdk:generateAkInteropTypedDts --rerun --info
./gradlew -p build-logic/akinterop-typed-dts test
diff -u goodsmanagersdk/build/akinterop-dts/Index.raw.d.ts \
  harmonyApp/entry/src/main/cpp/types/libgoods/Index.d.ts
rg --pcre2 -n 'KXPromise(?!\s*<)' \
  harmonyApp/entry/src/main/cpp/types/libgoods/Index.d.ts
```

若升级 AKInterop 后失败，先检查 raw DTS 和 `KNapiGenerated_MetaData.kt` 的结构是否改变，再同步修改插件解析器及其测试。不要手工修补生成的 `Index.d.ts`，否则下次 KSP 构建会覆盖且无法保证类型与 Kotlin API 一致。