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.
Files changed (164) hide show
  1. package/CHANGELOG.md +38 -2
  2. package/README.md +4 -2
  3. package/README.pt-BR.md +4 -1
  4. package/boilerplates/02-saas-starter/README.md +58 -293
  5. package/boilerplates/02-saas-starter/backend/.env.example +13 -0
  6. package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
  7. package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
  8. package/boilerplates/02-saas-starter/backend/package.json +32 -73
  9. package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
  10. package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
  11. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
  12. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
  13. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
  14. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
  15. package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
  16. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
  17. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
  18. package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
  19. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
  20. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
  21. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
  22. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
  23. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
  24. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
  25. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
  26. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
  27. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
  28. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
  29. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
  30. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
  31. package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
  32. package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
  33. package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
  34. package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
  35. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
  36. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
  37. package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
  38. package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
  39. package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
  40. package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
  41. package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
  42. package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
  43. package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
  44. package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
  45. package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
  46. package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
  47. package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
  48. package/boilerplates/README.md +9 -10
  49. package/dist/bin/init-project.js +1 -0
  50. package/dist/lib/core/journey.js +10 -0
  51. package/dist/lib/generators/memory-generator.d.ts +0 -11
  52. package/dist/lib/generators/memory-generator.js +5 -161
  53. package/dist/lib/generators/readme-generator.js +1 -1
  54. package/dist/lib/llm/json-output.d.ts +14 -0
  55. package/dist/lib/llm/json-output.js +77 -0
  56. package/dist/lib/project-wiring.d.ts +8 -0
  57. package/dist/lib/project-wiring.js +74 -2
  58. package/dist/lib/validators/structure-validator.js +0 -1
  59. package/dist/packages/llm/src/index.js +12 -2
  60. package/dist/scripts/llm-fit.js +23 -1
  61. package/docs/llm-fit-loop.md +16 -0
  62. package/memory/90-decisions/0088-templates-validados.md +3 -0
  63. package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
  64. package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
  65. package/package.json +1 -1
  66. package/specs/skills-do-projeto/plan.md +40 -0
  67. package/specs/skills-do-projeto/spec.md +63 -0
  68. package/specs/skills-do-projeto/tasks.md +27 -0
  69. package/templates/project/AGENTS.md +9 -0
  70. package/templates/project/agents/context-engineer.md +3 -0
  71. package/templates/project/agents/governance.md +3 -0
  72. package/templates/project/agents/marketing.md +3 -0
  73. package/templates/project/agents/orchestrator.md +3 -0
  74. package/templates/project/agents/product.md +3 -0
  75. package/templates/project/agents/sdd-architect.md +3 -0
  76. package/templates/project/skills/README.md +14 -0
  77. package/templates/project/skills/accessibility-review/SKILL.md +89 -0
  78. package/templates/project/skills/api-design/SKILL.md +77 -0
  79. package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
  80. package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
  81. package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
  82. package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
  83. package/templates/project/skills/commit-message/SKILL.md +143 -0
  84. package/templates/project/skills/data-migrations/SKILL.md +88 -0
  85. package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
  86. package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
  87. package/templates/project/skills/domain-modeling/SKILL.md +120 -0
  88. package/templates/project/skills/event-storming/SKILL.md +95 -0
  89. package/templates/project/skills/executive-writing/SKILL.md +99 -0
  90. package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
  91. package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
  92. package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
  93. package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
  94. package/templates/project/skills/observability/SKILL.md +93 -0
  95. package/templates/project/skills/product-evaluation/SKILL.md +130 -0
  96. package/templates/project/skills/prompt-spec/SKILL.md +83 -0
  97. package/templates/project/skills/pull-request/SKILL.md +101 -0
  98. package/templates/project/skills/query-performance/SKILL.md +83 -0
  99. package/templates/project/skills/release-checklist/SKILL.md +106 -0
  100. package/templates/project/skills/release-notes/SKILL.md +87 -0
  101. package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
  102. package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
  103. package/templates/project/skills/technical-spike/SKILL.md +101 -0
  104. package/templates/project/skills/testing/SKILL.md +109 -0
  105. package/templates/project/skills/threat-modeling/SKILL.md +87 -0
  106. package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
  107. package/templates/project/skills/ts-code-review/SKILL.md +121 -0
  108. package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
  109. package/templates/project/skills/ts-testing/SKILL.md +89 -0
  110. package/templates/project/skills/web-performance/SKILL.md +72 -0
  111. package/boilerplates/02-saas-starter/.env.example +0 -25
  112. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
  113. package/boilerplates/02-saas-starter/INFO.md +0 -252
  114. package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
  115. package/boilerplates/02-saas-starter/START-HERE.md +0 -259
  116. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
  117. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
  118. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
  119. package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
  120. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
  121. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
  122. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
  123. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
  124. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
  125. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
  126. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
  127. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
  128. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
  129. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
  130. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
  131. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
  132. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
  133. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
  134. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
  135. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
  136. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
  137. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
  138. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
  139. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
  140. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
  141. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
  142. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
  143. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
  144. package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
  145. package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
  146. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
  147. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
  148. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
  149. package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
  150. package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
  151. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
  152. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
  153. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
  154. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
  155. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
  156. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
  157. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
  158. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
  159. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
  160. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
  161. package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
  162. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
  163. package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
  164. 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)