From e293a8e5a9d5fc0e796366e6eb638e85ef748c7e Mon Sep 17 00:00:00 2001 From: skycurtain Date: Sun, 11 Oct 2026 22:41:43 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20R16=20=E6=88=90=E5=91=98=E6=A1=A3?= =?UTF-8?q?=E6=A1=88=E4=BF=AE=E6=94=B9=E4=B8=8E=E7=A9=BA=E5=A3=B3=E5=88=A0?= =?UTF-8?q?=E9=99=A4=E8=A3=81=E5=86=B3=E5=85=A5=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 成员操作面扩为可改 name/remark、key_count=0 时硬删空壳；软删除仍是账本实体默认语义。 --- README.md | 12 +++++------ docs/design/API契约-公共约定.md | 4 ++-- docs/design/API契约-管理面.md | 17 +++++++++++---- docs/design/members表字段设计.md | 33 ++++++++++++++++++++---------- docs/design/交互设计-审计日志.md | 4 ++-- docs/design/交互设计-总览与共性.md | 2 +- docs/design/交互设计-成员管理.md | 32 +++++++++++++++++++++-------- docs/design/需求清单.md | 16 ++++++++++++++- 8 files changed, 85 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 7b04b1a..f5ee917 100644 --- a/README.md +++ b/README.md @@ -136,7 +136,7 @@ docker compose down # 全停（数据在卷里，不丢） | 文档 | 什么时候读 | 状态 | |------|-----------|------| -| [`docs/design/需求清单.md`](docs/design/需求清单.md) | **需求权威索引与裁决档案**——R1–R15 全部定案；含支付拆表裁决 | 定稿（2026-10-09） | +| [`docs/design/需求清单.md`](docs/design/需求清单.md) | **需求权威索引与裁决档案**——R1–R16 定案；含支付拆表与成员档案/空壳删除裁决 | 定稿（2026-10-10） | | [`docs/design/技术选型.md`](docs/design/技术选型.md) | 技术栈裁决：全栈 TS；Bun + Hono + Drizzle/pg；前端 Vue 3 + antdv-next；分层落地与回退 | 定稿（2026-10-02） | | [`docs/design/api_keys表字段设计.md`](docs/design/api_keys表字段设计.md) | key 登记、生命周期与成员归属 | 定稿（2026-10-01） | | [`docs/design/usage_logs表字段设计.md`](docs/design/usage_logs表字段设计.md) | 日志明细、来源提列、去重与写入策略 | 同上 | @@ -144,7 +144,7 @@ docker compose down # 全停（数据在卷里，不丢） | [`docs/design/subscriptions表字段设计.md`](docs/design/subscriptions表字段设计.md) | 订阅权益：期间 + 额度预算 + 可选付款事实；`subscription_id` 直连日志 | 待审阅（2026-10-09） | | [`docs/design/topups表字段设计.md`](docs/design/topups表字段设计.md) | 充值入账事件：`paid_at` 主轴；不挂订阅 | 待审阅（2026-10-09） | | [`docs/design/qpu_history表字段设计.md`](docs/design/qpu_history表字段设计.md) | 换算参数时间线（自动采样、只读） | 定稿（2026-10-01） | -| [`docs/design/members表字段设计.md`](docs/design/members表字段设计.md) | 成员实体——key 归属、成员视图身份与按成员统计的锚点 | 同上 | +| [`docs/design/members表字段设计.md`](docs/design/members表字段设计.md) | 成员实体——key 归属、身份与统计锚点；档案可改、空壳可删 | 定稿（2026-10-10） | | [`docs/design/users表字段设计.md`](docs/design/users表字段设计.md) | 管理员（单行）——登录体系的身份落点 | 同上 | | [`docs/design/sessions表字段设计.md`](docs/design/sessions表字段设计.md) | 管理面会话——cookie 令牌的服务端对应物 | 同上 | | [`docs/design/交互设计-总览与共性.md`](docs/design/交互设计-总览与共性.md) | 交互总纲：访问拓扑、导航、跨页组件、状态与数值呈现约定 | 定稿（2026-10-01） | @@ -153,11 +153,11 @@ docker compose down # 全停（数据在卷里，不丢） | [`docs/design/交互设计-调用日志.md`](docs/design/交互设计-调用日志.md) | 调用日志：筛选、明细表、与 key/成员/总览的跳转链 | 定稿（2026-10-08） | | [`docs/design/交互设计-key管理.md`](docs/design/交互设计-key管理.md) | 登记（sk-key 唯一界面露面）、启停、归属、死亡显形 | 定稿（2026-10-01） | | [`docs/design/交互设计-支付记录.md`](docs/design/交互设计-支付记录.md) | 支付记录（两 Tab）：订阅权益 / 充值入账登记、核对提示 | 待审阅（2026-10-09） | -| [`docs/design/交互设计-成员管理.md`](docs/design/交互设计-成员管理.md) | 开户、令牌签发/重发（明文仅一次）、停用 | 定稿（2026-10-01） | -| [`docs/design/交互设计-审计日志.md`](docs/design/交互设计-审计日志.md) | 管理操作留痕时间线 | 同上 | +| [`docs/design/交互设计-成员管理.md`](docs/design/交互设计-成员管理.md) | 开户、档案修改、令牌签发/重发、启停、空壳删除 | 定稿（2026-10-10） | +| [`docs/design/交互设计-审计日志.md`](docs/design/交互设计-审计日志.md) | 管理操作留痕时间线 | 定稿（2026-10-10） | | [`docs/design/交互设计-成员视图.md`](docs/design/交互设计-成员视图.md) | 成员视图三页（总览 / 调用日志 / 支付参数）；订阅徽章展开 + 调用详情 | 定稿（2026-10-09） | -| [`docs/design/API契约-公共约定.md`](docs/design/API契约-公共约定.md) | API 总纲：路由隔离与鉴权两档、错误信封、时间 / 数值 / 分页 / 命名 | 定稿（2026-10-02） | -| [`docs/design/API契约-管理面.md`](docs/design/API契约-管理面.md) | 管理面 18 端点 | 待审阅（2026-10-09） | +| [`docs/design/API契约-公共约定.md`](docs/design/API契约-公共约定.md) | API 总纲：路由隔离与鉴权两档、错误信封、时间 / 数值 / 分页 / 命名 | 定稿（2026-10-10） | +| [`docs/design/API契约-管理面.md`](docs/design/API契约-管理面.md) | 管理面 18 端点 | 待审阅（2026-10-09 支付拆表）；R16 定稿 | | [`docs/design/API契约-成员视图.md`](docs/design/API契约-成员视图.md) | 成员视图 3 端点：`/me` · `/overview` · `/logs` | 待审阅（2026-10-09） | | [`docs/design/同步引擎设计.md`](docs/design/同步引擎设计.md) | 独立 `apps/engine`：轮次、失败只记录、`engine_status` 快照 | 已实现（定稿 2026-10-05） | | [`docs/references/NewAPI-接口范围.md`](docs/references/NewAPI-接口范围.md) | 上游可用接口参考：鉴权档位、字段语义、实测行为、源码出处（**唯一上游参考**） | 事实依据 | diff --git a/docs/design/API契约-公共约定.md b/docs/design/API契约-公共约定.md index bd36efb..acdd183 100644 --- a/docs/design/API契约-公共约定.md +++ b/docs/design/API契约-公共约定.md @@ -4,7 +4,7 @@ | 项目 | 内容 | |------|------| -| 状态 | 定稿（2026-10-02） | +| 状态 | 定稿（2026-10-02；R16 修订 2026-10-10） | | 关联 | 《交互设计-总览与共性》（§1 访问拓扑 · §3 呈现约定）·《交互设计-登录与会话》（鉴权档位与 401 分流）· 各篇表字段设计（DTO 字段权威）·《技术选型》§4（DTO 类型属 `packages/core`） | | 产出 | 路由前缀与隔离机制 · 鉴权两档 · 错误信封 · 时间 / 数值 / 分页 / 命名约定 | @@ -15,7 +15,7 @@ - JSON over HTTP，UTF-8；请求与响应体均为 `application/json` - 一套路由代码，两个世界靠**路径前缀与凭证中间件物理隔离**（共性 §1：令牌进不了管理面、会话进不了成员视图） - DTO 类型定义于 `packages/core`，web 以纯类型依赖引用——前后端一份契约类型（技术选型 §4 依赖规则） -- **端点面向交互设计，不与数据表对齐**——每个端点对应一个功能面（页面 / 流程需要什么）；表只是存储模型，按其事实性质获得恰好够用的操作面（引擎专写表纯只读、人工抄录表全 CRUD、账本实体软删除） +- **端点面向交互设计，不与数据表对齐**——每个端点对应一个功能面（页面 / 流程需要什么）；表只是存储模型，按其事实性质获得恰好够用的操作面（引擎专写表纯只读、人工抄录表全 CRUD、账本实体软删除为主——**空壳例外可硬删**：无 key 归属的成员行不承载账本事实，见 R16） ## 2. 路由前缀与隔离机制 diff --git a/docs/design/API契约-管理面.md b/docs/design/API契约-管理面.md index 61fb8ae..1dd0bef 100644 --- a/docs/design/API契约-管理面.md +++ b/docs/design/API契约-管理面.md @@ -4,7 +4,7 @@ | 项目 | 内容 | |------|------| -| 状态 | 待审阅（2026-10-09 支付拆表修订——§7） | +| 状态 | 待审阅（2026-10-09 支付拆表修订——§7）；R16 定稿（2026-10-10——§8） | | 关联 | 《API契约-公共约定》（定稿——总纲）· 八篇交互设计 · `api_keys` / `usage_logs` / `subscriptions` / `topups` / `qpu_history` / `members` / `users` / `sessions` 表字段设计（DTO 字段权威）· `需求清单.md` §9（访问主体模型） | | 产出 | 端点清单、请求 / 响应字段、错误码、本稿裁定项（§10）与遗留项（§11） | @@ -29,7 +29,7 @@ | 13 | `/api/admin/topups/:id` | PUT / DELETE | 编辑 / 删除 | | 14 | `/api/admin/qpu/latest` | GET | 当前换算率（表单美元双输入用） | | 15 | `/api/admin/members` | GET / POST | 成员清单 / 开户（令牌明文仅一次） | -| 16 | `/api/admin/members/:id` | PATCH | 停用 / 启用 | +| 16 | `/api/admin/members/:id` | PATCH / DELETE | 档案修改（name/remark）与启停 / 空壳删除（仅 `key_count = 0`） | | 17 | `/api/admin/members/:id/token` | POST | 令牌重发（明文仅一次） | | 18 | `/api/admin/audit-logs` | GET | 审计日志（分页） | @@ -259,7 +259,16 @@ ### PATCH `/api/admin/members/:id` → 200 `member` -`{ "status": "disabled" }` / `active`——停用即成员视图访问立即失效（令牌校验含状态判断）。 +部分更新，单字段或并存均可，审计按实际变更字段各落一行（§9）： + +- `{ "status": "disabled" }` / `active`——停用即成员视图访问立即失效（令牌校验含状态判断） +- `{ "name": "小张" }` / `{ "remark": "同事" }`（R16 档案修改）——`name` 冲突 `409 member_name_taken`；不接受 `token_hash` / `created_at` / `id` + +非法值 `422`；成员不存在 `404`。 + +### DELETE `/api/admin/members/:id` → 204 + +空壳删除（R16）：**仅当该成员当前 `key_count = 0`**（无任何 `api_keys.member_id` 指向）才物理删除行；否则 `409 member_has_keys`（`fields` 可附 `key_count`）。删除后名称 UNIQUE 释放、令牌一并作废。名下有 key 的清理路径 = 停用（软删除语义不变）。均落审计。 ### POST `/api/admin/members/:id/token` → 201 @@ -285,7 +294,7 @@ |----|------------| | key | `key.register` / `key.enable` / `key.disable` / `key.reassign`（归属变更） | | payment | `subscription.create` / `subscription.update` / `subscription.delete` / `topup.create` / `topup.update` / `topup.delete`（UI 菜单「支付记录」） | -| member | `member.create` / `member.enable` / `member.disable` / `member.token_issue`（开户自动签发）/ `member.token_reissue` | +| member | `member.create` / `member.update`（档案改 name/remark）/ `member.enable` / `member.disable` / `member.token_issue`（开户自动签发）/ `member.token_reissue` / `member.delete`（空壳硬删） | | account | `account.password_change` / `account.init`（系统，operator null） | 每个管理面写操作各落一行；查询类与成员侧动作不留痕。**表结构归技术稿（members / api_keys 表设计既有标注），立稿时以本文 DTO 字段为对齐锚点**（§11 遗留 2）。 diff --git a/docs/design/members表字段设计.md b/docs/design/members表字段设计.md index e794c3c..32f3582 100644 --- a/docs/design/members表字段设计.md +++ b/docs/design/members表字段设计.md @@ -4,8 +4,8 @@ | 项目 | 内容 | |------|------| -| 状态 | 定稿（2026-10-01） | -| 关联 | `docs/design/api_keys表字段设计.md` 3.9（归属列指向本表）· `docs/design/需求清单.md` §9 | +| 状态 | 定稿（2026-10-01；R16 修订 2026-10-10） | +| 关联 | `docs/design/api_keys表字段设计.md` 3.9（归属列指向本表）· `docs/design/需求清单.md` §9（访问主体模型）· R16（档案可改、空壳删除） | | 范围 | 列结构 + 语义 + 写入时机；令牌生成细节归技术稿；方言映射归数据访问层设计 | | 字段数 | 7 = 1 主键 + 6 业务字段 | @@ -21,13 +21,13 @@ | 列 | 类型 | 值来源 | 说明 | |----|------|--------|------| -| `id` | bigserial PK | 自增 | | -| `name` | text UNIQUE | 管理面录入 | 显示名——账目与视图中的署名 | -| `remark` | text | 管理面录入 | 备注（联系方式、是谁等；可空） | -| `status` | text | 管理面 | `active` / `disabled`——停用即成员视图访问立即失效（令牌校验含状态判断） | -| `token_hash` | text | 管理面生成令牌时 | 成员视图的访问凭证（哈希存储，明文只在生成时展示一次） | -| `token_issued_at` | timestamptz | 同上 | 当前令牌的签发时间（审计线索） | -| `created_at` | timestamptz | 开户时 | | +| `id` | bigserial PK | 自增 | 不可改 | +| `name` | text UNIQUE | 管理面录入（可改） | 显示名——账目与视图中的署名；开户后可改（R16） | +| `remark` | text | 管理面录入（可改） | 备注（联系方式、是谁等；可空）；开户后可改（R16） | +| `status` | text | 管理面启停 | `active` / `disabled`——停用即成员视图访问立即失效（令牌校验含状态判断）；**不并入档案编辑** | +| `token_hash` | text | 管理面生成令牌时 | 成员视图的访问凭证（哈希存储，明文只在生成时展示一次）；仅随重发更新 | +| `token_issued_at` | timestamptz | 同上 | 当前令牌的签发时间（审计线索）；仅随重发更新 | +| `created_at` | timestamptz | 开户时 | 不可改 | ## 3. 决策记录（含理由） @@ -45,17 +45,28 @@ 账目署名不可歧义。 -### 3.4 软删除（`status`）而非物理删除 +### 3.4 软删除（`status`）为主，空壳例外硬删（R16） -成员名下的 key 与历史用量是账本的一部分——「退拼」是停用（保留行、停访问），不是抹掉事实。 +成员名下的 key 与历史用量是账本的一部分——「退拼」是停用（保留行、停访问），不是抹掉事实。**默认无物理删除**。 + +**空壳例外（R16）**：当前 `key_count = 0`（无任何 `api_keys.member_id` 指向本行）时允许硬删——该行不承载账本事实，删了只清掉误建/未使用的开户壳，并释放 UNIQUE 名称。名下有 key 一律拒绝删除（只能停用）。硬删与软删除不冲突：账本实体的默认语义仍是软删除，空壳删是「无账本可保」时的清理通道。 + +### 3.5 档案字段可改（`name` / `remark`）（R16） + +- **动机**：开户后挂 key 前发现名称不对（误建、占位名）——已发出令牌时「改名」优于「删了重建」（重建会作废旧令牌） +- **可改字段收窄**：仅 `name` / `remark`；`status` / 令牌 / `id` / `created_at` 各走各的生命周期，不并入档案编辑 +- **`name` 仍 UNIQUE**（3.3 不变）；冲突 `409 member_name_taken` +- **展示口径 = 当前名**：日志 / 总览 / 成员视图联查实时取 `members.name`（与 `api_keys.token_name` 的「当前名为准」同则）——历史署名随改名漂移，可接受 ## 4. 写入时机 | 时机 | 动作 | |------|------| | 开户（管理面） | INSERT（`name` / `remark`；生成令牌 → `token_hash` + `token_issued_at`） | +| 档案修改（R16） | UPDATE `name` 和/或 `remark` | | 停用 / 启用 | UPDATE `status` | | 重发令牌 | UPDATE `token_hash` + `token_issued_at`（旧令牌即失效） | +| 空壳删除（R16） | DELETE（仅 `key_count = 0`；名下有 key 拒绝） | 以上全部为管理面写操作，均落**审计日志**（审计为独立需求，表结构归技术稿）。 diff --git a/docs/design/交互设计-审计日志.md b/docs/design/交互设计-审计日志.md index f02babb..446a56c 100644 --- a/docs/design/交互设计-审计日志.md +++ b/docs/design/交互设计-审计日志.md @@ -4,7 +4,7 @@ | 项目 | 内容 | |------|------| -| 状态 | 定稿（2026-10-01） | +| 状态 | 定稿（2026-10-01；R16 修订 2026-10-10） | | 关联 | `需求清单.md` §9（访问主体模型·审计日志条目）· `members/users表字段设计.md`（写入时机中「落审计」的动作全集） | | 数据 | 审计日志表（表结构归技术稿——本文锁定信息结构与展示） | @@ -27,7 +27,7 @@ |----|------| | Key | 登记 / 启用 / 停用 / 归属变更 | | 支付记录 | 订阅 / 充值登记、编辑、删除 | -| 成员 | 开户 / 停用 / 启用 / 令牌签发 / 令牌重发 | +| 成员 | 开户 / 档案修改（名称/备注）/ 停用 / 启用 / 令牌签发 / 令牌重发 / 空壳删除 | | 账号 | 改密 /（空库重建为系统事件，记「初始化」） | - 每类管理面写操作一行留痕——操作者列当前恒为作者（单管理员），但**审计是不可变历史，操作者归属不能事后补写**：保留该列是前向兼容（未来若扩展多管理员 / 权限引擎，历史记录自然区分），也是审计语义的自描述原则（who did what when 的 who 是本体字段） diff --git a/docs/design/交互设计-总览与共性.md b/docs/design/交互设计-总览与共性.md index 3952489..4b8e70a 100644 --- a/docs/design/交互设计-总览与共性.md +++ b/docs/design/交互设计-总览与共性.md @@ -28,7 +28,7 @@ | 菜单 | 页面 | 职责一句话 | |------|------|-----------| | 总览 | 全员总览 | 健康与用量全景（首页，登录后落地） | -| 成员管理 | 成员清单 | 开户、令牌、停用 | +| 成员管理 | 成员清单 | 开户、档案修改、令牌、启停、空壳删除 | | Key 管理 | key 清单 | 登记、启停、归属 | | 支付记录 | 记录清单 | 订阅/充值登记、核对 | | 调用日志 | 请求明细 | 全池模型请求查询与筛选 | diff --git a/docs/design/交互设计-成员管理.md b/docs/design/交互设计-成员管理.md index 8964754..c379354 100644 --- a/docs/design/交互设计-成员管理.md +++ b/docs/design/交互设计-成员管理.md @@ -1,11 +1,11 @@ # 交互设计 · 成员管理 -> 成员实体的操作面：开户、令牌签发与重发（明文仅展示一次）、停用。访问主体模型中「凭证事务经作者」的落点。 +> 成员实体的操作面：开户、档案修改（名称/备注）、令牌签发与重发（明文仅展示一次）、停用/启用、空壳删除。访问主体模型中「凭证事务经作者」的落点。 | 项目 | 内容 | |------|------| -| 状态 | 定稿（2026-10-01） | -| 关联 | 《交互设计-总览与共性》· `members表字段设计.md`（软删除、令牌不过期）· R12（成员视图的锚点） | +| 状态 | 定稿（2026-10-01；R16 修订 2026-10-10） | +| 关联 | 《交互设计-总览与共性》· `members表字段设计.md`（软删除、档案可改、空壳删除）· R12（成员视图的锚点）· R16 | | 数据 | `members` 全表 · 名下 key 聚合 | --- @@ -22,13 +22,21 @@ | 状态 | active / disabled 徽章 | | 令牌签发时间 | `token_issued_at`（提示「明文已不可找回，如需新令牌请重发」） | | 名下 key 数 | 聚合计数（hover 列出 key 名） | -| 操作 | 重发令牌 / 停用（或启用） | +| 操作 | 编辑 / 重发令牌 / 停用（或启用）/ 删除（见 §5 条件） | ## 2. 开户 表单：名称（必填、唯一性校验）、备注（可空）→ 提交 → **自动生成令牌** → 明文展示对话框（见 §3） -## 3. 令牌签发与重发（敏感操作的标准交互） +## 3. 档案修改（名称 / 备注）（R16） + +- **入口**：卡片操作「编辑」→ 小对话框（或行内编辑，实现期定） +- **可改字段**：名称（必填、唯一性校验）、备注（可空）——**仅此两项** +- 不含启停、不含令牌（各自走 §4 / §5 / 既有重发）；`created_at` 等只读展示 +- 名称冲突提示与开户一致（「名称已被占用」） +- 典型场景：误建/占位名 → 挂 key 前改名；已发出令牌时改名优于删除重建（重建会作废旧令牌） + +## 4. 令牌签发与重发（敏感操作的标准交互） **明文展示对话框**（开户自动触发，或重发触发）： @@ -38,12 +46,20 @@ - **重发**的确认弹窗先行：「重发后旧令牌立即失效（该成员正在用的访问将中断）」→ 确认 → 新明文对话框 - 对话框关闭后，界面任何地方不再出现明文（库里只有哈希——members 3.1） -## 4. 停用 / 启用 +## 5. 停用 / 启用 · 空壳删除 + +**停用 / 启用**： - 停用：确认弹窗「停用后该成员的视图立即不可访问（令牌验证含状态检查）；数据保留」——退拼 / 令牌疑似泄露的标准动作 - 启用：直接启用（下一请求即恢复） -- 软删除语义：**无删除按钮**——成员与其历史用量是账本事实，只有停用（members 3.4） +- 软删除语义仍是账本实体默认：名下有 key 的成员**只有停用**（members 3.4） -## 5. 空态 +**空壳删除（R16）**： + +- **条件**：仅 `key_count = 0` 时露出「删除」；名下有 key 则隐藏或禁用并提示「名下仍有 key，只能停用」 +- 确认弹窗：「删除后不可恢复（名称与令牌一并作废）；仅清理未挂 key 的空壳」→ 删除 +- 典型场景：误建、从未使用的开户行——清壳，避免停用行越积越多 + +## 6. 空态 「还没有成员——为每位分摊朋友开户并发放访问令牌」 diff --git a/docs/design/需求清单.md b/docs/design/需求清单.md index 084b36b..b528c56 100644 --- a/docs/design/需求清单.md +++ b/docs/design/需求清单.md @@ -4,7 +4,7 @@ | 项目 | 内容 | |------|------| -| 状态 | 定稿（2026-10-01） | +| 状态 | 定稿（2026-10-01；R16 定稿 2026-10-10） | | 关联 | `README.md`（背景、动因与架构约束）· 各篇表字段设计 · `docs/references/NewAPI-接口范围.md`（可用接口参考） | | 取代 | 《设计议题》（2026-09-29 由本清单取代；其中双形态裁决与 CFW 调研结论已并入本文 §5/§7） | @@ -57,6 +57,7 @@ |---|------|------|------| | R11 | 平台身份体系与鉴权 | 访问主体 = 作者 + 成员（运营方完全信任，不设身份）。**成员身份与管理面鉴权均已裁决**（2026-09-29，见裁决记录） | **已裁决**（2026-09-29） | | R12 | 成员自助视图 | 令牌进成员视图：**名下 key 的模型调用日志**——每条记录额外携带所属订阅/充值的信息（具体携带形态待核查后设计）+ 用量聚合（quota / 美元，按来源分解）；**完全公开透明**（订阅与支付参数对成员可见）；无「应付」概念（分摊是社交层问题）；登录壳交互（输令牌 → sessionStorage，关标签失效） | **已裁决**（2026-09-29） | +| R16 | 成员档案维护与空壳删除 | **修改**：开户后可改 `name` / `remark`（误建、挂 key 前改名等真实场景）；`status` 走启停、令牌走重发，不并入档案编辑。**删除**：仅当**当前无任何 key 归属**（`key_count = 0`）才允许硬删——清理空壳，不触碰账本事实；名下有 key 只能停用（软删除语义不变） | **已裁决**（2026-10-10） | ## 5. 交付域（已裁决） @@ -92,6 +93,8 @@ **需求阶段收官（2026-10-01）**：15 项全部有归宿——R1 / R2 / R5 / R6 / R7 / R8 / R9 / R11 / R12 / R13 / R14 / R15 已裁决关闭，R10 裁撤，R3 / R4 延后（提案存档见 §9）。表字段设计与交互设计均经作者逐篇审阅**定稿**；其后 API 契约与同步引擎设计亦已立稿。 +**增补（2026-10-10）**：R16（成员档案维护与空壳删除）已裁决——成员操作面由「开户 / 启停 / 重发」扩为含档案修改与条件硬删；随 members / API / 交互三线落地。 + ## 9. 裁决记录 ### 2026-09-29 · 访问主体模型（R11 · R12 · 关联 R5） @@ -164,6 +167,17 @@ - **展示仍称「支付记录」**：管理面一菜单两 Tab；成员「支付参数」两组清单；R7/R8/R9 哲学不变（只存事实、`subscription_id` 直连、币种无关） - **原 `payments表字段设计.md` 删除**，由两篇表设计替代；契约与交互随拆表修订 +### 2026-10-10 · 成员档案维护与空壳删除（R16） + +**动机**：开户后挂 key 前发现名称不对（误建、占位名）——改比重发/重建好（令牌已发出时重建会作废旧令牌）；另有从未使用的开户空壳需要清理，停用行会越积越多。 + +**裁决**： + +- **修改成员档案**：允许改 `name` / `remark` 两字段。`status` 与令牌不并入档案编辑（仍走启停 / 重发，生命周期语义不变）；`id` / `created_at` / `token_hash` / `token_issued_at` 不可直接改。`name` 仍 UNIQUE（账目署名不可歧义，members 3.3）；冲突 `409 member_name_taken`。**展示口径 = 当前名**（日志 / 总览 / 成员视图联查实时取 `members.name`，与 key 的 `token_name` 同则——历史账目署名随改名漂移可接受） +- **删除成员（条件硬删）**：**仅当 `key_count = 0`（当前无任何 `api_keys.member_id` 指向）** 才允许物理删除。理由：用量事实经 key 归属联查，空壳行不承载任何账本事实；硬删释放 UNIQUE 名称，便于「删了重建」。名下有 key → 拒绝删除（`409`），只允许停用——**软删除仍是账本实体的默认语义**，硬删只是空壳例外 +- **与支付删除的分界**：支付记录是人工抄录、改错即修（全 CRUD）；成员是账本锚点，默认软删除——空壳硬删不突破该哲学（无账本可保） +- **审计**：`member.update`（改名/改备注，按实际变更字段落痕）· `member.delete`（摘要含删除时名称）；均属管理面写操作 + ### 2026-09-29 · 数据资产域延后（R3 / R4） **裁决：不纳入现阶段**（锦上添花能力，核心功能实现后再议）。提案存档如下，供重启讨论时作起点：