110 lines
3.2 KiB
Markdown
110 lines
3.2 KiB
Markdown
---
|
|
name: ipa-detail
|
|
description: Generate API_SPEC.md and DB_DESIGN.md from SRD and UI_SPEC — Stage 3 of the IPA pipeline. Use when SRD and UI_SPEC are complete and interface contracts plus database schema need to be defined, when designing API endpoints from screen requirements, or when creating language-agnostic data models from entity lists. Trigger phrases: "generate api spec and db design", "ipa detail design", "stage 3 ipa".
|
|
---
|
|
|
|
<HARD-GATE>Do NOT generate API_SPEC/DB_DESIGN until UI_SPEC.md exists. Run ipa-design first.</HARD-GATE>
|
|
|
|
## Overview
|
|
|
|
Generate Stage 3 Detail Design documents following IPA standard. Platform agnostic — works with any project type.
|
|
|
|
Output:
|
|
- `docs/API_SPEC.md` — Interface specifications (API/CLI/MCP/Chat)
|
|
- `docs/DB_DESIGN.md` — Data design (SQL/NoSQL/Vector/File)
|
|
|
|
## When to Use
|
|
|
|
- docs/SRD.md and docs/UI_SPEC.md both exist and are reviewed
|
|
- Ready to define API contracts and database schema
|
|
- Completing Stage 3 of the IPA pipeline before planning
|
|
|
|
## Don't Use When
|
|
|
|
- UI_SPEC.md does not exist (run ipa-design first)
|
|
- SRD.md is missing (run ipa-spec first)
|
|
- Only UI changes are needed with no API/DB impact
|
|
|
|
## Project Type Handling
|
|
|
|
| Project Type | Interface Spec | Data Design |
|
|
|--------------|----------------|-------------|
|
|
| Web App | REST/GraphQL API | SQL/NoSQL |
|
|
| Desktop App | IPC/Native API | SQLite/Local |
|
|
| CLI Tool | Commands/Args/Flags | Config files |
|
|
| MCP Server | Tools/Resources/Prompts | — |
|
|
| Chatbot/RAG | Conversation flows | Vector DB |
|
|
| Library/SDK | Public API/Methods | — |
|
|
|
|
## Language-Agnostic Principle
|
|
|
|
API_SPEC.md uses:
|
|
- OpenAPI 3.x standard (YAML/JSON)
|
|
- Standard HTTP methods
|
|
- JSON Schema for request/response
|
|
- No framework-specific code
|
|
|
|
DB_DESIGN.md uses:
|
|
- Standard SQL (DDL)
|
|
- ER Diagram (Mermaid)
|
|
- Portable data types
|
|
- No ORM-specific syntax
|
|
|
|
## Workflow
|
|
|
|
1. Read `docs/SRD.md` for entities (E-xx) and features (FR-xx)
|
|
2. Read `docs/UI_SPEC.md` for screen → API mapping (S-xx)
|
|
3. Read prototypes if available for data flow visualization
|
|
4. Generate `docs/DB_DESIGN.md` (schema based on E-xx, 3NF, ER diagram)
|
|
5. Generate `docs/API_SPEC.md` (endpoints supporting all FR-xx and S-xx)
|
|
6. Verify traceability: API ↔ Screen ↔ Feature ↔ Entity
|
|
7. Ask user to review
|
|
|
|
## Required Output Structure
|
|
|
|
### docs/DB_DESIGN.md
|
|
|
|
```markdown
|
|
# Database Detailed Design
|
|
|
|
## 1. ER Diagram
|
|
[Mermaid ERD]
|
|
|
|
## 2. Table Definitions
|
|
|
|
### E-01: Users (users)
|
|
| Column | Type | Constraints | Description |
|
|
|--------|------|-------------|-------------|
|
|
| id | uuid | PK | Unique ID |
|
|
| email | varchar | Unique, Not Null | User email |
|
|
```
|
|
|
|
### docs/API_SPEC.md
|
|
|
|
```markdown
|
|
# Interface Specification (API)
|
|
|
|
## 1. Endpoint Matrix
|
|
| Method | URL | Feature (FR-xx) | Screen (S-xx) |
|
|
|--------|-----|-----------------|---------------|
|
|
| POST | /auth/login | FR-01 | S-01 |
|
|
|
|
## 2. Endpoint Details
|
|
|
|
### POST /auth/login
|
|
- **Description**: Authenticate user
|
|
- **Request**: { "email": "...", "password": "..." }
|
|
- **Response**: { "token": "..." }
|
|
```
|
|
|
|
## Traceability Check
|
|
|
|
- Every table corresponds to an E-xx
|
|
- Every endpoint links to an FR-xx
|
|
|
|
## Next Steps
|
|
|
|
After generation: run plan to create implementation tasks.
|
|
|
|
Does not implement code — only generates documentation.
|