用途
本技能用于将 Python 服务集成进以 PHP 为后端、并包含 Android 与 iOS 客户端的 SaaS 系统。它覆盖 FastAPI sidecar 架构、后台任务 worker（RQ/Celery）、PHP 与 Python 之间的契约、多租户隔离、Debian/Ubuntu 上的部署、可观测性以及失败模式处理。
当任务需要可复用的判断、领域约束或经过验证的工作流程，而不是临时性建议时，使用本技能。当任务与 python-saas-integration 无关，或更适合由更具体的配套技能处理时，不要使用本技能。
主要能力
技能提供两种互补的集成模式，二者共享同一 Python 代码库、同一领域逻辑和同一配置。
模式 A — FastAPI sidecar（同步）：在 127.0.0.1:8001（仅内部）上运行 Python HTTP 服务，PHP 在同一请求周期内需要计算结果时调用它。适用于响应时间预算约 2 秒以内、输出较小（JSON、小于 2MB 的小型 Excel/PDF）、用户等待结果的场景，例如为仪表盘组件计算 KPI、用 ML 模型为单条记录打分、渲染单页品牌收据。
模式 C — 后台 worker（异步）：PHP 将任务入队到 Redis（RQ 或 Celery 队列），Python worker 进程取出任务、执行、将输出写入存储并通知用户。适用于任务耗时超过数秒、输出较大（多标签 Excel、多页 PDF、批量打分）、任务为周期性（ETL 同步、定时报表）、用户可以等待（完成时邮件/通知，或轮询状态）的场景，例如生成 50 标签销售仪表盘、为 10,000 名客户批量打分预测流失、每晚同步 Stripe 发票。
决策规则：输出小于 2MB 且预期耗时小于 2 秒 → 模式 A（sidecar）；输出大于等于 2MB 或预期耗时大于等于 2 秒 → 模式 C（worker）；按计划触发（无用户请求）→ 模式 C；用户轮询或稍后收到通知 → 模式 C。模糊情况默认选择模式 C，因为它在规模上更宽容。
使用方式
先阅读 SKILL.md，然后仅加载任务所需的引用深度文件。按技能中的有序指导、检查清单和决策规则执行，而不是挑选孤立的代码片段。产出交付物时，在重要之处明确假设、风险和后续工作。
PHP 与 Python 契约：保持契约紧凑。认证方面，sidecar 仅绑定 127.0.0.1，绝不公开暴露；即便如此，每个请求仍使用 HMAC 签名令牌认证：PHP 签名 HMAC-SHA256(shared_secret, timestamp + path + body)，发送 X-Internal-Signature 和 X-Internal-Timestamp 头；Python 拒绝时间戳偏差超过 60 秒或签名无效的请求。请求/响应封装方面，每个 sidecar 端点返回 {"ok": true, "data": {...}} 或 {"ok": false, "error": {"code": "INVALID_INPUT", "message": "...", "details": {...}}}；worker 任务载荷的结果使用相同的 {ok, data, error} 结构。幂等性方面，每个改变状态的任务或 sidecar 调用必须接受 idempotency_key，worker 按 key 去重至少 24 小时，PHP 重试是安全的。
多租户安全：每个请求和每个任务都携带 tenant_id。Python 服务需验证 tenant_id 与调用方一致（HMAC 载荷尽可能绑定 tenant）；每个数据库查询按 tenant_id 限定范围，使用 SQLAlchemy 事件或显式 WHERE 子句，绝不假设；跨租户缓存数据时必须按 tenant 命名空间化缓存键；每行日志记录 tenant_id（通过 structlog contextvars）；worker 并发时，一个 Python worker 可能处理多个租户的任务，绝不在模块级变量中跨任务携带租户状态。
文件交接（大输出）：Python 生成文件 → 写入存储 → 返回 URL 给 PHP → PHP 交付给客户端。存储选项：S3（或兼容 S3）适合多主机部署，Python 写入时使用服务端加密，PHP 生成短 TTL 的签名 URL；共享本地磁盘适合单主机部署，写入 /var/app/storage/tenant_{id}/reports/... 并设置严格权限（0640，owner app，group nginx），nginx 通过 X-Accel-Redirect（内部）提供，由 PHP 控制授权。存储路径始终包含 tenant_id，绝不单独信任文件名做访问控制。临时文件在 24–72 小时后过期，由定时清扫任务删除。
Debian/Ubuntu 部署：Python 作为 systemd 服务运行，使用由 uv 管理的项目本地 venv。技能提供了 FastAPI sidecar 和 RQ worker 的 systemd unit 示例，以及 nginx 代理配置（仅内部网络可达，绝不暴露到公网）。
可观测性：Python 日志与 PHP 日志对齐，便于端到端追踪单个事件。日志：structlog → JSON → journald → 日志收集器（Promtail/Vector）→ Loki/Elasticsearch。关联 ID：PHP 为每个请求生成 UUID，作为 X-Correlation-ID 头或任务字段传递，Python 在请求/任务期间将其绑定到 structlog contextvars。指标：Prometheus 抓取每个 sidecar/worker 的 /metrics，标准直方图包括 http_request_duration_seconds、job_duration_seconds、job_failures_total。追踪：如果团队已使用 OpenTelemetry 则使用，否则关联 ID 足以起步。健康检查：sidecar 的 GET /health（存活）、GET /ready（就绪，检查 DB/Redis）；worker 在 Redis 中暴露心跳键。
失败模式：为 Python 宕机、缓慢或行为异常做规划。Sidecar 宕机时 PHP 收到连接拒绝，处理程序应优雅降级（功能开关关闭、缓存值、友好错误），绝不级联为整个应用的 500。Sidecar 缓慢时 PHP 客户端有严格超时（可配置，默认 5 秒），60 秒内连续 N 次失败后触发熔断。Worker 队列积压时，队列深度超过阈值或最旧任务年龄超过 SLA 时告警，失败 N 次的任务进入死信队列。毒消息：worker 按任务捕获异常、记录日志、发送到 DLQ 并继续处理，绝不因单个坏载荷崩溃 worker。幂等性：所有重试都是安全的，因为 worker 按 idempotency_key 去重。
版本与发布：Sidecar 使用语义化版本，蓝绿部署（在 :8002 运行新 sidecar，切换 nginx/PHP 配置，停止旧实例），零停机。Worker 采用排空后重启：新 worker 开始处理新任务，旧 worker 完成当前任务后退出，使用 SIGTERM 并给予 60 秒宽限期。模式变更仅做增量，绝不删除 PHP 仍发送的字段，弃用 → 警告 → 移除至少跨两个版本。
适用场景
为 PHP SaaS 增加 Python 能力（分析、文档生成、机器学习、OCR、ETL）；为新功能在同步（sidecar）与异步（worker）之间做选择；在项目中设置第一个 Python 服务；建立 PHP 与 Python 契约（认证、错误、文件交接）；在同一 Debian/Ubuntu 主机上随 PHP 部署 Python 服务。
限制
技能要求先加载 python-modern-standards 作为前置条件。当任务与 python-saas-integration 无关，或更适合由更具体的配套技能处理时，不应使用本技能；当请求只需要简单答案，且本技能的任何约束或引用都无实质帮助时，也不应使用。技能强调不要将示例当作可复制粘贴的真理而不检查适用性、约束或失败模式，也不要默认加载所有引用文件，而应使用渐进式披露。