init: 项目初始提交 - NeoZQYY Monorepo 完整代码

2026-02-15 14:58:14 +08:00
commit ded6dfb9d8
769 changed files with 182616 additions and 0 deletions
--- a/.kiro/specs/monorepo-migration/design.md
+++ b/.kiro/specs/monorepo-migration/design.md
@@ -0,0 +1,553 @@
+# 设计文档：Monorepo 迁移
+
+## 概述
+
+本设计将现有单一 ETL 仓库（`FQ-ETL`）迁移为 Monorepo 单体仓库（`NeoZQYY`），采用一次性搬迁策略。核心设计原则：
+
+1. **最小破坏性**：ETL 整体平移，保持内部结构不变，仅调整外部引用
+2. **分层隔离**：通过 uv workspace 实现 Python 包依赖隔离，通过 `.env` 分层实现配置隔离
+3. **数据库重组**：从现有 4 个 schema（billiards_ods/billiards_dwd/billiards_dws/etl_admin）重组为 6 层 schema（meta/ods/dwd/core/dws/app）
+4. **渐进式扩展**：第一阶段只建必要骨架，未来扩展点记录在 Roadmap 中
+
+## 架构
+
+### 整体架构
+
+```mermaid
+graph TB
+    subgraph "NeoZQYY Monorepo"
+        subgraph "apps/"
+            ETL["apps/etl/pipelines/feiqiu/"]
+            Backend["apps/backend/ (FastAPI)"]
+            Mini["apps/miniprogram/ (Donut+TDesign)"]
+            Admin["apps/admin-web/ (未来)"]
+        end
+        
+        subgraph "packages/"
+            Shared["packages/shared/"]
+        end
+        
+        subgraph "gui/"
+            GUI["gui/ (PySide6，过渡期)"]
+        end
+        
+        subgraph "db/"
+            ETLDB["db/etl_feiqiu/"]
+            AppDB["db/zqyy_app/"]
+            FDW["db/fdw/"]
+        end
+    end
+    
+    ETL --> Shared
+    Backend --> Shared
+    GUI --> Shared
+    Backend --> AppDB
+    ETL --> ETLDB
+    AppDB -.->|postgres_fdw 只读| ETLDB
+```
+
+### 数据流架构
+
+```mermaid
+graph LR
+    API["上游 SaaS API"] --> ODS["ods (原始数据)"]
+    ODS --> DWD["dwd (main+EX 明细)"]
+    DWD --> Core["core (统一最小字段集)"]
+    DWD --> DWS["dws (汇总/工资)"]
+    Core --> DWS
+    DWS --> App["app (视图+RLS)"]
+    App -.->|FDW 只读映射| ZqyyApp["zqyy_app DB"]
+    ZqyyApp --> FastAPI["FastAPI 后端"]
+    FastAPI --> MiniApp["微信小程序"]
+    
+    subgraph "etl_feiqiu DB"
+        Meta["meta (调度/游标)"]
+        ODS
+        DWD
+        Core
+        DWS
+        App
+    end
+```
+
+## 组件与接口
+
+### 1. 目录结构生成器（Scaffold）
+
+负责创建 Monorepo 完整目录结构和基础配置文件。
+
+**输入**：目标路径 `C:\NeoZQYY\`
+**输出**：完整目录树 + README.md + 配置文件
+
+**关键行为**：
+- 创建所有一级和二级目录
+- 为每个一级目录生成 README.md（作用 + 结构 + Roadmap）
+- 生成 `.gitignore`、`.kiroignore`、`.env.template`
+- 初始化 Git 仓库
+
+### 2. uv Workspace 配置
+
+**根 `pyproject.toml`**：
+```toml
+[project]
+name = "neozqyy"
+version = "0.1.0"
+requires-python = ">=3.10"
+
+[tool.uv.workspace]
+members = [
+    "apps/etl/pipelines/feiqiu",
+    "apps/backend",
+    "packages/shared",
+    "gui",
+]
+```
+
+**子项目 `pyproject.toml` 模式**（以 ETL 为例）：
+```toml
+[project]
+name = "etl-feiqiu"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+    "psycopg2-binary>=2.9.0",
+    "requests>=2.28.0",
+    "python-dateutil>=2.8.0",
+    "tzdata>=2023.0",
+    "python-dotenv",
+    "openpyxl>=3.1.0",
+    "neozqyy-shared",
+]
+
+[tool.uv.sources]
+neozqyy-shared = { workspace = true }
+```
+
+### 3. 配置隔离机制
+
+**分层加载顺序**：
+```
+根 .env（公共配置）→ 应用 .env.local（私有覆盖）→ 环境变量 → CLI 参数
+```
+
+**实现方式**：
+- 现有 `AppConfig` 的 `DEFAULTS < ENV < CLI` 模式保持不变
+- 新增：在 `load_env_overrides()` 中先加载根 `.env`，再加载应用级 `.env.local`
+- 冲突策略：应用级优先（后加载覆盖先加载）
+- 缺失检测：在 `_validate()` 中检查必需项，报告缺失项名称
+
+### 4. ETL 平移策略
+
+**平移范围**：
+| 源路径 | 目标路径 | 说明 |
+|--------|----------|------|
+| `api/` | `apps/etl/pipelines/feiqiu/api/` | API 客户端 |
+| `cli/` | `apps/etl/pipelines/feiqiu/cli/` | CLI 入口 |
+| `config/` | `apps/etl/pipelines/feiqiu/config/` | 配置 |
+| `loaders/` | `apps/etl/pipelines/feiqiu/loaders/` | 加载器 |
+| `models/` | `apps/etl/pipelines/feiqiu/models/` | 模型 |
+| `orchestration/` | `apps/etl/pipelines/feiqiu/orchestration/` | 调度 |
+| `scd/` | `apps/etl/pipelines/feiqiu/scd/` | SCD2 |
+| `tasks/` | `apps/etl/pipelines/feiqiu/tasks/` | 任务 |
+| `utils/` | `apps/etl/pipelines/feiqiu/utils/` | 工具 |
+| `quality/` | `apps/etl/pipelines/feiqiu/quality/` | 质量检查 |
+| `tests/` | `apps/etl/pipelines/feiqiu/tests/` | 测试 |
+| `database/*.sql` | `db/etl_feiqiu/schemas/` | DDL |
+| `database/migrations/` | `db/etl_feiqiu/migrations/` | 迁移脚本 |
+| `database/seed_*.sql` | `db/etl_feiqiu/seeds/` | 种子数据 |
+| `gui/` | `gui/` | GUI（顶层） |
+
+**import 路径策略**：
+- ETL 内部使用相对 import（`from .config.settings import AppConfig`）或保持现有绝对 import
+- `pyproject.toml` 中设置 `pythonpath`，使 `apps/etl/pipelines/feiqiu/` 为 Python 路径根
+- `pytest.ini` 同步更新 `pythonpath = .`
+- 目标：ETL 内部代码零修改或最小修改
+
+### 5. 小程序平移策略
+
+**平移范围**：
+| 源路径 | 目标路径 |
+|--------|----------|
+| `C:\ZQYY\XCX\`（除 Prototype） | `apps/miniprogram/` |
+| `C:\ZQYY\XCX\Prototype\` | `docs/h5_ui/` |
+
+小程序为独立前端项目（Donut + TDesign），不涉及 Python 依赖管理，直接复制即可。
+
+
+### 6. 数据库 Schema 重组（etl_feiqiu）
+
+**现有 → 新 schema 映射**：
+
+| 现有 Schema | 新 Schema | 说明 |
+|-------------|-----------|------|
+| `etl_admin` | `meta` | 调度、游标、运行记录 |
+| `billiards_ods` | `ods` | ODS 原始数据，结构不变 |
+| `billiards_dwd` | `dwd` | DWD 明细，保留 main+EX 拆分 |
+| （新增） | `core` | 统一维度/事实最小字段集 |
+| `billiards_dws` | `dws` | DWS 汇总，结构不变 |
+| （新增） | `app` | 面向外部的视图/函数 + RLS |
+
+**core schema 设计原则**：
+- 仅包含跨系统共享的最小字段集（如会员 ID、姓名、手机号、状态）
+- 维度表从 DWD 维度表提取核心字段
+- 事实表从 DWD 事实表提取核心度量
+- 第一版保持精简，后续按需扩展
+
+**app schema 设计原则**：
+- 以视图（VIEW）封装 DWS/Core 层数据
+- 所有视图启用 RLS，以 `site_id` 过滤
+- 提供函数接口供 FDW 映射使用
+- 不存储实际数据，仅做访问层
+
+**RLS 实现方案**：
+```sql
+-- 创建应用角色
+CREATE ROLE app_reader;
+
+-- 在 app schema 的视图上启用 RLS
+ALTER TABLE app.v_member_summary ENABLE ROW LEVEL SECURITY;
+
+-- 创建策略：根据会话变量 app.current_site_id 过滤
+CREATE POLICY site_isolation ON app.v_member_summary
+    FOR SELECT TO app_reader
+    USING (site_id = current_setting('app.current_site_id')::bigint);
+```
+
+### 7. 业务数据库设计（zqyy_app）
+
+**核心表**：
+- `users`：用户账户（微信 OpenID、手机号、角色）
+- `roles` / `permissions`：RBAC 权限模型
+- `user_roles`：用户-角色关联
+- `tasks`：任务管理（审批流）
+- `approvals`：审批记录
+
+**FDW 映射**：
+```sql
+-- 在 zqyy_app 中创建外部服务器
+CREATE SERVER etl_feiqiu_server
+    FOREIGN DATA WRAPPER postgres_fdw
+    OPTIONS (host 'localhost', dbname 'etl_feiqiu', port '5432');
+
+-- 创建用户映射
+CREATE USER MAPPING FOR app_user
+    SERVER etl_feiqiu_server
+    OPTIONS (user 'app_reader', password '***');
+
+-- 导入 app schema 的外部表
+IMPORT FOREIGN SCHEMA app
+    FROM SERVER etl_feiqiu_server
+    INTO fdw_etl;
+```
+
+**约束**：FDW 映射为只读，`zqyy_app` 不存储 ETL 数据副本。
+
+### 8. FastAPI 后端骨架
+
+**项目结构**：
+```
+apps/backend/
+├── app/
+│   ├── __init__.py
+│   ├── main.py              # FastAPI 入口
+│   ├── config.py             # 配置加载
+│   ├── database.py           # 数据库连接
+│   ├── routers/              # 路由模块
+│   │   └── __init__.py
+│   ├── middleware/            # 中间件
+│   │   └── __init__.py
+│   └── schemas/              # Pydantic 模型
+│       └── __init__.py
+├── tests/
+│   └── __init__.py
+├── pyproject.toml
+└── README.md
+```
+
+**关键配置**：
+- 连接 `zqyy_app` 数据库（通过 FDW 访问 ETL 数据）
+- OpenAPI 文档自动生成（FastAPI 内置）
+- 依赖 `packages/shared` 获取通用工具
+
+### 9. 共享包（packages/shared）
+
+**模块划分**：
+```
+packages/shared/
+├── src/
+│   └── neozqyy_shared/
+│       ├── __init__.py
+│       ├── enums.py           # 字段枚举定义
+│       ├── money.py           # 金额精度工具（CNY, numeric(2)）
+│       └── datetime_utils.py  # 时间处理工具
+├── tests/
+│   └── __init__.py
+├── pyproject.toml
+└── README.md
+```
+
+**提取来源**：
+- `enums.py`：从 ETL 的 `models/` 中提取通用枚举
+- `money.py`：金额四舍五入、格式化（`Decimal` + `ROUND_HALF_UP`，scale=2）
+- `datetime_utils.py`：时区转换、日期范围计算（从 `utils/` 提取）
+
+### 10. .kiro 迁移
+
+**迁移内容**：
+- 复制 `.kiro/steering/` 到 Monorepo
+- 更新 `product.md`：从单一 ETL 视角扩展为 Monorepo 全局视角
+- 更新 `tech.md`：新增 FastAPI、uv workspace、Donut+TDesign 等技术栈
+- 更新 `structure-lite.md`：反映 Monorepo 目录结构和模块边界
+- 更新路径引用：所有 steering 文件中的路径适配新结构
+
+## 数据模型
+
+### etl_feiqiu 数据库（六层 Schema）
+
+```mermaid
+erDiagram
+    META {
+        bigint run_id PK
+        text task_code
+        timestamptz started_at
+        timestamptz ended_at
+        text status
+        jsonb result_summary
+    }
+    
+    META ||--o{ ODS : "调度触发"
+    
+    ODS {
+        bigint id PK
+        text content_hash PK
+        jsonb payload
+        text source_endpoint
+        timestamptz fetched_at
+    }
+    
+    ODS ||--o{ DWD : "清洗装载"
+    
+    DWD {
+        bigint id PK
+        timestamptz scd2_start_time
+        timestamptz scd2_end_time
+        int scd2_is_current
+        int scd2_version
+    }
+    
+    DWD ||--o{ CORE : "提取最小字段集"
+    
+    CORE {
+        bigint id PK
+        text name
+        bigint site_id
+    }
+    
+    DWD ||--o{ DWS : "汇总聚合"
+    CORE ||--o{ DWS : "汇总聚合"
+    
+    DWS {
+        bigint id PK
+        date stat_date
+        numeric amount
+        bigint site_id
+    }
+    
+    DWS ||--o{ APP : "视图封装"
+    
+    APP {
+        text view_name
+        text rls_policy
+    }
+```
+
+### zqyy_app 数据库
+
+```mermaid
+erDiagram
+    USERS {
+        bigint id PK
+        text wx_openid UK
+        text mobile
+        text nickname
+        int status
+        timestamptz created_at
+    }
+    
+    ROLES {
+        int id PK
+        text name UK
+        text description
+    }
+    
+    USER_ROLES {
+        bigint user_id FK
+        int role_id FK
+    }
+    
+    PERMISSIONS {
+        int id PK
+        text resource
+        text action
+    }
+    
+    ROLE_PERMISSIONS {
+        int role_id FK
+        int permission_id FK
+    }
+    
+    USERS ||--o{ USER_ROLES : "拥有"
+    ROLES ||--o{ USER_ROLES : "分配给"
+    ROLES ||--o{ ROLE_PERMISSIONS : "包含"
+    PERMISSIONS ||--o{ ROLE_PERMISSIONS : "授予"
+    
+    FDW_ETL_VIEWS {
+        text foreign_table_name
+        text source_schema
+        text mapping_type
+    }
+```
+
+### 配置分层模型
+
+```
+优先级（低 → 高）：
+┌─────────────────────────────┐
+│  根 .env（公共配置模板）       │  DB_HOST, DB_PORT, TIMEZONE
+├─────────────────────────────┤
+│  应用 .env.local（私有覆盖）   │  DB_NAME, DB_PASSWORD, API_TOKEN
+├─────────────────────────────┤
+│  环境变量                     │  运行时覆盖
+├─────────────────────────────┤
+│  CLI 参数                    │  最高优先级
+└─────────────────────────────┘
+```
+
+
+## 正确性属性
+
+*属性是系统在所有有效执行中都应保持为真的特征或行为——本质上是关于系统应该做什么的形式化陈述。属性是人类可读规格与机器可验证正确性保证之间的桥梁。*
+
+### Property 1: README.md 结构完整性
+
+*对于任意* Monorepo 一级目录，其 README.md 文件应存在且包含"作用说明"、"结构描述"和"Roadmap"三个段落。
+
+**Validates: Requirements 1.5**
+
+### Property 2: Python 子项目配置完整性
+
+*对于任意* uv workspace 声明的 Python 子项目成员，该子项目目录下应存在独立的 `pyproject.toml` 文件，且文件中包含 `[project]` 段落。
+
+**Validates: Requirements 3.2**
+
+### Property 3: 配置优先级 - .env.local 覆盖
+
+*对于任意*配置项名称和两个不同的值，当根 `.env` 和应用 `.env.local` 都定义了该配置项时，配置加载器返回的值应等于 `.env.local` 中的值。
+
+**Validates: Requirements 4.3**
+
+### Property 4: 必需配置缺失检测
+
+*对于任意*必需配置项，当所有配置层级（.env、.env.local、环境变量、CLI）均未提供该项时，配置加载器应抛出错误，且错误信息中包含该缺失配置项的名称。
+
+**Validates: Requirements 4.4**
+
+### Property 5: 文件迁移完整性
+
+*对于任意*源-目标目录映射关系（ETL 业务代码、database 文件、tests 目录），源目录中的每个文件在目标目录的对应位置都应存在且内容一致。
+
+**Validates: Requirements 5.1, 5.2, 5.3**
+
+### Property 6: Schema 表定义迁移完整性
+
+*对于任意*现有数据库 schema（billiards_ods、billiards_dws）中的表，新 schema（ods、dws）的 DDL 文件中应包含该表的 CREATE TABLE 定义。
+
+**Validates: Requirements 7.3, 7.6**
+
+### Property 7: Core schema 最小字段集
+
+*对于任意* core schema 中的表，其字段数量应严格少于对应 dwd schema 中同名（或对应）表的字段数量。
+
+**Validates: Requirements 7.5**
+
+### Property 8: 测试数据库结构一致性
+
+*对于任意*生产数据库（etl_feiqiu、zqyy_app）中的 schema 和表定义，对应的测试数据库（test_etl_feiqiu、test_zqyy_app）中应存在相同的 schema 和表结构。
+
+**Validates: Requirements 9.1, 9.2**
+
+### Property 9: Steering 文件路径更新
+
+*对于任意* `.kiro/steering/` 目录下的文件，文件内容中不应包含旧仓库路径引用（如 `FQ-ETL`、`C:\ZQYY\FQ-ETL`）。
+
+**Validates: Requirements 10.2**
+
+### Property 10: 业务表 site_id 字段存在性
+
+*对于任意* app schema 中的业务视图和 dws/core schema 中的业务表，其定义中应包含 `site_id` 字段。
+
+**Validates: Requirements 13.1**
+
+### Property 11: RLS 按 site_id 隔离
+
+*对于任意* app schema 中启用了 RLS 的视图，当会话变量 `app.current_site_id` 设置为某个门店 ID 时，查询结果应仅包含该 `site_id` 的数据行。
+
+**Validates: Requirements 13.2**
+
+## 错误处理
+
+### 配置错误
+- **缺失必需配置**：启动时立即报错，列出所有缺失项名称，不启动服务
+- **配置值格式错误**：报告具体的配置项路径和期望格式
+- **.env 文件不存在**：使用默认值继续，不报错（.env.template 仅为模板）
+
+### 迁移错误
+- **源文件不存在**：记录警告日志，继续迁移其他文件，最终汇总报告缺失文件列表
+- **目标目录已存在**：提示用户确认是否覆盖，默认不覆盖
+- **import 路径修复失败**：记录错误日志，标记需要手动修复的文件
+
+### 数据库错误
+- **Schema 创建失败**：回滚当前 schema 的所有 DDL，报告失败原因
+- **FDW 连接失败**：记录错误日志，不影响本地表的正常使用
+- **RLS 策略创建失败**：回滚策略创建，报告受影响的表
+
+### 测试数据库错误
+- **结构不一致**：提供 diff 工具比较生产与测试库结构差异
+- **数据迁移失败**：回滚到迁移前状态，报告失败的表和原因
+
+## 测试策略
+
+### 测试框架
+- **单元测试**：`pytest`（Python 子项目）
+- **属性测试**：`hypothesis`（Python 属性测试库）
+- 每个属性测试配置最少 100 次迭代
+
+### 单元测试覆盖
+
+1. **Scaffold 测试**：验证目录创建、文件生成的具体示例
+2. **配置加载器测试**：验证分层加载、冲突处理、缺失检测的边界情况
+3. **迁移脚本测试**：验证文件复制、路径映射的具体场景
+4. **DDL 语法测试**：验证生成的 SQL 语法正确性
+
+### 属性测试覆盖
+
+每个属性测试必须引用设计文档中的属性编号：
+
+- **Feature: monorepo-migration, Property 1: README.md 结构完整性** — 验证所有一级目录 README 包含必需段落
+- **Feature: monorepo-migration, Property 2: Python 子项目配置完整性** — 验证所有 workspace 成员有 pyproject.toml
+- **Feature: monorepo-migration, Property 3: 配置优先级** — 生成随机配置项，验证 .env.local 覆盖行为
+- **Feature: monorepo-migration, Property 4: 必需配置缺失检测** — 生成随机必需项组合，验证缺失报错
+- **Feature: monorepo-migration, Property 5: 文件迁移完整性** — 验证源-目标文件映射的完整性
+- **Feature: monorepo-migration, Property 6: Schema 表定义迁移完整性** — 验证现有表在新 DDL 中存在
+- **Feature: monorepo-migration, Property 7: Core schema 最小字段集** — 验证 core 表字段数少于 dwd
+- **Feature: monorepo-migration, Property 8: 测试数据库结构一致性** — 验证测试库与生产库结构相同
+- **Feature: monorepo-migration, Property 9: Steering 文件路径更新** — 验证无旧路径残留
+- **Feature: monorepo-migration, Property 10: 业务表 site_id 存在性** — 验证业务表包含 site_id
+- **Feature: monorepo-migration, Property 11: RLS 隔离** — 验证 RLS 按 site_id 过滤（集成测试）
+
+### 集成测试
+
+- **ETL 运行验证**：在新目录结构下运行 `pytest tests/unit`，确保所有现有测试通过
+- **数据库 Schema 验证**：在测试数据库上执行 DDL，验证 schema 创建成功
+- **FDW 连接验证**：验证 zqyy_app 通过 FDW 可读取 etl_feiqiu 的 app schema 数据
+- **uv workspace 验证**：运行 `uv sync`，验证所有子项目依赖正确解析