Neo-ZQYY/docs/audit/changes/2026-02-15__monorepo-migration-phase1-8.md

Monorepo 迁移 Phase 1-8 审计记录

• 日期: 2026-02-15
• Prompt: Monorepo 迁移 spec 任务 1-8（骨架搭建、ETL 平移、小程序平移、DB Schema 重组、Steering 更新）
• 类型: 新仓库初始化（全量新建，非增量修改）
• 风险等级: 高（涉及 DB Schema、ETL 全量代码、配置体系）

变更概述

将单一 ETL 仓库（C:\ZQYY\FQ-ETL）迁移为 Monorepo 单体仓库（C:\NeoZQYY），整合 ETL、后端、小程序、GUI 等子项目。一次性搬迁策略，不保留 Git 历史。

变更清单

任务 1：骨架搭建

• 创建 9 个一级目录（apps/、gui/、packages/、db/、docs/、infra/、scripts/、samples/、tests/）及 README.md
• 初始化 Git 仓库、.gitignore、.kiroignore
• 生成根 pyproject.toml（uv workspace）和 4 个子项目 pyproject.toml
• 生成 .env.template

任务 3：ETL 平移

• 从 C:\ZQYY\FQ-ETL 原样复制 ETL 业务代码到 apps/etl/pipelines/feiqiu/
• 涉及目录：api/、cli/、config/、loaders/、models/、orchestration/、scd/、tasks/、utils/、quality/、tests/、scripts/、docs/、database/
• 复制 gui/ 到 gui/
• 更新 ETL pyproject.toml 依赖

任务 5：小程序平移

• 从 C:\ZQYY\XCX 复制到 apps/miniprogram/
• Prototype 复制到 docs/h5_ui/

任务 6：数据库 Schema 重组（高风险）

• 创建 db/etl_feiqiu/schemas/ 下 6 个 DDL：meta.sql、ods.sql、dwd.sql、core.sql、dws.sql、app.sql
• 创建 db/zqyy_app/schemas/init.sql（用户、角色、权限、任务、审批表）
• 创建 db/fdw/setup_fdw.sql（FDW 映射配置）
• 创建测试数据库脚本（create_test_db.sql、migrate_test_data.sql）
• 同步文档：docs/database/etl_feiqiu_schema_migration.md

任务 8：Steering 更新

• 复制 .kiro/steering/ 和 .kiro/specs/ 到 Monorepo
• 更新 product.md、tech.md、structure-lite.md、structure.md、governance.md、db-docs.md、steering-readme-maintainer.md 为 Monorepo 视角
• 清除所有旧路径引用（FQ-ETL、C:\ZQYY\FQ-ETL）

属性测试（PBT）

• 在 tests/ 下创建 7 个属性测试文件（Property 1-8, 10）

高风险路径命中

路径	风险类别	说明
apps/etl/pipelines/feiqiu/api/	API 契约	原样复制，无逻辑修改
apps/etl/pipelines/feiqiu/cli/	CLI 入口	原样复制，无逻辑修改
apps/etl/pipelines/feiqiu/config/	配置体系	原样复制，无逻辑修改
apps/etl/pipelines/feiqiu/database/	数据库操作	原样复制，无逻辑修改
apps/etl/pipelines/feiqiu/loaders/	落库逻辑	原样复制，无逻辑修改
apps/etl/pipelines/feiqiu/models/	数据模型	原样复制，无逻辑修改
apps/etl/pipelines/feiqiu/orchestration/	调度/游标	原样复制，无逻辑修改
apps/etl/pipelines/feiqiu/scd/	SCD2 处理	原样复制，无逻辑修改
apps/etl/pipelines/feiqiu/tasks/	业务任务	原样复制，无逻辑修改
apps/etl/pipelines/feiqiu/utils/	通用工具	原样复制，无逻辑修改
db/etl_feiqiu/schemas/*.sql	DB Schema	新建 DDL，未执行
db/zqyy_app/schemas/init.sql	DB Schema	新建 DDL，未执行
db/fdw/setup_fdw.sql	FDW 配置	新建，未执行
pyproject.toml	根配置	新建 uv workspace 配置
.env.template	环境配置	新建模板

验证结果

• ETL 单元测试：516 passed / 5 failed（源仓库已有 bug）/ 2 skipped
• 核心业务逻辑无回归
• DB Schema：新建 DDL 文件，未在生产数据库执行，无数据风险
• Steering 路径更新：grep 验证无旧路径残留

内联注释决策

• AI_CHANGELOG：不添加。所有文件均为新建/原样复制，无"修改"语义
• CHANGE 注释：不添加。ETL 代码原样复制，未修改现有逻辑

后续建议

1. 在 C:\NeoZQYY\apps\etl\pipelines\feiqiu\ 下运行 pytest tests/unit 确认测试通过
2. 修复源仓库已有的 5 个失败测试
3. DB Schema DDL 在测试环境验证后再应用到生产
4. 首次 git add . && git commit 建立基线