# 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 服务器等