6a-spec-install 1.0.1-dev.2 → 1.0.1-dev.20

package/.6aspec/rules/6A/6A_task_sop.md

@@ -0,0 +1,137 @@
+---
+description: 任务拆解标准操作流程 (Functional Entrypoint SOP)
+alwaysApply: false
+---
+
+# 6A-task: 任务拆解标准操作流程 (Functional Entrypoint SOP)
+
+## 工作流概述
+
+当触发 6A-task 工作流时，AI 需作为 **Lead Engineer / Project Manager**，基于已生成的 `TDD_{功能名称}.md` 文档，将架构设计转化为以**入口点（API/事件/定时任务）**为核心的原子开发任务。
+
+## 0. 执行协议 (Protocol) - 必须遵守
+
+你是一个**技术项目经理 (TPM)**。在执行任务拆解前，请严格遵守：
+
+1.  **主动检索 (Active Retrieval)**：
+    *   当用户指定 `{功能名称}` 时，优先尝试读取 `.docs/{功能名称}/TDD_{功能名称}.md`。
+    *   如果找不到 TDD 文档，**立即停止**并报错，提示用户先完成 TDD 设计。
+
+2.  **思维链门禁 (Chain of Thought Gatekeeping)**：
+    *   在输出任务列表前，**必须**先输出 `<thinking>` 块。
+    *   **Check**: TDD 是否包含清晰的“接口列表”、“定时任务列表”、“事件订阅列表”？
+    *   **Check**: 所有的入口点是否都有对应的“执行逻辑”描述？
+    *   **Decision**: 若 TDD 内容严重缺失（如只有标题无逻辑），拒绝拆解，要求用户先完善 TDD。
+
+3.  **依赖分析 (Dependency Analysis)**：
+    *   在 `<thinking>` 块中，分析任务间的依赖关系（例如：退款任务依赖于支付查询接口）。
+    *   基于依赖关系生成合理的**开发顺序**，而不是简单的线性排列。
+
+## 核心原则
+1. **纵向拆解**：一个任务即一个完整的功能入口，包含其关联的枚举、 DTO、Service、Repository，gateway 等所有逻辑实现
+2. **职责完备**：在执行某个任务时，AI 应根据需要自动创建或修改涉及的模型与逻辑，而不是拆分成多个任务
+3. **规约驱动**：不同类型的任务必须显式指定对应的编码规约文件
+
+## 输入要求
+- **必需输入**：已完成的 `TDD_{功能名称}.md` 文档
+- **关联规约**：
+    - API 任务：`./.6aspec/rules/biz/api_rule.md`
+    - 事件订阅任务：`./.6aspec/rules/biz/event_subscriber_rule.md`
+    - 定时任务任务：`./.6aspec/rules/biz/scheduled_job_rule.md`
+    - 后台任务任务：`./.6aspec/rules/biz/background_job_rule.md`
+
+## 第一阶段：任务分类与规则映射
+
+在拆解时，AI 必须识别 TDD 中的功能点属于哪种类型，并分配对应的规约文件：
+
+| 任务类型 | 识别特征 | 关联规约文件 |
+| :--- | :--- | :--- |
+| **API 任务** | TDD 中的 RESTful API 设计、Controller 接口 | `./.6aspec/rules/biz/api_rule.md` |
+| **事件订阅任务** | TDD 中的事件订阅 (Subscriber)、异步消息处理 | `./.6aspec/rules/biz/event_subscriber_rule.md` |
+| **定时任务任务** | TDD 中的定时任务 (Scheduled Task)、Cron 任务 | `./.6aspec/rules/biz/scheduled_job_rule.md` |
+| **后台任务任务** | TDD 中的后台任务（Async Background Job）、需要异步执行的任务 | `./.6aspec/rules/biz/background_job_rule.md` |
+
+## 第二阶段：输出规范
+
+### 1. 目录结构
+所有任务文件必须存储在以下路径：
+- `.docs/{功能名称}/task/`
+
+### 2. 文件命名规范
+- 格式：`task_{序号}_{任务类型}_{功能简名}.md`
+- 示例：`task_001_api_create_contract.md`, `task_002_event_contract_signed.md`
+
+### 3. 任务文档模板 (Task Template)
+每个生成的任务文件必须**严格包含**以下章节：
+
+```markdown
+# 任务 [序号]: [任务标题 (如: 开发 XXX 接口)]
+
+### 0. 任务状态
+- 状态：[待开始 / 进行中 / 已完成 / 阻塞 / 取消]
+- 最后更新：[YYYY-MM-DD]
+
+### 1. 任务目标
+- 描述任务的入口点（如：开发 API `POST /v1/contract/save`）
+- 明确该任务需要实现的功能边界
+
+### 2. 预计工时（小时）
+- 预计：X 小时
+- **评估基准 (Baseline)**：
+    - 简单 CRUD 接口：0.5 - 1h
+    - 带简单业务逻辑（校验/状态变更）：1 - 2h
+    - 复杂逻辑（外部调用/并发锁/事务）：3 - 5h
+    - 极高复杂度（核心金融链路）：5h+
+
+### 2.5 任务依赖与前置条件 (Dependencies)
+- **前置任务**：[Task-001 / 无] (必须先完成的任务)
+- **依赖模块**：[UserFacade / PaymentService] (需调用的外部依赖)
+
+### 3. 业务规则与实现细节
+- **核心逻辑**：基于 TDD 中的“执行逻辑”描述，详细说明 Service 层及领域层需处理的规则（如存在对应的可视化文档 `TDD_{功能名称}_Visual.md`，可作为辅助参考，但不得脱离 TDD 自行补充规则）。
+- **核心技术决策**：回顾 TDD 中的关键决策（如幂等方案），再次确认落实。
+- **数据结构与契约 (Binding)**：
+    - **API 契约**：必须严格遵循 `TDD_{功能名称}_API_def.md` 中的 Request/Response 结构。
+    - **Entity 引用**：实体类与 Mapper 均已预生成，请在代码实现阶段搜索并复用（如 `MyEntity.java`, `MyEntityMapper.java`或者`MyEntityDao.java`），**严禁重复创建**。
+- **状态流转**：若涉及状态变更，明确状态机逻辑。
+- **数据结构**：涉及的 DTO、Command、Query 的定义要求
+- **异常处理**：需捕获并抛出的业务异常类型。
+
+### 4. 跨模块依赖调用
+- 明确需要调用哪些已有模块的 Facade 或 RMI 接口
+- 描述依赖的数据来源或前置条件
+
+### 5. 必须参考的编码规则
+- **本任务类型**：[API / 事件订阅 / 定时任务 / 后台任务]
+- **规则文件**：[此处填入对应的 .md 规则路径]
+- **编码公共规则文件**：`.6aspec/rules/biz/code.md`和`.6aspec/rules/biz/project-structure.md`
+- **执行说明**：在执行本任务代码生成时，必须严格遵守该规则文件中的代码分层、命名及注释规范
+- **C/B 端标识**：API 接口必须识别是 C 端(小程序端)还是 B 端(PC 端和 APP 端)
+
+### 6. 验收标准 (DoD)
+- [ ] 对应的接口/订阅者/定时器已成功创建。
+- [ ] 内部逻辑（Service/Repository）完整实现且符合业务预期。
+- [ ] 幂等性与并发控制已按 TDD 要求实现。
+- [ ] 满足规约文件中的所有强制性要求。
+```
+
+## 第三阶段：拆解执行步骤
+1. **扫描入口点**：从 TDD 文档中提取所有“接口设计”、“事件设计”、“定时任务”和“后台任务”中的条目。
+2. **合并依赖项**：将该入口点涉及的所有业务逻辑（Service）、数据访问（Repository）、模型定义（DTO/VO/Enum）全部归入该入口点的原子任务中。
+3. **排序与编排**：基于`<thinking>`中的依赖分析，对任务进行逻辑排序（先基础后上层，先前置后依赖）。
+4. **生成文件**：为每个识别出的入口点生成独立的任务 Markdown 文件。
+5. **生成总览**：任务拆解完成后，必须在 `.docs/{功能名称}/task/README.md` 输出任务总览。
+6. **状态维护（必须执行）**：后续每当完成一个任务，必须同步更新：
+   - 对应任务文件中的“任务状态”。
+   - `.docs/{功能名称}/task/README.md` 中该任务的状态展示。
+
+## 输出要求
+1. **格式**：Markdown 源码格式。
+2. **一致性**：任务中的类名、方法名和字段名必须与 TDD 保持完全一致。
+3. **禁用范围**：不拆解前端任务、不拆解单纯的单元测试任务、不拆解 Entity/SQL 任务。
+4. **总览 README（必须输出）**：在 `.docs/{功能名称}/task/README.md` 生成任务总览文件，必须包含：
+   - **项目进度看板**：任务总工时、已完成工时、进度条。
+   - **任务清单**：按推荐执行顺序排列，包含状态图标 (✅/🔄/⏳)。
+   - **开发阶段划分**：建议将任务划分为 Phase 1 (Core), Phase 2 (Extensions) 等阶段。
+   - **验收标准汇总**：从各任务 DoD 汇总，形成整体 DoD。
+   - **注意事项与相关文档链接**: 至少包含：TDD、API_def、如存在则包含 Visual 文档链接

package/{.cursor → .6aspec}/rules/6A/6A_visual_logic_sop.md

@@ -30,8 +30,8 @@ alwaysApply: false
 ### 可选输入（用于补齐 TDD 未显式写清的信息）
 - 数据模型文档：`.docs/{功能名称}/MODEL_{功能名称}.md`
 - PRD：`.prd/{功能名称}-prd.md`
-- 事件清单：`./.cursor/rules/biz/event-list.md`（当涉及事件订阅/发布时）
-- 能力地图：`./.cursor/rules/biz/functional-capability-Map.md`（当涉及跨模块 Facade 依赖时）
+- 事件清单：`./.6aspec/biz/event-list.md`（当涉及事件订阅/发布时）
+- 能力地图：`./.6aspec/biz/functional-capability-Map.md`（当涉及跨模块 Facade 依赖时）
 
 ## 中断机制（必须执行）
 如果出现以下任一情况，必须停止画图并输出“提问清单”，等待人类补充：

package/.6aspec/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  
+**维护人**：开发团队
+