root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ded6dfb9d8b3252d96e9545412156172f91fd492
Neo-ZQYY/.kiro/specs/monorepo-migration/tasks.md

11 KiB
Raw Blame History

实施计划：Monorepo 迁移

概述

将现有 ETL 仓库迁移为 Monorepo 单体仓库，分 7 个阶段执行。每个阶段包含具体的代码/文件操作任务，按依赖顺序排列。

任务

  • 1. Monorepo 骨架搭建

    • 1.1 在 C:\NeoZQYY\ 创建完整目录结构

      • 创建所有一级目录：apps/、gui/、packages/、db/、docs/、infra/、scripts/、samples/、tests/、tmp/、.kiro/
      • 创建 apps/ 子目录：etl/pipelines/feiqiu/、backend/、miniprogram/、admin-web/
      • 创建 db/ 子目录：etl_feiqiu/schemas/、etl_feiqiu/migrations/、etl_feiqiu/seeds/、zqyy_app/schemas/、zqyy_app/migrations/、zqyy_app/seeds/、fdw/
      • 创建 docs/ 子目录：prd/、contracts/openapi/、contracts/schemas/、contracts/data_dictionary/、permission_matrix/、architecture/、database/、h5_ui/、ops/、audit/、roadmap/
      • 创建 infra/ 子目录：jump_proxy/、tailscale/、firewall/
      • Requirements: 1.1, 1.2, 1.3, 1.4, 14.1

    • 1.2 生成所有一级目录的 README.md

      • 每个 README 包含：作用说明、内部结构描述、Roadmap 段落
      • 一级目录列表：apps/、gui/、packages/、db/、docs/、infra/、scripts/、samples/、tests/
      • apps/etl/README.md 的 Roadmap 记录未来 sdk/connectors 拆分计划
      • packages/README.md 的 Roadmap 记录 etl_sdk、authz、data_contracts 候选
      • db/README.md 的 Roadmap 记录 FDW 演进计划
      • Requirements: 1.5, 1.6

    • 1.3 编写 README 结构完整性属性测试

      • Property 1: README.md 结构完整性
      • Validates: Requirements 1.5

    • 1.4 初始化 Git 仓库并生成版本控制配置

      • 在 C:\NeoZQYY\ 执行 git init
      • 生成 .gitignore：排除 tmp/、__pycache__/、.env、*.pyc、.hypothesis/、.pytest_cache/、logs/、node_modules/、虚拟环境目录、infra/ 下的敏感文件
      • 生成 .kiroignore
      • Requirements: 2.1, 2.2, 2.3, 14.2, 14.3

    • 1.5 配置 pyproject.toml 和 uv workspace

      • 生成根 pyproject.toml，声明 workspace 成员：apps/etl/pipelines/feiqiu、apps/backend、packages/shared、gui
      • 为每个 Python 子项目生成独立 pyproject.toml
      • Requirements: 3.1, 3.2

    • 1.6 编写 Python 子项目配置完整性属性测试

      • Property 2: Python 子项目配置完整性
      • Validates: Requirements 3.2

    • 1.7 生成环境配置模板

      • 生成根 .env.template，包含公共配置项模板（DB_HOST、DB_PORT、TIMEZONE 等）
      • Requirements: 4.1

  • 2. 检查点 - 骨架验证

    • 确保所有目录和文件已创建，ask the user if questions arise.

  • 3. ETL 项目平移

    • 3.1 复制 ETL 业务代码到 Monorepo

      • 将 C:\ZQYY\FQ-ETL 的 api/、cli/、config/、loaders/、models/、orchestration/、scd/、tasks/、utils/、quality/ 复制到 apps/etl/pipelines/feiqiu/
      • 将 tests/ 复制到 apps/etl/pipelines/feiqiu/tests/
      • 将 requirements.txt、pytest.ini、run_etl.bat、run_etl.sh 复制到 apps/etl/pipelines/feiqiu/
      • Requirements: 5.1, 5.3

    • 3.2 迁移数据库文件到 db/etl_feiqiu/

      • 将 database/schema_*.sql 复制到 db/etl_feiqiu/schemas/
      • 将 database/migrations/ 复制到 db/etl_feiqiu/migrations/
      • 将 database/seed_*.sql 复制到 db/etl_feiqiu/seeds/
      • 将 database/connection.py、database/operations.py、database/base.py 保留在 ETL 内部（apps/etl/pipelines/feiqiu/database/）
      • Requirements: 5.2

    • 3.3 迁移 GUI 到顶层

      • 将 C:\ZQYY\FQ-ETL\gui/ 复制到 C:\NeoZQYY\gui/
      • 生成 gui/pyproject.toml，声明 PySide6 依赖
      • Requirements: 5.6

    • 3.4 调整 ETL 的 pyproject.toml 和 pytest.ini

      • 更新 apps/etl/pipelines/feiqiu/pyproject.toml，从 requirements.txt 提取依赖
      • 更新 apps/etl/pipelines/feiqiu/pytest.ini，设置 pythonpath = .
      • Requirements: 5.4, 5.5

    • 3.5 编写文件迁移完整性属性测试

      • Property 5: 文件迁移完整性
      • Validates: Requirements 5.1, 5.2, 5.3

  • 4. 检查点 - ETL 平移验证

    • 在 apps/etl/pipelines/feiqiu/ 下运行 pytest tests/unit，确保所有单元测试通过
    • Ensure all tests pass, ask the user if questions arise.

  • 5. 小程序前端平移

    • 5.1 复制小程序项目到 Monorepo
      • 将 C:\ZQYY\XCX\（除 Prototype 目录）复制到 apps/miniprogram/
      • 将 C:\ZQYY\XCX\Prototype\ 复制到 docs/h5_ui/
      • 生成 apps/miniprogram/README.md
      • Requirements: 6.1, 6.2, 6.3

  • 6. 数据库 Schema 重组

    • 6.1 编写 etl_feiqiu 六层 Schema DDL

      • 创建 db/etl_feiqiu/schemas/meta.sql：从现有 etl_admin schema 迁移调度、游标、运行记录表
      • 创建 db/etl_feiqiu/schemas/ods.sql：从现有 billiards_ods 迁移所有表定义，schema 名改为 ods
      • 创建 db/etl_feiqiu/schemas/dwd.sql：从现有 billiards_dwd 迁移，保留 main+EX 拆分
      • 创建 db/etl_feiqiu/schemas/core.sql：设计统一维度/事实最小字段集表
      • 创建 db/etl_feiqiu/schemas/dws.sql：从现有 billiards_dws 迁移汇总表
      • 创建 db/etl_feiqiu/schemas/app.sql：创建面向外部的视图 + RLS 策略（以 site_id 隔离）
      • Requirements: 7.1, 7.2, 7.3, 7.4, 7.5, 7.6, 7.7, 7.8

    • 6.2 编写 Schema 表定义迁移完整性属性测试

      • Property 6: Schema 表定义迁移完整性
      • Validates: Requirements 7.3, 7.6

    • 6.3 编写 Core schema 最小字段集属性测试

      • Property 7: Core schema 最小字段集
      • Validates: Requirements 7.5

    • 6.4 编写 zqyy_app 数据库 Schema DDL

      • 创建 db/zqyy_app/schemas/init.sql：用户表、角色表、权限表、用户角色关联表、任务表、审批表
      • 所有业务表包含 site_id 字段
      • Requirements: 8.1, 8.2, 13.1

    • 6.5 编写 FDW 映射配置

      • 创建 db/fdw/setup_fdw.sql：CREATE SERVER、CREATE USER MAPPING（只读角色）、IMPORT FOREIGN SCHEMA
      • Requirements: 8.3, 8.4, 8.5

    • 6.6 编写业务表 site_id 存在性属性测试

      • Property 10: 业务表 site_id 字段存在性
      • Validates: Requirements 13.1

    • 6.7 编写测试数据库创建脚本

      • 创建 db/etl_feiqiu/scripts/create_test_db.sql：创建 test_etl_feiqiu，复用生产 DDL
      • 创建 db/zqyy_app/scripts/create_test_db.sql：创建 test_zqyy_app，复用生产 DDL
      • 创建 db/scripts/migrate_test_data.sql：从 LLZQ-test 迁移测试数据的脚本
      • Requirements: 9.1, 9.2, 9.3

    • 6.8 编写测试数据库结构一致性属性测试

      • Property 8: 测试数据库结构一致性
      • Validates: Requirements 9.1, 9.2

  • 7. 检查点 - 数据库 Schema 验证

    • 确保所有 DDL 文件语法正确，ask the user if questions arise.

  • 8. .kiro 迁移与 Steering 更新

    • [-] 8.1 复制 .kiro/steering/ 到 Monorepo

      • 将 C:\ZQYY\FQ-ETL\.kiro\steering\ 所有文件复制到 C:\NeoZQYY\.kiro\steering\
      • 将 C:\ZQYY\FQ-ETL\.kiro\specs\ 复制到 C:\NeoZQYY\.kiro\specs\（包含本 spec）
      • Requirements: 10.1

    • [~] 8.2 更新 Steering 文件为 Monorepo 视角

      • 更新 product.md：从单一 ETL 扩展为 Monorepo 全局视角（ETL + 后端 + 小程序 + GUI）
      • 更新 tech.md：新增 FastAPI、uv workspace、Donut+TDesign 技术栈
      • 更新 structure-lite.md：反映 Monorepo 目录结构和模块边界
      • 更新所有 steering 文件中的路径引用，移除旧仓库路径（FQ-ETL、C:\ZQYY\FQ-ETL）
      • Requirements: 10.2, 10.3

    • [~] 8.3 编写 Steering 文件路径更新属性测试

      • Property 9: Steering 文件路径更新
      • Validates: Requirements 10.2

  • 9. FastAPI 后端骨架

    • [~] 9.1 创建 FastAPI 项目结构

      • 创建 apps/backend/app/__init__.py、main.py、config.py、database.py
      • 创建 apps/backend/app/routers/__init__.py
      • 创建 apps/backend/app/middleware/__init__.py
      • 创建 apps/backend/app/schemas/__init__.py
      • 创建 apps/backend/tests/__init__.py
      • main.py 中配置 FastAPI 实例，启用 OpenAPI 文档自动生成
      • database.py 中配置 zqyy_app 数据库连接
      • Requirements: 11.1, 11.2, 11.3

    • [~] 9.2 生成 apps/backend/pyproject.toml

      • 声明 FastAPI、uvicorn、psycopg2-binary、neozqyy-shared 等依赖
      • 配置 uv workspace 源引用 neozqyy-shared
      • Requirements: 11.4

    • [~] 9.3 生成 apps/backend/README.md

      • 包含作用说明、项目结构、启动方式、Roadmap
      • Requirements: 1.5

  • 10. 共享包搭建

    • [~] 10.1 创建 packages/shared 包结构

      • 创建 packages/shared/src/neozqyy_shared/__init__.py
      • 创建 packages/shared/src/neozqyy_shared/enums.py：字段枚举定义（从 ETL models/ 提取通用枚举）
      • 创建 packages/shared/src/neozqyy_shared/money.py：金额精度工具（Decimal + ROUND_HALF_UP，scale=2）
      • 创建 packages/shared/src/neozqyy_shared/datetime_utils.py：时区转换、日期范围计算
      • 创建 packages/shared/tests/__init__.py
      • Requirements: 12.1, 12.2

    • [~] 10.2 生成 packages/shared/pyproject.toml

      • 声明包名 neozqyy-shared，最小依赖（python-dateutil、tzdata）
      • Requirements: 12.3

    • [~] 10.3 编写配置优先级属性测试

      • Property 3: 配置优先级 - .env.local 覆盖
      • Validates: Requirements 4.3

    • [~] 10.4 编写必需配置缺失检测属性测试

      • Property 4: 必需配置缺失检测
      • Validates: Requirements 4.4

  • 11. 检查点 - 全局验证

    • 验证 uv workspace 依赖解析：在根目录运行 uv sync
    • 验证 ETL 单元测试：在 apps/etl/pipelines/feiqiu/ 下运行 pytest tests/unit
    • Ensure all tests pass, ask the user if questions arise.

  • 12. RLS 与多门店隔离验证

    • [~] 12.1 编写 RLS 按 site_id 隔离属性测试
      • Property 11: RLS 按 site_id 隔离
      • Validates: Requirements 13.2
      • 需要集成测试环境（test_etl_feiqiu 数据库）

  • 13. 最终检查点

    • 确保所有文件已创建、所有 README 已编写、所有 DDL 语法正确
    • Ensure all tests pass, ask the user if questions arise.

备注

  • 标记 * 的任务为可选测试任务，可跳过以加速 MVP
  • 每个任务引用具体需求编号，确保可追溯
  • 检查点确保增量验证，避免问题累积
  • 属性测试验证通用正确性，单元测试验证具体边界情况
  • 文件复制操作需要用户在终端手动执行（涉及跨目录操作），Kiro 负责生成目标文件内容
Reference in New Issue View Git Blame Copy Permalink