feat: P1-P3 全栈集成 — 数据库基础 + DWS 扩展 + 小程序鉴权 + 工程化体系

## 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 排除规则
2026-02-26 08:03:53 +08:00
parent fafc95e64c
commit b25308c3f4
224 changed files with 17660 additions and 32198 deletions
--- a/docs/roadmap/2026-02-24__fdw-dwd-to-core-migration-plan.md
+++ b/docs/roadmap/2026-02-24__fdw-dwd-to-core-migration-plan.md
@@ -0,0 +1,85 @@
+# FDW 数据源迁移方案：DWD → Core
+
+> 创建日期：2026-02-24
+> 状态：已决策（上线后迭代）
+> 关联 SPEC：miniapp-db-foundation
+
+---
+
+## 背景
+
+当前 `miniapp-db-foundation` SPEC 中，FDW 外部表映射的数据源链路为：
+
+```
+ETL 库 dwd.dim_* / dws.dws_*
+    → app.v_dim_* / app.v_dws_*（RLS 视图，site_id 过滤）
+    → 业务库 fdw_etl.v_dim_* / fdw_etl.v_dws_*（FDW 外部表）
+```
+
+ETL 六层 Schema 中，`core` 层的定位是"跨门店标准化维度/事实"，是 DWD 层的精简子集。长远来看，小程序读取的维度数据应从 `core` 层获取，而非直接读 `dwd` 层。
+
+## 决策
+
+上线时保持现状（`app` 视图指向 `dwd.*` / `dws.*`），上线后再迭代切换到 `core`。
+
+## 理由
+
+1. Core 层当前仅 7 张表（`dim_site`、`dim_member`、`dim_assistant`、`dim_table`、`dim_goods_category`、`fact_settlement`、`fact_payment`），小程序需要的 11 张 DWD + 24 张 DWS 远超 Core 覆盖范围
+2. Core 层字段是精简子集（如 `core.dim_member` 无 `card_balance`、`total_consumption` 等），小程序前期需要 DWD 的完整字段
+3. `app` 视图层本身就是抽象层——后端通过 `fdw_etl.v_dim_member` 访问数据，底层视图定义可随时切换，后端代码零改动
+4. 上线关键路径是 P0 阶段（基础设施 → 微信配置 → 后端核心功能），Core 层完善属于 P2 范畴
+
+## 迁移路径
+
+### Phase 0：上线前（当前）
+
+按 SPEC 原样执行：
+- `app.v_dim_member` → `SELECT * FROM dwd.dim_member WHERE site_id = ...`
+- `app.v_dws_*` → `SELECT * FROM dws.dws_* WHERE site_id = ...`
+- FDW 通过 `IMPORT FOREIGN SCHEMA app` 映射
+
+### Phase 1：上线后 — 补齐 Core 层表
+
+- 盘点小程序实际用到的维度表，确认 Core 层需要补齐哪些字段
+- 对照 DWD 层的 `dim_member`、`dim_assistant` 等，在 Core 层补全小程序所需的业务字段
+- 新增 Core 层缺失的维度表（如 `core.dim_member_card_account`、`core.dim_staff` 等）
+
+### Phase 2：上线后 — ETL 填充任务
+
+- 在 ETL Connector 中新增 DWD → Core 的填充任务
+- 确保 Core 层数据与 DWD 层保持同步
+- 验证 Core 层数据完整性和正确性
+
+### Phase 3：上线后 — 切换视图定义
+
+- 修改 `app` 视图定义，将维度表从 `dwd.*` 切换到 `core.*`：
+  ```sql
+  -- 修改前
+  CREATE OR REPLACE VIEW app.v_dim_member AS
+  SELECT * FROM dwd.dim_member
+  WHERE site_id = current_setting('app.current_site_id')::bigint;
+
+  -- 修改后
+  CREATE OR REPLACE VIEW app.v_dim_member AS
+  SELECT * FROM core.dim_member
+  WHERE site_id = current_setting('app.current_site_id')::bigint;
+  ```
+- DWS 汇总表保持不变（它们本身就在 DWS 层，Core 层不涉及汇总）
+- 重新执行 `IMPORT FOREIGN SCHEMA app INTO fdw_etl` 同步外部表
+- 后端和小程序代码无需任何改动
+
+## 风险与缓解
+
+| 风险 | 缓解措施 |
+|------|---------|
+| Core 层字段不全导致小程序功能缺失 | Phase 1 先盘点再补齐，确保字段覆盖 |
+| DWD → Core 填充任务引入数据延迟 | Core 填充任务纳入 ETL 调度链，与 DWD 同步执行 |
+| 切换视图时短暂不可用 | 使用 `CREATE OR REPLACE VIEW` 原子替换，无停机 |
+| Core 层数据与 DWD 不一致 | 切换前运行数据一致性校验脚本 |
+
+## 关键设计优势
+
+`app` 视图层是整个方案的"切换开关"：
+- 后端只看到 `fdw_etl.v_dim_member`，不关心底层是 DWD 还是 Core
+- 切换只需修改视图 SQL + 重新 IMPORT，零代码改动
+- 可以逐表切换（先切 `dim_member`，验证通过后再切其他表），降低风险
--- a/docs/roadmap/BACKLOG.md
+++ b/docs/roadmap/BACKLOG.md
@@ -0,0 +1,186 @@
+# 项目待办总览（Backlog）
+
+> 最后更新：2026-02-24
+> 本文档汇总项目中所有已识别的待办事项，按子系统和优先级分类。
+> 来源：LAUNCH-CHECKLIST、SPEC 文档、字段审计报告、PRD、代码注释等。
+
+---
+
+## 阅读指南
+
+- P0 = 不做就上不了线
+- P1 = 上线前必须做
+- P2 = 可上线后迭代
+- ✅ = 已完成
+- 🔲 = 待办
+- 📋 = 有 SPEC 但未执行
+
+---
+
+## 一、小程序上线关键路径（P0）
+
+来源：`docs/deployment/LAUNCH-CHECKLIST.md`
+
+### 1.1 基础设施
+
+| 状态 | 项目 | 说明 |
+|------|------|------|
+| ✅ | 服务器目录结构 + 仓库克隆 | 20260220 完成 |
+| 🔲 | 配置环境变量文件 | 服务器 `.env` 手动创建 |
+| 🔲 | 安装 Python 依赖 | `uv sync --all-packages` |
+| 🔲 | 运行 `setup-server-git.py` | Git 排除规则 |
+| 🔲 | 运行 `init-server-env.py` | 删除排除文件 + 创建 export 目录 |
+| 🔲 | bat 脚本部署到服务器 | `D:\NeoZQYY\scripts\` |
+| 🔲 | 确认 Nginx 反代规则 | 测试 8001 / 正式 8000 |
+| 🔲 | SSL 证书自动续期 | |
+| 🔲 | 数据库备份方案 | pg_dump + Windows 计划任务 |
+
+### 1.2 微信侧配置
+
+| 状态 | 项目 | 说明 |
+|------|------|------|
+| ✅ | 合法域名 + HTTPS | 已配置 |
+| 🔲 | 消息推送配置提交验证 | 需服务器后端在线 |
+| 🔲 | 用户隐私保护指引 | 微信后台填写 |
+| 🔲 | 小程序名称/图标/简介/类目 | 审核必需 |
+| 🔲 | 体验成员配置 | 内部测试必需 |
+
+### 1.3 后端核心功能
+
+| 状态 | 项目 | 说明 |
+|------|------|------|
+| 🔲 | 微信登录接口 | `POST /api/auth/wechat_login` |
+| 🔲 | 权限中间件 | JWT site_id + role 校验 |
+| 🔲 | 至少一个有实际功能的首页 | 审核要求 |
+| 🔲 | 密钥配置 | `WX_APP_ID`、`WX_APP_SECRET`、`JWT_SECRET_KEY` |
+
+### 1.4 数据库基础设施
+
+| 状态 | 项目 | 说明 |
+|------|------|------|
+| 📋 | miniapp-db-foundation SPEC | 6 个任务全部待执行 |
+| 🔲 | auth/biz Schema 创建 | SPEC 任务 2 |
+| 🔲 | ETL RLS 视图层（35 张） | SPEC 任务 1 |
+| 🔲 | FDW 跨库映射 | SPEC 任务 3 |
+| 🔲 | 端到端验证脚本 | SPEC 任务 5 |
+
+---
+
+## 二、安全与审计（P1 — 上线前必须做）
+
+来源：`docs/deployment/LAUNCH-CHECKLIST.md` 第五阶段
+
+| 状态 | 项目 | 说明 |
+|------|------|------|
+| 🔲 | 用户申请/审核流 | `user_application` 表 + 审核 API |
+| 🔲 | 审计日志 | `audit_log` 表 + 审计中间件 |
+| 🔲 | 后端结构化日志 | 替代 uvicorn 默认日志 |
+| 🔲 | 服务器防火墙确认 | Tailscale 网卡入站限制 |
+| 🔲 | PostgreSQL 监听确认 | 仅内网/本机 |
+| 🔲 | 消息推送切安全模式 | AES 加解密 |
+
+---
+
+## 三、审核准备（P1 — 提交审核前）
+
+来源：`docs/deployment/LAUNCH-CHECKLIST.md` 第六阶段
+
+| 状态 | 项目 | 说明 |
+|------|------|------|
+| 🔲 | 主要页面功能截图 | |
+| 🔲 | 测试账号 | |
+| 🔲 | 类目资质文件 | 营业执照等 |
+| 🔲 | 功能介绍文案 | |
+
+---
+
+## 四、ETL 待办
+
+### 4.1 字段补全（来源：`field_review_for_user.md`）
+
+| 状态 | 项目 | 优先级 | 说明 |
+|------|------|--------|------|
+| 🔲 | 映射错误修复（4 处） | 高 | site_assistant_id、discount_price 列名、batch_stock_qty、provisional_total_cost |
+| 🔲 | 待新增/补映射字段（40 个） | 中 | 分布在 12 张 ODS 表，含 A/B/C 三类 |
+| 🔲 | 新建 DWD 表（2 张） | 中 | `dwd_goods_stock_movement`（优先）、`settlement_ticket`（待定） |
+| 🔲 | ODS 配置修改（1 处） | 中 | `goods_stock_summary` 改 `requires_window=True` |
+| 🔲 | ODS 平层化映射修复 | 低 | `table_area_id_list` 字段名映射错位 |
+
+### 4.2 DWS 层待建表
+
+| 状态 | 项目 | 来源 |
+|------|------|------|
+| 🔲 | `dws_member_spending_power_index` RLS 视图 | miniapp-db-foundation P2 预留 |
+| 🔲 | `dws_assistant_order_contribution` | miniapp-db-foundation P2 预留 |
+| 🔲 | `dws_goods_stock_summary`（日/周/月粒度） | dataflow-field-completion SPEC |
+
+### 4.3 Core 层迁移
+
+| 状态 | 项目 | 来源 |
+|------|------|------|
+| 🔲 | 补齐 Core 层维度表字段 | `docs/roadmap/2026-02-24__fdw-dwd-to-core-migration-plan.md` |
+| 🔲 | DWD → Core 填充任务 | 同上 |
+| 🔲 | app 视图从 DWD 切换到 Core | 同上 |
+
+### 4.4 架构优化
+
+| 状态 | 项目 | 来源 |
+|------|------|------|
+| 📋 | 冷数据归档（方案 5） | `ods_taskspec_refactor_proposal.md` 中长期待办 |
+| 🔲 | ETL SDK 抽象 | LAUNCH-CHECKLIST 7.4，飞球 Connector → 通用基类 |
+
+---
+
+## 五、后端待办（P2 — 上线后迭代）
+
+来源：`docs/deployment/LAUNCH-CHECKLIST.md` 第七阶段
+
+| 状态 | 项目 | 说明 |
+|------|------|------|
+| 🔲 | xlsx 导入/导出 | 上传、解析、校验、落库、错误报告 |
+| 🔲 | 运维监控系统 | BS 架构，集成管理后台，取代 bat 脚本 |
+| 🔲 | 租户模型 | tenant 层 + RLS Policy DDL |
+| 🔲 | 后端 API 集成测试 | |
+| 🔲 | 小程序端自动化测试 | |
+| 🔲 | 依赖版本 pin 上限 | 当前 `>=0.115` 等范围较宽松 |
+
+---
+
+## 六、SPEC 状态总览
+
+| SPEC | 状态 | 说明 |
+|------|------|------|
+| `admin-web-console` | ✅ 已完成 | Web 管理后台 |
+| `assistant-abolish-cleanup` | ✅ 已完成 | 助教废除链路清理 |
+| `dataflow-field-completion` | ✅ 已完成 | 字段补全与联调 |
+| `dataflow-structure-audit` | ✅ 已完成 | 数据流结构分析重构 |
+| `dwd-phase1-refactor` | ✅ 已完成 | DWD 第一阶段重构 |
+| `etl-aggregation-fix` | ✅ 已完成 | ETL 聚合修复 |
+| `etl-dws-flow-refactor` | ✅ 已完成 | DWS 流程重构 |
+| `etl-fullstack-integration` | ✅ 已完成 | 全栈集成测试 |
+| `etl-pipeline-debug` | ✅ 已完成 | ETL 全链路调试 |
+| `etl-staff-dimension` | ✅ 已完成 | 员工维度表 |
+| `ods-dedup-standardize` | ✅ 已完成 | ODS 去重标准化 |
+| `spi-spending-power-index` | ✅ 已完成 | 消费力指数 |
+| `miniapp-db-foundation` | 📋 待执行 | 小程序数据库基础设施（6 个任务） |
+
+---
+
+## 七、文档待办
+
+| 状态 | 项目 | 位置 |
+|------|------|------|
+| 🔲 | ADR（架构决策记录）模板 | `docs/architecture/` |
+| 🔲 | 数据字典完善 | `docs/contracts/data_dictionary/` |
+| 🔲 | 权限矩阵 | `docs/permission_matrix/` |
+| 🔲 | 运维手册 | `docs/ops/` |
+| ✅ | FDW DWD→Core 迁移方案 | `docs/roadmap/2026-02-24__fdw-dwd-to-core-migration-plan.md` |
+
+---
+
+## 维护说明
+
+本文档为项目待办的单一汇总入口。新增待办时：
+1. 先在对应的来源文档中记录（LAUNCH-CHECKLIST、SPEC、字段审计报告等）
+2. 同步更新本文档对应分类
+3. 完成后标记 ✅ 并注明日期