6a-spec-install 1.0.1-dev.13 → 1.0.1-dev.16

package/.cursor/rules/6A/6A_model_sop.md

@@ -28,6 +28,7 @@ alwaysApply: false
 - **可选输入**：已确认的领域边界与核心实体语义(可以是markdown文档)
 - **系统自带知识库**：
     - 现有能力地图:`./.6A-spec/biz/functional-capability-Map.md`
+    - **C端用户体系规范**:`./.cursor/rules/biz/c_user_system_rule.md` (仅在涉及C端用户/门户/小程序相关设计时**必需**读取)
 
 
 ## 第一阶段：资产审计与策略定义 (Asset Audit)
@@ -46,9 +47,24 @@ alwaysApply: false
 | (例：评价单) | 新建独立表 | 核心业务凭证，现有表无法承载 | `rental-customer` |
 
 ### 第二步：领域模型设计 (Domain Modeling)
-1. 使用 Mermaid 语法绘制 **UML 类图 (Class Diagram)**
-- **要求**：展示实体（Entity）之间的关系（一对一、一对多、组合关系），实体的字段必须要有中文说明
-- **禁止内容**：不要在此阶段绘制任何 Flowchart（流程图）或 Sequence（时序图）
+
+1. **核心领域对象说明 (Domain Object Definitions)**
+   需识别并解释核心领域名词（聚合根、实体、值对象），按如下表格输出：
+   | 领域对象 | 类型 | 业务含义与职责 | 生命周期描述 |
+   | :--- | :--- | :--- | :--- |
+   | (例：评价单) | 聚合根 | 记录客户对服务的评价内容 | 创建 -> 待评价 -> 已评价 -> 归档 |
+   | (例：评价维度) | 值对象 | 定义评价的具体切面（如响应速度） | 随评价配置创建，不可变 |
+
+2. **领域事件设计 (Domain Events)**
+   识别领域状态变更产生的关键业务事件：
+   | 事件名称 | 触发条件 | 携带关键数据 | 消费方示例 |
+   | :--- | :--- | :--- | :--- |
+   | (例：评价已提交) | 用户完成表单提交并落库 | 评价单ID, 评分, 评价时间 | 积分系统, 消息通知 |
+
+3. **UML 类图 (Class Diagram)**
+   使用 Mermaid 语法绘制：
+   - **要求**：展示实体（Entity）之间的关系（一对一、一对多、组合关系），实体的字段必须要有中文说明
+   - **禁止内容**：不要在此阶段绘制任何 Flowchart（流程图）或 Sequence（时序图）
 
 
 ### 第三步：数据库物理设计 (Physical Schema)
@@ -87,9 +103,9 @@ alwaysApply: false
 - 第一行，第一列：固定值：表中文名称，第二列：表中文名称
 - 第二行，第一列：固定值：表英文名称，第二列：表英文名称
 - 第三行，第一列：固定值：说明，第二列：说明
-- 第四行开始，第一列：字段中文名称，第二列：字段英文名称，第三列：字段类型，第四列：长度，第五列：是否必填(是、否)，第六列：字段说明
+- 第四行开始，第一列：字段中文名称，第二列：字段英文名称，第三列：字段类型，第四列：长度，第五列：是否必填(是、否)，第六列：字段说明，第七列：业务来源
 
-## 表设计表格展示示例
+#### 表设计表格展示示例
 ```
 ##### 1. 服务评价单表 (rental_ServiceEvaluation)
 | 表中文名称 | 服务评价单表 |
@@ -97,13 +113,21 @@ alwaysApply: false
 | 表英文名称 | rental_ServiceEvaluation |
 | 说明 | 服务评价单主表，记录服务评价的完整信息 |
 
-| 字段中文名称 | 字段英文名称 | 字段类型 | 长度 | 是否必填 | 字段说明 |
-| :--- | :--- | :--- | :--- | :--- |
-| 服务评价单GUID | serviceEvaluationGUID | 唯一标识 | - | 是 | 主键 |
-| 服务评价单号 | serviceEvaluationNo | 单行文本 | 是 | 64 | 服务评价单编号，系统自动生成 |
-| 服务场景 | serviceScene | 单行文本 | 64 | 是 | 服务场景：预约带看、合同新签、入住办理、换房办理、退房办理、报事工单、报修工单、投诉工单、建议工单 |
+| 字段中文名称 | 字段英文名称 | 字段类型 | 长度 | 是否必填 | 字段说明 | 业务来源 |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| 服务评价单GUID | serviceEvaluationGUID | 唯一标识 | - | 是 | 主键 | 系统生成 |
+| 服务评价单号 | serviceEvaluationNo | 单行文本 | 是 | 64 | 服务评价单编号，系统自动生成 | PRD 3.1.2 评价规则 |
+| 服务场景 | serviceScene | 单行文本 | 64 | 是 | 服务场景：预约带看、合同新签、入住办理、换房办理、退房办理、报事工单、报修工单、投诉工单、建议工单 | PRD 3.2 场景枚举 |
 ```
 
+### 第四步：关键决策说明 (Key Design Decisions)
+对建模过程中的核心决策进行记录，特别是涉及**复用/新建**、**拆分/合并**、**性能/范式**权衡的场景：
+
+| 决策点 | 备选方案 | 最终选择 | 决策理由 |
+| :--- | :--- | :--- | :--- |
+| (例：评价状态存储) | 方案A：在主表存状态字段<br>方案B：独立状态流水表 | 方案A | 业务逻辑简单，无须追溯状态变更历史，且查询性能要求高 |
+| (例：客户信息引用) | 方案A：冗余客户名称<br>方案B：仅存客户ID | 方案B | 客户改名频率低，且需保证各模块显示一致，通过前端关联查询解决展示问题 |
+
 ## 输出要求：
 1. 格式：Markdown 源码格式
 2. 文档位置：`.docs/{功能名称}` 目录
@@ -111,5 +135,5 @@ alwaysApply: false
 4. 请务必检查下第三步的输出是否满足格式要求
 
 ## 注意
-- 不要为了“完整”而臆造字段
-- 所有字段必须能在 PRD 中或者补充信息中找到业务来源
+- **严格溯源**：所有字段必须有明确的业务来源（PRD章节、补充需求文档或业界通用标准），并在“业务来源”列中明确标注，严禁“为了完整”而臆造字段。
+- **一致性**：表格中的说明必须与 PRD 描述保持一致。

package/.cursor/rules/biz/c_user_system_rule.md

@@ -0,0 +1,240 @@
+---
+description: C端用户体系规范
+alwaysApply: false
+---
+
+# C端用户体系规范
+
+## 概述
+
+本规范定义了系统中C端用户体系的设计标准，包括用户表结构、认证机制、身份类型、数据关联规范等。
+
+**适用范围**：所有面向C端用户的门户应用，主要依赖微信小程序。
+
+---
+
+## 一、核心表结构
+
+### 1.1 C端用户中心表（mdm_mycuser）
+
+**表说明**：C端用户中心的核心表，存储所有C端用户的基础信息。
+
+**使用场景**：
+- 用户在小程序登录后会自动生成一条用户记录
+- 存储用户基础信息和手机号
+- 未认证用户的业务关联直接使用此表
+
+**关键字段**：
+- 用户ID（主键）
+- 手机号：用户授权后的实名认证手机号
+- 创建时间：用户首次登录时间
+- 其他用户基础信息字段
+
+**使用原则**：
+- ✅ 查询所有C端用户（包括未认证用户）
+- ✅ 未认证用户的业务数据关联
+- ✅ 用户基础信息的存储和查询
+- ❌ 不应直接在此表存储业务相关字段
+
+---
+
+### 1.2 门户用户表（nr_tocuser）
+
+**表说明**：门户管理应用中的用户表，与 `mdm_mycuser` 一一对应（历史遗留原因）。
+
+**使用场景**：
+- 经过认证的用户业务关联
+- 门户业务相关的用户扩展信息
+- 用户身份信息的存储
+
+**关键字段**：
+- 用户ID（主键）
+- 关联的 mdm_mycuser 用户ID（外键）
+- 身份类型
+- 认证状态
+- 其他门户业务相关字段
+
+**使用原则**：
+- ✅ 已认证用户的业务数据关联（推荐使用此表）
+- ✅ 门户业务相关的用户扩展信息
+- ✅ 用户身份和权限相关的查询
+- ❌ 不应用于未认证用户的关联
+
+---
+
+### 1.3 表关系说明
+
+```
+┌─────────────────┐         一对一关系         ┌─────────────────┐
+│  mdm_mycuser    │ ─────────────────────────> │   nr_tocuser    │
+│  (C端用户中心)   │                            │   (门户用户)     │
+└─────────────────┘                            └─────────────────┘
+      ↑                                                ↑
+      │                                                │
+      │                                                │
+未认证用户关联                                    已认证用户关联
+```
+
+**说明**：
+1. 每个 `nr_tocuser` 记录对应一个 `mdm_mycuser` 记录
+2. `mdm_mycuser` 记录不一定有对应的 `nr_tocuser` 记录（未认证用户）
+3. 这是历史遗留的表结构设计，需要理解并正确使用
+
+---
+
+## 二、用户身份体系
+
+### 2.1 身份类型
+
+系统支持以下四种C端用户身份类型：
+
+| 身份类型 | 认证状态 | 说明 | 使用场景 |
+|---------|---------|------|---------|
+| **游客** | 未认证 | 仅登录小程序，未进行手机号认证 | 浏览公开信息、查看基础内容 |
+| **管理员** | 已认证 | 通过手机号认证，匹配为管理员身份 | 管理功能、审批操作 |
+| **业务代理人** | 已认证 | 通过手机号认证，匹配为业务代理人身份 | 代理业务操作、客户服务 |
+| **企业员工** | 已认证 | 通过手机号认证，匹配为企业员工身份 | 企业内部业务操作 |
+
+### 2.2 身份识别流程
+
+```
+用户登录小程序
+    ↓
+创建 mdm_mycuser 记录
+    ↓
+授权手机号？
+    ├─ 否 → 游客身份（只有 mdm_mycuser 记录）
+    └─ 是 → 手机号实名认证
+             ↓
+        手机号匹配系统基础数据
+             ↓
+        创建 nr_tocuser 记录
+             ↓
+        分配对应身份（管理员/业务代理人/企业员工）
+```
+
+### 2.3 认证机制
+
+**认证方式**：
+- 用户授权手机号
+- 手机号与系统基础数据的客户进行匹配
+- 匹配逻辑由认证服务统一处理（具体匹配规则由业务层定义）
+
+**认证状态判断**：
+```java
+// 判断用户是否已认证
+boolean isAuthenticated = nr_tocuser 记录存在;
+
+// 判断用户身份类型
+if (nr_tocuser.身份类型 == "管理员") {
+    // 管理员权限
+} else if (nr_tocuser.身份类型 == "业务代理人") {
+    // 业务代理人权限
+} else if (nr_tocuser.身份类型 == "企业员工") {
+    // 企业员工权限
+} else {
+    // 游客权限（仅有 mdm_mycuser 记录）
+}
+```
+
+---
+
+## 三、数据关联规范
+
+### 3.1 选择关联表的原则
+
+根据用户的认证状态选择合适的表进行业务数据关联：
+
+#### 规则一：已认证用户 → 使用 nr_tocuser
+
+**适用场景**：
+- 需要身份验证的业务操作
+- 需要权限控制的功能
+- 门户业务数据的用户关联
+
+#### 规则二：未认证用户 → 使用 mdm_mycuser
+
+**适用场景**：
+- 游客可访问的功能
+- 不需要身份验证的业务场景
+- 用户行为追踪
+
+#### 规则三：混合场景 → 同时支持两种关联
+
+**适用场景**：
+- 业务数据需要支持游客和已认证用户
+- 用户从游客升级为认证用户后，数据需要保持连续性
+
+--- 
+
+### 3.2 实体字段命名规范
+
+**关联字段命名**：
+
+| 关联表 | 字段名称          | 字段类型 | 说明 |
+|-------|---------------|---------|------|
+| `mdm_mycuser` | `cuserId`     | UUID（唯一标识） | 关联C端用户中心用户ID |
+| `mdm_mycuser` | `cuserName`   | String（单行文本，长度128） | 冗余字段：用户名称 |
+| `nr_tocuser` | `tocuserId`   | UUID（唯一标识） | 关联门户用户ID |
+| `nr_tocuser` | `tocuserName` | String（单行文本，长度128） | 冗余字段：用户名称 |
+
+---
+
+## 四、常见问题
+
+### Q1: 什么时候使用 mdm_mycuser，什么时候使用 nr_tocuser？
+
+**回答**：
+- **mdm_mycuser**：
+  - 未认证用户（游客）的业务关联
+  - 需要追踪所有用户（包括游客）的场景
+  - 用户基础信息的存储
+  
+- **nr_tocuser**：
+  - 已认证用户的业务关联（推荐）
+  - 需要身份验证的业务场景
+  - 需要权限控制的功能
+
+**判断标准**：看业务是否需要用户认证，需要认证就用 nr_tocuser，不需要认证就用 mdm_mycuser。
+
+---
+
+### Q2: 为什么有两个用户表？
+
+**回答**：
+这是历史遗留原因造成的设计。最初系统只有 `mdm_mycuser`（C端用户中心），后来门户系统独立发展，创建了 `nr_tocuser` 来存储门户业务相关的用户信息。虽然存在冗余，但两者有明确的职责划分：
+- `mdm_mycuser`：用户中心的核心表，存储用户基础信息
+- `nr_tocuser`：门户业务的扩展表，存储认证和身份信息
+
+---
+### Q5: C端用户的身份是如何匹配的？
+
+**回答**：
+用户通过手机号授权后，系统会执行以下匹配逻辑：
+1. 获取用户授权的手机号
+2. 将手机号与系统基础数据中的客户信息进行匹配
+3. 根据匹配结果分配相应的身份类型（管理员/业务代理人/企业员工）
+4. 创建 `nr_tocuser` 记录，存储身份信息
+
+**注意**：具体的匹配规则由业务层定义，不同的业务系统可能有不同的匹配逻辑。本规范只说明匹配机制的存在，不涉及具体匹配规则的实现细节。
+
+---
+
+## 五、检查清单
+
+在开发涉及C端用户的功能时，请确认：
+
+- [ ] 明确业务场景是否需要用户认证
+- [ ] 选择了正确的用户表进行关联（mdm_mycuser 或 nr_tocuser）
+- [ ] 实体字段命名符合规范（cuserId / tocuserId）
+- [ ] API 添加了正确的权限注解（@IdentityUserPermission()）
+- [ ] 添加了用户认证状态的判断逻辑
+- [ ] 考虑了不同身份类型的权限差异
+- [ ] 添加了必要的日志记录
+- [ ] 处理了用户不存在或未认证的异常情况
+---
+
+**文档版本**：v1.0  
+**最后更新**：2026-02-05  
+**维护人**：开发团队
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "6a-spec-install",
-  "version": "1.0.1-dev.13",
+  "version": "1.0.1-dev.16",
   "description": "6A-spec 驱动开发提示词安装工具，支持 Cursor 和 Claude",
   "main": "lib/installer.js",
   "bin": {