work_flow_ishare/SYSTEM_DESIGN.md

iShare 系统设计文档

优先级：最高（先于所有开发任务） 版本：v1.0 日期：2026-02-17

---

一、系统角色

角色	说明
普通用户	注册登录，购买合租商品，获取账号凭据
车主（发布者）	发布自己的合租位（个人拼车广场）
平台运营（管理员）	管理平台数据、自营商品、用户、订单
超级管理员	全局配置，含财务、权限管理

---

二、功能模块清单

2.1 用户端 H5 功能

模块	功能点
账号	手机号注册/登录、邮箱注册/登录、找回密码（验证码）、微信/社交登录（二期）
首页	平台分类Tab、推荐商品卡片、Banner 广告位、热门合租榜
商品列表	按平台类型筛选、按价格/评分排序、关键词搜索
商品详情	平台介绍、套餐选择（月/季/年）、评价列表、剩余席位数、立即购买
购买流程	选套餐 → 确认订单 → 支付（余额/在线支付）→ 获取账号凭据
我的订阅	当前有效订阅列表、账号凭据查看、续费、退订
广场/拼车	浏览他人发起的合租位、申请加入、发起自己的合租
推广中心	邀请码、邀请记录、返现奖励记录
钱包	余额查看、充值、提现（二期）、流水记录
通知	续费提醒、订单状态变更、系统公告
个人中心	基本信息编辑、头像、安全设置（改密）、退出登录

2.2 管理后台功能

模块	功能点
平台管理	平台CRUD、平台分类CRUD、图标上传
订阅计划管理	计划CRUD、付费方案CRUD（多地区/多货币）
自营商品管理	商品CRUD、上下架、库存（账号）管理、绑定账号凭据
订单管理	订单列表、状态查看、人工审核、退款处理
用户管理	用户列表、封禁/解封、余额调整、查看订阅记录
评价管理	评价列表、违规删除
财务管理	收入统计、提现申请审核（二期）、优惠券管理（二期）
通知配置	系统通知模板、续费提醒开关
系统配置	站点信息、支付配置、短信/邮件配置

---

三、核心业务流程

3.1 用户注册/登录

[用户] → 输入手机/邮箱
       → 获取验证码（短信/邮件）
       → 验证 → 首次登录自动注册 app_user
       → 生成 JWT Token（复用 pigx-auth）
       → 进入首页

3.2 购买合租商品（核心流程）

[用户] → 浏览商品列表（as_sub_product, status=上架）
       → 商品详情页
         ├── 查看剩余席位 = capacity - capacity_loaded（来自 as_user_sub 聚合）
         └── 选择付费方案（as_sub_payroll）
       → 点击"立即购买"
       → 创建订单（as_order, status=待支付）
       → 支付
         ├── 余额支付 → 扣减 as_wallet.balance
         └── 在线支付 → 支付宝/微信回调 → 更新订单状态
       → 支付成功
         ├── 订单状态 → 已支付 → 使用中
         ├── 创建 as_user_sub 记录（capacity_loaded +1）
         ├── 返回账号凭据（as_sub_account 解密后展示）
         └── 推送通知（订阅成功）

3.3 账号凭据查看

[用户] → "我的订阅" → 选择订阅
       → 验证身份（二次密码/生物识别，可选）
       → 从 as_sub_account 查询 account_name + account_passwd
       → AES 解密 account_passwd（服务端解密，不返回明文密钥）
       → 展示账号密码（可设置自动隐藏倒计时）

3.4 订阅到期/续费

[定时任务（每日凌晨）]
  → 扫描 as_user_sub.expire_time < now() + 7天
  → 发送续费提醒通知（as_notification）
  → 到期当日：as_user_sub.status = expired
  → capacity_loaded -1（释放席位）

[用户续费]
  → 进入"我的订阅" → 点击续费
  → 选择续费套餐 → 走购买流程（复用）
  → 续费成功：as_user_sub.expire_time 延长

3.5 广场拼车（个人发布）

[车主]
  → 填写合租信息（平台、计划、价格、总席位数、说明）
  → 创建 as_sub_product（product_type=2 个人）
  → 提交审核 → 管理员审核通过 → 上架（status=active）

[拼车者]
  → 广场浏览 → 找到心仪的拼车
  → 申请加入 → 走购买流程
  → 成功后 → 车主将账号凭据录入 as_sub_account
  → 拼车者可查看凭据

3.6 推广/邀请

[用户A] → 分享邀请码/链接
[用户B] → 点击链接注册
         → as_invite 记录（inviter=A, invitee=B）
[用户B首次购买成功]
  → 触发返现奖励
  → as_wallet_log 记录（用户A 获得返现）
  → as_wallet.balance 增加

---

四、数据库设计（完整版）

4.1 现有表评审与修订

⚠️ 现有设计问题

表	问题	修订方案
as_sub_account	passwd_salt 是 int，不够安全；缺加密字段标记	改为 varchar salt，加 encrypt_type 字段
as_sub_account	缺 status 字段（账号可能失效/被封）	加 status: 0=正常,1=失效,2=异常
as_user_sub	缺 status、start_time、expire_time	补充状态和时间字段
as_user_sub	remark 字段类型是 int（应为 varchar）	改为 varchar
as_sub_product	缺 status（上架/下架/售完）、available_seats	补充状态和实时剩余席位
as_sub_product	sub_plan_ids 用逗号分隔（反范式）	评估是否改为关联表（影响查询）
as_sub_payroll	缺促销价/折扣字段	加 original_price、discount_rate
as_platform_type	platform_type 是 int，0=全部 含义混乱	改用独立 sort_order + is_all 标志位

4.2 核心业务表（完整版）

保留现有（修订后）

• as_platform
• as_platform_type
• as_sub_plan
• as_sub_payroll（加 original_price, discount_rate）
• as_sub_account（加 status, encrypt_type, 改 passwd_salt 为 varchar）
• as_sub_product（加 status, available_seats）
• as_sub_product_comment
• as_user_sub（加 status, start_time, expire_time, 改 remark 为 varchar）

新增表

---

as_order — 订单表

字段	类型	说明
id	bigint PK	订单ID
order_no	varchar(32)	订单号（唯一，业务用）
user_id	bigint	购买用户
product_id	bigint	商品ID (as_sub_product)
payroll_id	bigint	付费方案ID (as_sub_payroll)
amount	decimal(10,2)	实付金额
original_amount	decimal(10,2)	原价
discount_amount	decimal(10,2)	优惠金额
pay_type	tinyint	支付方式: 1=余额, 2=支付宝, 3=微信
pay_no	varchar(64)	第三方支付单号
status	tinyint	0=待支付, 1=已支付, 2=已完成, 3=已退款, 4=已取消
user_sub_id	bigint	关联的用户订阅ID (创建后填充)
remark	varchar	备注
expire_time	datetime	订单过期时间（未支付自动取消）
pay_time	datetime	支付时间
create_time	datetime
update_time	datetime

---

as_wallet — 用户钱包

字段	类型	说明
id	bigint PK
user_id	bigint UNIQUE	用户ID（一人一钱包）
balance	decimal(10,2)	可用余额
frozen_amount	decimal(10,2)	冻结金额（待退款/提现）
total_income	decimal(10,2)	累计收入
total_expense	decimal(10,2)	累计支出
create_time	datetime
update_time	datetime

---

as_wallet_log — 钱包流水

字段	类型	说明
id	bigint PK
user_id	bigint	用户ID
amount	decimal(10,2)	金额（正=收入，负=支出）
type	tinyint	1=充值, 2=消费, 3=退款, 4=邀请返现, 5=提现
order_id	bigint	关联订单ID（可空）
balance_after	decimal(10,2)	操作后余额（快照）
remark	varchar	说明（如"订阅 Netflix 高级版"）
create_time	datetime

---

as_invite — 邀请关系

字段	类型	说明
id	bigint PK
inviter_id	bigint	邀请人用户ID
invitee_id	bigint	被邀请人用户ID
invite_code	varchar(16)	使用的邀请码
reward_amount	decimal(10,2)	返现金额
reward_status	tinyint	0=待发放, 1=已发放（首次购买后触发）
create_time	datetime
reward_time	datetime	返现时间

---

as_notification — 通知消息

字段	类型	说明
id	bigint PK
user_id	bigint	目标用户ID（0=全部用户）
title	varchar	通知标题
content	varchar	通知内容
type	tinyint	1=续费提醒, 2=订单通知, 3=系统公告, 4=邀请奖励
ref_id	bigint	关联业务ID（如订单ID、订阅ID）
is_read	tinyint	0=未读, 1=已读
create_time	datetime

---

app_user 字段补充

在现有 PigX 的 app_user 表上，补充以下字段（via ALTER）：

字段	类型	说明
invite_code	varchar(16) UNIQUE	用户的专属邀请码（注册时生成）
inviter_id	bigint	邀请人用户ID（注册时记录）

---

4.3 完整 ER 关系图

as_platform_type (1) ──< (N) as_platform         [platform_type]
as_platform      (1) ──< (N) as_sub_plan          [platform_id]
as_sub_plan      (1) ──< (N) as_sub_payroll       [sub_plans]
as_sub_plan      (N) >──< (N) as_sub_product      [sub_plan_ids]
as_sub_product   (1) ──< (N) as_sub_product_comment [product_id]
as_sub_product   (1) ──< (N) as_sub_account       [product_id]
as_sub_plan      (1) ──< (N) as_sub_account       [sub_plan_id]
as_sub_payroll   (1) ──< (N) as_sub_account       [sub_payroll_id]

as_sub_product   (1) ──< (N) as_order             [product_id]
as_sub_payroll   (1) ──< (N) as_order             [payroll_id]
as_order         (1) ──< (1) as_user_sub          [user_sub_id]

as_sub_plan      (1) ──< (N) as_user_sub          [plan_id]
as_sub_account   (1) ──< (N) as_user_sub          [main_account]

app_user (1) ──< (1) as_wallet                    [user_id]
as_wallet (1) ──< (N) as_wallet_log               [user_id]
as_order  (1) ──< (N) as_wallet_log               [order_id]

app_user (1) ──< (N) as_order                     [user_id]
app_user (1) ──< (N) as_user_sub                  [user_id]
app_user (1) ──< (N) as_sub_product               [user_id — 发布者]
app_user (1) ──< (N) as_sub_account               [user_id — 账号持有者]
app_user (1) ──< (N) as_sub_product_comment       [user_id]
app_user (1) ──< (N) as_notification              [user_id]

app_user (1) ──< (N) as_invite [as inviter]       [inviter_id]
app_user (1) ──< (1) as_invite [as invitee]       [invitee_id]

4.4 as_user_sub 状态机

     购买成功
[pending] ──────→ [active] ──→ 到期 ──→ [expired]
                     │                      │
                     │ 退款/申请退订         │ 续费
                     ↓                      ↓
                 [cancelled]           [active]

状态值：0=待激活, 1=使用中, 2=已到期, 3=已退订

4.5 as_order 状态机

[pending] → 15分钟未支付 → [cancelled]
[pending] → 支付成功 → [paid] → 激活订阅成功 → [completed]
[paid/completed] → 退款申请 → 审核通过 → [refunded]

---

五、接口设计要点

5.1 账号凭据安全

• account_passwd 使用 AES-256-GCM 加密存储
• 密钥由服务端持有（存配置中心/环境变量），不入库
• passwd_salt 用于 AES 的 IV（改为 varchar(32)，16字节随机）
• 凭据查看接口：仅限订阅状态为 active 的用户，且需校验 as_user_sub.user_id == currentUser
• 返回解密后的明文，但 不记录日志（防止泄露）

5.2 席位并发控制

• 购买时使用 数据库乐观锁 或 Redis 分布式锁 防止超卖
• as_sub_product.available_seats 在下单时 -1（乐观锁 version 字段）
• 订单取消/超时后 +1 回补

5.3 价格一致性

• 订单金额在创建时 快照 到 as_order.amount
• 不依赖付费方案的实时价格（防止价格变动导致差异）

---

六、设计待决策项（需 Ami 确认）

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

---

七、调整后的项目阶段

阶段	内容	时间
Phase D（当前·最高优先）	系统设计：功能清单 + 业务流程 + 数据库设计	进行中
Phase 0	环境搭建：仓库 + Fork PigX + CI/CD + 建库 SQL	D 完成后
Phase 1	后端核心 CRUD API	1-2周
Phase 2	管理后台前端	1周
Phase 3	用户端 H5	2-3周
Phase 4	支付集成	按需
Phase 5	测试 + 上线	—