Neo-ZQYY/docs/DOCUMENTATION-MAP.md

NeoZQYY 文档地图

本文档记录项目中所有文档资产的位置、类型和内容概要，方便快速定位。

---

一、根目录

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

---

二、项目级文档 docs/

2.1 文档中心首页

文件	内容
docs/README.md	项目架构图、模块文档索引、技术栈速览、认证体系概览、四库架构、常用命令
docs/etl-feiqiu-architecture.md	ETL Connector 整体架构说明

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

每个 BD_Manual_*.md 是一次数据库结构变更的完整审计文档，包含：变更说明、字段定义、影响分析、回滚策略、验证 SQL。

文件	记录内容
BD_Manual_auth_tables.md	auth Schema 8 张认证表（users、roles、permissions、user_applications 等）
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_dws_assistant_order_contribution.md	DWS 助教订单贡献表
BD_Manual_dws_goods_stock_summary.md	DWS 商品库存汇总表
BD_Manual_dws_member_spending_power_index.md	DWS 会员消费力指数表
BD_Manual_member_balance_changes.md	会员余额变动表
BD_Manual_recharge_settlements.md	充值结算表
BD_Manual_goods_stock_movements.md	商品库存流水表
BD_Manual_goods_stock_summary.md	商品库存汇总表
BD_Manual_goods_stock_warning_info.md	商品库存预警表
BD_Manual_store_goods_master.md	门店商品主表
BD_Manual_store_goods_sales_records.md	门店商品销售记录
BD_Manual_tenant_goods_master.md	租户商品主表
BD_Manual_assistant_accounts_master.md	助教账户主表
BD_Manual_assistant_service_records.md	助教服务记录表
BD_Manual_site_tables_master.md	门店台桌主表
README.md	数据库文档目录说明

子目录：

目录	内容
ddl/	9 个 DDL 基线文件，覆盖 etl_feiqiu 六层 Schema（meta/ods/dwd/core/dws/app）+ zqyy_app 两个 Schema（auth/public）+ FDW
_archived/	10 个已归档的历史变更文档（已废弃的表、已回滚的变更等）

2.3 审计记录 docs/audit/

项目变更的完整审计追踪体系。

路径	内容
audit_dashboard.md	审计仪表盘，汇总所有变更审计记录
README.md	审计目录说明
changes/	31 份变更审计文档（YYYY-MM-DD__<slug>.md 格式），每份包含：变更原因、影响范围、回滚策略、验证 SQL
prompt_logs/	~500 份 Prompt 日志（prompt_log_YYYYMMDD_HHMMSS.md），记录每次 AI 交互的输入输出

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/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 输入文档
docs/etl-feiqiu-architecture.md	ETL Connector 整体架构说明

---

三、模块内部文档

3.1 FastAPI 后端 apps/backend/

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

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 设计、表结构、索引策略）
docs/etl_tasks/	ETL 任务文档（每个任务的输入输出、依赖、调度配置）
docs/operations/	运维文档（监控、告警、故障排查）
docs/requirements/	需求文档（功能需求、非功能需求）

3.3 微信小程序 apps/miniprogram/

文件	内容
README.md	后端 API 集成、认证流程、权限模型、关键端点说明

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	3 个模块（enums / money / datetime_utils）的 API 文档及用法示例

---

四、数据库目录 db/

路径	内容
README.md	数据库目录总览、四库架构说明
zqyy_app/README.md	业务库文档：auth Schema 8 张表字段说明、迁移顺序、FDW 跨库访问
zqyy_app/migrations/	业务库迁移脚本（日期前缀命名）
etl_feiqiu/README.md	ETL 库文档：六层 Schema 说明、表清单
etl_feiqiu/migrations/	ETL 库迁移脚本（日期前缀命名）
fdw/	FDW（Foreign Data Wrapper）跨库访问配置脚本
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	助教废除清理