554 lines
18 KiB
Markdown
554 lines
18 KiB
Markdown
# 设计文档：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`，验证所有子项目依赖正确解析
|