📚 课程目录第3章文档化核心概念

3. 文档化核心概念

在精算模型的全生命周期中，文档化不是“交付前补写的说明材料”，而是模型可信度的一部分。独立验证（Independent Validation）能否高效开展，很大程度上取决于文档是否把模型的设计意图、假设边界、数据来源、计算逻辑和验证证据表达清楚。本节从目的、受众、类型与行业标准四个维度，建立文档化的核心概念框架。

一、文档化的根本目的：让模型可被“独立复现”

精算模型文档化的目的可以归纳为四个层次，它们层层递进，共同支撑模型治理：

可理解：让未参与建模的人理解模型解决什么问题、边界在哪里、关键假设是什么。
可复现：使验证人员能够依据文档独立重建计算路径，得到可解释、可对比的结果。
可审计：为内外部审计、监管检查提供完整的决策链条与变更痕迹。
可传承：降低人员流动带来的知识断层风险，使模型在多年后仍可维护和迭代。

核心判断标准：如果一名具备精算背景但未参与建模的验证人员，仅凭文档和可获取的数据，能否在合理时间内复现模型的关键输出？若答案是否定的，文档化就是不充分的。

二、受众分层：同一模型，不同写法

文档化的常见误区是“一份文档打天下”。实际上，不同受众关注点差异极大，文档需要分层设计。下表给出典型受众与关注重点的对应关系：

受众	核心关注	文档深度	典型问题
模型使用者（业务精算）	如何输入、如何解读输出、参数含义	操作层	这个参数填什么？结果怎么用？
独立验证人员	假设依据、公式推导、数据流、可复现性	技术层	这个假设从哪来？公式如何实现？
模型开发者/维护者	代码结构、版本变更、依赖关系	实现层	改这里会影响哪些模块？
审计与监管	治理流程、审批记录、合规证据	治理层	谁批准的？依据什么标准？
管理层	模型用途、局限性、关键风险	摘要层	这个模型能支撑什么决策？

受众分层并不意味着要写五套完全独立的文档，而是通过“主文档 + 分层附录/摘要”的方式组织，确保每类读者都能快速定位所需信息。

三、文档类型：技术文档、用户文档与验证文档

在精算模型治理实践中，通常将文档划分为三大类型，它们各有侧重又相互引用：

技术文档（Technical Documentation）：描述模型的方法论、假设、公式、数据来源、参数校准与实现逻辑。它是验证工作的主要依据，强调“为什么这样建模”和“如何计算”。
用户文档（User Documentation）：面向模型使用者，说明操作步骤、输入输出格式、参数设置、运行环境与常见问题。强调“怎么用”和“结果怎么读”。
验证文档（Validation Documentation）：记录独立验证的范围、方法、测试用例、发现的问题、结论与整改跟踪。强调“验证了什么”“证据是什么”“结论是否可靠”。

三类文档不是孤立的。技术文档中的假设编号应能被验证文档直接引用；用户文档中的参数说明应与技术文档中的参数定义保持一致。建立交叉引用编号体系，是提升文档可用性的低成本高收益做法。

四、行业标准与规范框架

精算模型文档化并非无章可循，多个专业组织和监管框架提供了参考标准：

SOA/CAS 模型治理实践：强调模型文档应覆盖目的、范围、假设、数据、方法、验证、局限性与变更记录。
北美精算师协会 ASOP 系列：如 ASOP 56（模型治理）对模型文档、验证与变更管理提出职业要求。
监管指引：如保险监管机构对内部模型（如偿付能力二代内部模型）的文档化要求，通常强调可审计性与可复现性。
通用软件与数据治理标准：如版本控制规范、数据字典、元数据管理，可借鉴到模型文档体系中。

这些标准的共同指向是：文档必须结构化、可追溯、可维护，而不是一次性说明。

五、场景示例：一份验证文档的目录结构

以下是一个精算模型独立验证文档的典型目录结构，可作为实际工作的起点：

1. 验证概述
   1.1 验证目的与范围
   1.2 验证依据（技术文档版本、监管要求）
   1.3 验证团队与独立性声明
2. 模型理解
   2.1 模型用途与业务背景
   2.2 关键假设与数据来源
   2.3 计算逻辑与实现路径
3. 验证方法与测试设计
   3.1 概念性验证（公式、假设合理性）
   3.2 代码实现验证（单元测试、边界测试）
   3.3 结果验证（基准对比、敏感性分析）
4. 验证发现与问题跟踪
   4.1 问题清单与严重程度
   4.2 整改建议与责任人
5. 验证结论
   5.1 模型是否适用于预期用途
   5.2 局限性与使用限制
6. 附录
   6.1 测试用例与数据
   6.2 交叉引用表（假设编号、公式编号）

六、常见误区与复盘要点

误区一：文档写完就归档，不再更新。模型一旦变更，文档不同步，验证依据即失效。
误区二：只写“做了什么”，不写“为什么这样做”。验证人员无法判断假设合理性。
误区三：技术文档与用户文档混在一起，导致验证人员被操作细节干扰，使用者被公式淹没。
误区四：验证文档只写结论，不写测试过程和证据，无法支撑独立复核。

复盘时可以用三个问题自查：文档是否能让验证人员独立复现？假设是否有明确来源和编号？变更是否有记录并触发文档更新？这三个问题覆盖了文档化最核心的质量维度。

文档化的本质，是把模型的“隐性知识”转化为“显性证据”。目的决定写什么，受众决定怎么写，类型决定写多深，标准决定写到什么程度才算合格。理解这四个维度的关系，是后续开展独立验证工作的前提。