Neo-ZQYY/.kiro/specs/monorepo-migration/tasks.md

# 实施计划：Monorepo 迁移

## 概述

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

## 任务

- [x] 1. Monorepo 骨架搭建
  - [x] 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_

  - [x] 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_

  - [x] 1.3 编写 README 结构完整性属性测试
    - **Property 1: README.md 结构完整性**
    - **Validates: Requirements 1.5**

  - [x] 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_

  - [x] 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_

  - [x] 1.6 编写 Python 子项目配置完整性属性测试
    - **Property 2: Python 子项目配置完整性**
    - **Validates: Requirements 3.2**

  - [x] 1.7 生成环境配置模板
    - 生成根 `.env.template`，包含公共配置项模板（DB_HOST、DB_PORT、TIMEZONE 等）
    - _Requirements: 4.1_

- [x] 2. 检查点 - 骨架验证
  - 确保所有目录和文件已创建，ask the user if questions arise.

- [x] 3. ETL 项目平移
  - [x] 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_

  - [x] 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_

  - [x] 3.3 迁移 GUI 到顶层
    - 将 `C:\ZQYY\FQ-ETL\gui/` 复制到 `C:\NeoZQYY\gui/`
    - 生成 `gui/pyproject.toml`，声明 PySide6 依赖
    - _Requirements: 5.6_

  - [x] 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_

  - [x] 3.5 编写文件迁移完整性属性测试
    - **Property 5: 文件迁移完整性**
    - **Validates: Requirements 5.1, 5.2, 5.3**

- [x] 4. 检查点 - ETL 平移验证
  - 在 `apps/etl/pipelines/feiqiu/` 下运行 `pytest tests/unit`，确保所有单元测试通过
  - Ensure all tests pass, ask the user if questions arise.

- [x] 5. 小程序前端平移
  - [x] 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_

- [x] 6. 数据库 Schema 重组
  - [x] 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_

  - [x] 6.2 编写 Schema 表定义迁移完整性属性测试
    - **Property 6: Schema 表定义迁移完整性**
    - **Validates: Requirements 7.3, 7.6**

  - [x] 6.3 编写 Core schema 最小字段集属性测试
    - **Property 7: Core schema 最小字段集**
    - **Validates: Requirements 7.5**

  - [x] 6.4 编写 zqyy_app 数据库 Schema DDL
    - 创建 `db/zqyy_app/schemas/init.sql`：用户表、角色表、权限表、用户角色关联表、任务表、审批表
    - 所有业务表包含 `site_id` 字段
    - _Requirements: 8.1, 8.2, 13.1_

  - [x] 6.5 编写 FDW 映射配置
    - 创建 `db/fdw/setup_fdw.sql`：CREATE SERVER、CREATE USER MAPPING（只读角色）、IMPORT FOREIGN SCHEMA
    - _Requirements: 8.3, 8.4, 8.5_

  - [x] 6.6 编写业务表 site_id 存在性属性测试
    - **Property 10: 业务表 site_id 字段存在性**
    - **Validates: Requirements 13.1**

  - [x] 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_

  - [x] 6.8 编写测试数据库结构一致性属性测试
    - **Property 8: 测试数据库结构一致性**
    - **Validates: Requirements 9.1, 9.2**

- [x] 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 负责生成目标文件内容