jianghaifeng/FruitServer
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
38c8f51315e9b82df03e7f78d7f8e2b4009f00f3
FruitServer/docs/plans/PROGRESS.md
T

4762 lines
166 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# PROGRESS — 工作留痕（FruitServer）
> 红线第 2 条：谁干活谁写这里（命令 + 原始输出 + 解读，逐动作追加）。
> 指令通道：`docs/plans/INBOX.md`（specs 仓库只拉取、由项目负责人更新）。
---
## 2026-10-16 I1：后台管理端 —— 商品（金币包）配置 + 系统公告管理
计划文件：`docs/plans/2026-10-16-I1.md`（先写计划再动手）。改了 `docs/api-phase1.md` §2.11/§2.12（契约先行）。
### 动作 1：开工前核对仓库状态
```
$ cd FruitServer && git status --short && git log --oneline -1
M docs/api-phase1.md
M fruitshorts-admin-api/.../FruitShortsApplication.java
M fruitshorts-app-api/.../AppNoticeService.java
M sql/data-phase1.sql
?? docs/plans/2026-10-16-I1.md
?? fruitshorts-admin-api/.../ProductAdminController.java（+ NoticeAdminController）
?? fruitshorts-admin-api/src/test/.../ProductAdminControllerContractTest.java（+ Notice / AdminPermissionAnnotation）
?? fruitshorts-module-commerce/.../ProductService.java（+ 3 个 VO）
?? fruitshorts-module-system/.../OpsNoticeService.java（+ 3 个 VO）
7513ac0 docs(plans): 指令通道迁入本仓库（specs 改为只拉取，由项目负责人更新）
```
解读：分支 `develop`，起点就是指令通道那笔 `7513ac0`；工作区只有本轮 I1 的改动。
### 动作 2：契约先行（先改文档再写代码）
`docs/api-phase1.md` 新增 **§2.11 商品（金币包）配置（已实现）**、**§2.12 系统公告管理（已实现）**：
接口表 + 字段表 + 校验错误码表 + 权限点 + 与 C 端可见性口径对齐说明。VIP 口径在契约里定死：
**允许建档、不允许启用**。
### 动作 3：后端门禁 —— `mvn test`
首轮（雪花 id 修复前）：
```
$ mvn test
[INFO] Tests run: 33, Failures: 0, Errors: 0, Skipped: 0 (fruitshorts-module-commerce)
[INFO] Tests run: 14, Failures: 0, Errors: 0, Skipped: 0 (fruitshorts-admin-api)
[INFO] Tests run: 49, Failures: 0, Errors: 0, Skipped: 0 (fruitshorts-app-api)
[INFO] Tests run: 12, Failures: 0, Errors: 0, Skipped: 0 (fruitshorts-transcode-worker)
[INFO] BUILD SUCCESS
```
解读：存量 91 条（app-api 41 + commerce 27 + admin-api 3 + worker 12 + …）无一跑红，新增 17 条全过，共 108。
### 动作 4：SQL 幂等（连跑三遍）
```
$ psql -f sql/data-phase1.sql # 第一次
INSERT 0 5 / UPDATE 5 / INSERT 0 4 / INSERT 0 4 / INSERT 0 3 / INSERT 0 3
$ psql -f sql/data-phase1.sql # 第二次
INSERT 0 5 / UPDATE 5 / INSERT 0 0 / INSERT 0 0 / INSERT 0 3 / INSERT 0 0
$ psql -t -c "select 'role_menu='||count(*) from sys_role_menu union all ..." # 跑前
role_menu=54 / permission=52 / menu=33 / role_perm=79
$ psql -f sql/data-phase1.sql # 第三次
RUN3 EXIT=0
role_menu=54 / permission=52 / menu=33 / role_perm=79 # 跑后：完全一致
```
解读：脚本可重复执行，**行数不增长、不重复插入**。新增权限点 `1160-1163`、菜单 `31/32/33`（商品挂 22「订单与权益」下、公告新建 32「运营管理」分组 + 33 子菜单），并给超管授了角色-菜单。
### 动作 5：打包 + 起回服务 + curl 自测（商品）
```
$ mvn -pl fruitshorts-app-api,fruitshorts-admin-api -am package -DskipTests → BUILD SUCCESS
（kill 8080/8081 → 重新起 jar → 健康检查）
admin=200 / app=200
```
商品自测（完整脚本 `/tmp/i1-curl.sh`，原始输出 `/tmp/i1-curl.log`）：
```
3) 新建商品 i1_test_coin_100（800+80，IDR 9900，platform=GOOGLE）
{"code":0,"message":"ok","data":2111010131922784257}
4) 新建后状态 → "status": 0, "statusText": "已下架" # 新建默认下架
5) code 重复 → {"code":200001,"message":"商品编码已存在：i1_test_coin_100"}
6) 同平台 store id 重复 → {"code":200001,"message":"该平台下商店商品 id 已被占用：I1_TEST_COIN_100"}
7) 金币包 coin_amount=0 → {"code":400,"message":"金币包的金币数量必须大于 0"}
8) VIP vip_days=0 → {"code":400,"message":"会员商品的会员天数必须大于 0"}
9) VIP vip_days=30 → {"code":0} # 允许建档
10) VIP 启用 → {"code":400,"message":"会员商品在订阅功能上线前不能启用（可先建档，上线后再上下架）"}
11) 上架 → {"code":0}，详情 status=1/已上架
12) C 端等价查询（store_product_id + platform in (GOOGLE,ALL) + status=1）
2111010131922784257 | i1_test_coin_100 | GOOGLE | I1_TEST_COIN_100 | 800 | 80 | 1 (1 row)
```
公告自测（同一脚本，13–18 步）：
```
13) 公告分页（新建前）→ total 0
14) 新建 target=ALL → {"code":0,"data":2111010133357236226}
15) 新建 target=CREATOR → {"code":0,"data":2111010133537591298}
16) 新建 expire_at=2020-01-01（已过期） → {"code":0}
17) C 端 GET /app/notices（匿名）→ total 1，只返回第 14 步那条
18) 后台下架第 14 步那条 → C 端 total 0
```
越权自测（`content.editor01` / role=content_operator，无 `product:*` / `notice:*`）：
```
GET /admin/products/page → {"code":403,"message":"无权限"}
GET /admin/notices/page → {"code":403,"message":"无权限"}
POST /admin/products → {"code":403,"message":"无权限"}
PUT /admin/notices/1/status → {"code":403,"message":"无权限"}
（无 token）GET /admin/products/page → {"code":401,"message":"未登录或登录已过期"}
```
解读：商品三类校验、VIP 只建不启、公告"C 端可见/不可见"三个分支、越权 401/403 全部实测通过。
`logs` 里 `200002 该商品未在后台配置` 的触发点在商店校验**之后**（`/app/orders/verify` 当前默认
`DisabledStoreVerifier` → 先返回 `200003 商店校验尚未配置`），所以 C 端链路验证到"进入商店校验环节"为止，
真正的发币链路等 Google Play 凭据到位（见回执「待确认」）。
### 动作 6：清理第一轮自测数据
```
DELETE 3 # 3 个自测商品
DELETE 4 # 4 条自测公告
products | soft_deleted notices
3 | 0 0
```
### 动作 7：前端页面（ReelShortWeb，develop 分支）
新增 4 个文件（首行署名 `// Author: fruit.com.cn` / `<!-- Author: fruit.com.cn -->`）：
```
src/api/admin/product.ts src/api/admin/notice.ts
src/views/commerce/ProductManagementView.vue src/views/operation/NoticeManagementView.vue
```
**挂载机制实测**（与 INBOX 描述有出入，以实测为准）：菜单树来自 DB `sys_menu`，
`src/utils/routerHelper.ts` 用 `import.meta.glob('../views/**/*.{vue,tsx}')` 按 `component` 字符串**动态解析**；
`src/router/index.ts` 的 `asyncRouterMap` 只静态声明 dashboard/content/user/system 这几个早期分组，
commerce/governance/board/creator-center 都不在里面 —— 所以新增页面**不需要**改静态路由表，
只要 ① 建 `.vue` ② 菜单 `component` 与视图路径一致。本轮据此实现，未动 `src/router/index.ts`。
前端门禁：
```
$ pnpm ts:check → 0 错误（无输出）
$ pnpm exec eslint --ext .js,.ts,.vue ./src
✖ 1 problem (1 error, 0 warnings) # 第一遍：NoticeManagementView.vue prettier 折行
（改完复跑）→ 无输出，0 error
$ pnpm build:pro → Build successful. Please see dist-pro directory
```
### 动作 8：`:3005` 真浏览器实测（Codex in-app browser）
```
登录 admin → 侧边栏出现「订单与权益 → 商品配置」「运营管理 → 系统公告」（其余菜单不变）
#/commerce/products → 标题「商品配置」，11 列与后端字段一一对应，状态列用 statusText（已上架/已下架）
#/operation/notices → 标题「系统公告」，空态「还没有发布公告」
新建商品（UI）→ toast「商品已创建（默认下架，请确认后再上架）」，行内 totalCoin 550、状态「已下架」
新建公告（UI）→ toast「公告已发布」，行内 发布时间 16:32:15、失效时间「-」、状态「已发布」
C 端 GET /app/notices（匿名）→ 立刻能看到这条（total 1）
下架 → toast「公告已下架」→ C 端 total 0
删除 → toast「商品已删除」「公告已删除」→ 列表回到种子数据
溢出检查（1440/1280/1024，两页各一次）
1440: docScroll=1440 clientWidth=1440 overflowX=false
1280: docScroll=1280 clientWidth=1280 overflowX=false
1024: docScroll=1024 clientWidth=1024 overflowX=false
截图：/tmp/i1-product-list.png、/tmp/i1-notice-list.png
```
### 动作 9：❌ 实测抓到的真缺陷 —— 雪花 id 在浏览器里被四舍五入
UI 上点「下架」时后端回：
```
{"code":200002,"message":"公告不存在"} # 明明列表里就有这条
```
定位：
```
$ node -e 'console.log(2111011206851596290, Number.isSafeInteger(2111011206851596290))'
2111011206851596300 false
$ psql -c "select id, title from ops_notice;"
2111011206851596290 | I1 自测公告（UI 创建） # DB 里是 …596290
```
解读：S0 换雪花主键后 id 已超过 JS 安全整数范围（2^53-1 = 9007199254740991）。
浏览器 `JSON.parse` 把 `2111011206851596290` 变成 `2111011206851596300`，
页面拿这个被改过的 id 回查 → `200002`。**这是 S0 之后所有"新建即操作"的通用风险**，
只是本轮新建的页面第一个撞上。
修复（**限定在本轮两个模块的契约内**，不动全局序列化、不动 app-api，避免影响 Flutter 客户端）：
```
fruitshorts-module-commerce/.../ProductRespVO.java id 加 @JsonSerialize(using = ToStringSerializer.class)
fruitshorts-module-system/.../NoticeRespVO.java 同上
ProductAdminController#create / NoticeAdminController#create 返回 Result<String>
ReelShortWeb/src/api/admin/{product,notice}.ts id: string
docs/api-phase1.md §2.11/§2.12 写明"id 以字符串下发"
```
新增两条防回归测试（把真实雪花 id 喂进去断言是字符串）：
`ProductAdminControllerContractTest#should_send_string_id_when_product_id_exceeds_js_safe_integer`、
`NoticeAdminControllerContractTest#should_send_string_id_when_notice_id_exceeds_js_safe_integer`。
### 动作 10：修复后复跑门禁（最终数字）
```
$ mvn test
[INFO] Tests run: 33, Failures: 0, Errors: 0, Skipped: 0 (module-commerce)
[INFO] Tests run: 16, Failures: 0, Errors: 0, Skipped: 0 (admin-api)
[INFO] Tests run: 49, Failures: 0, Errors: 0, Skipped: 0 (app-api)
[INFO] Tests run: 12, Failures: 0, Errors: 0, Skipped: 0 (transcode-worker)
[INFO] BUILD SUCCESS # 共 110 条（存量 91 + 新增 19）
$ mvn -pl fruitshorts-app-api,fruitshorts-admin-api -am package -DskipTests → BUILD SUCCESS
```
修复后复测（同一浏览器，重新起服务后）：
```
点「已发布」→ toast「公告已下架」，行内状态变「已下架」 # 修复前这里是「公告不存在」
C 端 GET /app/notices → {"total":0} # 下架后客户端立即不可见
接口返回类型核对：id= 2111012331625517057 type= str
```
### 动作 11：自测数据清理（收尾）
```
DELETE 1 # 商品 i1_ui_coin_880（第一轮 UI 建的）
DELETE 4 # 公告 4 条（含 UI 建的）
DELETE 1 # 商品 i1_ui2_coin_500（修复后 UI 建的）
DELETE 1 # 公告 I1 复测公告：印尼开服
products | soft_deleted notices
3 | 0 0
```
解读：`product` 表回到 3 行种子（`coin_100 / coin_550 / coin_1200`），`ops_notice` 回 0 行。
**没有留下任何自测数据。**
### 本轮遗留（已写进 INBOX 回执的「待确认」）
1. 雪花 id 的全局方案：admin-api 是否统一 `Long → String`（涉及所有既有页面的 `id` 类型），
app-api 是否要动（影响 Flutter 客户端解析）——属于平台级改动，等裁定。
2. `/app/orders/verify` 的真发币链路需要 Google Play 凭据（B1-1 已列清单）。
---
## 2026-10-16 J1：全局 ID 字符串化（Long → String）+ 契约统一
计划文件：`docs/plans/2026-10-16-J1.md`（先写计划再动手）。用户裁定「方案 (a) 全局修改，统一契约」。
### 动作 1：后端全局序列化（fruitshorts-framework）
新增 `JacksonLongToStringConfig`：`SimpleModule` 把 `Long.class` / `Long.TYPE` → `ToStringSerializer`，
经 `Jackson2ObjectMapperBuilderCustomizer` 挂进 Spring Boot 的 `ObjectMapper`。
两个入口都是 `scanBasePackages = "com.fruitshorts"`，一处生效两端一致，**没改 yml**。
一个刻意的例外：`PageResult.total` 是条数不是 id，用 mixin 显式保持数字（前端分页组件要数字）。
为此给 mixin 加了个 `PlainLongSerializer`（`NumberSerializer` 没有无参构造，`using=` 装不上）。
I1 里给商品/公告 VO 逐个加的 `@JsonSerialize` 与 `Result<String>` 新建返回**已回退成自然写法** ——
全局生效后它们只是冗余特例（现在是"所有模块一个口径"）。
### 动作 2：契约 §0 总口径
`docs/api-phase1.md` §0 新增「**ID 字段一律以字符串下发**」+ 示例 + 边界（`total` 与 `Integer` 保持数字、
id 回传按字符串传），§2.11/§2.12 的逐模块表述改成引用 §0。
### 动作 3：契约测试的 standalone mapper 也挂上模块（否则假绿）
`ControllerContractSupport`（app-api / admin-api 两处）自带手搓 `JsonMapper`，不含全局模块 ——
不改它的话，测试断言数字 id 也会过，而生产早就变成字符串了。挂上模块后：
```
$ mvn test
[INFO] Tests run: 33, Failures: 0, Errors: 0, Skipped: 0 (fruitshorts-module-commerce)
[INFO] Tests run: 21, Failures: 0, Errors: 0, Skipped: 0 (fruitshorts-admin-api)
[INFO] Tests run: 49, Failures: 0, Errors: 0, Skipped: 0 (fruitshorts-app-api)
[INFO] Tests run: 12, Failures: 0, Errors: 0, Skipped: 0 (fruitshorts-transcode-worker)
[INFO] BUILD SUCCESS # 共 115 条（存量 110 + 新增 5）
```
新增 `LongToStringSerializationTest` 5 条：普通字段 / 嵌套对象 / List / Map 值 / 分页（total 数字 + list id 字符串）
/ 请求体 `"id":"…"` 反序列化成 Long / 19 位路径变量绑定成 Long。
另外把 C 端 4 条 id 断言从数字改成 `value("…") + isString()`（原来"数字也能过"的宽松比较不算证据）。
### 动作 4：Web 与客户端适配
见回执的逐文件清单。要点：Web 审计出 4 处把 id 当数字用的地方（代看 id 过 `Number`、
两处 `Number(route.…)` 与 id 比较、菜单顶级哨兵 0 与 "0" 不一致）；Flutter 侧 id 本来就是
`(json['id'] ?? '').toString()`，会崩的是被全局规则扫到的 **Long 计数**，只改了 `expiresIn` 与 `viewCount`。
```
$ pnpm ts:check → 0 错误
$ pnpm exec eslint … ./src → 0 error
$ pnpm build:pro → Build successful
$ dart analyze lib test → No issues found!
$ flutter test → All tests passed! (+167)
```
### 动作 5：端到端复现"修复前后"（真实服务）
```
① 复现 PM 那个场景：C 端注册 → admin 列表/详情
$ curl -X POST :8081/app/auth/register -d '{"targetType":"EMAIL","target":"j1.selftest@example.com",…}'
→ "expiresIn": "7200" # long 字段，已是字符串
$ curl -H "Authorization: …" :8080/admin/app-users/page?pageSize=50
total = 2 int # 分页 total 仍是数字（例外生效）
命中用户: uid=U79DG5IOM id='2111015748376858626' id类型=str
$ curl -H "Authorization: …" :8080/admin/app-users/2111015748376858626
code= 0 message= ok # 修复前这里就是 200002
data.id= '2111015748376858626' uid= U79DG5IOM
```
```
② JS 侧逐位一致（真实响应喂 node）
$ node -e '…'
响应原文里的 id（JSON 字符串）: "2111015748376858626"
typeof 解析后 : string
String(parsed.id) : 2111015748376858626
库里 app_user.id : 2111015748376858626
逐位相等? : true
---- 反面对照：同一串数字当裸数字解析 ----
裸数字 -> String(parsed.id) : 2111015748376858600
逐位相等? : false
```
```
③ 全局范围：换两个模块（商品 / 创作者）走"新建 → 用响应 id 查详情 → 改状态"
新建商品响应 : {"code":0,"data":"2111015841427492865"}
商品详情 : code=0 id='2111015841427492865'
商品上架 : {"code":0}
新建创作者响应 : {"code":0,"data":"2111015841771425794"}
创作者详情 : code=0 id='2111015841771425794' name=J1 探针工作室
```
```
④ C 端字段类型（匿名可读的链路）
/app/home/feed : drama card id='5'(str) viewCount='3100000'(str)
/app/dramas/5 : id='5'(str) viewCount='3100000'(str) totalEpisodes=72(int) episode id='7'(str)
/app/episodes/7/play : episodeId='7'(str) dramaId='5'(str) durationSec=228(int) unlockCoin=0(int)
```
解读：**Long → 字符串**（id、viewCount、expiresIn、coinAmount），**Integer/int 与分页 total 仍是数字**，
与 §0 的规则和例外完全对上。
### 动作 6：自测数据清理（含一次口径纠正）
```
DELETE 1 # 自测用户 app_user（含 credential 2 / session 2 / device 2 / consent 3 / wallet 1）
DELETE 1 # 商品 j1_probe_coin
DELETE 1 # 创作者 J1PROBE
全库扫描 uid / 邮箱 / 雪花 id → 无任何残留（NOTICE: 扫描完成）
现存：creator 只剩 PM 那条 id=25（CR20261015001）、app_user 只剩 id=28（UHR-DLTH8）、
product 3 行种子、ops_notice 0 行 —— 都不是本轮数据。
```
⚠️ 口径纠正：我第一版清理脚本用 `psql -t -A -c "delete … returning 1" | wc -l` 数"行数"，
**数到的其实是 psql 的命令标签**（实测删 0 行时输出 `DELETE 0`，也是 1 行），所以那轮打印的
"删除 1 行"是假数字。真正的证据是后面的**全库残留扫描**（零命中）与现存数据核对，已按此结论写回执。
---
## 2026-10-16 K1：客户端对接（详情 + 播放 + 进度续看 + 收藏）+ 三态 UI
计划文件：`docs/plans/2026-10-16-K1.md`（先写计划再动手）。仓库：`ReelShort`（Flutter，develop）。
### 动作 1：勘察更正
条目说"客户端只调了 6 个接口、没有详情和票据"——实测**详情已接**（`CatalogApi.dramaDetail`），
**票据半接**（`CatalogApi.playTicket` 存在但没页面调用）。这一点写进计划与回执。
### 动作 2：分层实现（api → repository → logic → view）
- 新增 `playback_api.dart` / `watch_api.dart` / `library_api.dart` + `watch_progress.dart` 模型
- 新增 `PlaybackRepository`（票据 TTL 缓存，默认 10 分钟；时钟/TTL 可注入）、`FavoriteRepository`
- `WatchHistoryRepository` 换成服务端模型（每剧一条续看记录），删掉 `demoProfileId` 与 SharedPreferences 实现
- `FavoriteController` 乐观更新 + 失败回滚；`app.dart` 注入三个仓库与收藏控制器
### 动作 3：门禁（最终数字）
```
$ dart analyze lib test
No issues found!
$ flutter test
00:09 +188: All tests passed!
```
新增测试：`playback_ticket_expiry_test`（票据过期重取 + 签名 query 原样保留）、
`progress_throttle_test`（10 秒节流 + 切集补报 + 播完 finished + 续看定位）、
`watch_history_test`（重写为服务端模型）、`library/favorite_controller_test`（回滚/错误态/退出清空）、
`integration/live_watch_flow_test`（真实后端端到端）。
### 动作 4：真实后端联调（8081，原始输出）
```
① 首页 → dramaId=5
② 详情 → episodes=3，第一集 id='7' playUrl=/files/episode/202610/cec39d8e….mp4?e=1792144372&s=8791826a…
③ 票据 → episodeId='7' dramaId='5' accessType=FREE accessible=True
playUrl 与详情里的签名地址一致（客户端只补 host，不动 path/query）
④ 上报进度（42s）→ {"dramaId":"5","episodeId":"7","positionMs":"42000","durationMs":"228000","playCount":1}
⑤ 读回续看位置 → dramaId='5' episodeId='7' positionMs='42000' durationMs='228000'
⑥ 最近观看 → 条数=1，dramaId='5' episodeId='7' positionMs='42000'
⑦ 收藏 → toggle 返回 true → 收藏列表条数=1（首个 '5'）→ DELETE → 取消后条数=0
```
`flutter test test/integration/live_watch_flow_test.dart` → All tests passed（同一链路在客户端代码里跑通）。
解读：`positionMs/durationMs/dramaId` 都是**字符串**（J1 的新口径），客户端用 `jsonToInt` 解析。
### 动作 5：自测数据清理
```
已清理 2 个自测账号（k1.selftest.* / k1.receipt.*）+ 依赖行
残留核对：app_user 1 行（PM 的 id=28）、app_user_credential 1 行、watch_progress 0、user_favorite 0
```
（第一次清理漏了 `app_user` 本体——它的主键列叫 `id` 不是 `user_id`，随后单独删掉并复核。）
---
## 2026-10-16 K1-verify：用正确地址重做真机验证（设备侧取证）—— 结果：**未验证（已按用户要求交回用户执行）**
红线第 10 条新增后，本轮目标是"用正确地址 + 设备侧证据"重做真机验证。以下是逐动作留痕。
### 动作 1：取真实地址（不硬编码）
```
$ ipconfig getifaddr en0
192.168.31.187
$ for i in en0 en1 en2 utun0..3; do ipconfig getifaddr $i; done
en0 = 192.168.31.187 # 只有 en0 有地址；旧的 10.157.242.1 已不存在
$ lsof -nP -iTCP:8081 -sTCP:LISTEN
java 80383 ... TCP *:8081 (LISTEN)
```
### 动作 2：加设备侧集成测试（可重复、可入库的证据）
- `pubspec.yaml` dev_dependencies 加 `integration_test`（sdk）
- 新增 `integration_test/app_backend_test.dart`：在**手机进程里**请求 `/app/home/feed` 与 `/app/dramas/{id}`，
断言列表非空、详情 id 一致；再用真 App 跑一遍，断言首页底部标签栏出现（= 剧目列表加载成功）。
两个用例都把 `API_BASE_URL` 打进设备日志，便于区分"地址不对"还是"设备连不上"。
- `dart analyze lib test integration_test` → No issues found!
### 动作 3：第一次真机执行（**设备侧输出，17:56**）
```
$ IP=$(ipconfig getifaddr en0) && flutter test integration_test -d 00008101-000875813E42001E \
--dart-define=API_BASE_URL=http://$IP:8081
Running Xcode build... Xcode build done. 31.3s
Installing and launching... 20.0s
00:00 +0: should_fetch_home_feed_and_drama_detail_when_device_reaches_backend
[device] API_BASE_URL=http://192.168.31.187:8081
[device] 首页分区=4 剧目=3
[device] 详情 id=5 剧集=3
00:01 +1: should_render_home_drama_list_when_app_boots_on_device
[device] 首页剧目列表已渲染：API_BASE_URL=http://192.168.31.187:8081
00:05 +2: (tearDownAll)
00:06 +2: All tests passed!
```
解读：`[device]` 行是**手机进程里**打印的（不是开发机 curl），断言也在手机进程里跑；这一次是全过的。
### 动作 4：第二次执行（只跑第一个用例，17:59）—— 失败
```
Running Xcode build... Xcode build done. 17.8s
Installing and launching...
The Dart VM Service was not discovered after 60 seconds. This is taking much longer than expected...
```
我同时起了 lsof 轮询想抓"手机 IP → 8081"的已建立连接，**一个连接都没抓到**（原始文件只有 lsof 表头）——
因为 app 那次根本没 attach 上，也就没有发请求。这一步没有产出任何设备侧证据。
### 动作 5：第三次（`flutter run` 真机跑，18:03–18:04）—— 被叫停
```
Launching lib/main.dart on iPhone in debug mode...
Running Xcode build... Xcode build done. 30.4s
Installing and launching...
You may be prompted to give access to control Xcode...
```
PM 报告：该轮后续撞上 iOS 构建报错
`build/ios/iphoneos/video_player_avfoundation_video_player_avfoundation.bundle: No such file or directory`，
并把进程停掉、执行了 `flutter clean`（我自己的日志到 "Installing and launching" 为止，上面这条报错文本来自 PM 报告，不是我抓到的）。
**推测成因（如实写，未定论）**：我这轮 flutter run 与另一次执行**并发写同一个 build/ 目录**，
产物被互相破坏（PM 也把"并发写 build 目录"列为成因之一）。
### 动作 6：按用户指令停止执行，转为交接
用户 20:45 指令：「codex 不用跑测试 我来执行」。我随即：
```
$ kill -TERM 76461 76458 76675 77472 76250 # 我的 flutter run / xcodebuild / frontend_server / lsof 轮询
$ pgrep -fl "flutter_tools|xcodebuild|k1v_poller"
4173 ... flutter_tools.snapshot daemon # 只剩 IDE 常驻 daemon（非构建）
```
`build/` 目录里留着我被 kill 的那次构建的半成品，用户按 `flutter clean && flutter pub get` 起跑即可清掉。
### 结论口径
- 按**红线第 10 条**与用户要求：本批真机验证**标注「未验证」**，由用户执行后以用户的结果为准。
- 动作 3 那次是**真实的设备侧输出且全过**，但随后两次执行失败（一次 VM service 未 attach、一次构建产物缺失），
所以在用户重跑之前**不把它当作最终结论**；它作为历史记录保留在这里。
- 我**没有**用任何"开发机 curl"作为设备可达证据。
---
## 2026-10-17 K2：分类 + 观看记录 + 收藏列表 + 下载授权管理
### 动作 1：按 INBOX 指定顺序读取规范与契约
叙述：开工前先完整核对 INBOX K2 条目、项目约束、Git 流程、接口 §0/§1.3/§1.5/§1.6，
再读 A3/A5、CONTENT/RECORD 用例与测试计划。当前没有启动客户端构建，也没有改业务代码。
```
$ sed -n '1,260p' docs/plans/INBOX.md
# INBOX — 给 Codex 的指令队列（FruitServer 仓库内）
## [待处理] 2026-10-17 | K2 客户端第二批：分类 + 观看记录 + 收藏列表 + 下载授权（A3/A5 剩余）+ UI
本批只做 K2，做完停下写回执，不要连做 K3/K4。
接口只认 FruitServer/docs/api-phase1.md §1.3 / §1.5 / §1.6
$ sed -n '1,260p' /Users/jianghaifeng/Desktop/ReelShort/AGENTS.md
# 水果短剧（FruitShorts）— Codex 项目上下文
## 强制约束（不可违反）
## 自主执行原则（Autonomy — 最高优先级）
$ sed -n '1,340p' /Users/jianghaifeng/Desktop/ReelShort/CODING_STANDARDS.md
## 3. Dart / Flutter（ReelShort）
TDD 强制：先写测试（红灯）→ 实现（绿灯）→ 重构
门禁：dart analyze lib test 零告警 + flutter test 全过
$ sed -n '1,300p' /Users/jianghaifeng/Desktop/ReelShort/GIT_WORKFLOW.md
## 一、分支模型（Git Flow）
feature/*：具体功能开发，来源 develop
合并一律 --no-ff（禁用 fast-forward）
$ sed -n '1,64p;150,158p;186,222p' docs/api-phase1.md
## 0. 通用约定
所有 ID 字段（主键与外键）在 JSON 里都是字符串
### 1.3 内容浏览（已实现）
GET /app/categories | 分类列表
### 1.5 观看记录与收藏（已实现）
GET /app/watch/recent?limit=20 | 最近观看
DELETE /app/watch/progress/{dramaId} | 删除某剧记录
DELETE /app/watch/progress | 清空记录
### 1.6 离线下载（已实现）
GET /app/downloads/policy
PUT /app/downloads/settings
POST /app/downloads
GET /app/downloads
GET /app/downloads/{episodeId}/url
POST /app/downloads/{episodeId}/progress
DELETE /app/downloads/{episodeId}
DELETE /app/downloads
$ sed -n '1,90p' /Users/jianghaifeng/Desktop/ReelShort/docs/plans/codex-研发任务清单.md
- A3 内容（03）：首页 feed、发现 feed、分类、详情（一次请求渲染详情页）、搜索。
- A5 记录/收藏（05）：观看记录、最近观看、收藏切换与列表、下载授权。
$ sed -n '1,135p' /Users/jianghaifeng/Desktop/ReelShort/docs/16-测试用例库.md
TC-CONTENT-09 | 分类题材 | 有分类 | 查看分类 | 分类列表正确 | P2
TC-RECORD-01 | 观看历史 | 有播放 | 查看历史 | 按时间倒序，可删除 | P0
TC-RECORD-03 | 取消收藏 | 已收藏 | 取消 | 状态反转 | P0
TC-RECORD-04 | 收藏列表 | 有收藏 | 查看 | 分页正确 | P1
TC-RECORD-09 | 历史清空 | 有历史 | 清空 | 全部清空 | P2
$ sed -n '1,100p' /Users/jianghaifeng/Desktop/ReelShort/docs/09-测试计划.md
单元测试 | Dart 核心类 | flutter test | 核心模块 ≥80%
UI 测试 | 关键页面 | Flutter widget test | 核心页面
```
解读：K2 范围、TDD 顺序、接口白名单、三语言文案、三态、登录闸、门禁与设备验证边界均已确认。
搜索没有契约接口，本批不做；收藏分页和观看记录卡片字段按 INBOX 的降级方案处理。
### 动作 2：只读核对两个仓库基线与客户端现状
叙述：确认客户端从干净 `develop` 开工，并核对现有网络层、记录/收藏实现和页面入口，
用于计划中的真实文件清单。
```
$ git status --short --branch && git log -5 --oneline --decorate
## develop...origin/develop
00280ca (HEAD -> develop, origin/develop) merge: 同步 main 的作者标识提交到 develop
84a1f58 test(client): 新增设备侧集成测试（真机跑通后端可达性）
d7eff4c feat(client): 对接详情/播放/进度续看/收藏（K1 看剧闭环）+ 三态 UI
$ git status --short --branch && git log -5 --oneline --decorate # FruitServer
## develop...origin/develop
4118efd (HEAD -> develop, origin/develop) docs(inbox): 按 specs 补全 K2 执行规范与门禁
096e90c docs(inbox): 记录用户裁定——K2 先按现状契约执行，契约缺口后期再补
582453f docs(inbox): 下发 K2 客户端第二批（分类/记录/收藏/下载授权 + UI）
$ find lib -maxdepth 4 -type f | sort
lib/core/data/remote/catalog_api.dart
lib/core/data/remote/library_api.dart
lib/core/data/remote/watch_api.dart
lib/pages/discover/discover_view.dart
lib/pages/mine/mine_view.dart
...
```
解读：两仓均无未提交改动。分类 API、下载 API/page/controller 不存在；
观看记录删除只有单条，没有清空；收藏数据层已有但无独立页面；
`ApiClient` 只有 GET/POST/DELETE，下载设置所需的 PUT 需最小补齐。
### 动作 3：写 K2 计划
叙述：先落计划再动业务代码，明确四块范围、实施顺序、影响文件、三个契约缺口、
风险和待确认项。
```
文件：docs/plans/2026-10-17-K2.md
章节：范围与完成口径 / 实施顺序与 TDD / 预计影响文件 /
契约缺口 / 风险与控制 / 待确认 / 完成定义
```
解读：后续实现按 K2-A → K2-B → K2-C → K2-D 推进；每块先红后绿并单独跑门禁。
真机与 Android 构建结果按实际证据记录，缺失时明确标“未验证”。
### 动作 4：创建功能分支并跑存量基线门禁
叙述：客户端从 `develop` 创建任务指定分支；沙箱不允许写 `.git/index.lock`，
Git 与 Flutter 工具链缓存写操作按权限流程在受控环境执行。先确认存量门禁本身是绿的。
```
$ git checkout -b feature/flutter-k2-library develop
Switched to a new branch 'feature/flutter-k2-library'
## feature/flutter-k2-library
$ dart analyze lib test
Analyzing lib, test...
No issues found!
$ flutter test
00:10 +188: All tests passed!
```
解读：客户端基线 188 个测试全过、静态检查零告警，可以开始 K2-A。
### 动作 5：K2-A 测试红灯
叙述：先新增分类模型/API/控制器的契约测试，覆盖雪花 ID 字符串、分类到
`category-{id}` 分区映射、缺失分区空态、hot/new 入口、全量去重和失败重试。
```
$ flutter test test/category/category_controller_test.dart
test/category/category_controller_test.dart:6:8: Error: Error when reading
'lib/core/data/models/content_category.dart': No such file or directory
test/category/category_controller_test.dart:10:8: Error: Error when reading
'lib/core/data/remote/category_api.dart': No such file or directory
test/category/category_controller_test.dart:11:8: Error: Error when reading
'lib/core/data/repositories/category_repository.dart': No such file or directory
test/category/category_controller_test.dart:12:8: Error: Error when reading
'lib/core/data/services/category_controller.dart': No such file or directory
00:00 +0 -1: Some tests failed.
```
解读：红灯原因符合预期，目标实现尚不存在。下一步实现分类数据层与控制器。
### 动作 6：K2-A 实现绿灯与门禁
叙述：实现 `ContentCategory`、`CategoryApi`、`CategoryRepository`、
`CategoryController`，发现页改为读取 `/app/categories` 与 `/app/discover/feed`；
保留 For You / Hot / New 样式，服务端分类只匹配 `category-{id}`。
```
$ flutter test test/category/category_controller_test.dart
00:00 +5: All tests passed!
$ dart analyze lib test
Analyzing lib, test...
No issues found!
$ flutter test
00:08 +191 ~1: All tests passed!
```
解读：分类块绿。`~1` 是既有真实后端联调用例因本机 8081 未启动而按设计跳过，
不是失败。分类 UI 仍保留 hot/new 入口；后端发现 feed 未下发对应分区时显示空态。
### 动作 7：K2-B 测试红灯
叙述：先固定观看记录页核心逻辑：`updatedAt` 解析、recent 按 dramaId 去重、
详情并发上限 4、单条详情失败降级与单项重试、删除/清空乐观回滚、recent 失败态。
```
$ flutter test test/watch/watch_records_controller_test.dart
test/watch/watch_records_controller_test.dart:11:8: Error: Error when reading
'lib/core/data/services/watch_records_controller.dart': No such file or directory
test/watch/watch_records_controller_test.dart:23:3: Error: No named parameter
with the name 'updatedAt'.
test/watch/watch_records_controller_test.dart:49:21: Error: The getter
'updatedAt' isn't defined for the type 'WatchProgress'.
00:00 +0 -1: Some tests failed.
```
解读：红灯符合预期，观看记录控制器与更新时间字段尚不存在。
### 动作 8：K2-B 实现与门禁
叙述：增加 `updatedAt`、观看记录清空 API/repository，新增独立
`WatchRecordsController` 与 `WatchRecordsPage`。“我的 → 观看记录”已改为打开独立页。
详情请求按 dramaId 去重、最多 4 个并发；单条详情失败显示占位与单项重试；
单删和清空先更新 UI，失败回滚并提示；清空有二次确认。
```
$ flutter test test/watch/watch_records_controller_test.dart test/watch/watch_records_page_test.dart
00:00 +10: All tests passed!
$ dart analyze lib test
Analyzing lib, test...
No issues found!
$ flutter test
00:08 +201 ~1: All tests passed!
```
解读：K2-B 绿。`~1` 仍是既有真实后端联调用例跳过；本轮新增 10 个记录相关测试。
### 动作 9：K2-C 测试红灯
叙述：先补收藏取消失败的原位回滚测试，再新增独立收藏页的卡片、取消失败、
空态、失败重试与未登录闸测试。
```
$ flutter test test/library/favorite_controller_test.dart test/library/favorites_page_test.dart
test/library/favorite_controller_test.dart:80:8: Error: The setter 'failRemove'
isn't defined for the type 'InMemoryFavoriteRepository'.
test/library/favorites_page_test.dart:13:8: Error: Error when reading
'lib/pages/favorites/favorites_page.dart': No such file or directory
test/library/favorites_page_test.dart:108:23: Error: The getter 'listCalls'
isn't defined for the type 'InMemoryFavoriteRepository'.
00:00 +0 -2: Some tests failed.
```
解读：红灯符合预期：独立收藏页不存在，测试仓库也还不能模拟删除失败。
### 动作 10：K2-C 实现与门禁
叙述：新增独立 `FavoritesPage` 和复用列表卡片，服务端列表三态齐全；
取消收藏采用乐观更新，失败时按原索引回滚；我的页增加“我的收藏”入口。
```
$ flutter test test/library/favorite_controller_test.dart test/library/favorites_page_test.dart
00:00 +13: All tests passed!
$ dart analyze lib test
Analyzing lib, test...
No issues found!
$ flutter test
00:10 +207 ~1: All tests passed!
```
解读：K2-C 绿。收藏页按契约全量读取，不发送 `page/size`；真实后端联调用例仍按设计跳过。
### 动作 11：K2-D 测试红灯
叙述：先用 API 契约测试钉住 §1.6 全部 8 个下载接口与字符串 ID；
再用控制器测试固定策略/授权加载、后端 message 透传、设置回滚、删除和清空回滚。
```
$ flutter test test/download/download_api_test.dart test/download/download_controller_test.dart
test/download/download_api_test.dart:7:8: Error: Error when reading
'lib/core/data/remote/download_api.dart': No such file or directory
test/download/download_controller_test.dart:4:8: Error: Error when reading
'lib/core/data/models/download_license.dart': No such file or directory
test/download/download_controller_test.dart:9:31: Error: Type
'DownloadController' not found.
00:00 +0 -2: Some tests failed.
```
解读：红灯符合预期，下载模型、API、仓库与控制器尚未实现。
### 动作 12：K2-D 数据层与页面实现
叙述：实现下载策略/授权模型、8 个接口的 `DownloadApi`、仓库与控制器；
`ApiClient` 仅补契约需要的 `PUT`。新增“我的下载”页，展示策略、配额、
授权/任务原始状态、进度、有效期，并提供仅 Wi-Fi、清晰度、单删和清空；
详情页与播放页接入真实授权申请。授权失败直接展示后端 `message`。
```
$ flutter test test/download/download_api_test.dart test/download/download_controller_test.dart test/download/downloads_page_test.dart
00:00 +10: All tests passed!
$ dart analyze lib test
Analyzing lib, test...
No issues found!
$ flutter test
00:10 +219 ~1: All tests passed!
```
解读：K2-D 首轮绿。文件分片落盘、断点续传、离线播放、`licenseKey` 本地校验未做，
`url` 与 `progress` 只交付 API 方法；这些边界不会写成“已完成”。
### 动作 13：提交前边界审查（清晰度下拉修复）
叙述：审查发现当后端策略 `maxQuality` 已是 `720P/1080P` 时，
下拉选项会重复同一值并触发 Flutter 断言。先补测试得到红灯，再去重选项；
同时处理退出后重新登录页面不刷新、登录闸文案覆盖观看记录/下载的问题。
```
$ flutter test test/download/downloads_page_test.dart
Failed assertion: There should be exactly one item with
[DropdownButton]'s value: 720P.
Either zero or 2 or more [DropdownMenuItem]s were detected with the same value
00:01 +6 -1: Some tests failed.
$ flutter test test/download/downloads_page_test.dart
00:00 +7: All tests passed!
```
解读：边界缺陷已由测试固定并修复，避免特定后端清晰度值导致下载页崩溃。
### 动作 14：最终门禁与 Android 构建
叙述：整理掉格式化造成的无关测试 diff 后，在 develop 合并前后都复跑门禁。
首次 Android 构建因本机 Gradle 依赖经代理下载持续约 12 分钟，但最终成功；
修复后二次构建命中缓存（2.377 秒）。
```
$ dart analyze lib test
Analyzing lib, test...
No issues found!
$ flutter test
00:11 +220 ~1: All tests passed!
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 705.7s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
$ flutter build apk --debug # 最终修复后
Running Gradle task 'assembleDebug'... 2,377ms
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
解读：静态检查零告警、220 个测试通过；`~1` 是既有真实后端联调用例因本机未启动
8081 服务按设计跳过。Android debug APK 构建通过。
### 动作 15：Git 提交、合并与推送
叙述：客户端从干净 develop 建功能分支，功能提交与 `--no-ff` 合并提交均使用
项目规定作者。合并前确认 `origin/develop` 无新提交；合并后在 develop 复跑门禁，
再 push，最后删除已完成 feature 分支。未改 main。
```
commit=cc4d7c5a9dc6a4f6f0565a32503cce5973af703c
author=Zhou Weidong <502333560@qq.com>
subject=feat(flutter): 接入分类记录收藏与下载授权
merge=45f5f25640a274edb51bd90b3b5e52c43ba9d9cd
author=Zhou Weidong <502333560@qq.com>
subject=merge: 合并 K2 客户端分类记录收藏与下载授权
$ git push origin develop
To http://git.reelshort2.com/jianghaifeng/ReelShort.git
00280ca..45f5f25 develop -> develop
$ git branch -d feature/flutter-k2-library
Deleted branch feature/flutter-k2-library (was cc4d7c5).
```
解读：客户端 develop 已与 origin/develop 对齐，工作区干净。
### 动作 16：真实数据与未验证边界
叙述：生产环境注入的发现分类、观看记录、收藏、下载授权均调用契约 HTTP 接口，
不再用本地演示目录补齐。由于设备侧验证归用户执行，本轮没有把任何开发机请求
当作“设备可达”证据。
```
已接生产 HTTP 链路：
- GET /app/categories + GET /app/discover/feed
- GET /app/watch/recent + DELETE /app/watch/progress/{dramaId} + DELETE /app/watch/progress
- GET /app/favorites + DELETE /app/favorites/{dramaId} + POST /app/favorites/toggle
- §1.6 全部 8 个 /app/downloads* 契约接口
仍未做：
- 搜索（契约无接口）
- 下载文件分片落盘 / 断点续传 / 离线播放 / licenseKey 本地校验
- 真机 / 模拟器侧验证（未验证，由用户执行）
```
解读：功能代码和构建门禁已完成；设备网络、实际授权状态与 UI 交互需用户按回执步骤验证。
### 动作 17：用户真机验收清单
叙述：本动作只补齐验收证据与回执缺项，不新做功能、不改 ReelShort 产品代码。
本轮重新核对 ReelShort `develop` 为 `45f5f25`，FruitServer 文档开工前为 `698bb78`；
并复跑 `dart analyze lib test`、`flutter test`、`flutter build apk --debug`。
设备侧取证由用户执行，Codex 未执行。下面所有“预期”都是用户在手机上应看到的业务结果；
开发机 `curl` 只用于检查后端是否启动，不作为手机可达或设备侧验收证据。
#### 17.1 本轮门禁复跑原始输出
叙述：先确认 8081 监听状态，再按 ReelShort `develop` 顺序复跑三个客户端门禁。
Flutter 首次在受限沙箱内运行时被拒绝写 SDK 缓存
（`engine.stamp.tmp` / `engine.realm: Operation not permitted`），
随后在受控环境用同一组命令复跑；下面贴的是复跑成功的原始输出。
```
$ lsof -nP -iTCP:8081 -sTCP:LISTEN
（无输出，说明本轮复跑时 8081 未监听）
$ flutter devices
Found 3 connected devices:
iPhone (mobile) • 00008101-000875813E42001E • ios • iOS 26.6.1 23G83
macOS (desktop) • macos • darwin-arm64 • macOS 15.5 24F74 darwin-arm64
Chrome (web) • chrome • web-javascript • Google Chrome 155.0.8059.80
Checking for wireless devices...
No wireless devices were found.
Run "flutter emulators" to list and start any available device emulators.
```
```
$ cd /Users/jianghaifeng/Desktop/ReelShort/ReelShort
$ dart analyze lib test
Analyzing lib, test...
No issues found!
$ flutter test
test/integration/live_watch_flow_test.dart: should_complete_the_watch_flow_when_backend_is_running
客户端接口服务未启动，已跳过联调测试
test/integration/live_auth_test.dart: should_surface_business_error_when_sign_in_uses_unknown_email
客户端接口服务未启动，已跳过联调测试
test/integration/live_catalog_test.dart: should_parse_banner_and_sections_when_home_feed_is_fetched
客户端接口服务未启动，已跳过联调测试
test/integration/live_catalog_test.dart: should_order_episodes_by_number_and_attach_url_when_detail_is_fetched
客户端接口服务未启动，已跳过联调测试
test/integration/live_catalog_test.dart: should_return_play_url_when_episode_is_playable
客户端接口服务未启动，已跳过联调测试
00:10 +216 ~5: All tests passed!
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 2,672ms
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
解读：静态检查零告警；8081 未启动时测试结果是 `+216 ~5`，5 条跳过均来自 live 联调用例的
`markTestSkipped`，不是失败；Android debug APK 构建成功（缓存命中，`2,672ms`）。
本轮没有设备侧业务证据，也没有用开发机请求替代手机取证。
#### 17.2 从零前置条件
以下命令都需要在 Mac 终端执行。第 1 步只在首次搭建环境时执行；已有数据库可跳过。
1. 启动 PostgreSQL；首次环境再建角色、数据库并初始化脚本。
```
$ brew services start postgresql@18
$ export PATH="/opt/homebrew/opt/postgresql@18/bin:$PATH"
$ psql -d postgres -c "CREATE ROLE fruitshorts LOGIN PASSWORD 'fruitshorts';"
$ psql -d postgres -c "CREATE DATABASE fruitshorts OWNER fruitshorts ENCODING 'UTF8';"
$ cd /Users/jianghaifeng/Desktop/ReelShort/FruitServer
$ psql -h 127.0.0.1 -U fruitshorts -d fruitshorts -f sql/schema.sql
$ psql -h 127.0.0.1 -U fruitshorts -d fruitshorts -f sql/data.sql
$ psql -h 127.0.0.1 -U fruitshorts -d fruitshorts -f sql/schema-phase1.sql
$ psql -h 127.0.0.1 -U fruitshorts -d fruitshorts -f sql/partition-maintenance.sql
$ psql -h 127.0.0.1 -U fruitshorts -d fruitshorts -f sql/data-phase1.sql
```
预期：五个 SQL 脚本按顺序执行完成，没有主键冲突或表不存在错误。
重复执行是幂等的；不要颠倒 `partition-maintenance.sql` 与 `data-phase1.sql` 的顺序。
2. 构建并启动客户端接口服务 8081。
```
$ cd /Users/jianghaifeng/Desktop/ReelShort/FruitServer
$ mvn -pl fruitshorts-app-api -am package -DskipTests
$ java -jar fruitshorts-app-api/target/fruitshorts-app-api-1.0.0-SNAPSHOT.jar
```
预期：启动日志出现 `Started AppApiApplication`；另开终端检查：
```
$ lsof -nP -iTCP:8081 -sTCP:LISTEN
java ... TCP *:8081 (LISTEN)
$ curl -fsS http://127.0.0.1:8081/healthz
{"code":0,...,"data":{"status":"UP","app":"fruitshorts-app-api",...}}
```
`curl` 只证明开发机上的 8081 已启动，不能证明手机可达。
3. 准备手机与局域网。
- 手机和 Mac 连接同一个 Wi-Fi；关闭会隔离客户端的访客网络/VPN 代理。
- iPhone 首次启动 App 时，在系统弹窗中允许「本地网络」权限。
- Mac 防火墙若拦截 Java，到「系统设置 → 网络 → 防火墙 → 选项」允许 `java` 传入连接。
- 同网段地址用 `IP=$(ipconfig getifaddr en0)` 获取。若为空，先确认当前 Wi-Fi 网卡名，
再改用对应接口（如 `en1`）。
预期：终端打印形如 `192.168.x.x` 的局域网地址；手机浏览器能访问
`http://<该地址>:8081/healthz`，页面显示 `"status":"UP"`。
4. 获取 Flutter 运行设备号。
```
$ cd /Users/jianghaifeng/Desktop/ReelShort/ReelShort
$ flutter devices
```
预期：真机以 `iPhone (mobile) • <UDID> • ios` 形式出现。本轮机器识别到的设备号是
`00008101-000875813E42001E`；换手机或重装后必须重新执行 `flutter devices`，
不能继续照抄旧 UDID。也可以执行 `xcrun xctrace list devices` 查 iPhone UDID。
这里的“运行设备号”用于 `flutter run -d`。下载绑定使用的设备号是另一个概念：
客户端首次运行会在本地生成并持久化，随后由 `ApiClient` 作为 `X-Device-Id` 发送，
用户不需要也不能在界面上手填。测试文件里的 `dio-check-device`、`k1-live-device`
只是测试固定值，不是生产 App 的设备号。
5. 用当前 Mac 的局域网 IP 注入接口地址并运行 App。
```
$ cd /Users/jianghaifeng/Desktop/ReelShort
$ git checkout develop
$ git pull origin develop
$ git rev-parse HEAD
45f5f25640a274edb51bd90b3b5e52c43ba9d9cd
$ cd ReelShort
$ IP=$(ipconfig getifaddr en0)
$ echo "API_BASE_URL=http://$IP:8081"
$ flutter run -d 00008101-000875813E42001E \
--dart-define=API_BASE_URL=http://$IP:8081
```
`API_BASE_URL` 是 Dart 编译期 `--dart-define`，不是 `export API_BASE_URL=...` 环境变量；
改了地址必须停止 App 后用新参数重新 `flutter run`，热重载不会替换它。
真机不能用 `127.0.0.1` 访问 Mac，Android 模拟器才用 `10.0.2.2:8081`。
预期：App 启动后首页和发现页能加载封面、标题与分区；手机没有出现网络异常空屏。
如果页面一直报网络错误，先在手机浏览器验证第 3 步的 `/healthz`，再检查 Mac 防火墙和
本地网络权限；不要用开发机 `curl` 冒充设备通过。
#### 17.3 K2-A 分类验收
1. 打开「发现」页。
预期：先出现分类/分区加载态，随后分类条显示保留的 `For You`、`Hot`、`New` 入口，
再显示后端 `/app/categories` 返回的分类名称。默认种子数据下包括「都市情感」「重生逆袭」
「甜宠爱情」「悬疑复仇」；数据库改过名称时以实际后端返回名称为准。
2. 依次点「都市情感」「甜宠爱情」。
预期：顶部对应分类 chip 高亮；下方只展示 `/app/discover/feed` 中
`code == "category-{id}"` 的分区卡片。切换分类时内容跟着切换，不会保留上一个分类的卡片。
3. 点默认种子中没有已发布内容的「重生逆袭」或「悬疑复仇」。
预期：分区区域显示「这个分类暂时没有剧集。」。这是无分区空态，不应出现自行拼装的推荐列表、
旧分类残留卡片或网络失败文案。
4. 切回有内容的分类。
预期：卡片恢复显示；封面和标题与后端发现 feed 一致；点卡片可进入对应详情。
5. 失败与重试：停止 8081，冷启动 App 后打开「发现」页。
预期：分类区域显示「分类加载失败。」和「重试」按钮，不白屏。
重新启动 8081 后点「重试」，预期分类和分区恢复显示；必要时下拉刷新。
设备侧只能直接证明服务端分类名称与分类切换结果；`category-{id}` 的代码映射、
全量去重和并发/重试细节由 `test/category/category_controller_test.dart` 自动化覆盖。
解读：K2-A 的用户验收点是“分类条来自服务端、内容只取对应 `category-{id}` 分区、
缺失分区显示空态、失败可重试”；真机没有执行这些步骤，当前结论仍为未验证。
#### 17.4 K2-B 观看记录验收
1. 登录后播放任意一部剧的免费集约 10 秒，返回并进入「我的 → 观看历史」。
预期：页面先显示加载态，随后出现该剧卡片；卡片可见封面、剧名、
「第 N 集」、进度条、`续看至 mm:ss / mm:ss` 和「更新于 ...」。
即使该剧不在首页/发现已加载目录中，也应正常显示，不能因为目录里匹配不到而消失。
2. N+1 合并卡片：对同一部剧先后播放两个不同剧集，再播放另一部剧的一集，重新打开观看历史。
预期：同一部剧只出现一张卡片，不因看过多个剧集而重复；卡片展示该剧最新进度和对应集号。
不同剧各自一张卡片。详情是按 `dramaId` 去重后补取的，单条卡片加载中不应拖住其他卡片。
3. 单条删除：点某张卡片右侧的关闭图标。
预期：卡片立即从页面消失；返回再进入观看历史后仍然不存在。
4. 单删失败回滚：保持页面已加载，停止 8081，再点另一张卡片的关闭图标。
预期：卡片先乐观消失，随后回到原位置，并出现「删除记录失败，请重试。」。
重新启动 8081 后，删除动作可再次执行。
5. 清空：点页面右上方「清空」。
预期：先弹出「清空观看记录？」及「这会从当前账号移除全部观看记录。」；
点「暂不」列表保持不变；点「清空」后列表变空并显示「还没有观看记录。」。
6. 清空失败回滚：有记录且页面已加载时停止 8081，点「清空」并在二次确认中点「清空」。
预期：列表先清空，随后恢复原记录，并出现「清空观看记录失败，请重试。」。
7. 三态和失败重试：后端正常时进入页面观察加载态；清空后观察空态；停止 8081 后冷启动 App
再进入观看历史，观察「续看进度加载失败。」和「重试」。重启 8081 后点「重试」，
预期记录重新加载。
若单条详情请求失败，预期该卡片显示「剧集信息加载失败」与「重试」，其他卡片仍正常显示；
该分支和 4 并发上限由 `test/watch/watch_records_controller_test.dart`、
`test/watch/watch_records_page_test.dart` 自动化覆盖。真机验收重点看合并卡片和整页不被单条失败拖垮。
解读：K2-B 的用户验收点是三态、同一剧 N+1 详情合并为一张卡片、单删与清空的乐观回滚；
自动化测试已覆盖控制器行为，手机上的真实网络与回滚表现仍待用户取证。
#### 17.5 K2-C 收藏验收
1. 登录后在详情页或播放页点书签图标收藏一部剧。
预期：图标立即切换为已收藏状态；失败时图标回到原状态并显示「收藏操作失败，请重试。」。
2. 再收藏 1 至 2 部不同的剧，进入「我的 → 我的收藏」。
预期：页面展示服务端 `GET /app/favorites` 返回的全部收藏卡片，封面、标题与首页卡片一致；
列表不显示分页控件，也不发送自造的 `page/size`。点击卡片可进入详情。
3. 取消收藏：点某张收藏卡片右侧的粉色收藏图标。
预期：卡片立即消失；返回再进入我的收藏后仍然不存在。
4. 取消收藏失败回滚：保持列表已加载，停止 8081，再点另一张卡片的粉色图标。
预期：卡片先乐观消失，随后回到原位置，并出现「收藏操作失败，请重试。」。
重新启动 8081 后可再次取消。
5. 三态和失败重试：后端正常时进入页面观察加载态；取消全部收藏后观察「还没有收藏。」；
停止 8081 后冷启动 App 再进入我的收藏，观察「收藏列表加载失败。」和「重试」。
重启 8081 后点「重试」，预期列表恢复。
6. 服务端状态校准：在另一台设备或另一次登录中取消同一部收藏，再回到当前设备的我的收藏刷新。
预期：当前列表以服务端结果为准，不继续显示已被取消的收藏。
解读：K2-C 的用户验收点是服务端全量收藏列表、取消收藏后的乐观回滚和三态；
未登录引导另见 17.7，设备侧列表与回滚表现仍待用户取证。
#### 17.6 K2-D 下载授权验收
1. 登录后进入「我的 → 下载」。
预期：先出现加载态，随后显示策略卡：
「剩余 X / Y 个授权」、「授权有效期 N 天」以及后端返回的 `expirePolicyText` 原文；
下面显示「仅 Wi-Fi 下载」开关和「最高清晰度」下拉框。
2. 验证 §1.6 的 8 个接口。真机可观察结果如下：
| # | 接口 | 真机操作与预期可见结果 |
|---|---|---|
| 1 | `GET /app/downloads/policy` | 打开下载页后策略卡出现，配额、授权天数、`expirePolicyText` 来自后端 |
| 2 | `PUT /app/downloads/settings` | 切换仅 Wi-Fi 或清晰度后，页面立即显示新值；离开再进入仍保持 |
| 3 | `POST /app/downloads` | 详情页/播放页点下载图标，出现授权成功或后端拒绝提示 |
| 4 | `GET /app/downloads` | 打开下载页后出现当前设备授权列表；无授权时显示空态 |
| 5 | `GET /app/downloads/{episodeId}/url` | 本批只提供 API 方法，UI 不调用；真机无可观察入口，见自动化测试 |
| 6 | `POST /app/downloads/{episodeId}/progress` | 本批只提供方法，不做文件落盘/进度上报；真机无可观察入口，见自动化测试 |
| 7 | `DELETE /app/downloads/{episodeId}` | 点单条右侧关闭图标后该授权消失，重新进入仍不存在 |
| 8 | `DELETE /app/downloads` | 点「清空」并二次确认后授权列表变空，重新进入仍为空 |
3. 申请授权成功：进入任意可下载剧集的详情页或播放页，点下载图标（详情页右上角下载按钮，
或播放页右侧下载入口）。
预期：服务端接受时出现「下载授权已就绪。」；进入我的下载后能看到对应剧名、集号、
授权状态、任务状态、进度百分比、清晰度（后端有值时）和到期时间。
4. 授予失败透传后端 `message`：选择付费/未解锁剧集，或把当前设备配额用满后再次申请。
预期：SnackBar 原样显示后端返回的 `message`，不能替换成前端自造的“付费/未解锁/配额满”判断。
只有后端没有可用 message 时才回退到「申请下载失败。」。验收时记录手机屏幕上看到的完整原文；
当前环境没有执行这一步，因此具体拒绝文案仍属未验证。
5. 仅 Wi-Fi/清晰度成功：切换「仅 Wi-Fi 下载」，再选择 `AUTO`、`720P` 或 `1080P`。
预期：开关/下拉值立即变化，没有崩溃或重复选项；退出下载页再进入，值从
`GET /app/downloads/policy` 重新读取且保持。
6. 设置失败回滚：保持下载页已加载，停止 8081，再切换仅 Wi-Fi 或清晰度。
预期：值先乐观变化，随后恢复原值，并出现「下载设置更新失败。」。
7. 单删和清空。
- 点单条右侧关闭图标：预期该授权立即消失，重新进入后仍不存在。
- 停止 8081 后点另一条关闭图标：预期先消失再恢复，并提示「删除下载授权失败。」。
- 点「清空」：预期先弹出「清空下载授权？」及「这会吊销当前设备的全部下载授权。」；
点「暂不」不变，点「清空」后列表为空并显示「还没有下载授权。」。
- 停止 8081 后清空：预期列表先清空再恢复，并提示「清空下载授权失败。」。
8. 状态枚举后端驱动：查看授权卡上「授权：...」「任务：...」后的文本。
预期：显示后端原值，如 `ACTIVE/EXPIRED/REVOKED`、
`QUEUED/DOWNLOADING/PAUSED/COMPLETED/FAILED/CANCELED`，前端不做中文映射或本地推算。
现有数据只可能展示实际出现的状态；其余枚举由下载 API/控制器测试覆盖，
设备侧未逐一构造全部后端状态，回执不能写成“所有状态已真机验证”。
9. 三态和失败重试：后端正常时进入观察加载态；清空授权后观察空态；
停止 8081 后冷启动 App 再进入下载页，观察「下载设置加载失败。」和「重试」。
重启 8081 后点「重试」，预期策略卡和授权列表恢复。
本批不落盘、不断点续传、不提供离线播放；即使授权状态为 `ACTIVE`，也不能据此验收文件已下载。
解读：K2-D 的用户验收点是策略卡、8 个接口的可见结果、后端 `message` 透传、
仅 Wi-Fi/清晰度、单删/清空以及状态枚举原样展示。URL/进度两个接口没有本批 UI 入口，
只能由自动化测试证明方法契约；真机拒绝文案和全部状态仍未验证。
#### 17.7 未登录 AuthGate 与失败重试
1. 在「我的」页退出登录。
预期：账号回到未登录状态。
2. 依次进入「我的 → 观看历史」「我的 → 我的收藏」「我的 → 下载」。
预期：三个页面都显示登录引导：
「登录后可继续」、「观看记录、收藏、评论和下载需要登录。」和「去登录」按钮；
不显示网络错误、白屏或空列表冒充无数据。
3. 在未登录的详情页点收藏或在详情页/播放页点下载。
预期：出现底部登录提示；点「去登录」进入登录页，点「暂不」关闭提示且不发业务请求。
4. 完成登录后返回观看历史、我的收藏或下载页。
预期：页面自动从登录引导切换到加载态，再展示对应数据；不需要杀 App 才能刷新。
5. 失败重试统一检查：先让页面加载成功，再停止 8081 并冷启动 App 进入页面。
预期：记录页显示「续看进度加载失败。」、收藏页显示「收藏列表加载失败。」、
下载页显示「下载设置加载失败。」，均有「重试」按钮；重启 8081 后点「重试」能恢复，
不出现白屏或无提示的假成功。
解读：未登录时三个独立页面都应由页面级 AuthGate 接住；登录或后端恢复后应重新加载。
这些手机交互本轮未执行，不能用开发机请求代替。
#### 17.8 测试跳过口径差异与稳定复现命令
PM 复核事实与本轮复跑结果一致：
- 8081 未启动：`flutter test` 呈 `+216 ~5`，5 个 live 用例全部由
`markTestSkipped('客户端接口服务未启动，已跳过联调测试')` 跳过。
- 8081 已启动：PM 复核呈 `+220 ~1`，4 个 live 用例通过；
当前演示数据下 `live_watch_flow_test.dart` 仍由播放断言前的
`markTestSkipped('这部演示剧没有可播剧集，已跳过播放相关断言')` 保留 1 个跳过。
如果换了一套有可播剧集的种子数据，这个用例可能通过并呈 `+221 ~0`；以实际输出为准。
5 个 live 用例及跳过机制：
| 文件 | 用例 | 跳过机制 |
|---|---|---|
| `test/integration/live_auth_test.dart` | `should_surface_business_error_when_sign_in_uses_unknown_email` | 捕获连接失败后 `markTestSkipped('客户端接口服务未启动，已跳过联调测试')` |
| `test/integration/live_catalog_test.dart` | `should_parse_banner_and_sections_when_home_feed_is_fetched` | `serverUp()` 失败后 `markTestSkipped('客户端接口服务未启动，已跳过联调测试')` |
| `test/integration/live_catalog_test.dart` | `should_order_episodes_by_number_and_attach_url_when_detail_is_fetched` | 同上 |
| `test/integration/live_catalog_test.dart` | `should_return_play_url_when_episode_is_playable` | 同上 |
| `test/integration/live_watch_flow_test.dart` | `should_complete_the_watch_flow_when_backend_is_running` | 注册失败后跳过“服务未启动”；注册成功但无可播剧集时跳过“没有可播剧集” |
稳定复现 `+216 ~5`：
```
$ lsof -nP -iTCP:8081 -sTCP:LISTEN
（确认无输出）
$ cd /Users/jianghaifeng/Desktop/ReelShort/ReelShort
$ flutter test
00:10 +216 ~5: All tests passed!
```
稳定复现 `+220 ~1`：
```
# 终端 A：启动 8081 后保持运行
$ cd /Users/jianghaifeng/Desktop/ReelShort/FruitServer
$ mvn -pl fruitshorts-app-api -am package -DskipTests
$ java -jar fruitshorts-app-api/target/fruitshorts-app-api-1.0.0-SNAPSHOT.jar
# 终端 B：确认 8081 已监听后跑测试
$ curl -fsS http://127.0.0.1:8081/healthz
$ cd /Users/jianghaifeng/Desktop/ReelShort/ReelShort
$ flutter test
00:xx +220 ~1: All tests passed!
```
这 3 个 live 测试文件把地址硬编码为 `http://127.0.0.1:8081`，不读取
`--dart-define=API_BASE_URL`。因此复现测试口径必须在同一台 Mac 上启动 8081，
手机同一局域网只用于真机 App 验收，不能替代这里的环回联调。
本轮没有改这 3 个测试文件或产品代码。
解读：`~5` 与 `~1` 的差异来自 8081 是否启动，不是测试代码漂移；
`~1` 还是当前演示数据下播放断言前的跳过，不能把 `~5` 误报成 5 个失败。
#### 17.9 提交作者口径差异登记
叙述：已发生的历史提交不改写，不回滚，不 force push。下面用原始 Git 输出登记事实。
```
$ git show -s --format='%H%n author: %an <%ae>%n committer: %cn <%ce>%n subject: %s' cc4d7c5
cc4d7c5a9dc6a4f6f0565a32503cce5973af703c
author: Zhou Weidong <502333560@qq.com>
committer: Zhou Weidong <502333560@qq.com>
subject: feat(flutter): 接入分类记录收藏与下载授权
$ git show -s --format='%H%n author: %an <%ae>%n committer: %cn <%ce>%n subject: %s' 45f5f25
45f5f25640a274edb51bd90b3b5e52c43ba9d9cd
author: Zhou Weidong <502333560@qq.com>
committer: Zhou Weidong <502333560@qq.com>
subject: merge: 合并 K2 客户端分类记录收藏与下载授权
```
差异口径与最终裁定：
- specs 规范要求提交作者统一为 `Zhou Weidong <502333560@qq.com>`，上述两个历史提交按此口径产生。
- 用户曾口头要求使用 `jianghaifeng <haifeng_hello@163.com>`；该口径已作废，不再作为后续提交依据。
- 两个历史提交均已 push 到 `develop`；保留原始历史，不通过回滚或 force push 改写，不动 `main`。
- 已裁定：后续提交统一使用 `Zhou Weidong <502333560@qq.com>`，author 与 committer 均按此口径。
- 本回执提交 `cfce77a` 曾误用 `jianghaifeng <haifeng_hello@163.com>` / `trae-solo-agent <solo-agent@trae.ai>`，现已通过 amend 修正为 `Zhou Weidong <502333560@qq.com>`；amend 后最终提交号以本轮 `git log -2` 原始输出为准。
解读：提交作者差异是已发生事实，已推送的历史提交不通过回滚或 force push 改写；
jianghaifeng 口径作废，后续统一使用 Zhou Weidong，本回执提交已通过 amend 校正。
#### 17.10 仍未验证的边界
- 设备侧业务取证由用户执行，Codex 未执行；本轮没有手机屏幕截图、设备日志或手机到 8081 的连接证据。
- 具体后端拒绝 `message` 原文尚未在真机触发并记录。
- 8 个下载接口中，`GET /app/downloads/{episodeId}/url` 与
`POST /app/downloads/{episodeId}/progress` 本批没有 UI 调用入口，只有自动化 API 契约测试。
- `ACTIVE/EXPIRED/REVOKED` 与 `QUEUED/DOWNLOADING/PAUSED/COMPLETED/FAILED/CANCELED`
只验证“前端展示后端原值”的机制；没有逐一构造全部状态做真机验收。
- 文件分片落盘、断点续传、离线播放、`licenseKey` 本地校验不在 K2 范围，仍未实现，也不能验收。
- 收藏接口没有分页参数，本批按全量列表验收，不验收服务端分页。
- 搜索契约没有接口，本批不验收搜索。
---
## 2026-10-17 K3-A 评论实施（【Codex】）
叙述：按 K3 任务书先补计划文档基线，再按评论 API/controller/UI 顺序做 TDD。
首轮测试在实现前运行，用于确认红灯；实现后运行同一组定向测试转绿。
### 18.1 计划文档
命令：使用补丁工具增量更新 `docs/plans/2026-10-17-K3.md`。
原始结果：
```
Success. Updated the following files:
M /Users/jianghaifeng/Desktop/ReelShort/FruitServer/docs/plans/2026-10-17-K3.md
```
解读：保留既有 K3 计划，仅补记 ReelShort `45f5f25`、FruitServer `a0156ee`
和计划文件未跟踪的实测基线，没有覆盖已有内容。
### 18.2 K3-A 首次红灯
命令：
```
$ cd /Users/jianghaifeng/Desktop/ReelShort/ReelShort
$ flutter test test/comment/comment_api_test.dart test/comment/comment_controller_test.dart
```
原始输出（节选）：
```
Error when reading 'lib/core/data/remote/comment_api.dart': No such file or directory
Error when reading 'lib/core/data/models/comment.dart': No such file or directory
Error when reading 'lib/core/data/services/comment_controller.dart': No such file or directory
00:00 +0 -2: Some tests failed.
```
解读：生产 API、模型和 controller 尚不存在，红灯原因符合预期。
### 18.3 K3-A 数据层绿灯
命令：实现评论模型、API、仓库和 controller 后，重跑同一组定向测试。
原始输出：
```
00:00 +9: All tests passed!
```
解读：评论游标分页、String ID、发布回复、替换内容、敏感词 BLOCK message、
删除成功与失败回滚均通过。
### 18.4 K3-A UI 红灯与绿灯
首次运行：
```
$ flutter test test/comment/drama_comments_sheet_test.dart
ProviderNotFoundException: Could not find the correct Provider<EngagementController>
00:00 +0 -5: Some tests failed.
```
解读：旧弹窗仍直接依赖本地 `EngagementController`，符合 UI 红灯预期。
替换为服务端 controller、三态和回复输入后：
```
00:01 +5: All tests passed!
```
随后运行整个评论测试目录：
```
$ flutter test test/comment
00:01 +14: All tests passed!
```
解读：API、controller 和弹窗测试共 14 项全部通过。
### 18.5 K3-A 静态分析
首次分析：
```
info - lib/core/data/remote/comment_api.dart:23:9 - use_null_aware_elements
info - lib/core/data/remote/comment_api.dart:24:9 - use_null_aware_elements
2 issues found.
```
按 lint 改为 null-aware map value 后：
```
$ dart analyze lib test
Analyzing lib, test...
No issues found!
```
解读：K3-A 达到零告警口径。真机交互未执行，设备侧取证仍由用户完成。
### 18.6 K3-B 点赞红灯
命令：
```
$ cd /Users/jianghaifeng/Desktop/ReelShort/ReelShort
$ flutter test test/interaction test/comment/drama_comments_sheet_test.dart
```
原始输出（节选）：
```
Error when reading 'lib/core/data/services/interaction_controller.dart': No such file or directory
Method not found: 'InteractionController'.
00:01 +8 -1: Some tests failed.
```
解读：互动 API 已先通过，缺失的剧集点赞 controller 构成 K3-B 红灯。
### 18.7 K3-B 绿灯
实现 `InteractionController`、替换播放页右栏、去掉本地互动演示层后：
```
$ flutter test test/interaction test/comment/drama_comments_sheet_test.dart
00:01 +11: All tests passed!
```
补齐评论点赞成功/回滚和整机 AuthGate 断言后：
```
$ flutter test test/comment/comment_controller_test.dart test/widget_test.dart
00:04 +23: All tests passed!
```
静态分析：
```
$ dart analyze lib test
Analyzing lib, test...
No issues found!
```
解读：剧集与评论点赞均使用服务端结果校准；失败会回滚；未登录点剧集赞会打开
AuthGate 且仓库调用次数为 0。剧集点赞数字未展示，符合契约缺口降级方案。
### 18.8 K3-C 举报红灯
命令：
```
$ cd /Users/jianghaifeng/Desktop/ReelShort/ReelShort
$ flutter test test/interaction/report_dialog_test.dart test/comment/drama_comments_sheet_test.dart test/widget_test.dart
```
原始输出（节选）：
```
Error when reading 'lib/pages/interaction/widgets/report_dialog.dart': No such file or directory
Found 0 widgets with key [<'comment-menu-10'>]
Found 0 widgets with key [<'detail-more'>]
00:05 +21 -5: Some tests failed.
```
解读：举报弹窗、评论更多菜单和详情页更多菜单均尚未实现，红灯符合 K3-C 范围。
### 18.9 K3-C 绿灯
实现固定五项 `SPAM/ABUSE/PORN/AD/OTHER` 单选、可选描述、评论与短剧举报入口后：
```
$ flutter test test/interaction/report_dialog_test.dart test/comment/drama_comments_sheet_test.dart test/widget_test.dart
00:05 +26: All tests passed!
```
解读：举报原因与描述提交、评论举报成功、重复举报 message 透传、未登录 AuthGate
和详情页举报短剧均通过。
### 18.10 K3-C 静态分析
首次分析：
```
info - lib/pages/drama_detail/drama_detail_view.dart:319:42 - use_build_context_synchronously
info - lib/pages/drama_detail/drama_detail_view.dart:321:26 - use_build_context_synchronously
info - lib/pages/drama_detail/drama_detail_view.dart:327:26 - use_build_context_synchronously
3 issues found.
```
改为 State 自身 `context` + `mounted` 守卫后：
```
$ dart analyze lib test
Analyzing lib, test...
No issues found!
```
解读：举报实现达到零告警口径。
### 18.11 K3-D 分享回归
命令：
```
$ cd /Users/jianghaifeng/Desktop/ReelShort/ReelShort
$ flutter test test/core/platform_share_service_test.dart test/formatting/localized_content_test.dart test/widget_test.dart
```
原始输出：
```
00:05 +25: All tests passed!
```
解读：系统分享文本保持“标题 → 简介 → footer”顺序；en/zh/id 三语均生成
非空标题、简介和 `FruitShorts` footer；播放页分享入口回归通过。
### 18.12 代码规模红线修正
提交前检查命令：
```
$ wc -l lib/pages/player/widgets/drama_comments_sheet.dart
535 lib/pages/player/widgets/drama_comments_sheet.dart
```
解读：主弹窗超过单文件 500 行红线。将评论条目与交互回调拆到
`comment_tile.dart` 后：
```
$ wc -l lib/pages/player/widgets/drama_comments_sheet.dart lib/pages/player/widgets/comment_tile.dart
396 lib/pages/player/widgets/drama_comments_sheet.dart
149 lib/pages/player/widgets/comment_tile.dart
```
拆分后复跑互动定向测试：
```
00:06 +51: All tests passed!
```
解读：行为未回归，两个文件均低于 500 行。
### 18.13 最终门禁
```
$ dart analyze lib test
Analyzing lib, test...
No issues found!
$ flutter test
00:11 +241 ~1: All tests passed!
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 6.8s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
解读：唯一跳过项是既有 live watch 用例，因客户端接口服务未启动而按测试机制跳过。
真机/设备侧集成、截图、设备日志仍未执行。
### 18.14 Git 合并与推送
ReelShort 功能提交：
```
d361034226ec2bc431548d45068dc60046e5e473
author: Zhou Weidong <502333560@qq.com>
committer: Zhou Weidong <502333560@qq.com>
subject: feat(flutter): 接入互动评论点赞举报
```
`--no-ff` 合并提交：
```
9db6935308e65342be46c81419c2992ed2df1df0
author: Zhou Weidong <502333560@qq.com>
committer: Zhou Weidong <502333560@qq.com>
subject: merge: 合并 K3 客户端互动能力
```
推送：
```
To http://git.reelshort2.com/jianghaifeng/ReelShort.git
45f5f25..9db6935 develop -> develop
```
解读：K3 已合并到 ReelShort `develop` 并推送，未操作 `main`。
### 18.15 本人评论举报错误透传补充修复
逐条复核任务书时发现：本人评论的更多菜单原先只提供删除，无法触发
“不能举报自己发布的内容”这一后端 message。先补红灯用例，再让菜单始终提供
“举报评论”，本人评论额外提供“删除评论”。
红灯：
```
$ flutter test test/comment/drama_comments_sheet_test.dart --plain-name should_show_backend_message_when_reporting_own_comment
Found 0 widgets with text "Report comment"
00:00 +0 -1: Some tests failed.
```
修复后：
```
00:00 +1: All tests passed!
```
最终重跑：
```
$ dart analyze lib test
Analyzing lib, test...
No issues found!
$ flutter test
00:12 +242 ~1: All tests passed!
$ flutter build apk --debug
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
修复提交：
```
1488ee8f85671de96c70347c1b17fb9c4556bd88
fix(flutter): 透传举报本人评论错误
```
`--no-ff` 合并提交：
```
e1147cfcbabcdf457e427bbd118c32d37f8d9b15
merge: 合并 K3 举报错误透传修复
```
推送：
```
9db6935..e1147cf develop -> develop
```
解读：报告本人内容现在会把后端错误原样展示；author/committer 均保持统一。
---
## 2026-10-17 K5 克莱因蓝主题与印尼语适配（【Codex】）
### 19.1 诊断分支收口
叙述：上一项 iOS 首页诊断插桩已提交在独立分支，不并入 K5，也不阻塞干净基线。
```
$ git status --short --branch
## feature/flutter-ios-home-diagnostics
$ git log -1 --oneline
7efbed9 chore(flutter): 增加首页加载失败诊断日志
```
解读：诊断提交保留为未合并 feature 分支；K5 从 `develop e1147cf` 新建，
后续所有 K5 改动均在该基线上。
### 19.2 K5 计划
叙述：先写 `docs/plans/2026-10-17-K5.md`，记录方案 A 色值、影响文件、TDD、
风险和待确认，再开始代码。
```
Success. Updated the following files:
A docs/plans/2026-10-17-K5.md
```
### 19.3 K5 首次红灯
命令：
```
$ flutter test test/theme test/config/locale_controller_test.dart test/mine/mine_logic_test.dart test/widget_test.dart
```
原始输出（节选）：
```
Error when reading 'lib/core/theme/app_theme.dart': No such file or directory
Member not found: 'bluePressed'
Member not found: 'onPrimary'
Method not found: 'resolveAppLocale'
Found 0 widgets with text "Bahasa Indonesia"
Expected: empty
Actual: [
'lib/core/theme/app_colors.dart:5: static const blue = Color(0xFF2F7BFF);',
...
]
00:07 +22 -5: Some tests failed.
```
解读：主题 token/ThemeData、locale 解析、语言选项和旧蓝扫描全部按预期红灯。
### 19.4 K5 实现与定向绿灯
实现内容：
- `AppColors` 新增 `bluePressed/onPrimary`，更新 `blue/blueSoft`。
- 新增 `AppTheme.light/dark` 显式 ColorScheme 和控件主题。
- 页面旧蓝清理，深色高亮改 `blueSoft`，大面积选中态改 `bluePressed`。
- `resolveAppLocale` 支持 en/zh/id，未知系统语言回退 id。
- 两个语言入口增加 Bahasa Indonesia；快捷抽屉改 Wrap。
- 日期/时间改用 `MaterialLocalizations`。
定向测试：
```
$ flutter test test/theme test/config test/formatting test/mine/mine_logic_test.dart test/widget_test.dart test/auth test/library test/watch test/download test/drama_detail
00:08 +97: All tests passed!
```
旧蓝扫描补跑：
```
$ rg -n '0xFF2F7BFF|0xFF8FB4FF|Colors\.blue|_orange|seedColor' lib -g '*.dart'
```
结果：无匹配（仅保留 `AppColors.blue/blueSoft/bluePressed` 等 token 引用）。
### 19.5 K5 最终门禁
```
$ dart analyze lib test
Analyzing lib, test...
No issues found!
$ flutter test
00:12 +251 ~1: All tests passed!
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 26.6s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
解读：全量测试除既有 live watch 跳过外全部通过，APK 构建成功。
### 19.6 Git
```
10d448c8ba93aa2762e14babdb528805897b3992
author: Zhou Weidong <502333560@qq.com>
committer: Zhou Weidong <502333560@qq.com>
subject: feat(flutter): 应用克莱因蓝主题与印尼语适配
e52d81881c19202c7adc8d13a6f78f78e4f6182f
author: Zhou Weidong <502333560@qq.com>
committer: Zhou Weidong <502333560@qq.com>
subject: merge: 合并 K5 克莱因蓝主题与印尼语适配
To http://git.reelshort2.com/jianghaifeng/ReelShort.git
e1147cf..e52d818 develop -> develop
```
解读：K5 已以 `--no-ff` 合并到 ReelShort develop 并推送，未操作 main。
---
## 2026-10-17 K6 登录页、底部导航与震动反馈（【Codex】）
### 20.1 K6 计划与 UI 红灯
叙述：先写 `docs/plans/2026-10-17-K6.md`，再基于 K5 `develop e52d818`
创建 `feature/flutter-k6-auth-nav-ui`。首轮登录/底栏测试在实现前运行：
```
$ flutter test test/auth/auth_page_test.dart test/widget_test.dart
Found 0 widgets with text "FruitShorts"
Found 0 widgets with key [<'auth-email'>]
Expected: Color(... #101114)
00:07 +22 -5: Some tests failed.
```
解读：品牌区、表单 Key/显隐/焦点、底栏主题样式尚未实现，红灯符合任务范围。
### 20.2 K6 UI 绿灯
实现登录品牌区、autofill、密码显隐、next/done、busy 禁用、主题错误色、
Small screen 滚动和底部导航主题胶囊后：
```
$ flutter test test/auth test/home/home_nav_ui_test.dart test/widget_test.dart test/config/l10n_id_test.dart test/theme
00:06 +42: All tests passed!
```
提交：`e609e3a feat(flutter): 优化登录页与底部导航`。
### 20.3 Haptics 补充需求红灯
FruitServer `93af19e` 新增 K6-C 点击震动反馈。补 fake Haptics 和触发测试后：
```
Error when reading 'lib/core/platform/haptics.dart': No such file or directory
No named parameter with the name 'haptics'
00:02 +1 -4: Some tests failed.
```
解读：Haptics 抽象、Provider 注入与页面触发尚未实现。
### 20.4 Haptics 实现与定向绿灯
新增 `Haptics` + `FlutterHaptics`，通过 Provider 注入；tab selection、
关键操作 light、危险确认 medium；默认实现吞掉平台异常，页面调用全部
`unawaited`。新增 fake/静态扫描/异常静默测试。
```
$ flutter test test/core/haptics_test.dart test/core/haptics_scan_test.dart test/auth test/home/home_nav_ui_test.dart test/comment test/watch test/download test/library test/drama_detail test/player
00:05 +98: All tests passed!
```
提交：`8a481d5 feat(flutter): 增加关键操作震动反馈`。
### 20.5 K6 最终门禁
```
$ dart analyze lib test
Analyzing lib, test...
No issues found!
$ flutter test
00:14 +263 ~1: All tests passed!
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 6.6s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
解读：震动反馈、登录页、底栏和存量测试全部通过；`~1` 为既有 live watch 跳过。
### 20.6 Git
```
e609e3a feat(flutter): 优化登录页与底部导航
8a481d5 feat(flutter): 增加关键操作震动反馈
0cedaab merge: 合并 K6 登录导航与震动反馈
To http://git.reelshort2.com/jianghaifeng/ReelShort.git
e52d818..0cedaab develop -> develop
```
解读：K6 已合并并推送，author/committer 均为 Zhou Weidong，未操作 main。
### 20.7 iOS Xcode SPM 构建修复（K6 收尾）
叙述：只修改 `Runner.xcscheme` PreActions。新增 Python 无关的 shell
兜底链解析 Flutter，先 `flutter pub get`；原 prepare action 保留，并改为
同一路径解析后执行 `xcode_backend.sh prepare`。
XML 校验：
```
$ xmllint --noout ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme
（无输出，退出码 0）
```
清理 ephemeral 后直接 xcodebuild：
```
$ rm -rf ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage
$ xcodebuild -project ios/Runner.xcodeproj -scheme Runner -configuration Debug -sdk iphoneos build
Resolve Package Graph
the package at '.../FlutterGeneratedPluginSwiftPackage' cannot be accessed
xcodebuild: error: Could not resolve package dependencies
```
解读：Xcode 在运行 scheme PreActions 之前先解析 Package Graph，因此
“包目录完全不存在”的首次冷启动无法仅靠 scheme PreAction 自动生成。
这是 Xcode 执行顺序限制，不是 XML 语法错误。
使用 `flutter pub get` 恢复包后：
```
$ flutter pub get
Got dependencies!
$ xcodebuild -list -project ios/Runner.xcodeproj
Resolved source packages:
FlutterGeneratedPluginSwiftPackage: .../ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage
...
```
完整重建精简日志：
```
$ xcodebuild -project ios/Runner.xcodeproj -scheme Runner -configuration Debug -sdk iphoneos build
Resolve Package Graph
Resolved source packages:
Run pre-actions
export SCHEME_ACTION_NAME="Bootstrap Flutter SPM Package"
Resolving dependencies...
Got dependencies!
** BUILD SUCCEEDED **
```
解读：SPM 包存在时，PreAction 能成功刷新依赖，prepare 和完整 iPhoneOS
Debug 构建通过并完成签名。冷启动自动生成未通过验证，用户仍需在
新克隆/`flutter clean`/手动删除 ephemeral 后先运行 `flutter pub get`。
Git：
```
cc037a2956848128c4899df1f5092fea44d3620b
fix(ios): 刷新 Flutter SPM 包后再准备框架
0cedaab..ac706a4 develop -> develop
```
解读：scheme 修复已合并推送；author/committer 均为 Zhou Weidong。
### 20.8 K6 导航白线与观看历史缺陷修复
### 导航白线
首次红灯：
```
Expected: a value less than <0.2>
Actual: <1.0>
```
解读：当前深色 ColorScheme 默认 `outlineVariant` 实为白色，确认了白线根因。
修复：新增 light/dark outline token，两个 ColorScheme 显式设置
`outline/outlineVariant`；导航边框继续使用主题 token。
### 观看历史真实诊断
后端日志：
```
2026-10-17T16:35:22.816+08:00 POST /app/auth/register 耗时 242ms
2026-10-17T16:35:37.123+08:00 POST /app/watch/progress 耗时 51ms
```
数据库只读查询：
```
uid | drama_id | episode_id | position_ms | duration_ms
UKZBA9IBE | 1 | 1 | 1522 | 91326
UKZBA9IBE | 5 | 7 | 0 | 227880
```
真实 recent 响应：
```
{"code":0,"message":"ok","data":[
{"dramaId":"5","episodeId":"7",...},
{"dramaId":"1","episodeId":"1",...}
]}
```
临时直连 controller 诊断：
```
watch-records-diagnostic error=null records=2
record drama=5 episode=7 detail=闪婚后，傅先生每天都在撒糖 loading=false failed=false
record drama=1 episode=1 detail=替嫁新娘：总裁的掌心宠 loading=false failed=false
```
解读：真实用户同类数据在 API、JSON 解析、controller 和详情补取链路均正常，
未复现设备侧 401/100000、解析异常或详情失败。后端日志中的 429 仍属于
其他联调设备，用户 watch 请求没有该错误。
确认的客户端缺陷是 controller 吞掉真实异常：
```
Expected: '账号不存在，请先注册'
Actual: 'progressError'
```
修复：debug 打印异常类型、原文与堆栈；ApiException message 透传页面错误态。
### 定向与全量门禁
```
$ flutter test test/theme test/home/home_nav_ui_test.dart test/watch/watch_records_controller_test.dart test/watch/watch_records_page_test.dart
00:01 +21: All tests passed!
$ dart analyze lib test
Analyzing lib, test...
No issues found!
$ flutter test
00:13 +266 ~1: All tests passed!
$ flutter build apk --debug
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
### Git
```
732483465ced2b28438585a4b2f1573e9a0529cb
fix(flutter): 修复导航白线与观看记录错误透传
ac706a4..b7b1c50 develop -> develop
```
解读：修复已合并推送；用户设备特定 error 仍需设备日志确认。
---
## 2026-10-17 K7 首页轮播与站内通知（【Codex】）
### 21.1 K7 计划与首次红灯
叙述：先写 `docs/plans/2026-10-17-K7.md`，从干净 `develop b7b1c50`
创建 `feature/flutter-k7-carousel-notices`。
首次轮播/通知测试：
```
No named parameter with the name 'active'
Error when reading 'lib/core/data/models/notice.dart': No such file or directory
Error when reading 'lib/core/data/remote/notice_api.dart': No such file or directory
00:00 +0 -3: Some tests failed.
```
解读：轮播增强、通知数据层和页面尚不存在，红灯符合预期。
### 21.2 轮播绿灯
实现 Timer、交互暂停、active/TickerMode、圆点、失败占位与语义后：
```
$ flutter test test/discover/cover_carousel_test.dart
00:00 +7: All tests passed!
```
### 21.3 通知实现与定向绿灯
实现 Notice model/API/repository/controller/Page、我的页入口和三语文案后，
真实匿名接口返回：
```
$ curl -sS 'http://127.0.0.1:8081/app/notices?pageIndex=1&pageSize=20'
{"code":0,"message":"ok","data":{"total":0,"list":[]}}
```
通知与轮播定向测试：
```
$ flutter test test/discover/cover_carousel_test.dart test/notice
All tests passed!
```
期间修正 320px 下类型/时间同一行 3.5px 溢出，改为双 Flexible。
### 21.4 K7 最终门禁
```
$ dart analyze lib test
Analyzing lib, test...
No issues found!
$ flutter test
00:14 +284 ~1: All tests passed!
$ flutter build apk --debug
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
### 21.5 Git
```
b870956665f5268070c691533cc2a334f2aa7f59
feat(flutter): 增加轮播自动播放与站内通知
b7b1c50..3e8703b develop -> develop
```
解读：K7 已合并推送；author/committer 均为 Zhou Weidong。
---
## 2026-10-17 K7 真机缺陷修复：观看历史 Provider 与首页轮播数据源
### 22.1 范围与分支
叙述：用户真机验收后报告观看历史仍报错、首页轮播仍不显示。本轮只修客户端
Provider 注册与首页轮播数据源，不改后端、Web、specs 或既有发现页分区逻辑。
ReelShort 从 `develop 3e8703b` 拉
`fix/flutter-home-watch-provider-banners`；FruitServer 从 `develop 9c6aaed`
拉 `docs/flutter-home-watch-device-fix`，本仓库只改 `docs/plans/PROGRESS.md`。
### 22.2 先红：复现设备报告
真实 `LumaDramaApp` Provider 树打开「我的 -> 观看历史」：
```text
ProviderNotFoundException:
Could not find the correct Provider<CatalogRepository>
above this _WatchRecordsBody Widget
```
首页 feed 返回 2 条 banner、discover feed 返回 0 条 banner：
```text
Expected: exactly one matching candidate
Actual: Found 0 widgets with type "CoverCarousel"
```
解读：两处红灯分别复现了用户报告的 Provider 缺失和轮播为空。
### 22.3 修复
- `lib/app.dart` 在现有 Repository Provider 附近注册
`Provider<CatalogRepository>.value(value: _catalogRepository)`，与
`CatalogController` 共用同一实例。
- `lib/pages/discover/discover_view.dart` 改为监听
`CatalogController.feed.banners`，修复后首页 tab 使用 `/app/home/feed`
的 banners；发现页分区仍使用 `CategoryController`，没有新增接口。
- 新增 `test/watch/watch_history_provider_test.dart`：在真实 Provider 树打开
观看历史，断言不抛错并展示空态。
- 新增 `test/discover/home_banner_source_test.dart`：home banners 为 2、
discover banners 为空时，断言渲染两个圆点、首图显示且 4.5 秒后自动切到次图。
### 22.4 门禁原始输出
```text
$ dart analyze lib test
Analyzing lib, test...
No issues found!
```
```text
$ flutter test test/watch/watch_history_provider_test.dart test/discover/home_banner_source_test.dart
00:01 +2: All tests passed!
```
```text
$ flutter test test/discover/cover_carousel_test.dart test/watch/watch_records_page_test.dart
00:00 +12: All tests passed!
```
```text
$ flutter test
00:16 +286 ~1: All tests passed!
```
解读：完整套件 286 项通过，1 项联调测试因客户端接口服务未启动按设计跳过；
输出中的 `[WatchRecordsController] ...` 异常堆栈来自故意注入失败的既有测试。
### 22.5 Git
```text
5058853 fix(flutter): 注册目录仓库并修正首页轮播数据源
6cc5bfc merge: 合并首页轮播与观看历史真机修复
3e8703b..6cc5bfc develop -> develop
```
修复提交与合并提交的 author/committer 均为
`Zhou Weidong <502333560@qq.com>`。
### 22.6 用户真机验证步骤与预期
以下设备侧取证由用户执行，开发机测试不能替代真机证据。
1. 使用最新 `develop` 重新构建并安装，登录用户设备
`d-mvc33zh5-pemv3e`。
预期：`flutter run` 终端不再出现 `ProviderNotFoundException`。
2. 打开「我的 -> 观看历史」。
预期：页面正常打开；有历史时显示剧目与进度，无历史时显示空态，不再进入
Provider 错误页。
3. 回到发现页并等待首页 feed 加载完成。
预期：顶部轮播显示后端 `/app/home/feed` 返回的 2 张 banner，底部有两个圆点。
4. 等待 4.5 秒。
预期：轮播自动切到第 2 张；手动拖动后仍可从当前页继续自动轮播。
设备侧截图、日志与最终验收结论由用户执行。
---
## 37. K21 登录页 UI 优化
### 37.1 基线与布局
```text
ReelShort: e44fbdf style(ui): 合并 K20 客户端视觉统一
FruitServer: af28161 docs(plans): 下发 K21 登录页 UI 优化任务
```
计划先提交为 `0e3ddfc docs(plans): 增加 K21 登录页实施计划`。
布局由顶部对齐 + ListView 改为：
- `LayoutBuilder + SingleChildScrollView + ConstrainedBox + Center`；
- 正常高度品牌与卡片垂直居中；
- 高度小于 720 时使用紧凑横向品牌，保证 600 高测试视口与提交按钮可达；
- 返回按钮改为 `Positioned + SafeArea` 浮层，不占内容流；
- 小屏键盘仍保留 `28 + viewInsets.bottom` 底部 padding，可滚动到 `auth-submit`。
### 37.2 品牌与文案
- `auth-brand-mark` 改用 `assets/icon/splash_mark.png`，尺寸仍为 48×48。
- 品牌名 26/w800，tagline 14/blueSoft；正常视口居中竖排。
- 登录使用现有 `authSubtitle`；注册新增 `authSignUpSubtitle`：
```text
en: Create an account to keep your list, history, and progress.
zh: 创建账号，保存你的片单、观看记录和进度。
id: Buat akun untuk menyimpan daftar, riwayat, dan progresmu.
```
- 注册态密码框下显示 `authPasswordHint`，Key `auth-password-rule`；登录态隐藏。
### 37.3 字段错误与交互
`AuthLogic` 新增 `fieldError`，`validate()` 记录具体字段错误，输入变化或切换模式时清除。
邮箱/密码字段增加 semantic error 红框：
```text
errorBorder / focusedErrorBorder
color = colorScheme.error
width = 1.5
```
同时：
- `_submit()` busy 首行短路；
- 异步 catch 的 `setState` 前判断 mounted；
- 密码框 IME done 提交同样经过 busy 短路；
- 提交按钮增加 alpha 0.22 的辣椒红轻阴影，背景色与按下色不变。
### 37.4 保留项
```text
auth-brand-mark 48x48
auth-card radius 20 / border outlineVariantDark / width 1
input height 52 / radius 14 / fill bar / focus blue 1.5
submit height 52 / radius 26 / blue / bluePressed
auth-enter-animation 220ms / tween 0 -> 1
mode keys, title copy, hidden compatibility copy
error capsule radius 12 / alpha 0.1 / semantic color
320x568 + keyboard 260 scroll reachability
```
主 glow 颜色 alpha 保持 ≤0.18；新增 warm glow Key
`auth-background-warm-glow`，alpha 上限 0.06。
### 37.5 TDD 与门禁
新增 `test/auth/auth_k21_test.dart`，先红灯后转绿：
```text
$ flutter test test/auth/auth_k21_test.dart
00:00 +2: All tests passed!
```
全部 Auth 测试：
```text
$ flutter test test/auth/auth_visual_test.dart \
test/auth/auth_page_test.dart test/auth/auth_k21_test.dart
00:01 +17: All tests passed!
```
全量门禁：
```text
$ dart analyze lib test
No issues found!
$ flutter test
00:24 +343: All tests passed!
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 7.5s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
### 37.6 Git
```text
8a96f34 feat(auth): 优化登录页布局与字段反馈
b1c69e2 feat(auth): 合并 K21 登录页优化
e44fbdf..b1c69e2 develop -> develop
```
author/committer 均为 `Zhou Weidong <502333560@qq.com>`。
### 37.7 用户真机验收
设备侧取证由用户执行：
1. 普通手机竖屏打开登录页：品牌 hero 与卡片垂直居中，返回键为顶部浮层。
2. 切换注册：副标题变为注册文案，密码框下出现规则提示。
3. 提交空邮箱：邮箱出现 1.5px 红色边框，错误胶囊仍保留。
4. 输入非法邮箱后修改：字段红框清除。
5. 输入弱密码：密码框变红，规则提示仍在。
6. 连续点提交或按键盘 Done：只发出一次请求，busy 时按钮与模式切换禁用。
7. 320×568 小屏弹出键盘：滚动后提交按钮可点击。
8. 检查主辣椒红 glow、暖色副 glow 均淡且不影响文字对比度。
9. 检查品牌图为 `splash_mark.png`，显示 48×48，无拉伸。
---
## 36. K20 客户端视觉统一
### 36.1 基线与计划
```text
ReelShort: 42ce1d1 fix(account): 合并网络异常文案修复
FruitServer: 810d9fc docs(plans): 下发 K20 客户端视觉统一任务
```
计划先提交为 `3435784 docs(plans): 增加 K20 视觉统一实施计划`。
客户端从干净 develop 创建 `feature/flutter-k20-visual`。
### 36.2 统一 Token
新增 `lib/core/theme/app_dimens.dart`：
```text
页面边距 16
卡片圆角/内边距 16/16
内嵌块圆角/内边距 12/12
胶囊圆角 20
caption/body/list/section/page = 12/14/15/16/20
详情标题 24
导航标签 11
主按钮/整页主操作 = 48/52
点击区 44
导航高度/图标 = 64/22
进度条高度/圆角 = 4/4
账号卡高度/图标/标签 = 64/18/11
观看占位高度 114
```
`AppColors.favorite = #D74A7D`；主色继续使用辣椒红 `#C4322A`。
### 36.3 十四项实现
1. 新增 `AppBottomNav` / `AppBottomNavItem`，替换 home、discover、mine、
player fallback 四处导航；保留 `tab-home` 等既有 Key。
2. 账号入口卡改为 64 高、18 图标、11 标签和 44 以上点击区。
3. 清理全部 9.5/10 业务字号，任务书列出的 11 字号提升至 12。
4. 页面边距、卡片圆角、内边距和列表间距按 token 收敛。
5. 任务书列出的硬编码颜色替换为 `AppColors`；收藏红心使用 `favorite`。
6. 详情、记录、下载进度条统一 4 高、4 圆角、blueSoft/white24。
7. Filled/OutlinedButton 最小高度 48；empty 重试色改 blueSoft。
8. 页面标题 20/w800，详情标题 24，区块与列表标题按 token。
9. `themeMode = ThemeMode.dark`；根节点统一状态栏和系统导航栏颜色。
10. 8 个独立列表页补底部安全区。
11. 详情加载/失败分支补 AppBar，封面顶部加黑色渐变，边距 24→16。
12. 点赞/收藏选中态改实心图标；分类与 my tabs 补 selected 语义。
13. HeaderPill、LoginButton、分类 Chip 点击区补到 44。
14. 观看记录加载占位改为 114，并复用 12 内边距。
### 36.4 既有断言兼容
首轮回归发现两项既有断言与通用 token 冲突：
```text
Auth card radius expected 20, actual 16
EmptyState subtitle expected 12.5, actual 12
EmptyState action expected 13, actual 14
```
按“不改测试断言”要求保留为显式 token 例外：
```text
authCardRadius = 20
emptyStateSubtitle = 12.5
emptyStateAction = 13
```
其余通用卡片仍为 16，正文 caption 仍为 12。
### 36.5 门禁
```text
$ dart analyze lib test
Analyzing lib, test...
No issues found!
```
```text
$ flutter test
00:24 +341: All tests passed!
```
```text
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 7.8s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
### 36.6 Git
```text
df5fbe5 feat(ui): 增加视觉 token 与统一导航
c5bfd00 style(ui): 统一页面字号间距与状态样式
5f1df40 fix(ui): 保留空态既有字号口径
e44fbdf style(ui): 合并 K20 客户端视觉统一
42ce1d1..e44fbdf develop -> develop
```
提交 author/committer 均为 `Zhou Weidong <502333560@qq.com>`。
### 36.7 用户真机验收
设备侧取证由用户执行：
1. 首页底部导航：检查 64 高、22 图标、11 标签、主色胶囊选中态和四个原 Key。
2. 发现页：检查三处导航一致，分类 Chip 点击区 44、选中语义和 header 按钮高度。
3. 我的页：检查账号卡 64 高、四入口可点，菜单/语言入口仍在首屏可用。
4. 详情页：检查返回按钮可读、封面顶部渐变、24 标题、16 边距、进度条 4 高。
5. 观看记录：检查加载占位 114、真实卡片 12 padding、进度条和 12 以上辅助文本。
6. 下载页：检查策略卡、授权卡、12 圆角、进度条和安全区。
7. 公告/收藏/账号中心：检查卡片 12/16 圆角、正文 ≥12、底部安全区。
8. 播放器抽屉与右侧栏：检查点赞/收藏选中实心图标，fallback 导航与其他页一致。
9. 浅色封面详情页：确认返回/更多图标因顶部黑色渐变保持可读。
10. Android 系统栏：确认状态栏浅色图标、导航栏为 `AppColors.bar`。
---
## 35. K19 非 ApiException 网络文案修复
### 35.1 缺陷与修复
Trae 复核发现，账号中心三个逻辑类在断网、超时等非 `ApiException`
失败时，把内部哨兵键直接交给 `errorText`，会原样上屏：
```text
accountProfileLoadFailed
accountProfileSaveFailed
accountDevicesLoadFailed
accountExportLoadFailed
```
修复严格沿用既有 `errorText` 约定：
- 非 `ApiException` 统一置 `networkError`；
- `ApiException.message` 继续原样透传；
- 未修改 `errorText` 映射表；
- 未修改既有测试断言。
修改位置：
```text
ReelShort/lib/pages/account/account_profile_logic.dart
ReelShort/lib/pages/account/account_devices_logic.dart
ReelShort/lib/pages/account/account_export_logic.dart
```
### 35.2 TDD 与定向测试
先给 `FakeAccountRepository` 增加通用异常开关，并新增四个页面测试。
修复前红灯：
```text
00:01 +4 -4: Some tests failed.
should_show_localized_network_copy_when_profile_load_fails
should_show_localized_network_copy_when_profile_save_fails
should_show_localized_network_copy_when_devices_fail
should_show_localized_network_copy_when_export_fails
```
修复后定向测试：
```text
$ flutter test test/account/account_pages_test.dart
00:01 +8: All tests passed!
```
四个用例分别使用中文、英文、印尼语当前语言环境，断言上屏
`l10n.networkError`，且不出现内部哨兵键。
### 35.3 最终门禁
```text
$ dart analyze lib test
Analyzing lib, test...
No issues found!
```
```text
$ flutter test
00:23 +339: All tests passed!
```
```text
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 7.2s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
### 35.4 Git
```text
27ab7ce fix(account): 本地化网络异常文案
42ce1d1 fix(account): 合并网络异常文案修复
9b3ab9d..42ce1d1 develop -> develop
```
提交 author/committer 均为 `Zhou Weidong <502333560@qq.com>`。
### 35.5 用户验证建议
设备侧取证由用户执行：
1. 登录后断开手机网络，打开「个人资料」。
预期：显示当前语言的网络异常文案，不出现 `accountProfileLoadFailed`。
2. 恢复网络后修改昵称，再断网保存。
预期：显示当前语言的网络异常文案，不出现 `accountProfileSaveFailed`。
3. 断网打开「登录设备」。
预期：显示当前语言的网络异常文案，不出现 `accountDevicesLoadFailed`。
4. 断网打开「数据导出」。
预期：显示当前语言的网络异常文案，不出现 `accountExportLoadFailed`。
---
## 34. K19 客户端账号中心
### 34.1 基线与实施范围
基线确认：
```text
ReelShort: 7d68699 fix(config): 合并开发默认服务器地址
FruitServer: 5c93ba9 docs(plans): 下发 K19 账号中心接口对接任务
```
计划文档先提交为 `6b5e70e docs(plans): 增加 K19 账号中心实施计划`。
客户端从干净 develop 创建 `feature/flutter-k19-account`，只对接：
```text
GET /app/me
PUT /app/me
GET /app/me/devices
GET /app/me/export
POST /app/me/deactivate
POST /app/me/deactivate/cancel
```
接口口径以后端实际代码为准：设备直接返回实体数组；导出返回
`profile / credentials / consents / devices`；注销请求只发送 `reason`。
### 34.2 TDD 与实现
先用不存在的 `AccountApi/AccountProfile` 跑红灯，确认测试在实现前失败：
```text
Error: Error when reading 'lib/core/data/remote/account_api.dart':
No such file or directory
Some tests failed.
```
第一批实现后：
```text
$ flutter test test/account/account_api_test.dart
00:00 +7: All tests passed!
```
登录态同步先红灯：
```text
Error: The method 'applyProfile' isn't defined for the type 'AuthController'.
```
实现 `applyProfile(AuthUser)` 后：
```text
00:00 +1: All tests passed!
```
逻辑层覆盖资料保存回调、设备读取、导出复制、注销清会话和撤销失败文案：
```text
$ flutter test test/account/account_logic_test.dart
00:00 +5: All tests passed!
```
页面与入口先红灯，随后用稳定 Key 实现：
```text
$ flutter test test/account/account_pages_test.dart \
test/account/mine_account_entry_test.dart
00:01 +6: All tests passed!
```
实现文件：
```text
lib/core/data/remote/account_api.dart
lib/core/data/models/account_profile.dart
lib/core/data/models/account_device.dart
lib/core/data/models/account_export.dart
lib/core/data/repositories/account_repository.dart
lib/pages/account/*
lib/pages/mine/mine_view.dart
lib/core/data/services/auth_controller.dart
lib/app.dart
lib/l10n/app_{en,zh,id}.arb
```
### 34.3 首屏布局回归
首次全量测试时，新增账号卡把既有偏好设置和观看历史入口挤出可视区：
```text
Found 0 widgets with text "App Language"
Found 0 widgets with text "Watch History"
Some tests failed.
```
处理：不改既有测试断言，把账号卡收敛为 48px 紧凑横向入口，
保留四项图标、分隔线和账号标题；原有菜单项改用紧凑密度。
三个受影响测试回归：
```text
$ flutter test test/home/home_nav_ui_test.dart \
test/watch/watch_history_provider_test.dart test/widget_test.dart
00:06 +21: All tests passed!
```
### 34.4 最终门禁
```text
$ dart analyze lib test
Analyzing lib, test...
No issues found!
```
```text
$ flutter test
00:26 +335: All tests passed!
```
```text
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 10.0s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
### 34.5 Git
```text
44f6feb feat(account): 接入个人中心接口模型
ef7f4ce feat(account): 同步资料保存后的登录态
c68f024 feat(account): 增加账号中心页面逻辑
da09511 feat(account): 增加账号中心页面与入口
6fce24d refactor(account): 收敛账号页组件结构
7151bc9 style(account): 保持账号入口首屏可用
9b3ab9d feat(account): 合并 K19 账号中心
7d68699..9b3ab9d develop -> develop
```
所有提交 author/committer 均为 `Zhou Weidong <502333560@qq.com>`。
### 34.6 已知缺口
- 无注销状态查询：不能预先判断是否在冷静期，撤销失败直接展示后端文案。
- 无设备下线接口：设备页只读。
- 无头像上传接口：头像只展示。
- 资料响应不含生日：本批生日只能本次设置，不能回填或清空。
### 34.7 用户真机验证
以下步骤必须在设备侧执行并取证，开发机不代跑：
1. 登录后打开「我的」。
预期：钱包卡后、菜单卡前出现「账号」卡，四项入口完整可点击。
2. 打开「个人资料」。
预期：服务端字段回填；修改昵称/性别并保存后，我的页昵称同步更新。
3. 打开「登录设备」。
预期：设备号首尾可见、中间脱敏；平台、机型、时间、状态正确；空列表显示空态。
4. 打开「数据导出」。
预期：显示资料、凭据、授权记录数、设备数；复制 JSON 成功。
5. 打开「注销账号」。
预期：显示 15 天冷静期和立即登出提示；提交必须经过二次确认。
6. 确认注销。
预期：显示 `scheduledAt`，本地 token 清空并回到未登录状态。
7. 重新登录后撤销注销。
预期：有申请时成功；无申请时显示后端“没有待处理的注销申请”。
设备侧截图、日志和最终验收结论由用户执行。
---
## 2026-10-17 K10 统一空列表占位
### 26.1 范围、分支与计划
叙述：新增统一 `EmptyState`，替换任务书表格中的 10 处纯文字空态。只改空态
视觉、三语 l10n 与测试，不改列表数据、接口、加载/失败逻辑。
- 客户端分支：`feature/flutter-k10-empty-states`，基线 `19babb8`。
- 文档分支：`docs/k10-empty-states`，基线 K10 任务书 `3f84bc6`。
开工前先写并提交计划：
```text
f1d56b1 docs(plans): 增加 K10 统一空态实施计划
```
### 26.2 先红：组件与页面
组件文件尚不存在：
```text
$ flutter test test/empty_state/empty_state_test.dart
Error when reading 'lib/core/widgets/empty_state.dart': No such file or directory
Failed to load ".../empty_state_test.dart"
```
页面测试已能运行，但五处空态仍是旧实现：
```text
$ flutter test test/library/favorites_page_test.dart test/download/downloads_page_test.dart test/watch/watch_records_page_test.dart test/notice/notices_page_test.dart test/comment/drama_comments_sheet_test.dart
Found 0 widgets with type "EmptyState": []
00:03 +28 -6: Some tests failed.
```
解读：组件、收藏、下载、记录、通知、评论空态均未接入，红灯符合 K10 范围。
### 26.3 组件实现
新增：
```text
128 lib/core/widgets/empty_state.dart
```
规格：
- 默认 96x96、圆角 28、`AppColors.blue` 11% 背景，图标 42。
- compact 64x64、圆角 18、图标 28。
- 标题 16/w600，副标题 13 muted，最多 2 行。
- 可选 TextButton 最小高度 44，主题主色。
- 深色主题图标 `blueSoft`，浅色主题图标 `blue`。
- 外层 Semantics 只读标题；图形和文本排除重复语义，操作按钮仍可访问。
新增三语副标题：
```text
en: New content will appear here.
zh: 有新内容时会显示在这里。
id: Konten baru akan muncul di sini.
```
### 26.4 10 处替换
```text
lib/pages/home/home_view.dart movie_outlined
lib/pages/discover/widgets/home_drama_grid.dart grid_view_rounded / search_off_rounded
lib/pages/favorites/favorites_page.dart favorite_border_rounded
lib/pages/notices/notices_page.dart notifications_none_rounded
lib/pages/drama_detail/drama_detail_view.dart video_library_outlined
lib/pages/mine/mine_view.dart bookmark_border_rounded / history_rounded
lib/pages/downloads/downloads_page.dart download_outlined
lib/pages/watch_records/watch_records_page.dart history_rounded
lib/pages/player/widgets/drama_comments_sheet.dart chat_bubble_outline_rounded（compact）
```
首页将原合并的 `error || empty` 分支拆开：
- error 继续使用 `error_outline_rounded`、`catalogError`、重试与 debug API 地址。
- 空列表才使用 `EmptyState(noStories)`。
收藏、通知、记录、评论等失败态仍保留原错误与重试，不用 `EmptyState`。
### 26.5 定向与全量绿灯
组件测试：
```text
$ flutter test test/empty_state/empty_state_test.dart
00:00 +4: All tests passed!
```
组件与五处页面：
```text
$ flutter test test/empty_state/empty_state_test.dart test/library/favorites_page_test.dart test/download/downloads_page_test.dart test/watch/watch_records_page_test.dart test/notice/notices_page_test.dart test/comment/drama_comments_sheet_test.dart
00:03 +38: All tests passed!
```
```text
$ dart analyze lib test
Analyzing lib, test...
No issues found!
```
```text
$ flutter test
00:18 +302 ~1: All tests passed!
```
解读：302 项通过，1 项联调测试因客户端接口服务未启动按设计跳过；既有页面
用例保留，新增断言只增加 `EmptyState` 校验，不删除原用例。
### 26.6 Android debug 构建
用户 iOS `flutter run` 仍在运行，未终止该会话。为避免争用原项目 `build/`，
将同一工作区（排除 build/.git/.dart_tool/ephemeral）同步到独立临时副本后构建：
```text
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 6.9s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
解读：K10 最终代码通过 Android debug 构建，且原 iOS 运行会话未被中断。
### 26.7 Git
```text
6d08330 feat(flutter): 统一空列表占位组件
0466b4b merge: 合并 K10 统一空态组件
19babb8..0466b4b develop -> develop
```
功能提交与合并提交 author/committer 均为
`Zhou Weidong <502333560@qq.com>`。
- 2026-10-19 K22.1 首屏 loading：`.app-loading` 文字色改为 `#f8f1ea`，Web 提交 `a97b8cc`，合并 `3e8312e`，`pnpm build:pro` 通过。
### 26.8 用户真机验证步骤与预期
以下设备侧取证由用户执行，Codex 未跑真机。
1. 使用最新客户端 `develop`，分别切换深色和浅色主题进入一个空列表页面。
预期：显示 96x96 柔和蓝色底、图标、标题与可选说明，不白屏、不溢出。
2. 打开收藏、下载、观看记录、通知页面并清空对应数据。
预期：均显示统一 `EmptyState`，原有文案与清空/刷新逻辑正常。
3. 打开无评论的剧目评论弹窗。
预期：显示 compact 64x64 图标占位，弹窗仍可滚动与输入。
4. 打开无剧集详情或首页无剧目场景。
预期：显示对应空态；重试按钮行为保持不变。
5. 模拟接口失败。
预期：仍显示原错误图标、错误文案和重试，不显示空态占位。
6. 在 320px 宽小屏检查长标题、副标题和按钮。
预期：最多两行、可换行且无横向溢出，按钮点击区域不小于 44pt。
设备侧截图、语音朗读与最终验收结论由用户执行。
---
## 2026-10-17 K11 首页 3 列与全部分类
### 27.1 范围、分支与计划
叙述：在 K9 首页「全部剧目」网格上做最小修订，每行 3 个，分类首项从
`For You` 改为「全部」。只改网格参数、首个分类 label 和对应测试。
- 客户端分支：`feature/flutter-k11-home-grid-3col`，基线 `0466b4b`。
- 文档分支：`docs/k11-home-grid-3col`，基线任务书 `2a06190`。
开工前先写并提交计划：
```text
f97574b docs(plans): 增加 K11 首页三列网格实施计划
```
### 27.2 先红：3 列与全部文案
先更新 K9 网格测试的期望值并执行：
```text
$ flutter test test/discover/home_all_dramas_grid_test.dart
Expected: exactly one matching candidate
Actual: _TextWidgetFinder:<Found 0 widgets with text "All": []>
00:01 +0 -1: Some tests failed.
```
解读：分类首项仍显示旧文案，3 列断言在首个失败处之后尚未执行；红灯与 K11
目标一致。
### 27.3 实现
`home_drama_grid.dart`：
```text
crossAxisCount: 3
mainAxisSpacing: 14
crossAxisSpacing: 10
childAspectRatio: 2 / 3
```
`discover_view.dart`：
```text
(code: CategoryController.allCode, label: l10n.all)
```
已核对三份 ARB 原本已有 `all`：
```text
lib/l10n/app_en.arb:49: "all": "All",
lib/l10n/app_zh.arb:49: "all": "全部",
lib/l10n/app_id.arb:49: "all": "Semua",
```
解读：直接复用现有三语 getter，未添加重复 JSON key，也未改动 l10n 生成文件。
### 27.4 定向绿灯
```text
$ flutter test test/discover/home_all_dramas_grid_test.dart
00:01 +5: All tests passed!
```
测试同时断言：
- `crossAxisCount == 3`
- `crossAxisSpacing == 10`
- `mainAxisSpacing == 14`
- `childAspectRatio == 2/3`
- 首个 chip 为 `All`，且位于 `Hot` 左侧
- 320px 小屏 3 列布局无溢出
两个既有首页壳层用例仍保留，只更新旧分类断言：
```text
$ flutter test test/widget_test.dart
00:05 +17: All tests passed!
```
### 27.5 全量门禁与构建
```text
$ dart analyze lib test
Analyzing lib, test...
No issues found!
```
```text
$ flutter test
00:18 +302 ~1: All tests passed!
```
解读：302 项通过，1 项联调测试因客户端接口服务未启动按设计跳过。
用户 Android `flutter run` 仍在运行，未终止该会话。为避免争用原项目
`build/`，将当前工作区同步到独立临时副本后执行：
```text
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 21.8s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
### 27.6 Git
```text
f0db631 feat(flutter): 首页网格改为三列并首位显示全部
b5a8656 merge: 合并 K11 首页三列网格
0466b4b..b5a8656 develop -> develop
```
功能提交与合并提交 author/committer 均为
`Zhou Weidong <502333560@qq.com>`。
### 27.7 用户真机验证步骤与预期
以下设备侧取证由用户执行，Codex 未跑真机。
1. 使用最新客户端 `develop` 进入首页。
预期：分类 chips 第一项显示「全部 / All / Semua」，其后仍是热门、最新和
服务端分类。
2. 查看「全部剧目」列表。
预期：每行 3 个剧目，列间距 10、行间距 14，左右边距保持 16。
3. 检查长标题和类型。
预期：标题最多 2 行、类型最多 1 行，不横向或纵向溢出。
4. 点击「全部」及其他分类。
预期：网格内容按现有逻辑更新，点击卡片仍进入对应详情。
5. 在 320px 宽设备或小屏模拟器滚动列表。
预期：3 列布局稳定，无卡片重叠或整页溢出。
设备侧截图、滚动和分类切换结果由用户执行。
---
## 2026-10-17 K12 首页去标题与空态重做
### 28.1 范围、分支与计划
叙述：删除 K11 首页「全部剧目」标题，使分类 chips 后直接进入网格；同时将
K10 空态从实心圆角块改为双层同心圆。只改首页间距、`EmptyState` 和对应测试。
- 客户端分支：`feature/flutter-k12-home-empty-polish`，基线 `b5a8656`。
- 文档分支：`docs/k12-home-empty-polish`，基线任务书 `87a37e9`。
开工前先写并提交计划：
```text
e49664c docs(plans): 增加 K12 首页与空态视觉修订计划
```
构建前已确认用户真机会话停止，进程检查无并发 Flutter run/build。
### 28.2 先红：标题与旧空态
```text
$ flutter test test/empty_state/empty_state_test.dart test/discover/home_all_dramas_grid_test.dart
Found 0 widgets with key [<'empty-state-art-inner'>]: []
Expected: Size(60, 60)
Actual: Size(64, 64)
Expected: <260>
Actual: <280.0>
Found 1 widget with key [<'home-all-dramas-title'>]
00:02 +2 -7: Some tests failed.
```
解读：旧实心圆角空态仍为 96/64、最大宽 280，首页标题仍存在，红灯与 K12
目标一致。
### 28.3 首页去标题
删除 `home-all-dramas-title` Text 及其间隔，分类 Sliver 的底部 padding 改为 14。
实际 chips 控件增加稳定 Key：
```text
home-category-chips
```
测试读取 chips 底边与首张卡片的 RenderBox 顶边，断言间距：
```text
closeTo(14, 0.1)
```
### 28.4 空态双层同心圆
最终规格：
```text
default outer: 84, blue alpha 0.055, border alpha 0.11
default inner: 56, blue alpha 0.11
compact outer: 60; inner: 40
icon: 27 / compact 21
title: 15 w600
subtitle: 12.5, height 1.45
button: 13, min height 44
padding: 24x28 / compact 16x16
max width: 260
```
新增 Key：
```text
empty-state-art-inner
empty-state-padding
```
`empty-state-art`、`empty-state-icon`、`empty-state-title`、
`empty-state-action` 保持，外层 Semantics 仍只读标题。
### 28.5 定向与全量绿灯
组件、首页和既有壳层：
```text
$ flutter test test/empty_state/empty_state_test.dart test/discover/home_all_dramas_grid_test.dart test/widget_test.dart
00:06 +26: All tests passed!
```
既有壳层测试中的 `All Dramas` 文本锚点改为稳定网格 Key
`home-all-dramas-grid`，原导航流程与用例全部保留。
```text
$ dart analyze lib test
Analyzing lib, test...
No issues found!
```
```text
$ flutter test
00:17 +302 ~1: All tests passed!
```
解读：302 项通过，1 项联调测试因客户端接口服务未启动按设计跳过。
### 28.6 APK 构建
```text
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 16.6s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
### 28.7 Git
```text
2dd4627 feat(flutter): 精简首页标题并重做空态视觉
b762289 merge: 合并 K12 首页与空态视觉修订
b5a8656..b762289 develop -> develop
```
功能提交与合并提交 author/committer 均为
`Zhou Weidong <502333560@qq.com>`。
### 28.8 用户真机验证步骤与预期
以下设备侧取证由用户执行，Codex 未跑真机。
1. 打开首页并查看分类 chips 下方。
预期：不再显示「全部剧目」标题，chips 下方 14px 后直接出现 3 列网格。
2. 打开任一空列表页面。
预期：显示双层同心圆，外层比内层更淡，图标居中，不再是大块实心圆角矩形。
3. 分别切换深色和浅色主题。
预期：深色图标为 `blueSoft`，浅色图标为 `blue`，文字与背景对比清晰。
4. 检查带副标题和操作按钮的空态。
预期：标题 15、副标题 12.5、按钮 13，间距舒展，按钮点击区域不少于 44pt。
5. 打开无评论弹窗。
预期：使用 60/40 compact 双层圆，图标 21，上下留白 16，不挤压输入区。
6. 在 320px 宽小屏检查空态和首页。
预期：最大宽 260 生效，无横向溢出，标题最多两行。
设备侧截图、深浅主题与小屏结果由用户执行。
---
## 2026-10-17 K13 运行时服务器地址设置
### 29.1 范围、分支与计划
叙述：解决 debug APK 不带 `--dart-define` 时固定回退到 `.local` 的问题。
新增 debug-only 运行时地址，优先级为本地设置 > dart-define > 现有默认。
- 客户端分支：`feature/flutter-k13-dev-server-setting`，基线 `b762289`。
- 文档分支：`docs/k13-dev-server-setting`，基线任务书 `1a5951c`。
开工前先写并提交计划：
```text
6405dff docs(plans): 增加 K13 开发服务器地址实施计划
```
当前有真机 `flutter run` 会话，未主动终止；构建在独立副本中完成。
### 29.2 先红：运行时配置与入口缺失
```text
$ flutter test test/config/server_endpoint_test.dart test/mine/server_endpoint_setting_test.dart
Error when reading 'lib/core/config/server_endpoint.dart': No such file or directory
Member not found: 'AppConfig.clearRuntimeBaseUrl'
No named parameter with the name 'showServerSetting'
Some tests failed.
```
解读：运行时解析器、AppConfig 覆盖入口和 debug 设置参数均不存在，红灯符合 K13
范围。
### 29.3 运行时解析与启动顺序
新增：
```text
86 lib/core/config/server_endpoint.dart
```
关键规则：
```text
preference key: dev.api_base_url
runtime > dart-define(API_BASE_URL) > default
normalize: trim, http(s), non-empty host, trailing slash removed
release: ServerEndpoint.load(debug: false) returns before preferences are read
```
`main()` 在 `runApp` 前执行：
```dart
await ServerEndpoint.load();
runApp(const LumaDramaApp());
```
因此 `LumaDramaApp` 创建共用 ApiClient 前，运行时地址已经加载完成。
### 29.4 Debug 设置入口
我的页设置弹窗增加服务器地址行：
- 显示当前 `AppConfig.apiBaseUrl`；
- 编辑弹窗预填当前地址；
- 保存合法值后提示重启生效；
- 非法值显示三语错误且不写 SharedPreferences；
- 恢复默认清除 `dev.api_base_url`；
- 设置面板改为 85% 屏高内可滚动，避免小屏溢出。
可见性通过 `MyPage.debugShowSetting` 注入，默认 `kDebugMode`。release
编译时默认 false，不显示该行，也不读取本地覆盖。
新增三语 key：
```text
serverAddress
serverAddressHint
saveAddress
restartToApply
restoreDefault
invalidServerAddress
```
### 29.5 定向与全量绿灯
```text
$ flutter test test/config/server_endpoint_test.dart test/mine/server_endpoint_setting_test.dart
00:00 +7: All tests passed!
```
覆盖：
- 本地设置 > dart-define > 默认；
- trim、末尾斜杠、http/https；
- `ftp://`、缺 scheme、空 host 拒绝；
- debug=false 不应用本地覆盖；
- save/clear SharedPreferences；
- debug 入口可见、注入 false 不可见；
- 非法地址不保存并显示错误。
```text
$ dart analyze lib test
Analyzing lib, test...
No issues found!
```
```text
$ flutter test
00:19 +309 ~1: All tests passed!
```
解读：309 项通过，1 项联调测试因客户端接口服务未启动按设计跳过。
### 29.6 无 dart-define 的 Debug APK
用户真机 run 未终止。将当前工作区同步到独立临时副本，并明确不带构建参数：
```text
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 23.4s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
解读：即使 APK 没有 `--dart-define`，安装后也可在 debug 设置中保存真实服务器
地址，重启后覆盖现有 `.local` 默认值。
### 29.7 Git
```text
907562a feat(flutter): 增加 debug 运行时服务器地址设置
f95325d merge: 合并 K13 开发服务器地址设置
b762289..f95325d develop -> develop
```
功能提交与合并提交 author/committer 均为
`Zhou Weidong <502333560@qq.com>`。
### 29.8 用户真机验证步骤与预期
以下设备侧取证由用户执行，Codex 未跑真机。
1. 安装本次不带 `--dart-define` 构建的 debug APK。
预期：App 可以启动，进入「我的 → 设置」能看到「服务器地址」。
2. 点击「服务器地址」。
预期：编辑框预填当前地址，并显示「重启 App 生效」。
3. 输入真实局域网地址，例如 `http://192.168.31.187:8081`，保存。
预期：返回设置页并提示重启；输入框不会保留非法格式。
4. 完全结束 App 后重新打开，确认首页/发现请求成功，并在后端日志看到来自手机
的 `/app/home/feed` 等请求。
预期：请求使用新地址，不再访问 `.local` 默认地址。
5. 再次进入设置，点击「恢复默认」并重启。
预期：本地覆盖被清除，回到编译配置地址。
6. 用 release 构建检查。
预期：设置中完全没有服务器地址入口，且即使本地存有 key 也不会读取。
设备侧日志、截图与最终连通性结论由用户执行。
---
## 2026-10-17 K14 客户端文档
### 30.1 范围与依据
叙述：重写客户端 README，新增任务清单和文件说明。只改 ReelShort 的三份文档，
不改代码、specs、后端或 Web。
核对依据：
- `pubspec.yaml`、`pubspec.lock`
- `lib/` 与 `test/` 实际目录
- `lib/core/data/remote/**` 实际调用
- `FruitServer/docs/api-phase1.md` 章节
- `FruitServer/docs/plans/PROGRESS.md` 已完成批次
客户端分支：`docs/k14-client-docs`，基线 `f95325d`。
### 30.2 接口与目录核对
Flutter 版本：
```text
$ flutter --version
Flutter 3.47.7 • channel stable
Tools • Dart 3.13.5 • DevTools 2.60.0
```
接口路径：
```text
$ rg -o "'/app/[^']+'" lib/core/data/remote -g '*.dart' | sort -u | wc -l
26
```
按 HTTP 方法和重复 URL 逐项统计为 31 个方法级调用。README 已按账号、内容、
观看记录、收藏、下载、互动和公告分组列出。
### 30.3 文档内容
`ReelShort/README.md`：
- 印尼市场定位、技术栈、目录概览；
- 实际接口清单；
- Android USB、Android 模拟器、iOS 和 debug 运行时地址；
- iOS foundation 2.5.6、SPM 恢复、Android libdartjni 处理；
- 门禁命令、测试命名和当前边界。
`ReelShort/docs/TASKS.md`：
- K1-K13 批次表；
- K4、支付/金币、搜索、下载落盘待办；
- 未确认范围标「需核对」，未编造提交号。
`ReelShort/docs/FILES.md`：
- 目录树、关键文件职责、test 结构；
- `app_localizations*.dart`、`*.g.dart`、build、ephemeral 等生成物标注为勿手改。
仓库 `.gitignore` 包含 `/docs/`。本轮只对新增的两个 docs 文件使用
`git add -f`，没有修改 `.gitignore`。
### 30.4 门禁
```text
$ dart analyze lib test
Analyzing lib, test...
No issues found!
```
```text
$ flutter test
00:20 +309 ~1: All tests passed!
```
解读：文档改动未误改代码；309 项通过，1 项联调测试因服务未启动跳过。
### 30.5 Git
```text
5a28845 docs(client): 重写 README 并补充任务与文件说明
213c86e docs(client): 修正已接接口数量说明
9fe62d1 merge: 合并 K14 文档接口统计修正
f95325d..9fe62d1 develop -> develop
```
主提交、修正提交和最终合并的 author/committer 均为
`Zhou Weidong <502333560@qq.com>`。
### 30.6 文档验收
1. 打开 `ReelShort/README.md`，按表中命令可完成 Android USB、iOS 和 debug
运行时地址配置。
2. 打开 `ReelShort/docs/TASKS.md`，能区分已合入功能与待办/需核对事项。
3. 打开 `ReelShort/docs/FILES.md`，能定位核心配置、数据层、页面、测试和生成物。
4. 文档中的接口路径与 `lib/core/data/remote/` 一致。
---
## 2026-10-17 K15 首页服务器设置与真机默认地址
### 31.1 最终范围
用户最终确认手机与 Mac 在同一网络，不使用 USB 转发。修复范围确定为：
1. 真机默认地址改为 `http://10.157.242.1:8081`，只替换
`devHostBaseUrl`；
2. 平台默认选择与优先级保持不变：运行时设置 > dart-define > 平台默认；
3. 首页加载失败页 debug 下增加「服务器设置」，复用 K13 地址弹窗；
4. release 不显示入口。
客户端修复分支：`fix/home-server-default`，基线 `9fe62d1`。
### 31.2 地址与失败页实现
`AppConfig`：
```text
devHostBaseUrl = "http://10.157.242.1:8081"
```
注释已说明该 IP 跟随开发机网络变化，换网络时只改这一行。模拟器、桌面端和
iOS 模拟器仍使用 `127.0.0.1`；iOS/Android 真机使用该局域网地址。
K13 的服务器地址弹窗抽到：
```text
lib/core/widgets/server_endpoint_dialog.dart
```
我的页和首页错误页共用同一弹窗。首页错误页新增
`home-server-settings` 按钮，仅调试工具开启时显示；可编辑、保存、恢复默认，
保存后提示重启生效。
### 31.3 测试与门禁
新增/更新测试：
- `AppConfig.devHostBaseUrl` 为最终局域网地址；
- 原有运行时 > dart-define > 默认优先级继续通过；
- 首页错误页 debug 下显示按钮并可打开 `server-endpoint-input`；
- 注入 release 条件时按钮不显示；
- 我的页设置入口与非法地址拒绝继续通过。
```text
$ flutter test test/config/server_endpoint_test.dart test/mine/server_endpoint_setting_test.dart test/home/home_server_setting_test.dart
00:02 +10: All tests passed!
```
```text
$ dart analyze lib test
Analyzing lib, test...
No issues found!
```
```text
$ flutter test
00:21 +312 ~1: All tests passed!
```
```text
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 13.2s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
解读：312 项通过，1 项联调测试因服务未启动跳过；debug APK 构建成功。
### 31.4 Git
```text
c4694c6 fix(flutter): 增加首页服务器设置并更新真机默认地址
4778ce2 merge: 合并 K15 首页服务器设置修复
9fe62d1..4778ce2 develop -> develop
```
功能提交与合并提交 author/committer 均为
`Zhou Weidong <502333560@qq.com>`。
### 31.5 用户真机验证步骤
1. Android Studio 直接 Run，不额外传 `--dart-define`。
预期：默认请求 `http://10.157.242.1:8081`。
2. 若首页仍加载失败，在错误页查看 debug 地址和「服务器设置」按钮。
预期：点击后打开与「我的 → 设置」相同的地址弹窗。
3. 修改地址并保存，完全结束 App 后重开。
预期：使用新地址请求，后端日志出现手机侧请求。
4. release 构建中检查首页错误页。
预期：不显示服务器设置入口。
设备侧日志、截图和最终网络连通性结论由用户执行。
---
## 2026-10-17 K16 注册限流后台配置化
### 32.1 最终口径
叙述：K16 开工后 Trae 于 `461fb8e` 更新任务书，要求从 `sys_config` 读取配置，
不使用 `application.yml` 固化。初版 `@Value` 实现已按最新口径修正。
最终配置键：
```text
app.register.max-per-ip-per-day
app.register.max-per-device-per-day
```
- 值 <= 0：对应维度不限制；
- 键缺失或非整数：回退 IP 5 / 设备 3；
- 错误码和错误文案不变。
### 32.2 后端实现与测试
`AppAuthService` 注入 `ConfigService`，module-user 增加 module-system 依赖。
首次红灯：
```text
Could not find field 'maxRegisterPerIpPerDay'
Tests run: 16, Failures: 0, Errors: 4
```
最终定向测试：
```text
$ mvn -pl fruitshorts-app-api -am -Dtest=AppAuthServiceTest -Dsurefire.failIfNoSpecifiedTests=false test
Tests run: 18, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS
```
覆盖：IP 超限、设备超限、自定义阈值、IP=0、设备=0、缺省回退、非数字回退。
全量测试：
```text
$ mvn test
[INFO] BUILD SUCCESS
```
### 32.3 种子配置与后台页面
`sql/data-phase1.sql` 增加幂等种子：
```sql
INSERT INTO sys_config (id, config_key, config_value, remark) VALUES
(3, 'app.register.max-per-ip-per-day', '0', '0=不限制；生产建议 5'),
(4, 'app.register.max-per-device-per-day', '0', '0=不限制；生产建议 3')
ON CONFLICT (config_key) DO NOTHING;
```
当前开发库执行结果：
```text
INSERT 0 2
id | config_key | config_value | remark
----+-------------------------------------+--------------+--------------------
3 | app.register.max-per-ip-per-day | 0 | 0=不限制；生产建议 5
4 | app.register.max-per-device-per-day | 0 | 0=不限制；生产建议 3
```
后台 `SettingsView.vue` 原有页面只显示两个旧配置字段，因此补充了两个数值项，
沿用现有 `/admin/configs` 接口，不新建页面。
```text
$ pnpm build:pro
Build successful. Please see dist-pro directory
```
Web 提交 `54db082`，合并 `5c087f4`，已推送。
### 32.4 打包、重启与接口自检
```text
$ mvn -pl fruitshorts-app-api -am package -DskipTests
[INFO] BUILD SUCCESS
```
旧 8081 服务停止后，通过 `launchctl` 启动新 jar。当前服务：
```text
80642 0 com.fruitshorts.app-api
java 80642 ... TCP *:8081 (LISTEN)
```
健康检查：
```text
HTTP/1.1 200
{"code":0,"message":"ok","data":{"status":"UP","app":"fruitshorts-app-api",...}}
```
同一新设备号连续注册 4 次（令牌字段已省略）：
```text
attempt 1 HTTP 200 {"code":0,"message":"ok","newUser":true,"uid":"U-4JA-DDD"}
attempt 2 HTTP 200 {"code":0,"message":"ok","newUser":true,"uid":"UTIOUCLLV"}
attempt 3 HTTP 200 {"code":0,"message":"ok","newUser":true,"uid":"UR6ZJRO74"}
attempt 4 HTTP 200 {"code":0,"message":"ok","newUser":true,"uid":"UXJF6MECJ"}
```
解读：开发库两键均为 0，IP 与设备 guard 均跳过，连续注册不再 429。
### 32.5 Git
```text
FruitServer:
3403a52 docs(plans): 增加 K16 注册限流配置化计划
758eb69 feat(backend): 注册限流阈值改为可配置
f1aaaee fix(backend): 改为后台配置注册限流阈值
f4003ed test(backend): 覆盖注册限流缺省回退
5b7be2e merge: 合并注册限流缺省回退测试
78fb995..5b7be2e develop -> develop
ReelShortWeb:
54db082 feat(admin): 增加注册限流配置项
5c087f4 chore(admin): 合并注册限流配置项
3ec9ea6..5c087f4 develop -> develop
```
最终后端修正与 Web 提交的 author/committer 均为
`Zhou Weidong <502333560@qq.com>`。
### 32.6 用户验收步骤
1. 登录后台「系统设置」。
预期：看到注册频控两个数值项，当前均为 0。
2. 将单设备上限改为 3，保存后使用同一设备注册第 4 次。
预期：返回 429；恢复 0 后第 4 次可成功。
3. 将单 IP 上限改为 1，保存后从同一 IP 注册第 2 次。
预期：返回 429；恢复 0 后恢复不限。
4. 验证完成后开发库恢复 0/0；生产配置建议恢复 IP 5 / 设备 3。
设备侧接口结果与后台截图由用户最终验收。
### 32.7 API 文档键名补正
复核 `docs/api-phase1.md` §1.1 时发现文档仍沿用旧的
`fruitshorts.auth.register-max-*` 键名，与 `AppAuthService` 实际读取的
`sys_config` 键不一致。已补正为：
```text
app.register.max-per-ip-per-day
app.register.max-per-device-per-day
```
同时将入口表述统一为后台「系统配置」。本次只补正文档，不改运行逻辑。
补正后复核：
```text
$ mvn test
AppAuthServiceTest: Tests run: 18, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS
```
开发库两键均为 `0`。同一新设备号连续注册 4 次均为 `code=0`：
```text
uid=UFCIW1LWU
uid=UP2BH-DN_
uid=ULOFAAU2Z
uid=UDAYJR-_E
```
---
## 2026-10-17 K16 返工：sys_config 优先 + @Value 兜底
### 33.1 返工范围
K16 首版合并后，用户要求明确区分后台运行配置与 yml fallback：
- `AppAuthService` 运行时优先读取 `sys_config`：
`app.register.max-per-ip-per-day`、`app.register.max-per-device-per-day`；
- 键缺失或非整数时，回退 `@Value` 注入的
`fruitshorts.auth.register-max-*`；
- yml 中的值只作 fallback，默认 5 / 3；≤0 仍表示不限制。
返工分支：`fix/k16-register-config-fallback`。
### 33.2 TDD 与测试
先把非数字配置用例改为验证 @Value fallback=2，旧实现红灯：
```text
Could not find field 'maxRegisterPerIpPerDay'
Tests run: 18, Failures: 0, Errors: 1, Skipped: 0
BUILD FAILURE
```
增加注入字段并接入 registerLimit 后，定向测试转绿：
```text
RUNNING AppAuthServiceTest
Tests run: 18, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS
```
全量测试：
```text
$ mvn test
[INFO] fruitshorts-module-user ............................ SUCCESS
[INFO] fruitshorts-app-api ............................... SUCCESS
[INFO] BUILD SUCCESS
```
代码提交：
```text
35d92c0 fix(backend): 后台注册限流配置优先并保留注入兜底
```
### 33.3 数据库与后台接口
重新执行 `sql/data-phase1.sql` 中的幂等插入：
```text
INSERT 0 0
```
查询结果：
```text
config_key | config_value | remark
app.register.max-per-device-per-day | 0 | 0=不限制；生产建议 3
app.register.max-per-ip-per-day | 0 | 0=不限制；生产建议 5
(2 rows)
```
使用本机开发管理员登录后，`GET /admin/configs` 返回：
```json
{
"code": 0,
"message": "ok",
"configs": [
{
"key": "app.register.max-per-device-per-day",
"value": "0",
"remark": "0=不限制；生产建议 3"
},
{
"key": "app.register.max-per-ip-per-day",
"value": "0",
"remark": "0=不限制；生产建议 5"
}
]
}
```
现有 `SettingsView.vue` 已使用 `listConfigsApi` / `updateConfigsApi`，
页面上的两个数值输入项可直接读写这两键。
### 33.4 阈值 2 往返验证
通过后台 `PUT /admin/configs` 把 IP 上限临时设为 2、设备上限设为 0，
使用同一条测试 IP 连续注册：
```text
attempt 1 HTTP 200 code=0 message=ok
attempt 2 HTTP 200 code=0 message=ok
attempt 3 HTTP 200 code=429 message=当前网络注册过于频繁，请稍后再试
```
随后通过同一后台接口恢复 IP=0，再注册一次：
```text
attempt 4 HTTP 200 code=0 message=ok
```
说明：当前统一响应包装对外使用 HTTP 200，业务码在 `code` 字段返回 429。
### 33.5 打包与 8081
```text
$ mvn -pl fruitshorts-app-api -am package -DskipTests
[INFO] BUILD SUCCESS
```
通过 `launchctl kickstart -k gui/501/com.fruitshorts.app-api` 重启：
```text
before PID: 80642
after PID: 94657
java 94657 ... TCP *:8081 (LISTEN)
```
健康检查：
```text
{"code":0,"message":"ok","data":{"status":"UP","app":"fruitshorts-app-api","profiles":"","time":"2026-10-17T23:38:32.363463"}}
HTTP 200
```
---
## 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 范围、分支与计划
叙述：按 INBOX K8 条目重设计登录页视觉，不改 AuthLogic、校验、AuthController、
接口、登录/注册流程或其他页面。客户端从 `develop 6cc5bfc` 创建
`feature/flutter-k8-auth-visual`；FruitServer 从 K8 任务书提交 `c33e6cd`
创建 `docs/k8-auth-visual`，只改 `docs/plans/`。
开工前先写并提交计划：
```text
e7c11c3 docs(plans): 增加 K8 登录页视觉实施计划
```
实施文件：
- `lib/pages/auth/auth_view.dart`
- `lib/pages/auth/auth_widgets.dart`
- `lib/pages/auth/auth_form_widgets.dart`
- `test/auth/auth_visual_test.dart`
`auth_view.dart` 初次实现达到 654 行，触发项目单文件 500 行红线。随后按页面
组合、卡片/分段控件、表单控件与品牌组件拆分，最终行数：
```text
259 lib/pages/auth/auth_view.dart
183 lib/pages/auth/auth_widgets.dart
363 lib/pages/auth/auth_form_widgets.dart
311 test/auth/auth_visual_test.dart
```
解读：所有新增 Dart 文件均低于 500 行，页面状态类低于 300 行。
### 23.2 先红：视觉测试
叙述：先新增 `test/auth/auth_visual_test.dart`，未改既有
`test/auth/auth_page_test.dart`。
```text
$ flutter test test/auth/auth_visual_test.dart
Expected: exactly one matching candidate
Actual: Found 0 widgets with key [<'auth-brand'>]: []
Bad state: No element
The finder "Found 0 widgets with key [<'auth-mode-sign-up'>]: []"
could not find any matching widgets.
Expected: exactly one matching candidate
Actual: Found 0 widgets with key [<'auth-error-capsule'>]: []
00:01 +2 -4: Some tests failed.
```
解读：品牌区、220ms 入场动画、pill 分段控件和错误胶囊尚不存在，红灯与 K8
新增视觉范围一致；既有功能型交互仍可运行。
### 23.3 绿灯：视觉与交互实现
实现后的新增与既有 auth 用例：
```text
$ flutter test test/auth/auth_visual_test.dart test/auth/auth_page_test.dart
00:01 +15: All tests passed!
```
覆盖内容：
- 深色品牌页、`AppColors.ink`、顶部克莱因蓝渐变透明度不超过 0.18。
- 48px 蓝色圆角品牌方块、App 名和印尼市场 tagline。
- `AppColors.card`、20px 圆角、1px `outlineVariant` 边框、20px 内边距。
- 52px 输入框、14px 圆角、`AppColors.bar` 填充、邮箱/锁前缀图标和聚焦
1.5px 主色边框。
- 52px 主按钮、26px 圆角、`AppColors.blue`/`bluePressed`、16/w700
文字与 18px loading。
- pill 登录/注册分段控件、选中主色底、切换调用现有 `toggleMode()`。
- 220ms 淡入上滑、错误浅红胶囊、44pt 以上点击区域。
- 邮箱→密码焦点流转、密码显隐、busy 禁用、Haptics 和 autofill 均保留。
既有 `auth-switch-mode` Key 与旧测试所需文本兼容入口保留，但用户可见切换控件
已改为 pill 分段；旧用例没有删改。
### 23.4 全量门禁与构建
构建前检查并发进程：
```text
$ ps -axo pid=,etime=,args= | rg 'flutter_tools.snapshot (run|build)|xcodebuild|gradlew'
```
输出仅有当前检查命令自身，没有 Flutter run/build 进程后开始门禁。
```text
$ dart analyze lib test
Analyzing lib, test...
No issues found!
```
```text
$ flutter test
00:19 +292 ~1: All tests passed!
```
解读：292 项通过，1 项联调测试因客户端接口服务未启动按设计跳过；输出中的
`[WatchRecordsController]` 堆栈来自既有故意注入失败的测试。
```text
$ flutter build apk --debug
Running Gradle task 'assembleDebug'...
38.2s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
门禁执行期间 Flutter 工具自动改写 `pubspec.lock` 的包镜像和新版 SDK 传递依赖；
该文件不属于 K8 范围，已单独还原，未进入提交。
### 23.5 Git
```text
45c3c64 feat(flutter): 重设计登录页视觉
99f64ab merge: 合并 K8 登录页视觉重设计
6cc5bfc..99f64ab develop -> develop
```
修复提交与合并提交 author/committer 均为
`Zhou Weidong <502333560@qq.com>`。
### 23.6 用户真机验证步骤与预期
以下设备侧取证由用户执行，Codex 未跑真机。
1. 拉取最新客户端 `develop`，冷启动并进入登录页。
预期：全屏深色背景，顶部只有克制的蓝色光晕，品牌方块、App 名和印尼
tagline 清晰可见。
2. 观察表单卡片和输入框。
预期：卡片为深色圆角面板；输入框高 52、圆角 14，邮箱和锁图标存在。
3. 点击邮箱输入框并切换到密码框。
预期：聚焦输入框出现 1.5px 克莱因蓝边框，图标高亮；键盘 Next 会跳到密码，
Done 会提交。
4. 点击登录/注册 pill 两段。
预期：选中段蓝底白字，标题、副标题和按钮文案同步切换。
5. 点击密码右侧眼睛按钮。
预期：密码明文/密文切换，按钮点击区域不小于 44pt。
6. 输入错误邮箱或不安全密码并提交。
预期：卡片内出现浅红胶囊错误提示，文案与当前语言一致。
7. 在 iPhone SE 尺寸打开键盘并滚动。
预期：无横向溢出，提交按钮可滚动到键盘上方并点击。
8. 登录/注册提交时观察按钮与触觉。
预期：按钮显示 18px 白色 loading 环，输入与分段切换禁用；设备支持触觉时
有一次 light impact。
设备侧截图、日志与最终视觉验收结论由用户执行。
---
## 2026-10-17 K9 首页 2 列全部剧目
### 24.1 范围、分支与计划
叙述：按 INBOX K9 条目移除首页「继续观看」，在分类 chips 下方展示当前分类的
全部剧目。只改发现页、三语 l10n、首页相关测试与 `docs/plans/`；不改接口、
数据模型、轮播、通知或其他页面。
- 客户端：从 `develop 99f64ab` 创建 `feature/flutter-k9-home-grid`。
- 文档：从 K9 任务书 `b434f65` 创建 `docs/k9-home-grid`。
开工前先写并提交计划：
```text
496d273 docs(plans): 增加 K9 首页剧目网格实施计划
```
### 24.2 先红：首页网格测试
叙述：先新增 `test/discover/home_all_dramas_grid_test.dart`，未改实现与既有测试。
```text
$ flutter test test/discover/home_all_dramas_grid_test.dart
Expected: no matching candidates
Actual: Found 1 widget with text "Continue Watching"
Found 0 widgets with key [<'home-drama-card-city-lights-demo'>]: []
Found 0 widgets with text "All Dramas": []
00:02 +0 -5: Some tests failed.
```
解读：继续观看仍存在，「全部剧目」标题、2 列网格和卡片 Key 尚不存在，红灯与
K9 范围一致。
### 24.3 实现与定向绿灯
`discover_view.dart` 改为外层 `CustomScrollView`，首页 sliver 顺序为：
轮播、分类与标题、剧目网格、底部留白。网格代码拆到：
- `lib/pages/discover/widgets/home_drama_grid.dart`
关键参数：
```text
crossAxisCount: 2
mainAxisSpacing: 16
crossAxisSpacing: 12
childAspectRatio: 2 / 3
horizontal padding: 16
```
卡片使用 `RemoteImage`、14px 圆角、底部深色渐变；标题 2 行、类型 1 行。
点击直接调用现有 `logic.openCard(...)`。分类数据直接使用
`CategoryController.visibleDramas`。
新增三语 `allDramas` 并执行 `flutter gen-l10n`：
```text
$ rg -n "allDramas" lib/l10n
lib/l10n/app_localizations_en.dart:161: String get allDramas => 'All Dramas';
lib/l10n/app_zh.arb:58: "allDramas": "全部剧目",
lib/l10n/app_en.arb:58: "allDramas": "All Dramas",
lib/l10n/app_localizations_zh.dart:158: String get allDramas => '全部剧目';
lib/l10n/app_id.arb:58: "allDramas": "Semua Drama",
lib/l10n/app_localizations_id.dart:161: String get allDramas => 'Semua Drama';
```
定向绿灯：
```text
$ flutter test test/discover/home_all_dramas_grid_test.dart
00:01 +5: All tests passed!
```
覆盖：无继续观看、全部剧目标题、2 列 delegate、左右/行列间距、2:3 封面、
分类切换、无剧目空态、分类缺失空态、失败重试与 320px 小屏。
文件规模：
```text
487 lib/pages/discover/discover_view.dart
167 lib/pages/discover/widgets/home_drama_grid.dart
245 test/discover/home_all_dramas_grid_test.dart
```
解读：改造前 `discover_view.dart` 为 649 行；删除继续观看旧实现并拆分网格后
降到 500 行以内。首页源码已无 `continueWatching`、`_continueTile`、
`_ShowcaseCard`、`_cardsFor` 或嵌套 `GridView`。
### 24.4 既有壳层断言更新
`test/widget_test.dart` 原有 5 处断言首页出现 `Continue Watching`。K9 明确要求
该文案彻底消失，因此该断言与 `find.text('Continue Watching'), findsNothing`
不可能同时成立。
处理：保留全部既有用例、测试名称和导航流程，仅把 5 处已作废的可见文案断言
原位改为 `All Dramas`；没有删除测试用例。
```text
$ flutter test test/widget_test.dart
00:05 +17: All tests passed!
```
### 24.5 全量门禁与构建
首次静态分析发现新增测试有一个未使用 import：
```text
warning - test/discover/home_all_dramas_grid_test.dart:10:8
Unused import: 'package:fruitshorts/core/data/repositories/catalog_repository.dart'.
1 issue found.
```
移除后：
```text
$ dart analyze lib test
Analyzing lib, test...
No issues found!
```
```text
$ flutter test
00:18 +297 ~1: All tests passed!
```
解读：297 项通过，1 项联调测试因客户端接口服务未启动按设计跳过；输出中的
`[WatchRecordsController]` 堆栈来自既有故意注入失败的测试。
构建前检查：
```text
$ ps -axo pid=,etime=,args= | rg 'flutter_tools.snapshot (run|build)|xcodebuild|gradlew'
```
输出仅有当前检查命令自身，没有并发 Flutter run/build 后执行：
```text
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 8.4s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
### 24.6 Git
```text
cf03178 feat(flutter): 首页改为两列全部剧目网格
2c381be merge: 合并 K9 首页全部剧目网格
99f64ab..2c381be develop -> develop
```
功能提交与合并提交 author/committer 均为
`Zhou Weidong <502333560@qq.com>`。
### 24.7 用户真机验证步骤与预期
以下设备侧取证由用户执行，Codex 未跑真机。
1. 使用最新客户端 `develop` 进入首页「Home/发现」tab。
预期：页面不再出现「继续观看」标题或横向卡片。
2. 向下查看分类 chips。
预期：chips 下方显示当前语言对应的「全部剧目」/ `All Dramas` /
`Semua Drama`。
3. 观察列表布局。
预期：一行 2 个剧目，左右各 16，列间距 12、行间距 16；封面为 2:3 圆角。
4. 向下滚动长列表。
预期：继续按 2 列懒加载，滚动中无整页白屏或卡顿。
5. 依次点击「为你推荐 / 热门 / 最新 / 服务端分类」。
预期：网格内容随分类更新；「为你推荐」显示去重后的全部剧目。
6. 点击任意剧目卡片。
预期：沿用原详情流程打开对应剧目。
7. 在有长标题或空分类数据时检查卡片。
预期：标题最多 2 行、类型最多 1 行，不横向溢出；空态和失败重试文案保留。
设备侧截图、日志与最终验收结论由用户执行。
## K22 后台管理视觉与交互统一
### 分支与提交
```text
ReelShortWeb:
5c087f4 chore(admin): 合并注册限流配置项
97fbeda style(web): 统一后台图标与全局视觉
8f3447e chore(web): 合并 K22 后台视觉统一
FruitServer:
5e55171 docs(plans): 增加 K22 后台视觉统一计划
c14b4cb fix(sql): 统一后台菜单图标
be9e381 chore(sql): 合并 K22 菜单图标
```
功能提交与合并提交 author/committer 均为
`Zhou Weidong <502333560@qq.com>`。未修改 main、客户端业务代码与 Web 接口契约。
### 图标体系与扫描
新增 `src/constants/icons.ts`、`src/components/AppIcon/`，并将客户端品牌图标
复制为 `src/assets/imgs/brand-mark.png`。
```text
before-old-prefix=22
before-el-icon=15
before-element-plus-icons=16
old-prefix=0
el-icon=0
element-plus-icons=0
AppIcons unique=54 missing=0
```
页面与共享组件已不再直接引用旧 Iconify 前缀、`<el-icon>` 或
`@element-plus/icons-vue`。剩余两处 `<Icon>` 分别是 `AppIcon` 的底层包装与
`Icon` 自身的在线图标实现。
任务书列出的 `language-rounded`、`view-column-rounded`、`lock-rounded`、
`chevron-down-rounded` 在当前 Material Symbols JSON 中不存在，使用同语义且
通过存在性校验的 `translate-rounded`、`combine-columns-rounded`、
`lock-person-rounded`、`keyboard-arrow-down-rounded`。
### 菜单 SQL 与接口自检
已幂等执行：
```text
$ psql -d fruitshorts -v ON_ERROR_STOP=1 -f sql/data.sql
INSERT 0 3
INSERT 0 4
INSERT 0 19
INSERT 0 13
...
INSERT 0 4
$ psql -d fruitshorts -v ON_ERROR_STOP=1 -f sql/data-phase1.sql
DO
INSERT 0 0
...
UPDATE 5
...
INSERT 0 0
```
目标菜单回查：
```text
id | title | icon
----+------------+---------------------------------------------
1 | 工作台 | material-symbols:dashboard-rounded
2 | 工作台 | material-symbols:dashboard-rounded
3 | 内容管理 | material-symbols:video-library-rounded
6 | 后台管理 | material-symbols:settings-rounded
15 | 用户管理 | material-symbols:group-rounded
17 | 创作者管理 | material-symbols:movie-edit-rounded
20 | 内容治理 | material-symbols:policy-rounded
22 | 订单与权益 | material-symbols:payments-rounded
24 | 数据看板 | material-symbols:monitoring-rounded
26 | 创作者中心 | material-symbols:video-camera-front-rounded
32 | 运营管理 | material-symbols:campaign-rounded
(11 rows)
```
管理员登录后调用 `/admin/auth/menus`：
```text
工作台 material-symbols:dashboard-rounded
内容管理 material-symbols:video-library-rounded
后台管理 material-symbols:settings-rounded
用户管理 material-symbols:group-rounded
创作者管理 material-symbols:movie-edit-rounded
内容治理 material-symbols:policy-rounded
订单与权益 material-symbols:payments-rounded
数据看板 material-symbols:monitoring-rounded
运营管理 material-symbols:campaign-rounded
menus=28 icons=9 allMaterial=true
```
解读：超级管理员可见菜单接口返回的图标全部为 `material-symbols:` 前缀。
`创作者中心`（id 26）按既有规则对超级管理员隐藏，未出现在该菜单树，但数据库
回查已确认其图标正确。
### 登录页与全局壳
登录页：
- 删除 `admin` / `admin123` 占位，改为三语占位文案。
- “记住我”默认关闭，只保存用户名；退出和恢复时清理历史密码字段。
- 支持密码框回车提交；请求与动态路由生成完成前保持 loading，防重复。
- 品牌统一使用客户端 `splash_mark.png`，登录页与侧边栏同一资源。
- ≤960px 压缩品牌区；实测登录卡在 1024×768、800×768、375×812 首屏完整可见。
全局壳：
- 深色选中菜单、当前标签、主题开关轨道统一使用主色派生 token；
深色选中白字对比度由 `2.78:1` 提升到 `5.00:1`。
- 面包屑深色对比度 `11.13:1`，顶栏 `16.70:1`。
- 标签关闭图标改用 `var(--el-text-color-secondary)`。
- 删除 `body { min-width: 980px }` 和未使用的旧壳层死选择器。
- 补 1200/768 断点；1024、800、375 下 `documentElement.scrollWidth`
分别等于视口宽度，顶栏无越界元素。
- 用户头像/姓名读取 `userStore`，不再写死 `avatar.jpg` / `Archer`。
- “清除缓存并且重置”弹出二次确认，取消后保持当前状态。
- 字体、圆角、主色变量收敛；`#409eff !important` 已清零。
### 门禁
```text
$ pnpm lint:eslint
> fruitshorts-admin@1.0.0 lint:eslint /Users/jianghaifeng/Desktop/ReelShort/ReelShortWeb
> eslint --fix --ext .js,.ts,.vue ./src
```
```text
$ pnpm build:pro
> fruitshorts-admin@1.0.0 build:pro /Users/jianghaifeng/Desktop/ReelShort/ReelShortWeb
> VITE_CJS_IGNORE_WARNING=1 vite build --mode pro
[warn] Circular chunk: element-plus -> vue-chunks -> element-plus. Please adjust the manual chunk logic for these chunks.
[warn] node_modules/.pnpm/mockjs@1.1.0/node_modules/mockjs/dist/mock.js (537:22): Use of eval in "node_modules/.pnpm/mockjs@1.1.0/node_modules/mockjs/dist/mock.js" is strongly discouraged as it poses security risks and may cause issues with minification.
Build successful. Please see dist-pro directory
```
解读：ESLint 零错误；构建成功。两条 warning 来自既有 chunk 配置与 mockjs 依赖，
本批未改构建配置。
### 浏览器自查
Codex 已在本地开发服务完成以下自查，不作为用户验收：
- 登录页：三档宽度无横向溢出；800×768 登录卡底边 `754.40`，375×812 底边
`772.77`，均在首屏内。
- 登录交互：占位为“请输入用户名/请输入密码”；“记住我”默认未勾选；
密码框回车可进入工作台。
- 侧边栏：1024 展开 200px、收起 64px；375 抽屉展开 200px、遮罩关闭正常。
- 顶栏、标签页、面包屑、短剧管理工具栏均正常渲染 Material Symbols Rounded。
- 深色/浅色切换正常；深色选中菜单与当前标签均为白字压深主色，对比度 `5.00:1`。
- 清除缓存按钮显示“确认清除本地缓存并重新加载后台吗？”，取消有效。
- 浏览器控制台 0 个 error；动态路由刷新期间出现 2 条既有 `No match found`
router warning，随路由生成完成消失，不影响页面。
### 用户验收步骤与预期
1. 运行 `pnpm dev`，打开 `http://127.0.0.1:3005/#/login`。
预期：暖色品牌登录页；用户名/密码为中文占位；“记住我”默认关闭。
2. 输入管理员账号，在密码框直接回车。
预期：按钮进入 loading，随后只跳转一次工作台。
3. 检查左侧菜单、顶栏、标签页和短剧管理页工具栏。
预期：图标均为 Material Symbols Rounded，无旧图标混用。
4. 展开/收起侧栏，并打开右侧“项目配置”。
预期：品牌 mark 一致；主题开关边界清楚；布局无跳动。
5. 切换到深色再切回浅色。
预期：菜单、面包屑、当前标签、关闭图标与开关均清晰可辨。
6. 分别以 1024、800、375 宽度查看工作台、短剧管理和登录页。
预期：内容区与顶栏不横向裁切；375 可通过菜单按钮打开侧栏抽屉。
7. 点击“清除缓存并且重置”后选择取消。
预期：先出现二次确认，取消后页面状态不变。
最终业务验收由用户在浏览器执行。
### K22 复核收尾：静态路由图标
将 `src/router/index.ts` 中 5 处静态路由 `meta.icon` 从旧前缀改为
`AppIcons`：
```text
工作台：AppIcons.dashboard
内容管理：AppIcons.content
用户管理：AppIcons.group
后台管理：AppIcons.settings
```
`src/constants/icons.ts` 的历史短名与旧 Iconify 名兜底映射保持不变。
```text
$ rg -n "icon:\s*'(ant-design:|ep:)" src/router/index.ts
（无输出）
$ pnpm lint:eslint
> eslint --fix --ext .js,.ts,.vue ./src
$ pnpm build:pro
Build successful. Please see dist-pro directory
```
提交：
```text
29465ab fix(web): 统一静态路由图标
5494190 chore(web): 合并 K22 路由图标收尾
```
功能提交与合并提交 author/committer 均为
`Zhou Weidong <502333560@qq.com>`，Web `develop` 已推送。
## K22.1 后台收尾
### 登录页与注册清理
登录 hero 保留品牌 mark、kicker 与标题，删除说明段落和三个标签：
```text
FruitShorts
内容运营后台
短剧内容管理
登录
使用管理员账号进入工作台
用户名
密码
记住我
忘记密码
登录
```
同时删除已无引用的 `login.message/noAccount/pointDrama/pointPublish/pointAccess/
register/checkPassword/otherLogin/hasUser/code/codePlaceholder`、注册表单、注册入口、
`to-register` 事件和注册切换状态。
### 文件删除证据
删除前在 ReelShortWeb 全仓检索：
```text
[src/assets/imgs/logo.png]
[src/assets/imgs/avatar.jpg]
[public/logo.png]
[public/favicon.ico]
[CustomMenuView]
（以上均无引用）
[RegisterForm]
src/views/Login/components/index.ts
src/views/Login/Login.vue
```
`RegisterForm` 的引用已在同一提交中先移除。ReelShortWeb 全仓及开发库均无
`CustomMenuView` 路由/菜单记录：
```text
$ psql -d fruitshorts -c "SELECT id, title, component FROM sys_menu WHERE component ILIKE '%CustomMenu%';"
id | title | component
----+-------+-----------
(0 rows)
```
最终删除：
- `public/favicon.ico`
- `public/logo.png`
- `src/assets/imgs/logo.png`
- `src/assets/imgs/avatar.jpg`
- `src/views/permission/CustomMenuView.vue`
- `src/views/Login/components/RegisterForm.vue`
- `mock/`
### 品牌与本地图标
- `brand-mark.png` 复制到 `public/brand-mark.png`，favicon 和首屏 loading 均改用它。
- 首屏背景改为 `#100C0A`，标题浅色，loading mark 使用 12px 圆角。
- 删除 `public/favicon.ico`、`public/logo.png`。
- 修正侧边栏品牌图任意值类未生成的问题，展开/收起均为 38px、圆角 12px。
- 在线图标关闭后，UnoCSS 的运行时动态类不会自动收集；已把 `AppIcons`
全量加入 safelist，并显式加载本地
`@iconify/json/json/material-symbols.json`。
品牌文件校验：
```text
public/brand-mark.png
src/assets/imgs/brand-mark.png
76e01df1fa0ec94ca59842ea9e15f8084ae6532290ee874a88a3c5718159cea7
```
两个文件 SHA-256 一致。
### Mock 与 env
```text
.env.base VITE_USE_MOCK=false VITE_USE_ONLINE_ICON=false
.env.dev VITE_USE_MOCK=false VITE_USE_ONLINE_ICON=false
.env.pro VITE_USE_MOCK=false VITE_USE_ONLINE_ICON=false
.env.test VITE_USE_MOCK=false VITE_USE_ONLINE_ICON=false
```
已删除 `mock/`、`viteMockServe`、`mockPath`、生产 mock 注入和
`getTestRoleApi` 的 `/mock/role/list2` 分支；`tsconfig.json` 不再包含 mock。
`package.json` 移除 `@element-plus/icons-vue`、`@faker-js/faker`、
`vite-plugin-mock` 三个不再直接使用的依赖。
### 最终扫描
```text
old-prefix=0
el-icon=0
element-plus-icons=0
logo-png=0
mock-build-code=0
mock-directory=absent
```
`src/constants/icons.ts` 的旧名兼容映射按要求保留，未计入 old-prefix。
生产产物：
```text
dark-mode-rounded=1
translate-rounded=1
dashboard-rounded=1
video-library-rounded=1
group-rounded=1
settings-rounded=1
dist-pro/brand-mark.png
```
### 门禁
```text
$ pnpm lint:eslint
> fruitshorts-admin@1.0.0 lint:eslint
> eslint --fix --ext .js,.ts,.vue ./src
```
```text
$ pnpm build:pro
> fruitshorts-admin@1.0.0 build:pro
> VITE_CJS_IGNORE_WARNING=1 vite build --mode pro
[warn] Circular chunk: element-plus -> vue-chunks -> element-plus.
Build successful. Please see dist-pro directory
```
### 浏览器自查
- 登录 hero 只剩 kicker + 标题，无说明段落和三个标签。
- favicon 为 `/brand-mark.png`；首屏 loading 为 `/brand-mark.png`，
背景 `#100C0A`。
- `/brand-mark.png` 返回 `image/png`；旧 `/logo.png` 不再作为图片存在。
- 登录后菜单、顶栏、短剧管理工具栏全部使用离线 Material Symbols Rounded。
- 短剧管理页可见图标 22 个，空白 0 个；图标 mask 均有效。
- 侧边栏展开/收起品牌图均为 38×38，与登录页一致。
- 浏览器控制台 error 0 条，无 mock 或旧资源错误。
### 提交
```text
8aa84a3 docs(plans): 增加 K22.1 后台收尾计划
ada741f style(web): 精简登录品牌与注册入口
8797048 chore(web): 清理 mock 与旧品牌资源
e5c5101 chore(web): 合并 K22.1 后台收尾
```
功能提交与合并提交 author/committer 均为
`Zhou Weidong <502333560@qq.com>`。
## K23 后台视觉深化
### 主色
```text
--el-color-primary: #c4322a
--el-color-primary-light-3: #d3615b
--el-color-primary-light-5: #e19995
--el-color-primary-light-7: #f0c2c0
--el-color-primary-light-8: #f5d9d8
--el-color-primary-light-9: #faeeed
--el-color-primary-dark-2: #9d2822
```
旧用户持久化的 `#409eff` 在 store 恢复时迁移为 `#c4322a`。默认蓝扫描：
```text
$ rg '#409eff|#79bbff|#a0cfff|#c6e2ff|#d9ecff|#ecf5ff|#337ecc|rgba?\(64[ ,]+158[ ,]+255' src
（无输出）
```
### 二级菜单图标为空
`data.sql` 与 `data-phase1.sql` 均加入：
```sql
UPDATE sys_menu SET icon = '' WHERE type = 'MENU';
```
```text
type | total | empty_icon | with_icon
---------+-------+------------+-----------
CATALOG | 10 | 0 | 10
MENU | 23 | 23 | 0
parents=9 parentMissingIcon=0
children=19 childWithIcon=0
```
菜单管理仅在 `type='CATALOG'` 时显示图标选择，保存 MENU 时强制 icon 为空。
渲染层对嵌套项强制不输出 AppIcon，历史脏值也不保留图标空位。
### 对齐实测
```text
1024px: parent text left=42px, row=44px; child text left=42px, row=40px, icon=0
375px: parent text left=42px, row=44px; child text left=42px, row=40px, icon=0
popper: child row=40px, icon=0
```
浅色选中为浅主色底 + 主色文字；暗色选中为深主色底 + 白字，
暗色实测对比度 8.73:1。
### 短剧编辑弹窗
- 宽 680px，三区块，内容滚动、底部固定；375px 下宽 345px 且无横向溢出。
- 数字输入固定 180px，控件位于右侧；1024/375 实测均为 180px。
- 封面 96×128 预览、basename、状态 chip、更换/移除、查看原图、进度遮罩和错误提示。
- 删除原始 URL 输入框。
- txt 实测提示“封面仅支持 JPG、PNG 或 WebP 格式”；限制 5MB。
- 空名称保存显示字段错误“请输入短剧名称”；类型必选。
- 保存/上传中按钮禁用，关闭被拦截。
### 锁屏弹窗
- 宽 440px，高度 360px；375px 下宽 359px。
- 头部底边线 0px，关闭图标距右边缘 22px。
- 增加“输入密码解锁当前会话”；密码框回车可锁定，取消可关闭。
- 取消/锁定按钮均为 96×36px。
- 删除 `console.log('set: ', val)`。
### 门禁
```text
$ pnpm lint:eslint
> eslint --fix --ext .js,.ts,.vue ./src
$ pnpm build:pro
[warn] Circular chunk: element-plus -> vue-chunks -> element-plus.
Build successful. Please see dist-pro directory
```
浏览器自查：1024/375、明暗主题通过；控制台 error 0；无资源 404。
### 提交
```text
5356f24 docs(plans): 增加 K23 后台视觉深化计划
91bbfd5 docs(plans): 更正 K23 子菜单图标口径
ba90bf9 style(web): 统一辣椒红主色与菜单层级
805d7dd feat(web): 重做短剧编辑弹窗
898e439 fix(web): 优化锁屏弹窗布局与交互
ee3bb1c chore(web): 合并 K23 后台视觉深化
b400e36 fix(sql): 清空二级菜单图标
```
功能提交与合并提交 author/committer 均为
`Zhou Weidong <502333560@qq.com>`。
### 用户浏览器验收
1. 登录后检查按钮、链接、焦点环、标签和选中菜单：均应为辣椒红，无 Element 蓝。
2. 展开内容管理/后台管理：一级项有图标，二级项只有文字，父子文字左边缘同线。
3. 收起侧栏打开 popper：二级项无图标、行高 40px。
4. 编辑短剧：检查三区块、固定数字框、封面预览与“查看原图”，不再出现原始 URL 输入。
5. 上传非法格式或超过 5MB 图片：弹窗内显示错误且原图不变。
6. 打开锁屏：标题/说明清晰，可取消，回车可锁定。
7. 切换明暗主题并缩至 375px：布局不溢出，暗色选中态白字清晰。
- 2026-10-19 K23 菜单对齐补丁：一级 padding-left=16px、左侧 margin=0，二级 margin-left=42px；1024 实测父子文字 left 均为 42px，Web 提交 `40fbd6e`，合并 `fe1ae95`，`pnpm build:pro` 通过。
Reference in new issue View Git Blame Copy Permalink