create-mercato-app 0.6.6-develop.5654.1.ca21e35f26 → 0.6.6-develop.5672.1.11e27afad2
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/agentic/shared/AGENTS.md.template +1 -1
- package/agentic/shared/ai/skills/om-code-review/SKILL.md +9 -45
- package/agentic/shared/ai/skills/om-code-review/references/review-checklist.md +1 -1
- package/agentic/shared/ai/skills/om-module-scaffold/references/naming-conventions.md +4 -14
- package/agentic/shared/ai/skills/om-troubleshooter/SKILL.md +10 -6
- package/dist/agentic/shared/AGENTS.md.template +1 -1
- package/dist/agentic/shared/ai/skills/om-code-review/SKILL.md +9 -45
- package/dist/agentic/shared/ai/skills/om-code-review/references/review-checklist.md +1 -1
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/naming-conventions.md +4 -14
- package/dist/agentic/shared/ai/skills/om-troubleshooter/SKILL.md +10 -6
- package/package.json +1 -1
|
@@ -147,7 +147,7 @@ When the user asks to **create a new application** or a **new module**, do not i
|
|
|
147
147
|
| **Backend admin pages** | Auto-discovered files under `src/modules/<id>/backend/**`, paired `page.meta.ts` with `requireAuth` + `requireFeatures` + `pageGroup`/`pageGroupKey`/`pageOrder` | `.ai/skills/om-backend-ui-design/SKILL.md`, `.ai/skills/om-module-scaffold/references/navigation-patterns.md`; <https://docs.open-mercato.dev/framework/modules/routes-and-pages> |
|
|
148
148
|
| **Frontend public pages** | Auto-discovered files under `src/modules/<id>/frontend/**`. Customer portal pages live under `frontend/[orgSlug]/portal/<path>/page.tsx` with `requireCustomerAuth` / `requireCustomerFeatures` in `page.meta.ts` | `.ai/guides/ui.md` → Portal Extension; <https://docs.open-mercato.dev/framework/modules/routes-and-pages> |
|
|
149
149
|
| **API routes** | Files under `src/modules/<id>/api/**/route.ts` exporting handlers + `metadata` (per-method `requireAuth` / `requireFeatures`) + `openApi`. NEVER write a top-level `export const requireAuth` — the registry no longer recognises it | `.ai/guides/core.md` → API Routes; <https://docs.open-mercato.dev/framework/api/api-development-guide> |
|
|
150
|
-
| **CRUD APIs (factory)** | `makeCrudRoute({
|
|
150
|
+
| **CRUD APIs (factory)** | `makeCrudRoute({ metadata, orm, list, create, update, del, indexer })` from `@open-mercato/shared/lib/crud/factory` (`orm` is required; `list`/`create`/`update`/`del` are the per-operation configs). Always set `indexer` so query-index coverage stays correct. Custom (non-`makeCrudRoute`) write routes MUST call `validateCrudMutationGuard` before the mutation and `runCrudMutationGuardAfterSuccess` after success | `.ai/skills/om-module-scaffold/SKILL.md` → Create API Routes; <https://docs.open-mercato.dev/framework/api/crud-factory> |
|
|
151
151
|
| **CRUD forms in admin** | `<CrudForm entityId apiPath mode fields />` from `@open-mercato/ui/backend/CrudForm`; helpers `createCrud` / `updateCrud` / `deleteCrud` from `@open-mercato/ui/backend/utils/crud`; `createCrudFormError` from `@open-mercato/ui/backend/utils/serverErrors`. Never raw `<form>`, never raw `fetch` | `.ai/skills/om-backend-ui-design/SKILL.md`; <https://docs.open-mercato.dev/framework/admin-ui/crud-form> |
|
|
152
152
|
| **DataTables in admin** | `<DataTable entityId apiPath title columns />` from `@open-mercato/ui/backend/DataTable`. Keep `entityId` and `extensionTableId` stable so widget injection (columns, row actions, bulk actions, filters, toolbar) keeps working | `.ai/skills/om-backend-ui-design/SKILL.md`; <https://docs.open-mercato.dev/framework/admin-ui/data-grids> |
|
|
153
153
|
| **Authorization (RBAC)** | Declare features in `<module>/acl.ts`, grant them in `<module>/setup.ts` `defaultRoleFeatures`, gate pages and routes with `requireFeatures` in `metadata` / `page.meta.ts`. NEVER use `requireRoles` (role names mutate). Run `yarn mercato auth sync-role-acls` after adding new features | `.ai/guides/core.md` → Access Control; <https://docs.open-mercato.dev/framework/rbac/overview> |
|
|
@@ -81,51 +81,15 @@ Omit empty severity sections.
|
|
|
81
81
|
|
|
82
82
|
## Quick Rule Reference
|
|
83
83
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
- **
|
|
87
|
-
- **
|
|
88
|
-
- **
|
|
89
|
-
- **
|
|
90
|
-
- **
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
- **Validate all inputs with zod** in `data/validators.ts`
|
|
95
|
-
- **Use `findWithDecryption`** instead of raw `em.find`/`em.findOne`
|
|
96
|
-
- **Hash passwords with bcryptjs (cost >= 10)** — never log credentials
|
|
97
|
-
- **Every endpoint MUST declare auth guards** (`requireAuth`, `requireRoles`, `requireFeatures`)
|
|
98
|
-
|
|
99
|
-
### Data Integrity
|
|
100
|
-
|
|
101
|
-
- **Migration files and snapshots must match entity intent** — prefer `yarn db:generate`; scoped manual SQL is allowed only to avoid unrelated generated churn and must include `.snapshot-open-mercato.json`
|
|
102
|
-
- **Validate migration scope** — autogenerated doesn't mean correct
|
|
103
|
-
- **Workers/subscribers MUST be idempotent**
|
|
104
|
-
- **Commands MUST be undoable** — include before/after snapshots
|
|
105
|
-
|
|
106
|
-
### Naming
|
|
107
|
-
|
|
108
|
-
- Modules: **plural, snake_case** (folders and `id`)
|
|
109
|
-
- JS/TS identifiers: **camelCase**
|
|
110
|
-
- Database: **snake_case**, table names plural
|
|
111
|
-
- Standard columns: `id`, `created_at`, `updated_at`, `deleted_at`, `is_active`, `organization_id`
|
|
112
|
-
|
|
113
|
-
### UI & HTTP
|
|
114
|
-
|
|
115
|
-
- Forms: `CrudForm` — never custom
|
|
116
|
-
- Tables: `DataTable` — never manual markup
|
|
117
|
-
- Notifications: `flash()` — never `alert()` or custom toast
|
|
118
|
-
- API calls: `apiCall`/`apiCallOrThrow` — never raw `fetch`
|
|
119
|
-
- Dialogs: `Cmd/Ctrl+Enter` (submit), `Escape` (cancel)
|
|
120
|
-
- `pageSize` MUST be <= 100
|
|
121
|
-
|
|
122
|
-
### Code Quality
|
|
123
|
-
|
|
124
|
-
- No `any` types — use zod + `z.infer`
|
|
125
|
-
- No empty `catch` blocks
|
|
126
|
-
- No one-letter variable names
|
|
127
|
-
- Boolean parsing: use `parseBooleanToken`/`parseBooleanWithDefault`
|
|
128
|
-
- Don't add docstrings/comments to code you didn't change
|
|
84
|
+
`AGENTS.md` is the single source of truth for these rules — read it there instead of relying on a copy, so this skill never drifts from the canon. Map the dimension you are reviewing to the owning section:
|
|
85
|
+
|
|
86
|
+
- **Architecture** (FK-only cross-module links, `organization_id` scoping, DI/Awilix, events for side effects, extension entities) → `AGENTS.md` → Architecture Rules + Mandatory Module Mechanisms
|
|
87
|
+
- **Security** (zod validation, `findWithDecryption` over raw `em.find`/`em.findOne`, bcryptjs ≥ 10, never log credentials) → `AGENTS.md` → Data & Security
|
|
88
|
+
- **Authorization (RBAC)** — gate pages and routes with `requireFeatures`; **NEVER `requireRoles`** (role names mutate and can be spoofed) → `AGENTS.md` → Data & Security (RBAC) + Access Control
|
|
89
|
+
- **Data Integrity** (migration files + snapshots match intent, idempotent workers/subscribers, undoable commands) → `AGENTS.md` → CRITICAL Rules + Data & Security
|
|
90
|
+
- **Naming & standard columns** → `AGENTS.md` → Naming Conventions / Conventions
|
|
91
|
+
- **UI & HTTP** (`CrudForm`, `DataTable`, `flash()`, `apiCall` over raw `fetch`, dialog `Cmd/Ctrl+Enter`/`Escape`, `pageSize` ≤ 100) → `AGENTS.md` → UI & HTTP + Mandatory Module Mechanisms
|
|
92
|
+
- **Code Quality** (no `any`, no empty `catch`, no one-letter names, `parseBooleanToken`/`parseBooleanWithDefault`, don't comment code you didn't change) → `AGENTS.md` → Code Quality
|
|
129
93
|
|
|
130
94
|
## Review Heuristics
|
|
131
95
|
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
|
|
13
13
|
- [ ] All inputs validated with zod in `data/validators.ts`
|
|
14
14
|
- [ ] No `any` types
|
|
15
|
-
- [ ] Auth guards on all endpoints (`requireAuth
|
|
15
|
+
- [ ] Auth guards on all endpoints (`requireAuth` + `requireFeatures`; never `requireRoles` — role names mutate)
|
|
16
16
|
- [ ] Passwords hashed with bcryptjs (cost >= 10)
|
|
17
17
|
- [ ] No credentials logged or in error messages
|
|
18
18
|
- [ ] `findWithDecryption` used instead of raw `em.find`/`em.findOne`
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# Naming Conventions Quick Reference
|
|
2
2
|
|
|
3
|
+
> **Source of truth:** `AGENTS.md` (Naming Conventions / Conventions, Architecture Rules, Multi-tenant scoping) owns these rules. This file is an example-oriented cheat sheet for scaffolding — when it disagrees with `AGENTS.md`, `AGENTS.md` wins.
|
|
4
|
+
|
|
3
5
|
## Module & Files
|
|
4
6
|
|
|
5
7
|
| Element | Convention | Example |
|
|
@@ -25,17 +27,7 @@
|
|
|
25
27
|
|
|
26
28
|
## Standard Entity Columns
|
|
27
29
|
|
|
28
|
-
Every tenant-scoped entity MUST
|
|
29
|
-
|
|
30
|
-
```typescript
|
|
31
|
-
id: string // UUID v4 primary key
|
|
32
|
-
organization_id: string // Tenant organization (indexed)
|
|
33
|
-
tenant_id: string // Tenant ID (indexed)
|
|
34
|
-
is_active: boolean // Soft active flag (default: true)
|
|
35
|
-
created_at: Date // Creation timestamp
|
|
36
|
-
updated_at: Date // Last update timestamp (auto-updated)
|
|
37
|
-
deleted_at: Date | null // Soft delete timestamp
|
|
38
|
-
```
|
|
30
|
+
Every tenant-scoped entity MUST carry the standard columns (`id`, `organization_id`, `tenant_id`, `is_active`, `created_at`, `updated_at`, `deleted_at`) with `organization_id`/`tenant_id` indexed. See `AGENTS.md` → Conventions / Multi-tenant scoping for the authoritative list and types.
|
|
39
31
|
|
|
40
32
|
## API Routes
|
|
41
33
|
|
|
@@ -55,6 +47,4 @@ All HTTP methods live in a **single** `api/<entities>/route.ts` that exports nam
|
|
|
55
47
|
|
|
56
48
|
## Cross-Module References
|
|
57
49
|
|
|
58
|
-
-
|
|
59
|
-
- Never use `@ManyToOne` / `@OneToMany` decorators across modules
|
|
60
|
-
- Fetch related data via separate API calls or enrichers
|
|
50
|
+
Store cross-module links as `uuid` FK fields (`customer_id`, `order_id`) and fetch related data via separate API calls or enrichers — never `@ManyToOne` / `@OneToMany` decorators across modules. See `AGENTS.md` → Architecture Rules for the authoritative rule.
|
|
@@ -130,7 +130,7 @@ When in doubt about whether an action mutates state, treat it as mutating and as
|
|
|
130
130
|
|
|
131
131
|
2. **Do pages export `metadata` with `requireAuth`?**
|
|
132
132
|
```typescript
|
|
133
|
-
export const metadata = { requireAuth: true,
|
|
133
|
+
export const metadata = { requireAuth: true, requireFeatures: ['<module_id>.view'] }
|
|
134
134
|
```
|
|
135
135
|
Proposed fix: Add metadata export.
|
|
136
136
|
|
|
@@ -209,12 +209,16 @@ When in doubt about whether an action mutates state, treat it as mutating and as
|
|
|
209
209
|
**Checklist**:
|
|
210
210
|
|
|
211
211
|
1. **Is the file in the correct path?**
|
|
212
|
-
`src/modules/<module_id>/api/<
|
|
213
|
-
Method folders: `get/`, `post/`, `put/`, `delete/`
|
|
212
|
+
`src/modules/<module_id>/api/<resource>/route.ts` — all HTTP methods live in a single `route.ts`. Use path-based folders (`<resource>/`, `<resource>/[id]/`), never per-method `get/`/`post/`/`put/`/`delete/` folders.
|
|
214
213
|
|
|
215
|
-
2. **Does it export
|
|
214
|
+
2. **Does it export per-method handlers plus `metadata`?**
|
|
216
215
|
```typescript
|
|
217
|
-
export
|
|
216
|
+
export const metadata = {
|
|
217
|
+
GET: { requireAuth: true, requireFeatures: ['<module_id>.view'] },
|
|
218
|
+
POST: { requireAuth: true, requireFeatures: ['<module_id>.manage'] },
|
|
219
|
+
}
|
|
220
|
+
export async function GET(req: Request) { /* ... */ }
|
|
221
|
+
export async function POST(req: Request) { /* ... */ }
|
|
218
222
|
```
|
|
219
223
|
|
|
220
224
|
3. **Does it export `openApi`?**
|
|
@@ -290,7 +294,7 @@ export const metadata = { icon: <Trophy className="size-4" /> }
|
|
|
290
294
|
1. **Check browser network tab** — look for the POST/PUT request and response
|
|
291
295
|
2. **Is the zod schema matching the form fields?** Mismatched field names cause silent failures
|
|
292
296
|
3. **Are required fields filled?** Check form validation
|
|
293
|
-
4. **Does the API route handle the HTTP method?** Check `api
|
|
297
|
+
4. **Does the API route handle the HTTP method?** Check `api/<resource>/route.ts` exports a `POST`/`PUT` handler (and lists it in `metadata`)
|
|
294
298
|
|
|
295
299
|
---
|
|
296
300
|
|
|
@@ -147,7 +147,7 @@ When the user asks to **create a new application** or a **new module**, do not i
|
|
|
147
147
|
| **Backend admin pages** | Auto-discovered files under `src/modules/<id>/backend/**`, paired `page.meta.ts` with `requireAuth` + `requireFeatures` + `pageGroup`/`pageGroupKey`/`pageOrder` | `.ai/skills/om-backend-ui-design/SKILL.md`, `.ai/skills/om-module-scaffold/references/navigation-patterns.md`; <https://docs.open-mercato.dev/framework/modules/routes-and-pages> |
|
|
148
148
|
| **Frontend public pages** | Auto-discovered files under `src/modules/<id>/frontend/**`. Customer portal pages live under `frontend/[orgSlug]/portal/<path>/page.tsx` with `requireCustomerAuth` / `requireCustomerFeatures` in `page.meta.ts` | `.ai/guides/ui.md` → Portal Extension; <https://docs.open-mercato.dev/framework/modules/routes-and-pages> |
|
|
149
149
|
| **API routes** | Files under `src/modules/<id>/api/**/route.ts` exporting handlers + `metadata` (per-method `requireAuth` / `requireFeatures`) + `openApi`. NEVER write a top-level `export const requireAuth` — the registry no longer recognises it | `.ai/guides/core.md` → API Routes; <https://docs.open-mercato.dev/framework/api/api-development-guide> |
|
|
150
|
-
| **CRUD APIs (factory)** | `makeCrudRoute({
|
|
150
|
+
| **CRUD APIs (factory)** | `makeCrudRoute({ metadata, orm, list, create, update, del, indexer })` from `@open-mercato/shared/lib/crud/factory` (`orm` is required; `list`/`create`/`update`/`del` are the per-operation configs). Always set `indexer` so query-index coverage stays correct. Custom (non-`makeCrudRoute`) write routes MUST call `validateCrudMutationGuard` before the mutation and `runCrudMutationGuardAfterSuccess` after success | `.ai/skills/om-module-scaffold/SKILL.md` → Create API Routes; <https://docs.open-mercato.dev/framework/api/crud-factory> |
|
|
151
151
|
| **CRUD forms in admin** | `<CrudForm entityId apiPath mode fields />` from `@open-mercato/ui/backend/CrudForm`; helpers `createCrud` / `updateCrud` / `deleteCrud` from `@open-mercato/ui/backend/utils/crud`; `createCrudFormError` from `@open-mercato/ui/backend/utils/serverErrors`. Never raw `<form>`, never raw `fetch` | `.ai/skills/om-backend-ui-design/SKILL.md`; <https://docs.open-mercato.dev/framework/admin-ui/crud-form> |
|
|
152
152
|
| **DataTables in admin** | `<DataTable entityId apiPath title columns />` from `@open-mercato/ui/backend/DataTable`. Keep `entityId` and `extensionTableId` stable so widget injection (columns, row actions, bulk actions, filters, toolbar) keeps working | `.ai/skills/om-backend-ui-design/SKILL.md`; <https://docs.open-mercato.dev/framework/admin-ui/data-grids> |
|
|
153
153
|
| **Authorization (RBAC)** | Declare features in `<module>/acl.ts`, grant them in `<module>/setup.ts` `defaultRoleFeatures`, gate pages and routes with `requireFeatures` in `metadata` / `page.meta.ts`. NEVER use `requireRoles` (role names mutate). Run `yarn mercato auth sync-role-acls` after adding new features | `.ai/guides/core.md` → Access Control; <https://docs.open-mercato.dev/framework/rbac/overview> |
|
|
@@ -81,51 +81,15 @@ Omit empty severity sections.
|
|
|
81
81
|
|
|
82
82
|
## Quick Rule Reference
|
|
83
83
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
- **
|
|
87
|
-
- **
|
|
88
|
-
- **
|
|
89
|
-
- **
|
|
90
|
-
- **
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
- **Validate all inputs with zod** in `data/validators.ts`
|
|
95
|
-
- **Use `findWithDecryption`** instead of raw `em.find`/`em.findOne`
|
|
96
|
-
- **Hash passwords with bcryptjs (cost >= 10)** — never log credentials
|
|
97
|
-
- **Every endpoint MUST declare auth guards** (`requireAuth`, `requireRoles`, `requireFeatures`)
|
|
98
|
-
|
|
99
|
-
### Data Integrity
|
|
100
|
-
|
|
101
|
-
- **Migration files and snapshots must match entity intent** — prefer `yarn db:generate`; scoped manual SQL is allowed only to avoid unrelated generated churn and must include `.snapshot-open-mercato.json`
|
|
102
|
-
- **Validate migration scope** — autogenerated doesn't mean correct
|
|
103
|
-
- **Workers/subscribers MUST be idempotent**
|
|
104
|
-
- **Commands MUST be undoable** — include before/after snapshots
|
|
105
|
-
|
|
106
|
-
### Naming
|
|
107
|
-
|
|
108
|
-
- Modules: **plural, snake_case** (folders and `id`)
|
|
109
|
-
- JS/TS identifiers: **camelCase**
|
|
110
|
-
- Database: **snake_case**, table names plural
|
|
111
|
-
- Standard columns: `id`, `created_at`, `updated_at`, `deleted_at`, `is_active`, `organization_id`
|
|
112
|
-
|
|
113
|
-
### UI & HTTP
|
|
114
|
-
|
|
115
|
-
- Forms: `CrudForm` — never custom
|
|
116
|
-
- Tables: `DataTable` — never manual markup
|
|
117
|
-
- Notifications: `flash()` — never `alert()` or custom toast
|
|
118
|
-
- API calls: `apiCall`/`apiCallOrThrow` — never raw `fetch`
|
|
119
|
-
- Dialogs: `Cmd/Ctrl+Enter` (submit), `Escape` (cancel)
|
|
120
|
-
- `pageSize` MUST be <= 100
|
|
121
|
-
|
|
122
|
-
### Code Quality
|
|
123
|
-
|
|
124
|
-
- No `any` types — use zod + `z.infer`
|
|
125
|
-
- No empty `catch` blocks
|
|
126
|
-
- No one-letter variable names
|
|
127
|
-
- Boolean parsing: use `parseBooleanToken`/`parseBooleanWithDefault`
|
|
128
|
-
- Don't add docstrings/comments to code you didn't change
|
|
84
|
+
`AGENTS.md` is the single source of truth for these rules — read it there instead of relying on a copy, so this skill never drifts from the canon. Map the dimension you are reviewing to the owning section:
|
|
85
|
+
|
|
86
|
+
- **Architecture** (FK-only cross-module links, `organization_id` scoping, DI/Awilix, events for side effects, extension entities) → `AGENTS.md` → Architecture Rules + Mandatory Module Mechanisms
|
|
87
|
+
- **Security** (zod validation, `findWithDecryption` over raw `em.find`/`em.findOne`, bcryptjs ≥ 10, never log credentials) → `AGENTS.md` → Data & Security
|
|
88
|
+
- **Authorization (RBAC)** — gate pages and routes with `requireFeatures`; **NEVER `requireRoles`** (role names mutate and can be spoofed) → `AGENTS.md` → Data & Security (RBAC) + Access Control
|
|
89
|
+
- **Data Integrity** (migration files + snapshots match intent, idempotent workers/subscribers, undoable commands) → `AGENTS.md` → CRITICAL Rules + Data & Security
|
|
90
|
+
- **Naming & standard columns** → `AGENTS.md` → Naming Conventions / Conventions
|
|
91
|
+
- **UI & HTTP** (`CrudForm`, `DataTable`, `flash()`, `apiCall` over raw `fetch`, dialog `Cmd/Ctrl+Enter`/`Escape`, `pageSize` ≤ 100) → `AGENTS.md` → UI & HTTP + Mandatory Module Mechanisms
|
|
92
|
+
- **Code Quality** (no `any`, no empty `catch`, no one-letter names, `parseBooleanToken`/`parseBooleanWithDefault`, don't comment code you didn't change) → `AGENTS.md` → Code Quality
|
|
129
93
|
|
|
130
94
|
## Review Heuristics
|
|
131
95
|
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
|
|
13
13
|
- [ ] All inputs validated with zod in `data/validators.ts`
|
|
14
14
|
- [ ] No `any` types
|
|
15
|
-
- [ ] Auth guards on all endpoints (`requireAuth
|
|
15
|
+
- [ ] Auth guards on all endpoints (`requireAuth` + `requireFeatures`; never `requireRoles` — role names mutate)
|
|
16
16
|
- [ ] Passwords hashed with bcryptjs (cost >= 10)
|
|
17
17
|
- [ ] No credentials logged or in error messages
|
|
18
18
|
- [ ] `findWithDecryption` used instead of raw `em.find`/`em.findOne`
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# Naming Conventions Quick Reference
|
|
2
2
|
|
|
3
|
+
> **Source of truth:** `AGENTS.md` (Naming Conventions / Conventions, Architecture Rules, Multi-tenant scoping) owns these rules. This file is an example-oriented cheat sheet for scaffolding — when it disagrees with `AGENTS.md`, `AGENTS.md` wins.
|
|
4
|
+
|
|
3
5
|
## Module & Files
|
|
4
6
|
|
|
5
7
|
| Element | Convention | Example |
|
|
@@ -25,17 +27,7 @@
|
|
|
25
27
|
|
|
26
28
|
## Standard Entity Columns
|
|
27
29
|
|
|
28
|
-
Every tenant-scoped entity MUST
|
|
29
|
-
|
|
30
|
-
```typescript
|
|
31
|
-
id: string // UUID v4 primary key
|
|
32
|
-
organization_id: string // Tenant organization (indexed)
|
|
33
|
-
tenant_id: string // Tenant ID (indexed)
|
|
34
|
-
is_active: boolean // Soft active flag (default: true)
|
|
35
|
-
created_at: Date // Creation timestamp
|
|
36
|
-
updated_at: Date // Last update timestamp (auto-updated)
|
|
37
|
-
deleted_at: Date | null // Soft delete timestamp
|
|
38
|
-
```
|
|
30
|
+
Every tenant-scoped entity MUST carry the standard columns (`id`, `organization_id`, `tenant_id`, `is_active`, `created_at`, `updated_at`, `deleted_at`) with `organization_id`/`tenant_id` indexed. See `AGENTS.md` → Conventions / Multi-tenant scoping for the authoritative list and types.
|
|
39
31
|
|
|
40
32
|
## API Routes
|
|
41
33
|
|
|
@@ -55,6 +47,4 @@ All HTTP methods live in a **single** `api/<entities>/route.ts` that exports nam
|
|
|
55
47
|
|
|
56
48
|
## Cross-Module References
|
|
57
49
|
|
|
58
|
-
-
|
|
59
|
-
- Never use `@ManyToOne` / `@OneToMany` decorators across modules
|
|
60
|
-
- Fetch related data via separate API calls or enrichers
|
|
50
|
+
Store cross-module links as `uuid` FK fields (`customer_id`, `order_id`) and fetch related data via separate API calls or enrichers — never `@ManyToOne` / `@OneToMany` decorators across modules. See `AGENTS.md` → Architecture Rules for the authoritative rule.
|
|
@@ -130,7 +130,7 @@ When in doubt about whether an action mutates state, treat it as mutating and as
|
|
|
130
130
|
|
|
131
131
|
2. **Do pages export `metadata` with `requireAuth`?**
|
|
132
132
|
```typescript
|
|
133
|
-
export const metadata = { requireAuth: true,
|
|
133
|
+
export const metadata = { requireAuth: true, requireFeatures: ['<module_id>.view'] }
|
|
134
134
|
```
|
|
135
135
|
Proposed fix: Add metadata export.
|
|
136
136
|
|
|
@@ -209,12 +209,16 @@ When in doubt about whether an action mutates state, treat it as mutating and as
|
|
|
209
209
|
**Checklist**:
|
|
210
210
|
|
|
211
211
|
1. **Is the file in the correct path?**
|
|
212
|
-
`src/modules/<module_id>/api/<
|
|
213
|
-
Method folders: `get/`, `post/`, `put/`, `delete/`
|
|
212
|
+
`src/modules/<module_id>/api/<resource>/route.ts` — all HTTP methods live in a single `route.ts`. Use path-based folders (`<resource>/`, `<resource>/[id]/`), never per-method `get/`/`post/`/`put/`/`delete/` folders.
|
|
214
213
|
|
|
215
|
-
2. **Does it export
|
|
214
|
+
2. **Does it export per-method handlers plus `metadata`?**
|
|
216
215
|
```typescript
|
|
217
|
-
export
|
|
216
|
+
export const metadata = {
|
|
217
|
+
GET: { requireAuth: true, requireFeatures: ['<module_id>.view'] },
|
|
218
|
+
POST: { requireAuth: true, requireFeatures: ['<module_id>.manage'] },
|
|
219
|
+
}
|
|
220
|
+
export async function GET(req: Request) { /* ... */ }
|
|
221
|
+
export async function POST(req: Request) { /* ... */ }
|
|
218
222
|
```
|
|
219
223
|
|
|
220
224
|
3. **Does it export `openApi`?**
|
|
@@ -290,7 +294,7 @@ export const metadata = { icon: <Trophy className="size-4" /> }
|
|
|
290
294
|
1. **Check browser network tab** — look for the POST/PUT request and response
|
|
291
295
|
2. **Is the zod schema matching the form fields?** Mismatched field names cause silent failures
|
|
292
296
|
3. **Are required fields filled?** Check form validation
|
|
293
|
-
4. **Does the API route handle the HTTP method?** Check `api
|
|
297
|
+
4. **Does the API route handle the HTTP method?** Check `api/<resource>/route.ts` exports a `POST`/`PUT` handler (and lists it in `metadata`)
|
|
294
298
|
|
|
295
299
|
---
|
|
296
300
|
|