Files
dbx-main/AGENTS.md
T
king 89ad338024 fix(project): review fixes — access leaks, open paths, save safety, concurrency
- Subproject tasks via parent /tasks are re-filtered by current access (FULL/READ kept)
- PUT /api/projects/order: every id must be manageable; bad/duplicate ids -> 400, all-or-nothing
- Inbox, web alert popup, PC notifier open tasks via /project/t/{id}; embed=1 survives redirect;
  old /p/{home}?task= redirects READ users to the linked project
- Project page / snapshot / workload include the opened archived or sub project only
- Alerts: DB-side filters + oldest-first paging (no 50-row cut); badges counted without caps;
  my tasks keep every open task (completed capped)
- Meeting results: next-week meeting open, or own meeting open when no next meeting;
  header edits + result checks under row locks (FOR UPDATE / FOR SHARE)
- Inbox panel waits for the task window save (same retry/discard flow) before switching/closing;
  read failures stay unread
- Attachment upload removes only its own file on DB failure
- New project modal: create once, retry only failed member assignments
- update_task / update_project: locked-row validation in one transaction; completion hints from real transition
- Creator added as explicit member when another owner is chosen
- _once lock lifetime managed by refcount (no leak on failure)
- Section default assignee must still be a registered project user; follower add uses can_assign
- Docs (PROJECT_MODULE 6-15, help), tests (DB-less, real PostgreSQL, jsdom, Chrome)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 11:08:56 +09:00

8.5 KiB

main-app ERP 프로젝트 작업 기준

이 문서는 Codex가 이 저장소에서 작업할 때 가장 먼저 확인하는 기준 문서입니다. 작업 시작 전, 아래 "반드시 먼저 읽을 문서"를 모두 확인한 뒤 작업을 시작합니다.


반드시 먼저 읽을 문서

Codex는 이 저장소에서 작업을 시작하기 전에 반드시 아래 문서를 순서대로 읽고 맥락을 확보한 뒤 작업한다.

  1. docs/PROJECT_OVERVIEW.md — 프로젝트 정의, 기능 범위, 연동 대상
  2. docs/SERVER_ARCHITECTURE.md — 서버 구성도와 네트워크 흐름
  3. docs/DATABASES.md — PostgreSQL DB 구성과 명명 규칙
  4. docs/DEPLOYMENT.md — 배포 경로, 서비스 실행 방식, 복구 절차

문서 간 내용이 충돌하면 위의 우선순위(1 → 4)를 따른다.


프로젝트 한 줄 정의

main-app은 DBX ERP 시스템의 메인 프로젝트(허브) 이다.

담당 영역:

  • 주문관리
  • 상품코드 매칭
  • 재고관리
  • CS관리
  • 반품관리
  • 외부 쇼핑몰 API 연동 (카페24, 네이버 스마트스토어, 사방넷 등)
  • 개인경비 (app/modules/expense/, expense_db)
  • 쿠팡 밀크런 (app/modules/cupang/, cupang_db) — 출고 달력/박스 입수량 계산/입고센터 관리, 상품은 itemcode_db 읽기 전용
  • 휴가 관리 (app/modules/vacation/, vacation_db) — 월간 달력(구글식 bar)/연차·반차 신청/승인 워크플로/공휴일·연차 설정. 권한키 vacation·vacation_approver
  • 말레이시아 창고 재고관리 (app/modules/malaysia/, malaysia_stock_db) — 낱개(MT/MX/MZ) 입출고·조정, 세트(MY) BOM, 일일 재고조사(세트→낱개 자동 분해), 현재고 현황. 뚜껑(MD-)은 재고 집계 제외 — 단, 창고 랙에는 위치 확인용으로 배치 가능(store.LID_ITEMS). 상품은 itemcode_db 읽기 전용. 권한키 malaysia
  • 말레이시아 배송 (app/modules/dispatch/, dispatch_db) — TikTok·Shopee 출고관리. 플랫폼별 데이터 엑셀 업로드(TikTok=03_TikTok_Order_Export.xlsx, Shopee=Packing List.Doorstep Delivery.xlsx) → 1박스=1카드 출고 작업 리스트·SKU 피킹 요약·Kagayaku 전달표 자동 생성. 1박스 묶음 기준 Package ID > Tracking ID > Order ID, 같은 박스 같은 SKU 합산. 작업 상태 토글(dispatch_logs 기록). 받는 사람 이름/전화/주소는 박스 단위로 저장(작업 카드 표시 + 출고 엑셀 생성용 — 개인정보). 배치 다운로드 zip 에 업로드 원본 + 취합 출고 엑셀(YYYY.MM.DD(Ddd)_tictoc|shopee.xlsx) 포함. 엑셀은 openpyxl 파싱/생성. 권한키 dispatch. 상세는 docs/DISPATCH_MODULE.md
  • 카페24 상품관리 (app/modules/cafe24/, cafe24_db) — 카페24 관리자에 들어가지 않고 상품 상세페이지(description HTML) 조회·편집·즉시적용·예약적용·자동복원·버전 롤백·일괄수정. 카페24 OAuth/API 클라이언트는 향후 주문관리와 공유하기 위해 공통 계층 app/integrations/cafe24/ 에 둔다 — 라우터에서 httpx/requests 직접 호출 금지. 토큰은 Fernet 암호화 저장(CAFE24_TOKEN_SECRET), 로그/화면에 토큰·시크릿 절대 미출력. 쓰기 직전 항상 카페24 현재 HTML 을 다시 읽어 BACKUP revision 생성(로컬 값을 현재값으로 가정 금지). 예약은 DB 저장 + 별도 worker(app/modules/cafe24/worker.py, compose 서비스 dbx-cafe24-worker)가 처리 — 웹 프로세스에서 대기하지 않는다. 권한키 cafe24(연결/해제는 admin 전용). 상세는 docs/CAFE24_MODULE.md
  • 프로젝트 관리 (app/modules/project/, project_db) — 아사나식. 프로젝트/서브프로젝트(self-FK parent_id, CASCADE)·업무(tasks: 담당자·우선순위·시작/마감)·진행단계(project_stages 칸반, 새 프로젝트는 섹션 없이 시작)·멤버 배정(project_members)·활동이력(project_activity). 메인 뷰 달력(FullCalendar)/타임라인(vis-timeline) 버튼 토글 + 보드(드래그로 단계 이동)/리스트. 진입 권한키 project(관리자 페이지 토글로 직원별 부여, admin 자동). 권한은 등급(수퍼관리자 > Admin > Pro user > User, 2026-10-12)과 멤버십 기준 — 표는 docs/PROJECT_MODULE.md 6-14, 공통 판단 access.py(관리자도 멤버가 아니면 프로젝트가 안 보임, 예외는 수퍼관리자). 멤버 배정 후보는 project 권한 보유 등록 사용자에서 자동 목록(GET /project/api/assignable-users). 업무 배정·완료 시 관리자에게 메일(app/mail.py stdlib smtplib, SMTP_*+PROJECT_NOTIFY_EMAIL env, 미설정 시 조용히 skip, BackgroundTasks 비동기). 상세는 docs/PROJECT_MODULE.md

상세는 docs/PROJECT_OVERVIEW.md.

  • 자산관리 (app/modules/asset/, asset_db) — 사무집기·전산장비 등록/배정/반납/상태·구매/보증·이력. HWiNFO XML 분석·사양 조회·이전 보고서와 원본 보존. 권한키 asset, 환경변수 ASSET_DB_URL. 사진 등록/갤러리·모니터 자산 조회/등록/연결·수퍼 관리자 삭제(이력/원본 보존). 기존 설치는 마이그레이션 asset_db_002_photos_monitors.sql 필요. DB 미설정 시 저장 비활성, XML 분석 미리보기 가능. DB 생성은 사용자가 서버 명령으로 직접 진행. 상세 docs/ASSET_MODULE.md.

개발 원칙

  • 기존 코드를 수정하기 전 관련 파일을 먼저 읽고 구조를 파악한다.
  • 위험 명령은 반드시 사용자 확인 후 실행한다 (아래 "위험 명령" 절 참고).
  • .env, API 키, DB 비밀번호, OAuth Secret, 토큰은 절대 Git에 올리지 않는다.
  • 신규 DB가 필요하면 서버에서 실행할 명령을 제공하고 생성은 사용자가 직접 진행한다 (사용자 지시: 2026-10-06). DB명은 반드시 _db로 끝낸다 (예: inventory_db). 대상 서버·현재 DB·백업 상태와 생성 후 스키마·앱 계정 권한·연결 확인 명령을 함께 제공한다. 기존 DB 삭제·덮어쓰기 등 위험 명령은 아래의 별도 승인 원칙을 그대로 따른다.
  • 예전 문서/코드의 orderlist_app은 현재 기준 orderlist_db이다. 발견 시 수정 대상.

위험 명령 (사용자 확인 없이 실행 금지)

아래 명령은 반드시 사용자에게 의도를 설명하고 명시적 승인을 받은 뒤 실행한다.

분류 명령 예시
파일 삭제 rm -rf, Remove-Item -Recurse -Force
DB 파괴 DROP DATABASE, DROP TABLE, DROP SCHEMA
데이터 삭제 TRUNCATE, 조건 없는 대량 DELETE, UPDATE
Docker 파괴 docker volume rm, docker volume prune, docker system prune -a --volumes
Git 파괴 git reset --hard, git push --force, git clean -fd, git branch -D
운영 초기화 운영 DB 덤프 덮어쓰기, 마이그레이션 롤백

원칙:

  1. 실행 전 현재 상태 확인 명령을 먼저 보여준다 (예: docker ps, \l, git status).
  2. 백업 존재 여부와 위치를 명시한다.
  3. 실행 후 결과 확인 절차를 같이 제시한다.

서버 작업 원칙

  • 배포, DB 복구, Docker 작업 전에는 현재 상태 확인 명령을 먼저 제안한다.
  • PostgreSQL 작업 전에는 DB명, 컨테이너명, 포트, 백업 위치를 확인한다.
  • 운영 서버 경로와 개발 PC 경로를 혼동하지 않는다.
    • 개발 PC: G:\내 드라이브\프로젝트\Main-app
    • 운영 서버 (main-app): /opt/www/main ← 본 프로젝트 경로
    • 참고용 (같은 호스트 내 다른 서비스 경로): /opt/dbx-corm, /opt/dbx-orderlist
    • 명령 예시·문서 작성 시 main-app 경로는 반드시 /opt/www/main 사용. 상세는 docs/DEPLOYMENT.md.

환경 변수 / 비밀값

  • .env, .env.local, .env.production 은 Git에 절대 커밋하지 않는다.
  • 예시 파일(*.example)만 커밋한다.
  • 비밀값 유출이 의심되면 즉시 회전(rotate)을 권고한다.
  • 신규 환경변수 추가 시 *.example 파일과 본 문서(또는 docs/DEPLOYMENT.md)에 변수 설명을 함께 갱신한다.

디렉터리 구조 (요약)

Main-app/
├─ app/                  FastAPI 앱 소스
├─ docs/                 운영/설계 문서 (작업 전 필독)
├─ scripts/              배포·유지보수 스크립트
├─ skills/               Codex 규칙/스킬
├─ docker-compose.yml    운영 컴포즈
├─ docker-compose.local.yml  로컬 컴포즈
├─ Dockerfile
├─ requirements.txt
└─ AGENTS.md             ← 이 문서