Repository navigation
v3.6.6
2026-09-11 — v3.6.6 用电计量「取消登记」改为软删除(回收站),重新登记自动沿用历史数据
✨ entities_dates(多实体有数据日期)支持指定 年/月/日
现在该接口可使用:全部时间 / 时间段 / 指定日 / 指定月 / 指定年。
验证:6 项可见性用例 + 5 种时间模式 URL 生成全部通过,例如:
[all ] ?type=entities_dates&key=K&group=count
[range] ?type=entities_dates&key=K&start=2026-09-01&end=2026-09-30&group=count
[date ] ?type=entities_dates&key=K&date=2026-09-11&group=count
[year ] ?type=entities_dates&key=K&year=2026&group=count
[month] ?type=entities_dates&key=K&month=2026-09&group=count
✨ entities_dates(多实体有数据日期)新增 2 种分组方式
「分组方式」由原来的 2 种扩展为 4 种(group 参数支持语义化取值,同时兼容旧的 0/1):
| group | 说明 | 新增字段 |
|---|---|---|
all(默认,兼容 0) |
合并返回:去重日期总表 + 每实体日期 | all_count/all_dates/entities[] |
entity(兼容 1) |
按实体分组 | entities[] |
count ⭐ |
按日期数量返回:把"当天有数据的实体数"相同的日期聚成一组 | date_counts{date:实体数}、count_groups[{date_count, date_total, dates[]}] |
both ⭐ |
按日期数量 + 实体返回:在 count 基础上,每组再带出当天具体实体 |
每组 details[{date, entity_count, entities[]}] 与 entities[{entity_id, name, date_count}](去重,按出现天数降序);顶层同时保留 entities[] |
simple ⭐ |
极简返回:直接给扁平数组,开箱即用 | date_count(有数据的天数)、list:[{date, count}](count = 当天有数据的实体数,日期倒序) |
simple 示例(最省事的形态,无需再遍历对象):
{ "group": "simple", "date_count": 4,
"list": [ { "date": "2026-09-05", "count": 2 },
{ "date": "2026-09-03", "count": 1 },
{ "date": "2026-09-02", "count": 2 },
{ "date": "2026-09-01", "count": 3 } ] }🔧 精简:device_usage_detail 移除冗余的 columns 字段
full=1 时响应里的 columns 数组(列出 20 个列名)属冗余信息 —— 记录本身已包含全部字段,
调用方遍历首条记录即可得知可用键名。已移除 columns 输出,同时删掉随之无用的
PRAGMA table_info(...) 查询(少一次 DB 往返)与 cols 变量。
响应结构变化(仅去掉一个键,其余不变):
{ full, range, entity_count, total, returned, limit, offset, summary, records[] }
✨ device_usage_detail 新增 summary 合计节点
多实体明细接口新增 summary 节点,含全局总计与每实体合计:
"summary": {
"totals": { "count": 6, "duration_hour": 10.0, "energy_kwh": 3.4,
"entity_count": 2, "running_count": 1 },
"entities": [
{ "entity_id": "switch.ac", "name": "空调", "room": "客厅",
"count": 4, "duration_hour": 8.0, "energy_kwh": 3.0, "running_count": 1 },
{ "entity_id": "switch.light", "name": "灯", "room": "卧室",
"count": 2, "duration_hour": 2.0, "energy_kwh": 0.4, "running_count": 0 }
]
}🐛 修复:多维度聚合的「时间模式」UI 不显示(再次踩中跨作用域变量)
✨ 多实体明细同样支持「全部/时间段/指定日/指定月/指定年」时间模式
- 下拉选项文案更新为「📋 多实体明细(不聚合,全部/时间段/指定日/指定月/指定年,支持分页)」
✨ 多维度聚合(用时/用电、用电量)新增「指定日/指定月/指定年」时间模式
- 多维度聚合模式下新增 「时间模式」下拉:
全部时间/时间段/指定日/指定月/指定年 - 按模式联动显示输入:
- 时间段 → 开始/结束日期
- 指定日 → 日期选择器
- 指定月 → 年 + 月(月支持只填
9、或配年自动补零为2026-09) - 指定年 → 年
- 全部时间 → 不传任何时间参数
multiTimeQuery()统一生成时间参数片段;onMultiTimeModeChange()负责 UI 联动- 兼容:非聚合模式仍显示原有的开始/结束日期,行为不变
参数优先级(沿用 _usage_range_params):start/end > date > month > year;全不传 = 全部时间。
✨ device_usage_detail 新增 full=1:返回全部字段
多实体明细接口增加 full 参数(API 工具中为**「返回详细数据(全部字段)」复选框,默认勾选**)。
full |
返回 |
|---|---|
不传 / 0 |
精简字段(原行为,结构未变):entity_id/name/room/on_time/off_time/duration_hour/energy_kwh/running |
1 |
device_history 全部列 + 计算字段:id、entity_id、name、on_time、off_time、on_power、off_power、energy_consumed、duration(秒)、cross_day、room、state_attr(已解析为 JSON 数组)、now_kwh、on_user、off_user、on_snapshot、off_snapshot、power_entity、power_rating、duration_hour、energy_kwh、running;并附 columns 字段列出可用列名 |
✨ 新增 4 个设备类接口(device_history 多实体查询族)
| 接口 | 用途 | 关键参数 |
|---|---|---|
/query?type=device_usage_detail |
① 明细(不聚合) | entities、start/end/date/month/year、limit/offset |
/query?type=device_usage_total |
② 合计(年/月/日/全部) | entities、scope=all|year|month|date + year/month/date |
/query?type=device_usage_history |
③ 历史同期(历史今日/历史本月) | entities、scope=today|month |
/query?type=device_usage_avg |
④ 平均指标 | entities、start/end/date/month/year(默认全部时间) |
① 明细:每条记录一行,按 on_time 倒序;energy_kwh 无来源为 null;返回 total/returned 便于分页。
② 合计:每实体一行 + 全局 totals;scope 宽容写法(month 支持 9(配 year)/09/2026-09)。
③ 历史同期:scope=today 取往年同月同日、scope=month 取往年同月(均排除今年),另附 current(今年同期)与 by_year 逐年合计,便于同比。
④ 平均:avg_daily_count 平均每日次数(次数/有数据天数)、avg_daily_duration_hour 平均每日时长、avg_per_count_hour 平均每次时长;全局按加权计算(总时长/总次数、总次数/天数并集),非各实体简单平均。
口径统一:四个接口与既有 device_history 系列共用 _usage_range_params / _row_running_usage,
运行中记录一律按「当前时间 − on_time」计时、无用电来源则 energy_kwh = null,避免同一设备在不同接口数值打架。
API 工具(db_viewer):设备类分组新增上述 4 项;
新增「统计范围」下拉(自动切换 全部/年/月/日 或 历史今日/历史本月)与「条数上限/偏移」分页输入。
✨ 新增接口:/query?type=device_usage_multi(设备用时/用电多实体 × 多维度聚合)
参数(与 power_energy_multi 完全对齐):
entities(逗号分隔,空=全部)、bucket=day|month|year、view=entity|date、
start/end/date/month/year(优先级 start/end > date > month > year,全不传 = 全部时间)、devices=0 可省明细。
指标(沿用 device_history 系列既有口径):
| 字段 | 说明 |
|---|---|
count |
开启次数 |
duration_hour |
时长(小时)。运行中记录按「当前时间 − on_time」计入 |
energy_kwh |
用电量。已关闭取 energy_consumed;运行中 ① now_kwh − on_power ② 固定功率/1000×小时 ③ 无来源 → null |
running |
该时间桶内是否存在运行中的记录 |
返回结构:与 power_energy_multi 同形(view=entity → entities[].series[];view=date → dates[].devices[]),
另带 room(来自 entity_configs)。排序:entity 视图按 duration_hour 降序,date 视图时间倒序 + 桶内按时长降序。
语义修正:view=date 的 totals.device_count 表示该时间桶内出现过的设备数(entity_count 语义在桶维度下不成立,故改用 device_count 并保留 entity_count 于顶层 totals)。
API 工具(db_viewer):设备类分组新增 📊 多实体×多维度聚合(用时/用电,年/月/日,按实体或按时间),
复用同一套表单区(下拉文案随模式切换为「次数/时长/用电」)。
✨ 新增接口:/query?type=power_energy_multi(用电量多实体 × 多维度聚合)
| 参数 | 说明 |
|---|---|
entities |
多个实体,逗号分隔(entity_id 亦可,空 = 全部实体) |
bucket |
聚合维度:day(默认)/ month / year |
view |
返回结构:entity(默认,实体→时间桶)/ date(时间桶→实体) |
start / end |
日期区间,可单边 |
date / month / year |
指定某日 / 某月 / 某年 |
devices |
view=date 时是否返回明细,0 关闭(默认 1) |
时间过滤优先级:start/end > date > month > year;全不传 = 全部时间。
返回结构:
view=entity(按实体):
{ view, bucket, range:{start,end,date,month,year,label},
entity_count, totals:{kwh, day_count, entity_count},
entities:[{ entity_id, device_name, room, id_slug, daily_entity_id,
totals:{kwh, day_count},
series:[{key, kwh, day_count}] }] } ← 按 kwh 降序
view=date(按时间):
{ view, bucket, range:{...}, entity_count,
totals:{kwh, day_count, bucket_count, entity_count},
dates:[{ key, totals:{kwh, day_count, entity_count}, device_count,
devices:[{entity_id, device_name, room, id_slug, daily_entity_id,
kwh, day_count}] }] } ← 时间倒序,实体按 kwh 降序
- 元信息(device_name / room / id_slug / daily_entity_id)LEFT JOIN
power_meter_configs,
配置缺失时回退日表自带值;device_name/room取该实体最新非空值 - 无数据时返回空数组结构(不报错)
API 工具(db_viewer):「⚡ 用电计量」分组新增 📊 多实体×多维度聚合(年/月/日,按实体或按时间),
复用「多实体 + 粒度 + 返回结构 + 时间段」表单区(下拉文案随模式切换),URL 形如:
/query?type=power_energy_multi&entities=a,b&bucket=month&view=entity&start=2026-01-01&end=2026-09-30
🐛 修复:回收站永远显示「加载中...」(两处前端缺陷)
🐛 修复:db_viewer 页面被浏览器缓存导致"前端改动不生效"
✨ 新增:孤儿电表识别(配置行已被旧版本物理删除的补救)
背景:旧版本的「取消登记」是物理 DELETE 配置行。若在此之前点过取消登记,power_meter_configs 里已无该行,回收站自然为空,且无法恢复配置 —— 但 power_energy_daily 的历史用电数据仍在。
根因:power_meter_configs.enabled 在部分历史库中被建为 TEXT 类型。archive_config 执行 SET enabled = 0 时写入的是字符串 '0',而 Python 侧 bool('0') 为 True,导致归档项被误判为"生效",archived 过滤后列表为空。
修复:
ensure_tables新增 enabled 列类型归一化迁移:检测列亲和性,若非INTEGER则重建表(RENAME→CREATE→INSERT SELECT→DROP)彻底修正存储类型;已是 INTEGER 的库走轻量UPDATE ... CASE归一化- 所有判定点(
load_configs/archive_config/restore_config/purge_all_archived)统一改用COALESCE(CAST(enabled AS TEXT),'1') IN ('0','false','no','')判归档,兼容任何脏值 - 新增
_is_enabled(row)宽容判定工具(True/1/'1'/'true'/'yes' → 生效;False/0/'0'/'false'/'no'/None → 归档) - 新增
load_archived_configs()供回收站列表使用
✨ 新增:回收站「一键还原」
- 后端
restore_all_archived()+POST action=restore_all:一次性还原回收站全部登记并重新注册日/月/年用电实体(DB 翻转在 executor,实体注册回事件循环) - 前端回收站顶部新增 ♻️ 一键还原全部(N) 按钮,行内保留单条「♻ 恢复」
♻️ 背景与问题
旧实现中「取消登记」是物理删除 power_meter_configs 行(日表 power_energy_daily 保留)。由此带来两个问题:
- 重新登记同一功率实体时必须手动重填
id_slug,一旦填得不一样就会生成新的实体 ID,历史日用电数据"看不见了"(实际还在表里,但实体口径分叉); - 误删后无法恢复配置,只能凭记忆重建。
♻️ 新机制:软删除归档 + 回收站
PowerEnergyManager.remove_config()→ 新增archive_config():取消登记改为把配置行置为enabled=0(归档),配置行保留在库中load_configs()默认只返回enabled=1(生效中)的登记;采样、restore_all()、all_power统计均自动跳过归档项- 新增
find_config()/restore_config()/purge_config()/purge_all_archived() save_config()智能沿用:同一entity_id重新登记时保留原id、created_at,并补齐未显式传入的id_slug/device_name/room/daily_entity_idpower_energy_daily在任何路径下都不会被删除(含"彻底删除")
🔌 API 变更(/api/ha_data_store/power_energy)
| 方法 | 参数 | 说明 |
|---|---|---|
| GET | ?type=configs |
生效中的登记列表(不含归档) |
| GET | ?type=archived |
新增:回收站列表(已取消登记的配置) |
| GET | ?type=lookup&entity_id= |
新增:查单个登记(含已归档),供前端"带出原配置" |
| POST | action=create |
重新登记时自动沿用归档配置,返回消息提示「沿用原有配置与历史用电数据」;不再物理删除旧配置 |
| POST | action=delete |
语义改为取消登记(归档),日表数据保留 |
| POST | action=restore |
新增:从回收站恢复登记并重新注册三个用电实体 |
| POST | action=purge |
新增:彻底删除登记(物理删配置行,日表保留) |
| POST | action=purge_all |
新增:清空回收站 |
🖥 db_viewer 前端(⚡ 用电计量)
- 「已登记的功率计量」新增 编辑 按钮:一键把该登记的
entity_id/设备名/房间/ID 段/日用电实体/单位回填到登记表单 - 行内「删除」→ 「取消登记」;批量「删除选中」→ 「取消登记选中」;确认弹窗文案改为说明"移入回收站、历史数据保留"
- 登记表单:ID 段留空时自动沿用该实体的历史登记(含已取消登记的),无需手填也能避免实体 ID 分叉
- 新增 ♻️ 回收站 区块:列出已取消登记的配置(功率实体/设备名/房间/ID 段/日用电实体/取消时间)+ 恢复 / 彻底删除 / 清空回收站
- 切到「⚡ 用电计量」子页时自动刷新列表与回收站