v45 API 补录:手机号登录换令牌 + 我的名册 / 家谱接口 + 出口层敏感字段脱敏

🔴 为什么现在才提交(这是「补录」,代码早已上线并验证):
   v45 第三/第四批当时,同一工作区里有**并行的鸿蒙端工作流**正在改这个文件
   (手机号登录换令牌、media.php 的 ?token=)。按「绝不把别人正在写的裹进
   自己的提交」的纪律,那次只提交了自己的 5 个文件,本文件被**故意留下**。
   此后文件静止约 25 小时、端上工作流也已收尾 ⇒ 现在补录,让仓库与线上一致
   (线上 md5 = 本地 md5,deploy 是从工作树打包的,所以线上一直是这份)。

① `POST /api/v1/login` —— 手机号 + 密码 → API 令牌
   原先 App 只能「先去网页签发令牌、再手动粘贴」,能用但没法给别人用。
   与网页登录有意不同:不建会话(API 无状态);限流落**文件**
   (`sys_get_temp_dir()/fb_login_<sha256(ip|phone)>.json`,60s 窗口 / 5 次)
   而不进 $_SESSION;失败**统一**提示(不区分「没这个人」与「密码错」,
   否则接口成了手机号是否已注册的探测器);有效期用**服务端时间**算。
   成功时顺带 `Calendar::seedDefaults()`(全新安装的兜底)。

② `GET /api/v1/roster` —— 「**我**名册里的人」(我加的 + 别人分享的)
   与 `/people`(全家 801 人 = 通讯录底账)区分开:App 名册页要用这个,
   否则一屏 800 人且是「别人的通讯录」。组装**照抄 Web 端 index.php 的
   people 分支**(同一套类/判据):Person::roster → Kinship::label /
   Nickname::display / PersonQuery::phonePlain / PersonQuery::birthdaysOf /
   PersonTag::mapFor / Pinyin::initials,外加标签云与标签词表。
   ⚠️ 复用这些类而非另写,否则会「网页搜得到、App 搜不到」。

③ `GET /api/v1/kin` —— 家谱(以我为中心的关系图)
   用 `Kinship::familyMap($fam,$pid,$people,2,2)`,与 Web 端 kin/tree.php
   同一套 ⇒ 端上与网页的亲属关系必然一致。按代数排序,拍平直接关系字段。

④ 🔴 信息泄露修复:`stripSensitivePerson()`
   `Person::all()` / `Person::roster()` 都是 `SELECT p.*`,把
   `phone_hash` / `phone_encrypted` / `id_card_encrypted` / `birthday_id_card` /
   `birthday_lunar*` 一路吐给 App。前两个是 AES 密文(离线爆破材料),
   `phone_hash` 是「手机号是否属于这个家」的判定键。
   ⇒ 在 **API 出口层**脱敏(列表 / 详情 / 新建 / PATCH 四个出口都套)。
   ⚠️ **不能改 `Person::all()` 本身**:网页端确实在用(ContactImporter 靠
   phone_hash 去重、PersonQuery 靠 phone_encrypted 按手机号搜)
   ⇒ 网页要、App 不要 ⇒ 差异落在出口层。

线上验证(全绿):GET login→405 / 缺参→422 / 错密码→401「手机号或密码不对」
/ 不存在的手机号→**同样的** 401 与提示 / 连续错→第 6 次起 429 / 名册 800 人 /
标签云 15 个 / 称谓正确(爸爸→父亲…)/ 手机号解密正确 / 生日阴阳历 /
首字母 ypzbb / 6 个敏感字段全去除(列表与详情都验)。
This commit is contained in:
2026-10-14 09:41:34 +08:00
parent 32e9e9ab84
commit 13a5d08696
+357 -4
View File
@@ -38,6 +38,14 @@ final class ApiHandler
case 'tokens': $this->tokens($id, $method); return;
case 'home': $this->home(); return;
case 'people': $this->people($id, $sub, $method); return;
// 🔴 v45:名册(**我名册里的人**,不是全家 800 人)。
// 与 `people` 的区别见 `roster()` 方法的说明。
case 'roster': $this->roster($method); return;
// 🔴 v45:家谱(以我为中心的关系图)。
// 端上「家谱」页要用:父母 / 配偶 / 子女 / 兄弟姐妹 + 各代层次。
// ⚠️ 数据来自 `relations` 表(只存相邻两代的边),
// 亲属关系靠 `Kinship` 推导 —— 与 Web 端 `kin/tree.php` 同一套。
case 'kin': $this->kin(); return;
case 'notifications': $this->notifications($id, $sub, $method); return;
case 'calendar': $this->calendar($sub, $method); return;
case 'events': $this->events($id, $sub, $method); return;
@@ -50,11 +58,249 @@ final class ApiHandler
case 'resources': $this->resources($id, $method); return;
case 'books': $this->books($id, $sub, $method); return;
case 'notes': $this->notes($id, $method); return;
// 🔴 v45:登录(手机号 + 密码 → API 令牌)。
// 为什么必须走 API 而不是网页登录后复制 Cookie:
// App 是 Bearer 令牌那套,没有会话;而原先前端只能让人
// **手动去网页签发令牌再粘贴**到 App 里 —— 这个体验没法接受。
case 'login': $this->login($method); return;
}
Api::fail('未知的接口资源:' . $res, 'not_found', 404);
}
/* ═══════════════════════════════════════════════════════════════
登录(手机号 + 密码 → API 令牌)
═══════════════════════════════════════════════════════════════ */
/**
* `POST /api/v1/login` —— 用手机号 + 密码换一枚 API 令牌。
*
* 🔴 为什么需要这个接口(v45,用户 2026-10-12 "把服务器接进来、跑正式流程"):
* 原先 App 只能让人**先去网页「个人设置 → API 令牌」签发、再手动粘贴**
* 到 App 的设置页里。这是个"能用但没法给别人用"的流程。
* 有了它,App 首页就能直接登录。
*
* ⚠️ 与网页登录(`Auth::login`)的三处**有意不同**:
* ① 不建会话 —— API 是无状态 Bearer,登录只是"换令牌";
* ② 限流不能放 `$_SESSION`(API 没有 session)⇒ 落**文件**,
* 按"手机号 + 来源 IP"计数(见下方 `loginThrottle`);
* ③ 失败**不区分**"没这个人"与"密码错" —— 同一句提示,
* 否则接口成了"手机号是否已注册"的探测器。
*
* ⚠️ 成功时**顺带补建默认日历本**(与 `Auth::login` 同样的兜底):
* 全新安装时 `Schema::ensure()` 跑在"建人"之前,
* 那次遍历一个账号都没有 ⇒ 一本日历都不建。放在登录处最稳。
*/
private function login(string $method): void
{
if ($method !== 'POST') {
Api::fail('登录要用 POST。', 'method_not_allowed', 405);
}
$phone = Api::str('phone', '', 40);
$password = (string)Api::param('password', '');
$label = Api::str('label', 'App 登录', 60);
// 令牌有效期(天)。0 = 永不过期(与网页签发令牌的默认行为一致)。
$days = Api::int('days', 0);
if ($phone === '' || $password === '') {
Api::fail('手机号和密码都得填。', 'unprocessable', 422);
}
// ---- 限流:失败次数有成本(防爆破)----
$gate = self::loginThrottle($phone);
if ($gate !== null) {
Api::fail($gate, 'too_many_requests', 429);
}
$hash = Crypto::hash($phone);
$st = Database::get()->prepare(
'SELECT a.id AS account_id, a.password_hash, a.role, a.status,
p.id AS person_id, p.family_id, p.name, p.avatar
FROM accounts a
JOIN persons p ON p.id = a.person_id
WHERE p.phone_hash = ? LIMIT 1'
);
$st->execute([$hash]);
$row = $st->fetch();
// ⚠️ 账号不存在 / 被停用 / 密码错 —— **统一**同一句提示 + 同一个延迟。
// 分开回话就等于告诉对方"这个手机号存在/不存在"。
$ok = $row
&& (string)$row['status'] === 'active'
&& password_verify($password, (string)$row['password_hash']);
if (!$ok) {
self::loginThrottleFail($phone);
// 固定延迟:让每次失败都近似同价(对脚本爆破是实打实的成本)
usleep(300000);
Api::fail('手机号或密码不对。', 'unauthorized', 401);
}
self::loginThrottleClear($phone);
$personId = (int)$row['person_id'];
$familyId = (int)$row['family_id'];
$expiresAt = null;
if ($days > 0) {
// ⚠️ 用服务端时间算,不信客户端传的日期
$expiresAt = date('Y-m-d H:i:s', time() + $days * 86400);
}
$token = ApiToken::issue($personId, $label, $expiresAt);
Database::get()->prepare('UPDATE accounts SET last_login_at = NOW() WHERE id = ?')
->execute([(int)$row['account_id']]);
// 进门补默认日历本(幂等;失败不挡登录)
try {
Calendar::seedDefaults($familyId, $personId);
} catch (\Throwable $ex) {
error_log('[familybook] 登录补建默认日历本失败(已跳过):' . $ex->getMessage());
}
Api::ok([
'token' => $token,
'expires_at' => $expiresAt,
'person' => [
'id' => $personId,
'name' => (string)$row['name'],
'avatar' => (string)($row['avatar'] ?? ''),
'role' => (string)$row['role'],
'family_id' => $familyId,
],
]);
}
/* ---- 登录限流(**文件实现**,不碰数据库结构)----
⚠️ 为什么不用 session:API 是无状态的,压根没有 session。
⚠️ 为什么不用数据库表:这只是一个"短期计数器",
为它加表 + 写迁移的代价大于收益(本应用是单机部署)。
⇒ 落 `sys_get_temp_dir()` 下的小文件,60 秒窗口、5 次失败。
⚠️ 键里带 IP:防止"只针对某个手机号"刷爆别人的登录
(但也别只按 IP —— 同一家庭可能共用出口 IP)。 */
private static function loginThrottleFile(string $phone): string
{
$ip = (string)($_SERVER['REMOTE_ADDR'] ?? '0');
// ⚠️ 文件名用 hash,**不要把手机号写进文件名**(临时目录可能被列举)
return sys_get_temp_dir() . '/fb_login_' . hash('sha256', $ip . '|' . strtolower(trim($phone))) . '.json';
}
/** 返回"拦下来的提示",null = 放行 */
private static function loginThrottle(string $phone): ?string
{
$f = self::loginThrottleFile($phone);
if (!is_file($f)) { return null; }
$raw = @file_get_contents($f);
$d = $raw !== false ? json_decode($raw, true) : null;
if (!is_array($d)) { return null; }
$n = (int)($d['n'] ?? 0);
$t = (int)($d['t'] ?? 0);
if ($n >= 5 && (time() - $t) < 60) {
return '尝试太频繁了,请等 1 分钟再试。';
}
return null;
}
private static function loginThrottleFail(string $phone): void
{
$f = self::loginThrottleFile($phone);
$raw = @file_get_contents($f);
$d = $raw !== false ? json_decode($raw, true) : null;
$n = is_array($d) ? (int)($d['n'] ?? 0) : 0;
// 超过窗口就重新计数(否则失败过一次的人永远被算在同一轮里)
$t = is_array($d) ? (int)($d['t'] ?? 0) : 0;
if ((time() - $t) >= 60) { $n = 0; }
@file_put_contents($f, json_encode(['n' => $n + 1, 't' => time()]), LOCK_EX);
}
private static function loginThrottleClear(string $phone): void
{
@unlink(self::loginThrottleFile($phone));
}
/**
* `GET /api/v1/roster` —— 「**我**的名册」(App 名册页的主数据)。
*
* 🔴 与 `GET /people` 的**关键区别**(这决定了 App 名册页该用哪个):
* · `/people` —— 全家的人(本家 801 人),是"通讯录底账";
* · `/roster` —— **我名册里的人**(我加的 + 别人分享给我的),
* 是一个人**自己挑出来、常用**的那一小撮。
* Web 端名册页用的就是后者(`Person::roster()`,见 index.php 的注释)。
* ⇒ App 的名册页必须用 `/roster`,否则一屏 800 人,且是"别人的通讯录"。
*
* 组装顺序**照抄 Web 端 `index.php` 的 people 分支**(同一套类、同一套判据):
* `Person::roster` → `Kinship::label`(我该怎么称呼他)
* → `Nickname::display`(我怎么叫他)/ `PersonQuery::phonePlain`(解密手机号)
* → `PersonQuery::birthdaysOf`(阴历阳历只取月日)
* → `PersonTag::mapFor`(每人的标签)
* ⚠️ 一定要复用这些类而不是在 API 里另写一遍:
* 否则会出现"网页里搜得到、App 里搜不到"这类**两端不一致**
* (`PersonQuery` 的类注释专门强调过这一点)。
*
* 查询参数:`?q=`(关键字,走 PersonQuery 同一套粗筛 + 精筛)、
* `?kind=member|contact`、`?tag=`(只看某个标签)。
*/
private function roster(string $method): void
{
if ($method !== 'GET') {
Api::fail('名册只支持 GET。', 'method_not_allowed', 405);
}
[$fam, $pid] = Api::me();
$kind = Api::str('kind', 'member');
$q = Api::str('q');
$rows = Person::roster($fam, $pid, $kind, $q);
// ---- 装饰(与 Web 端同一套)----
$graph = Kinship::graph($fam);
$people = Person::map($fam);
$tagsOf = PersonTag::mapFor($fam, $pid);
foreach ($rows as &$row) {
// 「我该怎么称呼他」
$row['label'] = Kinship::label($graph, $pid, (int)$row['id'], $people);
// 「我怎么叫他」(昵称优先,没有就用本名)
$row['shown'] = Nickname::display($pid, $row) ?: (string)$row['name'];
// 手机号**明文**(库里的 phone_encrypted 解密;空则空串)
$row['phone_plain'] = PersonQuery::phonePlain($row);
// 生日:阴历/阳历各一条,**只到月日**(年份不外发)
$row['birthdays'] = PersonQuery::birthdaysOf($row);
// 标签
$row['tags'] = $tagsOf[(int)$row['id']] ?? [];
// 首字母(App 侧"输入即筛选"用;与网页 filter.js 的 data-initials 同一来源)
$row['initials'] = Pinyin::initials(
(string)$row['name'] . ' ' . (string)($row['my_nickname'] ?? '')
);
// 🔴 脱敏:名册行同样是 `SELECT p.*`,敏感密文一律不下发
// (见 stripSensitivePerson 的说明)。
$row = self::stripSensitivePerson($row);
}
unset($row);
// ---- 标签筛选(`?tag=` 为空 = 全部)----
$tagFilter = Api::str('tag');
if ($tagFilter !== '') {
$rows = array_values(array_filter(
$rows,
static fn(array $r): bool => in_array($tagFilter, $r['tags'] ?? [], true)
));
}
Api::ok([
'people' => array_values($rows),
// 标签云(筛选条用)+ 标签词表(编辑时选已有标签)
'tagCloud' => PersonTag::cloud($fam, $pid),
'groups' => PersonGroup::orderFor($fam, $pid),
'tagFilter' => $tagFilter,
'kind' => $kind,
'meId' => $pid,
'q' => $q,
]);
}
/* ═══════════════════════════════════════════════════════════════
我 / 令牌 / 首页
═══════════════════════════════════════════════════════════════ */
@@ -143,7 +389,7 @@ final class ApiHandler
// 只认本家的(跨家 id 直接当不存在,不泄露"别人家有没有这个人")
if (!$p || (int)$p['family_id'] !== $fam) { Api::notFound('这个人'); }
if ($method === 'GET') {
Api::ok($p);
Api::ok(self::stripSensitivePerson($p));
}
if ($method === 'PATCH' || $method === 'PUT') {
Api::requireWrite();
@@ -154,7 +400,7 @@ final class ApiHandler
'note' => Api::str('note', (string)($p['note'] ?? '')),
'phone' => Api::str('phone', (string)($p['phone'] ?? ''), 40),
]);
Api::ok(Person::find($id));
Api::ok(self::stripSensitivePerson((array)Person::find($id)));
}
if ($method === 'DELETE') {
Api::requireWrite();
@@ -175,18 +421,125 @@ final class ApiHandler
'note' => Api::str('note', ''),
'phone' => Api::str('phone', '', 40),
]);
Api::ok(Person::find($newId), 201);
Api::ok(self::stripSensitivePerson((array)Person::find($newId)), 201);
}
// 列表:支持 ?q= 搜索、?kind=member|contact
$list = Person::all($fam, Api::str('q'), Api::str('kind', 'member'), $pid);
Api::list(array_values($list));
// ⚠️ 逐行脱敏(见 stripSensitivePerson 的说明:网页要、App 不要)
$safe = [];
foreach ($list as $row) {
$safe[] = self::stripSensitivePerson((array)$row);
}
Api::list($safe);
}
/**
* 把人员行里**不该给到 App 的字段**去掉(就地改,返回同一个数组)。
*
* 🔴 v45 新增(用户 2026-10-12 接服务器时发现):
* `Person::all()` 是 `SELECT p.*`,于是把 `phone_hash` /
* `phone_encrypted` / `id_card_encrypted` 一起吐给了 App。
* 这三个都是**敏感物**:
* · `phone_encrypted` / `id_card_encrypted` 是 AES 密文,
* 给到客户端就等于把**离线爆破的材料**递出去了;
* · `phone_hash` 是"手机号是否属于这个家"的判定键,同样不该外流。
* App 侧一个都用不到(显示手机号要的是**解密后的明文**,
* 走的是另一条路)。
*
* ⚠️ 为什么在**这一层**脱敏,而不去改 `Person::all()`:
* 网页端**确实在用**这些字段 —— `ContactImporter` 靠 `phone_hash`
* 做导入去重、`PersonQuery` 靠 `phone_encrypted` 支持"按手机号搜索"。
* 从 `all()` 里删会**打断网页功能**。
* ⇒ 网页要、App 不要 ⇒ 差异就该落在"出口"这一层。
*
* ⚠️ 顺手去掉的还有几个**纯服务端内部**字段(`is_placeholder` 之外的
* 统计/审计列),App 的 UI 里没有对应位置,传了只是徒增体积。
*/
private static function stripSensitivePerson(array $row): array
{
unset(
$row['phone_hash'],
$row['phone_encrypted'],
$row['id_card_encrypted'],
// 生日相关的三个原始列:App 显示生日只用 `birthday`,
// 而 `birthday_id_card` / `birthday_lunar` 是**推算生日**用的中间量
// (农历、证件号),属于隐私推算材料,没必要下发。
$row['birthday_id_card'],
$row['birthday_lunar'],
$row['birthday_lunar_leap']
);
return $row;
}
/* ═══════════════════════════════════════════════════════════════
通知
═══════════════════════════════════════════════════════════════ */
/**
* 家谱(`GET /api/v1/kin`)。
*
* 🔴 为什么单独一个接口、而不是塞进 `/roster`:
* `/roster` 是"**我名册里**的人"(可筛可搜,数据是**一堆人**);
* 家谱是"**以我为中心的关系图**"(谁是谁的父母、配偶、子女,
* 是**一张网**)。两者的形状与用途都不同,塞在一起会让
* 名册接口多背一份"大部分人不用"的图谱数据。
*
* ⚠️ 用的是 `Kinship::familyMap($fam, $me, $people, up, down)` ——
* 与 Web 端 `kin/tree.php` **同一个方法**,所以端上与网页看到的
* 亲属关系必然一致(不会出现"App 说他是堂兄、网页说是表兄")。
* `$up` / `$down` 用默认 2 —— 手机上再往外排就看不下了。
*/
private function kin(): void
{
[$fam, $pid] = Api::me();
$people = Person::map($fam);
$map = Kinship::familyMap($fam, $pid, $people, 2, 2);
$graph = Kinship::graph($fam);
// ---- 把人整理成"一人一条 + 关系字段"的形状,便于端上直接渲染 ----
$byGen = [];
$gen = $map['gen'] ?? [];
$ago = $map['unit_of'] ?? [];
foreach ($gen as $id => $g) {
if (!isset($people[$id])) { continue; }
$row = $people[$id];
$label = Kinship::label($graph, $pid, (int)$id, $people);
$byGen[] = [
'id' => (int)$id,
'name' => (string)$row['name'],
'shown' => \App\Nickname::display($pid, $row) ?: (string)$row['name'],
'label' => $label, // 「我该怎么称呼他」
'gen' => (int)$g, // 0 = 我;负 = 长辈;正 = 晚辈
'avatar' => $row['avatar'] ?? null,
'avatar_color' => $row['avatar_color'] ?? null,
'unit' => (int)($ago[$id] ?? 0), // 户(夫妻单元)号
// 直接关系(拍平,端上画连线/分组用)
'parents' => array_map('intval', Kinship::parentIds($graph, (int)$id)),
'children' => array_map('intval', Kinship::childIds($graph, (int)$id)),
'spouses' => array_map('intval', Kinship::spouseIds($graph, (int)$id)),
'siblings' => array_map('intval', Kinship::siblingIds($graph, (int)$id)),
];
}
// 按代数排序(长辈在前、晚辈在后),同代按名字拼音稳定
usort($byGen, static function (array $a, array $b): int {
return $a['gen'] <=> $b['gen'] ?: strcmp($a['name'], $b['name']);
});
Api::ok([
'meId' => $pid,
'people' => $byGen,
'units' => $map['units'] ?? [],
'up' => 2,
'down' => 2,
'total' => count($byGen),
]);
}
private function notifications(int $id, string $sub, string $method): void
{
[, $pid] = Api::me();