Repository Guidelines

Codex Autonomous Execution Policy

This repository is used for ec-demo feature development and portfolio demonstration. Codex should work autonomously as much as possible while protecting source code, data, secrets, and external environments.

Basic Policy

• In general, Codex may autonomously run commands required for investigation, implementation, verification, testing, formatting, and local development.
• User confirmation should be required only for dangerous operations, destructive changes, external publication, secret exposure, production/VPS impact, or irreversible changes.
• Before making changes, inspect related files and understand the impact scope.
• After implementation, run build, test, lint, typecheck, or smoke checks where applicable.
• Prioritize readability, maintainability, and explainability because this project is also used as a career portfolio.
• If uncertainty is minor and the impact is limited, make a reasonable assumption and proceed autonomously.
• If a change involves major architecture, specification, external exposure, permissions, or production-like environments, ask before proceeding.

Allowed Without Confirmation

Codex may run non-dangerous commands without asking for user confirmation.

Investigation / Read-only Checks

• File listing and file content inspection
• grep, rg, find, and similar search commands
• git status
• git diff
• git log
• git branch
• git show
• gh status
• gh repo view
• gh issue list
• gh issue view
• gh pr list
• gh pr view
• gh pr diff
• gh pr checks
• gh workflow list
• gh run list
• gh run view

Development / Verification

• Dependency installation
• Build commands
• Test commands
• lint commands
• formatter commands
• typecheck commands
• local development server startup
• local verification scripts
• smoke-test scripts

Examples:

• npm install
• npm ci
• npm run dev
• npm run build
• npm run test
• npm test
• npm run lint
• npm run format
• npm run typecheck
• pnpm install
• pnpm dev
• pnpm build
• pnpm test
• pnpm lint
• mvn clean package -DskipTests
• mvn test
• ./scripts/test-saga.sh 1 1

Local Docker Operations

Local development Docker operations are allowed without confirmation as long as they do not delete persistent data or affect production/VPS/external environments.

Allowed examples:

• docker ps
• docker images
• docker logs
• docker compose ps
• docker compose logs
• docker compose up
• docker compose up -d
• docker compose build
• docker compose restart
• docker compose stop

Git / GitHub Operations

Non-dangerous Git and GitHub operations are allowed without confirmation.

Allowed examples:

• git checkout -b <branch>
• git switch -c <branch>
• git add <files>
• git commit
• gh issue create
• gh issue edit
• gh pr create

Must Ask Before Running

Codex must ask for user confirmation before running any dangerous operation.

Destructive File / Git Operations

• rm -rf
• Mass file deletion
• Deleting non-generated source/config files
• git reset --hard
• git clean -fd
• git rebase
• Any operation that rewrites existing history
• Any operation that is difficult to undo

GitHub / External Publication Operations

• git push
• git push --force
• gh pr merge
• gh workflow run
• gh release create
• gh repo delete
• GitHub repository settings changes
• Branch protection changes
• Actions secrets changes
• Deploy key changes
• Any permission, visibility, or publication-scope change

DB / Data Operations

• DB deletion
• DB initialization that removes existing data
• Existing data deletion
• Migrations that modify existing data
• Operations affecting production, shared, or external data

Docker / Infrastructure Operations

• docker compose down -v
• docker volume rm
• docker system prune
• docker builder prune
• Docker volume deletion
• Any operation that deletes persistent data
• Any operation that affects VPS, production, or external services

Secrets / Sensitive Information

• Displaying .env contents
• Displaying API keys
• Displaying access tokens
• Displaying passwords
• Displaying full environment variables
• Displaying full logs that may contain secrets

When secrets are needed for troubleshooting, check only whether variables exist, and mask actual values.

Cost / Account / Permission Impact

• Deployment to external services
• Operations that may incur cost
• Account changes
• Permission changes
• Production environment changes

Completion Report

After work is completed, report the following briefly:

• What was changed
• Files changed
• Main commands executed
• Build/test/lint/smoke-check results
• Remaining risks or follow-up items

Project Structure & Module Organization

• apps/bff: Backend-for-Frontend (REST/WebSocket, auth/session handling).
• apps/services/*: Domain microservices (order-service, payment-service, storage-service, account-service, alert-service, es-service).
• apps/web: Vue 3 + TypeScript frontend (Vite).
• platform/docker/local: local middleware stack (MySQL/Redis/Seata; optional Kafka/Elasticsearch).
• platform/docker/demo: VPS/demo deployment compose files.
• docs/adr, docs/architecture, docs/runbook: architecture decisions and operational docs.
• scripts/: flow and smoke-test utilities (for example, scripts/test-saga.sh).

Build, Test, and Development Commands

• cd platform/docker/local && docker compose up -d: start required local middleware.
• docker compose --profile kafka --profile elastic up -d: add optional Kafka/Elasticsearch.
• mvn clean package -DskipTests: build all backend modules.
• mvn test: run backend tests across modules.
• mvn spring-boot:run -pl apps/bff: run a single service (swap module path as needed).
• cd apps/web && pnpm install && pnpm dev: run frontend in development.
• cd apps/web && pnpm build: build frontend production assets.
• ./scripts/test-saga.sh 1 1: quick order/Saga flow smoke check.

Coding Style & Naming Conventions

• Java baseline is 21; keep service code aligned with Hybrid Hexagonal layering: web -> application -> domain <- gateway.
• Do not place Spring/DB framework annotations or infrastructure logic in domain.
• Follow Google Java Style (4-space indentation, clear class names).
• Frontend uses TypeScript + Vue SFCs with 2-space indentation; use PascalCase component/view file names (for example, CheckoutView.vue).
• Name tests with suffixes like *Test, *IntegrationTest, or *UnitTest.

Testing Guidelines

• Backend tests use Spring Boot Test (JUnit 5), with RestAssured and spring-kafka-test where needed.
• Run all tests with mvn test; run module tests with mvn test -pl apps/services/order-service.
• For Saga/payment changes, cover happy path, idempotency, and compensation/failure paths.
• No enforced coverage gate is defined; new behavior should include regression tests.

Commit & Pull Request Guidelines

• History follows mostly Conventional Commit prefixes: feat:, fix:, refactor: (scopes like feat(search): ... are encouraged).
• Keep commits focused to one logical change and mention the affected module.
• PRs should include: summary, impacted services, local verification commands/results, config/env updates, and UI screenshots for frontend changes.
• Link related issue/ADR when changing architecture or cross-service contracts.

Security & Configuration Tips

• Never commit secrets from .env or apps/bff/src/main/resources/serviceAccountKey.json.
• Use ./init.sh pull to sync local env files, then verify /actuator/health endpoints before running integration flows.

Docker Environment Configuration Rules

BASEPATH Rule

• All middleware config files must be placed under BASEPATH, NOT in the repository
• Default BASEPATH: /Users/wangjw/Dev/_Env/_demo/seata-mode
• Environment variable: export BASEPATH=/path/to/your/env

Config File Management

1. Source config templates are stored in platform/docker/demo/conf/
2. If config does not exist in BASEPATH, copy from source
3. Never commit runtime data or environment-specific configs to the repository

BASEPATH Directory Structure

${BASEPATH}/
  mysql/
    conf/my.cnf          # MySQL configuration
    data/                # MySQL data files
    log/                 # MySQL logs
  seata/
    conf/application.yml # Seata server configuration
    logs/                # Seata logs
  redis/
    conf/redis.conf      # Redis configuration
    data/                # Redis persistence
  kafka/
    data/                # Kafka data
  elasticsearch/
    data/                # Elasticsearch indices
  mongodb/
    data/                # MongoDB data
  minio/
    data/                # MinIO object storage

Setup Process

cd platform/docker/demo
export BASEPATH=/Users/wangjw/Dev/_Env/_demo/seata-mode
./setup-env.sh  # Creates directories and copies configs if missing
docker compose -f docker-compose-demo-env.yml up -d

When Adding New Middleware

1. Add source config to platform/docker/demo/conf/<middleware>/conf/
2. Update setup-env.sh to copy the new config
3. Update docker-compose-demo-env.yml with ${BASEPATH}/<middleware>/conf/ volume mount
4. Update this document with the new directory structure

Docker Service Port Mapping Rules

Application Service Ports (Internal)

Service URL Configuration

• Docker コンテナ間通信は内部ポートを使用
• ホストからのアクセスは外部ポートを使用
• 環境変数例: ORDER_SERVICE_BASE_URL=http://ec-demo-order-service:8082

Common Mistakes to Avoid

1. ❌ localhost をコンテナ間通信に使用しない（コンテナ名を使用）
2. ❌ 外部ポートをコンテナ間通信に使用しない（内部ポートを使用）
3. ❌ application.yml のデフォルトポートと docker-compose のポートマッピングの不一致

nginx Proxy Configuration

• /ec-api/* → ec-demo-bff:8080 (BFF API)
• /ec-api/ws/* → ec-demo-bff:8080/ws/ (WebSocket)
• /ec-demo/* → 静的ファイル (フロントエンド)

Elasticsearch & MinIO Initialization

ES Index Setup

cd platform/docker/demo/elasticsearch
./init-es-products-index.sh

• インデックス products_v1 作成
• エイリアス products 設定
• CSV からプロダクトデータインポート

MinIO Image Upload

cd platform/docker/demo/elasticsearch
./init-upload-product-minio.sh

• バケット ec-demo 作成（public アクセス）
• product/images/ に画像アップロード

Full Demo Environment Setup Order

1. ./setup-env.sh - 設定ファイルコピー
2. docker compose -f docker-compose-demo-env.yml --profile kafka --profile elastic --profile mongo --profile minio up -d - ミドルウェア起動
3. ./init-es-products-index.sh - ES インデックス作成
4. ./init-upload-product-minio.sh - MinIO 画像アップロード
5. docker compose -f docker-compose-demo-app.yml --profile elastic up -d - アプリ起動