open-im-sdk-flutter-m/.trellis/tasks/05-12-audit-android-int-long-native-parameter-mismatches-against-sdk-core/prd.md

audit android int-long native parameter mismatches against sdk core

Goal

Audit the Flutter Android bridge managers against the bound SDK core signatures, find places where Flutter int values are forwarded with the wrong boxed Java type (Integer vs Long / int32-style expectations), and fix confirmed mismatch risks to prevent more runtime ClassCastException failures.

What I already know

• A real crash was reproduced in getChannelHistoryMessages on Android: java.lang.Integer cannot be cast to java.lang.Long.
• The fixed plugin call site was android/src/main/java/io/openim/flutter_openim_sdk/manager/ChannelManager.java, where count was passed via value(...) instead of numeric conversion.
• Flutter side sends Dart int values through MethodChannel, which arrive on Android as boxed Java numbers.
• This repo’s Android bridge currently mixes raw value(methodCall, key) and int2long(methodCall, key) for numeric parameters.
• iOS already uses typed accessors like methodCall[int:], methodCall[int32:], methodCall[int64:].
• SDK core source is available at /mnt/d/workspace/go/im_dev/openim-sdk-core for signature comparison.
• Core signature examples already checked:
  • GetChannelHistoryMessages(..., count int, sinceSeq int64)
  • GetChannelMemberList(..., filter int32, offset int32, count int32)
  • GetGroupMemberList(..., filter int32, offset int32, count int32)
  • GetJoinedGroupListPage(..., offset, count int32)
  • GetGroupMemberListByJoinTimeFilter(..., offset int32, count int32, joinTimeBegin int64, joinTimeEnd int64)
  • GetFriendListPage(..., offset int32, count int32, filterBlack bool)
  • GetConversationListSplit(..., offset int, count int)
• gomobile/gobind Java bindings map Go int and int64 to Java long, while int32 maps to Java int; this is a common source of cross-platform bridge confusion.

Assumptions (temporary)

• The Android binding layer should match the generated Java API’s expected boxed types exactly enough to avoid reflection/runtime cast failures.
• Some existing value(...) calls on numeric args are safe when the generated Java signature expects Java int/boxed Integer, but unsafe when it expects Java long/boxed Long.
• The task likely includes both audit and code fixes for confirmed risks, not just reporting.

Open Questions

• Should this task only fix confirmed Android mismatches found by comparing to SDK core/bound signatures, or also refactor the bridge toward explicit typed helpers (int32 / int64) even for currently-safe call sites?

Requirements (evolving)

• Compare Android manager numeric forwarding against SDK core signatures and binding behavior.
• Identify confirmed mismatch sites and distinguish them from safe int32 call sites.
• Fix confirmed mismatch sites with minimal behavior change.
• Summarize findings clearly, including why each changed call needed conversion.
• If a broader pattern is found, capture it in spec/guides to prevent recurrence.

Acceptance Criteria (evolving)

• All Android manager numeric parameters that should be passed as Java Long are identified and fixed.
• No confirmed Integer → Long mismatch remains in audited Android manager methods.
• Findings are backed by SDK core signature comparison.
• Any preventive guidance learned from the audit is written back into .trellis/spec/.

Definition of Done (team quality bar)

• Audit completed across Android managers
• Code changes applied only where signature comparison justifies them
• Relevant docs/specs updated if a reusable lesson is found
• Build/test verification run as feasible for the touched layer

Out of Scope (explicit)

• Changing SDK core public APIs
• Large redesign of the plugin dispatch/reflection mechanism unless separately required
• iOS behavior changes unless needed for parity documentation

Technical Notes

• Touched/focus paths:
  • android/src/main/java/io/openim/flutter_openim_sdk/manager/*.java
  • ios/Classes/Module/*.swift
  • lib/src/manager/*.dart
  • /mnt/d/workspace/go/im_dev/openim-sdk-core/open_im_sdk/*.go
• Initial likely-risk buckets:
  • Go int / int64 parameters exposed to Android as Java long
  • Pagination / cursor params inconsistently forwarded via value(...)
• Confirmed fixed bug:
  • ChannelManager.getChannelHistoryMessages: count now uses int2long(...)