# 报销后端移植适配细则

> 实施 P0–P4 时加载。与 [00-migration-plan.md](./00-migration-plan.md) 配套。

---

## 1. 文件复制对照表

| bx-backend 源 | shanxia2.0 目标 | 改造程度 |
|---------------|----------------|---------|
| `schemas/common.py` | `schemas/bx/common.py` | 原样 |
| `schemas/expense_item.py` 等 | `schemas/bx/*.py` | id 改 str |
| `services/*.py` | `services/bx/*.py` | tenant + uuid + user |
| `routers/*.py` | `api/bx/*.py` | Depends + prefix + import |
| `models/*.py` | `models/bx_models.py` | 按 DDL 重写 |
| `utils/codegen.py` | `utils/bx_codegen.py` 或 `utils/codegen.py` | 租户隔离可选 |
| `core/deps.py` | **不复制** | 用 `core/bx_auth.py` |
| `services/minio.py` | **不复制** | 门户 storage 适配 |

---

## 2. Router 改造检查清单

复制每个 router 后逐项核对：

- [ ] `APIRouter(prefix="/api/xxx")` → `prefix="/xxx"`（去掉 `/api`）
- [ ] `from app.database import get_db` → `from app.core.database import get_db`
- [ ] `Depends(get_current_user)` → `Depends(get_bx_current_user)`
- [ ] `User` 类型 → `BxUserContext`
- [ ] `require_roles("ADMIN")` → `Depends(get_bx_current_user)` 或 `require_menu_code("bx:...")`（P5 后）
- [ ] 路径参数 `{advance_id}: int` → `str`
- [ ] `response_model=ApiResponse[...]` 保持不变
- [ ] **禁止** `return success_response(...)`

---

## 3. Service 改造检查清单

- [ ] 所有 `get_by_id(model, db, id: int)` → `id: str`
- [ ] 查询追加 `Model.tenant_no == tenant_no`
- [ ] 创建：`generate_uuid()`、`tenant_no`、`create_by`、`create_dept_id`
- [ ] `applicant_id` / `approver_id` 使用 `sys_user.id`（str）
- [ ] 冗余姓名字段：从 `SysUser.nick_name` 写入 `applicant_name` 等
- [ ] 单号生成：`generate_apply_code` 加租户维度（同日重置逻辑保留）
- [ ] 软删除：`del_flag=1`，查询默认 `del_flag=0`

---

## 4. Schema 改造检查清单

- [ ] `AdvanceApplyOut.id: int` → `str`
- [ ] `expense_item_id: Optional[int]` → `Optional[str]`
- [ ] 保留 `model_config`：`populate_by_name=True`, `alias_generator=to_camel`
- [ ] 保留 `DatetimeToStr` / `apply_time` 等字段 alias
- [ ] Create/Update body 与 bx 原字段一致

---

## 5. bx_auth 参考实现

```python
# backend/app/core/bx_auth.py（实施 P0 时落地）
from dataclasses import dataclass
from fastapi import Depends
from app.core.menu_guard import require_admin_or_super_admin

@dataclass
class BxUserContext:
    id: str
    name: str
    dept_id: str

def get_bx_current_user(
    user: dict = Depends(require_admin_or_super_admin),
) -> BxUserContext:
    return BxUserContext(
        id=user.get("user_id") or "",
        name=user.get("nick_name") or user.get("username") or "",
        dept_id=user.get("dept_id") or "",
    )
```

Service 中需要 tenant 时：

```python
from app.core.tenant_context import get_tenant_no

tenant_no = get_tenant_no(db, {"user_id": user.id, "role": ...})
```

---

## 6. main.py 注册

```python
from app.api.bx import bx_router

app.include_router(bx_router, prefix=settings.API_V1_PREFIX)
```

`api/bx/__init__.py`：

```python
from fastapi import APIRouter
from app.api.bx import expense_item, workflow, advance, reimburse, payment, attachment

bx_router = APIRouter()
bx_router.include_router(expense_item.router)
bx_router.include_router(workflow.router)
# ...
```

`app/api/__init__.py` 增加 `bx_router` 导出（可选，或直接 main 引用）。

---

## 7. 加密排除（config.py）

在 `API_ENCRYPT_EXCLUDE_PATHS` 追加（逗号分隔）：

```
/api/expense-items,
/api/workflows,
/api/advances,
/api/reimburses,
/api/payments,
/api/attachments
```

---

## 8. 字段一致性（可选）

后端 CRUD 落地后，若 WriteBody 字段较多，可扩展 `scripts/check_field_consistency.py` 支持 `bx_*` 表，规则同 CRM。

---

## 9. 测试建议

| 阶段 | 方式 |
|------|------|
| P1 | Swagger `/docs` 手动测 expense-items / workflows |
| P2 | 备用金完整流程 + 附件 upload |
| P3–P4 | 对照 bx 原环境相同操作序列 |
| 协议 | 断言响应 `code===0`、`data.rows` 存在 |

原 bx 环境（8011）可与门户（8000）并行，便于 diff 响应结构。