feat: add Phase D - system design (functions + business flows + DB design)
This commit is contained in:
阿米狗
371
SYSTEM_DESIGN.md
Normal file
371
SYSTEM_DESIGN.md
Normal file
@@ -0,0 +1,371 @@
|
|||||||
|
# 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** | 测试 + 上线 | — |
|
||||||
Reference in New Issue
Block a user