09｜前后端契约
数据模型、API与OA接口
明确平台事实对象、OA引用、接口规范和跨模块业务事件。
核心领域对象
不把OA对象复制成平台业务表
| 对象 | 平台定义 | 主要关系 |
|---|---|---|
| OaIdentityRef | 内部员工外部身份引用，不是员工档案 | oa_user_id→platform_role_mapping→customer/site assignment |
| OaProjectRef | OA内部项目引用和必要状态快照，不是项目管理 | tenant/site可关联一个或多个oa_project_id；只读 |
| Tenant | 客户数据、权限、套餐和计费隔离边界 | 拥有customer membership、subscription、site和数据 |
| CustomerUser/Membership | 外部客户账号及其租户身份 | 角色、站点范围、有效期和MFA |
| Subscription/Quota | 客户可用功能与资源限制 | package_version、tenant、usage和到期策略 |
| Site | 站点语言、类型、区域、状态和当前发布版本 | tenant、template、page、content、domain、release |
| Page/ComponentInstance | 页面版本和组件树 | site_branch、component_version和theme |
| ContentItem/Translation | 产品、新闻、案例等结构化内容 | content_schema、language、taxonomy和version |
| Domain/Certificate | 域名所有权、DNS期望、证书和站点绑定 | site_domain_binding版本化 |
| Release/Artifact | 发布快照、构建任务、产物、健康和线上指针 | site_version、deployment_unit |
| Inquiry/TrafficEvent | 网站转化事实/访问分析事件 | site、page、form和consent |
OA数据映射
只保留稳定外部ID和授权必要快照
| OA字段 | 平台字段 | 更新方式 | 使用限制 |
|---|---|---|---|
| 员工唯一ID | oa_identity_ref.external_user_id | SSO实时+Webhook/对账 | 主键必须稳定；禁用后撤销会话和分配 |
| 姓名/部门名称 | audit_actor_snapshot | 登录/动作时快照 | 只用于显示和历史审计，不作为权限判断主键 |
| 部门ID/角色code | identity_claim_snapshot | 每次登录和变更事件 | 映射为平台角色，不直接当站点数据范围 |
| 内部项目ID | oa_project_ref.external_project_id | 创建客户/站点时校验+定时摘要 | 只读引用，不在平台修改OA项目 |
| 项目负责人ID | internal_owner_assignment.source_ref | OA同步后生成服务范围候选 | 平台必须有明确customer/site assignment，不能仅凭部门自动全量访问 |
| 员工禁用/离职 | identity_status=disabled | Webhook优先，定时对账兜底 | 立即撤销登录、协助会话、API凭据和待分配权限 |
API统一契约
前端、PHP后端、OA适配器和Worker共同遵守
| 规则 | 要求 |
|---|---|
| 路径与版本 | /api/v1；动作使用 /sites/{id}:publish、/tenants/{id}:suspend，不直接写status |
| 身份上下文 | 内部从OA SSO换取平台会话；客户从平台认证；服务端解析tenant、actor、role、scope |
| 错误结构 | error_code、message、request_id、retryable、field_errors；不把异常堆栈返回前端 |
| 幂等 | 创建租户/站点、询盘、发布、域名验证、导入等使用Idempotency-Key |
| 并发 | 更新draft/page/content携带version或If-Match，冲突返回最新版本和差异 |
| 分页搜索 | 跨客户总后台使用cursor；限制page_size；复杂搜索走索引，不用offset扫描大表 |
| 长任务 | 发布、导入、导出、AI、同步立即返回task_id，页面订阅或轮询任务状态 |
| 文件 | 浏览器直传对象存储；服务端签发上传凭据和确认文件，不经PHP转发大文件 |
| 审计 | 敏感动作服务端记录actor_type、真实ID、tenant/site、前后值、reason、request_id和结果 |
关键业务事件
跨模块异步联动，OA不可用不能拖垮建站主链
| 事件 | 生产者 | 消费者动作 | 一致性/失败 |
|---|---|---|---|
| oa.identity.disabled | OA适配器 | 撤销平台会话、协助会话和站点服务分配 | 高优先级；失败P0告警 |
| tenant.activated | 客户域 | 创建配额、发送企业主邀请、初始化默认配置 | Outbox；邀请失败不回滚租户，可重发 |
| site.created | 站点域 | 预占资源、初始化模板/内容、建立监控 | 创建和配额原子；初始化失败补偿释放配额 |
| content.reviewed | 审核域 | 解锁发布候选或返回驳回原因 | 审核快照不可变 |
| release.published | 发布域 | 更新current_release、刷新CDN、启动监控、通知客户 | 健康检查后切换；失败保持旧版 |
| domain.verified | 域名域 | 允许绑定和SSL签发 | 重复事件幂等 |
| inquiry.created | 询盘域 | 客户通知、统计转化、可选回传外部系统 | 询盘入库优先；下游失败重试 |
| traffic.aggregated | 数据域 | 更新客户和总后台看板缓存 | 允许延迟，可从原始事件重算 |