D12 用户自助与门户域 · 设计文档

本域总览见《账号计费中心 · 结构大纲》。本文为该域完整设计：定位与边界 / 角色与依赖 / 数据模型 / 核心流程 / 接口契约 / 关键约束与验收标准。

1. 定位与边界

定位：终端用户面对账号计费中心的唯一自助面与编排层。它把各能力域已落定的事实——现金余额、赠金额度、信用额度、用量与费用、订单与退款进度、站内信、组织与成员关系——装配成两套工作区视图（个人空间 / 企业空间），并把用户意图（充值、邀请、退出组织、重签协议、设置余额告警阈值）翻译为对能力域端点的调用。本域不产生新事实，只回答四件事：取谁的事实、在哪个工作区上下文取、以什么形态呈现、用户动作该调谁的端点。全文顺序即数据模型（事实结构来自上游）→ 核心流程（运行路径）→ 接口契约（对外投影）。

关键口径

边界

• 不管钱：现金余额、赠金、信用额度与流水的记账在钱包与账务域（D04），本域只读。
• 不管计量与计价：用量聚合与账单口径由计量与计费域（D05）实现，门户复用同一聚合函数。
• 不管订单状态机与退款：订单创建、回调验签、退款工单在订购与支付域（D03）、退款与对账域（D07）。
• 不管组织与成员语义：组织、成员关系、组与邀请的写语义在账号与身份域（D01）；本域只写入口与编排边界。
• 不管站内信生成与投递：落表与短信、邮件触达在通知与触达域（D10）；本域只读列表、已读与阈值设置。
• 不管协议版本与运营面：协议版本与重签判定在风控与合规域（D09）；平台侧页面与运营端点索引在 D11。

2. 角色与依赖

能力矩阵

门户角色的可见性与禁用口径

• 菜单可见性由工作区角色驱动：未声明角色的菜单对所有工作区可见，声明角色的菜单按当前工作区角色过滤；角色判定同时作用于菜单渲染与路由拦截，避免「菜单不显示但路径可达」。角色映射是纯函数（工作区形态 + 组织内角色 → 菜单角色），工作区落定即重算并双写内存与本地缓存，避免「菜单已换、判断仍用旧角色」。
• 操作级权限不止于菜单：邀请、改成员角色、移除成员只对所有者与管理员开放；角色变更另有「不得越权改同级别或更高角色」的判定，越权由服务端拒绝并回以角色不足的错误码。

上游依赖

本域被引用 / 被进入面（邀请链接接收者经入站页消费邀请码并调用接受邀请端点）

3. 数据模型

本域无自有表。事实载体有两类：其他域的表（客户、流水、赠金、用量、订单、站内信、组织与成员、组、用户与凭证、操作留痕）与其他域的端点（自助读写所依赖的能力出口）。本域对前者一律只读，对后者只做调用与编排。

• 门户与上游是单一方向：读事实、调动作，没有一条上游依赖门户的数据。
• 欠款只看现金余额符号，派生态与可用额度只用于展示与文案（宽限中不得报停服）。

3.3 表清单（本域无自有表，只读下列 12 表）

• 落点规则即四种情形的唯一答案：未登录落登录页（白名单路径除外）；无可见工作区落账号设置页且不清令牌；单工作区按后端回退口径直接落其首页；多工作区默认选最近使用、无活跃记录时回退最近加入的企业，仍无企业则落个人空间。
• 跨工作区旧路径的映射是纯函数：输入目标路径与查询参数、输出等价路径与查询参数（或空表示无需重定向），不依赖组件实例，可直接单测；映射先于角色拦截执行，避免旧链接被无权限页接收。
• 组织专属页（成员、部门组、企业信息）无个人等价物，反向映射一律回落个人工作台，避免死链。

• 切换后整页导航：菜单树与标签栏都必须按新工作区重建，上一工作区的标签在此工作区即死链，故先清缓存再导航。
• 个人与企业首次切换时给出一次性告知：两个空间的余额、凭据与用量相互独立，个人资产不会丢失（按账号每设备仅首次弹出）。

• 两张工作台共用同一个钱包端点，差异只在上下文：个人工作台取本人客户的钱包，企业工作台取当前组织的钱包，两者金额互不叠加。
• 欠款口径统一为现金余额为负；工作区不存在（被退出或注销）时页面转为引导态而非报错，并给出回个人空间的路径。

• 账单端点是一次请求三类结果：按日用量汇总（量对得上）、流水按类型聚合（钱对得上）、按模型聚合（费用构成）；每日趋势与费用构成复用同一过滤口径。
• 用量行带两个金额：实收费用与原应有费用（免计费行为零，原价另列），据此区分「用了多少」与「本该付多少」。
• 组织透视按维度组合（日期、组、成员、凭据展示名、模型）分组并支持导出，导出按用户可读名称列出行。

• 自定义金额与定额面额共用一次下单意图；意图变更（换渠道、换面额、改金额）即作废幂等键，防止「改了金额却拿到旧单」。
• 支付结果页不信任任何回跳参数：回跳只取订单号用于定位，入账一律由服务端渠道回调验签完成；页面状态完全由订单查询结果决定，查询失败单独成态并给重试；结果页四态为已支付、待支付、失败、订单不存在。
• 渠道列表由后端按四道闸门（凭据齐备、探活通过、已启用、灰度放行）下发，门户不硬编码渠道，杜绝「点了才被拒」。

• 订单号是页面与端点的唯一索引：详情按订单号取单条，列表由服务端返回后在前端按状态分组——待支付可继续支付或放弃，已支付可申请退款并按部分退款另标「部分已退」，失败、已取消与已过期为终态且不可再支付，退款中、退款处理中、已退款、退款失败与退款未知分别展示。
• 退款族状态复用订单状态字段回传，门户只做文案映射；限流与冷静期由服务端判定，门户按错误码提示，不做本地倒计时。

• 本域只提供入口与编排：成员、邀请、组、配额的语义与写入都在账号与身份域，门户不复制校验规则，只把服务端错误码映射为提示。
• 组织变更（创建、加入、退出、注销）之后统一走回落流程：按剩余工作区重算上下文与账户形态再整页导航，避免「组织已退出但页面仍停在企业上下文」。

• 未读数来自同一可见集合的计数，与列表同源，不额外聚合。
• 阈值是门户侧唯一可持久化的通知偏好（单位为元，允许 0 表示关闭）；触发与投递在通知与触达域，门户只负责展示与设置。
• 告警状态回显包含阈值、当前现金余额与是否已触发；保存后必须重新拉取完整状态，因为写入响应只回阈值，触发态需按最新余额重算。

• 弹窗不可关闭（无关闭按钮、遮罩与键盘退出均无效），保证「未同意不得继续使用」由交互强制。
• 拦截时机在登录后首次进入门户，而非某个具体动作；出口侧仍有服务端门禁兜底（未同意即拒绝下单等动作），两层不互相替代。

5. 接口契约

5.1 本域自有自助端点（前缀 /api/account，门户访问令牌）

• 本人用量默认窗口为最近 30 天，页大小上限 100；组织透视页大小上限 200，维度缺省为「组 × 日期」，非法维度以参数错误拒绝。
• 透视导出取全量聚合行（行数受维度组合约束，非原始流水全量）；流水导出行数上限一万行并按导出时间命名。
• 全部端点金额为元字符串；用量行同时给出实收费用与原应有费用；流水行不下发内部账务键；阈值取值 0 至 10000 元。

5.2 门户页面 → 被引用端点索引（语义详见对应域）

• 本表只登记门户页面实际引用的端点，各行语义归属对应能力域，本域不重复展开；组织上下文相关请求携带组织上下文请求头，服务端按所选组织解析数据与权限。
• 订单回跳与渠道回调在订购与支付域完成，门户只做订单查询与展示，不参与验签入账；企业退出、注销、创建与加入之后的落点重算在本域，属组织变更的编排收口。

5.3 前端契约

6. 关键约束与验收标准

6.1 约束

1. 零自有事实：本域不建表、不写账、不缓存派生金额；所有金额与状态来自上游端点返回。
2. 欠款只看现金符号：欠款提示与还款入口以现金余额为负为唯一依据，不读欠费派生标记、不读可用额度。
3. 上下文单一实现：工作区判定与角色映射都是纯函数，请求头注入、菜单过滤、落点解析共用同一产出。
4. 无可见菜单不清令牌：落账号设置页保留登录态，保证用户仍能完成资料与安全动作。
5. 落点四分支封闭：未登录落登录页；无工作区落账号设置页；单工作区直接落其首页；多工作区按最近使用、最近加入、个人空间三级回退。
6. 切换即整页重建：工作区切换与组织变更后必须整页导航并清掉上一工作区的标签页缓存。
7. 两空间资产隔离：个人与企业工作区的余额、凭据与用量互不可见、互不叠加，首次进入企业工作区必须给出资产独立告知。
8. 金额字符串通道：从端点返回到前端渲染全程字符串，禁止先转浮点再比较或再格式化。
9. 支付结果不信任回跳：回跳参数仅用于定位订单，入账由服务端回调验签完成；结果页状态以订单查询为准。
10. 下单幂等键随意图：一次下单意图一个幂等键，重试复用；意图变更即作废。
11. 渠道由服务端下发：门户不硬编码渠道与账户信息，未通过闸门的渠道不得出现在充值页。
12. 企业工作区的资金与成员管理收口到所有者与管理员：成员仅可见部门组与企业信息；余额告警阈值同样收口。
13. 错误码只做映射：门户不复制上游校验规则，只把服务端错误码映射为提示与引导。

6.2 验收标准

6.3 待后续设计细化的开放项

1. 组织级站内信的细粒度个人已读：现为组织内共享已读态；拆分为每成员一份需先定存储与迁移口径。
2. 通知偏好的可订阅面：现仅余额告警阈值可持久化，用量突增、组织关闭等类型的订阅开关是否开放、粒度到人还是到工作区待定。
3. 工作区切换的免整页刷新：改为局部热切换需要菜单树与标签栏的上下文隔离方案。
4. 费用中心的跨工作区合并视图与门户侧分页服务端化：跨企业消费汇总是否需要、欠款与停服口径如何呈现待定；订单列表现按全量返回前端分组，量级增长后需改为服务端过滤分页。