261012_01_ENH: 진행현황에 서브 프로젝트 추가(2605040_C)
This commit is contained in:
195
AGENTS.md
195
AGENTS.md
@@ -35,6 +35,13 @@ Later and more specific instructions may override earlier general instructions o
|
||||
- Lead with the result or decision, then provide only the detail needed to verify it.
|
||||
- Do not create or retain a full session transcript.
|
||||
|
||||
### Attention-Aware Response Style
|
||||
|
||||
- Use `attention-aware-communication` for substantive answers, progress updates, and completion reports.
|
||||
- Default to concise, bottom-line-first Korean without omitting a condition, risk, number, or uncertainty needed for a correct decision.
|
||||
- Give full detail when the user requests depth. Use Spartan style only when explicitly requested.
|
||||
- Presentation rules never reduce investigation, implementation, validation, or reporting obligations.
|
||||
|
||||
## Work Authorization
|
||||
|
||||
- The default workflow is discussion first and explicit execution approval second.
|
||||
@@ -152,6 +159,13 @@ Preferred human-facing tools:
|
||||
- If a possible secret is discovered, do not repeat it. Report only its location, type, and recommended containment action.
|
||||
- Do not rotate, revoke, copy, or otherwise modify credentials unless that exact action is explicitly authorized.
|
||||
|
||||
## Workflow Skills
|
||||
|
||||
- Use `project-reference-loader` before substantive repository analysis, planning, implementation, debugging, or review. Read only the current project and shared references routed for that task, and reread them for each related task even if they were loaded earlier in the session.
|
||||
- Use `karpathy-guidelines` when implementing, refactoring, or reviewing code. It keeps assumptions visible, changes surgical, and success criteria verifiable.
|
||||
- Use `verification-before-completion` before claiming that work is complete, fixed, passing, ready, or safe to commit or publish.
|
||||
- A skill does not expand task scope or authorize Git publication, database execution, deployment, destructive actions, or external communication.
|
||||
|
||||
## Validation
|
||||
|
||||
- Discover supported build, test, lint, type-check, and formatting commands from repository files and project instructions. Do not invent commands.
|
||||
@@ -226,169 +240,42 @@ When implementation is complete, report in Korean:
|
||||
|
||||
## KriCommon Consumer Contract
|
||||
|
||||
### Dependency and API Boundary
|
||||
|
||||
- Consume KriCommon as `com.kri.common:starter:<approved-version>` using the consumer repository's established Gradle dependency and version-management conventions.
|
||||
- Import service-facing APIs from `com.kri.common.feature.*`. Treat `com.kri.common.runtime.*` as internal and do not bind application code to it unless no public API exists and the exception is explicitly documented.
|
||||
- Include the matching Spring starter for any optional Web, Security, JPA, Redis, AOP, or Swagger integration the service enables; KriCommon intentionally declares many integrations as compile-only.
|
||||
- Prefer the shared feature or an approved extension point over duplicating authentication, HTTP, error, enum, Excel, Redis, JSON, date/time, JPA, or utility behavior locally.
|
||||
|
||||
### Configuration and Overrides
|
||||
|
||||
- KriCommon configuration uses only `kri.*`. Established groups include `kri.auth.jwt`, `kri.auth.apikey`, `kri.security`, `kri.swagger`, `kri.web`, `kri.web.mdc`, `kri.http.bypass`, `kri.redis`, `kri.scheduling`, and `kri.error.expose`.
|
||||
- Read the version-matched README and configuration-property classes before setting a property; do not infer a property name or default from an older service.
|
||||
- Supply production JWT secrets, API keys, credentials, allowlists, and service URLs through the consumer's approved secret and configuration system. Never rely on library example or default secrets in production.
|
||||
- Preserve consumer override points. KriCommon's default security chain is created only when the consumer does not provide one, and overridable beans should remain explicit.
|
||||
- Adding a path to API-key allowed paths scopes where API-key authentication is attempted; it does not make the path public or grant authorization.
|
||||
|
||||
### Major Optional Capabilities
|
||||
|
||||
- JWT and API-key authentication integrate with Spring Security. API-key JPA preload requires Spring Data JPA; a consumer-provided claims provider can be used without JPA.
|
||||
- Common Web may register error handling, tracing/MDC, request-user resolution, enum conversion, and CORS behavior. Check for overlap before defining consumer-local equivalents.
|
||||
- Swagger support requires springdoc and defines the shared Bearer/API-key schemes and grouped paths.
|
||||
- Redis and scheduling are opt-in through their `kri.*.enabled` settings and matching runtime dependencies.
|
||||
- HTTP bypass targets are server-configured. Never accept an arbitrary full target URL from a frontend; retain allowed-path checks and do not forward hop-by-hop headers.
|
||||
- The external API client returns response bodies as documented, while bypass responses preserve raw bytes and target `Content-Type`.
|
||||
- `ExternalApiClient` multipart requests generate their own boundary and ignore a caller-supplied `Content-Type`. Multipart headers and `formField` values use UTF-8, while file bodies preserve the supplied bytes.
|
||||
- Multipart filenames, including non-ASCII names, are sent unchanged in the quoted `filename` parameter as raw UTF-8. No ASCII fallback or `filename*` parameter is added; CR/LF rejection and quote/backslash escaping still apply.
|
||||
- `JsonUtil` requires the consumer's explicit `ObjectMapper`; shared date/time helpers define KST as `Asia/Seoul` and also expose UTC semantics.
|
||||
|
||||
### Project Instruction Budget
|
||||
|
||||
- Keep `.agent/project.md` at or below 9 KiB (9,216 bytes) as the normal target. Do not delete material rules merely to meet the budget; move schema details, query or procedure inventories, API examples, and migration history to linked project documentation, and keep concise read-routing instructions here.
|
||||
|
||||
### Upgrade and Verification
|
||||
|
||||
- Review KriCommon release notes, README changes, configuration defaults, auto-configuration conditions, and affected public APIs before upgrading.
|
||||
- Commit dependency-lock or resolved-version changes according to the consumer repository's policy.
|
||||
- Run the consumer's focused compile and tests after an upgrade, including application-context startup tests when auto-configuration or security behavior is affected.
|
||||
- Consume KriCommon as `com.kri.common:starter:<approved-version>` through the repository's established Gradle version-management convention.
|
||||
- Import service-facing APIs from `com.kri.common.feature.*`; treat `com.kri.common.runtime.*` as internal.
|
||||
- Prefer a shared feature or approved extension point over duplicating authentication, HTTP, error, enum, Excel, Redis, JSON, date/time, JPA, crypto, or utility behavior locally.
|
||||
- Do not modify KriCommon or another consumer repository unless it is explicitly included in the approved task scope.
|
||||
|
||||
# KSIF Manage Backend
|
||||
### Required Shared References
|
||||
|
||||
## Generated Spring Boot Repository Rules
|
||||
Before each related task, read the current contents of every matching reference, even if it was read earlier in the session.
|
||||
|
||||
- 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.
|
||||
| Task scope | Required reference |
|
||||
|---|---|
|
||||
| Dependency, configuration, security, Web, Swagger, Redis, scheduling, HTTP, JSON, or date/time behavior | `.agent-harness/references/kri-common/platform-capabilities.md` |
|
||||
| Encryption, hashing, key material, or legacy crypto interoperability | `.agent-harness/references/kri-common/crypto-contract.md` |
|
||||
| KriCommon version upgrade or consumer verification | `.agent-harness/references/kri-common/upgrade-and-verification.md` |
|
||||
|
||||
## Project Rules
|
||||
If a task spans multiple scopes, read every matching reference. Generated files under `.agent-harness/references/` are read-only copies; edit KriCommon's `.agent/consumer.md` or `.agent/consumer-references/` and recompose instead.
|
||||
|
||||
### Data Sources
|
||||
- Internal DB: JPA
|
||||
- External survey DB: MyBatis
|
||||
- No physical FK constraints.
|
||||
# KSIF Manage Backend Project Instruction Router
|
||||
|
||||
### 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.
|
||||
## Required Project References
|
||||
|
||||
### 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.
|
||||
Before each related task, read the current contents of every matching reference below, even if it was read earlier in the session.
|
||||
|
||||
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.
|
||||
| Task scope | Required reference |
|
||||
|---|---|
|
||||
| Repository role, generated Spring Boot conventions, harness workflow, or verification | `.agent/references/repository-rules.md` |
|
||||
| Data sources, roles, Center scope, or authorization | `.agent/references/access-control.md` |
|
||||
| Progress/Final reports, Excel, scoring, headers, or report enums | `.agent/references/report-contract.md` |
|
||||
| Notice, Popup, Q&A, files, or pagination | `.agent/references/content-and-files.md` |
|
||||
| API boundaries, event logs, or unresolved behavior | `.agent/references/api-and-operations.md` |
|
||||
|
||||
Header hierarchy:
|
||||
`report_header_group → variable_group → variable_name → report_header_label`
|
||||
If a task spans multiple scopes, read every matching reference. Do not assume remembered content is current.
|
||||
|
||||
- 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`.
|
||||
## Harness Workflow
|
||||
|
||||
### 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
|
||||
- `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.
|
||||
|
||||
Reference in New Issue
Block a user