261105_01_DOC: 하네스 수정

This commit is contained in:
2026-11-05 12:20:12 +09:00
parent d6520a97c5
commit 77f10cf143
15 changed files with 464 additions and 141 deletions

View File

@@ -1,61 +1,19 @@
## Generated Spring Boot Repository Rules
# epolicy-dash-back Project Instruction Router
- 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.
## Required Project References
## Project Data Management Premises
Before each related task, read the current contents of every matching reference below, even if it was read earlier in the session.
- 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 has eleven required table-named sheets: `t_wave`, `t_wave_info`, `t_survey`, `t_survey_item`, `t_part`, `t_part_item`, `t_part_item_sub`, `t_part_item_base`, `t_part_item_chart`, `t_part_item_chart_highlight`, and `t_part_item_data`. Headers use database names and constrained headers list every allowed value in parentheses. The workbook must contain all referenced logical parents.
- Omit every auto-increment `_idx` column from Excel. Replacement imports regenerate identities.
- Reject duplicate Excel keys: Wave info `(wave_cd,wave_info_order)`; survey item `(wave_cd,survey_cd,survey_item_order)`; base `(wave_cd,part_cd,part_item_cd,survey_cd,part_item_sub_cd)`; chart/highlight omit `survey_cd`; data adds `part_item_data_order` to base.
- 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.
- Excel endpoints are `POST /api/v1/excel/import`, `GET /api/v1/excel/template`, `GET /api/v1/excel/waves/{waveCd}/export`, and `DELETE /api/v1/excel/waves/{waveCd}`. Downloads use the same eleven sheets, order, and headers; a missing Wave exports an empty workbook.
- Imports atomically replace every included Wave: validate first, delete all eleven managed tables, then insert. Failures restore prior data. Standalone reset uses the same child-to-root deletion and retains `t_file` metadata and physical files, allowing temporary orphans until that `wave_cd` is reimported.
- 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 files under `{kri.file.base-dir}/References/{waveCd}` using their original names. Treat `(wave_cd, file_order)` as the upload logical key: repeat uploads preserve `file_idx`, replace metadata and the physical file, and remove the prior filename after commit. Reject a filename already used by another order in the same Wave.
- 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.
| Task scope | Required reference |
|---|---|
| Any substantive analysis, planning, implementation, debugging, review, or documentation work in this repository | `.agent/references/repository-rules.md` |
| Work covered by the dashboard domain contract contract | `.agent/references/dashboard-domain-contract.md` |
## Dashboard Data Model Contract
If a task spans multiple scopes, read every matching reference. Do not assume remembered content is current.
- 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.
- Store the nullable `t_part_item_sub.part_item_sub_comment` value and expose it as `partItemSubComment` in Part-detail sub-item responses.
- 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)`.
- Store four `VARCHAR(8)` survey palette colors: required `survey_color` plus nullable highlight, negative, and negative-highlight colors. Include all in Excel/API; fall back to default, default, and negative/highlight/default respectively.
- 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.
- Chart/highlight key is `(wave_cd,part_cd,part_item_cd,part_item_sub_cd)`; one config applies to all survey series in its group. Chart type/gap default to `BAR`/`NONE`; colors come from survey palettes.
- Resolve chart highlights independently and return mode/value without calculating highlighted categories. Supported modes are `MAX_VALUE`, `LAST_VISIBLE`, and `SPECIFIED`; only `SPECIFIED` accepts a non-null comma-separated integer list. Highlight colors come only from the survey palette.
- Store item and sub-item negative mode/order independently (`DEFAULT`, `NEGATIVE`, `SPECIFIED`); sub settings never inherit parent settings. Only `SPECIFIED` accepts an order list. Return these settings and survey palette colors so the frontend classifies rows and applies final colors.
- Treat null `part_item_sub_cd` values as equal when matching normal-item chart/highlight settings. Validate Excel logical-key uniqueness, null sub codes for normal items, negative/highlight order syntax, and palette colors as `#RRGGBB`.
- 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.
## Harness Workflow
## 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 effective `color`, `highlightColor`, `negativeColor`, and `negativeHighlightColor` in both Wave-detail surveys and Part-detail series. Return item/sub-item `negativeMode` and nullable `negativeOrder`; the frontend classifies and colors chart rows.
- Return the stored nullable `t_part_item_base.base_text` value unchanged as Part-detail `series[].baseText`; `baseCount` remains a separate numeric field.
- Return `series[].chartGapMode`; the frontend applies `NONE`, `ALL`, or `LAST_VISIBLE`, where the last mode uses the greatest visible `part_item_data_order`.
- 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 in `t_part_item_chart`. The initial supported type is `BAR`; Excel accepts its label `bar` case-insensitively, the database stores code `BAR`, and Part-detail series 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.
- `AGENTS.md` and `CLAUDE.md` are generated outputs. Never edit them directly.
- Edit `.agent/project.md` only when routing changes. Store durable project detail in `.agent/references/`.
- A reference-only content change does not require recomposition when its route is unchanged. Run harness verification to validate routing and UTF-8.
- Recompose and verify after changing `.agent/project.md`, `.agent/profile.yml`, or another composed instruction source.

View File

@@ -0,0 +1,51 @@
## 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 has eleven required table-named sheets: `t_wave`, `t_wave_info`, `t_survey`, `t_survey_item`, `t_part`, `t_part_item`, `t_part_item_sub`, `t_part_item_base`, `t_part_item_chart`, `t_part_item_chart_highlight`, and `t_part_item_data`. Headers use database names and constrained headers list every allowed value in parentheses. The workbook must contain all referenced logical parents.
- Omit every auto-increment `_idx` column from Excel. Replacement imports regenerate identities.
- Reject duplicate Excel keys: Wave info `(wave_cd,wave_info_order)`; survey item `(wave_cd,survey_cd,survey_item_order)`; base `(wave_cd,part_cd,part_item_cd,survey_cd,part_item_sub_cd)`; chart/highlight omit `survey_cd`; data adds `part_item_data_order` to base.
- 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.
- Excel endpoints are `POST /api/v1/excel/import`, `GET /api/v1/excel/template`, `GET /api/v1/excel/waves/{waveCd}/export`, and `DELETE /api/v1/excel/waves/{waveCd}`. Downloads use the same eleven sheets, order, and headers; a missing Wave exports an empty workbook.
- Imports atomically replace every included Wave: validate first, delete all eleven managed tables, then insert. Failures restore prior data. Standalone reset uses the same child-to-root deletion and retains `t_file` metadata and physical files, allowing temporary orphans until that `wave_cd` is reimported.
- 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 files under `{kri.file.base-dir}/References/{waveCd}` using their original names. Treat `(wave_cd, file_order)` as the upload logical key: repeat uploads preserve `file_idx`, replace metadata and the physical file, and remove the prior filename after commit. Reject a filename already used by another order in the same Wave.
- 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.
- Store the nullable `t_part_item_sub.part_item_sub_comment` value and expose it as `partItemSubComment` in Part-detail sub-item responses.
- 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)`.
- Store four `VARCHAR(8)` survey palette colors: required `survey_color` plus nullable highlight, negative, and negative-highlight colors. Include all in Excel/API; fall back to default, default, and negative/highlight/default respectively.
- 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.
- Chart/highlight key is `(wave_cd,part_cd,part_item_cd,part_item_sub_cd)`; one config applies to all survey series in its group. Chart type/gap default to `BAR`/`NONE`; colors come from survey palettes.
- Resolve chart highlights independently and return mode/value without calculating highlighted categories. Supported modes are `MAX_VALUE`, `LAST_VISIBLE`, and `SPECIFIED`; only `SPECIFIED` accepts a non-null comma-separated integer list. Highlight colors come only from the survey palette.
- Store item and sub-item negative mode/order independently (`DEFAULT`, `NEGATIVE`, `SPECIFIED`); sub settings never inherit parent settings. Only `SPECIFIED` accepts an order list. Return these settings and survey palette colors so the frontend classifies rows and applies final colors.
- Treat null `part_item_sub_cd` values as equal when matching normal-item chart/highlight settings. Validate Excel logical-key uniqueness, null sub codes for normal items, negative/highlight order syntax, and palette colors as `#RRGGBB`.
- 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 effective `color`, `highlightColor`, `negativeColor`, and `negativeHighlightColor` in both Wave-detail surveys and Part-detail series. Return item/sub-item `negativeMode` and nullable `negativeOrder`; the frontend classifies and colors chart rows.
- Return the stored nullable `t_part_item_base.base_text` value unchanged as Part-detail `series[].baseText`; `baseCount` remains a separate numeric field.
- Return `series[].chartGapMode`; the frontend applies `NONE`, `ALL`, or `LAST_VISIBLE`, where the last mode uses the greatest visible `part_item_data_order`.
- 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 in `t_part_item_chart`. The initial supported type is `BAR`; Excel accepts its label `bar` case-insensitively, the database stores code `BAR`, and Part-detail series 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.

View File

@@ -0,0 +1,14 @@
## 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.
## Required Domain Reference
- Before changing Excel import/export, reference-file handling, dashboard data models, Wave authorization, chart/statistics behavior, or frontend-facing APIs, read `.agent/references/dashboard-domain-contract.md`.
- Treat that reference as binding project instruction for related work. Keep durable detail there and keep this routing file concise.