PL API JSON 命名（运输计划模块）

本能力补充 openspec/changes/zkxw-engineering-standards/specs/api-conventions/spec.md 中「JSON 字段命名」要求，专用于 app/api/pl/** 与 web-admin/src/api/pl/**、web-admin/src/views/pl/**。

ADDED Requirements

Requirement: 运输计划 API JSON 字段 camelCase 对齐

运输计划模块（路由前缀 /api/transport/**）的请求体、响应体及 Query 参数中，凡前端 TypeScript 使用 camelCase 的多词字段，后端 Pydantic Schema SHALL 通过 Field(..., alias="camelCase") 声明 JSON 别名，并设置 model_config = {"populate_by_name": True}（或 ConfigDict(populate_by_name=True)）。

路由层访问请求体 SHALL 使用 Python snake_case 属性名（如 payload.carrier_name），SHALL NOT 使用 payload.carrierName。

读接口（response_model=...Read）SHALL 为 ORM 列对应的 snake_case 字段配置 alias，使 FastAPI 默认 response_model_by_alias=True 输出 camelCase，与 web-admin/src/api/pl/index.ts 类型定义一致。

Scenario: 承运商新增

WHEN 前端 POST /api/transport/carrier 请求体为 { "carrierName": "某某物流", "contactName": "张三", "status": "1" }
THEN CarrierCreate SHALL 校验通过（HTTP 非 422）
AND 路由 SHALL 通过 payload.carrier_name 写入 pl_carrier.carrier_name

Scenario: 计划新增含产品明细

WHEN 前端 POST /api/transport/plan/ 请求体含 belongsCompany、planType、planDate 及 products[].productId
THEN PlanCreate / PlanProductCreate SHALL 校验通过
AND 响应 PlanRead / PlanProductRead 的 JSON 键 SHALL 为 planNo、createTime 等 camelCase

Scenario: 运输安排

WHEN 前端 POST /api/transport/order/arrange/{planId} 请求体为 { "vehicleId": "...", "driverId": "...", "freightType": "by_weight" }
THEN TransportArrange SHALL 校验通过
AND 路由 SHALL 使用 payload.vehicle_id、payload.driver_id 访问字段

Scenario: 列表分页 Query

WHEN 前端 GET 列表接口 Query 为 page=1&pageSize=20&planType=direct
THEN 路由参数 SHALL 通过 Query(..., alias="pageSize") 或 Schema alias 正确解析
AND SHALL NOT 静默忽略 pageSize 导致始终使用默认每页 20 条

Scenario: 仅 snake_case 无 alias 视为缺陷

WHEN app/schemas/pl/** 中 Write/Read Schema 的多词字段仅有 snake_case 属性名、无 alias
THEN 属于本变更范围内的规范违反；前端发送 camelCase 时将返回 422 Unprocessable Entity
AND 修复 SHALL 为后端补 alias，SHALL NOT 要求 web-admin 改为 snake_case

Requirement: 运输计划 Schema 变更门禁

修改 app/schemas/pl/** 或新增 PL 写接口时，提交前 SHALL 运行 python backend/scripts/check_pl_json_aliases.py；脚本失败 SHALL 阻塞合并。

Schema 覆盖范围 SHALL 至少包括：

路径	说明
`app/schemas/pl/__init__.py`	承运商、车辆、司机
`app/schemas/pl/plan.py`	计划与产品明细
`app/schemas/pl/transport.py`	运输、安排、审批
`app/schemas/pl/freight.py`	运费结算
`app/schemas/pl/inventory.py`	库存、证件提醒

参考实现：app/schemas/db/weighing.py（地磅模块 alias 模式）。

spec.md 3.3 KB Permalink Histórico Raw