Initial commit
This commit is contained in:
Zhongwei Li
325
skills/documentation/templates/domain-template.md
Normal file
325
skills/documentation/templates/domain-template.md
Normal file
@@ -0,0 +1,325 @@
|
||||
# [Domain Concept/Entity Name]
|
||||
|
||||
> **Category:** Domain/Business Rules
|
||||
> **Last Updated:** [Date]
|
||||
> **Status:** [Active/Under Review/Deprecated]
|
||||
|
||||
## Overview
|
||||
|
||||
**What:** [What this concept represents in the business]
|
||||
**Why:** [Why this exists, business justification]
|
||||
**Scope:** [Where in the application this applies]
|
||||
|
||||
## Business Context
|
||||
|
||||
### Background
|
||||
|
||||
[Business context and history of this domain concept]
|
||||
|
||||
### Stakeholders
|
||||
|
||||
- **[Role 1]:** [How they interact with this]
|
||||
- **[Role 2]:** [How they interact with this]
|
||||
- **[Role 3]:** [How they interact with this]
|
||||
|
||||
### Business Goals
|
||||
|
||||
1. [Goal 1]
|
||||
2. [Goal 2]
|
||||
3. [Goal 3]
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### [Concept 1]
|
||||
|
||||
**Definition:** [Clear definition]
|
||||
**Examples:** [Real-world examples]
|
||||
**Constraints:** [Business constraints]
|
||||
|
||||
### [Concept 2]
|
||||
|
||||
**Definition:** [Clear definition]
|
||||
**Examples:** [Real-world examples]
|
||||
**Constraints:** [Business constraints]
|
||||
|
||||
## Business Rules
|
||||
|
||||
### Rule 1: [Rule Name]
|
||||
|
||||
**Statement:** [Clear rule statement]
|
||||
|
||||
**Rationale:** [Why this rule exists]
|
||||
|
||||
**Applies to:** [Who/what this affects]
|
||||
|
||||
**Exceptions:** [When this rule doesn't apply]
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Given: [Initial state]
|
||||
When: [Action occurs]
|
||||
Then: [Expected outcome]
|
||||
```
|
||||
|
||||
### Rule 2: [Rule Name]
|
||||
|
||||
[Same structure as above]
|
||||
|
||||
## States and Transitions
|
||||
|
||||
### State Machine (if applicable)
|
||||
|
||||
```
|
||||
[Initial State]
|
||||
↓ [Event/Action]
|
||||
[Next State]
|
||||
↓ [Event/Action]
|
||||
[Final State]
|
||||
```
|
||||
|
||||
### State Definitions
|
||||
|
||||
**[State 1]**
|
||||
- **Meaning:** [What this state represents]
|
||||
- **Entry conditions:** [How entity enters this state]
|
||||
- **Exit conditions:** [How entity leaves this state]
|
||||
- **Allowed actions:** [What can happen in this state]
|
||||
|
||||
**[State 2]**
|
||||
[Same structure]
|
||||
|
||||
### Transition Rules
|
||||
|
||||
**[State A] → [State B]**
|
||||
- **Trigger:** [What causes transition]
|
||||
- **Conditions:** [Required conditions]
|
||||
- **Side effects:** [What else happens]
|
||||
- **Validation:** [What must be true]
|
||||
|
||||
## Permissions and Access Control
|
||||
|
||||
### Who Can Do What
|
||||
|
||||
**[Role 1]:**
|
||||
- ✅ Can: [Action 1, Action 2]
|
||||
- ❌ Cannot: [Action 3, Action 4]
|
||||
- ⚠️ Conditional: [Action 5 - under conditions]
|
||||
|
||||
**[Role 2]:**
|
||||
[Same structure]
|
||||
|
||||
### Permission Rules
|
||||
|
||||
**Rule:** [Permission rule statement]
|
||||
**Logic:**
|
||||
```
|
||||
IF [condition]
|
||||
AND [condition]
|
||||
THEN [permission granted/denied]
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
### Field Validations
|
||||
|
||||
**[Field 1]:**
|
||||
- **Type:** [Data type]
|
||||
- **Required:** [Yes/No]
|
||||
- **Format:** [Pattern or format]
|
||||
- **Range:** [Min/max values]
|
||||
- **Business rule:** [Any business constraint]
|
||||
|
||||
**[Field 2]:**
|
||||
[Same structure]
|
||||
|
||||
### Cross-Field Validations
|
||||
|
||||
**Validation 1:** [Description]
|
||||
```
|
||||
IF [field1] is [value]
|
||||
THEN [field2] must be [constraint]
|
||||
```
|
||||
|
||||
**Validation 2:** [Description]
|
||||
```
|
||||
[Validation logic]
|
||||
```
|
||||
|
||||
## Workflows
|
||||
|
||||
### Workflow 1: [Workflow Name]
|
||||
|
||||
**Trigger:** [What initiates this workflow]
|
||||
|
||||
**Steps:**
|
||||
1. **[Step 1]**
|
||||
- Actor: [Who performs this]
|
||||
- Action: [What happens]
|
||||
- Validation: [What's checked]
|
||||
- Outcome: [Result]
|
||||
|
||||
2. **[Step 2]**
|
||||
[Same structure]
|
||||
|
||||
3. **[Step 3]**
|
||||
[Same structure]
|
||||
|
||||
**Success Criteria:** [What defines success]
|
||||
**Failure Scenarios:** [What can go wrong]
|
||||
|
||||
## Calculations and Algorithms
|
||||
|
||||
### Calculation 1: [Name]
|
||||
|
||||
**Purpose:** [What this calculates]
|
||||
|
||||
**Formula:**
|
||||
```
|
||||
[Mathematical or logical formula]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Given:
|
||||
- input1 = [value]
|
||||
- input2 = [value]
|
||||
|
||||
Calculation:
|
||||
result = [formula applied]
|
||||
|
||||
Output: [result]
|
||||
```
|
||||
|
||||
**Edge Cases:**
|
||||
- [Edge case 1 and handling]
|
||||
- [Edge case 2 and handling]
|
||||
|
||||
## Constraints and Limits
|
||||
|
||||
### Business Constraints
|
||||
|
||||
1. **[Constraint 1]:** [Description and rationale]
|
||||
2. **[Constraint 2]:** [Description and rationale]
|
||||
3. **[Constraint 3]:** [Description and rationale]
|
||||
|
||||
### System Limits
|
||||
|
||||
- **[Limit 1]:** [Value and reason]
|
||||
- **[Limit 2]:** [Value and reason]
|
||||
- **[Limit 3]:** [Value and reason]
|
||||
|
||||
## Edge Cases
|
||||
|
||||
### Edge Case 1: [Scenario]
|
||||
|
||||
**Situation:** [Describe the edge case]
|
||||
**Business Rule:** [How to handle it]
|
||||
**Example:** [Concrete example]
|
||||
|
||||
### Edge Case 2: [Scenario]
|
||||
|
||||
[Same structure]
|
||||
|
||||
## Compliance and Regulations
|
||||
|
||||
### Regulatory Requirements
|
||||
|
||||
**[Regulation 1]:** [How it affects this domain concept]
|
||||
**[Regulation 2]:** [How it affects this domain concept]
|
||||
|
||||
### Audit Requirements
|
||||
|
||||
- **What to log:** [Events/changes to track]
|
||||
- **Retention:** [How long to keep records]
|
||||
- **Who can access:** [Audit log access rules]
|
||||
|
||||
## Reporting and Analytics
|
||||
|
||||
### Key Metrics
|
||||
|
||||
1. **[Metric 1]:** [What it measures and why it matters]
|
||||
2. **[Metric 2]:** [What it measures and why it matters]
|
||||
3. **[Metric 3]:** [What it measures and why it matters]
|
||||
|
||||
### Reporting Requirements
|
||||
|
||||
- **[Report 1]:** [Purpose, frequency, audience]
|
||||
- **[Report 2]:** [Purpose, frequency, audience]
|
||||
|
||||
## Examples and Scenarios
|
||||
|
||||
### Scenario 1: [Happy Path]
|
||||
|
||||
**Description:** [Common successful scenario]
|
||||
|
||||
**Flow:**
|
||||
```
|
||||
1. [Step with data]
|
||||
2. [Step with data]
|
||||
3. [Step with outcome]
|
||||
```
|
||||
|
||||
**Business Rules Applied:** [Which rules from above]
|
||||
|
||||
### Scenario 2: [Error Case]
|
||||
|
||||
**Description:** [Common error scenario]
|
||||
|
||||
**Flow:**
|
||||
```
|
||||
1. [Step with data]
|
||||
2. [Error condition]
|
||||
3. [Error handling per business rules]
|
||||
```
|
||||
|
||||
**Business Rules Applied:** [Which rules from above]
|
||||
|
||||
### Scenario 3: [Edge Case]
|
||||
|
||||
**Description:** [Unusual but valid scenario]
|
||||
|
||||
**Flow:**
|
||||
```
|
||||
1. [Step with data]
|
||||
2. [Edge condition]
|
||||
3. [Special handling]
|
||||
```
|
||||
|
||||
**Business Rules Applied:** [Which rules from above]
|
||||
|
||||
## Integration Points
|
||||
|
||||
### System Touchpoints
|
||||
|
||||
**[System 1]:**
|
||||
- **Interaction:** [How they interact]
|
||||
- **Data shared:** [What data flows]
|
||||
- **Trigger:** [What causes interaction]
|
||||
|
||||
**[System 2]:**
|
||||
[Same structure]
|
||||
|
||||
## Glossary
|
||||
|
||||
**[Term 1]:** [Definition in this context]
|
||||
**[Term 2]:** [Definition in this context]
|
||||
**[Term 3]:** [Definition in this context]
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Patterns:** [Pattern Doc](../patterns/doc.md) - [Technical implementation]
|
||||
- **Interfaces:** [Interface Doc](../interfaces/doc.md) - [External systems]
|
||||
- **Specifications:** [Spec](../specs/NNN-name/PRD.md) - [Feature requirements]
|
||||
|
||||
## References
|
||||
|
||||
- [Business document or policy]
|
||||
- [Industry standard or regulation]
|
||||
- [Internal decision document]
|
||||
|
||||
## Version History
|
||||
|
||||
| Date | Change | Reason | Author |
|
||||
|------|--------|--------|--------|
|
||||
| [Date] | Initial documentation | [Why] | [Name/Tool] |
|
||||
| [Date] | Updated [aspect] | [Why] | [Name/Tool] |
|
||||
255
skills/documentation/templates/interface-template.md
Normal file
255
skills/documentation/templates/interface-template.md
Normal file
@@ -0,0 +1,255 @@
|
||||
# [Service Name] Integration
|
||||
|
||||
> **Category:** External Interface
|
||||
> **Service:** [Service Name]
|
||||
> **Last Updated:** [Date]
|
||||
> **Status:** [Active/Deprecated/Planned]
|
||||
|
||||
## Overview
|
||||
|
||||
**Service:** [Full service name]
|
||||
**Provider:** [Company/organization]
|
||||
**Purpose:** [What this integration accomplishes]
|
||||
**Documentation:** [Link to official API docs]
|
||||
|
||||
## Authentication
|
||||
|
||||
### Method
|
||||
|
||||
[OAuth 2.0 / API Key / Basic Auth / JWT / etc.]
|
||||
|
||||
### Credentials Management
|
||||
|
||||
**Location:** [Where credentials are stored]
|
||||
**Environment Variables:**
|
||||
```bash
|
||||
SERVICE_API_KEY=xxx
|
||||
SERVICE_SECRET=xxx
|
||||
SERVICE_ENDPOINT=https://...
|
||||
```
|
||||
|
||||
**Rotation Policy:** [How often credentials change]
|
||||
|
||||
### Authentication Example
|
||||
|
||||
```[language]
|
||||
// Example of authentication setup
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## API Endpoints Used
|
||||
|
||||
### Endpoint 1: [Name]
|
||||
|
||||
**URL:** `[METHOD] /path/to/endpoint`
|
||||
**Purpose:** [What this endpoint does]
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"field1": "value",
|
||||
"field2": "value"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": { }
|
||||
}
|
||||
```
|
||||
|
||||
**Error Handling:**
|
||||
- `400`: [How we handle]
|
||||
- `401`: [How we handle]
|
||||
- `500`: [How we handle]
|
||||
|
||||
### Endpoint 2: [Name]
|
||||
|
||||
**URL:** `[METHOD] /path/to/endpoint`
|
||||
**Purpose:** [What this endpoint does]
|
||||
|
||||
[Same structure as above]
|
||||
|
||||
## Webhooks (if applicable)
|
||||
|
||||
### Webhook 1: [Event Name]
|
||||
|
||||
**Event Type:** `[event.type]`
|
||||
**Trigger:** [When this fires]
|
||||
**URL:** `[Your webhook endpoint]`
|
||||
|
||||
**Payload:**
|
||||
```json
|
||||
{
|
||||
"event": "type",
|
||||
"data": { }
|
||||
}
|
||||
```
|
||||
|
||||
**Signature Verification:**
|
||||
```[language]
|
||||
// How to verify webhook authenticity
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
```[language]
|
||||
// How we process this webhook
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## Rate Limits
|
||||
|
||||
- **Requests per second:** [Limit]
|
||||
- **Requests per day:** [Limit]
|
||||
- **Burst limit:** [Limit]
|
||||
|
||||
**Handling Strategy:** [How we respect limits]
|
||||
```[language]
|
||||
// Rate limiting implementation
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## Data Mapping
|
||||
|
||||
### Our Model → Service Model
|
||||
|
||||
| Our Field | Service Field | Transformation |
|
||||
|-----------|---------------|----------------|
|
||||
| `userId` | `external_id` | String conversion |
|
||||
| `email` | `email_address` | Direct mapping |
|
||||
| `amount` | `total_cents` | Multiply by 100 |
|
||||
|
||||
### Service Model → Our Model
|
||||
|
||||
| Service Field | Our Field | Transformation |
|
||||
|---------------|-----------|----------------|
|
||||
| `id` | `externalId` | Direct mapping |
|
||||
| `status` | `state` | Enum mapping |
|
||||
| `created_at` | `createdAt` | ISO 8601 parse |
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors
|
||||
|
||||
**Error 1: [Name/Code]**
|
||||
- **Cause:** [What triggers this]
|
||||
- **Recovery:** [How we handle it]
|
||||
- **Retry:** [Yes/No, strategy]
|
||||
|
||||
**Error 2: [Name/Code]**
|
||||
- **Cause:** [What triggers this]
|
||||
- **Recovery:** [How we handle it]
|
||||
- **Retry:** [Yes/No, strategy]
|
||||
|
||||
### Retry Strategy
|
||||
|
||||
```[language]
|
||||
// Exponential backoff implementation
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Credentials
|
||||
|
||||
**Sandbox URL:** `https://sandbox.service.com`
|
||||
**Test API Key:** `[Where to get it]`
|
||||
|
||||
### Mock Server
|
||||
|
||||
**Location:** `tests/mocks/[service]-mock.ts`
|
||||
**Usage:**
|
||||
```[language]
|
||||
// How to use mock in tests
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
```[language]
|
||||
// Example integration test
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Health Checks
|
||||
|
||||
**Endpoint:** `[Service status endpoint]`
|
||||
**Frequency:** [How often we check]
|
||||
|
||||
### Metrics to Track
|
||||
|
||||
- Request success rate
|
||||
- Response time (p50, p95, p99)
|
||||
- Error rate by type
|
||||
- Rate limit proximity
|
||||
|
||||
### Alerts
|
||||
|
||||
- **Critical:** [Conditions that trigger urgent alerts]
|
||||
- **Warning:** [Conditions that trigger warnings]
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- [Security consideration 1]
|
||||
- [Security consideration 2]
|
||||
- [Security consideration 3]
|
||||
|
||||
## Compliance
|
||||
|
||||
**Data Handling:**
|
||||
- PII fields: [List]
|
||||
- Retention policy: [Duration]
|
||||
- Geographic restrictions: [Any]
|
||||
|
||||
**Regulations:**
|
||||
- GDPR: [Compliance notes]
|
||||
- CCPA: [Compliance notes]
|
||||
- Other: [Relevant regulations]
|
||||
|
||||
## Cost Considerations
|
||||
|
||||
**Pricing Model:** [How service charges]
|
||||
**Cost per request:** [Estimate]
|
||||
**Monthly estimate:** [Based on usage]
|
||||
|
||||
## Migration/Upgrade Path
|
||||
|
||||
**Current Version:** [Version]
|
||||
**Upgrade Available:** [Yes/No, version]
|
||||
**Breaking Changes:** [List if applicable]
|
||||
|
||||
**Migration Steps:**
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Patterns:** [Pattern Doc](../patterns/doc.md) - [How we use this service]
|
||||
- **Domain:** [Domain Doc](../domain/doc.md) - [Business rules related to this]
|
||||
- **Specifications:** [Spec](../specs/NNN-name/SDD.md) - [Implementation details]
|
||||
|
||||
## External Resources
|
||||
|
||||
- [Official API documentation]
|
||||
- [Status page]
|
||||
- [Developer community/forum]
|
||||
- [SDK/library used]
|
||||
|
||||
## Contact
|
||||
|
||||
**Support:** [How to get help]
|
||||
**Account Manager:** [If applicable]
|
||||
**Escalation:** [Critical issue contact]
|
||||
|
||||
## Version History
|
||||
|
||||
| Date | Change | Author |
|
||||
|------|--------|--------|
|
||||
| [Date] | Initial integration | [Name/Tool] |
|
||||
| [Date] | Updated to v2 API | [Name/Tool] |
|
||||
144
skills/documentation/templates/pattern-template.md
Normal file
144
skills/documentation/templates/pattern-template.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# [Pattern Name]
|
||||
|
||||
> **Category:** Technical Pattern
|
||||
> **Last Updated:** [Date]
|
||||
> **Status:** [Active/Deprecated/Proposed]
|
||||
|
||||
## Purpose
|
||||
|
||||
[Brief description of what this pattern accomplishes and why it exists]
|
||||
|
||||
## Context
|
||||
|
||||
**When to use this pattern:**
|
||||
- [Scenario 1]
|
||||
- [Scenario 2]
|
||||
- [Scenario 3]
|
||||
|
||||
**When NOT to use this pattern:**
|
||||
- [Anti-scenario 1]
|
||||
- [Anti-scenario 2]
|
||||
|
||||
## Implementation
|
||||
|
||||
### Overview
|
||||
|
||||
[High-level description of how the pattern works]
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
[Directory structure or component organization]
|
||||
```
|
||||
|
||||
### Key Components
|
||||
|
||||
**[Component 1 Name]**
|
||||
- Purpose: [What it does]
|
||||
- Responsibilities: [What it handles]
|
||||
- Location: [Where to find it]
|
||||
|
||||
**[Component 2 Name]**
|
||||
- Purpose: [What it does]
|
||||
- Responsibilities: [What it handles]
|
||||
- Location: [Where to find it]
|
||||
|
||||
### Code Example
|
||||
|
||||
```[language]
|
||||
// Example implementation showing the pattern in action
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: [Scenario Name]
|
||||
|
||||
**Situation:** [Describe the use case]
|
||||
|
||||
**Implementation:**
|
||||
```[language]
|
||||
[Code showing how pattern is applied]
|
||||
```
|
||||
|
||||
**Result:** [What this achieves]
|
||||
|
||||
### Example 2: [Scenario Name]
|
||||
|
||||
**Situation:** [Describe the use case]
|
||||
|
||||
**Implementation:**
|
||||
```[language]
|
||||
[Code showing how pattern is applied]
|
||||
```
|
||||
|
||||
**Result:** [What this achieves]
|
||||
|
||||
## Edge Cases and Gotchas
|
||||
|
||||
### Edge Case 1: [Case Name]
|
||||
|
||||
**Problem:** [What can go wrong]
|
||||
**Solution:** [How to handle it]
|
||||
|
||||
### Edge Case 2: [Case Name]
|
||||
|
||||
**Problem:** [What can go wrong]
|
||||
**Solution:** [How to handle it]
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **[Practice 1]:** [Description]
|
||||
2. **[Practice 2]:** [Description]
|
||||
3. **[Practice 3]:** [Description]
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
❌ **Don't:** [What to avoid]
|
||||
**Why:** [Reason]
|
||||
**Instead:** [Better approach]
|
||||
|
||||
❌ **Don't:** [What to avoid]
|
||||
**Why:** [Reason]
|
||||
**Instead:** [Better approach]
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
**How to test code using this pattern:**
|
||||
- [Testing approach 1]
|
||||
- [Testing approach 2]
|
||||
- [Testing approach 3]
|
||||
|
||||
**Example test:**
|
||||
```[language]
|
||||
[Test code example]
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- **[Aspect 1]:** [Performance implication]
|
||||
- **[Aspect 2]:** [Performance implication]
|
||||
- **[Aspect 3]:** [Performance implication]
|
||||
|
||||
## Related Patterns
|
||||
|
||||
- [Pattern Name](./pattern-file.md) - [Relationship description]
|
||||
- [Pattern Name](./pattern-file.md) - [Relationship description]
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Domain:** [Domain Doc](../domain/doc.md) - [Relevance]
|
||||
- **Interfaces:** [Interface Doc](../interfaces/doc.md) - [Relevance]
|
||||
- **Specifications:** [Spec](../specs/NNN-name/SDD.md) - [Relevance]
|
||||
|
||||
## References
|
||||
|
||||
- [External resource 1]
|
||||
- [External resource 2]
|
||||
- [Internal decision doc or RFC]
|
||||
|
||||
## Version History
|
||||
|
||||
| Date | Change | Author |
|
||||
|------|--------|--------|
|
||||
| [Date] | Initial documentation | [Name/Tool] |
|
||||
Reference in New Issue
Block a user