507 lines
24 KiB
Markdown
507 lines
24 KiB
Markdown
# 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 服务器等
|