---
inclusion: always
---
# 产出物路径规范（强制）

Kiro 所有产出物分两类，各有归档规则，禁止随意散放。

## 一、程序输出（数据文件、日志、报告）

写入 `export/` 目录结构，路径从 `.env` 环境变量读取。禁止硬编码路径，禁止在 `export/` 外创建输出目录。

### 规则
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`（zqyy_app / FDW / RLS） |
| 数据库变更审计（ETL BD 手册） | `apps/etl/.../docs/database/` | 模块专属表级文档、跨层映射 |
| 变更审计记录 | `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/miniprogram-dev/` | 页面开发流程、代理手册、规范参考 |
| 运维手册 | `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`。