cykj/shanxia2.0
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
bf0099c2ad2d758c23987cc984b32aadd08e4681
shanxia2.0/docs/business-inventory/03-报销业务明细.md
T

11 KiB
Raw Blame History

报销业务明细清单（shanxia2.0 现状）

版本：v1.0
日期：2026-06-10
依据：docs/sql/shanxia2.0.sql、docs/bx-migration/module-status.md、backend/app/api/bx/、web-admin/src/views/bx/
源系统：shanxia/bx/bx-backend + shanxia/bx/bx-web（独立报销系统）

1. 模块定位

报销（bx）模块负责企业内部备用金与费用报销全流程：费用项目配置、审批工作流、申请/审批、财务发放与冲抵、发票夹额度、附件管理、多角色视图中心。表前缀 bx_*，菜单一级目录「报销管理」/bx。

与运输计划的关系：无直接表关联。运输结算单的「审核→开票→汇款」可借鉴 bx 的工作流、附件与支付模式，但应使用独立的 plan_* 表，不混入 bx_reimburse_*。

2. 技术实现

项 说明
后端入口 backend/app/api/bx/（expense_item、workflow、advance、reimburse、payment、attachment、invoice）
路由聚合 backend/app/api/bx/__init__.py → bx_router
模型/Schema backend/app/models/（bx 表）、backend/app/schemas/bx/
前端 web-admin/src/views/bx/、web-admin/src/api/bx/index.ts
API 前缀 /api/expense-items、/api/workflows、/api/advances、/api/reimburses、/api/payments、/api/attachments、/api/invoices、/api/invoice-wallets、/api/invoice-ledgers
响应协议 { "code": 0, "msg": "success", "data": { ... } }；分页为 rows + total
认证 门户 JWT（不移植原 bx_user）
权限 门户 sys_menu + sys_role

3. 数据表清单（14 张）

表名 说明
bx_expense_item 费用项目（二级树）
bx_workflow_def 工作流定义（按业务类型 advance/reimburse）
bx_workflow_node 工作流审批节点
bx_advance_apply 备用金申请单
bx_advance_approval 备用金审批记录
bx_reimburse_apply 报销申请主表
bx_reimburse_detail 报销费用明细行
bx_reimburse_approval 报销审批记录
bx_reimburse_offset 报销冲抵备用金关联
bx_attachment 附件（多业务类型共用）
bx_invoice 发票档案（按人归属）
bx_invoice_ledger 发票额度流水（入账/删除冲减/报销占用/退回）
bx_reimburse_invoice 报销单与发票可选关联
bx_invoice_wallet_summary 按人额度汇总缓存（总额/已用/余额）

不建表：bx_user、bx_role、bx_menu — 统一使用门户 sys_*。

4. 业务模块明细

4.1 费用项目管理（/bx/expense-item）

API 说明
GET /api/expense-items/tree 费用项目树
GET/POST/PUT/DELETE /api/expense-items/{id} 详情与 CRUD

用途：报销明细行选择费用科目；树形二级结构（一级/二级费用项）。

4.2 工作流配置（/bx/workflow/advance、/bx/workflow/reimburse）

API 说明
GET /api/workflows/ 分页列表
GET /api/workflows/biz/{biz_type} 按业务类型（advance / reimburse）
GET/POST/PUT/DELETE /api/workflows/{id} 定义 CRUD
PUT /api/workflows/{id}/nodes 保存节点列表

节点能力：多级审批人、顺序步骤；备用金与报销单分别配置一套工作流。

4.3 备用金（/bx/advance）

4.3.1 备用金申请（/bx/advance/apply）

能力 API 要点
我的申请 GET /api/advances/my
列表/详情 GET /api/advances/、GET /api/advances/{id}
新增/更新/删除 POST/PUT/DELETE
提交审批 POST /api/advances/{id}/submit
统计 GET /api/advances/my/stats、stats/status-counts

4.3.2 备用金审批（/bx/advance/approve）

能力 API 要点
待我审批 GET /api/advances/pending-approval
我已审批 GET /api/advances/approved-by-me
审批通过/驳回 POST .../approve、POST .../reject
审批记录 GET /api/advances/{id}/approvals

4.3.3 备用金发放（/bx/advance/issue）

能力 API 要点
发放列表 GET /api/payments/advance-issues
发放操作 POST /api/payments/advance/{advance_id}/issue
统计/导出 stats、export CSV

状态闭环：草稿 → 提交 → 审批中 → 已通过/已驳回 → 已发放。

4.4 报销单（/bx/reimburse）

4.4.1 报销申请（/bx/reimburse/apply）

能力 API 要点
自动生成标题 GET /api/reimburses/generate-title
我的申请/列表/详情 GET /my、GET /、GET /{id}
含明细保存 POST/PUT 主表 + bx_reimburse_detail
提交/删除/撤回 submit、DELETE、POST /{id}/withdraw
关联发票 create/update/submit 可传 invoiceIds（可选关联，不核销票面）
统计 my/stats、stats/status-counts

额度规则：提交时按报销合计扣减本人发票余额（全额占用，余额允许为负；不足不拦截，可后续在发票夹补票回升）；审批驳回或本人撤回时退回额度。发票上传在「我的发票夹 / 发票夹管理」，申请单不再本地上传发票。详见 docs/superpowers/specs/2026-08-12-reimburse-allow-negative-invoice-balance-design.md。

4.4.2 报销审批（/bx/reimburse/approve）

能力 API 要点
待我审批 / 已审批 同备用金模式
审批通过/驳回 approve、reject（驳回退回发票额度）
审批记录 GET /api/reimburses/{id}/approvals
详情 展示可选关联发票列表

4.5 发票夹（/bx/invoice-wallet-*）

入口 权限 说明
发票夹管理 bx:invoiceWallet:admin 按员工查看额度汇总；可代传/删除发票
我的发票夹 bx:invoiceWallet:mine 本人上传发票；看总额/已用/余额与流水
API 说明
GET /api/invoice-wallets/mine/summary 本人额度汇总
GET /api/invoice-wallets 管理员分页看各人员汇总
GET/POST /api/invoices 发票列表 / 上传（multipart：file+amount）
DELETE /api/invoices/{id} 仅管理员；冲减总额且余额不可为负
GET /api/invoice-ledgers 额度流水

记账模型：流水账本 + 发票档案；InvoiceLedgerService 为额度唯一写入入口。同一张发票可关联多笔报销（仅关联，不做票面核销）。

4.6 支付管理（/bx/payment）

能力 API 要点
待支付报销 GET /api/payments/pending
报销发放 POST /api/payments/{id}/pay
冲抵备用金 POST /api/payments/{id}/offset、batch-offset
已处理列表 GET /api/payments/processed
财务统计 GET /api/payments/stats
冲抵记录查询 offset-records（报销侧、备用金侧）

业务含义：审批通过的报销单进入财务待支付；发放时可选择冲抵已发备用金。

4.7 附件（/api/attachments）

API 说明
POST /upload multipart 上传（biz_type、biz_id）
GET /download/{id} 下载
GET /preview/{id} 预览 URL
GET /list 按业务单列表
PUT /bind-biz 绑定到业务单
DELETE /{id} 软删除

biz_type 示例：reimburse_apply、advance_issue 等；存储走 MinIO 路径。

4.8 视图中心（/bx/view）

页面 说明
我的申请单 /bx/view/mine 聚合当前用户备用金+报销
待我审批 /bx/view/todo 待办审批入口
全部申请单 /bx/view/all 总经理全量视图

5. 前端菜单（sys_menu）

报销管理 /bx
├── 基础配置 /bx/config
│   ├── 费用项目管理
│   ├── 工作流配置（备用金）
│   └── 工作流配置（报销单）
├── 备用金 /bx/advance
│   ├── 备用金申请
│   ├── 备用金审批
│   └── 备用金发放管理
├── 报销 /bx/reimburse
│   ├── 报销申请
│   ├── 报销审批
│   ├── 支付管理（发放/冲抵）
│   ├── 发票夹管理
│   └── 我的发票夹
└── 视图中心 /bx/view
    ├── 我的申请单
    ├── 待我审批
    └── 全部申请单（总经理）

按钮级权限示例：bx:advanceApply:submit、bx:payment:pay、bx:reimburseApprove:approve、bx:invoiceWallet:admin、bx:invoiceWallet:mine 等。

6. 典型业务闭环

6.1 备用金

配置费用项目 + 工作流
    → 员工申请备用金
    → 提交
    → 多级审批（通过/驳回）
    → 财务发放
    → （可选）后续报销冲抵

6.2 报销

员工/管理员上传发票入发票夹（增加额度）
    → 员工填写报销单（多明细行 + 可选关联发票）
    → 提交（全额扣减发票余额，可为负；不足不拦截）
    → 多级审批（驳回/撤回退回额度）
    → 财务支付（可冲抵备用金）

7. 移植完成度

阶段 内容 状态
DDL 14 张 bx_* 表（含发票夹 4 张） ✅
P0 ORM + Router 骨架 ✅
P1 费用项目 + 工作流 ✅
P2 备用金 + 附件 ✅
P3 报销 ✅
P4 支付/发放/冲抵 ✅
P5 sys_menu ✅
P6 前端拷贝 + 门户适配 ✅（含 bx-mobile P1–P3）
P6-FM Fresh Mint UI 深度对齐 ⬜ 未开始
P7 发票夹额度 + 报销扣减 ✅

8. 与其他模块关系

模块 关系
CRM 无表级外键；业务附件文件名可能含合同/报价 PDF
地磅 无集成
运输计划 无集成；结算审核可参考 bx 工作流设计
门户系统 用户/角色/菜单/登录完全依赖 sys_*

9. 不在范围项

项 说明
bx-mobile 移动端 已适配 shanxia2.0：门户鉴权、核心单据、发票夹、撤回/代申请/标题/审批历史、费用项与工作流配置（与 Web 业务结果对齐；不含用户/角色/菜单管理）
历史数据迁移 方案外，空库启动
原 bx 独立用户体系 已废弃

10. 参考路径

文档/代码 路径
移植方案 docs/bx-migration/00-migration-plan.md
API 清单 docs/bx-migration/01-api-inventory.md
模块状态 docs/bx-migration/module-status.md
SQL docs/sql/shanxia2.0.sql（bx_* 段）
原系统 shanxia/bx/bx-backend、shanxia/bx/bx-web
Reference in new issue View Git Blame Copy Permalink