# 设计与实现说明

## 文档依据和新增设计

阅读用户复制的 17 章课程和 README，范围与分批方法见文档阅读清单。系统业务明确是财务报销/发票审计，不是任意智能体执行行为的通用安全审计。五种角色、四节点主干与独立 feedback、七类规则、双引擎风险、确定性路由、政策 RAG、审批状态机和报表来自课件。Vue 前端、SQLite/local 文件、持久 outbox、配置管理页、不可变快照和站内告警是为本次完整可运行要求选择的实现。

本版不把课件中引用但未提供的源码当作已读代码。没有添加真实税务验真、任意代码执行、邮件/短信发送或自动模型训练。企业制度只能由用户提供，不以假制度或随机向量代替真实内容。

## 模块与数据模型

| 领域 | 模型 | 约束及用途 |
|---|---|---|
| 身份 | Department / Role / User / RefreshSession | 部门/登录名唯一；密码 scrypt；刷新凭据仅存哈希，轮换撤销 |
| 配置 | AgentConfig / AuditRule | 固定节点和规则；标识+版本唯一，更新追加记录 |
| 报销 | Reimbursement / Invoice / SequenceCounter | 金额整数分；单号按业务日期原子取号；发票 UUID 受控文件键与 SHA256；移除是软标记 |
| 审核 | AuditRun / AgentExecution / RuleEvaluation | 单据+轮次唯一；输入配置历史快照；节点尝试唯一；每条结果保留版本、级别与证据 |
| 审批 | ApprovalChain / ApprovalRound / ApprovalRecord | 路由/类型/部门/金额筛选；冻结链；每个审核一轮次；每轮每节点只签一次 |
| 政策 | KnowledgeDocument / KnowledgeChunk | 正文版本、中文分块与真实向量；改正文让索引失效；旧审核保存冻结原文 |
| 运行 | OutboxEvent / Alert / OperationLog / HumanFeedback / CacheEntry | 幂等事件键、租约、重试；告警去重；只读操作留痕；独立纠正建议；缓存 TTL |

当前共有 22 类关系/运行模型，字段含义和约束在 `app/domain/models.py` 的 `comment` 中。具体表清单以模型源文件为准；OpenAPI 提供请求契约，不暴露密码哈希、刷新凭据哈希或内部文件键。

## 审核步骤

1. extract：魔数识别 PNG/JPEG/PDF，验证大小、像素和页数；PDF逐页渲染并校验共同发票标识；真实 VLM 结构化输出，失败文件有界重试；最终回用户填报。0.90/0.50 是课件预设来源权重，不是实测模型概率。
2. rule_check：日期、金额、抬头、同内容重复、税额、税号格式、政策七类；另核对申请含税总额。逐条隔离异常，core_failure 转人工；critical/error 合规失败，未完成/警告部分合规。显式关闭的可选检查或不适用范围不计为未完成。
3. risk_detect：计算真实金额、来源权重、卖方集中度、提交日志频率和部门平均比值；没有样本保持不足状态；规则分数最高截为 1，按 0.30/0.60 划级。模型只能提高风险，合规失败提升高风险；模型失败保留规则依据。
4. make_decision：缺少关键依据/核心异常优先转人工；高风险或失败转财务；中风险或部分合规转主管；明确低风险且全部所需检查完成才自动通过。
5. feedback：只允许本人已签署的对应轮次添加反馈；独立保存不覆盖原结果，training_executed=false。

核心日期、金额、抬头和重复规则不允许关闭、缩小范围或降低基础严重程度。日期过期和大额提醒另用 warning 表达“需复核”，而非把格式与有效期混成同一个法律结论。税额使用发票明确声明率，税号检查只验证配置长度与字符。

## 状态、一致性与授权

```mermaid
stateDiagram-v2
    [*] --> draft
    draft --> pending_audit: 本人提交
    rejected --> pending_audit: 修订后重提
    pending_audit --> in_approval: 派单/自动轮次
    pending_audit --> withdrawn: 本人撤回
    in_approval --> approved: 最后节点通过/系统批准
    in_approval --> rejected: 驳回
    in_approval --> draft: 退回草稿
    approved --> [*]
    withdrawn --> [*]
```

员工仅看自己，主管可看同部门，财务/经理/管理员可看全局。可查看不代表可改别人的申请；编辑、上传和撤回另做所有权与状态检查。审批只允许冻结节点指定人员，禁止自审和管理员代签；当前角色变化或停用立即阻止推进。

修改单据用 revision，配置用 expected_version。提交与重跑要求 Idempotency-Key，同键返回同一审核；审批用条件更新和唯一约束防重签。API事务中写业务与 outbox，提交后消费者读取；外部模型调用不占写事务。消费者租约、退避与启动恢复为至少一次；真正业务副作用用 audit_id/轮次/事件键幂等。任务完成或失败回写都检查旧 revision，撤回和新轮次不会被迟到结果覆盖。

默认每文件图级最多 3 次；HTTP 层不自动重试。outbox 最多 3 次事件恢复用于核心故障，不对正常 AI 降级重新跑图；崩溃后的恢复可能重新执行已完成节点，执行日志新增而不覆盖。只部署单个主程序消费者，禁止多 worker 使用启动回收逻辑。

## 可运行边界

本地缓存、规则、文件、队列、审批均真实运行；外部模型未给服务地址时明确降级。真实 LLM/VLM协议测试使用 MockTransport，自动通过测试使用明确的合约替身，不能当作外部模型已验证。语义向量必须真实服务返回合格维度；改正文或模型名称使旧索引失效。模型服务升级可能改变同名模型的输出，冻结输入和最终输出用于解释与路由复现，不能保证生成模型的重复输出逐字相同。

SQLite 与本地向量扫描适合小规模单实例。配置不能宣称已经切换为 PostgreSQL/Redis/Milvus/MinIO；这些属于后续部署改造。Excel/PDF导出是实际字节，PDF默认中文 CID字体；如查看器缺字体，可配置具有使用授权的中文 TTF。

JSON 配置清单不允许写注释，所以 `package.json`、`tsconfig.json`、锁文件的说明集中在 README 和 `docs/依赖与配置说明.md`；其他手写源码、组件、关键配置和脚本包含中文注释。