w-web-perm 1.1.12 → 1.1.13

package/server/keyCheck.mjs

@@ -0,0 +1,281 @@
+import iseobj from 'wsemi/src/iseobj.mjs'
+import findTouchedDup from '../src/js/findTouchedDup.mjs' //判準單一擁有者在 src/js(前端清單頁共用), 本檔轉出供 procCore.mjs 與測試沿用既有匯入路徑
+
+
+//名稱唯一(F-02)與使用者對應鍵(F-14)之判準, 單一擁有者(規則帳本 R-NAME-UNIQ-01／02、R-MAPKEY-01／02／03, ADR-034):
+//  外部同步(WWebPerm.mjs:syncAndReplaceTabs)、後台整表寫入(procCore.mjs:updateTabItems)、登入查找(WWebPerm.mjs:getTokenUser／getGenUserByKV)只呼叫本檔, 不複製判準.
+//比對一律精確 ===(與伺服端 arrFinder 與 getTokenUser 之 select 一致; 不做大小寫／空白正規化: 正規化後比對會放行伺服端視為不同之名稱, 或拒絕伺服端視為不同之鍵).
+//鍵之值非字串者不參與重複比對(空／非字串另由呼叫端之 isestr 檢查負責). 以 Map／Set 計, 免原型鍵名(constructor、__proto__)誤判(規則帳本 R-KEY-01).
+
+
+let isStr = (v) => typeof v === 'string'
+
+
+/**
+ * 回傳 rows 內第一個「key 欄位值(須為字串)與先前某參與列相同」之列索引, 無則 -1
+ *
+ * @param {Array} rows 列陣列
+ * @param {String} key 欄位名
+ * @param {Function} [isPart] 判斷該列是否參與比對(如只計 active), 預設全部參與
+ * @returns {Number} 第二次(含)出現者之索引, 無重複為 -1
+ */
+function findDupIndex(rows, key, isPart = () => true) {
+    if (!Array.isArray(rows)) {
+        return -1
+    }
+    let seen = new Set()
+    for (let k = 0; k < rows.length; k++) {
+        let r = rows[k]
+        if (!isPart(r)) {
+            continue
+        }
+        let v = (r === null || typeof r !== 'object') ? undefined : r[key]
+        if (!isStr(v)) {
+            continue
+        }
+        if (seen.has(v)) {
+            return k
+        }
+        seen.add(v)
+    }
+    return -1
+}
+
+
+/**
+ * rows 內是否有兩列 key 值相同(字串, 精確 ===)
+ */
+function hasDupKey(rows, key) {
+    return findDupIndex(rows, key) >= 0
+}
+
+
+/**
+ * 回傳 rows 中第一個「key 值已被 from 不等於本 from 之既有列使用」之索引, 無則 -1; 同 from 之既有列不算衝突(隨後由 delAll 重寫)
+ *
+ * @param {Array} rows 本批列
+ * @param {Array} rowsExist 該表既有之全部列(select 結果)
+ * @param {String} from 本批之 from
+ * @param {String} key 欄位名
+ * @param {Object} [opt={}] 設定
+ * @param {Boolean} [opt.onlyActive=false] 為 true 時兩側皆只計 isActive==='y' 之列(使用者對應鍵: getTokenUser 只匹配 active)
+ * @returns {Number} 衝突列之索引, 無為 -1
+ */
+function findKeyOtherFrom(rows, rowsExist, from, key, opt = {}) {
+    if (!Array.isArray(rows) || !Array.isArray(rowsExist)) {
+        return -1
+    }
+    let onlyActive = opt.onlyActive === true
+    let used = new Set()
+    for (let r of rowsExist) {
+        if (r === null || typeof r !== 'object') {
+            continue
+        }
+        if (r.from === from) {
+            continue
+        }
+        if (onlyActive && r.isActive !== 'y') {
+            continue
+        }
+        if (isStr(r[key])) {
+            used.add(r[key])
+        }
+    }
+    for (let k = 0; k < rows.length; k++) {
+        let r = rows[k]
+        if (r === null || typeof r !== 'object') {
+            continue
+        }
+        if (onlyActive && r.isActive !== 'y') {
+            continue
+        }
+        if (isStr(r[key]) && used.has(r[key])) {
+            return k
+        }
+    }
+    return -1
+}
+
+
+/**
+ * 同表寫入互斥鍵(外審 sol R10, D2 設計稿 (a) 之最小版): 外部同步(syncAndReplaceTabs)與後台整表寫入(updateTabItems)對同一張表須共用同一個 kmx 鍵,
+ * 否則兩者各自「先檢查名稱／對應鍵、後寫入」可交錯——檢查後、寫入前對方已完成寫入, F-02／F-14 之全域唯一性被略過(終態同名兩列、授權取決於列序).
+ * 兩條路徑內都不得再取同一個鍵(kmx 非可重入, 巢狀同鍵即死結): syncAndReplaceTabs 內只呼叫 procOrm／woItems, 不呼叫 updateTabItems.
+ *
+ * @param {String} keyTable 表名
+ * @returns {String} 回傳 kmx 鍵
+ */
+function tabWriteKey(keyTable) {
+    return 'tabWrite:' + keyTable
+}
+
+
+//取鎖階層(規則帳本 R-WRITE-LOCK-02, ADR-036): 引用鏈序「被引用者先、引用端後」targets → pemis → grups → users(引用端之階層恆高於被引用者); 所有需持多把表鎖之路徑(後台整表寫入、外部同步、日後之外部列保護／清源)只能經 withTabLocks 取鎖,
+//同一把鎖不巢狀(pmKeyMutex 非可重入, 巢狀同鍵與相反次序皆死結, D1 設計稿 probe-mutex 實測); 持鎖後才讀取、預檢與寫入, 使預檢與寫入涵蓋同一版本(外審 A.3)
+let TAB_LOCK_RANK = { targets: 0, pemis: 1, grups: 2, users: 3 }
+
+
+/**
+ * 依取鎖階層取齊指定表鎖後執行 fn(單一取鎖函數): 表名去重、依 targets → pemis → grups → users 排序(階層外之表名排最後、彼此依字典序), 由外而內巢狀取 kmx(tabWriteKey(表));
+ * 各路徑取鎖次序一致故不成環.
+ * 分段取鎖: 先取被引用表之鎖、依該表之新舊資料判定須改寫引用端後, 才在內層以 held 指明已持之表再取引用端表之鎖(寫入引用端表不涉改名／刪除者免取, 免無謂之互等);
+ * held 非空時, keyTables 之階層須全數高於 held(否則拋錯, 即違反階層, 不嘗試取鎖).
+ *
+ * @param {Function} kmx 輸入 pmKeyMutex 實例
+ * @param {Array} keyTables 輸入須持鎖之表名陣列
+ * @param {Function} fn 輸入持鎖後執行之 async 函數
+ * @param {Array} [held=[]] 輸入呼叫端已持有鎖之表名陣列(內層分段取鎖用)
+ * @returns {Promise} 回傳 fn 之結果
+ */
+function withTabLocks(kmx, keyTables, fn, held = []) {
+    let rank = (t) => (Object.prototype.hasOwnProperty.call(TAB_LOCK_RANK, t) ? TAB_LOCK_RANK[t] : Infinity)
+    let ts = [...new Set(keyTables)].sort((a, b) => (rank(a) - rank(b)) || (a < b ? -1 : (a > b ? 1 : 0)))
+    if (held.length > 0) {
+        let maxHeld = Math.max(...held.map(rank))
+        if (ts.some((t) => rank(t) <= maxHeld)) {
+            throw new Error('tab lock order violation')
+        }
+    }
+    let run = fn
+    for (let k = ts.length - 1; k >= 0; k--) {
+        let inner = run
+        let key = tabWriteKey(ts[k])
+        run = () => kmx(key, inner)
+    }
+    return run()
+}
+
+
+/**
+ * 使用者對應鍵(mappingBy)所指之 users 欄位: 'email'／'name' 回該欄位名, 其餘(含預設 'id')回 null(不另檢查: id 為主鍵, 既有 idOtherFrom 已涵蓋跨 from)
+ */
+function mapKeyOf(mappingBy) {
+    return (mappingBy === 'email' || mappingBy === 'name') ? mappingBy : null
+}
+
+
+/**
+ * 外部同步 users 之對應鍵批內檢查(F-14): mappingBy 為 'email'／'name' 時, 每個 isActive==='y' 之列, 該欄位須為非空字串(trim 後長度 > 0)且批內唯一(精確 ===);
+ * isActive 非 'y' 者不參與(getTokenUser 只匹配 active). 先掃全批之空值再查重複(次序決定性).
+ *
+ * @param {Array} rows 本批 users 列(已 ltdtmapping)
+ * @param {String} mappingBy 'id'｜'email'｜'name'
+ * @returns {Object|null} null 為通過; { reason: 'mapKeyInvalid'|'mapKeyDuplicate', k } 為第一個違規列
+ */
+function checkMapKeyBatch(rows, mappingBy) {
+    let key = mapKeyOf(mappingBy)
+    if (key === null || !Array.isArray(rows)) {
+        return null
+    }
+    let isActive = (r) => r !== null && typeof r === 'object' && r.isActive === 'y'
+    let kInvalid = rows.findIndex((r) => isActive(r) && !(isStr(r[key]) && r[key].trim().length > 0))
+    if (kInvalid >= 0) {
+        return { reason: 'mapKeyInvalid', k: kInvalid }
+    }
+    let kDup = findDupIndex(rows, key, isActive)
+    if (kDup >= 0) {
+        return { reason: 'mapKeyDuplicate', k: kDup }
+    }
+    return null
+}
+
+
+/**
+ * 後台整表寫入 users 之 email／對應鍵檢查(R-PRINCIPLE-00 適用表 h, 規則帳本 R-MAPKEY-03; 遭遇衝突就收嚴, 但歷史資料不得使所有存檔失敗, 只擋「本次造成或觸及」者):
+ *
+ *  ① 一般 email(任何 mappingBy, 全表含停用列): 須為非空字串(僅檢查「新增列」與「email 值與庫內同 id 列不同的列」, 歷史既有之空／非字串原樣送回不拒),
+ *     且不得與他列重複(判準 findTouchedDup, 歷史既有重複原樣送回不拒).
+ *  ② 對應鍵(mappingBy 為 'email'／'name' 時, 與外部同步 F-14 同口徑): 兩側先過濾成 isActive==='y' 之列再比;
+ *     該欄位須為非空字串(trim 後長度 > 0; 僅檢查「新增列」「該欄位值與庫內同 id 之 active 列不同的列」與「由非 active 改為 active 的列」),
+ *     且 active 列間不得重複(findTouchedDup; 一列由 inactive 改 active 而撞值亦屬本次造成). inactive 列不參與.
+ *     mappingBy 為 'id'(預設)不做②, 故 name 不檢查; mappingBy 為 'email' 時 ① 已涵蓋 active 列之 email, ② 另補「停用列改為啟用」之情形.
+ *
+ * 錯誤鍵沿用 saveRowFieldInvalid(空／非字串)與 saveRowFieldDuplicate(重複); reason 供 srLog 區分來源(不含欄位值: email／name 為個資).
+ * 次序: 先 ① 後 ②; 同一階段內空值與重複取列索引較小者(與修正前 ckKey 逐列掃描之次序一致).
+ *
+ * @param {Array} rowsNew 送入之整表(已 ltdtmapping、id 數字轉字串)
+ * @param {Array} rowsOld 庫內現有全部列(select 結果)
+ * @param {String} mappingBy 'id'｜'email'｜'name'(其他值視同 'id')
+ * @returns {Object|null} null 為通過; 否則 { key: 'saveRowFieldInvalid'|'saveRowFieldDuplicate', reason, field, k }(k 為 rowsNew 之列索引)
+ */
+function checkUsersWrite(rowsNew, rowsOld, mappingBy) {
+    if (!Array.isArray(rowsNew)) {
+        return null
+    }
+    let isObj = (r) => r !== null && typeof r === 'object'
+    let isEstr = (v) => isStr(v) && v.length > 0
+    let isFilled = (v) => isStr(v) && v.trim().length > 0
+    let isActive = (r) => isObj(r) && r.isActive === 'y'
+    let listOld = Array.isArray(rowsOld) ? rowsOld.filter(isObj) : []
+
+    //findBad: listNew 中第一個「本次造成或觸及」且 key 值不合 isOk 之索引, 無則 -1; 新增列(庫內無同 id)與 key 值與庫內同 id 列不同者為造成或觸及
+    let findBad = (listNew, list, key, isOk) => {
+        let byId = new Map()
+        for (let r of list) {
+            if (isStr(r.id)) {
+                byId.set(r.id, r)
+            }
+        }
+        return listNew.findIndex((r) => {
+            let v = isObj(r) ? r[key] : undefined
+            let o = (isObj(r) && isStr(r.id)) ? byId.get(r.id) : undefined
+            let touched = o === undefined || v !== o[key]
+            return touched && !isOk(v)
+        })
+    }
+
+    //judge: 一個階段(列集合, 欄位, 空值判準, reason 前綴)之結果; idxMap 為過濾後索引對應回 rowsNew 之原索引
+    let judge = (listNew, idxMap, list, key, isOk, tag) => {
+        let kBad = findBad(listNew, list, key, isOk)
+        let kDup = findTouchedDup(listNew, list, key)
+        if (kBad < 0 && kDup < 0) {
+            return null
+        }
+        let isBad = kBad >= 0 && (kDup < 0 || kBad <= kDup) //同一列既空又被當重複(如新增第二個空字串 email)時以「空值」為主(與修正前 ckKey 先判空再判重複一致)
+        return {
+            key: isBad ? 'saveRowFieldInvalid' : 'saveRowFieldDuplicate',
+            reason: isBad ? `${tag}Invalid` : `${tag}Duplicate`,
+            field: key,
+            k: idxMap[isBad ? kBad : kDup],
+        }
+    }
+
+    //① 一般 email
+    let r1 = judge(rowsNew, rowsNew.map((v, k) => k), listOld, 'email', isEstr, 'email')
+    if (r1 !== null) {
+        return r1
+    }
+
+    //② 對應鍵(僅 active 列)
+    let keyMap = mapKeyOf(mappingBy)
+    if (keyMap === null) {
+        return null
+    }
+    let idxAct = []
+    let rowsNewAct = []
+    rowsNew.forEach((r, k) => {
+        if (isActive(r)) {
+            idxAct.push(k)
+            rowsNewAct.push(r)
+        }
+    })
+    return judge(rowsNewAct, idxAct, listOld.filter(isActive), keyMap, isFilled, 'mapKey')
+}
+
+
+/**
+ * 登入查找之結果判定(F-14): 以對應鍵查 perm users(isActive='y')命中 0 筆／1 筆／多筆; 多筆不取首筆(user 為 null, 由呼叫端依 count 拒絕)
+ *
+ * @param {Array} rs select 結果
+ * @returns {Object} { user, count }: count 為物件列之筆數; 僅 count===1 時 user 為該列
+ */
+function pickUniqueUser(rs) {
+    let rows = Array.isArray(rs) ? rs.filter((r) => iseobj(r)) : []
+    return {
+        user: rows.length === 1 ? rows[0] : null,
+        count: rows.length,
+    }
+}
+
+
+export { findDupIndex, hasDupKey, findKeyOtherFrom, findTouchedDup, tabWriteKey, withTabLocks, mapKeyOf, checkMapKeyBatch, checkUsersWrite, pickUniqueUser }

package/server/procCore.mjs

@@ -13,6 +13,11 @@ import getOwn from '../src/js/getOwn.mjs'
 import ds from '../src/schema/index.mjs'
 import procLang from './procLang.mjs'
 import validateRowsBeforeWrite from './validateRows.mjs'
+import planRefChanges, { REF_OF, diffRefTargets, fillIdlessIds } from '../src/js/refCascade.mjs'
+import { restoreExternalOrder, dropServerOnlyDiff, restoreServerFields, checkExternalWrite, hasExternalDiff } from '../src/js/externalRows.mjs'
+import { isBaselineValid, checkBaseline } from '../src/js/rowDigest.mjs'
+import { findTouchedDup, findDupIndex, withTabLocks, checkUsersWrite } from './keyCheck.mjs'
+import { checkCascadePlan, writeWithCascade } from './cascadeWrite.mjs'
 
 
 //isRowObj: 待寫入之列須為至少有一個自有可列舉鍵之物件(非 null、非陣列; 不用依 toString 判型之 iseobj, 免被 Symbol.toStringTag 偽稱)
@@ -58,7 +63,17 @@ function mergePickKeysOnly(ltdtDb, rowsIn, keyDetect, pickKeys) {
 }
 
 
-function proc(woItems, procOrm, { srLog, kmx, lockSave }) {
+//mappingBy: 使用者對應鍵('id'｜'email'｜'name', WWebPerm 已正規化; 未給或其他值視同 'id'), 供 users 整表寫入的對應鍵檢查(R-PRINCIPLE-00 適用表 h, R-MAPKEY-03)
+//cascadeRename: 群組／權限改名時是否連帶更新引用(預設 true; 只管改名, 刪除連帶清理不受影響, R-REF-CASCADE-01)
+//lockExternalRows: 後台是否不得改外部列(from 為非空字串者)之身分／結構欄(預設 true, R-EXT-OWN-01; 'n' 時回到舊行為, 僅保留 from 型別檢查)
+function proc(woItems, procOrm, { srLog, kmx, lockSave, mappingBy = 'id', cascadeRename = true, lockExternalRows = true }) {
+
+
+    //pickClientOpt: 用戶端(kpFunExt 第 3 參)只採納 baseline, 不接受 pickKeysOnly 等伺服端設定; 未給(undefined／null)視為舊客戶端
+    let pickClientOpt = (opt) => {
+        let b = (opt !== null && typeof opt === 'object') ? opt.baseline : undefined
+        return (b === undefined || b === null) ? {} : { baseline: b }
+    }
 
 
     //updateTabItems
@@ -74,6 +89,13 @@ function proc(woItems, procOrm, { srLog, kmx, lockSave }) {
             return Promise.reject('saveRowFieldInvalid')
         }
 
+        //baseline: 草稿所依據之載入基準 [[id, digest], ...](F-26, R-BASELINE-01; 前端於開啟編輯時綁定); 未給(舊客戶端)為 null; 給了但格式不合視為無效請求, 於任何讀寫之前拒絕
+        let baseline = get(opt, 'baseline', null)
+        if (baseline !== null && !isBaselineValid(baseline)) {
+            srLog.error({ event: 'updateTabItems-validate-error', keyTable, msg: 'saveRowFieldInvalid', reason: 'baselineInvalid', row: -1, field: '' })
+            return Promise.reject('saveRowFieldInvalid')
+        }
+
         //pickKeysOnly, 僅採納既有列之指定欄位變更(見 mergePickKeysOnly), 未給則整表 diff 寫入
         let pickKeysOnly = get(opt, 'pickKeysOnly', null)
 
@@ -91,10 +113,16 @@ function proc(woItems, procOrm, { srLog, kmx, lockSave }) {
         //雙擊防護(後端): 同一操作者之同表寫入處理中再送出即拒絕 'saveInProgress'(不排隊, 見 lockSave.mjs, ADR-025);
         //占位包在 kmx 之外層, 不同操作者之並行寫入仍由 kmx 序列化、各自成功(ADR-012)
         //序列化同表之並行整表批次寫入: 防 lost update (同 keyTable 序列化, 不同表並行)
-        return await lockSave(`updateTabItems:${keyTable}`, userId, () => kmx('updateTabItems:' + keyTable, async () => {
+        //持鎖: 先取本表之鎖; 本表有改名或刪除而須改寫引用端時, 才於內層依階層再取引用端表之鎖(見下方「引用連帶」段). 皆經單一取鎖函數(R-WRITE-LOCK-02); 與外部同步(WWebPerm.syncAndReplaceTabs)共用同表互斥鍵(外審 sol R10)
+        return await lockSave(`updateTabItems:${keyTable}`, userId, () => withTabLocks(kmx, [keyTable], async () => {
 
         //pickKeysOnly, 須於 mutex 內讀取資料庫為基底, 避免與並行寫入 race
         if (isearr(pickKeysOnly)) {
+            //有限數字 id 先轉為字串形式再與庫內對應(外審 sol R7): mergePickKeysOnly 只認非空字串 id, 數字 id(如 1)對不上庫內之 '1' 而該列指派被靜默略過卻回成功(R-ORM-04 之同一正規化, 此處原晚於合併)
+            rows = map(rows, (r) => {
+                let id = get(r, 'id')
+                return (typeof id === 'number' && Number.isFinite(id)) ? { ...r, id: String(id) } : r
+            })
             let ltdtDb = await woItems[keyTable].select()
             rows = mergePickKeysOnly(ltdtDb, rows, keyDetect, pickKeysOnly)
             srLog.info({ event: 'updateTabItems-pickKeysOnly', keyTable, userId, pickKeysOnly })
@@ -111,7 +139,8 @@ function proc(woItems, procOrm, { srLog, kmx, lockSave }) {
         })
 
         //ckKey, 回傳 err key (saveRowFieldInvalid / saveRowFieldDuplicate) 或 null; 動態細節 (row index/field/value) 改記 srLog, 不進使用者訊息
-        let ckKey = (rows, key) => {
+        //opt.skipDup 為 true 時只檢查空值／非字串, 不檢查重複: pemis／grups 之名稱唯一改由下方 findTouchedDup 判定(只拒本次造成或觸及者, F-02, ADR-034)
+        let ckKey = (rows, key, opt = {}) => {
             let err = null
 
             //check
@@ -129,7 +158,7 @@ function proc(woItems, procOrm, { srLog, kmx, lockSave }) {
                 }
 
                 //check
-                if (haskey(kp, value)) {
+                if (opt.skipDup !== true && haskey(kp, value)) {
                     srLog.error({ event: 'updateTabItems-ckKey-error', keyTable, key, msg: 'saveRowFieldDuplicate', row: k, value })
                     err = `saveRowFieldDuplicate`
                     return false //跳出
@@ -152,18 +181,13 @@ function proc(woItems, procOrm, { srLog, kmx, lockSave }) {
                     return Promise.reject(err)
                 }
             }
-            if (arrHas(keyTable, ['pemis', 'grups'])) { //users可重複name故不列入
-                err = ckKey(rows, 'name')
-                if (err !== null) {
-                    return Promise.reject(err)
-                }
-            }
-            if (arrHas(keyTable, ['users'])) {
-                err = ckKey(rows, 'email')
+            if (arrHas(keyTable, ['pemis', 'grups'])) { //users可重複name故不列入; 此處只驗空值, 名稱重複見下方 findTouchedDup
+                err = ckKey(rows, 'name', { skipDup: true })
                 if (err !== null) {
                     return Promise.reject(err)
                 }
             }
+            //users 之 email／對應鍵檢查改至下方 select 之後(需庫內現況判定「本次造成或觸及」, R-PRINCIPLE-00 適用表 h), 不再於此以整表 ckKey('email') 擋(歷史空值／重複會使所有存檔失敗)
         }
 
         //主鍵之有限數字轉為其字串形式(規則帳本 R-ORM-04; w-serv-orm 1.1.11 起庫內即如此存放): ltdtDiffByKey 以嚴格比對, 未轉時 123 對不上庫內之 '123',
@@ -173,9 +197,59 @@ function proc(woItems, procOrm, { srLog, kmx, lockSave }) {
             return (typeof id === 'number' && Number.isFinite(id)) ? { ...r, id: String(id) } : r
         })
 
+        //pemis／grups 以 id 對應既有列(見下方 isNameKeyTable 分支), 送入之整表內主鍵 id(字串)不得重複, 否則 Map(id → 列) 靜默併成一列而遺失其一(unit-procCore-writeValidate WV-008);
+        //缺 id 之列(API 直打, 視為新增)不參與; 錯誤鍵同 validateRowsBeforeWrite 之 idDuplicate: saveRowFieldDuplicate
+        if (arrHas(keyTable, ['pemis', 'grups'])) {
+            let kIdDup = findDupIndex(rows, 'id', (r) => isestr(get(r, 'id'))) //空字串 id 視為未給(待自動產號, validateRows 同), 不參與重複判定(外審 sol R6)
+            if (kIdDup >= 0) {
+                srLog.error({ event: 'updateTabItems-ckKey-error', keyTable, key: 'id', msg: 'saveRowFieldDuplicate', row: kIdDup, value: get(rows, [kIdDup, 'id']) })
+                return Promise.reject('saveRowFieldDuplicate')
+            }
+        }
+
         //ltdtDiffByKey
         let ltdtOld = await woItems[keyTable].select()
 
+        //表級載入基準比對(R-PRINCIPLE-00 原則 7, 規則帳本 R-BASELINE-01, ADR-037 Update(run11); 使用者 2026-10-22 裁示「多人同時編輯以表雜湊比對, 先動先贏」):
+        //有基準者, 草稿載入時之整表須與目前庫內整表相同(任一列內容指紋不同或列被增刪即過期), 否則整次拒收 saveStale、零寫入, 不部分變更、不上鎖; 指紋排除 order 與伺服器管理欄(見 rowDigest.getDigestFields).
+        //放在 select 之後、所有檢查與還原之前: 基準過期時下列各檢查之結果(撞名、新增列已存在、外部列守門…)皆以過期之畫面為前提, 應先回「請重新載入」而非誤導之其他訊息.
+        //無基準者(舊客戶端)不在此檢查: 後台列維持最後寫入者勝(ADR-013), 外部列之指派欄改動另於下方拒收(saveBaselineRequired). srLog 只記錯誤鍵、原因與差異筆數, 不記列 id／個資值
+        if (baseline !== null) {
+            let ck = checkBaseline({ keys: ds[keyTable].keys, ltdtOld, baseline })
+            if (ck !== null) {
+                srLog.error({ event: 'updateTabItems-stale-error', keyTable, userId, msg: ck.key, reason: ck.reason, n: ck.n })
+                return Promise.reject(ck.key)
+            }
+        }
+
+        //外部列之 order 由外部擁有(R-EXT-OWN-01): 上方 order=k+1 重編不得改外部列之順序, 還原為庫內值(使其不因後台存檔而成為 diff)
+        if (lockExternalRows) {
+            rows = restoreExternalOrder(rows, ltdtOld)
+        }
+
+        //pemis／grups 名稱唯一(F-02, 規則帳本 R-NAME-UNIQ-02, ADR-034): 寫入後之名稱集合即送入之整表(含他 from 之外部同步列), 其中出現兩列(不同 id)同名且為「本次造成或觸及」者整次拒收於任何寫入之前;
+        //庫內已有之歷史重複(僅外部同步可造成)原樣送回不算, 否則已有重複之庫將無法在後台修復. 比對為精確 ===(同 arrFinder). 放在 select 之後、saveNewRowExists 之前, 使撞名先於「新增列已存在」被回報(與修正前 ckKey 之次序相同)
+        let isNameKeyTable = arrHas(keyTable, ['pemis', 'grups'])
+        if (isNameKeyTable) {
+            let kDup = findTouchedDup(rows, ltdtOld, 'name')
+            if (kDup >= 0) {
+                srLog.error({ event: 'updateTabItems-ckKey-error', keyTable, key: 'name', msg: 'nameDuplicate', row: kDup, value: get(rows, [kDup, 'name']) })
+                return Promise.reject('nameDuplicate')
+            }
+        }
+
+        //users 之 email／對應鍵(R-PRINCIPLE-00 適用表 h, 規則帳本 R-MAPKEY-03): 遭遇衝突就收嚴, 但只擋「本次造成或觸及」者, 歷史既有之空值／重複原樣送回不拒(否則已有歷史資料之庫無法在後台修復, 連群組指派 pickKeysOnly 也會失敗);
+        //①全表 email 須為非空字串且不重複; ②mappingBy 為 email／name 時另對 isActive==='y' 之列檢查該欄位(含停用改啟用); 判準單一擁有者 keyCheck.checkUsersWrite(與外部同步 F-14 同口徑).
+        //放在 select 之後、saveNewRowExists 之前(次序同 pemis／grups 之 findTouchedDup), 於任何破壞性寫入之前(本函式在 kmx(tabWriteKey) 內, R-WRITE-LOCK-01); 被拒時資料表零變更.
+        //srLog 只記錯誤鍵、原因、欄位與列索引, 不記 email／name 之值(個資; 修正前重複時記 value)
+        if (keyTable === 'users') {
+            let ck = checkUsersWrite(rows, ltdtOld, mappingBy)
+            if (ck !== null) {
+                srLog.error({ event: 'updateTabItems-ckKey-error', keyTable, key: ck.field, msg: ck.key, reason: ck.reason, row: ck.k })
+                return Promise.reject(ck.key)
+            }
+        }
+
         //新增列已存在即拒絕 (ADR-025): 同一包重送且第 2 次於第 1 次完成後才處理時(占位已釋放), 第 1 次已建立之列會被當「修改」(diff),
         //以前端之佔位字覆寫伺服器於新增時填入之建立者 / 建立時間(procOrm save 只覆寫 userIdUpdate / timeUpdate); 故整包拒絕、不寫入
         if (size(idsNew) > 0) {
@@ -189,9 +263,44 @@ function proc(woItems, procOrm, { srLog, kmx, lockSave }) {
         }
 
         let ltdtNew = rows
-        let r = ltdtDiffByKey(ltdtOld, ltdtNew, keyDetect)
+        let r = null
+        if (isNameKeyTable || keyTable === 'users') { //users 亦拆出缺 id 之列(外審 sol R5): 同批兩列缺 id 時 ltdtmapping 皆補 id:'', ltdtDiffByKey 以 Map(id → 列) 使前列被後列覆蓋而只建立一列卻回成功
+            //pemis／grups 一律以主鍵 id 對應(F-02 完整化, run04 主責補強, ADR-034 Update): 寫入後之名稱集合須等於送入之整表, findTouchedDup 對「送入整表」驗唯一才成立,
+            //而以 name 為 diff 鍵時 ltdtDiffByKey 以 Map(name → 列) 對應, 下列單次存檔雖通過檢查卻使庫內與送入不同、留下同名兩列且仍回成功(D1 設計稿 §1.5 以真 procCore＋ORM 替身實測,
+            //unit-procCore-nameUniq NU-021～024 守護): ①改名 A→A2 並以舊名 A 新增另一列(新 id)——改名靜默遺失; ②刪除 A 並以同名新增(新 id, F-02② 原案)——舊列未刪;
+            //③鏈式改名 A→B 且 B→C——id-2 應為 C 卻停在 B; ④庫內已有同名列(歷史重複)時改名其中先出現之一列——新名稱之列走 add 而其 id 已存在, insert 對既有主鍵略過(NU-011 修前實測).
+            //改以 id 對應後: 改名成為 diff 而非 del + add(建立者與建立時間沿用庫內, 同名之歷史重複各自獨立); 缺 id 之送入列(API 直打)無從對應既有列, 視為新增.
+            let withId = ltdtNew.filter((v) => isestr(get(v, 'id')))
+            let noId = ltdtNew.filter((v) => !isestr(get(v, 'id')))
+            r = ltdtDiffByKey(ltdtOld, withId, 'id')
+            r.add = [...r.add, ...noId]
+        }
+        else {
+            r = ltdtDiffByKey(ltdtOld, ltdtNew, keyDetect)
+        }
         // console.log('ltdtDiffByKey r', r)
 
+        //外部列保護(F-23; R-PRINCIPLE-00 原則 3、5; 規則帳本 R-EXT-OWN-01, ADR-037): 於任何寫入之前(含引用端), 違規整次拒收、資料表零變更, 不靜默忽略;
+        //(載入基準之表級比對 checkBaseline 已在上方 select 之後先行, run11: 基準過期時應先回「請重新載入」, 而非誤導之「外部列不可修改」, run07 U1 觀察 1)
+        //①外部列僅伺服器管理欄不同者(外部同步重寫使其時間／建立者較新, 持舊快照送回)視為無變更, 免把建立者與建立時間回退為舊值(S2); 內容確有改動(指派欄)之外部列改帶庫內之伺服器管理欄寫入(restoreServerFields);
+        //②from 型別與外部列守門(checkExternalWrite): 新增列 from 須為 ''、外部列不可刪／不可改 from 與身分結構欄, 指派欄可寫(草稿新鮮而仍違規者在此被拒);
+        //③無基準而修改外部列之指派欄: 無從證明快照新舊, Lv1 放行之指派欄不得因舊快照還原外部已撤銷之授權(外審 B.2), 依原則 3 拒收(saveBaselineRequired); 後台列無基準維持舊行為(最後寫入者勝, ADR-013).
+        //srLog 只記錯誤鍵、原因、筆數與來源名稱, 不記列 id／個資值
+        let keysTab = ds[keyTable].keys
+        if (lockExternalRows) {
+            r = dropServerOnlyDiff({ keys: keysTab, r, ltdtOld })
+            r = restoreServerFields({ r, ltdtOld }) //改動之外部列帶庫內之伺服器管理欄: 持舊草稿(保留未存編輯期間外部同步重寫了該列)不得把較新之建立者／建立時間回退(外審 sol 第 3 點)
+        }
+        let ex =checkExternalWrite({ keyTable, keys: keysTab, r, ltdtOld, lockExternalRows })
+        if (ex !== null) {
+            srLog.error({ event: 'updateTabItems-external-error', keyTable, userId, msg: ex.key, reason: ex.reason, n: ex.n, froms: ex.froms })
+            return Promise.reject(ex.key)
+        }
+        if (baseline === null && lockExternalRows && hasExternalDiff({ r, ltdtOld })) {
+            srLog.error({ event: 'updateTabItems-stale-error', keyTable, userId, msg: 'saveBaselineRequired', reason: 'externalAssignNoBaseline' })
+            return Promise.reject('saveBaselineRequired')
+        }
+
         //寫入前驗證(規則帳本 R-ORM-01, ADR-026): 於第一個破壞步驟(del)之前擋下可預判之寫入失敗, 被拒時資料表零變更.
         //why: 寫入順序為 del → insert → save, 而 w-serv-orm 1.1.8 起對「會被 clearXSS 改寫之主鍵」整批拒絕、LMDB 對 > 1978 B 之主鍵整批拒絕,
         //修正前遇之即「舊列已刪、新列被拒」(改標的 id 時該列遺失, 2026-10-14 V3/V7 實測); 非主鍵欄位之標記則被靜默改寫(存值≠送入值).
@@ -209,30 +318,59 @@ function proc(woItems, procOrm, { srLog, kmx, lockSave }) {
             return Promise.reject(key)
         }
 
-        //del
-        if (size(r.del) > 0) {
-            await procOrm(userId, keyTable, 'del', r.del) //須使用procOrm才有辦法自動給予相關欄位
-            // .catch((err) => {
-            //     console.log('woItems[keyTable].del err', err)
-            // })
-        }
+        //writeMain
+        let writeMain = async () => {
+
+            //del
+            if (size(r.del) > 0) {
+                await procOrm(userId, keyTable, 'del', r.del) //須使用procOrm才有辦法自動給予相關欄位
+                // .catch((err) => {
+                //     console.log('woItems[keyTable].del err', err)
+                // })
+            }
+
+            //add
+            if (size(r.add) > 0) {
+                await procOrm(userId, keyTable, 'insert', r.add) //須使用procOrm才有辦法自動給予相關欄位
+                // .catch((err) => {
+                //     console.log('woItems[keyTable].insert err', err)
+                // })
+            }
+
+            //diff
+            if (size(r.diff) > 0) {
+                await procOrm(userId, keyTable, 'save', r.diff) //須使用procOrm才有辦法自動給予相關欄位
+                // .catch((err) => {
+                //     console.log('woItems[keyTable].save err', err)
+                // })
+            }
 
-        //add
-        if (size(r.add) > 0) {
-            await procOrm(userId, keyTable, 'insert', r.add) //須使用procOrm才有辦法自動給予相關欄位
-            // .catch((err) => {
-            //     console.log('woItems[keyTable].insert err', err)
-            // })
         }
 
-        //diff
-        if (size(r.diff) > 0) {
-            await procOrm(userId, keyTable, 'save', r.diff) //須使用procOrm才有辦法自動給予相關欄位
-            // .catch((err) => {
-            //     console.log('woItems[keyTable].save err', err)
-            // })
+        //引用連帶(R-PRINCIPLE-00 原則 6、適用表 m／n, 規則帳本 R-REF-CASCADE-01, ADR-036): grups／pemis 改名(同 id 異名)與 grups／pemis／targets 刪除(舊 id 不在送入整表),
+        //須於同一次寫入內連帶更新／清理引用它之授權字串(users.cgrups、grups.cpemis、pemis.crules). 是否須改寫引用端只依本表新舊列判定(diffRefTargets), 故於持有本表鎖之下即可決定是否再取引用端表之鎖;
+        //取齊鎖之後才讀取引用端、規劃與預檢(新名撞懸空名、歷史同名組改名、容器內相撞、改寫後欄位驗證), 預檢與寫入涵蓋同一版本(外審 A.3), 被拒時資料表零變更.
+        //寫入為引用端先、主體後, 失敗時補償還原引用端(cascadeWrite.mjs)
+        //未帶 id 之列(API 直打; 寫入時 ORM 補隨機主鍵, 即舊列刪、新列增)改依名稱對應既有列, 同名即同一實體而不清空引用(fillIdlessIds)
+        let rowsPlan = arrHas(keyTable, ['targets', 'pemis', 'grups']) ? fillIdlessIds(keyTable, ltdtOld, ltdtNew) : ltdtNew
+        let kind = arrHas(keyTable, ['targets', 'pemis', 'grups']) ? diffRefTargets({ keyTable, rowsOld: ltdtOld, rowsNew: rowsPlan, opt: { cascadeRename } }) : null
+        if (kind !== null && (kind.renames.length > 0 || kind.delNames.length > 0)) {
+            let holder = REF_OF[keyTable].holder
+            return await withTabLocks(kmx, [holder], async () => {
+                let holdersOld = await woItems[holder].select()
+                let plan = planRefChanges({ keyTable, rowsOld: ltdtOld, rowsNew: rowsPlan, holdersOld, opt: { cascadeRename } })
+                let errPlan = plan.err !== null ? plan.err : checkCascadePlan(plan)
+                if (errPlan !== null) {
+                    srLog.error({ event: 'updateTabItems-refCascade-error', keyTable, msg: errPlan })
+                    return Promise.reject(errPlan)
+                }
+                await writeWithCascade({ plan, holdersOld, woItems, procOrm, userId, srLog, writeMain })
+                return ltdtNew
+            }, [keyTable])
         }
 
+        await writeMain()
+
         return ltdtNew
 
         }))
@@ -252,9 +390,9 @@ function proc(woItems, procOrm, { srLog, kmx, lockSave }) {
 
 
     //updateTargets
-    let updateTargets = async (userId, rows) => {
+    let updateTargets = async (userId, rows, opt = {}) => {
         try {
-            await updateTabItems('targets', userId, rows, 'id')
+            await updateTabItems('targets', userId, rows, 'id', pickClientOpt(opt))
         }
         catch (err) { throw errLog('updateTargets-error', userId, err) }
         srLog.info({ event: 'updateTargets-success', userId })
@@ -263,9 +401,9 @@ function proc(woItems, procOrm, { srLog, kmx, lockSave }) {
 
 
     //updatePemis
-    let updatePemis = async (userId, rows) => {
+    let updatePemis = async (userId, rows, opt = {}) => {
         try {
-            await updateTabItems('pemis', userId, rows, 'name')
+            await updateTabItems('pemis', userId, rows, 'name', pickClientOpt(opt))
         }
         catch (err) { throw errLog('updatePemis-error', userId, err) }
         srLog.info({ event: 'updatePemis-success', userId })
@@ -274,9 +412,9 @@ function proc(woItems, procOrm, { srLog, kmx, lockSave }) {
 
 
     //updateGrups
-    let updateGrups = async (userId, rows) => {
+    let updateGrups = async (userId, rows, opt = {}) => {
         try {
-            await updateTabItems('grups', userId, rows, 'name')
+            await updateTabItems('grups', userId, rows, 'name', pickClientOpt(opt))
         }
         catch (err) { throw errLog('updateGrups-error', userId, err) }
         srLog.info({ event: 'updateGrups-success', userId })
@@ -284,7 +422,8 @@ function proc(woItems, procOrm, { srLog, kmx, lockSave }) {
     }
 
 
-    //updateUsers, opt.pickKeysOnly 給 ['cgrups'] 時僅採納既有使用者之群組指派變更(modeEditUsers='for:grups')
+    //updateUsers, opt.pickKeysOnly 給 ['cgrups'] 時僅採納既有使用者之群組指派變更(modeEditUsers='for:grups'; 伺服端設定, WWebPerm 組入, 不接受用戶端給);
+    //opt.baseline 為草稿載入基準(用戶端給, 其餘 opt 鍵不採納, 見 pickClientOpt 與 WWebPerm 之 kpFunExt)
     let updateUsers = async (userId, rows, opt = {}) => {
         try {
             await updateTabItems('users', userId, rows, 'id', opt)