Files
ksif-manage-back/.agent/references/report-contract.md

3.9 KiB

Reports

Progress:

  • Calculated in real time from the external survey DB.
  • Never use t_report_final_data.
  • Backend calculates 7-point and 100-point scores.
  • The backend owns the MyBatis Mapper interface, DTO contract, SQL, service call, and response assembly. The approved external survey source is fixed to PKEY = '2605040_A', excludes SURVEY_TYPE = 'TEST', and requires Status = 10.
  • Use only ReportHeaderType.CURRENT headers. A nonblank kon_qid maps to $.{prefix}.{kon_qid}, where prefix is the substring before _, or the full value when _ is absent.
  • Header 1001 is a special composite score with no kon_qid; calculate it in the external survey SQL and return it through the same metric contract.
  • The source variables used by the 1001 formula are assumed to be non-null values in the 1..7 range. Do not add null or range conditions to that special calculation.

Final:

  • Read pre-calculated values from t_report_final_data.
  • Do not recalculate during normal requests.
  • Admin imports final data through an Excel upload.
  • Upsert only the Centers represented by uploaded rows and retain all other Centers' existing final data.
  • Store completeCount in t_center.center_final_sample.
  • Treat blank cells and - as absent values and delete the matching existing t_report_final_data value for that uploaded Center.
  • Excel columns are centerCd, completeCount, followed by report_header_id values used as column headers.
  • Use only ReportHeaderType.FINAL headers for Final responses and Excel validation.
  • Validate every header ID, Center code, row shape, and value before applying the workbook atomically.

Header hierarchy: report_header_group → variable_group → variable_name → report_header_label

  • Order by report_header_order.
  • 7-point/100-point share one logical header.
  • Report endpoints are not paginated.
  • The initial and currently supported report filter is optional centerCd; keep the request boundary extensible for future filters.
  • For Progress, Admin requests with absent centerCd or centerCd = 0 return the aggregate row followed by all Centers. A specific Admin centerCd returns only that Center. Center users receive only their own Center.
  • For Final, Admin requests with absent centerCd or centerCd = 0 return the aggregate row followed by all Centers. A specific Admin centerCd returns the aggregate row followed by that Center. Center users receive the aggregate row followed by their own Center.
  • Return headers and content. Each content row contains centerCd, centerName, targetCount, completeCount, and ordered values.
  • For the aggregate centerCd = 0 row, calculate counts at query time instead of using the stored aggregate-row values. targetCount is the sum of center_quota across all nonzero Centers. Progress completeCount is the external survey query's aggregate count, while Final completeCount is the sum of center_final_sample across all nonzero Centers.
  • Each value contains headerId, nullable value7, and nullable value100.
  • Progress returns the available 7-point and 100-point values from MyBatis. Final returns value7 = null and the stored final value as value100.

Excel

  • Do not implement backend Excel-download endpoints.
  • The frontend will export the current screen query/filter result after the backend APIs are complete.
  • Final Report Excel upload remains a backend Admin capability as defined in the Reports rules.

Report Code Enums

  • Manage report_header_type as ReportHeaderType implements CodeEnum<Short> with 1 = CURRENT, 2 = FINAL.
  • Persist ReportHeaderType through an explicit JPA code converter so the existing smallint schema remains unchanged.
  • report_value_type, round_point, and kon_deny_value have been removed from t_report_header.
  • report_value_type and round_point have also been removed from the report API header response; kon_deny_value was not exposed by the API.