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

2026-02-19 08:35:13 +08:00
parent ded6dfb9d8
commit 4eac07da47
1387 changed files with 6107191 additions and 33002 deletions
--- a/docs/migrate/.env.old
+++ b/docs/migrate/.env.old
@@ -0,0 +1,221 @@
+# ==============================================================================
+# ETL 系统配置文件
+# ==============================================================================
+# 配置优先级：DEFAULTS < .env < CLI 参数
+# 语法：KEY=VALUE（正斜杠路径，布尔值用 true/false，列表用逗号分隔）
+
+# ------------------------------------------------------------------------------
+# 门店配置
+# ------------------------------------------------------------------------------
+STORE_ID=2790685415443269
+TIMEZONE=Asia/Shanghai
+
+# ------------------------------------------------------------------------------
+# 数据库配置
+# ------------------------------------------------------------------------------
+# 完整 DSN（优先使用，设置后忽略下面的分离式配置）
+PG_DSN=postgresql://local-Python:Neo-local-1991125@100.64.0.4:5432/LLZQ-test
+
+# 分离式配置（不使用 DSN 时启用）
+# PG_HOST=localhost
+# PG_PORT=5432
+# PG_NAME=your_database
+# PG_USER=your_user
+# PG_PASSWORD=your_password
+
+# 连接超时（秒，默认 20）
+PG_CONNECT_TIMEOUT=10
+
+# ------------------------------------------------------------------------------
+# 数据库 Schema 配置
+# ------------------------------------------------------------------------------
+# OLTP 业务数据 schema（默认 billiards）
+SCHEMA_OLTP=billiards
+
+# ETL 管理数据 schema（默认 etl_admin）
+SCHEMA_ETL=etl_admin
+
+# ------------------------------------------------------------------------------
+# API 配置
+# ------------------------------------------------------------------------------
+API_BASE=https://pc.ficoo.vip/apiprod/admin/v1/
+API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnQtdHlwZSI6IjQiLCJ1c2VyLXR5cGUiOiIxIiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW50aXR5L2NsYWltcy9yb2xlIjoiMTIiLCJyb2xlLWlkIjoiMTIiLCJ0ZW5hbnQtaWQiOiIyNzkwNjgzMTYwNzA5OTU3Iiwibmlja25hbWUiOiLnp5_miLfnrqHnkIblkZjvvJrmganmgakxIiwic2l0ZS1pZCI6IjAiLCJtb2JpbGUiOiIxMzgxMDUwMjMwNCIsInNpZCI6IjI5NTA0ODk2NTgzOTU4NDUiLCJzdGFmZi1pZCI6IjMwMDk5MTg2OTE1NTkwNDUiLCJvcmctaWQiOiIwIiwicm9sZS10eXBlIjoiMyIsInJlZnJlc2hUb2tlbiI6ImExdEV0VG9kQ0hoeWduelU3Umw0MDJMenFrVTdHS0xTM3h1U3VtNmFHK1E9IiwicmVmcmVzaEV4cGlyeVRpbWUiOiIyMDI2LzIvMjAg5LiK5Y2IMjo1Mzo0MiIsIm5lZWRDaGVja1Rva2VuIjoiZmFsc2UiLCJleHAiOjE3NzE1MjcyMjIsImlzcyI6InRlc3QiLCJhdWQiOiJVc2VyIn0.q4PikSEXoLfhuRmW_X1H3ykE0DCmQiVsLwwF_ZHoI3M
+
+# API 请求超时（秒，默认 20）
+API_TIMEOUT=20
+
+# 分页大小（默认 200）
+API_PAGE_SIZE=200
+
+# 最大重试次数（默认 3）
+API_RETRY_MAX=3
+
+# 重试退避时间（JSON 数组格式，单位秒，默认 [1, 2, 4]）
+# API_RETRY_BACKOFF=[1, 2, 4]
+
+# 额外请求参数（JSON 对象格式）
+# API_PARAMS={}
+
+# ------------------------------------------------------------------------------
+# 路径配置
+# ------------------------------------------------------------------------------
+# JSON 导出根目录
+EXPORT_ROOT=C:/ZQYY/export/ETL/JSON
+
+# 日志输出根目录
+LOG_ROOT=C:/ZQYY/export/ETL/LOG
+
+# 在线抓取 JSON 输出根目录（FETCH_ONLY 模式使用）
+FETCH_ROOT=C:/ZQYY/export/ETL/JSON
+
+# 本地清洗入库时的 JSON 输入目录（INGEST_ONLY 模式使用，为空则默认使用本次抓取目录）
+# INGEST_SOURCE_DIR=
+
+# manifest 文件名（默认 manifest.json）
+# MANIFEST_NAME=manifest.json
+
+# 入库报告文件名（默认 ingest_report.json）
+# INGEST_REPORT_NAME=ingest_report.json
+
+# 是否格式化输出 JSON（默认 true）
+WRITE_PRETTY_JSON=true
+
+# ------------------------------------------------------------------------------
+# 管线流程配置
+# ------------------------------------------------------------------------------
+# 运行流程：FULL（抓取+入库）、FETCH_ONLY（仅抓取落盘）、INGEST_ONLY（仅本地入库）
+PIPELINE_FLOW=FULL
+
+# ------------------------------------------------------------------------------
+# 时间窗口配置
+# ------------------------------------------------------------------------------
+# 窗口重叠秒数（默认 600，即 10 分钟）
+OVERLAP_SECONDS=600
+
+# 繁忙时段窗口分钟数（默认 30）
+WINDOW_BUSY_MIN=30
+
+# 空闲时段窗口分钟数（默认 180）
+WINDOW_IDLE_MIN=180
+
+# 空闲时段起止时间（默认 04:00 ~ 16:00）
+IDLE_START=04:00
+IDLE_END=16:00
+
+# 窗口切分单位（默认 day）
+WINDOW_SPLIT_UNIT=day
+
+# 窗口切分天数（默认 10）
+WINDOW_SPLIT_DAYS=10
+
+# 窗口补偿小时数（默认 2）
+WINDOW_COMPENSATION_HOURS=2
+
+# 空结果是否推进游标（默认 true）
+ALLOW_EMPTY_RESULT_ADVANCE=true
+
+# ------------------------------------------------------------------------------
+# 快照配置
+# ------------------------------------------------------------------------------
+# 快照缺失时是否删除（默认 true）
+SNAPSHOT_MISSING_DELETE=true
+
+# 快照为空时是否允许删除（默认 false）
+SNAPSHOT_ALLOW_EMPTY_DELETE=false
+
+# ------------------------------------------------------------------------------
+# 数据完整性检查配置
+# ------------------------------------------------------------------------------
+# 检查模式：history（历史区间）/ latest（最近一次）
+INTEGRITY_MODE=history
+
+# 历史检查起始日期
+INTEGRITY_HISTORY_START=2025-07-01
+
+# 历史检查结束日期（为空则到当天）
+# INTEGRITY_HISTORY_END=
+
+# 是否包含维度表（默认 true）
+INTEGRITY_INCLUDE_DIMENSIONS=true
+
+# 是否自动触发检查（默认 false）
+INTEGRITY_AUTO_CHECK=false
+
+# 是否自动回填缺失数据（默认 false）
+INTEGRITY_AUTO_BACKFILL=false
+
+# 是否比较内容（默认 true）
+INTEGRITY_COMPARE_CONTENT=true
+
+# 内容比较采样上限（默认 50）
+INTEGRITY_CONTENT_SAMPLE_LIMIT=50
+
+# 内容不一致时是否回填（默认 true）
+INTEGRITY_BACKFILL_MISMATCH=true
+
+# 回填后是否重新检查（默认 true）
+INTEGRITY_RECHECK_AFTER_BACKFILL=true
+
+# 指定 ODS 任务代码（逗号分隔，为空则全部）
+# INTEGRITY_ODS_TASK_CODES=
+
+# 是否强制按月切分（默认 true）
+# INTEGRITY_FORCE_MONTHLY_SPLIT=true
+
+# ------------------------------------------------------------------------------
+# 校验配置
+# ------------------------------------------------------------------------------
+# 抓取后校验时是否跳过 ODS 重载（默认 true）
+VERIFY_SKIP_ODS_ON_FETCH=true
+
+# 校验时是否使用本地 JSON（默认 true）
+VERIFY_ODS_LOCAL_JSON=true
+
+# ------------------------------------------------------------------------------
+# DWD 层配置
+# ------------------------------------------------------------------------------
+# 事实表是否使用 UPSERT（默认 true）
+DWD_FACT_UPSERT=true
+
+# ------------------------------------------------------------------------------
+# 任务列表配置
+# ------------------------------------------------------------------------------
+# ODS 抓取任务列表（逗号分隔）
+RUN_TASKS=PRODUCTS,TABLES,MEMBERS,ASSISTANTS,PACKAGES_DEF,ORDERS,PAYMENTS,REFUNDS,COUPON_USAGE,INVENTORY_CHANGE,TOPUPS,TABLE_DISCOUNT,ASSISTANT_ABOLISH,LEDGER
+
+# DWS 汇总任务列表（逗号分隔，为空则不执行）
+# RUN_DWS_TASKS=
+
+# 指数计算任务列表（逗号分隔，为空则不执行）
+# RUN_INDEX_TASKS=
+
+# 指数回溯天数（默认 60）
+INDEX_LOOKBACK_DAYS=60
+
+# ------------------------------------------------------------------------------
+# DWS 月度/薪资配置
+# ------------------------------------------------------------------------------
+# 新人封顶生效日期（默认 2026-03-01）
+# DWS_MONTHLY_NEW_HIRE_CAP_EFFECTIVE_FROM=2026-03-01
+
+# 新人封顶天数（默认 25）
+# DWS_MONTHLY_NEW_HIRE_CAP_DAY=25
+
+# 新人最高等级（默认 2）
+# DWS_MONTHLY_NEW_HIRE_MAX_TIER_LEVEL=2
+
+# 薪资计算运行天数（默认 5）
+# DWS_SALARY_RUN_DAYS=5
+
+# 是否允许非周期内运行（默认 false）
+# DWS_SALARY_ALLOW_OUT_OF_CYCLE=false
+
+# 包房课单价（默认 138）
+# DWS_SALARY_ROOM_COURSE_PRICE=138
+
+# ------------------------------------------------------------------------------
+# ODS 离线回放配置（仅开发/运维使用）
+# ------------------------------------------------------------------------------
+# ODS_JSON_DOC_DIR=export/test-json-doc
+# ODS_INCLUDE_FILES=
+# ODS_DROP_SCHEMA_FIRST=true
--- a/docs/migrate/monorepo-migration-summary.md
+++ b/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 服务器等
--- a/docs/migrate/oldworkspace-kiro-agent-config-summary.md
+++ b/docs/migrate/oldworkspace-kiro-agent-config-summary.md
@@ -0,0 +1,374 @@
+# Kiro Agent 配置总览
+
+> 生成日期：2026-02-15 | 适用仓库：NeoZQYY Monorepo
+
+本文档完整记录当前 `.kiro/` 目录下所有 Agent 相关配置（Hooks、Steering、Skills、MCP、自定义 Agent），说明各组件的作用、协作关系，以及为节省上下文开支所做的优化设计。
+
+---
+
+## 目录
+
+1. [整体架构概览](#1-整体架构概览)
+2. [Hooks（事件钩子）](#2-hooks事件钩子)
+3. [Steering（引导文件）](#3-steering引导文件)
+4. [Skills（技能）](#4-skills技能)
+5. [自定义 Agent（子代理）](#5-自定义-agent子代理)
+6. [MCP（Model Context Protocol）](#6-mcpmodel-context-protocol)
+7. [辅助脚本](#7-辅助脚本)
+8. [上下文优化策略](#8-上下文优化策略)
+9. [组件协作流程图](#9-组件协作流程图)
+
+---
+
+## 1. 整体架构概览
+
+```
+用户 Prompt
+  │
+  ├─→ [promptSubmit] audit-flagger.ps1    ← 判定是否高风险（写 .audit_state.json）
+  ├─→ [promptSubmit] prompt_audit_log.ps1 ← 记录 Prompt-ID + 原文到独立日志文件
+  │
+  ▼
+Kiro 主对话（Agent 执行）
+  │  ← Steering 文件注入上下文（always / fileMatch / manual 三种模式）
+  │  ← Skills 按需激活（由 Agent 或 /audit 子代理调用）
+  │  ← MCP 工具按需调用（Postgres / Git / Filesystem / Playwright / OpenAPI）
+  │
+  ▼
+[agentStop] audit-reminder.ps1
+  │  ← 检查 .audit_state.json，若有待审计则提醒（15 分钟限频）
+  │
+  ▼
+用户手动触发 /audit
+  │
+  ▼
+audit-writer 子代理（独立执行）
+  ├─→ 调用 Skills：change-annotation-audit / steering-readme-maintainer / bd-manual-db-docs
+  ├─→ 写审计产物（docs/audit/changes/、AI_CHANGELOG、CHANGE 注释、docs/database/）
+  ├─→ 刷新审计一览表（gen_audit_dashboard.py）
+  └─→ 清除 .audit_state.json 待审计标记
+```
+
+核心设计理念：**主对话专注编码，审计写入卸载到子代理**，避免重型文档操作膨胀主对话上下文。
+
+---
+
+## 2. Hooks（事件钩子）
+
+共 7 个 Hook，位于 `.kiro/hooks/`。按启用状态分为两组：
+
+### 2.1 已启用（4 个 runCommand + 1 个 askAgent）
+
+| Hook 文件 | 事件类型 | 动作类型 | 功能说明 |
+|---|---|---|---|
+| `audit-flagger.kiro.hook` | `promptSubmit` | `runCommand` | 每次提交 prompt 时运行 `audit_flagger.ps1`，基于 `git status` 判定是否存在高风险改动，结果写入 `.kiro/.audit_state.json`。不触发 LLM。 |
+| `prompt-audit-log.kiro.hook` | `promptSubmit` | `runCommand` | 每次提交 prompt 时运行 `prompt_audit_log.ps1`，在 `docs/audit/prompt_logs/` 生成独立日志文件（含 Prompt-ID、时间戳、原文），同时更新 `.kiro/.last_prompt_id.json`。不触发 LLM。 |
+| `audit-reminder.kiro.hook` | `agentStop` | `runCommand` | Agent 执行结束时运行 `audit_reminder.ps1`，若检测到待审计状态则通过 stderr 提醒用户运行 `/audit`。15 分钟限频，避免频繁打扰。 |
+| `run-audit-writer.kiro.hook` | `userTriggered` | `askAgent` | 用户手动触发（`/audit`），启动 `audit-writer` 子代理执行完整审计流程：变更影响审查 → 文档同步 → 审计落盘 → 刷新一览表 → 清除待审计标记。仅返回极短回执。 |
+| `db-docs-sync.kiro.hook` | `userTriggered` | `askAgent` | 用户按需触发，对比 Postgres 实际 schema 与 `docs/database/` 文档，自动补全或更新缺失/过时的表结构说明。 |
+
+### 2.2 已禁用（2 个 askAgent）
+
+| Hook 文件 | 事件类型 | 禁用原因 |
+|---|---|---|
+| `change-impact-review.kiro.hook` | `agentStop` | 原设计为每次 agentStop 自动执行变更影响审查 + 审计落盘。因上下文膨胀严重，已改为手动 `/audit` 子代理流程替代。 |
+| `db-schema-doc-enforcer.kiro.hook` | `fileEdited`（`*.sql` 等） | 原设计为保存 SQL 文件时自动更新 DB 文档。因频繁触发导致上下文浪费，已改由 `/audit` 流程统一处理。 |
+
+### 2.3 设计要点
+
+- **promptSubmit 钩子全部使用 `runCommand`**（纯 Shell），不消耗 LLM token
+- **agentStop 提醒也是 `runCommand`**，仅通过 stderr 输出一行文字
+- **重型 askAgent 操作全部改为 `userTriggered`**，由用户主动决定何时执行
+- 两个曾经自动触发的 askAgent Hook 已禁用，避免每次交互都产生大量审计写入
+
+---
+
+## 3. Steering（引导文件）
+
+共 8 个文件，位于 `.kiro/steering/`。通过 front-matter 中的 `inclusion` 字段控制注入时机：
+
+### 3.1 始终注入（`inclusion: always`）— 5 个
+
+| 文件 | 内容摘要 | Token 开销 |
+|---|---|---|
+| `governance.md` | 审计治理规则：何时必须审计、执行方式（自动判定 + 半自动执行）、审计产物清单 | 小 |
+| `language-zh.md` | 语言规范：输出简体中文、UTF-8 编码、注释只写"为什么" | 极小 |
+| `product.md` | 产品概述：ETL/后端/小程序/GUI 功能、业务上下文、主要入口 | 中 |
+| `structure-lite.md` | 项目结构精简版：顶层目录 + 关键模块边界 + 架构要点摘要 | 中 |
+| `tech.md` | 技术栈：依赖、数据库、测试、常用命令、配置体系 | 中 |
+
+### 3.2 条件注入（`inclusion: fileMatch`）— 1 个
+
+| 文件 | 匹配模式 | 内容摘要 |
+|---|---|---|
+| `db-docs.md` | `**/migrations/**`, `**/*.sql`, `**/*schema*.*`, `**/*ddl*.*`, `**/*.prisma` | 数据库文档规则：变更时必须同步 `docs/database/`，含最低文档要求 |
+
+### 3.3 手动加载（`inclusion: manual`）— 1 个
+
+| 文件 | 内容摘要 |
+|---|---|
+| `steering-readme-maintainer.md` | 变更影响审查快速清单（作为 `/slash command` 参考），详细流程指向同名 Skill |
+
+### 3.4 按需自动加载（`inclusion: auto`）— 1 个
+
+| 文件 | 名称 | 内容摘要 |
+|---|---|---|
+| `structure.md` | `structure-full` | 完整目录树 + 架构模式详解。仅在大型重构、模块迁移或跨子系统变更时加载 |
+
+### 3.5 设计要点
+
+- **`structure-lite.md`（always）vs `structure.md`（auto）**：日常对话只注入精简版（~50 行），完整目录树（~120 行）仅在需要时手动加载，节省约 60% 的结构信息 token
+- **`db-docs.md` 使用 fileMatch**：只有当上下文中出现 SQL/迁移文件时才注入，避免无关对话浪费 token
+- **`steering-readme-maintainer.md` 使用 manual**：作为快速参考，不自动注入
+
+---
+
+## 4. Skills（技能）
+
+共 3 个 Skill，位于 `.kiro/skills/`。每个 Skill 包含 `SKILL.md`（定义）和 `assets/`（模板）。
+
+### 4.1 change-annotation-audit（变更标注与审计）
+
+- **触发条件**：任何实质性代码/文档修改（特别是逻辑、资金、接口、DB 改动）
+- **产出**：
+  - `docs/audit/changes/<YYYY-MM-DD>__<slug>.md`（审计记录）
+  - 每个被改文件内的 `AI_CHANGELOG` 条目
+  - 每处逻辑变更附近的 `CHANGE` 标记注释（含 intent、assumptions、边界条件）
+- **模板**：`audit-record-template.md`、`file-changelog-templates.md`
+
+### 4.2 steering-readme-maintainer（文档同步审查）
+
+- **触发条件**：业务规则/ETL/API/鉴权/小程序交互等逻辑改动
+- **产出**：
+  - 评估并更新 `product.md` / `tech.md` / `structure-lite.md` / `structure.md` / `README.md`
+  - 输出审计友好摘要（Changed / Why / Risk / Verify）
+- **模板**：`steering-update-checklist.md`
+
+### 4.3 bd-manual-db-docs（数据库文档维护）
+
+- **触发条件**：DDL/迁移脚本修改（表/字段/类型/约束/索引/外键变更）
+- **产出**：
+  - `docs/database/` 下的 Schema Change Log（变更日志）
+  - Table Structure Doc（表结构文档更新）
+  - Rollback & Verification（回滚要点 + ≥3 条验证 SQL）
+- **模板**：`schema-changelog-template.md`、`table-structure-template.md`
+
+### 4.4 设计要点
+
+- Skills 不会自动注入上下文，仅在被 Agent 或子代理显式调用时激活
+- 三个 Skill 形成完整的审计闭环：**代码标注** + **文档同步** + **DB 文档**
+- 主对话中不直接调用 Skill，而是由 `audit-writer` 子代理统一调度
+
+---
+
+## 5. 自定义 Agent（子代理）
+
+### 5.1 audit-writer
+
+- **位置**：`.kiro/agents/audit-writer.md`
+- **工具权限**：`read`、`write`、`shell`
+- **职责**：专职"审计收口/后处理写入"，不依赖主对话上下文
+- **输入来源**：
+  - `git status --porcelain` + `git diff`（本次未提交变更）
+  - `.kiro/.last_prompt_id.json`（最新 Prompt-ID）
+  - `docs/audit/prompt_logs/`（prompt 原文，用于溯源）
+- **执行策略**：
+  1. 判断是否逻辑改动
+  2. 按需调用三个 Skill
+  3. 清除 `.kiro/.audit_state.json` 待审计标记
+  4. 运行 `scripts/gen_audit_dashboard.py` 刷新审计一览表
+- **输出约束**：强制极短回执（done / files_written / next_step），避免审计细节淹没主对话
+
+---
+
+## 6. MCP（Model Context Protocol）
+
+### 6.1 工作区级配置
+
+文件：`.kiro/settings/mcp.json`
+
+```json
+{ "mcpServers": {} }
+```
+
+工作区级未定义任何 MCP 服务器（全部在用户级配置）。
+
+### 6.2 用户级配置（全局）
+
+文件：`~/.kiro/settings/mcp.json`
+
+| 服务器名 | 命令 | 用途 | 状态 | 自动批准 |
+|---|---|---|---|---|
+| `filesystem` | `npx @modelcontextprotocol/server-filesystem` | 文件系统读写（作用域：`C:\NeoZQYY`） | 启用 | 全部 |
+| `git` | `uvx mcp-server-git@2025.12.18` | Git 操作（status/diff/commit/log 等） | 启用 | `git_status` |
+| `postgres` | `uvx postgres-mcp --access-mode=unrestricted` | PostgreSQL 数据库操作（查询/DDL/健康检查/索引分析） | 启用 | 全部 |
+| `playwright` | `npx @playwright/mcp@latest` | 浏览器自动化（截图/快照/点击/表单填写） | 启用 | 无 |
+| `openapi` | `uv tool run awslabs.openapi-mcp-server` | OpenAPI 规范交互（基于 `backend-api.json`） | 启用 | 全部 |
+| `trivy` | `trivy mcp` | 安全漏洞扫描 | 禁用 | — |
+
+### 6.3 设计要点
+
+- MCP 配置放在用户级而非工作区级，方便跨项目复用
+- `postgres` 使用 `unrestricted` 模式，支持 DDL 和数据操作（配合审计流程保障安全）
+- `git` 仅自动批准 `git_status`，其他操作需确认
+- `trivy` 当前禁用，预留安全扫描能力
+
+---
+
+## 7. 辅助脚本
+
+位于 `.kiro/scripts/`，全部为 PowerShell 脚本，由 Hook 的 `runCommand` 调用。
+
+| 脚本 | 调用者 | 功能 |
+|---|---|---|
+| `audit_flagger.ps1` | `audit-flagger` Hook | 解析 `git status`，匹配高风险路径（`api/`、`cli/`、`config/`、`database/`、`loaders/` 等），计算变更指纹（SHA1），写入 `.kiro/.audit_state.json` |
+| `audit_reminder.ps1` | `audit-reminder` Hook | 读取 `.audit_state.json`，若 `audit_required=true` 且距上次提醒 ≥15 分钟，则通过 stderr 输出提醒；工作树干净时自动清除标记 |
+| `prompt_audit_log.ps1` | `prompt-audit-log` Hook | 生成 Prompt-ID（`P<yyyyMMdd-HHmmss>` 格式），将 prompt 原文写入 `docs/audit/prompt_logs/prompt_log_<timestamp>.md`，更新 `.kiro/.last_prompt_id.json` |
+
+### 共同特征
+
+- 所有脚本使用 `Taipei Standard Time`（UTC+8）时区
+- 所有脚本在异常时静默退出（`exit 0`），绝不阻塞 prompt 提交
+- 输出编码统一 UTF-8
+- 过长 prompt（>20000 字符）自动截断，防止展开的 `#context` 污染日志
+
+---
+
+## 8. 上下文优化策略
+
+本项目在 Agent 配置中做了多层上下文节省优化，核心目标是：**在保证审计完整性的前提下，最小化每次对话的 token 消耗**。
+
+### 8.1 审计写入卸载（最大优化）
+
+| 优化前 | 优化后 | 节省效果 |
+|---|---|---|
+| `change-impact-review` Hook 在每次 `agentStop` 自动触发，执行完整审计写入（含文档同步、AI_CHANGELOG、CHANGE 注释、DB 文档） | 改为 `userTriggered` + `audit-writer` 子代理，主对话仅收到极短回执 | 每次交互节省 **数千~上万 token**（审计产物的生成和写入全部在子代理独立上下文中完成） |
+
+### 8.2 Hook 动作类型选择
+
+| 优化点 | 说明 |
+|---|---|
+| promptSubmit 钩子全部用 `runCommand` | 纯 Shell 执行，零 LLM token 消耗 |
+| agentStop 提醒用 `runCommand` | 仅 stderr 一行文字，不触发 Agent 回复 |
+| 禁用两个自动 `askAgent` Hook | `change-impact-review` 和 `db-schema-doc-enforcer` 曾在每次交互/文件保存时触发 Agent，现已禁用 |
+
+### 8.3 Steering 分层注入
+
+| 策略 | 实现 | 节省效果 |
+|---|---|---|
+| 结构信息分级 | `structure-lite.md`（always，~50 行）vs `structure.md`（auto/manual，~120 行） | 日常对话节省约 60% 结构信息 token |
+| DB 规则条件注入 | `db-docs.md` 使用 `fileMatch`，仅在上下文含 SQL 文件时注入 | 非 DB 相关对话零开销 |
+| 审查清单手动加载 | `steering-readme-maintainer.md` 使用 `manual` | 仅在用户主动引用时注入 |
+| always 文件精简化 | `governance.md` 采用 Lite 版本，只保留最小硬约束 | 相比完整版节省约 70% |
+
+### 8.4 Prompt 日志优化
+
+| 优化点 | 说明 |
+|---|---|
+| 独立文件而非追加 | 每次 prompt 写独立文件（`prompt_log_<timestamp>.md`），避免单文件无限增长 |
+| 自动截断 | prompt 超过 20000 字符时截断，防止展开的 `#context` 污染日志 |
+| 不触发 LLM | 日志写入完全由 Shell 脚本完成 |
+
+### 8.5 子代理隔离
+
+| 优化点 | 说明 |
+|---|---|
+| 独立上下文 | `audit-writer` 在独立上下文中执行，不污染主对话 |
+| 自给自足 | 子代理通过 `git status/diff` + `.last_prompt_id.json` 获取信息，不依赖主对话传递 |
+| 极短回执 | 强制只返回 done / files_written / next_step，避免审计细节回流主对话 |
+
+### 8.6 限频机制
+
+| 机制 | 说明 |
+|---|---|
+| 审计提醒 15 分钟限频 | `audit_reminder.ps1` 记录 `last_reminded_at`，避免每次 agentStop 都提醒 |
+| 变更指纹去重 | `audit_flagger.ps1` 计算文件列表 SHA1，相同指纹不重复标记 |
+
+---
+
+## 9. 组件协作流程图
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        用户提交 Prompt                           │
+└──────────┬──────────────────────────────────────────────────────┘
+           │
+           ├──→ [Hook: promptSubmit] audit_flagger.ps1
+           │      └─→ git status → 匹配高风险路径 → 写 .audit_state.json
+           │
+           ├──→ [Hook: promptSubmit] prompt_audit_log.ps1
+           │      └─→ 生成 Prompt-ID → 写 prompt_logs/ + .last_prompt_id.json
+           │
+           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     Kiro 主对话执行                               │
+│                                                                   │
+│  注入 Steering：governance + language-zh + product                │
+│                 + structure-lite + tech                           │
+│                 + db-docs（仅当上下文含 SQL 文件）                  │
+│                                                                   │
+│  可用 MCP：postgres / git / filesystem / playwright / openapi     │
+│                                                                   │
+│  可用 Skills：（通常不在主对话直接调用，由子代理调度）                │
+└──────────┬──────────────────────────────────────────────────────┘
+           │
+           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  [Hook: agentStop] audit_reminder.ps1                            │
+│    └─→ 检查 .audit_state.json                                    │
+│    └─→ 若 audit_required=true 且 ≥15min → stderr 提醒            │
+└──────────┬──────────────────────────────────────────────────────┘
+           │
+           ▼  （用户决定是否手动触发）
+┌─────────────────────────────────────────────────────────────────┐
+│  [Hook: userTriggered] /audit                                    │
+│    └─→ 启动 audit-writer 子代理（独立上下文）                      │
+│         ├─→ git status/diff + .last_prompt_id.json               │
+│         ├─→ Skill: change-annotation-audit                       │
+│         ├─→ Skill: steering-readme-maintainer                    │
+│         ├─→ Skill: bd-manual-db-docs（仅 DB 变更时）              │
+│         ├─→ 写审计产物 → 刷新 dashboard                           │
+│         └─→ 清除 .audit_state.json → 返回极短回执                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 附录：文件清单
+
+```
+.kiro/
+├── agents/
+│   └── audit-writer.md              # 审计子代理定义
+├── hooks/
+│   ├── audit-flagger.kiro.hook      # [启用] promptSubmit → runCommand
+│   ├── audit-reminder.kiro.hook     # [启用] agentStop → runCommand
+│   ├── change-impact-review.kiro.hook # [禁用] agentStop → askAgent
+│   ├── db-docs-sync.kiro.hook       # [启用] userTriggered → askAgent
+│   ├── db-schema-doc-enforcer.kiro.hook # [禁用] fileEdited → askAgent
+│   ├── prompt-audit-log.kiro.hook   # [启用] promptSubmit → runCommand
+│   └── run-audit-writer.kiro.hook   # [启用] userTriggered → askAgent
+├── scripts/
+│   ├── audit_flagger.ps1            # 高风险判定脚本
+│   ├── audit_reminder.ps1           # 审计提醒脚本（15min 限频）
+│   └── prompt_audit_log.ps1         # Prompt 日志记录脚本
+├── settings/
+│   └── mcp.json                     # 工作区 MCP 配置（空）
+├── skills/
+│   ├── bd-manual-db-docs/           # DB 文档维护 Skill
+│   ├── change-annotation-audit/     # 变更标注审计 Skill
+│   └── steering-readme-maintainer/  # 文档同步审查 Skill
+├── steering/
+│   ├── db-docs.md                   # [fileMatch] DB 文档规则
+│   ├── governance.md                # [always] 审计治理
+│   ├── language-zh.md               # [always] 语言规范
+│   ├── product.md                   # [always] 产品概述
+│   ├── steering-readme-maintainer.md # [manual] 审查快速参考
+│   ├── structure-lite.md            # [always] 项目结构精简版
+│   ├── structure.md                 # [auto] 完整目录树
+│   └── tech.md                      # [always] 技术栈
+├── .audit_state.json                # 审计状态（运行时）
+└── .last_prompt_id.json             # 最新 Prompt-ID（运行时）
+
+~/.kiro/settings/mcp.json            # 用户级 MCP 配置（6 个服务器）
+```