WuYongJie
6b2b486ce1
## 任务占用与边界 - 任务名称：全项目上游业务镜像目录与通用同步框架 - 实际开发者：WuYongJie - 目标结果：登记当前代码实际使用的上游原表，提供低压、可断点的首次全量、增量重叠和全量校准框架。 - 实际修改：13 个文件；新增通用数据集目录、动态镜像建表、同步状态、同步命令、生产低压轮询、测试和团队清单。 - 将写入的公共契约：`business_mirror_table_states`、`business-mirror:sync-tables`、`BusinessMirrorDatasetRegistry`、`BusinessMirrorSchemaManager`。 - 仅复用、明确不修改：`UpstreamReadOnlyQueryFactory`、`upstream_schema_columns`、既有 `product_price_mirror_rows`。 - 明确不包含：本 PR 不切换其余业务页面 Repository，不执行生产迁移或首次全量，不提交真实业务数据或凭据。 ## 合并前自审 - [x] 已重新拉取最新 `origin/main`，分支仅领先 1 个提交 - [x] `git merge-tree --write-tree origin/main HEAD` 无冲突 - [x] 完整 diff 共 13 个文件，未发现越界文件或敏感内容 - [x] 生产共享数据字典核对 38 个数据集，缺失对象/字段为 0 - [x] 临时 MariaDB 空库迁移实测成功，验证库已删除 - [x] 上游异常空结果不会清空已有镜像 - [x] 定时任务只轮转已完成首次全量的数据集，不会自动扫描未初始化大表 ## 测试 - `BusinessMirrorSynchronizerTest` 等相关测试：14 tests / 65 assertions 全通过 - 新同步器专项：5 tests / 25 assertions 全通过 - 新增 PHP 文件语法检查全部通过 - 两份生产激活脚本 `bash -n` 通过 - `git diff --check` 通过 ## 风险与回滚 - 包含新增迁移，但发布脚本遇到迁移仍会要求独立高风险授权；合并本身不会执行生产迁移。 - 首次全量必须逐数据集显式执行并做数量/翻页/筛选验收，特别是约 280 万行的大表不得随发布自动全扫。 - 回滚代码可回退本合并提交；生产迁移执行前必须备份 `caiwu_system_config` 与 `caiwu_business_mirror`。 Reviewed-on: http://git.1080p.hk/WuYongJie/CaiWuXiTong/pulls/53
CaiWuXiTong 财务系统
本项目基于 Akaunting 二次开发，包含统一系统设置、用户和侧边栏管理、多个只读云数据库来源，以及财务业务页面。
开发者快速开始
新人只需要做两件事：
- 启动 Docker Desktop；
- 在系统数据库页面输入负责人提供的系统数据库密码。
其余工作交给 Codex：拉取最新 main、执行 bash deploy/local-init.sh、处理本机引导库迁移、启动服务、清理缓存、打开 http://127.0.0.1:18088，并在连接后自动核对两套上游、数据字典和真实只读查询。初始化脚本会比较当前构建输入与镜像指纹，并校验必要静态资源；需要更新时自动重建，不再要求新人判断是否添加 --build。Codex 不得把这些命令、迁移或排错步骤转交给新人执行。
首次登录账号由初始化脚本生成并保存在本机私有凭据文件中。连接系统数据库成功后，临时登录会自动失效，改用系统数据库中属于自己的正式账号登录。
连接成功后，用户、侧边栏、系统设置、云数据库登记和共享快照会自动统一。不需要填写主机、端口、库名、账号、TLS、证书或两个云数据库密码，也不要复制生产环境或其他开发者的 APP_KEY、.env。
Codex 的接入验收不能只回答“成功”或“失败”，必须逐个来源报告：来源标识、数据库和 Schema、验证对象、读取字段、返回行数、耗时、数据状态及失败阶段。连接资料由系统自动处理，不属于新人操作项。
完整步骤和排错说明见 LOCAL_DEPLOY.md。
数据库边界
- 本机 MySQL 只负责第一次启动和临时登录，不是团队业务数据源。
- 系统数据库统一保存应用用户、系统设置、侧边栏配置和云数据库连接记录。
- 云数据库属于只读上游。本地开发从系统数据库自动取得连接资料并执行固定只读查询；生产页面使用共享按需查询快照。
- 系统数据库保存查询登记、数据字典和生产共享快照，但不会执行 SQL，也不是 SQL Server 网络代理。
- 开发者需要新表或字段时，Codex 先通过共享数据字典和通用只读入口完成真实数据探索，再实现 Repository、生产范围和刷新器；新人不需要配置上游或执行探测命令。
- 不得把数据库密码、连接串、生产
APP_KEY、Token、SSH 私钥或runtime/.env提交到 Git。
开发和发布
- 团队协作与安全规则：AGENTS.md
- 本地测试环境：LOCAL_DEPLOY.md
- 开发和正式部署：docs/开发与部署SOP.md
- 上游业务接入规范：docs/ecommerce-finance-development.md
- 视觉规范：DESIGN.md
正式发布只能使用已经合并的 main，并通过 scripts/deploy-from-workstation.ps1 在开发机构建提交 SHA 镜像。生产服务器只运行镜像，不执行源码构建。
技术基础
- PHP 8.3
- Laravel
- Vue
- Apache
- MySQL / MariaDB
- Docker
- Akaunting
上游 Akaunting 的版权和许可证信息见 LICENSE.txt。