pigx_ishare/DATABASE_DESIGN_OVERVIEW.md

iShare 数据库设计概要

版本：v3（基于 v2 评审修订）
修订时间：2026-02-17
完整建表 SQL（v2 基础版）：db/ishare_schema_v2.sql
增量变更 SQL（v2→v3）：db/ishare_schema_v3_delta.sql
完整字段说明：DATABASE_DESIGN_V2.md

---

一、表总览（27 张表）

1.1 App 基础表（复用 PigX，共 9 张）

#	表名	说明	变更
1	app_user	用户	追加 invite_code、inviter_id
2	app_role	角色	沿用
3	app_user_role	用户角色关联	沿用
4	app_social_details	第三方登录	沿用
5	app_article_category	文章分类	沿用
6	app_article	文章/公告	沿用
7	app_article_collect	文章收藏	沿用
8	app_page	页面配置	沿用
9	app_tabbar	底部导航	沿用

1.2 业务表（iShare 专属，共 18 张）

平台与产品

#	表名	说明	v3 变更
10	as_platform_type	平台分类（视频/音乐/AI等）	—
11	as_platform	流媒体平台	—
12	as_sub_plan	订阅计划	—
13	as_sub_payroll	付费方案（月/季/年）	—
14	as_sub_product	合租商品	移除 sub_plan_ids 逗号字段
15	as_product_plan_rel	产品-计划 M:N 关联表	✨ 新增（I2 修复）
16	as_sub_account	平台账号凭据（AES 加密）	—
17	as_sub_product_comment	商品评价	—
18	as_banner	首页 Banner 广告位	✨ 新增（I1 修复）

订阅与订单

#	表名	说明	v3 变更
19	as_user_sub	合租槽/共享池	补充索引
20	as_user_sub_member	个人订阅记录	移除唯一键、新增 status=4、补充索引
21	as_order	订单（含状态机、价格快照）	补充索引

钱包与推广

#	表名	说明	v3 变更
22	as_recharge	钱包充值单	✨ 新增（R1 修复）
23	as_wallet	用户钱包（乐观锁防并发）	—
24	as_wallet_log	钱包流水（含余额快照）	—
25	as_invite	邀请关系与返现	—
26	as_notification	系统通知	补充索引

---

二、核心 ER 关系概览（v3）

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] ← v3 改为关联表
as_platform      (1) ──< (N) as_sub_product    [platform_id 冗余加速查询]

as_sub_product   (1) ──< (N) as_sub_account    [product_id]
as_sub_product   (1) ──< (N) as_user_sub       [product_id]
as_user_sub      (1) ──< (N) as_user_sub_member [sub_id]

as_sub_product   (1) ──< (N) as_order          [product_id]
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] ← v3 新增
app_user  (1) ──< (N) as_order
app_user  (1) ──< (N) as_recharge              [user_id] ← v3 新增
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

---

三、关键状态机

3.1 订单（as_order）

[待支付] ─→ 15min 超时 ─→ [已取消]
[待支付] ─→ 支付成功   ─→ [已支付] ─→ 激活订阅 ─→ [已完成]
[已支付/已完成] ─→ 退款 ─→ [已退款]

3.2 充值单（as_recharge） ← v3 新增

[待支付(0)] ─→ 外部支付成功 ─→ [已到账(1)]
             ─→ 15min 超时  ─→ [已取消(3)]
             ─→ 支付失败    ─→ [支付失败(2)]
人工充值：管理员操作 → 直接创建 status=1 记录

3.3 个人订阅（as_user_sub_member） ← v3 修订

[待激活(0)] ─→ 订单完成  ─→ [使用中(1)]
[等待车主(4)] ← 广场拼车付款后，等待车主录入凭据
[等待车主(4)] ─→ 车主录入凭据 ─→ [使用中(1)]
[使用中(1)]   ─→ 到期      ─→ [已到期(2)] ─→ 续费 ─→ [使用中(1)] 新建记录
              ─→ 主动退订  ─→ [已退订(3)]

v3 修订：移除 UNIQUE(sub_id, user_id)，续费时新建记录（旧记录置2=已到期），保留完整历史

3.4 合租槽（as_user_sub）

[可加入(0)] ─→ 席位满 ─→ [已满(1)]
[可加入/已满] ─→ 到期     ─→ [已到期(2)]
             ─→ 车主关闭 ─→ [已关闭(3)]

---

四、关键设计机制

4.1 席位超卖防护（乐观锁）

-- 购买时原子性占位，affected rows = 0 则席位已满
UPDATE as_user_sub
SET capacity_loaded = capacity_loaded + 1
WHERE id = ? AND capacity_loaded < capacity;

4.2 账号凭据加密

• 算法：AES-256-GCM（as_sub_account.encrypt_type = 1）
• account_passwd：密文（Base64）
• passwd_salt：随机 IV（16 字节 Base64）
• 密钥：服务端环境变量，不入库
• 查看凭据：仅限 as_user_sub_member.status = 1，服务端解密后返回明文，不记录日志

4.3 钱包余额并发控制（乐观锁）

UPDATE as_wallet
SET balance = balance - ?, version = version + 1
WHERE user_id = ? AND version = ? AND balance >= ?;
-- affected rows = 0：并发冲突或余额不足

4.4 续费记录设计

• 续费时新建 as_user_sub_member 记录，旧记录 status 置为 2（已到期）
• 同一 sub_id + user_id 只允许一条 status = 1 的记录（应用层强制）
• 历史续费记录完整保留，支持对账和退款审计

4.5 产品-计划 M:N 查询

-- 商品详情：该商品关联哪些订阅计划
SELECT sp.* FROM as_sub_plan sp
JOIN as_product_plan_rel r ON r.plan_id = sp.id
WHERE r.product_id = ?
ORDER BY r.sort_order;

-- 计划维度：哪些商品使用了该计划
SELECT p.* FROM as_sub_product p
JOIN as_product_plan_rel r ON r.product_id = p.id
WHERE r.plan_id = ? AND p.status = 1;

4.6 订阅到期定时任务（每日 02:00）

1. expire_time < now() + 7天 且 status=1 → 推送续费提醒通知（as_notification）
2. expire_time < now()       且 status=1 → 标记 status=2（已到期）
                                         → as_user_sub.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_order	order_no UNIQUE	订单号查询
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_banner	(start_time, end_time)	时间段筛选
as_recharge	(user_id, status)	充值记录查询
as_product_plan_rel	(product_id) / (plan_id)	M:N 双向查询

---

六、v2 → v3 变更记录

问题	类型	处理方式	结果
R1 充值流水缺失	🔴 严重	新增 as_recharge 表	✅ 已修复
R2 续费历史丢失	🔴 严重	移除 as_user_sub_member UNIQUE KEY；续费改为新建记录	✅ 已修复
I1 Banner 表缺失	🟠 重要	新增 as_banner 表	✅ 已修复
I2 M:N 逗号分隔	🟠 重要	新增 as_product_plan_rel；移除 sub_plan_ids 字段	✅ 已修复
I3 文档字段不一致	🟠 重要	本文档统一使用 v2 修订后字段名	✅ 已同步
L1 拼车凭据状态	🟡 轻微	as_user_sub_member.status 增加值 4=等待车主录入凭据	✅ 已修复
L2 索引规划缺失	🟡 轻微	补充 12 项关键索引（见上表）	✅ 已修复

表数量变化：v2（23张）→ v3（27张，新增 as_recharge / as_banner / as_product_plan_rel）

---

七、待决策项（需 Ami 确认）

#	问题	选项
1	付费方式一期支持哪些？	A) 仅余额（人工充值）B) 余额+支付宝 C) 三种都支持
2	拼车广场是否需要审核流程？	A) 管理员审核 B) 自动上架 C) 仅自营，无拼车广场
3	账号凭据展示方式？	A) 直接明文 B) 需二次验证 C) 限时展示（30s后隐藏）
4	邀请返现比例和条件？	需定义：金额/比例，是否有上限
5	sub_plan_ids 是否改关联表？	✅ v3 已改为关联表 as_product_plan_rel
6	提现功能是否一期上线？	A) 一期上 B) 二期（一期只充值不提现）

---

最后更新：2026-02-17 · v3