Files

Neo 6f8f12314f feat: 累积功能变更 — 聊天集成、租户管理、小程序更新、ETL 增强、迁移脚本

包含多个会话的累积代码变更：
- backend: AI 聊天服务、触发器调度、认证增强、WebSocket、调度器最小间隔
- admin-web: ETL 状态页、任务管理、调度配置、登录优化
- miniprogram: 看板页面、聊天集成、UI 组件、导航更新
- etl: DWS 新任务（finance_area_daily/board_cache）、连接器增强
- tenant-admin: 项目初始化
- db: 19 个迁移脚本（etl_feiqiu 11 + zqyy_app 8）
- packages/shared: 枚举和工具函数更新
- tools: 数据库工具、报表生成、健康检查
- docs: PRD/架构/部署/合约文档更新

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-04-06 00:03:48 +08:00

38 KiB

Raw Permalink Blame History

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/`	视觉识别设计标准

判断流程

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

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

38 KiB Raw Permalink Blame History Unescape Escape

NeoZQYY 文档地图

一、根目录

二、项目级文档 docs/

2.1 文档中心首页

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

2.3 审计记录 docs/audit/

2.4 数据契约 docs/contracts/

2.5 部署文档 docs/deployment/

2.6 产品需求 docs/prd/

2.7 小程序 UI 原型 docs/h5_ui/

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

2.9 参考资料 docs/reference/

2.10 数据分析报告 docs/reports/

2.11 架构文档 docs/architecture/

2.12 MCP 文档 docs/mcp/

2.13 其他项目级文档目录

三、模块内部文档

3.1 FastAPI 后端 apps/backend/

3.2 ETL Connector apps/etl/connectors/feiqiu/

3.3 微信小程序 apps/miniprogram/

3.4 管理后台 apps/admin-web/

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

3.6 MCP Server apps/mcp-server/

3.7 共享包 packages/shared/

四、数据库目录 db/

五、Kiro 配置 .kiro/

5.1 Steering 文件（.kiro/steering/）

5.2 Hooks（.kiro/hooks/）

5.3 Skills（.kiro/skills/）

5.4 Agents（.kiro/agents/）

5.5 Scripts（.kiro/scripts/）

5.6 Spec 文件（.kiro/specs/）