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