Neo-ZQYY/docs

docs/ — 项目文档中心

NeoZQYY Monorepo 的文档中心，存放产品需求、技术架构、数据契约、运维手册、审计记录等所有文档资产。

项目全貌

NeoZQYY 是面向台球门店业务的全栈数据平台，包含 6 个子系统：

┌─────────────────────────────────────────────────────────────┐
│                    微信小程序（C 端）                          │
│                  apps/miniprogram/                           │
│          TypeScript + TDesign + Donut 多端                   │
└──────────────────────┬──────────────────────────────────────┘
                       │ REST API
┌──────────────────────▼──────────────────────────────────────┐
│                  FastAPI 后端                                 │
│                apps/backend/                                 │
│     13 个路由模块 · JWT 双认证 · WebSocket 日志               │
├──────────────┬───────────────────────┬──────────────────────┤
│  zqyy_app    │                       │   etl_feiqiu         │
│  (业务库)     │◄──── FDW 只读 ────────│   (ETL 数据仓库)      │
│  auth/biz    │                       │   6 层 Schema         │
└──────────────┘                       └──────────┬───────────┘
                                                  │
┌─────────────────────────────────────────────────▼───────────┐
│                  ETL Connector                               │
│          apps/etl/connectors/feiqiu/                         │
│     飞球 SaaS API → ODS → DWD → DWS 三层处理                 │
└─────────────────────────────────────────────────────────────┘

┌──────────────────────┐  ┌──────────────────────┐
│    管理后台            │  │    MCP Server         │
│  apps/admin-web/      │  │  apps/mcp-server/     │
│  React+Vite+AntDesign │  │  AI 工具集成           │
└──────────────────────┘  └──────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                  共享包 packages/shared/                      │
│            枚举 · 金额精度 · 时间工具                          │
└─────────────────────────────────────────────────────────────┘

模块文档索引

应用模块（各模块 README）

模块	路径	说明
ETL Connector	apps/etl/connectors/feiqiu/docs/	架构、API 参考、业务规则、运维文档
FastAPI 后端	apps/backend/README.md	架构、路由总览、认证体系、服务层
后端 API 参考	apps/backend/docs/API-REFERENCE.md	全部 API 端点详细说明
微信小程序	apps/miniprogram/README.md	开发指南、认证流程、API 集成
管理后台	apps/admin-web/README.md	页面功能、组件、状态管理
MCP Server	apps/mcp-server/README.md	工具说明、安全策略、配置
共享包	packages/shared/README.md	枚举、金额精度、时间工具 API

数据库文档

文档	路径	说明
zqyy_app 架构	db/zqyy_app/README.md	业务库 Schema、表结构、迁移顺序
etl_feiqiu 架构	db/etl_feiqiu/README.md	ETL 六层 Schema 说明
BD 手册	docs/database/	各表的详细变更文档（BD_Manual_*.md）

项目级文档

目录	说明	典型内容
architecture/	架构设计文档	系统架构图、ETL 架构说明
audit/	统一审计目录（变更记录 + Prompt 日志）	changes/ 变更审计、prompt_logs/ 交互日志
contracts/	数据契约	OpenAPI spec、JSON Schema、数据字典
database/	数据库设计与变更文档（BD 手册）	BD_Manual_*.md 表结构变更审计、ddl/ 基线
deployment/	部署与运维配置文档	启动清单、输出路径规范、隐私政策、微信安全/加密指南
h5_ui/	小程序 UI 原型（H5 静态页面）	页面原型、样式、交互脚本、H5 转 MP 检查工具
mcp/	MCP Server 相关文档	AI 数据库查询手册、微信开发者工具 MCP
migrate/	迁移记录与指南	Monorepo 迁移总结、旧配置迁移记录
miniprogram-dev/	小程序前端开发指南	API 审计、设计系统、H5 迁移指南、展示规范
ops/	运维手册	测试用户初始化、故障排查
permission_matrix/	权限矩阵	角色-资源权限映射（待填充）
prd/	产品需求文档	PRD 审阅 Q&A、specs/ 下 P1-P11 需求规格（含 P5.1/P5.2）
reference/	外部参考资料	百炼 Agent 指南、DashScope API 参考
reports/	数据分析报告与调研产出	DWD-DOC 标杆文档、业务分析、ETL 校准、VI 配色审计等（按主题分子目录）
roadmap/	路线图与待办	迁移计划、BACKLOG
spec-input/	Spec 流程的需求输入文档	用户提交的问题汇总，供开启 Spec 使用
vi-standards/	VI 设计标准	视觉识别设计标准（待填充）

技术栈速览

层级	技术
后端	Python 3.10+ / FastAPI / Uvicorn / psycopg2
前端（管理后台）	React 19 / Vite 6 / Ant Design 5 / Zustand / TypeScript
前端（小程序）	微信原生 + Donut + TDesign / TypeScript
数据库	PostgreSQL（4 库：etl_feiqiu / test_etl_feiqiu / zqyy_app / test_zqyy_app）
包管理	Python: uv workspace / 前端: pnpm
AI 集成	MCP Server（PostgreSQL 只读查询）

数据库四库架构

库名	用途	连接变量
etl_feiqiu	ETL 数据仓库（6 层 Schema）	PG_DSN
test_etl_feiqiu	ETL 测试库	TEST_DB_DSN
zqyy_app	业务数据（认证、队列、调度）	APP_DB_DSN
test_zqyy_app	业务测试库	默认连接

ETL 六层 Schema：meta → ods → dwd → core → dws → app

认证体系概览

系统支持两套独立认证：

认证方式	入口	用户来源	令牌
管理后台	/api/auth/login	admin_users 表	JWT（用户名+密码）
小程序	/api/xcx-auth/login	auth.users 表	JWT（微信 code）

小程序认证流程：微信登录 → 提交申请 → 管理员审批 → 正式使用

多门店隔离

• 业务数据通过 site_id 隔离
• ETL 数据库使用 RLS（Row Level Security）
• 后端 JWT 令牌携带 site_id，所有查询自动过滤
• 用户可关联多个门店，通过 API 切换

配置体系

优先级（低 → 高）：根 .env < 应用 .env.local < 环境变量 < CLI 参数

关键环境变量见 .env.template。

常用命令

# 安装依赖
uv sync --all-packages

# 启动后端
cd apps/backend && uv run uvicorn app.main:app --reload

# 启动管理后台
cd apps/admin-web && pnpm dev

# ETL 执行
cd apps/etl/connectors/feiqiu && python -m cli.main --dry-run --tasks DWD_LOAD_FROM_ODS

# 测试
cd apps/etl/connectors/feiqiu && pytest tests/unit
cd C:\Project\NeoZQYY && pytest tests/ -v

文件归属规则

• 模块专属的 docs/tests/scripts → 放模块内部
• 项目级/跨模块的 docs/tests/scripts → 放根目录
• 审计产物统一写 docs/audit/，禁止写入子模块内部