260715_0

2026-07-15 18:33:33 +09:00
parent 6b1583103f
commit f533082537
201 changed files with 19776 additions and 563 deletions
@@ -0,0 +1,77 @@
+---
+status: stable
+page_id: A09_Security
+related_pages: ["[[A09_Security/A09_frontend]]", "[[A06_Login/A06_backend]]", "[[A07_Register/A07_backend]]", "[[auth_rbac]]"]
+last_updated: 2026-07-12
+---
+
+# A09_Security — Backend
+
+마스터(회사관리자)·시스템관리자 보안/조직 관리 API + 활동 로그 기록. prefix `/api/security`.
+
+## 파일 구조
+
+| 파일 | 위치 | 역할 |
+|---|---|---|
+| `A09_Security_Router.py` | `A09_Security/A09_Security_Router.py:1-123` | 마스터/시스템관리자/활동로그 API |
+| `A09_Security_Schema.py` | `A09_Security/A09_Security_Schema.py:1-25` | 요청 검증 Pydantic 모델 3종 |
+
+## API 엔드포인트
+
+### 마스터(회사 관리자) 전용 — `require_master`
+
+| 엔드포인트 | 위치 | 역할 |
+|---|---|---|
+| `GET /api/security/master/dashboard` | `A09_Security/A09_Security_Router.py:28` | 마스터 대시보드(회사 기준) |
+| `GET /api/security/master/members` | `A09_Security/A09_Security_Router.py:33` | 회사 팀원 목록 |
+| `GET /api/security/master/join-requests` | `A09_Security/A09_Security_Router.py:38` | 가입 요청 목록 |
+| `POST /api/security/master/join-requests/{id}/decision` | `A09_Security/A09_Security_Router.py:43` | 가입 승인/거부 + 결과 메일 발송 |
+| `POST /api/security/master/members/{id}/remove` | `A09_Security/A09_Security_Router.py:59` | 팀원 비활성화(내보내기) |
+
+### 시스템 관리자 전용 — `require_system_admin`
+
+| 엔드포인트 | 위치 | 역할 |
+|---|---|---|
+| `GET /api/security/admin/dashboard` | `A09_Security/A09_Security_Router.py:86` | 시스템 대시보드 + psutil 리소스(cpu/memory/disk/process) |
+| `GET /api/security/admin/{collection}` | `A09_Security/A09_Security_Router.py:101` | 컬렉션 목록(companies/users/support) |
+| `PATCH /api/security/admin/{entity}/{id}/status` | `A09_Security/A09_Security_Router.py:110` | 엔티티 상태 변경(company/user/support) |
+
+### 인증 사용자 공통 — `verify_session`
+
+| 엔드포인트 | 위치 | 역할 |
+|---|---|---|
+| `POST /api/security/activity` | `A09_Security/A09_Security_Router.py:66` | 활동 로그 기록(202), `activity_logs` INSERT |
+
+## 요청 스키마 (Pydantic)
+
+| 모델 | 위치 | 필드 |
+|---|---|---|
+| `JoinDecisionRequest` | `A09_Security/A09_Security_Schema.py:8` | approved(bool), comment?(≤1000) |
+| `AdminStatusRequest` | `A09_Security/A09_Security_Schema.py:13` | status(3~20), reason(1~500) |
+| `ActivityLogRequest` | `A09_Security/A09_Security_Schema.py:18` | action_type(Literal 5종), resource_id?, status(SUCCESS/FAILURE), details(dict) |
+
+- `action_type` Literal: FILE_UPLOAD, FILE_DOWNLOAD, PROJECT_SAVE, DATA_PROCESS, PAGE_VIEW
+
+## DB 저장 (activity_logs)
+
+`POST /activity`가 INSERT하는 컬럼: `user_id, action_type, resource_id, status, details(JSON)`
+→ 테이블 정의 → [[db_schema/logs_monitoring]]
+
+## 권한 헬퍼
+
+- `require_master` — 회사 마스터(is_master) 권한
+- `require_system_admin` — SYSTEM_ADMIN 역할
+- `verify_session` — 로그인 세션
+- 권한 체계 상세 → [[auth_rbac]]
+
+## 의존성 (공통 유틸)
+
+- [[common_util]] — `common_util_auth`(권한 데코레이터), `common_util_auth_repository`(마스터/관리자 조회·처리), `common_util_email`(가입 결과 메일)
+- 외부 라이브러리: `psutil`(관리자 대시보드 리소스 계측) → [[dependencies]]
+- DB → [[db_schema/logs_monitoring]](activity_logs), [[db_schema/users_auth]](join_requests/companies)
+
+## 참고
+
+- 이 백엔드 API는 마스터/시스템관리자용이나, **프론트(`A09_Security_UI_Page.ts`)는 약관 열람만 하고 이 API를 사용하지 않음**.
+  API 클라이언트(`A09_Security_Api_Fetch.ts`)는 정의만 되고 미연동 상태 → [[A09_Security/A09_frontend]] 참고
+- B01_Dashboard의 관리자 기능과 역할이 겹칠 수 있음 (마스터 대시보드/멤버관리) — 향후 연동처 확인 필요