laoyang
f020a671c0
用户 2026-10-18 六条（全部已在真机逐条验证）：
① 登录页「先不登录 / 离线使用」彻底删除
用户：「把那些不登录、看离线数据之类的提示全部去掉。以后就不再拥有这样的
功能了，把这些功能也全部删除。」
⇒ 两个按钮 + onSkip + allowSkip 参数 + Index 里的 skip 分支一起删净。
这是产品决定（不是隐藏）：该路径本身就是安全缺口，v58 上了整库加密后更要堵死。
② 标语统一为「一家人用岁月写成的一本书」
用户：「这也是我们"家书"这个名字的由来。所以你不要再乱换这个标语了，
只要是想出现标语或者副标题的地方，就用这样一句话。」
· 端上 FB_DEFAULT_SLOGAN 是唯一定义处（登录页副标题 + 抽屉回落都用它）；
· 抽屉左上角原来是家庭名，现在显示**标语**；
· 三层优先级（个人 slogan → 家庭 motto → 应用默认口号）**在服务端算**
（Family::slogan，与网页端首页 heroSlogan 同一套），/login 与 /me 都返回。
用户还说：「如果这个用户自己有标语……这个地方就是用户自己自定义的标语。」
真机实测：登录者杨永全自己写了「修身，齐家」⇒ 抽屉就显示他那句。
③ 首页新增「最近纪念日」（放在近期任务之后、往年的今天之前）
用户：「未来最近的三个纪念日，包括每个人的生日，以及手动填写的各个纪念日。
以倒计时形式展示：距离哪个纪念日还有多少天，距离谁谁谁的生日还有多少天。」
· /home.recent_days = Anniversary::upcoming(fam,pid,370) 取前 3 ——
取满一年：窗口太小会让"刚过完生日"的家庭一个都取不到，模块直接空着；
· 数据源 all() = 派生生日 + 自建纪念日，正好覆盖用户说的两样；
· 倒计时：0 天显示「就是今天」（写「还有 0 天」读起来像已经过了）。
④ 悬浮栏图标也上色（用户：「除了下面的汉字，上面图标的颜色也变成跟汉字一样的颜色」）
🔴🔴 真根因两层，都是"无报错失效"：
· 第一层：Image.fillColor() **只对 SVG 生效**，而本工程 30+ 图标**全是 PNG**
⇒ 全工程 24 处图标染色一直是空操作（文字走 fontColor 所以只有文字变了）。
· 第二层（真机才现形）：改用 colorFilter 后，矩阵写成了"系数乘 RGB"
(R' = R_原 × 系数) —— 对白色图标成立，但本工程图标是**纯黑**，
黑 × 任何系数 = 仍是黑 ⇒ 真机上图标像素依旧是 (0,0,0)。
⇒ 最终形态：`fbTint` 用 **alpha 当载体**（R' = (r/255) × A_原）：
系数是归一化约定（官方灰度示例系数和为 1，量纲确定）；
形状完全由原图 alpha 决定 ⇒ 黑/白图标都成立，描边抗锯齿自然过渡。
真机像素实测：日程项图标与文字同为 (176,120,64)≈#B0763A；
未选中项图标 (44,39,35) 深灰（不再是纯黑）。
⚠️ 全工程 24 处 fillColor 一并改掉；FbIconButton.tint 类型改成 string，
让"误传 Resource"变成编译错误而不是又一个静默失效。
⑤ 顶栏：真实头像 + 拉开按钮间距
用户：「右上角的头像应该是真实的……现在提醒的按钮距离头像的按钮太近了。」
· /home 给 me_avatar、/login 给 avatar_url（avatar_url() 按线上存储驱动拼好）；
· 三颗按钮（同步 / 铃铛 / 头像）统一用 FbMetric.gapTopActions = 8。
⑥ 日程四处
· 「日期下面有几个点」⇒ 月视图与周视图的圆点全部删除，
连 FbDot / dots() / count / dotColor 一起清（不留死代码）；
· 「农历全部都是初一」⇒ 真根因是端上 lunarOf() **硬编码 return '初一'**，
而服务端 lunarRange() 本来就每天给真实农历（title）⇒ 改取 title；
· 「列表这个视图，今天的数据缺一条」⇒ 服务端 /calendar 的 from/to **默认只给本月**，
而列表视图要显示 -7 ~ +60 天 ⇒ 端上显式传范围
（loadModule 新增 pathOverride 参数）；
· 「点击了某一天之后并不明显，应该把这一天的颜色变深，而今天用一个较浅的颜色」
⇒ 照 SyncCalendar：选中 = 深色实底白字、今天 = 浅色底。
真机实测：17 号（选中）bg=#FFB0763A，18 号（今天）bg=#FFF5F0EA。
另：FbKeyStore 补上一个真机抓到的 HUKS 坑 —— isKeyItemExist 在密钥不存在时
**会抛 12000011**（不是返回 false），首次运行必被误判成"本机不支持 HUKS"
⇒ 永久明文降级。改成把"不存在"当正常分支，且降级态每次启动重试一次
（把同一把 DEK 重新用 KEK 包起来，不换密钥以免重下全部附件）。
验证：hvigor BUILD SUCCESSFUL；_fb_arkts_guard.js 328/0；
_fb_v59ui_falsify.py 19 项注入 23/0；_fb_home_api.py 60/0；
六条已在真机逐条取像素/布局树确认。
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）。