{"openapi":"3.0.3","info":{"title":"SaaS 3.0 / 0.5 接口","version":"0.5.007-service.1","description":"Authenticated ASGI API. Access keys expire and are revocable; member permissions and optional store scope apply. Energy uses kWh and Beijing calendar days. Missing values remain null. No SQL execution endpoint."},"servers":[{"url":"/"}],"security":[{"bearerAuth":[]},{"localSession":[]}],"paths":{"/api/v1/dataset":{"get":{"summary":"当前真实数据集与日期范围","parameters":[],"responses":{"200":{"description":"Successful local operation","content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"},"source_policy":{"type":"string","enum":["CLEANED_SAMPLE","CLEANED_THEN_LEGACY_THEN_NULL"]},"timezone":{"type":"string"},"unit":{"type":"string"}},"required":["label","start","end","source_policy","timezone","unit"],"additionalProperties":false}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict; do not silently overwrite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/catalog":{"get":{"summary":"权限内门店完整列表与设备快照统计","parameters":[],"responses":{"200":{"description":"Successful local operation","content":{"application/json":{"schema":{"type":"object","properties":{"stores":{"type":"array","items":{"$ref":"#/components/schemas/CatalogStore"}}},"required":["stores"],"additionalProperties":false}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict; do not silently overwrite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{store_id}/periods":{"get":{"summary":"截至as_of的单日、近7日、近30日及年内汇总，保留数据覆盖度","parameters":[{"name":"store_id","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"scope_id","in":"query","required":true,"schema":{"type":"integer","minimum":1}},{"name":"as_of","in":"query","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Successful local operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeriodOverview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict; do not silently overwrite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores":{"get":{"summary":"可访问门店及空调计量范围","parameters":[],"responses":{"200":{"description":"Successful local operation","content":{"application/json":{"schema":{"type":"object","properties":{"stores":{"type":"array","items":{"$ref":"#/components/schemas/Store"}}},"required":["stores"],"additionalProperties":false}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict; do not silently overwrite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{store_id}/reference":{"get":{"summary":"门店档案、有效设备和策略定义快照；权限内只读，非实时状态","parameters":[{"name":"store_id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Successful local operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreReference"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict; do not silently overwrite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{store_id}/profile":{"patch":{"summary":"仅编辑名称和地址；trim必填，版本冲突409，同值不写审计","parameters":[{"name":"store_id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Successful local operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResult"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict; do not silently overwrite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileUpdate"}}}}}},"/api/v1/stores/{store_id}/targets":{"get":{"summary":"逐日查询已生效TES-180/TES-210/TEV；首尾日期包含，不补0或计算达标","parameters":[{"name":"store_id","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"scope_id","in":"query","required":true,"schema":{"type":"integer","minimum":1}},{"name":"start","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"end","in":"query","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Successful local operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict; do not silently overwrite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{store_id}/metrics":{"get":{"summary":"夏季EBA与双TES节能指标；缺失、输入过期或历史阶段未知时保留空值","parameters":[{"name":"store_id","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"scope_id","in":"query","required":true,"schema":{"type":"integer","minimum":1}},{"name":"start","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"end","in":"query","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Successful local operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict; do not silently overwrite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{store_id}/energy":{"get":{"summary":"查询日值及覆盖天数；日期参数首尾均包含，最多366天","parameters":[{"name":"store_id","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"scope_id","in":"query","required":true,"schema":{"type":"integer","minimum":1}},{"name":"start","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"end","in":"query","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Successful local operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnergyResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict; do not silently overwrite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/imports/{batch_id}":{"get":{"summary":"导入记录及预览动作","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Successful local operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Import"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict; do not silently overwrite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/import-rows/{import_row_id}/lineage":{"get":{"summary":"查看来源封存记录；要求来源读取权限","parameters":[{"name":"import_row_id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Successful local operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lineage"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict; do not silently overwrite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/energy/{energy_id}/history":{"get":{"summary":"不可变修订历史","parameters":[{"name":"energy_id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Successful local operation","content":{"application/json":{"schema":{"type":"object","properties":{"revisions":{"type":"array","items":{"$ref":"#/components/schemas/Revision"}}},"required":["revisions"],"additionalProperties":false}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict; do not silently overwrite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/imports/preview":{"post":{"summary":"预览清洗CSV；扩量数据集空白回查封存老库，0保留，不覆盖已有清洗值","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Successful local operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Import"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict; do not silently overwrite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewInput"}}}}}},"/api/v1/imports/{batch_id}/commit":{"post":{"summary":"事务提交已预览批次；同键重试幂等，过期或版本冲突返回409","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Successful local operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Import"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"No access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict; do not silently overwrite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Operation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"localSession":{"type":"apiKey","in":"cookie","name":"saas05_session","description":"Signed 8-hour session; requires an access key login."}},"schemas":{"DailyRow":{"type":"object","properties":{"business_date":{"type":"string","format":"date"},"energy_id":{"type":"integer","minimum":1,"nullable":true},"energy_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"status":{"type":"string","enum":["AVAILABLE","NO_DATA","VOID"]},"source_kind":{"type":"string","nullable":true,"enum":["CLEANED","LEGACY_DIRECT","MANUAL_UPLOAD",null]},"source_label":{"type":"string"},"quality_status":{"type":"string","nullable":true},"quality_note":{"type":"string","nullable":true},"revision_no":{"type":"integer","minimum":1,"nullable":true},"import_row_id":{"type":"integer","minimum":1,"nullable":true},"source_reference":{"type":"object","nullable":true,"additionalProperties":true}},"required":["business_date","energy_id","energy_kwh","status","source_kind","source_label","quality_status","quality_note","revision_no","import_row_id","source_reference"],"additionalProperties":false},"Store":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string"},"store_code":{"type":"string"},"source_org_id":{"type":"integer","minimum":1,"nullable":true},"brand_name":{"type":"string"},"scope_id":{"type":"integer","minimum":1},"scope_kind":{"type":"string"},"unit":{"type":"string"},"timezone":{"type":"string"}},"required":["id","name","store_code","source_org_id","brand_name","scope_id","scope_kind","unit","timezone"],"additionalProperties":false},"Summary":{"type":"object","properties":{"requested_days":{"type":"integer","minimum":1},"available_days":{"type":"integer","minimum":0},"missing_days":{"type":"integer","minimum":0},"void_days":{"type":"integer","minimum":0},"available_energy_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"complete":{"type":"boolean"},"saving_metrics_status":{"type":"string","enum":["SEE_METRICS_ENDPOINT"]}},"required":["requested_days","available_days","missing_days","void_days","available_energy_kwh","complete","saving_metrics_status"],"additionalProperties":false},"EnergyResponse":{"type":"object","properties":{"store_id":{"type":"integer","minimum":1},"scope_id":{"type":"integer","minimum":1},"metric":{"type":"string"},"unit":{"type":"string"},"timezone":{"type":"string"},"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"},"summary":{"$ref":"#/components/schemas/Summary"},"days":{"type":"array","items":{"$ref":"#/components/schemas/DailyRow"}}},"required":["store_id","scope_id","metric","unit","timezone","start","end","summary","days"],"additionalProperties":false},"ImportRow":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"row_number":{"type":"integer","minimum":1},"resolved_store_id":{"type":"integer","minimum":1},"business_date":{"type":"string","format":"date"},"raw_energy":{"type":"string","nullable":true},"proposed_energy_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"before_energy_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"action":{"type":"string","enum":["INSERT","UPDATE","UNCHANGED","VOID","RESTORE","RELINK","SKIP_MISSING","KEEP_CLEANED"]},"source_kind":{"type":"string"},"quality_status":{"type":"string"},"quality_note":{"type":"string","nullable":true},"lineage_status":{"type":"string"}},"required":["id","row_number","resolved_store_id","business_date","raw_energy","proposed_energy_kwh","before_energy_kwh","action","source_kind","quality_status","quality_note","lineage_status"],"additionalProperties":false},"Import":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"batch_no":{"type":"string"},"filename":{"type":"string","nullable":true},"status":{"type":"string"},"total_rows":{"type":"integer","minimum":0},"insert_rows":{"type":"integer","minimum":0},"update_rows":{"type":"integer","minimum":0},"relink_rows":{"type":"integer","minimum":0},"unchanged_rows":{"type":"integer","minimum":0},"missing_rows":{"type":"integer","minimum":0},"kept_cleaned_rows":{"type":"integer","minimum":0},"uploaded_at":{"type":"string"},"committed_at":{"type":"string","nullable":true},"change_reason":{"type":"string","nullable":true},"rows":{"type":"array","items":{"$ref":"#/components/schemas/ImportRow"}},"action_counts":{"type":"object","additionalProperties":{"type":"integer","minimum":0}}},"required":["id","batch_no","filename","status","total_rows","insert_rows","update_rows","relink_rows","unchanged_rows","missing_rows","kept_cleaned_rows","uploaded_at","committed_at","change_reason","rows","action_counts"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"PreviewInput":{"type":"object","properties":{"filename":{"type":"string","maxLength":255},"content_base64":{"type":"string","format":"byte","description":"UTF-8 CSV bytes, maximum 4 MiB before base64. Columns 品牌/门店/日期/日能耗, optional 备注."},"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["filename","content_base64","reason"],"additionalProperties":false},"SourceRecord":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"source_kind":{"type":"string"},"source_table":{"type":"string"},"file_sha256":{"type":"string"},"explanation":{"type":"string","nullable":true},"record":{"type":"object","additionalProperties":true}},"required":["id","source_kind","source_table","file_sha256","explanation","record"],"additionalProperties":false},"Lineage":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"resolved_store_id":{"type":"integer","minimum":1},"batch_id":{"type":"integer","minimum":1},"raw_brand":{"type":"string","nullable":true},"raw_store_name":{"type":"string","nullable":true},"raw_date":{"type":"string","nullable":true},"raw_energy":{"type":"string","nullable":true},"action":{"type":"string"},"source_kind":{"type":"string"},"quality_status":{"type":"string"},"quality_note":{"type":"string","nullable":true},"source_reference":{"type":"object","nullable":true,"additionalProperties":true},"sources":{"type":"array","items":{"$ref":"#/components/schemas/SourceRecord"}}},"required":["id","resolved_store_id","batch_id","raw_brand","raw_store_name","raw_date","raw_energy","action","source_kind","quality_status","quality_note","source_reference","sources"],"additionalProperties":false},"Revision":{"type":"object","properties":{"revision_no":{"type":"integer","minimum":1},"operation":{"type":"string"},"before_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"after_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"before_is_void":{"type":"integer","nullable":true,"enum":[0,1,null]},"after_is_void":{"type":"integer","enum":[0,1]},"committed_at":{"type":"string"},"change_reason":{"type":"string"},"import_row_id":{"type":"integer","minimum":1},"source_kind":{"type":"string"},"quality_status":{"type":"string"},"quality_note":{"type":"string","nullable":true}},"required":["revision_no","operation","before_kwh","after_kwh","before_is_void","after_is_void","committed_at","change_reason","import_row_id","source_kind","quality_status","quality_note"],"additionalProperties":false},"StoreReference":{"type":"object","properties":{"target_candidate":{"type":"object","properties":{"tes_180_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero."},"tes_210_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero."},"known_payback_days":{"type":"integer","nullable":true,"enum":[180,210,null]},"selected_candidate_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"source_revision":{"type":"integer","minimum":1},"source_sheet_id":{"type":"string"},"source_row":{"type":"integer","minimum":1},"source_url":{"type":"string"},"status":{"type":"string","enum":["AWAITING_EFFECTIVE_DATE","AWAITING_SETTLEMENT_AND_DATE"]},"unit":{"type":"string"},"basis":{"type":"string"},"capture_id":{"type":"integer","minimum":1},"source_record_id":{"type":"integer","minimum":1}},"required":["tes_180_kwh","tes_210_kwh","known_payback_days","selected_candidate_kwh","source_revision","source_sheet_id","source_row","source_url","status","unit","basis","capture_id","source_record_id"],"additionalProperties":false,"nullable":true},"profile":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string"},"brand_name":{"type":"string"},"city":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"business_hours":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"},"next_day":{"type":"boolean"}},"required":["start","end","next_day"],"additionalProperties":false},"nullable":true},"business_mode":{"type":"string","nullable":true},"settlement_mode":{"type":"string","nullable":true},"version":{"type":"integer","minimum":1},"peak_hours":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"},"next_day":{"type":"boolean"}},"required":["start","end","next_day"],"additionalProperties":false},"nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"is_key_store":{"type":"boolean","description":"Legacy storage flag; false alone is not a confirmed non-key classification."},"key_store_status":{"type":"string","enum":["MARKED","UNCONFIRMED"]},"equipment_profile":{"type":"object","nullable":true,"additionalProperties":true}},"required":["id","name","brand_name","city","address","business_hours","business_mode","settlement_mode","version","peak_hours","tags","is_key_store","key_store_status","equipment_profile"],"additionalProperties":false},"devices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"source_device_id":{"type":"string"},"device_name":{"type":"string","nullable":true,"maxLength":50,"description":"Legacy op_device.name; null means no provided name, never inferred from code or type."},"device_code":{"type":"string"},"device_type":{"type":"string"},"online_status":{"type":"string","enum":["ONLINE","OFFLINE","UNKNOWN"]},"status_observed_at":{"type":"string","nullable":true},"synced_at":{"type":"string","nullable":true},"source_reference":{"type":"string","nullable":true}},"required":["id","source_device_id","device_name","device_code","device_type","online_status","status_observed_at","synced_at","source_reference"],"additionalProperties":false}},"strategy":{"type":"object","properties":{"configured_count":{"type":"integer","minimum":0,"nullable":true},"dispatched_count":{"type":"integer","minimum":0,"nullable":true},"distinguish_calendar":{"type":"boolean","nullable":true},"execution_status":{"type":"string"},"source_reference":{"type":"string","nullable":true},"observed_at":{"type":"string","nullable":true},"synced_at":{"type":"string"}},"required":["configured_count","dispatched_count","distinguish_calendar","execution_status","source_reference","observed_at","synced_at"],"additionalProperties":false,"nullable":true},"mode":{"type":"string","enum":["FROZEN_LEGACY_REFERENCE"]},"timestamp_timezone":{"type":"string","enum":["UTC"]},"strategy_count_basis":{"type":"string"},"availability_basis":{"type":"string"},"unavailable":{"type":"array","items":{"type":"string"}},"editable_fields":{"type":"array","items":{"type":"string","enum":["name","address"]}},"can_edit_profile":{"type":"boolean"},"stage_snapshot":{"type":"object","properties":{"stage":{"type":"string","nullable":true},"legacy_progress":{"type":"string","nullable":true},"captured_at":{"type":"string"},"source_reference":{"type":"string"},"basis":{"type":"string"}},"required":["stage","legacy_progress","captured_at","source_reference","basis"],"additionalProperties":false,"nullable":true},"stage_history":{"type":"array","items":{"type":"object","properties":{"stage":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"type":"string","nullable":true},"change_reason":{"type":"string"}},"required":["stage","valid_from","valid_to","change_reason"],"additionalProperties":false}},"device_events":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"},"coverage":{"type":"string","enum":["UNVERIFIED"]},"offline_count":{"type":"integer","minimum":0,"nullable":true},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"device_id":{"type":"integer","minimum":1},"event_type":{"type":"string"},"occurred_at":{"type":"string"},"note":{"type":"string","nullable":true}},"required":["id","device_id","event_type","occurred_at","note"],"additionalProperties":false}}},"required":["start","end","coverage","offline_count","events"],"additionalProperties":false}},"required":["target_candidate","profile","devices","strategy","mode","timestamp_timezone","strategy_count_basis","availability_basis","unavailable","editable_fields","can_edit_profile","stage_snapshot","stage_history","device_events"],"additionalProperties":false},"ProfileUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"address":{"type":"string","minLength":1,"maxLength":200},"expected_version":{"type":"integer","minimum":1}},"required":["name","address","expected_version"],"additionalProperties":false},"ProfileResult":{"type":"object","properties":{"status":{"type":"string","enum":["UPDATED","UNCHANGED"]},"profile":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string"},"address":{"type":"string","nullable":true},"version":{"type":"integer","minimum":1}},"required":["id","name","address","version"],"additionalProperties":false}},"required":["status","profile"],"additionalProperties":false},"TargetDay":{"type":"object","properties":{"business_date":{"type":"string","format":"date"},"status":{"type":"string","enum":["AVAILABLE","NO_EFFECTIVE_TARGET"]},"target_period_id":{"type":"integer","minimum":1,"nullable":true},"tes_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tes_180_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tes_210_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tev_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"effective_tev_warning_ratio":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tev_latest_observed_date":{"type":"string","nullable":true,"format":"date"},"source_kind":{"type":"string","nullable":true},"source_reference":{"type":"string","nullable":true},"evaluation_status":{"type":"string","enum":["NOT_EVALUATED"]}},"required":["business_date","status","target_period_id","tes_kwh","tes_180_kwh","tes_210_kwh","tev_kwh","effective_tev_warning_ratio","tev_latest_observed_date","source_kind","source_reference","evaluation_status"],"additionalProperties":false},"TargetsResponse":{"type":"object","properties":{"store_id":{"type":"integer","minimum":1},"scope_id":{"type":"integer","minimum":1},"unit":{"type":"string","enum":["kWh/日"]},"timezone":{"type":"string"},"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"},"summary":{"type":"object","properties":{"requested_days":{"type":"integer","minimum":0},"available_days":{"type":"integer","minimum":0},"missing_days":{"type":"integer","minimum":0}},"required":["requested_days","available_days","missing_days"],"additionalProperties":false},"days":{"type":"array","items":{"$ref":"#/components/schemas/TargetDay"}},"note":{"type":"string"}},"required":["store_id","scope_id","unit","timezone","start","end","summary","days","note"],"additionalProperties":false},"MetricDay":{"type":"object","properties":{"business_date":{"type":"string","format":"date"},"actual_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"eba_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"aes_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"aer_percent":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tes_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tes_180_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tes_210_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tev_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tes_threshold_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tes_180_threshold_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tes_210_threshold_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tev_threshold_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"effective_tev_warning_ratio":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"eba_pass":{"type":"boolean","nullable":true},"tes_pass":{"type":"boolean","nullable":true},"tes_180_pass":{"type":"boolean","nullable":true},"tes_210_pass":{"type":"boolean","nullable":true},"tev_pass":{"type":"boolean","nullable":true},"tev_latest_observed_date":{"type":"string","nullable":true,"format":"date"},"baseline_status":{"type":"string"},"baseline_reference":{"type":"string","nullable":true},"stage":{"type":"string","nullable":true},"evaluation_status":{"type":"string"}},"required":["business_date","actual_kwh","eba_kwh","aes_kwh","aer_percent","tes_kwh","tes_180_kwh","tes_210_kwh","tev_kwh","tes_threshold_kwh","tes_180_threshold_kwh","tes_210_threshold_kwh","tev_threshold_kwh","effective_tev_warning_ratio","eba_pass","tes_pass","tes_180_pass","tes_210_pass","tev_pass","tev_latest_observed_date","baseline_status","baseline_reference","stage","evaluation_status"],"additionalProperties":false},"MetricSummary":{"type":"object","properties":{"requested_days":{"type":"integer","minimum":0},"actual_days":{"type":"integer","minimum":0},"eba_days":{"type":"integer","minimum":0},"matched_days":{"type":"integer","minimum":0},"savings_days":{"type":"integer","minimum":0},"actual_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"matched_eba_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"aes_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"aer_percent":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tes_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tes_180_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tes_210_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tes_threshold_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tes_180_threshold_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"tes_210_threshold_kwh":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Exact decimal kWh, serialized as a string; never infer missing as zero.","nullable":true},"eba_pass":{"type":"boolean","nullable":true},"tes_pass":{"type":"boolean","nullable":true},"tes_180_pass":{"type":"boolean","nullable":true},"tes_210_pass":{"type":"boolean","nullable":true},"tev_pass":{"type":"boolean","nullable":true},"complete_for_savings":{"type":"boolean"}},"required":["requested_days","actual_days","eba_days","matched_days","savings_days","actual_kwh","matched_eba_kwh","aes_kwh","aer_percent","tes_kwh","tes_180_kwh","tes_210_kwh","tes_threshold_kwh","tes_180_threshold_kwh","tes_210_threshold_kwh","eba_pass","tes_pass","tes_180_pass","tes_210_pass","tev_pass","complete_for_savings"],"additionalProperties":false},"MetricsResponse":{"type":"object","properties":{"store_id":{"type":"integer","minimum":1},"scope_id":{"type":"integer","minimum":1},"unit":{"type":"string"},"timezone":{"type":"string"},"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"},"baseline_policy":{"type":"string","enum":["SUMMER_ONLY"]},"baseline_usage":{"type":"string","enum":["LOCAL_TRIAL"]},"rule_version":{"type":"string"},"tev_warning_ratio":{"type":"string","enum":["1.2"],"description":"Default only; the effective ratio is returned on each day."},"summary":{"$ref":"#/components/schemas/MetricSummary"},"availability":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string"},"label":{"type":"string"},"available_days":{"type":"integer","minimum":0},"requested_days":{"type":"integer","minimum":0},"status":{"type":"string","enum":["AVAILABLE","PARTIAL","UNAVAILABLE"]},"reasons":{"type":"array","items":{"type":"string"}}},"required":["metric","label","available_days","requested_days","status","reasons"],"additionalProperties":false}},"days":{"type":"array","items":{"$ref":"#/components/schemas/MetricDay"}},"notes":{"type":"array","items":{"type":"string"}}},"required":["store_id","scope_id","unit","timezone","start","end","baseline_policy","baseline_usage","rule_version","tev_warning_ratio","summary","availability","days","notes"],"additionalProperties":false},"CatalogStore":{"type":"object","properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string"},"store_code":{"type":"string"},"source_org_id":{"type":"integer","minimum":1,"nullable":true},"brand_name":{"type":"string"},"scope_id":{"type":"integer","minimum":1},"scope_kind":{"type":"string"},"unit":{"type":"string"},"timezone":{"type":"string"},"city":{"type":"string","nullable":true},"business_hours":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"},"next_day":{"type":"boolean"}},"required":["start","end","next_day"],"additionalProperties":false},"nullable":true},"peak_hours":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"},"next_day":{"type":"boolean"}},"required":["start","end","next_day"],"additionalProperties":false},"nullable":true},"business_mode":{"type":"string","nullable":true},"settlement_mode":{"type":"string","nullable":true},"is_key_store":{"type":"boolean","description":"Legacy storage flag; false alone is not a confirmed non-key classification."},"key_store_status":{"type":"string","enum":["MARKED","UNCONFIRMED"]},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"stage":{"type":"string","nullable":true},"stage_basis":{"type":"string","nullable":true},"device_count":{"type":"integer","minimum":0},"online_count":{"type":"integer","minimum":0},"offline_count":{"type":"integer","minimum":0},"unknown_count":{"type":"integer","minimum":0}},"required":["id","name","store_code","source_org_id","brand_name","scope_id","scope_kind","unit","timezone","city","business_hours","peak_hours","business_mode","settlement_mode","is_key_store","key_store_status","tags","stage","stage_basis","device_count","online_count","offline_count","unknown_count"],"additionalProperties":false},"PeriodOverview":{"type":"object","properties":{"store_id":{"type":"integer","minimum":1},"scope_id":{"type":"integer","minimum":1},"as_of":{"type":"string","format":"date"},"timezone":{"type":"string"},"periods":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["day","week","month","year"]},"label":{"type":"string"},"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"},"summary":{"$ref":"#/components/schemas/MetricSummary"}},"required":["key","label","start","end","summary"],"additionalProperties":false}}},"required":["store_id","scope_id","as_of","timezone","periods"],"additionalProperties":false}}}}