9.5 KiB
9.5 KiB
KSIF Manage Backend
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 ksif-manage-backand.\scripts\agent-harness.ps1 verify --project ksif-manage-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 Rules
Data Sources
- Internal DB: JPA
- External survey DB: MyBatis
- No physical FK constraints.
Roles
1001,2001: Admin with the same capabilities for the current scope.3001: Center- Center users are restricted to their own
center_cd. - Resolve a Center user's
center_cdfrom the internal user record when it is not present in the shared request-user claims. center_cd = 0is the project-wide code for the real aggregatet_centerrow named전체; do not synthesize this row in application code.
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', excludesSURVEY_TYPE = 'TEST', and requiresStatus = 10. - Use only
ReportHeaderType.CURRENTheaders. A nonblankkon_qidmaps to$.{prefix}.{kon_qid}, whereprefixis the substring before_, or the full value when_is absent. - Header
1001is a special composite score with nokon_qid; calculate it in the external survey SQL and return it through the same metric contract. - The source variables used by the
1001formula are assumed to be non-null values in the1..7range. 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
completeCountint_center.center_final_sample. - Treat blank cells and
-as absent values and delete the matching existingt_report_final_datavalue for that uploaded Center. - Excel columns are
centerCd,completeCount, followed byreport_header_idvalues used as column headers. - Use only
ReportHeaderType.FINALheaders 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
centerCdorcenterCd = 0return the aggregate row followed by all Centers. A specific AdmincenterCdreturns only that Center. Center users receive only their own Center. - For Final, Admin requests with absent
centerCdorcenterCd = 0return the aggregate row followed by all Centers. A specific AdmincenterCdreturns the aggregate row followed by that Center. Center users receive the aggregate row followed by their own Center. - Return
headersandcontent. Each content row containscenterCd,centerName,targetCount,completeCount, and orderedvalues. - For the aggregate
centerCd = 0row, calculate counts at query time instead of using the stored aggregate-row values.targetCountis the sum ofcenter_quotaacross all nonzero Centers. ProgresscompleteCountis the external survey query's aggregate count, while FinalcompleteCountis the sum ofcenter_final_sampleacross all nonzero Centers. - Each value contains
headerId, nullablevalue7, and nullablevalue100. - Progress returns the available 7-point and 100-point values from MyBatis. Final returns
value7 = nulland the stored final value asvalue100.
Notice / Popup
- 0 center mappings = all Centers.
- 1+ mappings = mapped Centers only.
- Use soft delete where provided.
- Store Center-level view history separately in
t_notice_viewandt_popup_view; target mapping tables describe visibility only. - Record a Notice or Popup view for the current Center without changing its target mappings.
- A viewed active Popup remains eligible for subsequent responses; view history is informational and does not suppress it.
- Popup periods are entered and stored with minute precision. Active lookup uses
start_dt <= nowandend_dt > now - 1 minute, so the selected start minute begins normally and the selected end minute remains active through its final second. - Notice and Popup bodies contain Tiptap HTML. Store and return the HTML unchanged and do not add a backend HTML-sanitizer dependency for the current scope.
- Admin roles create, update, and delete Notices and Popups. Center users may read only content visible to their own Center.
Q&A
- Question 1 : Answer 0..1.
- On first Center-user answer view, set:
is_view_answer,view_user,view_dt. - Center users may access only their own Center's questions.
- A Center may not update or delete a Question while it has an active Answer.
- Admin roles may create, update, and delete an Answer only until a Center user has viewed it.
- Once
is_view_answer = 1, the Answer may no longer be updated or deleted. - Use soft delete for Questions and Answers where provided.
Files
- Max 5 files.
- Max 5 MB each.
- Reject
.exe. - Separate storage locations:
notice,qna-question,qna-answer.
Pagination
- Use KriCommon
PageResponseDtofor Notice, Q&A Question, and Admin Popup lists. - Default to
page = 0,size = 20, ordered by registration date descending. - Apply role, Center, target, and soft-delete filters in the database query before pagination.
- Their
POST .../searchbodies extend the shared page request with optionalsearchKeywordandtargetCenterCds. MatchsearchKeywordagainst the row ID, title, or registration user with OR-connected contains searches. MatchtargetCenterCdswith IN semantics; always include rows targeting all Centers (0for Q&A and no target mappings for Notice/Popup). Null or empty filters apply no additional restriction. - Q&A Question list sorting additionally accepts virtual fields
answerDtandviewDt. SortanswerDtby the active Answer'sreg_dtandviewDtby the active Answer'sview_dt, using a left join so Questions without an Answer or Answer view remain in the page result. - Report endpoints do not use pagination.
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.
API Boundaries
- Authentication is already implemented and is outside the current API-development scope.
- Provide screen-oriented endpoints for Progress Report, Final Report, Notice, Q&A Question/Answer, menu exposure, and Popup management.
- Keep controllers thin and enforce role and Center access again in the service layer.
- Store registration, modification, deletion, answer-view, notice-view, and popup-view timestamps as KST
LocalDateTimevalues according to the existing project convention.
System Event Logs
- Controllers write a system event log after each successful create, update, delete, or upload operation.
- Event codes use the hundreds digit for the major category, tens digit for the minor category, and ones digit for the action.
- Action digits are
1 = insert,2 = update,3 = delete, and4 = upload. - Major categories are
2xx = Report,3xx = Notice,4xx = Q&A,5xx = Popup, and6xx = Menu. - Q&A minor categories are
41x = Questionand42x = Answer. - Log resource identifiers and aggregate counts; do not log HTML bodies or uploaded file contents.
Report Code Enums
- Manage
report_header_typeasReportHeaderType implements CodeEnum<Short>with1 = CURRENT,2 = FINAL. - Persist
ReportHeaderTypethrough an explicit JPA code converter so the existingsmallintschema remains unchanged. report_value_type,round_point, andkon_deny_valuehave been removed fromt_report_header.report_value_typeandround_pointhave also been removed from the report API header response;kon_deny_valuewas not exposed by the API.
Do Not Assume
Ask before implementing undefined:
- future differences between Admin
1001/2001 - report filters beyond
centerCd - progress-report scoring formulas and external survey SQL
- behavior that is not present in the approved API and screen contracts