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

需求文档：Monorepo 迁移

简介

将现有台球厅运营助手项目从单一 ETL 仓库（FQ-ETL）扩展为 Monorepo 单体仓库（NeoZQYY），整合 ETL 管线、微信小程序后端、小程序前端、管理后台等多个子项目。迁移采用一次性搬迁策略，不保留 Git 历史，所有架构决策已在前期讨论中确认。

术语表

• Monorepo：单体仓库，多个子项目共存于同一 Git 仓库中
• ETL_Pipeline：数据抽取-转换-加载管线，负责从上游 SaaS API 抓取数据并逐层处理
• ODS：操作数据存储层（Operational Data Store），保留源 payload
• DWD：明细数据层（Data Warehouse Detail），清洗后的明细数据
• DWS：数据服务层（Data Warehouse Service），汇总与聚合数据
• Core：统一维度/事实最小字段集层，位于 DWD 与 DWS 之间
• App_Schema：应用层 schema，提供视图/函数 + RLS 供外部访问
• Meta_Schema：元数据层 schema，存储 ETL 调度、游标、运行记录
• FDW：PostgreSQL 外部数据包装器（Foreign Data Wrapper），用于跨库只读映射
• uv_Workspace：Python 包管理工具 uv 的 workspace 模式，管理多包依赖
• RLS：行级安全策略（Row Level Security），用于多门店数据隔离
• SCD2：缓慢变化维度类型 2（Slowly Changing Dimension Type 2），维度历史追踪
• etl_feiqiu：飞球平台 ETL 数据库实例名
• zqyy_app：业务应用数据库实例名（用户/权限/任务/审批）
• site_id：门店标识字段，用于多门店数据隔离
• Scaffold：项目骨架，包含目录结构、配置文件、README 等基础设施

需求

需求 1：Monorepo 骨架搭建

用户故事： 作为开发者，我希望在 C:\NeoZQYY\ 创建完整的 Monorepo 目录结构和基础配置，以便所有子项目有统一的组织方式和开发规范。

验收标准

1. WHEN Scaffold 初始化执行时，THE Scaffold SHALL 在 C:\NeoZQYY\ 下创建以下一级目录：apps/、gui/、packages/、db/、docs/、infra/、scripts/、samples/、tests/、tmp/、.kiro/
2. WHEN Scaffold 初始化执行时，THE Scaffold SHALL 在 apps/ 下创建子目录：etl/（含 pipelines/feiqiu/）、backend/、miniprogram/、admin-web/
3. WHEN Scaffold 初始化执行时，THE Scaffold SHALL 在 db/ 下创建子目录：etl_feiqiu/（含 schemas/、migrations/、seeds/）、zqyy_app/（含 schemas/、migrations/、seeds/）、fdw/
4. WHEN Scaffold 初始化执行时，THE Scaffold SHALL 在 docs/ 下创建子目录：prd/、contracts/（含 openapi/、schemas/、data_dictionary/）、permission_matrix/、architecture/、database/、h5_ui/、ops/、audit/、roadmap/
5. THE Scaffold SHALL 为每个一级目录生成 README.md 文件，包含该目录的作用说明、内部结构描述和 Roadmap 段落
6. WHEN 某个功能"暂不实施但未来必须做"时，THE Scaffold SHALL 将该内容记录在对应目录 README.md 的 Roadmap 段落中

需求 2：Git 仓库与版本控制配置

用户故事： 作为开发者，我希望新 Monorepo 有正确的 Git 配置，以便代码版本管理规范且安全。

验收标准

1. WHEN Git 仓库初始化时，THE Scaffold SHALL 创建新的 Git 仓库，不迁移旧仓库历史
2. THE Scaffold SHALL 生成 .gitignore 文件，排除 tmp/、__pycache__/、.env（非模板）、*.pyc、.hypothesis/、.pytest_cache/、logs/、node_modules/、虚拟环境目录等
3. THE Scaffold SHALL 生成 .kiroignore 文件，排除不需要 Kiro 索引的目录

需求 3：Python 包管理与 uv Workspace 配置

用户故事： 作为开发者，我希望使用 pyproject.toml + uv workspace 管理多包依赖，以便各子项目的依赖隔离且可统一管理。

验收标准

1. THE Scaffold SHALL 在 Monorepo 根目录生成 pyproject.toml，配置 uv workspace 并声明所有 Python 子项目成员
2. THE Scaffold SHALL 为每个 Python 子项目（apps/etl/pipelines/feiqiu/、apps/backend/、packages/shared/、gui/）生成独立的 pyproject.toml
3. WHEN 子项目声明对 packages/shared 的依赖时，THE uv_Workspace SHALL 通过 workspace 路径引用解析该依赖

需求 4：环境配置隔离

用户故事： 作为开发者，我希望公共配置和各应用私有配置分层管理，以便敏感信息不泄露且配置不冲突。

验收标准

1. THE Scaffold SHALL 在 Monorepo 根目录生成 .env.template 文件，包含公共配置项（数据库主机、端口等非敏感信息）的模板
2. WHEN 各应用需要私有配置时，THE Scaffold SHALL 支持在应用目录下放置 .env.local 文件覆盖公共配置
3. IF 公共 .env 与应用 .env.local 存在同名配置项且值冲突，THEN THE 配置加载器 SHALL 以应用级 .env.local 的值为准
4. IF 必需的配置项在所有层级均缺失，THEN THE 配置加载器 SHALL 在启动时报告明确的错误信息，指出缺失的配置项名称

需求 5：ETL 项目平移

用户故事： 作为开发者，我希望将现有 ETL 项目整体平移到 Monorepo 中，以便 ETL 功能在新仓库中正常运行。

验收标准

1. WHEN ETL 平移执行时，THE 迁移脚本 SHALL 将 C:\ZQYY\FQ-ETL 的业务代码（api/、cli/、config/、loaders/、models/、orchestration/、scd/、tasks/、utils/、quality/）复制到 apps/etl/pipelines/feiqiu/
2. WHEN ETL 平移执行时，THE 迁移脚本 SHALL 将 database/ 目录的 DDL、seed、migration 文件迁移到 db/etl_feiqiu/ 对应子目录
3. WHEN ETL 平移执行时，THE 迁移脚本 SHALL 将 tests/ 目录复制到 apps/etl/pipelines/feiqiu/tests/
4. WHEN ETL 平移完成后，THE ETL_Pipeline SHALL 通过 pytest tests/unit 验证所有单元测试通过
5. IF ETL 内部存在需要调整的 import 路径，THEN THE 迁移脚本 SHALL 更新这些路径以适配新目录结构
6. WHEN ETL 平移执行时，THE 迁移脚本 SHALL 将现有 gui/ 目录迁移到 Monorepo 顶层 gui/

需求 6：小程序前端平移

用户故事： 作为开发者，我希望将微信小程序项目迁移到 Monorepo 中，以便前端代码与后端统一管理。

验收标准

1. WHEN 小程序平移执行时，THE 迁移脚本 SHALL 将 C:\ZQYY\XCX 的项目文件复制到 apps/miniprogram/
2. WHEN 小程序平移执行时，THE 迁移脚本 SHALL 将 C:\ZQYY\XCX\Prototype 目录复制到 docs/h5_ui/
3. WHEN 小程序平移完成后，THE 小程序项目 SHALL 保持原有的 Donut + TDesign 技术栈配置不变

需求 7：数据库 Schema 重组（etl_feiqiu）

用户故事： 作为数据工程师，我希望将 ETL 数据库重组为六层 schema 架构，以便数据分层清晰、职责明确。

验收标准

1. THE 数据库迁移 SHALL 为 etl_feiqiu 数据库创建六个 schema：meta、ods、dwd、core、dws、app
2. WHEN meta schema 创建时，THE DDL SHALL 包含 ETL 调度、游标、运行记录相关表（从现有 etl_admin schema 迁移）
3. WHEN ods schema 创建时，THE DDL SHALL 包含现有 billiards_ods 的所有表定义
4. WHEN dwd schema 创建时，THE DDL SHALL 保留现有 main + EX 拆分模式（因字段量大）
5. WHEN core schema 创建时，THE DDL SHALL 仅包含统一维度表和事实表的最小字段集
6. WHEN dws schema 创建时，THE DDL SHALL 包含现有 billiards_dws 的汇总表定义（助教业绩、财务日报、工资计算等）
7. WHEN app schema 创建时，THE DDL SHALL 创建面向外部访问的视图和函数，并配置 RLS 策略以 site_id 隔离多门店数据
8. THE 数据库迁移 SHALL 将所有 DDL 文件存放在 db/etl_feiqiu/schemas/ 目录下，每个 schema 一个独立文件

需求 8：业务数据库设计（zqyy_app）

用户故事： 作为后端开发者，我希望有独立的业务数据库存储用户、权限、任务、审批等应用数据，以便业务逻辑与 ETL 数据解耦。

验收标准

1. THE 数据库迁移 SHALL 为 zqyy_app 数据库创建用户管理、权限控制、任务管理、审批流程相关的表结构
2. THE 数据库迁移 SHALL 将 zqyy_app 的 DDL 文件存放在 db/zqyy_app/schemas/ 目录下
3. WHEN zqyy_app 需要访问 ETL 数据时，THE FDW 配置 SHALL 通过 postgres_fdw 将 etl_feiqiu 的 app schema 映射为 zqyy_app 中的外部表
4. THE FDW 配置 SHALL 以只读方式映射，zqyy_app 不存储 ETL 数据的副本
5. THE FDW 配置文件 SHALL 存放在 db/fdw/ 目录下

需求 9：测试数据库镜像

用户故事： 作为开发者，我希望有与生产结构完全一致的测试数据库，以便在不影响生产数据的情况下进行开发和测试。

验收标准

1. THE 数据库迁移 SHALL 创建 test_etl_feiqiu 数据库，其 schema 结构与 etl_feiqiu 完全一致
2. THE 数据库迁移 SHALL 创建 test_zqyy_app 数据库，其 schema 结构与 zqyy_app 完全一致
3. WHEN 测试数据库创建完成后，THE 迁移脚本 SHALL 提供从现有 LLZQ-test 数据库迁移测试数据到新结构的脚本
4. WHEN 生产数据库 schema 发生变更时，THE 测试数据库 SHALL 同步应用相同的迁移脚本以保持结构一致

需求 10：.kiro 配置迁移与 Steering 更新

用户故事： 作为开发者，我希望 Kiro IDE 的配置和 steering 文件适配 Monorepo 结构，以便 AI 辅助开发在新仓库中正常工作。

验收标准

1. WHEN .kiro 迁移执行时，THE 迁移脚本 SHALL 将现有 .kiro/steering/ 文件复制到 Monorepo 的 .kiro/steering/
2. WHEN .kiro 迁移完成后，THE Steering 文件 SHALL 更新所有路径引用以反映 Monorepo 目录结构
3. WHEN .kiro 迁移完成后，THE Steering 文件 SHALL 更新 product.md、tech.md、structure.md 为 Monorepo 视角的内容

需求 11：FastAPI 后端骨架

用户故事： 作为后端开发者，我希望有 FastAPI 项目骨架，以便快速开始小程序后端 API 的开发。

验收标准

1. WHEN 后端骨架创建时，THE Scaffold SHALL 在 apps/backend/ 下生成 FastAPI 项目结构，包含入口文件、路由目录、中间件目录、配置文件
2. THE 后端骨架 SHALL 配置 OpenAPI 文档自动生成
3. THE 后端骨架 SHALL 配置数据库连接模块，支持连接 zqyy_app 数据库
4. THE 后端骨架 SHALL 包含独立的 pyproject.toml，声明 FastAPI 及相关依赖

需求 12：共享包基础结构

用户故事： 作为开发者，我希望有统一的共享包存放跨项目复用的工具代码，以便避免代码重复。

验收标准

1. WHEN 共享包创建时，THE Scaffold SHALL 在 packages/shared/ 下生成 Python 包结构，包含 __init__.py 和 pyproject.toml
2. THE 共享包 SHALL 提取并包含以下通用工具模块：字段枚举定义、金额精度处理工具（CNY，numeric(2)）、时间处理工具
3. WHEN ETL 或后端项目引用共享包时，THE uv_Workspace SHALL 通过 workspace 路径依赖解析 packages/shared

需求 13：多门店数据隔离

用户故事： 作为系统架构师，我希望在同一数据库内通过 RLS 实现多门店数据隔离，以便未来扩展到多门店场景。

验收标准

1. THE 数据库设计 SHALL 在所有业务表中包含 site_id 字段标识门店归属
2. WHEN RLS 策略启用时，THE 数据库 SHALL 根据当前会话的 site_id 参数自动过滤查询结果，仅返回该门店的数据
3. WHEN 每个门店运行 ETL 时，THE ETL_Pipeline SHALL 作为独立进程执行，使用该门店的 site_id 标识数据

需求 14：基础设施配置管理

用户故事： 作为运维人员，我希望基础设施配置纳入版本控制，以便环境配置可追溯、可复现。

需求15：避免影响kiro性能，完成Monorepo后，根据文件和目录结构。编辑.kiroignore

验收标准：完善

验收标准

1. THE Scaffold SHALL 在 infra/ 下创建 jump_proxy/、tailscale/、firewall/ 子目录
2. THE infra 目录 SHALL 纳入 Git 版本控制
3. IF infra 目录中包含敏感配置文件，THEN THE .gitignore SHALL 排除这些敏感文件，同时保留非敏感的配置模板