This commit is contained in:
shishengliang
+22
-12
@@ -14,7 +14,7 @@
|
||||
|
||||
- 复用资产仓储 `MAIN_SQL`、`transformRow`、`isOperatingVehicle`、`isInventoryVehicle`。
|
||||
- 总数为未删除、未退出运营的车辆；运营为租赁/自营，库存为可运营/待运营；异动、待交车不另加。
|
||||
- 月末最后一天 `Asia/Shanghai` 17:00 为计划时点；只允许在 17:00:00（含）到 17:01:00（不含）内开始读取。
|
||||
- 每天 `Asia/Shanghai` 23:55 为计划时点，归属当天；只允许在 23:55:00（含）到 23:56:00（不含）内开始读取。每天独立保存完整逐车状态；月度展示月末当天、年度展示12月31日快照，不累加每日存量。
|
||||
- `captured_at` 是程序记录的实际开始读取时间，`scheduled_for` 是计划时点；两者不宣称完全相同。
|
||||
- 一致性读取可在窗口内开始后继续执行；持久化失败最多重试三次，始终使用同一份已取得数据，不重新读晚到的台账。
|
||||
- 当月在截止前显示实时点；年末前当年年度点显示实时点。截止后只能显示归档、归档中、失败或缺失。12 月快照直接用作年度年末点。
|
||||
@@ -33,9 +33,9 @@
|
||||
|
||||
## 存储
|
||||
|
||||
`bi_asset_history_settings` 保存首次实际启用时间。重复启用保留首次时间。
|
||||
`bi_asset_history_settings.enabled_at` 保留旧采集首次启用时间；`daily_enabled_at` 保存每日采集首次实际启用时间。重复启用保留首次时间，升级前的日期不会被标记为漏采。
|
||||
|
||||
`bi_asset_history_batches` 保存年月、口径版本、计划及实际时间、来源、状态、失败码、全量校验计数及导入追溯信息。年月与口径版本唯一。正式归档为 `COMPLETE`，失败为 `FAILED`，错过为 `MISSED`。
|
||||
`bi_asset_history_batches` 保存期间键、口径版本、计划及实际时间、来源、状态、失败码、全量校验计数及导入追溯信息。`period_key` 与口径版本唯一；新快照使用 YYYY-MM-DD，旧月度 YYYY-MM 键和明细原样保留。月度查询仅选月末日及旧月度记录；同月优先新日快照，但失败或缺失不会遮蔽旧 COMPLETE 归档。正式归档为 `COMPLETE`，失败为 `FAILED`，错过为 `MISSED`。
|
||||
|
||||
`bi_asset_history_vehicles` 保存车辆字符串 ID、原始运营/车辆状态、归档分类、公司、部门、负责人 ID 和冻结车辆 JSON。批次内车辆唯一；不以当前车辆表为外键。JSON 保留车牌、VIN、型号、品牌、业务归属等明细信息，排除无关的异动工作详情和待交车附件信息。
|
||||
|
||||
@@ -73,27 +73,37 @@ node --import tsx scripts/migrate-asset-history.ts --apply
|
||||
|
||||
如部分建表失败，修正原因后可重复执行；脚本使用 `CREATE TABLE IF NOT EXISTS`。新建空表不会伪造以前历史。
|
||||
|
||||
授权启用后，将服务进程环境变量设为 `ASSET_HISTORY_CAPTURE_ENABLED=1` 并按现有流程重启服务。调度器首次成功连接时记录 `enabled_at`，启用前的时点不会追补。如果在月末 17:00 之后才首次启用，即使仍处于该分钟，也从下一个月末开始采集。
|
||||
每日采集升级（2026-10-30）：先停止旧版采集服务，执行基础建表迁移（已有表不变），再审阅并执行一次增量迁移：
|
||||
|
||||
按本需求确认日期 2026-10-19，如果在 2026-10-31 17:00 前成功启用，首个计划时点为北京时间 **2026-10-31 17:00**；实际计划以数据库首次启用时间和服务时间计算，不硬编码。
|
||||
```sh
|
||||
node --import tsx scripts/migrate-asset-history.ts --daily
|
||||
node --import tsx scripts/migrate-asset-history.ts --daily --apply
|
||||
```
|
||||
|
||||
保持服务在计划时点在线。停止期间错过的 eligible 月份会在重启时记为 MISSED；已 FAILED 的记录保留诊断标记。记录到启用前没有归档，不能用重启时的实时数回填。日志前缀为 `[asset-history]`，包含年月及 captured/already-complete/locked/failed/missed 结果，不记录客户明细或连接凭据。
|
||||
增量迁移把 `period_month CHAR(7)` 改为 `period_key CHAR(10)`，原唯一索引继续约束期间键和版本；新增可空 `daily_enabled_at`。这是一次性 ALTER，不能重复执行。应在目标库完成迁移后启动新版服务并设置采集开关；旧版程序不能直接使用新字段名。迁移不启动采集，也不修改旧归档的计划/实际时间。当前页面仍提供月度和年度浏览，普通日期快照保存在数据库中。
|
||||
|
||||
建议仅让受控服务账号写快照表；源表仍只需读权限。多实例可启用同一数据库下的同一采集配置，命名锁和数据库唯一约束共同保证幂等。启用开关为进程级配置，`enabled_at` 是历史启用记录，不能仅根据该记录判断某个进程现在是否运行调度器。
|
||||
|
||||
授权启用后，将服务进程环境变量设为 `ASSET_HISTORY_CAPTURE_ENABLED=1` 并按现有流程重启服务。调度器首次成功连接时记录 `daily_enabled_at`，启用前的时点不会追补。如果在当天 23:55 之后才首次启用，即使仍处于该分钟，也从次日开始采集。
|
||||
|
||||
按每日采集需求确认日期 2026-10-30，如果在当天 23:55 前成功启用，首个计划时点为北京时间 **2026-10-30 23:55**；实际计划以每日采集首次启用时间和服务时间计算，不硬编码。
|
||||
|
||||
保持服务在计划时点在线。停止期间错过的 eligible 日期会在重启时记为 MISSED；已 FAILED 的记录保留诊断标记。记录到启用前没有归档，不能用重启时的实时数回填。日志前缀为 `[asset-history]`，包含日期及 captured/already-complete/locked/failed/missed 结果，不记录客户明细或连接凭据。
|
||||
|
||||
建议仅让受控服务账号写快照表；源表仍只需读权限。多实例可启用同一数据库下的同一采集配置，命名锁和数据库唯一约束共同保证幂等。启用开关为进程级配置，`daily_enabled_at` 是历史启用记录，不能仅根据该记录判断某个进程现在是否运行调度器。
|
||||
|
||||
管理员可用以下只读 SQL 检查，不通过普通用户接口暴露全量计数：
|
||||
|
||||
```sql
|
||||
SELECT enabled_at FROM bi_asset_history_settings WHERE id=1;
|
||||
SELECT period_month, scheduled_for, captured_at, completed_at,
|
||||
SELECT period_key, scheduled_for, captured_at, completed_at,
|
||||
definition_version, source, status, failure_code,
|
||||
total_count, operating_count, inventory_count
|
||||
FROM bi_asset_history_batches ORDER BY period_month DESC LIMIT 12;
|
||||
SELECT b.period_month, b.total_count, COUNT(v.vehicle_id) AS detail_count
|
||||
FROM bi_asset_history_batches ORDER BY period_key DESC LIMIT 31;
|
||||
SELECT b.period_key, b.total_count, COUNT(v.vehicle_id) AS detail_count
|
||||
FROM bi_asset_history_batches b
|
||||
LEFT JOIN bi_asset_history_vehicles v ON v.batch_id=b.id
|
||||
WHERE b.status='COMPLETE'
|
||||
GROUP BY b.id, b.period_month, b.total_count;
|
||||
GROUP BY b.id, b.period_key, b.total_count;
|
||||
```
|
||||
|
||||
## 回退
|
||||
@@ -108,7 +118,7 @@ GROUP BY b.id, b.period_month, b.total_count;
|
||||
|
||||
提供仅表头模板 `docs/asset-history-import-template.csv`。使用 UTF-8 CSV，每行一辆车，同一文件只允许一个年月、一个口径版本和一个统计时点。
|
||||
|
||||
必填字段：`period_month`、`scheduled_for`、`captured_at`、`definition_version`、`source_reference`、`vehicle_id`、`operation_status`。空缺车牌/VIN使用空值，不造车辆 ID。ID 均按文本读取。`scheduled_for` 必须是指定年月最后一天北京时间 17:00，`captured_at` 必须来自可信历史来源，不能把导入执行时间当作历史读取时间。
|
||||
必填字段：`period_month`、`scheduled_for`、`captured_at`、`definition_version`、`source_reference`、`vehicle_id`、`operation_status`。空缺车牌/VIN使用空值，不造车辆 ID。ID 均按文本读取。旧版月度导入契约的 `scheduled_for` 是指定年月最后一天北京时间 17:00（保留旧格式，不能作为每日自动采集规则），`captured_at` 必须来自可信历史来源，不能把导入执行时间当作历史读取时间。
|
||||
|
||||
其余字段见模板。部门、负责人、主体缺失须显式留空，不能用今日台账补齐；部门/个人权限因此可能看不到未归属的运营车辆，这是数据缺失而非自动扩大授权的理由。展示型号、品牌、原始车辆状态按历史来源保存；历史状态映射复用现有分类函数，不接受退出运营车辆或未知运营状态作为有效存量。归档分类由导入校验程序计算，不直接信任文件中的分类列。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user