# NeoZQYY 文档地图

> 本文档记录项目中所有文档资产的位置、类型和内容概要，方便快速定位。
> 归档规则见末尾「文档归档规则」章节；程序输出路径规范见 `docs/deployment/EXPORT-PATHS.md`。

---

## 一、根目录

| 文件 | 内容 |
|------|------|
| `README.md` | 项目总览：模块表（含文档链接）、技术栈、快速开始命令 |
| `.env.template` | 环境变量模板，列出所有可配置项及说明 |

---

## 二、项目级文档 `docs/`

### 2.1 文档中心首页

| 文件 | 内容 |
|------|------|
| `docs/README.md` | 项目架构图、模块文档索引、技术栈速览、认证体系概览、四库架构、常用命令 |

### 2.2 数据库变更手册 `docs/database/`

业务库（zqyy_app）相关的 BD 手册。ETL 专属表级文档已迁移至 `apps/etl/connectors/feiqiu/docs/database/`（见 3.2 节）。

| 文件 | 记录内容 |
|------|----------|
| `BD_Manual_auth_tables.md` | auth Schema 8 张认证表（users、roles、permissions、user_applications 等） |
| `BD_Manual_biz_tables.md` | biz Schema 核心业务表（coach_tasks、coach_task_history、notes、trigger_jobs、AI 表等） |
| `BD_Manual_auth_biz_schemas.md` | auth + biz Schema 创建 |
| `BD_Manual_fdw_etl_setup.md` | FDW 跨库访问配置（zqyy_app → etl_feiqiu） |
| `BD_Manual_app_schema_rls_views.md` | app Schema RLS 视图 |
| `BD_Manual_ai_tables.md` | AI 相关表（ai_chat_sessions、ai_chat_messages 等） |
| `BD_Manual_member_retention_clue.md` | 会员留存线索表 |
| `README.md` | 数据库文档目录说明 |

子目录：

| 目录 | 内容 |
|------|------|
| `ddl/` | 10 个 DDL 基线文件（含种子数据），覆盖 etl_feiqiu 六层 Schema（meta/ods/dwd/core/dws/app）+ zqyy_app 三个 Schema（auth/biz/public）+ FDW |
| `_archived/` | 已归档的历史变更文档（已废弃的表、已回滚的变更、已合并入 DDL 基线的迁移记录） |

### 2.3 审计记录 `docs/audit/`

项目变更的完整审计追踪体系。审计追溯链：Prompt 日志 ↔ Session 日志 ↔ 变更审计记录，通过 Prompt-ID 和 Session-ID 双向关联。

| 路径 | 内容 |
|------|------|
| `audit_dashboard.md` | 审计仪表盘，汇总所有变更审计记录 |
| `README.md` | 审计目录说明 |
| `SESSION-LOG-GUIDE.md` | Session 日志使用指南：索引字段说明、查询方法、典型场景、与其他审计产物的关系 |
| `changes/` | 39 份变更审计文档（`YYYY-MM-DD__<slug>.md` 格式），每份包含：变更原因、影响范围、回滚策略、验证 SQL |
| `prompt_logs/` | ~500 份 Prompt 日志（`prompt_log_YYYYMMDD_HHMMSS.md`），记录每次 AI 交互的输入输出 |
| `session_logs/` | 全量会话记录（按 `YYYY-MM/DD/` 分层），含双索引（`_session_index.json` / `_session_index_full.json`）、每轮 execution 的完整 Markdown 记录、LLM 生成的操作摘要 |

### 2.4 数据契约 `docs/contracts/`

| 路径 | 内容 |
|------|------|
| `openapi/backend-api.json` | 后端 API 的 OpenAPI 规范文件 |
| `data_dictionary/` | 数据字典（预留，待填充） |
| `schemas/` | 数据 Schema 定义（预留，待填充） |

### 2.5 部署文档 `docs/deployment/`

| 文件 | 内容 |
|------|------|
| `LAUNCH-CHECKLIST.md` | 上线检查清单：环境配置、数据库迁移、服务启动、验证步骤 |
| `EXPORT-PATHS.md` | 输出路径规范：环境变量映射表、目录结构、新增场景检查清单 |

### 2.6 产品需求 `docs/prd/`

| 路径 | 内容 |
|------|------|
| `小程序前后端.txt` | 小程序前后端原始需求描述 |
| `PRD审阅-Q&A.md` | PRD 审阅问答记录（第一轮） |
| `PRD审阅-Q&A-R2.md` | PRD 审阅问答记录（第二轮） |
| `SPI 消费力指数.md` | 消费力指数（SPI）算法需求说明 |
| `specs/00-数据依赖矩阵.md` | 各 SPEC 间的数据依赖关系矩阵 |
| `specs/01-SPEC任务拆分总览.md` | 11 个 SPEC 的任务拆分总览 |
| `specs/P1~P11` | 11 份 SPEC 拆分文档，覆盖：数据库基础(P1)、ETL DWS 扩展(P2)、认证系统(P3)、核心业务(P4)、AI 集成(P5)、前端任务/绩效/看板/详情(P6-P9)、租户管理后台(P10)、部署上线(P11) |

### 2.7 小程序 UI 原型 `docs/h5_ui/`

H5 静态原型页面，用于小程序 UI 设计参考。

| 路径 | 内容 |
|------|------|
| `index.html` | 原型首页入口 |
| `pages/` | 23 个页面原型，包括：登录(`login`)、申请(`apply`)、审核中(`reviewing`)、无权限(`no-permission`)、任务列表/详情(`task-list`/`task-detail`)、绩效(`performance`/`performance-records`)、助教详情(`coach-detail`)、客户详情(`customer-detail`)、客户服务记录(`customer-service-records`)、看板(`board-coach`/`board-customer`/`board-finance`)、聊天(`chat`/`chat-history`)、个人中心(`my-profile`)、首页设置(`home-settings`)、笔记(`notes`)、AI 图标演示(`ai-icon-demo`) |
| `css/` | 6 个样式文件 |
| `js/` | 8 个交互脚本 |
| `img/` | 图片资源 |

### 2.8 小程序前端开发指南 `docs/miniprogram-dev/`

微信小程序前端页面开发与 H5 原型迁移的统一文档中心。覆盖批量自动迁移、用户指定半自动开发、新页面从零开发三种模式。

| 路径 | 内容 |
|------|------|
| `README.md` | 入口索引：快速导航、目录结构、Power 依赖、关联资源 |
| `01-orchestration/batch-auto-playbook.md` | 批量自动模式：89 单元编排 + 4 代理流水线 |
| `01-orchestration/user-guided-playbook.md` | 半自动模式：对话触发 + 按需执行 |
| `01-orchestration/new-page-playbook.md` | 新页面开发：有原型 / 无原型两条路径 |
| `02-action/screenshot-agent.md` | 截图代理：H5/MP 双端截图执行手册 |
| `02-action/audit-agent.md` | 审计代理：结构化审计执行手册 |
| `02-action/fix-agent.md` | 修正代理：P0-P7 分级修正执行手册 |
| `02-action/verify-agent.md` | 验证代理：回归校验执行手册 |
| `02-action/page-dev-agent.md` | 页面开发代理：新页面完整开发执行手册 |
| `03-reference/wxss-rules.md` | WXSS 规范 + rpx 换算 + 颜色/字号/圆角标准值 |
| `03-reference/page-structure-map.md` | 各页面特殊结构速查 |
| `03-reference/css-risk-features.md` | CSS 风险特性 + 替代方案 |
| `03-reference/power-integration.md` | Power 集成指南（4 个 Power 的调用方式） |
| `03-reference/benchmark-history.md` | 基准测试历史记录 |
| `04-audit/PROGRESS.md` | 89 单元进度跟踪（实时更新） |
| `04-audit/CHANGELOG.md` | 文档体系版本变更记录 |
| `05-lessons/pitfalls.md` | 踩坑速查 + 页面迁移经验 |
| `05-lessons/convergence-patterns.md` | 收敛模式 + 不可消除差异白名单 |

### 2.9 参考资料 `docs/reference/`

| 文件 | 内容 |
|------|------|
| `bailian-agent-guide.md` | 百炼 Agent 集成参考指南（由 v1 + v2 合并） |
| `bailian-dashscope-api.md` | 百炼 DashScope API 参考 |

### 2.10 数据分析报告 `docs/reports/`

一次性数据分析、调研产出的报告文档。与 `prd/specs/` 的区别：specs 是需求规格，reports 是基于数据的分析结论。

| 文件 | 内容 |
|------|------|
| `complex-orders-analysis.md` | 复杂订单结构分析（ODS 全量扫描，关联键与复杂度定义） |
| `dwd-amount-duration-calibration.md` | DWD 层金额·绩效·时长字段口径全景（置信度与存疑项标注） |

### 2.11 架构文档 `docs/architecture/`

| 文件 | 内容 |
|------|------|
| `etl-feiqiu-architecture.md` | ETL Connector 整体架构说明（数据流、DWS/INDEX 任务、调度编排、CLI） |

### 2.12 其他项目级文档目录

| 路径 | 内容 |
|------|------|
| `docs/architecture/` | 架构文档（预留，待填充） |
| `docs/roadmap/BACKLOG.md` | 项目待办事项 |
| `docs/roadmap/2026-02-24__fdw-dwd-to-core-migration-plan.md` | FDW + DWD→Core 迁移计划 |
| `docs/migrate/monorepo-migration-summary.md` | Monorepo 迁移总结 |
| `docs/migrate/oldworkspace-kiro-agent-config-summary.md` | 旧工作区 Kiro 配置迁移记录 |
| `docs/ops/` | 运维文档（预留，待填充） |
| `docs/permission_matrix/` | 权限矩阵（预留，待填充） |
| `docs/spec-input/2026-02-22__etl-aggregation-fix-spec-input.md` | ETL 聚合修复的 Spec 输入文档 |


---

## 三、模块内部文档

### 3.1 FastAPI 后端 `apps/backend/`

| 文件 | 内容 |
|------|------|
| `README.md` | 架构概览、双库连接、认证系统、17 个路由模块摘要、服务层、配置加载、触发器系统 |
| `docs/API-REFERENCE.md` | 完整 API 参考：17 个路由模块的所有端点、请求/响应示例、认证要求、错误码 |

### 3.2 ETL Connector `apps/etl/connectors/feiqiu/`

| 路径 | 内容 |
|------|------|
| `README.md` | Connector 总览、快速开始、CLI 用法 |
| `docs/README.md` | 文档目录索引 |
| `docs/CHANGELOG.md` | 变更日志 |
| `docs/api-reference/` | 上游飞球 API 接口文档（字段映射、请求参数、响应结构） |
| `docs/architecture/` | 架构设计文档（数据流、分层设计、SCD 策略） |
| `docs/business-rules/` | 业务规则文档（金额精度、时区处理、去重逻辑） |
| `docs/database/` | ETL 数据库文档：按 Schema 层分目录（ODS/DWD/DWS/ETL_Admin），含表结构、索引策略、跨层映射（cross_layer）、变更记录 |
| `docs/etl_tasks/` | ETL 任务文档（每个任务的输入输出、依赖、调度配置） |
| `docs/operations/` | 运维文档（监控、告警、故障排查） |
| `docs/requirements/` | 需求文档（功能需求、非功能需求） |

### 3.3 微信小程序 `apps/miniprogram/`

| 文件 | 内容 |
|------|------|
| `README.md` | 后端 API 集成、认证流程（含开发模式）、权限模型、关键端点说明 |
| `doc/auth-integration-guide.md` | 认证集成详细指南 |

### 3.4 管理后台 `apps/admin-web/`

| 文件 | 内容 |
|------|------|
| `README.md` | 8 个页面、组件体系（含营业日提示）、API 层、状态管理、开发指南 |

### 3.5 MCP Server `apps/mcp-server/`

| 文件 | 内容 |
|------|------|
| `README.md` | MCP Server 功能说明、工具列表、配置方式 |

### 3.6 共享包 `packages/shared/`

| 文件 | 内容 |
|------|------|
| `README.md` | 4 个模块（enums / money / datetime_utils / 其他工具）的 API 文档及用法示例 |

---

## 四、数据库目录 `db/`

| 路径 | 内容 |
|------|------|
| `README.md` | 数据库目录总览、四库架构说明 |
| `zqyy_app/README.md` | 业务库文档：auth Schema 8 张表字段说明、迁移顺序、FDW 跨库访问 |
| `zqyy_app/migrations/` | 业务库迁移脚本（已合并入 DDL 基线，目录保留 .gitkeep） |
| `etl_feiqiu/README.md` | ETL 库文档：六层 Schema 说明、表清单 |
| `etl_feiqiu/migrations/` | ETL 库迁移脚本（已合并入 DDL 基线，目录保留 .gitkeep） |
| `fdw/` | FDW（Foreign Data Wrapper）跨库访问配置脚本（4 个，运行时资产） |
| `scripts/` | 数据库运维脚本 |
| `_archived/` | 已归档的历史数据库文件 |

---

## 五、Kiro 配置 `.kiro/`

### 5.1 Steering 文件（`.kiro/steering/`）

13 个 Steering 文件，控制 AI 助手的行为规范：

| 文件 | 作用 |
|------|------|
| `language-zh.md` | 语言规范：输出简体中文，代码标识符保留英文 |
| `governance.md` | 治理规范：审计触发条件、执行方式、产物要求 |
| `product.md` / `product-full.md` | 产品概述（精简版 / 完整版） |
| `tech.md` / `tech-full.md` | 技术栈与构建（精简版 / 完整版） |
| `structure-lite.md` / `structure.md` | 项目结构（精简版 / 完整版） |
| `export-paths.md` / `export-paths-full.md` | 输出路径规范（精简版 / 完整版） |
| `testing-env.md` | 测试环境规范：环境变量加载、cwd 要求、测试库使用 |
| `db-docs.md` | 数据库文档规范 |
| `steering-readme-maintainer.md` | README 维护者技能：变更影响审查与文档同步 |

### 5.2 Spec 文件（`.kiro/specs/`）

17 个 Spec 目录，每个包含 `requirements.md`、`design.md`、`tasks.md` 三件套：

| Spec | 内容 |
|------|------|
| `01-miniapp-db-foundation` | P1：小程序数据库基础建设 |
| `02-etl-dws-miniapp-extensions` | P2：ETL DWS 小程序扩展 |
| `03-miniapp-auth-system` | P3：小程序认证系统 |
| `[ETL]-fullstack-integration` | ETL 全栈集成 |
| `miniapp-core-business` | 小程序核心业务 |
| `miniapp-db-foundation` | 小程序数据库基础（早期版本） |
| `admin-web-console` | 管理后台控制台 |
| `etl-aggregation-fix` | ETL 聚合修复 |
| `etl-dws-flow-refactor` | ETL DWS 流程重构 |
| `etl-pipeline-debug` | ETL 管道调试 |
| `etl-staff-dimension` | ETL 员工维度 |
| `dwd-phase1-refactor` | DWD 第一阶段重构 |
| `ods-dedup-standardize` | ODS 去重标准化 |
| `spi-spending-power-index` | SPI 消费力指数 |
| `dataflow-field-completion` | 数据流字段补全 |
| `dataflow-structure-audit` | 数据流结构审计 |
| `assistant-abolish-cleanup` | 助教废除清理 |


---

## 六、文档归档规则

新建文档时，按以下规则选择目标目录。禁止在 `docs/` 根目录散放文件（`README.md` 和 `DOCUMENTATION-MAP.md` 除外）。

| 文档类型 | 目标目录 | 说明 |
|----------|----------|------|
| 数据分析报告、调研产出 | `reports/` | 一次性分析结论，带"生成时间/数据来源"标记 |
| 架构设计文档 | `architecture/` | 系统/模块架构图与说明 |
| 数据库变更审计 | `database/` | `BD_Manual_*.md` 格式，含回滚与验证 SQL |
| 变更审计记录 | `audit/changes/` | `YYYY-MM-DD__<slug>.md` 格式 |
| 产品需求规格 | `prd/specs/` | P1-P11 等需求 spec，不放分析报告 |
| 数据契约 | `contracts/` | OpenAPI spec、JSON Schema、数据字典 |
| 部署与运维配置 | `deployment/` | 启动清单、路径规范、安全指南 |
| 路线图与规划 | `roadmap/` | 迁移计划、BACKLOG |
| Spec 需求输入 | `spec-input/` | 问题汇总，供开启 Spec 流程 |
| 外部参考资料 | `reference/` | 第三方 API/SDK 指南 |
| 迁移记录 | `migrate/` | 仓库迁移总结、配置迁移记录 |
| MCP 相关 | `mcp/` | AI 工具集成文档 |
| UI 原型 | `h5_ui/` | H5 静态原型页面 |
| 小程序前端开发指南 | `miniprogram-dev/` | 页面开发流程、代理手册、规范参考、进度审计、经验教训 |
| 运维手册 | `ops/` | 故障排查、日常运维流程 |
| 权限矩阵 | `permission_matrix/` | 角色-资源权限映射 |

### 判断流程

1. 是模块专属文档？→ 放模块内部 `docs/`（如 `apps/etl/.../docs/`）
2. 是审计产物？→ 统一写 `docs/audit/`，禁止写入子模块
3. 按上表匹配文档类型 → 放对应子目录
4. 都不匹配？→ 先在上表新增分类，再创建子目录

> 本规则由 `.kiro/steering/export-paths.md` 强制执行。