PaperCoin 核心代码导读（上）：领域模型、持久化与主题

1.1 Constants.cs —— 版本的唯一真相#

1
public static class Constants
2
{
3
    public const string AppName = "PaperCoin";
4

5
    public static readonly string AppVersion =
6
        typeof(Constants).Assembly.GetName().Version?.ToString(3) ?? "0.0.0";

AppVersion 从程序集版本读取，而不是写字面量。程序集版本来自 Directory.Build.props 的 <Version> 标签——那是整个解决方案的版本单一来源。

为什么要这样做？MSI 安装包覆盖文件时比较的是文件版本，新版本必须严格大于已安装版本，相等就跳过更新。如果版本写死为字面量而程序集版本没同步改，就会出现”配置说升级了但 MSI 不更新文件”的情况。历史上 Core 和 Service 没设版本（都是 1.0.0.0），升级后旧的 Service.dll 留在安装目录，新主程序调用它不存在的方法，一按 + 号就崩溃。

ToString(3) 取前三位（主版本.次版本.修订版本），忽略第 4 位。

1
    public static readonly string AppDataFolder =
2
        Path.Combine(Environment.CurrentDirectory, "PaperCoin");
3
    public static readonly string ConfigFolder =
4
        Path.Combine(AppDataFolder, "Config");
5
    public static readonly string LogsFolder =
6
        Path.Combine(AppDataFolder, "Logs");
7
    public static readonly string BillFolder =
8
        Path.Combine(AppDataFolder, "Bills");

所有运行时数据放在进程当前工作目录下的 PaperCoin/ 子目录里。数据目录跟着程序目录走，所以安装路径必须锁住（后面会讲 InstallLocation 如何实现）。

目录结构：Config/（配置）、Logs/（日志）、Bills/（账单，按年/月/日分层）。

1.2 Models/AppConfig.cs —— 配置 POCO#

1
public class AppConfig
2
{
3
    public AppSection App { get; set; } = new();
4
    public LoggingSection Logging { get; set; } = new();
5
}
6

7
public class AppSection
8
{
9
    public bool AutoUpdate { get; set; }
10
    public string AutoUpdateSource { get; set; } = "Github";
11
    public bool AutoStart { get; set; } = true;
12
    public string Theme { get; set; } = "Dark";     // Dark / Bright / System
13
}
14

15
public class LoggingSection
16
{
17
    public string Level { get; set; } = "Infomation";  // 注意：拼错了但未使用
18
    public int RetainDays { get; set; } = 7;
19
}

简单的 POCO，配置 JSON 直接反序列化为此类型。LoggingSection 目前在代码中未被实际使用——Serilog 配置写死在 App.OnStartup 里。

1.3 Models/BillInfo.cs —— 核心领域模型#

1
public partial class BillEntry : ObservableObject
2
{
3
    public Guid Id { get; set; } = Guid.NewGuid();
4

5
    [ObservableProperty]
6
    private string _description = "";
7

8
    [ObservableProperty]
9
    private decimal _amount;
10

11
    [ObservableProperty]
12
    private string? _category;
13

14
    [ObservableProperty]
15
    private DateOnly _date = DateOnly.FromDateTime(DateTime.Today);

1
    public string DateText => Date.ToString("MM-dd");
2

3
    public string AmountText => Amount >= 0
4
        ? $"+{Amount:N2}"
5
        : $"-{Math.Abs(Amount):N2}";

1
    partial void OnAmountChanged(decimal value) => OnPropertyChanged(nameof(AmountText));
2
    partial void OnDateChanged(DateOnly value) => OnPropertyChanged(nameof(DateText));

2.1 BillJsonManager.cs —— JSON 序列化辅助#

1
public class BillJsonManager
2
{
3
    private static readonly JsonSerializerOptions Options = new()
4
    {
5
        WriteIndented = true,
6
        Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping, // 不转义中文
7
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase
8
    };

三个关键配置：

• WriteIndented = true：格式化输出，方便用户手工编辑账单 JSON。
• UnsafeRelaxedJsonEscaping：不把中文转成 \uXXXX，保持可读性。
• CamelCase：属性名首字母小写，与 JSON 惯例一致。

提供了 ToJSON/FromJSON/SaveToFileAsync/LoadFromFileAsync 四个静态方法，简单的序列化封装。

2.2 BillRepository.cs —— 账单持久化与查询（最核心）#

这是整个数据层最重要的类。磁盘布局为 Bills/yyyy/M/d/bills.json，年/月/日本身就是路径，因此没有独立索引文件，查询直接枚举目录。

1
public class BillRepository
2
{
3
    private const string IndexFileName = "bills.json";
4

5
    private readonly SemaphoreSlim _gate = new(1, 1);       // 保护索引构建
6
    private readonly SemaphoreSlim _writeGate = new(1, 1);  // 串行化写入与删除
7
    private readonly Dictionary<DateOnly, List<BillEntry>> _index = [];
8
    private bool _indexStale = true;

1
public async Task<IReadOnlyList<BillEntry>> LoadDayAsync(DateOnly date, ...)
2
{
3
    await EnsureIndexAsync(ct);
4
    lock (_index)
5
    {
6
        return _index.TryGetValue(date, out var list)
7
            ? list.ToList()          // 复制一份，不暴露内部集合
8
            : [];
9
    }
10
}

1
public async Task<IReadOnlyList<string>> GetCategoriesAsync(...)
2
{
3
    return _index.Values
4
        .SelectMany(list => list)
5
        .Select(e => e.Category)
6
        .Where(c => !string.IsNullOrWhiteSpace(c))
7
        .Select(c => c!.Trim())
8
        .GroupBy(c => c, StringComparer.OrdinalIgnoreCase)
9
        .OrderByDescending(g => g.Count())
10
        .ThenBy(g => g.Key, StringComparer.OrdinalIgnoreCase)
11
        .Select(g => g.Key)
12
        .ToList();
13
}

1
public async Task SaveAsync(IEnumerable<BillEntry> entries, ...)
2
{
3
    var byDate = entries.GroupBy(e => e.Date)
4
        .ToDictionary(g => g.Key, g => g.ToList());
5

6
    await _writeGate.WaitAsync(ct);
7
    try
8
    {
9
        foreach (var (date, list) in byDate)
10
            await WriteDayAsync(date, list, ct);
11

12
        lock (_index)
13
        {
14
            foreach (var (date, list) in byDate)
15
                _index[date] = list;
16
        }
17
    }
18
    finally { _writeGate.Release(); }
19
}

1
public async Task<bool> UpsertEntryAsync(BillEntry entry, DateOnly? previousDate, ...)
2
{
3
    await _writeGate.WaitAsync(ct);
4
    try
5
    {
6
        if (previousDate is { } old && old != entry.Date)
7
            await RemoveEntryFromDayAsync(old, entry.Id, ct);
8

9
        await MergeEntryIntoDayAsync(entry, ct);
10
        return true;
11
    }
12
    catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
13
    {
14
        Log.Warning(ex, "保存账单失败: {Date}", entry.Date);
15
        return false;
16
    }
17
    finally { _writeGate.Release(); }
18
}

1
private async Task MergeEntryIntoDayAsync(BillEntry entry, ...)
2
{
3
    var list = File.Exists(file) ? await ReadDayFileAsync(file, ct) : [];
4
    int existing = list.FindIndex(e => e.Id == entry.Id);
5
    if (existing >= 0) list[existing] = entry;   // 同 Id 覆盖
6
    else list.Add(entry);                         // 新 Id 追加
7
    await WriteDayAsync(entry.Date, list, ct);
8
    lock (_index) _index[entry.Date] = list;
9
}

1
public async Task<bool> DeleteDayAsync(DateOnly date, ...)
2
{
3
    await _writeGate.WaitAsync(ct);
4
    try
5
    {
6
        var file = Path.Combine(DayDirectory(date), IndexFileName);
7
        if (File.Exists(file)) File.Delete(file);
8
        PruneEmptyFolders(dir);
9
        lock (_index) _index.Remove(date);
10
        return true;
11
    }
12
    finally { _writeGate.Release(); }
13
}

1
private async Task EnsureIndexAsync(CancellationToken ct)
2
{
3
    if (!_indexStale) return;
4
    await _gate.WaitAsync(ct);
5
    try
6
    {
7
        if (!_indexStale) return;  // 双重检查：等锁期间可能已建好
8
        var built = await BuildIndexAsync(ct);
9
        lock (_index)
10
        {
11
            _index.Clear();
12
            foreach (var (date, list) in built) _index[date] = list;
13
        }
14
        _indexStale = false;
15
    }
16
    finally { _gate.Release(); }
17
}

2.3 ConfigService.cs —— 配置读写#

1
public class ConfigService
2
{
3
    public ConfigService()
4
    {
5
        Directory.CreateDirectory(Constants.ConfigFolder);
6
        _configFilePath = Path.Combine(Constants.ConfigFolder, Constants.AppSettingsFile);
7

8
        if (!File.Exists(_configFilePath))
9
        {
10
            var defaultConfig = new AppConfig();
11
            File.WriteAllText(_configFilePath, JsonSerializer.Serialize(defaultConfig, ...));
12
        }
13

14
        _configuration = new ConfigurationBuilder()
15
            .AddJsonFile(_configFilePath, optional: false, reloadOnChange: true)
16
            .Build();
17
    }

构造时确保配置目录和文件存在。用 Microsoft.Extensions.Configuration 的 AddJsonFile 加载，reloadOnChange: true 让文件变化时自动重新加载。

提供 GetAppConfig（绑定到强类型）、SaveAppConfig（序列化写回）、Reload（强制重载）三个方法。

2.4 ThemeManager.cs —— 主题状态#

主题管理器不含渲染代码——替换资源字典由 UI 层的 ThemeRenderer 完成。这里只负责”用户选了什么模式、这个模式对应哪个实际主题”。

1
public class ThemeManager
2
{
3
    public string Mode { get; private set; } = Dark;
4
    public string Resolved { get; private set; } = Dark;
5

6
    public ThemeManager(ConfigService configService)
7
    {
8
        Mode = Normalize(configService.GetAppConfig().App.Theme);
9
        Resolved = Resolve(Mode);
10
    }

用户选择的是模式（System/Dark/Bright），实际渲染用的是主题（Dark/Bright）。System 模式下，Resolve 读注册表探测当前系统主题。

1
public static string GetSystemTheme()
2
{
3
    using var key = Registry.CurrentUser.OpenSubKey(
4
        @"Software\Microsoft\Windows\CurrentVersion\Themes\Personalize");
5
    // AppsUseLightTheme: 0 = 深色, 1 = 浅色
6
    return key?.GetValue("AppsUseLightTheme") is int light && light == 0 ? Dark : Bright;
7
}

读的是 AppsUseLightTheme（应用模式），不是任务栏的 SystemUsesLightTheme。取不到按暗色兜底。

ApplyMode 方法：先写配置，成功后才改内存状态——避免配置写失败但界面已切换的不一致。如果解析后的实际主题变化了（比如从 Bright 切到 System 但系统当前是 Bright，实际主题不变），只触发 ResolvedThemeChanged 事件；如果没变化，不触发。

2.5 InstallLocation.cs —— 安装位置记录#

1
public static class InstallLocation
2
{
3
    public const string KeyPath = @"Software\Ksayus\PaperCoin";
4
    public const string ValueName = "InstallDir";
5

6
    public static void Record()
7
    {
8
        using var key = Registry.CurrentUser.CreateSubKey(KeyPath);
9
        key?.SetValue(ValueName, AppContext.BaseDirectory.TrimEnd('\\'));
10
    }
11
}

把当前安装位置写进 HKCU\Software\Ksayus\PaperCoin\InstallDir。安装程序升级时会搜这个键来决定装到哪里：搜到沿用旧路径，搜不到用默认值。这样升级不会把文件装到第二个目录。

KeyPath 和 ValueName 是与安装包 .vdproj 的 “Locator” 节点约定好的，改一处必须同步改另一处。

2.6 ShortcutRepair.cs —— 快捷方式图标修正#

这是为了绕开 VS 安装项目工具链缺陷的补丁。

问题背景：MSI 规定与快捷方式关联的图标必须是 PE 格式且扩展名与快捷方式目标一致。VS 安装项目把 .ico 字节原样塞进 MSI 的 Icon 表，条目名却带 .exe 后缀。安装时 Windows Installer 写出一个假 .exe，Shell 按 PE 加载失败，快捷方式就没有图标。

解决方案：运行期修正，通过 COM 互操作（IShellLinkW + IPersistFile）读写 .lnk 快捷方式文件，把 IconLocation 指向真实的 .ico 文件。

一个踩坑记录：对从磁盘 Load 的 IShellLink 调 SetIconLocation 再 Save，写盘后快捷方式的目标会变成图标文件的路径。所以用全新的链对象重写目标、起始目录、图标三项。

1
var shellLink = (IShellLinkW)new ShellLinkObject();
2
shellLink.SetPath(exePath);
3
shellLink.SetWorkingDirectory(AppContext.BaseDirectory);
4
shellLink.SetIconLocation(iconPath, 0);
5
((IPersistFile)shellLink).Save(shortcutPath, true);

图标文件位置：优先用程序目录里的 .ico（安装包装出来的）；没有就从内嵌资源 PaperCoin.Icon.papercoin-icon.ico 落盘到 %LOCALAPPDATA%\PaperCoin\。两个位置都在用户配置下，不需要提权。