1. 先把"出一张表"当成一个工程问题来看
GlobalDietaryR 这个包把 GDD 数据库里最脏的那部分活干得相当漂亮——读数据、对齐字段名、统一单位、处理缺失码，基本上一行read_gdd()加几个清洗函数就能拿到一张干净的暴露表。但用得久了你会发现，真正吃掉时间的部分在包的外面：拿到一张洗好的数据之后，怎么稳定地产出十几张口径一致、格式统一、同行一眼能看懂的表格。我把它叫做GDD 数据库通用表格生成系统，说白了就是一套"给数据 + 给规格，自动吐出成品表"的流水线。
为什么值得单独做成系统？因为膳食暴露数据天生是"多维、多口径、高返工"的体质。一份典型的 GDD 风格暴露表，横向挂着食物组、营养素、年龄组、性别、教育水平、年份、区域编码这么多层维度，字段动辄上百个。同一份数据，写报告要一张描述性统计表，做敏感性分析要一张按权重方案对比的表，投稿又要一张按分层展开的补充材料表。如果每次都是打开一个新脚本，复制上一段group_by再改两行，三个月后你自己都说不清哪张表的权重用的是哪一个变量。
这套系统适合谁？如果你只是偶尔跑一次单表分析，写几行 dplyr 就够了，不必上系统。但只要你符合下面任意一条，就值得花两天时间搭起来：同一批数据要反复出表超过五次；表格要交给别人复核或者写进正式文档；表格的数字要能被追溯回具体代码行；换一批数据（比如新版本发布）之后表格结构不能变。这套东西本质上是把"表格长什么样"和"数字怎么算出来"彻底分开，前者写成配置文件，后者写成受测试保护的函数。分开之后，改表头不用碰计算逻辑，改算法不用重排格式，两边各自演进。
1.1 手工脚本失控的典型轨迹
我见过太多项目是这么烂掉的。第一周，一个人写了三十行代码，group_by(food_grp, sex) %>% summarise(mean = weighted.mean(intake, w))，跑通了，皆大欢喜。第二周要加年龄分层，顺手复制一份改改。第三周发现有的食物组零消费比例极高，均值没意义，得加"消费者均值"，于是又开一个分支。到第六周，脚本目录里躺着table1.R、table1_v2.R、table1_final.R、table1_final_fix.R，每个文件里都有一段看着像但又不太一样的加权逻辑。
问题的根子不在代码水平，而在于表格的"形状"和"数值"被焊死在同一段代码里。表头改了要动计算函数，计算口径改了要小心别碰到格式化那几行。这种耦合在手写脚本里几乎无法避免，因为 R 的表达方式天然鼓励你把"取数—算—拼—打印"写成一条管道。真正的解耦需要人为设计一层中间表示，这也是后面整个架构的核心。
1.2 通用表格生成系统到底接手了哪些活
把需求拆开看，一套表格生成系统要负责四件事。第一是读规格：这张表有哪些行变量、哪些列变量、算什么统计量、保留几位小数、标题叫什么。第二是查字典：变量内部编码对应的中文标签是什么、分类水平按什么顺序排、单位是克还是千卡。第三是算数值：按规格分组、按权重加权、算均值标准误样本量，处理空组和缺失。第四是渲染成品：把算好的长表转成宽表，套上多层表头，输出成 Word、Excel 或者 Markdown。
这里有个容易被忽略的取舍：到底该把这四件事做成四个函数顺序调用，还是做成一个入口 + 配置？我的选择是后者，理由很实际——使用者不该被迫记住调用顺序。做成一个build_table("T01", data)之后，新增一张表只需要新增一个 YAML 文件，不需要新增任何 R 代码。这一点在多人协作里价值极大，因为写 YAML 的门槛远低于写 R，做数据的人可以自己加表，不用排队等写代码的人。
1.3 系统的边界：哪些坚决不做
新手搭这类系统最常见的失败模式是贪多。想着一劳永逸，把绘图、显著性检验、自动写文字描述全塞进去，结果三个月后没人敢改。我的原则是划三条硬边界。第一，不做统计推断的自动化，系统只负责算描述量，p 值、模型拟合留在外面，因为推断方法的选择高度依赖具体问题，不适合配置化。第二，不做数据清洗，清洗交给上游，系统接收的必须是已经规整好的长表或宽表，一旦系统开始处理"这个字段有时候是字符有时候是数字"这类脏活，配置就会爆炸。第三，不追求覆盖所有表格形态，能覆盖 80% 的常规表就够，剩下 20% 的特殊表允许手写，但手写的那张表必须复用同一套格式化函数，保证数字风格一致。
2. 四层架构：把耦合彻底拆开
整套系统的骨架我按四层来分，从上到下依次是数据层、元数据层、计算层、渲染层。数据层就是那张规整好的暴露表，一行一个观测，列是变量，不承担任何业务逻辑。元数据层是一组字典表，描述"每个变量是什么意思、怎么展示"。计算层接收数据 + 规格 + 字典，输出一张纯粹的数值长表。渲染层接收这张长表，输出成品文件。层与层之间只通过明确的数据结构通信，谁都不许偷偷读对方的全局变量。
这个分层最直接的好处是可测试。计算层可以脱离渲染层单独测，喂假数据进去比对数值；渲染层可以脱离真实数据单独测，喂一张手搓的长表进去比对格式。两层一起测的时候，出问题也能立刻定位是数值错还是排版错。我在实际项目里最深的体会是：一张表数字不对，九成是分组或者权重的问题；一张表格式不对，九成是因子水平或者小数位的问题。分层之后这两类 bug 各有各的归属，排查时间至少砍一半。
2.1 目录结构怎么摆
包内目录我按职责切，一个文件只干一件事：
GlobalDietaryR/ ├── R/ │ ├── spec-read.R # 读 YAML 规格 + 校验 │ ├── dict-lookup.R # 字典查询、因子水平还原 │ ├── compute-core.R # 加权统计量原子函数 │ ├── compute-table.R # 单表计算主流程 │ ├── render-long.R # 长表转宽表 │ ├── render-fmt.R # 数字格式化 │ ├── render-docx.R # Word 输出 │ └── render-xlsx.R # Excel 输出 ├── inst/ │ ├── specs/ # 每张表一个 YAML │ └── dict/ # 变量字典、水平字典 └── tests/ └── testthat/这个结构里最关键的是inst/specs/和inst/dict/两个目录。它们属于"随包分发的数据"，不是代码，但版本必须和代码一起走。我曾经踩过一个坑：规格文件放在项目工作目录里，某个同事为了跑自己的分析改了一行没提交，结果别人拉代码之后表格全变了但代码没变，查了半天。放进inst/跟着包版本走，这类问题直接消失。
2.2 为什么选配置驱动而不是函数堆叠
备选方案有两个。方案 A 是每个表写一个函数，table_exposure_overall()、table_exposure_by_sex()、table_exposure_by_age()，各自封装完整逻辑。方案 B 是配置驱动，一张表一个 YAML。方案 A 写起来快，读起来也直观，问题是函数数量会随着维度组合爆炸——行变量 5 种、列变量 4 种，理论上是 20 个函数，实际还得乘上统计量组合。
方案 B 的代价是要额外维护一套规格语法和校验逻辑，前期投入大概两三天。但它的好处是表的差异被压缩成数据而不是代码。两张只在列变量上不同的表，在配置里就是一行之差，在代码里就是两个函数。更要紧的是，配置能被非程序员读懂。一段 YAML 摆在面前，"这张表按性别和年龄组分列，算加权均值和标准误，保留一位小数"，做流行病学的同事扫一眼就知道对不对，不用等你解释代码。
2.3 一个容易被低估的设计：中间长表
计算层和渲染层之间，我坚持用一张长表做接口，而不是直接吐宽表。长表的每一行是"某个行维度 × 某个列维度 × 某个统计量"的一个格子，字段固定为row_id, row_label, col_id, col_label, stat, value, digits。这个设计最初是为了省事，后来发现它带来三个意外好处。
第一，调试直观。数字对不上时，直接看待输出的长表，一眼能看出是某个格子的值有问题，还是整行整列丢了。第二，格式统一。所有数字在长表阶段都是数值型，只带一个digits标记，格式化只发生在最后一步，绝不会出现"半路被转成字符串然后排不了序"的经典事故。第三，输出解耦。同一个长表可以渲染成 Word、Excel、Markdown，甚至转成 HTML，渲染器只负责摆位置，不碰数值。这个接口设计好了之后，我换过一次输出库，从头到尾没改计算层一行代码。
3. 元数据字典：整套系统的地基
字典这个东西在演示阶段特别容易糊弄，随便写个 data.frame 就行，但真正上量之后，它是唯一能保证"表头永远说人话"的部件。一套完整的变量字典至少要有六个字段：变量内部编码、展示标签、类型、单位、默认小数位、缺失值约定。类型决定了这个变量能放在行还是列还是度量位置，单位决定了要不要在表头里加括号，小数位决定了默认精度。
这里有个实战经验值得强调：字典必须是唯一的真相来源。也就是说，变量在表格里显示成什么样子，只能由字典决定，绝不能在渲染层再写一次映射。我踩过的坑是：字典里把性别标签写成"男/女"，某张表的 YAML 里为了好看又写了一组"男性/女性"，结果同一份报告里两张表的表头不一致。修复方式很粗暴但有效——规格文件只允许写变量编码，标签一律从字典取，渲染层如果查不到就报错，不允许兜底。
3.1 变量字典表怎么建
字典我用 tibble 直接写在包里，好处是随代码走、能被测试覆盖。结构大致如下：
dict_vars <- tibble::tribble( ~var_code, ~var_label, ~var_type, ~unit, ~digits, ~miss_code, "food_grp", "食物组", "cat", NA, NA, NA, "sex", "性别", "cat", NA, NA, NA, "age_band", "年龄组", "cat", NA, NA, NA, "edu_level", "教育水平", "cat", NA, NA, NA, "energy_kcal", "能量摄入", "num", "kcal", 1, -999, "protein_g", "蛋白质摄入", "num", "g", 2, -999, "w_total", "总权重", "weight", NA, NA, NA )var_type只允许四个取值：cat表示分类维度，可以放行或列；num表示数值度量，只能算统计量；weight表示权重；id表示标识列，不进表。这个约束看起来死板，但正是它让规格校验变得简单——读到规格里写food_grp放在 measure 位置，直接报错说"分类变量不能做度量"，而不是跑完之后发现表格里全是 NA。
miss_code这一列我特意放在字典里而不是硬编码。原因是不同来源的 GDD 数据缺失码不统一，有的是 -999，有的是 -9，还有的是 9999。把这些约定收进字典，计算层就能统一处理，不用在业务代码里到处判断。
3.2 分类水平的顺序
分类变量的顺序是表格质量的分水岭。默认按字母序或者按出现顺序排，结果往往是"18-29"排在"30-44"后面，"小学"排在"高中"前面，一张表看起来毫无章法。正确做法是给每个分类变量单独维护一张水平字典，明确写出水平和数值顺序：
dict_levels <- tibble::tribble( ~var_code, ~level_code, ~level_label, ~level_order, "age_band", "18-29", "18-29 岁", 1, "age_band", "30-44", "30-44 岁", 2, "age_band", "45-59", "45-59 岁", 3, "age_band", "60+", "60 岁及以上", 4, "sex", "M", "男", 1, "sex", "F", "女", 2 )有了这张表，计算层在分组之前就把对应列转成factor(x, levels = level_code[order(level_order)], labels = level_label)，顺序问题一次性根治。更重要的是，factor加.drop = FALSE的分组能保住空组——某个年龄组在某个食物组下一个人都没有的时候，表格里会老老实实出现一行 NA，而不是悄悄消失让你以为数据齐全。这在分层分析里极其关键，缺行比错值更难发现。
3.3 单位、精度与缺失语义
单位和小数位看似琐碎，实际是审稿意见的高发区。我的处理方式是把它们绑定在变量上而不是表上：能量一律保留一位小数并标kcal，蛋白质保留两位并标g，比例类指标保留三位且不标单位，样本量作为计数一律取整不加小数。这样设计之后，同一张表里不同指标用不同精度是完全自动的，不用手调。
缺失语义需要特别强调。表格里出现的"空"至少有三种含义：真实为零、缺失、不适用。这三者在读者眼里必须能区分开。我的约定是：真实为零显示0，缺失显示—，不适用显示空白。这个约定写进渲染层的格式化函数，全系统统一，绝不各表各写。顺带一提，Word 表格里用—（em dash）比用-或者NA要专业得多，但要注意字体支持，中文环境建议统一用宋体或等线，避免破折号变成方框。
4. 表格规格怎么写才不容易出错
一张表的规格文件，内容无非是"标题、数据源、行变量、列变量、统计量、精度覆盖、脚注"。但写成什么格式、允许哪些简写、校验做到什么程度，直接决定这套系统是两天就被放弃还是一直用下去。我的选择是 YAML，因为它支持注释、层级清晰、非程序员也敢改。一张典型的描述性统计表规格长这样：
table_id: T01 title: 膳食摄入描述性统计 data_source: exposure_core row_vars: - var: food_grp col_vars: - var: sex - var: age_band measure: - stat: mean weight: w_total - stat: se - stat: n digits_override: n: 0 footnote: "均值为加权均值；标准误基于有效样本量计算。"这段配置读起来基本就是自然语言：行按食物组分，列交叉性别和年龄组，算加权均值、标准误和样本量，样本量强制取整。计算引擎拿到之后，只需要三步：把行变量和列变量拼成分组键，按度量清单逐个算，把结果整理成长表。
4.1 行列交叉与多层表头的表达
多层表头是 Word 输出里最麻烦的一块。规格里不需要描述表头结构，只需要声明列变量的先后顺序——sex在前age_band在后，渲染层就自动生成"性别"合并单元格在上、"年龄组"分列在下的两层表头。这个约定让规格保持极简，代价是表头结构固定为"按列变量顺序从外到内"。实践中这个约束几乎不碍事，因为绝大多数表格的表头就是维度从粗到细。
真正需要人工干预的情况只有两种：一是某些列需要合并显示（比如把两个年龄组合并成一列），二是需要插入"合计"列。前者我建议改规格里的水平映射，用一个新的虚拟水平代表合并，避免在渲染层做特殊处理；后者用add_total: true开关，计算层在分组时额外跑一遍不带该维度的聚合，打上total标记，渲染层把它排到最右。
4.2 规格校验：宁可早报错，别等跑完
所有省下来的调试时间，都在校验上赚回来。我在spec-read.R里做了四层校验，任何一层不过直接停，报错信息必须带上是哪张表哪个字段哪里错。
| 校验层级 | 检查内容 | 不通过时的典型报错 |
|---|---|---|
| 结构层 | 必填字段是否齐全 | T01: 缺少 measure 字段 |
| 引用层 | 变量编码是否在字典中 | T01: 未知变量 food_group（是否为 food_grp？） |
| 类型层 | 变量类型是否与位置匹配 | T01: sex 是分类变量，不能作为 measure |
| 语义层 | 统计量与权重是否配套 | T01: stat=se 需要显式指定 weight |
引用层的报错我特意加了"是否为 food_grp"这种提示，用的是字符串距离匹配。这个小心思看起来微不足道，实际能省掉大量"拼错了变量名然后对着空表发呆"的时间。语义层的检查最容易被跳过，但它拦住的是最危险的一类错误：算出了标准误但没指定权重，结果整个置信区间是错的，而表格看起来完全正常。
4.3 统计量清单的可扩展写法
度量清单用列表而不是固定字段，是为了让新增统计量不影响老规格。目前内置的统计量有：mean（加权均值）、se（标准误）、n（有效样本量）、p0（零消费比例）、mean_consumer（消费者均值）、p50（加权中位数）。这个设计允许以后按需加，比如加一个cv（变异系数），只要在计算层注册一个函数、在字典里加个默认精度，老规格一行都不用改。
需要提醒的是，不要把统计量清单变成万能插槽。我见过有人往这里塞了二十个指标，结果一张表 8 列乘 6 个统计量，横着排不下，最后还得手工删。合理做法是一张表只回答一个问题，描述性统计和分布特征分开两张表，读者不用在 48 个数字里找自己想看的那个。
5. 计算引擎：加权统计量怎么算才站得住
膳食暴露数据的统计计算有两个绕不开的特性：一是几乎必须加权，二是零消费比例极高。这两个特性决定了不能简单套mean()和sd()。加权均值好理解，就是Σwx / Σw。麻烦的是标准误，很多人直接拿加权均值除以样本量的平方根，这是错的，会系统性低估方差。
正确的做法分两步。先算加权方差，用频率权重下的无偏估计形式：
s²_w = Σ w_i (x_i - x̄_w)² / (Σw_i - Σw_i² / Σw_i)分母为什么不是Σw_i - 1？因为权重之和通常远大于 1（比如几万人的调查权重量级），用Σw_i - 1会让分母几乎等于Σw_i，方差被严重低估。真正的自由度扣减量应该是Σw_i² / Σw_i，物理含义是"权重的集中程度"，权重越均匀这个扣减越接近 1。
然后算有效样本量，再算标准误：
n_eff = (Σw_i)² / Σw_i² SE = s_w / sqrt(n_eff)有效样本量的含义是"这批加权数据折合多少个等权观测"。如果权重完全相等，n_eff就等于真实样本量；权重越不均，n_eff越小，标准误越大——这正好反映了加权带来的精度损失。这套计算跟主流调查分析软件的口径一致，可以直接对标。
写成 R 函数就是这样一个原子操作，它必须能安全处理小样本和全缺失：
wmean <- function(x, w) { ok <- !is.na(x) & !is.na(w) & w > 0 x <- x[ok]; w <- w[ok] n <- length(x) if (n < 2L) { return(c(mean = if (n == 1L) x else NA_real_, se = NA_real_, n = n)) } sw <- sum(w) m <- sum(w * x) / sw v <- sum(w * (x - m)^2) / (sw - sum(w^2) / sw) neff <- sw^2 / sum(w^2) c(mean = m, se = sqrt(v / neff), n = n) }这段代码里w > 0这个条件看着多余，实际很有必要。GDD 数据里偶尔出现权重为 0 或负数的记录，通常来自插补失败或者合并逻辑出错。让它静默通过会污染均值，让它报错会中断整批任务，折中方案是直接剔除并计数，在最终输出的日志里提示"T01: 剔除 12 条非正权重记录"。这个日志我建议一定要留，因为 12 条不算多，但如果你不知道它被剔了，回头核对样本量时会出现对不上的情况。
5.1 零膨胀数据的正确姿势
食物组数据有个特点：某一类食物可能有一大半人根本不吃。这时候均值会被大量零拉低，读者看到"平均摄入 3.2 克"完全无法判断是"人人吃一点"还是"少数人吃很多、多数人不吃"。这两种情况的政策含义完全相反。
解法是在表格里同时给三个数字：全体均值、零消费比例、消费者均值。消费者均值只在x > 0的子集上做加权平均，标准误同样只用这个子集算。计算层实现起来不复杂，加一个mean_consumer统计量，内部先做子集筛选再调wmean。但有个细节必须注意：消费者子集的样本量可能很小，某些交叉格子下只有个位数，这时候算出来的均值毫无意义。我的处理是设一个展示阈值，子集有效样本量小于 30 时，数值照算但打上标记，渲染层显示为*加脚注说明。这样既不会丢信息，也不会让读者误信一个基于 5 个人的平均数。
5.2 分层汇总与合计行
交叉表里"合计"行的算法有两种，选错了会出现"合计不等于分层之和"的诡异现象，然后你要花两小时解释为什么。第一种是重新聚合：忽略列维度，把整个子集重新按权重算一遍。第二种是分层结果相加：把各列的均值按某种权重加权平均。这两者在数学上只有当各层权重比例恰好一致时才相等，实际几乎永远不相等。
正确做法是第一种，永远重新聚合。因为合计行的语义是"这批人的整体均值"，就应该用整体数据算。这也解释了为什么合计不等于分层简单平均——那是权重的正常体现，不是 bug。把这个道理写进表格脚注，能省掉无数次重复解释。实现上，我在计算主流程里对每个维度做一次drop再聚合，结果打上is_total = TRUE，渲染时统一放到最后，并且用一个视觉分隔（比如加粗）和普通分层区分开。
5.3 大数据下的性能取舍
GDD 的完整暴露表横向几百列、纵向几十万行，用 dplyr 直接跑交叉表，如果列变量有三层、每层五六个水平，分组数轻松上千，跑一张表几十秒很正常，跑十张表就是几分钟。这个速度在交互调试时很难受。
我的优化顺序是这样的：先看是不是分组太多，能不能用across()一次性算完多个统计量，避免重复分组；再看是不是因子水平太多导致.drop = FALSE产生了大量空组，空组在聚合阶段是纯开销；最后才考虑换data.table。实测下来，前两步能解决 80% 的性能问题，真正需要换引擎的场景不多。如果确实要换，建议只把聚合那一段换成data.table，其余保持 tidyverse 风格，不要整个包混用两套语法，维护成本会翻倍。
6. 渲染层：一次计算，多种输出
渲染层是整个系统里最没有技术含量、但最容易出细节事故的一层。它的输入永远是那张长表，输出是给人看的成品。核心动作只有三个：长表转宽表、数字格式化、套模板输出。听起来简单，但每一步都有坑。
长表转宽表用tidyr::pivot_wider，关键是names_from要拼一个复合列名，比如sex_age_band_stat，转完之后列顺序靠names_sort = FALSE加因子水平控制。这里有个坑：如果长表里某个格子缺失（比如某个交叉组合下样本量为零，计算层返回了 NA 行但没有实际生成），pivot_wider出来的宽表会少列，后续按位置取列全部错位。解决办法是转宽之前先complete()一遍所有行标签 × 列标签 × 统计量的组合，缺的填 NA，保证宽表的列数永远是行数 × 统计量数的确定值。
6.1 数字格式化：绝不能混着来
格式化函数必须是纯函数，输入数值和精度，输出字符串，中间不读任何全局状态：
fmt_num <- function(x, digits, na_text = "—") { out <- ifelse( is.na(x), na_text, formatC(x, format = "f", digits = digits, big.mark = ",") ) out }有个细节值得单独说：formatC的big.mark在中文文档里用逗号没问题，但如果你要投英文期刊，千分位分隔符可能要求用窄空格或者干脆不要。这属于输出层的配置，放在渲染参数里，别写死在函数默认值里。另一个细节是负零：formatC(-0.0001, format = "f", digits = 2)会输出-0.00，看着很怪。稳妥做法是格式化之前先把绝对值小于半个最小精度的数归零。
百分比类指标我建议在计算层就转成 0 到 100 的数值，而不是保留 0 到 1 的小数再在渲染层乘 100。原因很简单：一旦渲染层开始做算术，你就没法保证它和表格脚注里写的一致。所有算术留在计算层，渲染层只做展示，这条规矩能挡掉一大堆"表里写 12.3%，正文写 0.123"的低级错误。
6.2 Word 和 Excel 各自的脾气
Word 输出我用flextable，主要是多层表头的合并单元格支持得比较顺：
ft <- flextable::flextable(wide_body) |> flextable::set_header_labels(values = header_map) |> flextable::merge_at(j = 2:4, part = "header") |> flextable::bold(part = "header") |> flextable::autofit()merge_at的列索引要小心，它是相对wide_body的列位置算的，多层表头合并时容易差一位。我的做法是先打印names(wide_body)确认，再写合并参数，别凭记忆。另外中文字体一定要显式设置，默认字体在部分环境里中文会退化成宋体加粗，看着很别扭。
Excel 输出用openxlsx，优势是能保留数值类型——这对下游同事很重要，他们可能要拿这张表继续做图。所以 Excel 输出里我不用格式化后的字符串，而是写数值加自定义numFmt，让 Excel 自己按格式显示。这样单元格里存的还是数字，复制出去不失真。代价是openxlsx的数字格式字符串语法要单独学一遍，#,##0.0这种写法跟 R 的formatC不通用，得分开维护两套映射。
6.3 版式与可读性
表格做出来能看，和表格做出来好看，中间差着几个小时的细节。三个我每次都会调的地方：一是列宽，Word 里默认等宽会让标签列挤成一团，按内容长度分配更合理；二是行间距，多层表头下面的数据行要留一点呼吸感；三是脚注位置，必须紧贴表格下方，不能飘到页脚。
这些都属于渲染参数，我统一收在一个style列表里，规格文件可以覆盖，也可以不写用默认。默认值是怎么定的？就是拿一张典型表反复打印、反复调到顺眼为止，然后固化成默认。这件事没有技术含量，但值得做一次，因为后面所有表都受益。
7. 完整实操：从零跑通一张表
下面把前面所有零件串起来，走一遍完整流程。为了能复现，数据用模拟生成，不依赖任何真实数据源。
7.1 环境与依赖
# 核心依赖 install.packages(c( "dplyr", "tidyr", "tibble", "yaml", "flextable", "officer", "openxlsx", "testthat" ))officer是flextable的底层，导出 docx 必须装。yaml用来读规格，testthat用来做回归测试。整套依赖很轻，没有需要编译的重型包，这在给同事部署时很重要——装得越少，环境问题越少。
7.2 造一份模拟数据
模拟数据要尽量贴近真实结构，特别是要包含零消费、负权重、缺失值这三类边界情况，否则测不出问题：
set.seed(20240501) n <- 2000 demo <- tibble::tibble( id = seq_len(n), sex = sample(c("M", "F"), n, TRUE), age_band = sample(c("18-29", "30-44", "45-59", "60+"), n, TRUE), food_grp = sample(c("谷物", "蔬菜", "水果", "乳类", "肉类"), n, TRUE), intake = round(pmax(0, rgamma(n, shape = 0.8, scale = 60)), 2), w_total = round(runif(n, 200, 5000), 1), energy_kcal = round(rnorm(n, 1800, 350), 1) ) # 人为制造零消费：约三成记录摄入为 0 zero_idx <- sample(n, size = round(n * 0.3)) demo$intake[zero_idx] <- 0 # 人为制造少量非正权重，检验剔除逻辑 demo$w_total[sample(n, 12)] <- 0rgamma(shape = 0.8)这个参数是特意选的，形状参数小于 1 会让分布大量集中在接近零的位置，更接近真实膳食数据的右偏形态。用正态分布造出来的数据太"规矩"，测不出零膨胀相关的 bug。
7.3 写规格文件
table_id: T01 title: 膳食摄入描述性统计（模拟数据） data_source: demo row_vars: - var: food_grp col_vars: - var: sex - var: age_band measure: - stat: mean weight: w_total - stat: p0 weight: w_total - stat: mean_consumer weight: w_total - stat: n add_total: true digits_override: n: 0 p0: 3四个统计量分别是加权均值、零消费比例、消费者加权均值、有效样本量。加上合计行，列数是2 (性别) × 4 (年龄组) + 1 (合计) = 9列，乘 4 个统计量，一共 36 个数字。这个密度对一张表来说刚好，再多就得考虑拆表了。
7.4 跑通并检查
spec <- read_spec("inst/specs/T01.yml") dict <- load_dict() result <- compute_table(demo, spec, dict) long <- tidyr::pivot_longer( result, cols = c(mean, p0, mean_consumer, n), names_to = "stat", values_to = "value" ) wide <- to_wide(long, spec) print(wide)跑完之后必须做三项检查，缺一不可。第一，合计行对不对：把sex和age_band都去掉重新算一遍整体均值，跟合计行逐个比对，误差应该为零。第二，样本量加总对不对：各分层n相加，应该等于合计n减去被剔除的非正权重记录数，这个差额要能解释。第三，边界值合不合理：零消费比例应该落在 0 到 1 之间，消费者均值必须大于等于全体均值，如果有格子出现反向，基本可以断定是子集筛选写反了。
这三项检查建议写成函数，每次出表自动跑一遍，跑完打印一行T01 检查通过。看起来啰嗦，但这是唯一能在无人值守的情况下拦住错误的办法。
8. 常见问题与排查实录
这套系统跑了大半年，遇到的问题基本集中在几个固定位置，整理成速查表之后，新人上手也能自己解决大半。
| 现象 | 可能原因 | 排查动作 | 处理方式 |
|---|---|---|---|
| 表格整体为空 | 分组键全为 NA，或.drop = FALSE与因子不匹配 | 打印分组前数据的str() | 检查因子水平是否与字典一致 |
| 某些行消失 | 因子水平丢失，group_by走了默认drop = TRUE | 检查levels()长度 | 统一factor(levels = ...)加.drop = FALSE |
| 合计不等于分层之和 | 权重比例在层间不同（正常） | 用整体数据重算核对 | 脚注说明，不要"修正" |
| 标准误异常小 | 权重未传入，走了等权公式 | 检查weight字段是否拼错 | 语义校验层拦截 |
| 小数点位数不一致 | 数值与字符串被混在同一列 | 查看长表中value的类型 | 全流程只留数值，最后一步格式化 |
| 行顺序乱 | 排序发生在转宽之后 | 检查arrange位置 | 在长表阶段按row_id排好 |
| Word 表头错位 | merge_at列索引差一位 | 打印names(wide_body) | 按实际列位置重写合并参数 |
| 消费者均值为负 | 子集条件写成x != 0带入了负值 | 检查子集表达式 | 改为x > 0 |
8.1 数字对不上的排查顺序
"这张表的均值跟上次不一样"是最常见的求助。我的排查顺序是固定的四步，按代价从低到高排。第一步，比对样本量，如果两次的n不同，问题在筛选或者权重剔重；第二步，比对权重变量，如果n相同但均值差一点点，多半是权重换了；第三步，比对数据版本，GDD 数据库会迭代，隔了几周的两次运行数据本身可能就变了；第四步，比对代码版本，翻 git log 看计算层有没有改动。
绝大多数情况下第二步就查出来了——有人为了测试方便，在规格里把weight注释掉了，测完忘了改回来。这种事故一旦发生一次，你就会明白为什么我坚持在语义层做"stat=se必须显式指定weight"的强制校验。防呆设计永远比事后排查便宜。
8.2 空组和空表的区别
空组是某个交叉组合下没有观测，空表是整张表一个数字都没有。这两个问题经常被混为一谈，但原因完全不同。空表几乎总是配置错误：变量名拼错、数据源指定错、或者分组键里有全 NA 的列。空组则是数据分布问题，某些细分维度下确实没人，属于正常现象，只需要保证它显示为 NA 而不是消失。
判断方法很直接：打印分组之后的行数。如果行数是 0，是空表；如果行数正常但某些格子是 NA，是空组。前者去查配置，后者去查数据。这个二分法能省掉很多无效排查。
8.3 排查技巧：留一份"黄金样例"
我在每个项目的tests/fixtures/下都放一份手工核对过的数据和一个对应的期望输出，规模很小，大概 200 行，但从头到尾人工算过。每次改计算层代码，先跑这份样例，输出跟期望值逐个 cell 比对。这个做法在重构时价值巨大——有几次我优化性能改了聚合写法，样例立刻报出某一个格子的标准误差了 0.002，定位下去是浮点累加顺序导致的，虽然不影响结论，但说明确实动到了不该动的地方。
这份黄金样例的维护成本不高，但要求一个人肉对结果的过程。建议一次做对，之后所有改动都拿它当闸门。
9. 回归测试与版本可复现
表格这种产出物有个特点：它没有"编译失败"这种硬信号，错了也能照常输出，只是数字不对。所以测试不能只测"跑不跑得通"，必须测"跑出来的东西跟上次一不一样"。我用的是快照测试，思路很简单：第一次跑的时候把结果存成文件，之后每次跑都跟这个文件比对，不一致就停下来让人确认。
test_that("T01 结构与基线一致", { out <- build_table("T01", fixture_data) expect_snapshot(out) })快照测试的坑在于"预期内的变化"和"意外的变化"分不清。我的做法是严格区分：改计算逻辑导致的变化，必须人工检视后更新快照，并在提交信息里写清楚改了什么；改格式导致的变化，尽量放在另一组测试里，单独更新，不要和数值变化的快照混在一起。混在一起的结果就是快照文件变得庞大无比，一次更新几百行 diff，没人会认真看。
9.1 版本记录该记什么
表格类项目的变更记录，光记"修复 bug"没有意义，必须记到口径级别。我要求每条记录至少包含三项：影响了哪几张表、改了什么口径、对已有数字的影响方向。比如"T01/T02：标准误计算从等权改为加权，所有标准误数值增大，均值不变"。这样的记录在半年后回头看，能立刻判断某份旧报告的数字还能不能直接引用。
顺带说一个实践细节：把表的table_id和包的版本号绑在一起，输出的文件名带上版本，比如T01_v0.3.2.docx。看起来土，但这是唯一能让你在硬盘上堆积了三十个同名文件时还能分清新旧的办法。
9.2 我个人的几点做法
第一，先写校验再写计算。这套系统的校验代码行数大概和计算代码相当，甚至更多。一开始觉得啰嗦，用久了发现它拦住的问题远比它占的篇幅值钱。
第二，规格文件永远不写数值逻辑。我见过有人在 YAML 里写filter: intake > 0，看着很方便，实际上打开了潘多拉魔盒——配置里开始出现任意表达式，校验做不了，复用也做不了。所有筛选逻辑要么进字典作为固定规则，要么进计算层的命名选项。
第三，给每张表配一句"这张表回答什么问题"。写在规格文件的note字段里，不输出到成品。这句话在纠结要不要加某一列的时候特别好用——加不进去，说明这张表的问题已经变了，该拆表了。
这套东西搭起来大概花了两三天，之后每加一张表十几分钟，改口径只改一处，出错的概率肉眼可见地下降。真正让我觉得值的，不是省下的那些时间，而是半年后有人问"这个数字怎么来的"，我能直接翻出规格文件、计算函数和快照记录，把整条链路摆在对方面前。
