init: iShare Phase D 设计文档完整归档
文档清单： - README.md 仓库导航 - iShare-dev-plan.md 开发规划 - SYSTEM_DESIGN.md 系统设计（角色/流程/接口） - DATABASE_DESIGN_V2.md 数据库完整字段设计 - DATABASE_DESIGN_OVERVIEW.md 设计概要 v4（28张表） - DECISIONS.md 6个关键决策记录 - db/ishare_schema_v2.sql 基础建表 SQL - db/ishare_schema_v3_delta.sql v2→v3 增量（评审修复） - db/ishare_schema_v4_delta.sql v3→v4 增量（决策确认） - memory_2026-02-17.md 工作日志 Phase D 完成：28张表定稿，所有决策已确认
This commit is contained in:
232
DATABASE_DESIGN_OVERVIEW.md
Normal file
232
DATABASE_DESIGN_OVERVIEW.md
Normal file
@@ -0,0 +1,232 @@
|
||||
# iShare 数据库设计概要
|
||||
|
||||
> 版本：v4（决策确认后最终版）
|
||||
> 修订时间：2026-02-17
|
||||
> 完整建表 SQL（v2 基础版）：`db/ishare_schema_v2.sql`
|
||||
> 增量 SQL：`db/ishare_schema_v3_delta.sql` → `db/ishare_schema_v4_delta.sql`
|
||||
> 完整字段说明：`DATABASE_DESIGN_V2.md`
|
||||
> 设计决策记录：`DECISIONS.md`
|
||||
|
||||
---
|
||||
|
||||
## 一、表总览（28 张表）
|
||||
|
||||
### 1.1 App 基础表（复用 PigX，共 9 张）
|
||||
|
||||
| # | 表名 | 说明 | 变更 |
|
||||
|---|------|------|------|
|
||||
| 1 | `app_user` | 用户 | 追加 `invite_code`、`inviter_id` |
|
||||
| 2-9 | `app_role` / `app_user_role` / `app_social_details` / `app_article*` / `app_page` / `app_tabbar` | 框架基础 | 沿用 |
|
||||
|
||||
### 1.2 业务表（iShare 专属，共 19 张）
|
||||
|
||||
#### 平台与产品
|
||||
|
||||
| # | 表名 | 说明 | Phase |
|
||||
|---|------|------|-------|
|
||||
| 10 | `as_platform_type` | 平台分类 | P1 |
|
||||
| 11 | `as_platform` | 流媒体平台 | P1 |
|
||||
| 12 | `as_sub_plan` | 订阅计划 | P1 |
|
||||
| 13 | `as_sub_payroll` | 付费方案（月/季/年） | P1 |
|
||||
| 14 | `as_sub_product` | 合租商品（P1仅 type=1 自营） | P1 |
|
||||
| 15 | `as_product_plan_rel` | 产品-计划 M:N 关联 | P1 |
|
||||
| 16 | `as_sub_account` | 平台账号凭据（AES 加密） | P1 |
|
||||
| 17 | `as_sub_product_comment` | 商品评价 | P1 |
|
||||
| 18 | `as_banner` | 首页 Banner 广告位 | P1 |
|
||||
|
||||
#### 订阅与订单
|
||||
|
||||
| # | 表名 | 说明 | Phase |
|
||||
|---|------|------|-------|
|
||||
| 19 | `as_user_sub` | 合租槽/共享池 | P1 |
|
||||
| 20 | `as_user_sub_member` | 个人订阅记录（status=4 P2用） | P1 |
|
||||
| 21 | `as_order` | 订单（三种支付方式，复用 pigx-pay） | P1 |
|
||||
|
||||
#### 钱包与推广
|
||||
|
||||
| # | 表名 | 说明 | Phase |
|
||||
|---|------|------|-------|
|
||||
| 22 | `as_recharge` | 充值单（人工/支付宝/微信） | P1 |
|
||||
| 23 | `as_wallet` | 用户钱包（乐观锁防并发） | P1 |
|
||||
| 24 | `as_wallet_log` | 钱包流水（type=5 提现 P2用） | P1 |
|
||||
| 25 | `as_invite` | 邀请关系与返现记录 | P1 |
|
||||
| 26 | `as_invite_config` | 邀请返现规则配置（可配置） | P1 |
|
||||
| 27 | `as_notification` | 系统通知 | P1 |
|
||||
|
||||
---
|
||||
|
||||
## 二、核心 ER 关系概览
|
||||
|
||||
```
|
||||
as_platform_type (1) ──< (N) as_platform
|
||||
as_platform (1) ──< (N) as_sub_plan
|
||||
as_sub_plan (1) ──< (N) as_sub_payroll
|
||||
as_sub_plan (N) >──< (N) as_sub_product [via as_product_plan_rel]
|
||||
as_platform (1) ──< (N) as_sub_product [platform_id 冗余]
|
||||
|
||||
as_sub_product (1) ──< (N) as_sub_account
|
||||
as_sub_product (1) ──< (N) as_user_sub
|
||||
as_user_sub (1) ──< (N) as_user_sub_member
|
||||
|
||||
as_sub_product (1) ──< (N) as_order
|
||||
as_order (1) ──< (1) as_user_sub_member [order_id]
|
||||
|
||||
app_user (1) ──< (1) as_wallet
|
||||
as_wallet (1) ──< (N) as_wallet_log
|
||||
as_wallet (1) ──< (N) as_recharge [user_id]
|
||||
app_user (1) ──< (N) as_order
|
||||
app_user (1) ──< (N) as_recharge
|
||||
app_user (1) ──< (N) as_user_sub_member
|
||||
app_user (1) ──< (N) as_invite [as inviter]
|
||||
app_user (1) ──< (1) as_invite [as invitee]
|
||||
app_user (1) ──< (N) as_notification
|
||||
|
||||
as_invite_config (1:active) ──→ as_invite [规则快照到 reward_amount]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、关键状态机
|
||||
|
||||
### 3.1 订单（as_order）
|
||||
|
||||
```
|
||||
[待支付(0)] ─→ 15min 超时 ─→ [已取消(4)]
|
||||
[待支付(0)] ─→ 支付成功 ─→ [已支付(1)] ─→ 激活订阅 ─→ [已完成(2)]
|
||||
[已支付/完成] ─→ 退款 ─→ [已退款(3)]
|
||||
```
|
||||
|
||||
**支付方式：** 1=余额 / 2=支付宝 / 3=微信（均通过 pigx-pay 模块处理）
|
||||
|
||||
### 3.2 充值单（as_recharge）
|
||||
|
||||
```
|
||||
人工充值（管理员）: 直接创建 status=1 记录
|
||||
外部支付：
|
||||
[待支付(0)] ─→ 支付成功 ─→ [已到账(1)] ─→ as_wallet.balance +amount
|
||||
─→ 15min 超时 ─→ [已取消(3)]
|
||||
─→ 支付失败 ─→ [失败(2)]
|
||||
```
|
||||
|
||||
### 3.3 个人订阅（as_user_sub_member）
|
||||
|
||||
```
|
||||
[待激活(0)] ─→ 订单完成 ─→ [使用中(1)]
|
||||
[使用中(1)] ─→ 到期 ─→ [已到期(2)] ─→ 续费 → 新建记录回到[待激活(0)]
|
||||
─→ 主动退订 ─→ [已退订(3)]
|
||||
|
||||
[Phase2] 拼车广场付款后 → [等待车主录入凭据(4)] → 车主录入 → [使用中(1)]
|
||||
```
|
||||
|
||||
> 续费策略：新建 member 记录，旧记录置为2=已到期（保留历史，便于对账）
|
||||
|
||||
### 3.4 合租槽（as_user_sub）
|
||||
|
||||
```
|
||||
[可加入(0)] ─→ 席位满 ─→ [已满(1)]
|
||||
[可加入/已满] ─→ 到期 ─→ [已到期(2)]
|
||||
─→ 车主关闭 ─→ [已关闭(3)]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、关键设计机制
|
||||
|
||||
### 4.1 席位超卖防护（乐观锁）
|
||||
|
||||
```sql
|
||||
UPDATE as_user_sub
|
||||
SET capacity_loaded = capacity_loaded + 1
|
||||
WHERE id = ? AND capacity_loaded < capacity;
|
||||
-- affected rows = 0 → 席位已满，拒绝购买
|
||||
```
|
||||
|
||||
### 4.2 账号凭据安全
|
||||
|
||||
- 存储：AES-256-GCM 加密，密钥存环境变量不入库
|
||||
- 查看：**需二次验证（SMS OTP 或密码重输），OTP 存 Redis TTL 5min**
|
||||
- 返回：服务端解密后返回明文，不记录日志，前端倒计时隐藏
|
||||
|
||||
### 4.3 支付集成
|
||||
|
||||
- **复用 pigx-pay 模块**（已集成支付宝 + 微信）
|
||||
- 购买商品 → `as_order`（pay_type 2/3）→ pigx-pay 回调 → 更新订单状态 → 创建 member 记录
|
||||
- 余额充值 → `as_recharge`（pay_type 2/3）→ pigx-pay 回调 → 更新充值单 → 增加钱包余额
|
||||
|
||||
### 4.4 邀请返现（可配置规则）
|
||||
|
||||
```
|
||||
1. 管理后台配置 as_invite_config（选择激活规则）
|
||||
2. 被邀请人注册 → 写入 as_invite 记录
|
||||
3. 触发条件满足（首次购买 or 每次购买）
|
||||
→ 读取当前 is_active=1 的 as_invite_config
|
||||
→ 计算返现金额（快照到 as_invite.reward_amount）
|
||||
→ 延迟发放（reward_delay_days 天后）
|
||||
→ as_wallet_log（type=4）+ as_wallet.balance +reward_amount
|
||||
```
|
||||
|
||||
### 4.5 钱包余额并发控制（乐观锁）
|
||||
|
||||
```sql
|
||||
UPDATE as_wallet
|
||||
SET balance = balance - ?, version = version + 1
|
||||
WHERE user_id = ? AND version = ? AND balance >= ?;
|
||||
-- affected rows = 0 → 并发冲突或余额不足
|
||||
```
|
||||
|
||||
### 4.6 订阅到期定时任务（每日 02:00）
|
||||
|
||||
```
|
||||
1. expire_time < now()+7天 且 status=1 → 推送续费提醒
|
||||
2. expire_time < now() 且 status=1 → 置 status=2，capacity_loaded -1
|
||||
3. as_order.expire_time < now() 且 status=0 → 置 status=4（取消）
|
||||
4. as_recharge.expire_time < now() 且 status=0 → 置 status=3（取消）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、关键索引清单
|
||||
|
||||
| 表 | 索引字段 | 用途 |
|
||||
|----|---------|------|
|
||||
| `as_user_sub_member` | `(user_id, status)` | 我的订阅列表 |
|
||||
| `as_user_sub_member` | `(expire_time, status)` | 定时任务扫描到期 |
|
||||
| `as_order` | `(user_id, status)` | 用户订单列表 |
|
||||
| `as_notification` | `(user_id, is_read)` | 未读通知数 |
|
||||
| `as_user_sub` | `(product_id, status)` | 商品可用合租槽 |
|
||||
| `as_sub_account` | `(product_id, status)` | 产品账号列表 |
|
||||
| `as_sub_product` | `(product_type, status)` | 商品分类查询 |
|
||||
| `as_banner` | `(status, sort_order)` | 首页 Banner |
|
||||
| `as_recharge` | `(user_id, status)` | 充值记录查询 |
|
||||
| `as_product_plan_rel` | `(product_id)` / `(plan_id)` | M:N 双向查询 |
|
||||
| `as_invite_config` | `(is_active)` | 读取当前规则 |
|
||||
|
||||
---
|
||||
|
||||
## 六、版本变更记录
|
||||
|
||||
| 版本 | 变更内容 |
|
||||
|------|----------|
|
||||
| v1 | 原版骨架（2023-08，有多项严重缺陷） |
|
||||
| v2 | 全面修订：修复15项缺陷，新增6张表（23张） |
|
||||
| v3 | 评审修订：修复7个问题，新增3张表（27张） |
|
||||
| **v4** | **决策确认：新增 `as_invite_config`（28张），Phase 1/2 范围明确** |
|
||||
|
||||
---
|
||||
|
||||
## 七、所有待决策项（已全部确认 ✅）
|
||||
|
||||
| # | 问题 | 决策 |
|
||||
|---|------|------|
|
||||
| 1 | 付费方式一期 | ✅ C - 余额+支付宝+微信（复用 pigx-pay） |
|
||||
| 2 | 拼车广场 | ✅ C - Phase 1 不做，Phase 2 追加 |
|
||||
| 3 | 凭据展示 | ✅ B - 二次验证（SMS OTP 或密码重输） |
|
||||
| 4 | 邀请返现 | ✅ 完全可配置（类型/金额/触发条件），无上限 |
|
||||
| 5 | M:N 关联 | ✅ v3 已改为 `as_product_plan_rel` |
|
||||
| 6 | 提现功能 | ✅ B - Phase 2，一期只充值+消费 |
|
||||
|
||||
**Phase D（系统设计）✅ 全部完成**
|
||||
|
||||
---
|
||||
|
||||
*最后更新：2026-02-17 · v4 定稿*
|
||||
Reference in New Issue
Block a user