已确认设计方案.md 33 KB
AI-Agent 财务审计系统：第一轮设计方案
状态：用户已确认，第二轮实现与联调已完成。本文保留第一轮方案正文作为设计依据，其中将来时与“待确认”章节属于当时计划；最终实现、目录和验收以README、设计与实现说明、自检报告为准。
本方案以用户复制的 18 份 HTML 文档为依据。文档清单、阅读方法和逐篇结论见 文档阅读清单.md。下文中的“新增设计”是为满足用户的可运行系统、管理页面、可配置规则与审计留痕要求提出的实现选择，不能视为课件原项目已有功能。
1. 产品目标与本次交付范围
实现一个有登录和权限、可保存真实业务数据的财务报销审计系统。员工建单并上传发票，后台运行审核流水线；管理人员查看规则、风险、决策与依据；人工审批闭环；异常产生站内告警。前后端实际对接数据库和 API，不以纯静态页面或伪造成功数据代替业务。
第二轮实现以下全部功能：
| 模块 | 页面与行为 | 文档依据或来源 |
|---|---|---|
| 登录与权限 | 登录、刷新令牌、退出、当前用户；五种角色与部门；用户管理及初始化测试账号 | 01、02、04、17 |
| 报销与发票 | 草稿创建/编辑、发票批量上传和补录、提交、撤回、驳回后重提；单号与文件指纹 | 02、09、11、17 |
| Agent 管理 | 五个内置节点的状态、配置版本、执行统计、模型连接测试；调整超时、并发与重试参数 | 节点来自 08、10；管理页面和配置版本为用户要求的新增设计 |
| 审计规则配置 | 七类规则的参数、严重程度和适用范围；规则版本、生效/停用及试算；配置校验 | 12、15；管理 API 与版本为新增设计 |
| 审核任务与结果 | 异步任务、进度、每个节点耗时、提取来源、规则证据、风险特征、确定性决策与历史轮次 | 05–08、10–15、17 |
| 审批与反馈 | 按路由/类型/金额/部门选链、待办、逐级通过/驳回/退回；意见、反馈和审批历史 | 14、16、17；路由维度与明确轮次为新增设计 |
| 政策知识库 | 政策正文录入/导入、版本、中文分块、索引状态、重建、检索试验、命中片段和出处 | 09、15 |
| 审计日志 | 请求追踪、配置变更、提交、重跑、审批和告警处理；时间线、筛选、分页和导出 | 03、14、16、17；管理查询页面为新增设计 |
| 异常告警 | 高风险、critical 规则、服务降级、审核失败、审批链缺失、审批超时；确认和解决 | 07、12、13、16；站内告警模型与页面为新增设计 |
| 统计报表 | 总量、金额、状态、风险分布、部门维度；Excel/PDF 导出 | 03、16、17 |
界面默认中文。页面包括：工作台、报销列表与详情、审核任务与结果详情、Agent 管理、规则管理、审批待办、审批链管理、知识库、审计日志、告警中心、用户与部门管理。
本轮不设计任意 Agent 代码执行、拖拽生成任意工作流、模型自动训练、真实税务平台验真或对外邮件/短信通知。课件没有完整给出这些实现，用户也没有要求接入对应服务。人工反馈保存为可追踪记录和迭代建议，不虚称已经训练模型。
2. 技术栈与部署取舍
| 层 | 选型 | 为什么 |
|---|---|---|
| 前端 | Vue 3、TypeScript、Vite、Element Plus、Vue Router、Pinia | 课件未规定前端；表格、表单、弹窗、时间线和审批后台适合该组合，类型契约减少参数不一致 |
| 后端 | Python 3.11+、FastAPI、Uvicorn、Pydantic、SQLAlchemy async | 与 03、17 的推荐一致，复用参数验证、异步 I/O 和 OpenAPI |
| 流程 | LangGraph StateGraph | 按 08、10 保留四节点主干、条件重试及独立反馈 |
| 默认数据库 | SQLite + aiosqlite，开启外键、WAL、写入等待 | 新增部署选择：降低 Windows 本地启动门槛，先交付可完整运行的单实例系统 |
| 默认文件存储 | backend/data 下本地文件；数据库仅存受控文件键和 SHA-256 | 新增部署选择：保留非结构化文件与业务表分离，降低 MinIO 前置依赖 |
| 默认任务 | SQLite outbox + 应用内异步消费者 | 05 提到 outbox；新增具体实现，用持久记录和幂等副作用支持故障重试与重启恢复 |
| AI 调用 | httpx 异步访问 OpenAI 兼容 VLM/LLM；外部 Embedding/Rerank | 与 06、09 一致；独立超时、结构校验、限流与熔断 |
| 政策向量 | 小规模向量保存 SQLite，应用侧 COSINE 计算；使用真实 Embedding | 新增本地实现替代 Milvus，明确适合小数据集，不冒充大规模 ANN |
| 缓存 | 有 TTL 的本地持久缓存，按模型/参数/输入/政策版本生成键 | 09 的精确输入哈希缓存与本地降级思想；不宣称已经实现近似语义缓存 |
| 报表与 PDF 输入 | openpyxl、reportlab、Pillow、PyMuPDF | 文档规定 Excel/PDF 导出；新增 PDF 发票转图、中文字体配置和图像预处理 |
本次不要求 Docker、GPU、PostgreSQL、Redis、Milvus 或 MinIO 才能启动。课件的 PostgreSQL/Redis/Milvus/MinIO 部署将写进设计对照和后续演进说明；它们不是本次已经承诺实现并测试的备用后端。
真实 AI 模式配置外部地址和凭据后才启用。无 AI 配置时仍能建单、上传、规则审核、转人工、审批、查看日志和告警；界面明确显示“用户填报降级”“政策未完成 AI 校验”。不会显示虚假的 AI 提取成功。
Python/npm 依赖在第二轮安装验证后固定版本并保留 npm 锁文件；不把未经安装的版本写成已验证环境。Node 最低版本以最终 Vite 依赖约束为准，README 写明实测版本。
3. 架构与异步一致性
flowchart TD
UI[Vue 前端] --> API[FastAPI /api/v1]
API --> AUTH[JWT 与角色及所有权检查]
AUTH --> APP[应用服务与事务边界]
APP --> DB[(SQLite 业务表)]
APP --> FILES[本地发票与政策文件]
APP --> OUTBOX[(持久事件 outbox)]
OUTBOX --> WORKER[异步消费者 / 幂等任务]
WORKER --> GRAPH[LangGraph 审核图]
GRAPH --> EXTRACT[extract]
EXTRACT --> RULE[rule_check / 七类规则]
RULE --> RISK[risk_detect / 双引擎]
RISK --> DECISION[make_decision / 确定性路由]
EXTRACT -. 已配置时 .-> VLM[外部 VLM]
RULE -. 已配置时 .-> RAG[政策检索与 LLM]
RISK -. 已配置时 .-> LLM[外部 LLM]
DECISION --> RESULT[(审核结果与执行明细)]
RESULT --> COMPLETE[(审核完成 outbox)]
COMPLETE --> APPROVAL[审批状态机]
APPROVAL --> FEEDBACK[独立 feedback]
WORKER --> ALERTS[站内告警]
API --> LOGS[操作与请求审计日志]
后端分层为 API、应用服务、领域逻辑、基础设施、共享配置。领域逻辑用接口获取存储、检索和 AI 能力；规则/风险/路由可以独立测试。业务金额及状态变更用短事务，不在数据库写事务中等待模型网络响应。
提交时，将报销状态、新审核任务和 outbox 事件写入同一事务。消费者只读取已提交事件；提交接口返回 HTTP 202 和任务 ID。消费者不是直接读取路由里未提交的 ORM 对象，也不共享请求的 AsyncSession。
每个事件有唯一 event_id、业务幂等键、状态、尝试次数、下次重试时间和租约。单实例条件更新领取事件；执行失败后退避重试，达到上限转失败并告警。重启回收过期租约。消费者采用“至少一次执行 + 业务副作用幂等”，不承诺分布式精确一次。
每次提交生成单据 revision；事件、审核和审批都携带 revision。撤回或重新编辑后旧任务不能回写新轮次。审核重跑只允许非终态、无在途审批且无活动审核的单据；其他状态返回明确冲突。
4. 数据模型
以下为关键字段和约束，第二轮将提供完整 ORM、Pydantic Schema、迁移与数据字典。新增表的目的在“来源/约束”中写明，不暗示课件已经给出这些表。
| 表/实体 | 关键字段 | 来源、含义与约束 |
|---|---|---|
| Department | id、name、active | 02；部门名称唯一，停用不破坏历史单据 |
| Role | id、code、display_name | 01；五个预置角色 code 唯一 |
| User | id、username、password_hash、department_id、role_id、active | 02、04；用户名唯一，密码只存哈希 |
| RefreshSession | id、user_id、token_hash、expires_at、revoked_at | 新增；刷新令牌轮换、退出可撤销 |
| AgentConfig | node_name、name、enabled、version、config_json | 新增；node_name 限五个内置节点；修改生成版本；核心规则和决策不能被停用后直接放行 |
| AuditRule | id、code、version、enabled、severity、scope_json、params_json | 新增；七类规则唯一 code+version；配置白名单和范围校验；必需基础检查不可绕过 |
| Reimbursement | id、number、user_id、department_id、type、total_cents、status、revision | 02；number 唯一；type 为差旅/招待/办公；状态变更受控；revision 递增 |
| Invoice | id、reimbursement_id、file_key、file_hash、declared_fields、net_cents、tax_cents | 02、11；保留用户填报与抽取结果的区分；文件键不接受任意磁盘路径 |
| SequenceCounter | date_key、value | 新增；事务内原子递增生成 BX+YYYYMMDD+六位序号；唯一索引兜底，不使用 MAX 聚合行锁 |
| AuditRun | id、reimbursement_id、revision、run_no、status、snapshot_json、decision、risk_level、compliance_status、started_at、finished_at、error_code | 02、17；执行状态独立于四种决策；保存发票、规则、Agent、政策和模型版本快照 |
| AgentExecution | id、audit_id、node_name、attempt、status、duration_ms、input_json、output_json、error_code、token_usage | 新增；唯一 audit_id+node+attempt；区分 success/degraded/failed/skipped |
| RuleEvaluation | id、audit_id、invoice_id、rule_code、rule_version、passed、severity、execution_status、message、details_json | 12+新增；保存阈值、实际值、命中证据与跳过原因 |
| ApprovalChain | id、name、route、type、department_id、amount_min_cents、amount_max_cents、nodes_json、version、active | 16+新增；上下限合法；节点数组非空；route 新增以确保财务路由不派给不合适的审批链 |
| ApprovalRound | id、reimbursement_id、revision、audit_id、chain_snapshot、status | 新增；本轮冻结审批链；旧轮审批不得推进新轮 |
| ApprovalRecord | id、round_id、node_index、approver_id、result、opinion、created_at、decided_at | 16；同轮同节点唯一；result 为待办/通过/驳回/退回；仅指定非提交人可签署 |
| KnowledgeDocument | id、title、category、version、content、active、index_status、embedding_model | 02、15；分类、正文和版本明确；未索引与索引失败有独立状态 |
| KnowledgeChunk | id、document_id、document_version、position、text、vector_json、dimension | 新增本地检索存储；chunk 与原文版本关联；只有真实且维度匹配的向量可写入 |
| OutboxEvent | id、event_type、business_key、payload_json、status、attempts、lease_until、next_attempt_at、error_code | 05+新增；业务键唯一；支持事务内写入及重启恢复 |
| Alert | id、dedup_key、type、severity、audit_id、reimbursement_id、status、message、ack_by、resolved_by | 新增；去重键唯一；open→acknowledged→resolved；状态动作记录处理人和意见 |
| OperationLog | id、actor_id、action、resource_type、resource_id、request_id、trace_id、before_json、after_json、created_at | 03、14、16+新增；应用接口只追加；密码、令牌和 API 密钥不入日志 |
| HumanFeedback | id、audit_id、approval_record_id、actor_id、corrected_fields、reason、model_update_needed | 10；保留人工纠正和建议，不执行自动模型训练 |
| CacheEntry | key、value_json、expires_at、namespace、model_version | 09+新增；TTL、精确输入缓存、版本隔离 |
金额约定为新增设计：发票 amount 是未税金额，tax_amount 是税額，gross_amount 为两者之和；报销 total_amount 为含税申请额。审核提交校验申请总额与所附发票含税合计；风险金额采用同一含税口径，并记录该口径。
数据库按整数分保存，API 金额按两位小数字符串传输，内部用 Decimal 运算，拒绝超精度、非有限值和超范围。避免 SQLite/JavaScript 浮点造成分位误差。时间保存 UTC，前端按 Asia/Shanghai 展示；发票日期作为日期字段按配置业务时区解释。
5. 审核逻辑与证据
5.1 发票提取
支持 PNG/JPEG/PDF 文件上传。校验魔数、大小和页数；PDF 转图后逐页提取，超限返回明确错误，不静默漏页。图片长边按课件 1536px 预处理。真实 AI 输出走 Schema 验证；未识别字段为 null。PDF 转图是新增完整实现，不认为第 11 章已经提供了该代码。
无模型或调用失败：使用用户已填字段且标明 user_input_fallback，保留原始提取错误。课件的 0.90/0.50 仅作为“流程置信度标记”保留并明确不是校准概率。没有填报金额或关键字段时不补造默认值，进入人工复核。
统一配置最大提取调用次数，例如总计 3 次（首次 + 2 次重试）；不同时叠加 SDK、HTTP 和图级三套无限放大重试。仅瞬时故障重试，文件非法、字段格式错误等不重试。已成功的文件结果保留，仅重试失败文件。
5.2 七类审计规则
| 规则 code | 检查与配置 | 文档依据 |
|---|---|---|
| invoice_date_valid | 日期缺失/未来；超过 365 天默认提醒，阈值可配 | 12 |
| invoice_amount_valid | 未税金额必须 >0；大额提醒默认 100000；另核对报销含税合计 | 12；合计核对为新增完整性检查 |
| invoice_header_valid | 买卖方名称非空；未配置企业全称不声称完成全称匹配 | 12、15 |
| invoice_no_duplicate | 文件 SHA-256 与历史有效单据和同单其他发票比较，critical；排除自身同一发票 | 12；明确比较范围为新增设计 |
| tax_calculation_valid | 有税率时按 Decimal 核对税额，容差可配；缺税率标待核验 | 12；不臆造法定税率表 |
| tax_number_valid | 课件 15/18/20 位长度规则作为示例参数；不等同法定税号验真 | 12 |
| policy_compliance | 检索政策片段，结构化输出 compliant/non_compliant/partial/unknown 与引用 | 15；完整结构输出为修正 |
文件重复比较范围为新增设计：同单不同发票、其他已提交/审批中/已通过单据；排除自身本轮、已撤回/已驳回单据。对同内容的并发提交加唯一占用检查或提交串行化，避免两个任务同时查询时都漏检。改图绕过文件哈希仍可能发生，不能把哈希去重宣称为发票验真或造假鉴定。
规则逐条执行、逐条留痕，一条异常不停止整套规则，但异常不能作为通过。核心金额、日期、抬头、重复检查始终执行；页面仅允许合法参数和预定范围，不运行用户任意 Python 表达式。
合规汇总修正：未通过的 critical/error → fail；仅 warning、partial 或需要的检查 skipped → partial；全部必需校验成功才 pass。规则执行状态与业务通过值分开，避免“没检查”误显示“已合规”。
5.3 风险检测
按第 13 章保留规则评分：总额 >50000 加 0.4，否则 >20000 加 0.2；最低置信度 <0.6 加 0.3，否则 <0.8 加 0.15；卖方集中度 >0.8 且发票数 >3 加 0.2；近期次数 >10 加 0.15；部门均值比 >3 加 0.2。分数 ≥0.6 为高、≥0.3 为中、其余为低。
这些是课程示例阈值，不声称为某企业已批准的制度。默认保留、页面可配置并版本化。
新增统计口径：近期窗口默认 30 天；计入实际提交记录且排除当前待评估轮次，部门比值以历史有效单据计算。无足够数据时返回 null/insufficient_data 和解释，不使用虚假的 0 次或 5000 元均值。保存统计时点和特征快照供复核。
真实 LLM 返回合法结构后与规则等级取较高值；LLM 失败保留规则风险和降级说明。合规 fail 时升为 HIGH。评分采用 Decimal 或整数权重，避免 0.3/0.6 边界误差。规则/LLM 等级、评分、理由分别保存，不能只留下被选中的一个引擎结果。
5.4 确定性决策
| 优先级 | 条件 | 路由 | 说明 |
|---|---|---|---|
| 1 | 没有可用发票/关键输入缺失/未评估风险/核心节点执行失败 | to_manual | 扩展课件的无证据护栏，不以默认低风险和 pass 放行 |
| 2 | risk=HIGH 或 compliance=fail | to_finance | 第 14 章主矩阵 |
| 3 | risk=MEDIUM 或 compliance=partial | to_supervisor | 第 14 章主矩阵；必需政策校验降级可进入此分支 |
| 4 | 明确 risk=LOW、compliance=pass 且所需步骤已成功 | auto_approve | 明确检查通过才自动批准 |
人工填报降级可继续审核和审批，但不伪装为模型核验。政策不可用仍不终止整个流程；默认标记待复核并产生告警。将第 15 章“跳过政策也算通过”的策略收紧为 partial 是新增审慎设计，须随本方案确认。
相同“规范化上游结果 + 路由规则版本”得到相同路由；含模型调用的整条流程不保证每次重跑完全一致。因此重现历史路由使用已保存快照，新的模型重跑保存为另一记录，不覆盖旧结果。
6. 知识库、审批和告警
政策按标题→段落→句子分块，默认 512 字、64 字重叠。记录文档和分块版本。真实 Embedding 的文档与查询使用同模型/同维度，默认按课件 1024 维；切换模型需重建索引，绝不混用向量空间。
本地小规模索引计算 COSINE，配置 Rerank 时再精排。无 Embedding 时允许明确标为“关键词检索”的人工查看，不冒充语义召回；自动政策判断为 skipped/unknown。没有命中不能证明没有适用政策，只能显示“未找到依据”。政策引用返回文档 ID、标题、版本、chunk ID 和原文，不允许模型凭空编造出处。
审批链匹配 route、类型、部门和金额；空值为不限。命中多条按匹配明确程度、配置优先级和版本排序，是对课件“最新优先”的新增消歧策略。财务路由必须含审核员节点，主管路由必须含主管或更高授权节点，人工路由必须含人工复核节点；节点用户有效且不是提交人。链在审批轮次开始时冻结，之后配置变更不影响在途轮次。
状态白名单保留：DRAFT→PENDING_AUDIT；PENDING_AUDIT→IN_APPROVAL/WITHDRAWN；IN_APPROVAL→APPROVED/REJECTED/DRAFT；REJECTED→PENDING_AUDIT；APPROVED/WITHDRAWN 为终态。自动批准也在事务内依次走合法迁移并写系统审批记录，不私自跳过白名单。链不存在时留下待处理状态、事件失败原因和告警，不默认自动批准。
审批动作使用条件更新防重签，检查当前轮次、指定处理人和禁止自审。员工只操作本人单据，主管按部门查看，审核员处理授权审核/复核任务，经理配置审批链和查看授权报表，管理员管理配置；管理员身份不绕过“指定审批人/不得自审”。隐藏菜单和按钮只改善体验，后端始终执行权限校验。
应用内超时扫描默认 48 小时，可配置扫描周期；按审批记录 ID 去重创建告警。告警确认/解决包含操作人、时间和意见；“已解决”仅记录处理动作，不改写原风险或审核结论。站内告警是真实持久记录，本次不发送邮件/短信。
7. API 清单及前后端契约
统一前缀 /api/v1。列表支持 page/page_size 和模块筛选。常规成功响应为 {data, message, request_id}；分页 data 为 {items, total, page, page_size}；错误为 {error: {code, message, details}, request_id}。Pydantic 验证错误也转换为同一错误结构。
HTTP 使用 200/201、异步受理 202、未登录 401、无权限 403、不存在 404、冲突 409、参数错误 422、限流 429、依赖不可用 503。文件响应和 SSE 使用对应 MIME，不套 JSON 外壳。
| 方法与路径 | 请求要点 | 返回与用途 |
|---|---|---|
| POST /auth/login | username、password | access_token、refresh_token、expires_in、user |
| POST /auth/refresh | refresh_token | 轮换后的令牌；过期/撤销拒绝 |
| POST /auth/logout | refresh_token；当前身份 | 撤销刷新会话 |
| GET /auth/me | Bearer token | 当前用户、角色与权限 |
| GET/POST /users | 分页筛选 / 用户字段 | 用户列表 / 新用户 |
| PATCH /users/{id} | 姓名、角色、部门、active | 修改后用户；用户名等约束检查 |
| GET/POST /departments | 查询 / name | 部门列表 / 新部门 |
| PATCH /departments/{id} | name、active | 更新部门 |
| GET /agents | 状态筛选 | 五个内置 Agent 与执行统计 |
| GET/PATCH /agents/{node_name} | 配置、expected_version | 详情 / 新配置版本 |
| POST /agents/{node_name}/test | 已保存的连接配置 | 真实连接测试结果；无服务标 disabled/degraded |
| GET /rules | code、enabled、分页 | 七类规则和当前版本 |
| GET/PATCH /rules/{code} | 参数、severity、scope、expected_version | 详情 / 新规则版本 |
| POST /rules/{code}/test | invoice、context | 不写正式审核结果的规则试算 |
| GET/POST /reimbursements | 分页、状态、类型 / 报销字段 | 列表 / 草稿 |
| GET/PATCH /reimbursements/{id} | editable 字段、revision | 含发票/审核/审批摘要的详情 / 修改 |
| POST /reimbursements/{id}/invoices | multipart files、填报元数据 | SSE 上传进度与完成/失败帧 |
| PATCH /invoices/{id} | 用户补录结构化字段、revision | 更新后的发票；只允许可编辑轮次 |
| DELETE /invoices/{id} | 当前身份 | 从可编辑草稿移除发票 |
| GET /invoices/{id}/file | 当前身份 | 受控发票内容，禁止任意路径读取 |
| POST /reimbursements/{id}/submit | revision、Idempotency-Key | 202：报销状态、audit_id |
| POST /reimbursements/{id}/withdraw | revision | 撤回状态；旧任务失效 |
| GET /audit | 状态、风险、决策、报销 ID | 分页审核记录 |
| GET /audit/{audit_id} | 当前身份 | 结果、节点、规则、证据和版本快照 |
| GET /audit/{audit_id}/events | Last-Event-ID 可选 | SSE：开始、节点进度、完成、失败、心跳 |
| POST /audit/{audit_id}/rerun | reason、Idempotency-Key | 合法时 202 新 audit_id；在途/终态 409 |
| POST /audit/{audit_id}/feedback | 纠正字段、reason、关联审批 ID | 保存反馈与迭代建议 |
| GET /approvals | 待办/历史、报销 ID、分页 | 当前用户有权看到的审批记录 |
| POST /approvals/{id}/decide | action=approve/reject/return、opinion | 审批结果、当前轮次及报销状态 |
| GET/POST /approvals/chains | 分页 / 链匹配条件和 nodes | 链列表 / 已验证新链 |
| PATCH /approvals/chains/{id} | 配置、active、expected_version | 链新版本 |
| GET/POST /knowledge/documents | 分页 / title、category、content | 文档列表 / 新文档和索引状态 |
| PATCH /knowledge/documents/{id} | 正文、active、expected_version | 新版本；旧索引失效 |
| POST /knowledge/documents/import | multipart txt/md 文件 | 导入的政策正文和来源 |
| POST /knowledge/documents/{id}/reindex | 当前身份 | 202：索引任务 ID；无模型明确失败 |
| POST /knowledge/search | query、mode、top_k、category | 实际检索方式、文档版本、原文片段与分数 |
| GET /logs | actor、action、resource、trace、时间、分页 | 审计日志列表 |
| GET /logs/export | 同查询条件 | 授权范围内 CSV 文件 |
| GET /alerts | 类型、严重程度、状态、分页 | 告警列表 |
| POST /alerts/{id}/acknowledge | opinion | 已确认告警 |
| POST /alerts/{id}/resolve | opinion | 已解决告警；原风险保持历史事实 |
| GET /stats/overview | 时间范围、部门 | 总量/金额/状态/风险和部门统计 |
| GET /stats/export | 时间范围、部门、format=xlsx/pdf | 下载报表 |
| GET /health | 无敏感配置 | 数据库、消费者、存储、AI 配置/健康状态 |
API 静态路径（chains、export、import 等）在动态 ID 路径之前注册，避免被 ID 参数吞掉。Agent 和规则采用固定内置标识，删除表达为停用/新版本；不提供任意执行代码的创建接口。
SSE 上传是 multipart POST，前端用带 Authorization 的 fetch 读取 response.body，不能用只支持 GET 的 EventSource 发上传请求。审核事件同样支持 fetch 流和取消；断线可用 GET /audit/{id} 重取持久进度，页面卸载释放读取器。SSE 不把长期 token 放进 URL。
默认后端 127.0.0.1:8000，前端 127.0.0.1:5173。Vite 把 /api 代理到配置的后端；API_PREFIX、FRONTEND_PORT、BACKEND_TARGET 集中配置。CORS 使用明确允许源（localhost/127.0.0.1 的配置端口），允许 Authorization 和 Idempotency-Key，并暴露请求追踪、下载文件名所需响应头。刷新令牌过期后返回登录，不做无限重试。
8. 配置与中文注释规范
后端统一从 backend/.env 和 Settings 读取：APP_ENV、HOST、PORT、API_PREFIX、DATABASE_URL、DATA_DIR、CORS_ORIGINS、JWT_SECRET、TOKEN_TTL、上传限制、PDF 页数限制、业务时区、超时/重试/熔断/并发参数、LLM/VLM/Embedding/Rerank 地址和模型名、导出中文字体路径。路径以项目文件位置解析，不依赖启动时偶然的 cwd。
后台 Agent 配置的模型名与运行参数版本化；API 密钥来自服务端环境，页面只显示“已配置”，不返回明文。所有密钥默认通过初始化生成或用户设置；不会把课件演示凭据复制为应用生产凭据。
前端环境配置包括端口、代理目标和 API 前缀；API 模块与后端使用一致字段、枚举和金额类型。后端 OpenAPI 是接口事实来源，另交付中文 API 文档。
所有 Python/TypeScript/Vue/HTML/CSS/脚本代码文件都包含有意义中文注释：接口注明功能、参数、返回和异常；字段注明含义与约束；核心规则和状态分支解释原因；组件顶部注明名称、职责、props/emits，没有则明确无；请求封装注明 HTTP 契约，复杂生命周期说明取消/订阅释放原因。
JSON 文件不支持注释，package.json/锁文件保持合法 JSON；依赖与配置说明写到配套文档，不添加破坏语法的注释。requirements.txt、环境示例、构建配置、初始化及迁移脚本直接加入合法中文注释。
9. 第二轮预定落盘结构
最终目标仍是用户指定的原路径，不擅自替换：
D:\HuaweiMoveData\Users\HUAWEI\Desktop\agent\docs\docs\course_html\code
code/
├── backend/
│ ├── main.py
│ ├── requirements.txt
│ ├── requirements-dev.txt
│ ├── .env.example
│ ├── alembic.ini
│ ├── app/
│ │ ├── api/
│ │ ├── application/
│ │ ├── domain/
│ │ ├── infrastructure/
│ │ └── shared/
│ ├── migrations/
│ ├── scripts/
│ └── tests/
├── frontend/
│ ├── package.json
│ ├── package-lock.json
│ ├── index.html
│ ├── vite.config.ts
│ ├── tsconfig.json
│ ├── .env.example
│ └── src/
│ ├── api/
│ ├── components/
│ ├── views/
│ ├── router/
│ ├── stores/
│ ├── types/
│ └── styles/
├── docs/
│ ├── document-inventory.md
│ ├── design.md
│ ├── api.md
│ ├── data-dictionary.md
│ └── verification.md
└── README.md
第二轮先在当前可写工作区完成与核验，再申请原路径 code 的写入权限以落盘。若同名文件存在，列出冲突并保留备份，避免覆盖用户原代码。复制到目标后再次核验完整文件与相对路径；若目标仍不可写，明确报告并提供完整可下载项目/逐文件内容，不能声称已写入 D 盘。
10. 启动、联调与验收计划
README 将提供 Python/Node 环境准备、虚拟环境、依赖安装、配置、迁移、种子数据和双终端启动指南。初始化脚本幂等，创建五种角色、示例用户、七类规则、五个 Agent 与示例审批链。示例企业/用户/制度均标演示数据，不能冒充真实企业信息。
初始化后保留用户要求的入口：
# 在项目父目录运行，依赖安装完成后由 main.py 启动 API
cd code/backend && pip install -r requirements.txt && python main.py
# 在另一个终端启动前端
cd code/frontend && npm install && npm run dev
上述是第二轮交付的目标命令，不是本轮已执行通过的结果。Windows PowerShell 5.1 的 README 另给分行写法，避免不支持 &&。
验证将分四层完成，并保存命令、输出和实测限制：
- 静态验证：Python 编译/导入；TypeScript 类型检查和 npm production build；依赖清单与锁文件；中文注释检查。
- 业务测试：七条规则及 critical 汇总；金额精度；0.3/0.6 风险边界；缺失数据转人工；全状态矩阵；自审/越权/重复审批拒绝；真实历史特征；配置版本快照。
- 后端 API 集成：登录→建单→上传/补录→提交→后台审核→结果与日志/告警→人工审批→统计/下载；幂等提交、撤回竞态、重跑护栏、outbox 重启恢复及超时扫描。
- 实际启动与前端联调：分别启动后端/前端，检查健康和真实请求，再用浏览器操作业务闭环；验证 SSE、跨域/代理、401/403、表单错误和刷新后的持久数据。
AI 正常/异常分支可用协议测试服务验证，但必须标为测试替身，不称真实模型测试。只有用户配置并实际可达的模型服务才能验证真实提取与语义效果；没有该服务时验收降级链路，明确记录真实 AI 效果尚未测定。
完成后交付可运行源码、README、中文文档、完整依赖、文件清单和测试证据。不会承诺“绝对无 bug”；逐项报告已验证项与未验证外部依赖。
11. 课件需修正或补足的事项
| 位置 | 原文情况 | 本方案处理 |
|---|---|---|
| 05 §5 | 把 flush 说成其他事务可看到未提交修改 | 事务内写 outbox，提交后消费者读取；不把 flush 当 commit |
| 03 PostgreSQL 说明 | 描述 MAX 聚合配 FOR UPDATE 作为序号兜底 | SQLite 原子计数表与唯一索引；不照搬聚合锁示例 |
| 08 §5 与 10/11 | “三次重试”与失败即加计数导致的总尝试数口径不同 | 明确配置为总调用次数并测试边界，统一 3 次总尝试示例 |
| 12 §4 | 只检查 error/warning，遗漏 duplicate 的 critical | critical 与 error 都进入 fail |
| 13 §5 | recent_submissions=0、dept_avg_amount=5000 | 查询真实历史；缺样本明确 null，不伪造统计 |
| 13 图示/表述与代码 | 文本说双引擎并行，示例先后 await | 不将课件先后代码描述为已并行；本次先算规则基准再调用 LLM，记录实际耗时 |
| 14 §4 | 缺失风险/合规输入默认 LOW/pass | 缺失/未评估/核心失败转人工；不是自动通过 |
| 15 §4 | 字符串包含 non_compliant，partial 与解析异常可被当通过 | Schema 精确枚举验证；partial/unknown 有真实状态和引用 |
| 15 §4.2 | RAG 错误 passed=True 保持 pass | 新增默认 partial + 告警，但继续业务和人工审批 |
| 16 配置示例 | finance 不在五种用户角色枚举内 | to_finance 对应 auditor，统一字段与页面名称 |
| 11 类型探测 | 未知类型默认 JPEG；PDF 完整读取链路未给出 | 非支持类型拒绝；PDF 显式转图和页数限制 |
| 09 表述 | 标题称语义缓存，示例为精确哈希键；提到归一化影响 COSINE 精度 | 按示例实现精确缓存；校验真实向量和度量，不推广未提供的近似缓存算法 |
其中事务修正已核对官方文档：SQLAlchemy flush 在事务内发出 SQL，本身不结束事务；PostgreSQL READ COMMITTED 的其他事务只能看到查询开始前已提交的行。
12. 官方技术核验来源
下面来源只用于框架与工程语义核验，不作为用户课件已有业务的证据。
- SQLAlchemy 2.0 Session Basics — Flushing
- PostgreSQL — SET TRANSACTION / READ COMMITTED
- Vue 官方快速开始：Vite、TypeScript 与项目构建
- Element Plus 官方安装说明
- LangGraph 官方概览
13. 待确认内容
确认本方案即确认：本地默认部署采用 Vue 3 + FastAPI + SQLite；交付完整财务审计与审批闭环；真实 AI 服务按配置启用；缺失或跳过重要检查进入复核而非自动放行；第一轮结束，第二轮生成全部源码并尝试写入指定 D 盘 code 目录。
确认前不开始生成业务工程。本轮设计文件已保存至当前会话 outputs，尚未将任何业务代码写入原 code 目录。