docs(plans): 合并 K14 客户端文档回执

docs/plans/INBOX.md

@@ -20,7 +20,96 @@
 
 ---
 
-## [已处理·待用户验收] 2026-10-17 | K13 运行时服务器地址设置（仅 debug）
+## [已处理·待用户验收] 2026-10-17 | K14 客户端文档：README + 任务清单 + 文件说明
+
+**用户指令（2026-10-17）**：「现在更新客户端 readme 任务清单 及文件说明」。
+
+> 只改 `ReelShort` 仓库文档，不改代码、不改 specs、不改后端/Web。
+> 内容必须基于当前实际代码与已交付事实，**禁止编造**；不写任何密钥/账号。
+
+### 一、现状（实测）
+
+- `ReelShort/README.md` 仅 50 行，是原型阶段说明，已明显过时：
+  - 仍写“本地演示评论”“互动数据保存在本机”，实际 K3 已接后端评论/点赞/举报；
+  - 未提分类、通知、下载授权、克莱因蓝主题、印尼语默认、运行时服务器地址设置；
+  - 未写门禁命令、iOS SPM 兼容注意事项、USB 调试方式。
+- `ReelShort` 无 `docs/` 目录，没有任务清单与文件说明。
+- `lib` 现有 105 个 Dart 文件，目录：`core/{config,data/{models,remote,repositories,services},formatting,platform,theme,widgets}`、`l10n`、`pages/{auth,discover,downloads,drama_detail,favorites,home,interaction,mine,notices,player,watch_records}`。
+
+### 二、本批范围（3 份文档）
+
+#### K14-A 重写 `ReelShort/README.md`
+
+至少包含：
+
+1. 项目定位：面向印尼市场的短剧 App（Flutter）。
+2. 技术栈：Flutter 3.47 / Dart 3.13、Provider、dio、video_player、shared_preferences、flutter_localizations（en/zh/id）。
+3. 目录结构概览（core 三层 + pages + l10n + test）。
+4. 已接后端接口清单（按契约分组，**以代码实际调用为准**）：账号、首页/发现/分类/详情、播放、观看记录/收藏、下载授权 8 接口、互动（评论/点赞/举报）、公告。
+5. 运行方式：
+   - Android USB：`adb reverse tcp:8081 tcp:8081` + `flutter run -d <device> --dart-define=API_BASE_URL=http://127.0.0.1:8081`；
+   - iOS：`flutter run -d <udid> --dart-define=API_BASE_URL=http://<MacIP>:8081`；
+   - **debug 下可在「我的 → 设置 → 服务器地址」运行时修改**（K13），换网络不必重编。
+6. 环境注意：
+   - Xcode 16.2 / Swift 6.0.3 与 `shared_preferences_foundation 2.5.6` 的固定原因（2.6.0 需 Swift 6.1）；
+   - iOS SPM 报 `Missing package product` 时的恢复步骤（清 DerivedData、`flutter pub get`、`xcodebuild -resolvePackageDependencies`）；
+   - Android `libdartjni.so` 加载失败时卸载重装。
+7. 门禁命令：`dart analyze lib test`、`flutter test`、`flutter build apk --debug`；测试命名约定。
+8. 当前边界：下载不落盘/不续传/不离线播放；无搜索接口；通知无已读态。
+
+#### K14-B 新增 `ReelShort/docs/TASKS.md`
+
+表格形式，列：批次 / 范围 / 状态 / 关键提交或契约章节 / 备注。至少覆盖：
+
+- K1 详情+播放+进度+收藏；K2 分类/记录/收藏页/下载授权；K3 评论/点赞/举报/分享；K5 克莱因蓝主题+印尼语；K6 登录页+底部导航+震动；K7 轮播+站内通知；K8 登录页视觉；K9 首页网格；K10 空态；K11 3 列+全部首位；K12 去标题+空态重做；K13 运行时服务器地址。
+- 待办：K4 账号剩余（Google 登录需凭据）、B1 支付/金币、搜索（契约缺失）、下载落盘（另立批次）。
+- 状态以 `develop` 实际合并情况为准，不确定的标注「需核对」，不要编造提交号。
+
+#### K14-C 新增 `ReelShort/docs/FILES.md`
+
+- 目录树（到两级），每目录一句话职责。
+- 关键文件表：`lib/core/config/app_config.dart`、`server_endpoint`（如已实现）、`core/data/remote/*`、`repositories/*`、`services/*`、`core/theme/*`、`core/widgets/empty_state.dart`、`pages/*/`、`l10n/*.arb`。
+- `test/` 结构说明（按模块目录）。
+- 只写实际存在的文件；生成物（`*.g.dart`、`app_localizations*.dart`）标注为生成、勿手改。
+
+### 三、约束
+
+- 中文书写，简洁准确；不使用 AI 腔（“赋能/一站式/旨在”等）。
+- 不泄露任何密钥、账号、服务器凭据。
+- 只新增/修改 `README.md`、`docs/TASKS.md`、`docs/FILES.md`；不删既有内容以外的文件。
+- 提交作者与提交者统一 `Zhou Weidong <502333560@qq.com>`。
+
+### 四、门禁与 Git
+
+- 文档改动仍需 `dart analyze lib test` 与 `flutter test` 通过（确认未误改代码）。
+- 从干净 `develop` 拉 `docs/k14-client-docs`；完成后 `git merge --no-ff` 回 `develop` 并 push；不动 `main`。
+- 在 `FruitServer/docs/plans/PROGRESS.md` 追加「叙述 + 命令 + 原始输出 + 解读」，完成后停住写回执。
+
+### 五、K14 完成回执（2026-10-17）
+
+**结论**：客户端 README 已重写，并新增任务清单与文件说明。只改 ReelShort 的
+三份文档，未改代码、specs、后端或 Web。
+
+- 文档分支 `docs/k14-client-docs` 从 `f95325d` 完成并 `--no-ff` 合并；
+  主提交 `5a28845`，接口统计修正 `213c86e`，最终合并 `9fe62d1`，已推送
+  `f95325d..9fe62d1 develop`。
+- `README.md` 已覆盖印尼市场定位、Flutter 3.47.7/Dart 3.13.5 技术栈、
+  实际调用的 26 个 `/app/**` 路径（31 个方法级调用）、Android USB/iOS/运行时地址、iOS SPM、
+  shared_preferences 固定、Android libdartjni、门禁和当前边界。
+- 新增 `docs/TASKS.md`：K1-K13 状态表、K4/支付/搜索/下载落盘待办；
+  未写不确定提交号，未确认项标「需核对」。
+- 新增 `docs/FILES.md`：目录树、关键文件职责、test 结构和生成物说明。
+- 仓库 `.gitignore` 排除了 `/docs/`，本次仅对 TASKS/FILES 使用
+  `git add -f`，没有修改 `.gitignore`。
+- `dart analyze lib test` 零告警；`flutter test` 为
+  `00:20 +309 ~1: All tests passed!`；本轮仅文档，不需要 APK 构建。
+
+原始命令、输出与内容核对见 `docs/plans/PROGRESS.md`
+「30. K14 客户端文档」。
+
+---
+
+## [待处理] 2026-10-17 | K13 运行时服务器地址设置（仅 debug）
 
 **用户反馈（2026-10-17，已重复 3 次）**：每次 Codex 门禁构建出的 APK 不带 `--dart-define`，App 就回退到 `http://jiangdeMacBook-Air.local:8081`，真机不可用。
 

docs/plans/PROGRESS.md

@@ -2793,6 +2793,104 @@ b762289..f95325d  develop -> develop
 
 ---
 
+## 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 iOS 构建阻塞：固定 shared_preferences_foundation 2.5.6
 
 ### 25.1 现象与根因