verify-invoice-default/development/REQUIREMENTS.md

REQUIREMENTS —— 票据合规预审助手（verify-invoice-default）

需求来源：《核心建设内容：各部门"Skill"深度需求规格书》§4.1 财务处 Skill 001（票据合规性"秒级预审"）。 详细设计见工作区《财务处Skill001-票据合规秒级预审-开发文档.md》；本文是该技能仓内的需求与验收主文档。 定位原则：辅助非决策、审慎非激进 —— AI 只做预审提示，真伪与最终结论由人确认。

0. 技能标识

• 拟定 slug：verify-invoice-default
• 中文 name：票据合规预审助手
• 中文 description：高校报销场景的发票合规性秒级预审：核对字段完整性、购买方税号白名单、开票日期与出差行程逻辑、住宿交通经费标准，对连号、同商家集中开票、节假日开票等风险点红黄灯预警，生成《初审意见单》。
• account-manager platform_key：不适用（无网页 RPA，无账号下发）
• 命名形态：scope 型（verify ∈ 动词白名单；default ∈ scope 白名单；21 字符）
• 网页 RPA 登录策略：not_needed（无浏览器自动化；不使用 account-manager）

0.1 宿主入口定位

主能力（Action id / CLI）	对话	数据管理	定时	教程章节	不挂理由
prereview-invoice（prereview）	挂	toolbar（bind invoice_records，表单）	不挂	入口一/入口二	预审由单据驱动，无无人值守场景
prereview-batch-input（prereview-batch-input，async）	挂	不挂	不挂	入口二	批量输入依赖 input 目录，属对话长任务
render-html（render-html）	挂	toolbar（bind prereview_reports）+ skill-detail	不挂	入口一/入口二	同预审
mark-verified	不挂	row（prereview_reports，预填 id）	不挂	入口一	查验回填是"对着记录"的操作
list-reports / stats	挂	不挂	不挂	入口二	查询类，对话即达
view-standards	挂	仅展示表	不挂	入口二	标准库日常只读
set-standard	不挂	row（expense_standards，预填键）	不挂	入口一	管理员在表上改值更直接
add-whitelist	不挂	toolbar（taxid_whitelist，表单）	不挂	入口一	结构化录入，表单更稳
remove-whitelist	不挂	row（taxid_whitelist，预填税号）	不挂	入口一	同上
health / version / config-path	不挂	不挂	不挂	N/A	运维诊断，仅 skill-detail

整技能无 cron placement：TUTORIAL.md 入口三已声明"不需要定时"及理由。

0.2 AI + RPA 协作与授权边界

• 本技能无 RPA：不启动浏览器、不操作桌面/手机、不调用外部 HTTP。
• 发票照片 → 结构化字段由 Agent 多模态能力或用户粘贴完成；技能只接收结构化 JSON。
• 目标系统：无外部系统；全部计算在本地 SQLite。
• 禁止路线（全技能适用）：破解 / 逆向 / 私有协议 / 验证码绕过等；本技能不涉及。
• 国税查验接口、OCR API、财务系统对接均为后续扩展，接口到位前预审结果"待人工查验"闭环。

0.3 业务行生命周期

不适用：预审为同步单据计算，无"处理队列"状态机；prereview_reports.verify_status（待查验/已查验通过/已查验不符）仅记录查验回填状态，不承担抢占/重试语义。

1. 文档目标

明确 verify-invoice-default 的研发范围、交付标准与验收要求，作为开发与测试统一依据。

2. 业务背景

全校教职工报销需财务处逐张人工核验票据（真伪、抬头税号、日期逻辑、经费标准），单张 5-8 分钟、退单率高。需要开发 verify-invoice-default：对发票结构化字段自动完成合规预审，输出《初审意见单》（✅/⚠️/❌ 三色清单），把人工审核压缩到秒级并降低退单率。

3. 开发目标

• 解析并校验发票字段 JSON（单张/同批多张，上限 50 张/批）
• 实现四步规则引擎（F1-F4 / V1-V3 / S1-S3 / R1-R3，共 13 条规则）
• 输出结构化 JSON + 写入本地业务表 + 生成《初审意见单》HTML（html/ + render-html）
• 支持查验结果回填、标准库/白名单维护、预审统计
• 失败可诊断（稳定错误码 ERROR:<CODE>: + 统一日志）

4. 功能范围

必须实现

• health / version / init-db / config-path（模板基座；run 为模板演示入口，不承载业务）
• prereview（主命令）、prereview-batch-input（async Action）
• render-html / list-reports / show-report / mark-verified
• view-standards / set-standard / list-whitelist / add-whitelist / remove-whitelist / list-holidays / stats
• 业务表 5 张 + _jiangchang_* 中文展示元数据 + 种子数据（标准 8 条、税号 1 条、节假日 12 天）
• assets/actions.json 按 §0.1 定位表声明

可后续扩展

• 国税查验 API 直连、OCR API 集成、财务系统对接（项目余额校验）、PDF 意见单、跨批次连号检测、销方黑名单、定时入口

5. 非功能要求

• 目录结构符合 skill-template 规范；入口统一 scripts/main.py
• 单文件 < 900 行；UTF-8 without BOM；Windows UTF-8 输出兼容
• 机读输出 JSON；错误前缀 ERROR:；主命令 task_start/task_failed 日志齐全，无敏感明文
• 只存发票结构化字段，不存影像与身份证号等个人信息
• 测试离线可过（无网络、无浏览器）

6. 输入输出要求

输入

• invoice_json：发票字段（camelCase，兼容 snake_case/中文键），支持文件路径 / 内联 JSON / stdin
• 上下文：--purpose --project-no --trip-start --trip-end --trip-city --staff-title
• 批量：input/ 目录 JSON 文件（{"invoices": [...], "context": {...}} 或纯数组）

输出

• 成功：stdout JSON（ok/batch_no/count/verdict_counts/reports[]/disclaimer）
• 失败：ERROR:INVOICE_INVALID|INVOICE_INPUT_MISSING|REPORT_NOT_FOUND|VERIFY_INPUT_INVALID|STANDARD_INPUT_INVALID|WHITELIST_INPUT_INVALID|ENTITLEMENT_DENIED|QUERY_FAILED + 中文 message
• 落库：invoice_records、prereview_reports；文件：html/report-{id}.html

7. 依赖的兄弟技能或外部系统

• 无兄弟技能依赖；无外部系统
• requirements.txt：无特有依赖（公共能力由共享 runtime 提供）

8. 不在本次范围内的内容

• 不做自动报销提交、不改财务账务
• 不做发票真伪自动判定（只提示查验 + 回填）
• 不存发票影像；不接 OCR/国税 API/财务系统（扩展项）
• 不兼容旧模板历史结构

9. 验收标准

• 目录结构合规；目录名 = SKILL.md slug = constants.SKILL_SLUG；版本三处一致（SKILL.md/constants/CHANGELOG=1.0.0）
• health / version / init-db 正常；python tests/run_tests.py -v 全绿
• 规则引擎金标准测试覆盖 13 条规则正反例；三种代表性场景（通过/驳回/待确认）真实跑通
• mark-verified 回填"不符"后结论升级驳回；stats 与记录一致
• HTML 意见单生成、可重建、宿主侧栏可预览
• init_db() 写入 _jiangchang_tables/_jiangchang_columns，中文 display_name 完整，test_display_metadata 通过
• assets/actions.json 与 §0.1 定位表、TUTORIAL.md 章节一致
• 发布前 developer_ids 替换为本人匠厂用户 ID；发布后按入口定位表完成宿主多入口验收（含用户体验）

10. 开发注意事项

• cli 只做参数解析；核心逻辑在 service（prereview_service 唯一内核，多入口复用）
• 业务表间禁止 SQLite 外键；时间字段 Unix 秒
• 保留模板演示 cmd_run（POLICY-RPA-003 录屏集成守护要求 service 层保留视频集成令牌）；本技能业务命令不使用录屏
• 修改开发规范时同步 POLICY_MATRIX.md 与对应守护测试

11. 变更记录

日期	版本	变更人	变更内容
2026-09-13	v1.0	开发组	初版：四步规则引擎 + 标准库/白名单/查验回填 + 初审意见单