Files
Neo-ZQYY/docs/migrate/monorepo-migration-summary.md

24 KiB
Raw Blame History

NeoZQYY Monorepo 迁移总结

本文档记录从旧仓库到 NeoZQYY Monorepo 的完整迁移过程,供后续维护和开发参考。

1. 背景

1.1 迁移前状态

仓库 路径 内容
FQ-ETL C:\ZQYY\FQ-ETL ETL Connector + 桌面 GUI + 测试 + 文档 + 脚本
XCX C:\ZQYY\XCX\ 微信小程序源码

旧仓库 FQ-ETL 是一个单体项目ETL Connector、GUI、数据库脚本、文档混合在同一目录下缺乏模块边界。

1.2 迁移目标

将所有项目整合为 NeoZQYY MonorepoC:\NeoZQYY\),实现:

  • 清晰的模块边界apps/packages/db/docs 分离)
  • uv workspace 统一依赖管理
  • 六层数据库 Schema 架构meta/ods/dwd/core/dws/app
  • 多门店隔离site_id + RLS
  • FastAPI 后端骨架
  • 共享包(枚举、金额精度、时间工具)
  • 属性测试Property-Based Testing覆盖关键正确性属性

2. Monorepo 最终结构

C:\NeoZQYY\
├── apps/
│   ├── etl/pipelines/feiqiu/    # 飞球 Connector数据源连接器从 FQ-ETL 平移)
│   ├── backend/                  # FastAPI 后端(新建骨架)
│   ├── miniprogram/              # 微信小程序(从 XCX 平移)
│   └── admin-web/                # 管理后台(占位)
├── gui/                          # PySide6 桌面 GUI从 FQ-ETL 平移)
├── packages/shared/              # 跨项目共享包(新建)
├── db/
│   ├── etl_feiqiu/schemas/       # 六层 Schema DDL新建
│   ├── etl_feiqiu/migrations/    # ETL 迁移脚本(从 FQ-ETL 平移)
│   ├── etl_feiqiu/seeds/         # 种子数据(从 FQ-ETL 平移)
│   ├── etl_feiqiu/scripts/       # 测试数据库脚本(新建)
│   ├── zqyy_app/schemas/         # 业务数据库 DDL新建
│   └── fdw/                      # FDW 跨库映射(新建)
├── docs/                         # 文档(从 FQ-ETL 平移 + 新增)
├── infra/                        # 基础设施配置(占位)
├── scripts/                      # 运维脚本(从 FQ-ETL 平移)
├── samples/                      # 示例数据(占位)
├── tests/                        # Monorepo 级属性测试(新建)
├── tmp/                          # 临时文件gitignore
├── .kiro/                        # Kiro 配置
├── pyproject.toml                # uv workspace 根配置
├── .env.template                 # 环境变量模板
├── .gitignore
├── .kiroignore
└── README.md

3. 文件映射关系

3.1 ETL Connector飞球

旧路径FQ-ETL 新路径NeoZQYY
api/ apps/etl/pipelines/feiqiu/api/
cli/ apps/etl/pipelines/feiqiu/cli/
config/ apps/etl/pipelines/feiqiu/config/
database/ apps/etl/pipelines/feiqiu/database/
loaders/ apps/etl/pipelines/feiqiu/loaders/
models/ apps/etl/pipelines/feiqiu/models/
orchestration/ apps/etl/pipelines/feiqiu/orchestration/
scd/ apps/etl/pipelines/feiqiu/scd/
tasks/ apps/etl/pipelines/feiqiu/tasks/
utils/ apps/etl/pipelines/feiqiu/utils/
quality/ apps/etl/pipelines/feiqiu/quality/
tests/ apps/etl/pipelines/feiqiu/tests/
scripts/ scripts/(根级)
docs/ docs/(根级)
pytest.ini apps/etl/pipelines/feiqiu/pytest.ini
requirements.txt 已转化为 apps/etl/pipelines/feiqiu/pyproject.toml

3.2 数据库文件

旧路径FQ-ETL 新路径NeoZQYY
database/schema/ db/etl_feiqiu/schemas/(重构为六层 DDL
database/migrations/ db/etl_feiqiu/migrations/
database/seeds/ db/etl_feiqiu/seeds/
database/*.py apps/etl/pipelines/feiqiu/database/Python 模块保留在 ETL 内部)

3.3 GUI

旧路径FQ-ETL 新路径NeoZQYY
gui/ gui/(根级,独立于 apps

3.4 小程序

旧路径 新路径NeoZQYY
C:\ZQYY\XCX\ apps/miniprogram/
原型设计稿 docs/h5_ui/

3.5 Kiro 配置

旧路径FQ-ETL 新路径NeoZQYY
.kiro/steering/ .kiro/steering/(内容已更新为 Monorepo 视角)
.kiro/specs/ .kiro/specs/
.kiro/hooks/ .kiro/hooks/
.kiro/scripts/ .kiro/scripts/
.kiro/agents/ .kiro/agents/
.kiro/skills/ .kiro/skills/
.kiro/settings/ .kiro/settings/

4. 新建内容(非平移)

4.1 六层数据库 Schema DDL

db/etl_feiqiu/schemas/ 下新建 6 个 DDL 文件:

文件 Schema 用途
meta.sql meta 调度元数据:游标、运行记录、任务注册
ods.sql ods 操作数据存储层:原始 API 数据落地
dwd.sql dwd 明细数据层清洗后的维度表SCD2和事实表
core.sql core 统一最小字段集:跨门店标准化视图
dws.sql dws 数据服务层:汇总表(业绩、财务、会员分析)
app.sql app 应用视图层:启用 RLS按 site_id 过滤

4.2 业务数据库

文件 用途
db/zqyy_app/schemas/init.sql 业务应用数据库用户、RBAC、任务、审批7 张表均含 site_id
db/fdw/setup_fdw.sql postgres_fdw 配置zqyy_app 只读映射 etl_feiqiu.app schema

4.3 FastAPI 后端骨架

apps/backend/ 下新建:

  • app/main.py — FastAPI 入口,启用 OpenAPI 文档
  • app/config.py — 配置加载
  • app/database.py — zqyy_app 数据库连接
  • app/routers/ — 路由模块(占位)
  • app/middleware/ — 中间件(占位)
  • app/schemas/ — Pydantic 模型(占位)
  • pyproject.toml — 依赖声明fastapi, uvicorn, psycopg2-binary, neozqyy-shared

4.4 共享包

packages/shared/ 下新建:

  • src/neozqyy_shared/__init__.py
  • src/neozqyy_shared/enums.py — 字段枚举
  • src/neozqyy_shared/money.py — 金额精度工具
  • src/neozqyy_shared/datetime_utils.py — 时间处理工具

4.5 属性测试Property-Based Testing

tests/ 下新建 11 个属性测试文件,使用 hypothesis 库:

文件 Property 验证内容
test_property_readme_structure.py P1 README 结构完整性(三段式)
test_property_pyproject_completeness.py P2 pyproject.toml 完整性
test_property_config_priority.py P3 配置优先级(分层叠加)
test_property_config_missing.py P4 缺失配置检测
test_property_file_migration.py P5 文件迁移完整性
test_property_schema_migration.py P6 Schema 迁移完整性
test_property_core_minimal_fields.py P7 Core 最小字段集
test_property_test_db_consistency.py P8 测试数据库一致性
test_property_steering_paths.py P9 Steering 文件路径更新
test_property_site_id_existence.py P10 site_id 字段存在性
test_property_rls_site_id.py P11 RLS 按 site_id 隔离

4.6 uv Workspace 配置

pyproject.toml 声明 4 个 workspace 成员:

  • apps/etl/pipelines/feiqiu
  • apps/backend
  • packages/shared
  • gui

5. 迁移处理方式

5.1 文件复制策略

  • 使用 robocopy /E 进行跨目录批量复制Windows 环境)
  • ETL 业务代码11 个目录)整体平移,保持内部结构不变
  • requirements.txt 转化为 pyproject.toml 依赖声明
  • pytest.ini 保留在 ETL 子项目内,pythonpath = . 确保导入正确

5.2 数据库重构策略

旧仓库 database/ 目录混合了 DDLSQL和 Python 代码,迁移时按职责拆分:

5.2.1 文件拆分与去向

旧文件FQ-ETL database/ 新位置NeoZQYY 处理方式
schema_ODS_doc.sql db/etl_feiqiu/schemas/schema_ODS_doc.sql 原样复制(保留为历史参考)
schema_dwd_doc.sql db/etl_feiqiu/schemas/schema_dwd_doc.sql 原样复制(保留为历史参考)
schema_dws.sql db/etl_feiqiu/schemas/schema_dws.sql 原样复制(保留为历史参考)
schema_etl_admin.sql db/etl_feiqiu/schemas/schema_etl_admin.sql 原样复制(保留为历史参考)
schema_verify_perf_indexes.sql db/etl_feiqiu/schemas/schema_verify_perf_indexes.sql 原样复制
seed_dws_config.sql db/etl_feiqiu/seeds/seed_dws_config.sql 原样复制
seed_index_parameters.sql db/etl_feiqiu/seeds/seed_index_parameters.sql 原样复制
seed_ods_tasks.sql db/etl_feiqiu/seeds/seed_ods_tasks.sql 原样复制
seed_scheduler_tasks.sql db/etl_feiqiu/seeds/seed_scheduler_tasks.sql 原样复制
migrations/6 个 SQL db/etl_feiqiu/migrations/ 原样复制
connection.py apps/etl/pipelines/feiqiu/database/connection.py 保留在 ETL 内部
operations.py apps/etl/pipelines/feiqiu/database/operations.py 保留在 ETL 内部
base.py apps/etl/pipelines/feiqiu/database/base.py 保留在 ETL 内部
__init__.py apps/etl/pipelines/feiqiu/database/__init__.py 保留在 ETL 内部

5.2.2 新建六层 Schema DDL

db/etl_feiqiu/schemas/ 下新建 6 个 DDL 文件,定义 NeoZQYY 的目标六层架构:

文件 Schema 内容来源
meta.sql meta schema_etl_admin.sql 提取调度/游标/运行记录表,重命名为 meta schema
ods.sql ods schema_ODS_doc.sql 提取 ODS 表定义
dwd.sql dwd schema_dwd_doc.sql 提取维度表SCD2和事实表
core.sql core 新建:统一最小字段集视图
dws.sql dws schema_dws.sql 提取汇总表定义
app.sql app 新建:面向外部的视图 + RLS 策略(按 site_id 隔离)

注意:旧的 schema_*.sql 文件同时保留在 db/etl_feiqiu/schemas/ 下作为历史参考,新的六层 DDL 文件是目标架构的规范定义。后续应逐步以新文件为准,旧文件可在确认无差异后归档。

5.2.3 新建业务数据库与 FDW

文件 用途
db/zqyy_app/schemas/init.sql 业务应用数据库 DDLusers、roles、user_roles、permissions、role_permissions、tasks、approvals7 张表,均含 site_id
db/fdw/setup_fdw.sql postgres_fdw 配置zqyy_app 只读映射 etl_feiqiu.app schema

5.2.4 测试数据库脚本

文件 用途
db/etl_feiqiu/scripts/create_test_db.sql 创建 test_etl_feiqiu 数据库,结构与 etl_feiqiu 一致
db/zqyy_app/scripts/create_test_db.sql 创建 test_zqyy_app 数据库,结构与 zqyy_app 一致
db/scripts/migrate_test_data.sql 从旧 LLZQ-test 数据库迁移测试数据到新结构

5.2.5 重要说明DDL 与实际数据库的关系

本次迁移仅处理了 DDL 文件的组织和新建,未对远程 PostgreSQL 实例执行任何 DDL 变更。即:

  • 远程数据库仍使用旧的 schema 名称(billiards_odsbilliards_dwdbilliards_dwsetl_admin
  • 新的六层 DDLmeta/ods/dwd/core/dws/app是目标架构的设计文件
  • zqyy_app 数据库和 FDW 配置尚未在远程实例上创建
  • 实际的 schema 重命名/迁移需要后续单独执行(建议通过迁移脚本逐步推进)

5.3 Steering 文件更新

所有 .kiro/steering/ 文件已更新为 Monorepo 视角:

  • 路径引用从 FQ-ETL 改为 NeoZQYY 下的对应路径
  • 模块边界描述更新为新的目录结构
  • 技术栈描述增加 uv workspace、FastAPI、共享包等

5.4 验证策略

采用多层验证:

  1. 属性测试hypothesis— 11 个 Property 覆盖结构、配置、Schema、RLS 等
  2. ETL 单元测试 — 521 passed / 0 failed / 2 skipped
  3. uv sync — 成功解析 21 个包
  4. 多个检查点Task 2/4/7/11/13逐步验证

6. 最终验证结果

验证项 结果
目录结构11 个一级目录) 全部存在
README 文件12 个) 全部存在
DDL 文件8 个) 全部存在
pyproject.toml5 个) 全部存在
配置文件(.env.template/.gitignore/.kiroignore 全部存在
共享包模块4 个) 全部存在
FastAPI 骨架7 个文件) 全部存在
Steering 文件(无旧路径引用) 通过
Kiro hooks/agents/skills/scripts 已复制
uv sync 21 包解析成功
ETL 单元测试 521 passed / 2 skipped
属性测试 19/20 passed1 个内容漂移,非阻塞)

已知问题

  • test_property_file_migration.pytest_source_and_target_file_content_identicaltests/unit/test_audit_run.py 报告内容不一致 — 这是因为源仓库在迁移后继续开发导致的正常漂移,不影响 Monorepo 功能。

7. 后续开发指南

7.1 日常开发

# 安装依赖
cd C:\NeoZQYY
uv sync

# ETL 开发
cd apps/etl/pipelines/feiqiu
python -m cli.main --dry-run --tasks DWD_LOAD_FROM_ODS

# 后端开发
cd apps/backend
uvicorn app.main:app --reload

# 运行 ETL 单元测试
cd apps/etl/pipelines/feiqiu
pytest tests/unit

# 运行属性测试
cd C:\NeoZQYY
pytest tests/ -v

7.2 新增 ETL 任务

  1. apps/etl/pipelines/feiqiu/tasks/ 下创建任务文件
  2. 继承 BaseTask,实现 Extract/Transform/Load
  3. orchestration/task_registry.py 注册
  4. tests/unit/ 下编写单元测试

7.3 数据库变更

  • DDL 变更在 db/etl_feiqiu/schemas/ 对应的 Schema 文件中修改
  • 新增迁移脚本放在 db/etl_feiqiu/migrations/,使用日期前缀命名
  • 变更触发审计governance.md 规则),需运行 /audit
  • 同步更新 docs/database/ 下的表结构文档

7.4 共享包开发

  • packages/shared/src/neozqyy_shared/ 下添加模块
  • 其他子项目通过 neozqyy-shared workspace 引用自动获取更新
  • 运行 uv sync 刷新依赖

7.5 审计与治理

  • 高风险路径变更自动触发审计提醒hooks
  • 手动运行 /audit 生成审计产物
  • 审计记录存放在 docs/audit/changes/

8. 配置体系

分层叠加优先级(低→高):

  1. .env(公共默认值)
  2. 应用 .env.local(私有覆盖)
  3. 环境变量
  4. CLI 参数

敏感值DSN、API Token放在 .env / .env.local 中,禁止提交。.env.template 提供配置项模板。

9. 多门店隔离架构

  • 所有业务表包含 site_id 字段
  • app schema 视图启用 Row Level SecurityRLS
  • RLS 策略通过 current_setting('app.current_site_id') 会话变量过滤
  • zqyy_app 通过 FDW 只读访问 etl_feiqiu.app schema
  • Property 10/11 属性测试验证 site_id 存在性和 RLS 隔离正确性

10. Kiro 配置体系(.kiro/ 目录)

本节详细介绍 .kiro/ 目录下的所有配置,便于在 NeoZQYY 中进行相应调整。

10.1 目录结构

.kiro/
├── steering/           # Steering 文件Agent 上下文注入)
├── hooks/              # Agent Hooks事件驱动自动化
├── scripts/            # Hook 调用的 PowerShell 脚本
├── agents/             # 自定义子代理定义
├── skills/             # 可复用技能包
├── specs/              # Spec 文件(需求→设计→任务)
├── settings/           # Kiro 设置MCP 等)
├── .audit_state.json   # 审计状态(运行时生成)
└── .last_prompt_id.json # 最近 Prompt ID运行时生成

10.2 Steering 文件(.kiro/steering/

Steering 文件在 Agent 对话时自动或按需注入上下文,让 AI 理解项目背景和约束。

文件 加载方式 用途
product.md 自动always 产品概述:功能模块、业务上下文、核心实体、主要入口
tech.md 自动always 技术栈:依赖、数据库架构、测试框架、常用命令、配置体系
structure-lite.md 自动always 项目结构摘要:顶层目录、模块边界、高风险路径、架构要点
structure.md 自动auto 完整目录树 + 架构模式(仅大型重构/跨子系统变更时加载)
governance.md 自动always 治理规则:何时必须审计、执行方式、审计产物
language-zh.md 自动always 语言规范输出简体中文、UTF-8 编码、注释规则
db-docs.md 条件fileMatch 数据库文档规则:当编辑 *.sql/*schema*/*migration* 文件时自动注入
steering-readme-maintainer.md 手动manual 变更影响审查快速参考清单(可通过 # 上下文键加载)

加载方式说明:

  • always:每次对话自动注入
  • auto:满足 front-matter 中 inclusion: auto 条件时注入(如 structure.md 标记为 name: structure-full,需手动通过 # 引用)
  • fileMatch:当读取匹配 fileMatchPattern 的文件时自动注入
  • manual:仅当用户通过 # 上下文键显式引用时注入

10.3 Hooks.kiro/hooks/

Hooks 是事件驱动的自动化机制,在特定 IDE 事件发生时触发 Agent 动作或 Shell 命令。

10.3.1 已启用的 Hooks

Hook 事件 动作类型 功能
audit-flagger promptSubmit runCommand 每次提交 prompt 时,基于 git status 判断是否存在高风险改动,写入 .kiro/.audit_state.json
audit-reminder agentStop runCommand Agent 执行结束时,若存在待审计改动且距上次提醒超过 15 分钟,通过 stderr 输出提醒
prompt-audit-log promptSubmit runCommand 每次提交 prompt 时,在 docs/audit/prompt_logs/ 生成独立日志文件(按时间戳命名)
run-audit-writer userTriggered askAgent 手动触发 /audit:启动 audit-writer 子代理执行变更审计+文档同步+审计落盘
db-docs-sync userTriggered askAgent 手动触发:对比 Postgres 实际 schema 与 docs/database/ 文档,自动补全或更新

10.3.2 已禁用的 Hooks保留备用

Hook 事件 功能 禁用原因
change-impact-review agentStop 每次 Agent 结束后自动执行变更影响审查+审计落盘 改为手动 /audit 子代理流程,避免上下文膨胀
db-schema-doc-enforcer fileEdited*.sql 等) 保存 DB 相关文件时自动更新 docs/database/ /audit 流程统一处理

10.3.3 审计流程工作原理

用户提交 Prompt
    ↓
[audit-flagger] 扫描 git status → 写入 .audit_state.json标记是否需要审计
[prompt-audit-log] 记录 Prompt 到 docs/audit/prompt_logs/
    ↓
Agent 执行用户请求
    ↓
Agent 结束
    ↓
[audit-reminder] 检查 .audit_state.json → 若需审计且超过 15 分钟限频 → stderr 提醒
    ↓
用户手动点击 "Run /audit"
    ↓
[run-audit-writer] 启动 audit-writer 子代理 → 执行审计收口

10.4 Scripts.kiro/scripts/

Hook 调用的 PowerShell 脚本,均使用 Asia/Shanghai 时区Taipei Standard Time

脚本 调用者 功能
audit_flagger.ps1 audit-flagger hook 扫描 git status匹配高风险路径api/cli/config/database/loaders/models/orchestration/scd/tasks/utils/根文件/SQL写入审计状态
audit_reminder.ps1 audit-reminder hook 读取审计状态15 分钟限频提醒,工作树干净时自动清除状态
prompt_audit_log.ps1 prompt-audit-log hook 读取 $env:USER_PROMPT,生成带时间戳的 Prompt 日志文件,更新 .last_prompt_id.json

NeoZQYY 迁移注意:这些脚本中的高风险路径匹配规则(如 ^api/^database/)基于旧仓库的根目录结构。迁移到 NeoZQYY 后ETL 代码位于 apps/etl/pipelines/feiqiu/ 下,需要更新路径匹配规则以适配新结构。同时 hook 文件中的 workspaceFolderName 字段值为 "FQ-ETL",需改为 NeoZQYY 对应的工作区名称。

10.5 Agents.kiro/agents/

自定义子代理,通过 invokeSubAgent 工具调用。

代理 用途
audit-writer 审计收口子代理:基于 git status/diff 和 Prompt 日志执行变更影响审查,按需调用 3 个 skillsteering-readme-maintainer、change-annotation-audit、bd-manual-db-docs生成审计产物完成后清除审计状态并刷新审计一览表

audit-writer 的输出被严格限制为"极短回执"done/files_written/next_step避免审计细节淹没主对话上下文。

10.6 Skills.kiro/skills/

可复用的技能包,由 Agent 或子代理按需调用。每个 skill 包含 SKILL.md(定义)和 assets/(模板)。

Skill 触发条件 产物
steering-readme-maintainer 业务/ETL/API/鉴权/小程序交互等逻辑改动 同步更新 product.md/tech.md/structure-lite.md/README.md输出审计摘要
change-annotation-audit 任何实质性代码/文档修改 docs/audit/changes/<日期>__<slug>.md 审计记录;每个被改文件内 AI_CHANGELOG 条目;逻辑变更处 CHANGE 标记注释
bd-manual-db-docs DB schema/表结构变更 docs/database/ 下的变更日志、表结构文档更新、回滚策略、验证 SQL

10.7 Specs.kiro/specs/

Spec 是结构化的功能开发文档包含需求requirements.md→ 设计design.md→ 任务tasks.md三阶段。

Spec 状态 用途
monorepo-migration 已完成 本次 Monorepo 迁移的完整需求15 个需求涵盖骨架搭建、文件平移、DB 重组、测试等)
repo-audit 已完成 仓库治理只读审计:文件清单、流程树、文档对齐报告
scheduler-refactor 规划中 ETL 调度器重构:拆分为 CLI→PipelineRunner→TaskExecutor 三层架构
etl-task-documentation 已完成 ETL 任务说明文档:覆盖 ODS/DWD/DWS/INDEX 四层所有任务
docs-optimization 已完成 文档体系整理:覆盖度评估、审计一览表、业务规则目录
bd-manual-docs-consolidation 已完成 数据库文档整理目录规范化、DDL 对比同步、ODS 表级文档、字段映射

10.8 Settings.kiro/settings/

文件 用途
mcp.json MCPModel Context Protocol服务器配置。当前为空{}),可按需添加 MCP 服务器

10.9 运行时状态文件

文件 用途 生成者
.audit_state.json 审计状态:是否需要审计、原因、变更文件列表、指纹、上次提醒时间 audit_flagger.ps1
.last_prompt_id.json 最近一次 Prompt 的 ID 和时间戳,供 audit-writer 溯源 prompt_audit_log.ps1

10.10 NeoZQYY 迁移适配清单

从旧仓库迁移到 NeoZQYY 后,以下 .kiro/ 配置需要调整:

  1. Hook 文件中的 workspaceFolderName:所有 hook 的 workspaceFolderName 值为 "FQ-ETL",需改为新工作区名称
  2. audit_flagger.ps1 中的高风险路径:当前匹配 ^api/^database/ 等根级路径ETL 代码已移至 apps/etl/pipelines/feiqiu/ 下,需更新为新路径(如 ^apps/etl/pipelines/feiqiu/api/),同时增加 ^apps/backend/^packages/shared/^db/ 等新高风险路径
  3. audit_reminder.ps1 中的噪声过滤:当前排除 ^docs/audit/^\.kiro/,可能需要增加 ^tmp/
  4. Steering 文件路径引用:已在迁移过程中更新为 NeoZQYY 视角(已完成)
  5. db-docs.md 的 fileMatchPattern:当前匹配 **/migrations/****/*.sql 等,在 NeoZQYY 中仍然适用(使用了通配符)
  6. MCP 配置:根据需要在 settings/mcp.json 中添加 PostgreSQL MCP 服务器等