bug: [移动端] MentionSessionController 命名参数以下划线开头导致编译失败

[HalfAnElephant]

问题概述

MentionSessionController 构造函数声明了一个以下划线开头的命名参数：

MentionSessionController({
  required this._searchUsers,   // ← Dart 语法错误
  this.debounce = const Duration(milliseconds: 300),
});

Dart 语言规范禁止命名参数以下划线开头（analyzer 报错："Named parameters can't start with an underscore"），且 _searchUsers 作为私有字段名对调用方不可寻址。结果：该库及其全部测试都无法编译。

影响

• apps/mobile/packages/forum_app 编译失败，CI 门禁（ci-mobile）必然红灯。
• 所有构造调用点传的都是 searchUsers:（topic_page.dart:114 及 mention_panel_test.dart / mention_session_test.dart 全部用例），与声明参数名不匹配，即使去掉下划线限制也无法绑定。

证据

• mention_session.dart:324 — required this._searchUsers
• mention_session.dart:334 — 私有字段 final Future<List<MentionUser>> Function(String query) _searchUsers;
• 调用点全部使用 searchUsers: 命名参数

复现

cd apps/mobile && flutter analyze packages/forum_app/lib/src/pages/topic/mention_session.dart

或运行任意 mention_session_test.dart / mention_panel_test.dart 用例。

预期行为

库与测试能够编译，searchUsers 参数可正常传入。

实际行为

编译失败（Named parameters can't start with an underscore）。

建议修复

将参数公开化并转发给私有字段：

MentionSessionController({
  required Future<List<MentionUser>> Function(String query) searchUsers,
  this.debounce = const Duration(milliseconds: 300),
}) : _searchUsers = searchUsers;

来源：OCR review session b0a6067d（HEAD~30..HEAD）critical 级发现。

[oryn-mini]

🧹 Oryn Mini · 🔄 Superseded

Code review · Attempt 1 · Cycle 1

Source changed (headSha, baseSha); rerun before publishing

View the Actions run

Run details · operational receipt

{
  "version": 1,
  "workKey": "review:d121465715e7a38a4a56289e",
  "sourceKey": "d121465715e7a38a4a56289e",
  "intent": "review",
  "phase": "completed",
  "attempt": 1,
  "cycle": 1,
  "leaseID": "db99d377-0770-4f5e-a72b-2c9290be88d4",
  "disposition": "superseded",
  "run": "https://github.com/YourTongji/YourTJ-Hub/actions/runs/36033801065",
  "summary": "Source changed (headSha, baseSha); rerun before publishing"
}

---

[oryn-mini]

🧹 Oryn Mini · 🧭 Your input is needed

🟠 P1 · High · 🐛 Bug · High confidence

What I found

移动端帖子页的 ＠mention 会话控制器把构造参数写成了私有命名参数 required this._searchUsers，Dart 明确规定命名参数不能以下划线开头，而全部调用点传的又都是 searchUsers:，于是 forum_app 连导入它的测试一起编译不过，ci-mobile 的 analyze/test 与原生构建都会红。修复很小——把参数公开、在初始化列表转发给同名私有字段即可，调用点一行都不用改；但在修好之前，issue #565 的 mention 候选（300ms 防抖、stale 响应丢弃、搜索失败降级）没有任何可执行验证，移动端也无法出包。

Proposed change

• 前：MentionSessionController({required this._searchUsers, ...}) 声明了以下划线开头的命名参数（analyzer：Named parameters can't start with an underscore）；后：改为公开参数 required Future<List<MentionUser>> Function(String query) searchUsers，并用 : _searchUsers = searchUsers 转发，字段继续保持私有。
• 前：topic_page.dart:131、mention_session_test.dart（14 处）、mention_panel_test.dart（8 处）都写 searchUsers:，与声明的参数名对不上；后：参数名与全部 23 处调用点一致，调用点无需改动。
• 前：forum_app 无法编译，mention 的防抖/丢弃/降级行为只有源码、没有验证；后：mention 相关用例能真正运行，语义首次被 CI 执行。
• 前：docs/product/mobile-experience.md 已把回复编辑器的 ＠ 候选面板记为 Current，而代码层不可编译；后：修复落地后该状态词重新成立，本次不需要改文档。

How it fits together

topic_page 从 Riverpod provider 读搜索回调注入 MentionSessionController，测试与候选面板共用同一构造函数；当前构造参数名与调用点不一致。

flowchart TD
  accTitle: Mention 会话的搜索回调注入链路
  accDescr: topic_page 从 Riverpod provider 读搜索回调注入 MentionSessionController，测试与候选面板共用同一构造函数；当前构造参数名与调用点不一致。
  n_0["topic_page 构造会话"]
  n_1["mentionUserSearchProvider"]
  n_2["MentionSessionController"]
  n_3["私有字段 _searchUsers"]
  n_4["MentionCandidatesPanel"]
  n_5["mention 测试"]
  n_1 -->|"ref.read 注入"| n_0
  n_0 -->|"构造 searchUsers:"| n_2
  n_5 -->|"构造 searchUsers:"| n_2
  n_2 -->|"初始化私有字段"| n_3
  n_2 -->|"ChangeNotifier 更新"| n_4

Loading

Review findings

🔴 High · 构造函数声明了下划线开头的命名参数，Dart 直接判为错误 — apps/mobile/packages/forum_app/lib/src/pages/topic/mention_session.dart:324

MentionSessionController 的构造参数写成 required this._searchUsers。Dart 规定命名参数不能以下划线开头，analyzer 报 “Named parameters can't start with an underscore”，这是 error 级诊断，因此该库无法通过静态分析、也无法编译。此文件位于 lib/src，被 topic_page.dart 直接 import 并构造，所以整个 forum_app 包受影响，而不是仅这一处死代码。

🔴 High · 全部调用点使用 searchUsers:，与声明的参数名互不匹配 — apps/mobile/packages/forum_app/lib/src/pages/topic/mention_session.dart:323

topic_page.dart:131、mention_session_test.dart（14 处）、mention_panel_test.dart（8 处）共 23 处都传 searchUsers:。即使忽略下划线限制，类里只有 _searchUsers 这一个命名参数，调用方会得到 “The named argument 'searchUsers' isn't defined”。问题里给出的修法（公开 searchUsers + 初始化列表转发给私有字段）正好让声明和全部调用点对齐，无需改动调用点。

🟡 Medium · 整包不可编译使 ci-mobile 的 analyze/test 与原生构建必然失败 — .github/workflows/ci-mobile.yml:45

apps/mobile/pubspec.yaml 的 melos analyze 脚本对每个包执行 flutter analyze，test 脚本执行 flutter test --exclude-tags=golden；.github/workflows/ci-mobile.yml 的 Analyze（:45）与 Test（:48）步骤跑的就是这两条，同工作流的 native-build 也依赖同一个包。因此当前 revision 上任何触碰 apps/mobile/** 的 PR 都会红，issue #565 引入的 mention 行为（防抖/排序/失败降级）从未在被执行的测试里验证过。

More findings (1)

🔵 Low · 文档把该功能记为 Current，实际处于不可编译状态 — docs/product/mobile-experience.md:214

docs/product/mobile-experience.md 的发布小节写着回复编辑器输入 ＠ 会打开用户候选面板（reply target/topic author/participants 优先，随后 debounce 服务端搜索），状态词是 Current。修复落地后这段描述自动重新成立，本 issue 不需要额外文档改动；提及只是为了让维护者知道当前文档与可编译性之间的短暂不一致。

---

Next step

• 本环境没有 shell，我无法执行 analyzer；合并前请实际运行 cd apps/mobile && dart run melos run analyze 与 dart run melos run test（或在 packages/forum_app 内 flutter analyze / flutter test），确认 ci-mobile 的两个步骤都绿。
• 修复后请确认 mention_session_test.dart / mention_panel_test.dart 全部通过：编译通过不等于 300ms 防抖、stale 丢弃、失败降级这些语义正确。
• pages_behavior_test.dart:1878 通过 override mentionUserSearchProvider 走集成路径，不需要改参数名，但修复后跑一次可确认集成层没有别的断言依赖旧写法。
• 同类写法我已 grep 过，required this._（作为命名参数）在本仓库仅此一处，无需额外排查其他控制器。

Maintainer decision: 这次只做最小修复，还是同时追查这个硬错误是怎么进到 dev 的（ci-mobile 本应拦截）？

• 先落一行的构造参数修复，并跑通 melos analyze/test 让门禁恢复绿色
• 修复之外，另外确认引入该文件的 PR 上 ci-mobile 是否真的执行过（本次拿到的 check/CI 证据为空，无法判断）
• 修复并顺手给移动端加一个提交前本地 analyze 钩子

Recommendation: 先选第一项：修复是解除阻塞的关键，且难度极小。追查门禁为何未拦住属于后续独立问题，不要与本修复绑在同一步。

• 改 apps/mobile/packages/forum_app/lib/src/pages/topic/mention_session.dart:323-326：把 required this._searchUsers 换成公开参数 searchUsers，在初始化列表里 : _searchUsers = searchUsers 转发，debounce 默认值保持 300ms 不变。
• 在 apps/mobile 下运行 dart run melos run analyze 与 dart run melos run test，把输出贴回 issue；这就是 ci-mobile 会重复执行的门禁。
• 确认 mention 相关用例（mention_session/mention_panel，以及 pages_behavior 中的 mention 场景）在修复后通过，避免只修语法、语义问题留到后面才暴露。

Things to watch

• 修复前，任何触碰 apps/mobile/** 的 PR 都会让 ci-mobile 亮红，新的、不相关的分析或测试失败会被这同一条错误掩盖。
• 编译修复本身不证明功能正确：mention 相关用例从未在可编译的构建上跑过，防抖、stale 丢弃、失败降级若有语义问题会在修复后才暴露。
• 若把参数直接改成公开字段（this.searchUsers）而非初始化列表转发，会把回调暴露为 public 字段，偏离现有封装；建议保持 _searchUsers 私有。

Verification

🔎 Evidence supports the conclusion. Confirmed in source; not reproduced in a live run.

No host validation commands were run for this report.

Source evidence (10)

• apps/mobile/packages/forum_app/lib/src/pages/topic/mention_session.dart:324 — 构造函数中的 required this._searchUsers,：命名参数以下划线开头，属 Dart 编译错误（analyzer: Named parameters can't start with an underscore）。

• apps/mobile/packages/forum_app/lib/src/pages/topic/mention_session.dart:334 — 对应私有字段 final Future<List<MentionUser>> Function(String query) _searchUsers;——库外不可寻址，因此必须靠公开参数转发。

• apps/mobile/packages/forum_app/lib/src/pages/topic/mention_session.dart:453 — 字段唯一消费点 final users = await _searchUsers(query);——修复时应保留私有字段名，只改参数名。

• apps/mobile/packages/forum_app/lib/src/pages/topic/topic_page.dart:131 — 生产调用点 searchUsers: ref.read(mentionUserSearchProvider),，与声明的 _searchUsers 参数名不匹配。

• apps/mobile/packages/forum_app/test/mention_session_test.dart:257 — 测试调用点 searchUsers: (q) async { ... }；本文件共 14 处同样写法。

• apps/mobile/packages/forum_app/test/mention_panel_test.dart:133 — 第二个测试文件的调用点 searchUsers: (_) async => throw Exception('offline'),；本文件共 8 处同样写法。

• apps/mobile/packages/forum_app/lib/src/pages/topic/mention_search.dart:15 — typedef MentionUserSearch = Future<List<MentionUser>> Function(String query); 可直接作为公开参数类型使用（当前构造签名未复用它）。

• apps/mobile/pubspec.yaml:19 — melos analyze 脚本：每个包执行 flutter analyze（第 22 行的 test 脚本执行 flutter test --exclude-tags=golden）。

• .github/workflows/ci-mobile.yml:45 — ci-mobile 的 Analyze 步骤（Test 在同文件 :48）；native-build 任务也依赖同一包可编译，当前 revision 上该工作流必然失败。

• docs/product/mobile-experience.md:214 — 文档将回复编辑器的 ＠ 候选面板记为 Current（含 debounce 服务端搜索、Web 一致的 token/排序语义）。

---

Discussion and CI reflect the snapshot read for this review. Current checks and approval are verified separately before merging.

_{🧹 Oryn Mini · Source 7a56446 · Built with Synergy core}