영업부서의 매입매출 관리(회계모듈)와 SI 프로젝트 기술 인벤토리 관리(인프라모듈)를 하나의 웹 애플리케이션에서 통합 운영하는 사내 전용 플랫폼.
현재 상태: 코드 구조 마이그레이션 완료, 핵심 화면은 동작 중이며 일부 화면과 운영 세부 기능은 계속 보강 중 (v0.4)
문서 안내 — 코딩 규칙은
CLAUDE.md, 작업 지침은docs/guidelines/, 아키텍처 결정은docs/DECISIONS.md, 알려진 제약은docs/KNOWN_ISSUES.md, 프로젝트 배경은docs/PROJECT_CONTEXT.md참조. 멀티에이전트 작업 기준은docs/guidelines/agent_workflow.md,docs/agents/를 따른다. 엔트리포인트/초기화 구조, API 엔드포인트, 데이터 모델의 1차 기준은 소스 코드(app/core/startup/,app/modules/*/routers/,app/modules/*/models/)다. 인프라모듈의 세부 진행 상태와 우선순위는docs/superpowers/plans/2026-03-24-infra-module-roadmap.md를 기준으로 본다.
| 모듈 | 설명 | 상태 |
|---|---|---|
| 공통 (common) | 사용자, 업체, 인증, 시스템 설정 | 동작 중 |
| 회계 (accounting) | 사업 원장, 매입매출 실적, 입금/배분, 대시보드, 보고서, Excel | 핵심 기능 동작, 보강 진행 중 |
| 인프라 (infra) | 기간 컨텍스트, 자산 원장, IP 인벤토리, 포트맵, 배치도, 카탈로그, 감사 이력, Excel Import/Export | 핵심 화면 동작, 일부 화면 보강 진행 중 |
사업 원장 (마스터)
├── 사업 기본정보 (사업유형, 담당, 업체, 진행단계 등)
├── 사업기간 (ContractPeriod: Y25, Y26 등 연도 단위)
├── Forecast (ContractPeriod별 월별 예상 매출/GP)
├── TransactionLine (매출/매입 실적 라인)
└── Receipt (입금 내역)
↓
[Export]
├── [매입매출관리] Excel - 사업 단위
└── [영업관리] Excel - 전체 원장 (월별 집계)
고객사 선택 / 기간 컨텍스트 확인
├── 기간 목록 `/periods`
│ ├── 기간 기본정보 / 단계 / 산출물
│ └── 기간-업체 / 담당자 연결
├── 자산 원장 `/assets`
│ ├── Asset 등록 / 편집 / 상세
│ ├── HW 모델 연결 (ProductCatalog → 스펙/인터페이스)
│ ├── 설치 SW / IP / 담당자 / 관계 / Alias / 관련업체
│ └── 현재 역할 / 귀속기간 / 배치 정보 연결
├── 네트워크 화면
│ ├── IP 인벤토리 `/ip-inventory`
│ └── 포트맵 `/port-maps`
├── 배치도 `/physical-layout`
├── 제품 카탈로그 `/product-catalog`
├── 감사 이력 `/audit-history`
└── Excel Import/Export
| 영역 | 기술 |
|---|---|
| 백엔드 | Python 3.11+, FastAPI |
| ORM | SQLAlchemy 2.0 (Mapped 방식) |
| DB | PostgreSQL 16 |
| 프론트엔드 | Jinja2 + HTMX + AG Grid Community |
| Excel 처리 | openpyxl, pandas |
| 인증 | 세션 기반 (쿠키), bcrypt 해싱 |
| RBAC | 역할 기반 모듈 접근 제어 (Role.permissions JSON) |
| 포매터/린터 | black, ruff |
| 테스트 | pytest |
- Docker Desktop (WSL2 backend)
- Docker Compose
또는
- Python 3.11 이상
- PostgreSQL 16
- pip
# 1. 환경변수 파일 생성
cp .env.example .env
# SESSION_SECRET_KEY, BOOTSTRAP_ADMIN_PASSWORD 등 필수값 설정
# 2. 컨테이너 빌드 및 기동
docker compose up --build
# 3. 앱 접속
# http://localhost:9000app컨테이너는 PostgreSQL 준비 상태를 기다린 뒤alembic upgrade head를 실행하고 서버를 시작한다.- 기본 compose 구성은
db,app,worker,catalog-research-service역할로 동작한다.app: FastAPI 웹/API 전용, 앱 포트9000worker: 자동 카탈로그 리서치 스케줄링/DB 반영 전용catalog-research-service: 외부/모델 기반 카탈로그 조회 엔진, 서비스 포트8765
app,worker,db,catalog-research-service는restart: unless-stopped로 설정되어 자동 재기동된다.- 운영형 값은 compose 파일에 하드코딩하지 않고 루트
.env에서 주입한다. - 운영 환경에서는
ENV,SESSION_SECRET_KEY, DB 계정, bootstrap 관리자 비밀번호를 안전한 값으로 변경해야 한다. - 호스트 공개 포트는 앱
9000, DB5432기준이다. pjtmgr health check는http://127.0.0.1:9000/api/v1/health를 사용한다.
# 운영 compose 문법/환경변수 확인
docker compose -f docker-compose.prod.yml config --quiet
# 배포 후 기본 smoke check (앱 컨테이너 안에서 실행)
docker compose exec app python /app/scripts/smoke_check.py --base-url http://127.0.0.1:9000
# 프론트엔드 vendor/static 안전 검사 (호스트 또는 앱 컨테이너)
python scripts/check_frontend_assets.py- UI 성능/정적 리소스 변경 후에는 서버 health뿐 아니라 실제 브라우저 콘솔, 네트워크, grid 렌더링까지 확인한다.
- minified vendor 파일은 line 단위 삭제/수정 금지. sourcemap 주석 제거가 필요하면 targeted string replace 후 파일 크기와 global symbol을 확인한다.
# 1. 의존성 설치
python -m pip install -r requirements.txt
# 2. 환경변수 설정 (.env 파일 생성)
# DATABASE_URL=postgresql://pjtmgr:pjtmgr@localhost:5432/pjtmgr
# SESSION_SECRET_KEY=<운영 환경 필수, 충분히 긴 랜덤 세션 비밀키>
# BOOTSTRAP_ADMIN_LOGIN_ID=admin
# BOOTSTRAP_ADMIN_PASSWORD=<초기 관리자 비밀번호>
# BOOTSTRAP_ADMIN_NAME=관리자
# ENABLED_MODULES=common,accounting,infra
# 3. 서버 실행
uvicorn app.main:app --host 0.0.0.0 --port 9000 --reload
# 4. 브라우저 접속
# http://localhost:9000- 비개발 환경에서는
SESSION_SECRET_KEY가 없으면 앱이 시작되지 않는다. - 로컬 실행 시 PostgreSQL이 미리 기동되어 있어야 한다.
ENABLED_MODULES 환경변수로 활성 모듈을 제어한다:
ENABLED_MODULES=common,accounting,infra # 본사 전체 (기본값)
ENABLED_MODULES=common,infra # 현장 standalone (인프라만)
ENABLED_MODULES=common,accounting # 영업 전용common모듈은 항상 활성 (사용자, 업체, 인증 등 기반 기능)- 비활성 모듈의 테이블은 DB에 존재하되 라우터가 등록되지 않아 접근 불가
- startup 시 Alembic migration이 자동 적용되어 신규 DB도 스키마가 준비됨
- 활성 관리자 계정이 없으면 bootstrap 환경변수(
BOOTSTRAP_ADMIN_LOGIN_ID,BOOTSTRAP_ADMIN_PASSWORD,BOOTSTRAP_ADMIN_NAME)로 첫 관리자 계정을 생성 - Excel Import를 통해 기존 데이터 일괄 등록 가능 (관리자 전용)
[브라우저]
└─ HTML (Jinja2) + HTMX + AG Grid
│ HTTP / JSON
[FastAPI 서버] ── [사내 네트워크 전용, 외부 차단]
├─ app/core/ # 앱 팩토리, 설정, DB, 예외, 인증, startup
├─ app/modules/
│ ├─ common/ # 사용자, 업체, 설정, 감사로그
│ ├─ accounting/ # 사업, 매출/매입, 입금, 대시보드, 보고서
│ └─ infra/ # 프로젝트, 자산, IP, 포트맵, 정책, Excel, 현황판
└─ Alembic (단일 migration 체인)
│
[PostgreSQL 16]
- API와 템플릿 렌더링을 같은 FastAPI 인스턴스에서 처리
- 모듈 간 의존성:
core <- common <- {accounting, infra}단방향만 허용 accounting <-> infra직접 참조 금지- LLM은 개발(코드 생성) 단계에서만 사용, 런타임에는 포함하지 않음
README.md: 프로젝트 소개, 실행 방법, 현재 상태CLAUDE.md: 상위 개발 지침, 문서 갱신 규칙, 완료 조건docs/guidelines/: 백엔드, 인증/권한, 프론트엔드, Excel 작업별 상세 규칙docs/guidelines/agent_workflow.md,docs/agents/: 멀티에이전트 작업 오케스트레이션 기준과 역할 카드docs/DECISIONS.md: 구조/정책 결정 기록docs/KNOWN_ISSUES.md: 아직 해소되지 않은 제약과 우회docs/PROJECT_CONTEXT.md: 프로젝트 배경, 사용자, 문제 정의docs/PROJECT_STRUCTURE.md: 파일 단위 프로젝트 구조와 모듈별 역할- 엔트리포인트/초기화 구조, API 엔드포인트, 데이터 모델, 테스트 범위의 1차 기준은 소스 코드다
- 파일 단위 상세 구조와 모듈별 역할은
docs/PROJECT_STRUCTURE.md참조
| 영역 | 현재 상태 | 모듈 |
|---|---|---|
| 사업 관리 | 사업/기간 CRUD, 담당자 매핑, 기본 회계 흐름 동작 | accounting |
| Forecast / 실적 / 입금 | 핵심 계산과 CRUD 동작, 회귀 테스트 존재 | accounting |
| 업체 / 사용자 / 시스템 | 사용자, 업체, 설정, 역할 관리 동작 | common |
| 자산 | 목록/등록/상세/부속 정보(Alias 포함), 편집 모드, 역할 연계 기능 동작 | infra |
| IP 인벤토리 / 포트맵 / 업체 | 화면과 API는 동작하나 검증과 UX 보강이 더 필요 | infra |
| 정책 | DB/API 존재, UI 접근 경로 제거됨 (향후 재설계 예정) | infra |
| 배치도 | 센터/전산실/랙 트리 + 상면도 격자 + 랙 드래그 배치 동작 | infra |
| 제품 카탈로그 | CRUD, 최종분류/분류 메타 연결, 자산 연동 동작 | infra |
인프라모듈의 세부 페이지 상태와 우선순위는 active roadmap 문서를 기준으로 본다.
/periods,/assets,/audit-history,/product-catalog는 동작/ip-inventory,/port-maps,/contacts는 부분 동작/physical-layout배치도는 부분 동작 (트리+격자+랙배치)
상세 내용은
docs/KNOWN_ISSUES.md참조.
- 회계모듈 감사 로그 서비스 연동 미완료 (인프라모듈은 연동 완료)
- 동시 편집 충돌 방지(낙관적 잠금) 미구현
- 발행일 휴일 조정 미적용
- 대량 데이터(1000행 이상) Excel Import 성능 미검증
- 인프라모듈의 일부 화면은 placeholder 또는 부분 구현 상태