@tbox.cn/app-module-member 0.2.0 → 0.8.7

package/AGENTS.md

@@ -0,0 +1,16 @@
+# module-member —— 集成指引（AI 助手用）
+
+本模块为商圈业务模块，声明消费以下服务槽（Port 接口定义见 `src/server/ports/`）：
+
+- 服务槽清单：见 `tbox.module.json` 的 `contributes.services`（demand 侧，含 title/description meta）。
+
+## 自定义 API 对接（AI 集成）
+
+用户为本模块服务槽配置「自定义 API」后，adapter 实施落点 = `packages/provider-custom/`
+（会员：会员注册、卡面与权益查询）。实施步骤与完成判据见 `packages/provider-custom/AGENTS.md`；
+本模块 Port 接口为 adapter 的实现契约（输入 `ServiceAdapterInput`：config/instanceId/credentialRef）。
+
+## 真实厂商接入
+
+官方 provider 包形态（manifest 槽声明 + 独立包发布）参照 `modules/provider-mock` 结构样例与
+docs/reference/providers.md；厂商中立措辞纪律见该参考（本文件受 vendor-neutrality 门禁扫描）。

package/README.md

@@ -1,17 +1,105 @@
-# @tbox.cn/app-module-member
+# module-member · 会员业务组件
 
-商圈会员模块：积分查询/扣减/发放/退款、等级（codegen 源）。
+商圈会员域唯一承接组件（`@tbox.cn/app-module-member`，moduleId `member`）：
+入会四动作（支付宝授权 effect → complete-auth 回调）、会员信息、会员卡与偏好记忆、
+积分余额与流水、入会表单查询。运行时经 integrations registry 槽位（member×5：
+`account`/`profile`/`card`/`benefits`/`enrollment`——fail-fast 无兜底）接入
+provider 包供给的厂商 C 端实现（业务模块零 vendor——真源归 provider 包）；
+`InMemoryMemberService` 仅供隔离单测使用，不参与运行时注册或失败降级。
+同时是全局身份底座：`member.status` 服务工厂被其他模块消费做登录门禁。
 
-## 安装
+## 业务职责
 
-```sh
-pnpm add @tbox.cn/app-module-member
-```
+| 能力域 | 承接 |
+|---|---|
+| 账户状态 | authState/gate 判定、GUEST（已登录未入会）与 MEMBER 区分、登录≠入会 |
+| 会员信息 | 等级名/卡面图（无 tier 枚举字段，presentation.variant 表达蓝/银/金/黑）|
+| 积分 | 余额 + 明细（当页 10 条）|
+| 入会 | CTA 卡/表单卡/入会状态卡 |
+| 登录 | 登录 CTA 卡（供匿名轮引导）|
+| 隐私边界 | 隐私诉求拒不澄清，不落任何真实手机号/证件明文 |
 
-## 用法
+## 架构分层
 
-在生成应用中：
+    src/
+      server/
+        index.ts        模块注册（卡 map / 工具 6 注册 / 无 preTool）
+        tool.ts         6 工具定义 + 门禁辅助（~512 行）
+        action.ts       动作链（CTA 点击续接，~349 行）
+        service.ts      Port 汇编与门禁工厂（~245 行）
+        status.ts       账户状态派生（~76 行）
+        subject-binding subjectId 绑定（~19 行）
+        ports/index.ts  Port 接口（~27 行）
+        handler/        意图 handler 骨架（~170 行）
+      client/cards/     7 张卡组件
 
-```sh
-tbox-app module add @tbox.cn/app-module-member
-```
+## 领域模型（契约真源）
+
+- `modules/contracts-mall/src/services/member.ts`（~350 行）:member Snapshot 型
+  （账户/积分/权益/入会/卡面）与五 Port：MemberAccountPort、MemberProfilePort、
+  MemberCardPort、MemberBenefitsPort、MemberEnrollmentPort；SubjectBindingPort 已 deprecated。
+- `modules/contracts-mall/src/domain/points.ts` / `discount.ts`：积分与折扣小域。
+- 本模块无 server/domain.ts：账户状态机分散在 status.ts（派生）与 action.ts（续接），
+  会员实体只在契约 services 层——模块域模型「薄模块 + 契约厚库」形态。
+
+## 工具清单（tool.ts；index.ts:41-52 单点 withCardEmissionHint 包裹；index.ts:109-114 注册）
+
+| 工具 | 定义行 | oneLiner | carding | actions |
+|---|---|---|---|---|
+| queryPoints | tool.ts:160 | 积分账户：余额+明细 facts，供模型作答 | promotion-points-usage | 无 |
+| queryMemberInfo | tool.ts:239 | 等级/权益概览 facts | member-info | 无 |
+| queryMemberCard | tool.ts:299 | 会员卡卡面（辅助判定 hasCompleteMemberCard tool.ts:64-66）| member-card-summary | 无 |
+| queryEnrollmentCta | tool.ts:367 | 入会引导 CTA（含入会状态分流）| member-enrollment-cta | 是 |
+| queryEnrollmentForm | tool.ts:441 | 入会表单（匿名可查，登录后回填）| member-enrollment-form | 是 |
+| queryLoginCta | tool.ts:497 | 登录引导 CTA（未登录轮）| member-login-cta | 是 |
+
+细节机制：
+- 匿名短路 anonymousShort（tool.ts:113-120）：未登录请求统一短话术 + 登录卡，不发必然失败查询。
+- 隐私拒不面 memberPrivacyRefusal（tool.ts:48-62）：模型/用户提隐私核对诉求时冻结卡面细粒度
+  数据，返回拒不话术（隐私边界工具化而非提示词约定）。
+- queryPoints 链路：getAccount → authState 检查 → 门禁卡或 facts；facts 组装
+  balance/membershipLabel/items/total/contractNotice，积分服务降级时 pointsNotice 兜底话术。
+- 权益查询 listPointUsage(userId,1,10)（tool.ts:209-215），平台分页缺省 10 条（卡片轮播）。
+
+## 门禁两级（登录轴）
+
+- 匿名（identity.source=anonymous）：登录 CTA 卡，终止查询。
+- GUEST（已登录未入会）：入会 CTA 卡，不误伤可查面。
+- 登录≠入会：任何门禁不得把 GUEST 当匿名拦截。
+
+## 写动作面
+
+零独立写动作（无 StateStore 命名空间）；入会动作由 CTA/表单卡上的 actions 字段
+拉起客户端续接（action.ts 动作链），服务端不经工具写状态。
+
+## 卡片清单（7 张；client/cards/；dataSchema 锚 contracts-mall member schemas）
+
+| cardType | 说明 |
+|---|---|
+| member-card-summary | 会员卡面（等级/变体色）|
+| member-info | 会员信息概览 |
+| member-point-usage-list | 积分明细列表 |
+| member-enrollment-cta | 入会引导（含入会入口 actions）|
+| member-enrollment-form | 入会表单 |
+| member-enrollment-status | 入会状态回执 |
+| member-login-cta | 登录引导 |
+
+## 跨模块协作
+
+- 供出：`member.status` 服务工厂（ctx.services 锚）、`memberGateCardOf`、`toMallQueryContext`
+  （均 contracts-mall 公开入口）——alipay-activity / customer-service / promotion 门禁消费。
+- 不 import 其他 module（跨模块一律经 ctx 服务锚与事件总线）。
+
+## 铁律摘要
+
+- import 边界：只 import contracts/sdk 公开入口；client/** 引 server/** 必须 import type。
+- register 只注册不解析；工具实例顶层单例；跨模块交互一律经 ctx。
+- 卡片 key = meta.cardType；exports 恒指 src/。
+- 身份以 reqCtx 为准，不接模型注入的 userId/openId。
+
+## 已知限制与文档漂移
+
+- 旧的 README「C 端查询映射」表实为厂商端点映射，本版删除；
+  端点映射现由对应 provider 包侧维护。
+- `@vendor-contract` JSDoc 标注尚未存在（全仓 0 命中），Port 语义现摘自普通 JSDoc；
+  1030 Phase 1 计划增补，增补后本节更新。