选举2029：数据模型

数据模型（和视图模型）及其使用方式

我考虑在文章标题中使用"架构"这个词，但对于这个网站的规模来说感觉太夸张了。虽然我可以证明其合理性，但每次使用这个术语都会让我感到不适。不过这篇文章基本上会描述我如何在选举网站中处理数据，以及这些数据是什么。

在许多系统中，数据有多种用途，系统需要考虑到所有这些用途。对于我的选举网站，我只需要担心两种用途：

• 网站本身，纯粹是只读的
• 维护数据的工具，是读写式的

工具只由我在家中运行 - 所以我无需担心多个并发写入的并发问题。但我需要确保网站在我写入过程中检查更新时始终读取一致的数据视图 - 我将在后续文章中介绍这一点。

本文仅涉及数据的内部表示，在这里我基本上控制所有内容。大部分网站数据来自外部数据源，我将在后面的单独文章中介绍如何处理这些数据源。

网站如何使用数据

网站的代码涉及以下项目（暂时忽略测试项目）。此列表按依赖顺序排列：列表中的任何项目可能依赖于较早的项目，但不依赖于较晚的项目。

• Election2029.Common：实用工具代码
• Election2029.Models：核心数据模型，全部是不可变的（主要是密封记录）
• Election2029.Storage：纯粹关于存储数据的代码，无论是在文件系统中还是在Firestore中，但具有通用接口
• Election2029.ViewModels：模型的不可变包装器，用于简化视图代码（不依赖存储）
• Election2029.Web：ASP.NET Core代码，包含Razor页面等

Razor页面通常没有代码隐藏，而是注入相应的视图模型，这些模型在简单的Razor语法中呈现为HTML。目的是保持视图代码非常简单 - 我可以接受在这里或那里有一个循环，但大部分视图应该是HTML而不是C#。除此之外，将任何"真正"的逻辑放在视图模型中使它们更容易测试，这就是我拥有全面测试套件并希望拥有单元测试的方式。

每个页面都注入"该视图的世界状态的当前视图模型"。这个视图模型会重复使用，直到基础数据发生变化，这种情况相对较少。但它确实会变化，这意味着视图模型不能作为单例注入。我将在后续文章中重新讨论数据重新加载机制。页面渲染的结果也会被缓存，但只缓存10秒，以在数据新鲜度和过度工作重复之间取得平衡。理论上我可以说"缓存直到我们有新的视图模型"，但这可能比值得的更复杂。

工具如何使用数据

工具的代码涉及以下项目，以及网站的Election2029.Common、Election2029.Models、Election2029.Storage。

• Election2029.Tools.Common：所有工具的实用工具代码（因为除了我在这里讨论的"数据管理器"之外还有一些工具）
• Election2029.Tools.DemocracyClub.Models：Democracy Club数据的模型 - 我从中导入的外部源
• Election2029.Tools.Parliament.Members：议会成员API的模型和客户端代码 - 另一个外部源
• Election2029.Tools.DataManager：用于各种数据管理任务的命令行工具，包括添加投票、从外部数据源更新数据等

重要的是，这完全不使用Election2029.ViewModels。在我开始写这篇文章之前，DataManager项目对ViewModels项目有依赖关系，这让我有点紧张…但试探性地删除它后，我发现只有几个引用，我们很容易就修复了。（可以说，DataManager能够执行一些简单的文本格式化仍然有用，例如"格式化此投票的实地调查日期" - 我将来可能会将其移到模型项目中。）

模型

模型本身不仅仅是记录定义，尽管我在这里展示的就是这些。我认为数据模型具有以下附加成员是合理的：

• 简单的便利计算。例如，通过汇总每个政党的投票数来计算单个选区结果的总投票数。
• 基于其余数据的查找。例如，“投影集"包含按选区的投影结果列表；我们有一个从选区到"该选区结果"的查找。

这些可以放在视图模型中，但它们通常被多个视图模型使用，因此将它们放在模型中是有意义的。

模型被分组在一起。有一个ElectionCoreContext包含不相互引用的独立模型，然后是ElectionContext包含所有内容 - 它有一个ElectionCoreContext，然后是可以引用核心上下文中的模型但不能引用其他非核心模型的其他模型。这意味着创建ElectionContext包括：

• 独立创建核心上下文的每个元素
• 从这些元素创建核心上下文
• 创建每个非核心元素，以核心上下文作为参考
• 从核心上下文和非核心元素创建整体上下文

这使得数据模型比元素不能引用其他模型时更容易使用 - 例如，这意味着PartyChange可以引用Candidate和Party模型，而不仅仅包含候选人的ID和旧/新政党ID。核心/非核心分割意味着所有这一切都可以在没有任何循环依赖的情况下完成。

在下面的所有声明中，我省略了记录实现的任何额外接口，以及记录中的任何代码。

快速术语说明：这里的"上下文"只是我用来表示"世界最新状态"的术语。它与Entity Framework无关，与DDD有界上下文的任何相似之处至少有些巧合。（或者我怀疑你可以将整个ElectionContext视为单个有界上下文 - 系统足够小，一个边界围绕所有内容。我对DDD的了解不足以理解系统与它的契合程度。）

核心模型

ElectionCoreContext具有以下声明：

1
2
3
4
5
6

public sealed record ElectionCoreContext(
    ImmutableList<Constituency> Constituencies,
    ImmutableList<Candidate> Candidates,
    ImmutableList<Party> Parties,
    ImmutableList<ElectoralCommissionParty> ElectoralCommissionParties,
    ImmutableList<DataProvider> DataProviders);

这些元素包括：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

public sealed record Constituency(string Name, string Code, string? Code2023, string HexRQ, ConstituencyLinks Links);
public sealed record ConstituencyLinks(string? WhoCanIVoteFor2024, string? WhoCanIVoteFor2029, int ParliamentId);

public sealed record Candidate(int Id, string Name, int? MySocietyId, int? ParliamentId);

public sealed record Party(
    string Id, string BriefName, string FullName, ImmutableList<string> ElectoralCommisionIds,
    string? ParliamentAbbr, string CssPrefix, ImmutableList<string> ColorsByStrength);

public sealed record ElectoralCommissionParty(string ElectoralCommissionId, string Name);

public sealed record DataProvider(
    string Id, string Name, bool Enabled,
    string DescriptionHtml, string? Link, string? DataDirectory);

关于这些的一些说明：

• 通常我发现，用列表而不是集合或字典来建模记录更容易保持数据一致性…即使集合的顺序在逻辑上无关紧要（例如对于选区），拥有规范顺序非常方便，这样相等性测试更简单，差异易于阅读等。
• ConstituencyLinks可以内联到Constituency中（实际上在存储中就是这样）。这与Candidate如何内联外部数据源的ID不一致。这可能会随时间改变。
• “核心元素不相互引用"的方面在某种程度上被Party具有选举委员会ID列表所污染。理论上我可以增加模型中的"层级"数量，这样Party可以有一个ImmutableList…但事实证明我很少需要引用选举委员会政党。（背景是有大量政党在选举委员会注册。大多数时候我们只需要主要政党，我们不想或不需要区分，例如"绿党"和"苏格兰绿党” - 或者实际上是两个都称为"保守和统一党"的选举委员会政党。）
• DataProvider的DataDirectory部分仅由工具使用…这感觉有点奇怪，但并非特别不合理。
• DataProvider（基本上用于投票和席位投影）有一个Enabled标志，允许我在获得在网站上使用的许可时，从提供者摄取数据而不显示它。

非核心模型

到目前为止，相对简单。完整的ElectionContext相当大：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

public sealed record ElectionContext(
    ElectionCoreContext CoreContext,
    PostcodeMapping PostcodeMapping,
    ImmutableList<ByElection> ByElections,
    ImmutableList<Ballot> Ballots2029,
    ResultSet Results2029,
    ResultSet Results2024,
    ImmutableList<NotionalResult> NotionalResults2019,
    ImmutableList<ProjectionSet> ProjectionSets,
    ImmutableList<Poll> Polls,
    ImmutableList<PartyChange> PartyChanges,
    ImmutableList<CurrentRepresentation> CurrentRepresentation)

这些元素包括：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

public sealed record PostcodeMapping(ImmutableList<OutcodeMapping> OutcodeMappings);
public sealed record OutcodeMapping(string Outcode, ImmutableList<Constituency> Constituencies, ReadOnlyMemory<byte> Map);

public sealed record ByElection(LocalDate Date, Result Result);
public sealed record Result(
    Constituency Constituency, Party WinningParty, ImmutableList<Candidacy>? CandidateResults,
    int? SpoiltBallots, int? RegisteredVoters, Instant IngestionTime, Instant? DeclarationTime);

public sealed record Candidacy(Candidate Candidate, ElectoralCommissionParty Party, int? Votes);

public sealed record Ballot(Constituency Constituency, ImmutableList<Candidacy> Candidacies);

public sealed record ResultSet(ImmutableList<Result> Results, Instant? LastUpdated);

public sealed record NotionalResult(
    Constituency Constituency,
    ImmutableList<NotionalCandidacy> CandidateResults,
    int AbsoluteMajority,
    decimal Turnout);

public sealed record ProjectionSet(
    string Id, DataProvider Provider, string Name, string Abbreviation, LocalDate FieldworkStart,
    LocalDate FieldworkEnd, LocalDate PublicationDate, string? ArticleLink, string? DataLink,
    ImmutableList<Projection> Projections, ImmutableList<ProjectionDistribution> Distributions);
public sealed record Projection(Constituency Constituency, Party Party,
    ProjectionStrength Strength, string? Link,
    string? Description, ImmutableList<ProjectionMeasure>? VictoryChances, ImmutableList<ProjectionMeasure>? VoteShares);
public enum ProjectionStrength { Tossup, Lean, Likely, Safe };
public sealed record ProjectionMeasure(Party Party, decimal Percentage);

public sealed record Poll(
    string Id, DataProvider Provider, ImmutableList<PollValue> Values, string? PreviousId,
    LocalDate FieldworkStart, LocalDate FieldworkEnd, LocalDate PublicationDate,
    string? ArticleLink, string? DataLink);
public sealed record PollValue(Party Party, decimal Share, decimal? ShareChange);

public sealed record PartyChange(
    Candidate Candidate, Constituency Constituency,
    Party OldParty, Party? NewParty, LocalDate Date, string Description);

public sealed record CurrentRepresentation(Constituency Constituency, Candidate? Member, Party? Party);

更多说明：

• ReadOnlyMemory不一定是不可变的（例如它可以包装byte[]）；我可能在某个时候将其更改为ImmutableList，尽管在实践中它不会引起任何问题。邮政编码数据的结构本身就是一个有趣的话题 - 你猜对了 - 我将在另一篇文章中介绍。
• 对于非英国读者，补选是在正常周期之外举行的选举，由议员辞职、死亡或通过请愿被驱逐引起。（补选也发生在非议会选区的情况下，但我的网站只处理议会选区。）
• 在系统中，术语"选票"实际上是"选区中的候选人列表”；在日常使用中，它也可以表示"单张投票"，但我想不出更好的术语，这就是Democracy Club使用的。
• 没有ResultSet的LastUpdated属性我们可能也能管理，但将其作为自己的类型仍然有意义，因为它包括从选区到结果的简化映射。对于2019年名义结果来说，（还）不值得这样做，因为它们在少得多的地方使用。
• 说到2019年名义结果…这些是"特殊的"，因为2019年和2024年之间有显著的选区边界变化。名义结果是对2019年实际结果在新边界下会是什么样子的预测。有关更多细节，请查阅关于此主题的"Rallings & Thrasher"文档。
• Poll.PreviousId属性用于计算ShareChange。它可能应该消失 - 它在网站中任何地方都没有使用。（写这些文章的一个好副作用是某种代码审查的效果。在我实际发布这篇文章时，我可能已经删除了它。）
• PartyChange没有它可能的那样规范化。可以说，我们应该记录给定人员的政党历史，然后通过考虑"在任何给定时间谁是议员，以及他们在任何给定时间代表哪个政党"的历史在选区视图中反映这一点 - 这绝对是我在未来几年可能重新审视的领域。（一旦我们有了第一次实际补选，这将很快，推理起来会更容易。）
• CurrentRepresentation同样有点奇怪，因为我们应该能够从2024年选举结果、补选和政党变化的组合中推导出数据。目前它碰巧很方便，但可能随时间变得不那么方便。

关于PartyChange和CurrentRepresentation的方面让我想知道我是否可以引入一个不在任何地方存储的ConstituencyHistory模型，而是在ElectionContext构造时推导出来。

最终想法

如前所述，模型和视图模型都是不可变的。在我尝试使用不可变性的其他项目中，我遇到了很多摩擦 - 但这个项目是一个完全只读的网站，加上C#记录的功能，使它变得非常简单。我一直知道的益处（使推理其他代码可能做什么更容易，不必担心线程安全）仍然像以往一样有价值…但在这个特定项目中，限制和挫折不是问题。C#记录有一些挑战和烦恼，但没有什么真正的问题。

我现在要强调的一个方面，并在以后专门发布一些性能问题时讨论，是在单个ElectionContext中，模型的引用相等性是我们所需要的全部。如果你有两个引用不同对象（但属于同一个ElectionContext）的ProjectionSet引用，它们肯定是"不同"的投影集。有极少数模型这只是巧合为真，例如ProjectionMeasure，但这些没有任何逻辑身份。所有"主要"模型确实都有某种形式的身份，在ElectionContext中，引用相等性等同于逻辑身份。

描述了数据模型和网站的MVVM（至少名义上）方法后，我现在有很多选项可以选择接下来写什么。我想我可能会深入存储方面的事情…