chore(rebar): Pier_T_rebar 작업 폴더 초기 구성 및 외부 의존 파일 통합
- Code\rebar_pipeline, review_pipeline, pier-program을 정션에서 실제 폴더로 전환 - Code\rhino_mcp 및 CLAUDE_rhino배경.md 추가, .mcp.json은 PYTHONPATH로 새 위치 사용 - pier-program 내부 .git 제거(이력은 backup\pier-program_20261028.bundle에 보관) - worktree 가이드 반영(CLAUDE.local.md, HANDOFF.md) - D:\Rhino-MCP 경로 참조를 새 위치로 치환 Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
ahnyongjooandClaude Sonnet 5.5 committed
commit
964a841de1
3978 files changed
+58013356
No files matched your search
@@ -0,0 +1,289 @@
|
||||
---
|
||||
name: phase-4-api
|
||||
classification: capability
|
||||
classification-reason: Pattern guidance may overlap with model's built-in knowledge as it improves
|
||||
deprecation-risk: medium
|
||||
description: |
|
||||
Design and implement backend APIs with Zero Script QA validation.
|
||||
Triggers: API design, REST API, backend, endpoint, 백엔드 API, API 설계.
|
||||
imports:
|
||||
- ${PLUGIN_ROOT}/templates/pipeline/phase-4-api.template.md
|
||||
- ${PLUGIN_ROOT}/templates/shared/api-patterns.md
|
||||
- ${PLUGIN_ROOT}/templates/shared/error-handling-patterns.md
|
||||
hooks:
|
||||
Stop:
|
||||
- type: command
|
||||
command: "node ${HMCMKIT_PLUGIN_ROOT}/scripts/phase4-api-stop.js"
|
||||
timeout: 10000
|
||||
agent: hmcmkit:qa-monitor
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Glob
|
||||
- Grep
|
||||
- Bash
|
||||
user-invocable: false
|
||||
next-skill: phase-5-design-system
|
||||
pdca-phase: do
|
||||
task-template: "[Phase-4] {feature}"
|
||||
---
|
||||
|
||||
# Phase 4: API Design/Implementation + Zero Script QA
|
||||
|
||||
> Backend API implementation and script-free QA
|
||||
|
||||
## Purpose
|
||||
|
||||
Implement backend APIs that can store and retrieve data. Validate with structured logs instead of test scripts.
|
||||
|
||||
## What to Do in This Phase
|
||||
|
||||
1. **API Design**: Define endpoints, requests/responses
|
||||
2. **API Implementation**: Write actual backend code
|
||||
3. **Zero Script QA**: Log-based validation
|
||||
|
||||
## Deliverables
|
||||
|
||||
```
|
||||
docs/02-design/
|
||||
└── api-spec.md # API specification
|
||||
|
||||
src/api/ # API implementation
|
||||
├── routes/
|
||||
├── controllers/
|
||||
└── services/
|
||||
|
||||
docs/03-analysis/
|
||||
└── api-qa.md # QA results
|
||||
```
|
||||
|
||||
## PDCA Application
|
||||
|
||||
- **Plan**: Define required API list
|
||||
- **Design**: Design endpoints, requests/responses
|
||||
- **Do**: Implement APIs
|
||||
- **Check**: Validate with Zero Script QA
|
||||
- **Act**: Fix bugs and proceed to Phase 5
|
||||
|
||||
## Level-wise Application
|
||||
|
||||
| Level | Application Method |
|
||||
|-------|-------------------|
|
||||
| Starter | Skip this Phase (no API) |
|
||||
| Dynamic | Use bkend.ai BaaS (see below) |
|
||||
| Enterprise | Implement APIs directly |
|
||||
|
||||
### Dynamic Level: bkend.ai BaaS API Implementation
|
||||
|
||||
#### Step 1: MCP Setup
|
||||
|
||||
```bash
|
||||
ai-agent mcp add bkend --transport http https://api.bkend.ai/mcp
|
||||
```
|
||||
|
||||
#### Step 2: Table Design (via MCP tools)
|
||||
|
||||
Natural language request: "Create a users table with name(required), email(required, unique), age fields"
|
||||
-> MCP `backend_table_create` auto-invoked
|
||||
|
||||
#### Step 3: Service API Integration
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | /v1/data/{table} | List (filter, sort, page) |
|
||||
| POST | /v1/data/{table} | Create data |
|
||||
| GET | /v1/data/{table}/{id} | Get single |
|
||||
| PATCH | /v1/data/{table}/{id} | Partial update |
|
||||
| DELETE | /v1/data/{table}/{id} | Delete |
|
||||
|
||||
Required Headers: x-project-id, x-environment, Authorization
|
||||
|
||||
#### Step 4: Auth Implementation
|
||||
|
||||
Reference MCP tools `3_howto_implement_auth` and `6_code_examples_auth`
|
||||
|
||||
#### Step 5: Zero Script QA
|
||||
|
||||
- Check bkend REST API call logs in browser DevTools Network tab
|
||||
- Verify API behavior via response code/body
|
||||
|
||||
## What is Zero Script QA?
|
||||
|
||||
```
|
||||
Instead of writing test scripts, validate with structured debug logs
|
||||
|
||||
[API] POST /api/users
|
||||
[INPUT] { "email": "test@test.com", "name": "Test" }
|
||||
[PROCESS] Email duplicate check → Passed
|
||||
[PROCESS] Password hash → Complete
|
||||
[PROCESS] DB save → Success
|
||||
[OUTPUT] { "id": 1, "email": "test@test.com" }
|
||||
[RESULT] ✅ Success
|
||||
|
||||
Advantages:
|
||||
- Save test code writing time
|
||||
- See actual behavior with your eyes
|
||||
- Easy debugging
|
||||
```
|
||||
|
||||
## RESTful API Principles
|
||||
|
||||
### What is REST?
|
||||
|
||||
**RE**presentational **S**tate **T**ransfer - an architecture style for designing web services.
|
||||
|
||||
### 6 Core Principles
|
||||
|
||||
| Principle | Description | Example |
|
||||
|-----------|-------------|---------|
|
||||
| **1. Client-Server** | Separation of concerns between client and server | UI ↔ Data storage separated |
|
||||
| **2. Stateless** | Each request is independent, server doesn't store client state | Auth token included with each request |
|
||||
| **3. Cacheable** | Responses must indicate if cacheable | `Cache-Control` header |
|
||||
| **4. Uniform Interface** | Interact through consistent interface | Detailed below |
|
||||
| **5. Layered System** | Allow layered system architecture | Load balancer, proxy |
|
||||
| **6. Code on Demand** | (Optional) Server can send code to client | JavaScript delivery |
|
||||
|
||||
### Uniform Interface Details
|
||||
|
||||
The core of RESTful APIs is a **uniform interface**.
|
||||
|
||||
#### 1. Resource-Based URLs
|
||||
|
||||
```
|
||||
✅ Good (nouns, plural)
|
||||
GET /users # User list
|
||||
GET /users/123 # Specific user
|
||||
POST /users # Create user
|
||||
PUT /users/123 # Update user
|
||||
DELETE /users/123 # Delete user
|
||||
|
||||
❌ Bad (using verbs)
|
||||
GET /getUsers
|
||||
POST /createUser
|
||||
POST /deleteUser/123
|
||||
```
|
||||
|
||||
#### 2. HTTP Method Meanings
|
||||
|
||||
| Method | Purpose | Idempotent | Safe |
|
||||
|--------|---------|:----------:|:----:|
|
||||
| `GET` | Read | ✅ | ✅ |
|
||||
| `POST` | Create | ❌ | ❌ |
|
||||
| `PUT` | Full update | ✅ | ❌ |
|
||||
| `PATCH` | Partial update | ❌ | ❌ |
|
||||
| `DELETE` | Delete | ✅ | ❌ |
|
||||
|
||||
> **Idempotent**: Same result even if requested multiple times
|
||||
> **Safe**: Doesn't change server state
|
||||
|
||||
#### 3. HTTP Status Codes
|
||||
|
||||
```
|
||||
2xx Success
|
||||
├── 200 OK # Success (read, update)
|
||||
├── 201 Created # Creation success
|
||||
└── 204 No Content # Success but no response body (delete)
|
||||
|
||||
4xx Client Error
|
||||
├── 400 Bad Request # Invalid request (validation failure)
|
||||
├── 401 Unauthorized # Authentication required
|
||||
├── 403 Forbidden # No permission
|
||||
├── 404 Not Found # Resource not found
|
||||
└── 409 Conflict # Conflict (duplicate, etc.)
|
||||
|
||||
5xx Server Error
|
||||
├── 500 Internal Error # Internal server error
|
||||
└── 503 Service Unavailable # Service unavailable
|
||||
```
|
||||
|
||||
#### 4. Consistent Response Format
|
||||
|
||||
```json
|
||||
// Success response
|
||||
{
|
||||
"data": {
|
||||
"id": 123,
|
||||
"email": "user@example.com",
|
||||
"name": "John Doe"
|
||||
},
|
||||
"meta": {
|
||||
"timestamp": "2026-01-08T10:00:00Z"
|
||||
}
|
||||
}
|
||||
|
||||
// Error response
|
||||
{
|
||||
"error": {
|
||||
"code": "VALIDATION_ERROR",
|
||||
"message": "Email format is invalid.",
|
||||
"details": [
|
||||
{ "field": "email", "message": "Please enter a valid email" }
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
// List response (pagination)
|
||||
{
|
||||
"data": [...],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 100,
|
||||
"totalPages": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### URL Design Rules
|
||||
|
||||
```
|
||||
1. Use lowercase
|
||||
✅ /users/123/orders
|
||||
❌ /Users/123/Orders
|
||||
|
||||
2. Use hyphens (-), avoid underscores (_)
|
||||
✅ /user-profiles
|
||||
❌ /user_profiles
|
||||
|
||||
3. Express hierarchical relationships
|
||||
✅ /users/123/orders/456
|
||||
|
||||
4. Filtering via query parameters
|
||||
✅ /users?status=active&sort=created_at
|
||||
❌ /users/active/sort/created_at
|
||||
|
||||
5. Version management
|
||||
✅ /api/v1/users
|
||||
✅ Header: Accept: application/vnd.api+json;version=1
|
||||
```
|
||||
|
||||
### API Documentation Tools
|
||||
|
||||
| Tool | Features |
|
||||
|------|----------|
|
||||
| **OpenAPI (Swagger)** | Industry standard, auto documentation |
|
||||
| **Postman** | Testing + documentation |
|
||||
| **Insomnia** | Lightweight API client |
|
||||
|
||||
---
|
||||
|
||||
## API Design Checklist
|
||||
|
||||
- [ ] **RESTful Principles Compliance**
|
||||
- [ ] Resource-based URLs (nouns, plural)
|
||||
- [ ] Appropriate HTTP methods
|
||||
- [ ] Correct status codes
|
||||
- [ ] Unified error response format
|
||||
- [ ] Authentication/authorization method defined
|
||||
- [ ] Pagination method defined
|
||||
- [ ] Versioning method (optional)
|
||||
|
||||
## Templates
|
||||
|
||||
- `templates/pipeline/phase-4-api.template.md`
|
||||
- `templates/pipeline/zero-script-qa.template.md`
|
||||
|
||||
## Next Phase
|
||||
|
||||
Phase 5: Design System → APIs are ready, now build UI components
|
||||
Reference in new issue
Block a user