Add OMS WMS ERP platform

oms-wms-erp/GITHUB-SETUP.md

@@ -0,0 +1,481 @@
+# GitHub Setup Guide
+
+**Complete GitHub repository configuration for OMS·WMS·ERP**
+
+---
+
+## 1. Repository Settings
+
+### Basic Settings
+- **Repository Name**: `oms-wms-erp`
+- **Description**: Enterprise OMS·WMS·ERP Platform (Vue 3 + TypeScript)
+- **Visibility**: Private (internal use only)
+- **Default Branch**: `main`
+- **Squash merges**: Enabled (keep commit history clean)
+- **Auto-delete head branches**: Enabled (cleanup after PR merge)
+
+### Repository Collaborators
+
+Add team members with appropriate roles:
+
+| Role | Responsibility |
+|------|-----------------|
+| **Admin** | Release management, workflow updates, settings |
+| **Maintain** | Code review, PR approval, branch management |
+| **Triage** | Label management, issue assignment |
+| **Push** | Push to main, create branches, PR reviews |
+| **Pull** | Clone, pull, create issues/discussions |
+
+---
+
+## 2. Branch Protection Rules
+
+### Rule 1: Protect `main` Branch
+
+Navigate to: **Settings → Branches → Add rule**
+
+```
+Branch name pattern: main
+```
+
+Enable:
+- ✅ **Require a pull request before merging**
+  - Require approvals: 1
+  - Require review from code owners: Yes
+  - Dismiss stale pull request approvals: Yes
+
+- ✅ **Require status checks to pass before merging**
+  - Require branches to be up to date: Yes
+  - Required status checks:
+    - `lint` (ESLint)
+    - `test` (Unit tests)
+    - `build` (Production build)
+    - `storybook` (Storybook build)
+    - `accessibility` (A11y audit)
+
+- ✅ **Require code reviews**
+  - Require 1 approval minimum
+  - Require review from CODEOWNERS: Yes
+
+- ✅ **Require signed commits**: No (optional)
+
+- ✅ **Require resolution of conversations**: Yes
+
+### Rule 2: Protect `develop` Branch (if used)
+
+```
+Branch name pattern: develop
+```
+
+Enable:
+- ✅ Require PR before merge
+- ✅ Require 1 approval
+- ✅ Status checks (same as main)
+
+---
+
+## 3. CODEOWNERS File
+
+Create `.github/CODEOWNERS`:
+
+```
+# Root configuration
+* @frontend-team
+*.json @frontend-team
+*.yml @frontend-team
+
+# Components
+/src/components/primitives/ @frontend-lead
+/src/components/fields/ @frontend-team
+/src/components/composites/ @frontend-team
+
+# Stores & Services
+/src/stores/ @frontend-team
+/src/services/ @frontend-team
+
+# Tests
+/tests/ @qa-team
+
+# Documentation
+/docs/ @technical-writer
+DEVELOPMENT.md @frontend-lead
+README.md @frontend-lead
+```
+
+---
+
+## 4. GitHub Actions Secrets
+
+Navigate to: **Settings → Secrets and variables → Actions**
+
+### Required Secrets (None for public actions)
+
+- `CODECOV_TOKEN` (optional, for coverage reporting)
+  - Get from: https://codecov.io (if using Codecov)
+
+### Optional Secrets (for future phases)
+
+- `SENTRY_DSN` (error tracking)
+- `GA_ID` (analytics)
+- `NPM_TOKEN` (if publishing to npm)
+
+---
+
+## 5. Workflow Configuration
+
+### Workflows Location
+All workflows in `.github/workflows/`:
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| **ci.yml** | push (main/develop), PR | Lint → Test → Build → A11y |
+| **deploy-storybook.yml** | push (main) | Build & deploy to GitHub Pages |
+
+### Workflow Triggers
+
+**CI Workflow** (ci.yml)
+```yaml
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+```
+
+**Deploy Storybook** (deploy-storybook.yml)
+```yaml
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/components/**'
+      - '.storybook/**'
+```
+
+---
+
+## 6. GitHub Pages Deployment (Storybook)
+
+### Enable GitHub Pages
+
+Navigate to: **Settings → Pages**
+
+```
+Source: Deploy from a branch
+Branch: gh-pages (auto-created by deploy-storybook.yml)
+Folder: / (root)
+Enforce HTTPS: Yes
+```
+
+### Access Storybook
+
+After first deployment:
+```
+https://<username>.github.io/<repo-name>/
+```
+
+Example: `https://kjh2064.github.io/oms-wms-erp/`
+
+---
+
+## 7. Environment Setup
+
+### Development Environment
+
+1. **Clone repository**
+   ```bash
+   git clone https://github.com/<username>/oms-wms-erp.git
+   cd oms-wms-erp
+   ```
+
+2. **Copy environment file**
+   ```bash
+   cp .env.example .env.local
+   ```
+
+3. **Install & verify**
+   ```bash
+   make verify-step2
+   ```
+
+### CI/CD Environment
+
+Workflows run automatically on:
+- Every push to `main` or `develop`
+- Every pull request to `main` or `develop`
+
+No additional setup needed — GitHub Actions handles it.
+
+---
+
+## 8. PR Template
+
+Create `.github/pull_request_template.md`:
+
+```markdown
+## Description
+Brief description of changes.
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Related Issues
+Closes #(issue number)
+
+## Testing
+- [ ] Unit tests pass (npm run test:unit)
+- [ ] E2E tests pass (npm run test:e2e)
+- [ ] Storybook stories updated
+- [ ] No console errors
+
+## Checklist
+- [ ] Code follows project style (npm run lint passes)
+- [ ] Documentation updated
+- [ ] All tests passing
+- [ ] No new warnings
+- [ ] Accessibility verified (axe-core)
+
+## Screenshots (if applicable)
+Add screenshots for UI changes.
+```
+
+---
+
+## 9. Issue Templates
+
+Create `.github/ISSUE_TEMPLATE/bug_report.md`:
+
+```markdown
+---
+name: Bug Report
+about: Report a bug
+title: '[BUG] '
+labels: bug
+---
+
+## Description
+Brief description of the bug.
+
+## Steps to Reproduce
+1. Step 1
+2. Step 2
+3. Step 3
+
+## Expected Behavior
+What should happen.
+
+## Actual Behavior
+What actually happened.
+
+## Screenshots
+If applicable, add screenshots.
+
+## Environment
+- Node version: (e.g., 18.0.0)
+- Browser: (e.g., Chrome 120)
+- OS: (e.g., macOS)
+```
+
+Create `.github/ISSUE_TEMPLATE/feature_request.md`:
+
+```markdown
+---
+name: Feature Request
+about: Suggest an enhancement
+title: '[FEATURE] '
+labels: enhancement
+---
+
+## Description
+Brief description of the feature.
+
+## Motivation
+Why is this feature needed?
+
+## Proposed Solution
+How should it work?
+
+## Alternatives
+Other possible approaches?
+```
+
+---
+
+## 10. Monitoring & Maintenance
+
+### Check Workflow Status
+
+1. **GitHub Actions Dashboard**
+   ```
+   https://github.com/<username>/oms-wms-erp/actions
+   ```
+
+2. **View workflow run details**
+   - Click workflow name
+   - See jobs and logs
+   - Diagnose failures
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Build timeout | Increase timeout or optimize dependencies |
+| npm install fails | Check internet connection, clear npm cache |
+| Port already in use | Change port in vite.config.ts |
+| Test flakiness | Retry test, check for async issues |
+
+### Monitoring
+
+- **codecov.io** (optional) - Track test coverage over time
+- **GitHub Insights** - Monitor pull requests, contributors
+- **GitHub Pages** - Monitor Storybook deployment status
+
+---
+
+## 11. Team Workflow
+
+### Feature Branch Workflow
+
+```
+1. Create feature branch
+   git checkout -b feat/component-name
+
+2. Develop & commit
+   git commit -m "feat(component): description"
+
+3. Push to GitHub
+   git push origin feat/component-name
+
+4. Create Pull Request
+   - GitHub will run CI/CD checks automatically
+   - All checks must PASS
+   - Require 1 code review approval
+
+5. Merge to main
+   - Squash merge (keeps history clean)
+   - Delete branch after merge
+   - Storybook auto-deploys
+
+6. Release (manual)
+   - Tag commit: git tag v0.1.0
+   - Push tag: git push origin v0.1.0
+```
+
+### Code Review Process
+
+1. **Author** creates PR with description
+2. **Reviewers** check:
+   - ✅ Code quality (ESLint passes)
+   - ✅ Tests passing (100% for critical paths)
+   - ✅ Accessibility (WCAG 2.1 AA)
+   - ✅ Documentation updated
+3. **CI/CD** verifies:
+   - ✅ All status checks PASS
+   - ✅ No merge conflicts
+4. **Merge** to main (squash commit)
+5. **Deploy** Storybook auto-deploys
+
+---
+
+## 12. Release Process
+
+### Create Release
+
+```bash
+# 1. Create version tag
+git tag -a v0.1.0 -m "Release v0.1.0"
+
+# 2. Push tag
+git push origin v0.1.0
+
+# 3. GitHub auto-creates release
+# Visit: https://github.com/<username>/oms-wms-erp/releases
+```
+
+### Release Checklist
+
+- [ ] All tests passing
+- [ ] No critical warnings
+- [ ] Storybook built & deployed
+- [ ] Documentation updated
+- [ ] Version bumped in package.json
+- [ ] CHANGELOG updated
+- [ ] Tag created & pushed
+
+---
+
+## 13. Troubleshooting
+
+### Workflow Failures
+
+**Check logs:**
+```
+GitHub Actions → Workflow → Job → Logs
+```
+
+**Common failures:**
+- `lint` failure: Run `npm run lint -- --fix`
+- `test` failure: Run `npm run test:unit`
+- `build` failure: Check dependencies, run `npm ci`
+
+### Branch Protection Issues
+
+If you can't merge PR:
+1. Verify all checks PASS
+2. Ensure 1 approval received
+3. Check branch is up-to-date
+4. Resolve conversations
+
+---
+
+## 14. Best Practices
+
+### Commit Messages
+```
+feat(component): Add new Button component
+fix(button): Correct loading state
+docs: Update component guide
+test: Add Button unit tests
+chore: Update dependencies
+```
+
+### Branch Naming
+```
+feat/button-component
+fix/button-loading-state
+docs/add-guide
+refactor/simplify-input
+```
+
+### PR Titles
+```
+[FEAT] Add Button primitive component
+[FIX] Correct Table row-click event
+[DOCS] Update development guide
+[TEST] Add E2E tests for Order form
+```
+
+---
+
+## Phase 1 GitHub Setup Checklist
+
+- [ ] Repository created (main branch)
+- [ ] Branch protection rule applied to main
+- [ ] CODEOWNERS file created
+- [ ] GitHub Pages enabled
+- [ ] CI/CD workflows created (.github/workflows/)
+- [ ] .env.example committed
+- [ ] PR template added (.github/pull_request_template.md)
+- [ ] Issue templates added (.github/ISSUE_TEMPLATE/)
+- [ ] All team members invited & permissions set
+- [ ] First Storybook deploy successful
+- [ ] All workflows passing on main
+
+---
+
+**Status**: ✅ Phase 1 Step 4 Ready  
+**Timeline**: 2026-08-11 (Week 2, Friday)  
+**Next**: Phase 2 (Typed Fields, Week 3-4)