56 lines
9.7 KiB
Markdown
56 lines
9.7 KiB
Markdown
## Generated Spring Boot Repository Rules
|
|
|
|
- This backend application was generated by `@kri/create-spring-app` with 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.md` and `CLAUDE.md` are central-harness generated outputs. Never edit them directly; update `.agent/profile.yml` or `.agent/project.md` and recompose.
|
|
- After every `.agent/project.md` change, run `cd "D:\_____Dev\_________AgentHarnessBase"`, then `.\scripts\agent-harness.ps1 compose --project epolicy-dash-back` and `.\scripts\agent-harness.ps1 verify --project epolicy-dash-back` to keep the generated agent documents current and verified.
|
|
- Use the repository Gradle Wrapper and run `.\gradlew.bat compileJava` followed 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`, and `t_part_item_data`. Headers normally use database column names; append the complete allowed-value list in parentheses for constrained columns, such as `is_open (1, 0)`, `chart_type (bar)`, and `is_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 `_idx` as 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)` for `t_wave_info`, `(wave_cd, survey_cd, survey_item_order)` for `t_survey_item`, `(wave_cd, part_cd, part_item_cd, survey_cd, part_item_sub_cd)` for `t_part_item_base`, and that same result-series key plus `part_item_data_order` for `t_part_item_data`.
|
|
- Define the Excel import/export schema once with KriCommon `ExcelColumn` DTOs. Use KriCommon `ExcelMapper` for 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/import` for workbook import and `GET /api/v1/excel/template` for 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_file` metadata. Accept `fileTitle` and `fileOrder` as multipart request fields, derive `file_type` from the lowercase filename extension, and keep the original filename as `file_name`.
|
|
- For reference-file uploads, accept `waveCd` as 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 preserves `file_idx`, replaces the physical file, and updates `file_title`, `file_order`, and `file_type`.
|
|
- Reject a reference-file upload when its `waveCd` does 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_wave` as the root of the dashboard hierarchy. Most child data is logically scoped by `wave_cd`.
|
|
- Preserve this logical hierarchy: `t_wave` owns 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. Add `survey_cd` to identify a survey-specific result set and add `part_item_sub_cd` when a sub-item exists.
|
|
- `t_part_item_sub` has 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_sub` rows, and both base and data rows must use `part_item_sub_cd = NULL`. Never use `0` as a substitute for this `NULL` value.
|
|
- An item with sub-items has one or more `t_part_item_sub` rows. Every non-null `part_item_sub_cd` in 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_base` or `t_part_item_data` must belong to the same Wave. Survey items must likewise belong to an existing `(wave_cd, survey_cd)`.
|
|
- Treat `t_survey.survey_color` as a required `VARCHAR(8)` value. Include it as the `survey_color` column in the Excel template/import contract and persist it with each survey.
|
|
- Use `t_part_item_base` as the preferred source for determining which survey audiences apply to an item. Display the single matching `survey_alias` when 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 from `base_count`, and do not retain the removed `base_pre_text` or `base_post_text` fields in entities, Excel contracts, or query assembly.
|
|
- Use the corresponding `*_order` column for API and screen ordering: `wave_info_order`, `survey_order`, `survey_item_order`, `file_order`, `part_order`, `part_item_order`, and `part_item_data_order`. Use `part_item_sub_cd` as the default sub-item order because the schema has no separate sub-item order column.
|
|
- Use the same `t_part_item_data` rows for both chart and statistical-table views. `is_chart_visible` is a required Boolean column with database default `1`; 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/waves` for the header Wave list, `GET /api/v1/waves/{waveCd}` for the Wave overview/navigation/download model, and `GET /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 `isOpen` and a backend-computed `accessible` value. A user with `userRole < 2010` may access open and closed Waves; a user with `userRole >= 2010`, or with no role, may access only Waves whose `is_open` is true.
|
|
- Revalidate Wave access on both Wave-detail and Part-detail requests. Throw a KriCommon `BusinessException` with 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 `resultGroups` response shape. A normal item has one group with `subItem = null`; an item with sub-items has one group per Sub in `part_item_sub_cd` order.
|
|
- Return categories as objects containing `order`, `label`, and `chartVisible`, 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 `color` in 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_text` value unchanged as Part-detail `series[].baseText`; `baseCount` remains a separate numeric field.
|
|
- When importing `part_item_data_value`, round to scale 10 with `RoundingMode.HALF_UP` before validating and storing it as `DECIMAL(14,10)`. Reject only values that still exceed precision 14 after rounding.
|
|
- When `part_item_comment` is blank in Excel, store an empty string rather than `NULL` because the database column is required. Preserve the existing `NULL` semantics of other optional Excel fields.
|
|
- Manage chart types as code enums. The initial supported type is `BAR`; Excel accepts its label `bar` case-insensitively, the database stores code `BAR`, and frontend responses return code `BAR`. 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.
|