Neo-ZQYY/docs/DOCUMENTATION-MAP.md

# NeoZQYY 文档地图

> 本文档记录项目中所有文档资产的位置、类型和内容概要，方便快速定位。
> 归档规则见末尾「文档归档规则」章节；程序输出路径规范见 `docs/deployment/EXPORT-PATHS.md`。
> 最后更新：2026-03-28（board-finance-dws-area-refactor 财务看板区域维度重构）

---

## 一、根目录

| 文件 | 内容 |
|------|------|
| `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_fdw_finance_area.md` | FDW 财务区域查询映射（后端直连 ETL 库访问 v_dws_finance_area_daily / v_dws_finance_board_cache） |
| `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` | 会员留存线索表 |
| `BD_Manual_tenant_admin_tables.md` | NS4 租户管理后台 6 张表（tenant_admins、excel_upload_log、salary_adjustments、3 张 staging 表） |
| `BD_Manual_biz_registry_tables.md` | biz Schema 注册体系四张表（connectors、tenants、sites、site_code_history） |
| `BD_Manual_scheduled_tasks.md` | scheduled_tasks P16 新增字段（min_run_interval_value、min_run_interval_unit、last_success_at） |
| `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 日志使用指南：索引字段说明、查询方法、典型场景、与其他审计产物的关系 |
| `AUDIT-HOOKS-GUIDE.md` | 审计 Hooks 使用指南：Hook 触发机制、配置方式、与审计流程的集成 |
| `changes/` | 67 份变更审计文档（`YYYY-MM-DD__<slug>.md` 格式），每份包含：变更原因、影响范围、回滚策略、验证 SQL |
| `prompt_logs/` | 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` | 上线检查清单：环境配置、数据库迁移、服务启动、验证步骤 |
| `launch-checklist-patch.md` | 上线检查清单补丁 |
| `EXPORT-PATHS.md` | 输出路径规范：环境变量映射表、目录结构、新增场景检查清单 |
| `PRIVACY-POLICY.md` | 隐私政策文档 |
| `wx-api-security-guide.md` | 微信 API 安全指南 |
| `wx-encrypt-guide.md` | 微信加密指南 |

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

| 路径 | 内容 |
|------|------|
| `小程序前后端.txt` | 小程序前后端原始需求描述 |
| `后端接口需求说明_数据需求PRD.md` | 后端接口需求说明与数据需求 PRD |
| `PRD审阅-Q&A.md` | PRD 审阅问答记录（第一轮） |
| `PRD审阅-Q&A-R2.md` | PRD 审阅问答记录（第二轮） |
| `SPI 消费力指数.md` | 消费力指数（SPI）算法需求说明 |
| `ai-app-prompts.md` | AI 应用 Prompt 设计 |
| `AI需求2.md` | AI 需求第二版 |
| `specs/00-数据依赖矩阵.md` | 各 SPEC 间的数据依赖关系矩阵 |
| `specs/01-SPEC任务拆分总览.md` | 11 个 SPEC 的任务拆分总览 |
| `specs/P1~P11` | 15 份 SPEC 拆分文档，覆盖：数据库基础(P1)、ETL DWS 扩展(P2)、认证系统(P3)、核心业务(P4)、AI 集成(P5/P5.1/P5.2)、前端任务/绩效/看板/详情(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`/`task-detail-callback`/`task-detail-priority`/`task-detail-relationship`)、绩效(`performance`/`performance-records`)、助教详情(`coach-detail`)、客户详情(`customer-detail`)、客户服务记录(`customer-service-records`)、看板(`board-coach`/`board-customer`/`board-finance`)、聊天(`chat`/`chat-history`)、个人中心(`my-profile`)、笔记(`notes`) |
| `pages/_baked/` | 已烘焙（固化）的页面快照 |
| `css/` | 6 个样式文件 |
| `js/` | 8 个交互脚本 |
| `img/` | 图片资源 |
| `tools/` | H5 转小程序检查工具（`h5-to-mp-checker/`） |

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

微信小程序前端页面开发与 H5 原型迁移的统一文档中心。

| 路径 | 内容 |
|------|------|
| `README.md` | 入口索引：快速导航、目录结构、关联资源 |
| `QUICK-REFERENCE.md` | 快速参考手册 |
| `API-contract.md` | API 契约文档 |
| `API-OUTPUT-SPEC.md` | 后端接口输出规范（DS-API-OUTPUT-001）：字段类型约定 / 枚举值 / 各页面接口字段对照表 |
| `API-requirement.md` | API 需求文档 |
| `design-system/VI-DESIGN-SYSTEM.md` | VI 设计系统：任务/客户/等级配色、AI 图标、CSS 变量速查 |
| `design-system/DATETIME-DISPLAY-STANDARD.md` | 日期时间展示规范：由近及远 6 级展示规则、边界处理、JS 实现参考 |
| `design-system/DISPLAY-STANDARDS.md` | 前端展示规范（第1-6章）：金额 / 课时 / 计数 / 空值 / 百分比 / 等级文案 |
| `design-system/DISPLAY-STANDARDS-2.md` | 前端展示规范（第7-9章）：截止日期 / 评分星级 / Mock 数据规范 + 工具函数总表 |
| `design-system/vi-guide.html` | VI 设计系统可视化指南（HTML） |
| `api-audit/` | 19 个页面的 API 审计文档（每页一份 `.md`），含硬编码汇总（`_hardcode-summary.md`） |
| `h5-migration/` | H5 转小程序迁移指南：桥接文档（`h5-to-mp-bridge.md`）、附录（`appendix/`） |
| `API-requirement/` | API 需求子目录（预留） |

### 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 是基于数据的分析结论。

| 路径 | 内容 |
|------|------|
| `DWD-DOC/` | **权威标杆文档**（业务模型与财务数据权威数据源）：消费链路全景(01)、支付渠道与对账公式(02)、收入构成与储值卡资金流(03)、维度表全景(04)、F2 收支平衡公式(05)、校准清单(06)、GAP 闭环状态(07)、consume_money 口径时间线(`consume/`) |
| `business-analysis/` | 业务分析报告：每日营收报告(`daily-revenue-latest.md`)、高价值充值客户分析(`high-value-recharge-customer-analysis.md`) |
| `etl-calibration/` | ETL 校准报告：DWS BD 手册校准(2026-03-07)、DWS 代码校准(2026-03-07)、财务看板 DWS 审计(2026-03-07) |
| `h5-mp-conversion/` | H5 转小程序报告：财务看板审计(`board-finance-h5-mp-audit.md`)、H5 UI 提取(`h5-ui-extraction.md`) |
| `p4-task/` | P4 任务报告：Spec 与实现差距分析、任务生命周期全景 |
| `tech-solution/` | 技术方案（`_archived/bailian-technical-solution.md` ⚠️ 已归档，基于旧 OpenAI 兼容方案，P14 迁移后由 DashScope Application API 替代） |
| `vi-color-audit/` | VI 配色审计：详细审计(Phase2)、完成报告、实施文档、合规审计 |
| `2026-03-20__ai_app_page_mapping.md` | AI 应用→页面消费映射报告：8 个 AI 应用的触发方式、数据流向、页面展示位置汇总 |
| `_archived/2026-03-21__ai_full_chain_test.md` | ⚠️ 已归档（2026-03-21）— AI 全链路测试报告，基于旧 openai SDK，P14 迁移后由新测试替代 |

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

| 文件 | 内容 |
|------|------|
| `etl-feiqiu-architecture.md` | ETL Connector 整体架构说明（数据流、DWS/INDEX 任务、调度编排、CLI） |
| `backend-architecture.md` | 后端 FastAPI 服务层架构（路由/服务/FDW/Trace 模块清单、数据流、设计决策） |

### 2.12 MCP 文档 `docs/mcp/`

| 文件 | 内容 |
|------|------|
| `AI-DATABASE-QUERY-MANUAL.md` | AI 数据库查询手册 |
| `WEIXIN-DEVTOOLS-MCP.md` | 微信开发者工具 MCP 集成文档 |

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

| 路径 | 内容 |
|------|------|
| `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/init-test-user.md` | 测试用户初始化指南 |
| `docs/permission_matrix/` | 权限矩阵（预留，待填充） |
| `docs/vi-standards/` | VI 设计标准（预留，待填充） |
| `docs/spec-input/2026-02-22__etl-aggregation-fix-spec-input.md` | ETL 聚合修复的 Spec 输入文档 |

---

## 三、模块内部文档

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

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

RNS1.2 新增模块（客户与助教接口）：

| 路径 | 内容 |
|------|------|
| `app/routers/xcx_customers.py` | 客户端点：CUST-1 客户详情、CUST-2 客户服务记录 |
| `app/routers/xcx_coaches.py` | 助教端点：COACH-1 助教详情 |
| `app/services/customer_service.py` | 客户查询服务：Banner 概览、AI 洞察、消费记录嵌套、coachTasks、favoriteCoaches |
| `app/services/coach_service.py` | 助教查询服务：绩效、收入、任务分组、TOP 客户、历史月份 |
| `app/schemas/xcx_customers.py` | 客户相关 Pydantic Schema（CustomerDetailResponse、CustomerRecordsResponse 等） |
| `app/schemas/xcx_coaches.py` | 助教相关 Pydantic Schema（CoachDetailResponse 等） |
| `tests/unit/test_degradation_rns12.py` | RNS1.2 优雅降级单元测试 |
| `tests/unit/test_auth_rns12.py` | RNS1.2 权限校验单元测试 |
| `tests/integration/test_e2e_customer_coach.py` | CUST-1/CUST-2/COACH-1 端到端集成测试 |

RNS1.3 新增模块（三看板接口）：

| 路径 | 内容 |
|------|------|
| `app/routers/xcx_board.py` | 看板端点：BOARD-1 助教看板、BOARD-2 客户看板、BOARD-3 财务看板 |
| `app/routers/xcx_config.py` | 配置端点：CONFIG-1 技能类型 |
| `app/services/board_service.py` | 看板编排服务：日期范围/环比/排序/分页/降级 |
| `app/schemas/xcx_board.py` | 看板相关 Pydantic Schema（7 枚举 + ~40 响应 Schema） |
| `app/schemas/xcx_config.py` | 配置相关 Pydantic Schema（SkillTypeItem） |

RNS1.4 新增模块（CHAT 对齐与联调收尾）：

| 路径 | 内容 |
|------|------|
| `app/routers/xcx_chat.py` | CHAT 端点：CHAT-1 对话历史、CHAT-2a/2b 消息查询、CHAT-3 发送消息、CHAT-4 SSE 流式（替代原 `xcx_ai_chat.py`，路径从 `/api/ai/*` 迁移到 `/api/xcx/chat/*`） |
| `app/services/chat_service.py` | CHAT 业务逻辑：对话管理、消息持久化、对话复用规则、referenceCard 组装、标题生成 |
| `app/schemas/xcx_chat.py` | CHAT 相关 Pydantic Schema（ChatHistoryResponse、ChatMessagesResponse、ReferenceCard、SendMessageResponse、ChatStreamRequest 等） |

Monorepo 级属性测试（`tests/`）：

| 路径 | 内容 |
|------|------|
| `tests/test_rns12_properties.py` | RNS1.2 属性测试（14 个 Property，Hypothesis 框架） |
| `tests/test_board_properties.py` | RNS1.3 属性测试（18 个测试函数，12 个 Property，Hypothesis 框架） |
| `tests/test_board_service_unit.py` | RNS1.3 看板工具函数单元测试 |
| `tests/test_rns1_chat_title_properties.py` | RNS1.4 属性测试：标题生成优先级（Property 4，Hypothesis 框架） |
| `tests/test_rns1_chat_reuse_properties.py` | RNS1.4 属性测试：对话复用规则（Property 6） |
| `tests/test_rns1_chat_reference_card_properties.py` | RNS1.4 属性测试：referenceCard round trip（Property 7） |
| `tests/test_rns1_chat_persistence_properties.py` | RNS1.4 属性测试：消息持久化与会话元数据更新（Property 8） |
| `tests/test_rns1_chat_sse_properties.py` | RNS1.4 属性测试：SSE 事件类型有效性（Property 9） |
| `tests/test_rns1_chat_ordering_properties.py` | RNS1.4 属性测试：列表排序不变量（Property 3） |

NS2 新增模块（AI Prompt 细化）：

| 路径 | 内容 |
|------|------|
| `app/ai/data_fetchers/member_data.py` | 客户消费数据获取（消费记录、会员卡、备注） |
| `app/ai/data_fetchers/assistant_data.py` | 助教信息与服务记录获取 |
| `app/ai/data_fetchers/page_context.py` | 页面上下文文本化（10 种入口 contextType） |
| `app/ai/apps/app3_clue.py` | 应用 3 Prompt 拼接（客户数据维客线索分析） |
| `app/ai/apps/app4_analysis.py` | 应用 4 Prompt 拼接（关系分析/任务建议） |
| `app/ai/apps/app5_tactics.py` | 应用 5 Prompt 拼接（话术参考） |
| `app/ai/apps/app6_note.py` | 应用 6 Prompt 拼接（备注分析） |
| `app/ai/apps/app7_customer.py` | 应用 7 Prompt 拼接（客户分析） |
| `app/ai/apps/app1_chat.py` | 应用 1 页面上下文集成（async `_build_page_context`） |

Monorepo 级属性测试（NS2）：

| 路径 | 内容 |
|------|------|
| `tests/test_data_fetchers/test_member_data_props.py` | 客户数据获取属性测试（P1-P4, P6, P17） |
| `tests/test_data_fetchers/test_assistant_data_props.py` | 助教数据获取属性测试（P5） |
| `tests/test_data_fetchers/test_page_context_props.py` | 页面上下文属性测试（P10-P12） |
| `tests/test_data_fetchers/test_data_fetchers_unit.py` | 数据获取层单元测试 |
| `tests/test_ai_apps/test_build_prompt_props.py` | Prompt 拼接属性测试（P7-P9, P14-P17） |
| `tests/test_ai_apps/test_app1_props.py` | 应用 1 属性测试（P13, P16） |
| `tests/test_ai_apps/test_ai_apps_unit.py` | 应用层单元测试 |

P14 新增模块（AI DashScope 迁移）：

| 路径 | 内容 |
|------|------|
| `tests/test_ai_config_props.py` | AIConfig 属性测试（Property 2：环境变量校验完整性） |
| `tests/test_dashscope_client_props.py` | DashScopeClient 属性测试（Property 1：重试策略、Property 20：响应解析） |
| `tests/test_circuit_breaker_props.py` | 熔断器属性测试（Property 5：app_id 隔离、Property 6：状态机转换） |
| `tests/test_circuit_breaker_unit.py` | 熔断器单元测试 |
| `tests/test_rate_limiter_props.py` | 限流器属性测试（Property 7：窗口控制） |
| `tests/test_budget_tracker_props.py` | Token 预算属性测试（Property 8：预算检查正确性） |
| `tests/test_budget_tracker_unit.py` | Token 预算单元测试 |
| `tests/test_run_log_props.py` | 运行日志属性测试（Property 18：状态机、Property 19：Prompt 截断） |
| `tests/test_dispatcher_props.py` | 调度器属性测试（Property 9：事件链映射、Property 10：容错、Property 12：去重） |
| `tests/test_dispatcher_unit.py` | 调度器单元测试 |
| `tests/test_internal_ai_api.py` | 内部 AI API 属性测试（Property 11：认证） |
| `tests/test_sse_props.py` | SSE 事件流属性测试（Property 17：事件格式） |
| `tests/test_session_props.py` | session_id 属性测试（Property 3：格式、Property 4：对话复用） |
| `tests/test_cache_service_props.py` | 缓存服务属性测试（Property 14-16：过期策略、查询过滤、保留上限） |
| `tests/test_app8_idempotent.py` | App8 幂等写入属性测试（Property 13） |

P15 新增模块（AI 监控后台）：

| 路径 | 内容 |
|------|------|
| `app/routers/admin_ai.py` | AI 监控后台路由（13 个端点：Dashboard/调度/调用/缓存/预算/批量/告警） |
| `app/services/ai/admin_service.py` | AI 监控后台聚合服务（AdminAIService） |
| `app/services/ai/cleanup_service.py` | AI 数据清理服务（AICleanupService，每日 03:00） |
| `app/schemas/admin_ai.py` | AI 监控后台 Pydantic Schema |
| `tests/unit/test_admin_ai_router.py` | admin AI 路由单元测试（16 个测试） |
| `tests/unit/test_admin_ai_service.py` | AdminAIService 单元测试（9 个测试） |
| `tests/unit/test_ai_cleanup_service.py` | 清理服务单元测试（7 个测试） |
| `tests/unit/test_backfill_script.py` | 回填脚本单元测试（13 个测试） |
| `tests/integration/test_ai_full_chain.py` | AI 全链路测试（15 个场景，Mock/Real 双轨） |

Monorepo 级属性测试（P15）：

| 路径 | 内容 |
|------|------|
| `tests/test_admin_ai_dashboard_props.py` | Property 8：Dashboard 聚合正确性 |
| `tests/test_admin_ai_alert_props.py` | Property 9：告警筛选与状态转换 |
| `tests/test_admin_ai_cache_props.py` | Property 10：缓存失效精确性 |
| `tests/test_admin_ai_batch_props.py` | Property 11：批量执行预估公式 |
| `tests/test_admin_ai_pagination_props.py` | Property 12：分页与筛选正确性 |
| `tests/test_backfill_props.py` | Property 13：回填断点续跑 round-trip |
| `tests/test_ai_cleanup_props.py` | Property 14：数据保留不变量 |

DevTrace 全链路日志模块：

| 路径 | 内容 |
|------|------|
| `app/trace/config.py` | TraceConfig 配置类（环境变量读取 + 运行时动态修改） |
| `app/trace/context.py` | TraceContext + TraceSpan 数据模型（contextvars 请求级隔离，23 种 span_type） |
| `app/trace/writer.py` | JSON Lines 日志写入器（按日期分目录、按小时分文件、10MB 自动轮转） |
| `app/trace/cleanup.py` | 日志自动清理（按保留天数删除过期目录） |
| `app/trace/middleware.py` | TraceMiddleware ASGI 中间件（拦截 xcx_* 路由） |
| `app/trace/decorators.py` | @trace_service 装饰器（Service 层追踪） |
| `app/trace/db_wrapper.py` | 数据库连接生命周期追踪（DB_QUERY/DB_CONN/DB_CONN_RELEASE/DB_ERROR） |
| `app/trace/error_handler.py` | 异常/错误全链路追踪（ERROR span） |
| `app/trace/sse_wrapper.py` | SSE 流式响应追踪（SSE_START/SSE_EVENT/SSE_END/AI_CALL） |
| `app/trace/ws_wrapper.py` | WebSocket 连接追踪（WS_CONNECT/WS_MESSAGE/WS_DISCONNECT） |
| `app/trace/job_wrapper.py` | 后台 Job 执行追踪（JOB_START/JOB_END/JOB_ERROR） |
| `app/trace/coverage.py` | 覆盖率扫描器（路由/Service/Job/SSE/WS 五维度） |
| `app/routers/admin_dev_trace.py` | DevTrace 管理 API（8 端点：日期/请求列表/详情/清理/设置/覆盖率） |

Monorepo 级属性测试（DevTrace）：

| 路径 | 内容 |
|------|------|
| `tests/test_trace_context_props.py` | Property 1：Request ID 唯一性、Property 2：Span 顺序保持 |
| `tests/test_trace_writer_props.py` | Property 3：TraceSpan 结构完整性、Property 5：JSON 序列化往返一致性、Property 6：日志文件路径生成 |
| `tests/test_trace_cleanup_props.py` | Property 8：清理保留期正确性 |
| `tests/test_trace_auth_props.py` | Property 4：Token 前缀截断、Property 20：鉴权失败原因分类 |
| `tests/test_trace_switch_props.py` | Property 13：开关关闭时无 Trace 产出、Property 14：功能开关控制 Span 内容 |
| `tests/test_trace_middleware_props.py` | Property 15：路由前缀过滤 |
| `tests/test_trace_error_props.py` | Property 16：异常时 Trace 完整性 |
| `tests/test_trace_sse_props.py` | Property 17：SSE 流式 Trace 完整性 |
| `tests/test_trace_ws_props.py` | Property 18：WebSocket Trace 生命周期 |
| `tests/test_trace_job_props.py` | Property 19：后台 Job Trace 完整性 |
| `tests/test_trace_db_props.py` | Property 21：数据库连接生命周期配对 |

admin-web-restructure 新增模块（管理后台重构）：

| 路径 | 内容 |
|------|------|
| `app/routers/admin_db_health.py` | 数据库健康监控路由（GET /api/admin/db-health，4 库连接池/大小/慢查询） |
| `app/routers/admin_triggers.py` | 触发器统一视图路由（GET /api/admin/triggers/unified，biz/ai/etl 三源聚合） |
| `app/utils/cron_validator.py` | cron 表达式校验工具函数（5 字段格式验证） |
| `app/schemas/admin_db_health.py` | DbHealthItem Pydantic Schema |
| `app/schemas/admin_triggers.py` | UnifiedTriggerItem Pydantic Schema |
| `app/schemas/trigger_jobs.py` | UpdateTriggerConfigRequest Pydantic Schema（PATCH 配置编辑） |
| `tests/unit/test_cron_and_models.py` | cron 校验与 Pydantic 模型单元测试 |
| `tests/unit/test_admin_db_health.py` | DB 健康端点单元测试 |
| `tests/unit/test_admin_triggers.py` | 统一触发器端点单元测试 |
| `tests/unit/test_trigger_jobs_patch.py` | PATCH 触发器配置端点单元测试 |

Monorepo 级属性测试（admin-web-restructure）：

| 路径 | 内容 |
|------|------|
| `tests/test_admin_web_db_health_props.py` | Property 1：DB 健康 API 已连接数据库返回完整指标 |
| `tests/test_admin_web_unified_triggers_props.py` | Property 3：触发器统一视图数据完整性与字段完整性 |
| `tests/test_admin_web_trigger_config_props.py` | Property 4/5：触发器配置编辑不变量与更新正确性 |
| `tests/test_admin_web_cron_validator_props.py` | Property 6：cron 表达式校验拒绝无效输入 |

board-finance-dws-area-refactor 新增模块（财务看板区域维度重构）：

| 路径 | 内容 |
|------|------|
| `tests/test_area_mapping_props.py` | Property 1-2：区域映射 round-trip + 未知区域返回 None |
| `tests/test_area_mapping_unit.py` | 区域映射边界条件单元测试 |
| `tests/test_finance_area_daily_props.py` | Property 3-7：日粒度恒等式/非 all 零值/输出完整性/幂等性/settle_type 过滤 |
| `tests/test_finance_board_cache_props.py` | Property 8-9：数据指纹确定性/当期不缓存 |
| `tests/test_board_service_props.py` | Property 10-14：查询路由/区域过滤/revenue 项数/overview 覆盖/回归一致性 |
| `scripts/ops/backfill_finance_area_daily.py` | 历史数据回填脚本（日粒度 + 缓存重算） |
| `scripts/ops/validate_board_finance.py` | 144 组合全量验证脚本（8 time_range × 9 area_code × 2 compare） |

| 路径 | 内容 |
|------|------|
| `app/routers/tenant_auth.py` | 租户认证端点：登录、刷新令牌 |
| `app/routers/tenant_users.py` | 租户用户端点：申请列表、关联建议、审核通过/拒绝、用户列表/编辑/绑定 |
| `app/routers/tenant_excel.py` | 租户 Excel 端点：上传解析、确认写入、上传记录、模板下载 |
| `app/routers/tenant_clues.py` | 租户线索端点：客户搜索、线索列表/编辑/删除/隐藏显示 |
| `app/routers/admin_tenant_admins.py` | 管理端租户管理员 CRUD：列表、创建、编辑、重置密码 |
| `app/auth/tenant_admins.py` | 租户管理员认证依赖注入（`require_tenant_admin`、`site_filter_clause`、`verify_site_access`） |
| `app/schemas/tenant_users.py` | 租户用户相关 Pydantic Schema |
| `app/schemas/tenant_excel.py` | 租户 Excel 相关 Pydantic Schema |
| `app/schemas/tenant_clues.py` | 租户线索相关 Pydantic Schema |
| `app/schemas/admin_tenant_admins.py` | 管理端租户管理员 Pydantic Schema |

### 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` | 13 个页面（含 P15 AI 监控 4 页面、DevTrace 日志页面）、组件体系、API 层（含 adminAI、devTrace）、状态管理、开发指南 |

### 3.5 租户管理后台 `apps/tenant-admin/`

NS4 租户管理后台，独立 React 应用，面向租户管理员（Tenant_Admin）。

| 路径 | 内容 |
|------|------|
| `src/pages/Login/` | 登录页（用户名+密码） |
| `src/pages/UserApproval/` | 用户审核（申请列表 + 关联建议 + 审核操作） |
| `src/pages/UserManagement/` | 用户管理（列表 + 编辑 + 绑定） |
| `src/pages/ExcelUpload/` | Excel 上传（4 种模板 + 校验 + 冲突 diff + 确认写入） |
| `src/pages/RetentionClues/` | 维客线索管理（客户搜索 + 线索 CRUD + 隐藏/显示） |
| `src/components/SiteSelector/` | 门店筛选器组件 |
| `src/components/DiffTable/` | 冲突 diff 交互表格 |
| `src/components/ClueEditor/` | 线索编辑表单 |
| `src/services/api.ts` | API 调用封装（JWT 自动附加/刷新） |
| `src/hooks/useAuth.ts` | 认证状态管理 |

后端路由：`tenant_auth.py`、`tenant_users.py`、`tenant_excel.py`、`tenant_clues.py`（均注册在 `/api/tenant/*`）。管理端租户管理员 CRUD 由 `admin_tenant_admins.py`（`/api/admin/*`）提供，admin-web 前端调用。

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

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

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

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

---

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

| 路径 | 内容 |
|------|------|
| `README.md` | 数据库目录总览、四库架构说明 |
| `zqyy_app/README.md` | 业务库文档：auth Schema 8 张表字段说明、迁移顺序、FDW 跨库访问 |
| `zqyy_app/migrations/` | 业务库迁移脚本：`2026-03-22__p14_ai_module.sql`（P14：ai_run_logs、ai_trigger_jobs 新表 + ai_conversations.session_id）、`2026-03-22__ns41_registry_tables.sql`（NS4.1：biz.connectors/tenants/sites/site_code_history 四张新表 + 种子数据迁移）、`2026-03-22__p16_min_run_interval.sql`（P16：scheduled_tasks 三字段）、`2026-03-23__p15_ai_monitoring.sql`（P15：ai_run_logs.alert_status + BRIN 索引） |
| `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/`）

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

| 文件 | 作用 |
|------|------|
| `language-zh.md` | 语言规范：输出简体中文，代码标识符保留英文 |
| `agent-behavior.md` | AI 执行行为约束：上下文保护、子代理委托场景 |
| `planning-interrogation.md` | 编码前需求审问：必问清单、追问规则 |
| `pre-change-research.md` | 逻辑改动前置调研：子代理调研流程、Session 索引查询 |
| `project-overview.md` | 项目概览（精简版） |
| `product-full.md` | 产品概述（完整版，fileMatch 自动加载） |
| `tech.md` / `tech-full.md` | 技术栈与构建（精简版 / 完整版） |
| `structure.md` | 项目结构（完整版，fileMatch 自动加载） |
| `export-paths.md` / `export-paths-full.md` | 输出路径规范（精简版 / 完整版） |
| `testing-env.md` | 测试环境规范：环境变量加载、cwd 要求、测试库使用 |
| `db-docs.md` | 数据库文档规范 |
| `doc-map.md` | 文档地图 Steering（fileMatch 触发） |
| `deprecated-objects.md` | 归档目录与废弃对象规则 |
| `dwd-doc-authority.md` | DWD-DOC 标杆文档权威性声明 |
| `steering-readme-maintainer.md` | README 维护者技能：变更影响审查与文档同步 |

### 5.2 Hooks（`.kiro/hooks/`）

11 个 Agent Hook，自动化审计与流程控制：

| Hook | 触发事件 | 作用 |
|------|----------|------|
| `agent-on-stop` | agentStop | Agent 停止时触发审计流程 |
| `prompt-on-submit` | promptSubmit | Prompt 提交时触发合规预扫描 |
| `pre-change-guard` | preToolUse | 写操作前的变更守卫 |
| `cwd-guard-shell` | preToolUse | Shell 命令 cwd 守卫 |
| `run-audit-writer` | userTriggered | 手动触发审计写入 |
| `session-summary` | agentStop | Session 摘要生成 |
| `etl-fullstack-integration` | postTaskExecution | ETL 全栈集成任务后处理 |
| `etl-unified-analysis` | userTriggered | ETL 统一分析 |
| `field-disappearance-scan` | userTriggered | 字段消失扫描 |
| `h5-screenshot` | userTriggered | H5 截图 |
| `daily-revenue-report` | userTriggered | 每日营收报告 |

### 5.3 Skills（`.kiro/skills/`）

3 个技能模块：

| 技能 | 作用 |
|------|------|
| `bd-manual-db-docs` | PostgreSQL schema 变更时落盘 BD 手册到 `docs/database/` |
| `change-annotation-audit` | 每次修改生成审计记录、AI_CHANGELOG、CHANGE 标记注释 |
| `steering-readme-maintainer` | 变更影响审查并同步更新 README 与审计记录 |

### 5.4 Agents（`.kiro/agents/`）

| Agent | 作用 |
|-------|------|
| `audit-writer.md` | 变更后审计 + 文档同步，输出审计产物 |

### 5.5 Scripts（`.kiro/scripts/`）

11 个自动化脚本，支撑 Hooks 和审计流程：

| 脚本 | 作用 |
|------|------|
| `agent_on_stop.py` | Agent 停止时的审计处理 |
| `prompt_on_submit.py` | Prompt 提交时的合规预扫描 |
| `audit_flagger.py` | 审计标记器 |
| `audit_reminder.py` | 审计提醒器 |
| `build_audit_context.py` | 构建审计上下文 |
| `change_compliance_prescan.py` | 变更合规预扫描 |
| `file_baseline.py` | 文件基线管理 |
| `prompt_audit_log.py` | Prompt 审计日志 |
| `session_log.py` | Session 日志管理 |
| `_ensure_root.py` | 确保根目录工具 |

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

24 个 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：小程序认证系统 |
| `04-miniapp-core-business` | P4：小程序核心业务 |
| `05-miniapp-ai-integration` | P5：小程序 AI 集成 |
| `[ETL]-fullstack-integration` | ETL 全栈集成 |
| `admin-web-console` | 管理后台控制台 |
| `assistant-abolish-cleanup` | 助教废除清理 |
| `business-day-cutoff` | 营业日截止逻辑 |
| `dataflow-field-completion` | 数据流字段补全 |
| `dataflow-structure-audit` | 数据流结构审计 |
| `dwd-business-panorama` | DWD 业务全景 |
| `dwd-phase1-refactor` | DWD 第一阶段重构 |
| `etl-coupon-detail` | ETL 优惠券明细 |
| `etl-dws-flow-refactor` | ETL DWS 流程重构 |
| `etl-pipeline-debug` | ETL 管道调试 |
| `etl-staff-dimension` | ETL 员工维度 |
| `etl-unified-pipeline` | ETL 统一管道 |
| `h5-miniprogram-migration` | H5 转小程序迁移 |
| `h5-miniprogram-migration-subsequent` | H5 转小程序迁移（后续） |
| `ods-dedup-standardize` | ODS 去重标准化 |
| `p4-prerequisite-fixes` | P4 前置修复 |
| `p52-miniapp-fe-all-pages` | P5.2 小程序前端全页面 |
| `rns1-infra-contract-rewrite` | RNS1.0 基础设施与契约重写（响应包装、CamelModel、路由修正、API 契约） |
| `rns1-task-performance-api` | RNS1.1 任务与绩效接口（TASK-1 扩展、TASK-2、PERF-1、PERF-2、前端适配） |
| `rns1-customer-coach-api` | RNS1.2 客户与助教接口（CUST-1 客户详情、CUST-2 客户服务记录、COACH-1 助教详情） |
| `rns1-board-apis` | RNS1.3 三看板接口（BOARD-1 助教看板、BOARD-2 客户看板、BOARD-3 财务看板、CONFIG-1 技能类型） |
| `rns1-chat-integration` | RNS1.4 CHAT 对齐与联调收尾（CHAT-1/2/3/4 路径迁移、对话复用、referenceCard、SSE 流式、FDW 验证、13 页面联调） |
| `tenant-admin-web` | NS4 租户管理后台（独立认证、用户审核/管理、Excel 数据上传、维客线索管理、管理端租户管理员 CRUD） |
| `spi-spending-power-index` | SPI 消费力指数 |
| `ai-prompt-refinement` | NS2 AI Prompt 细化（共享数据获取层、6 个应用 Prompt 拼接、页面上下文文本化、17 个属性测试） |
| `P14-ai-dashscope-migration` | P14 AI 模块 DashScope 迁移（openai→dashscope Application API、熔断/限流/预算防护、运行日志、事件触发链、ETL 集成、DB 迁移、20 个属性测试） |
| `admin-web-enhancement` | NS4.1 + P16 管理后台增强（注册体系 + 租户管理员重构 + 调度任务间隔） |
| `ai-monitoring-testing` | P15 AI 监控后台 + 测试重建 + 回填（admin-web 4 页面、13 API 端点、15 全链路测试、14 属性测试、数据清理、回填脚本） |
| `dev-trace-log` | 开发调试全链路日志系统（Trace 基础设施 12 模块、8 API 端点、DevTrace 前端页面、22 属性测试，覆盖 HTTP/SSE/WS/Job/异常/DB/中间件） |
| `admin-web-restructure` | 管理后台重构优化（18 页面→7 模块菜单重组、Dashboard 仪表盘、ETLTasks Tab 合并、TriggerManager 统一管理、3 新后端 API、8 属性测试、LogViewer 归档） |
| `board-finance-dws-area-refactor` | 财务看板 DWS 区域维度重构（dws_finance_area_daily 原子层 + dws_finance_board_cache 缓存层 + 后端缓存优先查询 + 区域映射共享包 + 14 属性测试） |

---

## 六、文档归档规则

新建文档时，按以下规则选择目标目录。禁止在 `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/` | 页面开发流程、API 审计、设计系统、H5 迁移指南 |
| 运维手册 | `ops/` | 故障排查、日常运维流程、测试用户初始化 |
| 权限矩阵 | `permission_matrix/` | 角色-资源权限映射 |
| VI 设计标准 | `vi-standards/` | 视觉识别设计标准 |

### 判断流程

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

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