forjajs 5.0.1 → 5.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +38 -2
- package/README.md +4 -2
- package/README.pt-BR.md +4 -1
- package/boilerplates/02-saas-starter/README.md +58 -293
- package/boilerplates/02-saas-starter/backend/.env.example +13 -0
- package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
- package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
- package/boilerplates/02-saas-starter/backend/package.json +32 -73
- package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
- package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
- package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
- package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
- package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
- package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
- package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
- package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
- package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
- package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
- package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
- package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
- package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
- package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
- package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
- package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
- package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
- package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
- package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
- package/boilerplates/README.md +9 -10
- package/dist/bin/init-project.js +1 -0
- package/dist/lib/core/journey.js +10 -0
- package/dist/lib/generators/memory-generator.d.ts +0 -11
- package/dist/lib/generators/memory-generator.js +5 -161
- package/dist/lib/generators/readme-generator.js +1 -1
- package/dist/lib/llm/json-output.d.ts +14 -0
- package/dist/lib/llm/json-output.js +77 -0
- package/dist/lib/project-wiring.d.ts +8 -0
- package/dist/lib/project-wiring.js +74 -2
- package/dist/lib/validators/structure-validator.js +0 -1
- package/dist/packages/llm/src/index.js +12 -2
- package/dist/scripts/llm-fit.js +23 -1
- package/docs/llm-fit-loop.md +16 -0
- package/memory/90-decisions/0088-templates-validados.md +3 -0
- package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
- package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
- package/package.json +1 -1
- package/specs/skills-do-projeto/plan.md +40 -0
- package/specs/skills-do-projeto/spec.md +63 -0
- package/specs/skills-do-projeto/tasks.md +27 -0
- package/templates/project/AGENTS.md +9 -0
- package/templates/project/agents/context-engineer.md +3 -0
- package/templates/project/agents/governance.md +3 -0
- package/templates/project/agents/marketing.md +3 -0
- package/templates/project/agents/orchestrator.md +3 -0
- package/templates/project/agents/product.md +3 -0
- package/templates/project/agents/sdd-architect.md +3 -0
- package/templates/project/skills/README.md +14 -0
- package/templates/project/skills/accessibility-review/SKILL.md +89 -0
- package/templates/project/skills/api-design/SKILL.md +77 -0
- package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
- package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
- package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
- package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
- package/templates/project/skills/commit-message/SKILL.md +143 -0
- package/templates/project/skills/data-migrations/SKILL.md +88 -0
- package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
- package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
- package/templates/project/skills/domain-modeling/SKILL.md +120 -0
- package/templates/project/skills/event-storming/SKILL.md +95 -0
- package/templates/project/skills/executive-writing/SKILL.md +99 -0
- package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
- package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
- package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
- package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
- package/templates/project/skills/observability/SKILL.md +93 -0
- package/templates/project/skills/product-evaluation/SKILL.md +130 -0
- package/templates/project/skills/prompt-spec/SKILL.md +83 -0
- package/templates/project/skills/pull-request/SKILL.md +101 -0
- package/templates/project/skills/query-performance/SKILL.md +83 -0
- package/templates/project/skills/release-checklist/SKILL.md +106 -0
- package/templates/project/skills/release-notes/SKILL.md +87 -0
- package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
- package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
- package/templates/project/skills/technical-spike/SKILL.md +101 -0
- package/templates/project/skills/testing/SKILL.md +109 -0
- package/templates/project/skills/threat-modeling/SKILL.md +87 -0
- package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
- package/templates/project/skills/ts-code-review/SKILL.md +121 -0
- package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
- package/templates/project/skills/ts-testing/SKILL.md +89 -0
- package/templates/project/skills/web-performance/SKILL.md +72 -0
- package/boilerplates/02-saas-starter/.env.example +0 -25
- package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
- package/boilerplates/02-saas-starter/INFO.md +0 -252
- package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
- package/boilerplates/02-saas-starter/START-HERE.md +0 -259
- package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
- package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
- package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
- package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
- package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
- package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
- package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
- package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
- package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
- package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
- package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
- package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
- package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
- package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
- package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
- package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
- package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
- package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
- package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
- package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
- package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
- package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
- package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
- package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
- package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
- package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
- package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
- package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
|
@@ -1,85 +0,0 @@
|
|
|
1
|
-
# Auth Domain Context
|
|
2
|
-
|
|
3
|
-
## O que é Auth neste SaaS?
|
|
4
|
-
|
|
5
|
-
Autenticação & autorização stateless com JWT, permitindo:
|
|
6
|
-
1. Signup (criar org + user)
|
|
7
|
-
2. Login (JWT tokens)
|
|
8
|
-
3. Refresh (renovar access token)
|
|
9
|
-
4. Logout (invalidar token em Redis)
|
|
10
|
-
5. Password reset (email link)
|
|
11
|
-
|
|
12
|
-
## Fluxo de Autenticação
|
|
13
|
-
|
|
14
|
-
```
|
|
15
|
-
User abre app
|
|
16
|
-
↓
|
|
17
|
-
Frontend checa localStorage.accessToken
|
|
18
|
-
↓
|
|
19
|
-
[Token válido?] → SIM → Mostrar dashboard
|
|
20
|
-
↓ NÃO
|
|
21
|
-
[Token expirado?] → NÃO → Mostrar login
|
|
22
|
-
↓ SIM
|
|
23
|
-
POST /api/auth/refresh com refreshToken
|
|
24
|
-
↓
|
|
25
|
-
[Refresh válido?] → SIM → Novo accessToken
|
|
26
|
-
↓ NÃO
|
|
27
|
-
Limpar tokens, mostrar login
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
## Conceitos
|
|
31
|
-
|
|
32
|
-
### JWT Structure
|
|
33
|
-
```
|
|
34
|
-
Header.Payload.Signature
|
|
35
|
-
eyJhbGciOiJIUzI1NiJ9.
|
|
36
|
-
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
|
|
37
|
-
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
Payload contém:
|
|
41
|
-
- `sub` (subject): user ID
|
|
42
|
-
- `tenantId`: organization ID
|
|
43
|
-
- `roles`: ['owner', 'admin'] etc
|
|
44
|
-
- `iat`: issued at
|
|
45
|
-
- `exp`: expiry timestamp
|
|
46
|
-
|
|
47
|
-
### Strategies
|
|
48
|
-
|
|
49
|
-
**Local Strategy**:
|
|
50
|
-
- Username/email + password
|
|
51
|
-
- Usado em POST /api/auth/login
|
|
52
|
-
- Retorna JWT
|
|
53
|
-
|
|
54
|
-
**JWT Strategy**:
|
|
55
|
-
- Valida token em Authorization header
|
|
56
|
-
- Usado em @UseGuards(JwtAuthGuard)
|
|
57
|
-
- Extrai dados do token payload
|
|
58
|
-
|
|
59
|
-
## Regras & Invariantes
|
|
60
|
-
|
|
61
|
-
1. **Password validation**: Min 12 chars, 1 uppercase, 1 lowercase, 1 number, 1 symbol
|
|
62
|
-
2. **Email validation**: RFC 5322
|
|
63
|
-
3. **Unique constraint**: Email único por tenant (não global)
|
|
64
|
-
4. **Token signing**: Secret from process.env.JWT_SECRET
|
|
65
|
-
5. **Token expiry**: Access 15 min, Refresh 7 days
|
|
66
|
-
6. **Rate limiting**: 5 failed login attempts = 15 min lockout
|
|
67
|
-
7. **Tenant isolation**: User pode pertencer a múltiplas orgs (multi-tenant)
|
|
68
|
-
|
|
69
|
-
## Status Atual
|
|
70
|
-
|
|
71
|
-
- ✅ JWT strategy implementada
|
|
72
|
-
- ✅ Local strategy implementada
|
|
73
|
-
- ✅ User entity com password hash
|
|
74
|
-
- ✅ Signup endpoint
|
|
75
|
-
- ✅ Login endpoint
|
|
76
|
-
- ✅ Refresh endpoint
|
|
77
|
-
- 🚧 Password reset (future)
|
|
78
|
-
- 🚧 MFA (future)
|
|
79
|
-
|
|
80
|
-
## Próximos Steps
|
|
81
|
-
|
|
82
|
-
1. Implementar password reset flow
|
|
83
|
-
2. Adicionar rate limiting
|
|
84
|
-
3. Webhook para email de confirmação
|
|
85
|
-
4. Audit logging de eventos de auth
|
|
@@ -1,262 +0,0 @@
|
|
|
1
|
-
# Billing API Specification
|
|
2
|
-
|
|
3
|
-
## Endpoints
|
|
4
|
-
|
|
5
|
-
### 1. Process Payment
|
|
6
|
-
|
|
7
|
-
**POST** `/api/billing/charge`
|
|
8
|
-
|
|
9
|
-
Headers: `Authorization: Bearer {token}`, Content-Type: `application/json`
|
|
10
|
-
|
|
11
|
-
```json
|
|
12
|
-
{
|
|
13
|
-
"amount": 99.00,
|
|
14
|
-
"currency": "usd",
|
|
15
|
-
"description": "Pro Plan Upgrade",
|
|
16
|
-
"paymentMethodId": "pm_1234567890"
|
|
17
|
-
}
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
**Response 200**:
|
|
21
|
-
```json
|
|
22
|
-
{
|
|
23
|
-
"data": {
|
|
24
|
-
"paymentIntentId": "pi_1234567890",
|
|
25
|
-
"status": "succeeded",
|
|
26
|
-
"amount": 99.00,
|
|
27
|
-
"currency": "usd",
|
|
28
|
-
"invoiceId": "inv_xyz",
|
|
29
|
-
"invoiceNumber": "INV-2024-001",
|
|
30
|
-
"receipt": "https://..."
|
|
31
|
-
}
|
|
32
|
-
}
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
**Error 402**: Payment failed
|
|
36
|
-
**Error 400**: Invalid payment method
|
|
37
|
-
|
|
38
|
-
---
|
|
39
|
-
|
|
40
|
-
### 2. Get Invoices
|
|
41
|
-
|
|
42
|
-
**GET** `/api/billing/invoices`
|
|
43
|
-
|
|
44
|
-
Headers: `Authorization: Bearer {token}`
|
|
45
|
-
|
|
46
|
-
**Query params**:
|
|
47
|
-
- `status`: "paid", "pending", "failed" (optional)
|
|
48
|
-
- `limit`: 50 (default)
|
|
49
|
-
- `offset`: 0 (default)
|
|
50
|
-
|
|
51
|
-
**Response 200**:
|
|
52
|
-
```json
|
|
53
|
-
{
|
|
54
|
-
"data": [
|
|
55
|
-
{
|
|
56
|
-
"id": "inv_xyz",
|
|
57
|
-
"invoiceNumber": "INV-2024-001",
|
|
58
|
-
"amount": 99.00,
|
|
59
|
-
"status": "paid",
|
|
60
|
-
"issuedAt": "2024-01-01T00:00:00Z",
|
|
61
|
-
"paidAt": "2024-01-01T10:30:00Z",
|
|
62
|
-
"receipt": "https://..."
|
|
63
|
-
}
|
|
64
|
-
],
|
|
65
|
-
"pagination": {
|
|
66
|
-
"total": 12,
|
|
67
|
-
"limit": 50,
|
|
68
|
-
"offset": 0
|
|
69
|
-
}
|
|
70
|
-
}
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
---
|
|
74
|
-
|
|
75
|
-
### 3. Get Invoice Details
|
|
76
|
-
|
|
77
|
-
**GET** `/api/billing/invoices/:id`
|
|
78
|
-
|
|
79
|
-
**Response 200**:
|
|
80
|
-
```json
|
|
81
|
-
{
|
|
82
|
-
"data": {
|
|
83
|
-
"id": "inv_xyz",
|
|
84
|
-
"invoiceNumber": "INV-2024-001",
|
|
85
|
-
"organizationId": "org-uuid",
|
|
86
|
-
"amount": 99.00,
|
|
87
|
-
"currency": "usd",
|
|
88
|
-
"status": "paid",
|
|
89
|
-
"items": [
|
|
90
|
-
{
|
|
91
|
-
"description": "Pro Plan",
|
|
92
|
-
"quantity": 1,
|
|
93
|
-
"unitPrice": 99.00,
|
|
94
|
-
"amount": 99.00
|
|
95
|
-
}
|
|
96
|
-
],
|
|
97
|
-
"issuedAt": "2024-01-01T00:00:00Z",
|
|
98
|
-
"dueDate": "2024-01-15T00:00:00Z",
|
|
99
|
-
"paidAt": "2024-01-01T10:30:00Z"
|
|
100
|
-
}
|
|
101
|
-
}
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
---
|
|
105
|
-
|
|
106
|
-
### 4. Get Invoice PDF
|
|
107
|
-
|
|
108
|
-
**GET** `/api/billing/invoices/:id/pdf`
|
|
109
|
-
|
|
110
|
-
**Response 200**: PDF file (application/pdf)
|
|
111
|
-
|
|
112
|
-
---
|
|
113
|
-
|
|
114
|
-
### 5. Create Refund
|
|
115
|
-
|
|
116
|
-
**POST** `/api/billing/invoices/:id/refund`
|
|
117
|
-
|
|
118
|
-
```json
|
|
119
|
-
{
|
|
120
|
-
"reason": "duplicate_charge",
|
|
121
|
-
"amount": 99.00
|
|
122
|
-
}
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
**Response 201**:
|
|
126
|
-
```json
|
|
127
|
-
{
|
|
128
|
-
"data": {
|
|
129
|
-
"refundId": "ref_123",
|
|
130
|
-
"originalInvoiceId": "inv_xyz",
|
|
131
|
-
"amount": 99.00,
|
|
132
|
-
"status": "processing",
|
|
133
|
-
"estimatedDate": "2024-01-08T00:00:00Z"
|
|
134
|
-
}
|
|
135
|
-
}
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
---
|
|
139
|
-
|
|
140
|
-
### 6. Get Payment Methods
|
|
141
|
-
|
|
142
|
-
**GET** `/api/billing/payment-methods`
|
|
143
|
-
|
|
144
|
-
**Response 200**:
|
|
145
|
-
```json
|
|
146
|
-
{
|
|
147
|
-
"data": [
|
|
148
|
-
{
|
|
149
|
-
"id": "pm_1234567890",
|
|
150
|
-
"type": "card",
|
|
151
|
-
"card": {
|
|
152
|
-
"brand": "visa",
|
|
153
|
-
"last4": "4242",
|
|
154
|
-
"expMonth": 12,
|
|
155
|
-
"expYear": 2025
|
|
156
|
-
},
|
|
157
|
-
"default": true
|
|
158
|
-
}
|
|
159
|
-
]
|
|
160
|
-
}
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
---
|
|
164
|
-
|
|
165
|
-
### 7. Add Payment Method
|
|
166
|
-
|
|
167
|
-
**POST** `/api/billing/payment-methods`
|
|
168
|
-
|
|
169
|
-
```json
|
|
170
|
-
{
|
|
171
|
-
"paymentMethodId": "pm_token_from_stripe"
|
|
172
|
-
}
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
**Response 201**:
|
|
176
|
-
```json
|
|
177
|
-
{
|
|
178
|
-
"data": {
|
|
179
|
-
"id": "pm_1234567890",
|
|
180
|
-
"type": "card",
|
|
181
|
-
"default": false
|
|
182
|
-
}
|
|
183
|
-
}
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
---
|
|
187
|
-
|
|
188
|
-
### 8. Get Transactions
|
|
189
|
-
|
|
190
|
-
**GET** `/api/billing/transactions`
|
|
191
|
-
|
|
192
|
-
**Response 200**:
|
|
193
|
-
```json
|
|
194
|
-
{
|
|
195
|
-
"data": [
|
|
196
|
-
{
|
|
197
|
-
"id": "txn_123",
|
|
198
|
-
"amount": 99.00,
|
|
199
|
-
"type": "charge",
|
|
200
|
-
"status": "succeeded",
|
|
201
|
-
"relatedInvoiceId": "inv_xyz",
|
|
202
|
-
"createdAt": "2024-01-01T10:30:00Z"
|
|
203
|
-
}
|
|
204
|
-
]
|
|
205
|
-
}
|
|
206
|
-
```
|
|
207
|
-
|
|
208
|
-
---
|
|
209
|
-
|
|
210
|
-
## Error Codes
|
|
211
|
-
|
|
212
|
-
| Code | Message | Meaning |
|
|
213
|
-
|------|---------|---------|
|
|
214
|
-
| BIL_001 | Payment failed | Card declined, insufficient funds |
|
|
215
|
-
| BIL_002 | Invalid payment method | Payment method not found ou expirado |
|
|
216
|
-
| BIL_003 | Invoice not found | Invoice não existe |
|
|
217
|
-
| BIL_004 | Refund failed | Não pode fazer refund (expired, etc) |
|
|
218
|
-
| BIL_005 | Insufficient permissions | Apenas owner/admin pode gerenciar billing |
|
|
219
|
-
|
|
220
|
-
## Flow Examples
|
|
221
|
-
|
|
222
|
-
### Scenario: Charge for Upgrade
|
|
223
|
-
```bash
|
|
224
|
-
curl -X POST http://localhost:3000/api/billing/charge \
|
|
225
|
-
-H "Authorization: Bearer eyJhbGc..." \
|
|
226
|
-
-H "Content-Type: application/json" \
|
|
227
|
-
-d '{
|
|
228
|
-
"amount": 99.00,
|
|
229
|
-
"currency": "usd",
|
|
230
|
-
"description": "Pro Plan Upgrade",
|
|
231
|
-
"paymentMethodId": "pm_1234567890"
|
|
232
|
-
}'
|
|
233
|
-
```
|
|
234
|
-
|
|
235
|
-
### Scenario: List Invoices
|
|
236
|
-
```bash
|
|
237
|
-
curl -X GET http://localhost:3000/api/billing/invoices \
|
|
238
|
-
-H "Authorization: Bearer eyJhbGc..."
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
### Scenario: Get Invoice PDF
|
|
242
|
-
```bash
|
|
243
|
-
curl -X GET http://localhost:3000/api/billing/invoices/inv_xyz/pdf \
|
|
244
|
-
-H "Authorization: Bearer eyJhbGc..." \
|
|
245
|
-
-o invoice.pdf
|
|
246
|
-
```
|
|
247
|
-
|
|
248
|
-
### Scenario: Request Refund
|
|
249
|
-
```bash
|
|
250
|
-
curl -X POST http://localhost:3000/api/billing/invoices/inv_xyz/refund \
|
|
251
|
-
-H "Authorization: Bearer eyJhbGc..." \
|
|
252
|
-
-H "Content-Type: application/json" \
|
|
253
|
-
-d '{ "reason": "duplicate_charge", "amount": 99.00 }'
|
|
254
|
-
```
|
|
255
|
-
|
|
256
|
-
## Implementation Notes
|
|
257
|
-
|
|
258
|
-
- Todas operações isoladas por tenant
|
|
259
|
-
- Payment gateway é mock para MVP (90% success, 10% fail)
|
|
260
|
-
- Invoices geradas automaticamente após sucesso
|
|
261
|
-
- Refund processa em background (async)
|
|
262
|
-
- Retry logic para pagamentos falhados: 3 tentativas em 14 dias
|
|
@@ -1,176 +0,0 @@
|
|
|
1
|
-
# Subscriptions API Specification
|
|
2
|
-
|
|
3
|
-
## Endpoints
|
|
4
|
-
|
|
5
|
-
### 1. Get Subscription
|
|
6
|
-
|
|
7
|
-
**GET** `/api/subscriptions`
|
|
8
|
-
|
|
9
|
-
Headers: `Authorization: Bearer {token}`
|
|
10
|
-
|
|
11
|
-
**Response 200**:
|
|
12
|
-
```json
|
|
13
|
-
{
|
|
14
|
-
"data": {
|
|
15
|
-
"id": "sub-uuid",
|
|
16
|
-
"organizationId": "org-uuid",
|
|
17
|
-
"plan": "pro",
|
|
18
|
-
"status": "active",
|
|
19
|
-
"currentPeriodStart": "2024-01-01T00:00:00Z",
|
|
20
|
-
"currentPeriodEnd": "2024-02-01T00:00:00Z",
|
|
21
|
-
"cancellationScheduledAt": null,
|
|
22
|
-
"createdAt": "2024-01-01T10:00:00Z"
|
|
23
|
-
}
|
|
24
|
-
}
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
---
|
|
28
|
-
|
|
29
|
-
### 2. Create Subscription
|
|
30
|
-
|
|
31
|
-
**POST** `/api/subscriptions`
|
|
32
|
-
|
|
33
|
-
Headers: `Authorization: Bearer {token}`, Content-Type: `application/json`
|
|
34
|
-
|
|
35
|
-
```json
|
|
36
|
-
{
|
|
37
|
-
"plan": "pro"
|
|
38
|
-
}
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
**Response 201**:
|
|
42
|
-
```json
|
|
43
|
-
{
|
|
44
|
-
"data": {
|
|
45
|
-
"id": "sub-uuid",
|
|
46
|
-
"plan": "pro",
|
|
47
|
-
"status": "active",
|
|
48
|
-
"currentPeriodStart": "2024-01-01T00:00:00Z",
|
|
49
|
-
"currentPeriodEnd": "2024-02-01T00:00:00Z"
|
|
50
|
-
}
|
|
51
|
-
}
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
---
|
|
55
|
-
|
|
56
|
-
### 3. Upgrade/Downgrade Plan
|
|
57
|
-
|
|
58
|
-
**POST** `/api/subscriptions/:id/upgrade`
|
|
59
|
-
|
|
60
|
-
```json
|
|
61
|
-
{
|
|
62
|
-
"newPlan": "enterprise"
|
|
63
|
-
}
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
**Response 200**:
|
|
67
|
-
```json
|
|
68
|
-
{
|
|
69
|
-
"data": {
|
|
70
|
-
"id": "sub-uuid",
|
|
71
|
-
"plan": "enterprise",
|
|
72
|
-
"status": "active",
|
|
73
|
-
"upgradedAt": "2024-01-15T14:30:00Z",
|
|
74
|
-
"prorateCharge": 45.67
|
|
75
|
-
}
|
|
76
|
-
}
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
**Error 400**: Transição de plano inválida
|
|
80
|
-
|
|
81
|
-
---
|
|
82
|
-
|
|
83
|
-
### 4. Cancel Subscription
|
|
84
|
-
|
|
85
|
-
**POST** `/api/subscriptions/:id/cancel`
|
|
86
|
-
|
|
87
|
-
```json
|
|
88
|
-
{
|
|
89
|
-
"reason": "Too expensive",
|
|
90
|
-
"immediate": false
|
|
91
|
-
}
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
**Response 200**:
|
|
95
|
-
```json
|
|
96
|
-
{
|
|
97
|
-
"data": {
|
|
98
|
-
"id": "sub-uuid",
|
|
99
|
-
"status": "scheduled_for_cancellation",
|
|
100
|
-
"cancellationScheduledAt": "2024-02-01T00:00:00Z"
|
|
101
|
-
}
|
|
102
|
-
}
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
---
|
|
106
|
-
|
|
107
|
-
### 5. Get Usage Metrics
|
|
108
|
-
|
|
109
|
-
**GET** `/api/subscriptions/usage`
|
|
110
|
-
|
|
111
|
-
**Response 200**:
|
|
112
|
-
```json
|
|
113
|
-
{
|
|
114
|
-
"data": {
|
|
115
|
-
"subscriptionId": "sub-uuid",
|
|
116
|
-
"plan": "pro",
|
|
117
|
-
"apiCallsThisMonth": 45234,
|
|
118
|
-
"apiCallsLimit": 100000,
|
|
119
|
-
"storageUsed": 24.5,
|
|
120
|
-
"storageLimitGB": 100,
|
|
121
|
-
"seatsUsed": 3,
|
|
122
|
-
"seatsIncluded": 5,
|
|
123
|
-
"percentageUtilization": 45.2
|
|
124
|
-
}
|
|
125
|
-
}
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
---
|
|
129
|
-
|
|
130
|
-
## Error Codes
|
|
131
|
-
|
|
132
|
-
| Code | Message | Meaning |
|
|
133
|
-
|------|---------|---------|
|
|
134
|
-
| SUB_001 | Invalid plan transition | Downgrade mid-year ou outro erro |
|
|
135
|
-
| SUB_002 | Subscription not found | Org não tem subscription |
|
|
136
|
-
| SUB_003 | Plan not found | Plano não existe |
|
|
137
|
-
| SUB_004 | Approval required | Upgrade para Enterprise precisa aprovação |
|
|
138
|
-
| SUB_005 | Quota exceeded | Hard limit atingido |
|
|
139
|
-
|
|
140
|
-
## Flow Examples
|
|
141
|
-
|
|
142
|
-
### Scenario: Get Current Subscription
|
|
143
|
-
```bash
|
|
144
|
-
curl -X GET http://localhost:3000/api/subscriptions \
|
|
145
|
-
-H "Authorization: Bearer eyJhbGc..."
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
### Scenario: Upgrade to Pro
|
|
149
|
-
```bash
|
|
150
|
-
curl -X POST http://localhost:3000/api/subscriptions/{id}/upgrade \
|
|
151
|
-
-H "Authorization: Bearer eyJhbGc..." \
|
|
152
|
-
-H "Content-Type: application/json" \
|
|
153
|
-
-d '{ "newPlan": "pro" }'
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
### Scenario: Check Usage
|
|
157
|
-
```bash
|
|
158
|
-
curl -X GET http://localhost:3000/api/subscriptions/usage \
|
|
159
|
-
-H "Authorization: Bearer eyJhbGc..."
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
### Scenario: Cancel Subscription
|
|
163
|
-
```bash
|
|
164
|
-
curl -X POST http://localhost:3000/api/subscriptions/{id}/cancel \
|
|
165
|
-
-H "Authorization: Bearer eyJhbGc..." \
|
|
166
|
-
-H "Content-Type: application/json" \
|
|
167
|
-
-d '{ "reason": "Too expensive", "immediate": false }'
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
## Implementation Notes
|
|
171
|
-
|
|
172
|
-
- Todas operações isoladas por tenant
|
|
173
|
-
- Upgrade cobra pro-rata via Billing Agent
|
|
174
|
-
- Usage tracking é informativo (soft limits)
|
|
175
|
-
- Downgrade efetiva no fim do ciclo
|
|
176
|
-
- Cancellation pode ser imediata ou agendada
|
|
@@ -1,100 +0,0 @@
|
|
|
1
|
-
# Subscriptions Domain Context
|
|
2
|
-
|
|
3
|
-
## O que é Subscription neste SaaS?
|
|
4
|
-
|
|
5
|
-
Um subscription representa um plano escolhido por uma organização, com:
|
|
6
|
-
1. Escolha de plano (free, pro, enterprise)
|
|
7
|
-
2. Tracking de limite de uso (API calls, storage)
|
|
8
|
-
3. Upgrade/downgrade com proration
|
|
9
|
-
4. Eventos de billing vinculados
|
|
10
|
-
|
|
11
|
-
## Planos
|
|
12
|
-
|
|
13
|
-
### Free
|
|
14
|
-
- **Price**: $0/mês
|
|
15
|
-
- **API calls**: 1.000/mês
|
|
16
|
-
- **Storage**: 1GB
|
|
17
|
-
- **Users**: 1
|
|
18
|
-
- **Support**: Community
|
|
19
|
-
|
|
20
|
-
### Pro
|
|
21
|
-
- **Price**: $99/mês (ou $1.188/ano = 20% off)
|
|
22
|
-
- **API calls**: 100.000/mês
|
|
23
|
-
- **Storage**: 100GB
|
|
24
|
-
- **Users**: 5 (+ $10/user adicional)
|
|
25
|
-
- **Support**: Email 24h
|
|
26
|
-
|
|
27
|
-
### Enterprise
|
|
28
|
-
- **Price**: Custom
|
|
29
|
-
- **API calls**: Unlimited
|
|
30
|
-
- **Storage**: Unlimited
|
|
31
|
-
- **Users**: Unlimited
|
|
32
|
-
- **Support**: Dedicated account manager
|
|
33
|
-
|
|
34
|
-
## Fluxo de Upgrade
|
|
35
|
-
|
|
36
|
-
```
|
|
37
|
-
Usuário em Free
|
|
38
|
-
↓ (seleciona Pro)
|
|
39
|
-
Validar transição possível?
|
|
40
|
-
↓ SIM
|
|
41
|
-
Chamar Billing Agent (cobrar cartão)
|
|
42
|
-
↓ (sucesso)
|
|
43
|
-
Atualizar subscription.plan = 'pro'
|
|
44
|
-
Registrar audit log
|
|
45
|
-
↓
|
|
46
|
-
Enviar email confirmação
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
## Regras de Negócio
|
|
50
|
-
|
|
51
|
-
1. **Transições válidas**:
|
|
52
|
-
- Free → Pro: Imediato, charged pro-rata
|
|
53
|
-
- Free → Enterprise: Requires approval
|
|
54
|
-
- Pro → Free: Imediato, credit note gerado
|
|
55
|
-
- Pro → Enterprise: Requer aprovação
|
|
56
|
-
|
|
57
|
-
2. **Pro-rata charging**:
|
|
58
|
-
```
|
|
59
|
-
Days remaining in month = 30 - current_day
|
|
60
|
-
Daily rate = Plan price / 30
|
|
61
|
-
Pro-rata charge = daily_rate * days_remaining
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
3. **Effective dates**:
|
|
65
|
-
- Upgrade: Imediato
|
|
66
|
-
- Downgrade: Fim do ciclo de billing
|
|
67
|
-
|
|
68
|
-
4. **Quotas & Limits**:
|
|
69
|
-
- Free: 1k API calls (soft limit, aviso)
|
|
70
|
-
- Pro: 100k API calls (soft limit, aviso)
|
|
71
|
-
- Hard limits triggerem bloqueio e sugestão de upgrade
|
|
72
|
-
|
|
73
|
-
5. **Annual subscriptions**:
|
|
74
|
-
- 20% desconto (Pro = $1.188/ano)
|
|
75
|
-
- Renova em anniversary date
|
|
76
|
-
- Cannot downgrade mid-year
|
|
77
|
-
|
|
78
|
-
## Métricas Importantes
|
|
79
|
-
|
|
80
|
-
- **MRR** (Monthly Recurring Revenue): Soma de subscriptions ativas × preço
|
|
81
|
-
- **ARR** (Annual Recurring Revenue): MRR × 12
|
|
82
|
-
- **Churn rate**: (Orgs canceladas / Orgs ativas) × 100
|
|
83
|
-
- **Net Retention**: (MRR fim mês - (Downgrade + Churn) + Upgrades) / MRR início
|
|
84
|
-
- **ARPU** (Average Revenue Per User): MRR / Total users
|
|
85
|
-
|
|
86
|
-
## Status Atual
|
|
87
|
-
|
|
88
|
-
- ✅ Subscription entity criada
|
|
89
|
-
- ✅ CRUD endpoints
|
|
90
|
-
- ✅ Plan validation
|
|
91
|
-
- ✅ Upgrade logic
|
|
92
|
-
- 🚧 Annual subscriptions (future)
|
|
93
|
-
- 🚧 Bulk seats billing (future)
|
|
94
|
-
|
|
95
|
-
## Próximos Steps
|
|
96
|
-
|
|
97
|
-
1. Implementar annual subscriptions
|
|
98
|
-
2. Adicionar feature flags por plano
|
|
99
|
-
3. Criar dashboard de uso (consumo de API calls)
|
|
100
|
-
4. Webhooks para mudanças de subscription
|
|
@@ -1,81 +0,0 @@
|
|
|
1
|
-
# Product Backlog
|
|
2
|
-
|
|
3
|
-
## P0 - Critical (Sprint 1-2)
|
|
4
|
-
|
|
5
|
-
- [ ] **Setup**: PostgreSQL + Redis docker-compose
|
|
6
|
-
- [ ] **Auth**: JWT login/signup/refresh
|
|
7
|
-
- [ ] **Organizations**: Multi-tenant isolation
|
|
8
|
-
- [ ] **Users**: RBAC (owner, admin, member)
|
|
9
|
-
- [ ] **Subscriptions**: CRUD endpoints, plan validation
|
|
10
|
-
- [ ] **Billing**: Mock Stripe, invoice generation
|
|
11
|
-
- [ ] **Testing**: E2E tests for core flows
|
|
12
|
-
- [ ] **Documentation**: README, patterns, API docs
|
|
13
|
-
|
|
14
|
-
## P1 - High (Sprint 3-4)
|
|
15
|
-
|
|
16
|
-
- [ ] **Subscriptions**: Annual plans with 20% discount
|
|
17
|
-
- [ ] **Billing**: Retry logic for failed payments
|
|
18
|
-
- [ ] **Email**: Integration hooks for confirmation emails
|
|
19
|
-
- [ ] **Observability**: Structured JSON logging
|
|
20
|
-
- [ ] **Rate limiting**: Per-tenant + per-endpoint
|
|
21
|
-
- [ ] **Error handling**: Standardized error responses
|
|
22
|
-
- [ ] **Dashboard**: Metrics for MRR, churn, ARR
|
|
23
|
-
- [ ] **Database**: Indexes on all queries
|
|
24
|
-
|
|
25
|
-
## P2 - Medium (Q2)
|
|
26
|
-
|
|
27
|
-
- [ ] **Stripe**: Real payment integration
|
|
28
|
-
- [ ] **Webhooks**: Payment event handlers
|
|
29
|
-
- [ ] **Compliance**: GDPR data export
|
|
30
|
-
- [ ] **Audit**: Audit logging for user actions
|
|
31
|
-
- [ ] **Analytics**: Event tracking infrastructure
|
|
32
|
-
- [ ] **Performance**: Query optimization, caching
|
|
33
|
-
- [ ] **Monitoring**: Prometheus + Grafana
|
|
34
|
-
- [ ] **Tracing**: OpenTelemetry integration
|
|
35
|
-
|
|
36
|
-
## P3 - Low (Q3-Q4)
|
|
37
|
-
|
|
38
|
-
- [ ] **Multi-currency**: USD, EUR, GBP support
|
|
39
|
-
- [ ] **Tax**: Sales tax, VAT calculation
|
|
40
|
-
- [ ] **PDF**: Invoice PDF generation
|
|
41
|
-
- [ ] **MFA**: Multi-factor authentication
|
|
42
|
-
- [ ] **SSO**: SAML/OAuth integration
|
|
43
|
-
- [ ] **Mobile**: SDK for mobile apps
|
|
44
|
-
- [ ] **Internationalization**: i18n for UI
|
|
45
|
-
- [ ] **Performance**: Load testing, CDN
|
|
46
|
-
|
|
47
|
-
## Dependencies
|
|
48
|
-
|
|
49
|
-
- Setup must complete before Auth
|
|
50
|
-
- Auth must complete before Subscriptions
|
|
51
|
-
- Subscriptions must complete before Billing
|
|
52
|
-
- Core modules must complete before Analytics
|
|
53
|
-
|
|
54
|
-
## Known Issues
|
|
55
|
-
|
|
56
|
-
| Issue | Priority | Status |
|
|
57
|
-
|-------|----------|--------|
|
|
58
|
-
| None yet | - | - |
|
|
59
|
-
|
|
60
|
-
## Technical Debt
|
|
61
|
-
|
|
62
|
-
| Item | Sprint | Est. Hours |
|
|
63
|
-
|------|--------|-----------|
|
|
64
|
-
| Add integration tests | Sprint 3 | 4 |
|
|
65
|
-
| Refactor service layer | Sprint 4 | 6 |
|
|
66
|
-
| Database index optimization | Sprint 4 | 3 |
|
|
67
|
-
|
|
68
|
-
## Capacity Planning
|
|
69
|
-
|
|
70
|
-
- Team size: 1-3 engineers
|
|
71
|
-
- Velocity: 5-8 points/sprint
|
|
72
|
-
- Sprints per quarter: 12
|
|
73
|
-
- Total Q1 capacity: 60-96 points
|
|
74
|
-
|
|
75
|
-
## Prioritization Framework
|
|
76
|
-
|
|
77
|
-
1. **Frequency**: High-frequency features first (auth used every request)
|
|
78
|
-
2. **Risk**: High-risk features early (multi-tenant isolation)
|
|
79
|
-
3. **Dependencies**: Blockers before blocked
|
|
80
|
-
4. **Business value**: Revenue-impacting features (subscriptions, billing)
|
|
81
|
-
5. **Technical quality**: Testing, docs, patterns (for maintainability)
|