# @basenative/admin 中文文档

规范地址：https://npmcn.com/package/%40basenative/admin/

版本：3\.0\.0
npm 元数据更新时间：2026-10-31T13:47:47.327Z
中文译文更新时间：2026-10-31T16:11:28.073Z
软件包许可：Apache-2\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40basenative/admin
原文对照：https://npmcn.com/package/%40basenative/admin/?lang=original
项目主页：https://github.com/DuganLabs/BaseNative/tree/main/packages/admin#readme
源码仓库：https://github.com/DuganLabs/BaseNative

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：44.7 kB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-10-18T05:28:56.460Z
- 最新版本发布：2026-10-31T13:47:47.018Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

可插拔的管理和审核表面保护路由助手、角色/权限原语、审计日志中间件和用于BaseNative应用程序的队列审查UI组件

## 安装

```sh
npm install @basenative/admin
```

也可以使用：`pnpm add @basenative/admin`、`yarn add @basenative/admin`、`bun add @basenative/admin`

## README

# @ basenative/admin

BaseNative应用程序的可插拔管理和审核界面。汇集了 每个“用户可以提交内容，mod可以批准”的四个部分 从头开始重建应用程序：

1.  **角色** -分层 (`user < moderator < admin`) 可播种 从部署时允许列表进行管理升级。
2.  **队列** -提交表→批准的目标表，逐行 决定自动填充的审核列。
3.  **审计日志** -每个受保护的行动记录谁做了什么，什么时候，和 到哪个目标—在审计时不会使请求崩溃 写失败。
4.  **用户界面** -服务器渲染的构建块 (`<AdminQueueList>`， `<AdminUserList>`) 与 `@basenative/components` 和主题 通过CSS自定义属性。

Worker-runtime第一;在存储适配器允许的节点上运行良好。

## 安装

```sh
pnpm add @basenative/admin
# Optional — gets you sessions/cookies for `getCurrentUser`
pnpm add @basenative/auth
```

## 角色

```js
import { defineRoles, requireRole, roleSeed } from '@basenative/admin/roles';

const roles = defineRoles({ hierarchy: ['user', 'moderator', 'admin'] });

roles.isAdmin(user);        // top tier?
roles.isModerator(user);    // ≥ moderator (admin counts)
roles.hasRole(user, 'moderator');

// Inside a handler:
const guard = requireRole('moderator');
const { user, error } = guard(currentUser);
if (error) return error;
```

### 从env进行播种管理

提升中列出的句柄 `ADMIN_HANDLES` （逗号分隔）第一眼看到：

```js
user = await roleSeed({
  env, envKey: 'ADMIN_HANDLES',
  user,
  setRole: (id, role, by) => d1Users(env.DB).setRole(id, role, by),
});
```

## 提交队列

```js
import { defineQueue } from '@basenative/admin/queue';

const queue = defineQueue({
  db: env.DB,
  tables: { submissions: 'submissions', target: 'phrases', columns: ['category', 'phrase'] },
});

await queue.submit({ category: 'Foods', phrase: 'apple pie', submittedBy: 'alice' });
const pending = await queue.listPending();
await queue.decide(pending[0].id, 'approved', 'mod1');
```

在批准的行被复制到目标表与 `created_at` / `created_by` 由主持人的决定填充。覆盖 `onApprove` 如果你需要定制的推广逻辑。

## dropin处理程序

```js
import { defineAdminHandlers } from '@basenative/admin/handlers';
import { currentUser } from '@basenative/auth';

const admin = defineAdminHandlers({
  queue,
  users: d1Users(env.DB),
  getCurrentUser: currentUser,
});

// functions/api/moderate/pending.js
export const onRequestGet = admin.listPending;

// functions/api/moderate/decide.js
export const onRequestPost = admin.decide;

// functions/api/moderate/users.js
export const onRequestGet = admin.users;

// functions/api/moderate/promote.js
export const onRequestPost = admin.promote;
```

## 审计日志

```js
import { auditAction } from '@basenative/admin/audit';

await auditAction(env, {
  user,
  action: 'submission.approved',
  target: { type: 'submission', id: 42 },
  meta: { reason: 'duplicate' },
});
```

审计失败被捕获并记录-它们永远不会冒泡到用户。

## UI组件

```js
import { renderAdminQueueList, renderAdminUserList } from '@basenative/admin/components';

const html = renderAdminQueueList({ items: pending });
const usersHtml = renderAdminUserList({
  users: elevated,
  results,
  query: q,
  currentHandle: me.handle,
});
```

主题通过CSS变量- `--bn-admin-bg`， `--bn-admin-fg`， `--bn-admin-accent`， `--bn-admin-ok`， `--bn-admin-bad`， `--bn-admin-danger`.

动作委托：每个按钮携带 `data-action="bn-admin-decide"` (或 `bn-admin-set-role`) + `data-id` / `data-decision` / `data-role`． 线 分派到您的API的单个文档级单击处理程序。

## 迁移

应用 `migrations/0001_audit_and_roles.sql` (也输出为 `AUDIT_MIGRATION`）。

## 采用增量

您可以以任何顺序拉入位:

1.  从……开始 `roles` -最便宜的表面积；只是包装角色检查。
2.  添加 `audit` 接下来开始记录您已经拥有的受保护操作。
3.  将您的队列端点替换为 `handlers` 一旦数据形状向上行。
4.  交换您的队列UI `components` 最后的。

## 链接

-   碱性单氧- [https://github.com/DuganLabs/basenative](https://github.com/DuganLabs/basenative)
-   问题- - - - - - [https://github.com/DuganLabs/basenative/issues](https://github.com/DuganLabs/basenative/issues)
-   文档- [https://github.com/DuganLabs/basenative#readme](https://github.com/DuganLabs/basenative#readme)

## 许可证

apache - 2.0。

## 常见问题

### @basenative/admin 是什么？

可插拔的管理和审核表面保护路由助手、角色/权限原语、审计日志中间件和用于BaseNative应用程序的队列审查UI组件

### 如何安装 @basenative/admin？

在项目目录运行 npm install @basenative/admin，或使用 pnpm add / yarn add / bun add。

### @basenative/admin 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @basenative/admin 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @basenative/admin 可以商用吗？

@basenative/admin 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @basenative/admin 还在维护吗？

最新版本 3\.0\.0 发布于 2026/10/31（2 天前）；至今共发布 11 个版本，其中过去 12 个月发布了 11 个；首次发布于 2026/10/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。