분산된 입출고 관리와 물류 자동화를 하나의 서비스로 연결한다. C-0은 전체 계약을 정의하고 C-1~C-4가 화면·규칙·예외·데이터 처리를 상세화한다.
이 문서는 향후 개발할 서비스의 명세다. 현재 프로토타입은 예시 체험이며, 기존 JSON 저장 코드와 아래 관계형 스키마가 동일하게 구현됐다고 보지 않는다.
항목 정의 배경 엑셀·Slack·별도 캘린더·개인 PC 자동화로 나뉜 업무를 하나의 웹사이트에 통합한다. C의 AS-IS는 공유 시트와 Slack이며 Notion 단계가 아니다. 제공 기능 공통 상품 기준, 상품별 재고·이력, 요청 단위 입출고, 승인·변경·일정, 파일 가공·비용 비교, 운영 기준 관리 환경 전사 사용자 브라우저 / 내부 계정 / 서버 업무 저장 + 브라우저 파일 가공 / 예시 데이터로 초기 체험 목적 누락·혼재·반복 확인을 줄이고 담당자와 요청자가 같은 업무 상태·일정을 확인하게 한다. 목표 요청 커뮤니케이션 오류 이전 대비30% 감소 / 탐색 효율30% 증가 / 수정·상태 등 중간 과정 효율20% 증가 / 웹 접근으로 온보딩 개선
목표는 미달성 가설이다. 오류 = 요청정보 불일치로 재확인이 필요했던 건, 탐색 = 동일 과제의 완료 시간, 중간 과정 = 수정 접수~반영 소요시간으로 측정하는 안을 제안한다. 기준선과 비교 기간은 운영 전 합의한다.
접근 근거 관찰한 문제 개발 방향 물류팀 운영 경험·동료 인터뷰 여러 행 중 어디까지 하나의 요청인지 불명확하고 작성·논의·완료를 구분하기 어려움 요청 헤더+상품 행 / 명시 상태 / 담당자 지정 운영·재무의 정보 확인 시트·Slack·캘린더가 분리되고 상품 히스토리를 직접 탐색 상품별 수불·변경 이력 / 승인 요청에서 일정 파생 자동화 사용 경험 로컬 경로 설정·파일 가공·계약 기준이 분산 웹에서 파일 선택·검수 / 공통 상품·요금 기준 조회 현재 프로토타입 시현 정상 흐름에서 요청·논의 상태와 배송 일정이 함께 보이는 점에 긍정 반응 실제 운영 성과로 확대 해석하지 않고 운영 전 검수 진행
AI가 도울 일 문서·코드 초안, 반복 구현과 오류 수정 지원. 실제 주문의 규칙 결정이나 최종 출고 승인을 대신하지 않는다.
사람이 책임질 일 현장 인터뷰·우선순위·예외 기준·원본/가공 결과 대조·가격/재고/연락처 최종 검수.
역할 가능한 행동 제약 요청자 상품 검색·발번, 본인 초안 작성·수정·삭제, 요청 제출, 공유된 요청·전사 일정 조회, 본인 요청의 수정 제안 타인 초안·상품 기준 수정·승인·완료·운영 요금·자동화 접근 불가 물류 담당자 공유 요청 검토·승인·변경·완료, 재고·상품 운영정보 수정, 자동화·비용 비교, 업무 메모 계정 생성·비밀번호 초기화·운영 계약 기준 변경 불가 물류 어드민 물류 담당자 기능 전체, 계정 생성·비밀번호 재설정, 담당자 재배정·단계 변경, 3PL·요금·상시판매 기준 관리 완료 재고를 상태값만 바꿔 취소하는 우회는 금지
정책 개발 지시 초안 요청자는 본인 입력완료만 수정·삭제. 타인 초안은 전체보기에서도 노출하지 않는다. 요청 이후 요청자는 직접 값을 바꾸지 않고 수정 요청을 낸다. 실제 수정·승인·완료는 물류 역할이 처리한다. 전사 공유 승인된 입출고 일정은 전사 조회. 다른 사용자의 제출된 요청 조회 가능. 원본 파일·민감한 배송 정보는 자동화 역할에만 제공한다. 표시 재고 null과0 구분, 입력 실패 위치 표시, 완료 이력 보존. 회사 표기는 Knowmerce. 메모 공유 요청에 접근 가능한 구성원은 메모 작성 가능. 작성자·시간·내용을 보존한다.
상위 메뉴 화면 접근 홈 요청자4버튼 + 전사 캘린더 축약 / 물류 대시보드 전체 인벤토리 목록·검색 / 발번 / 상품 상세·변경·수불 이력 조회 전체 / 운영정보 수정 물류 입출고 신청 입고·출고 팝업 / 초안·바로 요청 전체 입출고 프로젝트 전체·승인대기·입고·출고·완료·이슈 해결 중 / 상세·수정·메모 전체 / 처리 물류 전사 입출고 캘린더 다보내 입고/출고, 패박 입고/출고의4개 레인 전체 자동화(물류팀) 앨범·MD·당첨자 / 입력·조건·검수·비용·다운로드 물류 운영 기준 3PL·주소·요금·상시판매·계정 어드민
대시보드는 승인 대기 → 슬랙 논의 중 → 이슈 해결 중 → 수정 요청의 상태 카드가 해당 프로젝트 조건으로 이동한다. 이슈 아이콘은 빨간색이다.
요청자 상품 검색·필요시 발번 C-1: 공통 품번을 얻는다. 요청자 입출고 작성 → 저장 또는 바로 요청 C-2: 저장은 입력완료, 요청은 검토 대기. 물류 담당자 조건·3PL 확인 → 승인 C-2: 슬랙 논의 중, 일정·게시 연결. 물류 담당자 작업·협의 → 실제 수량 확인 → 완료 C-1·C-2: 재고·원장·상태를 원자적으로 처리. 물류 담당자 주문서 업로드 → 가공·검수 → XLSX C-3: 기준을 읽고 브라우저에서 처리. 어드민 3PL·요금·상품 포장 기준·계정 유지 C-4: 기준 변경 후 다음 계산부터 적용. 출고 요청과 재고 차감은 별개다. 요청이 먼저 올 수 있으므로 재고 부족은 요청 단계에서 경고하고, 실출고 완료 단계에서는 실제 재고를 재검사한다.
브라우저 업무 화면과 파일 파싱·가공·검수·XLSX 생성. 자동화 입력/결과는 메모리에만 유지하고 새로고침 시 초기화 안내.
업무 API 계정·상품·요청·재고·3PL 기준을 인증된 역할로 조회·변경. 저장 시 관계와 현재 상태를 재검사.
관계형 업무 DB 아래16개 테이블의 논리 설계. 요청·상품 명세·재고 원자 처리. 작업 파일 백업/자동화 jobs 테이블 제외.
외부 연결 승인 후 서버가 Slack에 게시. 현재 프로토타입은 게시 초안/대기와 실제 연동을 구분. 원본 주문 파일은 Slack으로 자동 전송하지 않는다.
입력 상품·요청·기준 변경 브라우저 폼 → 서버 검증 → DB 저장 파생 승인·변경·취소 요청 상태 → 캘린더 조회와 Slack 게시 상태 가공 파일 + 읽기 전용 기준 브라우저 계산 → 사람 검수 → XLSX 다운로드 요구 ID 개발 지시 검수 기준 C0-R01 역할 기반 로그인·작업 메뉴를 제공한다. 클라이언트 숨김과 서버 권한 검사 일치 C0-R02 같은 상품·요청·3PL ID를 모든 모듈에서 공유한다. 요청1건 상품2개면 헤더1행·명세2행 C0-R03 승인·일정·이력의 상태를 한 요청에서 파생한다. 승인 후 일정1건, 변경 시 갱신, 취소 시 제외 C0-R04 브라우저 자동화 작업과 영구 업무 데이터를 분리한다. 원본 주문 파일·가공 작업 이력 DB를 새로 만들지 않음 C0-R05 공통 오류와 권한·동시 처리 응답을 정의한다. 실패 시 부분 저장·거짓 성공·중복 수불 없음 C0-R06 단계별 인수 기준과 초기 데이터로 도입한다. C-1을 선행하고 모듈별 테스트와 사용자 검수
상태 의미 후속 동작 입력완료 저장한 초안 본인 수정·삭제·요청 / 캘린더·재고 영향 없음 물류팀 확인 중 제출 후 검토 대기 물류 담당자 승인 / 아직 일정 미등록 슬랙 논의 중 물류 승인 이후 협의 전사 일정 생성·Slack 게시 / 배송·완료·이슈·취소로 진행 배송 중 / 출고중 출고 작업·운송 진행 운송 정보·출고 완료 예상 시점 기록 입고 완료 / 출고 완료 물류팀이 실제 수량을 확인 상품별 실수량과 수불을 함께 확정 / 직접 덮어쓰기 금지 이슈 해결 중 누락·업체 협의 등으로 중단 메모·정보 보완 후 진행 상태 선택 취소 승인된 미완료 요청을 중단 확인 팝업 / 일정 제외 / 재고 변화 없음 / 기록 보존
이벤트 DB 캘린더·Slack 저장 입력완료 헤더+상품 명세 미노출·미게시 요청 물류팀 확인 중 업무 목록에 표시, 승인 일정 미생성 승인 담당자·3PL 확정, 슬랙 논의 중 요청에서 일정 파생, 서버 게시 후 ts/status 저장 변경 승인 허용된 현재값·상품 수량 적용 같은 요청의 일정 갱신, 기존 Slack 게시 갱신 또는 후속 게시 취소 취소 상태·사유, 대기 수정 무효 일정 제외, Slack에 취소 반영 완료 상품별 실수량·원장·현재고·상태 확정 기존 일정은 과거 기록으로 남김
요청 A에 상품 aaa·bbb를 담으면 logistics_requests1행과 request_lines2행을 만든다. 두 행은 기존 products를 참조하며 상품을 복제하지 않는다.
actors 계정·역할 product_projects 상품 프로젝트 products 상품·sku_number warehouses 3PL·주소·기본요금 product_warehouses 상품·3PL 매핑 inventory_balances 현재고·미확인 logistics_requests 요청 헤더 request_lines 요청 상품 N행 inventory_movements 수불·상품변경 이력 warehouse_shipping_rates 국가·무게별 운임 request_changes 수정요청 헤더 request_change_lines 수정요청 상품 project_comments 업무 메모 request_status_history 상태 이력 recurring_rules 상시판매 규칙 recurring_rule_lines 규칙 대상 상품 연결선은 참조 관계를 요약한다. 카디널리티·필수 여부·삭제 제약은 아래 데이터 사전과 각 기능 문서의 API 계약을 우선한다.
actors 필드/제약 타입 논리 정의 id TEXT PRIMARY KEY NOT NULL login_id TEXT COLLATE NOCASE NOT NULL name TEXT NOT NULL role TEXT NOT NULL team TEXT NOT NULL password_hash TEXT NOT NULL password_salt TEXT NOT NULL created_at TEXT NOT NULL UNIQUE (login_id)
product_projects 필드/제약 타입 논리 정의 id TEXT PRIMARY KEY NOT NULL name TEXT NOT NULL created_at TEXT NOT NULL
products 필드/제약 타입 논리 정의 id TEXT PRIMARY KEY NOT NULL sku_number TEXT NOT NULL project_id TEXT NOT NULL REFERENCES product_projects(id) ON DELETE RESTRICT name TEXT NOT NULL ownership TEXT NOT NULL category TEXT NOT NULL barcode TEXT pack_capacity INTEGER charge_weight_g INTEGER is_gift INTEGER NOT NULL created_by TEXT NOT NULL REFERENCES actors(id) ON DELETE RESTRICT created_at TEXT NOT NULL UNIQUE (sku_number) CHECK (pack_capacity IS NULL OR pack_capacity > 0) CHECK (charge_weight_g IS NULL OR charge_weight_g > 0)
product_warehouses 필드/제약 타입 논리 정의 id TEXT PRIMARY KEY NOT NULL product_id TEXT NOT NULL REFERENCES products(id) ON DELETE RESTRICT warehouse_id TEXT NOT NULL REFERENCES warehouses(id) ON DELETE RESTRICT wms_sku TEXT UNIQUE (product_id, warehouse_id) UNIQUE (warehouse_id, wms_sku)
logistics_requests 필드/제약 타입 논리 정의 id TEXT PRIMARY KEY NOT NULL request_num INTEGER NOT NULL request_name TEXT NOT NULL direction TEXT NOT NULL requester_id TEXT NOT NULL REFERENCES actors(id) ON DELETE RESTRICT assignee_id TEXT REFERENCES actors(id) ON DELETE RESTRICT warehouse_id TEXT REFERENCES warehouses(id) ON DELETE RESTRICT status TEXT NOT NULL scheduled_at TEXT NOT NULL expected_end_at TEXT completed_at TEXT inbound_method TEXT inbound_attribute TEXT outbound_reason TEXT recipient TEXT phone TEXT postal_code TEXT address TEXT transport_info TEXT origin_country TEXT note TEXT created_at TEXT NOT NULL UNIQUE (request_num)
Slack 게시를 위해 slack_message_ts / slack_delivery_status / slack_last_error(nullable) 추가를 제안한다. 알림·정기실행 전용 테이블은 추가하지 않는다.
request_lines 필드/제약 타입 논리 정의 id TEXT PRIMARY KEY NOT NULL request_id TEXT NOT NULL REFERENCES logistics_requests(id) ON DELETE RESTRICT product_id TEXT NOT NULL REFERENCES products(id) ON DELETE RESTRICT line_no INTEGER NOT NULL sku_number_snapshot TEXT NOT NULL name_snapshot TEXT NOT NULL requested_qty INTEGER NOT NULL actual_qty INTEGER UNIQUE (request_id, product_id) UNIQUE (request_id, line_no) CHECK (requested_qty >= 0) CHECK (actual_qty IS NULL OR actual_qty >= 0)
request_changes 필드/제약 타입 논리 정의 id TEXT PRIMARY KEY NOT NULL request_id TEXT NOT NULL REFERENCES logistics_requests(id) ON DELETE RESTRICT requested_by TEXT NOT NULL REFERENCES actors(id) ON DELETE RESTRICT reason TEXT NOT NULL proposed_scheduled_at TEXT status TEXT NOT NULL reviewed_by TEXT REFERENCES actors(id) ON DELETE RESTRICT reviewed_at TEXT created_at TEXT NOT NULL
request_change_lines 필드/제약 타입 논리 정의 id TEXT PRIMARY KEY NOT NULL change_id TEXT NOT NULL REFERENCES request_changes(id) ON DELETE RESTRICT request_line_id TEXT NOT NULL REFERENCES request_lines(id) ON DELETE RESTRICT proposed_qty INTEGER NOT NULL UNIQUE (change_id, request_line_id) CHECK (proposed_qty >= 0)
project_comments 필드/제약 타입 논리 정의 id TEXT PRIMARY KEY NOT NULL request_id TEXT NOT NULL REFERENCES logistics_requests(id) ON DELETE RESTRICT actor_id TEXT NOT NULL REFERENCES actors(id) ON DELETE RESTRICT body TEXT NOT NULL created_at TEXT NOT NULL
request_status_history 필드/제약 타입 논리 정의 id TEXT PRIMARY KEY NOT NULL request_id TEXT NOT NULL REFERENCES logistics_requests(id) ON DELETE RESTRICT actor_id TEXT NOT NULL REFERENCES actors(id) ON DELETE RESTRICT from_status TEXT to_status TEXT NOT NULL reason TEXT created_at TEXT NOT NULL
warehouses 필드/제약 타입 논리 정의 id TEXT PRIMARY KEY NOT NULL name TEXT NOT NULL postal_code TEXT address TEXT NOT NULL address_detail TEXT contact_name TEXT contact_phone TEXT memo TEXT domestic_base_fee NUMERIC domestic_labor_fee NUMERIC overseas_labor_fee NUMERIC material_fee NUMERIC free_item_qty INTEGER extra_unit_fee NUMERIC extra_fee_cap NUMERIC created_by TEXT NOT NULL REFERENCES actors(id) ON DELETE RESTRICT created_at TEXT NOT NULL CHECK (domestic_base_fee IS NULL OR domestic_base_fee >= 0) CHECK (free_item_qty IS NULL OR free_item_qty >= 0)
warehouse_shipping_rates 필드/제약 타입 논리 정의 id TEXT PRIMARY KEY NOT NULL warehouse_id TEXT NOT NULL REFERENCES warehouses(id) ON DELETE RESTRICT country_code TEXT NOT NULL weight_from_g INTEGER NOT NULL weight_to_g INTEGER NOT NULL shipping_fee NUMERIC NOT NULL UNIQUE (warehouse_id, country_code, weight_from_g) CHECK (weight_from_g >= 0) CHECK (weight_to_g > weight_from_g) CHECK (shipping_fee >= 0)
inventory_balances 필드/제약 타입 논리 정의 product_warehouse_id TEXT PRIMARY KEY NOT NULL REFERENCES product_warehouses(id) ON DELETE RESTRICT quantity INTEGER verified_at TEXT updated_at TEXT NOT NULL CHECK (quantity IS NULL OR quantity >= 0)
inventory_movements 필드/제약 타입 논리 정의 id TEXT PRIMARY KEY NOT NULL product_warehouse_id TEXT NOT NULL REFERENCES product_warehouses(id) ON DELETE RESTRICT request_line_id TEXT REFERENCES request_lines(id) ON DELETE RESTRICT actor_id TEXT NOT NULL REFERENCES actors(id) ON DELETE RESTRICT movement_type TEXT NOT NULL quantity_delta INTEGER NOT NULL reason TEXT NOT NULL created_at TEXT NOT NULL
추가 설계 제안: change_payload_json(nullable)을 추가해 바코드·속성·보관처 변경의 전후값을 보존한다. 상품정보 변경은 quantity_delta=0으로 기록하고, 미확인 현재고를 0으로 확정하지 않는다.
recurring_rules 필드/제약 타입 논리 정의 id TEXT PRIMARY KEY NOT NULL name TEXT NOT NULL warehouse_id TEXT NOT NULL REFERENCES warehouses(id) ON DELETE RESTRICT created_by TEXT NOT NULL REFERENCES actors(id) ON DELETE RESTRICT
recurring_rule_lines 필드/제약 타입 논리 정의 id TEXT PRIMARY KEY NOT NULL rule_id TEXT NOT NULL REFERENCES recurring_rules(id) ON DELETE RESTRICT product_id TEXT NOT NULL REFERENCES products(id) ON DELETE RESTRICT UNIQUE (rule_id, product_id)
아이디 물류팀에서 발급한 ID
비밀번호 ••••••••
로그인
계정이 없는 경우 직접 물류팀에게 요청하세요
항목 처리 인증 서버에서 password_hash+salt 대조. 평문 비밀번호를 응답하거나 브라우저 저장소에 보관하지 않는다. 로그인 유지 방식은 서명된 HttpOnly 쿠키를 제안하며 actor_session 테이블은 추가하지 않는다. 삭제·바로 요청·취소 화면 확인 모달 후 처리. 실패 시 폼 입력 유지. 필수값·오류 400/422: 필드와 행 번호. 403: 권한. 404: 대상 없음. 409: 품번·상태 충돌. 통신 실패는 성공으로 표시하지 않는다. 재처리 업무 저장이 이미 성공했는지 조회 후 재시도. 완료 클릭 재시도는 상태 조건 검사로 중복 수불 차단. 암호 초기화 어드민이 새 비밀번호를 설정. credential_version·must_reset·is_active·actor_session을 논리 스키마에 추가하지 않는다.
제안 API 권한·동작 연결 문서 POST /auth/login · /logout 서버 인증/쿠키 만료. 데모 역할 전환과 운영 로그인은 구분 C-0 GET/POST /products · /inventory 상품·재고 기준, UNIQUE sku_number 재검사 C-1 POST /requests/:id/approve 물류 권한+현재 검토상태 확인 → 업무저장 성공 후 Slack 연결 C-2 POST /requests/:id/complete 조건부 상태 전환+상품별 원장/잔액의 단일 트랜잭션 C-2 GET /automation/reference 상품·운임 기준만 전달 / 업로드 파일 저장 API 없음 C-3 POST/PATCH /warehouses · /recurring-rules · /actors 어드민 권한 및 하위 참조 확인 C-4
API 경로는 개발 계약 제안이며 현재 코드의 act(action) 엔드포인트와 동일하다고 주장하지 않는다. revision/base_revision 컬럼 없이도 DB 트랜잭션과 현재 상태 조건 검사를 적용한다.
Slack 실패로 승인·캘린더를 롤백하지 않는다. 요청에 게시 실패 상태를 남기고 물류 담당자에게 재시도 버튼을 제공한다. ts가 있으면 기존 메시지를 갱신하며, ts 저장 전 전송 성공 여부가 불명확하면 담당자가 채널을 확인한 뒤 재시도한다. 자동 무한 재전송은 하지 않는다.
단계 도입 범위 완료 기준 C-0 용어·역할·상태·데이터 관계 합의 미확인 정책 분리, C1~4 계약 일치 C-1 품번·상품·현재고·이력, 최소 3PL 상품 기준과 기초 재고를 조회·검수 가능 C-2 요청·승인·일정·변경·완료 표준 요청을 실제 절차로 대조, 재고·일정 불일치 없음 C-3 브라우저 자동화·검수·XLSX 수작업 기준 파일과 수량·박스·금액 비교 C-4 운영 기준·계정·상시판매 조회 기준이 각 모듈과 동일하며 권한 위반 없음
리소스가 극도로 적으면 C-1부터 시작해 기존 시트의 당월 입출고를 수동 반영하고 Streamlit은 유지한다. 상품코드·현재고·당월 입출고·3PL 요금을 우선 이관하며 오래된 전량 이관은 전제하지 않는다.
테스트 ID 연결 요구 시나리오 기대 결과 C0-T01 C0-R01 요청자에게 관리자 변경 API 직접 호출 403, 저장 불변 C0-T02 C0-R02 요청1건에 상품2개 등록 헤더1행·명세2행, 상품 중복 생성 없음 C0-T03 C0-R03 승인→일정 변경→취소 일정 추가1회·갱신·제외 C0-T04 C0-R04 자동화 후 새로고침 파일 작업 미보존, 업무DB 불변 C0-T05 C0-R05 동일 완료를 두 번 요청 원장/재고1회만 반영 C0-T06 C0-R06 기초 데이터로 전체 정상 흐름 시현 사용자 검수와 미해결 항목 기록
구분 기준 사용자 확정 C-0~4 번호, 역할·상품 발번·입출고·캘린더·Slack 스펙, 단순화한 논리 DB, 파일 브라우저 처리 기존 산출물 참조 구 C-0 공통·구 C-1 입출고재고·구 C-2 자동화 명세를 최신5개로 재분리. 오래된 Slack 제외/이력 제외 문구는 사용하지 않음. 로컬 코드 확인 work/knowmerce-cloudflare/lib/model.ts, actions.ts, automation.ts, order-files.ts, accounts.ts. 공개 배포본보다 뒤의 로컬 기능이 존재. 데이터 모델 차이 현재 앱의 업무 JSON·세션·workspace revision은 구현 현황이다. 새 문서의16개 관계형 테이블이 적용됐다고 보지 않음. 추가 설계 제안 상품 메타데이터 전후값의 원장 change_payload_json, Slack 게시 상태3필드. 기존 요구인 상품변경 이력/Slack 게시를 저장할 최소 확장. 확인 필요 3PL 혼재 요청 분리 기준, 완료 후 보정, 실제 Slack 멘션 ID 매핑, 오류 목표의 측정 기준·운영 비교 기간
기존 배포 프로토타입 열기 ↗
배포 주소의 로그인 진입을 확인했다. 로컬에서 추가한 기능과 배포본은 차이가 있으며 이번 문서 작업에서 웹사이트를 다시 배포하지 않았다.