7.6 KiB
通用上游数据接入
使用边界
财务主库仍为团队 MariaDB/MySQL。SQL Server、PostgreSQL、MySQL/MariaDB 上游共用来源发现、字典、有限样本查询和表级镜像入口。添加同类型的第二个数据库不需要修改来源枚举、工厂或刷新器。
数据库连接记录未设置历史 source_key 时，系统使用稳定标识 database_<记录ID>。已有 jiansun、operations_replica、js_data_middle_platform 等映射保留。普通连接表单不再要求手工绑定来源或填写旧快照 scope；编辑旧连接仍保留这些历史字段。
原生 PostgreSQL/MySQL 连接统一要求 TLS、只读会话、非持久连接及最长 15 秒查询。SQL Server 继续复用已验证的 ODBC/DBLIB 入口。应用限制不替代上游只读账号；不提供接受用户原始 SQL 的网页接口。
开发流程（由 Codex 执行）
- 新人通过标准初始化启动本地环境，首次输入一次团队系统数据库密码。Docker healthy 只证明当前程序可用，
system-database:verify成功才表示共享接入通过。普通页面、计算逻辑和自动测试可先使用明确的隔离 fixture；不得把模拟数据当作真实财务数据。 - 在数据库管理页面添加并启用连接；“测试”与实际读取共用同一驱动。生产及现有字典刷新任务会发现新来源，不再要求逐库添加专用刷新器。
php artisan upstream:inspect列出来源标识，不输出凭据。upstream:inspect <source>列出已有字典对象；upstream:inspect <source> <schema> <object>查看字段。- 缺少目录时运行
upstream:schema:sync <source>。此命令只读上游元数据、写入系统库目录，失败保留原目录。 - 需要样本时明确指定
--columns=id,updated_at,label --limit=5，最多返回20行。只选本任务有权读取的非敏感字段；真实样本不得进入 Git、PR 或公开日志。样本不能证明全量完整性。 - 确认业务键、需要的字段、增量依据和业务含义后，登记数据集。以下仅为示例，表名必须来自实际目录：
php artisan business-mirror:register database_17 public example_orders \
--keys=id --columns=id,updated_at,label --watermark=updated_at
登记默认不启动同步。Codex 根据当前功能需求核对精确字段、批次和影响，备份受影响的配置、镜像与同步状态后，自主对同一声明追加 --enable-sync；生产调度即可自动完成或续传首次全量，完成后转为增量，无需负责人另行授权。登记和启用均由 Codex 执行，不让新人处理开关或命令。--disable-sync 停止后续自动执行，保留已有镜像。
声明式登记不能覆盖代码维护的数据集，也不能悄悄修改已有声明的稳定键、字段和增量口径；此类变化需评估历史数据/游标兼容性。来源表没有可靠更新时间时只按主键追加，不能承诺自动发现历史修改或删除，需另行声明校准策略。
页面读取与同步状态
已有公司、店铺、商标页在新人电脑没有数据
deploy/local-init.sh 会先使用本机已经保存的团队密码，按当前代码的加密团队资料验证最新端点；验证成功后自动备份并对齐系统库和业务镜像库的私有配置。这样服务器迁移后不必每台开发机手动修改主机、端口或上游开关。当前连接已正确时不会重复改写配置；验证失败保留原配置。此自动修复只在本地开发运行，不修改生产端点，不执行迁移或业务同步。
已有本地容器可由 Codex 直接执行 docker compose -f docker-compose.local.yml exec -T -u www-data app php artisan system-database:connect-team。从未保存团队密码的机器返回“首次接入”状态，仍只需在网页输入一次系统数据库密码；自动化接入可用 --password-stdin 安全传入，不提供明文密码命令行参数。不能把普通测试管理员的网页登录密码当成系统数据库密码。
这些页面优先读取 caiwu_business_mirror。本机 Docker 正常、临时引导库有用户，并不代表已经连接团队共享库。Codex 应先在最新主线执行 deploy/local-init.sh，通过系统数据库入口完成一次共享接入和重新登录，再运行 system-database:verify 并检查相应 business-mirror:status。镜像连接默认复用系统数据库主机、端口、账号和 TLS，不要求新人另填 SQL Server 密码，也不要把 furniture3d_prod 填成 operations_replica。
已有镜像可读时，上游开关关闭或网络暂不可达不应阻断页面。读取失败不能解释为真实记录数为 0。只有探索尚未接入的新表时，才需要使用对应上游的只读连接；不要为了让已有资料页出数据，在每个开发者的引导库重复登记生产来源。
新页面在原有公司、角色和数据权限校验之后调用 BusinessMirrorDataReader::paginate($datasetKey, $filters, $page, $perPage)。它只读业务镜像，返回完整总数、稳定分页、实际同步状态和最近完成时间。来源暂时关闭或不可达时，已完成镜像仍可读取；无首次镜像时明确报“尚未完成首次同步”，不登记逐页快照、不从页面直接访问上游。
通用筛选只接受已声明字段的等值条件；复杂业务联表、金额口径、公司行级过滤继续由固定 Repository 实现。不能把此内部读取器当作绕过业务权限的公开接口。
php artisan business-mirror:status [dataset] --json 只读输出启用、首次完成、最近尝试、最近完成及错误类型。running 表示一个同步窗口尚未完成，不保证此刻正有进程运行。最后尝试时间不是最后数据完成时间。
通用调度默认每轮最多8个数据集、30秒周期预算；未完成窗口与常规数据集交替处理，单数据集默认8秒软预算，积压任务默认最多6批。预算在批次之间检查，单条查询仍受驱动超时限制；不提高上游并发。失败任务至少冷却5分钟。专用商品/价格/钉钉调度保持既有路径。
调度只对已启用的登记数据集自动首次同步；initial_sync_approved 是兼容保留的初始化开关，由 Codex 使用 --enable-sync 一并设置，不代表需要负责人审批。既有代码数据集由 Codex 自主在生产同步节点执行对应的 --full，沿用互斥锁、分批、断点和验收。未完成的旧页面切换不等于已经上线，必须逐页验收并与正在开发的 PR 协调。
类型及验收
- PostgreSQL 带时区时间戳在镜像中保存为 UTC；业务展示按自己的明确时区换算。无时区日期时间保留原值。
bytea使用十六进制文本表示；不自动解释 JSON、数组、枚举中的业务语义。 - 验收包含：没有修改来源枚举也能发现新库；TLS/只读保护；字段目录；只复制明确字段；首次同步、第二页、末页、总数和筛选；增量插入与更新；源不可达时读旧镜像；失败和未启用状态。
- SQL Server 既有 Repository 与专用同步器需回归。不得把“新连接测试成功”当作全项目页面已迁移或所有业务表已同步。
系统连接保存后回滚的排查
截图中的“新配置未通过应用级验证”表示已尝试保存并复核，不等于未输入密码。保存系统连接必须同时统一 DB_HOST、读写地址，清除旧 DATABASE_URL 和 socket 覆盖，并处理重复赋值；验证失败时恢复完整旧配置。不要只改 SYSTEM_DATABASE_MODE 标志，也不要关闭失败回滚来制造“连接成功”。