# 财务对账中心 — 运维手册

## 1. 汇联易实际账拉取(`finance.huilianyi_actuals_sync`)激活步骤

该 cron **默认禁用**(migration 297 seed `enabled=0`)。汇联易 expense 开放
API 无法在 CI 真调、字段名离线不可定,故拉取逻辑做成防御式(端点/字段可
覆盖、原始留存、无权限优雅跳过),需经下列校验后再启用。

### 1.1 前置:汇联易开放平台「开通」读接口(已实测定位)
现有 `identity_sync_huilianyi` 连接器(身份推送,权限ID/client_id =
`7365ef54-af5b-41f3-823a-04ff4b92bb65`)目前只开通了 `/oauth/token` + 部门/员工
增删改查。财务读接口**全部未开通**,需到汇联易后台开通:

**路径**:汇联易后台 → 系统对接 → **开放权限**(`/main/setting/open-api-authority`)
→ 「Helix 身份同步」→ 详情/编辑 → 左侧按类别筛选 → 对下列接口点「开通权限」
(或勾选后「批量开通」)。

**最小必需(代码 `_DEFAULT_PATHS` 就调这两个)**:

| 类别 | 接口名称 | URL | 方式 |
|---|---|---|---|
| 报销单 | 报销单明细增量查询 | `/api/open/expenseReport` | GET |
| 成本中心 | 查询成本中心列表 | `/api/open/costCenter` | GET |

**建议一并开通(成本中心权威化 PR-C 更全)**:

| 类别 | 接口名称 | URL | 方式 |
|---|---|---|---|
| 成本中心 | 成本中心查询(项增量) | `/api/open/costCenterItem/incremental` | GET |
| 成本中心 | 成本中心项查询用户列表 | `/api/open/costCenterItem/users` | POST |

- **只开 GET/查询类**;不要开 POST/PUT 审批/付款写接口(Helix 财务只读)。
  `/oauth/token` 已开通,无需动。
- 若报销单详情/发票/付款状态不在「报销单明细增量查询」响应内(dry-run 会暴露),
  再到「报销单 / 发票 / 付款」类别按需开通对应 GET 接口,并在连接器 `config_public`
  覆盖端点路径(`finance_expense_report_path` / `finance_cost_center_path`)。
- **不要**在代码里建凭证;授权在汇联易后台界面由人点「开通权限」提交。

### 1.2 校验字段映射(dry-run)
真实 expense JSON 字段名以汇联易租户为准,首次必须 dry-run 验证:
```python
# 在 server 容器内 python shell:
from app.core.database import async_session_factory
from app.core.coordinators import finance_huilianyi_coordinator as hly
import asyncio
async def main():
    async with async_session_factory() as db:
        print(await hly.pull_actuals(db, "2026-05", dry_run=True))   # 报销单
        print(await hly.sync_cost_centers(db, dry_run=True))          # 成本中心
asyncio.run(main())
```
- 看 `sample` 里 `cost_center / cat / amount_usd / promote` 是否正确。
- 字段名不对(`rows=0` 但应有数据,或字段空):对照返回的 `raw`,在连接器
  `config_public` 覆盖端点路径(`finance_expense_report_path` /
  `finance_cost_center_path`),或在 `_pick(...)` 候选键里补真实字段名(改码 PR)。
- `skipped=read_failed` → 读权限没授全,回到 1.1。

### 1.3 调费用类型提升白名单
- 平台设置 `finance.huilianyi.promote_categories`(JSON 数组)= 应**计入统一
  账层**的**非 IT** 费用类型(差旅/餐饮/办公…),默认见
  `_DEFAULT_PROMOTE_CATEGORIES`。
- **务必保守**:把 IT 类(SaaS/云/采购发票)留在白名单外 →`promote=False`
  只对账,避免与 Helix 内部云/软件/AI/采购口径双算。
- 用 dry-run 的 `sample` 核对 `promote` 标记,确认无 IT 类被误提升。

### 1.4 启用 cron
确认字段映射 + 白名单无误后,在 `/admin/scheduled-jobs` 把
`finance.huilianyi_actuals_sync` 置 `enabled`。每日增量拉当月+上月 + 成本中心
主数据,落 `finance_external_statements` / `finance_cost_centers`。

## 2. 排障
- **总览/对账数突变**:先看该期间 `finance_external_statements` 行 `raw`,确认
  汇联易侧单据状态/金额;再看是否新费用类型被误提升(`promote_to_ledger`)。
- **某成本中心钱对不上**:内部 `finance_spend_facts`(应花)vs 外部
  `finance_external_statements`(实际)口径本就不同——外部含报销/差旅,内部含
  消费分摊;差异面在「外部比对」页,不是 bug。
- **拉取报 read_failed**:汇联易开放平台读权限被回收 / app 失效,回 1.1。