chore(조사): 요구 309 분석 B — 연산 자리 체크박스(시스템 관리자 카드) 검토 · 결정 아홉

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/raw/조사/2026-10-21_요구309_B_연산자리_체크박스.md

@@ -0,0 +1,132 @@
+# 요구 309-2 연산 자리 체크박스(시스템 관리자 대시보드) — 검토 · 설계 제안 (읽기만 · 코드 X)
+
+- 원문 = `docs/raw/요구_1021/사용자요구_1021.md:6` · 계획 = `PLAN.md` 502-2 · 앞 자료 = `2026-10-20_요구298_F_보안_속도.md`(F) · `2026-10-20_요구304_H_계산자리_시간_보안.md`(H).
+- 기준 = `main_laptop_1` `d4da1f29d` · 서버 · 측정 없음 · 시간 값은 H 실측 인용 · 「추정」 = 안 잰 값.
+
+## 0. 결론
+
+- 가능 · 작음 — 시스템 관리자만 보는 「계산 자리」 카드 + 체크박스 창 · 판 = 서버 한 곳 · 쓰기 = 시스템 관리자 · 「마스터 데이터」 카드와 같은 두 겹 가림(화면 `settingLinks` · 서버 `require_system_admin`).
+- 45 중 지금 바로 바꿀 수 있는 것 = **2**(지반 표본 G1 · 3D D3) · 서버 창구 하나 더 만들면 **+6**(E1 · F7 · F8 · C4 · R9 · F10) · 나머지 37 = 472-4 뒤 · 짝 유지 · 고정 서버 · 고정 브라우저 → 잠긴 체크 + 까닭 글.
+- 실행 중 체크 = **보안 이득 0**(TS 가 묶음에 그대로 · 개발 서버는 원본 파일째 나감) → 측정 · 비교 · 편의용. 보안이 목적이면 같은 판을 빌드가 읽는 빌드 스위치 + 운영 묶음 배포(S1) + 마스터 권한(S2 · S4)이 따로 필요.
+- [저장] · [확정] 서버 정본은 체크와 무관하게 그대로 · 설계값에 「브라우저만」은 안 둠(CLAUDE.md 5장 ⛔) · 「서버」 고름 = 조작 중 왕복 → 5장 「네트워크 왕복 금지」 예외 · 차례 번호 · 옛 요청 끊기와는 맞음(ground 서버 길 선례).
+- 추천 = **1단계 최소 판**(판 JSON · 읽기/쓰기 창구 · 시스템 로그 한 줄 · 체크 창 · G1 · D3 연결 · 새 코드 300 줄 안팎) → 측정 뒤 2단계(새 계산 창구) → 472-4 뒤 3단계 · 보안은 H 차례 1 · 2 · 4 에 합침.
+
+## 1. 지금 「마스터 데이터」 가림 — 두 겹
+
+| 겹 | 자리 | 내용 |
+|---|---|---|
+| 화면 카드 | `A00_Common/m_settings_nav.ts:48-61` | `role === "SYSTEM_ADMIN"` 일 때만 「마스터 데이터」(M01) 카드 · 나머지 역할 = `:62-70` 구조물 조합 하나 |
+| 화면 그림 | `B01_Dashboard/B01_Dashboard_UI_Page.ts:169-178` · `:201-210` | 「시스템 설정」 컨테이너가 `settingLinks` 그대로 그림 · ☰ 바로가기도 같은 한 벌(`m_settings_nav.ts:74-92`) |
+| 화면 페이지 | `M01_MasterData/M01_MasterData_UI_Page.ts:50-55` | 주소로 바로 들어와도 `SYSTEM_ADMIN` 아니면 토스트 + 대시보드로 · `A00_Common/router.ts:71-72` 는 가림 없음(페이지 몫) |
+| 서버 | `main.py:669-671` | `system_admin_only = [verify_session, require_system_admin]` 를 M01 라우터 통째에 · M02 시스템 층 · 구조물 옵션 쓰기도 같음(`:672-680`) |
+| 판정 함수 | `common_util/common_util_auth.py:171-176` | `require_system_admin` — 세션 `role != "SYSTEM_ADMIN"` 면 403 · 역할 = `users.role`(`:105-148` `verify_session`) |
+| 화면 판정 | `B01_Dashboard/B01_Dashboard_Api_Fetch.ts:12` | `role: "SYSTEM_ADMIN" \| "ADMIN" \| "USER"` · 판정 함수 없이 자리마다 `=== "SYSTEM_ADMIN"` |
+
+- 읽기 · 쓰기 갈림 선례 = 구조물 옵션 — 쓰기 `system_admin_only`(`main.py:680`) · 읽기 `protected`(`:681`).
+
+## 2. 체크박스 단위 · 바꿀 수 있는 것
+
+- 단위 = **묶음(계산 단계 · 단계 밖 묶음) 8 줄** 추천 — 묶음 단계는 한 단계가 여러 id 를 한 번에 셈(cross = C1 C2 C3 C5 C6 G2 G4 F4 · H 4.2) → id 하나만 서버로 못 뺌.
+- 칸 둘 — 「조작 중 브라우저 셈」(켬 = both · 끔 = server) · 「[저장] 서버 정본」(늘 켬 · 잠금).
+
+| # | 묶음(id) | 지금 site | 바꿈 | 서버 길 | 까닭 · 근거 |
+|---|---|---|---|---|---|
+| 1 | 지반 표본(G1) | browser_now | **지금 됨** | `POST /route/elevations`(`B05_Profile_Router_Terrain.py:78`) | 격자 못 받을 때 이미 서버 길(`B05_Profile_Api_TerrainGrid.ts:77-104`) · 서버 = 파이썬 표본기(소수 6자리 같은 값 · 346-1) |
+| 2 | 3D 길 모형(D3) | browser_now | **지금 됨** | 서버 Node 지음 · `GET .../corridor`(`B05_Profile_Router_Corridor.py:80`) | 워커 미리보기 끄면 [확정] 때 지은 모형만 · 조작 중엔 옛 모형 |
+| 3 | 토량 · 구조물 셈(E1 · F7 · F8 · C4) | browser_now | 2단계 | `run_calc`(`common_util_calc_runner.py:38`) 있음 · 조작 중 창구 없음 | 같은 TS 를 서버 Node 로(② · H 4.3) |
+| 4 | 이월 · 다시 얹기(R9 · F10) | browser_now | 2단계 | `run_calc` · [저장] 때 서버가 이미 셈 | 초안 미리보기만 브라우저 |
+| 5 | 노선 · 측점 · 종단 · 따라감 · 횡단 단계(R1 R3 R5~R7 G2 G4 P1~P6 P8 C1~C3 C5 C6 F1~F4 · 23) | browser_now | **잠금 · 472-4 뒤** | 서버 = 파이썬 짝(다른 코드) | 같은 단계에 짝 id 섞임 · 짝 모으기 뒤에만 「같은 셈」 |
+| 6 | 구조물 짝(F5 · F6 · F9) | browser_now | 잠금 | 파이썬 정본(B04 · B07 · B08 소비) | 짝 유지 · TS 는 미리보기(H 4.3) |
+| 7 | 고정 서버(E2 · G3 · D1 · D2 · N1) | server_canon · server_only | 잠금 ✓서버 | 서버 단독 | 값어치 A · GIS · 래스터 |
+| 8 | 고정 브라우저(R2 R4 R8 P7 C7 D4) | browser_only | 잠금 ✓브라우저 | 없음 | 입력 도구 · 그림(발자국) |
+
+- 합 = 2 + 4 + 2 + 23 + 3 + 5 + 6 = 45(등록부 `design_calc_registry.ts` 28 + `_facility.ts` 17).
+- B08 자재 · B09 원가 · M02 표 셈 = 등록부 밖 → 이번 표에 없음 · H 결정 2 · F (b) 몫(「서버」면 파이썬 한 벌로 충분 · TS 걷음).
+
+## 3. 실행 중 스위치 대 빌드 스위치
+
+| | 실행 중(이번 체크박스) | 빌드(H 4.1 both · server · browser) |
+|---|---|---|
+| 고르는 때 | 페이지 열 때 판 읽음 | `vite build` 때 판 읽음(`define` 상수 · 로컬 가지 dynamic import) |
+| 묶음에서 코드 | **남음** — 함수 · 속성 이름 · 상수 그대로 | `server` 묶음은 걷힘 |
+| 바꾸면 | 다음 페이지 열기부터 | 다시 짓기 + 배포(전역 깃 싱크) |
+| 쓸모 | 서버 · 브라우저 시간 대조 · 같은 값 확인 · 느린 PC 시험 | 식 숨김 |
+
+- 보안이 목적이면 더 필요한 것: ① 임시 배포 = 운영 묶음(S1 · 개발 서버 5173 은 TS 파일째 내주므로 빌드 스위치도 무력) ② 마스터 · 쿼리 project_id 길 권한(S2 · S4) ③ 같은 판 JSON 을 vite 가 읽는 빌드 스위치 + 운영 묶음에 `server` id 이름이 없는지 시험 ④ 저장 본문 = 사용자 입력만(H 4.4).
+- 이어 붙이는 꼴 — 체크 창이 쓰는 판 = 빌드가 읽는 판 한 벌 · 창에 「묶음 반영: 다음 배포」 표시(4단계).
+
+## 4. 동작
+
+| 항목 | 제안 |
+|---|---|
+| 읽는 때 | B05 · B06 페이지 열 때 GET 한 번 · 모듈 기억(페이지 수명) · sessionStorage 아님(그 층 = 사용자 조작 캐시 · 포트별) · 자리 = 묶음 열기 자료 줄(`design_pipeline_page.ts:583-588` 과 나란히 · 그 파일 699 줄이라 다른 파일에서) |
+| 「서버」 · 조작 중 | 단계 함수가 `ctx.signal` 로 fetch · 새 조작 = 차례 +1 · 앞 요청 끊음(`design_pipeline.ts:325`) · 늦은 답 버림(`:259` · `:263`) → 지금 틀과 맞음(ground `remote` 선례) |
+| 왕복 시간 | G1 = 표본 22 ms + 회선 3~23 ms(랩탑 · Tailscale) + 세션 14 ms ≈ 0.04~0.06 s(H 2.3 · 2.5 · 추정 합) · 3 묶음 = Node 새 프로세스 0.2~0.27 s + 상세 1.45 MB 넘김(H 2.2) |
+| 막히는 것 | 브라우저 단계는 차례로 기다림(`design_pipeline.ts:297`) → 서버 단계 답까지 뒤 단계(종단 · 횡단 · 발자국) 멈춤 · 끊긴 요청도 서버는 끝까지 셈 → 끌기 중 부하 · 3 · 4 묶음은 잠잠 뒤 보냄(배분 선례 `B05_Profile_Api_HaulPlan.ts:21` 400 ms) |
+| [저장] · [확정] | 그대로 — 서버가 사용자 입력으로 다시 셈(H 2.4) · 판은 저장 길을 안 건드림 |
+| 열린 페이지 | 다음 열기 · 새로고침부터 — 열린 채 바꾸면 단계 재사용 표식(`lastSig`)이 섞임 · 창에 「열린 페이지는 새로고침 뒤」 한 줄 |
+| 기본값 | 판 없음 = 지금 등록부 `site` 그대로 → 넣기만으로 바뀌는 것 0 |
+| 범위 | 전체 한 벌 추천 · 프로젝트별 = 줄 × 프로젝트 · 쓸모 적음 · 「내 계정만」(시험용)은 `user_ui_prefs`(`B01_Dashboard_Repository.py:528-554` · 글만 받음) 길이 있음 |
+
+## 5. 판을 둘 자리
+
+| 후보 | 자리 | 장점 | 흠 |
+|---|---|---|---|
+| **git JSON(추천)** | `resources/master_template/calc_sites.json` · 선례 `구조물정의.json` + 판 · 이력(`M02_SO_Definition.py:4` · `:24` · `:208-225`) | 빌드 스위치가 그대로 읽음 · 랩탑 고침이 임시 배포에 가는 때 = 전역 깃 싱크 · 시놀로지 동기화 밖(코드 폴더) | 쓰는 서버 폴더 파일이 바뀜 → 커밋 · push 필요(「마스터 편집은 그냥 푸시」 규칙) |
+| DB 새 표 | `db_management/020_*.sql` · 표 없음(지금 설정 표 0) | 쓰면 바로 모든 서버 | **DB 하나를 랩탑 · 데스크탑이 같이 씀** → 랩탑 시험 체크가 검증 사용자(임시 배포)에 곧바로 번짐 · 빌드가 못 읽음 |
+| 계정 취향 | `user_ui_prefs`(`db_management/018_user_ui_prefs.sql:17`) | 고칠 것 거의 없음 | 계정마다 · 「정책을 정함」이 아님 · 표 주석상 배치 값만 |
+| 환경 값 | `config/config_system.py` · `.env` | — | 화면에서 못 바꿈 · 재시작 필요 |
+
+## 6. 서버 강제 · 권한 · 감사
+
+- 쓰기 `PUT /api/dashboard/admin/calc-sites` = `Depends(require_system_admin)`(B01 선례 `B01_Dashboard_Router.py:425`) · 읽기 `GET /api/dashboard/calc-sites` = 로그인(값만 · 코드 없음).
+- 검사 — id = 바꿀 수 있는 줄(2 · 2단계 뒤 8)만 · 잠금 줄 · 모르는 id = 400 · 바꿀 수 있는 목록 = 파이썬 상수 + 등록부와 같은지 시험(선례 `NODE_IDS` · `common_util_calc_runner.py:20-35` · `test_472_3_calc_runner.py`).
+- 판이 정본을 약하게 못 함 — 저장 길은 판을 읽지 않음 · 늘 서버 다시 셈 · 브라우저 결과를 받는 길 없음(D2 흠은 H 4.4 로 따로).
+- 2단계 계산 창구 `POST /api/projects/{id}/calc` = `require_project_access`(`common_util_auth.py:187-`) · 본문 크기 상한 · 호출량 감시(`common_util_audit.py:105` `note_api_call`).
+- 감사 = **필요** — 바꿀 때 `record_audit(action="CALC_SITE_CHANGE", resource_type="calc_site", resource_ref=<묶음>)`(`common_util_audit.py:43-65`) → 대시보드 「시스템 로그」(`B01_Dashboard_UI_Page.ts:320-322`)에 보임 · 판 이력 파일은 선택.
+
+## 7. 비용 · 단계
+
+### 7.1 1단계 — 최소 판(G1 · D3 만 실제로 바뀜)
+
+| 파일 | 할 일 | 크기(추정) |
+|---|---|---|
+| `resources/master_template/calc_sites.json` 새 | 판 `{묶음: "both" \| "server"}` · 판 번호 | 10 줄 |
+| `common_util/common_util_calc_sites.py` 새 | 읽기 · 검사 · 쓰기 · 바꿀 수 있는 목록 | 60 줄 |
+| `B01_Dashboard/B01_Dashboard_Router.py`(583) | GET · PUT · 감사 | +30 줄 |
+| `B01_Dashboard/B01_Dashboard_UI_CalcSites.ts` 새 | 8 줄 표 · 체크 · 잠금 까닭 · [저장](창 사본 → 저장 때만 PUT · 선례 `A00_Common/app_settings.ts:5`) | 130 줄 |
+| `A00_Common/m_settings_nav.ts`(98) · `B01_Dashboard_UI_Page.ts`(340) | 시스템 관리자 갈래에 카드 하나 · 누르면 창 | +15 줄 |
+| 글 표(`ui_template/ui_template_locale_m1.ts`) | 제목 · 줄 이름 · 까닭 | +15 줄 |
+| `A00_Common/design/design_calc_sites.ts` 새 | 페이지 열 때 한 번 받음 · `calcSite(묶음)` | 30 줄 |
+| `B05_Profile/logic/B05_Profile_Pipeline_RouteGround.ts`(200) | 「서버」면 격자 대신 `remote` | +3 줄 |
+| `B05_Profile/B05_Profile_UI_Corridor_Worker_Client.ts` | 「서버」면 워커 안 띄움 · 서버 모형 | +5 줄 |
+| 시험 `resources/tester/test_309_2_calc_sites.py` 새 · `test_b01_settings_cards.py` 덧 | 카드 = 시스템 관리자만 · PUT 403(ADMIN · USER) · 잠금 id 400 · 감사 줄 · 목록 = 등록부 · ground 가 판 따라 길 고름 | 120 줄 |
+
+- 합 ≈ 새 380 줄 · 고침 70 줄 · 화면 검증 = ORCA(체크 → B05 열기 → `__aisloPipeline` · 요청 수로 판정 → 되돌림).
+
+### 7.2 다음
+
+| 단계 | 할 일 | 양 |
+|---|---|---|
+| 2 | 계산 창구(`/calc` → `run_calc`) · 3 · 4 묶음 연결 · 잠잠 뒤 보냄 · 시간 대조 표(F 6장 측정) | 중간 |
+| 3 | 472-4 짝 모으기 뒤 5 묶음 열기 · 상주 Node · 5장 지침 고침 | 큼 |
+| 4 | 보안 — 같은 판을 vite `define` 으로 · `server` 묶음 TS 걷음 · 운영 묶음 검사 시험(H 차례 4) · S1 · S2 · S4 먼저 | 중간 |
+
+### 7.3 위험
+
+- 지반 격자를 cross 단계도 같이 씀(`design_pipeline_page.ts:259` `createCrossStage({ grid: groundDeps.grid })`) → `grid()` 를 통째 null 로 하면 미교차 넓힘(G2)이 달라짐 → 판 분기는 ground 단계 안에서만.
+- `design_pipeline_page.ts` 699 줄 — 한 줄도 못 더함 · 연결은 다른 파일에서.
+- 판 파일을 임시 배포 서버에서 고치면 그 폴더 미커밋 → 싱크 때 겹침 · 판 고침은 랩탑에서만 할지 정해야 함.
+- 「서버」로 둔 채 잊으면 검증 사용자 조작이 느려짐 → 창 맨 위 「지금 서버 N 줄」 표시 · 기본값 both.
+
+## 사용자 결정 필요
+
+1. 목적 — (가) 측정 · 비교 · 편의(실행 중 체크 · 보안 이득 0) ★추천 · (나) 보안(빌드 스위치 · 다시 짓기 · S1 먼저 · H 결정 3 과 같은 물음).
+2. 단위 — 묶음 8 줄 ★추천 · id 45 줄(대부분 잠금).
+3. 범위 — 전체 한 벌 ★추천 · 프로젝트별 · 내 계정만(시험용).
+4. 판 자리 — git JSON(전역 깃 싱크 때 배포로) ★추천 · DB 표(랩탑 체크가 임시 배포에 곧바로).
+5. 열린 페이지 — 다음 열기부터 ★추천 · 바로.
+6. 「서버」 때 조작 중 왕복 — 5장 지침의 시험용 예외로 둠 ★추천 · 지침 고침.
+7. 화면 자리 — 「시스템 설정」 안 카드 + 창(마스터 데이터 옆) ★추천 · 대시보드 따로 구역.
+8. 감사 — 시스템 로그 한 줄 ★추천 · 판 이력 파일까지.
+9. 착수 차례 — 1단계만 먼저 · 2단계는 1단계 측정 뒤 ★추천 · 1 · 2 한 번에.