微信小程序页面迁移校验之前 P5任务处理之前

.kiro/steering/agent-behavior.md

@@ -0,0 +1,17 @@
+---
+inclusion: always
+---
+# AI 执行行为约束
+
+## 上下文保护
+目标：避免大量文件内容或命令输出涌入主对话，导致上下文爆炸。
+
+### 委托子代理的场景
+- 批量文件读取（≥3 个文件）或大范围代码搜索
+- 需要探索不熟悉的模块/目录结构
+- CLI 命令输出量大或需要多步骤 shell 操作
+
+### 主流程直接处理的场景
+- 读取单个已知文件（路径明确、内容可预期）
+- 简单的单条命令（如 `uv sync`、单个 pytest 文件）
+- 小范围精确搜索（已知关键词和文件范围）

.kiro/steering/deprecated-objects.md

@@ -0,0 +1,25 @@
+---
+inclusion: always
+---
+
+# 归档目录与废弃对象规则（强制）
+
+## `_archived/` 目录规则
+
+仓库中所有 `_archived/` 目录（`db/_archived/`、`docs/database/_archived/`、`apps/**/docs/database/_archived/` 等）存放的是已废弃、已归档的历史内容。
+
+1. 除非用户明确要求查阅历史/归档内容，否则禁止读取或参考 `_archived/` 下的任何文件
+2. 从 `_archived/` 中读到的表结构、映射、任务定义、DDL 等，不得视为当前有效对象
+3. 补充映射、表清单、任务列表、DDL 时，仅以活跃目录中的文件为准，忽略 `_archived/`
+4. 如果 `_archived/` 中的内容与活跃目录冲突，以活跃目录为准
+
+## 已废弃对象黑名单（高频误引，显式列出）
+
+| 对象 | 类型 | 删除日期 | 替代方案 |
+|------|------|----------|----------|
+| `dwd.dwd_assistant_trash_event` | DWD 表 | 2026-02-22 | `dwd_assistant_service_log_ex.is_trash` |
+| `dwd.dwd_assistant_trash_event_ex` | DWD 扩展表 | 2026-02-22 | 同上 |
+| `ods.assistant_cancellation_records` | ODS 表 | 2026-02-22 | 不再需要独立链路 |
+| `ODS_ASSISTANT_ABOLISH` | ETL 任务 | 2026-02-22 | 无 |
+| `ASSISTANT_ABOLISH` | 调度任务 | 2026-02-22 | 无 |
+| `BILLIARD_VIP` | cfg_area_category 分类代码 | 2026-03-07 | V1-V4 归入 `BILLIARD`，V5 归入 `SNOOKER`（台桌级映射） |

.kiro/steering/doc-map.md

@@ -30,6 +30,6 @@ description: 项目文档地图索引。需要定位文档、理解项目结构
 
 - 新增 DB 表/字段 → 必须写 `BD_Manual_*.md`（见 `db-docs.md` steering）
 - 新增输出路径 → 先加 `.env` 变量，再更新 `EXPORT-PATHS.md`（见 `export-paths.md` steering）
-- 逻辑改动 → 检查是否命中审计条件（见 `governance.md` steering）
+- 逻辑改动 → 审计由 hooks 自动检测提醒，按需触发 `/audit`
 - 新增/修改 API → 同步更新 `API-REFERENCE.md`
 - 新增 ETL 任务 → 同步更新 `docs/etl_tasks/` 对应文档

.kiro/steering/dwd-doc-authority.md

@@ -0,0 +1,53 @@
+---
+inclusion: always
+---
+
+# DWD-DOC 标杆文档（权威数据源，强制优先参考）
+
+`docs/reports/DWD-DOC/` 是本项目的业务模型与财务数据权威标杆文档。
+所有涉及金额口径、支付渠道、消费链路、账务公式、字段语义的开发工作，必须以此目录为第一参考源。
+
+## 文档清单
+
+| 文件 | 内容 | 关键规则 |
+|------|------|----------|
+| `README.md` | 总览 + GAP 闭环状态 | 文档索引入口 |
+| `01-business-panorama.md` | 消费链路 + 优惠机制 + 消费场景 | settle_type 枚举、助教费用拆分、团购券三层价格 |
+| `02-accounting-panorama.md` | 支付渠道 + 对账公式 + consume_money 口径 | 支付渠道恒等式、F2 三期公式 |
+| `03-financial-panorama.md` | 收入构成 + 储值卡资金流 + 对账矩阵 | 平台结算互斥关系 |
+| `04-dimension-panorama.md` | 维度表与主数据全景 | SCD2 维度取值规则 |
+| `05-f2-balance-audit.md` | F2 收支平衡公式专项 | 三期公式 + 139 笔失败根因 |
+| `06-calibration-checklist.md` | 校准清单 + 验证 SQL | 全部验证公式集中 |
+| `consume/consume-money-caliber.md` | consume_money 口径变化时间线 | 三种口径(A/B/C)定义与切换时间点 |
+
+## 强制规则（所有 session 生效）
+
+1. **consume_money 禁止直接用于计算**：存在三种历史口径(A/B/C)混合，DWS 层及下游统一使用 `items_sum = table_charge_money + goods_money + assistant_pd_money + assistant_cx_money + electricity_money`
+2. **助教费用必须拆分**：使用 `assistant_pd_money`（陪打）和 `assistant_cx_money`（超休），禁止使用笼统的 `service_fee` / `ASSISTANT_BASE` / `ASSISTANT_BONUS`（`service_fee` 仅在平台结算表中表示"平台服务费"，语义不同）
+3. **支付渠道恒等式**：`balance_amount = recharge_card_amount + gift_card_amount`（100% 成立），三者不可重复计算
+4. **settle_type 过滤**：正向交易取 `IN (1, 3)`，本表无 `is_delete` 字段
+5. **电费未启用**：`electricity_money` 全为 0，`gross_amount` 不含电费是正确的
+6. **折扣互斥**：`discount_manual`（大客户优惠）与 `discount_other` 互斥，两者之和 = `adjust_amount`
+7. **现金流互斥**：`cash_inflow_total` 中 `platform_settlement_amount` 和 `groupbuy_pay_amount` 互斥
+8. **废单判断**：使用 `dwd_assistant_service_log_ex.is_trash`，`dwd_assistant_trash_event` 已废弃（2026-02-22 DROP）
+9. **储值卡字段命名**：DWS 层使用 `balance_pay`（总额）、`recharge_card_pay`（现金充值卡）、`gift_card_pay`（赠送卡）；`recharge_card_consume`（财务日报）
+
+## 使用场景
+
+- 编写或修改 ETL 任务代码（DWD/DWS 层）
+- 编写或修改后端 API 涉及金额计算的逻辑
+- 编写或修改小程序/管理后台涉及财务数据展示的页面
+- 编写 SQL 查询涉及结算、支付、消费金额
+- 编写或审阅 BD 手册、SPEC 文档中的字段口径描述
+- 前置调研（`pre-change-research.md`）中涉及财务/账务模块时
+
+## 与其他文档的优先级
+
+当以下文档与 DWD-DOC 标杆文档冲突时，以 DWD-DOC 为准：
+- BD 手册（`apps/etl/connectors/feiqiu/docs/database/`）
+- ETL 任务文档（`apps/etl/connectors/feiqiu/docs/etl_tasks/`）
+- 业务规则文档（`apps/etl/connectors/feiqiu/docs/business-rules/`）
+- SPEC 文档（`docs/prd/specs/`）
+- DDL 注释（`docs/database/ddl/`）
+
+> 标杆文档基于 2026-03-06 对 test_etl_feiqiu 数据库的实际数据验证，公式和比例关系具有权威性。

.kiro/steering/export-paths.md

@@ -1,16 +1,49 @@
 ---
 inclusion: always
 ---
+# 产出物路径规范（强制）
 
-# 输出路径规范（强制）
+Kiro 所有产出物分两类，各有归档规则，禁止随意散放。
 
-## 核心原则
-所有文件输出必须写入 `export/` 统一目录结构，通过 `.env` 环境变量控制路径。禁止在 `export/` 体系外自行创建输出目录。
+## 一、程序输出（数据文件、日志、报告）
 
-## 编码规则
-1. 路径必须从 `.env` 读取，禁止硬编码任何目录结构（含绝对路径和相对路径）
-2. 环境变量缺失时必须报错（`KeyError` / `RuntimeError`），禁止静默回退
-3. 路径读取方式：`scripts/ops/` 用 `_env_paths.get_output_path()`；ETL 核心用 `AppConfig.io.*`；独立脚本用 `os.environ.get()` + 显式报错
-4. 新增输出类型：先在根 `.env` + `.env.template` 新增变量，再在代码中引用，同步更新 `docs/deployment/EXPORT-PATHS.md`
+写入 `export/` 目录结构，路径从 `.env` 环境变量读取。禁止硬编码路径，禁止在 `export/` 外创建输出目录。
 
-> 完整目录结构、环境变量映射表、新增场景检查清单见 `export-paths-full.md`（fileMatch：读到 `.env*` / `scripts/` / `export/` 文件时自动加载，也可 `#export-paths-full` 手动加载）。
+### 规则
+1. 环境变量缺失时必须报错（`KeyError` / `RuntimeError`），禁止静默回退
+2. 读取方式：`scripts/ops/` → `_env_paths.get_output_path()`；ETL 核心 → `AppConfig.io.*`；独立脚本 → `os.environ.get()` + 显式报错
+3. 新增输出类型：先在 `.env` + `.env.template` 加变量，再更新 `docs/deployment/EXPORT-PATHS.md`
+
+> 完整目录结构与映射表见 `export-paths-full.md`（fileMatch 自动加载）。
+
+## 二、文档产出（markdown、设计文档、分析报告）
+
+写入 `docs/` 对应子目录，禁止在 `docs/` 根目录散放文件。
+
+### 归档规则
+
+| 文档类型 | 目标目录 | 示例 |
+|----------|----------|------|
+| 数据分析报告、调研产出 | `docs/reports/` | 复杂订单分析、字段口径全景 |
+| 架构设计文档 | `docs/architecture/` | ETL 架构说明 |
+| 数据库变更审计（BD 手册） | `docs/database/` | `BD_Manual_*.md` |
+| 变更审计记录 | `docs/audit/changes/` | `YYYY-MM-DD__<slug>.md` |
+| 产品需求规格 | `docs/prd/specs/` | P1-P11 需求 spec |
+| 数据契约（OpenAPI/Schema） | `docs/contracts/` | `backend-api.json` |
+| 部署与运维配置 | `docs/deployment/` | 启动清单、路径规范 |
+| 路线图与规划 | `docs/roadmap/` | 迁移计划、BACKLOG |
+| Spec 需求输入 | `docs/spec-input/` | 问题汇总供开启 Spec |
+| 外部参考资料 | `docs/reference/` | 第三方 API 指南 |
+| 迁移记录 | `docs/migrate/` | Monorepo 迁移总结 |
+| MCP 相关文档 | `docs/mcp/` | AI 查询手册 |
+| UI 原型 | `docs/h5_ui/` | H5 静态页面 |
+| 运维手册 | `docs/ops/` | 故障排查流程 |
+| 权限矩阵 | `docs/permission_matrix/` | 角色-资源映射 |
+
+### 禁止事项
+- 禁止在 `docs/` 根目录直接创建 `.md` 文件（`README.md` 和 `DOCUMENTATION-MAP.md` 除外）
+- 禁止将分析报告放入 `prd/specs/`（specs 只放需求规格）
+- 禁止将审计产物写入子模块内部（统一写 `docs/audit/`）
+- 模块专属文档放模块内部（如 `apps/etl/.../docs/`），不放 `docs/`
+
+> 完整文档索引见 `docs/DOCUMENTATION-MAP.md`。

.kiro/steering/governance.md

@@ -1,27 +0,0 @@
----
-inclusion: always
----
-
-# Governance（Lite）
-
-## 目的
-在“上下文压缩很致命”的前提下，保留最小硬约束：**任何逻辑改动必须可追溯、可验证、可回滚**。
-
-## 何时必须审计（Audit Required）
-满足任一即视为“高风险”，必须运行 `/audit`：
-- 改动文件命中：`api/`、`cli/`、`config/`、`database/`、`loaders/`、`models/`、`orchestration/`、`scd/`、`tasks/`、`utils/` 或根目录散文件
-- 出现 DB schema / migration / `*.sql` / `*.prisma` 结构性变更
-- 业务口径/资金精度与舍入/数据清洗聚合映射/API 契约/鉴权权限/调度游标逻辑发生变化
-
-## 执行方式（自动判定 + 半自动执行）
-- 系统会在你提交 prompt 时自动判定“是否待审计”，并在与 Kiro 交互结束时提醒（15 分钟限频）
-- 用户将手动触发 `/audit`（Manual: Run /audit hook），由 **audit-writer 子代理**执行重型写入
-- 主对话只接收“极短回执”（done + files_written + next_step），避免审计细节淹没上下文
-
-## 审计产物（由 /audit 生成）
-- `docs/audit/changes/<YYYY-MM-DD>__<slug>.md`
-- 每个被改文件内：`AI_CHANGELOG`
-- 每处逻辑变更附近：`CHANGE` 注释
-- DB schema 变更：同步 `docs/database/`
-
-（详细模板/清单/流程见 skills：`steering-readme-maintainer`、`change-annotation-audit`、`bd-manual-db-docs`）

.kiro/steering/language-zh.md

@@ -1,18 +1,7 @@
 ---
 inclusion: always
 ---
-# 语言与编码规范（强制）
-
-## 输出语言
-- 默认：所有“说明性文字”一律使用简体中文（对话回复、文档内容、代码注释、README/ADR/变更说明等）。
-- 允许保留英文的部分：
-  - 代码标识符（类名/函数名/变量名/接口名/库名/命令名）不翻译
-  - 第三方工具的原始 CLI 输出/报错原文不篡改（可在原文后补充中文解释）
-
-## 文档与注释
-- 新增/修改的文档必须与代码变更同步更新
-- 注释只写“为什么/边界/假设”，避免复述代码
-
-## 编码与字符集
-- 仓库内所有文本文件统一 UTF-8，无 BOM。
-- 禁止出现 GBK/Big5 混用；若发现历史文件，先转码再重构
+# 语言规范
+- 说明性文字一律简体中文（对话、文档、注释、变更说明）；代码标识符和第三方 CLI 原文保留英文
+- 文档与代码变更同步更新；注释只写"为什么/边界/假设"
+- 全仓 UTF-8 无 BOM，禁止 GBK/Big5 混用

.kiro/steering/miniprogram-h5-conversion.md

@@ -0,0 +1,152 @@
+---
+inclusion: fileMatch
+fileMatchPattern: "**/miniprogram/miniprogram/pages/**,**/miniprogram/miniprogram/components/**,**/h5_ui/**"
+name: miniprogram-h5-conversion
+description: H5 原型转微信小程序的强制规范。读到小程序页面/组件或 H5 原型文件时自动加载。
+---
+
+# H5 → 微信小程序转换规范（强制）
+
+本规范适用于所有将 `docs/h5_ui/pages/*.html` 转换为小程序页面的任务。
+
+## 一、转换前强制加载
+
+每次转换页面前，必须加载以下资源（按顺序）：
+
+1. `wechat-miniprogram` Power 的 steering 文件：`view-layer.md`、`tdesign.md`、`builtin-components.md`
+2. 目标页面的交互说明：`docs/h5_ui/interactions/<page>.md`
+3. 设计 Token：`docs/h5_ui/design-tokens.json`
+4. 图标映射表：`docs/h5_ui/icon-mapping.md`
+5. 目标页面的 H5 源码：`docs/h5_ui/pages/<page>.html`
+6. 计算样式（如有）：`docs/h5_ui/computed-styles.json` 中对应页面的 key
+7. 截图（如用户提供）：`docs/h5_ui/screenshots/<page>--*.png`
+
+## 二、原型忠实度（最高优先级）
+
+- `docs/h5_ui/pages/*.html` 中的结构、层次、元素、配色、间距、交互行为是唯一视觉真相
+- 任何偏离原型的实现都需要用户明确确认
+- 截图是校验还原度的唯一视觉参考
+
+## 三、标签映射（硬性规则）
+
+| HTML | WXML | 说明 |
+|------|------|------|
+| `<div>` | `<view>` | 容器 |
+| `<span>` / `<p>` | `<text>` | 文本必须用 `<text>` 包裹 |
+| `<a>` | `<navigator>` | 或 `wx.navigateTo()` |
+| `<img>` | `<image mode="">` | 必须指定 `mode` 和宽高 |
+| `<svg>` 内联 | `<image src="xx.svg">` | 不支持内联 SVG |
+| `<ul>/<li>` | `<view wx:for>` | 无列表语义标签 |
+| `<select>` | `<t-picker>` | 完全不同的交互 |
+| `<button>` | `<t-button>` | TDesign 优先 |
+| `<input>` | `<t-input>` | TDesign 优先 |
+
+严禁在 WXML 中使用 HTML 标签（div/span/p/a/img 等）。
+
+## 四、样式规则
+
+### rpx 换算
+- 基准：屏幕宽度 = 750rpx，设计稿以 375px 宽为基准
+- 换算公式：H5 的 px 值 × 2 = rpx 值
+- 严禁同一类间距混用 rpx 和 px
+
+### 设计 Token 引用
+颜色、间距、圆角、字号、阴影必须参照 `docs/h5_ui/design-tokens.json`，不得凭记忆硬编码。
+
+### 不支持的 CSS
+| CSS 特性 | 替代方案 |
+|----------|---------|
+| `backdrop-filter: blur()` | 半透明背景色 `rgba()` |
+| `*` 通配符选择器 | 逐个元素设置 |
+| 远程 `@font-face` | `wx.loadFontFace()` |
+
+### 样式隔离
+- `app.wxss` = 全局样式
+- 页面 `.wxss` = 自动隔离
+- 组件 `.wxss` = 默认隔离，穿透用外部样式类或 CSS 变量
+
+## 五、TDesign 优先原则
+
+- 凡 TDesign 组件库能覆盖的 UI 元素，必须使用 TDesign 组件
+- 自定义实现仅限 TDesign 无法覆盖的场景
+- TDesign 样式覆盖优先用 CSS 变量，其次外部样式类，最后 `!important`
+- 组件必须在页面 `.json` 的 `usingComponents` 中注册
+
+## 六、事件系统
+
+- 不能在 `bindtap` 中传参：用 `data-*` 属性
+- 取值路径：`e.detail.value`（非 `event.target.value`）
+- 阻止冒泡：用 `catchtap`（非 `preventDefault`）
+- `data-` 属性名自动转换：连字符转驼峰，大写转小写
+
+## 七、数据与状态
+
+- 用 `this.setData()` 驱动视图更新，无 DOM API
+- `wx:if` 中不支持复杂 JS 表达式，需在 JS 中预处理
+- 布尔属性必须用 `{{}}` 包裹：`checked="{{true}}"`
+- 列表渲染必须加 `wx:key`
+
+## 八、导航与路由
+
+- 页面栈最多 10 层，`navigateTo` 超过会静默失败
+- 跳转 tabBar 页面必须用 `switchTab`
+- 路径以 `/` 开头，不带 `.wxml` 后缀
+- 登录/登出场景用 `reLaunch`
+
+## 九、Mock 数据策略（纯 UI 阶段）
+
+后端 API 未就绪时，使用 mock 数据：
+- 在页面 JS 的 `onLoad` 中用 `this.setData()` 设置 mock 数据
+- mock 数据结构必须贴近真实 API 返回格式（参考对应 Spec 的接口定义）
+- mock 数据用 `// TODO: 替换为真实 API 调用` 注释标记
+- 联调时只需替换数据获取逻辑，不改动 WXML/WXSS
+
+## 十、新页面开发 Checklist
+
+- [ ] HTML 标签全部替换为 WXML 组件
+- [ ] 内联 SVG 提取为文件，改用 `<image>` 或 `<t-icon>`
+- [ ] Tailwind 类全部手写为 WXSS（px × 2 = rpx）
+- [ ] 不支持的 CSS 改为替代方案
+- [ ] 事件绑定改为 `bindtap` / `bind:change`，传参用 `data-*`
+- [ ] `alert/confirm` 改为 `wx.showToast` / `wx.showModal`
+- [ ] `localStorage` 改为 `wx.setStorageSync`
+- [ ] 路由跳转改为 `wx.navigateTo` / `wx.reLaunch` 等
+- [ ] 图片设置 `mode` 属性
+- [ ] 列表渲染加 `wx:key`
+- [ ] 布尔属性用 `{{}}` 包裹
+- [ ] TDesign 组件在页面 `.json` 中注册
+- [ ] 安全区适配：JS `wx.getSystemInfoSync().statusBarHeight` 动态 padding-top（禁止用 `env(safe-area-inset-top)`）
+- [ ] 页面配置：`navigationBarTitleText` 等
+
+## 十一、验收标准
+
+- 视觉还原度：与 H5 截图对比，布局/间距/颜色/字号一致
+- 交互完整性：交互说明中的所有状态和操作均已实现
+- 空状态/加载态/错误态：均有处理
+- TDesign 组件正确使用，无原生 HTML 标签残留
+
+## 十二、实战踩坑速查
+
+> 完整记录见 `docs/prd/MIGRATION-PLAYBOOK.md` 第六章。
+
+### WXML 模板
+- **禁止在 `{{}}` 中调用 JS 方法**（`.toFixed()`、`.map()` 等）→ 用 WXS 模块 `utils/format.wxs`
+- **TabBar 页面跳转必须用 `wx.switchTab`**（task-list、board-finance、my-profile），`navigateTo` 会静默失败
+
+### 样式与布局
+- **一屏页面**（login、reviewing、no-permission 等）：`height: 100vh` + `box-sizing: border-box`，不用 `min-height: 100vh`
+- **状态栏适配**：用 JS `wx.getSystemInfoSync().statusBarHeight` 动态设置 `padding-top`，禁止用 `env(safe-area-inset-top)`
+- **padding-top + 100vh**：必须配合 `box-sizing: border-box`，否则底部内容溢出
+
+### TDesign 组件
+- **`t-button icon="xxx"` 只支持内置图标**：品牌图标（微信 logo 等）必须导出 SVG，用 `<view>` + `<image>` 组合
+- **TDesign 默认样式优先级高**：与原型差异大时，直接用原生 `<view>` 实现，绕开样式干扰
+
+### 资源引用
+- **所有 H5 内联 SVG 必须导出为独立 `.svg` 文件**，存放 `assets/icons/`，用 `<image>` 引用
+- **引用不存在的图片会 500 错误**：用 CSS 渐变、emoji、`<t-icon>` 替代
+
+---
+
+> 以上内容已整合至 `docs/prd/MIGRATION-PLAYBOOK.md`（唯一权威迁移文档）。
+> 避坑清单见第六章，迁移流程见第二章，输入素材见第十二章，AI 工作流见第十一章。

.kiro/steering/planning-interrogation.md

@@ -0,0 +1,62 @@
+---
+inclusion: always
+---
+# 编码前需求审问（强制）
+
+AI 在用户清晰度结束的地方开始产生幻觉。因此，在写任何一行代码之前，必须通过持续提问来延伸用户的清晰度，找出思维中的 gaps，避免在破碎的基础上构建。
+
+## 触发条件
+当用户提出涉及以下任一场景的需求时，进入「审问模式」：
+- 新建功能/模块/页面/接口
+- 重构或重新设计已有逻辑
+- 涉及多模块联动的改动
+- 任何需求描述中存在模糊、隐含假设、或未定义边界的情况
+
+## 强制流程
+
+### 1. 进入 Planning 模式
+收到需求后，不立即动手，先进入提问循环。每轮提出 3-5 个针对性问题，直到所有维度都有明确答案。
+
+### 2. 必问清单（最低要求）
+以下问题必须逐一确认，不得假设答案：
+
+| 维度 | 必问问题 |
+|------|----------|
+| 用户 | 这是给谁用的？（角色/人群） |
+| 核心行为 | 用户执行的核心操作是什么？ |
+| 完成后果 | 操作完成后发生什么？（跳转/提示/状态变化） |
+| 数据写入 | 需要保存什么数据？保存到哪里？ |
+| 数据展示 | 需要展示什么数据？数据来源？ |
+| 错误处理 | 出错时发生什么？用户看到什么？ |
+| 成功反馈 | 成功时发生什么？用户看到什么？ |
+| 认证 | 需要登录/鉴权吗？什么权限级别？ |
+| 存储 | 需要数据库吗？哪个库？新表还是已有表？ |
+| 终端适配 | 需要在手机上工作吗？响应式要求？ |
+| 边界条件 | 并发/幂等/数据量上限/超时？ |
+
+### 3. 追问规则
+- 用户回答后，如果答案引出新的未定义项，继续追问
+- 不接受"你看着办"作为最终答案——至少确认关键维度
+- 每轮追问聚焦于上一轮答案暴露的 gaps
+- 当所有必问维度都有明确答案、且无新假设浮出时，才可结束审问
+
+### 4. 输出需求确认摘要
+审问结束后，输出一份简洁的「需求确认摘要」，包含：
+- 目标用户与场景
+- 核心功能描述（一句话）
+- 数据流向（输入 → 处理 → 输出/存储）
+- 关键约束与边界条件
+- 明确排除的内容（不做什么）
+
+用户确认摘要后，才可进入实施阶段。
+
+## 与前置调研的关系
+- 本规则在 `pre-change-research.md`（前置调研）之前执行
+- 流程顺序：需求审问 → 用户确认 → 前置调研 → 用户确认 → 编码实施
+- 如果审问阶段发现需求本身不成立，直接终止，不进入调研
+
+## 例外
+- 用户明确说"直接改"、"跳过审问"、"不用问了"
+- Bug 修复且用户已给出明确的复现步骤和期望行为
+- 纯格式/文档/注释调整
+- 用户提供了完整的 spec 文档且所有维度已覆盖

.kiro/steering/pre-change-research.md

@@ -0,0 +1,40 @@
+---
+inclusion: always
+---
+# 逻辑改动前置调研（强制）
+
+任何涉及逻辑改动的任务（ETL 流程、业务规则、API 接口、数据模型、前端交互逻辑等），在写第一行代码之前，必须完成以下调研步骤：
+
+## 强制流程
+
+### 1. 委托子代理调研（节省主流程上下文）
+使用 `context-gatherer` 子代理执行调研，传入以下指令要点：
+- 要改动的模块/文件路径
+- 搜索 `docs/audit/changes/` 中相关的历史审计记录
+- **查询 Session 索引**：读取 `docs/audit/session_logs/_session_index.json`，按 `summary.files_modified` 筛选涉及目标模块的历史 session，提取 `description`（操作摘要）和 `startTime`，了解该模块近期被修改的上下文和原因（详见 `docs/audit/SESSION-LOG-GUIDE.md`）
+- 阅读涉及模块的 README、PRD spec（`docs/prd/specs/`）
+- 数据库相关：BD 手册（`docs/database/BD_Manual_*.md`）
+- ETL 相关：产品说明、数据流报告
+- 接口相关：OpenAPI spec、接口文档
+- 读取要修改的文件及其直接依赖（调用方、被调用方）
+- 确认数据流向：上游输入 → 当前处理 → 下游消费
+- 识别潜在影响范围（哪些模块/表/接口会受波及）
+
+子代理返回精炼摘要，主流程不直接读取大量文件，保持上下文干净。
+
+> **Session 日志作为调研数据源**：Session 索引（`_session_index.json`）记录了每轮 AI 操作的结构化摘要（文件变更、子代理调用、错误、LLM 生成的操作描述），是了解"某个文件/模块近期发生了什么"的最高效数据源。相比逐个打开审计记录，索引查询零 Token 成本且信息密度更高。
+
+### 2. 输出上下文摘要
+基于子代理返回的调研结果，向用户输出简要的「改动前上下文摘要」，包含：
+- 当前模块的职责和关键逻辑
+- 历史变更要点（如有）
+- 本次改动的影响范围评估
+- 需要注意的风险点或边界条件
+
+用户确认后再开始实施。
+
+## 例外
+- 纯格式调整（缩进、空行、import 排序）
+- 注释/文档纯文字修改（不涉及逻辑描述变更）
+- 用户明确说"直接改"或"跳过调研"
+- 新建文件且不涉及已有逻辑的修改

.kiro/steering/product.md

@@ -1,22 +0,0 @@
----
-inclusion: always
----
-
-# 产品概述
-
-NeoZQYY Monorepo — 面向台球门店业务的全栈数据平台。
-
-## 子系统
-- ETL Connector（`apps/etl/connectors/feiqiu/`）：上游 SaaS API → ODS → DWD → DWS 三层处理
-- FastAPI 后端（`apps/backend/`）：业务 API 服务
-- 微信小程序（`apps/miniprogram/`）：C 端用户界面
-- 管理后台（`apps/admin-web/`）：任务管理、调度配置、数据查看、ETL 监控
-- MCP Server（`apps/mcp-server/`）：AI 工具集成服务
-- 共享包（`packages/shared/`）：枚举、金额精度、时间工具
-
-## 业务上下文
-- 多门店隔离：`site_id` + RLS
-- 核心实体：会员、助教、台桌、订单、支付、退款、团购套餐、库存
-- 领域语言中文；货币 CNY，金额 numeric(2)
-
-> ETL 功能细节、指数算法等见 `product-full.md`（fileMatch：读到 ETL 任务/模型/业务规则文件时自动加载，也可 `#product-full` 手动加载）。

.kiro/steering/project-overview.md

@@ -0,0 +1,36 @@
+---
+inclusion: always
+---
+# 项目概览
+
+NeoZQYY Monorepo — 面向台球门店业务的全栈数据平台。多门店隔离（`site_id` + RLS），领域语言中文，货币 CNY，金额 numeric(2)。
+
+## 子系统与目录
+| 目录 | 说明 |
+|------|------|
+| `apps/etl/connectors/feiqiu/` | 飞球 Connector：上游 SaaS API → ODS → DWD → DWS |
+| `apps/backend/` | FastAPI 后端 |
+| `apps/miniprogram/` | 微信小程序（C 端） |
+| `apps/admin-web/` | 管理后台（React + Vite + Ant Design） |
+| `apps/mcp-server/` | MCP Server（AI 工具集成） |
+| `packages/shared/` | 跨项目共享包（枚举、金额精度、时间工具） |
+| `db/` | DDL / 迁移 / 种子（`etl_feiqiu/`、`zqyy_app/`、`fdw/`） |
+| `docs/` | 项目级文档 + `audit/`（统一审计落地点） |
+| `tests/` | Monorepo 级属性测试（hypothesis） |
+| `scripts/` | 项目级运维脚本（`ops/`、`audit/`、`migrate/`、`server/`） |
+
+## 高风险路径（变更需审计）
+- ETL：`api/`、`cli/`、`config/`、`database/`、`loaders/`、`models/`、`orchestration/`、`scd/`、`tasks/`、`utils/`、`quality/`
+- `apps/backend/app/`、`apps/admin-web/src/`、`apps/miniprogram/miniprogram/`
+- `packages/shared/`、`db/`、根目录散文件（`.env*`、`pyproject.toml`）
+
+## 文件归属规则
+- 模块专属 docs/tests/scripts → 模块内部
+- 项目级/跨模块 → 根目录对应文件夹
+- 审计产物统一写 `docs/audit/`，禁止写入子模块
+- 编码：UTF-8、纯 SQL、迁移脚本日期前缀、任务大写蛇形
+
+## 治理
+任何逻辑改动必须可追溯、可验证、可回滚。审计检测与提醒由 hooks 自动执行（`agent-on-stop` + `prompt-on-submit`），用户按需手动触发 `/audit`。
+
+> 详细目录树见 `structure.md`（fileMatch 自动加载）；ETL 功能细节见 `product-full.md`（fileMatch 自动加载）。

.kiro/steering/steering-readme-maintainer.md

@@ -11,7 +11,7 @@ inclusion: manual
 - 发生业务/资金口径/ETL/接口/鉴权/小程序交互等“逻辑改动”时
 
 ## 快速清单
-- 是否需要更新 product.md / tech.md / structure.md / README.md / (各子目录下README.md)
+- 是否需要更新 project-overview.md / tech.md / structure.md / README.md / (各子目录下README.md)
 - 是否需要补齐审计记录 docs/audit/changes/<date>__<slug>.md
 - 是否需要在每个修改文件写入 AI_CHANGELOG
 - 是否需要在逻辑变更处加 CHANGE 标记注释

.kiro/steering/structure-lite.md

@@ -1,34 +0,0 @@
----
-inclusion: always
----
-
-# 项目结构（Lite）
-
-> 详细目录树、架构模式、文件归属规则展开说明见 `structure.md`（读到 pyproject.toml 或 agent 定义时自动加载，也可 `#structure-full` 手动加载）。
-
-## 顶层目录
-- `apps/etl/connectors/feiqiu/` — 飞球 Connector
-- `apps/backend/` — FastAPI 后端
-- `apps/miniprogram/` — 微信小程序
-- `apps/admin-web/` — 管理后台（React + Vite + Ant Design）
-- `apps/mcp-server/` — MCP Server（AI 工具集成）
-- `packages/shared/` — 跨项目共享包
-- `db/` — DDL / 迁移 / 种子（`etl_feiqiu/`、`zqyy_app/`、`fdw/`）
-- `docs/` — 项目级文档 + `audit/`（统一审计落地点）
-- `tests/` — Monorepo 级属性测试
-- `scripts/` — 项目级运维脚本（`ops/`、`audit/`、`migrate/`、`server/`）
-
-## 高风险路径（变更需审计）
-- `apps/etl/connectors/feiqiu/` 下：`api/`、`cli/`、`config/`、`database/`、`loaders/`、`models/`、`orchestration/`、`scd/`、`tasks/`、`utils/`、`quality/`
-- `apps/backend/app/`、`apps/admin-web/src/`、`apps/miniprogram/miniprogram/`
-- `packages/shared/`、`db/`、根目录散文件（`.env*`、`pyproject.toml`）
-
-## 文件归属规则（强制）
-- 模块专属的 docs/tests/scripts → 放模块内部
-- 项目级/跨模块的 docs/tests/scripts → 放根目录
-- 审计产物统一写 `docs/audit/`，禁止写入子模块内部
-- 一览表刷新：`python scripts/audit/gen_audit_dashboard.py`
-
-## 编码/命名约定
-- UTF-8、纯 SQL（非 ORM）、迁移脚本 `db/etl_feiqiu/migrations/`（日期前缀）
-- 任务大写蛇形（`DWD_LOAD_FROM_ODS`）、日志经 `utils/logging_utils.py`

.kiro/steering/structure.md

@@ -1,6 +1,6 @@
 ---
 inclusion: fileMatch
-fileMatchPattern: "pyproject.toml,**/pyproject.toml,.kiro/steering/structure-lite.md,.kiro/agents/**"
+fileMatchPattern: "pyproject.toml,**/pyproject.toml,.kiro/steering/project-overview.md,.kiro/agents/**"
 name: structure-full
 description: 完整目录树 + 架构模式 + 文件归属规则展开。读到项目配置或 steering/agent 定义时自动加载。
 ---

.kiro/steering/tech.md

@@ -1,17 +1,13 @@
 ---
 inclusion: always
 ---
+# 技术栈
 
-# 技术栈与构建
-
-## 语言与运行时
-- Python 3.10+，uv workspace（根 `pyproject.toml` 声明 4 个成员：etl/connectors/feiqiu、backend、mcp-server、shared）
+- Python 3.10+，uv workspace（4 成员：etl/connectors/feiqiu、backend、mcp-server、shared）
 - 管理后台：React + Vite + Ant Design（`apps/admin-web/`，独立 pnpm）
-
-## 数据库
-- PostgreSQL 远程实例，四库：`etl_feiqiu` / `test_etl_feiqiu`（ETL）、`zqyy_app` / `test_zqyy_app`（业务）
-- ETL 六层 Schema：meta / ods / dwd / core / dws / app
+- PostgreSQL 四库：`etl_feiqiu` / `test_etl_feiqiu`（ETL，六层 Schema）、`zqyy_app` / `test_zqyy_app`（业务）
 - DSN：`PG_DSN`（ETL）、`APP_DB_DSN`（业务），根 `.env` 定义
+- 配置分层：根 `.env` < `.env.local` < 环境变量 < CLI 参数；ETL 配置类 → `AppConfig`
 
 ## 常用命令
 ```bash
@@ -22,12 +18,8 @@ cd apps/etl/connectors/feiqiu && pytest tests/unit         # ETL 单元测试
 cd C:\NeoZQYY && pytest tests/ -v                          # 属性测试
 ```
 
-## 配置体系
-- 分层叠加：根 `.env` < 应用 `.env.local` < 环境变量 < CLI 参数
-- ETL 配置类：`apps/etl/connectors/feiqiu/config/settings.py` → `AppConfig`
+## 脚本规范
+- 复杂操作优先写 Python 脚本，避免 PowerShell 复杂逻辑
+- 一次性运维脚本 → `scripts/ops/`；模块专属 → 模块内 `scripts/`
 
-## 脚本执行规范
-- 复杂操作优先写 Python 脚本再执行，避免 PowerShell 复杂逻辑
-- 一次性运维脚本放 `scripts/ops/`，模块专属脚本放模块内 `scripts/`
-
-> 核心依赖清单、DDL 基线、种子数据等详细信息见 `tech-full.md`（fileMatch：读到 pyproject.toml / 配置 / 迁移文件时自动加载，也可 `#tech-full` 手动加载）。
+> 依赖清单、DDL 基线等见 `tech-full.md`（fileMatch 自动加载）。

.kiro/steering/testing-env.md

@@ -1,25 +1,19 @@
 ---
 inclusion: always
 ---
-
 # 测试与验证环境规范（强制）
 
-## 核心原则
-AI 执行测试、验证、调试、一次性脚本时，必须使用与正式运行一致的参数环境。禁止因"只是测试"而省略配置、跳过 `.env` 加载、或使用不完整的参数集。
+AI 执行测试/验证/调试/一次性脚本时，必须使用与正式运行一致的参数环境。
 
-## 具体要求
+## 规则
+1. 必须 `load_dotenv` 加载根 `.env`；必需变量（`FETCH_ROOT`、`EXPORT_ROOT`、`PG_DSN` 等）缺失时立即报错，禁止静默回退空字符串
+2. cwd 与正式一致：ETL → `apps/etl/connectors/feiqiu/`；后端 → `apps/backend/`
+3. 配置走 `AppConfig.load()` 正常流程，不得为测试单独构造简化配置
+4. 数据库使用测试库：`test_etl_feiqiu` / `test_zqyy_app`（`TEST_DB_DSN`），禁止连正式库
 
-1. **环境变量必须完整加载**：测试脚本必须通过 `load_dotenv` 或等效方式加载根 `.env`（及模块 `.env`），不得假设"测试不需要路径配置"
-2. **禁止空值回退到意外默认**：如果某个必需参数（如 `FETCH_ROOT`、`EXPORT_ROOT`、`PG_DSN`）未加载到，应立即报错终止，而非静默使用空字符串或其他配置项的值
-3. **cwd 必须与正式运行一致**：ETL CLI 测试的 `cwd` 应为 `apps/etl/connectors/feiqiu/`；后端测试的 `cwd` 应为 `apps/backend/`
-4. **不得为测试单独构造简化配置**：除非用户明确要求隔离测试环境，否则一律使用 `AppConfig.load()` 正常流程加载配置
-5. **数据库连接使用测试库**：测试涉及数据库时，优先使用 `test_etl_feiqiu` / `test_zqyy_app`（通过 `TEST_DB_DSN` 环境变量），而非正式库
+## 例外
+- 用户明确指定简化环境
+- 纯单元测试用 FakeDB/FakeAPI（不涉及真实路径/连接）
+- `--dry-run` CLI 验证（路径配置仍需完整）
 
-## 例外情况
-以下场景允许偏离：
-- 用户明确指定使用特定参数或简化环境
-- 纯单元测试使用 FakeDB/FakeAPI（`tests/unit/task_test_utils.py`），不涉及真实路径或连接
-- `--dry-run` 模式下的 CLI 验证（但路径配置仍需完整）
-
-## 背景
-此规则源于实际事故：测试时 `FETCH_ROOT` 未正确加载，`or` 链回退到空字符串，导致时区值 `Asia/Shanghai` 被误用为文件路径，在项目目录下创建了垃圾目录 `Asia/Shanghai/ODS_JSON_ARCHIVE/`。
+> 背景：曾因 `FETCH_ROOT` 未加载，`or` 链回退空字符串，时区值 `Asia/Shanghai` 被误用为路径，创建了垃圾目录。

.kiro/steering/weixin-devtools-mcp.md

@@ -0,0 +1,29 @@
+---
+inclusion: manual
+---
+
+# 微信开发者工具 MCP 连接规范
+
+使用 `weixin-devtools-mcp` 操作小程序时，必须遵循以下规则：
+
+## 连接方式
+
+1. 启动自动化端口：
+   ```powershell
+   & "C:\dev\WechatDevtools\cli.bat" auto --project "C:\NeoZQYY\apps\miniprogram" --auto-port 9420
+   ```
+
+2. AI 使用 `connect_devtools` 时，只能用 `wsEndpoint` 策略：
+   - `strategy`: `wsEndpoint`
+   - `wsEndpoint`: `ws://127.0.0.1:9420`
+   - `projectPath`: `C:\NeoZQYY\apps\miniprogram`
+
+## 禁止事项
+
+- 禁止使用 `connect`、`discover`、`auto`、`launch` 策略（会导致开发者工具重启）
+- 禁止在未确认自动化端口已启动的情况下调用 `connect_devtools`
+- 如果连接失败，提示用户检查终端中自动化端口是否在运行，不要自行重试其他策略
+
+## 详细文档
+
+参见 `docs/mcp/WEIXIN-DEVTOOLS-MCP.md`