📝 docs(project): 生成项目上下文文档和架构文档

- 创建 project-context.md：50 条 AI Agent 必须遵循的关键规则
- 创建 architecture.md：E2E 测试工具包架构决策文档
- 包含技术栈、框架规则、测试规范和反模式指南
- 已针对 LLM 上下文效率优化

🤖 Generated with [Claude Code](https://claude.com/claude-code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

_bmad-output/planning-artifacts/architecture.md

@@ -0,0 +1,1013 @@
+---
+stepsCompleted: ['step-01-init', 'step-02-context', 'step-03-starter', 'step-04-decisions', 'step-05-patterns', 'step-06-structure', 'step-07-validation', 'step-08-complete']
+inputDocuments:
+  - name: PRD - E2E测试工具包
+    path: _bmad-output/planning-artifacts/prd.md
+    type: prd
+    loadedAt: '2026-01-08T02:10:00.000Z'
+  - name: 项目文档索引
+    path: docs/index.md
+    type: project-knowledge
+    loadedAt: '2026-01-08T02:10:00.000Z'
+  - name: Monorepo架构
+    path: docs/architecture/monorepo.md
+    type: project-doc
+    loadedAt: '2026-01-08T02:10:00.000Z'
+  - name: 模块组织结构
+    path: docs/architecture/module-structure.md
+    type: project-doc
+    loadedAt: '2026-01-08T02:10:00.000Z'
+  - name: 数据模型
+    path: docs/architecture/data-models.md
+    type: project-doc
+    loadedAt: '2026-01-08T02:10:00.000Z'
+  - name: API设计
+    path: docs/architecture/api-design.md
+    type: project-doc
+    loadedAt: '2026-01-08T02:10:00.000Z'
+  - name: 编码标准
+    path: docs/standards/coding-standards.md
+    type: project-doc
+    loadedAt: '2026-01-08T02:10:00.000Z'
+  - name: 后端模块开发规范
+    path: docs/standards/backend-module-standards.md
+    type: project-doc
+    loadedAt: '2026-01-08T02:10:00.000Z'
+  - name: UI包开发规范
+    path: docs/standards/ui-package-standards.md
+    type: project-doc
+    loadedAt: '2026-01-08T02:10:00.000Z'
+  - name: 测试规范
+    path: docs/standards/testing-standards.md
+    type: project-doc
+    loadedAt: '2026-01-08T02:10:00.000Z'
+workflowType: 'architecture'
+project_name: '188-179-template-6'
+user_name: 'Root'
+date: '2026-01-08T02:10:00.000Z'
+lastStep: 8
+status: 'complete'
+completedAt: '2026-01-08'
+---
+
+# Architecture Decision Document
+
+_This document builds collaboratively through step-by-step discovery. Sections are appended as we work through each architectural decision together._
+
+---
+
+## Project Context Analysis
+
+### Requirements Overview
+
+**Functional Requirements (50 total):**
+
+| 类别 | FR范围 | 架构含义 |
+|------|--------|----------|
+| Radix UI Select 测试 | FR1-FR6 | 需封装复杂的 Radix UI DOM 操作，区分静态/异步场景 |
+| 文件上传测试 | FR7-FR10 | 需处理 fixtures 文件管理和多文件上传场景 |
+| 表单交互测试 | FR11-FR15 | 需支持多步骤表单流程和滚动操作 |
+| 动态列表测试 | FR16-FR20 | 需处理动态 DOM 更新和异步状态管理 |
+| 对话框操作 | FR21-FR24 | 需统一的对话框打开/关闭/等待模式 |
+| 工具包基础设施 | FR25-FR32 | 需 npm workspace 集成、TypeScript 类型安全 |
+| 文档和开发支持 | FR33-FR40 | 需完整示例、迁移指南、快速入门 |
+| 质量保障 | FR41-FR45 | 需稳定性保障（20次连续运行100%通过） |
+| 可扩展性 | FR46-FR50 | 需配置化设计和版本升级兼容 |
+
+**Non-Functional Requirements (46 total):**
+
+| 类别 | NFR范围 | 架构驱动因素 |
+|------|--------|-------------|
+| 可靠性 | NFR1-NFR7 | 测试稳定性是核心，错误处理必须清晰 |
+| 性能 | NFR8-NFR14 | 静态Select 2秒、异步Select 5秒的性能约束 |
+| 集成性 | NFR15-NFR24 | Playwright 兼容、Monorepo workspace 集成 |
+| 代码质量 | NFR25-NFR40 | 无 any 类型、≥80% 覆盖率、JSDoc 完整 |
+| 兼容性 | NFR41-NFR46 | 跨浏览器、CI/CD 环境、版本升级兼容 |
+
+**Scale & Complexity:**
+
+- **Primary domain**: 开发者工具 / 测试基础设施
+- **Complexity level**: Low（相对独立的工具函数 + 文档）
+- **Estimated architectural components**: 6个核心工具函数 + 1个共享包
+
+### Technical Constraints & Dependencies
+
+**技术栈约束:**
+- 纯 TypeScript 实现，目标 ES2020+
+- 使用 pnpm workspace 协议进行本地开发
+- Peer dependency: `@playwright/test`（由测试项目提供）
+- 无运行时依赖，保持轻量
+
+**架构约束:**
+- 必须与现有 Page Object 模式集成
+- 必须遵循 Monorepo 架构规范
+- 必须兼容现有的测试基础设施（Vitest + Playwright）
+
+**外部依赖:**
+- Radix UI 组件库（DOM 结构变化风险）
+- Playwright 框架版本兼容性
+- 现有 `@d8d/shared-test-util`（后端集成测试，独立于本工具包）
+
+### Cross-Cutting Concerns Identified
+
+1. **测试稳定性**: 统一等待策略、错误处理、重试逻辑
+2. **开发体验**: 简洁 API、清晰错误提示、完整文档
+3. **可扩展性**: 支持配置对象、预留钩子函数
+4. **版本兼容性**: 使用 stable selectors（role、data-testid）应对 Radix UI 升级
+5. **Monorepo 集成**: 通过 workspace 协议安装，支持本地开发迭代
+
+---
+
+## Starter Template Evaluation
+
+### Primary Technology Domain
+
+开发者工具 / 测试基础设施包
+
+### Starter Options Considered
+
+**不适用**：本项目是在现有 Monorepo 中创建的内部测试工具包（`packages/e2e-test-utils`），而非独立应用项目。
+
+**技术栈已由现有项目确定：**
+- 纯 TypeScript，目标 ES2020+
+- Playwright 作为 peer dependency
+- Vitest 用于工具函数自测
+- 遵循现有 Monorepo 架构规范
+
+**包结构需要遵循：**
+- pnpm workspace 协议集成
+- 与现有测试基础设施兼容
+- 与现有包结构保持一致
+
+---
+
+## Core Architectural Decisions
+
+### Decision Priority Analysis
+
+**Critical Decisions (Block Implementation):**
+- ✅ 包内部结构：按功能分组
+- ✅ API 设计模式：3个必需参数 + 可选配置对象
+- ✅ 类型系统策略：分层类型（共享+特定）
+- ✅ 选择器策略：混合策略（testid → ARIA → 文本）
+
+**Important Decisions (Shape Architecture):**
+- ✅ 错误处理策略：结构化错误类 + 友好消息
+- ✅ 测试配置：三层测试策略
+
+**Deferred Decisions (Post-MVP):**
+- VS Code snippets
+- CLI 测试生成器
+- AI 辅助测试生成
+
+---
+
+### Package Structure
+
+**决策**: 按功能分组（选项B）
+
+**目录结构**:
+```
+packages/e2e-test-utils/
+├── src/
+│   ├── index.ts              # 主导出
+│   ├── types.ts              # 共享类型定义
+│   ├── radix-select.ts       # Radix UI Select 工具
+│   ├── file-upload.ts        # 文件上传工具
+│   ├── form-helper.ts        # 表单辅助函数
+│   ├── dialog.ts             # 对话框操作
+│   └── dynamic-list.ts       # 动态列表管理
+├── tests/
+│   ├── unit/                 # 单元测试
+│   ├── integration/          # 集成测试
+│   └── stability/            # 稳定性测试
+├── package.json
+└── README.md
+```
+
+**理由**: 清晰的职责分离，便于测试和维护
+
+---
+
+### API Design Pattern
+
+**决策**: 3个必需参数 + 可选配置对象
+
+**核心原则**:
+- 必需参数 ≤ 3 个
+- 复杂配置通过可选对象传递
+- 类型推断友好
+- JSDoc 完整
+
+**示例**:
+```typescript
+// 静态 Select - 简洁场景
+export async function selectRadixOption(
+  page: Page,
+  label: string,
+  value: string
+): Promise<void>
+
+// 异步 Select - 需要配置
+export async function selectRadixOptionAsync(
+  page: Page,
+  label: string,
+  value: string,
+  options?: AsyncSelectOptions
+): Promise<void>
+```
+
+---
+
+### Type System Strategy
+
+**决策**: 分层类型（选项C）
+
+**类型分层**:
+```
+types.ts (共享/基础类型)
+├── BaseOptions (超时等通用配置)
+└── 导出 Playwright 类型
+
+各模块文件 (特定类型)
+├── radix-select.ts → AsyncSelectOptions
+├── file-upload.ts → FileUploadOptions
+└── ...
+```
+
+**优势**:
+- 共享类型统一管理
+- 特定类型就近定义
+- 支持类型复用和扩展
+
+---
+
+### Selector Strategy
+
+**决策**: 混合策略（testid → ARIA → 文本）
+
+**优先级**:
+1. `data-testid` - 最高优先级，需开发团队配合
+2. `aria-label` + role - 无障碍标准
+3. Text content + role - 兜底方案
+
+**配套措施**:
+- 推荐在 Radix 组件上添加 `data-testid`
+- 提供迁移指南
+
+---
+
+### Error Handling Strategy
+
+**决策**: 结构化错误类 + 友好消息
+
+**错误结构**:
+```typescript
+export class E2ETestError extends Error {
+  constructor(
+    public readonly context: ErrorContext,
+    message?: string
+  ) { ... }
+}
+
+export interface ErrorContext {
+  operation: string;      // 操作类型
+  target: string;         // 目标
+  expected?: string;      // 期望值
+  actual?: string;        // 实际值
+  available?: string[];   // 可用选项
+  suggestion?: string;    // 修复建议
+}
+```
+
+**示例输出**:
+```
+❌ selectOption failed
+Target: 残疾类型
+Expected: 视力残疾
+Available: 听力残疾, 言语残疾, 肢体残疾
+💡 Suggestion: Check if the option value matches exactly
+```
+
+---
+
+### Testing Configuration
+
+**决策**: 三层测试策略
+
+| 测试类型 | 范围 | 工具 | 目标 |
+|----------|------|------|------|
+| 单元测试 | 单个函数逻辑 | **Vitest** | ≥80% 覆盖率 |
+| 集成测试 | 与 DOM/浏览器交互 | **Playwright** | 验证实际操作 |
+| 稳定性测试 | 20次连续运行 | **Playwright** | 100% 通过率 |
+
+**集成测试基础设施**：
+- 创建独立的测试应用 `tests/test-app/`
+- 使用 Vite + React
+- 导入 `@d8d/shared-ui-components` 的实际组件
+- Playwright 配置自动启动测试应用服务器
+
+**配置文件**:
+```typescript
+// vitest.config.ts - 单元测试
+{
+  coverage: { statements: 80, branches: 80, functions: 80, lines: 80 },
+  testTimeout: 10000,
+}
+
+// playwright.config.ts - 集成/稳定性测试
+{
+  testDir: './tests/integration',
+  webServer: {
+    command: 'pnpm --filter @d8d/e2e-test-utils-test-app dev',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !process.env.CI,
+  },
+}
+```
+
+---
+
+### Decision Impact Analysis
+
+**Implementation Sequence:**
+1. 创建包结构 + package.json
+2. 实现 types.ts + index.ts
+3. 实现各工具函数（从简单到复杂）
+4. 编写单元测试
+5. 编写集成测试
+6. 编写稳定性测试
+7. 在残疾人管理中验证
+
+**Cross-Component Dependencies:**
+- 所有工具函数依赖 `types.ts`
+- index.ts 依赖所有模块（tree-shakeable 导出）
+- 测试依赖完整的函数实现
+
+---
+
+## Implementation Patterns & Consistency Rules
+
+### Pattern Categories Defined
+
+**Critical Conflict Points Identified:**
+4 个类别，每个类别都可能导致 AI Agent 实现不一致
+
+### Naming Patterns
+
+**函数命名约定**：
+- 风格：动词+名词，camelCase
+- 示例：`selectRadixOption`、`uploadFileToField`、`fillMultiStepForm`
+- 异步函数：添加 `Async` 后缀（如 `selectRadixOptionAsync`）
+
+**类型命名约定**：
+- 接口：PascalCase，`Options` 后缀
+- 示例：`AsyncSelectOptions`、`FileUploadOptions`
+- 基础类型：`BaseOptions` 作为所有配置的基类
+
+**测试文件命名**：
+- 单元测试：与源文件同名，`.test.ts` 后缀
+- 集成测试：描述性名称，如 `select-scenarios.test.ts`
+- 稳定性测试：`stability.test.ts`
+
+### Structure Patterns
+
+**测试目录结构**：
+```
+tests/
+├── fixtures/           # 集中管理测试资源
+│   ├── images/        # 测试图片
+│   └── data/          # 测试数据
+├── unit/              # 单元测试（无 Playwright）
+├── integration/       # 集成测试（需要 Playwright）
+└── stability/         # 稳定性测试
+```
+
+**源文件组织**：
+- 每个工具函数独立文件
+- `types.ts` 存放共享类型
+- `index.ts` 作为主导出（tree-shakeable）
+
+### Format Patterns
+
+**JSDoc 格式**：
+```typescript
+/**
+ * 函数描述（简洁说明）
+ *
+ * @param paramName - 参数描述
+ * @param paramTwo - 参数描述
+ * @throws {E2ETestError} 错误条件
+ * @example
+ * ```ts
+ * await functionName(page, 'arg', 'value');
+ * ```
+ */
+```
+
+**配置对象格式**：
+```typescript
+// 所有可选配置都继承 BaseOptions
+export interface XxxOptions extends BaseOptions {
+  /** 特定选项描述 */
+  specificOption?: boolean;
+}
+
+export interface BaseOptions {
+  /** 超时时间（毫秒）*/
+  timeout?: number;
+}
+```
+
+**错误消息格式**：
+- 标题：❌ 操作失败
+- 上下文：目标、期望值、实际值
+- 建议：💡 修复建议
+
+### Process Patterns
+
+**选择器查找流程**：
+```typescript
+const SELECTOR_STRATEGIES = [
+  findByTestId,      // 1. data-testid
+  findByAria,        // 2. aria-label + role
+  findByText,        // 3. text content + role
+] as const;
+// 按优先级尝试，找到即返回
+```
+
+**等待策略常量**：
+```typescript
+export const DEFAULT_TIMEOUTS = {
+  static: 2000,      // 静态选项
+  async: 5000,       // 异步选项
+  networkIdle: 10000, // 网络空闲
+} as const;
+```
+
+**错误处理流程**：
+```typescript
+// 1. 捕获底层错误
+// 2. 转换为 E2ETestError
+// 3. 包含完整 ErrorContext
+export function throwError(context: ErrorContext): never {
+  throw new E2ETestError(context, formatErrorMessage(context));
+}
+```
+
+### Enforcement Guidelines
+
+**所有 AI Agent 必须：**
+
+1. **遵循命名约定**：函数、类型、文件名按规范命名
+2. **使用完整 JSDoc**：每个导出函数必须有完整文档
+3. **统一错误处理**：使用 `E2ETestError` 和 `ErrorContext`
+4. **按优先级查找选择器**：testid → ARIA → 文本
+5. **使用常量定义超时**：从 `DEFAULT_TIMEOUTS` 获取
+6. **配置对象继承 BaseOptions**：确保一致性
+
+**强制执行方式：**
+- ESLint 规则检查命名
+- TypeScript 严格类型检查
+- 测试覆盖率 ≥80%
+- Code Review 验证模式
+
+### Pattern Examples
+
+**正确示例**：
+```typescript
+// ✅ 正确：遵循命名和格式约定
+/**
+ * 选择 Radix UI 下拉框的静态选项
+ *
+ * @param page - Playwright Page 对象
+ * @param label - 下拉框标签文本
+ * @param value - 要选择的选项值
+ * @throws {E2ETestError} 当下拉框或选项未找到时
+ */
+export async function selectRadixOption(
+  page: Page,
+  label: string,
+  value: string
+): Promise<void> {
+  try {
+    // 实现逻辑
+  } catch (error) {
+    throwError({
+      operation: 'selectRadixOption',
+      target: label,
+      expected: value,
+    });
+  }
+}
+```
+
+**反模式（避免）**：
+```typescript
+// ❌ 错误：缺少 JSDoc
+export async function select(p: any, l: string, v: string) {}
+
+// ❌ 错误：使用 any 类型
+export async function selectOption(
+  page: Page,
+  label: any,
+  value: any
+): Promise<void> {}
+
+// ❌ 错误：自定义错误类型
+throw new Error('Select failed');
+
+// ❌ 错误：硬编码超时
+await page.waitForTimeout(5000);
+```
+
+---
+
+## Project Structure & Boundaries
+
+### Complete Project Directory Structure
+
+```
+packages/e2e-test-utils/
+├── src/
+│   ├── index.ts                    # 主导出，tree-shakeable
+│   ├── types.ts                    # 共享类型定义
+│   ├── errors.ts                   # 错误类和错误处理
+│   ├── constants.ts                # 常量定义（超时、选择器策略等）
+│   ├── radix-select.ts             # Radix UI Select 工具
+│   ├── file-upload.ts              # 文件上传工具
+│   ├── form-helper.ts              # 表单辅助函数
+│   ├── dialog.ts                   # 对话框操作
+│   └── dynamic-list.ts             # 动态列表管理
+├── tests/
+│   ├── fixtures/
+│   │   ├── images/
+│   │   │   ├── sample-id-card.jpg
+│   │   │   └── sample-disability-card.jpg
+│   │   └── data/
+│   │       └── test-users.json
+│   ├── test-app/                   # 独立测试应用
+│   │   ├── package.json
+│   │   ├── vite.config.ts
+│   │   ├── index.html
+│   │   ├── main.tsx
+│   │   └── pages/
+│   │       ├── select.tsx          # Select 测试页面
+│   │       ├── dialog.tsx          # Dialog 测试页面
+│   │       ├── file-upload.tsx     # 文件上传测试页面
+│   │       ├── form.tsx            # 表单测试页面
+│   │       └── dynamic-list.tsx    # 动态列表测试页面
+│   ├── unit/                       # Vitest 单元测试
+│   │   ├── radix-select.test.ts
+│   │   ├── file-upload.test.ts
+│   │   ├── form-helper.test.ts
+│   │   ├── dialog.test.ts
+│   │   └── dynamic-list.test.ts
+│   ├── integration/                # Playwright 集成测试
+│   │   ├── select-scenarios.spec.ts
+│   │   ├── upload-scenarios.spec.ts
+│   │   └── form-scenarios.spec.ts
+│   └── stability/                  # Playwright 稳定性测试
+│       └── repeat-run.spec.ts
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts                # 单元测试配置
+├── playwright.config.ts            # 集成/稳定性测试配置
+├── README.md
+└── CHANGELOG.md
+```
+
+### Architectural Boundaries
+
+**包边界**：
+- **输入**: 接收 Playwright `Page` 对象作为参数
+- **输出**: 返回 `Promise<void>` 或抛出 `E2ETestError`
+- **依赖**: Peer dependency `@playwright/test`，无运行时依赖
+
+**工具函数边界**：
+- 每个工具函数独立运行，无共享状态
+- 不依赖其他工具函数（避免循环依赖）
+- 所有共享逻辑通过 `types.ts`、`errors.ts`、`constants.ts` 提供
+
+### Requirements to Structure Mapping
+
+**FR 类别 → 文件映射**：
+
+| FR 类别 | 文件 | 说明 |
+|---------|------|------|
+| FR1-FR6 (Radix UI Select) | `radix-select.ts` | 静态和异步 Select 工具 |
+| FR7-FR10 (文件上传) | `file-upload.ts` | 文件上传工具 |
+| FR11-FR15 (表单交互) | `form-helper.ts` | 多步骤表单、滚动 |
+| FR16-FR20 (动态列表) | `dynamic-list.ts` | 添加/删除列表项 |
+| FR21-FR24 (对话框) | `dialog.ts` | 对话框操作 |
+| FR25-FR32 (工具包基础设施) | `index.ts`, `package.json` | 包导出和配置 |
+| FR41-FR45 (质量保障) | `tests/` | 所有测试文件 |
+
+### Integration Points
+
+**内部通信**：
+- 工具函数通过 `types.ts` 共享类型定义
+- 通过 `errors.ts` 统一错误处理
+- 通过 `constants.ts` 共享配置常量
+
+**外部集成**：
+- **Playwright**: 通过 peer dependency 集成，提供 `Page` 对象
+- **测试项目**: 通过 workspace 协议安装：`@d8d/e2e-test-utils@workspace:*`
+- **现有 Page Object**: 可与现有 Page Object 模式共存
+
+**数据流**：
+```
+测试代码 → 工具函数 → Playwright API → DOM 操作
+                ↓
+            E2ETestError (失败时)
+```
+
+### File Organization Patterns
+
+**配置文件**：
+- `package.json`: 包定义、workspace 协议配置
+- `tsconfig.json`: TypeScript 严格模式配置
+- `vitest.config.ts`: Vitest 单元测试配置、覆盖率目标
+- `playwright.config.ts`: Playwright 集成/稳定性测试配置、测试应用服务器
+
+**源码组织**：
+- 按功能分组（每个工具函数一个文件）
+- 共享代码集中在 `types.ts`、`errors.ts`、`constants.ts`
+- `index.ts` 作为主导出点，支持 tree-shaking
+
+**测试组织**：
+- `tests/unit/`: Vitest 单元测试，测试单个函数逻辑
+- `tests/integration/`: Playwright 集成测试，验证与真实 DOM 的交互
+- `tests/stability/`: Playwright 稳定性测试，20次连续运行
+- `tests/test-app/`: 独立测试应用，提供 @d8d/shared-ui-components 组件测试环境
+- `tests/fixtures/`: 测试资源集中管理
+
+---
+
+## Architecture Validation Results
+
+### Coherence Validation ✅
+
+**Decision Compatibility:**
+
+所有核心技术决策相互兼容，无冲突：
+- ✅ TypeScript ES2020+ 与 Playwright peer dependency 兼容
+- ✅ 按功能分组的包结构与分层类型系统一致
+- ✅ 混合选择器策略支持错误处理中的上下文信息
+- ✅ 三层测试策略与工具函数设计模式匹配
+
+**Pattern Consistency:**
+
+实现模式完全支持架构决策：
+- ✅ 命名约定与 API 设计模式一致（动词+名词，camelCase）
+- ✅ 配置对象继承 BaseOptions 与类型系统策略一致
+- ✅ 错误处理流程使用结构化错误类
+- ✅ 选择器查找流程遵循混合策略优先级
+
+**Structure Alignment:**
+
+项目结构完全支持所有架构决策：
+- ✅ 测试目录结构分离单元测试和集成测试
+- ✅ test-app 提供真实的 @d8d/shared-ui-components 测试环境
+- ✅ 源文件组织支持按功能分组和独立模块
+- ✅ 配置文件完整覆盖所有测试工具
+
+### Requirements Coverage Validation ✅
+
+**Epic/Feature Coverage:**
+
+所有 50 个功能需求都有架构支持：
+
+| FR 类别 | 架构支持 | 验证 |
+|---------|----------|------|
+| FR1-FR6 (Radix UI Select) | `radix-select.ts` + test-app/pages/select.tsx | ✅ |
+| FR7-FR10 (文件上传) | `file-upload.ts` + test-app/pages/file-upload.tsx | ✅ |
+| FR11-FR15 (表单交互) | `form-helper.ts` + test-app/pages/form.tsx | ✅ |
+| FR16-FR20 (动态列表) | `dynamic-list.ts` + test-app/pages/dynamic-list.tsx | ✅ |
+| FR21-FR24 (对话框) | `dialog.ts` + test-app/pages/dialog.tsx | ✅ |
+| FR25-FR32 (工具包基础设施) | `index.ts` + `package.json` | ✅ |
+| FR33-FR40 (文档和开发支持) | README.md + JSDoc 完整性要求 | ✅ |
+| FR41-FR45 (质量保障) | 三层测试策略 + 稳定性测试 | ✅ |
+| FR46-FR50 (可扩展性) | 配置对象设计 + BaseOptions 扩展 | ✅ |
+
+**Functional Requirements Coverage:**
+
+所有功能需求类别完全覆盖：
+- ✅ Radix UI 组件测试：6个核心工具函数 + 独立测试应用
+- ✅ 文件上传测试：fixtures 管理 + Playwright 文件上传 API
+- ✅ 表单交互测试：多步骤表单支持 + 滚动操作常量
+- ✅ 动态列表测试：添加/删除列表项工具函数
+- ✅ 对话框操作：统一的打开/关闭/等待模式
+- ✅ 工具包基础设施：workspace 协议 + TypeScript 类型安全
+- ✅ 文档和开发支持：JSDoc 完整性 + README 模板
+- ✅ 质量保障：80% 覆盖率 + 20次连续稳定性测试
+- ✅ 可扩展性：配置对象 + 版本升级兼容性
+
+**Non-Functional Requirements Coverage:**
+
+所有 46 个非功能需求都已处理：
+
+| NFR 类别 | 架构支持 | 验证 |
+|---------|----------|------|
+| NFR1-NFR7 (可靠性) | E2ETestError + ErrorContext + 友好错误消息 | ✅ |
+| NFR8-NFR14 (性能) | DEFAULT_TIMEOUTS 常量 + 超时配置 | ✅ |
+| NFR15-NFR24 (集成性) | Playwright peer dependency + workspace 协议 | ✅ |
+| NFR25-NFR40 (代码质量) | 无 any 类型 + 80% 覆盖率 + JSDoc 完整 | ✅ |
+| NFR41-NFR46 (兼容性) | 稳定选择器策略 + 跨浏览器测试 | ✅ |
+
+### Implementation Readiness Validation ✅
+
+**Decision Completeness:**
+
+所有关键决策都已记录版本和理由：
+- ✅ 包内部结构：按功能分组
+- ✅ API 设计模式：3个必需参数 + 可选配置对象
+- ✅ 类型系统策略：分层类型（共享+特定）
+- ✅ 选择器策略：混合策略（testid → ARIA → 文本）
+- ✅ 错误处理策略：结构化错误类 + 友好消息
+- ✅ 测试配置：三层测试策略（Vitest + Playwright）
+
+**Structure Completeness:**
+
+项目结构完整且具体：
+- ✅ 所有源文件和目录已定义
+- ✅ 测试应用结构完整（test-app/）
+- ✅ 集成点清晰指定（Playwright、测试项目）
+- ✅ 组件边界明确定义
+
+**Pattern Completeness:**
+
+所有潜在冲突点都已解决：
+- ✅ 命名约定：函数、类型、文件名
+- ✅ 结构模式：测试目录、源文件组织
+- ✅ 格式模式：JSDoc、配置对象、错误消息
+- ✅ 流程模式：选择器查找、等待策略、错误处理
+
+### Gap Analysis Results
+
+**Critical Gaps:** 无
+
+**Important Gaps:** 无
+
+**Nice-to-Have Gaps:**
+- 📝 VS Code snippets 代码片段（已推迟到 MVP 后）
+- 📝 CLI 测试生成器（已推迟到 MVP 后）
+- 📝 AI 辅助测试生成（已推迟到 MVP 后）
+
+### Validation Issues Addressed
+
+**集成测试基础设施问题（已解决）：**
+
+**问题描述：**
+原始架构将集成测试配置为使用 Vitest 运行 Playwright，这不符合 Playwright 的最佳实践。
+
+**解决方案：**
+- ✅ 分离单元测试和集成测试工具
+- ✅ 单元测试使用 Vitest（测试纯函数逻辑）
+- ✅ 集成测试和稳定性测试使用 Playwright（测试真实浏览器交互）
+- ✅ 创建独立测试应用 `tests/test-app/` 提供 @d8d/shared-ui-components 测试环境
+- ✅ Playwright 配置自动启动测试应用服务器
+
+**架构影响：**
+- 更新 `Testing Configuration` 部分
+- 更新项目目录结构，添加 `tests/test-app/`
+- 添加 `playwright.config.ts` 配置文件
+- 更新测试文件命名约定（`.spec.ts` 用于 Playwright）
+
+### Architecture Completeness Checklist
+
+**✅ Requirements Analysis**
+- [x] 项目上下文彻底分析
+- [x] 规模和复杂度评估
+- [x] 技术约束识别
+- [x] 跨领域关注点映射
+
+**✅ Architectural Decisions**
+- [x] 关键决策文档化并记录版本
+- [x] 技术栈完全指定
+- [x] 集成模式定义
+- [x] 性能考虑已处理
+
+**✅ Implementation Patterns**
+- [x] 命名约定建立
+- [x] 结构模式定义
+- [x] 通信模式指定
+- [x] 流程模式文档化
+
+**✅ Project Structure**
+- [x] 完整目录结构定义
+- [x] 组件边界建立
+- [x] 集成点映射
+- [x] 需求到结构映射完成
+
+**✅ Testing Strategy**
+- [x] 三层测试策略定义
+- [x] 测试工具选择合理（Vitest + Playwright）
+- [x] 集成测试基础设施完整
+- [x] 稳定性测试方法明确
+
+### Architecture Readiness Assessment
+
+**Overall Status:** READY FOR IMPLEMENTATION
+
+**Confidence Level:** HIGH
+
+**Key Strengths:**
+1. ✅ 清晰的模块化设计，按功能分组
+2. ✅ 完整的类型系统策略，支持类型推断
+3. ✅ 结构化的错误处理，提供友好错误消息
+4. ✅ 灵活的选择器策略，应对 Radix UI 版本升级
+5. ✅ 合理的测试分层，单元测试与集成测试分离
+6. ✅ 独立的测试应用，支持真实组件交互测试
+7. ✅ 完整的一致性规则，确保 AI Agent 实现一致性
+
+**Areas for Future Enhancement:**
+1. 📝 VS Code snippets 提升开发体验
+2. 📝 CLI 测试生成器加速测试编写
+3. 📝 AI 辅助测试生成降低学习曲线
+
+### Implementation Handoff
+
+**AI Agent Guidelines:**
+
+1. **严格遵循所有架构决策**：按文档中的定义实现，不得偏离
+2. **使用实现模式保持一致性**：所有 AI Agent 必须遵循命名、结构、格式、流程模式
+3. **尊重项目结构和边界**：按定义的目录结构组织代码
+4. **参考架构文档解决所有问题**：遇到不确定的情况时查阅此文档
+
+**First Implementation Priority:**
+
+```bash
+# 1. 创建包基础结构
+mkdir -p packages/e2e-test-utils/src
+mkdir -p packages/e2e-test-utils/tests/{unit,integration,stability,fixtures/{images,data}}
+
+# 2. 创建测试应用
+mkdir -p packages/e2e-test-utils/tests/test-app/pages
+
+# 3. 初始化 package.json（包含正确的 peer dependencies）
+# 4. 实现 types.ts 和 index.ts
+# 5. 从简单到复杂实现各工具函数
+# 6. 编写单元测试（Vitest）
+# 7. 编写集成测试（Playwright + test-app）
+# 8. 在残疾人管理功能中验证
+```
+
+**Success Criteria:**
+- ✅ 所有 50 个功能需求实现
+- ✅ 所有 46 个非功能需求满足
+- ✅ 单元测试覆盖率 ≥80%
+- ✅ 稳定性测试 20 次连续运行 100% 通过
+- ✅ 在残疾人管理功能中成功使用
+
+---
+
+## Architecture Completion Summary
+
+### Workflow Completion
+
+**Architecture Decision Workflow:** COMPLETED ✅
+**Total Steps Completed:** 8
+**Date Completed:** 2026-01-08
+**Document Location:** _bmad-output/planning-artifacts/architecture.md
+
+### Final Architecture Deliverables
+
+**📋 Complete Architecture Document**
+
+- 所有架构决策已文档化，包含明确的技术选择
+- 确保一致性：AI 实现模式和规则完整定义
+- 项目结构完整：所有文件和目录都已定义
+- 需求映射清晰：从 FR/NFR 到具体文件的映射
+- 验证通过：架构一致性和完整性已确认
+
+**🏗️ Implementation Ready Foundation**
+
+- 6 个核心架构决策（包结构、API 设计、类型系统、选择器策略、错误处理、测试配置）
+- 4 个一致性规则类别（命名、结构、格式、流程）
+- 6 个核心工具函数 + 1 个共享测试应用
+- 50 个功能需求 + 46 个非功能需求完全支持
+
+**📚 AI Agent Implementation Guide**
+
+- 技术栈：TypeScript ES2020+、Playwright、Vitest
+- 一致性规则：防止 AI Agent 实现冲突
+- 项目结构：清晰的边界和集成点
+- 集成模式：workspace 协议、peer dependencies
+
+### Implementation Handoff
+
+**For AI Agents:**
+本架构文档是实现 E2E 测试工具包的完整指南。严格遵循所有决策、模式和结构。
+
+**First Implementation Priority:**
+
+```bash
+# 1. 创建包基础结构
+mkdir -p packages/e2e-test-utils/src
+mkdir -p packages/e2e-test-utils/tests/{unit,integration,stability,fixtures/{images,data}}
+
+# 2. 创建测试应用
+mkdir -p packages/e2e-test-utils/tests/test-app/pages
+
+# 3. 初始化 package.json
+{
+  "name": "@d8d/e2e-test-utils",
+  "version": "1.0.0",
+  "type": "module",
+  "peerDependencies": {
+    "@playwright/test": "^1.40.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4",
+    "vite": "^6.0.11",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  }
+}
+
+# 4. 实现 types.ts 和 index.ts
+# 5. 从简单到复杂实现各工具函数
+# 6. 编写单元测试（Vitest）
+# 7. 编写集成测试（Playwright + test-app）
+# 8. 在残疾人管理功能中验证
+```
+
+**Development Sequence:**
+
+1. 初始化包结构和配置文件
+2. 实现类型定义和主导出
+3. 实现核心工具函数（radix-select → dialog → file-upload → form-helper → dynamic-list）
+4. 编写单元测试（Vitest）
+5. 创建测试应用并编写集成测试（Playwright）
+6. 编写稳定性测试（20次连续运行）
+7. 在残疾人管理功能中验证
+
+### Quality Assurance Checklist
+
+**✅ Architecture Coherence**
+
+- [x] 所有决策无冲突，协同工作
+- [x] 技术选择完全兼容
+- [x] 模式支持架构决策
+- [x] 结构与所有选择一致
+
+**✅ Requirements Coverage**
+
+- [x] 所有功能需求都有支持
+- [x] 所有非功能需求都已处理
+- [x] 跨领域关注点已解决
+- [x] 集成点已明确定义
+
+**✅ Implementation Readiness**
+
+- [x] 决策具体且可执行
+- [x] 模式防止 Agent 冲突
+- [x] 结构完整且无歧义
+- [x] 提供清晰示例
+
+### Project Success Factors
+
+**🎯 Clear Decision Framework**
+每个技术选择都是协作完成的，有清晰的理由，确保所有利益相关者理解架构方向。
+
+**🔧 Consistency Guarantee**
+实现模式和规则确保多个 AI Agent 将产生兼容、一致的代码。
+
+**📋 Complete Coverage**
+所有项目需求都有架构支持，从业务需求到技术实现的清晰映射。
+
+**🏗️ Solid Foundation**
+选择的测试策略和架构模式提供了生产就绪的基础。
+
+---
+
+**Architecture Status:** READY FOR IMPLEMENTATION ✅
+
+**Next Phase:** 开始实现阶段，使用文档化的架构决策和模式。
+
+**Document Maintenance:** 当实现过程中做出重大技术决策时，更新此架构文档。
+
+---
+
+**🎉 架构工作流程完成！**
+
+你的 E2E 测试工具包架构已经全面完成，经过验证，可以开始实现了。
+
+**✅ 交付内容：**
+
+- 完整的架构文档，包含所有决策和模式
+- 为 AI Agent 实现准备好的项目结构
+- 验证确认所有部分协同工作
+- 开发阶段的实施指导
+
+**📍 文档位置：**
+`_bmad-output/planning-artifacts/architecture.md`
+
+**🚀 下一步：**
+
+1. 查看完整的架构文档
+2. 创建包结构开始实现
+3. 为 AI Agent 创建实现任务，遵循架构决策
+
+你的架构将确保所有开发工作的一致、高质量实现。恭喜完成这些重要的架构决策！

_bmad-output/project-context.md

@@ -0,0 +1,583 @@
+---
+project_name: '188-179-template-6'
+user_name: 'Root'
+date: '2026-01-08T00:00:00.000Z'
+sections_completed:
+  - technology_stack
+  - language_rules
+  - framework_rules
+  - test_rules
+  - code_quality_rules
+  - anti_patterns
+status: complete
+rule_count: 50
+optimized_for_llm: true
+---
+
+# Project Context for AI Agents
+
+_This file contains critical rules and patterns that AI agents must follow when implementing code in this project. Focus on unobvious details that agents might otherwise miss._
+
+---
+
+## Technology Stack & Versions
+
+### Core Technologies
+
+| 类别 | 技术 | 版本 | 用途 |
+|------|------|------|------|
+| **包管理** | pnpm | 10.18.3 | Monorepo工作空间管理 |
+| **TypeScript** | typescript | 5.9.3 | 类型安全，严格模式 |
+| **前端框架** | React | 19.1.0 | Web应用UI |
+| **前端框架** | Taro | 3.x | 小程序开发 |
+| **构建工具** | Vite | 7.x | 快速构建和热重载 |
+| **后端框架** | Hono | 4.8.5 | API服务器 |
+| **数据库ORM** | TypeORM | 0.3.25 | 数据库操作 |
+| **数据库** | PostgreSQL | 17 | 主数据库 |
+| **缓存** | Redis | 7 | 缓存和会话 |
+| **存储** | MinIO | 8.0.5 | 对象存储 |
+
+### Testing Stack
+
+| 测试类型 | 工具 | 版本 | 用途 |
+|----------|------|------|------|
+| **Web/后端测试** | Vitest | 3.2.4 | 主要测试运行器 |
+| **Mini UI测试** | Jest | 最新 | Mini UI包测试 |
+| **E2E测试** | Playwright | 1.55.0 | 端到端测试 |
+| **组件测试** | Testing Library | 16.3.0 | React组件测试 |
+| **DOM环境** | Happy DOM | 18.0.1 | 轻量级DOM环境 |
+
+### UI Libraries
+
+| 库 | 版本 | 用途 |
+|----|------|------|
+| Radix UI | Latest | 无障碍组件库 |
+| Tailwind CSS | 4.1.11 | 样式框架 |
+| Heroicons | 2.2.0 | 图标库 |
+| Ant Design Icons | 6.0.0 | 补充图标 |
+
+### Development Environment
+
+- **Node.js**: 20.19.2
+- **默认端口**: 8080
+- **开发服务器**: 自动启动在8080端口
+- **数据库连接**: `psql -h 127.0.0.1 -U postgres`
+
+---
+
+## Critical Implementation Rules
+
+### 语言特定规则
+
+#### TypeScript 配置
+- **严格模式**: 所有项目启用 `strict: true`，禁止 `any` 类型
+- **目标配置**: ES2022，ESNext 模块，bundler 解析
+- **类型显式**: 函数参数、返回值必须有明确类型注解
+
+#### 命名约定
+- **文件名**: kebab-case (如: `user.service.ts`)
+- **类名**: PascalCase (如: `UserService`)
+- **函数/变量**: camelCase (如: `getUserById`)
+- **常量**: UPPER_SNAKE_CASE (如: `API_BASE_URL`)
+- **接口**: PascalCase，无 `I` 前缀 (如: `User`)
+
+#### 包间依赖
+- **Monorepo 协议**: 使用 `workspace:*` 引用内部包
+  ```json
+  "@d8d/shared-types": "workspace:*"
+  ```
+
+#### RPC 类型安全规范（关键）
+- **响应类型提取**: 使用 `InferResponseType` 从客户端提取
+  ```typescript
+  import type { InferResponseType } from 'hono/client'
+
+  // 基础响应类型
+  type UserResponse = InferResponseType<typeof userClient.$get, 200>;
+
+  // 获取嵌套数据
+  type UserData = InferResponseType<typeof userClient.$get, 200>['data'][0];
+
+  // ⚠️ 路径参数注意：:id 必须用中括号
+  type DetailResponse = InferResponseType<typeof userClient[':id']['$get'], 200>;
+  ```
+
+- **请求类型提取**: 使用 `InferRequestType` 提取
+  ```typescript
+  import type { InferRequestType } from 'hono/client'
+
+  // POST 请求体类型
+  type CreateUserRequest = InferRequestType<typeof userClient.$post>['json'];
+
+  // PUT 请求体类型
+  type UpdateUserRequest = InferRequestType<typeof userClient[':id']['$put']>['json'];
+  ```
+
+- **常见错误**:
+  ```typescript
+  // ❌ 错误：:id 路径忘记中括号
+  InferResponseType<typeof client[':id'].$get, 200>
+
+  // ✅ 正确：:id 必须用中括号
+  InferResponseType<typeof client[':id']['$get'], 200>
+  ```
+
+- **类型命名规范**:
+  - 响应类型: `[ResourceName]Response`
+  - 请求类型: `[ResourceName]Request`
+
+#### 测试与调试
+- **测试运行**: `pnpm test --testNamePattern "测试名称"`
+- **Console 输出**: Vitest 中只有 `console.debug` 会显示
+- **E2E 调试**: 失败时查看 `test-results/**/error-context.md`
+- **类型导入**: 使用 `import` 配合 `vi.mocked`，不用 `require`
+
+#### Git 操作
+- **锁文件冲突**: `rm -f .git/index.lock && git add <文件> && git commit -m "消息"`
+
+---
+
+### 框架特定规则
+
+#### React 19 (Web UI)
+- **数据获取**: 使用 `@tanstack/react-query` 管理服务器状态
+- **表单管理**: 使用 `react-hook-form` + `@hookform/resolvers`
+- **组件模式**:
+  - 编辑/新建使用条件渲染两个独立 Form 组件
+  - 不在单个 Form 组件上动态切换 props
+- **测试选择器**: 关键元素添加 `data-testid`，优先 `getByTestId()`
+- **表单调试**:
+  ```typescript
+  form.handleSubmit(handleSubmit, (errors) => console.debug('表单验证错误:', errors))
+  ```
+
+#### Taro 3.x (小程序)
+- **布局规范**:
+  ```typescript
+  // ❌ View 默认横向布局
+  <View><Text>行1</Text><Text>行2</Text></View>
+
+  // ✅ 添加 flex flex-col
+  <View className="flex flex-col">
+    <Text>行1</Text>
+    <Text>行2</Text>
+  </View>
+  ```
+- **图标使用**:
+  ```typescript
+  // ✅ 正确：Heroicons 图标类 + 尺寸
+  <View className="i-heroicons-chevron-left-20-solid w-5 h-5" />
+
+  // ❌ 错误：使用 emoji
+  <Text>🔔</Text>
+  ```
+- **Navbar 配置**:
+  - TabBar 页面: `leftIcon=""`, `leftText=""`
+  - 二级页面: `leftIcon="i-heroicons-chevron-left-20-solid"`
+- **测试框架**: 使用 Jest 而非 Vitest
+
+#### Hono 4.x (API 服务器)
+- **路由定义**:
+  ```typescript
+  import { OpenAPIHono } from '@hono/zod-openapi'
+
+  const app = new OpenAPIHono()
+  ```
+- **响应验证**:
+  ```typescript
+  import { parseWithAwait, createZodErrorResponse } from '@d8d/shared-utils'
+
+  app.get('/custom', async (c) => {
+    try {
+      const result = await service.getData()
+      // ✅ 必须验证响应
+      const validated = await parseWithAwait(Schema, result)
+      return c.json(validated, 200)
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        return c.json(createZodErrorResponse(error), 400)
+      }
+    }
+  })
+  ```
+
+#### TypeORM 0.3.25 (数据库)
+- **Entity 定义**:
+  ```typescript
+  @Entity('table_name')
+  export class Example {
+    @PrimaryGeneratedColumn({
+      name: 'id',
+      type: 'int',
+      unsigned: true,
+      comment: '主键ID'
+    })
+    id!: number
+
+    @Column({
+      name: 'field_name',
+      type: 'varchar',
+      length: 100,
+      nullable: false,
+      comment: '字段描述'
+    })
+    @Index('idx_field_name', { unique: true })
+    fieldName!: string
+  }
+  ```
+- **Service 层**:
+  ```typescript
+  export class ExampleService extends GenericCrudService<Example> {
+    override async create(data: Partial<Example>): Promise<Example> {
+      // 业务逻辑检查
+      return super.create(data)
+    }
+  }
+  ```
+
+#### Zod 4.x (验证)
+- **Schema 定义**:
+  ```typescript
+  import { z } from 'zod'
+
+  export const ExampleSchema = z.object({
+    id: z.number().int().positive().openapi({
+      description: 'ID',
+      example: 1
+    }),
+    // ✅ Zod 4.0 需要泛型参数
+    createdAt: z.coerce.date<Date>().openapi({
+      description: '创建时间'
+    }),
+    amount: z.coerce.number<number>().openapi({
+      description: '金额'
+    })
+  })
+  ```
+- **不导出推断类型**: RPC 自动推断，无需手动导出
+
+---
+
+### 测试规则
+
+#### 测试框架选择
+- **Web/后端测试**: Vitest 3.2.4
+- **Mini UI 测试**: Jest（注意：与 Web 不同）
+- **E2E 测试**: Playwright 1.55.0
+- **组件测试**: Testing Library 16.3.0
+- **DOM 环境**: Happy DOM 18.0.1
+
+#### 测试文件命名
+- **Vitest 测试**: `*.test.ts`
+- **Playwright E2E**: `*.spec.ts`
+- **测试位置**: `tests/unit`, `tests/integration`, `tests/e2e`
+
+#### 覆盖率目标
+- **单元测试**: ≥80%
+- **集成测试**: ≥60%
+- **关键流程 E2E**: 100%
+
+#### 测试命令
+```bash
+# 运行特定测试
+pnpm test --testNamePattern "测试名称"
+
+# Mini UI 测试（使用 Jest）
+cd mini && pnpm test --testNamePattern "名称"
+
+# E2E 测试
+pnpm test:e2e:chromium
+
+# 类型检查（可用 grep 过滤）
+pnpm typecheck 2>&1 | grep "pattern"
+```
+
+#### 调试技巧
+- **Vitest**: 只有 `console.debug` 会显示，其他 console 被屏蔽
+- **E2E 失败**: 先查看 `test-results/**/error-context.md`
+- **表单调试**:
+  ```typescript
+  form.handleSubmit(handleSubmit, (errors) => console.debug('表单验证错误:', errors))
+  ```
+
+#### 测试数据管理
+- **工厂模式**: 使用 `createTestXxx(overrides)` 函数
+- **数据库策略**:
+  - 单元测试: 内存数据库或 mock
+  - 集成测试: 专用测试数据库，事务回滚
+  - E2E 测试: 接近生产环境
+
+#### Mini UI 特殊规则
+- **测试框架**: 必须使用 Jest，不能用 Vitest
+- **运行位置**: 进入 mini 目录后运行测试
+- **API 测试**: `yongren-api.test.ts`, `yongren-routes.test.ts`
+
+---
+
+### 代码质量与风格规则
+
+#### 文档要求
+- **JSDoc**: 公共 API 必须包含完整 JSDoc 注释
+  ```typescript
+  /**
+   * 函数描述（简洁说明）
+   *
+   * @param paramName - 参数描述
+   * @param paramTwo - 参数描述
+   * @throws {ErrorType} 错误条件
+   * @example
+   * ```ts
+   * await functionName(page, 'arg', 'value');
+   * ```
+   */
+  ```
+- **README**: 每个包必须有独立的 README 说明用途和使用方法
+- **关键逻辑**: 复杂业务逻辑必须添加注释说明
+
+#### 代码风格
+- **缩进**: 使用 2 个空格（不使用 tab）
+- **格式化**: 使用 Prettier 统一代码格式
+- **Linting**: ESLint 配置 TypeScript 和 React 规则
+- **提交前检查**: 使用 husky 进行 pre-commit 钩子检查
+
+#### 代码组织
+- **包结构**:
+  ```
+  packages/example-module/
+  ├── src/
+  │   ├── entities/        # 数据实体
+  │   ├── services/        # 业务逻辑
+  │   ├── schemas/         # 验证 Schema
+  │   ├── routes/          # API 路由
+  │   ├── middleware/      # 中间件
+  │   ├── utils/           # 工具函数
+  │   └── index.ts         # 包入口
+  ├── tests/
+  └── README.md
+  ```
+- **导出规范**: 在 `index.ts` 统一导出
+  ```typescript
+  export * from './entities';
+  export * from './services';
+  export { exampleRoutes } from './routes';
+  export { exampleSchema } from './schemas';
+  ```
+
+#### 安全最佳实践
+- **输入验证**: 使用 Zod Schema 验证所有输入
+- **敏感数据**: 从响应中排除密码等敏感字段
+- **SQL 注入**: 使用 TypeORM 参数化查询，不拼接 SQL
+- **日志**: 不在日志中记录敏感信息
+
+#### 性能优化
+- **数据库查询**: 只查询需要的字段，使用索引
+- **N+1 避免**: 使用 relations 而非循环查询
+- **缓存**: 使用 Redis 缓存热点数据
+
+---
+
+### 关键禁止规则（Anti-Patterns）
+
+#### TypeScript 类型禁令
+```typescript
+// ❌ 禁止：使用 any 类型
+function process(data: any) { }
+
+// ❌ 禁止：直接导入 schema 类型（可能导致 Date/string 不匹配）
+import { UserSchema } from './schema';
+type User = z.infer<typeof UserSchema>;
+
+// ❌ 禁止：Zod 4.0 缺少泛型参数
+createdAt: z.coerce.date()
+amount: z.coerce.number()
+
+// ✅ 正确：使用 RPC 推断类型
+type UserResponse = InferResponseType<typeof userClient.$get, 200>;
+type UserData = InferResponseType<typeof userClient.$get, 200>['data'][0];
+```
+
+#### React/UI 禁令
+```typescript
+// ❌ 禁止：在单个 Form 组件上动态切换 props
+<Form mode={isEdit ? 'edit' : 'create'} />
+
+// ✅ 正确：使用条件渲染两个独立 Form
+{isEdit ? <EditForm /> : <CreateForm />}
+
+// ❌ 禁止：使用 getByText 查找可能重复的文本
+screen.getByText('保存')
+
+// ✅ 正确：添加 data-testid 并使用
+<button data-testid="save-button">保存</button>
+screen.getByTestId('save-button')
+
+// ❌ 禁止：RPC 路径参数忘记中括号
+InferResponseType<typeof client[':id'].$get, 200>
+
+// ✅ 正确：:id 必须用中括号
+InferResponseType<typeof client[':id']['$get'], 200>
+```
+
+#### Mini UI 禁令
+```typescript
+// ❌ 禁止：忘记 flex flex-col
+<View>
+  <Text>行1</Text>
+  <Text>行2</Text>
+</View>
+
+// ✅ 正确：添加 flex flex-col
+<View className="flex flex-col">
+  <Text>行1</Text>
+  <Text>行2</Text>
+</View>
+
+// ❌ 禁止：使用 emoji 图标
+<Text>🔔</Text>
+<Text>←</Text>
+
+// ✅ 正确：使用 Heroicons 图标类
+<View className="i-heroicons-bell-20-solid w-5 h-5" />
+<View className="i-heroicons-chevron-left-20-solid w-5 h-5" />
+
+// ❌ 禁止：在 Mini UI 包内使用别名导入
+import { utils } from '@/utils'
+
+// ✅ 正确：使用相对路径
+import { utils } from '../../utils'
+```
+
+#### 后端模块禁令
+```typescript
+// ❌ 禁止：Entity 列定义省略属性
+@Column({ name: 'email' })
+email!: string;
+
+// ✅ 正确：完整定义
+@Column({
+  name: 'email',
+  type: 'varchar',
+  length: 100,
+  nullable: false,
+  comment: '邮箱'
+})
+email!: string;
+
+// ❌ 禁止：覆盖方法不使用 override
+async create(data: Partial<T>): Promise<T> {
+  return super.create(data);
+}
+
+// ✅ 正确：使用 override 关键字
+override async create(data: Partial<T>): Promise<T> {
+  return super.create(data);
+}
+
+// ❌ 禁止：自定义路由不验证响应
+app.get('/custom', async (c) => {
+  const result = await service.getData();
+  return c.json(result, 200);
+})
+
+// ✅ 正确：使用 parseWithAwait 验证
+app.get('/custom', async (c) => {
+  const result = await service.getData();
+  const validated = await parseWithAwait(Schema, result);
+  return c.json(validated, 200);
+})
+
+// ❌ 禁止：物理删除
+await repository.delete(id);
+
+// ✅ 正确：使用 status 字段软删除
+await repository.update(id, { status: 0 });
+```
+
+#### 测试禁令
+```typescript
+// ❌ 禁止：在 Vitest 中使用 console.log（被屏蔽）
+console.log('debug info');
+
+// ✅ 正确：使用 console.debug
+console.debug('debug info');
+
+// ❌ 禁止：Mini UI 使用 Vitest
+// mini-ui-packages/xxx/package.json
+"test": "vitest"
+
+// ✅ 正确：Mini UI 使用 Jest
+"test": "jest"
+
+// ❌ 禁止：测试中使用 require
+const utils = require('./utils');
+
+// ✅ 正确：使用 import
+import { utils } from './utils';
+// 配合 vi.mocked 使用
+const mockedUtils = vi.mocked(utils);
+```
+
+---
+
+## 项目结构概览
+
+```
+188-179-template-6/
+├── packages/           # 核心共享包和业务模块 (61个)
+├── allin-packages/     # AllIn业务模块 (15个)
+├── mini-ui-packages/   # 小程序UI组件库 (18个)
+├── web/                # 管理后台应用
+├── mini/               # 员工小程序 (Taro)
+├── mini-talent/        # 人才小程序 (Taro)
+├── docs/               # 项目文档
+└── _bmad-output/       # BMAD工作流输出
+```
+
+---
+
+## 开发快速命令
+
+```bash
+# 启动所有应用
+pnpm dev
+
+# 仅启动管理后台
+pnpm run dev:web
+
+# 构建所有包
+pnpm build
+
+# 运行测试
+pnpm test
+
+# 类型检查
+pnpm typecheck
+```
+
+---
+
+## 使用指南
+
+### 给 AI Agent
+
+- **实施前必读**: 在编写任何代码之前，请完整阅读此文件
+- **严格遵循**: 完全按照文档中记录的所有规则实施
+- **存疑时**: 当不确定时，选择更严格的选项
+- **更新维护**: 当出现新模式时，更新此文件
+
+### 给人类开发者
+
+- **保持精简**: 保持此文件专注于 AI Agent 的需求
+- **技术栈变更**: 当技术栈变化时更新
+- **季度评审**: 定期评审以删除过时规则
+- **移除明显规则**: 随时间推移移除变得显而易见的规则
+
+### 最后更新
+
+**日期**: 2026-01-08
+**版本**: 1.0
+**状态**: 已完成，已针对 LLM 优化
+
+---
+
+_此文档由 generate-project-context 工作流生成。更新项目时请保持此文档同步。_