diff --git a/docs/plans/PROGRESS.md b/docs/plans/PROGRESS.md
index f470e2f..bea2411 100644
--- a/docs/plans/PROGRESS.md
+++ b/docs/plans/PROGRESS.md
@@ -2202,6 +2202,140 @@ $ flutter test
 
 ---
 
+## 2026-10-17 iOS 构建阻塞：固定 shared_preferences_foundation 2.5.6
+
+### 25.1 现象与根因
+
+用户从 Xcode 16.2 构建 iOS 时，Swift 6.0.3 在
+`shared_preferences_foundation 2.6.0` 生成文件中报：
+
+```text
+Unexpected , separator
+messages.g.swift:33:2
+```
+
+根因是 2.6.0 的函数参数列表使用 trailing comma，需要 Swift 6.1。此前可构建
+时锁文件为 foundation 2.5.7；`a4415c8` 同步依赖锁后升到了 2.6.0。
+
+用户随后修正固定目标：最终使用 2.5.6，不使用 2.5.4；2.5.7 的本地缓存缺
+`PrivacyInfo.xcprivacy`，也不使用。
+
+### 25.2 修复
+
+客户端从 `develop a4415c8` 创建独立分支：
+
+```text
+fix/ios-shared-preferences-foundation
+```
+
+`pubspec.yaml`：
+
+```yaml
+dependency_overrides:
+  shared_preferences_foundation: 2.5.6
+```
+
+执行：
+
+```text
+$ flutter pub get
+Resolving dependencies...
+Downloading packages...
+! shared_preferences_foundation 2.5.6 (overridden) (2.6.0 available)
+Got dependencies!
+```
+
+锁文件：
+
+```text
+$ rg -n -A 8 '^  shared_preferences_foundation:' pubspec.lock
+407:  shared_preferences_foundation:
+408-    dependency: "direct overridden"
+409-    description:
+410-      name: shared_preferences_foundation
+411-      sha256: "4e7eaffc2b17ba398759f1151415869a34771ba11ebbccd1b0145472a619a64f"
+412-      url: "https://pub.flutter-io.cn"
+413-    source: hosted
+414-    version: "2.5.6"
+```
+
+确认缓存包完整：
+
+```text
+$ find "$HOME/.pub-cache/hosted/pub.flutter-io.cn/shared_preferences_foundation-2.5.6" -name PrivacyInfo.xcprivacy -print
+/Users/jianghaifeng/.pub-cache/hosted/pub.flutter-io.cn/shared_preferences_foundation-2.5.6/darwin/shared_preferences_foundation/Sources/shared_preferences_foundation/Resources/PrivacyInfo.xcprivacy
+```
+
+### 25.3 依赖树原始输出
+
+```text
+$ flutter pub deps --style=compact | grep shared_preferences_foundation
+- shared_preferences 2.5.6 [flutter shared_preferences_android shared_preferences_foundation shared_preferences_linux shared_preferences_platform_interface shared_preferences_web shared_preferences_windows]
+- shared_preferences_foundation 2.5.6 [flutter shared_preferences_platform_interface]
+```
+
+解读：`shared_preferences 2.5.6` 与 override 后的
+`shared_preferences_foundation 2.5.6` 兼容，无需降级主插件。
+
+### 25.4 iOS 编译验证
+
+为排除先前版本的构建缓存，先清理再重新解析：
+
+```text
+$ flutter clean
+Cleaning Xcode workspace...                                         7.2s
+Deleting build...                                                  482ms
+Deleting .dart_tool...                                              24ms
+Deleting ephemeral...                                                2ms
+Deleting Generated.xcconfig...                                       0ms
+Deleting flutter_export_environment.sh...                            0ms
+Deleting .flutter-plugins-dependencies...                            0ms
+```
+
+```text
+$ flutter pub get
+! shared_preferences_foundation 2.5.6 (overridden) (2.6.0 available)
+Got dependencies!
+```
+
+完整无签名设备构建：
+
+```text
+$ flutter build ios --debug --no-codesign
+Warning: Building for device with codesigning disabled. You will have to manually codesign before deploying to device.
+Building com.stormg.lumadramv for device (ios)...
+Running Xcode build...
+Xcode build done.                                           22.1s
+✓ Built build/ios/iphoneos/Runner.app
+```
+
+解读：Swift Compiler 编译通过，不再出现 `Unexpected , separator`。
+本轮未运行真机，也未执行签名安装。
+
+### 25.5 Git
+
+```text
+2c30f83 chore(ios): 固定 shared_preferences_foundation 2.5.6
+19babb8 merge: 合并 iOS shared_preferences 编译修复
+a4415c8..19babb8  develop -> develop
+```
+
+该 chore 提交只包含 `pubspec.yaml` 与 `pubspec.lock`，K9 修改未混入；
+author/committer 均为 `Zhou Weidong <502333560@qq.com>`。
+
+### 25.6 用户后续验证
+
+1. 拉取最新客户端 `develop` 并执行 `flutter pub get`。
+   预期：终端显示 `shared_preferences_foundation 2.5.6 (overridden)`。
+2. 从 Xcode 16.2 直接 Run 或执行 `flutter run` 到 iPhone。
+   预期：Swift Compiler 不再报 `Unexpected , separator`，App 可完成构建启动。
+3. 打开设置或任何依赖 `shared_preferences` 的页面，修改语言或登录态。
+   预期：偏好设置读写正常。
+
+设备侧构建日志、启动截图与偏好读写结果由用户执行。
+
+---
+
 ## 2026-10-17 K8 登录页视觉重设计
 
 ### 23.1 范围、分支与计划