[Feature Request] iOS: merge duplicate Mac devices and archive retired devices

[o1xhack]

Source: user feedback from Telegram.

Requirement:
CodexBar Mobile should provide a simple sync device management flow for Mac devices that appear duplicated or outdated after reinstall, replacement, or retirement.

The iOS app should allow users to:

• Merge duplicate Mac device identities when they belong to the same physical Mac after reinstall.
• Archive retired Mac devices when they are real old devices that should no longer trigger stale sync warnings.
• Keep historical sync data without destructive deletion.
• Undo merge/archive decisions when needed.

---

来源：Telegram 用户反馈。

需求：
CodexBar Mobile 应该提供一个简单的同步设备管理流程，用于处理 Mac 重装、更换或退役后出现的重复设备或旧设备提示。

iOS App 应允许用户：

• 当多个 Mac 设备身份实际属于同一台重装后的 Mac 时，手动合并重复设备身份。
• 当旧 Mac 已经退役且不应继续触发同步过期提醒时，将其归档。
• 保留历史同步数据，不做破坏性删除。
• 必要时撤销合并或归档操作。

[o1xhack]

Research / implementation direction

This request covers two related but semantically different sync-device cases:

1. Duplicate identity after Mac reinstall

   • The user still has one physical Mac.
   • The Mac reinstall can create a new sync device identity, so iOS may show both the old and new Mac entries.
   • The correct action is not deletion. The correct action is to link the old device identity to the current one as a merged alias.

2. Retired or replaced Mac

   • The user may have one old Mac that is no longer used, plus a different new Mac.
   • These are two real devices and should not be merged as the same physical device.
   • The correct action is to archive the old device so it no longer triggers stale-sync warnings, while still preserving historical sync data.

Recommended product model

Add iOS Sync Device Management with three visible states:

• Active: normal device, participates in sync status and stale-sync warnings.
• Merged alias: an old device identity that belongs to another active physical Mac identity.
• Archived: a real retired device kept for history, but excluded from active sync warnings.

Recommended user actions

• Merge with another Mac...

  • Use when two device entries are the same physical Mac before/after reinstall.
  • Should be user-confirmed and reversible.

• Archive this device

  • Use when the Mac is retired, sold, replaced, or intentionally no longer syncing.
  • Should hide stale-sync warnings for that device but keep historical data.

• Restore / Unmerge

  • Restore an archived device to active.
  • Undo a mistaken merge.

Recommended technical direction

Use non-destructive CloudKit lifecycle records instead of deleting or rewriting existing device/provider records.

A possible model:

DeviceLifecycleEvent
- recordID
- kind: alias / unalias / archive / unarchive / successor
- primaryDeviceID
- relatedDeviceIDs
- createdAt
- createdFromDeviceID
- note / reason

The iOS sync reader can replay these lifecycle events to derive current device state:

• alias groups multiple device IDs into one physical device.
• archive removes a real device from active stale-sync warnings.
• successor can optionally show that an archived device was replaced by another Mac.
• unalias / unarchive allow safe reversal.

Important data semantics

Device merge must not behave exactly like multi-device aggregation.

If two IDs are aliases for the same physical Mac, local cost/provider data should avoid double-counting. This is different from two active Macs, where local provider costs may legitimately be summed across devices.

Recommended sync merge order:

1. Apply device lifecycle records first and collapse aliases into physical-device snapshots.
2. Within the same physical device alias group, prefer newest/richer provider snapshots rather than blindly summing local cost.
3. After that, run normal cross-device merge behavior across distinct active physical devices.

Suggested MVP scope

• Add shared device lifecycle/linkage model.
• Add CloudKit read/write support for lifecycle records.
• Add iOS Settings → Sync device management UI.
• Support manual merge, archive, restore, and unmerge.
• Remove stale-sync warnings for archived or merged-alias device identities.
• Preserve all historical CloudKit/device/provider data.
• Add 4-language localization for all user-facing strings.
• Add unit tests for lifecycle replay, alias grouping, archive filtering, and local-cost non-duplication.
• Run the sync compatibility gate if this changes CloudKit/sync behavior.

Risks / gates

• New CloudKit record types or fields require a Production schema deploy audit before release.
• This likely triggers docs/ios-sync-compatibility-testing.md because it changes Mac → CloudKit → iOS sync behavior and cross-version display semantics.
• Automatic merge should not be part of the MVP. The app may suggest likely duplicates, but the final merge/archive decision should stay user-confirmed.

[o1xhack]

This should start after the current upstream sync work in #28 is completed.

Reason:
#28 updates the Mac-side provider/sync baseline to upstream v0.36.0 / v0.36.1. This device-management feature should be designed and implemented against that updated baseline so we do not build UI or CloudKit behavior on top of soon-to-change sync/provider data.

Proposed order:

1. Finish [Upstream Sync] 上游新版本发布：v0.36.0 & v0.36.1 #28 upstream sync and confirm the new Mac/iOS sync baseline.
2. Re-check the duplicated-device behavior with the updated build.
3. Start this issue as a separate feature implementation.