4.0 KiB
4.0 KiB
小白记账架构约定
架构选择
采用“模块化单体 + 本地优先 + 按需云服务”。早期保持一个可安装程序和一个清晰代码库，避免微服务带来的部署与排障成本，同时为未来拆分保留稳定接口。
分层
界面层
只负责展示、输入和用户反馈，不直接实现税务计算或修改数据库。
应用层
组织用户操作，例如“导入流水”“确认分类”“生成申报草稿”。应用层通过模块公开接口协作。
领域层
保存交易、账簿、规则、申报等核心业务规则。领域逻辑不依赖页面，也不依赖具体数据库。
基础设施层
负责 SQLite、文件系统、加密、网络、日志、更新和 Windows 系统能力。
业务模块
identity：用户、经营主体、授权documents：票据和原始文件transactions：流水、去重、业务分类ledger：凭证、账簿和更正记录tax-rules：有版本的确定性税务规则filing：申报草稿、确认、提交和回执review：人工复核队列和意见reporting：经营概览与报表audit：不可静默修改的操作与依据记录platform：本地存储、加密、更新、备份和恢复
依赖规则
- 界面只能调用应用层。
- 应用层通过模块公开接口访问领域能力。
- 一个模块不得直接修改另一个模块的数据库表。
- AI 输出必须先经过结构校验和确定性规则校验。
- 税务计算不得调用生成式模型。
- 外部 OCR、AI 和申报通道必须经过适配层，以便更换供应商。
数据原则
- 金额以“分”为单位保存为整数。
- 原始文件使用内容哈希去重。
- 原始交易不可覆盖，更正通过追加版本实现。
- 计算结果记录输入版本、规则版本和程序版本。
- 数据库升级必须有迁移、校验与回退方案。
- 客户端日志默认不得记录身份证号、账号、完整票据内容或访问令牌。
技术边界
- 桌面容器：Tauri 2
- 界面与主要业务代码：React + TypeScript
- 本地存储：SQLite；生产版本启用加密与 Windows 安全密钥保护
- 云端接口：版本化 JSON API
- 云端数据：PostgreSQL
- 桌面底层桥接：保持少量 Rust 代码，不在其中堆积业务规则
当前仓库首先实现可运行的界面与纯领域逻辑；本地数据库、Tauri 容器和云端服务按阶段接入，不用模拟实现冒充生产能力。
OCR 与 LLM 迁移边界
当前纯本地测试版通过 providers 适配层访问百度 OCR 和 OpenAI 兼容 LLM。documents 模块只依赖统一的识别与建议函数，不读取供应商密钥，也不拼装 HTTP 请求。这样迁移到服务端时，可将 providers 的实现移动到服务端，客户端改为调用小白记账版本化 API，票据复核页面与字段校验规则无需重写。
客户端与服务端分离后遵守以下边界：
- 供应商密钥只存在服务端密钥管理系统或受保护环境变量中。
- 客户端只持有用户登录后的短期会话凭据，不持有 OCR 或 LLM 密钥。
- 服务端按经营主体做鉴权、限流、调用审计和数据隔离。
- OCR 与 LLM 的响应都先经过服务端结构校验；客户端仍保留金额、日期和枚举白名单等确定性校验。
- AI 只生成建议，不能直接写入账簿、修改税额或代替人工确认。
票据、流水与凭证
票据证明交易内容，流水证明资金实际收付，凭证负责把两类证据关联起来。三者不互相冒充：确认发票不会创建流水，导入流水也不会自动认定某张发票属于它。
当前一对一匹配由版本化确定性规则完成。金额和收支方向必须完全一致，日期必须在允许窗口内，交易对方名称只影响排序。用户确认后，系统保存匹配证据快照并按需追加流水分类修订；撤销通过新的审计事件和反向修订完成，不删除原记录，也不覆盖撤销前已经发生的后续人工修改。