pigx_ishare/DATABASE_DESIGN_OVERVIEW.md

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 席位超卖防护（乐观锁）

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 钱包余额并发控制（乐观锁）

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 定稿