持久化用户历史消费泥点投影
后台用户详情展示历史花费并保留手动对账 消费落账原子更新投影并提供存量初始化 为手动对账增加独立管理员操作权限 更新SpacetimeDB绑定、文档和测试
This commit is contained in:
@@ -248,7 +248,7 @@
|
||||
## 2026-07-14 后台账号采用 owner 引导账号与一级 Tab 实时授权
|
||||
|
||||
- 背景：后台此前只支持一组环境变量管理员，所有 `/admin/api/*` 共用统一 admin 门禁，无法给运营、审核等人员分配独立账号和页面范围。
|
||||
- 决策：现有 `GENARRATIVE_ADMIN_USERNAME/PASSWORD` 账号固定作为不可编辑 owner；新增 member 独立保存到私有 `admin_account` 表，密码使用 Argon2id 摘要。登录凭据快照与普通账号快照在类型层分离，普通列表、按 ID 查询和写入响应不包含 `password_hash`。Argon2id 在 blocking 任务中运行并由 api-server 有界限流；未知、停用和 owner 错密账号使用 dummy hash 抹平耗时。member 权限粒度固定为后台 18 个一级 Tab，“账号管理”只允许 owner 且不可授予 member。member 每次请求重新读取当前账号并校验启停、`token_version` 和 Tab 权限；权限、密码或启停变化递增版本并立即淘汰旧 JWT。账号不存在返回 `401`，SpacetimeDB 故障保留 `502/503` 而不清理有效 token。前端导航过滤和页面挂载门禁只负责体验，正式授权由 api-server 的 API-to-Tab 矩阵执行，未登记的新后台路由对 member 默认拒绝。后台面向运营展示管理员身份时统一使用 `displayName`；持久审计仍保存稳定 subject，由 api-server 解析显示名称，前端不得暴露账号 ID 或用登录用户名代替。写接口必须在主事务前加载显示名目录，或在主事务后降级解析，不能把已提交写入伪装为失败。
|
||||
- 决策：现有 `GENARRATIVE_ADMIN_USERNAME/PASSWORD` 账号固定作为不可编辑 owner；新增 member 独立保存到私有 `admin_account` 表，密码使用 Argon2id 摘要。登录凭据快照与普通账号快照在类型层分离，普通列表、按 ID 查询和写入响应不包含 `password_hash`。Argon2id 在 blocking 任务中运行并由 api-server 有界限流；未知、停用和 owner 错密账号使用 dummy hash 抹平耗时。member 常规权限粒度固定为后台 15 个一级 Tab，“账号管理”只允许 owner 且不可授予 member；2026-07-24 起，历史花费手动对账作为独立高风险操作权限 `profile-wallet-consumption-reconcile`，不随任意 Tab 自动授予。member 每次请求重新读取当前账号并校验启停、`token_version`、Tab 权限和独立操作权限；任一权限、密码或启停变化递增版本并立即淘汰旧 JWT。账号不存在返回 `401`，SpacetimeDB 故障保留 `502/503` 而不清理有效 token。前端导航和操作按钮过滤只负责体验，正式授权由 api-server 路由权限矩阵执行，未登记的新后台路由对 member 默认拒绝。后台面向运营展示管理员身份时统一使用 `displayName`；持久审计仍保存稳定 subject，由 api-server 解析显示名称，前端不得暴露账号 ID 或用登录用户名代替。写接口必须在主事务前加载显示名目录，或在主事务后降级解析，不能把已提交写入伪装为失败。
|
||||
- 影响范围：`admin_account`、SpacetimeDB typed procedures / client facade、后台 JWT 与 session DTO、`/admin/api/accounts*`、后台路由权限中间件、admin-web 导航和账号管理页。
|
||||
- 验证方式：SpacetimeDB schema / client / API 定向测试、`npm run check:admin-account-procedures` 隔离 procedure smoke、完整路由矩阵测试、admin-web 权限路由与账号 API 测试、owner/member 浏览器 smoke、`npm run check:spacetime-schema`、编码与 diff 门禁。
|
||||
- 关联文档：`docs/technical/【后台管理】多账号与Tab访问权限方案-2026-07-14.md`。
|
||||
@@ -4502,3 +4502,11 @@
|
||||
- 决策：普通手机号认证请求统一使用可选 `countryCode` 与必填 `purePhoneNumber`，省略国家码时默认中国大陆 `86`，直接替换旧 `phone` 字段。前端把浏览器 E.164 自动填充值拆成这两个字段；后端先验证国家码，再复用纯手机号规范化并生成 E.164 存储。
|
||||
- 微信边界：小程序客户端仍只上传 `wechatPhoneCode`；`platform-auth` 必须要求微信成功响应中的 `phoneNumber`、`countryCode` 与 `purePhoneNumber` 均存在且非空，但只使用后两项执行国家码校验和 E.164 构造。腾讯官方仅说明境外 `phoneNumber` 会带区号，并未承诺 E.164 格式，中国号码示例中它与纯号码相同，因此不得校验 `phoneNumber == +{countryCode}{purePhoneNumber}`。微信字段缺失时失败关闭，不能使用普通请求的 `86` 默认值。
|
||||
- 数据边界：认证投影与 SpacetimeDB 的 `phone_number_e164` 保持不变，不新增国家码或纯号码列，也不需要 schema 迁移或 bindings 生成。
|
||||
|
||||
## 2026-07-24 后台用户详情展示历史花费泥点
|
||||
|
||||
- 口径：`historicalConsumedPoints` 表示用户历史总消费，只累计 `profile_wallet_ledger.source_type = asset_operation_consume` 且 `amount_delta < 0` 的绝对值；`asset_operation_refund` 不冲减，充值退款追回、余额重置、赠送和退款 hold 均不计入。
|
||||
- 投影边界：新增 `profile_wallet_consumption_total`，已有投影时消费流水成功落账在同一 SpacetimeDB 事务内按主键 O(1) 原子累加；退款不回减。首次上线在停止业务写入的维护窗口由 owner 调用 `POST /admin/api/profile/users/initialize-consumption-projections`，一次扫描全部权威钱包流水，为每个已有钱包流水的用户建立存量投影，成功后才能恢复流量。维护遗漏或新用户缺行时，首次消费和 runtime service identity 受限的 `admin_get_profile_wallet_detail_and_return` 都可按用户索引兜底重建一次；消费事务重建已包含当前流水，不重复加本次金额。不得用最近 50 条流水列表近似，也不得把全量流水扫描塞进充值订单每行复用的通用钱包快照。
|
||||
- 对账边界：保留管理员显式手动对账。owner 始终可用；member 必须单独持有 `profile-wallet-consumption-reconcile` 独立操作权限，任意 Tab 都不隐式授予。`POST /admin/api/profile/users/reconcile-consumption` 经二次确认后调用 runtime service identity 受限 procedure，扫描该用户全部权威流水、比较并校准投影，记录管理员与对账时间。
|
||||
- 展示边界：现有共享“用户详情”弹窗的钱包区增加“历史花费”，前端只展示 BFF 顶层字段，不自行汇总账单；只有 BFF 返回 `canReconcileConsumption=true` 时展示手动对账按钮。
|
||||
- 验证方式：SpacetimeDB 钱包聚合测试、api-server / admin-web 定向测试、`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run check:spacetime-runtime-access`、`npm run admin-web:typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
|
||||
@@ -3363,3 +3363,10 @@
|
||||
- 处理：灰度页只能以 `/admin/api/feature-gates` 为数据源，固定目标列表只登记现役功能；新增或退役业务 target 只修改固定目标注册，不得让通用页面依赖业务列表接口。旧 `creation-entry:*` 目标、接口和页面保持退役。
|
||||
- 验证：`adminRoutes` 必须包含 `gray-release`，admin-web TypeScript/ESLint/Vitest 不得排除灰度页；页面测试必须断言只请求 feature-gates，并继续覆盖现役固定 target、直接 Gate Key 保存与新 target 状态重置。
|
||||
- 关联：`apps/admin-web/src/pages/AdminGrayReleaseConfigPage.tsx`、`apps/admin-web/src/app/adminRoutes.ts`、`server-rs/crates/api-server/src/modules/admin.rs`、`docs/technical/【架构下线】旧创作模板业务退役方案-2026-07-17.md`。
|
||||
|
||||
## 历史钱包消费不能从最近流水或通用订单快照推算
|
||||
|
||||
- 现象：后台用户详情要展示累计花费时，直接复用只返回最近 50 条的 `list_profile_wallet_ledger`，或在充值订单每行使用的通用钱包快照里扫描该用户全部流水。
|
||||
- 原因：最近流水会低估历史总额；通用钱包快照又会被订单列表反复构造，把一次按用户聚合放大为 `订单数 × 流水数` 的重复扫描。
|
||||
- 处理：历史花费只累计 `asset_operation_consume` 负向流水绝对值，退款不冲减；通过 `profile_wallet_consumption_total` 在已有投影时按主键 O(1) 累加。首次上线必须在停写维护窗口由 owner 执行全量初始化，为每个已有钱包流水的用户建立投影，不能让所有存量用户的首次正常消费各自扫描历史；维护遗漏或新用户缺行时才在首次消费或详情读取中按用户索引兜底重建一次。手动对账扫描是独立高风险操作，member 必须单独持有 `profile-wallet-consumption-reconcile`，不能因为能打开共享用户详情就自动获得。
|
||||
- 验证：构造消费、退款、充值退款追回和赠送混合流水，断言只累计消费；维护初始化后正常消费只按主键累加；重复详情读取不得重复扫描或重复累计；任意 Tab 权限不能调用手动对账，同时确认充值订单列表的通用钱包快照没有新增历史流水扫描。
|
||||
|
||||
Reference in New Issue
Block a user