modern-admin-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Modern Admin — Integration skill

Modern Admin — 集成技能

Modern Admin is a vendor framework. Treat

@modern-admin/*

as read-only; only call its public exports. This skill encodes the project's non-obvious rules so you don't re-discover them.

Modern Admin是一个供应商框架。请将

@modern-admin/*

视为只读；仅调用其公开导出的内容。本技能收录了项目中的非显性规则，帮你避免重复踩坑。

Ground rules (always apply)

基本规则（始终适用）

bun only. Never
```
npm
```
/
```
yarn
```
/
```
pnpm
```
.

UUID v7 for every generated id.

import { uuidv7 } from '@modern-admin/core'

. Never

crypto.randomUUID()

randomUUID()

nanoid

. Don't trust

@default(uuid(7))

— generate in app code.

Latest stable versions. Adapt code to new APIs; never pin older to dodge breaking changes.
i18n everywhere. No hardcoded user-visible strings. Add keys to
```
packages/i18n/src/locales/en.ts
```
AND mirror to all 8 other locales (
```
de
```
/
```
es
```
/
```
fr
```
/
```
it
```
/
```
ja
```
/
```
pl
```
/
```
pt-BR
```
/
```
ru
```
). UI components stay i18n-unaware (
```
labels?: {...}
```
prop);
```
packages/react
```
is the translation boundary. See
```
references/conventions.md
```
.
Mobile-first. Verify every new UI at ≤375px viewport.
Auto-discovery beats config. Override only what diverges.

仅使用bun。绝不使用
```
npm
```
/
```
yarn
```
/
```
pnpm
```
。
所有生成的ID均使用UUID v7。导入
```
import { uuidv7 } from '@modern-admin/core'
```
。绝不使用
```
crypto.randomUUID()
```
、
```
randomUUID()
```
、
```
nanoid
```
。不要信任
```
@default(uuid(7))
```
——在应用代码中生成。
始终使用最新稳定版本。适配新API；绝不通过锁定旧版本来规避破坏性变更。
全流程国际化。禁止硬编码用户可见字符串。将键添加至
```
packages/i18n/src/locales/en.ts
```
，并同步到其他8种语言（
```
de
```
/
```
es
```
/
```
fr
```
/
```
it
```
/
```
ja
```
/
```
pl
```
/
```
pt-BR
```
/
```
ru
```
）。UI组件保持无感知国际化（通过
```
labels?: {...}
```
属性传递）；
```
packages/react
```
是翻译边界。详见
```
references/conventions.md
```
。
移动端优先。验证每个新UI在≤375px视口下的表现。
自动发现优于配置。仅覆盖与默认规则不符的部分。

When to use Modern Admin

Modern Admin的适用场景

Use it for CRUD-over-Postgres admin panels (Prisma 7 / Drizzle 0.45) with role-gated actions, search, filters, uploads, audit log, revisions, webhooks, AI assistant. Don't use it for public UI, non-relational stores, or when admin shouldn't share a DB with main app (use it as a separate service against a replica instead).

适用于基于Postgres的CRUD管理面板（Prisma 7 / Drizzle 0.45），支持角色权限控制、搜索、筛选、上传、审计日志、版本回溯、Webhook、AI助手。请勿将其用于公共UI、非关系型存储，或管理面板不应与主应用共享数据库的场景（此时应将其作为独立服务连接至副本数据库）。

Deployment model — default to standalone

部署模型——默认采用独立部署

Recommended layout: separate NestJS 11 service against the same Postgres. Scaffold with

MODERN_ADMIN_TOKEN=ghp_xxx bun create @modern-admin admin-service

. Mount behind

/admin

of the main domain via reverse proxy. See

references/deployment.md

for the existing-Prisma reuse rules (one schema, one client; never add a second

generator

) and the fourteen

Ma*

models that must be copied verbatim —

setupPrismaSystem

fails at boot if any are missing.

推荐架构：独立的NestJS 11服务连接至同一Postgres数据库。使用

MODERN_ADMIN_TOKEN=ghp_xxx bun create @modern-admin admin-service

搭建项目。通过反向代理挂载至主域名的

/admin

路径下。现有Prisma复用规则详见

references/deployment.md

（单一schema、单一客户端；绝不添加第二个

generator

），必须完整复制的14个

Ma*

模型——若缺失任何一个，

setupPrismaSystem

会在启动时失败。

The three pieces of every resource

每个资源的三个核心部分

Source registry (
```
src/admin-sources.ts
```
) — maps logical resource ids to adapter-specific raw source objects via
```
registerAdminSources({...})
```
. Import as a side-effect before
```
NestFactory.create
```
in
```
main.ts
```
.
Resource controller —
```
extends AdminController<Row>
```
(never body-less), carries
```
@AdminResource(...)
```
metadata +
```
@Before
```
/
```
@After
```
hooks +
```
@Action
```
methods.

NestJS module —

@Module({ controllers: [FooAdminController] })

See

references/resources.md

for the canonical Prisma source factory (including the critical relation-field-

type

rewrite for FK→reference resolution), the resource-creation 8-step checklist, and the property-type selection matrix.

源注册表（
```
src/admin-sources.ts
```
）——通过
```
registerAdminSources({...})
```
将逻辑资源ID映射到适配器特定的原始源对象。在
```
main.ts
```
的
```
NestFactory.create
```
之前作为副作用导入。
资源控制器——
```
extends AdminController<Row>
```
（绝不能为空实现），包含
```
@AdminResource(...)
```
元数据 +
```
@Before
```
/
```
@After
```
钩子 +
```
@Action
```
方法。

NestJS模块——

@Module({ controllers: [FooAdminController] })

。

标准Prisma源工厂（包括用于外键→引用解析的关键关联字段

type

重写）、资源创建8步清单、属性类型选择矩阵详见

references/resources.md

。

NestJS-style permissions —

actions:

key is FORBIDDEN

NestJS风格权限——禁止使用

actions:

字段

The #1 mistake AI agents make.

AdminResourceMeta = Omit<ResourceOptions, 'actions'> & {source, ...}

. Writing

@AdminResource({ actions: {...} })

is a

TS2353

. All action config goes through

@Action

@Before

@After

method decorators, or — for role gating — through

MaRole.permissions

(DB-driven, edited in the panel). Code-pinned

isAccessible

is reserved for invariants no role may bypass. See

references/permissions.md

for the role-matrix recipe, true- invariant

Promise<never>

stubs, base-class signature matching for overrides (avoid

TS2416

), and the

guard:

isAccessible:

distinction.

AI助手最常犯的错误。

AdminResourceMeta = Omit<ResourceOptions, 'actions'> & {source, ...}

。编写

@AdminResource({ actions: {...} })

会触发

TS2353

错误。所有动作配置需通过

@Action

@Before

@After

方法装饰器完成，或——针对角色权限控制——通过

MaRole.permissions

（数据库驱动，可在面板中编辑）完成。代码固定的

isAccessible

仅用于所有角色都无法绕过的不变规则。角色矩阵方案、真正不变规则的

Promise<never>

占位符、用于重写的基类签名匹配（避免

TS2416

）、

guard:

与

isAccessible:

的区别详见

references/permissions.md

。

Auth wiring — the five must-knows

认证配置——必须掌握的五点

admin()
plugin is MANDATORY when using
```
rolesResourceId
```
. Without it
```
session.user.role
```
is
```
undefined
```
and every role-gated action returns 403 — even when
```
ma_user.role
```
is
```
'admin'
```
in the database.

Mount Better Auth via
createBetterAuthMiddleware(toNodeHandler(auth))
, not bare
toNodeHandler
. The bare handler is greedy and shadows

AuthController

/login

/me

/ui-props

with its own 404s.

ModernAdminStaticUiModule.forRoot({ path: '/admin', ... })
is REQUIRED to serve the SPA + handle deep-link refreshes. Without it
```
/admin
```
and every refresh 404s.
RedisCacheProvider({ client, subscriber })
— pass clients, not URLs. ioredis can't multiplex pub/sub on a command connection.

Keep
app.use(<basePath>, ...)
,
betterAuth({ basePath })
, and
runtimeConfig.authBasePath
in lockstep. A mismatch surfaces as

POST /api/auth/sign-in/email 404

on login.

Full details + code examples:

references/auth-and-infra.md

使用
rolesResourceId
时，
admin()
插件是强制要求。若无此插件，
```
session.user.role
```
会是
```
undefined
```
，所有角色权限控制的动作都会返回403——即使数据库中
```
ma_user.role
```
为
```
'admin'
```
。
通过
createBetterAuthMiddleware(toNodeHandler(auth))
挂载Better Auth，而非直接使用
toNodeHandler
。直接使用处理器会抢占
```
AuthController
```
的
```
/login
```
、
```
/me
```
、
```
/ui-props
```
路径，导致这些接口返回404。
必须配置
ModernAdminStaticUiModule.forRoot({ path: '/admin', ... })
，用于提供SPA服务并处理深度链接刷新。若无此配置，
```
/admin
```
路径及所有刷新操作都会返回404。
RedisCacheProvider({ client, subscriber })
——传递客户端实例，而非URL。ioredis无法在命令连接上复用发布/订阅功能。

保持
app.use(<basePath>, ...)
、
betterAuth({ basePath })
和
runtimeConfig.authBasePath
三者一致。不匹配会导致登录时出现

POST /api/auth/sign-in/email 404

错误。

完整细节及代码示例：

references/auth-and-infra.md

。

References

参考文档

```
./references/deployment.md
```
— §2 standalone deploy, §2.5 reusing existing Prisma schema, the 14
```
Ma*
```
models, anti-pattern of duplicated generators.
```
./references/resources.md
```
— §3 the three-pieces recipe, source registry, resource controller, 8-step per-resource checklist, §4 property-type matrix, §5 hide vs. expose (
```
isVisible
```
vs
```
isAccessible
```
).
```
./references/permissions.md
```
— §6 roles × actions, DB-driven vs code-pinned,
```
actions:
```
forbidden, read-only via roles, base-class signature, true invariants, sealed-invariant property
```
isAccessible
```
,
```
guard:
```
vs permissions.
```
./references/actions-and-plugins.md
```
— §7 built-in actions and when to override, §8 plugin/feature selection guide, §10 hooks vs actions vs handlers.
```
./references/custom-ui.md
```
— §9 when to write a custom component, the three-step workflow,
```
@modern-admin/ui
```
primitives, Tailwind 4
```
border
```
rule.

./references/auth-and-infra.md

— §11 a–f:

BetterAuthProvider

wiring,

RedisCacheProvider

ModernAdminStaticUiModule

createBetterAuthMiddleware

admin()

plugin requirement,

BigInt

serialisation.

```
./references/conventions.md
```
— §12 i18n boundary, §13 UUID v7, §14 cache + realtime.
```
./references/anti-patterns.md
```
— §15 full anti-pattern list, §16 verification checklist, §17 reference index of canonical files.

```
./references/deployment.md
```
— §2独立部署，§2.5复用现有Prisma schema，14个
```
Ma*
```
模型，重复generator的反模式。
```
./references/resources.md
```
— §3三部分方案，源注册表，资源控制器，每个资源的8步清单，§4属性类型矩阵，§5隐藏与暴露（
```
isVisible
```
vs
```
isAccessible
```
）。
```
./references/permissions.md
```
— §6角色×动作，数据库驱动vs代码固定，禁止使用
```
actions:
```
，通过角色设置只读，基类签名，真正不变规则，密封不变属性
```
isAccessible
```
，
```
guard:
```
vs 权限。
```
./references/actions-and-plugins.md
```
— §7内置动作及重写时机，§8插件/功能选择指南，§10钩子vs动作vs处理器。
```
./references/custom-ui.md
```
— §9自定义组件的编写时机，三步工作流，
```
@modern-admin/ui
```
基础组件，Tailwind 4
```
border
```
规则。

./references/auth-and-infra.md

— §11 a–f：

BetterAuthProvider

配置，

RedisCacheProvider

，

ModernAdminStaticUiModule

，

createBetterAuthMiddleware

，

admin()

插件要求，

BigInt

序列化。

```
./references/conventions.md
```
— §12国际化边界，§13 UUID v7，§14缓存+实时性。
```
./references/anti-patterns.md
```
— §15完整反模式列表，§16验证清单，§17标准文件参考索引。

Verification checklist (always run before "done")

验证清单（完成前必须执行）

bun run dev

(or

scripts/dev.sh start api-prisma web

) starts clean;

.dev-logs/

show no errors.

Seed admin can log in at
```
/admin
```
and sees every registered resource.
Sensitive columns (
```
password
```
,
```
apiKey
```
, …) absent from both JSON and UI.
Every destructive action has
```
guard:
```
confirm +
```
isAccessible
```
role check.
Every new visible string exists in all 9 locale files.
```
bun run typecheck
```
is green workspace-wide.
Tests added for every custom hook, action handler, UI component.
375px viewport: list/show/edit pages have no horizontal page scroll.

bun run dev

（或

scripts/dev.sh start api-prisma web

）启动无异常；

.dev-logs/

中无错误日志。

种子管理员可在
```
/admin
```
登录，并能看到所有已注册资源。
敏感列（
```
password
```
、
```
apiKey
```
等）在JSON和UI中均不可见。
所有破坏性动作均配置
```
guard:
```
确认 +
```
isAccessible
```
角色校验。
每个新增可见字符串均存在于所有9个语言文件中。
```
bun run typecheck
```
在整个工作区中执行通过。
为每个自定义钩子、动作处理器、UI组件添加测试。
375px视口下：列表/详情/编辑页面无横向滚动条。

Canonical files to read before writing new code

编写新代码前必读的标准文件

apps/_shared/src/admin/posts/posts.controller.ts

— hooks + record + bulk actions.

apps/_shared/src/admin/customers/customers.controller.ts

—

passwordsFeature

aiFillFeature

+ custom action.

apps/_shared/src/admin/source-registry.ts

— source registry.

```
apps/api-prisma/src/admin-sources.ts
```
— logical-id mapping + relation field rewriting.
```
apps/api-prisma/src/admin.module.ts
```
— admin module wiring.

packages/core/src/decorators/{resource,property,action}-options.ts

— schemas.

packages/core/src/actions/action.ts

packages/core/src/ports/current-admin.ts

—

ActionContext

CurrentAdmin

types for

isAccessible

isVisible

callbacks.

packages/nest/src/admin/decorators.ts

—

AdminController

@Before

@After

@Action

When in doubt, read the source — every public export has JSDoc explaining its contract.

apps/_shared/src/admin/posts/posts.controller.ts

— 钩子 + 单条/批量动作。

apps/_shared/src/admin/customers/customers.controller.ts

—

passwordsFeature

aiFillFeature

+ 自定义动作。

apps/_shared/src/admin/source-registry.ts

— 源注册表。

```
apps/api-prisma/src/admin-sources.ts
```
— 逻辑ID映射 + 关联字段重写。
```
apps/api-prisma/src/admin.module.ts
```
— 管理模块配置。

packages/core/src/decorators/{resource,property,action}-options.ts

— schema定义。

packages/core/src/actions/action.ts

、

packages/core/src/ports/current-admin.ts

—

ActionContext

、

CurrentAdmin

类型，用于

isAccessible

isVisible

回调。

packages/nest/src/admin/decorators.ts

—

AdminController

、

@Before

、

@After

、

@Action

装饰器。

如有疑问，阅读源码——每个公开导出的内容都有JSDoc说明其契约。

modern-admin-integration

Original

Translation

Modern Admin — Integration skill

Modern Admin — 集成技能

Ground rules (always apply)

基本规则（始终适用）

When to use Modern Admin

Modern Admin的适用场景

Deployment model — default to standalone

部署模型——默认采用独立部署

The three pieces of every resource

每个资源的三个核心部分

NestJS-style permissions —
`actions:`
key is FORBIDDEN

NestJS风格权限——禁止使用
`actions:`
字段

Auth wiring — the five must-knows

认证配置——必须掌握的五点

References

参考文档

Verification checklist (always run before "done")

验证清单（完成前必须执行）

Canonical files to read before writing new code

编写新代码前必读的标准文件

modern-admin-integration

Original

Translation

Modern Admin — Integration skill

Modern Admin — 集成技能

Ground rules (always apply)

基本规则（始终适用）

When to use Modern Admin

Modern Admin的适用场景

Deployment model — default to standalone

部署模型——默认采用独立部署

The three pieces of every resource

每个资源的三个核心部分

NestJS-style permissions — actions: key is FORBIDDEN

NestJS风格权限——禁止使用actions:字段

Auth wiring — the five must-knows

认证配置——必须掌握的五点

References

参考文档

Verification checklist (always run before "done")

验证清单（完成前必须执行）

Canonical files to read before writing new code

编写新代码前必读的标准文件

NestJS-style permissions —
`actions:`
key is FORBIDDEN

NestJS风格权限——禁止使用
`actions:`
字段