forjajs 5.0.0 → 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 (171) hide show
  1. package/CHANGELOG.md +68 -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/create-memory-nest-kit.js +0 -0
  50. package/dist/bin/forja.js +0 -0
  51. package/dist/bin/init-project.js +1 -0
  52. package/dist/lib/core/journey.js +10 -0
  53. package/dist/lib/generators/memory-generator.d.ts +0 -11
  54. package/dist/lib/generators/memory-generator.js +5 -161
  55. package/dist/lib/generators/readme-generator.js +1 -1
  56. package/dist/lib/llm/json-output.d.ts +14 -0
  57. package/dist/lib/llm/json-output.js +77 -0
  58. package/dist/lib/project-upgrade.d.ts +0 -4
  59. package/dist/lib/project-upgrade.js +19 -1
  60. package/dist/lib/project-wiring.d.ts +8 -0
  61. package/dist/lib/project-wiring.js +74 -2
  62. package/dist/lib/validators/structure-validator.js +0 -1
  63. package/dist/packages/llm/src/index.js +12 -2
  64. package/dist/scripts/llm-fit.js +23 -1
  65. package/dist/scripts/project-upgrade.js +9 -6
  66. package/docs/init-project.md +1 -1
  67. package/docs/llm-fit-loop.md +16 -0
  68. package/memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md +1 -1
  69. package/memory/90-decisions/0088-templates-validados.md +3 -0
  70. package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
  71. package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
  72. package/package.json +2 -2
  73. package/specs/skills-do-projeto/plan.md +40 -0
  74. package/specs/skills-do-projeto/spec.md +63 -0
  75. package/specs/skills-do-projeto/tasks.md +27 -0
  76. package/templates/project/AGENTS.md +9 -0
  77. package/templates/project/agents/context-engineer.md +3 -0
  78. package/templates/project/agents/governance.md +3 -0
  79. package/templates/project/agents/marketing.md +3 -0
  80. package/templates/project/agents/orchestrator.md +3 -0
  81. package/templates/project/agents/product.md +3 -0
  82. package/templates/project/agents/sdd-architect.md +3 -0
  83. package/templates/project/skills/README.md +14 -0
  84. package/templates/project/skills/accessibility-review/SKILL.md +89 -0
  85. package/templates/project/skills/api-design/SKILL.md +77 -0
  86. package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
  87. package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
  88. package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
  89. package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
  90. package/templates/project/skills/commit-message/SKILL.md +143 -0
  91. package/templates/project/skills/data-migrations/SKILL.md +88 -0
  92. package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
  93. package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
  94. package/templates/project/skills/domain-modeling/SKILL.md +120 -0
  95. package/templates/project/skills/event-storming/SKILL.md +95 -0
  96. package/templates/project/skills/executive-writing/SKILL.md +99 -0
  97. package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
  98. package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
  99. package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
  100. package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
  101. package/templates/project/skills/observability/SKILL.md +93 -0
  102. package/templates/project/skills/product-evaluation/SKILL.md +130 -0
  103. package/templates/project/skills/prompt-spec/SKILL.md +83 -0
  104. package/templates/project/skills/pull-request/SKILL.md +101 -0
  105. package/templates/project/skills/query-performance/SKILL.md +83 -0
  106. package/templates/project/skills/release-checklist/SKILL.md +106 -0
  107. package/templates/project/skills/release-notes/SKILL.md +87 -0
  108. package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
  109. package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
  110. package/templates/project/skills/technical-spike/SKILL.md +101 -0
  111. package/templates/project/skills/testing/SKILL.md +109 -0
  112. package/templates/project/skills/threat-modeling/SKILL.md +87 -0
  113. package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
  114. package/templates/project/skills/ts-code-review/SKILL.md +121 -0
  115. package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
  116. package/templates/project/skills/ts-testing/SKILL.md +89 -0
  117. package/templates/project/skills/web-performance/SKILL.md +72 -0
  118. package/boilerplates/02-saas-starter/.env.example +0 -25
  119. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
  120. package/boilerplates/02-saas-starter/INFO.md +0 -252
  121. package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
  122. package/boilerplates/02-saas-starter/START-HERE.md +0 -259
  123. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
  124. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
  125. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
  126. package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
  127. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
  128. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
  129. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
  130. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
  131. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
  132. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
  133. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
  134. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
  135. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
  136. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
  137. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
  138. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
  139. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
  140. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
  141. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
  142. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
  143. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
  144. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
  145. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
  146. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
  147. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
  148. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
  149. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
  150. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
  151. package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
  152. package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
  153. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
  154. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
  155. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
  156. package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
  157. package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
  158. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
  159. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
  160. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
  161. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
  162. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
  163. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
  164. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
  165. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
  166. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
  167. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
  168. package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
  169. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
  170. package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
  171. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
@@ -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)
@@ -1,97 +0,0 @@
1
- # Roadmap 12 Meses
2
-
3
- ## Q1 2024 - MVP (Agora)
4
-
5
- ### Sprint 1-2: Foundation
6
- - ✅ Setup Agent: Environment + schemas
7
- - ✅ Auth Agent: JWT + login/signup
8
- - ✅ Organizations Agent: Multi-tenant structure
9
- - **Target**: 2 semanas
10
-
11
- ### Sprint 3: Subscriptions
12
- - ✅ Subscriptions Agent: CRUD + plan management
13
- - ✅ Billing Agent: Mock Stripe + invoices
14
- - **Target**: 1 semana
15
-
16
- ### Sprint 4: Polish & Testing
17
- - ✅ E2E tests (auth, subscriptions, billing)
18
- - ✅ Documentation (README, patterns)
19
- - ✅ Docker compose ready
20
- - **Target**: 1 semana
21
-
22
- **Q1 Goal**: Scaffold completo, tudo funcionando, documentado.
23
-
24
- ---
25
-
26
- ## Q2 2024 - Real Payments & Analytics
27
-
28
- ### Sprint 5-6: Real Stripe Integration
29
- - Real Stripe API integration
30
- - Webhook handlers
31
- - Refund processing
32
- - Tax calculation (US states)
33
-
34
- ### Sprint 7: Analytics
35
- - Event tracking infrastructure
36
- - Churn monitoring
37
- - MRR/ARR dashboard
38
- - Usage analytics
39
-
40
- **Q2 Goal**: Production payment processing, observability.
41
-
42
- ---
43
-
44
- ## Q3 2024 - Scale & Compliance
45
-
46
- ### Sprint 9-10: Observability
47
- - Prometheus metrics
48
- - Grafana dashboards
49
- - Distributed tracing (OpenTelemetry)
50
- - Error tracking (Sentry)
51
-
52
- ### Sprint 11: Compliance
53
- - SOC2 readiness
54
- - GDPR data export
55
- - Audit logging
56
- - Rate limiting per endpoint
57
-
58
- **Q3 Goal**: Enterprise-ready, auditable, observable.
59
-
60
- ---
61
-
62
- ## Q4 2024 - Internationalization
63
-
64
- ### Sprint 13-14: Multi-Currency
65
- - Multi-currency support
66
- - Exchange rate handling
67
- - Localized pricing
68
- - Regional compliance (EU VAT, etc)
69
-
70
- ### Sprint 15: Performance
71
- - Database query optimization
72
- - Caching strategy refinement
73
- - Bulk operations
74
- - Load testing
75
-
76
- **Q4 Goal**: Global scale, optimized performance.
77
-
78
- ---
79
-
80
- ## Known Risks & Mitigations
81
-
82
- | Risk | Probability | Impact | Mitigation |
83
- |------|-------------|--------|-----------|
84
- | Payment gateway changes | Low | High | Abstract payment layer, easy swap |
85
- | Scale issues in month 3 | Medium | Medium | Load testing in Q2, caching strategy |
86
- | Compliance complexity | High | Medium | Legal review early, audit trails |
87
- | Team onboarding | Medium | Medium | Comprehensive docs, pattern examples |
88
-
89
- ---
90
-
91
- ## Success Metrics
92
-
93
- - **Velocity**: 5 points/sprint (stabilize Q2)
94
- - **Quality**: >80% test coverage, <1% bug escape
95
- - **Deployment**: <30 min per release
96
- - **Documentation**: 100% API endpoints documented
97
- - **Time to MVP**: <4 weeks for new SaaS using this kit