Files
ksif-manage-back/.agent/project.md

9.5 KiB

KSIF Manage Backend

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 ksif-manage-back and .\scripts\agent-harness.ps1 verify --project ksif-manage-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 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_cd from the internal user record when it is not present in the shared request-user claims.
  • center_cd = 0 is the project-wide code for the real aggregate t_center row 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', 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.

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_view and t_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 <= now and end_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 PageResponseDto for 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 .../search bodies extend the shared page request with optional searchKeyword and targetCenterCds. Match searchKeyword against the row ID, title, or registration user with OR-connected contains searches. Match targetCenterCds with IN semantics; always include rows targeting all Centers (0 for 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 answerDt and viewDt. Sort answerDt by the active Answer's reg_dt and viewDt by the active Answer's view_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 LocalDateTime values 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, and 4 = upload.
  • Major categories are 2xx = Report, 3xx = Notice, 4xx = Q&A, 5xx = Popup, and 6xx = Menu.
  • Q&A minor categories are 41x = Question and 42x = Answer.
  • Log resource identifiers and aggregate counts; do not log HTML bodies or uploaded file contents.

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.

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