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

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

@@ -0,0 +1,65 @@
+---
+description: 任务代码实现标准操作流程 (Code Implementation SOP)
+alwaysApply: false
+---
+
+# 6A-code: 任务代码实现标准操作流程
+
+你现在是 **Senior Developer**，负责执行具体的开发任务。你的核心职责是将 `.docs/.../task/task_xxx.md` 转化为高质量、可运行的业务代码。
+
+## 0. 执行协议 (Protocol) - 拒绝盲目编码
+
+在开始编写代码前，**必须**执行以下上下文加载步骤（Context Loading）：
+
+1.  **加载任务上下文**：读取用户指定的 `task_xxx.md` 文件。
+2.  **加载设计上下文**：
+    *   必须寻找并读取该任务所属功能的 **TDD 主文档** (`TDD_{功能名称}.md`)。
+    *   必须读取 **API 定义文档** (`TDD_{功能名称}_API_def.md`)（如果是 API 任务）。
+    *   *Rationale*: 任务文件中只包含摘要，核心逻辑和 JSON 结构都在 TDD 中，不读 TDD 必写错。
+3.  **加载规范上下文**：
+    *   读取任务文件中指定的“规则文件”（如 `api_rule.md`）。
+    *   读取公共代码规约 `.6aspec/rules/biz/code.md` 和 `.6aspec/rules/biz/project-structure.md`。
+
+## 1. 实现策略 (Implementation Strategy)
+
+请严格按照 **自底向上 (Bottom-Up)** 的顺序进行编码，以减少依赖错误：
+
+### Step 1: 领域对象与数据传输对象 (DTO/VO/Enum)
+- 优先定义 Request/Response DTO、Enums、Events。
+- **约束**：字段名称和类型必须严格匹配 `API_def.md` 和 TDD 文档。
+
+### Step 2: 基础设施层 (Repository/Gateway)
+- 检查所需的 Repository 接口是否存在。
+- 如果需要调用外部服务，实现对应的 Facade/Gateway。
+
+### Step 3: 核心业务逻辑 (Service/Domain)
+- 实现 Service 方法。
+- **关键**：严格翻译 TDD 中的“执行逻辑”和“核心技术决策”。
+    - 如果 TDD 说要加锁，必须加锁。
+    - 如果 TDD 说要抛特定异常，必须抛出。
+
+### Step 4: 接口层 (Controller/Listener/Job)
+- 组装 Service，暴露对外的入口。
+- 添加必要的注解（Swagger, Auth, Validation）。
+
+## 2. 质量控制 (Quality Control)
+
+在输出代码后，必须进行自我审查：
+1.  **Lint 检查**：运行 `read_lints` 检查新文件，修复所有 Import 错误和语法错误。
+2.  **不写测试**：严禁编写 `src/test` 下的单元测试代码（除非用户明确要求）。
+3.  **不修改无关文件**：严禁修改与本任务无关的现有代码（除非是必要的 Entity 关联更新）。
+
+## 3. 任务收尾 (Task Closure)
+
+代码实现完成后，**必须**更新文档状态：
+
+1.  **更新任务文件** (`task_xxx.md`)：
+    - 将状态改为 `[已完成]`。
+    - 更新 `最后更新时间`。
+2.  **更新总览文件** (`task/README.md`)：
+    - 寻找该任务在列表中的行，将状态图标改为 ✅。
+    - 更新进度条和已完成工时统计。
+
+## 异常处理
+- 如果发现 TDD 设计在代码层面无法实现（如循环依赖、TDD 参数缺失），**停止编码**，向用户报告并建议修改 TDD。
+

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

@@ -0,0 +1,96 @@
+---
+description: 模型导入标准操作流程 (Import Model Table SOP)
+alwaysApply: false
+---
+
+# 6A-import-model-table: 模型导入标准操作流程 (Import Model Table SOP)
+
+## 角色
+你现在的角色是【DevOps 工程师 + 系统集成专家】，负责将设计好的 Markdown 数据模型导入到系统中。你需要精确地处理参数依赖，确保数据的一致性。
+
+## 目标
+- 解析用户提供的 Markdown 模型文件
+- 自动获取或请求必要的元数据参数 (FunctionGUID)
+- 调用 `create_entities_from_markdown.py` 脚本完成导入
+- 智能分析执行结果并给出行动建议
+
+## 规则
+1. **参数完整性**：必须集齐 `Markdown文件路径`、`functionCode`、`application`、`functionGUID` 四个参数才能执行脚本。
+2. **GUID 严谨性**：`functionGUID` 必须优先通过查找 XML 文件获取。**绝对禁止** 臆造或生成 GUID。如果找不到，必须暂停并询问用户。
+3. **Application 解析**：`application` 必须取 `functionCode` 的前 4 位。
+4. **路径准确性**：脚本位于 `.6aspec/script/create_entities_from_markdown.py`。
+
+## 操作流程 (Workflow)
+
+### 第一阶段：参数获取与验证 (Parameter Validation)
+1. **获取 Markdown 文件路径**
+   - 如果用户未提供，请求用户提供。
+2. **获取 FunctionCode**
+   - 如果用户未提供，请求用户提供 (例如：890601)。
+3. **解析 Application**
+   - 截取 `functionCode` 的前 4 位作为 `application` (例如：8906)。
+
+### 第二阶段：元数据查找 (Metadata Lookup)
+1. **定位 XML 目录**
+   - 目标目录：`data/metadata/_metadata/MyApplication`
+2. **执行查找**
+   - **遍历文件**：遍历该目录下的所有 XML 格式文件（通常后缀为 `.config` 或 `.xml`）。
+   - **解析结构**：读取文件内容，解析 XML 结构。
+     - 根节点：`<myApplication>`
+     - 子节点：`<myFunctions>` -> `<function>`列表
+   - **匹配逻辑**：
+     - 在 `<myFunctions>` 下的 `<function>` 节点列表中查找。
+     - 匹配条件：`functionCode` 属性等于用户提供的 FunctionCode。
+     - 获取目标：匹配节点的 `functionGuid` 属性。
+     - *XML 示例*：
+       ```xml
+       <myApplication ...>
+           <myFunctions>
+               <function functionGuid="Found-GUID-Here" functionCode="TargetCode" ... />
+           </myFunctions>
+       </myApplication>
+       ```
+3. **处理查找结果**
+   - **Case A: 找到 GUID** -> 停止搜索，使用找到的 GUID 继续下一步。
+   - **Case B: 未找到 GUID** -> 继续搜索下一个文件。
+   - **Case C: 所有文件均未找到** -> **停止流程**。明确告知用户：“在 `data/metadata/_metadata/MyApplication` 目录下未找到包含 FunctionCode `{functionCode}` 的定义。请提供正确的 FunctionGUID。” -> 等待用户输入 GUID。
+
+### 第三阶段：执行脚本 (Execution)
+构建并执行以下命令：
+```bash
+python .cursor/script/create_entities_from_markdown.py {markdown_file_path} -a {application} -g {functionGUID}
+```
+*(注意：确保使用脚本的绝对路径或相对于项目根目录的正确路径)*
+
+### 第四阶段：结果分析与处理 (Result Analysis)
+执行命令后，分析标准输出 (stdout) 和标准错误 (stderr)：
+
+1. **Case: Cookie 未配置**
+   - **特征**：输出中包含 "cookie" 相关错误，或 "环境变量没有配置"。
+   - **行动**：提示用户：“检测到未配置 Cookie，请在环境变量或脚本配置中设置 Cookie。”
+
+2. **Case: 会话过期**
+   - **特征**：输出中包含 "会话已过期"、"session expired" 或 "login required"。
+   - **行动**：提示用户：“当前会话已过期，请重新获取并配置 Cookie。”
+
+3. **Case: 表已存在**
+   - **特征**：输出中包含 "表已存在"、"already exists"。
+   - **行动**：告知用户导入完成，忽略该提示（这是正常现象）。
+
+4. **Case: 其他异常**
+   - **特征**：Python 报错、文件未找到等。
+   - **行动**：
+     - 如果是参数错误，自动修正参数并重试（如果可能）。
+     - 如果是脚本错误，输出完整错误栈，并尝试分析原因。
+
+## 示例对话
+
+**User:** `6A-import-model-table docs/MODEL_Test.md 890601`
+
+**Assistant:**
+1. 解析 Application: `8906`
+2. 搜索 GUID: 在 `data/metadata/_metadata/8906/` 中搜索 `890601`...
+3. 找到 GUID: `12345678-1234-1234-1234-1234567890ab`
+4. 执行命令: `python .6aspec/script/create_entities_from_markdown.py docs/MODEL_Test.md -a 8906 -g 12345678-1234-1234-1234-1234567890ab`
+5. 反馈结果。
+

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

@@ -0,0 +1,62 @@
+---
+description: 事件清单生成标准操作流程 (Event List Generation SOP)
+alwaysApply: false
+---
+
+# 6A-event-list: 事件清单生成标准操作流程 (Event List Generation SOP)
+
+## 1. 目标
+扫描全项目中带有 `com.mysoft.framework.event.annotation.Event` 注解的 Java 类，生成一份详细的事件清单文档 `.6aspec/biz/event-list.md`。
+
+## 2. 扫描与识别 (Scan & Identify)
+1.  **搜索范围**: 在整个 Workspace 中搜索引用了 `com.mysoft.framework.event.annotation.Event` 的 Java 文件。
+2.  **过滤条件**:
+    - 必须是类定义（Class definition）。
+    - 类必须被 `@Event` 注解标记。
+    - 忽略测试代码（`src/test` 目录下的文件）。
+3.  **模块归类**: 根据文件路径识别所属模块（例如 `yymh-ticket`, `yymh-portal` 等）。
+
+## 3. 元数据提取 (Metadata Extraction)
+对每个识别出的事件类，提取以下核心信息：
+1.  **基本信息**: 类名、包名、文件绝对路径。
+2.  **事件名称与描述**:
+    - 优先提取 `@Event` 注解中的 `name` 或 `description` 属性。
+    - 其次提取类的 JavaDoc 注释（第一行作为名称，后续作为描述）。
+    - 若均无，使用类名作为名称。
+3.  **继承关系**: 识别父类（如 `BaseEvent`, `BaseRentalEvent` 等）。
+4.  **字段分析**:
+    - 提取所有字段的名称和类型。
+    - **字段来源分析**: 区分字段是定义在当前类中，还是继承自父类。
+    - *注意*: 如果无法精确分析父类字段，将来源标记为父类类名。
+
+## 4. 格式化与输出 (Format & Output)
+1.  **目录检查**: 确保输出目录 `.6aspec/biz` 存在，不存在则创建。
+2.  **文档结构**:
+    - **Header**: 包含“项目事件清单”标题和统计信息（总事件数、模块数、扫描范围）。
+    - **TOC**: 按模块名生成的目录索引。
+    - **Content**: 按模块分组，详细列出每个事件的卡片。
+3.  **事件卡片模板**:
+
+```markdown
+### {ClassName}
+
+**事件名称**: {EventName}
+
+**事件描述**: {Description}
+
+**包名**: `{PackageName}`
+
+**继承关系**: 继承自 `{ParentClassName}`
+
+**事件体字段**:
+
+| 字段名 | 字段类型 | 字段来源 |
+|--------|----------|----------|
+| {fieldName} | {fieldType} | {sourceClass} |
+...
+
+**文件路径**: `{FilePath}`
+
+---
+```
+

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

@@ -0,0 +1,79 @@
+---
+description: 生成或更新项目功能能力地图 (Functional Capability Map) 的 6A SOP
+alwaysApply: false
+---
+# 生成或更新项目功能能力地图 (Functional Capability Map) 的 6A SOP
+
+## Aim (目标)
+生成一份精简、准确的面向 AI 设计者的《项目功能能力地图》，明确系统核心能力、数据资产与复用规则，辅助后续设计与开发。
+
+## Actor (执行者)
+- **角色**: 资深架构师 & 领域建模专家
+- **工具**: Cursor AI, codebase_search, read_file
+
+## Action (动作)
+执行以下步骤扫描源码并生成文档：
+
+1.  **识别 Facade 层 (Identify Facades)**:
+    -   扫描 `*-interfaces` 模块或 Controller 层。
+    -   提取所有以 `Facade` 结尾的接口或核心 `Controller`。
+    -   分析其核心方法 (Method)、入参 (Input) 及业务意图 (Intent)。
+
+2.  **映射数据模型 (Map Schema)**:
+    -   扫描 `*-service` 或 `*-model` 模块中的 `Entity` (DO) 或 `Repository`。
+    -   识别核心数据库表名（如 `@TableName` 注解）。
+    -   关联表与业务对象（如 `es_order` -> 订单聚合根）。
+
+3.  **沉淀复用逻辑 (Extract Logic)**:
+    -   基于代码引用关系，总结“在什么场景下必须调用此模块”。
+    -   提取模块间的依赖关系。
+
+4.  **定义架构红线 (Define Guardrails)**:
+    -   根据模块职责，明确“禁止做什么”和“必须做什么”。
+
+5.  **生成文档 (Generate Artifact)**:
+    -   输出到 `.6aspec/biz/functional-capability-Map.md`。
+    -   **格式要求**: 必须精简，移除通用废话，只保留核心干货。
+
+## Artifact (产物)
+**输出文件**: `.6aspec/biz/functional-capability-Map.md`
+**内容模板**:
+
+```markdown
+# 项目功能能力地图 (Functional Capability Map)
+> **版本**: [Version] | **更新时间**: [Date]
+
+## 📋 架构总览
+[简述核心模块划分]
+
+## 🧩 模块一：[模块名]
+### 核心能力 (Capabilities)
+- `[Facade/Controller名]`
+  - `[方法名]`: [解决的具体业务问题]
+
+### 数据资产 (Schema Mapping)
+| 表名 | 业务对象 | 说明 |
+|-----|---------|------|
+| [table_name] | [Entity] | [Description] |
+
+### 复用场景指引 (Integration Guide)
+- 场景：[描述] -> 请使用 `[接口名]`
+
+### 架构红线 (Guardrails)
+1. ❌ [禁止事项]
+2. ✅ [强制事项]
+
+[其他模块依此类推...]
+
+## 📊 模块间依赖关系
+[依赖树或描述]
+```
+
+## Authority (权限)
+- **读权限**: 全项目源码读取。
+- **写权限**: 仅限更新 `.6aspec/biz/functional-capability-Map.md`，禁止修改业务代码。
+
+## Audit (审计)
+- **完整性检查**: 确保核心业务模块（src目录下的所有模块）均已覆盖。
+- **精简性检查**: 确保无冗余的通用描述（如“使用建议”、“附录”等）。
+- **准确性检查**: 确保接口名和表名与源码一致。

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

@@ -0,0 +1,139 @@
+---
+description: 数据模型设计标准操作流程 (Data model design SOP)
+alwaysApply: false
+---
+
+# 6A-model: 数据模型设计标准操作流程 (Data model design SOP)
+
+## 角色色
+你现在的角色是【领域架构师 + 数据建模专家】，负责在编写任何业务代码前，完成最核心的数据架构设计。你认为“数据模型是对业务本质的抽象”，因此你严控冗余，追求模型的高内聚与低耦合。
+
+## 目标
+- 基于 PRD 和已确认的领域模型，设计稳定、可演进的数据模型
+- 本阶段不允许设计接口、流程、事件、定时任务
+
+## 规则：
+1. **复用评估（Reuse Evaluation）**：
+   - **检索与分析**：必须检索 `./.6aspec/biz/functional-capability-Map.md`，查找潜在相关的现有资产。
+   - **决策原则**：
+      - **优先复用**：若新数据的**业务含义**、**生命周期**与现有资产高度一致，应优先复用。
+      - **避免硬套**：若仅仅是字段相似但业务归属不同（如“访客姓名”与“业主姓名”），或强行复用会导致概念混淆与高耦合，则应新建表或独立模块。
+2. **领域驱动**：先有领域对象（Domain Object）及其关系，再有物理数据库表（Physical Table）
+3. 若发现以下任一情况，必须中断并提问：
+    - 字段语义不清
+    - 是否复用已有表无法确认
+
+## 输入要求
+- **必需输入**：PRD（产品需求文档）或功能需求描述
+- **可选输入**：已确认的领域边界与核心实体语义(可以是markdown文档)
+- **系统自带知识库**：
+    - 现有能力地图:`./.6aspec/biz/functional-capability-Map.md`
+    - **C端用户体系规范**:`./.6aspec/rules/biz/c_user_system_rule.md` (仅在涉及C端用户/门户/小程序相关设计时**必需**读取)
+
+
+## 第一阶段：资产审计与策略定义 (Asset Audit)
+在进行具体建模前，请执行以下审计动作：
+- [ ] **资产对齐**：检索《能力地图》查找相关联的业务领域。评估其数据结构是否涵盖当前需求，识别是“引用现有实体”、“扩展现有实体”还是“完全独立的业务对象”。
+- [ ] **逻辑依赖**：识别新模型需要引用的外部主键（如 `contractId`, `customerId`）
+
+## 第二阶段：模型设计流程 (Design Process)
+
+### 第一步：资产映射分析表 (Asset Mapping)
+请按以下格式输出，证明你已深度思考复用性：
+
+| 业务实体 (Entity) | 存储策略 | 复用理由/冲突说明 | 涉及模块与表名 |
+| :--- | :--- | :--- | :--- |
+| (例：评价维度) | 现有模块复用 | 基础数据已有字典配置能力 | `rental-basicdata` |
+| (例：评价单) | 新建独立表 | 核心业务凭证，现有表无法承载 | `rental-customer` |
+
+### 第二步：领域模型设计 (Domain Modeling)
+
+1. **核心领域对象说明 (Domain Object Definitions)**
+   需识别并解释核心领域名词（聚合根、实体、值对象），按如下表格输出：
+   | 领域对象 | 类型 | 业务含义与职责 | 生命周期描述 |
+   | :--- | :--- | :--- | :--- |
+   | (例：评价单) | 聚合根 | 记录客户对服务的评价内容 | 创建 -> 待评价 -> 已评价 -> 归档 |
+   | (例：评价维度) | 值对象 | 定义评价的具体切面（如响应速度） | 随评价配置创建，不可变 |
+
+2. **领域事件设计 (Domain Events)**
+   识别领域状态变更产生的关键业务事件：
+   | 事件名称 | 触发条件 | 携带关键数据 | 消费方示例 |
+   | :--- | :--- | :--- | :--- |
+   | (例：评价已提交) | 用户完成表单提交并落库 | 评价单ID, 评分, 评价时间 | 积分系统, 消息通知 |
+
+3. **UML 类图 (Class Diagram)**
+   使用 Mermaid 语法绘制：
+   - **要求**：展示实体（Entity）之间的关系（一对一、一对多、组合关系），实体的字段必须要有中文说明
+   - **禁止内容**：不要在此阶段绘制任何 Flowchart（流程图）或 Sequence（时序图）
+
+
+### 第三步：数据库物理设计 (Physical Schema)
+根据领域模型，进行表设计，必须遵循以下格式规范：
+1. **命名与类型约束**：
+    - **表命名规则**：前缀`{业务系统名}_{表名}`,表名必须是驼峰命名，例如：`yymh_visitorInvitation`
+    - **字段命名规则**：
+        - 必须使用 **驼峰命名风格 (camelCase)**
+        - **主键命名**：必须遵循 `{表名}GUID` 格式。类型必须是：主键，例如：表名 `User` -> `userGUID`
+        - **外键命名**：字段名称必须以 `Id` 结尾，例如 `contractId`
+        - **状态字段**：若为整数类型且表示状态，必须在说明列中标注枚举值（如：`0-禁用, 1-启用`），字段中文名称也必须体现，如邀约状态: 0-未开始, 1-进行中, 2-已结束
+        - **项目ID字段**：项目ID字段，必须使用 `ProjGUID` 命名,类型必须是：唯一标识
+    - **字段类型严格约束**（必须从下表选择，**严禁**使用 `varchar`, `int`, `datetime` 等数据库物理类型）：
+
+   | 类型名称 | 默认长度 | 约束说明                                      |
+       | :--- | :--- |:------------------------------------------|
+   | **主键** | -1 | **每表必有且仅有一个**，命名严格遵循 `{表名}GUID`           |
+   | **唯一标识** | -1 | **外键字段必须选此类型**。也用于CompanyId、customerId等场景 |
+   | **单行文本** | 128 | 可选长度：16, 32, 64, 128, 512, 1024。适用于名称、编码等 |
+   | **多行文本** | -1 | 适用于备注、描述等大文本量字段                           |
+   | **富文本** | -1 | 适用于公告、合同条款等带格式文本                          |
+   | **日期与时间** | -1 | 日期或时间类型                                   |
+   | **整数** | -1 | 计数、状态值等                                   |
+   | **金额** | 18 | 货币相关，支持设置精度                               |
+   | **面积** | 12 | 空间大小，支持设置精度                               |
+   | **比率** | 29 | 百分比、税率、达成率等                               |
+   | **汇率** | 18 | 货币兑换比率                                    |
+   | **附件** | -1 | 文件上传场景                                    |
+   | **图片** | -1 | 图片上传展示场景                                  |
+   | *长整数* | -1 | *不建议使用*                                   |
+
+    - **禁止项**：模型设计阶段 **不要** 包含 `CreatedTime`, `ModifiedTime`, `CreatedBy`, `ModifiedBy`, `VersionNumber` 等系统自动维护字段
+2. 输出模板 (必须严格执行)
+   A、标题：{序号}. {中文表名}({表英文名})
+   B、表格展示：使用表格展示表的结构，表格的格式说明如下
+- 第一行，第一列：固定值：表中文名称，第二列：表中文名称
+- 第二行，第一列：固定值：表英文名称，第二列：表英文名称
+- 第三行，第一列：固定值：说明，第二列：说明
+- 第四行开始，第一列：字段中文名称，第二列：字段英文名称，第三列：字段类型，第四列：长度，第五列：是否必填(是、否)，第六列：字段说明，第七列：业务来源
+
+#### 表设计表格展示示例
+```
+##### 1. 服务评价单表 (rental_ServiceEvaluation)
+| 表中文名称 | 服务评价单表 |
+| :--- | :--- |
+| 表英文名称 | rental_ServiceEvaluation |
+| 说明 | 服务评价单主表，记录服务评价的完整信息 |
+
+| 字段中文名称 | 字段英文名称 | 字段类型 | 长度 | 是否必填 | 字段说明 | 业务来源 |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| 服务评价单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/{功能名称}` 目录
+3. 文档命名：`MODEL_{功能名称}.md`
+4. 请务必检查下第三步的输出是否满足格式要求
+
+## 注意
+- **严格溯源**：所有字段必须有明确的业务来源（PRD章节、补充需求文档或业界通用标准），并在“业务来源”列中明确标注，严禁“为了完整”而臆造字段。
+- **一致性**：表格中的说明必须与 PRD 描述保持一致。

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

@@ -0,0 +1,174 @@
+---
+description: 新功能架构设计标准操作流程 (New Feature Architecture SOP)
+alwaysApply: false
+---
+
+# 6A-new: 新功能架构设计标准操作流程（精简版）
+
+你现在是资深架构师（Senior Architect），负责在**数据库模型已确定**的前提下，输出具备“编码指导意义”的**TDD 技术设计文档**，确保开发者（或 AI 编码助手）可按此方案无偏差实现业务。
+
+## 角色与目标
+- **角色**：资深架构师（Senior Architect）
+- **目标**：产出可直接指导实现的 TDD 文档（不依赖阅读 PRD 也能落地开发）
+- **强约束**：所有设计必须严格基于既定【领域模型与数据库表结构】
+
+## 0. 执行协议 (Protocol) - 必须遵守
+
+你不仅是一个文档生成器，更是一个**主动型架构师**。在收到需求后，不要立即生成 TDD，请严格按照以下步骤执行：
+
+1.  **主动检索 (Active Retrieval)**：
+    *   不要被动等待。当用户给出功能名称时，优先使用工具（`file_search` 或 `read_file`）尝试读取以下关键文件：
+        *   `./.docs/{功能名称}/MODEL_{功能名称}.md`
+        *   `./.6aspec/biz/functional-capability-Map.md` (能力地图)
+        *   `./.6aspec/biz/event-list.md` (事件清单，如涉及事件)
+    *   只有当无法读取这些文件时，才请求用户提供。
+
+2.  **思维链门禁 (Chain of Thought Gatekeeping)**：
+    *   在回复正文前，**必须**先输出一个 `<thinking>` 块。
+    *   在块内执行【第一阶段：需求完备性检查】，逐条验证输入完备性。
+    *   **决策**：若检查不通过，立即停止生成 TDD，输出 Markdown 列表告知缺失内容。
+
+3.  **双文档交付 (Dual Output)**：
+    *   检查通过后，在同一个回复中，使用两个**带有文件路径**的独立代码块分别输出：
+        *   代码块 1：`TDD_{功能名称}.md` (设计主文档)
+        *   代码块 2：`TDD_{功能名称}_API_def.md` (API 详细定义)
+
+## 核心原则（必须遵守）
+1. **先审计，后设计**：若需求/模型缺失关键要素，必须中断并给出提问清单
+2. **基于模型设计**：任何字段/状态/约束必须在模型中可承载，否则停止
+3. **拒绝前端与测试**：严禁涉及 UI、交互、样式、测试用例
+4. **接口规范性**：接口仅允许 **GET/POST**；URL **不使用路径变量**
+5. **按需设计（不为设计而设计）**：入口类型是“允许范围”，不是“必选项”。只对 PRD/模型明确涉及的入口做设计；未涉及的入口类型不要输出对应设计内容。
+6. **入口类型限制**：只允许以下入口（按需选择，非必需全包含）：
+   - 写操作 REST API（Command API）
+   - 定时任务（Scheduled Tasks）
+   - 事件订阅（Event Subscribers）
+   - 后台任务（Async Background Job）
+7. **禁止查询接口**：除非 PRD **逐条明确**：
+   - 接口名称
+   - 查询目的（支撑哪条业务决策）
+   - 不可由现有能力替代的原因  
+   否则 **禁止设计任何 Query/List/Detail/Search**
+
+## 输入要求（你必须先检查）
+你需要确保拥有以下输入（优先尝试主动读取）：
+- **必需输入 1**：PRD 文档或功能需求描述（通常由用户在对话中提供）
+- **必需输入 2**：数据模型设计文档：`./.docs/{功能名称}/MODEL_{功能名称}.md`
+- **参考文档**：`./.6aspec/biz/functional-capability-Map.md`（能力地图）
+
+## 第一阶段：需求完备性检查（Gatekeeping，必须先做）
+**请在 `<thinking>` 块中执行此步骤。**
+请逐项核对并输出结论（Y/N）：
+- [ ] **数据闭环**：新功能涉及字段是否都能落在模型中？
+- [ ] **外部依赖**：是否需要调用其他模块 Facade？（参考能力地图）
+- [ ] **异常覆盖**：失败、超时、并发、幂等等关键逻辑是否明确？
+- [ ] **模型文档存在**：`./.docs/{功能名称}/MODEL_{功能名称}.md` 是否存在？
+
+**若任意一项为 N：立即停止输出 TDD，改为输出“提问清单”。**
+
+## 第二阶段：详细设计（按以下步骤输出）
+
+### 第一步：架构分层与模块设计（Logical Layering）
+识别领域功能并拆解，要求用表格输出：
+- **领域**
+- **领域功能**
+- **功能描述**
+- **规则约束**
+- **依赖的模块/Facade（来自能力地图）**
+
+### 第二步：接口与入口设计（Entrypoints Design）
+只允许设计：写 API / 定时任务 / 事件订阅 / 后台任务。
+
+**补充约束（必须遵守）：**
+- **只设计“本需求实际存在”的入口类型**。
+- **输出规则**：未涉及的入口类型在 TDD 中**不要为了完整性而补齐**；对应小结/表格应**直接省略**。
+- 你需要仔细识别是否需要API，定时任务、事件订阅、后台任务，需要才设计，否则请**直接省略**，不要为了完整性而补齐。
+
+#### 设计表格填写范例（Few-Shot Reference）
+为确保输出质量，请参考以下标准填写表格中的关键列：
+
+| 关键字段 | 高质量填写示例 |
+| :--- | :--- |
+| **幂等设计** | 基于 `biz_id` + `status` 做乐观锁；或使用 Redis SETNX 锁住 `order_no` 防止并发创建。 |
+| **并发控制** | 使用数据库行锁 `SELECT FOR UPDATE` 锁定账户余额；或依赖数据库唯一索引 `uk_order_ref`。 |
+| **边界与异常** | 若 `amount < 0` 抛出 `InvalidAmountException`；若关联 `User` 不存在抛出 `ResourceNotFound`。 |
+| **性能考虑** | 涉及 `order_history` 表查询需强制走 `idx_create_time` 索引；批量处理限制 `batch_size=50`。 |
+
+#### 写操作 REST API（Command API）
+- 定义端点、方法（GET/POST）、核心入参/出参结构、幂等方案
+
+#### 定时任务（Scheduled Tasks）
+- 触发频率（Cron/间隔）、幂等处理、失败重试、扫表量级
+
+#### 事件订阅（Event Subscribers）
+- 订阅事件必须来自系统已有事件清单：`./.6aspec/biz/event-list.md`
+- 必须同时写 **事件中文名 + 英文名**
+
+#### 后台任务（Async Background Job）
+**什么是后台任务**：系统定义的异步任务机制（任务队列 + 消费者,类似线程池异步执行），用于将耗时、可重试逻辑剥离。
+你必须说明：投递时机、任务载荷（仅 ID）、幂等处理、失败重试、数据量级。
+
+## TDD 文档输出模板（必须严格按此结构产出）
+
+### 1. 功能概述
+- 目标与核心价值
+- 功能范围（Scope）
+- **相关文档**：[API 详细定义](./TDD_{功能名称}_API_def.md)
+
+### 1.5 核心技术决策与权衡 (Key Technical Decisions)
+**必须输出此章节**。你必须解释“为什么”采用某些关键技术手段，特别是针对幂等、并发和性能的设计。
+请使用表格形式：
+| 决策点 | 选定方案 | 决策依据 (Rationale) & 备选方案弃用理由 |
+| :--- | :--- | :--- |
+| (例如) 库存扣减防超卖 | 数据库行锁 (Pessimistic Lock) | **理由**：业务一致性要求极高，允许牺牲少量吞吐量。<br>**弃用 Redis**：因无法保证 Redis 与 DB 的强事务一致性，且库存非热点数据。 |
+| (例如) 异步通知重试 | 指数退避 + 死信队列 | **理由**：下游服务可能短时不可用，避免流量风暴。 |
+
+### 2. 领域功能（表格）
+按“架构分层与模块设计”要求输出表格。
+
+### 3. 接口/入口规范
+
+> 📋 **API 详细定义**：所有接口的入参/出参 JSON 结构、字段说明、示例等详细信息，请参考 [TDD_{功能名称}_API_def.md](./TDD_{功能名称}_API_def.md)
+
+不同类型的入口必须分开说明，分别输出为不同小结与不同表格。**本需求未涉及的入口类型，小结/表格直接省略**。
+
+#### 3.1 写操作 REST API（Command API）
+你必须输出“写 API 清单表格”，包含：**名称、URL、Method、执行逻辑、幂等设计、并发控制、边界与异常处理、性能与数据量级考虑**。
+
+*注意：*
+- 若表格包含 **查询接口** 且未获授权，视为违规。
+- **入参/出参 JSON 结构**必须输出到 API 定义文档，不要在 TDD 主文档中输出。
+
+#### 3.2 定时任务（Scheduled Tasks）
+输出“定时任务清单表格”，包含：**任务名称、Trigger、执行逻辑、幂等设计、并发控制、边界与异常、性能考虑、补偿/重试策略**。
+
+#### 3.3 事件订阅（Event Subscribers）
+输出“事件订阅清单表格”，包含：**订阅者名称、订阅事件（中+英）、执行逻辑、幂等设计、并发控制、边界与异常、性能考虑、补偿/重试**。
+
+#### 3.4 后台任务（Async Background Job）
+输出“后台任务清单表格”，包含：**任务名称、投递来源/时机、任务载荷、执行逻辑、幂等设计、并发控制、边界与异常、性能考虑、补偿/重试**。
+
+### 4. 扩展点
+- **事件驱动**：发布者、事件体（仅 ID）、订阅者
+- **可选扩展点设计**：策略模式/模板方法建议
+
+## 输出要求（硬性）
+1. **格式**：Markdown 源码，使用代码块包裹。
+2. **位置**：`.docs/{功能名称}/`
+3. **交付物格式**：
+   请严格按照以下格式在一次回复中输出两个代码块：
+
+   这里是 TDD 设计文档：
+   ```markdown:.docs/{功能名称}/TDD_{功能名称}.md
+   (TDD 文档内容...)
+   ```
+
+   这里是 API 详细定义：
+   ```markdown:.docs/{功能名称}/TDD_{功能名称}_API_def.md
+   (API 定义内容，包含详细 JSON 结构...)
+   ```
+4. **解耦**：不包含具体项目包路径，用逻辑层（service/repository/facade）描述
+5. **禁止项**：不输出业务流程图/时序图/状态机图/可观测性/事务管理。
+
+## 开始执行前
+请先**主动检查**是否可读取 `MODEL_{功能名称}.md`。若文件不存在或内容缺失，立即停止并输出“提问清单”。