9.7 KiB
9.7 KiB
Generated Spring Boot Repository Rules
- This backend application was generated by
@kri/create-spring-appwith Java 17 and Spring Boot 3.5.7. - Consume KriCommon through
com.kri.common:starter:beta.1.6.4; do not change that approved version or duplicate shared behavior without explicit approval. - The selected primary database is
mysql. Preserve its configured dialect, driver, transaction, schema, and migration conventions. - Keep controllers thin and preserve the generated service, DTO, persistence, configuration, QueryDSL, JDBC, and optional MyBatis boundaries.
AGENTS.mdandCLAUDE.mdare central-harness generated outputs. Never edit them directly; update.agent/profile.ymlor.agent/project.mdand recompose.- After every
.agent/project.mdchange, runcd "D:\_____Dev\_________AgentHarnessBase", then.\scripts\agent-harness.ps1 compose --project epolicy-dash-backand.\scripts\agent-harness.ps1 verify --project epolicy-dash-backto keep the generated agent documents current and verified. - Use the repository Gradle Wrapper and run
.\gradlew.bat compileJavafollowed by focused tests for relevant changes.
Project Data Management Premises
- Do not implement a frontend administration page at this stage. Do not add create, update, or delete features for individual information records unless a future approved requirement explicitly expands the scope.
- Supply and maintain the data required by this project through Excel-based bulk upload instead of individual administration features.
- Keep user and file data outside the Excel bulk-import scope. Import the remaining project data from one Excel workbook containing multiple sheets.
- The Excel workbook contract uses nine required sheets named after their tables:
t_wave,t_wave_info,t_survey,t_survey_item,t_part,t_part_item,t_part_item_sub,t_part_item_base, andt_part_item_data. Headers normally use database column names; append the complete allowed-value list in parentheses for constrained columns, such asis_open (1, 0),chart_type (bar), andis_chart_visible (1, 0). The workbook must contain all logical parent rows referenced by its child rows. - Treat every database column whose name ends with
_idxas an auto-increment identity. Do not include these columns in Excel import or template sheets, and preserve an existing identity by matching the row's logical key during repeat imports. - For identity-backed Excel tables, use these import logical keys:
(wave_cd, wave_info_order)fort_wave_info,(wave_cd, survey_cd, survey_item_order)fort_survey_item,(wave_cd, part_cd, part_item_cd, survey_cd, part_item_sub_cd)fort_part_item_base, and that same result-series key pluspart_item_data_orderfort_part_item_data. - Define the Excel import/export schema once with KriCommon
ExcelColumnDTOs. Use KriCommonExcelMapperfor workbook mapping and keep only project-specific type, value, and cross-sheet relationship rules in a consumer-local validator; do not duplicate a general-purpose Excel parser. - Use
POST /api/v1/excel/importfor workbook import andGET /api/v1/excel/templatefor downloading an empty XLSX template. The exported template must contain the same nine required sheets in dependency order and the exact headers accepted by the importer. - Apply a valid workbook atomically using upsert semantics: insert new primary/logical keys, update matching keys, and retain existing database rows that are absent from the workbook. Do not use a bulk import to delete omitted rows unless a future approved requirement explicitly changes this policy.
- A reference-file upload writes both the physical file and its
t_filemetadata. AcceptfileTitleandfileOrderas multipart request fields, derivefile_typefrom the lowercase filename extension, and keep the original filename asfile_name. - For reference-file uploads, accept
waveCdas a path variable and store the file under{kri.file.base-dir}/References/{waveCd}using the original filename. Treat(wave_cd, file_name)as the upload logical key: uploading the same filename again preservesfile_idx, replaces the physical file, and updatesfile_title,file_order, andfile_type. - Reject a reference-file upload when its
waveCddoes not exist. Coordinate the database transaction and filesystem replacement so a database rollback restores the previous file or removes a newly created file.
Dashboard Data Model Contract
- Treat
t_waveas the root of the dashboard hierarchy. Most child data is logically scoped bywave_cd. - Preserve this logical hierarchy:
t_waveowns wave information, surveys, file metadata, and parts; a survey owns survey items; a part owns part items; and a part item owns optional sub-items, base counts, and result data. - Do not add physical database foreign keys. The backend must validate all logical parent-child relationships during Excel import and any future data mutation.
- Treat
(wave_cd, part_cd, part_item_cd)as the logical item key. Addsurvey_cdto identify a survey-specific result set and addpart_item_sub_cdwhen a sub-item exists. t_part_item_subhas no physical primary key in the planned schema. Treat(wave_cd, part_cd, part_item_cd, part_item_sub_cd)as its logical identifier and lookup key.- A normal item has no
t_part_item_subrows, and both base and data rows must usepart_item_sub_cd = NULL. Never use0as a substitute for thisNULLvalue. - An item with sub-items has one or more
t_part_item_subrows. Every non-nullpart_item_sub_cdin its base and data rows must reference a sub-item belonging to the same(wave_cd, part_cd, part_item_cd). - Every survey code used by
t_part_item_baseort_part_item_datamust belong to the same Wave. Survey items must likewise belong to an existing(wave_cd, survey_cd). - Treat
t_survey.survey_coloras a requiredVARCHAR(8)value. Include it as thesurvey_colorcolumn in the Excel template/import contract and persist it with each survey. - Use
t_part_item_baseas the preferred source for determining which survey audiences apply to an item. Display the single matchingsurvey_aliaswhen only one audience applies; display공통when all defined audiences apply. - Store an optional display string in
t_part_item_base.base_text(VARCHAR(128)). Do not reconstruct it frombase_count, and do not retain the removedbase_pre_textorbase_post_textfields in entities, Excel contracts, or query assembly. - Use the corresponding
*_ordercolumn for API and screen ordering:wave_info_order,survey_order,survey_item_order,file_order,part_order,part_item_order, andpart_item_data_order. Usepart_item_sub_cdas the default sub-item order because the schema has no separate sub-item order column. - Use the same
t_part_item_datarows for both chart and statistical-table views.is_chart_visibleis a required Boolean column with database default1; statistical tables use every row, while charts omit categories and matching values whose flag is false. Do not introduce a separate table-data source that could diverge from chart values. - Avoid N+1 query patterns when assembling a Wave dashboard. Fetch the required Part, Item, Sub, Base, and Data ranges in batches and assemble the response hierarchy in the backend.
Frontend API Contract
- Provide screen-oriented APIs rather than exposing table-shaped CRUD endpoints. Use
GET /api/v1/wavesfor the header Wave list,GET /api/v1/waves/{waveCd}for the Wave overview/navigation/download model, andGET /api/v1/waves/{waveCd}/parts/{partCd}for all items and result data in one Part. - Return every Wave in the header list and include both
isOpenand a backend-computedaccessiblevalue. A user withuserRole < 2010may access open and closed Waves; a user withuserRole >= 2010, or with no role, may access only Waves whoseis_openis true. - Revalidate Wave access on both Wave-detail and Part-detail requests. Throw a KriCommon
BusinessExceptionwith forbidden status when a restricted user requests a closed Wave; frontend visibility is not an authorization boundary. - Assemble normal and sub-item results through one
resultGroupsresponse shape. A normal item has one group withsubItem = null; an item with sub-items has one group per Sub inpart_item_sub_cdorder. - Return categories as objects containing
order,label, andchartVisible, alongside complete survey value series. The frontend uses all category/value indexes for statistical tables and filters matching indexes only for chart rendering. Reject Excel imports when category labels, display orders, or chart-visibility flags differ between survey series in the same Item/Sub result group. - Expose each survey's stored color as
colorin both Wave-detail survey objects and Part-detail series objects so the frontend uses one server-managed color mapping. - Return the stored nullable
t_part_item_base.base_textvalue unchanged as Part-detailseries[].baseText;baseCountremains a separate numeric field. - When importing
part_item_data_value, round to scale 10 withRoundingMode.HALF_UPbefore validating and storing it asDECIMAL(14,10). Reject only values that still exceed precision 14 after rounding. - When
part_item_commentis blank in Excel, store an empty string rather thanNULLbecause the database column is required. Preserve the existingNULLsemantics of other optional Excel fields. - Manage chart types as code enums. The initial supported type is
BAR; Excel accepts its labelbarcase-insensitively, the database stores codeBAR, and frontend responses return codeBAR. Reject unsupported labels during Excel validation. - Build file download URLs in the backend from the configured file resource path and the stored file metadata. Do not require the frontend to construct filesystem paths.