470 lines
17 KiB
Markdown
470 lines
17 KiB
Markdown
# 报销系统（bx）移植实施方案
|
||
|
||
> **编写日期**：2026-06-06
|
||
> **状态**：方案已定稿，待按阶段实施
|
||
> **源系统**：`shanxia/bx/bx-backend` + `shanxia/bx/bx-web`
|
||
> **目标系统**：`shanxia2.0/backend` + `shanxia2.0/web-admin`
|
||
> **DDL 基线**：`docs/sql/20260606_bx_tables.sql`（已在 shanxia2.0 库执行）
|
||
|
||
---
|
||
|
||
## 1. 迁移目标
|
||
|
||
将原报销系统业务功能迁入山峡一体化门户（shanxia2.0），实现：
|
||
|
||
1. **业务等价**：备用金、报销、工作流、支付/冲抵、视图中心等能力与 bx 原系统一致；
|
||
2. **协议兼容**：移植 API 保持 bx 原 **REST 风格**（GET/PUT/DELETE/POST）、**入参位置**、**响应 envelope**（`code:0`、`msg`、`data.rows`），**不**统一为 CRM 的 POST Body 风格；
|
||
3. **体系融合**：用户/角色/菜单/认证使用门户 `sys_*`，业务表使用 `bx_*` + 门户公共字段；
|
||
4. **UI 融合**：Web 端挂「报销管理」一级菜单，页面适配 Fresh Mint 规范（第二阶段）。
|
||
|
||
**不在本次范围**：`bx-mobile` 移动端、`bx_user/bx_role/bx_menu` 等独立权限表、历史业务数据导入（空库启动）。
|
||
|
||
---
|
||
|
||
## 2. 范围边界
|
||
|
||
### 2.1 数据库（10 张业务表，已完成 DDL）
|
||
|
||
| 表 | 用途 | DDL 状态 |
|
||
|----|------|---------|
|
||
| `bx_expense_item` | 费用项目（二级树） | ✅ |
|
||
| `bx_workflow_def` | 工作流定义 | ✅ |
|
||
| `bx_workflow_node` | 工作流节点 | ✅ |
|
||
| `bx_advance_apply` | 备用金申请 | ✅ |
|
||
| `bx_advance_approval` | 备用金审批记录 | ✅ |
|
||
| `bx_reimburse_apply` | 报销申请 | ✅ |
|
||
| `bx_reimburse_detail` | 报销明细 | ✅ |
|
||
| `bx_reimburse_approval` | 报销审批记录 | ✅ |
|
||
| `bx_reimburse_offset` | 冲抵关联 | ✅ |
|
||
| `bx_attachment` | 附件 | ✅ |
|
||
|
||
**不建表**：`bx_user`、`bx_role`、`bx_role_user`、`bx_menu`、`bx_menu_role`。
|
||
|
||
### 2.2 后端 API（约 60 个端点，待移植）
|
||
|
||
| 模块 | 源文件 | 端点数 | 优先级 |
|
||
|------|--------|--------|--------|
|
||
| 费用项目 | `routers/expense_item.py` | 5 | P1 |
|
||
| 工作流 | `routers/workflow.py` | 8 | P1 |
|
||
| 备用金 | `routers/advance.py` | 14 | P2 |
|
||
| 附件 | `routers/attachment.py` | 6 | P2 |
|
||
| 报销 | `routers/reimburse.py` | 15 | P3 |
|
||
| 支付/发放 | `routers/payment.py` | 12 | P4 |
|
||
|
||
**不移植**：`auth.py`、`user.py`、`role.py`、`menu.py`。
|
||
|
||
### 2.3 前端页面（13 页，第二阶段）
|
||
|
||
| 分组 | 页面 | 源文件 |
|
||
|------|------|--------|
|
||
| 基础配置 | 费用项目管理、工作流（备用金）、工作流（报销） | `ExpenseProjectPage`、`WfAdvancePage`、`WfReimbursePage` |
|
||
| 备用金 | 申请、审批、发放管理 | `AdvanceApplyPage`、`AdvanceApprovePage`、`AdvanceIssuePage` |
|
||
| 报销 | 申请、审批、支付管理 | `ReimburseApplyPage`、`ReimburseApprovePage`、`PaymentPage` |
|
||
| 视图中心 | 我的申请、待我审批、全部申请单 | `MinePage`、`TodoPage`、`AllPage` |
|
||
|
||
**不移植**：用户/角色/菜单管理、首页 Dashboard、Demo 页。
|
||
|
||
---
|
||
|
||
## 3. 核心原则（与 CRM 移植的差异）
|
||
|
||
| 原则 | 说明 |
|
||
|------|------|
|
||
| **API 协议保持 bx 原样** | 列表用 GET + Query；响应 `{ code: 0, msg, data }`；分页 `data.rows`；**禁止**改为门户 `code:200` / `message` / `data.list` |
|
||
| **Router 近原样复制** | 从 `bx-backend/app/routers/` 复制到 `backend/app/api/bx/`，仅改 Depends、import、前缀、租户注入 |
|
||
| **Service 选择性迁移** | `services/*.py` 业务算法可复用；必须加 `tenant_no`、UUID 主键、`sys_user` 用户 ID |
|
||
| **不走 CRM crud 分层** | bx 模块内部保持 `router → service → model`，不强制拆 `crud/bx/`（除非后续维护需要） |
|
||
| **最小改动** | 不重命名 URL、不改 HTTP 方法、不改前端 camelCase 字段名 |
|
||
| **门户能力注入** | 认证、租户、DB Session、对象存储用 shanxia2.0 现有能力 |
|
||
|
||
---
|
||
|
||
## 4. 源系统与目标系统对照
|
||
|
||
### 4.1 技术栈（同源，利于移植）
|
||
|
||
| 项 | bx-backend | shanxia2.0 backend |
|
||
|----|-----------|-------------------|
|
||
| 语言 | Python 3 | Python 3.9 |
|
||
| 框架 | FastAPI | FastAPI |
|
||
| ORM | SQLAlchemy | SQLAlchemy |
|
||
| 校验 | Pydantic v2 | Pydantic v2 |
|
||
|
||
### 4.2 API 协议对照
|
||
|
||
| 维度 | bx 原系统 | shanxia2.0 CRM（勿用于 bx） | bx 移植目标 |
|
||
|------|----------|---------------------------|------------|
|
||
| 成功码 | `0` | `200` | **保持 `0`** |
|
||
| 消息字段 | `msg` | `message` | **保持 `msg`** |
|
||
| 时间戳 | 无 | `timestamp` | **不加** |
|
||
| 分页字段 | `rows, total, page, pageSize` | `list, total, page, pageSize` | **保持 `rows`** |
|
||
| 列表请求 | GET + query | POST + body | **保持 GET** |
|
||
| 路径示例 | `/api/advances/` | `/api/web/crm/customer/list` | **保持 `/api/advances/`** |
|
||
|
||
### 4.3 数据模型对照
|
||
|
||
| 维度 | bx 原 sx.sql | shanxia2.0 已执行 DDL |
|
||
|------|-------------|----------------------|
|
||
| 主键 | `bigint AUTO_INCREMENT` | `varchar(64) UUID` |
|
||
| 外键 ID | `bigint` | `varchar(64)` |
|
||
| 租户 | 无 | `tenant_no DEFAULT 'shanxia2.0'` |
|
||
| 用户引用 | `bx_user.id` | `sys_user.id` |
|
||
|
||
---
|
||
|
||
## 5. 目标架构
|
||
|
||
### 5.1 后端目录结构
|
||
|
||
```
|
||
backend/app/
|
||
├── models/bx_models.py # 10 张表 ORM（对齐 20260606 DDL）
|
||
├── schemas/bx/
|
||
│ ├── common.py # ApiResponse / PagedData（从 bx 复制）
|
||
│ ├── expense_item.py
|
||
│ ├── workflow.py
|
||
│ ├── advance.py
|
||
│ ├── reimburse.py
|
||
│ ├── payment.py
|
||
│ └── attachment.py # id: int → str
|
||
├── services/bx/ # 从 bx-backend/services 迁移
|
||
│ ├── base.py # 可选：通用分页（改 UUID）
|
||
│ ├── expense_item.py
|
||
│ ├── workflow.py
|
||
│ ├── advance.py
|
||
│ ├── reimburse.py
|
||
│ ├── payment.py
|
||
│ └── attachment.py
|
||
├── core/
|
||
│ └── bx_auth.py # 门户 user → BxUserContext
|
||
└── api/bx/
|
||
├── __init__.py # 聚合 bx_router
|
||
├── expense_item.py # prefix="/expense-items"
|
||
├── workflow.py # prefix="/workflows"
|
||
├── advance.py # prefix="/advances"
|
||
├── reimburse.py # prefix="/reimburses"
|
||
├── payment.py # prefix="/payments"
|
||
└── attachment.py # prefix="/attachments"
|
||
```
|
||
|
||
### 5.2 路由挂载（避免 `/api/api/...`）
|
||
|
||
bx 原 router 前缀为 `/api/advances`；门户 `main.py` 已挂 `prefix="/api"`。
|
||
|
||
**规则**：bx router 的 `APIRouter(prefix=...)` **去掉 `/api`**，例如：
|
||
|
||
```python
|
||
# bx 原：prefix="/api/advances"
|
||
# 门户：prefix="/advances"
|
||
router = APIRouter(prefix="/advances", tags=["备用金管理"])
|
||
```
|
||
|
||
```python
|
||
# main.py
|
||
from app.api.bx import bx_router
|
||
app.include_router(bx_router, prefix=settings.API_V1_PREFIX) # → /api/advances/...
|
||
```
|
||
|
||
### 5.3 响应包装（独立体系）
|
||
|
||
bx 模块 **禁止** 使用 `app.core.response.success_response()`。
|
||
|
||
统一使用 `schemas/bx/common.py`：
|
||
|
||
```python
|
||
class ApiResponse(BaseModel, Generic[T]):
|
||
code: int = 0
|
||
msg: str = "success"
|
||
data: Optional[T] = None
|
||
|
||
class PagedData(BaseModel, Generic[T]):
|
||
rows: List[T]
|
||
total: int
|
||
page: int
|
||
page_size: int # JSON 序列化为 pageSize（alias_generator=to_camel）
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 门户适配层
|
||
|
||
### 6.1 认证（`core/bx_auth.py`）
|
||
|
||
bx 原：`get_current_user` → ORM `User`，`user.id: int`
|
||
门户：`require_admin_or_super_admin` → `dict`，`user_id: str`
|
||
|
||
```python
|
||
@dataclass
|
||
class BxUserContext:
|
||
id: str # sys_user.id
|
||
name: str # nick_name 冗余写入 applicant_name 等
|
||
dept_id: str # create_dept_id
|
||
|
||
def get_bx_current_user(user: dict = Depends(require_admin_or_super_admin)) -> BxUserContext:
|
||
...
|
||
```
|
||
|
||
Router 中：`Depends(get_current_user)` → `Depends(get_bx_current_user)`。
|
||
|
||
### 6.2 租户隔离
|
||
|
||
所有业务查询/写入通过 `get_tenant_no(db, user_dict)` 获取 `tenant_no`，在 Service 层追加：
|
||
|
||
```python
|
||
query.filter(Model.tenant_no == tenant_no, Model.del_flag == 0)
|
||
```
|
||
|
||
创建记录时：
|
||
|
||
```python
|
||
obj_in["id"] = generate_uuid()
|
||
obj_in["tenant_no"] = tenant_no
|
||
obj_in["create_by"] = user.id
|
||
obj_in["create_dept_id"] = user.dept_id or ""
|
||
```
|
||
|
||
### 6.3 API 加密中间件
|
||
|
||
门户默认对 `/api/*` 启用 `ApiCryptoMiddleware`；bx 原系统无加密。
|
||
|
||
**开发阶段**：将 bx 业务路径加入 `API_ENCRYPT_EXCLUDE_PATHS`（`backend/app/core/config.py`）：
|
||
|
||
```
|
||
/api/expense-items,
|
||
/api/workflows,
|
||
/api/advances,
|
||
/api/reimburses,
|
||
/api/payments,
|
||
/api/attachments
|
||
```
|
||
|
||
**前端接入 web-admin 后**：评估是否改为走门户加密（需 bx 页 axios 适配），或长期保持 exclude。
|
||
|
||
### 6.4 附件 / MinIO
|
||
|
||
不直接拷贝 `bx-backend/app/services/minio.py`。实现 `services/bx/storage.py` 适配器，内部调用门户已有 OSS/MinIO 上传能力，对外仍暴露：
|
||
|
||
- `POST /api/attachments/upload`（multipart）
|
||
- `GET /api/attachments/download/{id}`（StreamingResponse）
|
||
- `GET /api/attachments/preview/{id}`
|
||
|
||
---
|
||
|
||
## 7. 分阶段实施计划
|
||
|
||
### 总览
|
||
|
||
```
|
||
P0 基础设施 → P1 基础配置 → P2 备用金+附件 → P3 报销 → P4 支付 → P5 菜单 → P6 前端
|
||
│ │ │ │ │ │ │
|
||
ORM/Auth expense+wf advance reimburse payment sys_menu web-admin
|
||
```
|
||
|
||
### P0：基础设施（后端骨架）
|
||
|
||
| 步骤 | 任务 | 产出 | 完成标准 |
|
||
|------|------|------|---------|
|
||
| P0-1 | 创建 `models/bx_models.py` | 10 表 ORM | 字段顺序与 DDL 一致 |
|
||
| P0-2 | 创建 `schemas/bx/common.py` | ApiResponse / PagedData | 与 bx 响应一致 |
|
||
| P0-3 | 创建 `core/bx_auth.py` | BxUserContext + Depends | 能解析门户 JWT 用户 |
|
||
| P0-4 | 创建 `api/bx/__init__.py` | 空 bx_router | main.py 可注册 |
|
||
| P0-5 | 配置加密排除路径 | config 更新 | bx 路径不加密 |
|
||
| P0-6 | 迁移 `utils/codegen.py`、`date_range.py` | 单号生成等 | 单元可调用 |
|
||
|
||
**验收**：服务启动无报错；`GET /api/health` 正常；bx_router 已挂载。
|
||
|
||
---
|
||
|
||
### P1：基础配置（费用项目 + 工作流）
|
||
|
||
| 步骤 | 任务 | 源参考 |
|
||
|------|------|--------|
|
||
| P1-1 | `schemas/bx/expense_item.py` | `bx-backend/app/schemas/expense_item.py` |
|
||
| P1-2 | `services/bx/expense_item.py` | 加 tenant + UUID |
|
||
| P1-3 | `api/bx/expense_item.py` | 5 端点原样 |
|
||
| P1-4 | `schemas/bx/workflow.py` + service + router | 8 端点 |
|
||
|
||
**API 清单**：
|
||
|
||
| 方法 | 路径 |
|
||
|------|------|
|
||
| GET | `/api/expense-items/tree` |
|
||
| GET/POST/PUT/DELETE | `/api/expense-items/`、`/api/expense-items/{item_id}` |
|
||
| GET | `/api/workflows/`、`/api/workflows/biz/{biz_type}`、`/api/workflows/{workflow_id}` |
|
||
| POST/PUT/DELETE | `/api/workflows/`、`/api/workflows/{workflow_id}` |
|
||
| PUT | `/api/workflows/{workflow_id}/nodes` |
|
||
|
||
**验收**：Swagger 可调通 CRUD；费用树、工作流节点保存与原 bx 行为一致。
|
||
|
||
---
|
||
|
||
### P2：备用金 + 附件
|
||
|
||
| 步骤 | 任务 | 说明 |
|
||
|------|------|------|
|
||
| P2-1 | advance schemas / service / router | 含 submit/approve/reject 状态机 |
|
||
| P2-2 | attachment storage 适配 + router | upload/download/preview/bind-biz |
|
||
| P2-3 | 联调：申请 → 上传附件 → 提交审批 | 端到端 |
|
||
|
||
**API 清单（advance，14 端点）**：
|
||
|
||
| 方法 | 路径 |
|
||
|------|------|
|
||
| GET | `/api/advances/`、`/my`、`/my/stats`、`/stats/status-counts` |
|
||
| GET | `/api/advances/pending-approval`、`/pending-approval/stats`、`/approved-by-me` |
|
||
| GET | `/api/advances/{advance_id}`、`/{advance_id}/approvals` |
|
||
| POST | `/api/advances/`、`/{advance_id}/submit`、`/approve`、`/reject` |
|
||
| PUT/DELETE | `/api/advances/{advance_id}` |
|
||
|
||
**验收**：完整备用金审批链路；附件 upload/list/download 可用。
|
||
|
||
---
|
||
|
||
### P3：报销
|
||
|
||
| 步骤 | 任务 |
|
||
|------|------|
|
||
| P3-1 | reimburse schemas（含 detail） |
|
||
| P3-2 | reimburse service（明细、标题生成） |
|
||
| P3-3 | reimburse router（15 端点） |
|
||
|
||
**验收**：报销申请 CRUD + 明细 + 审批流与 bx 一致。
|
||
|
||
---
|
||
|
||
### P4：支付 / 发放 / 冲抵
|
||
|
||
| 步骤 | 任务 |
|
||
|------|------|
|
||
| P4-1 | payment service（最复杂：pay/offset/issue/batch-offset） |
|
||
| P4-2 | payment router（含 CSV export StreamingResponse） |
|
||
|
||
**验收**：报销支付、备用金发放、冲抵关联、offset-records 查询正确。
|
||
|
||
---
|
||
|
||
### P5：菜单与权限（门户 sys_menu）
|
||
|
||
在 `sys_menu` 新增一级 **「报销管理」**（`parent_id='2'`，Web 端根），子结构：
|
||
|
||
```
|
||
报销管理
|
||
├── 基础配置
|
||
│ ├── 费用项目管理
|
||
│ ├── 工作流配置（备用金）
|
||
│ └── 工作流配置（报销单）
|
||
├── 备用金
|
||
│ ├── 备用金申请
|
||
│ ├── 备用金审批
|
||
│ └── 备用金发放管理
|
||
├── 报销
|
||
│ ├── 报销申请
|
||
│ ├── 报销审批
|
||
│ └── 支付管理（发放/冲抵）
|
||
└── 视图中心
|
||
├── 我的申请单
|
||
├── 待我审批
|
||
└── 全部申请单（总经理）
|
||
```
|
||
|
||
权限标识（`perms`）建议前缀 `bx:`，与 CRM `crm:` 并列。角色-菜单通过 `sys_role_menu` 配置（可参考 bx 原 `bx-menu-role-init.sql` 角色语义：员工/财务/总经理）。
|
||
|
||
**验收**：admin 登录可见菜单；无权限用户 403。
|
||
|
||
---
|
||
|
||
### P6：前端移植（web-admin）
|
||
|
||
| 步骤 | 任务 | 参考 |
|
||
|------|------|------|
|
||
| P6-1 | 拷贝 `bx-web/src/views/pages/*.vue` → `web-admin/src/views/bx/` | 排除 User/Role/Menu/Home/Demo |
|
||
| P6-2 | 拷贝/适配 `bx-web/src/api/` | baseURL 指向门户 `/api`，协议已是 bx 风格 |
|
||
| P6-3 | Fresh Mint UI 适配 | 参考 `docs/crm-migration/step-03-frontend-adapt.md` |
|
||
| P6-4 | 认证改为门户登录态 | 不再调 `/api/auth/login` |
|
||
| P6-5 | 用户下拉改用 `sys_user` API | 替代 `userApi.dropdown` |
|
||
| P6-6 | 路由与 component 路径对齐 sys_menu | hash 路由 |
|
||
|
||
**UI 规范**：`docs/web-admin-ui-spec-fresh-mint.md`；列表参考 `/#/demo/order`，树形参考 `/#/demo/category`。
|
||
|
||
**验收**：各页面功能与 bx-web 对照通过；UI 符合 Fresh Mint。
|
||
|
||
---
|
||
|
||
## 8. 单模块后端实施 SOP（每个模块重复）
|
||
|
||
1. **读源**：`bx-backend/app/routers/{module}.py` + `services/{module}.py`，中文简述业务逻辑
|
||
2. **Schema**：复制到 `schemas/bx/`，`id` 及外键改 `str`，保留 camelCase alias
|
||
3. **Service**：复制到 `services/bx/`，追加 `tenant_no` 过滤、UUID 生成、用户字段映射
|
||
4. **Router**：复制到 `api/bx/`，改 Depends / import / prefix（去 `/api`）
|
||
5. **注册**：在 `api/bx/__init__.py` include_router
|
||
6. **验证**：Swagger 或 Postman 对照 bx 原接口逐项测试
|
||
7. **更新**：[module-status.md](./module-status.md)
|
||
|
||
---
|
||
|
||
## 9. 完整 API 路径索引（移植后保持不变）
|
||
|
||
详见 [01-api-inventory.md](./01-api-inventory.md)。
|
||
|
||
---
|
||
|
||
## 10. 验证清单
|
||
|
||
### 10.1 后端协议
|
||
|
||
- [ ] 成功响应 `code === 0`，字段名为 `msg`（非 `message`）
|
||
- [ ] 分页 `data.rows`（非 `data.list`）
|
||
- [ ] 列表接口为 GET + query 参数
|
||
- [ ] 路径与 bx-web `api/index.ts` 一致
|
||
- [ ] 错误时 HTTP 4xx/5xx + 合理 detail（与 bx 行为接近）
|
||
|
||
### 10.2 业务
|
||
|
||
- [ ] 费用项目二级树 CRUD
|
||
- [ ] 工作流定义 + 节点保存（advance / reimburse 各一条）
|
||
- [ ] 备用金：草稿 → 提交 → 多级审批 → 驳回/通过 → 发放
|
||
- [ ] 报销：申请 + 明细 + 审批 + 支付/冲抵
|
||
- [ ] 附件：upload → bind-biz → download/preview
|
||
- [ ] 视图：我的 / 待办 / 全部（总经理）
|
||
|
||
### 10.3 门户集成
|
||
|
||
- [ ] 租户隔离：不同 tenant 数据不可见
|
||
- [ ] 门户 JWT 可访问 bx 接口
|
||
- [ ] 菜单权限控制生效
|
||
|
||
---
|
||
|
||
## 11. 风险与对策
|
||
|
||
| 风险 | 对策 |
|
||
|------|------|
|
||
| ID 类型 int→str，前端 bx 页仍用 number | Schema 用 str；前端 P6 逐步改类型；JSON 字符串 ID 可兼容 |
|
||
| API 加密与 bx GET 冲突 | 开发期 exclude；联调后再定是否前端加密 |
|
||
| 门户与 bx 响应双标准并存 | bx 模块独立 common.py，禁止混用 success_response |
|
||
| payment 业务复杂 | 单独 P4，充分对照 bx service 单测/手测 |
|
||
| 审批人取自 workflow_node.approver_id | 配置工作流时选 sys_user，与原 bx 选 bx_user 操作一致 |
|
||
|
||
---
|
||
|
||
## 12. 文档索引
|
||
|
||
| 文档 | 用途 |
|
||
|------|------|
|
||
| [00-migration-plan.md](./00-migration-plan.md) | 本文：总实施方案 |
|
||
| [module-status.md](./module-status.md) | 模块进度跟踪 |
|
||
| [01-api-inventory.md](./01-api-inventory.md) | 全量 API 路径与方法 |
|
||
| [ref-backend-adapt.md](./ref-backend-adapt.md) | 后端适配细则（认证/租户/Service 改造清单） |
|
||
| `docs/sql/20260606_bx_tables.sql` | DDL 权威来源 |
|
||
| `docs/sql/sx.sql` | bx 原表业务字段对照 |
|
||
| `docs/crm-migration/ref-lessons-learned.md` | 前端/UI 踩坑（P6 参考） |
|
||
| `docs/web-admin-ui-spec-fresh-mint.md` | Web UI 规范（P6） |
|
||
|
||
---
|
||
|
||
## 13. 下一步行动
|
||
|
||
**当前建议从 P0 开始**：创建 `bx_models.py`、`schemas/bx/common.py`、`core/bx_auth.py` 并挂载空 `bx_router`。
|
||
|
||
每完成一个阶段，更新 [module-status.md](./module-status.md) 并在 PR/提交说明中标注阶段编号（如 `bx P1 expense-item`）。
|