# 小白记账架构约定

## 架构选择

采用“模块化单体 + 本地优先 + 按需云服务”。早期保持一个可安装程序和一个清晰代码库，避免微服务带来的部署与排障成本，同时为未来拆分保留稳定接口。

## 分层

### 界面层

只负责展示、输入和用户反馈，不直接实现税务计算或修改数据库。

### 应用层

组织用户操作，例如“导入流水”“确认分类”“生成申报草稿”。应用层通过模块公开接口协作。

### 领域层

保存交易、账簿、规则、申报等核心业务规则。领域逻辑不依赖页面，也不依赖具体数据库。

### 基础设施层

负责 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 只生成建议，不能直接写入账簿、修改税额或代替人工确认。