133 lines
8.1 KiB
Markdown
133 lines
8.1 KiB
Markdown
# 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 | 开发组 | 初版：四步规则引擎 + 标准库/白名单/查验回填 + 初审意见单 |
|