# Starlink

**Repository Path**: jack-che/starlink

## Basic Information

- **Project Name**: Starlink
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-07-20
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Starlink

## 项目简介
`Starlink` 是一套基于手机号维度、完整复刻三大通信运营商（移动/联通/电信）全核心业务的仿真系统，**以手机营业厅 APP 为主入口**，配套营业厅 Web 后台作为 B 端运营支撑；可模拟真实运营商计费、出账、套餐、风控等全链路业务逻辑，支持开发测试、业务教学、流程模拟、风控演练等场景。
本系统完全以**手机号**作为唯一核心主索引，所有用户资产、套餐、账单、通话、短信、流量、增值业务、权限均绑定手机号，1:1还原运营商生产级业务模型。

## 核心定位
1. **全业务覆盖**：复刻运营商个人通信全生命周期业务，无功能阉割；
2. **手机号唯一主键**：所有数据、操作、权限隔离均以手机号为核心维度；
3. **高仿真生产逻辑**：计费、出账、停机复机、携号转网、过户、销户、风控校验完全对标真实运营商规则；
4. **多端统一入口**：以**手机营业厅 APP 为主入口**（C 端用户统一触点），配套线下营业厅、小程序作为运营 / 备用渠道（100XX 客服热线、短信营业厅指令等历史渠道兼容见 § 六.可选模块（v2.x））；
5. **可扩展插件化**：支持新增套餐、增值业务、营销活动、风控规则、第三方接口。

## 技术栈
> 选型坚持"**2 人能长期维护**"的原则，框架与语言高度内聚（Node.js + TypeScript 一线到底）。任何与本表冲突的子文档以本表为准。

### 后端
- 核心框架：**NestJS**（装饰器驱动的 controller/service 分层与依赖注入，适合 2 人协作与单测）
- 语言：TypeScript（≥5.4）
- 数据库：**PostgreSQL 16+**（业务主库，使用 JSONB、行级锁 `SELECT ... FOR UPDATE`、声明式分区表）
- ORM：**Prisma**（与 TypeScript 类型一致性最好；以 `prisma migrate` 为主迁移工具）
- 缓存：Redis 7+（手机号缓存、会话、`real_time_resource` 实时计数；以 PG 为权威账）
- 中间件：RabbitMQ 3.13+（话单/短信/账单异步队列）、MinIO（电子存根、通话详单 PDF、实名照片）
- 鉴权：手机号验证码、服务密码、人脸核验、经办人授权（详见 `docs/04-接口设计/`）
- 定时任务：Node-Schedule（凌晨出账、月结、流量重置、过期业务回收；与 PG advisory lock 配套保证单实例串行）
- 配置：`config.yaml` + `dotenv`，按环境覆盖

### 前端（以手机端为主）
- **UniApp** 模拟手机营业厅 APP（**主入口 / 主交付物**，覆盖 iOS / Android / H5）
- Vue3 + Vant 移动端组件库
- 微信小程序模拟页
- H5 短信营业厅
- Vue3 + Element Plus 营业厅 Web 后台（B 端运营支撑工具，P2 / M3 启用，非主交付物）

### 基础设施
- Docker 一键部署
- Nginx 反向代理、接口限流
- Swagger 完整接口文档（按手机号维度分组）

## 一、以手机号为核心的数据模型设计
所有数据表均以 `phone`（手机号，char(11)）作为关联外键/唯一索引，核心实体关联关系：
```
手机号(phone)
├─ 用户基础信息（实名、身份证、归属地、运营商、在网状态）
├─ 账户资产（预存话费、赠款、冻结金额、信用额度）
├─ 主套餐（月租、流量包、语音包、短信包、生效/失效时间）
├─ 增值业务（彩铃、视频会员、来电显示、定向流量包）
├─ 实时资源（剩余流量、剩余语音、剩余短信、限速状态）
├─ 账单流水（月结账单、实时扣费记录、充值记录）
├─ 通信详单（通话记录、短信记录、上网日志）
├─ 业务工单（过户、补卡、停机、携号、销户、改套餐）
└─ 风控记录（欠费停机、高频骚扰、实名异常、号码冻结）
```

## 二、复刻运营商全核心业务模块（全部基于手机号操作）
### 1. 号码开户 & 实名入网（手机号生命周期起点）
- 选号池：号段归属运营商、归属地市、靓号分级、最低消费约束
- 实名核验：身份证录入、人脸校验、一证多号限制、实名档案绑定手机号
- 开户签约：选择主套餐、预存话费、开通基础业务（来电显示）
- 生成唯一手机号主账户，初始化流量/语音资源、计费周期

### 2. 账户与话费资产管理（手机号账户）
- 充值缴费：线上充值、线下营业厅缴费、代充、赠款发放
- 余额查询：通用余额、定向赠款、冻结资金、信用透支额度
- 扣费逻辑：实时计费（通话/短信/超额流量）、月结批量扣月租
- 欠费机制：低余额提醒、单向停机、双向停机、欠费滞纳金、补缴复机
- 发票管理：按手机号开具月结电子发票、充值发票、下载存根

### 3. 套餐与资源管理（手机号绑定套餐）
#### 基础套餐
- 更改主套餐、套餐升档/降档、次月生效/立即生效规则
- 套餐资源重置：每月1号流量语音清零结转规则（通用流量结转、定向不结转）
#### 叠加包业务
- 通用流量包、定向流量包、日包/小时包、语音加油包、短信包
- 包自动续订、取消续订、过期失效、超量限速/断网计费
#### 增值业务
- 彩铃、来电管家、视频会员、宽带融合、国际漫游包
- 订购、退订、到期自动续费、增值业务单独账单

### 4. 通信服务详单（手机号通信行为）
- 通话详单：主叫/被叫、通话时长、本地/长途/漫游、扣费金额、通话基站归属
- 短信详单：点对点短信、106营销短信、上行/下行、短信扣费
- 上网详单：流量消耗、APP定向流量抵扣、时段限速、4G/5G区分
- 详单查询限制：近6个月记录、实名核验鉴权、导出PDF详单

### 5. 号码状态运维全业务
- 停机保号：按月收取保号费、暂停通信、保留号码
- 复机：欠费补缴复机、保号到期复机、业务开通复机
- 挂失补卡：凭手机号+实名信息补办SIM卡、旧卡失效
- 过户：原机主+新机主双实名变更手机号持有人
- 携号转网：运营商迁出/迁入、号码保留、合约违约金计算
- 销户：余额退还、合约校验、号码冷冻回收、二次放号冷却期

### 6. 线上线下渠道业务（统一操作手机号）
**主入口（C 端用户统一触点）：**
1. 手机营业厅 APP：手机号验证码登录、自助办业务、查账单、充值、改套餐，作为 C 端用户首选渠道

**运营 / 备用渠道：**
2. 营业厅 Web 后台（B 端支撑工具）：人工受理所有业务、打印回执、实名纸质存根
3. 第三方渠道：微信 / 支付宝充值、第三方套餐营销办理
4. 微信小程序：复用 `uni-app-mobile/` 业务模块，作为 M1+ 的备用触点

> 历史渠道（100XX 客服热线、短信营业厅指令）当前不作为主线路，已下沉到 § 六.可选模块（v2.x）。

### 7. 计费与出账核心引擎（运营商核心）
- 实时话单解析：通话、短信、上网实时产生扣费流水
- 批价规则：套餐内资源优先抵扣，超出后阶梯单价计费
- 月结出账：每月固定日期生成账单、汇总月租/增值/超额费用
- 合约管控：合约期内改套餐/携号/销户违约金自动计算
- 对账模块：充值渠道对账、第三方分成、营收统计

### 8. 风控与号码安全体系
- 欠费风控：欠费停机、催收工单、黑名单手机号
- 骚扰风控：高频呼出、垃圾短信拦截、号码限制呼出
- 实名风控：一证五号超限、虚假实名锁定号码、二次核验
- 登录安全：手机号验证码、服务密码修改、登录设备记录、异常登录冻结

### 9. 融合附属业务（手机号为主账号）— 可选模块，见 § 六
- 手机号绑定宽带、IPTV、家庭共享套餐
- 副卡业务：主手机号共享流量语音、副卡独立话费账户
- 国际/港澳台漫游：开通漫游包、漫游计费规则、漫游关停

> 注：以上 3 项为可选模块（v2.x），与"以手机 App 为主"的主线弱相关，统一在 § 六.后续迭代规划中承接。

> 合规 / 数据销毁 / 隐私口径统一在 **§ 九** 沉淀，M0 启动前必须先看。

## 三、系统核心特性（手机号全量复刻亮点）
1. **手机号全局唯一隔离**
   所有接口、查询、业务操作必须传入手机号，数据行级隔离，不同手机号资产、账单、业务完全互不干扰。
2. **完整生命周期仿真**
   从开户→正常使用→停机保号→过户→携号→销户→号码回收放号全流程闭环，复刻真实运营商号码流转逻辑。
3. **真实计费规则复刻**
   套内抵扣、超额计费、结转、月租月结、赠款优先级、合约违约金1:1还原商用规则，可用于计费测试。
4. **多渠道操作数据互通**
   APP、营业厅、客服办理的同一手机号业务实时同步，工单统一归档，详单全局统一。
5. **可批量手机号批量操作**
   支持批量开卡、批量充值、批量停机、批量套餐变更，适用于企业批量测试场景。
6. **完整日志审计**
   手机号每一笔操作（充值、办业务、查询详单）留存操作人、渠道、时间、操作内容，满足运营商审计规范。

## 四、目录结构
```
Starlink/
├── docs/                          # 项目文档（中文主题目录，按项目生命周期顺序）
│   ├── 01-项目概览/                # 项目一句话定位、核心卖点、读者画像
│   ├── 02-需求分析/                # 需求分析组织约定（按 § 二模块 + § 八里程碑）
│   ├── 03-数据库设计/              # phone 为主键的数据库契约总览
│   ├── 04-接口设计/                # REST 风格、鉴权、响应 / 错误码、URL 约定
│   ├── 05-代码实现/                # server / uni-app-mobile / web-admin 的目录分层与 Commit 规范
│   ├── 06-联调测试/                # 单测 / 集成 / 契约 / E2E / 性能基线
│   └── 07-应用上线/                # Docker Compose、Nginx、Swagger 暴露、回滚与监控占位
├── server/              # 后端服务
│   ├── controller/      # 接口控制器（按手机号业务模块拆分）
│   ├── service/         # 核心业务逻辑（计费、开户、工单、风控）
│   ├── model/           # 数据库实体（全部以phone为主键）
│   ├── queue/           # 话单、账单异步队列消费
│   └── task/            # 月结、流量重置定时任务
├── uni-app-mobile/      # 模拟手机营业厅APP（C 端主入口 / 主交付物，iOS + Android + H5）
├── wx-miniapp/           # 微信小程序模拟页（M1 起，复用 uni-app-mobile 业务模块）
├── web-admin/            # 营业厅运营后台（B 端支撑工具，P2 / M3）
├── sql/                 # 初始化库表脚本（核心phone索引表）
├── docker/              # 容器部署脚本
├── config.yaml          # 运营商参数配置（月租、流量单价、停机规则）
└── README.md            # 本说明文档
```

## 五、适用场景
1. 通信行业开发测试：计费、套餐、工单功能自动化测试；
2. 高校通信专业教学：模拟运营商全业务实训平台；
3. 风控安全演练：模拟欠费、骚扰、实名异常等号码风险场景；
4. 营销活动仿真：批量手机号发放流量包、赠费活动验证；
5. 第三方对接调试：充值渠道、小程序、客服系统对接调试。


## 六、后续迭代规划
1. 新增5G专网、物联网卡业务（物联网卡号复用手机号核心模型）
2. 对接模拟短信网关、语音网关，生成真实通信话单
3. 增加大数据统计模块：手机号营收、套餐渗透率、欠费分析
4. 可视化业务流程画布，自定义套餐、计费规则配置
5. 支持多运营商并行模拟（移动/联通/电信独立号段池）

### 可选模块（v2.x）— 与"以手机 App 为主"主线弱相关，按团队余力排期
1. **融合附属业务**：手机号绑定宽带 / IPTV / 家庭共享套餐、副卡业务、国际 / 港澳台漫游
2. **历史渠道兼容**：100XX 客服热线（坐席查询 / 工单 / 投诉）、短信营业厅指令（短信查话费 / 办简单业务）

## 七、业务目标优先级（2 人团队 / MoSCoW）
团队规模 **2 人**，按"全栈 + 业务细分"分工：**首要差异化卖点 = 计费与对账仿真度（计费规则 1:1 还原运营商生产逻辑）**。下面按 MoSCoW 把 § 二的 9 大业务模块切成三档，方便排期与砍需求。

| 优先级 | 业务模块 | 阶段 | 2 人模块分配 | 核心交付物 | 对外亮点 |
|--------|----------|------|----------------|------------|----------|
| **P0** | **计费与出账核心引擎** | M0 | 计费模块主 | 实时话单解析、批价规则、套餐内资源优先抵扣、月结出账；合约违约金自动计算 / 月对账报表在 M2 持续补齐 | **计费规则 1:1 还原运营商生产逻辑**（兜底卖点） |
| **P0** | **账户与话费资产管理** | M0 | 账户模块主，APP 端协 | 充值缴费、余额查询、实时扣费、欠费停机、月结电子发票 | 手机 APP 主路径的资产底座 |
| **P0** | **手机营业厅 APP 主链路** | M0 | APP 模块主，账户 / 计费模块协 | UniApp APP 端到端：手机号登录、开户、充值、查账单、查流量、改套餐 | **以手机 APP 为统一用户触点**（C 端唯一入口） |
| **P1** | **套餐与资源管理** | M1 | 套餐模块主 | 基础套餐升档/降档、叠加包续订/退订、增值业务（彩铃、视频会员）、月内资源结转；批量 API（批量开卡/充值/停机/改套餐）随本里程碑一起交付 | 完整的套餐生命周期 |
| **P1** | **号码状态运维全业务** | M1 | 状态运维模块主，APP 模块协 | 停机保号、复机、挂失补卡、过户、携号转网、销户、二次放号冷却；批量停机/复机随本里程碑一起交付 | 真实号码流转逻辑闭环 |
| **P1** | **通信服务详单** | M1 | 详单模块主 | 通话/短信/上网详单、近 6 个月记录查询、PDF 导出、实名鉴权 | 详单全局统一可追溯 |
| **P1** | **风控与号码安全体系** | M2 | 风控模块主 | 欠费/实名/高频骚扰三类风控、操作审计全留存、登录设备与异常登录冻结 | 可用于高校/企业风控演练 |
| **P2** | **渠道非 APP 部分（同 § 六可选模块）** | M3 | 营业厅 Web / 第三方渠道模块主 | 营业厅 Web 后台（B 端运营）、第三方充值对接；微信小程序维持 wx-miniapp/ 现状，不在本里程碑新增 | 渠道补全 |
| **P2** | **融合附属业务** | M3+ | 融合业务模块主 | 手机号绑定宽带/IPTV、家庭共享、副卡、国际/港澳台漫游、5G 专网、物联网卡 | 后续业务延展 |
| **P2** | **可视化业务流程画布 + 多运营商并行模拟** | M3+ | 可视化与多号段模块主 | 自定义套餐 / 计费规则配置、移动 / 联通 / 电信独立号段池 | 教学与营销活动仿真 |

> 取消标准：任一里程碑若超过 6 周未完成目标，按 P2 优先级砍需求，不延期；P0 模块在任何阶段都不得砍。

## 八、项目里程碑（M0–M3 / 2 人 4 阶段）

本节是 § 七优先级表"阶段"列的**真源**——为团队节奏、交付物、验收口径提供统一锚点。

| 阶段 | 周期 | 目标 | 2 人分工（按模块拆账） | 主要交付物 |
|------|------|------|--------------------------------|------------|
| **M0 MVP 主链路** | 4–5 周 | 计费 + APP 主链路跑通 | 计费引擎 + 账户主，APP 端到端页面协 | 1) 手机号开户 / 登录；2) 充值；3) 月结出账；4) 实时话单扣费；5) 套餐内资源抵扣；6) APP 首屏账单与流量可视化 |
| **M1 业务闭环** | 4–5 周 | 完整号码生命周期 | 套餐 / 状态 / 详单后端主，套餐 / 状态 / 详单 APP 与小程序页面协 | 1) 改套餐（次月 / 立即生效）；2) 停机保号 / 复机；3) 挂失补卡 / 过户 / 携号转网 / 销户；4) 近 6 个月详单 + PDF 导出；5) **App 体验打磨 v1**（首屏可性化 + 操作埋点 + 扫码登录） |
| **M2 风控与计费增强** | 4–5 周 | 仿真度跃升 | 风控引擎 + 合约违约金 + 滞纳金主，风控运营后台 + 审计日志可视化协 | 1) 欠费 / 实名 / 高频骚扰三类风控上线；2) 合约违约金 / 滞纳金自动计算；3) 月对账报表；4) 全链路操作审计；5) **App 体验打磨 v2**（推送集成 + 离线缓存 + 人脸 / 指纹快捷登录） |
| **M3 多端扩展 + 持续运营** | 4+ 周 | 渠道 + 插件化 | 对接短信 / 语音网关 + 第三方充值主，营业厅 Web + 可视化套餐配置画布协 | 1) 100XX 客服工单；2) 营业厅 Web 后台；3) 可视化业务流程画布（在线配置套餐 / 计费）；4) 5G 专网 / 物联网卡雏形 |

**两条基本规则**

1. **2 人全栈 + 业务细分**：每人既写后端也写前端，但按业务模块拆账；M0 阶段为了跑通计费 + APP 主链路会临时"模块侧重"（计费后端由 1 人主推、APP 端到端由另 1 人主推），M1 起回归对等拆分；任何"主 / 协"标记都**不**指人员而是模块。
2. **里程碑取消标准**：任一里程碑超过 6 周未完成既定目标，按 P2 优先级砍需求，不延期；P0 模块在任何阶段都不得砍。

## 九、数据合规与隐私（手机号 + 实名档案为强敏感数据）

> 仿真系统也按真实运营商合规口径处理：身份证、人脸照片、服务密码一律视为强敏感数据，所有留存与销毁走本节约束；详细字段与加密策略见 `docs/03-数据库设计/`。

| 数据类型 | 加密 / 留存 | 销毁时机 | 备注 |
|----------|----------------|----------|------|
| 手机号 + 服务密码 | PBKDF2 / bcrypt 哈希；Redis 仅缓存 phone 索引 | 销户满 90 天强制清除（PG `user_info` 软删 → 冷库） | 30 天后从 Redis 强制驱逐 |
| 身份证号 | AES-256-GCM 加密列存，密钥走 KMS | 用户销户即时从 `user_info` 移除明文，仅保留哈希指纹 | 一证五号关联走 `risk_relation` |
| 人脸照片 | 落 MinIO（BOR 私桶 + 路径混淆），不与 PG 同行存 | 用户销户 30 天后清理对象，超期靠生命周期策略 | M2 启用"人脸照片不出库"约束（仅做特征比对） |
| 通话/短信/上网详单（CDR） | PG 分区表 + 上一年只读 | 详单保留 ≥ 6 个月（运营商查询口径）；满 5 年归档冷库 | 客户/教学查询统一走脱敏接口 |
| 操作审计（audit_log） | 只追加，PG 分区 | ≥ 5 年留存（与运营商审计规范对齐） | M2 启用，写入 `X-Internal-Token` 鉴权 |

**M0 必须落地**：
- [ ] 身份证 / 人脸 / 服务密码 字段加密与 KMS 占位
- [ ] 详单查询脱敏接口
- [ ] 销户触发 PII 即时回收任务（参考 `docs/03-数据库设计/` § 6 演进约束 + § 7 数据安全）