Skip to content

Commit c4e4bbd

Browse files
thothaweiclaude
andauthored
fix(app): 字數上限與後端數的不是同一種單位——計數器說沒超過,後端擋下(第二十六輪) (#98)
本輪掃的族是跨端輸入邊界對帳(App 欄位上限 vs 後端 validator),從沒掃過。 掃出來的東西比預期硬:不只有三個欄位沒擋,**有擋的那三個擋的單位也是錯的**。 根因:Flutter 的 TextField.maxLength 數的是 grapheme cluster,後端每一支上限數的 都是 rune。對 ASCII 與中文相同,對 emoji 差 7 倍——實跑探針: 「👨‍👩‍👧‍👦」characters=1 runes=7;maxLength: 5 放行了 35 個 rune。 於是評分畫面計數器顯示「200/200 沒超過」、送出卻被後端以 400 擋下,而錯誤訊息 (「評論長度超過上限」)不會說上限是多少,對照計數器只會更困惑。 六個欄位:評分評論 200/遺失物描述 300/預約備註 200 三個單位錯; 聊天訊息 500/常用地點名稱 40 兩個完全沒擋;常用地點地址唯讀,刻意不加限制器 ——它由地圖選點反查填入,客戶端截短會產生**錯的地址**,司機會開到別的地方。 修法:共用 RuneLimitingTextInputFormatter + runeCounter,擋的單位與顯示的數字 都與後端一致。裁切落在 cluster 邊界而不是直接砍 rune 陣列——從 ZWJ 序列中間切 會留下半個字。maxLength 只留著讓 Flutter 畫計數器的位置,強制交給 formatter。 驗收:flutter analyze 無 issue、flutter test 434 passed(425+新 9)、 flutter build apk --debug --flavor customer 成功。 反向驗證兩個半邊各一次:拿掉聊天的 formatter → 700 rune 整段進得去該案 FAIL; 把限制器改回數 cluster → 5 案 FAIL。 另有一案專驗「真畫面接上去了」(常用地點開表單→輸入 30 面旗子→只留 20 面、 計數器顯示 40/40)——只驗共用元件的話,某個畫面漏接 inputFormatters 不會變紅。 Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
1 parent 1029ab5 commit c4e4bbd

9 files changed

Lines changed: 404 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -219,8 +219,8 @@ REST 一定完整,而推播要傳達的資訊只有「有事發生了」。
219219
至此三端齊備:**乘客評 → 司機看得到自己的平均分 → 營運看得出誰評價低**。
220220
詳見 [`docs/TODO.md`](docs/TODO.md)「⭐ 乘客評分司機」。
221221

222-
**目前**:`flutter analyze` 無 issue、`flutter test` **425 passed**(54 個測試檔,2026-08-01 實跑)。
223-
~~414 passed~~/~~383 passed~~/~~377 passed~~/~~361 passed~~/~~356 passed~~/~~351 passed~~/~~339 passed~~ 是漏更新的舊數字——**這一行請跟著最後一次實跑一起改**。
222+
**目前**:`flutter analyze` 無 issue、`flutter test` **434 passed**(55 個測試檔,2026-08-01 實跑)。
223+
~~425 passed~~/~~414 passed~~/~~383 passed~~/~~377 passed~~/~~361 passed~~/~~356 passed~~/~~351 passed~~/~~339 passed~~ 是漏更新的舊數字——**這一行請跟著最後一次實跑一起改**。
224224

225225
**2026-07-30 弱網逾時對帳的實跑收尾**(詳見 [`docs/TODO.md`](docs/TODO.md) 第十四~十五輪):
226226
先做了一支「請求照送、回應吃掉」的代理 [`tool/lossy_proxy.py`](tool/lossy_proxy.py)——

‎docs/TODO.md‎

Lines changed: 87 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@
7777
- [🗓️ 預約司機+常用地點(跨端新功能,含 debug 兩個)](#-預約司機常用地點2026-07-31跨端新功能)
7878
- [📜 第二十四輪:「我的行程」只看得到最近 20 趟](#-2026-07-31-第二十四輪我的行程只看得到最近-20-趟本批修掉)
7979
- [🔁 第二十五輪:分頁尾巴會卡死在轉圈(回頭 debug 第二十四輪自己)](#-2026-08-01-第二十五輪分頁的尾巴會卡死在轉圈回頭-debug-第二十四輪自己本批修掉-2-個)
80+
- [🔤 第二十六輪:App 的字數上限與後端數的不是同一種單位](#-2026-08-01-第二十六輪app-的字數上限與後端數的不是同一種單位本批修掉-6-個欄位)
8081

8182
**四、維護、決策與待辦**
8283
- [🧹 清開發殘留 worktree/舊分支(維護項 5)](#-清開發殘留-worktree舊分支維護項-52026-07-28-完成)
@@ -93,7 +94,7 @@
9394
- **UI/UX 翻新(2026-07-10)**:LINE 綠亮暗雙主題;司機駕駛情境 UI;乘客地圖為底+卡片降級。靜態驗收 49 tests 通過;模擬器主鏈路待後端 docker 可起後補跑。
9495
**登入/註冊頁 2026-07-23 補齊翻新**(先前是唯一漏網畫面),詳見下方「🔐 登入頁 UI/UX 翻新+驗證」。
9596
- **座標導航(2026-07-10)**:司機端目的地導航改吃後端 `dropoff_point` 座標,地址僅供顯示與退路。
96-
- 單元測試:**54 個測試檔、`flutter test` 425 passed**(2026-08-01 第二十四輪併回 main 並修完尾巴那兩個洞後實測;
97+
- 單元測試:**55 個測試檔、`flutter test` 434 passed**(2026-08-01 第二十六輪後實測;
9798
`flutter analyze` 無 issue、`flutter build apk --debug --flavor customer` 成功)。
9899
~~(54 項)~~ 是 2026-07-10 的數字,長期沒更新,已更正——**本節的數字請跟著最後盤點日一起改**。
99100
- 遠端:`github.com/thothawei/fleet-app`。**2026-07-29 實查**:`git ls-remote --heads origin` 只有 `main`、
@@ -2461,9 +2462,93 @@ PSQL_DSN='postgres://fleet:change_me@127.0.0.1:5433/fleet?sslmode=disable' \
24612462

24622463
---
24632464

2465+
## 🔤 2026-08-01 第二十六輪:App 的字數上限與後端數的不是同一種單位(本批修掉 6 個欄位)
2466+
2467+
> 本輪掃的族是**跨端輸入邊界對帳**——App 的欄位上限 vs 後端 validator。
2468+
> 從沒掃過,而且掃出來的東西比預期硬:不只有三個欄位沒擋,
2469+
> **有擋的那三個擋的單位也是錯的**。
2470+
2471+
### 根因一句話
2472+
2473+
Flutter 的 `TextField.maxLength` 數的是 **grapheme cluster**(使用者感知的「一個字」),
2474+
後端每一支上限數的都是 **rune**(`utf8.RuneCountInString` / `len([]rune(...))`)——
2475+
對 ASCII 與中文相同,對 emoji 差到 7 倍。
2476+
2477+
### 取證(不是查文件,是實跑探針)
2478+
2479+
```
2480+
「👨‍👩‍👧‍👦」characters=1 runes=7 「🇹🇼」characters=1 runes=2 「👍🏽」characters=1 runes=2
2481+
TextField(maxLength: 5) 擋完後 → characters=5 runes=35
2482+
```
2483+
2484+
`maxLength: 5` 放行了 **35 個 rune**。於是評分畫面的計數器顯示「200/200 沒超過」,
2485+
送出卻被後端以 400 擋下,而錯誤訊息(「評論長度超過上限」)**不會說上限是多少**——
2486+
對照著計數器看只會更困惑。
2487+
2488+
### 六個欄位的對帳表
2489+
2490+
| 欄位 | 後端上限(rune) | 修改前的 App | 判定 |
2491+
|---|---|---|---|
2492+
| 評分評論 | `ratingCommentMaxRunes` 200 | `maxLength: 200`(數 cluster) | ❌ 單位錯 |
2493+
| 遺失物描述 | `lostItemDescMaxRunes` 300 | `maxLength: 300`(數 cluster) | ❌ 單位錯 |
2494+
| 預約備註 | `maxScheduleNoteRunes` 200 | `maxLength: 200`(數 cluster) | ❌ 單位錯 |
2495+
| 聊天訊息 | `chatMaxRunes` 500 | **完全沒有上限** | ❌ 只能送出後才知道 |
2496+
| 常用地點名稱 | `maxPlaceLabelRunes` 40 | **完全沒有上限** | ❌ 同上 |
2497+
| 常用地點地址 | `maxPlaceAddressRunes` 200 | 唯讀(地圖選點反查) | ⚠️ 見下 |
2498+
2499+
### 修法
2500+
2501+
- 新增共用的 [`RuneLimitingTextInputFormatter`](../lib/shared/widgets/rune_limit.dart)
2502+
+ `runeCounter()`:**擋的單位與顯示的數字都與後端一致**。
2503+
- **裁切落在 cluster 邊界**,不是直接砍 rune 陣列——從 ZWJ 序列中間切下去會留下
2504+
半個字(孤立的修飾符/ZWJ 尾巴),畫面會出現使用者沒打過的東西。寧可少收一個完整的字。
2505+
- 保留 `maxLength` 只為了讓 Flutter 畫出計數器的位置,實際強制交給 formatter
2506+
(`maxLengthEnforcement: none`)——兩套同時生效會先被 cluster 那套擋掉。
2507+
- 聊天輸入框**不放計數器**:訊息框下面多一行 `x/500` 太吵,而 500 字平常打不到。
2508+
- **常用地點「地址」刻意不加限制器**:它是唯讀的、由地圖選點反查填入。
2509+
真的超過 200 rune 時應該讓後端拒絕,而不是在客戶端把地址默默截短——
2510+
**截短過的地址是錯的地址**,司機會開到別的地方去。
2511+
2512+
### 驗收
2513+
2514+
- `flutter analyze` 無 issue、`flutter test` **434 passed**(425 +新 9)。
2515+
- **反向驗證兩個半邊各一次**:
2516+
- 拿掉聊天輸入框的 formatter(回到先前無上限)→ 700 個 rune 整段進得去,該案 FAIL。
2517+
- 把限制器改回數 cluster(=`maxLength` 的行為)→ **5 案 FAIL**。
2518+
- **有一個案子專門驗「真畫面接上去了」**(常用地點名稱:開編輯表單→輸入 30 面旗子
2519+
→只留 20 面、計數器顯示 `40/40`)——只驗共用元件本身的話,
2520+
某個畫面漏接 `inputFormatters` 不會有任何測試變紅。
2521+
- `flutter build apk --debug --flavor customer` 成功。
2522+
2523+
### 同族還沒碰的角落
2524+
2525+
- **遺失物描述/預約備註/評分評論這三個畫面沒有各自的「真畫面接上去了」測試**
2526+
(只有常用地點與聊天室有)。三個接法完全相同、`analyze` 也綠,
2527+
但嚴格說它們的接線目前靠 review 不靠測試。**條件**:下次動到這三個畫面時順手補。
2528+
- **司機端沒有任何自由輸入欄位**(車牌走後端驗證、聊天共用同一個元件),所以本輪不必動司機端。
2529+
2530+
---
2531+
24642532
## 下次任務
24652533

2466-
> **🎯 2026-08-01 第二十五輪之後的狀態(開工先看這段)**
2534+
> **🎯 2026-08-01 第二十六輪之後的狀態(開工先看這段)**
2535+
>
2536+
> 1. **`gh pr list`(三個 repo)照樣是第一件事**——本輪開工時三個 repo 的 open PR 皆為 0。
2537+
> 2. **第九次實查三個外部卡點:依然都不在**(`android/app/google-services.json`、
2538+
> `ios/Runner/GoogleService-Info.plist` 不存在、`xcrun devicectl list devices` → No devices found)。
2539+
> 3. **這一輪學到的一條(值得單獨記住)**:
2540+
> **「兩邊都有做限制」不等於「限制得住」——要先問兩邊數的是不是同一種單位。**
2541+
> 評分/協尋/預約那三個欄位的 `maxLength` 數字與後端**完全相同**(200/300/200),
2542+
> 程式碼上看起來對得整整齊齊,實際上一個數 grapheme、一個數 rune。
2543+
> 對帳跨端契約時,**單位與數值要分開問兩次**。
2544+
> 4. **下一輪候選**(依價值排序):
2545+
> - **同族收尾**:遺失物描述/預約備註/評分評論三個畫面補「真畫面接上去了」的測試
2546+
> (本輪只補了常用地點與聊天室)。**條件**:下次動到那三個畫面時順手做,不必為它單開一輪。
2547+
> - **數值與金額格式**(從沒掃過):`formatCentsAsNtd` 的 0/負數/大數、
2548+
> 車資與清潔費相加的邊界、收入頁的月聚合。與本輪同一類(跨端表示法對帳)。
2549+
> - **狀態機**(從沒掃過):後端新增 ride status code 時 App 的退路
2550+
> (目前 `statusLabel` 有 default,但「未知狀態要不要給操作鈕」沒有統一答案)。
2551+
24672552
>
24682553
> 1. **`gh pr list`(三個 repo)照樣是第一件事。** 本輪開工時:app 只有 #97(就是本輪在收的那支)、
24692554
> dispatch #72(redis 讓開埠號)、admin 0。

‎lib/customer/screens/lost_item_screen.dart‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
import 'package:flutter/material.dart';
2+
import 'package:flutter/services.dart';
23
import 'package:provider/provider.dart';
34

45
import '../../core/api/fleet_api_client.dart' show ApiException;
56
import '../../core/models/models.dart';
67
import '../../core/util/money.dart';
78
import '../../shared/screens/ride_chat_screen.dart';
9+
import '../../shared/widgets/rune_limit.dart';
810
import '../customer_controller.dart';
911

1012
/// 乘客端遺失物協尋:對已完成行程回報遺失 → 顯示處理費 → 與司機即時對話 →
@@ -222,7 +224,12 @@ class _ReportForm extends StatelessWidget {
222224
TextField(
223225
controller: description,
224226
maxLines: 3,
227+
// 與後端 lostItemDescMaxRunes(300)對齊,且數的是 rune 不是 grapheme
228+
// (見 RuneLimitingTextInputFormatter 的說明)。
229+
inputFormatters: const [RuneLimitingTextInputFormatter(300)],
225230
maxLength: 300,
231+
maxLengthEnforcement: MaxLengthEnforcement.none,
232+
buildCounter: runeCounter(300, description),
226233
decoration: const InputDecoration(
227234
labelText: '物品描述(例:黑色錢包掉在後座)',
228235
border: OutlineInputBorder(),

‎lib/customer/screens/saved_places_screen.dart‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
import 'package:flutter/material.dart';
2+
import 'package:flutter/services.dart';
23
import 'package:latlong2/latlong.dart';
34
import 'package:provider/provider.dart';
45

56
import '../../core/models/models.dart';
7+
import '../../shared/widgets/rune_limit.dart';
68
import '../customer_controller.dart';
79
import '../widgets/saved_places_bar.dart' show savedPlaceIcon;
810
import 'map_picker_screen.dart';
@@ -335,6 +337,12 @@ class _PlaceEditorSheetState extends State<_PlaceEditorSheet> {
335337
TextField(
336338
controller: _label,
337339
onChanged: (_) => setState(() {}),
340+
// 先前**完全沒有上限**:後端 maxPlaceLabelRunes 是 40,超過會回
341+
// 「地點名稱過長」,但那句話沒說上限是多少,使用者只能亂猜著砍。
342+
inputFormatters: const [RuneLimitingTextInputFormatter(40)],
343+
maxLength: 40,
344+
maxLengthEnforcement: MaxLengthEnforcement.none,
345+
buildCounter: runeCounter(40, _label),
338346
decoration: const InputDecoration(
339347
labelText: '名稱',
340348
hintText: '例如:健身房、媽媽家',

‎lib/customer/screens/scheduled_rides_screen.dart‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
import 'package:flutter/material.dart';
2+
import 'package:flutter/services.dart';
23
import 'package:latlong2/latlong.dart';
34
import 'package:provider/provider.dart';
45

56
import '../../core/models/models.dart';
7+
import '../../shared/widgets/rune_limit.dart';
68
import '../customer_controller.dart';
79
import '../widgets/saved_places_bar.dart';
810
import 'map_picker_screen.dart';
@@ -428,7 +430,12 @@ class _ScheduleEditorScreenState extends State<_ScheduleEditorScreen> {
428430
const SizedBox(height: 20),
429431
TextField(
430432
controller: _note,
433+
// 與後端 maxScheduleNoteRunes(200)對齊,且數的是 rune 不是 grapheme
434+
// (見 RuneLimitingTextInputFormatter 的說明)。
435+
inputFormatters: const [RuneLimitingTextInputFormatter(200)],
431436
maxLength: 200,
437+
maxLengthEnforcement: MaxLengthEnforcement.none,
438+
buildCounter: runeCounter(200, _note),
432439
decoration: const InputDecoration(
433440
labelText: '給司機的備註(選填)',
434441
hintText: '例如:有一件大行李',

‎lib/customer/widgets/rating_sheet.dart‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
11
import 'package:flutter/material.dart';
2+
import 'package:flutter/services.dart';
3+
4+
import '../../shared/widgets/rune_limit.dart';
25

36
import '../customer_controller.dart';
47

@@ -109,7 +112,12 @@ class _RatingSheetState extends State<_RatingSheet> {
109112
controller: _commentCtrl,
110113
enabled: !_submitting,
111114
maxLines: 3,
112-
maxLength: 200, // 與後端 ratingCommentMaxRunes 對齊
115+
// 與後端 ratingCommentMaxRunes(200)對齊。**用 rune 不用 maxLength**:
116+
// maxLength 數的是 grapheme cluster,emoji 會讓計數器說沒超過而後端擋下。
117+
inputFormatters: const [RuneLimitingTextInputFormatter(200)],
118+
maxLength: 200,
119+
maxLengthEnforcement: MaxLengthEnforcement.none,
120+
buildCounter: runeCounter(200, _commentCtrl),
113121
decoration: const InputDecoration(
114122
labelText: '想說的話(選填)',
115123
border: OutlineInputBorder(),

‎lib/shared/screens/ride_chat_screen.dart‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import 'package:flutter/material.dart';
55
import '../../core/api/fleet_api_client.dart' show ApiException;
66
import '../../core/models/models.dart';
77
import '../widgets/app_lifecycle_reactor.dart';
8+
import '../widgets/rune_limit.dart';
89

910
/// 乘客↔司機共用聊天室。
1011
/// - 歷史:進場以 REST 載入,之後以 afterId 增量補讀(WS 斷線重連保底)。
@@ -264,6 +265,14 @@ class _RideChatScreenState extends State<RideChatScreen> {
264265
controller: _input,
265266
minLines: 1,
266267
maxLines: 4,
268+
// 先前**完全沒有上限**:後端 chatMaxRunes 是 500,超過回 400
269+
// 「訊息長度超過上限」——訊息會留在輸入框(送出路徑本來就這樣設計),
270+
// 但那句話沒說上限是多少,只能一段一段刪著試。
271+
// 這裡不放計數器:聊天輸入框下面多一行 `x/500` 太吵,
272+
// 而 500 字對一則訊息來說平常打不到。
273+
inputFormatters: const [
274+
RuneLimitingTextInputFormatter(500),
275+
],
267276
textInputAction: TextInputAction.send,
268277
onSubmitted: (_) => _send(),
269278
decoration: const InputDecoration(

‎lib/shared/widgets/rune_limit.dart‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
import 'package:flutter/material.dart';
2+
import 'package:flutter/services.dart';
3+
4+
/// 依 **rune 數**(Unicode code point)限制輸入長度,並提供同一單位的計數器。
5+
///
6+
/// **為什麼不直接用 `TextField.maxLength`**:它數的是 grapheme cluster
7+
/// (使用者感知的「一個字」),而後端每一支上限數的都是 rune
8+
/// (`utf8.RuneCountInString` / `len([]rune(...))`)。兩者對 ASCII 與中文相同,
9+
/// 對 emoji 差很多——實測 `maxLength: 5` 會放行 5 個 ZWJ 家庭 emoji = **35 個 rune**:
10+
///
11+
/// ```
12+
/// 「👨‍👩‍👧‍👦」characters=1 runes=7 「🇹🇼」characters=1 runes=2 「👍🏽」characters=1 runes=2
13+
/// ```
14+
///
15+
/// 於是畫面上的計數器顯示「200/200 沒超過」,送出卻被後端以 400 擋下,
16+
/// 而錯誤訊息(「評論長度超過上限」)**不會告訴使用者到底該砍掉多少**——
17+
/// 對照計數器只會更困惑。擋在同一個單位上,這條路才不會出現。
18+
class RuneLimitingTextInputFormatter extends TextInputFormatter {
19+
const RuneLimitingTextInputFormatter(this.maxRunes)
20+
: assert(maxRunes > 0, 'maxRunes 必須為正');
21+
22+
final int maxRunes;
23+
24+
@override
25+
TextEditingValue formatEditUpdate(
26+
TextEditingValue oldValue,
27+
TextEditingValue newValue,
28+
) {
29+
if (runeCount(newValue.text) <= maxRunes) return newValue;
30+
// **以 grapheme cluster 為單位裁切**,不是直接砍 rune 陣列:
31+
// 從 ZWJ 序列中間切下去會留下半個字(孤立的修飾符/ZWJ 尾巴),
32+
// 畫面會出現使用者沒打過的東西。寧可少收一個完整的字。
33+
final buffer = StringBuffer();
34+
var used = 0;
35+
for (final cluster in newValue.text.characters) {
36+
final n = cluster.runes.length;
37+
if (used + n > maxRunes) break;
38+
buffer.write(cluster);
39+
used += n;
40+
}
41+
final text = buffer.toString();
42+
return TextEditingValue(
43+
text: text,
44+
selection: TextSelection.collapsed(offset: text.length),
45+
composing: TextRange.empty,
46+
);
47+
}
48+
}
49+
50+
/// 與後端同一單位的長度計算。
51+
int runeCount(String s) => s.runes.length;
52+
53+
/// `TextField.buildCounter` 用的計數器,顯示的數字與後端檢查的是同一個。
54+
///
55+
/// 沿用 `maxLength` 的 `x/y` 形狀(使用者已經認得),只是把 x 換成 rune 數。
56+
/// **要傳 controller**:counter 不是 `EditableText` 的後代,用 context 往上找拿不到
57+
/// 目前文字,只能退回 framework 給的 `currentLength`——那正是 grapheme 數。
58+
/// `TextField` 會跟著 controller 變動重建,所以這裡讀到的一定是最新值。
59+
InputCounterWidgetBuilder runeCounter(
60+
int maxRunes,
61+
TextEditingController controller,
62+
) {
63+
return (
64+
BuildContext context, {
65+
required int currentLength,
66+
required int? maxLength,
67+
required bool isFocused,
68+
}) {
69+
final used = runeCount(controller.text);
70+
return Text(
71+
'$used/$maxRunes',
72+
style: Theme.of(context).textTheme.bodySmall,
73+
semanticsLabel: '已輸入 $used 字,上限 $maxRunes 字',
74+
);
75+
};
76+
}

0 commit comments

Comments
 (0)