在准备环境前提交次全部更改。

docs/migrate/monorepo-migration-summary.md

@@ -0,0 +1,506 @@
+# NeoZQYY Monorepo 迁移总结
+
+> 本文档记录从旧仓库到 NeoZQYY Monorepo 的完整迁移过程，供后续维护和开发参考。
+
+## 1. 背景
+
+### 1.1 迁移前状态
+
+| 仓库 | 路径 | 内容 |
+|------|------|------|
+| FQ-ETL | `C:\ZQYY\FQ-ETL` | ETL Connector + 桌面 GUI + 测试 + 文档 + 脚本 |
+| XCX | `C:\ZQYY\XCX\` | 微信小程序源码 |
+
+旧仓库 FQ-ETL 是一个单体项目，ETL Connector、GUI、数据库脚本、文档混合在同一目录下，缺乏模块边界。
+
+### 1.2 迁移目标
+
+将所有项目整合为 NeoZQYY Monorepo（`C:\NeoZQYY\`），实现：
+- 清晰的模块边界（apps/packages/db/docs 分离）
+- uv workspace 统一依赖管理
+- 六层数据库 Schema 架构（meta/ods/dwd/core/dws/app）
+- 多门店隔离（site_id + RLS）
+- FastAPI 后端骨架
+- 共享包（枚举、金额精度、时间工具）
+- 属性测试（Property-Based Testing）覆盖关键正确性属性
+
+## 2. Monorepo 最终结构
+
+```
+C:\NeoZQYY\
+├── apps/
+│   ├── etl/pipelines/feiqiu/    # 飞球 Connector（数据源连接器，从 FQ-ETL 平移）
+│   ├── backend/                  # FastAPI 后端（新建骨架）
+│   ├── miniprogram/              # 微信小程序（从 XCX 平移）
+│   └── admin-web/                # 管理后台（占位）
+├── gui/                          # PySide6 桌面 GUI（从 FQ-ETL 平移）
+├── packages/shared/              # 跨项目共享包（新建）
+├── db/
+│   ├── etl_feiqiu/schemas/       # 六层 Schema DDL（新建）
+│   ├── etl_feiqiu/migrations/    # ETL 迁移脚本（从 FQ-ETL 平移）
+│   ├── etl_feiqiu/seeds/         # 种子数据（从 FQ-ETL 平移）
+│   ├── etl_feiqiu/scripts/       # 测试数据库脚本（新建）
+│   ├── zqyy_app/schemas/         # 业务数据库 DDL（新建）
+│   └── fdw/                      # FDW 跨库映射（新建）
+├── docs/                         # 文档（从 FQ-ETL 平移 + 新增）
+├── infra/                        # 基础设施配置（占位）
+├── scripts/                      # 运维脚本（从 FQ-ETL 平移）
+├── samples/                      # 示例数据（占位）
+├── tests/                        # Monorepo 级属性测试（新建）
+├── tmp/                          # 临时文件（gitignore）
+├── .kiro/                        # Kiro 配置
+├── pyproject.toml                # uv workspace 根配置
+├── .env.template                 # 环境变量模板
+├── .gitignore
+├── .kiroignore
+└── README.md
+```
+
+## 3. 文件映射关系
+
+### 3.1 ETL Connector（飞球）
+
+| 旧路径（FQ-ETL） | 新路径（NeoZQYY） |
+|---|---|
+| `api/` | `apps/etl/pipelines/feiqiu/api/` |
+| `cli/` | `apps/etl/pipelines/feiqiu/cli/` |
+| `config/` | `apps/etl/pipelines/feiqiu/config/` |
+| `database/` | `apps/etl/pipelines/feiqiu/database/` |
+| `loaders/` | `apps/etl/pipelines/feiqiu/loaders/` |
+| `models/` | `apps/etl/pipelines/feiqiu/models/` |
+| `orchestration/` | `apps/etl/pipelines/feiqiu/orchestration/` |
+| `scd/` | `apps/etl/pipelines/feiqiu/scd/` |
+| `tasks/` | `apps/etl/pipelines/feiqiu/tasks/` |
+| `utils/` | `apps/etl/pipelines/feiqiu/utils/` |
+| `quality/` | `apps/etl/pipelines/feiqiu/quality/` |
+| `tests/` | `apps/etl/pipelines/feiqiu/tests/` |
+| `scripts/` | `scripts/`（根级） |
+| `docs/` | `docs/`（根级） |
+| `pytest.ini` | `apps/etl/pipelines/feiqiu/pytest.ini` |
+| `requirements.txt` | 已转化为 `apps/etl/pipelines/feiqiu/pyproject.toml` |
+
+### 3.2 数据库文件
+
+| 旧路径（FQ-ETL） | 新路径（NeoZQYY） |
+|---|---|
+| `database/schema/` | `db/etl_feiqiu/schemas/`（重构为六层 DDL） |
+| `database/migrations/` | `db/etl_feiqiu/migrations/` |
+| `database/seeds/` | `db/etl_feiqiu/seeds/` |
+| `database/*.py` | `apps/etl/pipelines/feiqiu/database/`（Python 模块保留在 ETL 内部） |
+
+### 3.3 GUI
+
+| 旧路径（FQ-ETL） | 新路径（NeoZQYY） |
+|---|---|
+| `gui/` | `gui/`（根级，独立于 apps） |
+
+### 3.4 小程序
+
+| 旧路径 | 新路径（NeoZQYY） |
+|---|---|
+| `C:\ZQYY\XCX\` | `apps/miniprogram/` |
+| 原型设计稿 | `docs/h5_ui/` |
+
+### 3.5 Kiro 配置
+
+| 旧路径（FQ-ETL） | 新路径（NeoZQYY） |
+|---|---|
+| `.kiro/steering/` | `.kiro/steering/`（内容已更新为 Monorepo 视角） |
+| `.kiro/specs/` | `.kiro/specs/` |
+| `.kiro/hooks/` | `.kiro/hooks/` |
+| `.kiro/scripts/` | `.kiro/scripts/` |
+| `.kiro/agents/` | `.kiro/agents/` |
+| `.kiro/skills/` | `.kiro/skills/` |
+| `.kiro/settings/` | `.kiro/settings/` |
+
+## 4. 新建内容（非平移）
+
+### 4.1 六层数据库 Schema DDL
+
+在 `db/etl_feiqiu/schemas/` 下新建 6 个 DDL 文件：
+
+| 文件 | Schema | 用途 |
+|------|--------|------|
+| `meta.sql` | meta | 调度元数据：游标、运行记录、任务注册 |
+| `ods.sql` | ods | 操作数据存储层：原始 API 数据落地 |
+| `dwd.sql` | dwd | 明细数据层：清洗后的维度表（SCD2）和事实表 |
+| `core.sql` | core | 统一最小字段集：跨门店标准化视图 |
+| `dws.sql` | dws | 数据服务层：汇总表（业绩、财务、会员分析） |
+| `app.sql` | app | 应用视图层：启用 RLS，按 site_id 过滤 |
+
+### 4.2 业务数据库
+
+| 文件 | 用途 |
+|------|------|
+| `db/zqyy_app/schemas/init.sql` | 业务应用数据库（用户、RBAC、任务、审批），7 张表均含 site_id |
+| `db/fdw/setup_fdw.sql` | postgres_fdw 配置，zqyy_app 只读映射 etl_feiqiu.app schema |
+
+### 4.3 FastAPI 后端骨架
+
+`apps/backend/` 下新建：
+- `app/main.py` — FastAPI 入口，启用 OpenAPI 文档
+- `app/config.py` — 配置加载
+- `app/database.py` — zqyy_app 数据库连接
+- `app/routers/` — 路由模块（占位）
+- `app/middleware/` — 中间件（占位）
+- `app/schemas/` — Pydantic 模型（占位）
+- `pyproject.toml` — 依赖声明（fastapi, uvicorn, psycopg2-binary, neozqyy-shared）
+
+### 4.4 共享包
+
+`packages/shared/` 下新建：
+- `src/neozqyy_shared/__init__.py`
+- `src/neozqyy_shared/enums.py` — 字段枚举
+- `src/neozqyy_shared/money.py` — 金额精度工具
+- `src/neozqyy_shared/datetime_utils.py` — 时间处理工具
+
+### 4.5 属性测试（Property-Based Testing）
+
+在 `tests/` 下新建 11 个属性测试文件，使用 hypothesis 库：
+
+| 文件 | Property | 验证内容 |
+|------|----------|----------|
+| `test_property_readme_structure.py` | P1 | README 结构完整性（三段式） |
+| `test_property_pyproject_completeness.py` | P2 | pyproject.toml 完整性 |
+| `test_property_config_priority.py` | P3 | 配置优先级（分层叠加） |
+| `test_property_config_missing.py` | P4 | 缺失配置检测 |
+| `test_property_file_migration.py` | P5 | 文件迁移完整性 |
+| `test_property_schema_migration.py` | P6 | Schema 迁移完整性 |
+| `test_property_core_minimal_fields.py` | P7 | Core 最小字段集 |
+| `test_property_test_db_consistency.py` | P8 | 测试数据库一致性 |
+| `test_property_steering_paths.py` | P9 | Steering 文件路径更新 |
+| `test_property_site_id_existence.py` | P10 | site_id 字段存在性 |
+| `test_property_rls_site_id.py` | P11 | RLS 按 site_id 隔离 |
+
+### 4.6 uv Workspace 配置
+
+根 `pyproject.toml` 声明 4 个 workspace 成员：
+- `apps/etl/pipelines/feiqiu`
+- `apps/backend`
+- `packages/shared`
+- `gui`
+
+## 5. 迁移处理方式
+
+### 5.1 文件复制策略
+
+- 使用 `robocopy /E` 进行跨目录批量复制（Windows 环境）
+- ETL 业务代码（11 个目录）整体平移，保持内部结构不变
+- `requirements.txt` 转化为 `pyproject.toml` 依赖声明
+- `pytest.ini` 保留在 ETL 子项目内，`pythonpath = .` 确保导入正确
+
+### 5.2 数据库重构策略
+
+旧仓库 `database/` 目录混合了 DDL（SQL）和 Python 代码，迁移时按职责拆分：
+
+#### 5.2.1 文件拆分与去向
+
+| 旧文件（FQ-ETL `database/`） | 新位置（NeoZQYY） | 处理方式 |
+|---|---|---|
+| `schema_ODS_doc.sql` | `db/etl_feiqiu/schemas/schema_ODS_doc.sql` | 原样复制（保留为历史参考） |
+| `schema_dwd_doc.sql` | `db/etl_feiqiu/schemas/schema_dwd_doc.sql` | 原样复制（保留为历史参考） |
+| `schema_dws.sql` | `db/etl_feiqiu/schemas/schema_dws.sql` | 原样复制（保留为历史参考） |
+| `schema_etl_admin.sql` | `db/etl_feiqiu/schemas/schema_etl_admin.sql` | 原样复制（保留为历史参考） |
+| `schema_verify_perf_indexes.sql` | `db/etl_feiqiu/schemas/schema_verify_perf_indexes.sql` | 原样复制 |
+| `seed_dws_config.sql` | `db/etl_feiqiu/seeds/seed_dws_config.sql` | 原样复制 |
+| `seed_index_parameters.sql` | `db/etl_feiqiu/seeds/seed_index_parameters.sql` | 原样复制 |
+| `seed_ods_tasks.sql` | `db/etl_feiqiu/seeds/seed_ods_tasks.sql` | 原样复制 |
+| `seed_scheduler_tasks.sql` | `db/etl_feiqiu/seeds/seed_scheduler_tasks.sql` | 原样复制 |
+| `migrations/`（6 个 SQL） | `db/etl_feiqiu/migrations/` | 原样复制 |
+| `connection.py` | `apps/etl/pipelines/feiqiu/database/connection.py` | 保留在 ETL 内部 |
+| `operations.py` | `apps/etl/pipelines/feiqiu/database/operations.py` | 保留在 ETL 内部 |
+| `base.py` | `apps/etl/pipelines/feiqiu/database/base.py` | 保留在 ETL 内部 |
+| `__init__.py` | `apps/etl/pipelines/feiqiu/database/__init__.py` | 保留在 ETL 内部 |
+
+#### 5.2.2 新建六层 Schema DDL
+
+在 `db/etl_feiqiu/schemas/` 下新建 6 个 DDL 文件，定义 NeoZQYY 的目标六层架构：
+
+| 文件 | Schema | 内容来源 |
+|------|--------|----------|
+| `meta.sql` | meta | 从 `schema_etl_admin.sql` 提取调度/游标/运行记录表，重命名为 meta schema |
+| `ods.sql` | ods | 从 `schema_ODS_doc.sql` 提取 ODS 表定义 |
+| `dwd.sql` | dwd | 从 `schema_dwd_doc.sql` 提取维度表（SCD2）和事实表 |
+| `core.sql` | core | 新建：统一最小字段集视图 |
+| `dws.sql` | dws | 从 `schema_dws.sql` 提取汇总表定义 |
+| `app.sql` | app | 新建：面向外部的视图 + RLS 策略（按 site_id 隔离） |
+
+注意：旧的 `schema_*.sql` 文件同时保留在 `db/etl_feiqiu/schemas/` 下作为历史参考，新的六层 DDL 文件是目标架构的规范定义。后续应逐步以新文件为准，旧文件可在确认无差异后归档。
+
+#### 5.2.3 新建业务数据库与 FDW
+
+| 文件 | 用途 |
+|------|------|
+| `db/zqyy_app/schemas/init.sql` | 业务应用数据库 DDL：users、roles、user_roles、permissions、role_permissions、tasks、approvals（7 张表，均含 site_id） |
+| `db/fdw/setup_fdw.sql` | postgres_fdw 配置：zqyy_app 只读映射 etl_feiqiu.app schema |
+
+#### 5.2.4 测试数据库脚本
+
+| 文件 | 用途 |
+|------|------|
+| `db/etl_feiqiu/scripts/create_test_db.sql` | 创建 test_etl_feiqiu 数据库，结构与 etl_feiqiu 一致 |
+| `db/zqyy_app/scripts/create_test_db.sql` | 创建 test_zqyy_app 数据库，结构与 zqyy_app 一致 |
+| `db/scripts/migrate_test_data.sql` | 从旧 LLZQ-test 数据库迁移测试数据到新结构 |
+
+#### 5.2.5 重要说明：DDL 与实际数据库的关系
+
+本次迁移仅处理了 DDL 文件的组织和新建，**未对远程 PostgreSQL 实例执行任何 DDL 变更**。即：
+- 远程数据库仍使用旧的 schema 名称（`billiards_ods`、`billiards_dwd`、`billiards_dws`、`etl_admin`）
+- 新的六层 DDL（meta/ods/dwd/core/dws/app）是目标架构的设计文件
+- `zqyy_app` 数据库和 FDW 配置尚未在远程实例上创建
+- 实际的 schema 重命名/迁移需要后续单独执行（建议通过迁移脚本逐步推进）
+
+### 5.3 Steering 文件更新
+
+所有 `.kiro/steering/` 文件已更新为 Monorepo 视角：
+- 路径引用从 `FQ-ETL` 改为 `NeoZQYY` 下的对应路径
+- 模块边界描述更新为新的目录结构
+- 技术栈描述增加 uv workspace、FastAPI、共享包等
+
+### 5.4 验证策略
+
+采用多层验证：
+1. 属性测试（hypothesis）— 11 个 Property 覆盖结构、配置、Schema、RLS 等
+2. ETL 单元测试 — 521 passed / 0 failed / 2 skipped
+3. uv sync — 成功解析 21 个包
+4. 多个检查点（Task 2/4/7/11/13）逐步验证
+
+## 6. 最终验证结果
+
+| 验证项 | 结果 |
+|--------|------|
+| 目录结构（11 个一级目录） | ✅ 全部存在 |
+| README 文件（12 个） | ✅ 全部存在 |
+| DDL 文件（8 个） | ✅ 全部存在 |
+| pyproject.toml（5 个） | ✅ 全部存在 |
+| 配置文件（.env.template/.gitignore/.kiroignore） | ✅ 全部存在 |
+| 共享包模块（4 个） | ✅ 全部存在 |
+| FastAPI 骨架（7 个文件） | ✅ 全部存在 |
+| Steering 文件（无旧路径引用） | ✅ 通过 |
+| Kiro hooks/agents/skills/scripts | ✅ 已复制 |
+| uv sync | ✅ 21 包解析成功 |
+| ETL 单元测试 | ✅ 521 passed / 2 skipped |
+| 属性测试 | ✅ 19/20 passed（1 个内容漂移，非阻塞） |
+
+### 已知问题
+
+- `test_property_file_migration.py` 中 `test_source_and_target_file_content_identical` 对 `tests/unit/test_audit_run.py` 报告内容不一致 — 这是因为源仓库在迁移后继续开发导致的正常漂移，不影响 Monorepo 功能。
+
+## 7. 后续开发指南
+
+### 7.1 日常开发
+
+```bash
+# 安装依赖
+cd C:\NeoZQYY
+uv sync
+
+# ETL 开发
+cd apps/etl/pipelines/feiqiu
+python -m cli.main --dry-run --tasks DWD_LOAD_FROM_ODS
+
+# 后端开发
+cd apps/backend
+uvicorn app.main:app --reload
+
+# 运行 ETL 单元测试
+cd apps/etl/pipelines/feiqiu
+pytest tests/unit
+
+# 运行属性测试
+cd C:\NeoZQYY
+pytest tests/ -v
+```
+
+### 7.2 新增 ETL 任务
+
+1. 在 `apps/etl/pipelines/feiqiu/tasks/` 下创建任务文件
+2. 继承 `BaseTask`，实现 Extract/Transform/Load
+3. 在 `orchestration/task_registry.py` 注册
+4. 在 `tests/unit/` 下编写单元测试
+
+### 7.3 数据库变更
+
+- DDL 变更在 `db/etl_feiqiu/schemas/` 对应的 Schema 文件中修改
+- 新增迁移脚本放在 `db/etl_feiqiu/migrations/`，使用日期前缀命名
+- 变更触发审计（governance.md 规则），需运行 `/audit`
+- 同步更新 `docs/database/` 下的表结构文档
+
+### 7.4 共享包开发
+
+- 在 `packages/shared/src/neozqyy_shared/` 下添加模块
+- 其他子项目通过 `neozqyy-shared` workspace 引用自动获取更新
+- 运行 `uv sync` 刷新依赖
+
+### 7.5 审计与治理
+
+- 高风险路径变更自动触发审计提醒（hooks）
+- 手动运行 `/audit` 生成审计产物
+- 审计记录存放在 `docs/audit/changes/`
+
+## 8. 配置体系
+
+分层叠加优先级（低→高）：
+1. 根 `.env`（公共默认值）
+2. 应用 `.env.local`（私有覆盖）
+3. 环境变量
+4. CLI 参数
+
+敏感值（DSN、API Token）放在 `.env` / `.env.local` 中，禁止提交。`.env.template` 提供配置项模板。
+
+## 9. 多门店隔离架构
+
+- 所有业务表包含 `site_id` 字段
+- `app` schema 视图启用 Row Level Security（RLS）
+- RLS 策略通过 `current_setting('app.current_site_id')` 会话变量过滤
+- `zqyy_app` 通过 FDW 只读访问 `etl_feiqiu.app` schema
+- Property 10/11 属性测试验证 site_id 存在性和 RLS 隔离正确性
+
+## 10. Kiro 配置体系（`.kiro/` 目录）
+
+本节详细介绍 `.kiro/` 目录下的所有配置，便于在 NeoZQYY 中进行相应调整。
+
+### 10.1 目录结构
+
+```
+.kiro/
+├── steering/           # Steering 文件（Agent 上下文注入）
+├── hooks/              # Agent Hooks（事件驱动自动化）
+├── scripts/            # Hook 调用的 PowerShell 脚本
+├── agents/             # 自定义子代理定义
+├── skills/             # 可复用技能包
+├── specs/              # Spec 文件（需求→设计→任务）
+├── settings/           # Kiro 设置（MCP 等）
+├── .audit_state.json   # 审计状态（运行时生成）
+└── .last_prompt_id.json # 最近 Prompt ID（运行时生成）
+```
+
+### 10.2 Steering 文件（`.kiro/steering/`）
+
+Steering 文件在 Agent 对话时自动或按需注入上下文，让 AI 理解项目背景和约束。
+
+| 文件 | 加载方式 | 用途 |
+|------|----------|------|
+| `product.md` | 自动（always） | 产品概述：功能模块、业务上下文、核心实体、主要入口 |
+| `tech.md` | 自动（always） | 技术栈：依赖、数据库架构、测试框架、常用命令、配置体系 |
+| `structure-lite.md` | 自动（always） | 项目结构摘要：顶层目录、模块边界、高风险路径、架构要点 |
+| `structure.md` | 自动（auto） | 完整目录树 + 架构模式（仅大型重构/跨子系统变更时加载） |
+| `governance.md` | 自动（always） | 治理规则：何时必须审计、执行方式、审计产物 |
+| `language-zh.md` | 自动（always） | 语言规范：输出简体中文、UTF-8 编码、注释规则 |
+| `db-docs.md` | 条件（fileMatch） | 数据库文档规则：当编辑 `*.sql`/`*schema*`/`*migration*` 文件时自动注入 |
+| `steering-readme-maintainer.md` | 手动（manual） | 变更影响审查快速参考清单（可通过 `#` 上下文键加载） |
+
+加载方式说明：
+- `always`：每次对话自动注入
+- `auto`：满足 front-matter 中 `inclusion: auto` 条件时注入（如 `structure.md` 标记为 `name: structure-full`，需手动通过 `#` 引用）
+- `fileMatch`：当读取匹配 `fileMatchPattern` 的文件时自动注入
+- `manual`：仅当用户通过 `#` 上下文键显式引用时注入
+
+### 10.3 Hooks（`.kiro/hooks/`）
+
+Hooks 是事件驱动的自动化机制，在特定 IDE 事件发生时触发 Agent 动作或 Shell 命令。
+
+#### 10.3.1 已启用的 Hooks
+
+| Hook | 事件 | 动作类型 | 功能 |
+|------|------|----------|------|
+| `audit-flagger` | promptSubmit | runCommand | 每次提交 prompt 时，基于 `git status` 判断是否存在高风险改动，写入 `.kiro/.audit_state.json` |
+| `audit-reminder` | agentStop | runCommand | Agent 执行结束时，若存在待审计改动且距上次提醒超过 15 分钟，通过 stderr 输出提醒 |
+| `prompt-audit-log` | promptSubmit | runCommand | 每次提交 prompt 时，在 `docs/audit/prompt_logs/` 生成独立日志文件（按时间戳命名） |
+| `run-audit-writer` | userTriggered | askAgent | 手动触发 `/audit`：启动 audit-writer 子代理执行变更审计+文档同步+审计落盘 |
+| `db-docs-sync` | userTriggered | askAgent | 手动触发：对比 Postgres 实际 schema 与 `docs/database/` 文档，自动补全或更新 |
+
+#### 10.3.2 已禁用的 Hooks（保留备用）
+
+| Hook | 事件 | 功能 | 禁用原因 |
+|------|------|------|----------|
+| `change-impact-review` | agentStop | 每次 Agent 结束后自动执行变更影响审查+审计落盘 | 改为手动 `/audit` 子代理流程，避免上下文膨胀 |
+| `db-schema-doc-enforcer` | fileEdited（`*.sql` 等） | 保存 DB 相关文件时自动更新 `docs/database/` | 由 `/audit` 流程统一处理 |
+
+#### 10.3.3 审计流程工作原理
+
+```
+用户提交 Prompt
+    ↓
+[audit-flagger] 扫描 git status → 写入 .audit_state.json（标记是否需要审计）
+[prompt-audit-log] 记录 Prompt 到 docs/audit/prompt_logs/
+    ↓
+Agent 执行用户请求
+    ↓
+Agent 结束
+    ↓
+[audit-reminder] 检查 .audit_state.json → 若需审计且超过 15 分钟限频 → stderr 提醒
+    ↓
+用户手动点击 "Run /audit"
+    ↓
+[run-audit-writer] 启动 audit-writer 子代理 → 执行审计收口
+```
+
+### 10.4 Scripts（`.kiro/scripts/`）
+
+Hook 调用的 PowerShell 脚本，均使用 `Asia/Shanghai` 时区（Taipei Standard Time）。
+
+| 脚本 | 调用者 | 功能 |
+|------|--------|------|
+| `audit_flagger.ps1` | audit-flagger hook | 扫描 `git status`，匹配高风险路径（api/cli/config/database/loaders/models/orchestration/scd/tasks/utils/根文件/SQL），写入审计状态 |
+| `audit_reminder.ps1` | audit-reminder hook | 读取审计状态，15 分钟限频提醒，工作树干净时自动清除状态 |
+| `prompt_audit_log.ps1` | prompt-audit-log hook | 读取 `$env:USER_PROMPT`，生成带时间戳的 Prompt 日志文件，更新 `.last_prompt_id.json` |
+
+**NeoZQYY 迁移注意**：这些脚本中的高风险路径匹配规则（如 `^api/`、`^database/`）基于旧仓库的根目录结构。迁移到 NeoZQYY 后，ETL 代码位于 `apps/etl/pipelines/feiqiu/` 下，需要更新路径匹配规则以适配新结构。同时 hook 文件中的 `workspaceFolderName` 字段值为 `"FQ-ETL"`，需改为 NeoZQYY 对应的工作区名称。
+
+### 10.5 Agents（`.kiro/agents/`）
+
+自定义子代理，通过 `invokeSubAgent` 工具调用。
+
+| 代理 | 用途 |
+|------|------|
+| `audit-writer` | 审计收口子代理：基于 `git status/diff` 和 Prompt 日志执行变更影响审查，按需调用 3 个 skill（steering-readme-maintainer、change-annotation-audit、bd-manual-db-docs），生成审计产物，完成后清除审计状态并刷新审计一览表 |
+
+audit-writer 的输出被严格限制为"极短回执"（done/files_written/next_step），避免审计细节淹没主对话上下文。
+
+### 10.6 Skills（`.kiro/skills/`）
+
+可复用的技能包，由 Agent 或子代理按需调用。每个 skill 包含 `SKILL.md`（定义）和 `assets/`（模板）。
+
+| Skill | 触发条件 | 产物 |
+|-------|----------|------|
+| `steering-readme-maintainer` | 业务/ETL/API/鉴权/小程序交互等逻辑改动 | 同步更新 product.md/tech.md/structure-lite.md/README.md；输出审计摘要 |
+| `change-annotation-audit` | 任何实质性代码/文档修改 | `docs/audit/changes/<日期>__<slug>.md` 审计记录；每个被改文件内 `AI_CHANGELOG` 条目；逻辑变更处 `CHANGE` 标记注释 |
+| `bd-manual-db-docs` | DB schema/表结构变更 | `docs/database/` 下的变更日志、表结构文档更新、回滚策略、验证 SQL |
+
+### 10.7 Specs（`.kiro/specs/`）
+
+Spec 是结构化的功能开发文档，包含需求（requirements.md）→ 设计（design.md）→ 任务（tasks.md）三阶段。
+
+| Spec | 状态 | 用途 |
+|------|------|------|
+| `monorepo-migration` | 已完成 | 本次 Monorepo 迁移的完整需求（15 个需求，涵盖骨架搭建、文件平移、DB 重组、测试等） |
+| `repo-audit` | 已完成 | 仓库治理只读审计：文件清单、流程树、文档对齐报告 |
+| `scheduler-refactor` | 规划中 | ETL 调度器重构：拆分为 CLI→PipelineRunner→TaskExecutor 三层架构 |
+| `etl-task-documentation` | 已完成 | ETL 任务说明文档：覆盖 ODS/DWD/DWS/INDEX 四层所有任务 |
+| `docs-optimization` | 已完成 | 文档体系整理：覆盖度评估、审计一览表、业务规则目录 |
+| `bd-manual-docs-consolidation` | 已完成 | 数据库文档整理：目录规范化、DDL 对比同步、ODS 表级文档、字段映射 |
+
+### 10.8 Settings（`.kiro/settings/`）
+
+| 文件 | 用途 |
+|------|------|
+| `mcp.json` | MCP（Model Context Protocol）服务器配置。当前为空（`{}`），可按需添加 MCP 服务器 |
+
+### 10.9 运行时状态文件
+
+| 文件 | 用途 | 生成者 |
+|------|------|--------|
+| `.audit_state.json` | 审计状态：是否需要审计、原因、变更文件列表、指纹、上次提醒时间 | `audit_flagger.ps1` |
+| `.last_prompt_id.json` | 最近一次 Prompt 的 ID 和时间戳，供 audit-writer 溯源 | `prompt_audit_log.ps1` |
+
+### 10.10 NeoZQYY 迁移适配清单
+
+从旧仓库迁移到 NeoZQYY 后，以下 `.kiro/` 配置需要调整：
+
+1. **Hook 文件中的 `workspaceFolderName`**：所有 hook 的 `workspaceFolderName` 值为 `"FQ-ETL"`，需改为新工作区名称
+2. **audit_flagger.ps1 中的高风险路径**：当前匹配 `^api/`、`^database/` 等根级路径，ETL 代码已移至 `apps/etl/pipelines/feiqiu/` 下，需更新为新路径（如 `^apps/etl/pipelines/feiqiu/api/`），同时增加 `^apps/backend/`、`^packages/shared/`、`^db/` 等新高风险路径
+3. **audit_reminder.ps1 中的噪声过滤**：当前排除 `^docs/audit/` 和 `^\.kiro/`，可能需要增加 `^tmp/` 等
+4. **Steering 文件路径引用**：已在迁移过程中更新为 NeoZQYY 视角（已完成）
+5. **db-docs.md 的 fileMatchPattern**：当前匹配 `**/migrations/**`、`**/*.sql` 等，在 NeoZQYY 中仍然适用（使用了通配符）
+6. **MCP 配置**：根据需要在 `settings/mcp.json` 中添加 PostgreSQL MCP 服务器等