root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
075caf067f5494e36eb249c659252c210865125e
Neo-ZQYY/db/zqyy_app/README.md
Neo b25308c3f4 feat: P1-P3 全栈集成 — 数据库基础 + DWS 扩展 + 小程序鉴权 + 工程化体系 
## P1 数据库基础
- zqyy_app: 创建 auth/biz schema、FDW 连接 etl_feiqiu
- etl_feiqiu: 创建 app schema RLS 视图、商品库存预警表
- 清理 assistant_abolish 残留数据

## P2 ETL/DWS 扩展
- 新增 DWS 助教订单贡献度表 (dws.assistant_order_contribution)
- 新增 assistant_order_contribution_task 任务及 RLS 视图
- member_consumption 增加充值字段、assistant_daily 增加处罚字段
- 更新 ODS/DWD/DWS 任务文档及业务规则文档
- 更新 consistency_checker、flow_runner、task_registry 等核心模块

## P3 小程序鉴权系统
- 新增 xcx_auth 路由/schema（微信登录 + JWT）
- 新增 wechat/role/matching/application 服务层
- zqyy_app 鉴权表迁移 + 角色权限种子数据
- auth/dependencies.py 支持小程序 JWT 鉴权

## 文档与审计
- 新增 DOCUMENTATION-MAP 文档导航
- 新增 7 份 BD_Manual 数据库变更文档
- 更新 DDL 基线快照（etl_feiqiu 6 schema + zqyy_app auth）
- 新增全栈集成审计记录、部署检查清单更新
- 新增 BACKLOG 路线图、FDW→Core 迁移计划

## Kiro 工程化
- 新增 5 个 Spec（P1/P2/P3/全栈集成/核心业务）
- 新增审计自动化脚本（agent_on_stop/build_audit_context/compliance_prescan）
- 新增 6 个 Hook（合规检查/会话日志/提交审计等）
- 新增 doc-map steering 文件

## 运维与测试
- 新增 ops 脚本：迁移验证/API 健康检查/ETL 监控/集成报告
- 新增属性测试：test_dws_contribution / test_auth_system
- 清理过期 export 报告文件
- 更新 .gitignore 排除规则
2026-02-26 08:03:53 +08:00

165 lines
6.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 被此库只读引用
Reference in New Issue View Git Blame Copy Permalink