shishengliang
65904c8270
Preserve August hydrogen revision and September audit evidence; calculate interrupted vehicle history across all prior months. Record remaining carry-policy and layout-baseline discrepancies.
73 lines
5.2 KiB
Markdown
73 lines
5.2 KiB
Markdown
# 里程绩效：原型与 API 对接
|
||
|
||
## 页面与业务流程
|
||
|
||
月度核算展示本次批次的考核明细；异常核对定位缺少里程、来源冲突、交车区间重叠；详情按车牌和租赁记录追溯到每日来源及原始行。数据接入接收租赁区间和三类里程长表。规则中心明确参与车辆、有效期、测试候选、来源提供方优先级。API 对接页面展示真实接口状态与契约。
|
||
|
||
演示数据完全虚构。真实模式与演示模式不混用结果。当前只提供试算，不模拟已审批或已发放。
|
||
|
||
## 已接通的本机接口
|
||
|
||
前端相对路径 `/api`，开发代理转发 `http://127.0.0.1:8765` 并移除 `/api`。JSON 返回 UTF-8；错误体 `{ "error": "说明" }`。状态码 200/201 成功、400 请求错误、404 快照不存在、409 有异常禁止导出。
|
||
|
||
| 方法 | 路径 | 请求与结果 |
|
||
|---|---|---|
|
||
| GET | /health | 服务状态、引擎 version |
|
||
| POST | /imports/leases | 原始 xlsx 二进制；返回 id、raw_rows、accepted_rows、issues |
|
||
| POST | /imports/mileage?source=hydrogen&provider=guangzhou | 原始 xlsx；source 支持 hydrogen/tbox/gps，provider 需与规则对应 |
|
||
| GET | /imports/{id} | 标准化导入快照、行和错误 |
|
||
| POST | /assessments | 下方请求；返回 id/status/summary/issues |
|
||
| GET | /assessments/{id} | records、daily_trace、issues、excluded、inputs、engine_version |
|
||
| GET | /assessments/{id}/export.xlsx | ready 时导出业务考核源表；异常返回 409 |
|
||
|
||
```json
|
||
{
|
||
"lease_import_id": "导入返回的64位ID",
|
||
"mileage_import_ids": ["里程导入ID"],
|
||
"config": {
|
||
"month": "2026-08",
|
||
"test_plates": [],
|
||
"test_threshold_km": 50,
|
||
"source_priority": {
|
||
"hydrogen": ["guangzhou"],
|
||
"tbox": ["vehicle-platform"],
|
||
"gps": ["g7", "dongfang", "xinda", "guangan"]
|
||
},
|
||
"rules": [{
|
||
"plate": "DEMO-001", "target_id": 1,
|
||
"target_name": "交投40辆4.5T普货", "monthly_target_km": 3000,
|
||
"valid_from": "2026-08-01", "valid_to": "2026-08-31"
|
||
}]
|
||
}
|
||
}
|
||
```
|
||
|
||
文件最大 20 MB，解压后最大 200 MB，表头必须在前十行。里程表必填 `plate_number,date,mileage_km`（日里程，km）。租赁表字段：`vehicle_id,plate_number,contract_id,contract_code,project_name,customer_name,business_department_name,business_manager_name,delivery_vehicle_id,delivery_time,return_vehicle_task_id,return_time`。未还车可留空最后两项。里程空值不可当零；合法零必须保留。来源提供方顺序用于按日补缺，不能叠加多个 GPS 提供方。
|
||
|
||
ID 为内容哈希，同输入生成相同快照标识。调用方应保存 ID 并随批次保存输入、规则和引擎版本；重新补数生成新批次，不覆盖旧批次。
|
||
|
||
## 最新规则与旧 API 的明确差异
|
||
|
||
依据项目 8 月说明顶部的当前口径：非测试日有纯氢（含 0）取纯氢，无纯氢取仪表；测试日取 GPS；测试候选日无法判定且无纯氢时兜底 GPS。现有 API 则按区间选来源并对测试日清零，不能直接固化为正式规则。规则中心的 JSON 参数只能配置现有引擎支持项，不能靠改参数完成算法迁移。
|
||
|
||
最新四名离职人员为全部奖金剔除，不发放不转交。历史说明存在被覆盖的停发、转接口径，应采用带生效月份和批准记录的规则版本。结转、累计补发、历史有效奖励和归属分段需从 `calc_engine.py` 与最新计算入口抽离；不能以简单完成率乘奖金替代。
|
||
|
||
## 后续系统设计（建议契约，尚未实现）
|
||
|
||
建议实体：source_snapshot、lease_segment、daily_mileage、rule_version、assessment_batch、assessment_record、bonus_ledger、review_event。逐日依据关联来源行；奖金账本以车辆、负责人、政策有效期和所属月份为粒度，金额使用整数分或 Decimal。
|
||
|
||
建议新增接口：
|
||
|
||
- `POST /v1/sync-jobs`：按月份从车辆平台、租赁系统及 GPS 拉取快照，返回 job_id；通过 `GET /v1/jobs/{id}` 查询进度与失败原因。
|
||
- `GET/POST /v1/rule-versions`：草稿规则、版本、生效期和审批记录。
|
||
- `POST /v1/assessment-batches`：固定输入快照 ID、规则版本 ID、历史账本版本，异步执行；支持 Idempotency-Key。
|
||
- `GET /v1/assessment-batches/{id}/records`：分页与服务端筛选；详情包含分段和每日证据。
|
||
- `GET /v1/assessment-batches/{id}/bonus-ledger`：当月、结转、历史补发、累计补发及剔除依据。
|
||
- `POST /v1/assessment-batches/{id}/submit`、`/approve`、`/lock`：核算员提交、复核人审批、财务锁定。未解决异常禁止提交；输入变更后重建批次，锁定结果不可直接改写。
|
||
|
||
待对接系统提供：租赁区间接口、车辆唯一键、人员及归属变更接口、每日纯氢/仪表/GPS 接口、分页与增量游标、鉴权方法和限流规则。供应商密钥放服务端，不存前端。补数、重复记录、换牌、跨月交还车和跨月规则变更应有回归样本。
|
||
|
||
## 验收重点
|
||
|
||
真实零与空值区分；同日多源仅补缺；交还车及负责人切换不重不漏；测试日判定与所取来源可追溯；单条金额舍入后再汇总；历史奖励不被新政策追溯修改；异常阻止正式导出；同输入可复算；快照不可变。
|