From 355f808294cb0920f2345a8f089c62eb1aee0824 Mon Sep 17 00:00:00 2001
From: wc24 <wc24@qq.com>
Date: Tue, 11 Aug 2026 16:57:35 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AD=97=E6=AE=B5=E7=B1=BB=E5=9E=8B?=
 =?UTF-8?q?=E8=A1=A8=E7=85=A7=E5=AE=9E=E9=87=8D=E5=88=97=E2=80=94=E2=80=94?=
 =?UTF-8?q?=E5=88=A0=E6=8E=89=E4=B8=8D=E5=AD=98=E5=9C=A8=E7=9A=84=20json?=
 =?UTF-8?q?=EF=BC=8C=E8=A1=A5=E4=B8=8A=20object/array=EF=BC=9Bselect=20?=
 =?UTF-8?q?=E7=9A=84=E5=B1=9E=E6=80=A7=E5=90=8D=E6=98=AF=20options?=
 =?UTF-8?q?=EF=BC=9B=E8=A1=A5=E5=8F=AA=E8=AF=BB=E6=A8=A1=E5=9D=97=E6=80=8E?=
 =?UTF-8?q?=E4=B9=88=E6=B3=A8=E5=86=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md         | 38 +++++++++++++++++++++++++++++++++++---
 package-lock.json |  4 ++--
 package.json      |  2 +-
 3 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index ff0604f..a35dddf 100644
--- a/README.md
+++ b/README.md
@@ -112,7 +112,7 @@ shrimp 不是铁板一块的协议,它是**一组可选拼装件**。每个件
 
 | 启用前提 | 它的契约 |
 |---|---|
-| **使用 `ShrimpTable`(前端表格组件)** | • list 响应必须是 `IPageResult` = `{ list, total, page, pageSize, totalPages }`<br>• 字段 `type` 必须落在内置枚举:`string` / `number` / `boolean` / `date` / `select` / `textarea` / `password` / `relation` / `json` / `tab` —— 或自行注册 `IFieldTypeHandler`<br>• populate 字段旁挂 `${key}_label`(数组关联挂数组) |
+| **使用 `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) |
@@ -248,8 +248,31 @@ export class MyAdmin extends ShrimpServer {
 - `required: true` — 表单必填
 - `defaultValue: ...` — 新增时的默认值
 
-**字段 type 选这些:**
-`string` / `number` / `boolean` / `date` / `textarea` / `password` / `select` / `relation` / `json` / `tab`
+### 字段类型
+
+内置就这 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`,别借用不存在的名字。
 
 ---
 
@@ -287,6 +310,15 @@ const orderFields: IFieldConfig[] = [
 
 `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) {
diff --git a/package-lock.json b/package-lock.json
index 8b50c83..8d923ac 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
     "name": "shrimp-server",
-    "version": "0.7.12",
+    "version": "0.8.1",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "shrimp-server",
-            "version": "0.7.12",
+            "version": "0.8.1",
             "devDependencies": {
                 "@types/bcrypt": "^5.0.0",
                 "@types/express": "^5.0.0",
diff --git a/package.json b/package.json
index b0dd3d5..684e1e1 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "shrimp-server",
-    "version": "0.8.0",
+    "version": "0.8.1",
     "description": "Shrimp 框架后端 — 声明式字段驱动的 Node.js 管理后台框架(Express + Mongoose + JWT)",
     "main": "dist/main/index.js",
     "types": "dist/main/index.d.ts",