291 lines
14 KiB
Markdown
291 lines
14 KiB
Markdown
# NeoZQYY 文档地图
|
||
|
||
> 本文档记录项目中所有文档资产的位置、类型和内容概要，方便快速定位。
|
||
> 归档规则见末尾「文档归档规则」章节；程序输出路径规范见 `docs/deployment/EXPORT-PATHS.md`。
|
||
|
||
---
|
||
|
||
## 一、根目录
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `README.md` | 项目总览：模块表（含文档链接）、技术栈、快速开始命令 |
|
||
| `.env.template` | 环境变量模板，列出所有可配置项及说明 |
|
||
|
||
---
|
||
|
||
## 二、项目级文档 `docs/`
|
||
|
||
### 2.1 文档中心首页
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `docs/README.md` | 项目架构图、模块文档索引、技术栈速览、认证体系概览、四库架构、常用命令 |
|
||
|
||
### 2.2 数据库变更手册 `docs/database/`
|
||
|
||
每个 `BD_Manual_*.md` 是一次数据库结构变更的完整审计文档，包含：变更说明、字段定义、影响分析、回滚策略、验证 SQL。
|
||
|
||
| 文件 | 记录内容 |
|
||
|------|----------|
|
||
| `BD_Manual_auth_tables.md` | auth Schema 8 张认证表（users、roles、permissions、user_applications 等） |
|
||
| `BD_Manual_biz_tables.md` | biz Schema 4 张核心业务表（coach_tasks、coach_task_history、notes、trigger_jobs） |
|
||
| `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` | 门店台桌主表 |
|
||
| `BD_Manual_20260301_cleanup_and_fixes.md` | 已删除表残留清理 + ODS 商品销售窗口修复 + dim_staff_ex 列名修复 |
|
||
| `README.md` | 数据库文档目录说明 |
|
||
|
||
子目录：
|
||
|
||
| 目录 | 内容 |
|
||
|------|------|
|
||
| `ddl/` | 10 个 DDL 基线文件，覆盖 etl_feiqiu 六层 Schema（meta/ods/dwd/core/dws/app）+ zqyy_app 三个 Schema（auth/biz/public）+ FDW |
|
||
| `_archived/` | 10 个已归档的历史变更文档（已废弃的表、已回滚的变更等） |
|
||
|
||
### 2.3 审计记录 `docs/audit/`
|
||
|
||
项目变更的完整审计追踪体系。审计追溯链：Prompt 日志 ↔ Session 日志 ↔ 变更审计记录，通过 Prompt-ID 和 Session-ID 双向关联。
|
||
|
||
| 路径 | 内容 |
|
||
|------|------|
|
||
| `audit_dashboard.md` | 审计仪表盘，汇总所有变更审计记录 |
|
||
| `README.md` | 审计目录说明 |
|
||
| `SESSION-LOG-GUIDE.md` | Session 日志使用指南：索引字段说明、查询方法、典型场景、与其他审计产物的关系 |
|
||
| `changes/` | 38 份变更审计文档（`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/reference/`
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `bailian-agent-guide.md` | 百炼 Agent 集成参考指南（由 v1 + v2 合并） |
|
||
| `bailian-dashscope-api.md` | 百炼 DashScope API 参考 |
|
||
|
||
### 2.9 数据分析报告 `docs/reports/`
|
||
|
||
一次性数据分析、调研产出的报告文档。与 `prd/specs/` 的区别：specs 是需求规格，reports 是基于数据的分析结论。
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `complex-orders-analysis.md` | 复杂订单结构分析（ODS 全量扫描，关联键与复杂度定义） |
|
||
| `dwd-amount-duration-calibration.md` | DWD 层金额·绩效·时长字段口径全景（置信度与存疑项标注） |
|
||
|
||
### 2.10 架构文档 `docs/architecture/`
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `etl-feiqiu-architecture.md` | ETL Connector 整体架构说明（数据流、DWS/INDEX 任务、调度编排、CLI） |
|
||
|
||
### 2.11 其他项目级文档目录
|
||
|
||
| 路径 | 内容 |
|
||
|------|------|
|
||
| `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 设计、表结构、索引策略） |
|
||
| `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/` | 业务库迁移脚本（日期前缀命名） |
|
||
| `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` | 助教废除清理 |
|
||
|
||
|
||
---
|
||
|
||
## 六、文档归档规则
|
||
|
||
新建文档时，按以下规则选择目标目录。禁止在 `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 静态原型页面 |
|
||
| 运维手册 | `ops/` | 故障排查、日常运维流程 |
|
||
| 权限矩阵 | `permission_matrix/` | 角色-资源权限映射 |
|
||
|
||
### 判断流程
|
||
|
||
1. 是模块专属文档？→ 放模块内部 `docs/`（如 `apps/etl/.../docs/`）
|
||
2. 是审计产物？→ 统一写 `docs/audit/`，禁止写入子模块
|
||
3. 按上表匹配文档类型 → 放对应子目录
|
||
4. 都不匹配？→ 先在上表新增分类，再创建子目录
|
||
|
||
> 本规则由 `.kiro/steering/export-paths.md` 强制执行。
|