dsh-whale-post-roster

English: roster README in English

名单接口：谁在名单里（含成员属性与群发清单）＋ 读 JSON 的样例实现

• 提供接口：whale.roster
• 依赖接口：（无）
• 自测：node selftest.mjs（只看退出码：0 过／非 0 不过）

接口带 apiVersion；核心不许知道任何名字 —— 名单只在这里，核心一行名字都没有。 属性名也一样：flag(id, name) 的 name 由配置或调用方给 ⇒ 本件里不出现任何具体属性名。

接口

| 方法 | 一句话 | |---|---| | list() | 全部成员（保留成员自带的其余字段 —— 自定义属性不会被吃掉） | | has(id) | 名单里有这个人吗 | | label(id) | 他叫什么（缺省退回 id） | | member(id) | 整条成员记录（含自定义属性）；不认识 ⇒ undefined | | flag(id, name) | 成员属性：两种来源都认；假值（false／0／空串）一律算"不带" | | without(ids, name) | 从一份名单里剔掉带该属性的人（认不出的原样留着，不越权改名单） | | broadcast() | 群发该发给谁 ＝ 完整名单剔掉 groupWithout | | groups() | 有哪些组名 | | group(name, opts) | 某组成员；opts.without 可临时剔；opts.without: null ⇒ 这一次不剔 |

名单文件（格式公开、内容自填）

{ "apiVersion": 1,
  "members": [ { "id": "alice", "label": "Alice" },
               { "id": "carol", "label": "Carol", "<属性名>": true } ],
  "groups": { "all": ["alice", "carol"], "club": ["alice"] },
  "<属性名>": ["carol"] }

• id 就是信箱目录名（<root>/inbox/<id>/）。
• 成员属性两种写法都认（任选）：① 写在成员对象上 ② 顶层同名数组。
• 成员写成纯字符串也认（"alice"）；没有 id 的一律丢掉。
• 坏输入不抛未捕获异常 —— 坏 JSON／不是对象／apiVersion 不认识 ⇒ 一律退化成空名单。

配置

| 字段 | 默认 | 含义 | |---|---|---| | file | <root>/roster.json | 名单文件 | | groupWithout | 不配 | 群发默认剔掉带此属性的成员；点名不受影响（"群发默认不到它，点名才进"） | | sample | false | true ⇒ 文件不存在时用内置样例（只为试跑） |

边界

• provider 撒谎，核心拦不住 —— 核心不认识任何名字，所以它没法自己判定"谁才算合法成员"； 要防这一层就在本件加校验与自测。
• 组员必须出现在名单里才投（否则"幽灵组员"会收到信 ⇒ 会往名单外的信箱写文件）。
• 发给一个组、组里剔完没人 ⇒ 拒发（宁可不发，也不发一封没有收件人的信）。