747 lines
30 KiB
Markdown
747 lines
30 KiB
Markdown
# shrimp-server
|
|
|
|
声明式字段驱动的 Node.js 后台管理框架(Express + Mongoose + JWT)。后台只声明"表 + 字段",前端自动渲染表格、表单、搜索、菜单。
|
|
|
|
## 在你的项目里用
|
|
|
|
```sh
|
|
# 推荐: HTTP(任何能访问 git.zeromvc.com 的机器都能用)
|
|
npm install git+http://git.zeromvc.com/wc24/shrimp-server.git#v0.5.0
|
|
|
|
# 也可以 SSH(需要 ssh key 配好)
|
|
npm install git+ssh://git@git.zeromvc.com:wc24/shrimp-server.git#v0.5.0
|
|
```
|
|
|
|
> 仓库 ship `.ts` 源码,消费方项目需要 TS 运行器(`tsx` / `ts-node`)或在打包工具(vite / webpack / esbuild)里能解析 `.ts`。
|
|
|
|
### ts-node / ts-node-dev 用户:让它编译 node_modules 内的 .ts
|
|
|
|
`ts-node` 默认会把 `node_modules/` 当成"已编译"跳过,直接把 shrimp-server 的 `.ts`
|
|
源码丢给 Node — Node 22+ 看到 `export` 会按 ESM 加载然后炸 `Unexpected token 'export'`。
|
|
在 `tsconfig.json` 里把 ignore 覆盖掉:
|
|
|
|
```jsonc
|
|
{
|
|
"compilerOptions": { /* ... */ },
|
|
"ts-node": {
|
|
// 默认是 /(?:^|/)node_modules// — 这里清空,让 ts-node 也编译 shrimp-server
|
|
"ignore": ["(?!)"]
|
|
}
|
|
}
|
|
```
|
|
|
|
`tsx` 用户不需要这一步(tsx 默认就编译 node_modules 内的 .ts)。
|
|
|
|
### TypeScript 用户:让 tsc 识别子路径
|
|
|
|
包用 package.json `exports` 字段划分了 `'shrimp-server'`(0 重依赖核心)、
|
|
`'shrimp-server/expmon'`(Express + Mongoose 整合方案)和 `'shrimp-server/types'`
|
|
(纯类型)三个入口。**TS 默认的 `moduleResolution: "node"` 不读 `exports`,会找不到子路径模块。**
|
|
两个解法二选一:
|
|
|
|
```jsonc
|
|
// 方案 A: 升 moduleResolution(配合 module: node16,严格但纯净)
|
|
"compilerOptions": {
|
|
"module": "node16",
|
|
"moduleResolution": "node16"
|
|
}
|
|
```
|
|
|
|
```jsonc
|
|
// 方案 B: 保留 commonjs,显式 paths 指过去(兼容 ts-node-dev 老版)
|
|
"compilerOptions": {
|
|
"module": "commonjs",
|
|
"baseUrl": ".",
|
|
"paths": {
|
|
"shrimp-server": ["node_modules/shrimp-server/src/main/index.ts"],
|
|
"shrimp-server/expmon": ["node_modules/shrimp-server/src/main/expmon.ts"],
|
|
"shrimp-server/types": ["node_modules/shrimp-server/src/main/types.ts"]
|
|
}
|
|
}
|
|
```
|
|
|
|
Node 22+ 的 CJS 加载器 **会**读 `exports`,所以运行时不需要额外配置 — 只是 TS 的
|
|
类型解析在 `moduleResolution: "node"` 模式下落后于 Node 实际行为,需要 paths 兜底。
|
|
|
|
### 三个入口,按需选择
|
|
|
|
包内提供**核心**、**expmon(Express+Mongo 整合)**和**纯类型**三个 entry,**peer deps 全部 optional**——你只装自己用得到的那一份:
|
|
|
|
```ts
|
|
// 1) 核心: 0 重依赖(只需 node + tsx),适合自己接 HTTP / 只用内存 CRUD / 嵌入其它框架
|
|
import { Shrimp, ShrimpTableModule, MemoryShrimpCrud, ShrimpFieldTypes } from "shrimp-server"
|
|
|
|
// 2) expmon: Express + Mongoose + JWT 整合方案,需要装上面 4 个 peer
|
|
import { ShrimpServer, MongoShrimpCrud, MongoShrimp } from "shrimp-server/expmon"
|
|
|
|
// 3) 纯类型: 只含 IShrimpType.ts(types + ShrimpCode enum + ShrimpError class)
|
|
// 给前端 / shrimp-admin / 任何"只要协议、不要框架运行时"的消费方
|
|
import { ShrimpCode, ShrimpError } from "shrimp-server/types"
|
|
import type { IFieldConfig, IMenuItem, IMeResult } from "shrimp-server/types"
|
|
```
|
|
|
|
只用 (1) 时,**不要**在自己的 package.json 里写 express/mongoose/bcrypt/jsonwebtoken,可以省下大量 install 时间(尤其是 mongoose 的 native binding)。需要 (2) 时按 peer 范围装齐即可。(3) 完全独立,既不会拉 Shrimp 主类也不会拉 mongoose,前端 bundle 安全。
|
|
|
|
> bcrypt 在 core 里走的是动态 `import('bcrypt')`,不触发 Password 字段 hash / `UserModule.verifyPassword` 就完全不会去 require 它。所以即便用 core 也注册了 password 字段,只要你不真正调用 `add/edit` 写入 Password 或 `getUser` 校验密码,bcrypt 仍是可不装的。
|
|
|
|
---
|
|
|
|
# 使用指南
|
|
|
|
本文按"想做什么"组织,每个场景给你最短的可工作代码。
|
|
|
|
> Memory:Shrimp 在 list/get 时把 relation 字段的关联标签旁挂为 `${key}_label`(数组关联挂数组)。这是有意设计,读写对称,不要改成 `{_id, label}` 嵌套对象。
|
|
|
|
---
|
|
|
|
## 约定
|
|
|
|
shrimp 不是铁板一块的协议,它是**一组可选拼装件**。每个件对外有自己的契约,你用了哪个件就被哪个件的契约绑住,不用就不必遵守。盘点时按**作用域**分两层。
|
|
|
|
### 🌐 全局约定(只要你说"我在写 shrimp",就跑不掉)
|
|
|
|
| 契约 | 说明 |
|
|
|---|---|
|
|
| `IModuleInfo` 形状 | 任何模块声明都得这么写 — 见 [src/IShrimpType.ts](src/IShrimpType.ts) `IModuleInfo` |
|
|
| `IFieldConfig` 形状 | 字段就这样描述(`name` / `label` / `type` / `relation` / `rules` …) |
|
|
| Shrimp 树结构 | `parent`/`children` 嵌套、`getFullPath()` 路径语义 |
|
|
| Power / Role 声明 | `power` 树形 + `role` 持 `powers[]` |
|
|
| `ILabel` 多语言形态 | 见下方 §国际化 — 6 选 1 的标签类型 |
|
|
|
|
### 🔌 条件约定(用了某个件,才被它的契约绑住)
|
|
|
|
| 启用前提 | 它的契约 |
|
|
|---|---|
|
|
| **使用 `ShrimpTable`(前端表格组件)** | • list 响应必须是 `IPageResult` = `{ list, total, page, pageSize, totalPages }`<br>• 字段 `type` 必须落在内置枚举(见下方 §字段类型)—— 或自行注册 `IFieldTypeHandler`<br>• populate 字段旁挂 `${key}_label`(数组关联挂数组) |
|
|
| **使用 `buildShrimpRouter` / `ShrimpServer`** | • HTTP 路由形状:`GET /config`、`POST /login`、`GET /me`、`POST /<modulePath>/<event>`<br>• JWT 携带:`Authorization: Bearer <token>`<br>• 后端需实现 `IUserAccessor`(getJwtPayload / isUserActive / getUserRoleIds / isRoleSuperAdmin / getRolePowers / getUserDisplayName) — 见 [src/forExpress/types.ts](src/forExpress/types.ts) |
|
|
| **使用 `MongoShrimp`** | • User/Role/OperationLog 的 mongoose Schema 形状<br>• `onDbConnected` 钩子时序:连接就绪后才能注册需要 DB 的模块 |
|
|
| **挂 `OperationLogModule`** | • CRUD 动作自动写日志的字段集(operator / module / action / target / time) |
|
|
| **使用默认 `Field*.vue` 渲染**(前端) | • 字段 `type` 必须是内置枚举之一,否则需注册 `typeHandler` 才能渲染 |
|
|
| **使用 Shrimp 子模块机制** | • 子表 `ownerKey` 是后端注册侧独占,**不进 fields[]**<br>• 前端只发通用 `ownerId`,不感知 `ownerKey` 的实际字段名 |
|
|
|
|
> 替换某个件,这个件的条件契约自动失效。例如:你换掉 `ShrimpTable` 用 AG-Grid,list 响应格式和字段 type 枚举两条对你都不再生效;你不挂 `OperationLogModule`,日志契约就不存在。
|
|
|
|
---
|
|
|
|
### 国际化 (ILabel)
|
|
|
|
所有前端可见文本字段(`label` / `tip` / `menu.label` / `power.label` / `field.label` / `rule.message` …)统一类型 `ILabel`。**用哪种形态取决于你写在哪一层**。
|
|
|
|
#### 框架层(`lib/shrimp/`)
|
|
框架是可复用组件,内置文案要支持翻译,**必须用对象形态**:
|
|
|
|
```ts
|
|
{ t: 'shrimp.fieldRequired', params: { field: field.label } } // 翻译 + 模板参数
|
|
{ tc: 'shrimp.itemCount', count: n } // 复数
|
|
{ d: createdAt, format: 'short' } // 日期格式化
|
|
{ n: amount, format: 'currency' } // 数字/货币格式化
|
|
```
|
|
|
|
#### 业务层(`src/`)
|
|
当前项目独有内容,**直接写中文字面量**:
|
|
|
|
```ts
|
|
label: '方案管理'
|
|
throw new ShrimpError('余额不足')
|
|
this.addEvent('changeState', '更改状态')
|
|
{ name: 'matter', label: '物资管理', children: [...] }
|
|
```
|
|
|
|
业务层后续若要做多语言,把对应处改成 `{ t: 'app.xxx' }` 即可,类型已经支持,不必改动框架代码。
|
|
|
|
#### `ILabel` 完整形态(类型上 6 选 1)
|
|
|
|
```ts
|
|
type ILabel =
|
|
| string // 1. 字面量,前端原样显示
|
|
| { t: string; params?: Record<string, ILabel | any> } // 2. 翻译(vue-i18n t)
|
|
| { tc: string; count: number; params?: ... } // 3. 复数(vue-i18n tc)
|
|
| { d: number | Date; format?: string } // 4. 日期格式化
|
|
| { n: number; format?: string } // 5. 数字/货币格式化
|
|
| Record<string, string> // 6. 内联多语言 { zh, en }
|
|
```
|
|
|
|
`params` 值本身也是 `ILabel`,前端递归翻译。
|
|
|
|
#### 反模式
|
|
```ts
|
|
label: 'user.username' // ❌ 看着像 i18n key 但是 string,前端按字面量原样显示
|
|
label: { t: 'user.username' } // ✅ 框架场景:显式翻译
|
|
label: '用户名' // ✅ 业务场景:直接字面量
|
|
```
|
|
|
|
## 1. 起一个后台(5 分钟)
|
|
|
|
```ts
|
|
// src/MyAdmin.ts
|
|
import { ShrimpServer } from '../lib/shrimp/ShrimpServer'
|
|
|
|
export class MyAdmin extends ShrimpServer {
|
|
protected async onDbConnected() {
|
|
await this.initDefaultData('超级管理员', 'Built-in admin')
|
|
}
|
|
}
|
|
```
|
|
|
|
```ts
|
|
// index.ts
|
|
import express from 'express'
|
|
import { MyAdmin } from './src/MyAdmin'
|
|
|
|
const admin = new MyAdmin('jwt-secret', { title: '我的后台' }, 'mongodb://localhost:27017/myapp')
|
|
|
|
const app = express()
|
|
app.use(express.json())
|
|
app.use('/admin-api', admin.router)
|
|
app.listen(3001)
|
|
```
|
|
|
|
启动后访问前端,默认账号 `admin / admin`。
|
|
|
|
---
|
|
|
|
## 2. 加一张 CRUD 表
|
|
|
|
```ts
|
|
// src/MyAdmin.ts
|
|
import mongoose, { Schema } from 'mongoose'
|
|
import { ShrimpTableModule } from '../lib/shrimp/Shrimp'
|
|
import { MongoShrimpCrud } from '../lib/shrimp/MongoShrimpCrud'
|
|
import { IFieldConfig } from '../lib/shrimp/IShrimpType'
|
|
|
|
const ItemSchema = new Schema({
|
|
code: { type: String, required: true },
|
|
name: { type: String, required: true },
|
|
description: { type: String, default: '' },
|
|
}, { timestamps: true })
|
|
|
|
const itemFields: IFieldConfig[] = [
|
|
{ key: 'code', label: 'item.code', type: 'string', required: true, searchable: true, editable: 'addOnly' },
|
|
{ key: 'name', label: 'item.name', type: 'string', required: true, searchable: true },
|
|
{ key: 'description', label: 'item.description', type: 'textarea' },
|
|
{ key: 'createdAt', label: 'item.createdAt', type: 'date', editable: 'readonly', sortable: true },
|
|
]
|
|
|
|
export class MyAdmin extends ShrimpServer {
|
|
constructor(jwtSecret: string, config: any, mongoUri: string) {
|
|
super(jwtSecret, config, mongoUri)
|
|
|
|
const itemModel = mongoose.model('items', ItemSchema)
|
|
new ShrimpTableModule(
|
|
this, 'item', new MongoShrimpCrud(itemModel),
|
|
itemFields, '物品管理'
|
|
).initCrud()
|
|
}
|
|
}
|
|
```
|
|
|
|
到这一步,前端管理界面就出现"物品管理"菜单 + 表格 + 新增/编辑表单 + 删除按钮,完全自动渲染。
|
|
|
|
**字段配置常用项:**
|
|
- `searchable: true` — 出现在搜索框
|
|
- `sortable: true` — 表头点击排序
|
|
- `filterable: true` — 出现在筛选栏(精确匹配)
|
|
- `editable: 'addOnly'` — 新增可填,编辑禁改(如 `code`)
|
|
- `editable: 'readonly'` — 永远只读(如 `createdAt`)
|
|
- `tableHide: true` — 表格不显示这一列但仍返回数据
|
|
- `hidden: true` — 数据完全不下发到前端
|
|
- `required: true` — 表单必填
|
|
- `defaultValue: ...` — 新增时的默认值
|
|
|
|
### 字段类型
|
|
|
|
内置就这 11 个,以 [src/IShrimpType.ts](src/IShrimpType.ts) 的 `ShrimpFieldTypes` 为准:
|
|
|
|
| type | 用途 |
|
|
|---|---|
|
|
| `string` | 单行文本 |
|
|
| `number` | 数字 |
|
|
| `boolean` | 开关 |
|
|
| `date` | 日期 |
|
|
| `textarea` | 多行文本 |
|
|
| `password` | 密码,列表不回显 |
|
|
| `select` | 枚举,配 `options: [{label, value}]`(属性名就叫 `options`) |
|
|
| `relation` | 关联别的模块,配 `relation: {moduleKey, labelKey}`,见 §3 |
|
|
| `tab` | 分组容器 |
|
|
| `object` | 嵌套对象,配 `fields: IFieldConfig[]` 描述内部字段 |
|
|
| `array` | 数组,配 `item: IFieldConfig` 描述元素 |
|
|
|
|
字符串数组用 `array` + `item`,不要用 `object`——`object` 要的是 `fields`(一组具名字段),装不下一个同构列表:
|
|
|
|
```ts
|
|
{ key: 'tags', label: '标签', type: 'array', item: { key: '', label: '标签', type: 'string' } }
|
|
```
|
|
|
|
**没有 `json` 这个类型。** 写了它不会报错:前端查不到处理器,静默回落成 `string` 渲染(0.8.2 起控制台留一条 warning)。需要别的形状就自行注册 `IFieldTypeHandler`,别借用不存在的名字。
|
|
|
|
---
|
|
|
|
## 3. 关联其他表
|
|
|
|
```ts
|
|
const orderFields: IFieldConfig[] = [
|
|
{ key: 'no', label: 'order.no', type: 'string', required: true },
|
|
{
|
|
key: 'itemId',
|
|
label: 'order.itemId',
|
|
type: 'relation',
|
|
relation: { moduleKey: 'item', labelKey: 'name' }, // 关联 item 表,显示 name
|
|
filterable: true,
|
|
},
|
|
// 数组关联(多选)
|
|
{
|
|
key: 'tagIds',
|
|
label: 'order.tagIds',
|
|
type: 'relation',
|
|
relation: { moduleKey: 'tag', labelKey: 'name' },
|
|
multiple: true,
|
|
defaultValue: [],
|
|
},
|
|
]
|
|
```
|
|
|
|
`list / get` 返回的数据会自动多一个 `itemId_label`(单值)或 `tagIds_label`(数组)字段,前端表格直接显示标签,无需另发请求。
|
|
|
|
> 自动 populate 走 `root.crudRegistry`,你不需要手动登记 — `ShrimpTableModule` 构造时自动登记。
|
|
|
|
---
|
|
|
|
## 4. 定义自定义业务事件(不止 CRUD)
|
|
|
|
`initCrud()` 注册了 5 个标准事件,如果你需要更多,自己加。
|
|
|
|
**要注册得更少(只读模块):不调 `initCrud()` 就行。** 模块访问权本身就涵盖 `list` / `get`,不需要也不应该手动 `addEvent('list')`——`initCrud()` 加的是 `add` / `edit` / `delete` 这几个写入口:
|
|
|
|
```ts
|
|
// 只能看,不能改。前端表格照常出,但没有新增/编辑/删除按钮
|
|
new ShrimpTableModule(this, 'item', new MongoShrimpCrud(itemModel), itemFields, '物品管理')
|
|
```
|
|
|
|
字段一律配 `editable: 'readonly'` 是另一件事——那管的是表单控件,不管有没有写入口。两个都要做。
|
|
|
|
```ts
|
|
class OrderTable extends ShrimpTableModule<IOrder> {
|
|
constructor(parent, dataSource) {
|
|
super(parent, 'order', dataSource, orderFields, '订单管理')
|
|
this.initCrud()
|
|
this.addEvent('ship', '发货') // 新增 ship 事件,业务直接写中文
|
|
this.addEvent('refund', '退款')
|
|
}
|
|
|
|
async ship(id: string) {
|
|
return this.dataSource.edit(id, { status: 'shipped', shippedAt: Date.now() } as any)
|
|
}
|
|
|
|
async refund(id: string, reason: string) {
|
|
// 业务逻辑...
|
|
return true
|
|
}
|
|
}
|
|
```
|
|
|
|
前端 HTTP 直接调:
|
|
- `POST /admin-api/order/ship`,body `[id]`
|
|
- `POST /admin-api/order/refund`,body `[id, reason]`
|
|
|
|
> body 永远是参数数组,框架按位置解构。前端 `vueAdmin.getModule<IOrderProto>('order').ship(id)` 自动包装。
|
|
|
|
---
|
|
|
|
## 5. 改默认行为(钩子)
|
|
|
|
### 拦截新增/编辑
|
|
|
|
```ts
|
|
class UserTable extends ShrimpTableModule<IUser> {
|
|
async edit(id: string, item: Partial<IUser>) {
|
|
if (item.role === 'admin' && !this.root.operator?.isSuperAdmin) {
|
|
throw new ShrimpError('不能将用户提升为管理员')
|
|
}
|
|
return super.edit(id, item)
|
|
}
|
|
}
|
|
```
|
|
|
|
### 字段级 reqFilter / validate
|
|
通过 `registerTypeHandler` 注册自定义 type 的处理器:
|
|
|
|
```ts
|
|
import { ShrimpTableModule, ShrimpError } from '../lib/shrimp/Shrimp'
|
|
|
|
ShrimpTableModule.registerTypeHandler('phone', {
|
|
reqFilter: (value) => String(value).replace(/\s+/g, ''),
|
|
validate: (value) => /^\d{11}$/.test(value) ? null : 'myapp.invalidPhone',
|
|
})
|
|
```
|
|
|
|
字段配置写 `type: 'phone'`,框架自动应用。
|
|
|
|
### 自定义 type 的前端渲染
|
|
后端只声明 `type: 'fieldGoodsPicker'` 即可,前端在 `hand-admin/src/module/fields/` 放一个 `FieldGoodsPicker.vue`,会按命名约定自动注册(`Field*.vue` → `'field' + *`)。
|
|
|
|
### 替换密码哈希(passwordHasher)
|
|
|
|
默认 Password 字段写入时走 bcrypt,登录时 `UserModule.verifyPassword` 也走 bcrypt。bcrypt 是 lazy import 的——不真正调用 hash/verify 就不会 require,所以**不需要**密码功能的项目可以根本不装 bcrypt。
|
|
|
|
需要替换(测试用明文 / 改 argon2 / 接入老系统的 SHA256)时,在启动期改一行:
|
|
|
|
```ts
|
|
import { Shrimp, plainHasher } from "shrimp-server"
|
|
|
|
// 测试 / 开发
|
|
Shrimp.passwordHasher = plainHasher
|
|
|
|
// 或自定义
|
|
Shrimp.passwordHasher = {
|
|
async hash(plain) { /* ... */ return hashed },
|
|
async verify(plain, hashed) { /* ... */ return ok },
|
|
}
|
|
```
|
|
|
|
`Password` 字段 reqFilter 和 `UserModule.verifyPassword` 都会走新 hasher。**plainHasher 仅用于测试/开发**,不要在生产环境用。
|
|
|
|
---
|
|
|
|
## 6. 用 operator 拿到当前登录用户
|
|
|
|
`AsyncLocalStorage` 维护的请求级上下文,事件 handler 里随时可取:
|
|
|
|
```ts
|
|
class TaskTable extends ShrimpTableModule<ITask> {
|
|
async add(item) {
|
|
const op = this.root.operator
|
|
return super.add({ ...item, ownerId: op?.userId } as any)
|
|
}
|
|
|
|
async list(query) {
|
|
const op = this.root.operator
|
|
// 非超管只看自己的
|
|
if (!op?.isSuperAdmin) {
|
|
query = { ...query, filter: { ...query?.filter, ownerId: op?.userId } }
|
|
}
|
|
return super.list(query)
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 7. 权限怎么走通
|
|
|
|
每个模块和事件都自动有 power key,角色 `IRole.powers` 存放被授权的 key:
|
|
|
|
| 注册位置 | 生成的 power key |
|
|
| --- | --- |
|
|
| `new ShrimpTableModule(root, 'item', ...)` | `item`(模块访问权,涵盖 list/get) |
|
|
| `.addEvent('add', '新增')` | `item.add` |
|
|
| `.addEvent('edit', '编辑')` | `item.edit` |
|
|
| 子模块 `new ShrimpModule(parentModule, 'sub', ...)` | `parent.sub`(子模块详见第 9 节) |
|
|
|
|
授权流程:
|
|
1. 进角色管理界面,新建角色,在 PowerTree 勾对应 key,保存
|
|
2. 进用户管理,给用户绑这个角色
|
|
3. 用户重新登录(或刷新 token),`/me` 自动按权限过滤模块和菜单
|
|
|
|
`isSuperAdmin: true` 的角色绕开所有检查。
|
|
|
|
---
|
|
|
|
## 8. 菜单分组
|
|
|
|
默认顶层模块平铺。要把多个模块归到一个菜单组,覆盖 `getMenuTree()`:
|
|
|
|
```ts
|
|
import { IMenuItem } from '../lib/shrimp/IShrimpType'
|
|
|
|
class MyAdmin extends ShrimpServer {
|
|
getMenuTree(): IMenuItem[] {
|
|
const labelMap: Record<string, string> = {
|
|
matter_item: '物品', matter_scheme: '方案',
|
|
matter_dropGroup: '掉落组', matter_point: '物资点',
|
|
}
|
|
const matterKeys = Object.keys(labelMap)
|
|
const matterChildren = matterKeys
|
|
.filter(k => this.modules.has(k))
|
|
.map(k => ({ name: k, label: labelMap[k], moduleKey: k }))
|
|
|
|
const grouped = new Set(matterChildren.map(c => c.moduleKey))
|
|
const rest: IMenuItem[] = []
|
|
this.modules.forEach(m => {
|
|
if (grouped.has(m.moduleKey)) return
|
|
rest.push({ name: m.moduleKey, label: m.moduleKey, moduleKey: m.moduleKey })
|
|
})
|
|
return [...rest, { name: 'matter', label: '物资管理', children: matterChildren }]
|
|
}
|
|
}
|
|
```
|
|
|
|
要点:
|
|
- 分组节点 **不要** 带 `moduleKey`,只用 `children`
|
|
- 叶子节点带 `moduleKey`,路由就是 `/<moduleKey>`
|
|
- `filterMenuTree` 会按权限自动剔除整组没权限的分支
|
|
- 分组支持**任意层嵌套**: `children` 里继续放带 `children` 的分组节点即可,前端菜单/面包屑递归渲染,无限层级
|
|
|
|
---
|
|
|
|
## 9. 子模块(行内跳转的从属页面)
|
|
|
|
主模块上的每一行经常需要一个独立的二级编辑页(比如"方案"的物资点配置)。子模块就是这种场景的官方表达:挂在主模块下、不进菜单、按行跳转、独立鉴权。
|
|
|
|
### 注册
|
|
|
|
```ts
|
|
const schemeModule = new ShrimpTableModule(server, 'matter_scheme', crud, schemeFields, '方案管理').initCrud()
|
|
new ShrimpModule(schemeModule, 'pointDrops', '物资点配置', undefined, { icon: 'Setting' })
|
|
```
|
|
|
|
参数顺序: `(parent, moduleKey, label, power?, options?)`。`options.icon` 用于前端操作栏跳转按钮(element-plus icon 名,大写驼峰)。
|
|
|
|
子模块也可以再挂子模块,**嵌套任意层**: `parent` 传入上一层 `ShrimpModule` 即可。
|
|
|
|
```ts
|
|
const project = new ShrimpTableModule(server, 'project', ..., '项目管理').initCrud()
|
|
const task = new ShrimpTableModule(project, 'task', ..., '任务', undefined, { ownerKey: 'projectId' }).initCrud()
|
|
const subtask = new ShrimpTableModule(task, 'subtask', ..., '子任务步骤', undefined, { ownerKey: 'taskId' }).initCrud()
|
|
```
|
|
|
|
效果:
|
|
- 路由自动注册为 `/project` → `/project/task` → `/project/task/subtask`
|
|
- 前端 Vue 组件按目录嵌套: `src/module/project.vue` / `src/module/project/task.vue` / `src/module/project/task/subtask.vue`
|
|
- Power key 链: `project` / `project.task` / `project.task.subtask`
|
|
- 面包屑递归显示并可点击逐级返回 (`物资管理 / 项目管理 / 任务 / 子任务步骤`),顶栏额外提供"返回"按钮走浏览器历史(回退时保留父 id 的 `?id=` 查询)
|
|
|
|
#### 多级父 id 在 URL 中的传递
|
|
|
|
子表页面的 `ownerId` 来自 `?id=`(immediate parent 的记录 id)。多级嵌套时,**祖先级**的 id 也要带上,否则用户点面包屑回到中间层就丢失了过滤条件。
|
|
|
|
约定:
|
|
- `?id=<immediate_parent_id>` — 当前页 ownerId
|
|
- `?pids=<root>,<...>,<grandparent>` — 祖先链(root → immediate-parent 之前的所有 id,逗号分隔)
|
|
|
|
例:
|
|
- `/project/task?id=projA` — task 的 ownerId 是 projA
|
|
- `/project/task/subtask?id=taskB&pids=projA` — subtask 的 ownerId 是 taskB,上一层(task)需要 projA
|
|
- `/a/b/c/d?id=cId&pids=aId,bId` — 4 层嵌套
|
|
|
|
`ShrimpTable.handleSubJump` 跳子模块时自动把 `?id` 推入 `pids`,row._id 写到新 `?id`;`topbar` 面包屑按每个层级所需的 `id`/`pids` 重建 `:to` 链接;`useTableUrlSync` 白名单只同步 `page/pageSize/keyword/sort/filter`,`id` 和 `pids` 自动保留。
|
|
|
|
### 权限
|
|
|
|
子模块复用现有的 power 树,不引入新机制:
|
|
- 模块自身 power key 自动是 `parent.sub`(例: `matter_scheme.pointDrops`)
|
|
- 用户角色没勾这个 key → `/me` 返回的 moduleInfo 里不会出现该子模块 → 前端按钮和路由都不存在
|
|
- 子模块上 `addEvent` 的事件 power 是 `parent.sub.event`,层级继续延伸
|
|
|
|
### 前端约定
|
|
|
|
子模块的 moduleInfo 是**扁平**的,与主模块同列,靠 `parent` 字段关联:
|
|
|
|
```ts
|
|
{ moduleKey: 'pointDrops', parent: 'matter_scheme', icon: 'Setting', ... }
|
|
```
|
|
|
|
`ShrimpClient` 自动:
|
|
- 注册路由 `/<parent>/<sub>`(嵌套层级按 parent 链拼接)
|
|
- 把对应 Vue 组件文件期望放在 `src/module/<parent>/<sub>.vue`
|
|
- `ShrimpTable` 检测 `moduleInfo.parent === currentModuleKey` 的项,在操作栏每行加一个图标按钮,点击跳到 `/<parent>/<sub>?id=<row._id>`
|
|
|
|
子模块页面通常**不需要自己的 CRUD**——它操作的是主模块的某条记录,直接调主模块 API:
|
|
|
|
```vue
|
|
<!-- src/module/matter_scheme/pointDrops.vue -->
|
|
<script setup lang="ts">
|
|
import { useRoute } from 'vue-router'
|
|
import { vueAdmin } from '@/VueAdmin'
|
|
|
|
const route = useRoute()
|
|
const api = vueAdmin.getModule<any>('matter_scheme')
|
|
const id = route.query.id as string
|
|
// await api.get(id) / api.edit(id, { ... })
|
|
</script>
|
|
```
|
|
|
|
只有当子模块需要自己的事件(如批量同步、独立列表)时,才把它做成 `ShrimpTableModule` 并 `initCrud()`。
|
|
|
|
### 真子表: `ownerKey` 自动过滤
|
|
|
|
当子模块有**独立的记录集合**(master-detail,如"用户的操作日志"),需要按父记录 id 过滤,这通过 `options.ownerKey` 声明:
|
|
|
|
```ts
|
|
new OperationLogModule(userModule, crud, fields, label, undefined, {
|
|
icon: 'Tickets',
|
|
ownerKey: 'operatorId', // 子表记录中指向父记录(user._id)的字段名
|
|
})
|
|
```
|
|
|
|
#### 前后端各做什么
|
|
|
|
约定的语义是: 前端只发一个通用 `ownerId`(父记录 id),后端按自己 `ownerKey` 配置翻译成具体字段名。`ownerKey` **只活在后端**,前端不知道(也不必知道)子表记录里那一列叫什么名字。
|
|
|
|
- **后端 `ShrimpTableModule`**:
|
|
- `list/clear/export`: `buildQuery` 读 `query.ownerId`,如果 `this.ownerKey` 已配置,强制注入 `where[ownerKey] = { eq: ownerId }`(放在用户 filter 之后,用户绕不过)
|
|
- `add(item, ownerId?)` / `import(data, ownerId?)`: 第二参数是 ownerId,自动写入 `item[ownerKey]`,前端不需要在 payload 里放业务字段名
|
|
|
|
- **前端 `ShrimpTable`**:
|
|
- 通过 `moduleInfo.parent` 判断当前模块是子模块,从 `route.query.id` 取父 id 作为 `ownerId`
|
|
- 所有 RPC(list/clear/export/add/import)自动带上 `ownerId`,不混入 filter
|
|
|
|
#### ownerKey 字段不进 fields[]
|
|
|
|
子表里 ownerKey 对应的列(如 operationLog 的 `operatorId`)语义上就是"父记录外键",所有行都同值,不属于 UI 关心范围:
|
|
|
|
```ts
|
|
// OperationLogModule.ts
|
|
const operationLogFields: IFieldConfig[] = [
|
|
// 注意: operatorId 不在 fields 里 — 纯数据库字段,框架按 ownerKey 自动注入 filter
|
|
{ key: "ip", ... },
|
|
{ key: "method", ... },
|
|
...
|
|
]
|
|
```
|
|
|
|
效果: 子表页面不渲染 ownerKey 列、筛选抽屉里没这一项、表单里也没这一项,但数据库照常存。如果某天需要做"顶层操作日志列表"(显示全部用户的日志,按操作者筛选),那是另一个模块/另一份 fields 配置的事。
|
|
|
|
子模块页面写法极简:
|
|
|
|
```vue
|
|
<!-- src/module/user/operationLog.vue -->
|
|
<ShrimpTable moduleKey="operationLog" />
|
|
```
|
|
|
|
如需在某场景下手动追加额外过滤(例如二级筛选),可继续传 `:baseFilter`,它会**覆盖**用户的筛选选择,但不影响 `ownerId` 注入:
|
|
|
|
```vue
|
|
<ShrimpTable moduleKey="operationLog" :baseFilter="{ success: false }" />
|
|
```
|
|
|
|
#### URL 参数保留
|
|
|
|
`useTableUrlSync` 把 `page/pageSize/keyword/sortBy/sortOrder/filter` 同步到 URL,但**保留**其它已有的 query 参数(如 `?id=`),不会被 sort/filter 操作清掉。子表页面的父 id 因此不会在用户排序后消失。
|
|
|
|
### 不要做的事
|
|
|
|
- 别把子模块塞进 `getMenuTree()`,它不应出现在菜单里
|
|
- 别给子模块单独建一个无关 power(`new ShrimpPower(...)` 覆盖默认),会破坏 `parent.sub` 的继承语义
|
|
- 别在 `moduleInfo` 上找 `subModules` 数组——结构已经扁平化,用 `parent` 字段过滤
|
|
|
|
---
|
|
|
|
## 10. 替换内置 User/Role
|
|
|
|
最常见场景:你已经有用户表,字段名跟 Shrimp 不一样,或想加额外字段。
|
|
|
|
```ts
|
|
class MyAdmin extends ShrimpServer {
|
|
// 1. 改 schema
|
|
protected createUserSchema() {
|
|
return new Schema({
|
|
account: { type: String, required: true }, // 重命名 username → account
|
|
password: { type: String, required: true },
|
|
displayName: String,
|
|
roleId: { type: [Schema.Types.ObjectId], default: [] },
|
|
active: { type: Boolean, default: true },
|
|
phone: String, // 额外字段
|
|
}, { timestamps: true })
|
|
}
|
|
|
|
// 2. 改字段访问钩子(让框架认得你的字段名)
|
|
protected getUserDisplayName(user: any) { return user.displayName || '' }
|
|
protected isUserActive(user: any) { return user.active === true }
|
|
protected getUserRoleIds(user: any) {
|
|
return Array.isArray(user.roleId) ? user.roleId.map(String) : []
|
|
}
|
|
|
|
// 3. (可选)替换模块类,加自定义字段配置
|
|
protected createUserModule(dataSource) {
|
|
return new UserModule(this, dataSource, [
|
|
{ key: 'account', label: 'user.account', type: 'string', required: true, editable: 'addOnly' },
|
|
{ key: 'password', label: 'user.password', type: 'password', tableHide: true },
|
|
{ key: 'displayName', label: 'user.displayName', type: 'string' },
|
|
{ key: 'phone', label: 'user.phone', type: 'string' },
|
|
// ...
|
|
])
|
|
}
|
|
}
|
|
```
|
|
|
|
登录接口 `POST /login` 仍然收 `username`,框架内部走的是 `userModule.getUser(username, password)`。如果你想让登录接口用 `account`,override `UserModule.getUser`:
|
|
|
|
```ts
|
|
class MyUserModule extends UserModule {
|
|
async getUser(account: string, password: string) {
|
|
const user = await this.dataSource.findOne({ account, active: true })
|
|
if (!user || !(await bcrypt.compare(password, user.password))) {
|
|
throw new ShrimpError({ t: 'shrimp.loginFailed' }) // 复用框架已有的 i18n key,沿用其翻译
|
|
}
|
|
return user
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 11. 初始化默认数据
|
|
|
|
```ts
|
|
protected async onDbConnected() {
|
|
await this.initDefaultData('超级管理员', '内置') // 没有用户时自动创建 admin/admin
|
|
// 也可以直接用 dataSource 灌业务表
|
|
const itemCrud = (this.modules.get('item') as any).dataSource
|
|
if ((await itemCrud.list({ limit: 1 })).total === 0) {
|
|
await itemCrud.add({ code: 'gold', name: '金币' })
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 12. 报业务错
|
|
|
|
```ts
|
|
import { ShrimpError, ShrimpCode } from '../lib/shrimp/IShrimpType'
|
|
|
|
// 业务直接写中文(推荐)
|
|
throw new ShrimpError('余额不足')
|
|
throw new ShrimpError('账号已被封禁', ShrimpCode.FORBIDDEN)
|
|
|
|
// 需要多语言或模板参数时,用对象形态
|
|
throw new ShrimpError({ t: 'myapp.notEnoughBalance', params: { need, current } })
|
|
```
|
|
|
|
框架自动把 `ShrimpError.tip`(`ILabel`)透传给前端,前端按 `ILabel` 形态解析:string 字面输出,`{t}` 走 i18n。
|
|
|
|
---
|
|
|
|
## 13. 用全局 options 复用枚举
|
|
|
|
```ts
|
|
class MyAdmin extends ShrimpServer {
|
|
constructor(...) {
|
|
super(...)
|
|
this.globalOptions['gameType'] = [
|
|
{ label: 'shrimp.gameA', value: 'A' },
|
|
{ label: 'shrimp.gameB', value: 'B' },
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
字段引用:
|
|
```ts
|
|
{ key: 'game', label: 'task.game', type: 'select', options: 'gameType' }
|
|
```
|
|
|
|
`/me` 只下发当前用户能访问的模块用到的 options key,自动去重。
|
|
|
|
---
|
|
|
|
## 14. 常见踩坑
|
|
|
|
- **`relation.moduleKey` 必须能在 crudRegistry 找到。** 如果改成了非默认数据源,确认 `(dataSource as any).model` 存在,否则自动 populate 不生效。
|
|
- **`searchable` 只对字符串型字段生效。** 关键词搜索走 LIKE,数字/布尔字段加了也没用,要做精确筛选用 `filterable`。
|
|
- **`editable: 'addOnly'` 字段在编辑时直接被 `prepareEditItem` 丢弃。** 不需要前端自己处理。
|
|
- **嵌套模块也走 `Shrimp.call` 递归。** URL `/admin-api/parent/child/event` 会自动逐层路由。`getModuleInfo` 会扁平输出所有有权限的模块(含子模块),子模块通过 `parent` 字段关联,详见第 9 节。
|
|
- **子模块 moduleKey 在前端是全局查找的。** 扁平 `moduleInfo` 通过 `find(m.moduleKey === key)` 定位,如果不同主模块下挂同名子模块(`config`、`detail` 这种通用名容易撞),会找到第一个匹配项导致字段/RPC 错位。子模块名**建议带主模块前缀或语义化命名**(如 `pointDrops` 而非 `config`)。
|
|
- **`ShrimpModule` 身兼三职:RPC 容器 / 权限节点 / 纯 UI 导航占位。** 当前子模块允许完全没有 `addEvent`,只作为导航锚点和权限节点存在(如 `pointDrops`,所有数据操作走主模块 API)。如果子模块需要独立的列表/操作,改用 `ShrimpTableModule` 并 `initCrud()`。
|
|
- **`add` 当前返回 Mongoose Document 包装(含 `_doc`、`$__`)而非 lean 对象。** 这是 `MongoShrimpCrud.add` 的预存行为,前端通常只看 `_id`。
|