基于 FastAPI 的后端：合同 OCR、客户与库房收款配置、销售报货、报货计划、订货计划、磅单、结余核销、收款明细与回款导入等。详见 pyproject.toml 中的依赖说明。
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# 创建虚拟环境
uv venvuv sync合同 OCR、磅单等依赖 rapidocr-onnxruntime、opencv-contrib-python 等（已在 pyproject.toml 中声明）。email-validator 等常用包也已列入依赖；若本地环境缺包，以 uv sync 为准补齐。
- 复制模板并编辑：
cp .env.example .env，按环境填写（勿将真实.env提交到版本库）。 - 数据库：
database_setup.py与多数服务通过MYSQL_*连接；DATABASE_URL在app/core/config.py等处为占位/兼容读取，请勿只配DATABASE_URL而省略MYSQL_*。 - 扣子 Coze（可选）：
app/core/config.py同时支持历史变量名（Coze_url、project_id、session_id、YOUR_TOKEN）与大写别名（COZE_URL、COZE_PROJECT_ID、COZE_SESSION_ID、COZE_BEARER_TOKEN），填一组即可。 - 其它可选项（见
.env.example内注释）：CORS_ALLOW_ORIGINS、OPENAI_API_KEY、日志相关LOG_DIR/LOG_LEVEL/LOG_ENABLE_CONSOLE/LOG_ENABLE_FILE/LOG_RETENTION_DAYS等。
python database_setup.pydatabase_setup.py 会创建（若不存在）核心业务表，例如：pd_users、pd_user_permissions、pd_contracts、pd_deliveries、pd_delivery_plans（含 创建人 / 最后修改人 字段：created_by、created_by_name、updated_by、updated_by_name）、pd_weighbills、pd_balance_details、pd_payment_details、pd_warehouse_payees、pd_payment_upload_logs、固定 50 槽位 pd_product_categories 等，并初始化权限定义数据。
- 全新库：直接执行上述命令或依赖应用启动时的
create_tables()即可。 - 已有库：若曾早于某次迭代建库，报货计划相关能力会在首次调用服务时尝试自动
ALTER TABLE pd_delivery_plans补全操作人字段；若无 DDL 权限，需由 DBA 按database_setup.py中的定义手工补列。
# 开发环境（热重载）
uv run main.py
# 或
uvicorn main:app --reload --host 0.0.0.0 --port 8007实际端口以环境变量 PORT 为准（未设置时默认为 8007）。
- Swagger 文档:
http://127.0.0.1:<PORT>/docs（将<PORT>换成你的PORT）
- 启动时：执行
create_tables()检查/创建表；并启动定时任务（默认每天 00:10，上海时区）将到期合同批量标记为「已失效」（宽限逻辑见expire_contracts_after_grace）。 - 鉴权：见下文「接口鉴权说明」。
- 用户角色：库表约束与业务侧一致的角色包括：管理员、大区经理、自营库管理、财务、会计、审核主管（枚举见
database_setup.py中pd_users的CHECK，前端可选GET /api/v1/user/roles）。
以下路径均挂在 /api/v1 下；完整参数与响应以 /docs 为准。
GET /healthz：健康检查。GET /init-db：手动触发数据库初始化（仅建议开发/调试；生产勿对公网开放）。
登录成功后携带：Authorization: Bearer <token>。
POST /api/v1/user/auth/login、POST /api/v1/user/auth/logout、POST /api/v1/user/auth/refresh：登录与令牌。GET /api/v1/user/me、PUT /api/v1/user/me、PUT /api/v1/user/me/password：当前用户资料与改密。GET /api/v1/user/roles：系统预置角色列表（含 审核主管 等）。POST /api/v1/user/users、GET /api/v1/user/users、GET/PUT/DELETE /api/v1/user/users/{id}、POST /api/v1/user/users/{id}/reset-password：用户管理（权限约束见路由实现与/docs）。- 权限矩阵、角色模板等见
/docs中 用户认证与权限 分组。
POST /api/v1/contracts/ocr：上传合同图片，OCR 识别；可选自动保存与图片落盘。自动写入数据库时须带查询参数plan_no（报货计划编号，即pd_delivery_plans.plan_no）。POST /api/v1/contracts/manual：手动录入合同（含品种与单价明细）；请求 JSON 必须包含plan_no（同上）；服务端会解析为delivery_plan_id落库。GET /api/v1/contracts：分页列表，支持精确条件与模糊关键词。GET /api/v1/contracts/{contract_id}：详情（含品种明细）。GET /api/v1/contracts/{contract_id}/image：预览合同图片。PUT /api/v1/contracts/{contract_id}：更新合同与品种明细。DELETE /api/v1/contracts/{contract_id}：删除合同。POST /api/v1/contracts/export：导出 CSV（合同 ID 列表为空可表示导出全部，以实际接口行为为准）。
- 冶炼厂客户的增删改查。
GET/POST /api/v1/customers/warehouse-payees、PUT /api/v1/customers/warehouse-payees/{id}：库房收款员配置（与业务里pd_warehouse_payees/pd_payees等逻辑配合使用，细节以代码与/docs为准）。
- 报货单的增删改查、联单上传、审核相关能力（部分接口需登录，见
/docs）。
POST /api/v1/deliveries：新增报货订单/销售台账。GET /api/v1/deliveries：列表；每条含contract_product_prices（与GET .../contract-product-prices相同结构，无数据时为[]）。GET /api/v1/deliveries/{delivery_id}：单条详情。GET /api/v1/deliveries/{delivery_id}/image：预览联单图片。PUT /api/v1/deliveries/{delivery_id}：更新。DELETE /api/v1/deliveries/{delivery_id}：删除。POST /api/v1/deliveries/{delivery_id}/upload-order：上传报货单附件。- 报单合同品类单价（表
pd_delivery_contract_product_prices，按报单delivery_id存关联合同的品类与单价，可与合同品种表独立改价）：GET /api/v1/deliveries/{delivery_id}/contract-product-prices：列表。POST /api/v1/deliveries/{delivery_id}/contract-product-prices/sync-from-contract：按报单当前关联合同，从pd_contract_products全量覆盖写入本表（需登录）。PATCH /api/v1/deliveries/{delivery_id}/contract-product-prices：批量改单价（需登录）； body：{"items":[{"id":1,"unit_price":8500}]}或{"items":[{"product_name":"电动车","unit_price":8500}]}。
POST /api/v1/delivery-plans/：录入（需登录）；写入created_by/created_by_name，并将updated_by/updated_by_name设为同一操作人。GET /api/v1/delivery-plans/：分页列表（支持计划编号、状态、冶炼厂、计划开始日期区间等筛选）。GET /api/v1/delivery-plans/{plan_id}：详情（含品类单价明细；响应中含操作人字段）。PUT /api/v1/delivery-plans/{plan_id}：修改（需登录）；更新主表或替换items时写入 最后修改人。DELETE /api/v1/delivery-plans/{plan_id}：删除（当前实现未强制 JWT，生产建议收紧）。POST /api/v1/delivery-plans/increment-confirmed-trucks：按plan_no累加已定车数并重算未定车数（需登录）；同时更新最后修改人。
- 录入、列表、详情、改车数、审核；列表与详情均返回
audit_remark（审核备注）。 - 审核接口：
audit_result为 审核未通过 时remark必填（须写明原因）；审核通过 时备注可选。审核通过与报货计划已定车数联动（与increment-confirmed-trucks规则一致，详见/docs）。
- OCR、创建、列表、详情、图片、修改、删除、确认、与报货匹配、按合同查价等。
- 结余生成、支付回单、收款明细、回款导入与上传日志等；完整列表见
/docs中 磅单结余管理、收款明细管理 等分组。
- 固定 50 槽位品类的查询、写入与按名删除。
- 挂载方式：
main.py中为/api/v1挂载了HTTPBearer(auto_error=False)；register_pd_auth_routes注册/api/v1/user下认证与用户管理路由。 - 是否必须登录：由各路由是否声明
Depends(get_current_user)决定（以代码与/docs为准）。 - 已强制登录的典型能力（会持续迭代，以下非穷尽）：
- 报货计划：
POST /api/v1/delivery-plans/、PUT /api/v1/delivery-plans/{plan_id}、POST /api/v1/delivery-plans/increment-confirmed-trucks。 - 报货、收款、磅单等模块中的部分写操作与敏感读操作。
- 报货计划：
- 仍可能匿名访问的接口：如部分合同/客户/结余/品类、报货计划列表与详情/删除等；生产环境建议在网关统一鉴权，或逐步为这些路由补上登录与权限校验。
- 务必修改
JWT_SECRET，勿使用.env.example或文档中的占位值。 .env含密钥，勿提交；模板仅维护/.env.example（无真实口令与 Token）。GET /init-db无鉴权，勿对公网开放。- 业务接口鉴权未全覆盖，见上一节。
- 数据库连接：
core/database.py的get_conn()使用DictCursor；部分模块仍从contract_service等引入另一套get_conn()（默认游标），行为略有差异，后续可考虑统一。 - 报货计划：
app/services/delivery_plan_service.py在首次访问时会对旧库尝试补全pd_delivery_plans上的操作人相关列（见_ensure_plan_audit_columns）。 - 请求日志中间件会注入当前用户上下文（见
main.py中request_logger与get_user_identity_from_authorization）。