wandering
64bbe53e71
文档一直写着「地址来自 scripts/data/config.json」，但 config.py 读 URL 只看环境变量与内置默认， 根本不读这个文件；本地那份还是改造前的旧文件，三个 URL 键是示例占位假值，还带着早已删除的 consumable_storage / attachment_dir。修法是让文档变成真的： - 优先级：环境变量 > config.json > src/config.py 内置默认；值统一 strip；坏 JSON 或缺文件不抛，退回默认并告警 - 含 your- 的占位值按未配置处理并 WARNING：优先级一改这些假地址就会立刻生效并把登录打挂，这条守卫 是本改动自身的安全带（老文件实测：三条 WARNING 后回落到内置默认，登录不受影响） - 凭据只从文件读（宿主清洗子进程的敏感环境变量，靠 env 传密码不可靠）；新增 safe_config() 作为唯一 可进日志的视图，load_config() 含明文密码 - 清死代码：SAFE_CONFIG_KEYS、attachment_dir（Web 时代遗留，全项目零引用） - config.example.json 补五个可选 URL 键（留空=用默认）；.env.example 的示例赋值全部注释掉—— env 优先级最高，整份复制出去会真拿 your-sso-url 去登录 - 本地 scripts/data/config.json 去掉 7 个陈旧键，只留凭据；改前备份为 config.json.bak-20261020 - 测试 tests/test_config.py 3 → 9 例：文件覆盖默认 / env 覆盖文件 / 占位忽略 / strip / 凭据不读 env / safe_config 无密码 / 坏文件 / 缺文件 / 返回副本 / 示例文件不得再含 your- 假值；全部指向 tmp 不碰真凭据 - 文档：操作指南写清三级优先级与占位语义，scripts/data/README 补字段表，AGENTS 增加配置优先级约束， 方案文档 §14 记录并划掉 §13.4 对应未完成项 验证：ruff / format --check / mypy src / deptry 全绿，pytest 141 passed，mcp_smoke 25 工具； load_config() 实测无 WARNING 且 URL 与凭据取值正确。--no-verify 提交并手跑等价检查。
305 lines
14 KiB
Markdown
305 lines
14 KiB
Markdown
---
|
||
last_reviewed: 2026-10-19
|
||
---
|
||
|
||
# 阜阳师范大学财务报销系统 - 自动化操作指南
|
||
|
||
> 适用场景：日常报销录入。入口是 MCP 服务器，编排由宿主 Agent（如 DSH）完成；工具参数表见 [MCP.md](./MCP.md)。
|
||
> 本文讲财务侧口径、页面要素与材料要求。文中账号、卡号、姓名一律是占位示例——**真实值不要写进仓库任何位置**。
|
||
|
||
---
|
||
|
||
## 一、系统概览
|
||
|
||
```
|
||
信息门户(SSO登录) → 财务系统入口 → 单点登录页 → 网络报销 → 日常报销录入
|
||
(tyrz.fynu.edu.cn) (点击「财务系统」) (新标签页) (a:has(img)) (/expen/common/common)
|
||
```
|
||
|
||
| 系统 | 地址 | 说明 |
|
||
|------|------|------|
|
||
| SSO 登录 | `https://tyrz.fynu.edu.cn/sso/login` | 统一认证入口 |
|
||
| 信息门户 | `https://tyrz.fynu.edu.cn/oshall` | 登录后跳转目标 |
|
||
| 报销系统 | `http://<财务系统内网地址>:8081` | 网络报销主系统 |
|
||
| 日常报销录入 | `/expen/common/common?v=4.0` | 普通报销目标页 |
|
||
| 差旅报销 | `/expen/travel/travel?v=4.0` | 差旅报销目标页 |
|
||
|
||
取值优先级：**环境变量 > `scripts/data/config.json` > `src/config.py` 内置默认**。
|
||
环境变量名是 `SSO_LOGIN_URL` / `PORTAL_URL` / `REIMBURSE_URL` / `REIMBURSE_PAGE` / `TRAVEL_PAGE`
|
||
（见 `.env.example`；项目**不会**自动读 `.env` 文件，要自己 export 或写进宿主的 MCP env）。
|
||
配置文件里这几项**可以不写**；写了占位假值（含 `your-`）会被当成没配并打 WARNING，不会拿去登录。
|
||
|
||
---
|
||
|
||
## 二、使用方式
|
||
|
||
没有 Web 界面，也没有 CLI 产品入口。准备三步，之后全部在 Agent 对话里完成：
|
||
|
||
1. **注册 MCP 服务器**到宿主：`python -m src.mcp.server`（stdio），DSH 的 patch 写法见 `docs/MCP.md`
|
||
2. **配好** `scripts/data/config.json`（参考根目录 `config.example.json`）
|
||
3. **要手机拍照上传时**启动收件器：`make upload`（默认 `0.0.0.0:5055`）
|
||
|
||
自检：`make mcp-smoke` 会真起 stdio 子进程握手并列出 25 个工具。
|
||
|
||
---
|
||
|
||
## 三、材料准备
|
||
|
||
| 材料 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| 发票 PDF / 图片 | 是 | 电子发票尽量给 PDF：有文本层，准确率明显高于读图 |
|
||
| 支付截图 | 是 | 公务卡刷卡记录；要能看清**商户**、日期、金额、卡号后四位 |
|
||
| 出差事前申请单 | 差旅必需 | 缺它财务不认，Agent 会主动索要 |
|
||
| 其他附件 | 视情况 | 会议通知、合同等 |
|
||
|
||
### 发票类型分流
|
||
|
||
| 类型 | 判断依据 | 产物 | 报销流程 |
|
||
|------|----------|------|----------|
|
||
| 差旅发票 | 高铁票、机票、酒店住宿等 | 不生成申购单 | 差旅报销（含按人按天补助） |
|
||
| 普通发票 | 其他（办公用品、耗材、元件等） | 低值易耗品**申购单** | 普通报销（一条总明细 + 逐笔支付） |
|
||
|
||
> Word 版「易耗品出库单」已下线：模板自 2026-08-31 起不在仓库，那条路径此前一直静默失败。
|
||
|
||
---
|
||
|
||
## 四、Agent 操作流程
|
||
|
||
| 步 | 做什么 | 用什么 |
|
||
|----|--------|--------|
|
||
| 1 | 建会话，拿到手机上传页地址 | `case_create` |
|
||
| 2 | 材料入库（本地路径用正斜杠；手机上传后用 `source="inbox"` 收取） | `case_add_files` |
|
||
| 3 | 渲染页面与文本层 | `case_render_pages` → `case_read_text` 或直接读 PNG |
|
||
| 4 | 逐张抽取落盘；核对后局部修正 | `case_save_extraction` / `case_patch_extraction` |
|
||
| 5 | 金额匹配，**逐条处理 `review_required`** | `match_payments` |
|
||
| 6 | 取骨架 → 填值 → 落盘校验（试算用 `validate_info` 不落盘） | `info_skeleton` → `save_info` |
|
||
| 7 | 普通发票生成申购单（`exclude` 剔除不参与申购的物品） | `doc_requisition` |
|
||
| 8 | 随时复查态势；要重跑就清派生产物 | `case_status` / `case_reset` |
|
||
| 9 | 填报（可选）：开浏览器 → 登录 → 建单 → 按步填 → 复查 → 关 | `browser_open` → `browser_login` → `browser_new_form` → `browser_fill` → `browser_page_state` → `browser_close` |
|
||
|
||
### 填报这段要注意
|
||
|
||
- 浏览器默认**有头**：提交不可逆，得看得见在点什么；期间别手动点页面
|
||
- `browser_login` 返回 `need_human` 时，人在已经打开的那个窗口里扫码或输验证码，然后**重调 `browser_login`**
|
||
——不要另开浏览器。`cases/<id>/.browser.lock` 记着谁拥有它，返回 `owned_by_other_process` 就等对方释放
|
||
- `travel_info` 与 `normal_info` 同时存在时，`browser_new_form` 必须显式传 `kind`（混合发票只能走普通报销）
|
||
- 步骤不能跳：travel 是 basic/details/payment/subsidy/attachments，normal 没有 subsidy
|
||
- 每步截图按 `001-步骤名.png` 落在 `cases/<id>/screenshots/`；失败时截图路径在返回的 `detail.screenshot`
|
||
- **`browser_close` 不提交也不存草稿**，填了一半会丢；提交本身仍未实现（P4），必须人工核对后自己点
|
||
- 中途断了不必重来：重新开浏览器登录后用 `browser_open_form`（先 `preview_only=true` 核对**单据编号**，
|
||
命中多张会直接拒绝）从列表页找回原单续填；**别再 `browser_new_form`**，那会多建一张单
|
||
- 列表页那个「查看」按钮是看审批流程图，不是打开单据；要接着填是选中行后点「修改」
|
||
|
||
**`ok: true` 的含义有限**：`match_payments` 成功只代表贪心跑完。一对多凑额、发票总额小于支付总额、
|
||
未匹配项都会进 `review_required`，必须逐条确认——等额发票尤其容易配错。
|
||
|
||
**什么时候算完成**：`validate_info` 报告 `valid: true` 且无业务约束违反。缺料就向用户要材料；
|
||
Agent 不许自己宣布「可以提交了」。
|
||
|
||
### 产物位置
|
||
|
||
全部在 `cases/<case_id>/`（整个目录已 gitignore，含身份证号与卡号）：
|
||
|
||
| 产物 | 说明 |
|
||
|------|------|
|
||
| `pages/<票据>/p01.png` | 渲染页面（已按文本方向自动转正） |
|
||
| `.invoice_cache/*.json` | 单张票据结构化数据 |
|
||
| `match_result.json` / `invoice_groups.json` | 匹配与分组结果 |
|
||
| `invoice_summary.csv` / `payment_records.csv` | 发票级与支付级汇总 |
|
||
| `travel_info.json` / `normal_info.json` | 填报所需的完整结构化数据 |
|
||
| `artifacts/低值易耗品申购_<case>.xls` | 申购单，拿去资产/财务口径核对 |
|
||
|
||
---
|
||
|
||
## 五、页面元素速查
|
||
|
||
### 基本信息页
|
||
|
||
| 字段 | 选择器 | 操作 |
|
||
|------|--------|------|
|
||
| 报销说明 | `#EXPENEXPLAIN` | fill |
|
||
| 项目代码 | `#PROJECTCODE` | click → 弹窗选择 |
|
||
| 项目弹窗 | `#promodal .fixed-table-body tbody tr` | 点击第一行 |
|
||
| 下一步按钮 | `#saveAndNext` | click |
|
||
|
||
### 报销明细页
|
||
|
||
| 字段 | 选择器 | 操作 |
|
||
|------|--------|------|
|
||
| 增加按钮 | `#insertDetail` | click |
|
||
| 经济事项代码 | `#economicscode2` | click → 弹窗选择 |
|
||
| 经济科目弹窗 | `#econmodal .fixed-table-body tbody tr` | 点击第 3 行 |
|
||
| 单据数 | `input[name="expenPwCommondetail.HOWBILLS"]` | fill |
|
||
| 报销总金额 | `#je_zwzcdz` | fill |
|
||
| 确定按钮 | `#detailAdd` | click |
|
||
|
||
### 支付方式页
|
||
|
||
| 字段 | 选择器 | 操作 |
|
||
|------|--------|------|
|
||
| 增加按钮 | `#insertPay` | click |
|
||
| 人员编号 | `#personid2` | fill |
|
||
| 人员姓名 | `#accountname2` | fill |
|
||
| 刷卡日期 | `#receiptdate2` | fill |
|
||
| 公务卡号 | `#localaccount2` | fill |
|
||
| 刷卡金额 | `#receiptmoney2` | fill |
|
||
| 实报金额 | `#money2` | fill |
|
||
| 商户 | `#merchant2` | fill |
|
||
| 备注 | `#smark2` | fill |
|
||
| 确定按钮 | `#payAdd` | click |
|
||
|
||
### 附件清单页
|
||
|
||
| 字段 | 选择器 | 操作 |
|
||
|------|--------|------|
|
||
| 增加按钮 | `#insertAcc` | click |
|
||
| 附件类型 | `#fjlx` | select_option → 1（发票） |
|
||
| 附件说明 | `#fpsmxx` | fill |
|
||
| 文件上传 | `#file` | set_input_files |
|
||
| 确定按钮 | `#cjtj` | click |
|
||
|
||
### 提交
|
||
|
||
| 操作 | 选择器 |
|
||
|------|--------|
|
||
| 提交按钮 | `#submit` |
|
||
| 提交按钮（备用） | `#submit2` |
|
||
|
||
---
|
||
|
||
## 六、数据流向
|
||
|
||
```
|
||
材料（PDF / 图片）
|
||
│ case_render_pages：页面 PNG + 文本层 + 自动转正
|
||
▼
|
||
宿主 Agent 读图与判断 ← 本项目不调用任何模型
|
||
│ case_save_extraction（schemas.py 规范化日期与金额）
|
||
▼
|
||
.invoice_cache/*.json
|
||
│ match_payments（分组 + 一对一/一对多贪心 + 业务约束）
|
||
▼
|
||
match_result.json / invoice_groups.json / 两份 CSV
|
||
│ info_skeleton → 填值 → save_info（声明式规则校验）
|
||
▼
|
||
travel_info.json 或 normal_info.json
|
||
│ doc_requisition（Excel COM，仅普通发票）
|
||
▼
|
||
artifacts/ 申购单
|
||
│ browser_open → browser_login → browser_new_form → browser_fill（提交仍未实现，须人工）
|
||
▼
|
||
财务系统报销单
|
||
```
|
||
|
||
---
|
||
|
||
## 七、关键设计说明
|
||
|
||
### 7.1 浏览器启动
|
||
|
||
Playwright `sync_playwright()` 启动 Chromium，**默认有头**（`headless=False`）——提交不可逆，得看清楚在点什么。
|
||
SSO 需要扫码或验证码时人工完成即可，流程会继续。每次运行都要重新登录。
|
||
|
||
### 7.2 明细录入策略
|
||
|
||
普通报销用「一条总明细」：所有发票合并成一条，报销总金额 = 各笔支付之和，单据数 = 发票张数；
|
||
支付方式逐笔录入，一笔一条。差旅按人去程/返程分条录交通费，补助按人按天算。
|
||
|
||
### 7.3 经济科目与项目
|
||
|
||
经济科目弹窗固定选第 3 行（`rows[2]`），项目弹窗固定选第 1 行。要改就改这两个索引，
|
||
位置在 `src/infra/browser/travel.py` 与 `normal.py`。
|
||
|
||
### 7.4 网络报销链接动态获取
|
||
|
||
单点登录页的「网络报销」链接参数每次不同，因此用 `a:has(img[src*="wlbx"])` 定位并读 `href`，不硬编码 URL。
|
||
|
||
### 7.5 手机上传
|
||
|
||
收件器是**独立进程**：`case_create` 返回带令牌的手机页地址，上传落 `cases/<id>/inbox/`，
|
||
再由 Agent 调 `case_add_files(source="inbox")` 收取。它只写不读（没有列表也没有下载路由）、令牌强制、
|
||
扩展名白名单、25MB/文件、200 文件/会话。旧 Web 的「PC 端轮询同步」已删除。
|
||
|
||
---
|
||
|
||
## 八、配置说明
|
||
|
||
`scripts/data/config.json`（已在 `.gitignore`，**永远不要提交**）：
|
||
|
||
```json
|
||
{
|
||
"username": "<工号>",
|
||
"password": "<密码>",
|
||
"default_name": "<报销人姓名>",
|
||
"default_card_no": "<公务卡号>",
|
||
"default_person_id": "<人员编号>",
|
||
"upload_pin": "<手机上传访问码，可留空>"
|
||
}
|
||
```
|
||
|
||
| 字段 | 用途 |
|
||
|------|------|
|
||
| `username` / `password` | 信息门户登录 |
|
||
| `default_name` | 支付方式的「人员姓名」 |
|
||
| `default_person_id` | 支付方式的「人员编号」 |
|
||
| `default_card_no` | 支付方式的「公务卡号」 |
|
||
| `upload_pin` | 上传收件器访问码（等价 `--pin` 或环境变量 `UPLOAD_PIN`） |
|
||
|
||
URL 类字段（`sso_login_url`、`portal_url`、`reimburse_url`、`reimburse_page`、`travel_page`）有内置默认值，
|
||
需要才配；配了就生效（早先版本这里写了也不读，已修）。想临时改地址用环境变量更方便，不用动文件。
|
||
凭据不放环境变量：DSH 会清洗 stdio 子进程里含 KEY/PASSWORD/SECRET/TOKEN 的变量。
|
||
|
||
校验规则在 `config/validation_rules.json`；改规则要同步跑测试（骨架与规则有一致性用例）。
|
||
|
||
---
|
||
|
||
## 九、日志与排查
|
||
|
||
- 控制台 + `logs/<日期>.log`（UTF-8）。**没有 SSE 或任何长连接事件流**，进度靠 `case_status` 查
|
||
- 浏览器调试截图在 `images/`（已 gitignore）；P3 之后过程截图进 `cases/<id>/screenshots/NNN-<step>.png`
|
||
- 超时：页面默认 30 秒、门户登录 30 秒、单点登录页 15 秒
|
||
- 排查顺序：`case_status` → `match_result.json` → 某张 `.invoice_cache/*.json` → `logs/<日期>.log`
|
||
|
||
---
|
||
|
||
## 十、常见问题
|
||
|
||
| 问题 | 原因 | 解决 |
|
||
|------|------|------|
|
||
| 登录超时 | SSO 要扫码或验证码 | 有头模式下人工完成，流程会继续 |
|
||
| 未找到财务系统入口 | 门户页面结构变了 | 看 `images/debug_*` 截图定位选择器 |
|
||
| 经济科目选择失败 | 弹窗加载延迟 | 增大等待，或调整点第几行的索引 |
|
||
| 金额不匹配 | 明细合计 ≠ 支付合计 | 复核 `match_result.json` 与 `review_required` |
|
||
| 附件上传失败 | PDF 路径不对 | 材料要在 `cases/<id>/` 下，路径用正斜杠 |
|
||
| 宿主看不到新增工具 | 旧 stdio 子进程还在跑旧代码 | 杀掉子进程，DSH 会自动重启并重同步工具 |
|
||
| 报「binding arguments must be lossless JSON」 | Windows 路径用了反斜杠 | 改成 `D:/Code/...` |
|
||
| 手机上传 403 | URL 缺令牌或令牌不对 | 用 `case_create` 返回的完整地址 |
|
||
| 抽取字段读错（编号/卡号/金额位数） | 文本层与读图本来就会冲突 | 放大该区域重看，两路都不许默认采信 |
|
||
| 申购单生成失败 | 未装 Excel 或 pywin32；或有弹窗未关 | 需要 Windows + Excel，人工关掉残留 Excel 窗口再试 |
|
||
| 浏览器起不来 | 没装 Chromium | `uv run playwright install chromium` |
|
||
| 返回 `owned_by_other_process` | 上一代 MCP 子进程还占着浏览器 | 让持有者 `browser_close`；心跳超 180 秒自动接管 |
|
||
| 登录一直不跳转 | SSO 要扫码或有验证码 | 看返回的 `need_human` 与截图，人工完成后重调 `browser_login` |
|
||
| 某一步 fill 失败 | 选择器没命中或页面慢 | 看返回 `detail.screenshot` 的截图，人工看一眼再重填该步 |
|
||
|
||
---
|
||
|
||
## 十一、相关命令
|
||
|
||
```bash
|
||
make check # ruff + format + mypy src + deptry
|
||
make test # pytest + 覆盖率
|
||
make mcp-smoke # MCP stdio 自检
|
||
make upload # 启动扫码上传收件器
|
||
|
||
# 不经 MCP 单独重生成申购单（调试用）
|
||
uv run python -m src.infra.documents.requisition --session cases/<case_id> --exclude 千斤顶
|
||
```
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [docs/MCP.md](./MCP.md) — 25 个工具的参数与返回约定
|
||
- [.agents/skills/reimbursement/SKILL.md](../.agents/skills/reimbursement/SKILL.md) — 宿主 Agent 的操作纪律
|
||
- [AGENTS.md](../AGENTS.md) — 开发约束与踩坑记录
|