laoyang
4a063114c5
用户 2026-10-19 第二批八条（原话逐条对应）： ═══ ⑨ P0：「现在还是不稳定，会退出，提示：这台设备已经被退出登录，请重新登录。」 真因**是我 v61 自己埋的**：「个人设置」页（`FbAccountPage`）里两处 `fbApi` 调用**取了 `token` 变量却没传进请求选项** ⇒ 没有 Authorization 头 ⇒ 服务端 401 ⇒ `FbHttp` 的全局回调 `unauthorizedCb` **清掉本地令牌 + 踢回登录页**。 而本页在 `aboutToAppear` 里就调它 ⇒ **点一下右上角头像，App 就退出登录**。 ⚠️ 我上一轮把同一现象归因成"残留旧令牌 / 设备会话被顶掉"（还去线上查了 `api_tokens` 表，一切正常）—— **那个结论是错的**，等于把 bug 归给了环境。 修法（两处调用 + **两道架构防线**，缺一不可）： ① 修两处调用，把 token 传进去； ② `fbApi` 内部：**本地有令牌、调用方又没传时自动补上** （大部分接口本来就要鉴权，补上是"纠正"；`/login`、`/ping` 带了也无害）； ③ **401 只在"确实带了令牌"时才算被踢** —— 否则"没带令牌"也会触发全局清令牌， 那正是这次事故的机制。 ═══ ④「你这个按钮到底是在弹框的右上角关闭，还是在下面关闭……全放在右上角。」 选**右上角 ✕**（底部已被 编辑/保存/删除 占满，再塞关闭会堆三四个按钮，分不清主操作）。 新增 `components/FbSheetClose.ets`： · `FbSheetClose` —— 32vp 圆形 ✕（热区 40+，小图标在手机上点不中）； · `FbSheetTitleBar` —— 左标题 + 右收尾（设置类给 `confirmText` 显示「完成」）。 9 个浮层全接；名册详情 / 日程详情 / 简要卡**底部不再有「关闭」**。 ⚠️ 浅色底走 `fbAlpha`，**不能拼 `+ '14'`** —— ArkUI 八位色是 `#AARRGGBB` （本项目曾因写 `#00000066` 导致遮罩**从来没显示过**）。 ═══ ①「观影……弹出的框左上角有一条灰色的线，不知道是什么。」 那是浮层顶部的**抽屉把手**（36×4 的 `line2` 浅灰短线）。本意是"可下拉关掉"的提示， 但 ① 它落在左上角、旁边没有文字；② 这个浮层的关闭本来就不靠下拉。 ⇒ 用户认不出它 = 它没起作用，**删掉**（不改成居中 —— 那只是把灰线挪个位置）。 ═══ ②「然后这个观影人的头像并没有带进来。」 同看人的 `FbAvatar` **漏传 `imageUrl`** —— 服务端 `Movie::attendees()` 本来就 `SELECT p.avatar`、端上 `parseAttendees` 也解析进了 `a.avatar`， 纯粹是**渲染时忘了用它** ⇒ 有头像的人也退化成色块。 ⚠️ 与名册详情 2026-10-15 那个是同一个 bug（当时是 `FbPersonSheet` 漏传）。 ═══ ③「点击这个图片呢，不能左右滑动看所有的这个图片。」 全屏查看器原来**只有底部「上一张/下一张」文字按钮**。现在整张大图左右滑翻页。 ⚠️ 用 `.gesture(PanGesture(Horizontal))` 而不是 `SwipeGesture`： `SwipeGesture` 要"快速划动"才识别，在有滚动容器的页面容易被先吃掉 （日程页实测：`gesture`/`priorityGesture` 都不触发）。`PanGesture` 看**累计位移**。 ⚠️ 判定要求 `|dx| >= 40 && |dx| > |dy|`，否则竖划会被误判成翻页。 ═══ ⑤「影院管理……增加影院呢、修改影院呢、高级搜索、统计、年度报告，这些全部都应该补充进去。」 端上原来**只有一个只读列表**（连"新增"都没有）。补成四个页签： · **影院**：新增 / 修改 / 删除（服务端 CRUD 早就有，端上一直没接）+ 删除二次确认； · **统计**：总览（看过/影院/人数/人次）+ 按影院/按年/按月的条形图； · **搜索**：片名 / 影院 / 起止日期（条件全空时不查，与网页 `hasCond` 同行为）； · **年报**：按年切换（第一场/最后一场、最常去的影院、一起看最多的人、每月分布）。 ⚠️ **统计/年报必须联网**（`/movies/stats|report`）：口径要与网页**完全一致** （同一份 `MovieStats`）。本地库算出来的是"已同步的那部分"， 少同步一次就少一部 ⇒ 用户会发现"网页 124 部、App 121 部"。 ⇒ 断网时明说"需要联网"，而不是给一个偏低的数字。 ⚠️ 影院写操作后**立刻回写本地库**（`refreshCinemas`），否则刚建的那家要等下次同步 才出现，看着像失败；并用 `INSERT OR REPLACE` 而非"清空再插" （中途失败会留下一个空表 = 用户的影院列表整个消失）。 ═══ ⑥「名册搜索，搜索后，下面有一个白色的框，什么内容都没有，删除。」 那是列表**末尾给悬浮栏留高度的占位块**（`height(FB_DOCK_RESERVE)`）， 底色是 `FbColors.surface`（**白**）而列表容器是 `paper`（**米**）—— 列表内容一短（搜索只剩一两条）它就露出来，看着像"什么都没有的白框"。 ⇒ 改底色与列表同色。**不能删**：删了最后一张卡片会被悬浮栏压住。 ═══ ⑦「如果一个人没头像，在列表是有一个文字的头像的，那么点击后弹框，也应该有。」 `FbAvatar` 原来是 `if/else`：有 `imageUrl` 就**只画 Image**， 而图片**加载失败时 `Image` 什么都不显示**（只露出纯色底）⇒ 看着是个光板。 （`alt()` 只在**加载中**起作用，失败后是空白。） ⇒ 改成**叠加**：底色 + 文字头像**常驻**，图片有就叠在上面 （加载成功即盖住文字，失败则自动露出文字头像）。 ⚠️ 之前注释说"图层叠会错位"——那是因为当时想靠 Image 的 intrinsic size 撑尺寸； 现在两层都显式给 `dia`，尺寸来源唯一，不存在错位。 ═══ ⑧「现在名册的列表太空了，应该显示更多内容，例如工作单位、职务。」 列表卡片加一行「单位｜职务」（独立成行，避免与标签/生日挤）。 ⚠️ 用 `persons.org` / `persons.title` 而**不是** `person_jobs`： 列表读的是**本地库**，而本地库只存 `persons` 那一行 （`person_jobs` 是一对多，端上没同步那张表）⇒ 服务端加了字段也到不了列表。 线上实测 801 人里 192 人有单位、48 人有职务，列表立刻有内容。 验证： · 编译 BUILD SUCCESSFUL · ArkTS 守卫 536/0（新增整组 groupV62，含 P0 两道防线） · 反向验证 51/0（新增 13 条注入，逐条确认能变红） · Schema 列守卫 12/0 · **真机 22/0**（6 组，含照片横滑 `1/5 → 2/5`、四个页签、点头像不被踢）
FamilyBook_harmonyos · 家书鸿蒙客户端
家书（FamilyBook）的 HarmonyOS 客户端。 服务端是那套「自托管的家庭生活系统」，这个仓库是它的手机 / 平板端。
把一个家的「人」「日子」「去过的地方、看过的电影」收进同一本书里。
当前状态
界面框架阶段（v0.1.0） —— 骨架与全部模块页面已就位，数据全部是演示数据。 服务端还没有客户端用的接口，所以这一轮只做「长什么样」，不做任何读写。
| 已完成 | 说明 |
|---|---|
| 工程骨架 | Stage 模型 + ArkTS / ArkUI，targetSdk 26.0.0 / compatibleSdk 6.1.1(24) |
| 沉浸式 | 照本机 SyncCalendar 的方案：系统栏全透明 + 根容器 expandSafeArea，通知栏与页面完全同色 |
| 左侧抽屉 | 宽屏常驻侧栏 / 窄屏滑出层，两套形态同一组件 |
| 12 个模块页面 | 首页、名册、观影、旅程、日程、资源、任务、纪念日、财务、读书、笔记（+ 家谱） |
| 附加页面 | 通知消息、个人设置 |
| 主题体系 | 宣纸米 / 砖红配色，深浅色两套资源，深浅自动跟随系统 |
| 模块主题色 | 与 Web 端 Module::PRESET_COLORS 同一套 12 色预设 |
| 编译验证 | hvigorw assembleHap 0 error / 0 warning |
| 真机验证 | 装机成功；15 个页面逐个点开、断言渲染内容，15/15 通过 |
| 待办（下一轮） | 说明 |
|---|---|
| 接口对接 | 服务端需要提供客户端用的 JSON 接口（登录、各模块列表与详情） |
| 登录态 | 会话持久化、令牌刷新、启动时的登录门禁 |
| 交互实现 | 新建 / 编辑 / 删除、搜索、筛选、拖拽排序 |
| 日程周/天视图 | 按半小时定位的时间轴 + 手势（本轮只做了月视图） |
| 附件能力 | 上传、图片/视频预览、裁剪 |
| 财务折线图 | 净资产与各账目的盘点变化曲线 |
与 Web 端的取舍
数据看 Web 端，排版按手机重做 —— 不照搬电脑端版面。
模块
不做「导航」模块（Web 端有）。用户原话：「导航是专门为电脑端开发的，都是网站，
主要用在浏览器的主页，所以不需要」。手机上每个网站都有 App，收藏夹没有使用场景。
⇒ 本工程的模块清单与 Web 端 Module::LIST 有意不等，别"顺手补回去"。
「家谱」不在抽屉里（与 Web 端一致）：它默认不上导航条（用户说过 「不需要每天都查看家谱」），走「名册 → 家谱」的分段切换进入。
版面
| 模块 | Web 端 | 鸿蒙端 | 为什么 |
|---|---|---|---|
| 首页 | hero 招牌 + 信息面板 + 日程/任务并排 + 我的家人 + 未来七天 + 模块卡 | 去掉 hero；信息面板作无卡片的页面头部；其余保持顺序上下堆叠 | hero 只重复信息面板已有的信息（家庭名 × 问候），手机首屏高度宝贵 |
| 观影 | 瀑布流海报墙 | 两列定尺寸网格 | 瀑布流列宽随图高浮动，手机上很难扫 |
| 任务 | 多列看板（拖动改状态） | 按状态分组的三段列表 | 手机宽度放不下多列；用户关心的是"做到哪一步" |
| 笔记 | 定尺寸卡片网格 | 两列定高卡片网格 | 与 Web 端一致（用户要求过"块大小要确定"） |
| 家谱 | HTML 折线树 | 「以我为中心的圈层」（直系 / 其他亲属） | 折线树在窄屏排不下 |
| 财务 | 概览 + 折线图 + 账目表 | 概览（图占位）+ 按类别分组的账目 | 折线图需要图表能力，留到第二轮 |
目录结构
entry/src/main/ets/
entryability/EntryAbility.ets 应用入口：主题跟随、系统栏配色
entrybackupability/ 备份扩展
common/
Theme.ets 设计令牌（颜色 / 间距 / 字号）+ 模块调色板
Store.ets 全局状态（V2：@ObservedV2 + @Trace）
model/
Modules.ets 模块注册中心（对应 Web 端 App\Module）
Types.ets 全部数据类型（对应各模板渲染的字段）
DemoData.ets 演示数据（接上接口后可整个删除）
components/
Widgets.ets 共享展示件（头像 / 标签 / 空态 / 圆点…）
Drawer.ets 左侧抽屉 + 骨架（并排 / 浮层两形态）
TopBar.ets 顶栏
pages/
Index.ets 主界面：模块分发
home/ movies/ trips/ calendar/ tasks/ people/
resources/ days/ ledger/ books/ misc/ settings/
设计说明
沉浸式（三件套，缺一不可）
参考本机另一个应用 SyncCalendar（用户指定）的做法：
- 系统栏涂成全透明 ——
statusBarColor: '#00000000'、navigationBarColor: '#00000000'； - 窗口底色 = 页面底色 ——
win.setWindowBackgroundColor(pageBg)，供透明系统栏透出； - 紧邻系统栏的元素不设自己的背景色 —— 顶栏不能有
backgroundColor， 让它透出根容器底色；根容器再expandSafeArea([SYSTEM], [TOP, BOTTOM])把背景铺到状态栏区域。
原理：透明系统栏透出的是窗口底色，而顶栏也透出同一个底色 ⇒ 天然同色、 「通知栏与上方完全融为一体」。内容仍在安全区内，不需要手算状态栏高度。
⚠️ 常见的两个坑（都踩过）：
- 调
setWindowLayoutFullScreen(true)后子组件会钻到状态栏底下，页面得自己让位， 极易算错（曾出现顶部重复避让 156px）； - 给状态栏或顶栏写死颜色必然与相邻层割裂（曾出现「米色状态栏 + 白色顶栏」的拼接感）。
验证方式：逐行像素采样（_tooling/familybook_immersion_check.py）。
判据是「状态栏区颜色 == 顶栏区颜色」，用数字裁定而不是目测 ——
最终实测 y=0..271 全为 #F7F3EA（纸色），达标。
Web 端顶栏是一排横向模块入口，最多放 12 个模块 —— 手机宽度下必然溢出。 改成左侧抽屉后，竖向排列不受数量限制，还能顺带放下「模块说明 + 主题色」 这层信息，一眼看清每个模块是干什么的。
抽屉有两套形态，由窗口短边决定（≥ 600vp 为宽屏）：
- 宽屏（平板 / 折叠屏展开 / 横屏手机）：抽屉常驻，与内容并排；
- 窄屏：内容铺满，抽屉从左侧滑出，点遮罩或选中模块即收起。
判据用「短边」而不是「宽度」—— 短边在旋转时不变，所以比例接近 1:1 的设备 横竖屏布局保持一致。
为什么是抽屉
Web 端顶栏是一排横向模块入口，最多放 12 个模块 —— 手机宽度下必然溢出。 改成左侧抽屉后，竖向排列不受数量限制，还能顺带放下「模块说明 + 主题色」 这层信息，一眼看清每个模块是干什么的。
抽屉有两套形态，由窗口短边决定（≥ 600vp 为宽屏）：
- 宽屏（平板 / 折叠屏展开 / 横屏手机）：抽屉常驻，与内容并排；
- 窄屏：内容铺满，抽屉从左侧滑出，点遮罩或选中模块即收起。
判据用「短边」而不是「宽度」—— 短边在旋转时不变，所以比例接近 1:1 的设备 横竖屏布局保持一致。
模块注册中心
模块清单只有一个来源：model/Modules.ets 的 FB_MODULES，
与 Web 端 app/Module.php 的 Module::LIST 一一对应（key 必须等于路由名）。
加一个模块只改那一处 —— 抽屉、设置页的显隐开关、主题色选择全部自动出现。 这是 Web 端踩过的坑（漏改一处就「有页面但导航里找不到入口」），端上照搬这套结构。
主题色
每个模块一个主题色，三档（按钮底 / hover / 文字色）由主色按 HSL 压明度算出来，
保证三档永远同色系。算法与 Web 端 Module::cssVars() 共用同一套公式。
预设色板 FB_PRESET_COLORS 也与 Web 端 Module::PRESET_COLORS 逐值一致 ——
否则同一个人在手机和电脑上选出的「观影紫」会是两种紫。
编译期约束（踩过的坑）
| 坑 | 处理 |
|---|---|
Circle().fill() 是 API 26 才有的重载 |
compatibleSdk 是 24，改用「方块 + 圆角」画圆（components/Widgets.ets::FbDot），零版本风险 |
setWindowBackgroundColor 对 phone/tablet 不可用 |
去掉，页面自身已用同色铺满整屏 |
window.getLastWindow() 只有异步版 |
由 EntryAbility 用 getMainWindowSync() 取一次存进 AppStorage，页面侧同步读 |
跨文件顶层名冲突（arkts-no-decl-merging） |
所有导出名统一加 Fb 前缀 |
Button('label') { ... } 报 10905202 |
一律用 Button() { Row() { ... } } |
@Param 类型写成 string 导致传 Resource 报错 |
颜色类入参统一声明 ResourceColor |
| 嵌套目录下 import 相对路径层级 | 页面在 pages/<模块>/，公共件在 components/、model/，相对路径要多退一级 |
构建
需要 HarmonyOS SDK（DevEco Studio 自带）。本机开发时：
export NODE_HOME="<DevEco>/tools/node"
export DEVECO_SDK_HOME="<DevEco>/sdk"
<DevEco>/tools/ohpm/bin/ohpm install --all
<DevEco>/tools/hvigor/bin/hvigorw assembleHap --mode module -p product=default
产物在 entry/build/default/outputs/default/entry-default-unsigned.hap。
local.properties 里写本机 SDK 路径，不入库（见 .gitignore）。