# db/zqyy_app — 业务数据库

`zqyy_app` 是 NeoZQYY 的业务数据库，存储用户认证、任务队列、调度配置、执行日志等数据。  
测试库：`test_zqyy_app`（开发和测试环境默认连接）。

## Schema 架构

| Schema | 用途 | 状态 |
|--------|------|------|
| `auth` | 用户认证与权限（微信用户、角色、权限、申请、绑定） | 已建表 |
| `biz` | 业务数据（预留，未来存储门店业务数据） | 已创建，待建表 |
| `public` | 管理后台（admin_users、task_queue、scheduled_tasks、task_execution_log） | 已建表 |

## auth Schema — 认证系统（8 张表）

### auth.users — 微信用户主表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | SERIAL PK | 自增主键 |
| wx_openid | VARCHAR(128) UNIQUE | 微信 OpenID |
| wx_union_id | VARCHAR(128) | 微信 UnionID |
| wx_avatar_url | VARCHAR(512) | 头像 URL |
| nickname | VARCHAR(50) | 昵称 |
| phone | VARCHAR(20) | 手机号 |
| status | VARCHAR(20) | 状态：pending / approved / rejected / disabled |
| created_at | TIMESTAMPTZ | 创建时间 |
| updated_at | TIMESTAMPTZ | 更新时间 |

### auth.site_code_mapping — 球房ID与门店映射
| 字段 | 类型 | 说明 |
|------|------|------|
| id | SERIAL PK | 自增主键 |
| site_code | VARCHAR(10) UNIQUE | 球房ID（格式：2字母+3数字，如 AB123） |
| site_id | BIGINT UNIQUE | 门店 ID（对应 ETL 库的 site_id） |
| site_name | VARCHAR(100) | 门店名称 |
| tenant_id | INT | 租户 ID |

### auth.roles — 角色定义
| 字段 | 类型 | 说明 |
|------|------|------|
| id | SERIAL PK | 自增主键 |
| code | VARCHAR(50) UNIQUE | 角色编码 |
| name | VARCHAR(100) | 角色名称 |
| description | TEXT | 描述 |

预置角色：
| code | name | 权限 |
|------|------|------|
| `coach` | 助教 | view_tasks, view_board_coach |
| `staff` | 员工 | view_tasks, view_board |
| `site_admin` | 店铺管理员 | 全部 5 个权限 |
| `tenant_admin` | 租户管理员 | 全部 5 个权限 |

### auth.permissions — 权限定义
| 字段 | 类型 | 说明 |
|------|------|------|
| id | SERIAL PK | 自增主键 |
| code | VARCHAR(50) UNIQUE | 权限编码 |
| name | VARCHAR(100) | 权限名称 |
| description | TEXT | 描述 |

预置权限：
| code | name |
|------|------|
| `view_tasks` | 查看任务 |
| `view_board` | 查看看板 |
| `view_board_finance` | 查看财务看板 |
| `view_board_customer` | 查看客户看板 |
| `view_board_coach` | 查看助教看板 |

### auth.role_permissions — 角色-权限关联
联合主键 `(role_id, permission_id)`，外键级联删除。

### auth.user_applications — 用户入驻申请
| 字段 | 类型 | 说明 |
|------|------|------|
| id | SERIAL PK | 自增主键 |
| user_id | INT FK | 关联 auth.users |
| site_code | VARCHAR(10) | 球房ID |
| site_id | BIGINT | 门店 ID（后端自动填充） |
| applied_role_text | VARCHAR(100) | 申请身份文本 |
| employee_number | VARCHAR(50) | 员工编号 |
| phone | VARCHAR(20) | 手机号 |
| status | VARCHAR(20) | pending / approved / rejected |
| reviewer_id | INT | 审核人 |
| review_note | TEXT | 审核备注 |
| created_at | TIMESTAMPTZ | 申请时间 |
| reviewed_at | TIMESTAMPTZ | 审核时间 |

### auth.user_site_roles — 用户-门店-角色关联
| 字段 | 类型 | 说明 |
|------|------|------|
| id | SERIAL PK | 自增主键 |
| user_id | INT FK | 关联 auth.users |
| site_id | BIGINT | 门店 ID |
| role_id | INT FK | 关联 auth.roles |

唯一约束：`(user_id, site_id, role_id)` — 同一用户在同一门店下不能重复分配同一角色。

### auth.user_assistant_binding — 用户-人员绑定
| 字段 | 类型 | 说明 |
|------|------|------|
| id | SERIAL PK | 自增主键 |
| user_id | INT FK | 关联 auth.users |
| site_id | BIGINT | 门店 ID |
| assistant_id | BIGINT | 助教 ID（ETL 库） |
| staff_id | BIGINT | 员工 ID（ETL 库） |
| binding_type | VARCHAR(20) | 绑定类型 |

## public Schema — 管理后台

### admin_users — 管理后台用户
用于管理后台（`apps/admin-web/`）的用户名密码登录。

默认种子数据：`admin / admin123`（生产环境部署后务必修改）。

### task_queue — 任务执行队列
存储待执行和执行中的 ETL 任务，按 `site_id` 隔离。

### scheduled_tasks — 调度任务配置
存储定时调度规则，由后端 `Scheduler` 服务消费。

### task_execution_log — 任务执行日志
记录每次 ETL 任务执行的状态、耗时、日志输出。

## FDW 跨库访问

`zqyy_app` 通过 Foreign Data Wrapper（FDW）只读访问 `etl_feiqiu` 数据库：
- 迁移脚本：`2026-02-24__p1_setup_fdw_etl.sql`
- 用途：小程序认证时的人员匹配（查询 ETL 库中的助教/员工记录）
- 安全：FDW 连接使用只读用户

## 目录结构

```
db/zqyy_app/
├── migrations/                                    # 迁移脚本（日期前缀）
│   ├── 2026-02-24__p1_create_auth_biz_schemas.sql # 创建 auth + biz Schema
│   ├── 2026-02-24__p1_setup_fdw_etl.sql           # 设置 FDW 跨库访问
│   ├── 2026-02-25__p3_create_auth_tables.sql      # 创建 auth 8 张表
│   └── 2026-02-25__p3_seed_roles_permissions.sql  # 预置角色和权限
├── schemas/                                       # Schema DDL（待补充）
├── seeds/
│   └── admin_web_seed.sql                         # 管理后台默认管理员
├── scripts/
│   └── create_test_db.sql                         # 创建测试库脚本
└── README.md
```

## 迁移执行顺序

1. `p1_create_auth_biz_schemas.sql` — 创建 Schema
2. `p1_setup_fdw_etl.sql` — 设置 FDW
3. `p3_create_auth_tables.sql` — 创建认证表
4. `p3_seed_roles_permissions.sql` — 插入种子数据

所有迁移脚本使用 `IF NOT EXISTS` / `ON CONFLICT DO NOTHING` 幂等语法，可重复执行。

## 与其他模块的关系

- `apps/backend/` — 通过 `get_connection()` 读写此库
- `apps/miniprogram/` — 通过后端 API 间接访问
- `apps/admin-web/` — 通过后端 API 间接访问
- `db/etl_feiqiu/` — 通过 FDW 被此库只读引用