Neo
b25308c3f4
## P1 数据库基础 - zqyy_app: 创建 auth/biz schema、FDW 连接 etl_feiqiu - etl_feiqiu: 创建 app schema RLS 视图、商品库存预警表 - 清理 assistant_abolish 残留数据 ## P2 ETL/DWS 扩展 - 新增 DWS 助教订单贡献度表 (dws.assistant_order_contribution) - 新增 assistant_order_contribution_task 任务及 RLS 视图 - member_consumption 增加充值字段、assistant_daily 增加处罚字段 - 更新 ODS/DWD/DWS 任务文档及业务规则文档 - 更新 consistency_checker、flow_runner、task_registry 等核心模块 ## P3 小程序鉴权系统 - 新增 xcx_auth 路由/schema（微信登录 + JWT） - 新增 wechat/role/matching/application 服务层 - zqyy_app 鉴权表迁移 + 角色权限种子数据 - auth/dependencies.py 支持小程序 JWT 鉴权 ## 文档与审计 - 新增 DOCUMENTATION-MAP 文档导航 - 新增 7 份 BD_Manual 数据库变更文档 - 更新 DDL 基线快照（etl_feiqiu 6 schema + zqyy_app auth） - 新增全栈集成审计记录、部署检查清单更新 - 新增 BACKLOG 路线图、FDW→Core 迁移计划 ## Kiro 工程化 - 新增 5 个 Spec（P1/P2/P3/全栈集成/核心业务） - 新增审计自动化脚本（agent_on_stop/build_audit_context/compliance_prescan） - 新增 6 个 Hook（合规检查/会话日志/提交审计等） - 新增 doc-map steering 文件 ## 运维与测试 - 新增 ops 脚本：迁移验证/API 健康检查/ETL 监控/集成报告 - 新增属性测试：test_dws_contribution / test_auth_system - 清理过期 export 报告文件 - 更新 .gitignore 排除规则
3.7 KiB
3.7 KiB
环境搭建指南
1. 前置条件
| 组件 | 版本要求 | 说明 |
|---|---|---|
| Python | 3.10+ | 推荐 3.12 或 3.13 |
| PostgreSQL | 远程实例 | 需要可访问的 PostgreSQL 服务 |
| uv | 最新版 | Python 包管理器（替代 pip） |
2. 安装步骤
2.1 克隆仓库并创建虚拟环境
git clone <repo-url> etl-billiards
cd etl-billiards
# 创建并激活虚拟环境
python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate
2.2 安装依赖
uv sync
核心依赖说明：
| 包名 | 用途 |
|---|---|
psycopg2-binary |
PostgreSQL 驱动 |
requests |
上游 API HTTP 客户端 |
python-dateutil / tzdata |
日期解析与时区处理 |
python-dotenv |
.env 文件加载 |
openpyxl |
Excel 导入导出（DWS 数据） |
如需运行测试，还需安装：
uv sync --group test
2.3 配置环境变量
在项目根目录创建 .env 文件（禁止提交到版本控制）：
# 数据库连接（推荐使用 DSN 模式）
PG_DSN=postgresql://用户名:密码@主机:端口/数据库名
# 或分离式配置（不使用 DSN 时启用）
PG_HOST=localhost
PG_PORT=5432
PG_NAME=your_database
PG_USER=your_user
PG_PASSWORD=your_password
# 业务库 DSN（后端 / 跨模块脚本使用）
APP_DB_DSN=postgresql://用户名:密码@主机:端口/数据库名
# 门店与 API
STORE_ID=1
API_TOKEN=your_bearer_token
# 可选
APP_TIMEZONE=Asia/Shanghai
安全提示：
.env文件包含敏感信息，已在.gitignore中排除。
3. 配置体系
系统采用三层配置叠加，优先级从低到高：
config/defaults.py → .env / 环境变量 → CLI 参数
- 默认值定义在
config/defaults.py - 环境变量通过
python-dotenv加载，由config/env_parser.py解析 - CLI 参数拥有最高优先级，可覆盖前两层
- 通过
AppConfig.get("dotted.path")访问配置值，例如config.get("db.dsn")
4. 数据库初始化
系统使用六层 Schema 架构：
| Schema | 用途 |
|---|---|
meta |
调度与运行记录（游标、任务注册） |
ods |
ODS 原始数据层 |
dwd |
DWD 明细数据层 |
core |
跨门店标准化层 |
dws |
DWS 汇总数据层 |
app |
RLS 视图层 |
初始化步骤：
# 推荐使用 CLI 工具任务初始化（DDL 基线见 docs/database/ddl/）
python -m cli.main --tasks INIT_ODS_SCHEMA,INIT_DWD_SCHEMA,INIT_DWS_SCHEMA,SEED_DWS_CONFIG --pg-dsn "$PG_DSN"
# 或手动执行 DDL（从 docs/database/ddl/ 获取最新基线）
psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__meta.sql
psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__ods.sql
psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__dwd.sql
psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__dws.sql
# 执行种子数据
psql "$PG_DSN" -f db/etl_feiqiu/seeds/seed_*.sql
注：旧的
db/etl_feiqiu/schemas/和db/etl_feiqiu/migrations/已归档至db/_archived/。 DDL 基线现由docs/database/ddl/统一管理，可通过python scripts/ops/gen_consolidated_ddl.py重新生成。
5. 验证安装
# 试运行（不写库），确认连接和配置正常
python -m cli.main --dry-run --tasks ODS_MEMBER --store-id 1
# 运行单元测试
pytest tests/unit
# 运行集成测试（需要数据库）
TEST_DB_DSN="postgresql://..." pytest tests/integration
6. 运行入口
| 入口 | 命令 | 说明 |
|---|---|---|
| CLI | python -m cli.main |
主入口，支持全部参数 |
| 后端 API | cd apps/backend && uvicorn app.main:app --reload |
FastAPI 后端服务 |
| 管理后台 | cd apps/admin-web && pnpm dev |
React + Vite 开发服务器 |