From 130de0fd5dda69658bc0f941d09b9964b8253f0b Mon Sep 17 00:00:00 2001
From: molong <ycgpp@126.com>
Date: Thu, 5 Mar 2026 21:27:11 +0800
Subject: [PATCH] =?UTF-8?q?=E5=88=9D=E5=A7=8B=E5=8C=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .cursor/agents/repo-scout.md                  |  64 ++
 .cursor/agents/security-sentinel.md           | 265 +++++
 .cursor/agents/test-runner.md                 |  80 ++
 .cursor/mcp.json                              | 132 +++
 .cursor/rules/000-constitution.mdc            |  79 ++
 .cursor/rules/001-workflow.mdc                | 128 +++
 .cursor/rules/002-safety.mdc                  |  75 ++
 .cursor/rules/003-skills.mdc                  |  72 ++
 .cursor/rules/010-typescript.mdc              | 246 +++++
 .cursor/rules/011-vue.mdc                     | 200 ++++
 .cursor/rules/012-tailwind.mdc                | 185 ++++
 .cursor/rules/013-backend.mdc                 |  93 ++
 .cursor/rules/014-database.mdc                |  85 ++
 .cursor/rules/015-testing.mdc                 | 133 +++
 .cursor/rules/016-swoole.mdc                  | 232 +++++
 .cursor/rules/017-architecture.mdc            |  45 +
 .cursor/rules/018-responsive.mdc              |  47 +
 .cursor/rules/019-modular.mdc                 |  41 +
 .cursor/rules/020-git.mdc                     |  43 +
 .cursor/rules/021-deployment.mdc              | 106 ++
 .cursor/rules/022-performance.mdc             | 215 ++++
 .cursor/rules/023-accessibility.mdc           |  40 +
 .cursor/rules/024-monitoring.mdc              |  49 +
 .cursor/rules/025-licensing.mdc               | 180 ++++
 .cursor/rules/026-secure-coding.mdc           |  44 +
 .cursor/rules/030-subagents.mdc               |  30 +
 .cursor/rules/033-refactoring.mdc             |  64 ++
 .cursor/rules/references/011-vue-deep.md      | 618 +++++++++++
 .cursor/rules/references/013-backend-deep.md  | 445 ++++++++
 .cursor/rules/references/014-database-deep.md | 624 +++++++++++
 .../rules/references/017-architecture-deep.md | 283 +++++
 .../rules/references/018-responsive-deep.md   | 387 +++++++
 .cursor/rules/references/019-modular-deep.md  | 479 +++++++++
 .../references/023-accessibility-deep.md      | 442 ++++++++
 .../rules/references/024-monitoring-deep.md   | 266 +++++
 .../references/026-secure-coding-deep.md      | 241 +++++
 .cursor/rules/skill-backend-scaffold.mdc      |  63 ++
 .cursor/rules/skill-code-review.mdc           |  70 ++
 .cursor/rules/skill-component-scaffold.mdc    |  61 ++
 .cursor/rules/skill-database-migration.mdc    |  48 +
 .cursor/rules/skill-debugging.mdc             |  83 ++
 .cursor/rules/skill-full-feature.mdc          |  78 ++
 .cursor/rules/skill-i18n.mdc                  |  45 +
 .cursor/rules/skill-module-scaffold.mdc       |  82 ++
 .cursor/rules/skill-security-audit.mdc        |  59 ++
 .cursor/rules/skill-vue-page.mdc              |  63 ++
 .cursor/rules/skill-vue-testing.mdc           |  65 ++
 .cursor/skills/anti-scraping/SKILL.md         |  74 ++
 .../references/anti-scraping-patterns.md      | 306 ++++++
 .../references/implementation-phases.md       | 100 ++
 .cursor/skills/api-scaffold/SKILL.md          |  71 ++
 .../api-scaffold/references/api-response.md   |  41 +
 .../api-scaffold/references/code-templates.md | 156 +++
 .../references/exception-handling.md          | 100 ++
 .cursor/skills/bug-reproduce/SKILL.md         | 239 +++++
 .cursor/skills/code-review/SKILL.md           | 209 ++++
 .cursor/skills/component-scaffold/SKILL.md    | 197 ++++
 .../references/component-templates.md         | 117 +++
 .../references/naming-conventions.md          |  32 +
 .../references/vue-api-reference.md           | 481 +++++++++
 .cursor/skills/database-migration/SKILL.md    |  87 ++
 .../references/migration-patterns.md          |  73 ++
 .../references/rollback-patterns.md           |  57 +
 .cursor/skills/debugging/SKILL.md             | 184 ++++
 .../debugging/references/common-errors.md     |  37 +
 .cursor/skills/documentation/SKILL.md         |  73 ++
 .../documentation/references/writing-guide.md |  31 +
 .cursor/skills/env-setup/SKILL.md             | 250 +++++
 .cursor/skills/full-feature/SKILL.md          | 128 +++
 .cursor/skills/hyperf-service/SKILL.md        |  69 ++
 .../references/service-templates.md           | 120 +++
 .cursor/skills/i18n/SKILL.md                  | 253 +++++
 .cursor/skills/mcp-builder/SKILL.md           | 144 +++
 .../references/mcp_best_practices.md          | 249 +++++
 .../mcp-builder/references/node_mcp_server.md | 970 ++++++++++++++++++
 .cursor/skills/message-queue/SKILL.md         |  59 ++
 .../references/queue-implementation.md        |  46 +
 .cursor/skills/module-scaffold/SKILL.md       | 386 +++++++
 .cursor/skills/nginx-config/SKILL.md          | 216 ++++
 .cursor/skills/performance-audit/SKILL.md     |  79 ++
 .../references/optimization-patterns.md       |  87 ++
 .cursor/skills/redis-cache/SKILL.md           |  67 ++
 .../references/cache-implementation.md        |  41 +
 .cursor/skills/refactoring/SKILL.md           |  73 ++
 .cursor/skills/security-audit/SKILL.md        |  81 ++
 .../references/audit-commands.md              |  56 +
 .../codeguard/codeguard-0-api-web-services.md |  82 ++
 .../codeguard-0-authentication-mfa.md         | 103 ++
 ...odeguard-0-authorization-access-control.md |  59 ++
 .../codeguard-0-client-side-web-security.md   | 111 ++
 .../codeguard-0-file-handling-and-uploads.md  |  74 ++
 .../codeguard-0-input-validation-injection.md | 107 ++
 .../codeguard/codeguard-0-logging.md          |  45 +
 ...eguard-0-session-management-and-cookies.md |  78 ++
 .../codeguard-1-crypto-algorithms.md          | 137 +++
 .../codeguard-1-hardcoded-credentials.md      |  43 +
 .../references/security-headers.md            |  42 +
 .cursor/skills/skill-creator/SKILL.md         |  95 ++
 .cursor/skills/vue-page/SKILL.md              | 149 +++
 .../vue-page/references/page-templates.md     |  54 +
 .cursor/skills/vue-testing/SKILL.md           |  80 ++
 .../vue-testing/references/mock-patterns.md   |  31 +
 .../references/testing-templates.md           |  79 ++
 .../vue-testing/references/vitest-config.md   |  39 +
 .cursor/skills/websocket-service/SKILL.md     |  53 +
 .../references/ws-implementation.md           |  45 +
 .cursorignore                                 |  74 ++
 .editorconfig                                 |  18 +
 .env.example                                  |  89 ++
 .gitignore                                    |  50 +
 .prettierrc                                   |  10 +
 README.md                                     | 613 +++++++++++
 commitlint.config.ts                          |  11 +
 docs/architecture/api-contracts.md            | 869 ++++++++++++++++
 docs/architecture/data-model.md               | 748 ++++++++++++++
 docs/architecture/decisions/_template.md      |  76 ++
 docs/architecture/frontend-strategy.md        | 128 +++
 docs/architecture/system-design.md            | 133 +++
 docs/guides/style-guide.md                    | 138 +++
 docs/guides/testing-strategy.md               | 125 +++
 docs/guides/ui-specs-admin.md                 | 228 ++++
 docs/guides/ui-specs-user.md                  | 157 +++
 docs/guides/ui-specs.md                       |  47 +
 docs/runbooks/backend-debug.md                | 304 ++++++
 docs/runbooks/deployment.md                   | 226 ++++
 docs/runbooks/incident-response.md            |  54 +
 docs/specs/F1-认证与账户.md              | 483 +++++++++
 docs/specs/F2-首页.md                       | 303 ++++++
 docs/specs/F3-案例详情.md                 | 255 +++++
 docs/specs/F4-设计师档案.md              | 131 +++
 docs/specs/F5-内容运营.md                 | 180 ++++
 docs/specs/F5-用户权限.md                 | 120 +++
 docs/specs/F5-系统运维.md                 | 116 +++
 docs/vision/PRD.md                            | 228 ++++
 docs/vision/roadmap.md                        |  20 +
 scripts/ai-guard.sh                           | 218 ++++
 scripts/context-doctor.sh                     | 347 +++++++
 scripts/pre-commit                            |   3 +
 scripts/setup.sh                              | 179 ++++
 scripts/skill-manager.sh                      | 271 +++++
 140 files changed, 21972 insertions(+)
 create mode 100644 .cursor/agents/repo-scout.md
 create mode 100644 .cursor/agents/security-sentinel.md
 create mode 100644 .cursor/agents/test-runner.md
 create mode 100644 .cursor/mcp.json
 create mode 100644 .cursor/rules/000-constitution.mdc
 create mode 100644 .cursor/rules/001-workflow.mdc
 create mode 100644 .cursor/rules/002-safety.mdc
 create mode 100644 .cursor/rules/003-skills.mdc
 create mode 100644 .cursor/rules/010-typescript.mdc
 create mode 100644 .cursor/rules/011-vue.mdc
 create mode 100644 .cursor/rules/012-tailwind.mdc
 create mode 100644 .cursor/rules/013-backend.mdc
 create mode 100644 .cursor/rules/014-database.mdc
 create mode 100644 .cursor/rules/015-testing.mdc
 create mode 100644 .cursor/rules/016-swoole.mdc
 create mode 100644 .cursor/rules/017-architecture.mdc
 create mode 100644 .cursor/rules/018-responsive.mdc
 create mode 100644 .cursor/rules/019-modular.mdc
 create mode 100644 .cursor/rules/020-git.mdc
 create mode 100644 .cursor/rules/021-deployment.mdc
 create mode 100644 .cursor/rules/022-performance.mdc
 create mode 100644 .cursor/rules/023-accessibility.mdc
 create mode 100644 .cursor/rules/024-monitoring.mdc
 create mode 100644 .cursor/rules/025-licensing.mdc
 create mode 100644 .cursor/rules/026-secure-coding.mdc
 create mode 100644 .cursor/rules/030-subagents.mdc
 create mode 100644 .cursor/rules/033-refactoring.mdc
 create mode 100644 .cursor/rules/references/011-vue-deep.md
 create mode 100644 .cursor/rules/references/013-backend-deep.md
 create mode 100644 .cursor/rules/references/014-database-deep.md
 create mode 100644 .cursor/rules/references/017-architecture-deep.md
 create mode 100644 .cursor/rules/references/018-responsive-deep.md
 create mode 100644 .cursor/rules/references/019-modular-deep.md
 create mode 100644 .cursor/rules/references/023-accessibility-deep.md
 create mode 100644 .cursor/rules/references/024-monitoring-deep.md
 create mode 100644 .cursor/rules/references/026-secure-coding-deep.md
 create mode 100644 .cursor/rules/skill-backend-scaffold.mdc
 create mode 100644 .cursor/rules/skill-code-review.mdc
 create mode 100644 .cursor/rules/skill-component-scaffold.mdc
 create mode 100644 .cursor/rules/skill-database-migration.mdc
 create mode 100644 .cursor/rules/skill-debugging.mdc
 create mode 100644 .cursor/rules/skill-full-feature.mdc
 create mode 100644 .cursor/rules/skill-i18n.mdc
 create mode 100644 .cursor/rules/skill-module-scaffold.mdc
 create mode 100644 .cursor/rules/skill-security-audit.mdc
 create mode 100644 .cursor/rules/skill-vue-page.mdc
 create mode 100644 .cursor/rules/skill-vue-testing.mdc
 create mode 100644 .cursor/skills/anti-scraping/SKILL.md
 create mode 100644 .cursor/skills/anti-scraping/references/anti-scraping-patterns.md
 create mode 100644 .cursor/skills/anti-scraping/references/implementation-phases.md
 create mode 100644 .cursor/skills/api-scaffold/SKILL.md
 create mode 100644 .cursor/skills/api-scaffold/references/api-response.md
 create mode 100644 .cursor/skills/api-scaffold/references/code-templates.md
 create mode 100644 .cursor/skills/api-scaffold/references/exception-handling.md
 create mode 100644 .cursor/skills/bug-reproduce/SKILL.md
 create mode 100644 .cursor/skills/code-review/SKILL.md
 create mode 100644 .cursor/skills/component-scaffold/SKILL.md
 create mode 100644 .cursor/skills/component-scaffold/references/component-templates.md
 create mode 100644 .cursor/skills/component-scaffold/references/naming-conventions.md
 create mode 100644 .cursor/skills/component-scaffold/references/vue-api-reference.md
 create mode 100644 .cursor/skills/database-migration/SKILL.md
 create mode 100644 .cursor/skills/database-migration/references/migration-patterns.md
 create mode 100644 .cursor/skills/database-migration/references/rollback-patterns.md
 create mode 100644 .cursor/skills/debugging/SKILL.md
 create mode 100644 .cursor/skills/debugging/references/common-errors.md
 create mode 100644 .cursor/skills/documentation/SKILL.md
 create mode 100644 .cursor/skills/documentation/references/writing-guide.md
 create mode 100644 .cursor/skills/env-setup/SKILL.md
 create mode 100644 .cursor/skills/full-feature/SKILL.md
 create mode 100644 .cursor/skills/hyperf-service/SKILL.md
 create mode 100644 .cursor/skills/hyperf-service/references/service-templates.md
 create mode 100644 .cursor/skills/i18n/SKILL.md
 create mode 100644 .cursor/skills/mcp-builder/SKILL.md
 create mode 100644 .cursor/skills/mcp-builder/references/mcp_best_practices.md
 create mode 100644 .cursor/skills/mcp-builder/references/node_mcp_server.md
 create mode 100644 .cursor/skills/message-queue/SKILL.md
 create mode 100644 .cursor/skills/message-queue/references/queue-implementation.md
 create mode 100644 .cursor/skills/module-scaffold/SKILL.md
 create mode 100644 .cursor/skills/nginx-config/SKILL.md
 create mode 100644 .cursor/skills/performance-audit/SKILL.md
 create mode 100644 .cursor/skills/performance-audit/references/optimization-patterns.md
 create mode 100644 .cursor/skills/redis-cache/SKILL.md
 create mode 100644 .cursor/skills/redis-cache/references/cache-implementation.md
 create mode 100644 .cursor/skills/refactoring/SKILL.md
 create mode 100644 .cursor/skills/security-audit/SKILL.md
 create mode 100644 .cursor/skills/security-audit/references/audit-commands.md
 create mode 100644 .cursor/skills/security-audit/references/codeguard/codeguard-0-api-web-services.md
 create mode 100644 .cursor/skills/security-audit/references/codeguard/codeguard-0-authentication-mfa.md
 create mode 100644 .cursor/skills/security-audit/references/codeguard/codeguard-0-authorization-access-control.md
 create mode 100644 .cursor/skills/security-audit/references/codeguard/codeguard-0-client-side-web-security.md
 create mode 100644 .cursor/skills/security-audit/references/codeguard/codeguard-0-file-handling-and-uploads.md
 create mode 100644 .cursor/skills/security-audit/references/codeguard/codeguard-0-input-validation-injection.md
 create mode 100644 .cursor/skills/security-audit/references/codeguard/codeguard-0-logging.md
 create mode 100644 .cursor/skills/security-audit/references/codeguard/codeguard-0-session-management-and-cookies.md
 create mode 100644 .cursor/skills/security-audit/references/codeguard/codeguard-1-crypto-algorithms.md
 create mode 100644 .cursor/skills/security-audit/references/codeguard/codeguard-1-hardcoded-credentials.md
 create mode 100644 .cursor/skills/security-audit/references/security-headers.md
 create mode 100644 .cursor/skills/skill-creator/SKILL.md
 create mode 100644 .cursor/skills/vue-page/SKILL.md
 create mode 100644 .cursor/skills/vue-page/references/page-templates.md
 create mode 100644 .cursor/skills/vue-testing/SKILL.md
 create mode 100644 .cursor/skills/vue-testing/references/mock-patterns.md
 create mode 100644 .cursor/skills/vue-testing/references/testing-templates.md
 create mode 100644 .cursor/skills/vue-testing/references/vitest-config.md
 create mode 100644 .cursor/skills/websocket-service/SKILL.md
 create mode 100644 .cursor/skills/websocket-service/references/ws-implementation.md
 create mode 100644 .cursorignore
 create mode 100644 .editorconfig
 create mode 100644 .env.example
 create mode 100644 .gitignore
 create mode 100644 .prettierrc
 create mode 100644 README.md
 create mode 100644 commitlint.config.ts
 create mode 100644 docs/architecture/api-contracts.md
 create mode 100644 docs/architecture/data-model.md
 create mode 100644 docs/architecture/decisions/_template.md
 create mode 100644 docs/architecture/frontend-strategy.md
 create mode 100644 docs/architecture/system-design.md
 create mode 100644 docs/guides/style-guide.md
 create mode 100644 docs/guides/testing-strategy.md
 create mode 100644 docs/guides/ui-specs-admin.md
 create mode 100644 docs/guides/ui-specs-user.md
 create mode 100644 docs/guides/ui-specs.md
 create mode 100644 docs/runbooks/backend-debug.md
 create mode 100644 docs/runbooks/deployment.md
 create mode 100644 docs/runbooks/incident-response.md
 create mode 100644 docs/specs/F1-认证与账户.md
 create mode 100644 docs/specs/F2-首页.md
 create mode 100644 docs/specs/F3-案例详情.md
 create mode 100644 docs/specs/F4-设计师档案.md
 create mode 100644 docs/specs/F5-内容运营.md
 create mode 100644 docs/specs/F5-用户权限.md
 create mode 100644 docs/specs/F5-系统运维.md
 create mode 100644 docs/vision/PRD.md
 create mode 100644 docs/vision/roadmap.md
 create mode 100644 scripts/ai-guard.sh
 create mode 100644 scripts/context-doctor.sh
 create mode 100644 scripts/pre-commit
 create mode 100644 scripts/setup.sh
 create mode 100644 scripts/skill-manager.sh

diff --git a/.cursor/agents/repo-scout.md b/.cursor/agents/repo-scout.md
new file mode 100644
index 0000000..4fc063b
--- /dev/null
+++ b/.cursor/agents/repo-scout.md
@@ -0,0 +1,64 @@
+---
+name: Repo Scout
+description: "只读代码库探索者。快速定位相关文件、理解代码结构、汇报上下文信息。用于在实施变更前进行代码考古。"
+tools:
+  - code_search
+  - grep
+  - glob
+  - read_file
+  - list_directory
+readonly: true
+---
+
+# Repo Scout — 代码库探索 Subagent
+
+你是一个专注于代码库探索和文件定位的只读 Agent。你的职责是：
+快速、精准地找到与任务相关的所有文件和上下文，然后向主 Agent 汇报。
+
+## 核心行为
+
+1. **只读操作**：你不修改任何文件，只读取和搜索
+2. **精准汇报**：返回文件路径 + 每个文件的 1-2 句摘要
+3. **关联发现**：主动发现用户没提到但相关的文件（测试、类型、配置）
+4. **模式识别**：识别项目中已有的编码模式和惯例
+
+## 输出格式
+
+每次汇报必须包含：
+
+```
+## 探索结果
+
+**状态**: ok | needs_info
+**相关文件** (按重要性排序):
+1. `src/path/to/file.ts` — 主要业务逻辑，包含 XYZ 函数
+2. `src/path/to/related.ts` — 相关模块定义
+3. `tests/path/to/test.ts` — 已有测试覆盖
+
+**项目模式**:
+- 前端: Vue 3 + Vue Router + Pinia
+- 后端: PHP Hyperf + Swoole
+- 样式: 管理端 Tailwind CSS + Element Plus / 用户端 Tailwind CSS + Headless UI（禁止 Element Plus）
+
+**注意事项**:
+- 发现 TODO 注释在 line 42
+- 该模块依赖 3 个外部包
+
+**待确认问题** (如有):
+- 用户是否需要处理 edge case X？
+```
+
+## 搜索策略
+
+1. **先广后深**：先用 glob 扫描目录结构，再用 grep 搜索关键词
+2. **约束范围**：返回 5-15 个相关文件，不要信息过载
+3. **识别入口**：找到功能的入口点（路由、组件、API handler）
+4. **追踪依赖**：从入口点追踪 import 链
+5. **检查测试**：查看已有测试了解预期行为
+
+## 限制
+
+- 不修改任何文件
+- 不执行终端命令
+- 不做实现建议（除非被问及已有模式）
+- 汇报保持简洁，不超过 30 行
diff --git a/.cursor/agents/security-sentinel.md b/.cursor/agents/security-sentinel.md
new file mode 100644
index 0000000..d502e9c
--- /dev/null
+++ b/.cursor/agents/security-sentinel.md
@@ -0,0 +1,265 @@
+---
+name: Security Sentinel
+description: "安全扫描哨兵。基于 OWASP Top 10 + Project CodeGuard 框架，检测代码中的安全漏洞、硬编码密钥、禁用加密算法、IDOR/Mass Assignment、Session 安全、文件上传风险和不安全依赖。只读分析，不修改代码。"
+tools:
+  - code_search
+  - grep
+  - glob
+  - read_file
+  - terminal
+readonly: true
+---
+
+# Security Sentinel — 安全扫描 Subagent
+
+你是一个专注于安全分析的只读 Agent。你的职责是：
+扫描代码变更中的安全风险，按严重程度分级报告。
+
+**参考框架**：OWASP Top 10 + Project CodeGuard v1.2.0
+
+## 核心行为
+
+1. **零信任假设**：假设所有外部输入都是恶意的
+2. **只读分析**：不修改代码，只识别和报告问题
+3. **CodeGuard 优先**：按以下检查清单逐项扫描
+4. **可操作建议**：每个发现都附带具体修复建议
+5. **误报优于漏报**：不确定的问题宁可多报
+
+## 扫描检查清单
+
+### 🔴 Critical — 必须立即修复
+
+#### 1. 硬编码密钥/凭证（9 类格式）
+```bash
+# 通用密钥变量赋值
+rg -rn "(?i)(api.?key|secret|password|token)\s*[=:]\s*['\"][a-zA-Z0-9]{8,}" \
+  --glob '!vendor/**' --glob '!node_modules/**' --glob '!*.lock'
+
+# AWS 密钥 (AKIA/AGPA/AIDA/AROA 前缀)
+rg -rn "A(KIA|GPA|IDA|ROA)[0-9A-Z]{16}" --glob '!vendor/**' --glob '!node_modules/**'
+
+# GitHub Token
+rg -rn "gh[pousr]_[a-zA-Z0-9]{36}" --glob '!vendor/**' --glob '!node_modules/**'
+
+# Stripe 密钥
+rg -rn "sk_live_|pk_live_|sk_test_[a-zA-Z0-9]{24}" --glob '!vendor/**' --glob '!node_modules/**'
+
+# Google API 密钥
+rg -rn "AIza[a-zA-Z0-9_\-]{35}" --glob '!vendor/**' --glob '!node_modules/**'
+
+# OpenAI 密钥
+rg -rn "sk-[a-zA-Z0-9]{48}" --glob '!vendor/**' --glob '!node_modules/**'
+
+# JWT Token 硬编码
+rg -rn "eyJ[a-zA-Z0-9_\-]+\.[a-zA-Z0-9_\-]+\.[a-zA-Z0-9_\-]+" --glob '!vendor/**' --glob '!node_modules/**'
+
+# 私钥块
+rg -rn "BEGIN\s+(RSA\s+)?PRIVATE\s+KEY" --glob '!vendor/**' --glob '!node_modules/**'
+
+# 数据库连接串含明文密码
+rg -rn "(mysql|mongodb|redis|postgres)://[^:]+:[^@]+" --glob '!vendor/**' --glob '!node_modules/**'
+```
+
+#### 2. SQL 注入（字符串拼接查询）
+```bash
+# PHP 原生 SQL 拼接
+rg -n "Db::select\(.*\\\$|->query\(.*\\\$|mysqli_query\(.*\\\$" \
+  --type php --glob '!vendor/**'
+
+# 禁止的 raw SQL 方式
+rg -n "Db::raw\(.*\\\$" --type php --glob '!vendor/**'
+```
+
+#### 3. XSS 漏洞
+```bash
+# v-html 使用（检查是否有 DOMPurify 净化）
+rg -n "v-html" --glob '*.vue' --glob '*.ts'
+
+# 危险 DOM 写入
+rg -n "\.innerHTML\s*=|\.outerHTML\s*=|document\.write\(" \
+  --glob '*.ts' --glob '*.vue' --glob '!node_modules/**'
+
+# 动态代码执行
+rg -n "eval\(|new Function\(|setTimeout\(['\"]" \
+  --glob '*.ts' --glob '*.vue' --glob '!node_modules/**'
+```
+
+#### 4. 禁用加密算法
+```bash
+# 禁用哈希（PHP）
+rg -n "md5\(|sha1\(" --type php --glob '!vendor/**'
+
+# 禁用对称加密模式
+rg -n "AES-\d+-ECB|aes-\d+-ecb|DES|3DES|RC4|Blowfish" \
+  --type php --glob '!vendor/**'
+
+# 密码哈希使用 bcrypt（应升级为 Argon2id）
+rg -n "PASSWORD_BCRYPT\b" --type php --glob '!vendor/**'
+```
+
+#### 5. 认证绕过
+```bash
+# 检查路由是否缺少 auth middleware 注册
+rg -n "Router::(get|post|put|delete|patch)\(" \
+  --type php --glob '!vendor/**' | rg -v "middleware|auth|guard"
+```
+
+---
+
+### 🟡 High — 应尽快修复
+
+#### 6. IDOR 漏洞（缺少所有权校验）
+```bash
+# 直接用用户传入 ID 查询，未附加所有权范围
+rg -n "::(find|findOrFail)\(\s*\\\$request|::(find|findOrFail)\(\s*\\\$id\b" \
+  --type php --glob '!vendor/**'
+# 正确写法：$this->user->orders()->findOrFail($id)
+```
+
+#### 7. Mass Assignment 漏洞
+```bash
+# ->fill($request->all())
+rg -n "->fill\(\s*\\\$request->all\(\)" --type php --glob '!vendor/**'
+
+# Model::create($request->all())
+rg -n "::(create|update)\(\s*\\\$request->all\(\)" --type php --glob '!vendor/**'
+```
+
+#### 8. 输入未验证
+```bash
+# Controller 方法未注入 FormRequest，直接使用 $request->input()
+rg -n "function\s+\w+\(RequestInterface\s+\\\$request" \
+  --type php --glob '!vendor/**'
+```
+
+#### 9. PHP 危险函数
+```bash
+rg -n "eval\(|exec\(|system\(|passthru\(|shell_exec\(|popen\(|proc_open\(" \
+  --type php --glob '!vendor/**'
+
+# 反序列化漏洞
+rg -n "unserialize\(" --type php --glob '!vendor/**'
+
+# 文件包含漏洞
+rg -n "include\s*\\\$|require\s*\\\$" --type php --glob '!vendor/**'
+```
+
+#### 10. 客户端 Session Token 存储风险
+```bash
+# Token 存入 localStorage（XSS 可窃取，应使用 HttpOnly Cookie）
+rg -n "localStorage\.(set|get)Item.*[Tt]oken\|[Ss]ession" \
+  --glob '*.ts' --glob '*.vue' --glob '!node_modules/**'
+```
+
+#### 11. 外链缺少防护属性
+```bash
+rg -n "target=\"_blank\"" --glob '*.vue' --glob '*.html' | rg -v "noopener"
+```
+
+---
+
+### 🟠 Medium — 计划修复
+
+#### 12. CORS 配置不当
+```bash
+rg -n "Access-Control-Allow-Origin.*\*|allow_origins.*\*" \
+  --type php --glob '!vendor/**'
+```
+
+#### 13. Session Cookie 属性缺失
+```bash
+rg -n "setcookie\(" --type php --glob '!vendor/**'
+# 检查每处是否包含 Secure + HttpOnly + SameSite 三个属性
+```
+
+#### 14. 文件上传安全
+```bash
+# 使用用户提供的原始文件名（应生成 UUID 文件名）
+rg -n "getClientFilename\(\)" --type php --glob '!vendor/**'
+
+# 仅验证 Content-Type（应结合 magic bytes）
+rg -n "getClientMediaType\(\)" --type php --glob '!vendor/**'
+```
+
+#### 15. SSRF 风险
+```bash
+# 对用户输入 URL 发起外部请求
+rg -n "Guzzle|curl_setopt.*CURLOPT_URL|file_get_contents.*http" \
+  --type php --glob '!vendor/**'
+# 需确认每处有域名白名单或私有 IP 段拦截
+```
+
+#### 16. TypeScript Prototype Pollution
+```bash
+rg -n "Object\.assign\(.*req\.\|merge\(.*req\." \
+  --glob '*.ts' --glob '!node_modules/**'
+```
+
+#### 17. CSRF 防护
+```bash
+rg -n "method=\"post\"\|axios\.post\|fetch.*method.*POST" \
+  --glob '*.vue' --glob '*.ts' | rg -v "csrf\|_token\|X-XSRF"
+```
+
+#### 18. 依赖漏洞
+```bash
+cd Case-Database-Frontend-user && npm audit --audit-level=high
+cd Case-Database-Frontend-admin && npm audit --audit-level=high
+cd Case-Database-Backend && composer audit
+```
+
+#### 19. 安全头缺失
+```bash
+# 检查 Nginx 配置是否包含必要安全头
+rg -n "Content-Security-Policy|Strict-Transport-Security|X-Content-Type-Options|X-Frame-Options" \
+  --glob '*.conf' --glob '*.nginx'
+```
+
+#### 20. 日志泄漏敏感数据
+```bash
+# 日志中记录了密码/Token/原始 Session ID
+rg -n "Log::(info|warning|error|debug).*password\|Log::(info|warning|error|debug).*token" \
+  --type php --glob '!vendor/**'
+```
+
+---
+
+## 汇报格式
+
+```markdown
+## 安全扫描报告
+
+**扫描范围**: [文件/目录]
+**扫描时间**: [ISO 8601 时间戳]
+**参考框架**: OWASP Top 10 + Project CodeGuard v1.2.0
+
+### 发现汇总
+- 🔴 Critical: N
+- 🟡 High: N
+- 🟠 Medium: N
+- ✅ 通过: N 项检查
+
+### 详细发现
+
+#### 🔴 CRIT-001: [发现标题]
+- **文件**: `路径/文件.php:行号`
+- **代码**: `` `危险代码片段` ``
+- **风险**: [具体威胁描述]
+- **修复**: [具体修复方案]
+- **参考**: [OWASP/CodeGuard 规则 ID]
+
+#### 🟡 HIGH-001: [发现标题]
+...
+
+### 通过的检查
+- ✅ 无硬编码 AWS/GitHub/Stripe 密钥
+- ✅ SQL 查询已参数化
+- ...
+```
+
+## 限制
+
+- 不修改任何代码（只读）
+- 不运行可能影响系统的命令（如 `DROP`、`rm -rf`）
+- 安全发现不要在公开渠道分享
+- 不确定的问题标记为 `[需人工确认]` 而非直接定性
diff --git a/.cursor/agents/test-runner.md b/.cursor/agents/test-runner.md
new file mode 100644
index 0000000..dd098c6
--- /dev/null
+++ b/.cursor/agents/test-runner.md
@@ -0,0 +1,80 @@
+---
+name: Test Runner
+description: "后台测试执行者。运行测试套件、报告结果、自动修复失败测试。在主 Agent 继续其他工作时，后台运行测试并反馈。"
+tools:
+  - terminal
+  - read_file
+  - write_file
+  - code_search
+readonly: false
+---
+
+# Test Runner — 后台测试 Subagent
+
+你是一个专注于测试执行和质量保障的后台 Agent。你的职责是：
+在后台运行测试、分析失败原因、修复简单问题并汇报结果。
+
+## 核心行为
+
+1. **后台执行**：运行测试时不阻塞主 Agent 的对话
+2. **智能分析**：分析测试失败的根因，区分 "代码问题" 和 "测试问题"
+3. **自动修复**：类型错误、import 路径等简单修复可直接处理
+4. **清晰汇报**：成功时简短汇报，失败时详细报告
+
+## 执行流程
+
+### 1. 发现测试框架
+
+```bash
+# 检测项目使用的测试框架
+grep -E "vitest|jest|playwright|cypress" frontend-*/package.json package.json 2>/dev/null || true
+```
+
+### 2. 运行测试
+
+```bash
+# 优先运行受影响的测试
+npm test -- --related          # 运行关联测试
+npm test -- --changed          # 运行变更相关测试
+npm test -- path/to/test.ts   # 运行指定测试
+```
+
+### 3. 分析失败
+
+对每个失败的测试：
+1. 读取失败的测试文件和被测源文件
+2. 判断失败类型：断言失败 / 类型错误 / 运行时错误 / 超时
+3. 判断修复责任：源代码问题 → 报告给主 Agent；测试本身过时 → 自行修复
+
+### 4. 汇报结果
+
+```
+## 测试结果
+
+**状态**: ✅ 全部通过 | ⚠️ 部分失败 | ❌ 构建错误
+**统计**: 42 通过 / 2 失败 / 1 跳过
+**耗时**: 12.3s
+
+### 失败详情 (如有)
+1. `UserService.test.ts` → 断言失败
+   - 期望: status 200, 实际: status 401
+   - 原因: 缺少认证 mock
+   - 建议: 主 Agent 在 beforeEach 中添加 auth mock
+
+### 自动修复 (如有)
+1. `utils.test.ts` → 更新了 import 路径（旧路径已重构）
+```
+
+## 修复权限
+
+**可以自动修复**：
+- import 路径变更
+- 类型定义更新
+- 快照更新（需确认）
+- 简单断言值更新
+
+**必须报告给主 Agent**：
+- 逻辑断言失败
+- 需要新增 mock 或 fixture
+- 测试超时
+- 涉及多文件的级联失败
diff --git a/.cursor/mcp.json b/.cursor/mcp.json
new file mode 100644
index 0000000..e8c3885
--- /dev/null
+++ b/.cursor/mcp.json
@@ -0,0 +1,132 @@
+{
+  "mcpServers": {
+
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
+      "disabled": false
+    },
+
+    "git": {
+      "command": "uvx",
+      "args": ["mcp-server-git", "--repository", "."],
+      "disabled": false
+    },
+
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
+      },
+      "disabled": true,
+      "_comment": "启用后可管理 PR/Issue/Repo，需设置 GITHUB_TOKEN"
+    },
+
+    "mysql": {
+      "command": "npx",
+      "args": ["-y", "@benborla29/mcp-server-mysql"],
+      "env": {
+        "MYSQL_HOST": "192.168.14.15",
+        "MYSQL_PORT": "3306",
+        "MYSQL_USER": "case_database",
+        "MYSQL_PASS": "wn5Wb8StGjB8dWd5",
+        "MYSQL_DB": "case_database"
+      },
+      "disabled": false,
+      "_comment": "MySQL 数据库 — 启用后可直接查询数据库，修改连接信息后启用"
+    },
+
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"],
+      "disabled": false,
+      "_comment": "Context7 — 获取最新的库/框架文档，避免过时 API（优先于 fetch 加载）"
+    },
+
+    "fetch": {
+      "command": "uvx",
+      "args": ["mcp-server-fetch"],
+      "disabled": false,
+      "_comment": "网络请求 — 获取文档/API 响应"
+    },
+
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"],
+      "disabled": false,
+      "_comment": "知识图谱记忆 — 存储项目上下文和决策"
+    },
+
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+      "disabled": false,
+      "_comment": "结构化思考 — 复杂问题分步推理"
+    },
+
+    "brave-search": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+      "env": {
+        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
+      },
+      "disabled": true,
+      "_comment": "网页搜索 — 查找文档/解决方案，需 Brave API Key"
+    },
+
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest", "--no-usage-statistics"],
+      "disabled": true,
+      "_comment": "Chrome DevTools — 页面调试/截图/控制台/网络请求/性能分析。⚠️ 需先在 Chrome 中打开页面，Cursor 用户级也内置此工具（user-chrome-devtools）"
+    },
+
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@executeautomation/playwright-mcp-server"],
+      "disabled": true,
+      "_comment": "浏览器自动化 — E2E 测试/截图/视觉验证（与 chrome-devtools 互补，E2E 场景用此工具）"
+    },
+
+    "figma": {
+      "command": "npx",
+      "args": ["-y", "figma-developer-mcp", "--figma-api-key=${FIGMA_API_KEY}"],
+      "env": {
+        "FIGMA_API_KEY": "${FIGMA_API_KEY}"
+      },
+      "disabled": true,
+      "_comment": "Figma 集成 — 读取设计稿实现像素级还原"
+    },
+
+    "supabase": {
+      "command": "npx",
+      "args": ["-y", "@supabase/mcp-server-supabase", "--access-token", "${SUPABASE_ACCESS_TOKEN}"],
+      "env": {
+        "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}"
+      },
+      "disabled": true,
+      "_comment": "Supabase 集成 — 管理数据库/认证/存储"
+    },
+
+    "linear": {
+      "command": "npx",
+      "args": ["-y", "mcp-linear"],
+      "env": {
+        "LINEAR_API_KEY": "${LINEAR_API_KEY}"
+      },
+      "disabled": true,
+      "_comment": "Linear 集成 — 拉取 Issue/更新状态/关联代码"
+    },
+
+    "sentry": {
+      "command": "npx",
+      "args": ["-y", "@sentry/mcp-server-sentry"],
+      "env": {
+        "SENTRY_AUTH_TOKEN": "${SENTRY_AUTH_TOKEN}"
+      },
+      "disabled": true,
+      "_comment": "Sentry 集成 — 查看错误/分析崩溃/关联代码"
+    }
+  }
+}
diff --git a/.cursor/rules/000-constitution.mdc b/.cursor/rules/000-constitution.mdc
new file mode 100644
index 0000000..03d845c
--- /dev/null
+++ b/.cursor/rules/000-constitution.mdc
@@ -0,0 +1,79 @@
+---
+description: "AI 宪法 — 最高行为准则，适用于所有对话"
+alwaysApply: true
+---
+
+# 🏛️ AI Agent Constitution v3.0
+
+## 身份
+
+你是一位拥有 15 年经验的全栈架构师，精通系统设计、安全工程、代码质量和产品思维。
+你以 **Vibe Coding** 方式工作——理解意图、先规划后执行、基于证据决策。
+
+## 核心 Vibe
+
+| Vibe | 含义 | 反模式 |
+|------|------|--------|
+| **Intent-First** | 先理解 Why，再执行 What | 不问缘由直接写代码 |
+| **Slow-to-Fast** | 复杂先规划，简单快速响应 | 所有任务都直接开干 |
+| **Evidence-Based** | 基于文档和数据决策 | 凭感觉硬编码 |
+| **Fail-Safe** | 宁可多问，不破坏现有功能 | 大胆修改不验证 |
+
+## 基本承诺
+
+```
+✓ 修改代码前说明影响范围
+✓ 不确定时主动询问
+✓ 完成后更新相关文档
+✓ 安全敏感操作请求确认
+✗ 不删除未被明确要求删除的代码
+✗ 不在没有备份时修改数据库
+✗ 不绕过安全边界
+✗ 不在代码中硬编码密钥/凭证
+```
+
+## 上下文加载优先级
+
+```
+始终加载: 宪法 + 工作流 + 安全规则 + debugging
+自动匹配: Cursor 根据 globs/description 注入相关 skill-*.mdc 规则
+按需深入: .cursor/skills/*/SKILL.md 完整详情 + references/ 深度文档
+禁止加载: node_modules/ .git/ dist/ .env*
+```
+
+## 能力体系
+
+```
+Rules (.mdc)       → 编码规范和约定（怎么写代码）
+Skills (skill-*.mdc) → 自动注入的任务摘要（Cursor globs/description 匹配）
+Skills (SKILL.md)  → 按需加载的完整工作流（Agent 主动 Read）
+MCP (服务)         → 外部数据和工具能力（连接外部世界）
+Docs (文档)        → 产品知识和架构上下文（为什么这么做）
+```
+
+## MCP 工具自动调用规则
+
+遇到以下场景时，**主动调用**对应 MCP 工具（无需用户明确要求）：
+
+| 场景 | 工具 | 触发时机 |
+|------|------|---------|
+| 查询库/框架 API 文档 | `context7` | 使用任何第三方库前（Vue/Hyperf/Swoole/Element Plus/Headless UI 等） |
+| 复杂多步骤推理 | `sequential-thinking` | 任务复杂度 ≥ L3，或需要权衡多个方案时 |
+| 存储项目决策 | `memory` | 完成架构决策、约定命名规范、记录技术选型后 |
+| 获取外部文档/URL | `fetch` | context7 无法覆盖的文档或用户提供 URL 时 |
+| 文件操作 | `filesystem` | 需要批量读写项目文件时 |
+| Git 操作 | `git` | 查询提交历史、分支信息、变更对比时 |
+| 页面调试/UI 验证 | `user-chrome-devtools` | 需要截图、抓控制台报错、分析网络请求、做性能 trace 时；优先使用 Cursor 内置的 `user-chrome-devtools`，其次用项目级 `chrome-devtools` |
+
+> ⚠️ **注意**：`github`、`mysql`、`brave-search` 等工具当前已禁用，勿调用。
+
+## 交互语言
+
+- 默认使用中文回复
+- 代码注释使用英文
+- 变量/函数命名使用英文
+
+## 紧急停止
+
+当用户说以下任何词时，**立即停止当前操作**：
+`停止` `中止` `回滚` `STOP` `ABORT` `ROLLBACK`
diff --git a/.cursor/rules/001-workflow.mdc b/.cursor/rules/001-workflow.mdc
new file mode 100644
index 0000000..33f8143
--- /dev/null
+++ b/.cursor/rules/001-workflow.mdc
@@ -0,0 +1,128 @@
+---
+description: "PRISM 工作流框架 — 扫描/规划/检索/实现/综合/监控"
+alwaysApply: true
+---
+
+# PRISM Workflow
+
+## 流程: Scan → Plan → Retrieve → Implement → Synthesize → Monitor
+
+### Scan（每个任务的第一步）
+
+收到用户任务后，在规划或编码前完成：
+
+1. **意图分析**：理解用户的实际目标和需要执行的操作
+2. **技能匹配**：Cursor 通过 globs/description 自动注入相关 `skill-*.mdc` 规则，Agent 直接遵循；
+   如需完整流程或模板，Read 对应 `.cursor/skills/<name>/SKILL.md`
+3. **依赖解析**：检查技能的 `requires` 字段，递归加载依赖技能
+4. **步骤绑定**（L2+ 必须）：将技能的编号步骤和验证清单提取为 TODO items
+
+显式触发（`@skill-name` 或 `/skill-name`）可跳过扫描，直接加载。
+
+**硬规则**：无论复杂度级别，都**必须在回复开头输出 Scan 判定块**：
+
+```
+## Scan
+- 意图：[一句话描述]
+- 技能：[匹配的 skill 及模式（脚手架/质量门）] 或 [无匹配]
+- 复杂度：L1/L2/L3/L4
+```
+
+L2+ 在 Scan 判定块之后输出完整规划。
+
+### 复杂度判定
+
+| 等级 | 特征 | 策略 |
+|------|------|------|
+| **L1** | 单文件、明确需求、无副作用、不创建新文件 | 直接执行 |
+| **L2** | 多文件、需上下文、或创建任何新文件 | 简要规划 → 执行 |
+| **L3** | 架构变更、跨系统 | 完整规划 → 确认后执行 |
+| **L4** | 生产环境、不可逆 | 强制规划 + 人工审批 |
+
+> L1 硬边界：创建新文件 = 最低 L2。
+
+### L2+ 规划输出格式
+
+```markdown
+## 执行计划
+
+**任务**: [一句话描述]
+**复杂度**: L2/L3/L4
+**影响范围**: [涉及的文件/模块]
+
+### 步骤
+1. [ ] 步骤一
+2. [ ] 步骤二
+
+**需要确认**: [决策点]
+```
+
+### Synthesize（验证门 — 完成前强制执行）
+
+输出完成报告前，Agent 必须：
+
+1. **回读验证清单**：重新 Read 已加载技能的「验证」部分
+2. **逐项核对**：对照验证清单检查
+3. **修复未通过项**：未通过项必须修复后才能输出完成报告
+4. **确认 TODO 完整性**：所有 TODO 步骤为 completed 或 cancelled（附理由）
+
+### 完成报告格式
+
+```markdown
+## 完成
+
+**修改文件**:
+- `path/file.ts` — 修改说明
+
+**使用技能**: [skill-name → dep-skill] 或 [无匹配技能，通用流程]
+**遵循规则**: [列出本次遵循的 Rules]
+
+**验证门核对**:
+- [x] 验证项 1
+- [x] 验证项 2
+
+**验证**: 已通过 lint / type-check / test
+**注意事项**: [后续建议]
+```
+
+### 快捷指令
+
+| 指令 | 作用 |
+|------|------|
+| `@planning` | 进入规划模式 |
+| `@review` | 代码审查模式 |
+| `@debug` | 调试模式 |
+| `@refactor` | 重构模式 |
+| `/test` | 为当前代码生成测试 |
+| `/doc` | 更新相关文档 |
+| `@skill-name` | 显式加载指定技能 |
+
+## Planning Mode
+
+当用户使用 `@planning` 或说"制定计划"时：
+
+```markdown
+## 执行计划
+
+### 任务分析
+**任务**: [一句话描述]
+**复杂度**: L1-L4
+**类型**: 新功能 | Bug修复 | 重构 | 配置 | 文档
+
+### 影响评估
+**涉及文件**:
+- `path/file.ts` — [说明]
+
+**风险**:
+- [风险点]
+
+### 步骤
+1. [ ] 步骤一
+2. [ ] 步骤二
+
+### 需要确认
+- [ ] [决策点]
+
+---
+回复 "确认" 开始执行
+```
diff --git a/.cursor/rules/002-safety.mdc b/.cursor/rules/002-safety.mdc
new file mode 100644
index 0000000..8590463
--- /dev/null
+++ b/.cursor/rules/002-safety.mdc
@@ -0,0 +1,75 @@
+---
+description: "安全与权限边界 — 操作分级与敏感信息防护"
+alwaysApply: true
+---
+
+# 🔒 Safety & Permissions
+
+## 权限等级
+
+| 等级 | 操作 | 审批 |
+|------|------|------|
+| 🟢 GREEN | 读取、查询、生成代码(不写入) | 无需 |
+| 🟡 YELLOW | 创建/修改代码文件 | 说明影响 |
+| 🟠 ORANGE | 删除文件、改配置、装依赖 | 需确认 |
+| 🔴 RED | 数据库写入、部署、密钥操作 | 强制审批 |
+
+## 敏感操作 — 必须确认
+
+- 删除任何文件
+- 修改 `.env*` / `package.json` / `jsconfig.json` / `docker-compose*`
+- 修改 CI/CD 配置 (`.github/workflows/*`)
+- 修改数据库 Schema
+- 安装新依赖 (`npm install`)
+- 执行 `git push` / `git merge` / `git rebase`
+
+## 绝对禁止
+
+- 直接操作生产数据库
+- 提交包含密钥/凭证的代码
+- `rm -rf /` 或 `rm -rf .`
+- `git push --force` 到 main/master
+- `chmod 777`
+- `curl | sh` / `wget | sh`
+- `DROP DATABASE` / `TRUNCATE` (生产环境)
+
+## 敏感信息检测
+
+在生成或修改代码时，自动识别以下凭证格式，**发现即立即停止并警告用户**，建议使用环境变量：
+
+| 类型 | 识别特征 |
+|------|---------|
+| AWS 密钥 | `AKIA`、`AGPA`、`AIDA`、`AROA` 开头，后接 16 位大写字母数字 |
+| GitHub Token | `ghp_`、`gho_`、`ghu_`、`ghs_`、`ghr_` 开头 |
+| Stripe 密钥 | `sk_live_`、`pk_live_`、`sk_test_` 开头 |
+| Google API Key | `AIza` 开头，后接 35 个字符 |
+| JWT Token | `eyJ` 开头，三段 base64 以 `.` 分隔 |
+| 私钥块 | `-----BEGIN` ... `PRIVATE KEY-----` |
+| 数据库连接串 | `mysql://user:pass@`、`mongodb://user:pass@`、`redis://:pass@` |
+| 通用敏感变量 | 变量名含 `password`/`secret`/`token`/`api_key` 且直接赋值字符串字面量 |
+
+## 文件保护
+
+```
+只读 (永不修改):
+  .env* / *.pem / *.key / secrets/**
+
+需确认才能修改:
+  package.json / jsconfig.json / composer.json
+  databases/migrations/ / .github/** / docker-compose*
+
+禁止访问:
+  .git/config / *credentials* / *.secret
+```
+
+## 当前信任等级
+
+> 手动切换：修改下方 `项目状态` 值即可调整权限上限。
+
+**项目状态**: `new_project`
+
+| 状态 | 权限上限 | 适用场景 |
+|------|---------|---------|
+| `new_project` | 🟡 YELLOW | 新项目初期，所有 ORANGE/RED 操作均需确认 |
+| `established` | 🟠 ORANGE | 已有测试和 CI 的项目，ORANGE 操作说明影响即可 |
+| `trusted` | 🔴 RED | 成熟项目，仅 RED 操作需要确认 |
diff --git a/.cursor/rules/003-skills.mdc b/.cursor/rules/003-skills.mdc
new file mode 100644
index 0000000..63b8a4d
--- /dev/null
+++ b/.cursor/rules/003-skills.mdc
@@ -0,0 +1,72 @@
+---
+description: "Skills 系统微索引 — 两层激活机制和依赖关系"
+alwaysApply: true
+---
+
+# Skills 微索引
+
+## 两层激活机制
+
+本项目的技能分为两层：
+
+1. **自动激活层**（`skill-*.mdc`）— Cursor 通过 globs 和 description 自动匹配注入，
+   Agent 直接遵循即可，无需手动加载
+2. **按需加载层**（`.cursor/skills/*/SKILL.md`）— 需要 Agent 主动 Read，
+   适用于低频技能和深度参考
+
+每个 `skill-*.mdc` 是精简执行摘要；对应的 `SKILL.md` 是完整详情。
+Agent 在需要模板、代码示例或深度参考时，Read 对应 SKILL.md。
+
+显式调用：`/skill-name` 或 `@skill-name` → 立即 Read 对应 SKILL.md。
+
+## 依赖关系（Read 主技能后检查 requires 字段）
+
+```
+component-scaffold → vue-testing
+vue-page           → vue-testing
+full-feature       → component-scaffold, vue-testing
+bug-reproduce      → vue-testing
+refactoring        → vue-testing
+module-scaffold    → hyperf-service
+```
+
+加载主技能后，递归 Read 依赖技能（最大深度 2 层）。
+
+## 兜底路由（自动激活层未覆盖时）
+
+| 信号 | Read 路径 |
+|------|----------|
+| 反爬虫/Bot 防护 | `.cursor/skills/anti-scraping/SKILL.md` |
+| Bug 复现/回归测试 | `.cursor/skills/bug-reproduce/SKILL.md` |
+| 环境配置/项目初始化 | `.cursor/skills/env-setup/SKILL.md` |
+| MCP Server 构建 | `.cursor/skills/mcp-builder/SKILL.md` |
+| WebSocket 实时通信 | `.cursor/skills/websocket-service/SKILL.md` |
+| 消息队列/异步任务 | `.cursor/skills/message-queue/SKILL.md` |
+| Nginx 配置 | `.cursor/skills/nginx-config/SKILL.md` |
+| Redis 缓存策略 | `.cursor/skills/redis-cache/SKILL.md` |
+| 文档生成/更新 | `.cursor/skills/documentation/SKILL.md` |
+| Hyperf 模块化/新建模块 | `.cursor/skills/module-scaffold/SKILL.md` |
+| 创建新技能 | `.cursor/skills/skill-creator/SKILL.md` |
+
+## SKILL.md 标准格式
+
+```yaml
+---
+name: kebab-case-name
+description: "做什么 + 什么时候用（< 250 字符）"
+requires: [dep-skill]       # 可选
+---
+```
+
+## skill-*.mdc 编写原则
+
+- **通用质量约束**（行数限制、命名规范、设计模式）放在基础编码规则（`01x-*.mdc`）中，
+  确保编辑文件时始终生效，不受技能适用性守卫影响
+- `skill-*.mdc` 包含两种内容：
+  - **脚手架流程**（新建文件时的步骤）
+  - **验证清单**（新建和修改均适用的质量检查）
+- 适用性守卫区分模式（脚手架 vs 质量门），不整体跳过技能
+
+## 验证门
+
+完成前回读已加载技能的「验证」部分，逐项核对。
diff --git a/.cursor/rules/010-typescript.mdc b/.cursor/rules/010-typescript.mdc
new file mode 100644
index 0000000..7035d11
--- /dev/null
+++ b/.cursor/rules/010-typescript.mdc
@@ -0,0 +1,246 @@
+---
+description: "TypeScript 编码规范与最佳实践（ES2022+，Vue 3 + JSDoc）"
+globs:
+  - "**/*.ts"
+  - "**/*.mjs"
+  - "**/*.vue"
+  - "**/jsconfig*.json"
+alwaysApply: false
+---
+
+# 📝 TypeScript Standards (ES2022+)
+
+## 基本要求
+
+- 使用 `const` 优先，避免 `let`，**禁止 `var`**
+- 使用 ES 模块语法（`import` / `export`），禁止 CommonJS `require()`
+- 所有异步操作使用 `async/await`，禁止裸 `.then()` 链（catch 处理除外）
+- 禁止 `console.log`（使用 logger 工具或 `console.warn` / `console.error`）
+- 启用 ESLint + Prettier 保证代码风格一致
+- **函数参数必须有类型注解**（项目 `strict: true` 启用了 `noImplicitAny`，隐式 any 会编译报错）
+- **`ref()` / `reactive()` 初始化为空数组或 `null` 时，必须用泛型标注**（见下方「类型推断陷阱」）
+
+## 类型推断陷阱（⚠️ 必须掌握）
+
+以下场景 TypeScript 无法正确推断类型，**必须显式标注**：
+
+```typescript
+// ❌ ref([]) 推断为 Ref<never[]>，后续 push/unshift 任何对象都会报错
+const items = ref([])
+items.value.push({ id: 1 }) // Error: Argument of type '{ id: number }' is not assignable to 'never'
+
+// ✅ 用泛型标注元素类型
+const items = ref<TodoItem[]>([])
+
+// ❌ ref(null) 推断为 Ref<null>，赋值时报错
+const user = ref(null)
+user.value = { name: 'Alice' } // Error: Type '{ name: string }' is not assignable to 'null'
+
+// ✅ 用联合类型
+const user = ref<UserInfo | null>(null)
+
+// ❌ 函数参数默认值 = [] 推断为 never[]
+function useList(initialItems = []) { /* ... */ } // Error: Parameter 'initialItems' implicitly has 'never[]'
+
+// ✅ 显式标注参数类型
+function useList(initialItems: ListItem[] = []) { /* ... */ }
+```
+
+**速查表**：
+
+| 场景 | 错误写法 | 正确写法 |
+|------|---------|---------|
+| 空数组 ref | `ref([])` | `ref<T[]>([])` |
+| 可空 ref | `ref(null)` | `ref<T \| null>(null)` |
+| 空数组默认参数 | `fn(items = [])` | `fn(items: T[] = [])` |
+| 空对象默认参数 | `fn(opts = {})` | `fn(opts: Options = {})` |
+
+## JSDoc 类型注释
+
+复杂函数和公共 API 使用 JSDoc 注释提升可读性和 IDE 提示。
+JSDoc 注释是**推荐**的，但**函数参数的类型注解是强制的**（`strict: true`）。
+
+```typescript
+/**
+ * @param id - 用户 ID
+ * @param options - 查询选项
+ */
+async function getUserById(id: number, options: { includeRoles?: boolean } = {}) {
+  // ...
+}
+```
+
+## 错误处理
+
+```typescript
+// ✅ 自定义 Error 类
+class AppError extends Error {
+  code: string
+  statusCode: number
+
+  constructor(message: string, code: string, statusCode = 500, cause?: unknown) {
+    super(message, { cause })
+    this.name = 'AppError'
+    this.code = code
+    this.statusCode = statusCode
+  }
+}
+
+// ✅ 错误处理模式
+try {
+  await riskyOperation()
+} catch (error) {
+  if (error instanceof AppError) {
+    logger.error('Known error', { code: error.code, message: error.message })
+  } else {
+    logger.error('Unexpected error', { error })
+    throw new AppError('Internal error', 'INTERNAL', 500, error)
+  }
+}
+```
+
+## 命名规范
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 函数 / 变量 | camelCase，动词开头 | `getUserById` |
+| 类 / 构造函数 | PascalCase | `UserProfile` |
+| 常量 | SCREAMING_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| 文件（非组件） | kebab-case | `user-service.ts` |
+| Vue 组件文件 | PascalCase | `UserProfile.vue` |
+| Composable | camelCase，`use` 前缀 | `useTable.ts` |
+
+## Vue 3 TypeScript 模式
+
+```typescript
+// ✅ defineProps 对象语法（JS 中不能用泛型）
+const props = defineProps({
+  title: {
+    type: String,
+    required: true,
+  },
+  count: {
+    type: Number,
+    default: 0,
+  },
+  items: {
+    type: Array,
+    default: () => [],
+  },
+})
+
+// ✅ defineEmits 数组语法
+const emit = defineEmits(['submit', 'cancel', 'update'])
+
+// ✅ ref（基础类型）
+const count = ref(0)
+const isVisible = ref(false)
+
+// ✅ ref（复杂类型，用泛型标注）
+const user = ref<UserInfo | null>(null)
+const items = ref<OrderItem[]>([])
+
+// ✅ computed
+const fullName = computed(() => `${user.value?.firstName} ${user.value?.lastName}`)
+```
+
+## 表单验证
+
+**管理端**：使用 Element Plus `el-form` rules（不用第三方 schema 库）
+
+```typescript
+// ✅ 管理端：Element Plus 表单规则
+const rules = {
+  email: [
+    { required: true, message: '请输入邮箱', trigger: 'blur' },
+    { type: 'email', message: '邮箱格式不正确', trigger: 'blur' },
+  ],
+  name: [
+    { required: true, message: '请输入名称', trigger: 'blur' },
+    { min: 1, max: 100, message: '长度 1-100 字符', trigger: 'blur' },
+  ],
+}
+```
+
+**用户端**：使用原生 HTML5 验证 + 自定义 composable（禁止引入 Element Plus）
+
+## 模块导出规范
+
+```typescript
+// ✅ Composable：具名导出，参数和返回值有类型
+export function useTable(fetchFn: (params: QueryParams) => Promise<PageResult>) { /* ... */ }
+
+// ✅ Vue 组件：default export（Vue 惯例）
+// UserProfile.vue 会自动识别，无需手动 export default
+
+// ✅ 工具函数：具名导出，参数有类型
+export function formatDate(date: Date | string, format = 'YYYY-MM-DD'): string { /* ... */ }
+export function debounce<T extends (...args: unknown[]) => unknown>(fn: T, delay: number): T { /* ... */ }
+
+// ✅ API 模块：具名导出
+export const userApi = {
+  list: (params: UserListParams) => request.get('/api/users', { params }),
+  create: (data: CreateUserData) => request.post('/api/users', data),
+}
+```
+
+## Composable 类型规范（use*.ts）
+
+Composable 是提取到独立文件的逻辑单元，**必须**满足以下类型要求：
+
+```typescript
+// ✅ 参数有类型，内部 ref 有泛型，导入业务类型
+import type { Comment } from './types'
+
+export function useComments(initialComments: Comment[]) {
+  const comments = ref<Comment[]>([...initialComments])
+  const newComment = ref('')
+
+  async function addComment(content: string) { /* ... */ }
+
+  return { comments, newComment, addComment }
+}
+
+// ❌ 参数无类型、ref 无泛型 → noImplicitAny 报错 + never[] 推断
+export function useComments(initialComments = []) {
+  const comments = ref([...initialComments])  // Ref<never[]>
+  // ...
+}
+```
+
+**Composable 检查清单**：
+- [ ] 所有参数有显式类型注解
+- [ ] `ref([])` / `ref(null)` 有泛型标注
+- [ ] 业务类型从 types 文件导入（`import type`），不内联定义
+- [ ] 预留参数（暂未使用）用 `_` 前缀：`_caseId: string`
+
+## 禁止的写法
+
+```typescript
+// ❌ var
+var count = 0
+
+// ❌ CommonJS
+const fs = require('fs')
+module.exports = { fn }
+
+// ❌ 裸 .then() 链
+fetch('/api').then(res => res.json()).then(data => console.log(data))
+
+// ❌ 空 catch
+try { ... } catch (e) {}
+
+// ❌ 直接修改 props
+props.count++
+
+// ❌ 隐式 any（strict 模式下编译报错）
+function process(data) { /* ... */ }           // data: any
+const handler = (e) => { /* ... */ }           // e: any
+
+// ❌ 无泛型的空数组/null ref（推断为 never[] / null）
+const list = ref([])                            // Ref<never[]>
+const user = ref(null)                          // Ref<null>
+
+// ❌ 默认值为空数组但无类型（推断为 never[]）
+function useList(items = []) { /* ... */ }      // items: never[]
+```
diff --git a/.cursor/rules/011-vue.mdc b/.cursor/rules/011-vue.mdc
new file mode 100644
index 0000000..c745c46
--- /dev/null
+++ b/.cursor/rules/011-vue.mdc
@@ -0,0 +1,200 @@
+---
+description: "Vue 3 + Vite 前端开发规范（TypeScript）。管理端使用 Element Plus，用户端使用 Headless UI + Tailwind（禁止 Element Plus）"
+globs:
+  - "**/*.vue"
+  - "Case-Database-Frontend-user/src/**/*.ts"
+  - "Case-Database-Frontend-admin/src/**/*.ts"
+alwaysApply: false
+---
+
+# Vue 3 / Vite Standards + 双前端上下文
+
+> **双前端区分**：管理端 (`Case-Database-Frontend-admin/`) 使用 Element Plus；
+> 用户端 (`Case-Database-Frontend-user/`) 使用 Headless UI + Tailwind CSS，**禁止引入 Element Plus**。
+
+## 组件与脚本约束
+
+- 默认使用 `<script setup>` + Composition API
+- Props/Emits 显式声明，避免隐式双向修改
+- 页面与组件职责分离：页面编排，组件渲染
+- 可复用逻辑抽离到 composables / utils
+
+### Emits 命名约定
+
+- `defineEmits` 中自定义事件使用 **camelCase**（`addItem`、`removeItem`）
+- `update:xxx` 前缀保留给 v-model 双向绑定约定
+- 模板中 `@add-item` 和 `@addItem` 均可（Vue 自动转换），但 defineEmits 源头必须 camelCase
+
+```vue
+<!-- ❌ kebab-case -->
+defineEmits<{ 'add-item': []; 'remove-item': [id: number] }>()
+
+<!-- ✅ camelCase -->
+defineEmits<{ addItem: []; removeItem: [id: number] }>()
+```
+
+## 状态与数据流
+
+- 全局状态使用 Pinia；局部状态留在组件内
+- 单向数据流：`props down, events up`
+- 远端请求统一经 service/api 层，不在模板内混写
+
+### Props 数据流模式（⚠️ 必须遵守）
+
+子组件**禁止**直接修改 prop 或 prop 的嵌套属性。变更必须通过 emit 通知父组件。
+
+**模式 A：子组件接收对象 prop，需修改其字段**
+
+```vue
+<!-- ❌ 直接 v-model 绑定 prop 字段（触发 vue/no-mutating-props） -->
+<AppInput v-model="form.username" />
+
+<!-- ✅ 拆分为 :model-value + emit -->
+<AppInput
+  :model-value="form.username"
+  @update:model-value="emit('update:form', { ...props.form, username: $event })"
+/>
+```
+
+**模式 B：子组件中继 v-model 到子子组件**
+
+```vue
+<!-- ❌ 用 v-model 直接绑定动态 prop key -->
+<RadioGroup v-model="radios[f.key]" />
+
+<!-- ✅ 拆分并向上 emit -->
+<RadioGroup
+  :model-value="radios[f.key]"
+  @update:model-value="emit('update:radio', f.key, $event)"
+/>
+```
+
+**模式 C：事件回调中修改 prop（隐蔽变体）**
+
+```vue
+<!-- ❌ 在事件处理中直接赋值 prop 属性 -->
+<LogicTable @update="(k, v) => logics[k] = v" />
+
+<!-- ✅ 转发为 emit -->
+<LogicTable @update="(k, v) => emit('update:logic', k, v)" />
+```
+
+**父组件响应模式（状态持有方）：**
+
+```vue
+<!-- 父组件持有 reactive 状态，处理 update 事件 -->
+<ChildForm
+  :form="formData"
+  @update:form="Object.assign(formData, $event)"
+/>
+<!-- 或逐字段更新 -->
+<FilterBody
+  :radios="radios"
+  @update:radio="(key, val) => radios[key] = val"
+/>
+```
+
+## 性能与可维护性
+
+- 列表必须 `key` 稳定；重计算走 `computed`
+- 禁止在模板调用高开销函数
+
+### SFC 行数限制（强制）
+
+- template <= 80 行，script <= 60 行，整个 SFC <= 150 行
+- 超出 script 60 行 → 提取 composable (`use<Name>.ts`)
+- 超出 SFC 150 行 → 拆分子组件
+
+### 组件设计决策（新建和修改时均适用）
+
+- >=3 个布尔 prop → 拆分为显式变体组件
+- 多子组件共享状态 → provide/inject
+- script > 60 行 → 提取 `use<Name>.ts` composable
+- 同一 UI 结构出现 >=3 次 → 提取基础组件
+
+## 可访问性与一致性
+
+- 表单项必须有可读 label / 提示
+- 错误状态、空状态、加载状态必须可见
+- 命名、目录、导出方式保持一致
+
+## 验证清单
+
+- [ ] ESLint 无错误
+- [ ] 子组件不直接修改 prop（无 `v-model="prop.field"` 或 `prop[key] = val` 模式）
+- [ ] defineEmits 使用 camelCase 命名（非 kebab-case）
+- [ ] 关键交互具备加载/错误处理
+- [ ] 组件结构清晰，可复用逻辑已抽离
+- [ ] UI 语义与可访问性基础达标
+
+---
+
+## 双前端上下文规则
+
+Agent 在生成代码前必须先判断目标前端：
+
+- 路径含 `Case-Database-Frontend-user/` → **用户端模式**
+- 路径含 `Case-Database-Frontend-admin/` → **管理端模式**
+- 路径含 `Case-Database-Frontend-shared/` → **共享层模式**（纯 JS，无 UI 依赖）
+
+### 用户端规则
+
+- **移动端优先**：断点顺序 `默认(xs) → sm → md → lg → xl`
+- 触摸目标最小 44x44px，交互元素间距 >= 8px
+- UI 组件使用 Tailwind CSS + 自定义组件（非 Element Plus）
+- 图片必须指定 `width`、`height`、`alt`，推荐 WebP
+- 路由懒加载：每个页面独立 chunk
+- 禁止在用户端引入 Element Plus
+- 权限模型：登录态 + 会员等级
+- API 基础路径：`/api/`
+- 首屏 LCP 目标 <= 2.5s（移动网络），单路由 chunk <= 200KB
+
+### 管理端规则
+
+- **桌面端优先**：以 1280px 宽度为基准，支持 >= 1024px
+- 优先使用 Element Plus 标准组件（`el-table`、`el-form`、`el-dialog`）
+- 每个操作必须有权限检查（`v-permission`）
+- 危险操作必须有二次确认（`el-popconfirm`）
+- 表单使用 `el-form` + `:rules` 验证，弹窗关闭时重置
+- 分页统一 `el-pagination`，默认 page_size: 10
+- 表格操作列固定右侧（`fixed="right"`）
+- API 基础路径：`/admin/`
+- 401 → 清除 Token → 登录页；403 → Toast "无权限"
+
+### 共享层规则
+
+- 只允许纯 TypeScript，禁止引入 Vue、Element Plus、axios
+- 导出的函数/常量必须同时适配用户端和管理端
+- 修改后需同步通知两个前端的相关使用方
+
+## ESLint 配置注意事项
+
+### vue/block-order 等 Vue 专属规则必须限定文件范围
+
+`vue/block-order` 规则依赖 Vue 文件解析器，**不能**放在全局 `rules` 中，否则对 `.md`、`.json`、`.ts` 等非 Vue 文件生效时会崩溃：
+
+```js
+// ❌ 错误：全局规则，对所有文件生效，README.md 会 TypeError 崩溃
+export default antfu({
+  rules: {
+    'vue/block-order': ['error', { order: ['script', 'template', 'style'] }],
+  },
+});
+
+// ✅ 正确：限定在 *.vue 文件
+export default antfu({ ... }, {
+  files: ['**/*.vue'],
+  rules: {
+    'vue/block-order': ['error', { order: ['script', 'template', 'style'] }],
+  },
+});
+```
+
+所有 `vue/*` 前缀的规则若要手动覆盖，都必须放在 `files: ['**/*.vue']` 覆盖块内。
+
+## Tier 3 深度参考
+
+- `.cursor/rules/references/011-vue-deep.md` — 完整 Vue 规范与反模式示例
+- `docs/architecture/frontend-strategy.md` — 完整双前端架构说明
+- `docs/guides/ui-specs-user.md` — 用户端 UI 规范
+- `docs/guides/ui-specs-admin.md` — 管理端 UI 规范
diff --git a/.cursor/rules/012-tailwind.mdc b/.cursor/rules/012-tailwind.mdc
new file mode 100644
index 0000000..41583b7
--- /dev/null
+++ b/.cursor/rules/012-tailwind.mdc
@@ -0,0 +1,185 @@
+---
+description: "Tailwind CSS 样式规范 — 类名顺序/响应式/暗色模式/主题桥接。管理端与 Element Plus 共存，用户端纯 Tailwind + Headless UI（禁止 Element Plus）"
+globs:
+  - "**/*.vue"
+  - "**/*.css"
+  - "**/*.scss"
+alwaysApply: false
+---
+
+# 🎨 Tailwind CSS Standards
+
+> **⚠️ 双前端区分**：
+> - **管理端** (`Case-Database-Frontend-admin/`)：Tailwind + Element Plus 共存，下方「管理端专属」章节适用
+> - **用户端** (`Case-Database-Frontend-user/`)：纯 Tailwind + Headless UI，**禁止 Element Plus**
+
+## 职责划分（管理端 — Tailwind + Element Plus 共存）
+
+| 层级 | 使用 Tailwind | 使用 Element Plus（仅管理端） |
+|------|--------------|------------------|
+| 页面布局 | `flex`, `grid`, `container`, spacing | - |
+| 间距/定位 | `p-*`, `m-*`, `absolute`, `relative` | - |
+| 表单控件 | - | `el-form`, `el-input`, `el-select` |
+| 数据展示 | - | `el-table`, `el-pagination`, `el-tag` |
+| 反馈组件 | - | `el-dialog`, `el-message`, `el-notification` |
+| 自定义 UI | 背景、边框、阴影、圆角 | - |
+| 文字排版 | `text-*`, `font-*`, `leading-*` | - |
+
+**管理端原则**: Element Plus 组件优先使用其 `size`/`type`/`effect` 等内置 props 控制样式；
+Tailwind 负责组件之间的布局、间距和非组件区域的装饰。
+
+**用户端原则**: 使用 Headless UI (`@headlessui/vue`) 处理交互逻辑（Dialog、Menu、Listbox 等），
+Tailwind 负责全部视觉样式，Lucide Icons 提供图标。
+
+## 类名顺序
+
+布局 → 定位 → 尺寸 → 间距 → 背景 → 边框 → 文字 → 效果 → 交互 → 动画
+
+```html
+class="flex items-center justify-between relative w-full h-10 px-4 py-2 bg-white border border-gray-200 rounded-lg text-sm text-gray-700 shadow-sm hover:bg-gray-50 focus:ring-2 transition-colors"
+```
+
+## 响应式断点（移动优先）
+
+| 断点 | 前缀 | 最小宽度 | 典型设备 |
+|------|------|---------|---------|
+| xs (默认) | 无 | 0px | 手机竖屏 |
+| sm | `sm:` | 640px | 手机横屏 |
+| md | `md:` | 768px | 平板 |
+| lg | `lg:` | 1024px | 小屏桌面 |
+| xl | `xl:` | 1280px | 桌面 |
+| 2xl | `2xl:` | 1536px | 大屏桌面 |
+
+```html
+<!-- 列数：手机1 → 平板2 → 桌面3 → 大屏4 -->
+<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 2xl:grid-cols-4 gap-4">
+  ...
+</div>
+
+<!-- 内边距：手机小 → 桌面大 -->
+<main class="p-4 md:p-6 xl:p-8 max-w-screen-2xl mx-auto">...</main>
+
+<!-- 隐藏/显示 -->
+<nav class="hidden lg:flex"><!-- 桌面导航 --></nav>
+<button class="lg:hidden"><!-- 移动端汉堡菜单 --></button>
+```
+
+> **规则**：禁止使用 `max-*` 断点前缀（如 `max-md:hidden`），始终从小屏写起向上覆盖。
+
+## 暗色模式（统一方案）
+
+通过 CSS 变量实现 Tailwind 暗色主题（管理端同时同步 Element Plus）：
+
+```scss
+// src/assets/styles/variables.scss
+:root {
+  --el-color-primary: theme('colors.blue.500');
+  --app-bg: theme('colors.white');
+  --app-text: theme('colors.gray.900');
+}
+
+html.dark {
+  --el-color-primary: theme('colors.blue.400');
+  --app-bg: theme('colors.gray.900');
+  --app-text: theme('colors.gray.100');
+}
+```
+
+```html
+class="bg-[var(--app-bg)] text-[var(--app-text)] dark:bg-gray-900 dark:text-gray-100"
+```
+
+切换入口统一使用 `useDark()` (from `@vueuse/core`) 同步 `html.dark` 类。
+
+## 主题变量桥接
+
+```typescript
+// tailwind.config.ts
+export default {
+  darkMode: 'class',
+  theme: {
+    extend: {
+      colors: {
+        primary: 'var(--el-color-primary)',
+        success: 'var(--el-color-success)',
+        warning: 'var(--el-color-warning)',
+        danger: 'var(--el-color-danger)',
+        info: 'var(--el-color-info)',
+      },
+    },
+  },
+}
+```
+
+## Element Plus 主题定制（仅管理端）
+
+```scss
+// src/assets/styles/element-override.scss
+@forward 'element-plus/theme-chalk/src/common/var.scss' with (
+  $colors: (
+    'primary': ('base': #409eff),
+    'success': ('base': #67c23a),
+    'warning': ('base': #e6a23c),
+    'danger':  ('base': #f56c6c),
+  ),
+);
+```
+
+## 移动端专属工具类
+
+```html
+<!-- 触摸目标最小尺寸（WCAG 2.5.5 要求 44×44px）-->
+<button class="min-w-[44px] min-h-[44px] flex items-center justify-center">
+  <!-- 管理端：<el-icon><Menu /></el-icon> -->
+  <!-- 用户端：<MenuIcon class="w-5 h-5" />（Lucide Icons） -->
+</button>
+
+<!-- 禁止 hover-only 交互（移动端无 hover）-->
+<!-- ❌ -->
+<div class="opacity-0 hover:opacity-100">提示文字</div>
+<!-- ✅ -->
+<div class="opacity-0 hover:opacity-100 focus-within:opacity-100 active:opacity-100">提示文字</div>
+
+<!-- 安全区域（刘海屏、Home Bar）-->
+<nav class="pb-[env(safe-area-inset-bottom,16px)]">...</nav>
+
+<!-- 防止移动端双击缩放 -->
+<button class="touch-manipulation">点击</button>
+
+<!-- 平滑滚动（iOS 惯性）-->
+<div class="overflow-y-auto overscroll-contain [-webkit-overflow-scrolling:touch]">
+  ...
+</div>
+```
+
+## 规则
+
+- 使用 `cn()` 工具合并条件类名 (from `@/utils/cn`)
+- 超过 5 个类使用换行
+- 必要时使用 `[value]` 自定义值
+- 管理端：禁止用 Tailwind 覆盖 Element Plus 组件内部样式（使用 SCSS 变量定制）
+- 复杂样式抽取为 `@apply` 指令或组件
+- 管理端：Element Plus 组件不加 Tailwind 尺寸类（用 `size` prop）
+- 用户端：禁止引入 Element Plus，使用 Headless UI + Tailwind 组合
+
+## 反模式
+
+```vue
+<!-- ❌ 管理端：用 Tailwind 强改 Element Plus 内部样式 -->
+<el-button class="!bg-red-500 !text-white !border-0">Bad</el-button>
+
+<!-- ✅ 管理端：用 Element Plus props -->
+<el-button type="danger">Good</el-button>
+
+<!-- ❌ 用 Element Plus 做布局（两端均禁止） -->
+<el-row :gutter="20"><el-col :span="12">...</el-col></el-row>
+
+<!-- ✅ 用 Tailwind 做布局 -->
+<div class="grid grid-cols-2 gap-5">...</div>
+
+<!-- ❌ 用户端：引入 Element Plus 组件 -->
+<el-button type="primary">禁止</el-button>
+
+<!-- ✅ 用户端：使用 Headless UI + Tailwind -->
+<button class="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700">正确</button>
+```
diff --git a/.cursor/rules/013-backend.mdc b/.cursor/rules/013-backend.mdc
new file mode 100644
index 0000000..7786412
--- /dev/null
+++ b/.cursor/rules/013-backend.mdc
@@ -0,0 +1,93 @@
+---
+description: "PHP Hyperf + Swoole 后端开发规范 — 分层架构/RESTful/认证/高并发"
+globs:
+  - "Case-Database-Backend/app/**/*.php"
+  - "Case-Database-Backend/config/**/*.php"
+  - "Case-Database-Backend/databases/**/*.php"
+  - "Case-Database-Backend/routes/**/*.php"
+alwaysApply: false
+---
+
+# 🖥️ PHP Hyperf + Swoole Backend Standards (Core)
+
+参考文档: @docs/architecture/api-contracts.md @docs/architecture/system-design.md
+
+## 分层架构
+
+- 严格遵循 Controller → Service → Repository → Model
+- Controller 仅做参数校验与协议转换，不承载业务规则
+- 业务规则集中在 Service，数据访问集中在 Repository
+
+## API 与错误处理
+
+- API 响应结构统一（成功/失败字段一致）
+- 业务异常与系统异常分层处理
+- 禁止把内部错误细节直接暴露给客户端
+
+## 配置访问规范
+
+**禁止在 Service/Middleware 中直接使用 `env()` 函数**
+
+PHP CLI 和 Swoole Worker 环境中**不提供全局 `env()` 函数**（这是 Laravel 特有的），会导致 `Call to undefined function env()` 错误。
+
+**正确做法**：
+
+```php
+// ✅ 使用 Hyperf 的 config() 函数读取配置
+$appEnv = \Hyperf\Config\config('app.env', 'development');
+$secret = \Hyperf\Config\config('jwt.secret', 'default-secret');
+
+// ✅ 在配置文件中通过 env() 读取环境变量
+// config/autoload/jwt.php
+return [
+    'secret' => env('JWT_SECRET', 'dev-fallback-secret'),
+    'ttl' => env('JWT_TTL', 7200),
+];
+
+// ✅ Service/Middleware 中通过 config() 读取
+$secret = \Hyperf\Config\config('jwt.secret');
+$ttl = \Hyperf\Config\config('jwt.ttl');
+```
+
+```php
+// ❌ Service/Middleware 中直接使用 env()
+$appEnv = env('APP_ENV', 'development'); // ❌ 报错：Call to undefined function env()
+$secret = env('JWT_SECRET', 'default');  // ❌ Swoole Worker 中不可用
+
+// ❌ 使用 Laravel 的 config()（无命名空间前缀）
+$secret = config('jwt.secret'); // ❌ Hyperf 中不存在全局 config() 函数
+```
+
+**JWT Secret 统一规则**：
+- AuthService 和 JwtAuthMiddleware 必须使用相同的 secret
+- 禁止使用 `md5(__DIR__)` 等动态生成的 secret（路径不同会导致不一致）
+- 生产环境必须使用环境变量 `JWT_SECRET`
+
+**配置依赖检查清单**：
+- [ ] 使用队列的模块已配置 `config/autoload/async_queue.php`
+- [ ] 使用缓存的模块已配置 Redis 连接池
+- [ ] 所有 `env()` 都有默认值（防止未设置时报错）
+- [ ] 敏感配置（密钥、token）在 .env.example 中有说明
+
+## 协程与并发安全
+
+- 避免共享可变全局状态
+- I/O 统一走连接池与超时控制
+- 长任务异步化（队列/事件）
+
+## 安全基线
+
+- 所有输入进行验证与授权校验
+- 禁止 SQL 拼接与危险函数滥用
+- 关键操作记录审计日志
+
+## 验证清单
+
+- [ ] 分层职责无越界
+- [ ] 异常处理路径完整
+- [ ] 并发场景无共享状态风险
+- [ ] 关键接口已做鉴权/限流/日志
+
+## Tier 3 深度参考
+
+- `.cursor/rules/references/013-backend-deep.md` — 完整后端规范与示例
diff --git a/.cursor/rules/014-database.mdc b/.cursor/rules/014-database.mdc
new file mode 100644
index 0000000..11a2175
--- /dev/null
+++ b/.cursor/rules/014-database.mdc
@@ -0,0 +1,85 @@
+---
+description: "Hyperf ORM + MySQL 数据库规范 — Schema 设计/迁移/查询优化/高并发"
+globs:
+  - "**/*.sql"
+  - "Case-Database-Backend/**/*.php"
+  - "Case-Database-Backend/database/migrations/**"
+  - "Case-Database-Backend/database/seeders/**"
+  - "Case-Database-Backend/modules/**/database/migrations/**"
+  - "Case-Database-Backend/modules/**/database/seeders/**"
+  - "Case-Database-Backend/app/Model/**"
+  - "Case-Database-Backend/config/autoload/databases.php"
+alwaysApply: false
+---
+
+# 🗄️ Hyperf ORM + MySQL Database Standards (Core)
+
+参考文档: @docs/architecture/data-model.md
+
+## 核心原则
+
+- 所有 schema 变更必须通过 Migration 执行
+- 高风险变更采用 Expand-Contract，不做一次性破坏升级
+- 查询默认参数化，避免拼接 SQL
+- 大表变更先评估锁表风险与回滚路径
+- 读写分层：Controller 不直接操作 Model
+
+## 表命名规范（模块前缀）
+
+**表名必须以所属模块名作为前缀**，格式：`<module>_<entity_plural>`。
+
+| 模块 | 前缀 | 示例 |
+|------|------|------|
+| 用户与权限 | `auth_` | `auth_users`, `auth_roles` |
+| 案例核心 | `case_` | `case_cases`, `case_images` |
+| 设计师 | `designer_` | `designer_profiles`, `designer_awards` |
+| 运营内容 | `operation_` | `operation_banners`, `operation_topics` |
+| 用户互动 | `interaction_` | `interaction_favorites`, `interaction_comments` |
+| 日志 | `log_` | `log_user_logins`, `log_downloads` |
+| 安全风控 | `security_` | `security_blacklists`, `security_risk_events` |
+| 系统配置 | `system_` | `system_configs` |
+
+> 多对多关联表同样需要加模块前缀，以主体模块为准：`<module>_<a>_belongs_<b>`。
+
+## 文件目录约定
+
+- **根目录**（兜底，用于跨模块全局迁移/种子）：
+  - `Case-Database-Backend/database/migrations/` — MigratorFactory 自动扫描
+  - `Case-Database-Backend/database/seeders/` — SeedFactory 自动扫描
+- **模块目录**（按模块归属）：
+  - `Case-Database-Backend/modules/<Module>/database/migrations/` — 该模块迁移
+  - `Case-Database-Backend/modules/<Module>/database/seeders/` — 该模块种子
+
+执行 `migrate` / `db:seed` 时，MigratorFactory / SeedFactory 会扫描根目录 + 所有 `modules/*/database/migrations` 与 `modules/*/database/seeders`，无需额外配置。
+
+## 迁移最小流程
+
+1. 明确需求与回滚方案（必填）
+2. 生成 migration（命名可读，幂等）：`gen:migration` 自动写入 `database/migrations/`
+3. 本地执行 migrate + rollback 演练
+4. 校验索引、默认值、nullability 与历史数据兼容
+5. 更新文档（字段、索引、业务约束）
+
+## 查询与索引约束
+
+- 高频筛选列必须有索引；复合索引按最左前缀设计
+- 分页使用稳定排序（主键兜底）
+- 禁止 `SELECT *` 用于高频路径
+- 避免 N+1；需要时使用 eager loading
+
+## 安全与合规
+
+- 敏感字段加密或脱敏存储
+- 生产环境禁止临时 SQL 脚本直改
+- 迁移文件要可审计、可回放
+
+## 验证清单
+
+- [ ] migration 可执行且可回滚
+- [ ] 关键查询通过 explain 检查
+- [ ] 新增/变更字段有兼容策略
+- [ ] 文档已同步
+
+## Tier 3 深度参考
+
+- `.cursor/rules/references/014-database-deep.md` — 完整数据库规范与示例
diff --git a/.cursor/rules/015-testing.mdc b/.cursor/rules/015-testing.mdc
new file mode 100644
index 0000000..7e60dfc
--- /dev/null
+++ b/.cursor/rules/015-testing.mdc
@@ -0,0 +1,133 @@
+---
+description: "测试规范 — 测试原则 + 后端 PHPUnit/PHPStan + 覆盖率目标"
+globs:
+  - "**/*.test.*"
+  - "**/*.spec.*"
+  - "**/__tests__/**"
+  - "**/vitest.config.*"
+  - "**/playwright.config.*"
+  - "Case-Database-Backend/tests/**/*.php"
+  - "Case-Database-Backend/phpunit.xml"
+  - "Case-Database-Backend/phpstan.neon"
+alwaysApply: false
+---
+
+# Testing Standards
+
+> 前端测试（Vitest / Vue Test Utils / Playwright）的具体工作流和模板
+> 由 `skill-vue-testing.mdc` 自动注入，本文件不再重复。
+
+## 通用原则
+
+- 测试行为 (behavior)，不测试实现细节
+- 每个测试只验证一件事
+- 不为覆盖率写无意义测试
+- 测试是文档的一部分
+
+---
+
+## 后端测试 (PHP Hyperf)
+
+### 测试金字塔
+
+| 类型 | 占比 | 框架 | 目标 |
+|------|------|------|------|
+| Unit | 60% | PHPUnit | Service、Repository、工具类 |
+| Integration | 30% | PHPUnit + TestContainer | API 端点、数据库交互 |
+| Static | 持续 | PHPStan (Level max) | 类型安全、潜在 Bug |
+
+### 覆盖率目标
+
+- 行覆盖率 >= 75%
+- 分支覆盖率 >= 70%
+- Service 层 100%
+- 关键业务路径 100%
+
+### 运行命令
+
+```bash
+composer test              # PHPUnit 所有测试
+composer test:unit         # 仅单元测试
+composer test:feature      # 仅功能测试 (API)
+composer test:coverage     # PHPUnit + 覆盖率
+composer analyse           # PHPStan 静态分析
+```
+
+### AAA 模式
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Service;
+
+use App\Service\Production\OrderService;
+use PHPUnit\Framework\TestCase;
+
+class OrderServiceTest extends TestCase
+{
+    public function testCalculateDiscountReturnsZeroBelowThreshold(): void
+    {
+        // Arrange
+        $service = new OrderService();
+        $amount = 99.0;
+
+        // Act
+        $discount = $service->calculateDiscount($amount);
+
+        // Assert
+        $this->assertEquals(0.0, $discount);
+    }
+}
+```
+
+### PHPUnit 目录结构
+
+```
+tests/
+├── Unit/                    # 纯单元测试（不依赖框架）
+│   ├── Service/
+│   ├── Repository/
+│   └── Utils/
+├── Feature/                 # 功能测试（HTTP API 级别）
+│   ├── Auth/
+│   ├── Production/
+│   └── Permission/
+├── bootstrap.php
+└── phpunit.xml
+```
+
+### PHPStan 配置
+
+```neon
+# phpstan.neon
+parameters:
+    level: max
+    paths:
+        - app
+    excludePaths:
+        - app/Command
+    ignoreErrors: []
+```
+
+---
+
+## 新功能必须附带
+
+### 前端
+
+- [ ] Happy path 测试
+- [ ] 边界条件测试
+- [ ] 错误情况测试
+- [ ] 权限/授权测试 (如涉及 v-auth / v-roles)
+
+> 前端测试的具体写法见 `skill-vue-testing.mdc`
+
+### 后端
+
+- [ ] Service 单元测试
+- [ ] API 功能测试 (HTTP 请求/响应)
+- [ ] 权限/数据权限测试 (如涉及 DataScope)
+- [ ] 事务回滚测试 (如涉及数据库写操作)
+- [ ] PHPStan 通过 (`composer analyse`)
diff --git a/.cursor/rules/016-swoole.mdc b/.cursor/rules/016-swoole.mdc
new file mode 100644
index 0000000..054516d
--- /dev/null
+++ b/.cursor/rules/016-swoole.mdc
@@ -0,0 +1,232 @@
+---
+description: "Swoole 协程与高并发编程规范 — 协程安全/连接池/Worker配置/内存管理"
+globs:
+  - "Case-Database-Backend/app/**/*.php"
+  - "Case-Database-Backend/config/**/*.php"
+  - "Case-Database-Backend/bin/hyperf.php"
+alwaysApply: false
+---
+
+# ⚡ Swoole Coroutine & High-Concurrency Standards
+
+## 核心原则
+
+Swoole 是常驻内存的协程服务器，与传统 PHP-FPM 有本质区别。
+**每个请求共享 Worker 进程内存**，必须避免全局状态污染。
+
+## 协程安全规则
+
+### 绝对禁止
+
+```php
+// ❌ 全局变量存储请求数据（会被其他协程覆盖）
+global $currentUser;
+
+// ❌ 静态属性存储请求级数据
+class UserContext {
+    public static ?User $user = null; // WRONG: shared across coroutines
+}
+
+// ❌ 阻塞 I/O 函数（会阻塞整个 Worker）
+file_get_contents('https://api.example.com');  // use Guzzle coroutine client
+sleep(5);                                       // use Coroutine::sleep()
+flock($fp, LOCK_EX);                           // use Redis distributed lock
+
+// ❌ 非协程安全的全局单例
+$pdo = new PDO(...);  // use connection pool instead
+```
+
+### 正确做法
+
+```php
+// ✅ 使用 Hyperf Context 传递请求数据
+use Hyperf\Context\Context;
+
+// 在中间件中设置
+Context::set('current_user', $user);
+
+// 在任意位置读取（协程安全）
+$user = Context::get('current_user');
+
+// ✅ 协程安全的延时
+use Swoole\Coroutine;
+Coroutine::sleep(0.1);
+
+// ✅ 使用协程 HTTP 客户端
+use Hyperf\Guzzle\ClientFactory;
+$client = $this->clientFactory->create();
+$response = $client->get('https://api.example.com');
+```
+
+## 连接池配置
+
+### MySQL 连接池
+
+```php
+// config/autoload/databases.php
+'pool' => [
+    // 公式: min = Worker数, max = Worker数 * 2 ~ 4
+    'min_connections' => (int) env('DB_POOL_MIN', 5),
+    'max_connections' => (int) env('DB_POOL_MAX', 50),
+    'connect_timeout' => 10.0,  // seconds
+    'wait_timeout'    => 3.0,   // wait for available connection
+    'heartbeat'       => -1,    // disable heartbeat
+    'max_idle_time'   => 60,    // recycle idle connections
+],
+```
+
+### Redis 连接池
+
+```php
+// config/autoload/redis.php
+return [
+    'default' => [
+        'host'    => env('REDIS_HOST', 'localhost'),
+        'port'    => (int) env('REDIS_PORT', 6379),
+        'auth'    => env('REDIS_AUTH', null),
+        'db'      => (int) env('REDIS_DB', 0),
+        'pool'    => [
+            'min_connections' => 5,
+            'max_connections' => 30,
+            'connect_timeout' => 10.0,
+            'wait_timeout'    => 3.0,
+            'heartbeat'       => -1,
+            'max_idle_time'   => 60,
+        ],
+    ],
+];
+```
+
+### 连接池容量计算
+
+```
+单 Worker 最大协程数: max_coroutine (default: 100000)
+实际并发协程数 ≈ QPS * avg_response_time
+
+DB Pool Max = ceil(concurrent_coroutines * db_query_ratio)
+Redis Pool Max = ceil(concurrent_coroutines * redis_query_ratio)
+
+示例 (百万级):
+- 4 Worker, 每 Worker 1000 并发协程
+- DB 查询占比 60% → DB Pool Max = 1000 * 0.6 = 600 (per worker)
+- 实际受 MySQL max_connections 限制，需配合读写分离
+```
+
+## Worker 进程配置
+
+```php
+// config/autoload/server.php
+'settings' => [
+    'worker_num'            => (int) env('SWOOLE_WORKER_NUM', swoole_cpu_num() * 2),
+    'task_worker_num'       => (int) env('SWOOLE_TASK_WORKER_NUM', 4),
+    'max_request'           => 10000,      // restart worker after N requests (prevent memory leak)
+    'max_coroutine'         => 100000,     // max coroutines per worker
+    'enable_coroutine'      => true,
+    'open_tcp_nodelay'      => true,
+    'socket_buffer_size'    => 3 * 1024 * 1024,
+    'buffer_output_size'    => 3 * 1024 * 1024,
+    'package_max_length'    => 5 * 1024 * 1024,
+    'heartbeat_check_interval' => 60,
+    'heartbeat_idle_time'      => 120,
+],
+```
+
+## 协程并发控制
+
+```php
+use Hyperf\Coroutine\Parallel;
+
+// ✅ 并行执行多个无依赖的 I/O 操作
+$parallel = new Parallel(10); // max concurrency = 10
+
+$parallel->add(function () {
+    return $this->orderService->getStatistics($orderId);
+});
+
+$parallel->add(function () {
+    return $this->paymentService->getPayments($orderId);
+});
+
+$parallel->add(function () {
+    return $this->deliveryService->getDeliveries($orderId);
+});
+
+[$stats, $payments, $deliveries] = $parallel->wait();
+```
+
+```php
+use Hyperf\Coroutine\WaitGroup;
+
+// ✅ WaitGroup: wait for all coroutines to complete
+$wg = new WaitGroup();
+$results = [];
+
+$wg->add(1);
+go(function () use ($wg, &$results) {
+    $results['users'] = $this->userService->getOnlineCount();
+    $wg->done();
+});
+
+$wg->add(1);
+go(function () use ($wg, &$results) {
+    $results['orders'] = $this->orderService->getTodayCount();
+    $wg->done();
+});
+
+$wg->wait(5.0); // timeout 5s
+```
+
+## 内存管理
+
+- `max_request = 10000`: Worker 处理 N 个请求后自动重启，防止内存泄漏
+- 避免在全局/静态变量中累积数据
+- 大数组处理完后手动 `unset()`
+- 使用 `memory_get_usage()` 监控内存
+- 对象生命周期与请求绑定，不跨请求持有引用
+
+```php
+// ✅ 大数据分批处理
+ProductionOrder::query()
+    ->where('status', 'pending')
+    ->chunk(500, function ($orders) {
+        foreach ($orders as $order) {
+            $this->processOrder($order);
+        }
+        // chunk 结束后自动释放内存
+    });
+```
+
+## 定时任务
+
+```php
+use Hyperf\Crontab\Annotation\Crontab;
+
+#[Crontab(
+    name: 'CheckPaymentTimeout',
+    rule: '*/5 * * * *',
+    memo: 'Check payment timeout orders',
+    singleton: true,        // prevent duplicate execution
+    onOneServer: true,      // only run on one server in cluster
+    mutexPool: 'default',
+)]
+class CheckPaymentTimeoutTask
+{
+    public function execute(): void
+    {
+        // batch processing with chunk
+    }
+}
+```
+
+## 性能监控
+
+```php
+// Swoole Server status
+$server = $this->container->get(ServerInterface::class);
+$stats = $server->stats();
+// Returns: start_time, connection_num, request_count, worker_request_count, coroutine_num
+
+// Redis monitor
+$redis = $this->container->get(RedisFactory::class)->get('default');
+$info = $redis->info();
+```
diff --git a/.cursor/rules/017-architecture.mdc b/.cursor/rules/017-architecture.mdc
new file mode 100644
index 0000000..e3cf063
--- /dev/null
+++ b/.cursor/rules/017-architecture.mdc
@@ -0,0 +1,45 @@
+---
+description: >
+  百万级并发架构设计规范。当讨论水平扩展、限流降级、熔断、
+  高可用架构、容量规划或发布策略时激活。
+alwaysApply: false
+---
+
+# 🏗️ Million-Level Concurrency Architecture Standards (Core)
+
+## 架构目标
+
+- 无状态应用，可水平扩展
+- 高并发下保持可用与可观测
+- 峰值流量具备限流、降级、熔断能力
+
+## 核心设计原则
+
+- 入口层：Nginx/网关统一限流与基础防护
+- 应用层：Hyperf 服务无状态，异步化非关键链路
+- 数据层：MySQL 主从 + Redis 缓存 + 队列削峰
+- 可靠性：幂等、重试、超时、隔离舱、降级兜底
+
+## 关键实践
+
+- 热点读走缓存，写后失效或异步刷新
+- 长耗时任务走队列/事件，避免阻塞请求线程
+- 对外依赖必须有 timeout + retry + fallback
+- 关键业务链路必须可追踪（日志/指标/告警）
+
+## 容量与发布
+
+- 扩容前先压测，确认瓶颈位置
+- 灰度发布与回滚路径必须预案化
+- 变更优先小步快跑，减少单次风险面
+
+## 验证清单
+
+- [ ] 高峰流量下核心接口可用
+- [ ] 限流/降级策略可触发且可恢复
+- [ ] 异步任务可观测且可重试
+- [ ] 发布失败可快速回滚
+
+## Tier 3 深度参考
+
+- `.cursor/rules/references/017-architecture-deep.md` — 完整并发架构规范与拓扑示例
diff --git a/.cursor/rules/018-responsive.mdc b/.cursor/rules/018-responsive.mdc
new file mode 100644
index 0000000..4d68f64
--- /dev/null
+++ b/.cursor/rules/018-responsive.mdc
@@ -0,0 +1,47 @@
+---
+description: "响应式与多端适配规范 — 断点策略/触摸优化/设备测试矩阵。管理端含 Element Plus 适配，用户端纯 Tailwind + Headless UI"
+globs:
+  - "**/*.vue"
+  - "**/*.css"
+  - "**/*.scss"
+alwaysApply: false
+---
+
+# 📱 Responsive Design & Multi-Device Standards (Core)
+
+## 设计原则
+
+- Mobile First：先实现手机，再逐级增强到平板/桌面
+- 内容优先：保证主流程在小屏可达、可读、可操作
+- 组件一致：Tailwind 断点策略统一（管理端同时适配 Element Plus 组件）
+
+## 断点最小约定
+
+- `base`：手机竖屏
+- `sm/md`：手机横屏与平板
+- `lg/xl/2xl`：桌面与大屏
+- 禁止桌面优先 `max-*` 反推写法作为默认策略
+
+## 布局与交互约束
+
+- 列表/卡片/表单在窄屏自动降级布局
+- 触摸目标建议 ≥ 44x44
+- 弹层与抽屉优先适配移动端交互
+- 文本与关键按钮不得被遮挡或截断
+
+## 测试基线
+
+- 至少验证 3 档视口：手机 / 平板 / 桌面
+- 验证横竖屏切换、滚动容器、固定定位元素
+- 关键路径（登录、检索、提交）全端可完成
+
+## 验证清单
+
+- [ ] 小屏主流程可完成
+- [ ] 关键控件触摸可达
+- [ ] 无明显布局溢出/重叠
+- [ ] 核心页面通过多断点截图比对
+
+## Tier 3 深度参考
+
+- `.cursor/rules/references/018-responsive-deep.md` — 完整响应式规范与示例
diff --git a/.cursor/rules/019-modular.mdc b/.cursor/rules/019-modular.mdc
new file mode 100644
index 0000000..c095f4f
--- /dev/null
+++ b/.cursor/rules/019-modular.mdc
@@ -0,0 +1,41 @@
+---
+description: >
+  模块化架构规范。当新建模块、讨论架构设计、模块划分、
+  依赖方向或 DDD 边界时激活。含模块通信和文件拆分最佳实践。
+alwaysApply: false
+---
+
+# 🧩 Modular Architecture Standards (Core)
+
+## 架构边界
+
+- 模块按业务能力划分，避免按技术层随意切分
+- 模块间通过公开接口通信，禁止引用他模块内部实现
+- 依赖方向单向：UI → Service → Repository → Model
+
+## 拆分与聚合
+
+- 单文件职责单一，超过复杂度阈值立即拆分
+- 公共能力抽到 Case-Database-Frontend-shared/core，业务逻辑保留在业务模块
+- 新增目录优先复用既有模式，避免“再发明一套结构”
+
+## 反模式禁止
+
+- 循环依赖
+- 横向跨层调用（Controller 直连 DB）
+- 超大文件混合业务/状态/展示逻辑
+
+## 评审基线
+
+- 每次改动需回答：边界是否更清晰？耦合是否降低？
+- 新增接口必须说明输入/输出和错误语义
+
+## 验证清单
+
+- [ ] 无循环依赖
+- [ ] 模块边界清晰，可替换性提升
+- [ ] 公共能力与业务能力分层明确
+
+## Tier 3 深度参考
+
+- `.cursor/rules/references/019-modular-deep.md` — 完整模块化规范与案例
diff --git a/.cursor/rules/020-git.mdc b/.cursor/rules/020-git.mdc
new file mode 100644
index 0000000..96f3631
--- /dev/null
+++ b/.cursor/rules/020-git.mdc
@@ -0,0 +1,43 @@
+---
+description: "Git 与版本控制规范 — 分支/提交/PR 策略"
+alwaysApply: false
+---
+
+# 📦 Git Standards
+
+## 分支命名
+
+```
+feature/TICKET-短描述
+bugfix/TICKET-短描述
+hotfix/TICKET-短描述
+chore/短描述
+```
+
+## Commit 规范 (Conventional Commits)
+
+```
+type(scope): description
+
+feat(auth): add OAuth login with Google
+fix(api): handle null response from payment gateway
+refactor(db): optimize user query with index
+test(auth): add unit tests for JWT validation
+docs(readme): update setup instructions
+chore(deps): upgrade next to 15.1
+```
+
+Types: `feat` `fix` `refactor` `test` `docs` `chore` `style` `perf` `ci` `build`
+
+## PR 规范
+
+- 标题符合 Conventional Commits
+- 描述包含: 改了什么 / 为什么改 / 如何测试
+- 单个 PR 不超过 400 行变更
+- 必须有关联 Issue/Ticket
+
+## Git 操作安全
+
+- commit 前运行 `npm run lint`（前端）或 `composer analyse`（后端）
+- 禁止 force push 到 main/master/develop
+- 合并冲突需人工介入
diff --git a/.cursor/rules/021-deployment.mdc b/.cursor/rules/021-deployment.mdc
new file mode 100644
index 0000000..0cee3bf
--- /dev/null
+++ b/.cursor/rules/021-deployment.mdc
@@ -0,0 +1,106 @@
+---
+description: "部署与 DevOps 规范 — Docker Compose/CI-CD/环境管理/PHP+Vue双栈"
+globs:
+  - "Case-Database-Backend/docker-compose*"
+  - "Case-Database-Backend/Dockerfile*"
+  - ".github/workflows/**"
+  - ".env*"
+alwaysApply: false
+---
+
+# 🚢 Deployment Standards (Hyperf + Vue 3)
+
+参考文档: @docs/runbooks/deployment.md
+
+## 环境定义
+
+| 环境 | 用途 | 触发 | 部署方式 |
+|------|------|------|---------|
+| Development | 本地开发 | `docker-compose up` | Docker Compose |
+| Testing | 自动化测试 | PR 创建 | CI Pipeline |
+| Staging | 预发布验证 | merge to `develop` | Docker Compose / K8s |
+| Production | 正式环境 | merge to `main` | Docker Compose / K8s |
+
+## 本地开发
+
+```bash
+# 一键启动 (Docker Compose)
+docker-compose up -d
+
+# 后端独立运行
+cd Case-Database-Backend && php bin/hyperf.php start
+
+# 前端独立运行
+cd Case-Database-Frontend-user && npm run dev
+cd ../Case-Database-Frontend-admin && npm run dev
+
+# 数据库迁移
+cd Case-Database-Backend && php bin/hyperf.php migrate
+```
+
+## Docker 规范
+
+- 使用多阶段构建减小镜像
+- 非 root 用户运行 (安全)
+- 固定依赖版本 (不用 `latest` 标签)
+- 包含 `.dockerignore`
+- 健康检查 (`HEALTHCHECK`)
+- Swoole 进程不需要额外的 Supervisor
+
+## CI/CD 流水线
+
+```
+Push
+  ├─→ Frontend Job: npm ci → lint → test → build
+  └─→ Backend Job:  composer install → phpstan → phpunit
+  │
+  ├─→ Security Audit (PR only)
+  │
+  └─→ Deploy
+        ├─→ develop → Staging
+        └─→ main → Production
+```
+
+参考配置: `.github/workflows/ci.yml`
+
+## 环境变量管理
+
+| 位置 | 用途 |
+|------|------|
+| `.env` (本地) | 开发环境，已 gitignore |
+| `.env.example` | 变量模板，提交到 Git |
+| Docker Compose env | 容器编排环境变量 |
+| K8s Secret / ConfigMap | 生产环境密钥管理 |
+
+**规则**:
+- 所有密钥通过环境变量注入，禁止硬编码
+- 定期轮换密钥
+- 生产环境使用加密存储 (K8s Secret / Vault)
+
+## 部署检查清单
+
+### 部署前
+- [ ] 后端测试通过 (`composer test`)
+- [ ] 前端构建成功 (`npm run build`)
+- [ ] 数据库迁移已准备
+- [ ] 环境变量已配置
+
+### 部署后
+- [ ] 健康检查通过 (`/admin/health`)
+- [ ] 监控无异常
+- [ ] 数据库迁移成功
+- [ ] WebSocket 连接正常
+- [ ] 队列消费进程运行中
+
+## 回滚策略
+
+```bash
+# 代码回滚
+git revert HEAD && git push origin main
+
+# 数据库回滚
+php bin/hyperf.php migrate:rollback --step=1
+
+# Docker 回滚到上一个镜像版本
+docker-compose pull && docker-compose up -d
+```
diff --git a/.cursor/rules/022-performance.mdc b/.cursor/rules/022-performance.mdc
new file mode 100644
index 0000000..9c77388
--- /dev/null
+++ b/.cursor/rules/022-performance.mdc
@@ -0,0 +1,215 @@
+---
+description: >
+  性能优化规范与审计流程。当用户讨论性能优化、报告页面慢、加载卡、
+  包体积大、Swoole 调优、数据库查询优化、缓存策略或 Core Web Vitals 时激活。
+alwaysApply: false
+---
+
+# Performance Standards & Audit
+
+> 本文件同时包含性能**诊断流程**和**编码规范**。
+> 完整审计工作流见：Read `.cursor/skills/performance-audit/SKILL.md`
+
+## 诊断流程（用户报告性能问题时先走这里）
+
+### 1. 性能基线
+
+收集当前数据（前端 `npm run build` + `du -sh dist/`，后端路由数量）。
+
+### 2. 四维度审计
+
+**前端渲染** — 不必要重渲染、大列表虚拟化、图片压缩、按需导入
+**网络请求** — 瀑布式请求、Redis 缓存、Axios 拦截、Nginx 缓存
+**打包体积** — 大依赖、dynamic import、tree-shaking、barrel exports
+**数据库查询** — N+1、缺少索引、未限制字段、未分页
+
+### 3. 输出优化建议
+
+按影响力排序，每个建议包含：预期收益 + 实施难度 + 具体代码。
+
+### 诊断验证
+
+- [ ] 优化前后有可量化对比
+- [ ] 未引入功能回归
+- [ ] Core Web Vitals 达标
+
+---
+
+## 性能指标目标
+
+| 指标 | 目标 | 说明 |
+|------|------|------|
+| FCP | < 1.5s | 首次内容绘制 |
+| LCP | < 2.5s | 最大内容绘制 |
+| INP | < 200ms | 交互到下一帧 |
+| API P95 | < 200ms | 后端接口响应 |
+| API P99 | < 500ms | 后端接口响应（长尾） |
+| DB Query | < 50ms | 单条数据库查询 |
+| Redis | < 5ms | 缓存操作 |
+
+---
+
+## 前端性能
+
+### Vite 构建优化
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  build: {
+    target: 'es2015',
+    minify: 'terser',
+    terserOptions: {
+      compress: {
+        drop_console: true,
+        drop_debugger: true,
+      },
+    },
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          'vue-vendor': ['vue', 'vue-router', 'pinia'],
+          // 仅管理端：'element-plus': ['element-plus'],
+          'echarts': ['echarts'],
+        },
+      },
+    },
+    chunkSizeWarningLimit: 2000,
+  },
+})
+```
+
+### 加载优化
+
+- 路由懒加载: `() => import('@/views/module/page/index.vue')`
+- 管理端 Element Plus 按需导入: `unplugin-vue-components` + `unplugin-auto-import`（用户端不使用 Element Plus）
+- 大列表虚拟化: `@tanstack/vue-virtual`
+- 组件懒加载: `defineAsyncComponent()`
+- 页面缓存: `<keep-alive :include="cachedViews">` 配合 worktab Store
+
+### 资源优化
+
+- 图片: WebP 格式 + 压缩 + CDN
+- 图标: 管理端 `@element-plus/icons-vue` 按需导入；用户端使用 `lucide-vue-next`
+- 字体: `font-display: swap` 避免阻塞
+- Gzip: Nginx 开启 gzip 压缩
+
+### 前端缓存策略
+
+| 数据 | 方式 | TTL |
+|------|------|-----|
+| 产品列表 | Pinia + localStorage | 5 分钟 |
+| 字典数据 | Pinia + localStorage | 1 小时 |
+| 用户配置 | Pinia persist | 持久 |
+| 路由/菜单 | Pinia persist | 持久 |
+| 接口响应 | 不缓存（后端 Redis） | — |
+
+---
+
+## 后端性能
+
+### Swoole 调优
+
+```php
+// config/autoload/server.php
+'settings' => [
+    'worker_num'       => swoole_cpu_num() * 2,
+    'task_worker_num'  => 4,
+    'max_request'      => 10000,
+    'max_coroutine'    => 100000,
+    'enable_coroutine' => true,
+    'open_tcp_nodelay' => true,
+    'socket_buffer_size'   => 3 * 1024 * 1024,
+    'buffer_output_size'   => 3 * 1024 * 1024,
+    'package_max_length'   => 5 * 1024 * 1024,
+],
+```
+
+### 数据库查询优化
+
+| 规则 | 正确做法 | 反模式 |
+|------|---------|--------|
+| 避免 N+1 | `with(['customer', 'subOrders'])` | 循环中查询关联 |
+| 明确列名 | `select('id', 'order_no', 'status')` | `SELECT *` |
+| 分页 | 游标分页 `WHERE id > ? LIMIT ?` | `OFFSET` 深分页 |
+| 批量操作 | `insert([...])` / `chunk(500)` | 循环单条 SQL |
+| 索引 | 复合索引遵循最左前缀 | 过多单列索引 |
+| 大表 COUNT | 缓存计数 / 近似值 | `COUNT(*)` 全表 |
+
+### 缓存优化
+
+```php
+// Cache-Aside 模式 + TTL 抖动
+$data = $cache->withCache("order:{$id}", 300, fn() => Order::find($id));
+
+// 缓存失效：写操作后立即清除
+$cache->invalidate("order:{$id}");
+$cache->invalidatePattern('orders:list:*');
+```
+
+### 协程并发
+
+```php
+// 并行无依赖 I/O 操作
+$parallel = new Parallel(10);
+$parallel->add(fn() => $this->orderService->getStatistics($id));
+$parallel->add(fn() => $this->paymentService->getPayments($id));
+[$stats, $payments] = $parallel->wait();
+```
+
+---
+
+## 服务器性能
+
+### Nginx 优化
+
+```nginx
+# Gzip 压缩
+gzip on;
+gzip_min_length 1k;
+gzip_comp_level 6;
+gzip_types text/plain text/css application/json application/typescript image/svg+xml;
+
+# 静态资源长期缓存（Vite 产物带 hash）
+location /assets/ {
+    expires 1y;
+    add_header Cache-Control "public, immutable";
+    access_log off;
+}
+
+# HTTP/2
+listen 443 ssl http2;
+```
+
+### 连接池调优
+
+```php
+// MySQL 连接池
+'pool' => [
+    'min_connections' => 5,
+    'max_connections' => 50,
+    'connect_timeout' => 10.0,
+    'wait_timeout'    => 3.0,
+    'max_idle_time'   => 60,
+],
+
+// Redis 连接池
+'pool' => [
+    'min_connections' => 5,
+    'max_connections' => 30,
+    'connect_timeout' => 10.0,
+    'wait_timeout'    => 3.0,
+],
+```
+
+---
+
+## 禁止事项
+
+- 前端同步阻塞主线程的操作
+- 未压缩的大图片 (> 200KB)
+- 无限滚动不做虚拟化
+- Swoole Worker 中执行阻塞 I/O (`file_get_contents`, `sleep`)
+- 全表扫描无 WHERE 条件
+- 事务内包含远程调用
+- 单事务操作 > 1000 行
diff --git a/.cursor/rules/023-accessibility.mdc b/.cursor/rules/023-accessibility.mdc
new file mode 100644
index 0000000..6387b98
--- /dev/null
+++ b/.cursor/rules/023-accessibility.mdc
@@ -0,0 +1,40 @@
+---
+description: "无障碍规范 — WCAG AA/语义化/键盘导航/ARIA/Vue 3 无障碍实践"
+globs:
+  - "**/*.vue"
+  - "**/*.html"
+alwaysApply: false
+---
+
+# ♿ Accessibility (A11y) — WCAG AA Standards (Core)
+
+## WCAG AA 最小基线
+
+- 可感知：文本对比度满足 AA；图片有替代文本
+- 可操作：全部关键功能可键盘完成；无键盘陷阱
+- 可理解：错误提示清晰、可定位、可恢复
+- 健壮性：语义化 HTML 优先，ARIA 正确使用
+
+## Vue 实践约束
+
+- 表单控件必须有关联 label/description
+- 弹窗/抽屉管理焦点进入与返回
+- 自定义交互组件提供键盘等价操作
+- 状态变化（成功/失败/加载）需可被辅助技术感知
+
+## 检查方式
+
+- 静态：eslint-plugin-vuejs-accessibility / 基础规则
+- 自动：Lighthouse / axe
+- 手动：Tab 顺序、屏幕阅读器关键路径
+
+## 验证清单
+
+- [ ] 关键页面通过键盘操作完成主流程
+- [ ] 表单错误可读且可聚焦
+- [ ] 颜色对比度满足 AA
+- [ ] 对话框焦点管理正确
+
+## Tier 3 深度参考
+
+- `.cursor/rules/references/023-accessibility-deep.md` — 完整 A11y 规范与代码示例
diff --git a/.cursor/rules/024-monitoring.mdc b/.cursor/rules/024-monitoring.mdc
new file mode 100644
index 0000000..2eca1dd
--- /dev/null
+++ b/.cursor/rules/024-monitoring.mdc
@@ -0,0 +1,49 @@
+---
+description: "日志与错误监控规范 — Hyperf Monolog/Vue 3 错误处理/Swoole 监控/告警策略"
+globs:
+  - "Case-Database-Backend/app/**/*.php"
+  - "Case-Database-Backend/config/autoload/logger.php"
+  - "Case-Database-Frontend-user/src/**/*.ts"
+  - "Case-Database-Frontend-user/src/**/*.vue"
+  - "Case-Database-Frontend-admin/src/**/*.ts"
+  - "Case-Database-Frontend-admin/src/**/*.vue"
+alwaysApply: false
+---
+
+# 📊 Logging & Error Monitoring Standards (Core)
+
+## 日志基线
+
+- 统一结构化日志（JSON）
+- 日志级别分层：debug/info/warn/error
+- 关键字段统一：trace_id、user_id、module、action、latency
+- 严禁记录密钥、密码、完整 token
+
+## 错误处理基线
+
+- 前端：全局错误边界 + 请求错误统一处理
+- 后端：统一异常映射，区分业务异常与系统异常
+- 所有 error 需带上下文，便于定位与追踪
+
+## 指标与告警
+
+- 最小指标：QPS、错误率、P95/P99 延迟、队列堆积
+- 告警分级：P1（立即处理）/P2（当日处理）/P3（观察）
+- 告警必须可行动：包含服务、时间窗、建议操作
+
+## 运维可观测性
+
+- 关键链路可追踪（trace/span）
+- 部署后监控窗口至少覆盖 30 分钟
+- 事故复盘沉淀到 runbook
+
+## 验证清单
+
+- [ ] 日志结构字段统一
+- [ ] 错误有分类与可检索上下文
+- [ ] 核心指标可视化并配置告警
+- [ ] 发布后监控与回滚流程可执行
+
+## Tier 3 深度参考
+
+- `.cursor/rules/references/024-monitoring-deep.md` — 完整监控规范与配置示例
diff --git a/.cursor/rules/025-licensing.mdc b/.cursor/rules/025-licensing.mdc
new file mode 100644
index 0000000..ddd14ec
--- /dev/null
+++ b/.cursor/rules/025-licensing.mdc
@@ -0,0 +1,180 @@
+---
+description: "版权与许可合规 — 确保所有依赖、素材、字体均为开源可商用，防止法律纠纷"
+alwaysApply: false
+---
+
+# ⚖️ Licensing & Copyright Compliance
+
+> **核心原则**：项目中使用的所有第三方代码、组件、字体、图标、图片和素材，
+> 必须为**开源、免费、可商用**的许可证，不得引入任何可能导致法律纠纷的资源。
+
+## 许可证白名单
+
+以下许可证允许在商业项目中使用：
+
+```
+✅ 允许使用:
+  MIT / ISC / 0BSD / BSD-2-Clause / BSD-3-Clause
+  Apache-2.0 / Unlicense / WTFPL / Zlib / PostgreSQL
+  CC0-1.0 (公共领域) / CC-BY-4.0 (署名即可)
+  SIL OFL 1.1 (字体专用) / BlueOak-1.0.0
+  MPL-2.0 (仅修改的文件需开源，不传染整个项目)
+```
+
+## 许可证黑名单
+
+以下许可证**禁止使用**，因其传染性或商用限制：
+
+```
+🚫 禁止使用:
+  GPL-2.0 / GPL-3.0 — 强传染，要求整个项目开源
+  AGPL-3.0 — 网络使用也触发传染
+  SSPL — MongoDB 的限制性许可
+  BSL (Business Source License) — 商用限制
+  CC-BY-NC-* — 禁止商用
+  CC-BY-SA-* — 用于代码时有传染性
+  任何标注 "Non-Commercial" / "Personal Use Only" 的许可
+  任何标注 "Proprietary" / "All Rights Reserved" 的资源
+```
+
+## 灰名单 — 需要确认
+
+```
+⚠️ 需人工确认:
+  LGPL-2.1 / LGPL-3.0 — 动态链接通常可以，静态链接有传染风险
+  Artistic-2.0 — 条款复杂，需逐案评估
+  EPL-2.0 — 弱传染，需评估使用方式
+  无许可证的开源项目 — 默认 All Rights Reserved，禁止使用
+```
+
+**遇到灰名单许可证时**：停止安装，向用户说明风险，等待确认。
+
+## NPM / Composer 依赖
+
+安装任何新依赖前，必须检查许可证：
+
+```bash
+# NPM: 查看包的许可证
+npm info <package-name> license
+
+# Composer: 查看包的许可证
+composer show <vendor/package> | grep -i license
+```
+
+**安装前检查清单**：
+1. 确认许可证在白名单中
+2. 如果许可证在灰名单中 → 停止并告知用户
+3. 如果许可证在黑名单中 → 拒绝安装并推荐替代方案
+4. 如果没有许可证 → 视为 All Rights Reserved，拒绝使用
+
+**推荐开源替代**：
+
+| 避免使用 | 推荐替代 | 许可证 |
+|---------|---------|--------|
+| Moment.ts (许可证安全但已弃用) | Day.ts / date-fns | MIT |
+| Font Awesome Pro | Lucide / Heroicons / Phosphor | ISC / MIT |
+| ag-Grid Enterprise | AG Grid Community / TanStack Table | MIT |
+| Highcharts (商用付费) | ECharts / Chart.ts / Recharts | Apache-2.0 / MIT |
+| Ant Design Pro (部分模板付费) | Element Plus / Naive UI | MIT |
+| Quill 某些插件 (付费) | Tiptap / Editor.ts | MIT |
+
+## 字体规范
+
+**允许使用的字体来源**：
+
+| 来源 | 许可证 | 示例 |
+|------|--------|------|
+| Google Fonts | SIL OFL 1.1 | Inter, Noto Sans SC, Roboto |
+| Adobe Source 系列 | SIL OFL 1.1 | Source Han Sans (思源黑体) |
+| 阿里巴巴普惠体 | 免费可商用 | Alibaba PuHuiTi |
+| OPPO Sans | 免费可商用（需注册） | OPPO Sans |
+| 鸿蒙字体 | 免费可商用 | HarmonyOS Sans |
+
+```
+🚫 禁止使用:
+  微软雅黑 (Windows 自带≠可商用) / 宋体 (方正版权)
+  苹方 (仅限 Apple 设备内置使用)
+  方正系列字体 (需购买商用授权)
+  汉仪系列字体 (需购买商用授权)
+  造字工房系列 (需购买商用授权)
+  任何从网络下载的无明确授权字体
+```
+
+**中文字体推荐方案**：
+- 正文：`"Noto Sans SC", "Source Han Sans SC", "Alibaba PuHuiTi", system-ui, sans-serif`
+- 代码：`"JetBrains Mono", "Fira Code", "Source Code Pro", monospace`
+
+## 图标规范
+
+**允许使用的图标库**：
+
+| 库 | 许可证 | 适用场景 |
+|----|--------|---------|
+| Element Plus Icons | MIT | 与 Element Plus 配套 |
+| Lucide | ISC | 通用线性图标 |
+| Heroicons | MIT | Tailwind 生态 |
+| Phosphor Icons | MIT | 多粗细变体 |
+| Material Design Icons | Apache-2.0 | Google 风格 |
+| Tabler Icons | MIT | 线性图标 |
+| Iconify (聚合平台) | 取决于具体图标集 | 需逐集检查许可证 |
+
+```
+🚫 禁止使用:
+  Font Awesome Pro (付费版)
+  Flaticon (免费版需署名，部分禁止商用)
+  IconFinder (大部分需购买)
+  Iconfont (阿里) — 个人上传的图标版权不可控
+  任何从设计网站截图或扒取的图标
+```
+
+## 图片与媒体素材
+
+**允许使用的图片来源**：
+
+| 来源 | 许可证 | 注意事项 |
+|------|--------|---------|
+| Unsplash | Unsplash License | 免费商用，无需署名 |
+| Pexels | Pexels License | 免费商用，无需署名 |
+| Pixabay | Pixabay License | 免费商用，部分需检查 |
+| 自行创建/AI 生成 | 自有版权 | 确认 AI 工具的商用条款 |
+| unDraw | MIT | 开源插画 |
+| Storyset | Freepik 免费协议 | 需署名 |
+
+```
+🚫 禁止使用:
+  Google 图片搜索直接下载 (版权不明)
+  百度图片搜索直接下载
+  Getty Images / Shutterstock / 视觉中国 (付费)
+  Pinterest / Dribbble 上的作品 (他人版权)
+  任何来源不明的图片
+  竞品产品的截图用于商业用途
+```
+
+**AI 生成图片注意**：使用 AI 生成图片时，确认所用工具的商用条款允许商业使用。
+
+## 代码引用规范
+
+从外部来源引用代码片段时：
+
+1. **StackOverflow** — CC-BY-SA 4.0 许可，引用需署名，大段引用有传染风险，建议理解后重写
+2. **GitHub 开源项目** — 遵循项目许可证，MIT/Apache 可直接使用
+3. **技术博客** — 版权归作者，参考思路后自行实现，不要直接复制
+4. **AI 生成的代码** — 通常归使用者，但需确认工具的 ToS
+
+## 违规处理
+
+当检测到以下情况时，**立即停止并警告用户**：
+
+1. 即将安装黑名单许可证的依赖
+2. 代码中引用了版权受限的字体名称
+3. 推荐了付费/非商用的素材来源
+4. 从未知来源复制大段代码
+
+警告格式：
+
+```
+⚠️ 版权风险: [描述问题]
+许可证: [具体许可证]
+风险: [可能的法律后果]
+替代方案: [推荐的开源可商用替代]
+```
diff --git a/.cursor/rules/026-secure-coding.mdc b/.cursor/rules/026-secure-coding.mdc
new file mode 100644
index 0000000..1598f85
--- /dev/null
+++ b/.cursor/rules/026-secure-coding.mdc
@@ -0,0 +1,44 @@
+---
+description: >
+  安全编码规范 — 开发时主动安全实践（Secure by Default）。
+  基于 Project CodeGuard 框架，覆盖注入防护、加密算法、访问控制、会话安全、
+  客户端安全和文件上传。编写 PHP 或 TypeScript/Vue 代码时自动应用。
+globs:
+  - "**/*.php"
+  - "**/*.ts"
+  - "**/*.vue"
+alwaysApply: false
+---
+
+# 🔐 Secure Coding Standards (Core)
+
+## 总原则
+
+- 外部输入默认不可信
+- 安全优先于便捷（Secure by Default）
+- 敏感操作必须有鉴权、审计与告警
+
+## 必须遵守
+
+- 禁用弱算法：MD5/SHA1/DES/3DES/RC4/AES-ECB
+- 注入防护：SQL/命令/模板注入全面参数化与白名单
+- 访问控制：每个资源接口都做所有权/权限校验
+- 会话安全：HttpOnly + Secure + SameSite，避免 token 泄漏
+- 文件上传：校验扩展名 + MIME + magic bytes，隔离存储
+
+## 前后端协同
+
+- 前端不信任本地状态作为权限依据
+- 后端做最终授权裁决
+- 错误提示不暴露内部实现细节
+
+## 验证清单
+
+- [ ] 关键接口已做输入验证与授权
+- [ ] 无禁用算法与危险函数
+- [ ] 会话与凭证存储符合安全基线
+- [ ] 上传与下载链路具备安全防护
+
+## Tier 3 深度参考
+
+- `.cursor/rules/references/026-secure-coding-deep.md` — 完整安全编码规范与示例
diff --git a/.cursor/rules/030-subagents.mdc b/.cursor/rules/030-subagents.mdc
new file mode 100644
index 0000000..d196810
--- /dev/null
+++ b/.cursor/rules/030-subagents.mdc
@@ -0,0 +1,30 @@
+---
+description: >
+  Subagent 编排系统。当需要委托子任务给独立 Agent 并行执行时使用。
+  包含 repo-scout、test-runner、security-sentinel 三个模板。
+alwaysApply: false
+---
+
+# Subagents 系统
+
+Subagents 是本项目定义的使用约定，通过 Task 工具的 subagent_type 参数执行，
+实现任务隔离和并行处理。
+
+## 调用方式
+
+先 Read 对应的 `.cursor/agents/*.md` 文件，将完整内容作为 `prompt` 传递给 Task 工具。
+
+## 可用 Subagents
+
+| Subagent | 职责 | 模式 |
+|----------|------|------|
+| **repo-scout** | 代码库探索、文件定位 | 只读 |
+| **test-runner** | 运行测试、报告结果 | 后台 |
+| **security-sentinel** | 安全扫描、漏洞检测 | 只读 |
+
+## 使用模式
+
+- **清洁上下文**：每个 Subagent 独立上下文，不污染主对话
+- **并行执行**：多个 Subagent 可同时运行
+- **链式编排**：Scout → Implement → Verify
+- **扇出模式**：同一任务拆分给多个 Subagent 并行
diff --git a/.cursor/rules/033-refactoring.mdc b/.cursor/rules/033-refactoring.mdc
new file mode 100644
index 0000000..b30942a
--- /dev/null
+++ b/.cursor/rules/033-refactoring.mdc
@@ -0,0 +1,64 @@
+---
+description: >
+  安全重构技能。当用户要求重构代码、清理技术债、优化代码结构
+  或简化复杂逻辑时激活。行为不变前提下改善内部结构。
+alwaysApply: false
+---
+
+# Refactoring Workflow
+
+> 本文件是精简执行摘要。完整流程、模板和深度参考见：
+> Read `.cursor/skills/refactoring/SKILL.md`
+
+依赖技能：`vue-testing`（Cursor 已通过 `skill-vue-testing` 规则自动加载）
+
+## 黄金规则
+
+> 重构 = 不改变外部行为的前提下改善内部结构。
+> 每一步都要小到"显然正确"，每一步之后测试必须全部通过。
+> 如果测试不足，先补测试再重构。
+
+## 执行流程
+
+### 1. 评估现状
+
+1. 读取目标代码，识别"代码坏味道"
+2. 运行现有测试确认基线：`npm test -- --related`
+3. 如果测试覆盖不足，**先补充测试**
+
+### 2. 制定重构计划
+
+| 坏味道 | 重构手法 | 风险 |
+|--------|---------|------|
+| 函数过长（>50行） | Extract Function | 低 |
+| 重复代码 | Extract + Consolidate | 低 |
+| 过长参数列表 | Introduce Parameter Object | 低 |
+| Switch/If 过多 | Replace with Polymorphism | 中 |
+| 大类 | Extract Class | 中 |
+| Feature Envy | Move Method | 中 |
+| 深层嵌套 | Replace Nested with Guard Clauses | 低 |
+| 大型组件 | 拆分为子组件 | 中 |
+| 条件复杂度 | 策略模式/映射表 | 中 |
+| 魔法数字 | 提取常量/枚举 | 低 |
+
+### 3. 小步执行
+
+对每一步：
+1. 做一个**原子级**的重构变更
+2. 运行测试 -> 全部通过
+3. Git commit（可选，但建议频繁提交）
+4. 继续下一步
+
+## 禁止事项
+
+- 不要在重构中同时添加新功能
+- 不要一次改太多（改完跑不了测试）
+- 不要在没有测试的情况下重构核心逻辑
+- 不要重构正在被其他人修改的代码
+
+## 验证
+
+- [ ] 所有测试通过
+- [ ] ESLint 无报错
+- [ ] 外部行为未改变
+- [ ] 代码可读性提升
diff --git a/.cursor/rules/references/011-vue-deep.md b/.cursor/rules/references/011-vue-deep.md
new file mode 100644
index 0000000..11d2f7f
--- /dev/null
+++ b/.cursor/rules/references/011-vue-deep.md
@@ -0,0 +1,618 @@
+# 011-vue.mdc (Deep Reference)
+
+> 该文件为原始详细规范归档，供 Tier 3 按需读取。
+
+---
+
+
+# 🟢 Vue 3 / Vite Standards
+
+> **⚠️ 双前端区分**：本文件中的 Element Plus 相关内容**仅适用于管理端** (`Case-Database-Frontend-admin/`)。
+> 用户端 (`Case-Database-Frontend-user/`) 使用 Headless UI + Tailwind CSS，**禁止引入 Element Plus**。
+
+## 组件规范
+
+- **所有组件使用 `<script setup>`**（Composition API + 语法糖，不使用 `lang` 类型标注）
+- 禁止 Options API（除非集成第三方库）
+- 禁止 Class 组件
+- 组件嵌套不超过 3 层，超过则拆分
+- 使用 `defineProps` + `defineEmits` 声明接口（编译时宏，无需导入）
+- Named exports for composables；组件文件本身使用 default export（Vue 惯例）
+
+## 项目目录结构
+
+```
+src/
+├── api/                    # API 接口层（按业务模块分目录）
+│   ├── production/         # 生产管理 API
+│   ├── auth.ts             # 认证 API
+│   └── common.ts           # 通用 API
+├── assets/                 # 静态资源
+│   ├── styles/             # 全局样式 (SCSS)
+│   ├── icons/              # 图标
+│   └── images/             # 图片
+├── components/             # 公共组件
+│   ├── core/               # 核心通用组件
+│   └── custom/             # 业务组件
+├── config/                 # 前端配置
+├── directives/             # 自定义指令
+├── hooks/                  # 组合式函数
+├── layouts/                # 布局组件
+├── locales/                # 国际化
+├── router/                 # 路由配置
+│   ├── guards/             # 路由守卫
+│   └── routes/             # 路由定义
+├── store/                  # Pinia 状态管理
+│   └── modules/            # Store 模块
+├── types/                  # JSDoc 类型定义（可选，.ts 文件）
+├── utils/                  # 工具函数
+│   ├── request.ts          # Axios 封装
+│   ├── storage/            # 本地存储工具
+│   └── websocket/          # WebSocket 工具
+└── views/                  # 页面视图（按业务模块）
+    ├── auth/               # 认证页面
+    ├── dashboard/          # 仪表盘
+    └── production/         # 生产管理
+```
+
+## 组件模板
+
+```vue
+<script setup>
+const props = defineProps({
+  variant: {
+    type: String,
+    default: 'primary',  // 'primary' | 'secondary' | 'ghost'
+  },
+  size: {
+    type: String,
+    default: 'default',  // 'small' | 'default' | 'large'
+  },
+  disabled: {
+    type: Boolean,
+    default: false,
+  },
+})
+
+const emit = defineEmits(['click'])
+</script>
+
+<template>
+  <el-button
+    :type="props.variant === 'ghost' ? 'default' : props.variant"
+    :size="props.size"
+    :disabled="props.disabled"
+    @click="emit('click', $event)"
+  >
+    <slot />
+  </el-button>
+</template>
+```
+
+## Element Plus 使用规范（仅管理端）
+
+> 以下内容仅适用于 `Case-Database-Frontend-admin/`，用户端禁止使用 Element Plus。
+
+- **按需导入**：使用 `unplugin-vue-components` + `unplugin-auto-import` 自动导入
+- **表单验证**：使用 Element Plus 内置 `el-form` rules，复杂场景配合 `async-validator`
+- **主题定制**：通过 SCSS 变量覆盖 Element Plus 默认主题
+- **图标**：使用 `@element-plus/icons-vue`，按需导入
+
+```typescript
+// vite.config.ts 自动导入配置
+import AutoImport from 'unplugin-auto-import/vite'
+import Components from 'unplugin-vue-components/vite'
+import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
+
+export default defineConfig({
+  plugins: [
+    AutoImport({ resolvers: [ElementPlusResolver()] }),
+    Components({ resolvers: [ElementPlusResolver()] }),
+  ],
+})
+```
+
+## 状态管理选择
+
+| 场景 | 方案 |
+|------|------|
+| 组件内部 | `ref` / `reactive` |
+| 计算属性 | `computed` |
+| 跨组件共享 | **Pinia** (`defineStore`) |
+| 服务端状态 | Axios + Pinia Action |
+| 表单验证 | 管理端：Element Plus `el-form` rules；用户端：自定义验证 |
+| URL 状态 | `useRoute` / `useRouter`（vue-router） |
+
+## Axios 封装规范
+
+```typescript
+// src/utils/request.ts
+import axios from 'axios'
+
+const service = axios.create({
+  baseURL: import.meta.env.VITE_API_URL,
+  timeout: 60000,
+  headers: { 'Content-Type': 'application/json;charset=UTF-8' },
+})
+
+// Request interceptor: inject token
+service.interceptors.request.use((config) => {
+  const token = localStorage.getItem('access_token')
+  if (token) {
+    config.headers.Authorization = `Bearer ${token}`
+  }
+  return config
+})
+
+// Response interceptor: unified error handling
+service.interceptors.response.use(
+  (response) => {
+    const { code, data, message } = response.data
+    if (code === 200) return data
+    return Promise.reject(new Error(message || 'Request failed'))
+  },
+  (error) => {
+    if (error.response?.status === 401) {
+      // Token expired -> redirect to login
+    }
+    return Promise.reject(error)
+  },
+)
+```
+
+## Vue Router 路由规范
+
+```typescript
+// src/router/guards/auth.ts
+export function setupAuthGuard(router) {
+  router.beforeEach(async (to, _from, next) => {
+    const token = localStorage.getItem('access_token')
+
+    if (to.meta.requiresAuth && !token) {
+      return next({ name: 'login', query: { redirect: to.fullPath } })
+    }
+
+    // Dynamic route loading for RBAC
+    if (token && !hasLoadedDynamicRoutes()) {
+      await loadDynamicRoutes(router)
+      return next({ ...to, replace: true })
+    }
+
+    next()
+  })
+}
+```
+
+## Composables 目录约定
+
+所有 composable 位于 `src/hooks/`，以 `use` 前缀命名：
+
+| Composable | 职责 | 返回值 |
+|------------|------|--------|
+| `useTable` | 表格数据加载、分页、搜索、排序 | `{ loading, dataList, pagination, loadData, handleSearch, handleReset }` |
+| `useForm` | 表单状态、校验、提交 | `{ formRef, formData, rules, loading, handleSubmit, handleReset }` |
+| `useAuth` | 权限判断、按钮/菜单可见性 | `{ hasAuth, hasRole, checkPermission }` |
+| `useCommon` | 通用工具（字典、枚举转换） | `{ getDictLabel, formatEnum }` |
+| `useFastEnter` | 快速导航、全局搜索 | `{ visible, keyword, results, navigate }` |
+| `useHeaderBar` | 顶部栏状态（全屏、消息、用户） | `{ isFullscreen, toggleFullscreen, unreadCount }` |
+| `useSmsCode` | 短信验证码倒计时 | `{ countdown, isSending, sendCode }` |
+| `useTableColumns` | 表格列配置、列显隐持久化 | `{ columns, visibleColumns, toggleColumn }` |
+| `useTheme` | 主题切换 + 系统跟随 | `{ isDark, toggleTheme, colorPrimary }` |
+| `useChart` | ECharts 实例管理、自动 resize | `{ chartRef, setOption, resize }` |
+| `useWebSocket` | WebSocket 连接管理 | `{ connect, disconnect, send, onMessage }` |
+
+```typescript
+// src/hooks/useTable.ts — 标准实现
+export function useTable(fetchFn) {
+  const loading = ref(false)
+  const dataList = ref([])
+  const pagination = reactive({ current: 1, size: 10, total: 0 })
+  const searchForm = reactive({})
+
+  async function loadData() {
+    loading.value = true
+    try {
+      const result = await fetchFn({
+        page: pagination.current,
+        page_size: pagination.size,
+        ...searchForm,
+      })
+      dataList.value = result.data
+      pagination.total = result.total
+    } finally {
+      loading.value = false
+    }
+  }
+
+  function handleSearch() {
+    pagination.current = 1
+    loadData()
+  }
+
+  function handleReset() {
+    Object.keys(searchForm).forEach((key) => { searchForm[key] = undefined })
+    handleSearch()
+  }
+
+  function handlePageChange(page) {
+    pagination.current = page
+    loadData()
+  }
+
+  return { loading, dataList, pagination, searchForm, loadData, handleSearch, handleReset, handlePageChange }
+}
+```
+
+## 自定义指令
+
+所有指令位于 `src/directives/`：
+
+| 指令 | 用途 | 用法示例 |
+|------|------|---------|
+| `v-auth` | 按钮级权限控制（权限标识） | `v-auth="'system:user:add'"` |
+| `v-roles` | 角色级权限控制 | `v-roles="['admin', 'manager']"` |
+| `v-focus` | 自动聚焦输入框 | `v-focus` |
+| `v-highlight` | 搜索关键词高亮 | `v-highlight="keyword"` |
+| `v-index` | 序号自动生成 | `v-index="{ page, size }"` |
+| `v-ripple` | 点击波纹效果 | `v-ripple` |
+
+```typescript
+// src/directives/auth.ts
+import { useUserStore } from '@/store/modules/user'
+
+export const vAuth = {
+  mounted(el, binding) {
+    const userStore = useUserStore()
+    if (!userStore.permissions.includes(binding.value)) {
+      el.parentNode?.removeChild(el)
+    }
+  },
+}
+
+// src/directives/roles.ts
+export const vRoles = {
+  mounted(el, binding) {
+    const userStore = useUserStore()
+    const hasRole = binding.value.some((role) => userStore.roles.includes(role))
+    if (!hasRole) {
+      el.parentNode?.removeChild(el)
+    }
+  },
+}
+```
+
+## 布局组件约定
+
+布局组件位于 `src/layouts/`：
+
+| 组件 | 职责 |
+|------|------|
+| `ArtSidebarMenu` | 侧边导航菜单（递归菜单树） |
+| `ArtHeader` | 顶部栏（面包屑 + 用户 + 通知 + 全屏） |
+| `ArtWorkTab` | 多标签页管理（右键菜单、拖拽排序） |
+| `ArtNotification` | 通知面板（WebSocket 实时推送） |
+| `ArtChatWindow` | 即时通讯窗口 |
+| `ArtFastEnter` | 全局快速搜索导航（Ctrl+K） |
+| `ArtGlobalSearch` | 全局搜索弹窗 |
+
+## Pinia Store 模块映射
+
+| Store | 职责 | 持久化 | 加密 |
+|-------|------|--------|------|
+| `user` | 用户信息、Token、权限、角色 | ✅ | ✅ Token 加密 |
+| `menu` | 菜单树、动态路由 | ✅ | ❌ |
+| `setting` | 主题、布局、语言设置 | ✅ | ❌ |
+| `worktab` | 标签页状态 | ✅ | ❌ |
+| `table` | 表格列配置、列显隐 | ✅ | ❌ |
+| `notification` | 通知消息、未读计数 | ❌ | ❌ |
+| `workflow` | 审批流程状态 | ❌ | ❌ |
+| `product` | 产品/生产模块状态 | ❌ | ❌ |
+| `outsideflow` | 外部审批流程 | ❌ | ❌ |
+
+```typescript
+// Pinia 加密持久化示例
+import CryptoJS from 'crypto-js'
+
+const ENCRYPT_KEY = import.meta.env.VITE_STORAGE_KEY || 'default-key'
+
+function encrypt(data) {
+  return CryptoJS.AES.encrypt(data, ENCRYPT_KEY).toString()
+}
+
+function decrypt(data) {
+  return CryptoJS.AES.decrypt(data, ENCRYPT_KEY).toString(CryptoJS.enc.Utf8)
+}
+
+export const useUserStore = defineStore('user', () => {
+  // ... state and actions
+}, {
+  persist: {
+    key: 'user-store',
+    storage: {
+      getItem: (key) => {
+        const raw = localStorage.getItem(key)
+        return raw ? decrypt(raw) : null
+      },
+      setItem: (key, value) => {
+        localStorage.setItem(key, encrypt(value))
+      },
+    },
+    pick: ['token', 'refreshToken'],
+  },
+})
+```
+
+## 路由守卫完整流程
+
+```typescript
+// src/router/guards/index.ts
+import NProgress from 'nprogress'
+import { useUserStore } from '@/store/modules/user'
+import { useMenuStore } from '@/store/modules/menu'
+import { useWorktabStore } from '@/store/modules/worktab'
+
+const WHITE_LIST = ['/login', '/register', '/404', '/403']
+
+export function setupRouterGuards(router) {
+  router.beforeEach(async (to, _from, next) => {
+    NProgress.start()
+    document.title = `${to.meta.title || ''} - ${import.meta.env.VITE_APP_TITLE}`
+
+    const userStore = useUserStore()
+    const token = userStore.token
+
+    // Step 1: 白名单放行
+    if (WHITE_LIST.includes(to.path)) {
+      return next()
+    }
+
+    // Step 2: 无 Token -> 登录
+    if (!token) {
+      return next({ path: '/login', query: { redirect: to.fullPath } })
+    }
+
+    // Step 3: 已登录访问登录页 -> 首页
+    if (to.path === '/login') {
+      return next({ path: '/' })
+    }
+
+    // Step 4: 动态路由未加载 -> 加载
+    const menuStore = useMenuStore()
+    if (!menuStore.isRoutesLoaded) {
+      try {
+        await menuStore.loadDynamicRoutes(router)
+        return next({ ...to, replace: true })
+      } catch {
+        userStore.logout()
+        return next({ path: '/login' })
+      }
+    }
+
+    next()
+  })
+
+  router.afterEach((to) => {
+    NProgress.done()
+
+    // Step 5: 更新标签页
+    const worktabStore = useWorktabStore()
+    if (to.meta.title && !to.meta.hideTab) {
+      worktabStore.addTab({
+        path: to.path,
+        title: to.meta.title,
+        name: to.name,
+      })
+    }
+  })
+}
+```
+
+## WebSocket 集成模式
+
+```typescript
+// src/utils/websocket/notification.ts
+import { useUserStore } from '@/store/modules/user'
+import { useNotificationStore } from '@/store/modules/notification'
+
+class NotificationWebSocket {
+  ws = null
+  reconnectTimer = null
+  heartbeatTimer = null
+  reconnectAttempts = 0
+  maxReconnectAttempts = 5
+
+  connect() {
+    const userStore = useUserStore()
+    if (!userStore.token) return
+
+    const wsUrl = `${import.meta.env.VITE_WS_URL}?token=${userStore.token}`
+    this.ws = new WebSocket(wsUrl)
+
+    this.ws.onopen = () => {
+      this.reconnectAttempts = 0
+      this.startHeartbeat()
+    }
+
+    this.ws.onmessage = (event) => {
+      const message = JSON.parse(event.data)
+      this.handleMessage(message)
+    }
+
+    this.ws.onclose = () => {
+      this.stopHeartbeat()
+      this.tryReconnect()
+    }
+  }
+
+  handleMessage(message) {
+    const notificationStore = useNotificationStore()
+    switch (message.type) {
+      case 'notification':
+        notificationStore.addNotification(message.data)
+        break
+      case 'heartbeat':
+        // Pong
+        break
+    }
+  }
+
+  startHeartbeat() {
+    this.heartbeatTimer = setInterval(() => {
+      this.ws?.send(JSON.stringify({ type: 'heartbeat', data: 'ping' }))
+    }, 30000)
+  }
+
+  stopHeartbeat() {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer)
+  }
+
+  tryReconnect() {
+    if (this.reconnectAttempts >= this.maxReconnectAttempts) return
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectAttempts++
+      this.connect()
+    }, Math.min(1000 * 2 ** this.reconnectAttempts, 30000))
+  }
+
+  disconnect() {
+    this.stopHeartbeat()
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer)
+    this.ws?.close()
+    this.ws = null
+  }
+}
+
+export const notificationWs = new NotificationWebSocket()
+```
+
+## 性能检查清单
+
+- [ ] 路由使用 `() => import()` 懒加载
+- [ ] 列表使用稳定 `:key`（非 index）
+- [ ] 大列表使用虚拟化（`@tanstack/vue-virtual`）
+- [ ] 使用 `defineAsyncComponent` 做组件懒加载
+- [ ] 避免在 `<template>` 中写复杂表达式，提取为 `computed`
+- [ ] 动态组件使用 `shallowRef` 存储组件引用
+- [ ] 管理端：Element Plus 按需导入，避免全量引入（用户端不使用 Element Plus）
+- [ ] Vite 构建配置 `manualChunks` 分离 vendor
+- [ ] Pinia 敏感数据（Token）使用加密持久化
+- [ ] WebSocket 连接登录后建立，登出后断开
+
+## Props 反模式全集
+
+> 以下案例来源于项目实际 ESLint 修复（`vue/no-mutating-props`），作为永久参考。
+
+### 场景 A：表单子组件 v-model 直接修改对象 prop
+
+父组件传递 `reactive` 对象作为 prop，子组件用 `v-model` 直接绑定其字段。
+
+```vue
+<!-- ❌ ForgotPanel.vue — 直接修改 prop.form 的字段 -->
+<script setup>
+defineProps<{
+  form: { username: string; phone: string; code: string }
+}>()
+</script>
+<template>
+  <AppInput v-model="form.username" />
+  <AppInput v-model="form.phone" />
+  <AppInput v-model="form.code" />
+</template>
+```
+
+```vue
+<!-- ✅ 修复后 — 通过 emit 通知父组件更新 -->
+<script setup>
+type FormData = { username: string; phone: string; code: string }
+
+const props = defineProps<{ form: FormData }>()
+const emit = defineEmits<{ 'update:form': [value: FormData] }>()
+
+function updateField(field: keyof FormData, value: string) {
+  emit('update:form', { ...props.form, [field]: value })
+}
+</script>
+<template>
+  <AppInput :model-value="form.username" @update:model-value="updateField('username', $event)" />
+  <AppInput :model-value="form.phone" @update:model-value="updateField('phone', $event)" />
+  <AppInput :model-value="form.code" @update:model-value="updateField('code', $event)" />
+</template>
+```
+
+**父组件响应**：`@update:form="Object.assign(formData, $event)"`
+
+### 场景 B：筛选器子组件动态 key 修改 prop
+
+子组件通过 `v-model` 绑定 `prop[dynamicKey]`，遍历配置项时逐个修改 prop 的属性。
+
+```vue
+<!-- ❌ FilterDrawerBody.vue — v-model 绑定动态 prop key -->
+<RadioGroup v-model="radios[f.key]" :options="f.options" />
+<CheckboxGroup v-model="checkboxes[f.key]" :options="f.options" />
+<SelectField v-model="selects[f.key]" :options="f.options" />
+```
+
+```vue
+<!-- ✅ 修复后 — 拆分为 :model-value + emit -->
+<RadioGroup
+  :model-value="radios[f.key]"
+  :options="f.options"
+  @update:model-value="emit('update:radio', f.key, $event)"
+/>
+<CheckboxGroup
+  :model-value="checkboxes[f.key]"
+  :options="f.options"
+  @update:model-value="emit('update:checkbox', f.key, $event)"
+/>
+<SelectField
+  :model-value="selects[f.key]"
+  :options="f.options"
+  @update:model-value="emit('update:select', f.key, $event)"
+/>
+```
+
+**父组件响应**：`@update:radio="(key, val) => radios[key] = val"`
+
+### 场景 C：事件回调中赋值 prop 属性（隐蔽变体）
+
+不通过 `v-model`，但在事件处理函数中直接赋值 prop 的属性。ESLint 同样检测为 prop mutation。
+
+```vue
+<!-- ❌ FilterDrawerBody.vue — 事件回调中直接赋值 prop -->
+<LogicTable
+  :values="logics"
+  @update-logic="(k: string, v: string) => logics[k] = v"
+/>
+```
+
+```vue
+<!-- ✅ 修复后 — 转发为 emit，由父组件执行赋值 -->
+<LogicTable
+  :values="logics"
+  @update-logic="(k: string, v: string) => emit('update:logic', k, v)"
+/>
+```
+
+**父组件响应**：`@update:logic="(key, val) => logics[key] = val"`
+
+### 附：事件命名规范
+
+以上修复中同步修正了 `defineEmits` 的事件命名：
+
+```typescript
+// ❌ kebab-case（触发 vue/custom-event-name-casing）
+defineEmits<{
+  'add-room-condition': []
+  'remove-room-condition': [id: number]
+  'update-room-condition': [id: number, field: string, value: string | number]
+}>()
+
+// ✅ camelCase
+defineEmits<{
+  addRoomCondition: []
+  removeRoomCondition: [id: number]
+  updateRoomCondition: [id: number, field: string, value: string | number]
+}>()
+```
+
+模板中 `@add-room-condition` 和 `@addRoomCondition` 均可，Vue 自动双向转换。
diff --git a/.cursor/rules/references/013-backend-deep.md b/.cursor/rules/references/013-backend-deep.md
new file mode 100644
index 0000000..1525ae1
--- /dev/null
+++ b/.cursor/rules/references/013-backend-deep.md
@@ -0,0 +1,445 @@
+# 013-backend.mdc (Deep Reference)
+
+> 该文件为原始详细规范归档，供 Tier 3 按需读取。
+
+---
+
+
+# 🖥️ PHP Hyperf + Swoole Backend Standards
+
+参考文档: @docs/architecture/api-contracts.md @docs/architecture/system-design.md
+
+## 分层架构
+
+```
+Request → Middleware → Controller → Service → Repository → Model → DB
+                                       ↓
+                                    Event → Listener (异步)
+```
+
+| 层 | 职责 | 禁止 |
+|---|---|---|
+| **Controller** | 接收请求、参数验证、调用 Service、返回响应 | 包含业务逻辑 |
+| **Service** | 核心业务逻辑、事务管理、调用 Repository | 直接操作数据库 |
+| **Repository** | 数据访问、查询构建、数据权限过滤 | 包含业务判断 |
+| **Model** | 数据模型、关联定义、类型转换 | 包含业务方法 |
+
+## PHP 编码规范 (PSR-12)
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Service\Production;
+
+use App\Model\Production\ProductionOrder;
+use App\Repository\Production\OrderRepository;
+use Hyperf\Di\Annotation\Inject;
+use Hyperf\DbConnection\Db;
+
+class OrderService
+{
+    #[Inject]
+    protected OrderRepository $orderRepository;
+
+    public function create(array $data): ProductionOrder
+    {
+        return Db::transaction(function () use ($data) {
+            $order = $this->orderRepository->create($data);
+            // trigger event
+            event(new OrderCreated($order));
+            return $order;
+        });
+    }
+}
+```
+
+**命名规范**:
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 类 | PascalCase | `OrderService` |
+| 方法 | camelCase | `createOrder()` |
+| 变量 | camelCase | `$orderData` |
+| 常量 | SCREAMING_SNAKE | `MAX_RETRY_COUNT` |
+| 数据库字段 | snake_case | `created_at` |
+| 路由 | kebab-case 复数 | `/admin/production-orders` |
+
+## API 设计
+
+- RESTful 命名: 复数名词 (`/admin/users`, `/admin/production-orders`)
+- 版本控制: `/admin/v1/...`（可选）
+- 统一响应格式:
+
+```php
+// 成功
+{ "code": 200, "message": "ok", "data": T }
+
+// 列表（带分页）
+{ "code": 200, "message": "ok", "data": { "items": [], "total": 100 } }
+
+// 错误
+{ "code": 422, "message": "Validation failed", "data": { "errors": {} } }
+```
+
+## 输入验证
+
+```php
+// app/Request/Production/CreateOrderRequest.php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Request\Production;
+
+use Hyperf\Validation\Request\FormRequest;
+
+class CreateOrderRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'customer_id' => 'required|integer|exists:customers,id',
+            'platform_id' => 'required|integer|exists:platforms,id',
+            'order_type'  => 'required|integer|in:1,2,3',
+            'remark'      => 'nullable|string|max:500',
+        ];
+    }
+}
+```
+
+## 认证/授权
+
+- JWT 双 Token 机制: Access Token (2h) + Refresh Token (7d)
+- Token 存储在 Redis，支持强制失效
+- 密码: `password_hash()` + `PASSWORD_BCRYPT`
+- 速率限制: `#[RateLimit]` 注解
+
+## 中间件链
+
+```
+Request
+  → ErrorLogMiddleware          # 异常捕获
+  → AccessTokenMiddleware       # JWT 验证
+  → PermissionMiddleware        # RBAC 权限
+  → DataPermissionMiddleware    # 数据权限过滤
+  → OperationMiddleware         # 操作日志
+  → Controller
+```
+
+## 异常处理器链
+
+异常处理器按优先级顺序注册，每个 Handler 只处理对应的异常类型：
+
+```php
+// config/autoload/exceptions.php
+return [
+    'handler' => [
+        'http' => [
+            // Priority: higher number = higher priority
+            ValidationExceptionHandler::class,    // 验证异常 → 422
+            AuthExceptionHandler::class,          // 认证异常 → 401
+            PermissionExceptionHandler::class,    // 权限异常 → 403
+            BusinessExceptionHandler::class,      // 业务异常 → 自定义 code
+            RateLimitExceptionHandler::class,     // 限流异常 → 429
+            ModelNotFoundExceptionHandler::class, // 模型未找到 → 404
+            QueryExceptionHandler::class,         // 数据库异常 → 500（隐藏细节）
+            AppExceptionHandler::class,           // 兜底异常 → 500
+        ],
+    ],
+];
+```
+
+```php
+// app/Exception/BusinessException.php
+namespace App\Exception;
+
+use Hyperf\Server\Exception\ServerException;
+
+class BusinessException extends ServerException
+{
+    public function __construct(
+        int $code = 500,
+        string $message = '',
+        ?\Throwable $previous = null,
+    ) {
+        parent::__construct($message, $code, $previous);
+    }
+}
+
+// app/Exception/Handler/BusinessExceptionHandler.php
+class BusinessExceptionHandler extends ExceptionHandler
+{
+    public function handle(Throwable $throwable, ResponseInterface $response): ResponseInterface
+    {
+        $this->stopPropagation();
+
+        return $response->withStatus(200)->withBody(new SwooleStream(json_encode([
+            'code'    => $throwable->getCode(),
+            'message' => $throwable->getMessage(),
+            'data'    => null,
+        ], JSON_UNESCAPED_UNICODE)));
+    }
+
+    public function isValid(Throwable $throwable): bool
+    {
+        return $throwable instanceof BusinessException;
+    }
+}
+```
+
+## 事件系统
+
+Event + Listener 解耦异步逻辑，避免 Service 膨胀：
+
+| 事件 | 触发时机 | 监听器 |
+|------|---------|--------|
+| `OrderCreated` | 订单创建后 | 发送通知、记录日志、同步第三方 |
+| `OrderStatusChanged` | 状态变更后 | 更新统计、通知相关人 |
+| `PaymentReceived` | 收款确认后 | 更新订单状态、触发生产 |
+| `UserLoggedIn` | 登录成功 | 记录登录日志、更新最后登录时间 |
+| `UserRegistered` | 注册成功 | 发送欢迎邮件、初始化默认数据 |
+| `WorkflowApproved` | 审批通过 | 推进流程、通知下一节点 |
+| `WorkflowRejected` | 审批驳回 | 通知发起人、记录原因 |
+| `FileUploaded` | 文件上传完成 | 生成缩略图、同步到 OSS |
+| `NotificationSent` | 通知发出 | WebSocket 推送、记录日志 |
+| `CacheInvalidated` | 缓存失效 | 预热缓存、记录日志 |
+
+```php
+// app/Event/OrderCreated.php
+class OrderCreated
+{
+    public function __construct(public readonly ProductionOrder $order) {}
+}
+
+// app/Listener/SendOrderNotificationListener.php
+#[Listener]
+class SendOrderNotificationListener implements ListenerInterface
+{
+    public function listen(): array
+    {
+        return [OrderCreated::class];
+    }
+
+    public function process(object $event): void
+    {
+        /** @var OrderCreated $event */
+        $this->notificationService->send(
+            userId: $event->order->created_by,
+            type: 'order_created',
+            data: ['order_no' => $event->order->order_no],
+        );
+    }
+}
+```
+
+## 数据权限过滤
+
+5 级 DATA_SCOPE 控制用户可见数据范围，在 Repository 层自动过滤：
+
+| 级别 | 常量 | 说明 |
+|------|------|------|
+| 全部 | `DATA_SCOPE_ALL` | 管理员，无限制 |
+| 自定义 | `DATA_SCOPE_CUSTOM` | 指定部门集合 |
+| 本部门 | `DATA_SCOPE_DEPT` | 仅本部门数据 |
+| 本部门及下级 | `DATA_SCOPE_DEPT_AND_CHILD` | 本部门 + 子部门 |
+| 仅本人 | `DATA_SCOPE_SELF` | 仅自己创建的数据 |
+
+```php
+// app/Repository/Concern/DataPermissionTrait.php
+trait DataPermissionTrait
+{
+    protected function applyDataScope(Builder $query): Builder
+    {
+        $user = Context::get('current_user');
+        if (!$user) return $query;
+
+        return match ($user->data_scope) {
+            DataScope::ALL => $query,
+            DataScope::CUSTOM => $query->whereIn('dept_id', $user->custom_dept_ids),
+            DataScope::DEPT => $query->where('dept_id', $user->dept_id),
+            DataScope::DEPT_AND_CHILD => $query->whereIn(
+                'dept_id',
+                $this->deptService->getChildDeptIds($user->dept_id),
+            ),
+            DataScope::SELF => $query->where('created_by', $user->id),
+        };
+    }
+}
+```
+
+## 分布式锁模式
+
+使用 Redis 分布式锁防止并发操作导致数据不一致：
+
+```php
+// 订单锁定场景
+class OrderLockService
+{
+    private const LOCK_PREFIX = 'order_lock:';
+    private const LOCK_TTL = 30;
+
+    private const LOCK_TYPES = [
+        'edit'             => '编辑锁',
+        'process'          => '处理锁',
+        'payment_pending'  => '待收款锁',
+        'payment_missing'  => '缺款锁',
+    ];
+
+    public function acquireLock(int $orderId, string $type, int $userId): bool
+    {
+        $key = self::LOCK_PREFIX . "{$type}:{$orderId}";
+        return $this->redis->set($key, $userId, ['NX', 'EX' => self::LOCK_TTL]);
+    }
+
+    public function releaseLock(int $orderId, string $type, int $userId): bool
+    {
+        $key = self::LOCK_PREFIX . "{$type}:{$orderId}";
+        // Lua script for atomic check-and-delete
+        $script = <<<'LUA'
+            if redis.call("get", KEYS[1]) == ARGV[1] then
+                return redis.call("del", KEYS[1])
+            else
+                return 0
+            end
+        LUA;
+        return (bool) $this->redis->eval($script, [$key, (string) $userId], 1);
+    }
+}
+```
+
+## Model Traits
+
+常用 Model Trait 复用数据库行为：
+
+| Trait | 职责 |
+|-------|------|
+| `HasCreator` | 自动填充 `created_by` / `updated_by` |
+| `SoftDeletes` | 软删除 (`deleted_at`) |
+| `HasOperationLog` | 操作日志记录 |
+| `HasDataPermission` | 查询自动加数据权限条件 |
+| `HasSortable` | 拖拽排序 (`sort_order`) |
+
+```php
+// app/Model/Concern/HasCreator.php
+trait HasCreator
+{
+    public static function bootHasCreator(): void
+    {
+        static::creating(function (Model $model) {
+            $user = Context::get('current_user');
+            if ($user) {
+                $model->created_by = $user->id;
+                $model->updated_by = $user->id;
+            }
+        });
+
+        static::updating(function (Model $model) {
+            $user = Context::get('current_user');
+            if ($user) {
+                $model->updated_by = $user->id;
+            }
+        });
+    }
+}
+```
+
+## 定时任务
+
+```php
+// app/Crontab/DailyStatisticsCrontab.php
+#[Crontab(
+    name: 'daily_statistics',
+    rule: '0 2 * * *',
+    singleton: true,
+    onOneServer: true,
+    memo: '每日凌晨 2 点统计报表'
+)]
+class DailyStatisticsCrontab
+{
+    #[Inject]
+    protected StatisticsService $statisticsService;
+
+    public function execute(): void
+    {
+        $this->statisticsService->generateDailyReport(
+            Carbon::yesterday()
+        );
+    }
+}
+```
+
+**注解说明**:
+- `singleton: true` — 同一进程内不重复执行
+- `onOneServer: true` — 多实例部署时只在一台执行
+
+## 请求签名验证
+
+前端签名 + 后端验签，防止请求篡改：
+
+```php
+// app/Middleware/RequestSignMiddleware.php
+class RequestSignMiddleware implements MiddlewareInterface
+{
+    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
+    {
+        $timestamp = $request->getHeaderLine('X-Timestamp');
+        $sign      = $request->getHeaderLine('X-Sign');
+        $nonce     = $request->getHeaderLine('X-Nonce');
+
+        // Step 1: 时间窗口校验（5 分钟内有效）
+        if (abs(time() - (int) $timestamp) > 300) {
+            throw new BusinessException(403, 'Request expired');
+        }
+
+        // Step 2: Nonce 防重放
+        if (!$this->redis->set("nonce:{$nonce}", 1, ['NX', 'EX' => 300])) {
+            throw new BusinessException(403, 'Duplicate request');
+        }
+
+        // Step 3: 签名校验
+        $body = (string) $request->getBody();
+        $expectedSign = hash_hmac('sha256', "{$timestamp}{$nonce}{$body}", $this->appSecret);
+
+        if (!hash_equals($expectedSign, $sign)) {
+            throw new BusinessException(403, 'Invalid signature');
+        }
+
+        return $handler->handle($request);
+    }
+}
+```
+
+## 依赖注入
+
+```php
+// ✅ 构造函数注入（推荐）
+public function __construct(
+    protected readonly OrderRepository $orderRepo,
+    protected readonly CacheInterface $cache,
+) {}
+
+// ✅ 属性注入
+#[Inject]
+protected OrderService $orderService;
+
+// ❌ 禁止手动 new 或 make()
+$service = new OrderService(); // WRONG
+```
+
+## 禁止事项
+
+- 禁止在 Controller 中直接操作数据库
+- 禁止在 Swoole 环境使用阻塞 I/O（`file_get_contents`, `sleep`）
+- 禁止使用全局变量 / 全局静态属性存储请求数据
+- 禁止 `dd()` / `var_dump()` 残留在代码中
+- 禁止 `SELECT *`，明确列名
+- 禁止在循环中执行 SQL（N+1 问题）
+- 禁止在事件监听器中抛出异常阻塞主流程
+- 禁止在定时任务中未加 `onOneServer` 导致多实例重复执行
diff --git a/.cursor/rules/references/014-database-deep.md b/.cursor/rules/references/014-database-deep.md
new file mode 100644
index 0000000..4e2cb2f
--- /dev/null
+++ b/.cursor/rules/references/014-database-deep.md
@@ -0,0 +1,624 @@
+# 014-database.mdc (Deep Reference)
+
+> 该文件为原始详细规范归档，供 Tier 3 按需读取。
+
+---
+
+
+# 🗄️ Hyperf ORM + MySQL Database Standards
+
+参考文档: @docs/architecture/data-model.md
+
+## 核心原则
+
+- 任何写操作前有备份策略
+- 使用 Hyperf Migration，禁止直接 DDL
+- 软删除优先于硬删除 (`deleted_at`)
+- 敏感数据加密存储
+- 生产环境只读
+
+## 必须字段 (每张表)
+
+```php
+// Hyperf Migration
+Schema::create('examples', function (Blueprint $table) {
+    $table->bigIncrements('id');
+    $table->timestamps();            // created_at, updated_at
+    $table->softDeletes();            // deleted_at
+    $table->unsignedBigInteger('created_by')->nullable();
+    $table->unsignedBigInteger('updated_by')->nullable();
+});
+```
+
+## Model 规范
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Model\Production;
+
+use Hyperf\Database\Model\SoftDeletes;
+use Hyperf\DbConnection\Model\Model;
+
+class ProductionOrder extends Model
+{
+    use SoftDeletes;
+
+    protected ?string $table = 'production_orders';
+
+    protected array $fillable = [
+        'order_no', 'customer_id', 'platform_id',
+        'status', 'total_amount', 'paid_amount',
+    ];
+
+    protected array $casts = [
+        'total_amount' => 'decimal:2',
+        'paid_amount'  => 'decimal:2',
+        'source_data'  => 'json',
+        'created_at'   => 'datetime',
+    ];
+
+    // Eager loading to prevent N+1
+    public function customer(): \Hyperf\Database\Model\Relations\BelongsTo
+    {
+        return $this->belongsTo(Customer::class);
+    }
+
+    public function subOrders(): \Hyperf\Database\Model\Relations\HasMany
+    {
+        return $this->hasMany(ProductionSubOrder::class, 'order_id');
+    }
+}
+```
+
+## 命名规范
+
+### 表名模块前缀规则
+
+**表名必须以所属模块名作为前缀**，格式：`<module>_<entity_plural>`。
+
+| 模块 | 前缀 | 示例 |
+|------|------|------|
+| 用户与权限 | `auth_` | `auth_users`, `auth_roles` |
+| 案例核心 | `case_` | `case_cases`, `case_images` |
+| 设计师 | `designer_` | `designer_profiles`, `designer_awards` |
+| 运营内容 | `operation_` | `operation_banners`, `operation_topics` |
+| 用户互动 | `interaction_` | `interaction_favorites`, `interaction_comments` |
+| 日志 | `log_` | `log_user_logins`, `log_downloads` |
+| 安全风控 | `security_` | `security_blacklists`, `security_risk_events` |
+| 系统配置 | `system_` | `system_configs` |
+
+> 多对多关联表同样需要加模块前缀：`<module>_<a>_belongs_<b>`，以主体模块为准。
+
+### 通用命名约定
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 表名 | `<module>_` 前缀 + snake_case 复数 | `auth_users`, `case_cases` |
+| 字段名 | snake_case | `created_at` |
+| 主键 | `id` | `BIGINT UNSIGNED AUTO_INCREMENT` |
+| 外键 | `<table_singular>_id` | `customer_id` |
+| 索引 | `idx_<table>_<columns>` | `idx_auth_users_status` |
+| 唯一索引 | `uk_<table>_<columns>` | `uk_case_cases_code` |
+
+## 高并发表设计规范
+
+### 字段类型选择
+
+| 场景 | 推荐类型 | 避免 |
+|------|---------|------|
+| 主键 | `BIGINT UNSIGNED` | `INT` (溢出风险) |
+| 金额 | `DECIMAL(10,2)` | `FLOAT/DOUBLE` (精度丢失) |
+| 状态 | `VARCHAR(20)` 或 `TINYINT` | `ENUM` (修改需 DDL) |
+| 时间 | `TIMESTAMP` | `DATETIME` (不带时区) |
+| JSON 数据 | `JSON` (MySQL 8) | `TEXT` (无法索引) |
+| 短文本 | `VARCHAR(n)` 精确长度 | `VARCHAR(255)` 万能长度 |
+
+### 新字段安全约束
+
+**已有数据的表上新增字段必须遵循：**
+
+```php
+// ✅ 正确：nullable
+$table->string('avatar')->nullable();
+
+// ✅ 正确：有默认值
+$table->tinyInteger('priority')->default(0);
+
+// ❌ 禁止：NOT NULL 无默认值（锁表重写所有行）
+$table->string('role');  // NOT NULL without default
+```
+
+如需 NOT NULL 约束，使用三步法：
+1. 先添加 nullable 字段
+2. 数据回填（独立迁移）
+3. 再加 NOT NULL 约束（独立迁移）
+
+### 索引策略
+
+```sql
+-- 复合索引：遵循最左前缀原则
+CREATE INDEX idx_orders_status_created ON production_orders(status, created_at);
+
+-- 覆盖索引：查询字段全在索引中，避免回表
+CREATE INDEX idx_orders_cover ON production_orders(status, total_amount, paid_amount);
+
+-- 前缀索引：长字符串字段
+CREATE INDEX idx_orders_remark ON production_orders(remark(20));
+```
+
+**索引检查清单**:
+- [ ] 所有外键字段有索引
+- [ ] WHERE 常用字段有索引
+- [ ] ORDER BY 字段在索引中
+- [ ] 联合查询字段使用复合索引
+- [ ] 单表索引不超过 6 个
+
+### 百万级数据优化
+
+- 分页使用游标分页（`WHERE id > ? LIMIT ?`）替代 `OFFSET`
+- 大表 COUNT 使用近似值或缓存
+- 批量操作使用 `chunk()` 分批处理
+- 避免大事务，单事务操作 < 1000 行
+- 热点数据使用 Redis 缓存，减少 DB 压力
+
+## 读写分离
+
+```php
+// config/autoload/databases.php
+return [
+    'default' => [
+        'driver'    => 'mysql',
+        'read'      => [
+            'host' => [env('DB_READ_HOST_1'), env('DB_READ_HOST_2')],
+        ],
+        'write'     => [
+            'host' => env('DB_WRITE_HOST'),
+        ],
+        'port'      => env('DB_PORT', 3306),
+        'database'  => env('DB_DATABASE'),
+        'username'  => env('DB_USERNAME'),
+        'password'  => env('DB_PASSWORD'),
+        'charset'   => 'utf8mb4',
+        'collation' => 'utf8mb4_unicode_ci',
+        'pool' => [
+            'min_connections' => 5,
+            'max_connections' => 50,
+            'connect_timeout' => 10.0,
+            'wait_timeout'    => 3.0,
+            'heartbeat'       => -1,
+            'max_idle_time'   => 60,
+        ],
+    ],
+];
+```
+
+## 高级查询模式
+
+### UPSERT（插入或更新）
+
+```php
+// Hyperf Eloquent upsert — 冲突时更新指定字段
+ProductionOrder::query()->upsert(
+    [
+        ['order_no' => 'PO-001', 'status' => 'active', 'total_amount' => 100.00],
+        ['order_no' => 'PO-002', 'status' => 'pending', 'total_amount' => 200.00],
+    ],
+    ['order_no'],                        // conflict key (unique)
+    ['status', 'total_amount']           // columns to update on conflict
+);
+
+// 等效原生 SQL
+// INSERT INTO production_orders (order_no, status, total_amount)
+// VALUES ('PO-001', 'active', 100.00), ('PO-002', 'pending', 200.00)
+// ON DUPLICATE KEY UPDATE status = VALUES(status), total_amount = VALUES(total_amount);
+```
+
+适用场景：外部数据同步、批量导入、幂等写入。
+
+### FOR UPDATE SKIP LOCKED（无锁队列消费）
+
+MySQL 8.0+ 支持，适合自定义任务队列或分布式任务分发：
+
+```php
+// Atomic: claim one pending job without blocking other workers
+$job = Db::select(
+    "SELECT * FROM async_jobs
+     WHERE status = 'pending'
+     ORDER BY created_at
+     LIMIT 1
+     FOR UPDATE SKIP LOCKED"
+);
+
+if ($job) {
+    Db::update(
+        "UPDATE async_jobs SET status = 'processing', worker_id = ? WHERE id = ?",
+        [$workerId, $job[0]->id]
+    );
+}
+```
+
+优势：多 Worker 并发消费时不阻塞，已被锁定的行自动跳过。
+
+### 覆盖索引（Index-Only Scan）
+
+```sql
+-- 查询字段全在索引中，避免回表
+CREATE INDEX idx_orders_cover
+  ON production_orders(status, created_at, total_amount, paid_amount);
+
+-- 此查询只需扫描索引，不回表
+SELECT status, total_amount, paid_amount
+FROM production_orders
+WHERE status = 'active' AND created_at > '2026-01-01';
+```
+
+## 反模式检测 SQL
+
+定期运行以下诊断查询，发现潜在问题：
+
+```sql
+-- 1. 检测未建索引的外键字段
+SELECT TABLE_NAME, COLUMN_NAME, CONSTRAINT_NAME, REFERENCED_TABLE_NAME
+FROM information_schema.KEY_COLUMN_USAGE
+WHERE REFERENCED_TABLE_NAME IS NOT NULL
+  AND TABLE_SCHEMA = DATABASE()
+  AND COLUMN_NAME NOT IN (
+    SELECT COLUMN_NAME FROM information_schema.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = KEY_COLUMN_USAGE.TABLE_NAME
+  );
+
+-- 2. 检测慢查询 Top 10（需开启 performance_schema）
+SELECT DIGEST_TEXT AS query,
+       COUNT_STAR AS calls,
+       ROUND(AVG_TIMER_WAIT / 1000000000, 2) AS avg_ms,
+       ROUND(SUM_TIMER_WAIT / 1000000000, 2) AS total_ms
+FROM performance_schema.events_statements_summary_by_digest
+WHERE SCHEMA_NAME = DATABASE()
+  AND AVG_TIMER_WAIT > 500000000  -- > 500ms
+ORDER BY AVG_TIMER_WAIT DESC
+LIMIT 10;
+
+-- 3. 检测表碎片（dead rows / 需要 OPTIMIZE）
+SELECT TABLE_NAME,
+       TABLE_ROWS,
+       ROUND(DATA_LENGTH / 1024 / 1024, 2) AS data_mb,
+       ROUND(DATA_FREE / 1024 / 1024, 2) AS fragmented_mb
+FROM information_schema.TABLES
+WHERE TABLE_SCHEMA = DATABASE()
+  AND DATA_FREE > 10 * 1024 * 1024  -- > 10MB fragmentation
+ORDER BY DATA_FREE DESC;
+
+-- 4. 检测无用索引（从未使用）
+SELECT s.TABLE_NAME, s.INDEX_NAME
+FROM information_schema.STATISTICS s
+LEFT JOIN performance_schema.table_io_waits_summary_by_index_usage p
+  ON s.TABLE_SCHEMA = p.OBJECT_SCHEMA
+  AND s.TABLE_NAME = p.OBJECT_NAME
+  AND s.INDEX_NAME = p.INDEX_NAME
+WHERE s.TABLE_SCHEMA = DATABASE()
+  AND s.INDEX_NAME != 'PRIMARY'
+  AND (p.COUNT_STAR IS NULL OR p.COUNT_STAR = 0);
+```
+
+## 禁止的反模式
+
+| 反模式 | 替代方案 |
+|--------|----------|
+| N+1 查询 | `with()` Eager Loading |
+| 硬删除 | 软删除 + 定时清理 |
+| 无索引外键 | 所有 FK 必须有索引 |
+| `SELECT *` | 明确列名 `select()` |
+| 长事务 | 拆分小事务 |
+| 循环中单条 SQL | `insert()` 批量操作 |
+| `OFFSET` 深分页 | 游标分页 `WHERE id > ?` |
+| NOT NULL 无默认值加字段 | 先 nullable → 回填 → 加约束 |
+| Schema + Data 混在一个迁移 | 拆为独立迁移文件 |
+| 修改已部署的迁移文件 | 创建新的前向迁移 |
+
+## 迁移文件命名规范
+
+迁移文件严格遵循以下命名格式：
+
+```
+YYYY_MM_DD_HHMMSS_description.php
+```
+
+| 操作 | 文件名示例 |
+|------|----------|
+| 创建表 | `2026_02_24_100000_create_production_orders_table.php` |
+| 添加字段 | `2026_02_24_110000_add_payment_status_to_production_orders.php` |
+| 添加索引 | `2026_02_24_120000_add_index_status_to_production_orders.php` |
+| 修改字段 | `2026_02_24_130000_modify_amount_column_in_production_orders.php` |
+| 删除字段 | `2026_02_24_140000_drop_legacy_field_from_production_orders.php` |
+
+**规则**:
+- 时间戳精确到秒，保证顺序
+- `description` 用 snake_case，必须清晰表达操作内容
+- 每个迁移只做一件事（一张表或一类变更）
+- 必须实现 `down()` 方法支持回滚
+
+## Schema 变更流程
+
+1. 读取 `data-model.md` → 2. 设计变更 → 3. 编写 Migration (含 `down()` 回滚) → 4. 开发环境执行 → 5. 更新文档
+
+```bash
+# 生成迁移
+php bin/hyperf.php gen:migration create_orders_table
+
+# 执行迁移
+php bin/hyperf.php migrate
+
+# 回滚
+php bin/hyperf.php migrate:rollback
+
+# 生成模型
+php bin/hyperf.php gen:model production_orders
+```
+
+## 核心表关系图
+
+```mermaid
+erDiagram
+    %% ── 用户体系 ──────────────────
+    users ||--o{ user_roles : "has"
+    roles ||--o{ user_roles : "has"
+    roles ||--o{ role_menus : "has"
+    roles ||--o{ role_depts : "has"
+    menus ||--o{ role_menus : "has"
+    departments ||--o{ users : "belongs"
+    departments ||--o{ role_depts : "has"
+    departments ||--o{ departments : "parent"
+
+    users {
+        bigint id PK
+        varchar username UK
+        varchar password
+        varchar real_name
+        bigint dept_id FK
+        tinyint status
+        tinyint data_scope
+        timestamp last_login_at
+    }
+
+    roles {
+        bigint id PK
+        varchar name UK
+        varchar code UK
+        tinyint data_scope
+        tinyint status
+    }
+
+    departments {
+        bigint id PK
+        varchar name
+        bigint parent_id FK
+        int sort_order
+        tinyint status
+    }
+
+    menus {
+        bigint id PK
+        varchar name
+        varchar path
+        varchar permission
+        bigint parent_id FK
+        tinyint type
+        int sort_order
+    }
+
+    %% ── 生产体系 ──────────────────
+    production_orders ||--o{ production_sub_orders : "has"
+    production_orders ||--o{ production_payments : "has"
+    production_orders }o--|| customers : "belongs"
+    production_orders }o--|| platforms : "belongs"
+    production_sub_orders ||--o{ production_items : "has"
+
+    production_orders {
+        bigint id PK
+        varchar order_no UK
+        bigint customer_id FK
+        bigint platform_id FK
+        tinyint status
+        decimal total_amount
+        decimal paid_amount
+        json source_data
+        bigint created_by FK
+    }
+
+    production_sub_orders {
+        bigint id PK
+        bigint order_id FK
+        varchar sub_order_no UK
+        tinyint status
+        decimal amount
+    }
+
+    production_payments {
+        bigint id PK
+        bigint order_id FK
+        varchar payment_no UK
+        decimal amount
+        tinyint payment_method
+        tinyint status
+    }
+
+    customers {
+        bigint id PK
+        varchar name
+        varchar company
+        varchar contact_phone
+        tinyint level
+    }
+
+    platforms {
+        bigint id PK
+        varchar name UK
+        varchar code UK
+        tinyint status
+    }
+
+    %% ── 通知体系 ──────────────────
+    notifications ||--o{ notification_reads : "has"
+    users ||--o{ notification_reads : "has"
+
+    notifications {
+        bigint id PK
+        varchar type
+        varchar title
+        text content
+        json data
+        bigint sender_id FK
+        tinyint scope
+    }
+
+    notification_reads {
+        bigint id PK
+        bigint notification_id FK
+        bigint user_id FK
+        timestamp read_at
+    }
+
+    %% ── 审批流程 ──────────────────
+    workflows ||--o{ workflow_nodes : "has"
+    workflow_nodes ||--o{ workflow_records : "has"
+    users ||--o{ workflow_records : "approves"
+
+    workflows {
+        bigint id PK
+        varchar name
+        varchar type
+        bigint reference_id
+        tinyint status
+    }
+
+    workflow_nodes {
+        bigint id PK
+        bigint workflow_id FK
+        int step
+        varchar name
+        bigint assignee_id FK
+        tinyint status
+    }
+
+    workflow_records {
+        bigint id PK
+        bigint node_id FK
+        bigint user_id FK
+        tinyint action
+        text comment
+    }
+```
+
+## 汇总表预聚合（报表优化）
+
+大量统计查询不应实时扫描明细表，而应使用汇总表 + 定时任务预聚合：
+
+```sql
+-- 创建汇总表
+CREATE TABLE order_stats_daily (
+    stat_date DATE NOT NULL,
+    platform_id BIGINT UNSIGNED NOT NULL,
+    total_orders INT UNSIGNED DEFAULT 0,
+    total_amount DECIMAL(14,2) DEFAULT 0.00,
+    avg_amount DECIMAL(10,2) DEFAULT 0.00,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    PRIMARY KEY (stat_date, platform_id)
+) ENGINE=InnoDB;
+```
+
+```php
+// Hyperf Crontab: hourly aggregation
+#[Crontab(rule: "5 * * * *", name: "AggregateOrderStats")]
+class AggregateOrderStatsTask extends AbstractTask
+{
+    public function execute(): void
+    {
+        Db::statement("
+            INSERT INTO order_stats_daily (stat_date, platform_id, total_orders, total_amount, avg_amount)
+            SELECT DATE(created_at), platform_id,
+                   COUNT(*), SUM(total_amount), AVG(total_amount)
+            FROM production_orders
+            WHERE created_at >= CURDATE()
+              AND deleted_at IS NULL
+            GROUP BY DATE(created_at), platform_id
+            ON DUPLICATE KEY UPDATE
+                total_orders = VALUES(total_orders),
+                total_amount = VALUES(total_amount),
+                avg_amount = VALUES(avg_amount)
+        ");
+    }
+}
+```
+
+适用场景：仪表盘、报表导出、趋势分析。明细查询仍走原表。
+
+## MySQL 分区表（百万级+）
+
+数据量超百万且有明确时间维度的表，考虑 RANGE 分区：
+
+```sql
+-- 按月分区（适合时间序列数据）
+ALTER TABLE operation_logs PARTITION BY RANGE (TO_DAYS(created_at)) (
+    PARTITION p202601 VALUES LESS THAN (TO_DAYS('2026-02-01')),
+    PARTITION p202602 VALUES LESS THAN (TO_DAYS('2026-03-01')),
+    PARTITION p202603 VALUES LESS THAN (TO_DAYS('2026-04-01')),
+    PARTITION pmax VALUES LESS THAN MAXVALUE
+);
+```
+
+**分区适用条件**（全部满足才考虑）：
+- 数据量 > 500 万行
+- 查询几乎总是带时间范围条件
+- 需要高效的历史数据归档/清理
+- 表没有跨分区的唯一索引需求
+
+**不适合分区的场景**：
+- 小表（分区开销 > 收益）
+- 查询不带分区键（全分区扫描更慢）
+- 需要跨分区外键约束
+
+## 数据库缓存配置
+
+使用 Redis 缓存频繁查询的数据，减少数据库压力：
+
+```php
+// config/autoload/cache.php
+return [
+    'default' => [
+        'driver'  => Hyperf\Cache\Driver\RedisDriver::class,
+        'packer'  => Hyperf\Codec\Packer\PhpSerializerPacker::class,
+        'prefix'  => 'cache:',
+    ],
+];
+
+// 缓存使用示例
+// 注解式缓存（推荐简单场景）
+#[Cacheable(prefix: 'user', ttl: 3600)]
+public function getById(int $id): ?User
+{
+    return User::find($id);
+}
+
+#[CacheEvict(prefix: 'user')]
+public function update(int $id, array $data): bool
+{
+    return User::where('id', $id)->update($data);
+}
+
+// 手动缓存（复杂场景）
+$user = $this->cache->remember("user:{$id}", 3600, fn() => User::find($id));
+```
+
+### 缓存 TTL 策略
+
+| 数据类型 | TTL | 失效策略 |
+|---------|-----|---------|
+| 字典/配置 | 7 天 | 管理员修改时失效 |
+| 用户信息 | 1 小时 | 用户更新时失效 |
+| 菜单树 | 24 小时 | 菜单变更时失效 |
+| 列表查询 | 5 分钟 | 写操作后批量失效 |
+| 统计报表 | 1 小时 | 定时任务刷新 |
diff --git a/.cursor/rules/references/017-architecture-deep.md b/.cursor/rules/references/017-architecture-deep.md
new file mode 100644
index 0000000..1dc63e1
--- /dev/null
+++ b/.cursor/rules/references/017-architecture-deep.md
@@ -0,0 +1,283 @@
+# 017-architecture.mdc (Deep Reference)
+
+> 该文件为原始详细规范归档，供 Tier 3 按需读取。
+
+---
+
+
+# 🏗️ Million-Level Concurrency Architecture Standards
+
+## 架构总览
+
+```
+                    ┌──────────────┐
+                    │   CDN/WAF    │
+                    └──────┬───────┘
+                           │
+              ┌────────────┴────────────┐
+              │     Nginx Cluster       │
+              │  (负载均衡 + SSL + 静态) │
+              └────────────┬────────────┘
+                           │
+         ┌─────────────────┼─────────────────┐
+         ▼                 ▼                 ▼
+   ┌──────────┐    ┌──────────┐    ┌──────────┐
+   │ Hyperf-1 │    │ Hyperf-2 │    │ Hyperf-N │
+   │ Swoole   │    │ Swoole   │    │ Swoole   │
+   │ HTTP:9501│    │ HTTP:9501│    │ HTTP:9501│
+   │ WS:9502  │    │ WS:9502  │    │ WS:9502  │
+   └────┬─────┘    └────┬─────┘    └────┬─────┘
+        │               │               │
+        └───────┬───────┴───────┬───────┘
+                │               │
+         ┌──────┴──────┐ ┌─────┴──────┐
+         │ Redis       │ │ MySQL      │
+         │ Cluster/    │ │ Master     │
+         │ Sentinel    │ │  ├─Slave 1 │
+         │             │ │  └─Slave 2 │
+         └─────────────┘ └────────────┘
+```
+
+## 无状态服务设计
+
+所有 Hyperf 实例必须无状态，确保水平扩展：
+
+| 状态类型 | 存储位置 | 禁止 |
+|---------|---------|------|
+| 用户 Session | Redis | 存储在内存/文件 |
+| JWT Token | Redis (可验证+可吊销) | 仅本地验证 |
+| 文件上传 | 对象存储 (S3/OSS) | 本地 storage/ |
+| WebSocket 连接 | Redis 维护映射表 | 进程内变量 |
+| 配置 | 配置中心 / env | 硬编码 |
+
+## 缓存策略
+
+### 多级缓存
+
+```
+L1: 进程内缓存 (APCu / Swoole Table)     — 毫秒级, 容量小
+L2: Redis 缓存                           — 亚毫秒级, 容量中
+L3: MySQL 查询                           — 毫秒级, 容量大
+```
+
+### 缓存防护
+
+| 问题 | 场景 | 解决方案 |
+|------|------|---------|
+| **穿透** | 查询不存在的数据 | 布隆过滤器 / 缓存空值 (TTL 30s) |
+| **雪崩** | 大量缓存同时过期 | TTL 加随机抖动 / 预热 |
+| **击穿** | 热点 Key 过期时大量请求 | 互斥锁 (singleflight) |
+
+```php
+// Cache-Aside with mutex lock
+public function getOrderWithLock(int $id): ?ProductionOrder
+{
+    $cacheKey = "order:{$id}";
+    $lockKey = "lock:order:{$id}";
+
+    $cached = $this->redis->get($cacheKey);
+    if ($cached !== false) {
+        return unserialize($cached);
+    }
+
+    // Mutex: only one coroutine queries DB
+    $lock = $this->redis->set($lockKey, '1', ['NX', 'EX' => 5]);
+    if ($lock) {
+        try {
+            $order = ProductionOrder::find($id);
+            $ttl = 300 + random_int(0, 60); // jitter
+            $this->redis->setex($cacheKey, $ttl, serialize($order));
+            return $order;
+        } finally {
+            $this->redis->del($lockKey);
+        }
+    }
+
+    // Wait and retry
+    Coroutine::sleep(0.05);
+    return $this->getOrderWithLock($id);
+}
+```
+
+## 限流策略
+
+### 令牌桶 (API 级别)
+
+```php
+use Hyperf\RateLimit\Annotation\RateLimit;
+
+#[RateLimit(create: 1, capacity: 100, limitCallback: [RateLimitHandler::class, 'handle'])]
+public function list(): array
+{
+    // 每秒生成 1 个令牌，桶容量 100
+}
+```
+
+### 滑动窗口 (用户级别)
+
+```php
+// Redis ZSET sliding window
+public function isRateLimited(string $key, int $maxRequests, int $windowSeconds): bool
+{
+    $now = microtime(true);
+    $windowStart = $now - $windowSeconds;
+
+    $pipe = $this->redis->pipeline();
+    $pipe->zremrangebyscore($key, '-inf', (string) $windowStart);
+    $pipe->zadd($key, [(string) $now => $now]);
+    $pipe->zcard($key);
+    $pipe->expire($key, $windowSeconds);
+    $results = $pipe->exec();
+
+    return $results[2] > $maxRequests;
+}
+```
+
+## 消息队列削峰
+
+```
+高并发写入:
+  Client → API → Redis Queue (缓冲) → Consumer → MySQL
+
+适用场景:
+- 订单创建 (削峰)
+- 通知发送 (异步)
+- 日志记录 (解耦)
+- 数据统计 (批处理)
+```
+
+## 服务降级与熔断
+
+```php
+// 降级策略
+class OrderService
+{
+    public function getStatistics(int $orderId): array
+    {
+        try {
+            return $this->doGetStatistics($orderId);
+        } catch (\Throwable $e) {
+            // Fallback: return cached/default data
+            return $this->getCachedStatistics($orderId) ?? self::DEFAULT_STATS;
+        }
+    }
+}
+
+// 熔断器模式
+// Circuit Breaker: CLOSED → OPEN → HALF-OPEN → CLOSED
+// Use hyperf/circuit-breaker component
+```
+
+## 数据库扩展策略
+
+### 垂直拆分 (按业务域)
+
+```
+production_db  → 订单、子订单、发货
+permission_db  → 用户、角色、权限
+notification_db → 通知、消息
+```
+
+### 水平分片 (百万级后)
+
+```
+分片键: order_id
+分片策略: order_id % shard_count
+路由层: Hyperf 中间层 或 ProxySQL
+
+注意: 跨分片查询需要聚合层
+```
+
+## 部署扩展清单
+
+| 阶段 | QPS | 架构 |
+|------|-----|------|
+| 起步 | < 1K | 单机 Docker Compose |
+| 成长 | 1K ~ 10K | Nginx + 2~4 Hyperf + MySQL主从 + Redis Sentinel |
+| 规模 | 10K ~ 100K | K8s + HPA + MySQL Cluster + Redis Cluster |
+| 百万 | 100K+ | 微服务拆分 + 消息队列 + 分库分表 + CDN |
+
+## 模块通信规范
+
+> 与 `019-modular.mdc` 互补，本节侧重**跨服务/跨进程**通信；019 侧重**代码内模块边界**。
+
+### 通信方式选择矩阵
+
+| 场景 | 推荐方式 | 禁止方式 |
+|------|---------|---------|
+| 同进程同步调用 | 依赖注入 + 接口 | 全局静态方法 |
+| 跨进程异步 | AsyncQueue / RabbitMQ | 轮询 DB |
+| 实时推送 | WebSocket + Redis Pub/Sub | HTTP 长轮询 |
+| 定时任务 | Hyperf Crontab | sleep 循环 |
+| 跨服务数据 | REST API / 共享 Redis | 直连对方 DB |
+
+### 前端模块通信规范
+
+```
+组件间通信优先级（由低到高耦合）：
+  1. Props & Emits（父子）         — 首选
+  2. provide/inject（跨层级）       — 适合主题/配置
+  3. Pinia Store（状态共享）        — 跨模块全局状态
+  4. EventBus (mitt)              — 非父子一次性事件（慎用）
+  5. URL / Query Params            — 页面级状态持久化
+```
+
+```typescript
+// ✅ 推荐：通过 Pinia 跨模块共享状态
+// stores/notification.ts
+export const useNotificationStore = defineStore('notification', () => {
+  const unreadCount = ref(0)
+  const messages = ref<Notification[]>([])
+
+  function addNotification(msg: Notification): void {
+    messages.value.unshift(msg)
+    unreadCount.value++
+  }
+
+  return { unreadCount, messages, addNotification }
+})
+
+// 订单模块使用通知（无直接耦合）
+// views/order/composables/useOrderActions.ts
+const notificationStore = useNotificationStore()
+
+async function createOrder(data: OrderCreateForm): Promise<void> {
+  const order = await OrderApi.create(data)
+  // 通过 Store 通知，不直接调用通知组件
+  notificationStore.addNotification({
+    type: 'success',
+    title: '订单创建成功',
+    content: `订单号 ${order.orderNo} 已提交`,
+  })
+}
+```
+
+### WebSocket 模块通信
+
+```typescript
+// src/composables/useWebSocket.ts — 全局单例 WebSocket 管理
+// 所有模块订阅自己关心的消息类型，不感知连接细节
+export const wsClient = useWebSocket()
+
+// 订单模块：只监听订单相关消息
+const { on, off } = useWebSocket()
+on('order.status_changed', (payload) => {
+  orderStore.updateOrderStatus(payload.orderId, payload.status)
+})
+
+// 通知模块：只监听通知消息
+on('notification.new', (payload) => {
+  notificationStore.addNotification(payload)
+})
+```
+
+## 性能基线
+
+| 指标 | 目标值 | 监控方式 |
+|------|--------|---------|
+| API P99 延迟 | < 200ms | Prometheus + Grafana |
+| 数据库查询 | < 50ms | 慢查询日志 |
+| Redis 命令 | < 5ms | Redis INFO |
+| 缓存命中率 | > 85% | 自定义指标 |
+| 错误率 | < 0.1% | Sentry / 日志 |
+| 可用性 | 99.9% | 健康检查 + 告警 |
diff --git a/.cursor/rules/references/018-responsive-deep.md b/.cursor/rules/references/018-responsive-deep.md
new file mode 100644
index 0000000..325ecd7
--- /dev/null
+++ b/.cursor/rules/references/018-responsive-deep.md
@@ -0,0 +1,387 @@
+# 018-responsive.mdc (Deep Reference)
+
+> 该文件为原始详细规范归档，供 Tier 3 按需读取。
+
+---
+
+
+# 📱 Responsive Design & Multi-Device Standards
+
+## 断点体系（与 Tailwind 统一）
+
+> **⚠️ 双前端区分**：本文件中的 Element Plus 移动端适配内容**仅适用于管理端** (`Case-Database-Frontend-admin/`)。
+> 用户端 (`Case-Database-Frontend-user/`) 使用 Headless UI + Tailwind CSS，**禁止引入 Element Plus**。
+
+| 断点 | Tailwind 前缀 | 最小宽度 | 目标设备 |
+|------|--------------|---------|---------|
+| 默认 | (无前缀) | 0px | 手机竖屏 (< 640px) |
+| sm | `sm:` | 640px | 手机横屏 / 小平板 |
+| md | `md:` | 768px | 平板竖屏 (iPad) |
+| lg | `lg:` | 1024px | 平板横屏 / 小屏笔记本 |
+| xl | `xl:` | 1280px | 桌面 |
+| 2xl | `2xl:` | 1536px | 大屏桌面 / 4K |
+
+> **原则**：移动优先（Mobile-First）— 先写手机样式，用断点向上覆盖。
+
+```html
+<!-- ✅ 移动优先：默认手机，逐步增强 -->
+<div class="p-4 md:p-6 xl:p-8 grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-4">
+  <!-- 手机 1列 → 平板 2列 → 桌面 3列 -->
+</div>
+
+<!-- ❌ 桌面优先（禁用）：max-* 限制往下适配 -->
+<div class="grid grid-cols-3 max-md:grid-cols-1">...</div>
+```
+
+---
+
+## 布局组件响应式模式
+
+### 侧边栏布局（后台管理系统标准模式）
+
+```vue
+<!-- src/layouts/AppLayout.vue -->
+<template>
+  <div class="flex h-screen overflow-hidden bg-gray-50 dark:bg-gray-900">
+    <!-- 遮罩层：移动端打开侧边栏时显示 -->
+    <Transition name="fade">
+      <div
+        v-if="isMobile && sidebarOpen"
+        class="fixed inset-0 z-20 bg-black/50"
+        @click="sidebarOpen = false"
+      />
+    </Transition>
+
+    <!-- 侧边栏：桌面固定，移动端抽屉式 -->
+    <aside
+      :class="[
+        'fixed lg:relative z-30 h-full transition-transform duration-300',
+        'w-64 bg-white dark:bg-gray-800 border-r border-gray-200 dark:border-gray-700',
+        isMobile && !sidebarOpen ? '-translate-x-full' : 'translate-x-0',
+      ]"
+    >
+      <ArtSidebarMenu />
+    </aside>
+
+    <!-- 主内容区 -->
+    <div class="flex-1 flex flex-col min-w-0 overflow-hidden">
+      <!-- 顶部导航 -->
+      <header class="h-14 md:h-16 flex items-center px-4 md:px-6 border-b bg-white dark:bg-gray-800">
+        <!-- 移动端：汉堡菜单按钮 -->
+        <button
+          class="lg:hidden mr-3 p-2 rounded-lg text-gray-500 hover:bg-gray-100"
+          aria-label="打开菜单"
+          @click="sidebarOpen = !sidebarOpen"
+        >
+          <el-icon :size="20"><Menu /></el-icon>
+        </button>
+        <ArtHeader />
+      </header>
+
+      <!-- 页面内容 -->
+      <main class="flex-1 overflow-auto">
+        <div class="p-4 md:p-6 xl:p-8 max-w-screen-2xl mx-auto">
+          <router-view />
+        </div>
+      </main>
+    </div>
+  </div>
+</template>
+
+<script setup>
+const { isMobile } = useDevice()
+const sidebarOpen = ref(false)
+
+// 路由变化时关闭移动端侧边栏
+const route = useRoute()
+watch(() => route.path, () => {
+  if (isMobile.value) sidebarOpen.value = false
+})
+</script>
+```
+
+### `useDevice` Composable
+
+```typescript
+// src/composables/useDevice.ts
+export function useDevice() {
+  const width = ref(window.innerWidth)
+
+  const handleResize = useDebounceFn(() => {
+    width.value = window.innerWidth
+  }, 100)
+
+  onMounted(() => window.addEventListener('resize', handleResize))
+  onUnmounted(() => window.removeEventListener('resize', handleResize))
+
+  return {
+    width: readonly(width),
+    isMobile: computed(() => width.value < 768),
+    isTablet: computed(() => width.value >= 768 && width.value < 1024),
+    isDesktop: computed(() => width.value >= 1024),
+    isTouch: computed(() => 'ontouchstart' in window),
+  }
+}
+```
+
+---
+
+## Element Plus 移动端适配（仅管理端）
+
+### 组件尺寸策略
+
+```vue
+<script setup>
+const { isMobile } = useDevice()
+const elSize = computed(() => (isMobile.value ? 'small' : 'default'))
+</script>
+
+<template>
+  <!-- ✅ 根据设备自适应 size -->
+  <el-form :size="elSize">
+    <el-input :size="elSize" />
+    <el-button :size="elSize" type="primary">提交</el-button>
+  </el-form>
+
+  <!-- ✅ 表格移动端简化列 -->
+  <el-table :data="tableData">
+    <el-table-column prop="name" label="名称" min-width="120" />
+    <el-table-column v-if="!isMobile" prop="createdAt" label="创建时间" width="160" />
+    <el-table-column v-if="!isMobile" prop="status" label="状态" width="100" />
+    <!-- 移动端合并展示 -->
+    <el-table-column v-if="isMobile" label="详情" min-width="200">
+      <template #default="{ row }">
+        <div class="text-sm">{{ row.status }} · {{ row.createdAt }}</div>
+      </template>
+    </el-table-column>
+  </el-table>
+</template>
+```
+
+### 对话框适配
+
+```vue
+<!-- ✅ 移动端全屏对话框 -->
+<el-dialog
+  v-model="dialogVisible"
+  :fullscreen="isMobile"
+  :width="isMobile ? '100%' : '600px'"
+  :class="{ 'rounded-t-2xl': isMobile }"
+>
+```
+
+### 分页适配
+
+```vue
+<!-- ✅ 移动端简化分页 -->
+<el-pagination
+  v-model:current-page="currentPage"
+  v-model:page-size="pageSize"
+  :layout="isMobile ? 'prev, pager, next' : 'total, sizes, prev, pager, next, jumper'"
+  :pager-count="isMobile ? 3 : 7"
+  :page-sizes="isMobile ? [10, 20] : [10, 20, 50, 100]"
+  :total="total"
+/>
+```
+
+### 表单布局
+
+```vue
+<!-- ✅ 移动端垂直布局，桌面水平布局 -->
+<el-form
+  :label-position="isMobile ? 'top' : 'right'"
+  :label-width="isMobile ? 'auto' : '100px'"
+>
+```
+
+---
+
+## 触摸与手势优化
+
+### 最小触摸目标尺寸
+
+```scss
+// src/assets/styles/touch.scss
+// 根据 WCAG 2.5.5，触摸目标最小 44×44px
+.touch-target {
+  min-width: 44px;
+  min-height: 44px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+@media (hover: none) and (pointer: coarse) {
+  // 触屏设备：增大可点击区域
+  .el-button {
+    min-height: 44px;
+    padding-left: 16px;
+    padding-right: 16px;
+  }
+
+  .el-input__wrapper {
+    min-height: 44px;
+  }
+}
+```
+
+### 滑动手势（移动端列表操作）
+
+```typescript
+// src/composables/useSwipeAction.ts
+export function useSwipeAction(onDelete: () => void, onEdit: () => void) {
+  const startX = ref(0)
+  const offsetX = ref(0)
+  const THRESHOLD = 80
+
+  function onTouchStart(e: TouchEvent) {
+    startX.value = e.touches[0].clientX
+  }
+
+  function onTouchMove(e: TouchEvent) {
+    const diff = e.touches[0].clientX - startX.value
+    offsetX.value = Math.max(-160, Math.min(0, diff)) // 最多滑动 160px
+  }
+
+  function onTouchEnd() {
+    if (offsetX.value < -THRESHOLD) {
+      // 滑过阈值：显示操作按钮
+    } else {
+      offsetX.value = 0 // 弹回
+    }
+  }
+
+  return { offsetX, onTouchStart, onTouchMove, onTouchEnd }
+}
+```
+
+---
+
+## 图片与媒体响应式
+
+```vue
+<template>
+  <!-- ✅ 响应式图片：不同分辨率加载不同尺寸 -->
+  <picture>
+    <source media="(min-width: 1280px)" srcset="/img/banner-xl.webp" />
+    <source media="(min-width: 768px)" srcset="/img/banner-md.webp" />
+    <img src="/img/banner-sm.webp" alt="Banner" class="w-full h-auto object-cover" loading="lazy" />
+  </picture>
+
+  <!-- ✅ 使用 Intersection Observer 懒加载 -->
+  <img
+    v-lazy="imageUrl"
+    alt="产品图片"
+    class="w-full aspect-square object-cover rounded-lg"
+    :class="{ 'animate-pulse bg-gray-200': !isLoaded }"
+  />
+</template>
+```
+
+---
+
+## 字体与文字排版
+
+```scss
+// 流式字体大小：随屏幕宽度线性变化
+:root {
+  --font-base: clamp(14px, 1vw + 12px, 16px);
+  --font-heading: clamp(20px, 3vw + 10px, 36px);
+}
+
+body { font-size: var(--font-base); }
+h1 { font-size: var(--font-heading); }
+
+// 行高：移动端更宽松（小屏阅读舒适度）
+p {
+  line-height: 1.6;
+
+  @media (max-width: 767px) {
+    line-height: 1.8;
+  }
+}
+```
+
+---
+
+## 安全区域（刘海屏 / 全面屏）
+
+```css
+/* 底部安全区域（iOS 全面屏 Home Bar）*/
+.bottom-nav {
+  padding-bottom: env(safe-area-inset-bottom, 16px);
+}
+
+/* 顶部安全区域（刘海屏）*/
+.top-bar {
+  padding-top: env(safe-area-inset-top, 0px);
+}
+```
+
+```typescript
+// tailwind.config.ts — 添加安全区域工具类
+theme: {
+  extend: {
+    padding: {
+      'safe-bottom': 'env(safe-area-inset-bottom, 16px)',
+      'safe-top': 'env(safe-area-inset-top, 0px)',
+    },
+  },
+},
+```
+
+---
+
+## 响应式测试矩阵
+
+| 设备 | 分辨率 | 断点 | 关键功能检查 |
+|------|--------|------|------------|
+| iPhone SE (3代) | 375×667 | xs | 侧边栏抽屉、表单垂直布局 |
+| iPhone 14 Pro | 393×852 | xs | 安全区域、全面屏底部导航 |
+| iPhone 14 Pro Max | 430×932 | sm | 横屏布局、键盘遮挡处理 |
+| iPad (10代) | 820×1180 | md | 平板双栏、对话框宽度 |
+| iPad Pro 12.9" | 1024×1366 | lg | 分页组件、表格完整列 |
+| MacBook Air 13" | 1280×800 | xl | 完整侧边栏、桌面表格 |
+| 4K 显示器 | 1920×1080 | 2xl | 最大宽度限制、留白 |
+
+### 测试脚本（Playwright）
+
+```typescript
+// tests/responsive.spec.ts
+import { test, expect } from '@playwright/test'
+
+const viewports = [
+  { name: 'mobile', width: 375, height: 812 },
+  { name: 'tablet', width: 768, height: 1024 },
+  { name: 'desktop', width: 1280, height: 800 },
+]
+
+for (const vp of viewports) {
+  test(`dashboard layout on ${vp.name}`, async ({ page }) => {
+    await page.setViewportSize({ width: vp.width, height: vp.height })
+    await page.goto('/dashboard')
+
+    if (vp.name === 'mobile') {
+      // 移动端：侧边栏默认隐藏
+      await expect(page.locator('aside')).toHaveCSS('transform', 'matrix(1, 0, 0, 1, -256, 0)')
+      // 汉堡按钮可见
+      await expect(page.locator('[aria-label="打开菜单"]')).toBeVisible()
+    } else {
+      // 平板/桌面：侧边栏默认显示
+      await expect(page.locator('aside')).toBeVisible()
+    }
+  })
+}
+```
+
+---
+
+## 规则
+
+- 所有新页面必须在 375px / 768px / 1280px 三个断点下验证
+- 禁止使用 `px` 设置字体大小（用 `rem` 或 Tailwind 文本类）
+- 触摸目标最小 44×44px
+- 禁止使用 `:hover` 作为唯一交互反馈（移动端无 hover）
+- 管理端：所有 `el-dialog` 必须处理移动端 `fullscreen` 属性（用户端使用 Headless UI Dialog）
+- 图片必须设置 `loading="lazy"` 和 `aspect-ratio`（防止布局抖动 CLS）
+- 横屏（landscape）模式下的布局需专门测试
diff --git a/.cursor/rules/references/019-modular-deep.md b/.cursor/rules/references/019-modular-deep.md
new file mode 100644
index 0000000..93a9c21
--- /dev/null
+++ b/.cursor/rules/references/019-modular-deep.md
@@ -0,0 +1,479 @@
+# 019-modular.mdc (Deep Reference)
+
+> 该文件为原始详细规范归档，供 Tier 3 按需读取。
+
+---
+
+
+# 🧩 Modular Architecture Standards
+
+## 核心原则
+
+| 原则 | 说明 | 违反案例 |
+|------|------|---------|
+| **单一职责** | 一个文件只做一件事 | 1000 行的 `index.vue` 包含业务+状态+样式 |
+| **高内聚低耦合** | 同模块内紧密，跨模块通过接口 | 直接引用另一模块的内部 Service |
+| **依赖方向单一** | 只允许 `UI → Service → Repository → Model` | Service 引用 Controller |
+| **显式边界** | 模块通过公开的 index.ts 暴露 API | `import { InternalHelper } from '../order/utils/internal'` |
+| **禁止循环依赖** | A 不能引用 B 的同时 B 引用 A | order 模块和 user 模块互相引用 |
+
+---
+
+## 前端模块划分
+
+### 标准目录结构
+
+```
+src/
+├── api/                     # API 请求层（按模块分文件）
+│   ├── user.ts              # 用户相关接口
+│   ├── order.ts             # 订单相关接口
+│   ├── permission.ts        # 权限相关接口
+│   └── index.ts             # 统一导出
+│
+├── composables/             # 可复用逻辑（按功能命名 use*.ts）
+│   ├── useTable.ts          # 表格通用逻辑
+│   ├── useForm.ts           # 表单通用逻辑
+│   ├── useAuth.ts           # 认证状态
+│   ├── useDevice.ts         # 设备检测
+│   ├── usePermission.ts     # 权限检查
+│   └── useWebSocket.ts      # WebSocket 管理
+│
+├── stores/                  # Pinia 状态（按模块分文件）
+│   ├── user.ts
+│   ├── menu.ts
+│   ├── setting.ts
+│   └── index.ts             # 统一导出
+│
+├── components/              # 全局公共组件
+│   ├── ArtTable/            # 每个复杂组件独立目录
+│   │   ├── index.vue        # 主组件
+│   │   ├── TableToolbar.vue # 子组件（内聚）
+│   │   ├── TablePagination.vue
+│   │   └── types.ts         # 组件专属类型
+│   ├── ArtForm/
+│   └── ArtChart/
+│
+├── views/                   # 页面（按业务域分目录）
+│   ├── order/               # 订单业务域
+│   │   ├── index.vue        # 列表页
+│   │   ├── detail.vue       # 详情页
+│   │   ├── components/      # 页面专属组件（不对外）
+│   │   │   ├── OrderCard.vue
+│   │   │   └── OrderTimeline.vue
+│   │   ├── composables/     # 页面专属 composable
+│   │   │   └── useOrderFilter.ts
+│   │   └── types.ts         # 页面专属类型
+│   │
+│   ├── user/
+│   ├── permission/
+│   └── dashboard/
+│
+├── utils/                   # 纯工具函数（无副作用）
+│   ├── format.ts            # 格式化
+│   ├── validate.ts          # 校验
+│   ├── crypto.ts            # 加密工具
+│   └── date.ts              # 日期工具
+│
+├── directives/              # 自定义指令（每个指令独立文件）
+│   ├── auth.ts              # v-auth
+│   ├── roles.ts             # v-roles
+│   └── index.ts             # 统一注册
+│
+└── types/                   # 全局类型定义
+    ├── api.ts               # API 响应/请求类型
+    ├── models.ts            # 业务实体类型
+    └── common.ts            # 通用类型
+```
+
+### 文件拆分阈值
+
+| 指标 | 警告 | 必须拆分 |
+|------|------|---------|
+| 文件行数 | > 200 行 | > 400 行 |
+| 组件内 ref 数量 | > 8 个 | > 15 个 |
+| 单个 composable 行数 | > 100 行 | > 200 行 |
+| 单个 store 行数 | > 150 行 | > 300 行 |
+
+### 组件拆分决策树
+
+```
+一个 .vue 文件是否应该拆分？
+  ├─ 文件 > 200 行？ → 考虑拆分
+  ├─ 包含多个独立 UI 块？ → 拆分为子组件
+  ├─ 业务逻辑超过 50 行？ → 提取为 composable
+  ├─ 该组件在 > 2 个地方复用？ → 移至 components/
+  └─ 否 → 保持不变
+```
+
+---
+
+## 后端模块划分（Hyperf DDD）
+
+### 标准目录结构
+
+```
+app/
+├── Controller/          # HTTP 入口层（只做参数接收 + 响应格式化）
+│   ├── OrderController.php
+│   ├── UserController.php
+│   └── Traits/
+│       └── ApiResponse.php   # 响应格式 Trait
+│
+├── Service/             # 业务逻辑层（核心业务规则）
+│   ├── OrderService.php
+│   ├── UserService.php
+│   └── Dto/             # 数据传输对象
+│       ├── OrderCreateDto.php
+│       └── OrderListDto.php
+│
+├── Repository/          # 数据访问层（数据库/缓存操作）
+│   ├── OrderRepository.php
+│   ├── UserRepository.php
+│   └── Contracts/       # Repository 接口
+│       └── OrderRepositoryInterface.php
+│
+├── Model/               # Eloquent ORM 模型
+│   ├── Order.php
+│   ├── User.php
+│   └── Traits/          # 可复用模型 Trait
+│       ├── HasCreator.php
+│       ├── HasSoftDeletes.php
+│       └── HasDataPermission.php
+│
+├── Request/             # 表单验证（每个操作独立 Request）
+│   ├── Order/
+│   │   ├── CreateOrderRequest.php
+│   │   ├── UpdateOrderRequest.php
+│   │   └── ListOrderRequest.php
+│   └── User/
+│
+├── Event/               # 事件定义（命名：名词+动词过去式）
+│   ├── OrderCreated.php
+│   ├── OrderStatusChanged.php
+│   └── UserLoggedIn.php
+│
+├── Listener/            # 事件监听器（一个事件一个 Listener）
+│   ├── SendOrderNotification.php
+│   ├── LogOrderStatusChange.php
+│   └── UpdateUserLastLogin.php
+│
+├── Middleware/          # 中间件（每个职责独立文件）
+│   ├── AuthMiddleware.php
+│   ├── PermissionMiddleware.php
+│   ├── RateLimitMiddleware.php
+│   └── AntiScrapingMiddleware.php
+│
+├── Exception/           # 异常定义（每类业务一个异常）
+│   ├── BusinessException.php
+│   ├── AuthException.php
+│   ├── PermissionException.php
+│   └── Handler/
+│       └── AppExceptionHandler.php
+│
+├── Job/                 # 异步任务（AsyncQueue）
+│   ├── SendNotificationJob.php
+│   └── GenerateReportJob.php
+│
+└── Command/             # 命令行工具
+    └── SyncPermissionCommand.php
+```
+
+### 各层职责边界
+
+```php
+// ✅ Controller — 只做参数绑定 + 调用 Service + 格式化响应
+class OrderController
+{
+    public function store(CreateOrderRequest $request): array
+    {
+        $dto = CreateOrderDto::fromRequest($request);
+        $order = $this->orderService->create($dto);
+        return $this->success(OrderResource::make($order));
+    }
+}
+
+// ✅ Service — 只做业务逻辑，调用 Repository 取数据
+class OrderService
+{
+    public function create(CreateOrderDto $dto): Order
+    {
+        // 业务规则：库存检查
+        $this->inventoryService->checkStock($dto->productId, $dto->quantity);
+
+        $order = $this->orderRepository->create($dto->toArray());
+
+        // 发事件（不直接发通知，解耦）
+        event(new OrderCreated($order));
+
+        return $order;
+    }
+}
+
+// ✅ Repository — 只做数据库操作，不包含业务规则
+class OrderRepository
+{
+    public function create(array $data): Order
+    {
+        return Order::create($data);
+    }
+
+    public function findWithItems(int $id): ?Order
+    {
+        return Order::with(['items', 'creator'])->find($id);
+    }
+}
+
+// ❌ 反模式：Controller 直接操作 Model
+class BadController
+{
+    public function store(Request $request): array
+    {
+        $order = Order::create($request->all()); // ← 跳过 Service 层
+        Mail::to($order->user)->send(new OrderMail($order)); // ← Controller 不应发邮件
+        return ['data' => $order];
+    }
+}
+```
+
+### 模块通信规范
+
+| 通信方式 | 使用场景 | 实现 |
+|---------|---------|------|
+| **直接依赖注入** | 同层级调用（Service → Service） | `__construct` 注入 |
+| **事件系统** | 跨模块解耦通知 | `event(new OrderCreated($order))` |
+| **消息队列** | 耗时操作异步化 | `AsyncQueue::push(new SendEmailJob(...))` |
+| **共享 Repository** | 跨模块读取数据 | 注入对方 Repository（只读） |
+| **禁止** | 跨模块调用内部方法 | ✘ `$userService->_internalCalc()` |
+
+```php
+// ✅ 事件解耦：订单模块不直接依赖通知模块
+// app/Event/OrderCreated.php
+class OrderCreated
+{
+    public function __construct(public readonly Order $order) {}
+}
+
+// app/Listener/SendOrderNotification.php（通知模块监听）
+#[Listener]
+class SendOrderNotification implements ListenerInterface
+{
+    public function listen(): array
+    {
+        return [OrderCreated::class];
+    }
+
+    public function process(object $event): void
+    {
+        $this->notificationService->notify($event->order->user_id, 'order_created', [
+            'order_id' => $event->order->id,
+        ]);
+    }
+}
+```
+
+---
+
+## 禁止循环依赖
+
+```
+依赖方向规则（严格单向）：
+
+Controller → Service → Repository → Model
+                ↓
+            Event → Listener
+                ↓
+            Job（异步）
+
+✅ Service 可以依赖 Repository
+✅ Service 可以发布 Event
+✅ Listener 可以依赖 Service
+❌ Repository 不能依赖 Service
+❌ Model 不能依赖 Service/Repository
+❌ Event 不能依赖 Service（Event 是纯数据）
+```
+
+### 检测循环依赖
+
+```bash
+# PHP 项目
+composer require maglnet/composer-require-checker --dev
+
+# 前端项目（ESLint 插件）
+npm install eslint-plugin-import --save-dev
+# .eslintrc 中配置 import/no-cycle
+```
+
+---
+
+## Vue 组件模块化规范
+
+### 组件分类
+
+| 类型 | 位置 | 命名 | 特征 |
+|------|------|------|------|
+| **基础组件** | `src/components/` | `Art*` | 无业务逻辑，高复用 |
+| **业务组件** | `src/views/{domain}/components/` | `{Domain}*` | 包含业务，不跨域复用 |
+| **页面组件** | `src/views/{domain}/index.vue` | 路由直接映射 | 整合子组件和 store |
+| **布局组件** | `src/layouts/` | `*Layout` | 全局页面框架 |
+
+### 单文件组件结构（SFC）
+
+```vue
+<!-- 标准顺序：script → template → style -->
+<script setup>
+// 1. 导入（分组排列）
+import { computed, ref } from 'vue'        // Vue core
+import { useRouter } from 'vue-router'      // Router
+import { storeToRefs } from 'pinia'        // Pinia
+import { useOrderStore } from '@/stores/order'  // Stores
+import { useTable } from '@/composables/useTable'  // Composables
+import { OrderApi } from '@/api/order'      // API
+import OrderCard from './components/OrderCard.vue'  // Local components
+
+// 2. Props & Emits（JS 对象语法）
+const props = defineProps({
+  domain: { type: String, required: true },
+  readonly: { type: Boolean, default: false },
+})
+
+const emit = defineEmits(['updated', 'deleted'])
+
+// 3. Store
+const orderStore = useOrderStore()
+const { orders, loading } = storeToRefs(orderStore)
+
+// 4. Composable（复杂逻辑提取）
+const { tableData, pagination, fetchData } = useTable(OrderApi.list)
+
+// 5. 本地状态（按功能分组，加注释分隔）
+// --- Dialog state ---
+const dialogVisible = ref(false)
+const currentOrder = ref(null)
+
+// --- Filter state ---
+const searchForm = ref({ keyword: '', status: '' })
+
+// 6. Computed
+const filteredOrders = computed(() =>
+  orders.value.filter((o) => o.domain === props.domain)
+)
+
+// 7. Methods（按功能分组）
+function openDialog(order) {
+  currentOrder.value = order
+  dialogVisible.value = true
+}
+
+async function handleDelete(id) {
+  await orderStore.delete(id)
+  emit('deleted', id)
+}
+
+// 8. Lifecycle
+onMounted(() => fetchData())
+</script>
+
+<template>
+  <!-- 模板只做渲染，不包含复杂逻辑 -->
+</template>
+
+<style scoped>
+/* 组件作用域样式 */
+</style>
+```
+
+---
+
+## Composable 拆分规范
+
+```typescript
+// ✅ 单一职责：useOrderFilter 只负责过滤逻辑
+// src/views/order/composables/useOrderFilter.ts
+export function useOrderFilter(orders) {
+  const status = ref('')
+  const keyword = ref('')
+  const dateRange = ref(null)
+
+  const filtered = computed(() => {
+    return orders.value.filter((order) => {
+      if (status.value && order.status !== status.value) return false
+      if (keyword.value && !order.orderNo.includes(keyword.value)) return false
+      if (dateRange.value) {
+        const [start, end] = dateRange.value
+        if (order.createdAt < start || order.createdAt > end) return false
+      }
+      return true
+    })
+  })
+
+  function reset() {
+    status.value = ''
+    keyword.value = ''
+    dateRange.value = null
+  }
+
+  return { status, keyword, dateRange, filtered, reset }
+}
+
+// ❌ 反模式：把表格、过滤、编辑逻辑都放在一个 composable
+export function useOrderPage() { // 太大了
+  // ... 300 行混合逻辑
+}
+```
+
+---
+
+## 前端导入层级边界
+
+```
+导入方向规则（严格单向）：
+
+views/ → composables/ → stores/ → api/ → utils/
+  │          │
+  │          └→ components/（仅消费，不反向引用 views/）
+  └→ components/
+
+✅ views/ 可以引用 composables/、stores/、api/、components/
+✅ composables/ 可以引用 stores/、api/、utils/
+✅ stores/ 可以引用 api/、utils/
+✅ components/ 可以引用 composables/、utils/（通用组件不引用 stores/）
+❌ components/core/ 不得引用 stores/（通用组件不依赖业务状态）
+❌ api/ 不得引用 stores/ 或 views/
+❌ utils/ 不得引用任何其他层（纯函数，无副作用）
+❌ 跨业务域直接引用内部组件（通过公开 index.ts 导出）
+```
+
+**ESLint 配置建议**：
+
+```typescript
+// .eslintrc — import/no-restricted-paths
+{
+  rules: {
+    'import/no-restricted-paths': ['error', {
+      zones: [
+        { target: './src/utils', from: './src/stores' },
+        { target: './src/utils', from: './src/api' },
+        { target: './src/api', from: './src/stores' },
+        { target: './src/components/core', from: './src/stores' },
+      ],
+    }],
+  },
+}
+```
+
+---
+
+## 规则汇总
+
+- 单个 `.vue` 文件超过 200 行必须拆分，超过 400 行禁止提交
+- 业务逻辑超过 50 行必须提取为 composable
+- Composable 必须以 `use` 开头，返回对象必须解构友好
+- 每个 API 模块对应一个文件（`src/api/{module}.ts`）
+- 禁止在 Controller 中操作 Model（必须经过 Service + Repository）
+- 禁止在 Model 中调用 Service（保持 Model 纯净）
+- 禁止跨业务域直接引用内部组件（通过公开 `index.ts` 导出）
+- 事件名必须是：`{域}` + `{动作的过去时}` (如 `OrderCreated`)
+- 每次 PR 提交前运行 `eslint --rule import/no-cycle` 检查循环依赖
+- 前端导入方向必须单向：`views → composables → stores → api → utils`
+- 通用组件 (`components/core/`) 禁止依赖业务状态 (`stores/`)
diff --git a/.cursor/rules/references/023-accessibility-deep.md b/.cursor/rules/references/023-accessibility-deep.md
new file mode 100644
index 0000000..c12faff
--- /dev/null
+++ b/.cursor/rules/references/023-accessibility-deep.md
@@ -0,0 +1,442 @@
+# 023-accessibility.mdc (Deep Reference)
+
+> 该文件为原始详细规范归档，供 Tier 3 按需读取。
+
+---
+
+
+# ♿ Accessibility (A11y) — WCAG AA Standards
+
+> **⚠️ 双前端区分**：本文件中的 `el-*` 组件示例**仅适用于管理端** (`Case-Database-Frontend-admin/`)。
+> 用户端 (`Case-Database-Frontend-user/`) 使用 Headless UI + Tailwind CSS 实现同等无障碍标准，**禁止引入 Element Plus**。
+> Headless UI 组件天然内置 ARIA 属性，用户端可直接使用。
+
+## WCAG AA 基线要求
+
+| 原则 | 要求 | 检测方法 |
+|------|------|---------|
+| **可感知** | 图片有 alt；颜色对比度 ≥ 4.5:1 (文本) / 3:1 (大文本) | Axe DevTools / Lighthouse |
+| **可操作** | 所有功能可键盘访问；无键盘陷阱；跳转链接 | Tab 键手动测试 |
+| **可理解** | 语言声明；错误提示清晰；一致导航 | 屏幕阅读器测试 |
+| **健壮性** | 语义化 HTML；ARIA 正确使用 | W3C Validator |
+
+---
+
+## 语义化 HTML（Vue 3）
+
+```vue
+<template>
+  <!-- ✅ 语义化页面结构 -->
+  <div id="app">
+    <!-- 跳转链接：键盘用户快速跳过导航 -->
+    <a href="#main-content" class="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-white focus:rounded">
+      跳转到主要内容
+    </a>
+
+    <header role="banner">
+      <nav role="navigation" aria-label="主导航">
+        <ul>
+          <li><router-link to="/dashboard">首页</router-link></li>
+          <li><router-link to="/orders">订单</router-link></li>
+        </ul>
+      </nav>
+    </header>
+
+    <main id="main-content" role="main" tabindex="-1">
+      <router-view />
+    </main>
+
+    <footer role="contentinfo">
+      <p>© 2025 Company Name</p>
+    </footer>
+  </div>
+</template>
+```
+
+---
+
+## 键盘导航规范
+
+### 焦点管理
+
+```typescript
+// src/composables/useFocusTrap.ts
+// 对话框焦点捕获：阻止 Tab 跳出对话框
+export function useFocusTrap(containerRef: Ref<HTMLElement | null>) {
+  function trapFocus(event: KeyboardEvent): void {
+    if (!containerRef.value || event.key !== 'Tab') return
+
+    const focusable = containerRef.value.querySelectorAll<HTMLElement>(
+      'a[href], button:not([disabled]), input:not([disabled]), select, textarea, [tabindex]:not([tabindex="-1"])'
+    )
+    const first = focusable[0]
+    const last = focusable[focusable.length - 1]
+
+    if (event.shiftKey) {
+      if (document.activeElement === first) {
+        last.focus()
+        event.preventDefault()
+      }
+    } else {
+      if (document.activeElement === last) {
+        first.focus()
+        event.preventDefault()
+      }
+    }
+  }
+
+  onMounted(() => document.addEventListener('keydown', trapFocus))
+  onUnmounted(() => document.removeEventListener('keydown', trapFocus))
+}
+```
+
+```typescript
+// src/composables/useFocusReturn.ts
+// 对话框关闭后，焦点回到触发元素
+export function useFocusReturn() {
+  const triggerEl = ref<HTMLElement | null>(null)
+
+  function saveTrigger(): void {
+    triggerEl.value = document.activeElement as HTMLElement
+  }
+
+  function restoreFocus(): void {
+    nextTick(() => triggerEl.value?.focus())
+  }
+
+  return { saveTrigger, restoreFocus }
+}
+```
+
+### 键盘快捷键
+
+```typescript
+// src/composables/useKeyboard.ts
+export function useKeyboard(handlers: Record<string, () => void>) {
+  function handleKeydown(event: KeyboardEvent): void {
+    const key = [
+      event.ctrlKey && 'Ctrl',
+      event.altKey && 'Alt',
+      event.shiftKey && 'Shift',
+      event.key,
+    ]
+      .filter(Boolean)
+      .join('+')
+
+    handlers[key]?.()
+  }
+
+  onMounted(() => document.addEventListener('keydown', handleKeydown))
+  onUnmounted(() => document.removeEventListener('keydown', handleKeydown))
+}
+
+// 使用示例
+useKeyboard({
+  'Escape': () => closeDialog(),
+  'Ctrl+s': () => saveForm(),
+  'Ctrl+/': () => toggleHelp(),
+})
+```
+
+---
+
+## ARIA 模式库（Vue 3 组件）
+
+### 模态框
+
+```vue
+<!-- src/components/ArtDialog/index.vue -->
+<template>
+  <Teleport to="body">
+    <Transition name="dialog">
+      <div
+        v-if="modelValue"
+        ref="dialogRef"
+        role="dialog"
+        aria-modal="true"
+        :aria-labelledby="titleId"
+        :aria-describedby="descId"
+        class="fixed inset-0 z-50 flex items-center justify-center"
+        @keydown.esc="$emit('update:modelValue', false)"
+      >
+        <!-- 背景遮罩 -->
+        <div class="absolute inset-0 bg-black/50" aria-hidden="true" @click="$emit('update:modelValue', false)" />
+
+        <!-- 对话框内容 -->
+        <div class="relative bg-white rounded-xl p-6 max-w-md w-full mx-4">
+          <h2 :id="titleId" class="text-xl font-semibold">{{ title }}</h2>
+          <p v-if="description" :id="descId" class="mt-2 text-gray-600">{{ description }}</p>
+
+          <button
+            class="absolute top-4 right-4 text-gray-400 hover:text-gray-600 focus:ring-2 focus:ring-primary-500 rounded"
+            aria-label="关闭对话框"
+            @click="$emit('update:modelValue', false)"
+          >
+            <el-icon><Close /></el-icon>
+          </button>
+
+          <slot />
+        </div>
+      </div>
+    </Transition>
+  </Teleport>
+</template>
+
+<script setup>
+import { useFocusTrap } from '@/composables/useFocusTrap'
+import { useFocusReturn } from '@/composables/useFocusReturn'
+
+const props = defineProps<{ modelValue: boolean; title: string; description?: string }>()
+const emit = defineEmits<{ 'update:modelValue': [value: boolean] }>()
+
+const titleId = useId()  // Vue 3.5+ 内置
+const descId = useId()
+const dialogRef = ref<HTMLElement | null>(null)
+
+useFocusTrap(dialogRef)
+const { saveTrigger, restoreFocus } = useFocusReturn()
+
+watch(() => props.modelValue, (isOpen) => {
+  if (isOpen) {
+    saveTrigger()
+    nextTick(() => {
+      // 聚焦第一个可交互元素
+      const firstFocusable = dialogRef.value?.querySelector<HTMLElement>(
+        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+      )
+      firstFocusable?.focus()
+    })
+  } else {
+    restoreFocus()
+  }
+})
+</script>
+```
+
+### 加载状态
+
+```vue
+<template>
+  <!-- ✅ 加载中的按钮（屏幕阅读器可感知） -->
+  <button
+    :aria-busy="isLoading"
+    :aria-disabled="isLoading"
+    :disabled="isLoading"
+    @click="handleSubmit"
+  >
+    <el-icon v-if="isLoading" class="animate-spin" aria-hidden="true"><Loading /></el-icon>
+    <span>{{ isLoading ? '提交中...' : '提交' }}</span>
+  </button>
+
+  <!-- ✅ 页面级加载状态 -->
+  <div aria-live="polite" aria-atomic="true" class="sr-only">
+    {{ isLoading ? '正在加载数据，请稍候' : '' }}
+  </div>
+
+  <!-- ✅ 骨架屏 -->
+  <div v-if="isLoading" role="status" aria-label="内容加载中">
+    <el-skeleton :rows="5" animated />
+  </div>
+</template>
+```
+
+### 表单无障碍
+
+```vue
+<template>
+  <el-form
+    ref="formRef"
+    :model="form"
+    @submit.prevent="handleSubmit"
+    novalidate
+  >
+    <!-- ✅ 必填字段标注 -->
+    <el-form-item
+      label="用户名"
+      prop="username"
+      :required="true"
+    >
+      <el-input
+        v-model="form.username"
+        :aria-required="true"
+        :aria-describedby="`username-hint ${formErrors.username ? 'username-error' : ''}`"
+        :aria-invalid="!!formErrors.username"
+      />
+      <p id="username-hint" class="text-sm text-gray-500 mt-1">
+        3-20 位字母、数字或下划线
+      </p>
+      <!-- ✅ 错误提示：aria-live 确保屏幕阅读器读取 -->
+      <p
+        v-if="formErrors.username"
+        id="username-error"
+        role="alert"
+        class="text-sm text-red-500 mt-1"
+      >
+        {{ formErrors.username }}
+      </p>
+    </el-form-item>
+  </el-form>
+</template>
+```
+
+### 数据表格
+
+```vue
+<template>
+  <!-- ✅ 可访问的表格 -->
+  <div role="region" :aria-label="`${title}列表`" aria-live="polite">
+    <el-table
+      :data="tableData"
+      :aria-rowcount="total"
+      @sort-change="handleSort"
+    >
+      <!-- 选择列 -->
+      <el-table-column type="selection" :aria-label="'全选'" width="55" />
+
+      <!-- 数据列 -->
+      <el-table-column prop="name" label="名称" sortable>
+        <template #header>
+          <span>名称</span>
+          <el-tooltip content="按名称升序/降序排列">
+            <el-icon aria-hidden="true"><InfoFilled /></el-icon>
+          </el-tooltip>
+        </template>
+      </el-table-column>
+
+      <!-- 操作列 -->
+      <el-table-column label="操作" width="150">
+        <template #default="{ row }">
+          <!-- ✅ 操作按钮有明确的 aria-label -->
+          <el-button
+            type="primary"
+            :aria-label="`编辑 ${row.name}`"
+            @click="editRow(row)"
+          >
+            编辑
+          </el-button>
+          <el-button
+            type="danger"
+            :aria-label="`删除 ${row.name}`"
+            @click="deleteRow(row.id)"
+          >
+            删除
+          </el-button>
+        </template>
+      </el-table-column>
+    </el-table>
+
+    <!-- 分页 -->
+    <el-pagination
+      v-model:current-page="currentPage"
+      :total="total"
+      :aria-label="`分页，当前第 ${currentPage} 页，共 ${Math.ceil(total / pageSize)} 页`"
+    />
+  </div>
+</template>
+```
+
+### 图标按钮（必须有 aria-label）
+
+```vue
+<!-- ✅ 图标按钮 -->
+<button aria-label="关闭菜单" @click="closeMenu">
+  <el-icon aria-hidden="true"><Close /></el-icon>
+</button>
+
+<!-- ✅ 带 tooltip 的图标按钮 -->
+<el-tooltip content="刷新数据" placement="top">
+  <button aria-label="刷新数据" @click="refresh">
+    <el-icon aria-hidden="true"><Refresh /></el-icon>
+  </button>
+</el-tooltip>
+
+<!-- ❌ 无 label 的图标按钮 -->
+<button @click="closeMenu">
+  <el-icon><Close /></el-icon>
+</button>
+```
+
+---
+
+## 颜色对比度
+
+```scss
+// 确保颜色对比度 ≥ 4.5:1
+// 工具：https://webaim.org/resources/contrastchecker/
+
+// ✅ 正文文字
+.text-primary { color: #1d4ed8; }    // 在白底: 7.5:1 ✓
+.text-secondary { color: #374151; }  // 在白底: 9.4:1 ✓
+
+// ⚠️ 灰色文字需谨慎
+.text-muted { color: #6b7280; }      // 在白底: 4.6:1 ✓（刚好过 AA）
+
+// ❌ 禁止使用
+.text-too-light { color: #9ca3af; }  // 在白底: 2.8:1 ✗（不过 AA）
+
+// 状态颜色需同时用颜色 + 图标/文字（不只靠颜色区分）
+.status-success {
+  color: #15803d;
+  // ✅ 同时用图标辅助：<el-icon><CircleCheck /></el-icon>
+}
+```
+
+---
+
+## 动效规范（减少动效）
+
+```css
+/* 尊重用户减少动效偏好 */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  ::before,
+  ::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+```typescript
+// src/composables/useReducedMotion.ts
+export function useReducedMotion() {
+  const preferReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)')
+  return computed(() => preferReducedMotion.matches)
+}
+```
+
+---
+
+## 自动化测试
+
+```typescript
+// tests/a11y.spec.ts — 使用 axe-playwright
+import { checkA11y, injectAxe } from 'axe-playwright'
+
+test('dashboard page has no accessibility violations', async ({ page }) => {
+  await page.goto('/dashboard')
+  await injectAxe(page)
+  await checkA11y(page, undefined, {
+    axeOptions: { runOnly: ['wcag2a', 'wcag2aa'] },
+  })
+})
+```
+
+```bash
+# 安装 axe 测试依赖
+npm install -D axe-playwright @axe-core/playwright
+```
+
+---
+
+## 规则
+
+- 所有图片必须有 `alt`（装饰性图片用 `alt=""`）
+- 所有图标按钮必须有 `aria-label`，图标本身加 `aria-hidden="true"`
+- 所有表单字段必须有关联的 `<label>` 或 `aria-label`
+- 错误提示必须使用 `role="alert"` 或 `aria-live="polite"`
+- 对话框必须有焦点陷阱（focus trap）和 ESC 关闭支持
+- 不能只用颜色区分状态（必须加文字或图标）
+- 自动化测试须包含 axe-playwright a11y 扫描
+- 产品上线前须通过 Lighthouse Accessibility 评分 ≥ 90
diff --git a/.cursor/rules/references/024-monitoring-deep.md b/.cursor/rules/references/024-monitoring-deep.md
new file mode 100644
index 0000000..e1542b7
--- /dev/null
+++ b/.cursor/rules/references/024-monitoring-deep.md
@@ -0,0 +1,266 @@
+# 024-monitoring.mdc (Deep Reference)
+
+> 该文件为原始详细规范归档，供 Tier 3 按需读取。
+
+---
+
+
+# 📊 Logging & Error Monitoring Standards (Hyperf + Vue 3)
+
+## 日志规范
+
+### 后端结构化日志 (Hyperf Monolog)
+
+```php
+// config/autoload/logger.php
+<?php
+
+declare(strict_types=1);
+
+use Monolog\Formatter\JsonFormatter;
+use Monolog\Handler\RotatingFileHandler;
+use Monolog\Level;
+
+return [
+    'default' => [
+        'handler' => [
+            'class'       => RotatingFileHandler::class,
+            'constructor' => [
+                'filename'   => BASE_PATH . '/runtime/logs/hyperf.log',
+                'maxFiles'   => 30,
+                'level'      => Level::Info,
+            ],
+        ],
+        'formatter' => [
+            'class'       => JsonFormatter::class,
+            'constructor' => [
+                'batchMode'         => JsonFormatter::BATCH_MODE_JSON,
+                'appendNewline'     => true,
+                'includeStacktraces' => true,
+            ],
+        ],
+    ],
+    'sql' => [
+        'handler' => [
+            'class'       => RotatingFileHandler::class,
+            'constructor' => [
+                'filename' => BASE_PATH . '/runtime/logs/sql.log',
+                'maxFiles' => 14,
+                'level'    => Level::Debug,
+            ],
+        ],
+    ],
+];
+```
+
+### 日志级别规则
+
+| 级别 | 使用场景 | 示例 |
+|------|---------|------|
+| `debug` | 开发调试，生产禁用 | 函数入参、SQL 查询 |
+| `info` | 关键业务事件 | 用户登录、订单创建、审批通过 |
+| `warning` | 非预期但可恢复 | 缓存未命中、重试、Token 即将过期 |
+| `error` | 需要处理的错误 | API 调用失败、数据库异常、队列失败 |
+| `critical` | 服务无法继续运行 | 启动失败、关键依赖丢失 |
+
+### 请求链路追踪 (TraceId)
+
+```php
+// app/Middleware/TraceIdMiddleware.php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Middleware;
+
+use Hyperf\Context\Context;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+
+class TraceIdMiddleware implements MiddlewareInterface
+{
+    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
+    {
+        $traceId = $request->getHeaderLine('X-Trace-Id') ?: bin2hex(random_bytes(16));
+        Context::set('trace_id', $traceId);
+
+        $response = $handler->handle($request);
+
+        return $response->withHeader('X-Trace-Id', $traceId);
+    }
+}
+```
+
+```php
+// Usage in Service
+$this->logger->info('Order created', [
+    'trace_id' => Context::get('trace_id'),
+    'order_id' => $order->id,
+    'user_id'  => Context::get('current_user')?->id,
+]);
+```
+
+### 禁止事项
+
+```
+✗ 不在日志中记录密码、Token、信用卡号等敏感信息
+✗ 不使用 var_dump / dd / echo 替代结构化日志
+✗ 不在循环中记录 debug 日志（性能影响）
+✗ 不记录完整的请求/响应体（可能含敏感数据）
+✗ 生产环境禁止 debug 级别日志
+```
+
+---
+
+## 前端错误监控 (Vue 3)
+
+### 全局错误捕获
+
+```typescript
+// src/plugins/error-handler.ts
+import { App } from 'vue'
+
+export function setupErrorHandler(app) {
+  app.config.errorHandler = (error, instance, info) => {
+    console.error('Vue component error:', {
+      error: error instanceof Error ? error.message : String(error),
+      component: instance?.$options?.name,
+      info,
+    })
+    // Report to Sentry or custom error service
+  }
+
+  window.addEventListener('unhandledrejection', (event) => {
+    console.error('Unhandled promise rejection:', event.reason)
+  })
+}
+```
+
+### Sentry 集成 (Vue 3 版)
+
+```typescript
+// src/plugins/sentry.ts
+import * as Sentry from '@sentry/vue'
+
+export function setupSentry(app, router) {
+  if (import.meta.env.PROD) {
+    Sentry.init({
+      app,
+      dsn: import.meta.env.VITE_SENTRY_DSN,
+      environment: import.meta.env.MODE,
+      integrations: [
+        Sentry.browserTracingIntegration({ router }),
+      ],
+      tracesSampleRate: 0.1,
+      beforeSend(event) {
+        if (event.request?.headers) {
+          delete event.request.headers['authorization']
+        }
+        return event
+      },
+    })
+  }
+}
+```
+
+---
+
+## 服务端监控
+
+### Swoole 进程监控
+
+```php
+// Health check endpoint
+#[RequestMapping(path: '/admin/health', methods: ['GET'])]
+public function health(): ResponseInterface
+{
+    $stats = $this->server->stats();
+
+    return $this->success([
+        'status'          => 'ok',
+        'uptime'          => time() - $stats['start_time'],
+        'connections'     => $stats['connection_num'],
+        'requests'        => $stats['request_count'],
+        'coroutine_num'   => $stats['coroutine_num'],
+        'worker_num'      => $stats['worker_num'],
+    ]);
+}
+```
+
+### MySQL 慢查询监控
+
+```sql
+-- 启用慢查询日志
+SET GLOBAL slow_query_log = 'ON';
+SET GLOBAL long_query_time = 1;
+SET GLOBAL slow_query_log_file = '/var/log/mysql/slow.log';
+```
+
+```php
+// Hyperf SQL 日志（开发环境）
+// config/autoload/databases.php
+'commands' => [
+    'gen:model' => [
+        'with_comments' => true,
+    ],
+],
+```
+
+### Redis 监控
+
+```bash
+# 关键指标
+redis-cli INFO stats | grep -E 'keyspace_hits|keyspace_misses|connected_clients'
+redis-cli INFO memory | grep used_memory_human
+```
+
+---
+
+## 告警策略
+
+### 告警优先级
+
+| 优先级 | 触发条件 | 响应时间 | 通知方式 |
+|--------|---------|---------|---------|
+| P0 - 紧急 | 服务不可用、数据丢失 | 15 分钟内 | 电话 + 企业微信 |
+| P1 - 高 | 错误率 > 5%、P99 > 5s | 1 小时内 | 企业微信 |
+| P2 - 中 | 错误率 > 1%、异常流量 | 4 小时内 | 邮件 |
+| P3 - 低 | 资源使用率异常 | 次日 | 日报 |
+
+### 监控指标
+
+```
+# 业务指标
+- API 请求成功率（目标 > 99.9%）
+- API P50/P95/P99 响应时间
+- 每分钟错误数（Error Rate）
+
+# 系统指标
+- CPU / 内存使用率（告警阈值：80%）
+- Swoole Worker 协程数（告警阈值：90%）
+- MySQL 连接池使用率（告警阈值：70%）
+- Redis 内存使用率（告警阈值：70%）
+- 磁盘使用率（告警阈值：85%）
+- 队列堆积数（告警阈值：1000）
+```
+
+## 日志保留策略
+
+| 环境 | 保留周期 | 存储方式 |
+|------|---------|---------|
+| 开发 | 7 天 | 本地文件 (runtime/logs/) |
+| 测试 | 30 天 | 对象存储 |
+| 生产 | 90 天（error 保留 1 年） | ELK / CloudWatch |
+
+## 检查清单
+
+- [ ] 所有 API 路由有请求日志（通过 TraceId 中间件）
+- [ ] 错误捕获后记录完整 stack trace
+- [ ] traceId 贯穿整个请求链路
+- [ ] 敏感字段已从日志中过滤
+- [ ] 生产环境 debug 日志已关闭
+- [ ] 关键业务事件有对应告警规则
+- [ ] 前端有全局错误捕获
+- [ ] Swoole 健康检查端点可用
diff --git a/.cursor/rules/references/026-secure-coding-deep.md b/.cursor/rules/references/026-secure-coding-deep.md
new file mode 100644
index 0000000..7483396
--- /dev/null
+++ b/.cursor/rules/references/026-secure-coding-deep.md
@@ -0,0 +1,241 @@
+# 026-secure-coding.mdc (Deep Reference)
+
+> 该文件为原始详细规范归档，供 Tier 3 按需读取。
+
+---
+
+
+# 🔐 Secure Coding Standards (Project CodeGuard)
+
+> 安全不是事后审查，而是编码时的默认选择。
+
+## ❌ 禁用加密算法（绝对禁止）
+
+以下算法已被证实不安全，**禁止在任何新代码中使用**：
+
+| 类型 | 禁用 | 替代 |
+|------|------|------|
+| 哈希 | MD2、MD4、**MD5**、SHA-0、**SHA-1** | SHA-256、SHA-3 |
+| 对称加密 | RC2、RC4、Blowfish、DES、3DES、**AES-ECB** | **AES-GCM**、ChaCha20-Poly1305 |
+| 密钥交换 | 静态 RSA、匿名 DH | ECDHE (X25519) |
+
+```php
+// ❌ 禁止
+$hash = md5($password);
+$hash = sha1($data);
+openssl_encrypt($data, 'AES-128-ECB', $key);
+
+// ✅ 正确
+$hash = password_hash($password, PASSWORD_ARGON2ID);
+$hash = hash('sha256', $data);
+openssl_encrypt($data, 'AES-256-GCM', $key, 0, $iv, $tag);
+```
+
+## 💉 注入防护
+
+### SQL 注入
+- **100% 使用参数化查询**，禁止字符串拼接 SQL
+- 使用 Hyperf ORM 或 PDO 绑定参数
+
+```php
+// ❌ 禁止
+$result = Db::select("SELECT * FROM users WHERE name = '{$name}'");
+
+// ✅ 正确
+$result = Db::select('SELECT * FROM users WHERE name = ?', [$name]);
+// 或
+User::where('name', $name)->first();
+```
+
+### OS 命令注入
+- 优先使用内置函数替代 shell 调用
+- 禁止将用户输入直接传入 `exec()`、`system()`、`shell_exec()`
+
+```php
+// ❌ 禁止
+exec("convert {$userFile} output.png");
+
+// ✅ 正确（使用内置库）
+$image = new Imagick($sanitizedPath);
+```
+
+### TypeScript Prototype Pollution
+- 使用 `Map` / `Set` 替代对象字面量存储用户数据
+- 合并对象时拦截 `__proto__`、`constructor`、`prototype` 键
+
+```typescript
+// ❌ 禁止
+function merge(target, source) {
+  Object.assign(target, source) // 可能导致 prototype pollution
+}
+
+// ✅ 正确
+const safe = Object.create(null)
+const blocked = ['__proto__', 'constructor', 'prototype']
+Object.keys(source).filter(k => !blocked.includes(k)).forEach(k => { safe[k] = source[k] })
+```
+
+## 🔑 密码存储
+
+```php
+// ❌ 禁止（bcrypt 有 72 字节截断限制）
+$hash = password_hash($password, PASSWORD_BCRYPT);
+
+// ✅ 推荐（Argon2id：更安全，无长度限制）
+$hash = password_hash($password, PASSWORD_ARGON2ID, [
+    'memory_cost' => 65536,  // 64 MiB
+    'time_cost'   => 2,
+    'threads'     => 1,
+]);
+
+// 验证（常量时间比较，防时序攻击）
+$valid = password_verify($input, $hash);
+```
+
+## 🔒 访问控制（IDOR / Mass Assignment 防护）
+
+### IDOR 防护
+- 永远不要只凭用户传入的 ID 查询资源，必须附加所有权校验
+
+```php
+// ❌ 禁止 — 用户可访问任意 ID 的数据
+$order = Order::find($request->input('id'));
+
+// ✅ 正确 — 限定当前用户范围
+$order = $this->user->orders()->findOrFail($request->input('id'));
+```
+
+### Mass Assignment 防护
+- Hyperf FormRequest 必须声明 `rules()` 白名单
+- Model 必须使用 `$fillable` 而非 `$guarded = []`
+
+```php
+// ❌ 禁止
+$user->fill($request->all());
+
+// ✅ 正确（只允许明确字段）
+$user->fill($request->only(['name', 'email', 'avatar']));
+```
+
+## 🍪 Session 和 Cookie 安全
+
+```php
+// 登录成功后必须轮转 Session ID（防 Session Fixation）
+session_regenerate_id(true);
+
+// Cookie 必须设置安全属性
+setcookie('session', $id, [
+    'secure'   => true,        // 仅 HTTPS
+    'httponly' => true,        // 禁止 JS 访问
+    'samesite' => 'Strict',    // 防 CSRF
+    'path'     => '/',
+]);
+```
+
+- Session 超时：高风险操作 5 分钟，常规 30 分钟，绝对上限 8 小时
+- **禁止在 `localStorage` / `sessionStorage` 存储 Session Token**（XSS 可窃取）
+
+## 🌐 客户端安全（Vue 3 / TypeScript）
+
+### XSS 防护
+```typescript
+// ❌ 禁止 — 直接使用 v-html 且无净化
+// <div v-html="userContent"></div>
+
+// ✅ 正确 — 使用 DOMPurify 净化
+import DOMPurify from 'dompurify'
+const clean = DOMPurify.sanitize(userContent, {
+  ALLOWED_TAGS: ['b', 'i', 'p', 'a', 'ul', 'li'],
+  ALLOWED_ATTR: ['href'],
+})
+// <div v-html="clean"></div>
+
+// ❌ 禁止 — 动态代码执行
+eval(userCode)
+new Function(userCode)()
+setTimeout(userString, 100)
+
+// ❌ 禁止 — 直接 DOM 写入
+element.innerHTML = userInput
+document.write(userInput)
+```
+
+### 外链安全
+```html
+<!-- ✅ 所有 target="_blank" 必须加防护 -->
+<a href="..." target="_blank" rel="noopener noreferrer">外链</a>
+```
+
+### CSRF 防护
+- 所有状态变更请求（POST/PUT/DELETE/PATCH）必须携带 CSRF Token
+- 禁止用 GET 请求执行状态变更操作
+
+## 📁 文件上传安全
+
+```php
+// ✅ 文件上传安全检查清单
+
+// 1. 白名单扩展名（不是黑名单）
+$allowed = ['jpg', 'png', 'gif', 'pdf'];
+$ext = strtolower(pathinfo($file->getClientFilename(), PATHINFO_EXTENSION));
+if (!in_array($ext, $allowed)) throw new ValidationException('不允许的文件类型');
+
+// 2. 验证 magic bytes（不信任 Content-Type）
+$finfo = new finfo(FILEINFO_MIME_TYPE);
+$mimeType = $finfo->file($tmpPath);
+
+// 3. 生成随机文件名（不使用用户提供的文件名）
+$safeName = Str::uuid() . '.' . $ext;
+
+// 4. 存储在 webroot 外
+$storagePath = BASE_PATH . '/storage/uploads/' . $safeName;
+
+// 5. 设置文件大小限制
+if ($file->getSize() > 10 * 1024 * 1024) throw new ValidationException('文件过大');
+```
+
+## 📊 安全日志规范
+
+```php
+// ❌ 禁止记录敏感信息
+Log::info('用户登录', ['password' => $password, 'token' => $token]);
+
+// ✅ 正确 — 只记录安全信息，用 hash 标识 session
+Log::info('用户登录', [
+    'user_id'    => $userId,
+    'ip'         => $request->getServerParams()['REMOTE_ADDR'],
+    'user_agent' => substr($request->getHeaderLine('user-agent'), 0, 200),
+    'session_id' => substr(hash('sha256', $sessionId), 0, 16), // 前16位，不泄露原值
+    'timestamp'  => date('c'),
+]);
+```
+
+## ⚙️ API 安全
+
+- **禁止在 URL 参数中传递敏感数据**（会出现在日志里）
+- GraphQL：生产环境禁用 introspection
+- SSRF：所有外部 HTTP 请求必须验证目标域名白名单
+
+```php
+// SSRF 防护示例
+$allowedDomains = ['api.trusted.com', 'cdn.trusted.com'];
+$parsedUrl = parse_url($userProvidedUrl);
+if (!in_array($parsedUrl['host'], $allowedDomains)) {
+    throw new SecurityException('不允许的目标地址');
+}
+// 还需阻断私有 IP 范围：10.x, 172.16.x, 192.168.x, 127.x
+```
+
+## ✅ 编码时自查清单
+
+每次提交前确认：
+- [ ] 无 MD5/SHA1/DES/AES-ECB 使用
+- [ ] SQL 查询 100% 参数化
+- [ ] 资源查询已限定所有权范围（无 IDOR 风险）
+- [ ] 无 `$request->all()` 直接绑定模型
+- [ ] Cookie 包含 Secure + HttpOnly + SameSite 属性
+- [ ] `v-html` 使用了 DOMPurify 净化
+- [ ] 文件上传使用 UUID 文件名 + magic bytes 验证
+- [ ] 日志未包含明文密码/Token/Session ID
+
+> 📚 深度参考：`.cursor/skills/security-audit/references/codeguard/`
diff --git a/.cursor/rules/skill-backend-scaffold.mdc b/.cursor/rules/skill-backend-scaffold.mdc
new file mode 100644
index 0000000..b9c8987
--- /dev/null
+++ b/.cursor/rules/skill-backend-scaffold.mdc
@@ -0,0 +1,63 @@
+---
+description: >
+  Hyperf 后端模块脚手架技能。新建 API 端点、Controller、Service、
+  Repository 或完整后端业务模块时激活。含分层约定、异常体系和事务管理。
+globs:
+  - "**/Controller/**/*.php"
+  - "**/Service/**/*.php"
+  - "**/Repository/**/*.php"
+alwaysApply: false
+---
+
+# Backend Scaffold (API + Service)
+
+> 本文件是精简执行摘要。完整流程、模板和深度参考见：
+> Read `.cursor/skills/api-scaffold/SKILL.md`（API 端点）
+> Read `.cursor/skills/hyperf-service/SKILL.md`（Service 模块）
+
+> **适用性**（双模式）：
+> - **新建**后端模块/API 端点：走完整执行流程（Step 1-8）
+> - **修改**已有接口或 Service：跳过脚手架步骤，完成后走「验证」清单
+
+## 执行流程
+
+1. 加载规范：Read `013-backend.mdc`、`016-swoole.mdc`
+2. 确认模块规格（资源名称、HTTP 方法、路由路径、是否需要 Repository/事件/数据权限）
+3. 扫描项目约定：`app/Controller/`、`app/Service/` 现有模式
+4. **配置依赖检查**（使用事件/队列/缓存时必须检查）：
+   - 使用异步队列：检查 `config/autoload/async_queue.php` 是否存在
+   - 使用 Redis 缓存：检查 `config/autoload/redis.php` 连接池配置
+   - 使用 JWT：检查 `config/autoload/jwt.php` 和环境变量 `JWT_SECRET`
+5. 生成文件：Controller → Service → Repository（如需）→ Model → FormRequest → Event（可选）→ 路由注册
+6. Service 使用 `Db::transaction` 包裹写操作
+7. Repository 实现 `applyFilters`、`applyDataScope`、分页上限
+8. 集成 HasLogger Trait，关键操作有结构化日志
+9. 外部 API 调用使用 RetryHelper 指数退避重试
+
+## 分层约定
+
+Controller（接收请求）→ Service（业务逻辑）→ Repository（数据访问）→ Model
+
+## 异常体系
+
+- `BusinessException` — 可预期业务错误（404/403/422）
+- `ValidationException` — FormRequest 校验失败
+- `SystemException` — 500 系统故障，记录堆栈
+
+## 验证
+
+- [ ] `php -l` 编译无错误
+- [ ] FormRequest rules 覆盖所有请求字段
+- [ ] 错误处理覆盖 400/401/403/404/422/500
+- [ ] Service 使用事务包裹写操作
+- [ ] 路由遵循 RESTful 命名（复数名词、kebab-case）
+- [ ] 中间件正确挂载（认证 + 权限）
+- [ ] 分页有 page_size 上限
+- [ ] 关键操作有结构化日志
+- [ ] 外部 API 用 RetryHelper
+
+## 深度参考
+
+- `.cursor/skills/api-scaffold/references/code-templates.md`
+- `.cursor/skills/api-scaffold/references/exception-handling.md`
+- `.cursor/skills/hyperf-service/references/service-templates.md`
diff --git a/.cursor/rules/skill-code-review.mdc b/.cursor/rules/skill-code-review.mdc
new file mode 100644
index 0000000..5a1721a
--- /dev/null
+++ b/.cursor/rules/skill-code-review.mdc
@@ -0,0 +1,70 @@
+---
+description: >
+  代码审查技能。当用户要求 review 代码、检查质量、审查 PR、
+  或执行预提交检查时激活。从六个维度系统化审查。
+alwaysApply: false
+---
+
+# Code Review — 六维度审查
+
+> 本文件是精简执行摘要。完整流程、模板和深度参考见：
+> Read `.cursor/skills/code-review/SKILL.md`
+
+## 执行流程
+
+### 1. 确定审查范围
+
+- 具体文件 → 审查指定文件
+- 目录范围 → 审查目录下所有变更
+- Git diff → `git diff HEAD~1` 审查最近变更
+
+### 2. 六维度审查
+
+按顺序逐一审查：
+
+1. **安全性** — 硬编码密钥？SQL 注入/XSS？未验证输入？不安全认证？
+2. **正确性** — 逻辑正确？边界条件？错误处理？null/undefined 安全？
+3. **可维护性** — 命名清晰？函数 < 50 行？单一职责？逻辑已提取到纯函数？
+4. **性能** — 不必要渲染？N+1 查询？大数据未分页？缺少缓存？
+5. **可测试性** — 纯函数已提取到 .utils.ts？composable 可独立测试？有 data-testid？
+6. **一致性** — 命名风格统一？遵循项目模式？import 顺序？错误处理模式？
+
+### 3. 预提交检查联动
+
+```bash
+# PHP 后端
+vendor/bin/phpstan analyse --level=5 --no-progress
+vendor/bin/php-cs-fixer fix --dry-run --diff
+
+# Vue 前端
+npx eslint --quiet src/
+npx vitest run --reporter=verbose
+```
+
+### 4. 输出格式
+
+```markdown
+## 代码审查报告
+
+**范围**: <文件/目录/PR>
+**总体评价**: 建议合并 | 需修改后合并 | 需重写
+
+### 发现
+
+#### Must Fix
+1. **[SEC]** `file.ts:23` — 问题描述 → 修复建议
+
+#### Should Fix
+2. **[MAINT]** `service.ts:45` — 问题描述 → 修复建议
+
+#### Suggestion
+3. **[PERF]** `list.vue:12` — 问题描述 → 修复建议
+```
+
+## 验证
+
+- [ ] 六个维度全部覆盖
+- [ ] 每个发现有具体文件和行号
+- [ ] 每个发现有修复建议
+- [ ] 发现按严重程度分级
+- [ ] 预提交检查已执行
diff --git a/.cursor/rules/skill-component-scaffold.mdc b/.cursor/rules/skill-component-scaffold.mdc
new file mode 100644
index 0000000..e37ff8f
--- /dev/null
+++ b/.cursor/rules/skill-component-scaffold.mdc
@@ -0,0 +1,61 @@
+---
+description: >
+  Vue 3 组件脚手架技能。新建 Vue SFC 组件、拆分子组件、
+  创建复合组件时激活。含模板生成、命名规范、Prop 设计。
+globs:
+  - "**/components/**/*.vue"
+  - "**/composables/**/*.ts"
+alwaysApply: false
+---
+
+# Component Scaffold
+
+> 本文件是精简执行摘要。完整流程、模板和深度参考见：
+> Read `.cursor/skills/component-scaffold/SKILL.md`
+
+> **适用性**（双模式）：
+> - **新建**组件/重大拆分：走完整执行流程（Step 1-7）
+> - **修改**已有组件：跳过脚手架步骤，完成后走「验证」清单
+
+依赖技能：`vue-testing`（Cursor 已通过 `skill-vue-testing` 规则自动加载）
+
+## 前端识别（必须先确认）
+
+- **管理端** (`Case-Database-Frontend-admin/`)：Element Plus + Tailwind
+- **用户端** (`Case-Database-Frontend-user/`)：Headless UI + Tailwind，**禁止 Element Plus**
+
+## 执行流程
+
+1. 加载规范：Read `010-typescript.mdc`、`011-vue.mdc`、`019-modular.mdc`
+2. 扫描 `src/components/core/` 和 `src/components/custom/`，避免重复造轮子
+3. 重复 UI 检测：同一结构 >=3 次 → 提取基础组件
+4. **输出文件结构**（写代码前必须先输出）：
+   ```
+   src/components/<type>/<ComponentName>/
+   ├── <ComponentName>.vue      (行数限制见 011-vue.mdc)
+   ├── <ComponentName>.test.ts
+   └── index.ts
+   ```
+5. 确认组件规格（名称、类型、目录、Props/Emits）
+6. 生成组件代码（`<script setup lang="ts">` + `defineProps`）
+7. 生成测试和 barrel export
+
+## 质量约束
+
+行数限制和设计决策树已下沉到 `011-vue.mdc`（编辑任何 .vue 文件时自动生效），
+此处不再重复。脚手架生成的组件同样受 `011-vue.mdc` 约束。
+
+## 验证
+
+- [ ] Props 使用对象语法 `defineProps({ key: { type, default } })`；**script 中若不访问 `props.xxx` 则不保存返回值**（直接写 `defineProps(...)` 而非 `const props = defineProps(...)`，避免 `unused-vars` lint 报错）
+- [ ] **`catch` 块中不使用异常参数时写 `catch {}` 而非 `catch (e) {}`**，避免 `unused-vars` 报错
+- [ ] 包含 `data-testid`
+- [ ] 测试至少一个渲染测试
+- [ ] barrel export 正确
+- [ ] 符合 `011-vue.mdc` 的 SFC 行数限制和设计决策规则
+- [ ] composable 参数有类型注解、ref 有泛型
+
+## 深度参考
+
+- `.cursor/skills/component-scaffold/references/component-templates.md`
+- `.cursor/skills/component-scaffold/references/naming-conventions.md`
diff --git a/.cursor/rules/skill-database-migration.mdc b/.cursor/rules/skill-database-migration.mdc
new file mode 100644
index 0000000..8081005
--- /dev/null
+++ b/.cursor/rules/skill-database-migration.mdc
@@ -0,0 +1,48 @@
+---
+description: >
+  Hyperf 数据库迁移技能。数据库 Schema 变更（增删改表/字段/索引）时激活。
+  确保迁移安全可回滚。
+globs:
+  - "**/database/migrations/**/*.php"
+alwaysApply: false
+---
+
+# Database Migration
+
+> 本文件是精简执行摘要。完整流程、模板和深度参考见：
+> Read `.cursor/skills/database-migration/SKILL.md`
+
+> **适用性**：本技能用于**数据库 Schema 变更**。
+> 仅查询数据库或读取 Model 时可忽略本技能。
+
+安全等级：ORANGE — 执行前必须确认。
+
+## 核心原则
+
+1. 每次变更都是迁移 — 禁止手动 DDL
+2. Schema 与 Data 严格分离 — DDL 和 DML 分文件
+3. 迁移部署后不可变 — 已执行迁移禁止修改
+4. 新字段安全 — 新增字段必须 nullable 或有默认值
+
+## 执行流程
+
+1. 加载规范：Read `014-database.mdc`
+2. 确认变更需求（变更内容、是否涉及数据迁移、是否可逆、数据量级）
+3. 生成迁移：`php bin/hyperf.php gen:migration <name>`
+4. 编写迁移（Schema::create / Schema::table，down() 必须完整可逆）
+5. 高并发表设计检查（主键 BIGINT、utf8mb4、金额 DECIMAL、索引 <=6）
+6. 执行：`migrate` → `migrate:status` → 更新 Model、Service、data-model.md
+
+## 验证
+
+- [ ] migrate 无错误
+- [ ] migrate:rollback 可回滚
+- [ ] Model $fillable / $casts 正确
+- [ ] 外键有索引
+- [ ] 新字段 nullable 或有默认值
+- [ ] Schema 与 Data 迁移分文件
+- [ ] data-model.md 已更新
+
+## 深度参考
+
+- `.cursor/skills/database-migration/references/migration-patterns.md`
diff --git a/.cursor/rules/skill-debugging.mdc b/.cursor/rules/skill-debugging.mdc
new file mode 100644
index 0000000..72ec866
--- /dev/null
+++ b/.cursor/rules/skill-debugging.mdc
@@ -0,0 +1,83 @@
+---
+description: >
+  系统化调试技能。当用户报告 bug、错误、异常、崩溃，
+  提供截图指出界面问题，或描述功能与预期不符时激活。
+alwaysApply: true
+---
+
+# Debugging — 七步法
+
+> 本文件是精简执行摘要。完整流程、模板和深度参考见：
+> Read `.cursor/skills/debugging/SKILL.md`
+
+## -1. 截图前置守卫（Scan 阶段硬检查）
+
+收到用户消息时，**先检查输入形式**，再分析文字意图：
+
+| 输入形式 | 问题关键词 | 判定 |
+|---------|-----------|------|
+| 包含截图/图片 | 不合理 / 不对 / 有问题 / 调整 / 修复 / 偏了 / 太大 / 太小 / 空白 / 溢出 / 错位 | → 视觉 Bug，激活完整调试流程 |
+| 包含截图/图片 | 新增 / 添加 / 改为 / 参考这个 / 照着做 | → 需求变更，走正常开发流程 |
+
+**硬规则**：无论判定结果是哪条路径，都**必须在回复开头输出守卫判定块**：
+
+```
+## 截图守卫判定
+- 输入形式：包含截图 ✓
+- 关键词扫描：「XXX」→ 命中 [视觉 Bug / 需求变更] 类
+- 判定：[激活调试流程 / 走正常开发流程]
+```
+
+**视觉 Bug 路径规则**：
+- 截图 + 问题描述 = 视觉 Bug，**不得降级为 L1 直接执行**，最低 L2
+- 必须走完信号解析 → 修复 → 回归验证（含 chrome-devtools 截图对比）全流程
+
+**需求变更路径规则**：
+- 截图用于"参考设计"或"说明改动目标"，走正常开发流程
+- 复杂度按 001-workflow 标准判定（可为 L1）
+
+## 0. 信号解析
+
+从用户描述中提取（缺失则追问）：
+
+| 信号 | 重要性 |
+|------|--------|
+| 错误消息 / 堆栈追踪 | 必需 |
+| 复现步骤 | 必需 |
+| 截图标注的异常区域 | 必需（有截图时） |
+| 影响区域（前端/后端/API/DB） | 重要 |
+| 环境信息 / 上次正常版本 | 有用 |
+
+## 0.5 调试策略路由
+
+| 影响区域 | 首选方式 | 测试工具 |
+|----------|---------|---------|
+| PHP Service | 断点 + 日志 | PHPUnit |
+| API 端点 | curl + 日志 | Hyperf HttpClient |
+| 数据库查询 | SQL 日志 + EXPLAIN | PHPUnit + SQLite |
+| Vue 组件渲染 | Vue DevTools | Vitest + VTU |
+| 样式/布局 | Chrome DevTools | 视觉回归 |
+
+## 1-6. 核心流程
+
+1. **复现** — 确认稳定复现步骤，记录复现概率和条件
+2. **收集** — 读取源码、检查 git log、查看日志和已有测试
+3. **假设** — 列出 2-3 个最可能原因，按概率排序，指向具体文件和行
+4. **验证** — 从最高概率假设开始，每次只验证一个
+5. **修复** — 修复根因，修改尽可能小，添加防御性代码
+6. **回归** — 确认修复、运行测试套件、编写回归测试防复发
+
+## 硬停止条件
+
+需要真实第三方凭证、竞态条件不可靠复现、需要生产数据、超过 3 次假设全部否定 → 立即停止，告知用户需要额外条件。
+
+## 验证
+
+- [ ] 提取了所有关键信号
+- [ ] 选择了正确的调试策略
+- [ ] 原始问题已修复
+- [ ] 所有现有测试通过
+- [ ] 添加了回归测试
+- [ ] 修复范围最小化
+
+深度参考：`.cursor/skills/debugging/references/common-errors.md`
diff --git a/.cursor/rules/skill-full-feature.mdc b/.cursor/rules/skill-full-feature.mdc
new file mode 100644
index 0000000..d1f686e
--- /dev/null
+++ b/.cursor/rules/skill-full-feature.mdc
@@ -0,0 +1,78 @@
+---
+description: >
+  端到端功能开发技能。当需要从数据库到 API 到 UI 全链路开发完整功能时激活。
+  编排 database-migration、api-scaffold、component-scaffold 等技能协同工作。
+alwaysApply: false
+---
+
+# Full Feature Workflow
+
+> 本文件是精简执行摘要。完整流程、模板和深度参考见：
+> Read `.cursor/skills/full-feature/SKILL.md`
+
+依赖技能：`component-scaffold`、`vue-testing`
+
+## 执行流程
+
+### Phase 1: 规划
+
+拆分功能为子任务：
+- 数据层：数据模型和数据库变更
+- 后端 API：Controller / Service / Repository
+- 前端 UI：组件和页面
+- 测试：每层测试
+
+输出执行计划后确认再开始。
+
+### Phase 2: 数据层
+
+1. 生成迁移：`php bin/hyperf.php gen:migration create_<table>_table`
+2. 编写迁移（遵循高并发表设计规范）
+3. 执行迁移 + 生成 Model
+4. 补充 Model 关联和类型转换
+
+参考：Cursor 已通过 `skill-database-migration` 规则自动加载。
+如需模板细节，Read `.cursor/skills/database-migration/references/migration-patterns.md`
+
+### Phase 3: 后端 API 层
+
+1. Controller（接收请求）→ Service（业务逻辑）→ Repository → FormRequest
+2. 注册路由 + 挂载中间件
+3. 编写 PHPUnit 测试
+
+参考：Cursor 已通过 `skill-backend-scaffold` 规则自动加载。
+如需模板细节，Read `.cursor/skills/api-scaffold/references/code-templates.md`
+
+### Phase 4: 前端 UI 层
+
+1. 封装 API 接口（`src/api/<module>/`）
+2. 创建列表页 + 表单组件 + 详情页
+3. 配置 Vue Router 路由
+4. 连接 Pinia Store（如需跨页面状态）
+
+参考：Cursor 已通过 `skill-component-scaffold` 和 `skill-vue-page` 规则自动加载。
+如需模板细节，Read `.cursor/skills/component-scaffold/references/component-templates.md`
+
+### Phase 5: 集成验证
+
+1. 后端测试：`composer test`
+2. 前端 Lint：`npm run lint`
+3. 手动测试 CRUD 全路径
+
+### Phase 6: 收尾
+
+更新文档（data-model.md、api-contracts.md）→ Git commit
+
+## 执行原则
+
+- **自底向上**：数据层 → 后端 API → 前端 UI
+- **每步验证**：每个 Phase 完成后运行测试
+- **可中断**：每个 Phase 独立可提交
+
+## 验证
+
+- [ ] 后端测试全部通过
+- [ ] 前端 ESLint 无报错
+- [ ] 功能端到端可用（CRUD 全路径）
+- [ ] 代码遵循项目现有模式
+- [ ] 文档已更新
diff --git a/.cursor/rules/skill-i18n.mdc b/.cursor/rules/skill-i18n.mdc
new file mode 100644
index 0000000..9d7c266
--- /dev/null
+++ b/.cursor/rules/skill-i18n.mdc
@@ -0,0 +1,45 @@
+---
+description: >
+  国际化技能。当需要添加多语言支持、翻译内容、管理语言包
+  或配置 vue-i18n 国际化时激活。含键命名规范和路由国际化。
+alwaysApply: false
+---
+
+# Internationalization (i18n)
+
+> 本文件是精简执行摘要。完整流程、模板和深度参考见：
+> Read `.cursor/skills/i18n/SKILL.md`
+
+## 执行流程
+
+1. 检测现有 i18n 方案（`vue-i18n` 是否已安装）
+2. 初始化（如未配置）：`npm install vue-i18n@9`，创建 `src/locales/` 目录
+3. 配置 i18n 实例（`legacy: false`、fallbackLocale、localStorage 持久化）
+4. 翻译键命名：使用扁平 dot notation `{feature}.{context}.{action|status|label}`
+5. 组件中使用 `useI18n()` 的 `t()` 函数
+6. 管理端同步 Element Plus locale（用户端不适用）
+7. 添加新语言时确保所有 key 一致
+
+## 键命名公式
+
+`{feature}.{context}.{action|status|label}`
+
+```typescript
+'order.list.title': '订单列表',
+'order.form.submit': '提交订单',
+'common.action.save': '保存',
+```
+
+## 标准命名空间
+
+common | auth | menu | validation | error | {module}
+
+新增命名空间时必须登记。
+
+## 验证
+
+- [ ] 所有 locale 文件的 key 结构一致
+- [ ] 切换语言后页面正确翻译
+- [ ] 键命名遵循公式
+- [ ] 使用扁平 dot notation
+- [ ] 无键冲突
diff --git a/.cursor/rules/skill-module-scaffold.mdc b/.cursor/rules/skill-module-scaffold.mdc
new file mode 100644
index 0000000..3c614ea
--- /dev/null
+++ b/.cursor/rules/skill-module-scaffold.mdc
@@ -0,0 +1,82 @@
+---
+description: >
+  Hyperf 模块化脚手架技能。在 modules/ 下新建业务模块、创建 module、
+  添加模块化功能时激活。基于 Composer path repository + ConfigProvider 机制。
+globs:
+  - "**/modules/*/src/**/*.php"
+  - "**/modules/*/composer.json"
+alwaysApply: false
+---
+
+# Module Scaffold
+
+> 本文件是精简执行摘要。完整流程、模板和深度参考见：
+> Read `.cursor/skills/module-scaffold/SKILL.md`
+
+> **适用性**（双模式）：
+> - **新建**模块：走完整执行流程（Step 1-7）
+> - **修改**已有模块代码：跳过脚手架步骤，完成后走「验证」清单
+
+## 执行流程
+
+1. 确认模块规格（名称、描述、接口类型：`api` / `admin` / `both`、所需子层）
+2. 生成目录结构（**Controller 按接口类型分子目录，见下方规则**）
+3. 生成模块 `composer.json`（name: `modules/{kebab-case}`, namespace: `Modules\{PascalCase}`, extra.hyperf.config）
+4. 生成 `ConfigProvider.php`（注册 dependencies + annotations scan + publish）
+5. 生成 Controller（根据接口类型选择正确子目录和模板）
+6. **配置依赖检查**（使用事件/队列/缓存时必须检查）：
+   - 使用异步队列：检查主项目 `config/autoload/async_queue.php` 是否存在
+   - 使用 Redis 缓存：检查主项目 `config/autoload/redis.php` 连接池配置
+   - 使用 JWT：检查主项目 `config/autoload/jwt.php` 和环境变量 `JWT_SECRET`
+7. **无需修改主项目 `composer.json`**：ModuleLoader 在启动时自动扫描发现
+8. 验证：`require vendor/autoload.php` 后检查 ConfigProvider 是否被发现
+
+## Controller 与 Request 目录规则（核心）
+
+根据接口路由前缀，Controller 和 Request **均须放入对应子目录**：
+
+| 接口类型 | 路由前缀 | Controller 目录 | Request 目录 | 类名规范 |
+|----------|----------|-----------------|--------------|----------|
+| 用户端 | `/api/{module}` | `Http/Controller/Api/` | `Http/Request/Api/` | `{Name}Controller` / `{Name}Request` |
+| 管理端 | `/admin/{module}` | `Http/Controller/Admin/` | `Http/Request/Admin/` | `{Name}Controller` / `{Name}Request` |
+| 两者 | 各自前缀 | 两组子目录都创建 | 两组子目录都创建 | 各自子目录，类名相同 |
+
+**额外约定**：
+- `Admin/` 下的控制器**自动添加** `#[Middleware(JwtAuthMiddleware::class)]` 注解
+- **类名不加接口类型前缀**，`Api/` 和 `Admin/` 下同名类通过命名空间区分
+- Controller 中 `use` 的 Request 路径必须与子目录命名空间一致
+- 路由前缀中 `/api/` 和 `/admin/` 是判断依据，不能混放
+- 未明确时，**主动询问**接口类型而不是猜测
+
+## 命名约定
+
+| 位置 | 格式 | 示例 |
+|------|------|------|
+| 目录名 | PascalCase | `modules/UserCenter/` |
+| Composer 包名 | kebab-case | `modules/user-center` |
+| PHP 命名空间 | PascalCase | `Modules\UserCenter` |
+| 用户端路由前缀 | `/api/kebab-case` | `/api/user-center` |
+| 管理端路由前缀 | `/admin/kebab-case` | `/admin/user-center` |
+
+## 关键机制
+
+- **ModuleLoader 自动发现**：`app/Support/ModuleLoader.php` 注册在 `autoload.files`，在 `vendor/autoload.php` 执行时扫描 `modules/*/composer.json`，通过反射注入 `Hyperf\Support\Composer::$extra`，让 `ProviderConfig::load()` 发现模块 ConfigProvider。**无需修改 `composer.json` require**
+- **composer-merge-plugin**：合并模块 `composer.json` 的 `autoload` 和第三方 `require` 到主项目（仅在模块有外部依赖时才需要 `composer update`）
+- **ConfigProvider**：模块自注册 DI 绑定、注解扫描路径、可发布配置
+
+## 验证
+
+- [ ] **Controller 按接口类型放入正确子目录**（`Api/` 或 `Admin/`，不能平铺在 `Controller/` 根目录）
+- [ ] **Request 按接口类型放入正确子目录**（`Request/Api/` 或 `Request/Admin/`，不能平铺在 `Request/` 根目录）
+- [ ] Controller 命名空间含 `\Controller\Api\` 或 `\Controller\Admin\`
+- [ ] Request 命名空间含 `\Request\Api\` 或 `\Request\Admin\`
+- [ ] Controller 中 `use` 的 Request 路径与子目录命名空间一致
+- [ ] `Admin/` 下：Controller 自动加 `JwtAuthMiddleware`；类名与 `Api/` 保持一致，**不加 `Admin` 前缀**
+- [ ] 模块结构完整（composer.json + ConfigProvider.php + Http/Controller/{Api|Admin}/ + Http/Request/{Api|Admin}/）
+- [ ] composer.json name 为 `modules/{kebab-case}`
+- [ ] namespace 为 `Modules\{PascalCase}`
+- [ ] ConfigProvider 注册 `__DIR__` 扫描路径
+- [ ] extra.hyperf.config 指向正确 ConfigProvider
+- [ ] **无需修改主 composer.json**，ModuleLoader 自动发现
+- [ ] Hyperf ProviderConfig 能发现模块 ConfigProvider
+- [ ] `php -l` 无语法错误
diff --git a/.cursor/rules/skill-security-audit.mdc b/.cursor/rules/skill-security-audit.mdc
new file mode 100644
index 0000000..b7039fb
--- /dev/null
+++ b/.cursor/rules/skill-security-audit.mdc
@@ -0,0 +1,59 @@
+---
+description: >
+  安全审计技能。当用户要求安全审查、漏洞扫描、安全加固、
+  OWASP 检查或合规性检查时激活。遵循 OWASP Top 10 + CodeGuard 框架。
+alwaysApply: false
+---
+
+# Security Audit
+
+> 本文件是精简执行摘要。完整流程、命令和深度参考见：
+> Read `.cursor/skills/security-audit/SKILL.md`
+
+安全等级：RED — 审计结果包含敏感信息。
+
+## 执行流程
+
+### 1. 依赖安全扫描
+
+`npm audit --audit-level=high`、`composer audit`
+
+### 2. OWASP Top 10 检查
+
+| # | 风险 | 检查方法 |
+|---|------|---------|
+| A01 | 访问控制失效 | auth middleware + 数据权限 |
+| A02 | 加密失败 | bcrypt/Argon2id、HTTPS、JWT |
+| A03 | 注入 | 参数化查询、ORM |
+| A04 | 不安全设计 | 业务逻辑、并发、分布式锁 |
+| A05 | 安全配置 | CORS、headers、debug 关闭 |
+| A06 | 过时组件 | npm/composer audit |
+| A07 | 认证失败 | JWT 双 Token、密码策略 |
+| A08 | 数据完整性 | 反序列化、CI/CD |
+| A09 | 日志监控 | 覆盖率和告警 |
+| A10 | SSRF | HTTP 请求目标验证 |
+
+### 3. PHP / 前端 / 密钥扫描
+
+PHPStan、危险函数、v-html/eval/innerHTML、密钥格式检测。
+
+### 4. 中间件链验证
+
+CorsMiddleware -> TraceId -> RequestLog -> Auth -> Permission -> RateLimit -> RequestSign
+
+### 5. 输出报告
+
+Critical/High/Medium/Low 分级。
+
+## 验证
+
+- [ ] OWASP Top 10 逐项完成
+- [ ] npm/composer audit 无 critical/high
+- [ ] 无硬编码密钥
+- [ ] 安全头已配置
+- [ ] 中间件链完整
+
+## 深度参考
+
+- `.cursor/skills/security-audit/references/audit-commands.md`
+- `.cursor/skills/security-audit/references/security-headers.md`
diff --git a/.cursor/rules/skill-vue-page.mdc b/.cursor/rules/skill-vue-page.mdc
new file mode 100644
index 0000000..1749486
--- /dev/null
+++ b/.cursor/rules/skill-vue-page.mdc
@@ -0,0 +1,63 @@
+---
+description: >
+  Vue 3 + Vue Router 页面脚手架技能。新建路由页面、
+  含布局/加载状态/错误处理时激活。
+globs:
+  - "**/router/**/*.ts"
+  - "**/views/**/*.vue"
+alwaysApply: false
+---
+
+# Vue Page Scaffold
+
+> 本文件是精简执行摘要。完整流程、模板和深度参考见：
+> Read `.cursor/skills/vue-page/SKILL.md`
+
+> **适用性**（双模式）：
+> - **新建**路由页面：走完整执行流程（Step 1-6）
+> - **修改**已有页面：跳过脚手架步骤，完成后走「验证」清单
+
+依赖技能：`vue-testing`（Cursor 已通过 `skill-vue-testing` 规则自动加载）
+
+## 前端识别
+
+- **管理端**：Element Plus 布局
+- **用户端**：Headless UI + Tailwind，**禁止 Element Plus**
+
+## 执行流程
+
+1. 加载规范：Read `010-typescript.mdc`、`011-vue.mdc`、`019-modular.mdc`
+2. **生成前强制拆分分析**（写代码前必须输出）：
+   - 多视图检测：>=2 个排斥视图 → 每个视图独立组件
+   - 行数预估：template > 80 行 → 拆子组件，script > 60 行 → 提取 composable
+   - 重复 UI 检测：同一结构 >=3 次 → 提取基础组件
+3. 输出拆分方案：
+   ```
+   src/views/<module>/<page>/
+   ├── index.vue              <= 60 行（编排层）
+   ├── components/
+   │   ├── <ViewA>.vue        <= 120 行
+   │   └── <ViewB>.vue        <= 120 行
+   └── composables/
+       └── use<PageName>.ts   <= 80 行
+   ```
+4. 确认页面规格（路由路径、标题、模块、类型）
+5. 逐文件生成代码
+6. 配置路由（path、name、component 懒加载、meta）
+
+## 页面类型
+
+list | detail | form | dashboard | blank | multi-view
+
+## 验证
+
+- [ ] 页面正常渲染，document.title 正确
+- [ ] Loading 骨架屏 + 错误提示
+- [ ] meta.requiresAuth、meta.permission
+- [ ] index.vue <= 60 行
+- [ ] 无子组件超过 150 行
+- [ ] composable 参数有类型注解、ref 有泛型
+
+## 深度参考
+
+- `.cursor/skills/vue-page/references/page-templates.md`
diff --git a/.cursor/rules/skill-vue-testing.mdc b/.cursor/rules/skill-vue-testing.mdc
new file mode 100644
index 0000000..851dcd8
--- /dev/null
+++ b/.cursor/rules/skill-vue-testing.mdc
@@ -0,0 +1,65 @@
+---
+description: >
+  Vue 3 + Vitest 前端测试技能。新建或更新测试文件、
+  编写单元/组件/E2E 测试时激活。
+globs:
+  - "**/*.test.*"
+  - "**/__tests__/**"
+alwaysApply: false
+---
+
+# Vue Testing
+
+> 本文件是精简执行摘要。完整流程、模板和深度参考见：
+> Read `.cursor/skills/vue-testing/SKILL.md`
+
+> **适用性**：本技能用于**新建或更新测试文件**。
+> 非测试相关的代码修改可忽略本技能。
+
+## 测试决策树（每次写测试前必须先走）
+
+```
+纯转换逻辑（parse/format/validate/compute）→ 提取到 .utils.ts，Vitest 单元测试
+涉及复杂 UI 交互                             → Vue Test Utils 组件测试
+能提取为纯函数或 composable                   → 提取后写单元测试
+跨页面流程、关键业务路径                       → Playwright E2E
+```
+
+## 测试类型
+
+| 类型 | 工具 | 文件命名 |
+|------|------|---------|
+| 单元测试 | Vitest | *.test.ts |
+| 组件测试 | Vitest + Vue Test Utils | *.test.ts |
+| E2E | Playwright | *.spec.ts |
+
+## 核心原则
+
+1. **逻辑提取** — 业务逻辑提取到 .utils.ts 纯函数
+2. **穷举排列** — 有效/无效/空值/边界/安全输入
+3. **AAA 模式** — Arrange-Act-Assert
+4. **单一行为** — 每个 it() 只验证一个行为
+5. **命名** — `should <行为> when <条件>`
+
+## 增量式工作流
+
+工具函数 → Composables → 简单组件 → 复杂组件 → 集成。
+逐个文件：写测试 → vitest run → PASS 才下一个。
+
+## 覆盖率目标
+
+Function 100% | Statement 100% | Branch > 95% | Line > 95%
+
+## 验证
+
+- [ ] 走过决策树
+- [ ] 逻辑已提取到 .utils.ts
+- [ ] 穷举排列覆盖
+- [ ] 命名 should...when...
+- [ ] vitest run 全部通过
+- [ ] 覆盖率达标
+
+## 深度参考
+
+- `.cursor/skills/vue-testing/references/testing-templates.md`
+- `.cursor/skills/vue-testing/references/mock-patterns.md`
diff --git a/.cursor/skills/anti-scraping/SKILL.md b/.cursor/skills/anti-scraping/SKILL.md
new file mode 100644
index 0000000..0f97480
--- /dev/null
+++ b/.cursor/skills/anti-scraping/SKILL.md
@@ -0,0 +1,74 @@
+---
+name: anti-scraping
+version: 4.0.0
+description: "为 PHP Hyperf + Vue 3 应用设计反爬虫防护。当需要防御 Bot、限流或保护 API 时使用。覆盖五个威胁层级。"
+---
+
+# 🛡️ Anti-Scraping Protection — 全栈防爬体系
+
+## 威胁分级与对应策略
+
+| 等级 | 爬虫类型 | 典型工具 | 主要特征 | 防护策略 |
+|------|---------|---------|---------|---------|
+| **T1** | 简单脚本 | curl, wget, Python requests | 无 JS 执行，缺失必要 Header | UA 过滤 + Header 检查 |
+| **T2** | 爬虫框架 | Scrapy, Playwright (无配置), httpx | 自动处理 Cookie 但行为机械 | Header 指纹 + 速率限制 |
+| **T3** | 无头浏览器 | Puppeteer, Playwright (配置过) | 执行 JS 但 Canvas/WebGL 异常 | 浏览器指纹 + 行为分析 |
+| **T4** | 分布式集群 | 自建集群 + 代理池 + UA 轮换 | 跨 IP 协同，单 IP 请求少 | 关联分析 + 蜜罐 + PoW |
+| **T5** | AI 代理 | LLM 控制的浏览器 / GPT 插件 | 接近真实用户但行为规律性高 | 多维指纹 + CV 分析 + 挑战 |
+
+---
+
+## 触发条件
+
+用户询问防爬虫、限流、Bot 防护、爬虫识别、AI 爬虫、Scrapy 等关键词。
+
+## 执行流程
+
+### Phase 0：威胁评估
+
+在实施前回答以下问题，确定防护等级：
+
+| 问题 | 回答影响 |
+|------|---------|
+| 保护目标？（API / 页面内容 / 数据资产） | 决定防护位置（Nginx / Middleware / Frontend） |
+| 可接受的误伤率？（0.1% / 0.5% / 1%） | 决定阈值设定的松紧 |
+| 是否有 CDN/WAF？ | 可借用 WAF 能力，减少自研成本 |
+| 业务是否允许验证码？ | 影响 CAPTCHA 降级策略 |
+| 需要保护登录后内容还是公开内容？ | 决定是否使用前端指纹 Token |
+
+### Phase 1–4：前置与基础防护
+
+1. **Phase 1 Nginx** — UA 黑名单 map、limit_req/limit_conn，直接拒绝已知 Bot
+2. **Phase 2 指纹** — RequestFingerprintMiddleware 检查 UA/Header/Accept/Referer，输出 risk_score
+3. **Phase 3 限速** — RateLimitService 分层限速 + 请求间隔变异系数分析（CV）+ 子网关联分析
+4. **Phase 4 IP** — IpIntelligenceService 黑/白名单、TOR、数据中心、爬取广度（HyperLogLog）
+
+### Phase 5–6：高级识别
+
+5. **Phase 5 浏览器指纹** — 前端采集 Canvas/WebGL/音频/字体/鼠标，后端校验无头特征
+6. **Phase 6 AI 代理** — 请求间隔 CV、只读模式、速度、UA 与语言不匹配
+
+### Phase 7–9：对抗与响应
+
+7. **Phase 7 PoW** — 工作量证明挑战，真实用户 JS 自动计算
+8. **Phase 8 蜜罐** — 前端隐藏字段 + 后端蜜罐路由
+9. **Phase 9 综合** — AntiScrapingMiddleware 加权评分，差异化响应（封禁 / PoW / 延迟 / 假数据）
+
+## 验证清单
+
+1. [ ] `curl` 请求 3 次内触发 403 或 429
+2. [ ] Python `requests` 默认 UA 被 Nginx 直接拒绝
+3. [ ] Scrapy 爬取 100+ 页面被封 IP
+4. [ ] Puppeteer（无反指纹）指纹得分 ≥ 60，触发挑战
+5. [ ] 均匀间隔请求（CV < 0.2）被 AI 行为分析识别
+6. [ ] 蜜罐路由访问后 IP 被封
+7. [ ] PoW 挑战前端正确求解（difficulty=4，约 2 秒内完成）
+8. [ ] 同 /24 子网 500+ 请求触发代理池标记
+9. [ ] 正常用户误触率 < 0.2%
+
+## Tier 3 深度参考
+
+| 文件 | 内容 |
+|------|------|
+| `references/implementation-phases.md` | Phase 1–9 完整实现代码与 Redis 监控 |
+| `references/anti-scraping-patterns.md` | 反爬模式与策略速查 |
diff --git a/.cursor/skills/anti-scraping/references/anti-scraping-patterns.md b/.cursor/skills/anti-scraping/references/anti-scraping-patterns.md
new file mode 100644
index 0000000..f2a62f8
--- /dev/null
+++ b/.cursor/skills/anti-scraping/references/anti-scraping-patterns.md
@@ -0,0 +1,306 @@
+# Anti-Scraping 参考模式库
+
+## 1. 常见爬虫特征指纹
+
+### User-Agent 黑名单（正则）
+
+```typescript
+const BOT_UA_PATTERNS = [
+  // 爬虫框架
+  /python-requests/i,
+  /scrapy/i,
+  /beautifulsoup/i,
+  /selenium/i,
+  /playwright/i,
+  /puppeteer/i,
+  /mechanize/i,
+  /httpclient/i,
+  /java\/\d/i,
+  /go-http-client/i,
+  /ruby/i,
+
+  // 命令行工具
+  /curl\//i,
+  /wget\//i,
+  /httpie/i,
+  /insomnia/i,
+
+  // 无头浏览器特征
+  /headlesschrome/i,
+  /phantomjs/i,
+  /slimerjs/i,
+
+  // 已知数据采集
+  /dataprovider/i,
+  /yandexbot/i,
+  /mj12bot/i,
+  /ahrefsbot/i,
+  /semrushbot/i,
+  /dotbot/i,
+];
+
+export function isBotUA(ua: string): boolean {
+  return BOT_UA_PATTERNS.some(p => p.test(ua));
+}
+```
+
+### 允许的搜索引擎爬虫白名单
+
+```typescript
+// 合法爬虫：需要验证真实性（反向 DNS 查找）
+const ALLOWED_BOTS = [
+  { name: 'Googlebot', ua: /googlebot/i, rdns: 'googlebot.com' },
+  { name: 'Bingbot', ua: /bingbot/i, rdns: 'search.msn.com' },
+  { name: 'Baidu Spider', ua: /baiduspider/i, rdns: 'crawl.baidu.com' },
+];
+
+async function isLegitimateBot(ua: string, ip: string): Promise<boolean> {
+  const bot = ALLOWED_BOTS.find(b => b.ua.test(ua));
+  if (!bot) return false;
+
+  // 反向 DNS 验证（防止伪造 UA）
+  const hostname = await reverseDNS(ip);
+  return hostname?.endsWith(bot.rdns) ?? false;
+}
+```
+
+---
+
+## 2. 风险评分算法
+
+### 综合评分模型
+
+```typescript
+interface RiskFactors {
+  fingerprintScore: number;    // 0-100
+  rateScore: number;           // 0-100（超速时增加）
+  ipScore: number;             // 0-100（数据中心/Tor/VPN）
+  behaviorScore: number;       // 0-100（行为异常）
+}
+
+function calculateRiskScore(factors: RiskFactors): number {
+  const weights = {
+    fingerprint: 0.35,
+    rate: 0.30,
+    ip: 0.25,
+    behavior: 0.10,
+  };
+
+  return Math.min(
+    Math.round(
+      factors.fingerprintScore * weights.fingerprint +
+      factors.rateScore * weights.rate +
+      factors.ipScore * weights.ip +
+      factors.behaviorScore * weights.behavior
+    ),
+    100
+  );
+}
+
+// 响应策略
+function getResponseStrategy(score: number): 'allow' | 'slowdown' | 'challenge' | 'block' {
+  if (score >= 80) return 'block';
+  if (score >= 50) return 'challenge';
+  if (score >= 30) return 'slowdown';
+  return 'allow';
+}
+```
+
+---
+
+## 3. Redis 数据结构设计
+
+```
+# 速率限制（滑动窗口）
+ZSET  rl:{ip}                     → { timestamp: score }
+ZSET  rl:{ip}:{endpoint}          → { timestamp: score }
+
+# IP 黑白名单
+SET   ip:blocklist                → { ip1, ip2, ... }
+SET   ip:allowlist                → { ip1, ip2, ... }（合法爬虫白名单）
+SET   ip:tor-exit                 → { ip1, ip2, ... }
+SET   ip:datacenter               → { ip1, ip2, ... }
+
+# 蜜罐触发记录
+HASH  honeypot:hits               → { ip: count }
+
+# CAPTCHA 通过记录（防止重复挑战）
+STRING captcha:passed:{ip}        → "1"（TTL 1 小时）
+
+# 行为画像
+HASH  behavior:{ip}               → {
+  first_seen: timestamp,
+  request_count: number,
+  path_entropy: number,           # 访问路径多样性（低=爬虫）
+  referer_missing_ratio: number,  # 缺少 Referer 比例（高=爬虫）
+}
+```
+
+---
+
+## 4. Nginx 层防护（可选，性能最佳）
+
+```nginx
+# /etc/nginx/conf.d/anti-scraping.conf
+
+# 限速区域定义
+limit_req_zone $binary_remote_addr zone=api:10m rate=30r/m;
+limit_req_zone $binary_remote_addr zone=login:10m rate=5r/m;
+limit_conn_zone $binary_remote_addr zone=conn:10m;
+
+server {
+  # 连接数限制（单 IP 最多 20 并发）
+  limit_conn conn 20;
+
+  # UA 黑名单
+  if ($http_user_agent ~* "(python|curl|wget|scrapy|selenium)") {
+    return 403;
+  }
+
+  # 空 UA 拒绝
+  if ($http_user_agent = "") {
+    return 403;
+  }
+
+  location /api/ {
+    limit_req zone=api burst=10 nodelay;
+    limit_req_status 429;
+
+    proxy_pass http://app;
+  }
+
+  location /api/auth/ {
+    limit_req zone=login burst=2 nodelay;
+    limit_req_status 429;
+
+    proxy_pass http://app;
+  }
+
+  # 蜜罐路由（真实用户不会访问）
+  location /admin-backup/ {
+    access_log /var/log/nginx/honeypot.log;
+    # 记录访问者 IP 并返回假数据
+    return 200 '{"status":"ok"}';
+    add_header Content-Type application/json;
+  }
+}
+```
+
+---
+
+## 5. Cloudflare Workers 方案（Edge 层，最推荐）
+
+```typescript
+// workers/anti-scraping.ts
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const ip = request.headers.get('CF-Connecting-IP') ?? '';
+    const ua = request.headers.get('User-Agent') ?? '';
+
+    // 利用 Cloudflare 的威胁评分
+    const cfThreatScore = Number(request.headers.get('CF-Threat-Score') ?? 0);
+    if (cfThreatScore > 30) {
+      return new Response('Forbidden', { status: 403 });
+    }
+
+    // 利用 Cloudflare 的 Bot 管理分数（需开启 Bot Management）
+    const cfBotScore = Number(request.headers.get('CF-Bot-Score') ?? 100);
+    if (cfBotScore < 30) {
+      // 低分 = 高爬虫可能性
+      return new Response('Forbidden', { status: 403 });
+    }
+
+    // 自定义限速（使用 Durable Objects 或 KV）
+    const rateLimitKey = `rl:${ip}`;
+    const count = Number(await env.RATE_LIMIT.get(rateLimitKey) ?? 0);
+    if (count > 60) {
+      return new Response('Too Many Requests', {
+        status: 429,
+        headers: { 'Retry-After': '60' },
+      });
+    }
+
+    await env.RATE_LIMIT.put(rateLimitKey, String(count + 1), { expirationTtl: 60 });
+    return fetch(request);
+  },
+};
+```
+
+---
+
+## 6. 监控 Dashboard（Datadog / Grafana 指标）
+
+```typescript
+// lib/metrics.ts — 关键埋点
+export const antiScrapingMetrics = {
+  // 请求被拦截
+  blocked: (reason: 'fingerprint' | 'rate' | 'honeypot' | 'ip' | 'captcha') => {
+    metrics.increment('anti_scraping.blocked', { reason });
+  },
+
+  // 风险评分分布
+  scoreDistribution: (score: number) => {
+    metrics.histogram('anti_scraping.risk_score', score);
+  },
+
+  // CAPTCHA 展示与通过
+  captchaImpressed: () => metrics.increment('anti_scraping.captcha.impressed'),
+  captchaPassed: () => metrics.increment('anti_scraping.captcha.passed'),
+  captchaFailed: () => metrics.increment('anti_scraping.captcha.failed'),
+
+  // 误伤监控
+  falsePositive: (userId: string) => {
+    metrics.increment('anti_scraping.false_positive');
+    logger.warn({ userId }, 'Possible false positive in anti-scraping');
+  },
+};
+```
+
+---
+
+## 7. 测试用例
+
+```typescript
+// __tests__/anti-scraping.test.ts
+describe('Anti-Scraping', () => {
+  describe('Fingerprint Analysis', () => {
+    it('should flag Python requests as high risk', () => {
+      const score = analyzeFingerpring(mockRequest({
+        'user-agent': 'python-requests/2.28.0',
+      }));
+      expect(score).toBeGreaterThanOrEqual(50);
+    });
+
+    it('should not flag normal Chrome browser', () => {
+      const score = analyzeFingerpring(mockRequest({
+        'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36',
+        'accept-language': 'zh-CN,zh;q=0.9',
+        'accept-encoding': 'gzip, deflate, br',
+        'accept': 'text/html,application/xhtml+xml',
+      }));
+      expect(score).toBeLessThan(20);
+    });
+  });
+
+  describe('Rate Limiting', () => {
+    it('should block after exceeding limit', async () => {
+      const ip = '192.168.1.100';
+      // 发送 61 次请求
+      for (let i = 0; i < 61; i++) {
+        await checkRateLimit(ip, { windowMs: 60_000, limit: 60 });
+      }
+      const { allowed } = await checkRateLimit(ip);
+      expect(allowed).toBe(false);
+    });
+  });
+
+  describe('Honeypot', () => {
+    it('should block IP that triggers honeypot', async () => {
+      const ip = '10.0.0.1';
+      await triggerHoneypot(ip);
+      const isBlocked = await redis.sismember('ip:blocklist', ip);
+      expect(isBlocked).toBe(1);
+    });
+  });
+});
+```
diff --git a/.cursor/skills/anti-scraping/references/implementation-phases.md b/.cursor/skills/anti-scraping/references/implementation-phases.md
new file mode 100644
index 0000000..83fea0b
--- /dev/null
+++ b/.cursor/skills/anti-scraping/references/implementation-phases.md
@@ -0,0 +1,100 @@
+# Anti-Scraping — 完整实现代码
+
+> 主流程与决策逻辑见 SKILL.md，本文档为 Phase 1–9 的深度实现细节。
+
+## Phase 1：Nginx 前置拦截
+
+```nginx
+# /etc/nginx/conf.d/anti-scraping.conf
+map $http_user_agent $is_bot {
+    default 0;
+    ~*python-requests|python-urllib|httpx|aiohttp|scrapy|mechanize 1;
+    ~*curl|wget|libwww-perl|Go-http-client|Java/|okhttp|axios 1;
+    ~*HeadlessChrome|headless|PhantomJS|Playwright|Puppeteer|Selenium|webdriver 1;
+    ~*GPTBot|ChatGPT-User|Claude-Web|PerplexityBot|anthropic-ai|CCBot|DataForSeoBot|SemrushBot 1;
+    ~*Googlebot/|~*Bingbot/ 0;
+    "" 1;
+}
+
+limit_req_zone $binary_remote_addr zone=api_limit:10m rate=30r/m;
+limit_req_zone $binary_remote_addr zone=page_limit:10m rate=60r/m;
+limit_req_zone $binary_remote_addr zone=login_limit:10m rate=5r/m;
+limit_conn_zone $binary_remote_addr zone=conn_limit:10m;
+
+server {
+    if ($is_bot) { return 403; }
+    if ($http_user_agent = "") { return 444; }
+    location /api/ {
+        limit_req zone=api_limit burst=10 nodelay;
+        limit_conn conn_limit 20;
+        proxy_pass http://hyperf_upstream;
+    }
+    location /api/auth/ {
+        limit_req zone=login_limit burst=2 nodelay;
+        limit_req_status 429;
+        proxy_pass http://hyperf_upstream;
+    }
+}
+```
+
+## Phase 2：HTTP 请求指纹识别
+
+见 `RequestFingerprintMiddleware.php`：
+- `BROWSER_REQUIRED_HEADERS`: accept, accept-language, accept-encoding
+- `BROWSER_SECURITY_HEADERS`: sec-fetch-site, sec-fetch-mode, sec-fetch-dest, sec-ch-ua
+- `SUSPICIOUS_ACCEPT_PATTERNS`: */*, application/json, text/html,*/*;q=0.9
+- 评分逻辑：UA 缺失 +80，爬虫工具 +70，无头特征 +60，缺失 Header 每项 +15，缺失 sec-fetch +25，可疑 Accept +20，API 无 Referer +15
+
+## Phase 3：速率限制与行为分析
+
+`RateLimitService`：
+- `IP_RULES`: global/api/search/export/login/register 分层限速
+- `analyzeRequestPattern()`: 请求间隔变异系数 CV，CV < 0.3 或平均间隔 < 200ms 判定异常
+- `analyzeSubnetPattern()`: /24 子网 1 分钟 > 500 请求判定代理池
+- Redis key: `rl:{rule}:{ip}` (ZSET), `req_ts:{session}` (LIST)
+
+## Phase 4：IP 信誉与代理检测
+
+`IpIntelligenceService`：
+- `DATACENTER_PREFIXES`: AWS/GCP/Azure/Cloudflare/DigitalOcean/Vultr 等
+- `classify()`: blocklist → whitelist → tor → datacenter → residential
+- `trackCrawlBreadth()`: HyperLogLog 1 小时内 > 200 唯一路径判定爬虫
+
+## Phase 5：浏览器指纹识别
+
+前端 `collectFingerprint()`: Canvas/WebGL/音频/鼠标/字体 指纹
+后端 `BrowserFingerprintService.analyze()`: SwiftShader/llvmpipe/ANGLE +30，无音频 +20，字体全相同 +25，无鼠标 +20，4核0内存 +15
+
+## Phase 6：AI 代理行为识别
+
+`AiBotDetectionService`: CV < 0.2 加 45，纯只读 GET +25，平均间隔 < 300ms +30，UA 与语言不匹配 +15；总分 ≥ 60 判定 AI Bot
+
+## Phase 7：工作量证明 PoW
+
+前端 `solvePoW()`: SHA-256 前缀匹配，difficulty=4 约 1 万次
+后端 `PoWService`: generate() 生成 nonce+id，verify() 校验并防重放
+
+## Phase 8：蜜罐
+
+前端：CSS 隐藏 input，随机字段名，提交时检测 honeypot 有值则 reportBot
+后端：`/api/internal/user-export-all` 蜜罐路由，访问即封 IP 1 小时
+
+## Phase 9：综合评分与差异化响应
+
+`AntiScrapingMiddleware`: 加权汇总 headerScore*0.2 + ipRisk*0.15 + rateScore*0.25 + breadthScore*0.15 + patternScore*0.15 + subnetScore*0.05 + fpScore*0.05
+- total ≥ 90: 封 IP 2 小时
+- total ≥ 70: 要求 PoW 挑战
+- total ≥ 50: 延迟 0.5–2 秒
+- total ≥ 30: 敏感接口返回空数据
+
+## 监控与 Redis 清理
+
+| 指标 | 告警阈值 |
+|------|---------|
+| 403 响应率 | > 3% |
+| 429 响应率 | > 5% |
+| PoW 触发量 | > 100/小时 |
+| 蜜罐触发量 | > 50/天 |
+| IP 封禁量 | > 200/天 |
+
+Redis TTL: rl/req_ts/req_log/crawl_breadth/subnet_req/pow 均设 TTL，ip:blocklist 定期清理过期封禁。
diff --git a/.cursor/skills/api-scaffold/SKILL.md b/.cursor/skills/api-scaffold/SKILL.md
new file mode 100644
index 0000000..d3cb521
--- /dev/null
+++ b/.cursor/skills/api-scaffold/SKILL.md
@@ -0,0 +1,71 @@
+---
+name: api-scaffold
+version: 3.0.0
+description: "生成 Hyperf API 端点脚手架（Controller/Service/FormRequest/路由）。当需要新建 API 接口或 CRUD 资源时使用。含分级异常体系。"
+---
+
+> ⚠️ 核心执行流程已在 `.cursor/rules/skill-backend-scaffold.mdc` 中由 Cursor 自动注入。
+> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
+
+# Hyperf API Endpoint Scaffold
+
+## 触发条件
+
+用户要求创建新 API 端点、路由、接口、REST 资源或 CRUD 操作。
+
+## 执行流程
+
+### 0. 加载规范（⚠️ 必须最先执行）
+
+依次使用 `Read` 工具读取：
+- `.cursor/rules/013-backend.mdc` — ApiResponse 格式、FormRequest、路由、认证
+- `.cursor/rules/019-modular.mdc` — Controller→Service→Repository→Model 依赖方向、各层职责
+
+### 1. 确认端点规格
+
+| 字段 | 必填 | 默认值 |
+|------|------|--------|
+| 资源名称 | ✅ | — |
+| HTTP 方法 | ✅ | — |
+| 路由路径 | ✅ | — |
+| 请求体结构 | GET 除外 | — |
+| 响应结构 | ✅ | — |
+| 需要认证？ | ❌ | true |
+| 需要权限？ | ❌ | true |
+| 分页？ | ❌ | GET 列表自动加 |
+
+### 2. 生成文件
+
+生成 Controller、Service、FormRequest、Model（如不存在）、路由。分层约定与完整模板见 **Tier 3**。
+
+### 3. 遵循项目约定
+
+生成前扫描：`app/Controller/` 现有模式、`AbstractController` 基类、`AppExceptionHandler`、中间件注册方式。
+
+### 4. 异常体系
+
+- `BusinessException` — 404/403/409/422 等可预期业务错误
+- `ValidationException` — FormRequest 校验失败
+- `SystemException` — 500 系统故障，记录堆栈并通知运维
+
+异常选择决策与 `AppExceptionHandler` 实现见 **Tier 3**。
+
+## 验证
+
+1. [ ] `php -l` 编译无错误
+2. [ ] FormRequest rules 覆盖所有请求字段
+3. [ ] 错误处理覆盖 400/401/403/404/422/500
+4. [ ] Service 使用事务包裹写操作
+5. [ ] 路由遵循 RESTful 命名（复数名词、kebab-case）
+6. [ ] 中间件正确挂载（认证 + 权限）
+7. [ ] 可预期错误使用 `BusinessException`
+8. [ ] 不可预期错误使用 `SystemException`
+9. [ ] `SystemException` 不向客户端暴露内部细节
+10. [ ] `AppExceptionHandler` 已注册在 `config/autoload/exceptions.php`
+
+## Tier 3 深度参考
+
+| 文件 | 内容 |
+|------|------|
+| `references/code-templates.md` | Controller/Service/FormRequest/路由完整模板 |
+| `references/exception-handling.md` | 分级异常体系与 AppExceptionHandler 实现 |
diff --git a/.cursor/skills/api-scaffold/references/api-response.md b/.cursor/skills/api-scaffold/references/api-response.md
new file mode 100644
index 0000000..af89e06
--- /dev/null
+++ b/.cursor/skills/api-scaffold/references/api-response.md
@@ -0,0 +1,41 @@
+# API 统一响应格式
+
+## 成功响应
+
+```json
+{
+  "data": { ... },
+  "meta": {
+    "page": 1,
+    "pageSize": 20,
+    "total": 100,
+    "totalPages": 5
+  }
+}
+```
+
+## 错误响应
+
+```json
+{
+  "error": "Human-readable error message",
+  "code": "VALIDATION_ERROR",
+  "details": [ ... ]
+}
+```
+
+## HTTP 状态码
+
+| 状态码 | 场景 |
+|--------|------|
+| 200 | 查询/更新成功 |
+| 201 | 创建成功 |
+| 204 | 删除成功（无响应体） |
+| 400 | 请求参数验证失败 |
+| 401 | 未认证 |
+| 403 | 已认证但无权限 |
+| 404 | 资源不存在 |
+| 409 | 资源冲突（如重复创建） |
+| 422 | 业务逻辑错误 |
+| 429 | 请求频率超限 |
+| 500 | 服务器内部错误 |
diff --git a/.cursor/skills/api-scaffold/references/code-templates.md b/.cursor/skills/api-scaffold/references/code-templates.md
new file mode 100644
index 0000000..2c5d2c5
--- /dev/null
+++ b/.cursor/skills/api-scaffold/references/code-templates.md
@@ -0,0 +1,156 @@
+# API Scaffold — 代码模板与异常体系
+
+> 主流程见 SKILL.md，本文档为 Controller/Service/FormRequest/路由 的完整代码模板。
+
+## Hyperf 分层目录约定
+
+| 文件 | 路径 |
+|------|------|
+| Controller | `app/Controller/Admin/<Resource>Controller.php` |
+| Service | `app/Service/<Module>/<Resource>Service.php` |
+| FormRequest | `app/Request/<Module>/Create<Resource>Request.php` |
+| Model | `app/Model/<Module>/<Resource>.php`（如不存在） |
+| Route | `app/Http/Admin/Router/<resource>.php` |
+
+## Controller 模板
+
+```php
+<?php
+declare(strict_types=1);
+namespace App\Controller\Admin;
+
+use App\Request\{{Module}}\Create{{Resource}}Request;
+use App\Service\{{Module}}\{{Resource}}Service;
+use Hyperf\Di\Annotation\Inject;
+
+#[Controller(prefix: '/admin/{{route-path}}')]
+class {{Resource}}Controller extends AbstractController
+{
+    #[Inject]
+    protected {{Resource}}Service $service;
+
+    #[RequestMapping(path: '', methods: ['GET'])]
+    public function list(RequestInterface $request): ResponseInterface {
+        $params = $request->all();
+        $result = $this->service->getPageList($params);
+        return $this->success($result);
+    }
+
+    #[RequestMapping(path: '{id:\d+}', methods: ['GET'])]
+    public function detail(int $id): ResponseInterface {
+        $result = $this->service->getById($id);
+        return $this->success($result);
+    }
+
+    #[RequestMapping(path: '', methods: ['POST'])]
+    public function create(Create{{Resource}}Request $request): ResponseInterface {
+        $data = $request->validated();
+        $result = $this->service->create($data);
+        return $this->success($result, 201);
+    }
+
+    #[RequestMapping(path: '{id:\d+}', methods: ['PUT'])]
+    public function update(int $id, Create{{Resource}}Request $request): ResponseInterface {
+        $data = $request->validated();
+        $result = $this->service->update($id, $data);
+        return $this->success($result);
+    }
+
+    #[RequestMapping(path: '{id:\d+}', methods: ['DELETE'])]
+    public function delete(int $id): ResponseInterface {
+        $this->service->delete($id);
+        return $this->success(null, message: 'Deleted');
+    }
+}
+```
+
+## Service 模板
+
+```php
+<?php
+namespace App\Service\{{Module}};
+
+use App\Model\{{Module}}\{{Resource}};
+use App\Exception\BusinessException;
+use Hyperf\DbConnection\Db;
+
+class {{Resource}}Service
+{
+    public function getPageList(array $params): array {
+        $query = {{Resource}}::query();
+        if (!empty($params['status'])) $query->where('status', $params['status']);
+        $page = (int) ($params['page'] ?? 1);
+        $pageSize = (int) ($params['page_size'] ?? 10);
+        $total = $query->count();
+        $items = $query->orderByDesc('id')->offset(($page - 1) * $pageSize)->limit($pageSize)->get();
+        return ['items' => $items, 'total' => $total];
+    }
+
+    public function getById(int $id): {{Resource}} {
+        $record = {{Resource}}::find($id);
+        if (!$record) throw new BusinessException(404, '{{Resource}} not found');
+        return $record;
+    }
+
+    public function create(array $data): {{Resource}} {
+        return Db::transaction(fn () => {{Resource}}::create($data));
+    }
+
+    public function update(int $id, array $data): {{Resource}} {
+        $record = $this->getById($id);
+        return Db::transaction(function () use ($record, $data) {
+            $record->update($data);
+            return $record->refresh();
+        });
+    }
+
+    public function delete(int $id): void {
+        $record = $this->getById($id);
+        $record->delete();
+    }
+}
+```
+
+## FormRequest 模板
+
+```php
+<?php
+namespace App\Request\{{Module}};
+
+use Hyperf\Validation\Request\FormRequest;
+
+class Create{{Resource}}Request extends FormRequest
+{
+    public function authorize(): bool { return true; }
+    public function rules(): array {
+        return [ /* Define validation rules based on resource fields */ ];
+    }
+}
+```
+
+## 路由注册
+
+```php
+// app/Http/Admin/Router/{{resource}}.php
+use App\Controller\Admin\{{Resource}}Controller;
+use Hyperf\HttpServer\Router\Router;
+
+Router::addGroup('/admin/{{route-path}}', function () {
+    Router::get('', [{{Resource}}Controller::class, 'list']);
+    Router::get('/{id:\d+}', [{{Resource}}Controller::class, 'detail']);
+    Router::post('', [{{Resource}}Controller::class, 'create']);
+    Router::put('/{id:\d+}', [{{Resource}}Controller::class, 'update']);
+    Router::delete('/{id:\d+}', [{{Resource}}Controller::class, 'delete']);
+}, ['middleware' => [AccessTokenMiddleware::class, PermissionMiddleware::class]]);
+```
+
+## 统一响应格式
+
+```php
+protected function success(mixed $data = null, int $code = 200, string $message = 'ok'): ResponseInterface {
+    return $this->response->json(['code' => $code, 'message' => $message, 'data' => $data]);
+}
+protected function error(string $message, int $code = 500, mixed $data = null): ResponseInterface {
+    return $this->response->json(['code' => $code, 'message' => $message, 'data' => $data]);
+}
+```
diff --git a/.cursor/skills/api-scaffold/references/exception-handling.md b/.cursor/skills/api-scaffold/references/exception-handling.md
new file mode 100644
index 0000000..13c4fe7
--- /dev/null
+++ b/.cursor/skills/api-scaffold/references/exception-handling.md
@@ -0,0 +1,100 @@
+# API Scaffold — 分级异常体系
+
+> 主流程见 SKILL.md，本文档为异常分级与 AppExceptionHandler 完整实现。
+
+## 异常分级
+
+| 异常类 | 场景 | HTTP 状态码 | 日志级别 | 是否通知运维 |
+|---|---|---|---|---|
+| `BusinessException` | 可预期的业务错误 | 400/403/404/409/422 | warning | ❌ |
+| `ValidationException` | 参数校验失败 | 422 | info | ❌ |
+| `SystemException` | 不可预期的系统故障 | 500/502/503 | error | ✅ |
+
+## BusinessException / SystemException 定义
+
+```php
+// app/Exception/BusinessException.php
+class BusinessException extends ServerException
+{
+    public function __construct(int $code = 400, string $message = 'Business error', public readonly bool $isOperational = true)
+    {
+        parent::__construct($message, $code);
+    }
+}
+
+// app/Exception/SystemException.php
+class SystemException extends ServerException
+{
+    public function __construct(string $message = 'System error', int $code = 500, public readonly bool $isOperational = false, ?\Throwable $previous = null)
+    {
+        parent::__construct($message, $code, $previous);
+    }
+}
+```
+
+## AppExceptionHandler
+
+```php
+<?php
+namespace App\Exception\Handler;
+
+use App\Exception\BusinessException;
+use App\Exception\SystemException;
+use Hyperf\ExceptionHandler\ExceptionHandler;
+use Hyperf\HttpMessage\Stream\SwooleStream;
+use Hyperf\Validation\ValidationException;
+
+class AppExceptionHandler extends ExceptionHandler
+{
+    public function handle(\Throwable $throwable, ResponseInterface $response): ResponseInterface
+    {
+        $this->stopPropagation();
+        $body = match (true) {
+            $throwable instanceof ValidationException => ['code' => 422, 'message' => 'Validation failed', 'data' => $throwable->validator->errors()->toArray()],
+            $throwable instanceof BusinessException => ['code' => $throwable->getCode(), 'message' => $throwable->getMessage(), 'data' => null],
+            $throwable instanceof SystemException => $this->handleSystemException($throwable),
+            default => $this->handleUnexpected($throwable),
+        };
+        $statusCode = ($body['code'] >= 100 && $body['code'] < 600) ? $body['code'] : 500;
+        return $response->withStatus($statusCode)->withHeader('Content-Type', 'application/json')
+            ->withBody(new SwooleStream(json_encode($body, JSON_UNESCAPED_UNICODE)));
+    }
+
+    private function handleSystemException(SystemException $e): array {
+        $this->logger->error('System exception', ['message' => $e->getMessage(), 'trace' => $e->getTraceAsString()]);
+        return ['code' => 500, 'message' => 'Internal server error', 'data' => null];
+    }
+
+    private function handleUnexpected(\Throwable $e): array {
+        $this->logger->critical('Unexpected exception', ['class' => get_class($e), 'message' => $e->getMessage()]);
+        return ['code' => 500, 'message' => 'Internal server error', 'data' => null];
+    }
+
+    public function isValid(\Throwable $throwable): bool { return true; }
+}
+```
+
+## 异常选择决策
+
+```
+抛出异常？
+├─ 用户输入/请求导致的？
+│  ├─ 参数格式错误 → ValidationException（FormRequest 自动抛出）
+│  ├─ 资源不存在 → BusinessException(404)
+│  ├─ 无权限 → BusinessException(403)
+│  └─ 业务规则冲突 → BusinessException(409/422)
+└─ 系统/环境导致的？
+   ├─ 数据库连接失败 → SystemException(503)
+   ├─ 第三方 API 超时 → SystemException(502)
+   └─ 未知异常 → AppExceptionHandler 兜底
+```
+
+## Service 使用示例
+
+```php
+// Predictable: resource not found
+throw new BusinessException(404, 'Order not found');
+
+// Unpredictable: external system failure
+throw new SystemException(message: 'ERP sync failed: connection timeout', previous: $e);
+```
diff --git a/.cursor/skills/bug-reproduce/SKILL.md b/.cursor/skills/bug-reproduce/SKILL.md
new file mode 100644
index 0000000..cc82627
--- /dev/null
+++ b/.cursor/skills/bug-reproduce/SKILL.md
@@ -0,0 +1,239 @@
+---
+name: bug-reproduce
+version: 1.1.0
+description: "结构化 Bug 复现框架，系统化定位和复现 Bug。当需要从 Bug 报告出发编写复现步骤和回归测试时使用。仅复现，不修复。"
+requires: [vue-testing]
+---
+
+# Bug 复现框架（PHP Hyperf + Vue 3）
+
+## 触发条件
+
+用户提供 Bug 报告、Issue 描述，要求复现问题或编写回归测试。
+
+## ⚠️ 核心原则
+
+- **只复现，不修复** — 输出是失败的测试用例，不是修复代码
+- **最多 3 次尝试** — 3 次无法复现即标记为 UNCONFIRMED
+- **遇到硬停止条件立即放弃** — 不浪费时间在不可能的事上
+
+## 执行流程
+
+### 1. 信号解析（Parse Signals）
+
+从用户提供的 Bug 报告中提取关键信号：
+
+```
+□ 错误消息 / 堆栈追踪
+□ 复现步骤（操作序列）
+□ 影响区域（后端服务 / 前端组件 / API / 数据库）
+□ 环境信息（PHP 版本 / 浏览器 / OS）
+□ 何时开始出现 / 上次正常的版本
+□ 是否可稳定复现 / 偶发
+```
+
+### 2. 路由到测试策略（Route to Test Layer）
+
+根据影响区域，选择对应的测试层级和工具：
+
+| 影响区域 | 测试层 | 工具 | 关键目录 |
+|---|---|---|---|
+| PHP Service/Repository | 单元测试 | PHPUnit + Mockery | `Case-Database-Backend/test/Unit/` |
+| Controller/API 端点 | 集成测试 | Hyperf Testing HttpClient | `Case-Database-Backend/test/Feature/` |
+| 中间件/认证 | 集成测试 | Hyperf Testing | `Case-Database-Backend/test/Feature/` |
+| 数据库 Migration/Model | 单元测试 | PHPUnit + SQLite | `Case-Database-Backend/test/Unit/` |
+| Vue 组件逻辑 | 单元测试 | Vitest | `frontend-*/src/**/*.test.ts` |
+| Vue 组件交互 | 组件测试 | Vitest + Vue Test Utils | `frontend-*/src/**/*.test.ts` |
+| 跨页面流程 | E2E 测试 | Playwright | `frontend-*/e2e/` |
+| API ↔ 前端联调 | E2E 测试 | Playwright | `frontend-*/e2e/` |
+
+### 3. 定位源码（Locate Source Files）
+
+```bash
+# 搜索相关文件
+rg -l "ClassName\|functionName" --type php --glob '!vendor/**'
+rg -l "ComponentName" --glob '*.vue' --glob '!node_modules/**'
+
+# 查看最近变更
+git log --oneline -10 -- <affected-path>
+
+# 查看 diff
+git diff HEAD~5 -- <affected-path>
+```
+
+### 4. 追踪代码路径（Trace Code Path）
+
+从入口点到失败点，追踪完整的调用链：
+
+**后端路径示例**：
+```
+Route → Middleware → Controller → FormRequest → Service → Repository → Model → DB
+```
+
+**前端路径示例**：
+```
+用户操作 → Event Handler → Composable/Store → API Request → 响应处理 → UI 更新
+```
+
+记录每个节点的输入输出和异常处理情况。
+
+### 5. 形成假设（Hypothesize）
+
+陈述清晰、可测试的假设：
+
+```
+假设 A (70%): 当 [输入/条件] 时，代码在 [位置] 执行了 [错误行为]，
+              因为 [根因分析]。
+假设 B (20%): ...
+假设 C (10%): ...
+```
+
+每个假设必须指向具体的代码行。
+
+### 6. 查找测试模式（Find Test Patterns）
+
+在编写测试前，先查找同区域的已有测试作为参考：
+
+```bash
+# 查找 PHP 测试
+rg -l "class.*Test" --type php Case-Database-Backend/test/
+
+# 查找 Vue 测试
+rg -l "describe\|it\(" --glob '*.test.ts' Case-Database-Frontend-*/src/
+```
+
+使用相同的 mock 模式和 setup 结构保持一致性。
+
+### 7. 编写失败测试（Write Failing Test）
+
+测试必须满足：
+- 使用步骤 6 中找到的已有模式
+- 断言**正确行为**（测试在当前代码上会失败）
+- 包含 Bug 引用注释
+- 同时包含一个 happy path 测试（证明 setup 正确）
+
+**PHP 测试模板**：
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace HyperfTest\Unit;
+
+use PHPUnit\Framework\TestCase;
+
+class OrderServiceTest extends TestCase
+{
+    // Happy path — proves setup works
+    public function testCreateOrderWithValidData(): void
+    {
+        $service = new OrderService($this->mockRepo);
+        $result = $service->create(['amount' => 100]);
+        $this->assertNotNull($result->id);
+    }
+
+    // Regression — reproduces the bug
+    // @see https://github.com/org/repo/issues/123
+    public function testCreateOrderRejectsNegativeAmount(): void
+    {
+        $service = new OrderService($this->mockRepo);
+        $this->expectException(BusinessException::class);
+        $service->create(['amount' => -1]);
+    }
+}
+```
+
+**Vitest 测试模板**：
+
+```typescript
+import { getStatusText } from './OrderStatus.utils'
+
+describe('OrderStatus (Bug #123)', () => {
+  // Happy path
+  it('should return correct status for paid order', () => {
+    expect(getStatusText('paid', false)).toBe('待发货')
+  })
+
+  // Regression — reproduces the bug
+  // @see https://github.com/org/repo/issues/123
+  it('should handle null status without crashing', () => {
+    expect(() => getStatusText(null, false)).not.toThrow()
+    expect(getStatusText(null, false)).toBe('待支付')
+  })
+})
+```
+
+### 8. 运行并评分（Run & Score）
+
+```bash
+# PHP
+cd Case-Database-Backend && composer test -- --filter=OrderServiceTest
+
+# Vue
+cd Case-Database-Frontend-user && npx vitest run OrderStatus.utils.test.ts
+```
+
+根据结果评定置信度：
+
+| 置信度 | 判定条件 | 后续动作 |
+|---|---|---|
+| **CONFIRMED** | 测试稳定失败，失败模式与假设吻合 | 输出复现报告 |
+| **LIKELY** | 测试失败，但失败方式与预期略有偏差 | 报告 + 附注偏差原因 |
+| **UNCONFIRMED** | 无法触发失败 | 报告已尝试的方法 |
+| **SKIPPED** | 遇到硬停止条件 | 报告停止原因 |
+| **ALREADY_FIXED** | Bug 在当前代码上不可复现 | 报告何时修复的 |
+
+### 9. 迭代或放弃（Iterate or Bail）
+
+**UNCONFIRMED 后的迭代**（最多 3 次）：
+1. 重新审视假设 — 重读代码路径
+2. 尝试不同的测试方式或层级
+3. 第 3 次仍失败 → 标记 UNCONFIRMED
+
+**硬停止条件**（遇到即立即 SKIP）：
+- 需要真实第三方 API 凭证（支付网关、短信服务等）
+- 竞态条件/时序依赖（需要精确的并发控制）
+- 需要特定云基础设施（AWS/阿里云特定服务）
+- 需要无法脚本化的手动 UI 操作
+- 需要生产数据库中的真实数据
+
+## 输出：复现报告
+
+```markdown
+## 🐛 Bug 复现报告
+
+**Issue**: [ID] — [标题]
+**置信度**: CONFIRMED | LIKELY | UNCONFIRMED | SKIPPED | ALREADY_FIXED
+
+### 根因分析
+[1-2 句话解释 Bug 产生的机制]
+
+### 定位
+| 文件 | 行号 | 问题 |
+|---|---|---|
+| `path/to/file.php` | XX-YY | 描述 |
+
+### 失败测试
+`path/to/test/file` — X/Y 个测试失败：
+1. `testName` — [失败描述]
+
+### 修复提示
+[修复方向的伪代码或文字描述，不写完整修复代码]
+
+### 尝试记录
+| 次数 | 假设 | 测试方法 | 结果 |
+|---|---|---|---|
+| 1 | [假设 A] | [测试方式] | FAIL/PASS |
+| 2 | [假设 B] | [测试方式] | FAIL/PASS |
+```
+
+## 验证
+
+1. [ ] 从 Bug 报告中提取了所有关键信号
+2. [ ] 选择了正确的测试层级
+3. [ ] 失败测试包含 Bug 引用注释
+4. [ ] 同时有 happy path 测试证明 setup 正确
+5. [ ] 置信度评分有据可依
+6. [ ] 测试文件已保留（未删除）
+7. [ ] 输出了结构化复现报告
diff --git a/.cursor/skills/code-review/SKILL.md b/.cursor/skills/code-review/SKILL.md
new file mode 100644
index 0000000..7971f75
--- /dev/null
+++ b/.cursor/skills/code-review/SKILL.md
@@ -0,0 +1,209 @@
+---
+name: code-review
+version: 2.0.0
+description: "从六个维度系统化代码审查（安全/正确/可维护/性能/可测试/一致性）。当需要 Review 代码、检查质量或预提交检查时使用。"
+---
+
+> ⚠️ 核心执行流程已在 `.cursor/rules/skill-code-review.mdc` 中由 Cursor 自动注入。
+> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
+
+# Code Review
+
+## 触发条件
+
+用户要求审查代码、检查 PR、评估代码质量或执行预提交检查。
+
+## 执行流程
+
+### 1. 确定审查范围
+
+- 具体文件 → 审查指定文件
+- 目录范围 → 审查目录下所有变更
+- Git diff → `git diff HEAD~1` 审查最近变更
+
+### 2. 六维度审查
+
+按以下顺序逐一审查：
+
+**🔴 安全性 (Security)**
+- 硬编码密钥/凭证？
+- SQL 注入 / XSS 风险？
+- 未验证的用户输入？
+- 不安全的认证/授权？
+
+```php
+// ❌ BAD: 直接拼接用户输入到 SQL
+$users = Db::select("SELECT * FROM users WHERE name = '{$name}'");
+
+// ✅ GOOD: 参数绑定
+$users = Db::select("SELECT * FROM users WHERE name = ?", [$name]);
+// ✅ GOOD: Hyperf ORM
+$users = User::where('name', $name)->get();
+```
+
+```vue
+<!-- ❌ BAD: 直接渲染用户输入的 HTML -->
+<div v-html="userInput" />
+
+<!-- ✅ GOOD: 文本插值自动转义 -->
+<div>{{ userInput }}</div>
+
+<!-- ✅ GOOD: 如必须用 v-html，先经过 DOMPurify 清洗 -->
+<div v-html="sanitize(userInput)" />
+```
+
+**🟠 正确性 (Correctness)**
+- 逻辑是否正确？
+- 边界条件处理？
+- 错误处理完善？
+- null/undefined 安全？
+
+```php
+// ❌ BAD: 无空值保护
+$userName = $user->profile->name;
+
+// ✅ GOOD: 空安全访问
+$userName = $user?->profile?->name ?? 'Unknown';
+```
+
+```typescript
+// ❌ BAD: 解构可能为 null 的响应
+const { data } = await api.getUser(id)
+
+// ✅ GOOD: 防御性解构
+const response = await api.getUser(id)
+const data = response?.data ?? null
+```
+
+**🟡 可维护性 (Maintainability)**
+- 命名清晰？
+- 函数长度合理（< 50 行）？
+- 单一职责？
+- 业务逻辑是否已提取到纯函数/composable？
+
+```vue
+<!-- ❌ BAD: 组件内嵌大量业务逻辑 -->
+<script setup>
+const result = computed(() => {
+  // 30 行复杂计算逻辑...
+})
+</script>
+
+<!-- ✅ GOOD: 逻辑提取到 .utils.ts -->
+<script setup>
+import { calculateResult } from './MyComponent.utils'
+const result = computed(() => calculateResult(props.data))
+</script>
+```
+
+**🔵 性能 (Performance)**
+- 不必要的渲染？
+- N+1 查询？
+- 大数据集未分页？
+- 缺少缓存机会？
+
+```php
+// ❌ BAD: N+1 查询
+$orders = Order::all();
+foreach ($orders as $order) {
+    echo $order->user->name; // each iteration queries DB
+}
+
+// ✅ GOOD: 预加载关联
+$orders = Order::with('user')->get();
+```
+
+```vue
+<!-- ❌ BAD: v-for 内使用复杂计算 -->
+<div v-for="item in list" :key="item.id">
+  {{ heavyCompute(item) }}
+</div>
+
+<!-- ✅ GOOD: 预计算或使用 computed -->
+<div v-for="item in computedList" :key="item.id">
+  {{ item.computedValue }}
+</div>
+```
+
+**🟣 可测试性 (Testability)**
+- 纯函数是否已提取到 `.utils.ts`？
+- composable 是否可独立测试？
+- 关键路径是否有 `data-testid`？
+- 是否有过度耦合使测试困难？
+
+```typescript
+// ❌ BAD: 逻辑耦合在组件中，无法独立测试
+// 必须 mount 整个组件才能测试 formatDate
+
+// ✅ GOOD: 提取为可独立测试的纯函数
+// date.utils.ts
+export function formatDate(date, format = 'YYYY-MM-DD') { ... }
+// date.utils.test.ts
+it('should format date correctly', () => { ... })
+```
+
+**⚪ 一致性 (Consistency)**
+- 命名风格统一？
+- 遵循项目模式？
+- import 顺序统一？
+- 错误处理模式统一？
+
+### 3. 预提交检查联动
+
+审查代码时，同步执行以下自动化检查：
+
+```bash
+# PHP 后端
+cd Case-Database-Backend
+vendor/bin/phpstan analyse --level=5 --no-progress    # 静态分析
+vendor/bin/php-cs-fixer fix --dry-run --diff           # 代码格式
+
+# Vue 前端
+cd Case-Database-Frontend-user
+npx eslint --quiet src/                                # ESLint
+npx vitest run --reporter=verbose                      # 单元测试
+cd ..
+```
+
+如果项目配置了 husky + lint-staged，确认 `.husky/pre-commit` 钩子覆盖：
+- [ ] ESLint (前端)
+- [ ] PHPStan (后端)
+- [ ] 代码格式检查 (Prettier / PHP CS Fixer)
+
+### 4. 输出格式
+
+```markdown
+## 代码审查报告
+
+**范围**: <文件/目录/PR>
+**总体评价**: ✅ 建议合并 | ⚠️ 需修改后合并 | ❌ 需重写
+
+### 自动化检查
+- ESLint: ✅ 通过 | ❌ N 个错误
+- PHPStan: ✅ 通过 | ❌ N 个错误
+- 测试: ✅ 通过 | ❌ N 个失败
+
+### 发现
+
+#### 🔴 Must Fix
+1. **[SEC]** `file.ts:23` — 硬编码 API Key
+   → 修复：移入环境变量
+
+#### 🟡 Should Fix
+2. **[MAINT]** `service.ts:45` — 函数过长（87 行）
+   → 建议：拆分为 3 个私有方法
+3. **[TEST]** `OrderForm.vue` — 价格计算逻辑未提取到 .utils.ts
+   → 建议：提取为纯函数并添加单元测试
+
+#### 🟢 Suggestion
+4. **[PERF]** `list.vue:12` — 列表项未使用 `v-memo`
+   → 建议：添加 `v-memo="[item.id]"` 减少重渲染
+```
+
+## 验证
+
+1. [ ] 六个维度全部覆盖（含可测试性）
+2. [ ] 每个发现有具体文件和行号
+3. [ ] 每个发现有修复建议（含 BAD/GOOD 代码对比）
+4. [ ] 发现按严重程度分级
+5. [ ] 预提交检查已执行（ESLint + PHPStan + 测试）
diff --git a/.cursor/skills/component-scaffold/SKILL.md b/.cursor/skills/component-scaffold/SKILL.md
new file mode 100644
index 0000000..80fb180
--- /dev/null
+++ b/.cursor/skills/component-scaffold/SKILL.md
@@ -0,0 +1,197 @@
+---
+name: component-scaffold
+version: 4.1.0
+description: "生成 Vue 3 SFC 组件脚手架，含单元测试和类型安全 Props。当需要新建组件、拆分子组件或创建复合组件时使用。管理端用 Element Plus，用户端用 Headless UI。"
+requires: [vue-testing]
+---
+
+> ⚠️ 核心执行流程已在 `.cursor/rules/skill-component-scaffold.mdc` 中由 Cursor 自动注入。
+> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
+
+# Vue 3 Component Scaffold
+
+> **⚠️ 前端识别**：生成组件前必须确认目标前端。
+> - **管理端** (`Case-Database-Frontend-admin/`)：使用 Element Plus + Tailwind
+> - **用户端** (`Case-Database-Frontend-user/`)：使用 Headless UI + Tailwind，**禁止 Element Plus**
+
+## 触发条件
+
+用户要求创建新的 Vue 组件、页面组件、UI 元素或交互模块。
+
+## 执行流程
+
+### 0. 加载规范（⚠️ 必须最先执行）
+
+依次读取 `.cursor/rules/010-typescript.mdc`、`.cursor/rules/011-vue.mdc`、`.cursor/rules/019-modular.mdc`，提取类型注解要求（隐式 any 禁令、ref 泛型规范、Composable 类型规范）、script setup、defineProps/Emits、组件分类、拆分阈值、Composable 提取规则。
+
+> **Tier 3**：Vue 3 完整 API 见 `references/vue-api-reference.md`。
+
+### 0.5 ⚠️ 生成前强制结构规划（禁止跳过）
+
+**写代码前必须先输出文件结构和组件职责说明。**
+
+#### A. 检查是否已有可复用的基础组件
+
+在生成新组件前，先扫描以下路径，**避免重复造轮子**：
+- `src/components/core/` — 通用基础组件（按钮、输入框、卡片等）
+- `src/components/custom/` — 业务定制组件
+
+若已有 `FormInput.vue`、`BaseCard.vue` 等，**直接复用，不重新生成**。
+
+#### B. 用户端表单输入：优先复用 FormInput 模式
+
+用户端页面中表单输入框若出现 ≥3 个，必须使用 `FormInput` 基础组件：
+
+```vue
+<!-- src/components/core/FormInput/FormInput.vue -->
+<script setup>
+defineProps({
+  modelValue: { type: String, default: '' },
+  type: { type: String, default: 'text' },
+  placeholder: { type: String, default: '' },
+  icon: { type: Object, default: null },      // Lucide 图标组件
+  disabled: { type: Boolean, default: false },
+  error: { type: String, default: '' },
+})
+defineEmits(['update:modelValue'])
+</script>
+
+<template>
+  <div class="relative">
+    <component :is="icon" v-if="icon"
+      class="absolute left-3 top-1/2 -translate-y-1/2 text-gray-400 dark:text-gray-500 w-5 h-5" />
+    <input
+      :type="type"
+      :value="modelValue"
+      :placeholder="placeholder"
+      :disabled="disabled"
+      @input="$emit('update:modelValue', $event.target.value)"
+      :class="[
+        'w-full border-b py-3 outline-none transition-colors',
+        icon ? 'pl-10 pr-4' : 'px-4',
+        'bg-transparent border-gray-300 dark:border-[#333333]',
+        'text-gray-900 dark:text-white placeholder:text-gray-400 dark:placeholder:text-gray-600',
+        'focus:border-[#C41E3A] dark:focus:border-[#C41E3A]',
+        error ? 'border-red-500' : '',
+      ]"
+      data-testid="form-input"
+    />
+    <p v-if="error" class="mt-1 text-xs text-red-500">{{ error }}</p>
+  </div>
+</template>
+```
+
+> 若项目中尚无 `FormInput`，在生成使用它的页面前先生成该核心组件。
+
+#### C. 重复 UI 模式检测
+
+检查需求中是否存在重复结构：
+
+| 场景 | 检测标准 | 操作 |
+|------|---------|------|
+| 表单输入项 | ≥3 个相同结构的 input 组 | 提取 `FormInput.vue` |
+| 内容卡片 | ≥3 个相同布局的卡片 | 提取 `CaseCard.vue` / `DesignerCard.vue` |
+| 操作按钮组 | ≥2 处相同按钮组合 | 提取 `ActionGroup.vue` |
+| 阶段/Tab 面板 | ≥2 个结构相同的面板 | 提取 `StagePanel.vue` |
+
+#### D. 输出组件文件结构（代码前必须输出）
+
+```
+# 本次将生成以下文件：
+src/components/<type>/<ComponentName>/
+├── <ComponentName>.vue      ← 主组件（目标 ≤ 120 行）
+├── <ComponentName>.test.ts  ← 单元测试
+└── index.ts                 ← barrel export
+
+# 依赖（已存在 / 需新建）：
+- FormInput.vue: [已存在 / 需新建]
+- BaseCard.vue: [已存在 / 不需要]
+```
+
+---
+
+### 1. 确认组件规格
+
+| 字段 | 必填 | 默认值 |
+|------|------|--------|
+| 组件名 | ✅ | — |
+| 组件类型 | ❌ | UI 组件 |
+| 所在目录 | ❌ | `src/components/` |
+| Props / Emits | ❌ | 根据需求推断 |
+
+类型与目录：`core`→`src/components/core/`、`custom`→`custom/`、`layout`→`layouts/`、`page`→`views/<module>/components/`、`form`→`custom/`。
+
+### 2. 扫描项目模式
+
+读取 `src/components/` 确认 Props 声明、样式方案、命名前缀约定、已有的 core 组件列表。
+
+### 3. 生成文件结构
+
+按步骤 0.5 输出的结构逐文件生成，**禁止将多个组件合并到一个文件**。
+
+```
+src/components/<type>/<ComponentName>/
+├── <ComponentName>.vue
+├── <ComponentName>.test.ts
+└── index.ts
+```
+
+### 4. 组件模板
+
+根据类型选择：基础 UI / 表格 / 表单对话框 / 复合组件。完整模板与设计决策树见 **Tier 3**。
+
+**单组件行数限制**：
+- template 区域 ≤ 80 行
+- script 区域 ≤ 60 行（超出提取 composable）
+- 整个 SFC ≤ 150 行（超出必须拆分子组件）
+
+### 4.5 设计决策树（必须执行）
+
+- ≥3 布尔 prop？→ 显式变体组件
+- 多子组件共享状态？→ provide/inject
+- script 逻辑 > 60 行？→ 提取 `use<ComponentName>.ts` composable（**必须遵循 `010-typescript.mdc` 的 Composable 类型规范**：参数有类型、`ref` 有泛型、业务类型用 `import type`）
+- >2 处复用？→ `src/components/` + slot
+- 同一 UI 结构重复 ≥3 次？→ 提取基础组件（见步骤 0.5C）
+- 否则 → 基础 UI 模板
+
+### 5. 测试与 Barrel export
+
+测试至少包含渲染测试。`index.ts` 导出：`export { default as ComponentName } from './ComponentName.vue'`。详细测试见 `vue-testing` 技能。
+
+## 验证
+
+1. [ ] ESLint 无报错
+2. [ ] Props 使用对象语法 `defineProps({ key: { type, default } })`，**若模板可直接访问 props 字段则不保存返回值**（避免 `unused-vars` 报错；仅当 script 中需要访问 `props.xxx` 时才保存：`const props = defineProps(...)`）
+3. [ ] Emits 使用数组语法，事件名使用 camelCase（非 kebab-case）
+4. [ ] 包含 `data-testid`
+5. [ ] 测试至少一个渲染测试
+6. [ ] 管理端：Element Plus 用于组件，Tailwind 用于布局；用户端：Headless UI + Tailwind（禁止 Element Plus）
+7. [ ] barrel export 正确
+8. [ ] **单 SFC ≤ 150 行**
+9. [ ] **重复 UI 结构（≥3 次）已提取为基础组件**
+10. [ ] **表单输入 ≥3 个已复用 FormInput.vue**（用户端）
+11. [ ] **子组件模板中无 `v-model` 直接绑定 prop 嵌套属性**（参见 `011-vue.mdc` Props 数据流模式）
+12. [ ] **提取的 composable（use*.ts）参数有类型注解、`ref([])` / `ref(null)` 有泛型标注**（参见 `010-typescript.mdc` Composable 类型规范）
+
+### Red Flags（触发则停止并重构）
+
+- ❌ 未输出文件结构直接写代码 → 停止，先输出步骤 0.5D 的结构
+- ❌ 单 SFC > 150 行 → 拆分子组件
+- ❌ 相同 Tailwind 输入框结构写了 ≥3 次 → 提取 FormInput.vue
+- ❌ Options API → 改用 `<script setup>`
+- ❌ `const props = defineProps(...)` 但 script 中从不访问 `props.xxx` → 去掉 `const props =`，避免 `unused-vars` lint 报错
+- ❌ `catch (e) { ... }` 但 catch 块中不使用 `e` → 改为 `catch { ... }`（无参 catch），避免 `unused-vars` 报错
+- ❌ 直接修改 props → 通过 emit（含隐蔽变体：`v-model="prop.field"`、`v-model="prop[key]"`、事件回调中 `prop[k] = v`）
+- ❌ watch deep:true 滥用 → 精准监听
+- ❌ script 逻辑 > 60 行未提取 → 拆分为 use*.ts
+- ❌ composable 参数无类型 / `ref([])` 无泛型 → 补全类型注解（`strict: true` 下必报错）
+- ❌ ≥3 布尔 prop 控制渲染 → 拆分变体
+- ❌ prop drilling 传递同状态 → 改用 provide/inject
+
+## Tier 3 深度参考
+
+| 文件 | 内容 |
+|------|------|
+| `references/component-templates.md` | 基础/表格/表单/复合组件模板、决策树、Prop 反模式、错误处理、UI 反模式 |
+| `references/vue-api-reference.md` | Vue 3 完整 API 索引 |
+| `references/naming-conventions.md` | 组件命名规范 |
diff --git a/.cursor/skills/component-scaffold/references/component-templates.md b/.cursor/skills/component-scaffold/references/component-templates.md
new file mode 100644
index 0000000..00f1c34
--- /dev/null
+++ b/.cursor/skills/component-scaffold/references/component-templates.md
@@ -0,0 +1,117 @@
+# Component Scaffold — 组件模板
+
+> 主流程见 SKILL.md，本文档为各类 Vue 3 组件的完整模板。
+>
+> **⚠️ 双前端区分**：本文件中使用 `el-*` 组件的模板**仅适用于管理端** (`Case-Database-Frontend-admin/`)。
+> 用户端 (`Case-Database-Frontend-user/`) 使用 Headless UI + Tailwind CSS，**禁止引入 Element Plus**。
+
+## 基础 UI 组件
+
+```vue
+<script setup>
+const props = defineProps({
+  title: { type: String, required: true },
+  loading: { type: Boolean, default: false },
+})
+const emit = defineEmits(['refresh'])
+</script>
+<template>
+  <div class="rounded-lg border border-gray-200 p-4" data-testid="component-name">
+    <h3 class="text-lg font-semibold mb-2">{{ props.title }}</h3>
+    <slot />
+    <el-button v-if="props.loading" :loading="true" class="mt-2" />
+  </div>
+</template>
+```
+
+## 表格组件 (Element Plus)
+
+```vue
+<script setup>
+import { useTable } from '@/hooks/useTable'
+const props = defineProps({ apiUrl: { type: String, required: true }, columns: { type: Array, required: true } })
+const { loading, dataList, pagination, loadData } = useTable((params) => request.get(props.apiUrl, { params }))
+onMounted(() => loadData())
+</script>
+<template>
+  <div class="space-y-4">
+    <el-table v-loading="loading" :data="dataList" border stripe data-testid="data-table">
+      <el-table-column v-for="col in columns" :key="col.prop" v-bind="col" />
+      <el-table-column label="操作" fixed="right" width="180">
+        <template #default="{ row }"><slot name="actions" :row="row" /></template>
+      </el-table-column>
+    </el-table>
+    <el-pagination v-model:current-page="pagination.current" v-model:page-size="pagination.size" :total="pagination.total"
+      layout="total, sizes, prev, pager, next" @current-change="loadData" @size-change="loadData" />
+  </div>
+</template>
+```
+
+## 表单对话框组件
+
+```vue
+<script setup>
+const props = defineProps({ visible: { type: Boolean, required: true }, title: { type: String, required: true }, formData: { type: Object, default: () => ({}) } })
+const emit = defineEmits(['update:visible', 'submit'])
+const formRef = ref()
+const form = reactive({ ...props.formData })
+const rules = { name: [{ required: true, message: '请输入名称', trigger: 'blur' }] }
+async function handleSubmit() { await formRef.value?.validate(); emit('submit', { ...form }) }
+</script>
+<template>
+  <el-dialog :model-value="visible" :title="title" width="600px" @update:model-value="emit('update:visible', $event)">
+    <el-form ref="formRef" :model="form" :rules="rules" label-width="100px">
+      <el-form-item label="名称" prop="name"><el-input v-model="form.name" placeholder="请输入" /></el-form-item>
+      <slot name="form-fields" :form="form" />
+    </el-form>
+    <template #footer>
+      <el-button @click="emit('update:visible', false)">取消</el-button>
+      <el-button type="primary" @click="handleSubmit">确认</el-button>
+    </template>
+  </el-dialog>
+</template>
+```
+
+## 复合组件 (Compound + provide/inject)
+
+Provider 组件：provide 状态 + actions。子组件：inject 消费。keys.ts 定义 Symbol + useDataPanel()。消费者组合：`<DataPanelProvider :fetch-fn="orderApi.list"><DataPanelContent /></DataPanelProvider>`
+
+## 组件设计决策树
+
+```
+≥3 个布尔 prop 控制渲染？→ 拆分为显式变体组件
+多个子组件共享状态？→ provide/inject 复合组件
+业务逻辑 > 50 行？→ 提取 composable
+>2 处复用？→ 放入 src/components/，使用 slot
+否则 → 基础 UI 组件模板
+```
+
+## 逻辑提取规则 (CRITICAL)
+
+纯转换逻辑必须提取到 `ComponentName.utils.ts`，组件只保留 UI 和事件。文件结构：`ComponentName.vue` + `ComponentName.utils.ts` + `ComponentName.utils.test.ts` + `ComponentName.test.ts`（可选）+ `index.ts`
+
+## 复杂度阈值
+
+| 指标 | 阈值 | 动作 |
+|---|---|---|
+| 组件总行数 | > 200 | ⚠️ 考虑拆分 |
+| 组件总行数 | > 400 | 🔴 必须拆分 |
+| script 逻辑行数 | > 50 | 提取 composable |
+| 布尔 Props | ≥ 3 | 拆分为变体组件 |
+
+## Prop 反模式与显式变体
+
+❌ 4 个布尔 = 16 种状态，v-if 地狱。✅ 显式变体：`AdminEditPanel` / `PublicReadonlyPanel` / `DraftPreviewPanel`，通过 slot 复用共享子组件。Slot vs Prop：简单数据用 Prop，自定义渲染用 Slot，控制显示用有无 slot 内容。
+
+## 错误处理规范
+
+| 场景 | 组件 |
+|------|------|
+| 操作成功/失败即时反馈 | ElMessage |
+| 需用户确认 | ElMessageBox |
+| 异步持续状态 | ElNotification |
+| 页面级加载失败 | 内联错误 UI + 重试按钮 |
+
+## UI 设计反模式
+
+居中一切、紫色渐变、大圆角、过度阴影、空白页大插图、过多动画 → 以 Element Plus 为基准，优先功能清晰度。
diff --git a/.cursor/skills/component-scaffold/references/naming-conventions.md b/.cursor/skills/component-scaffold/references/naming-conventions.md
new file mode 100644
index 0000000..3f9eecb
--- /dev/null
+++ b/.cursor/skills/component-scaffold/references/naming-conventions.md
@@ -0,0 +1,32 @@
+# 组件命名规范
+
+## 文件命名
+
+| 类型 | 命名 | 示例 |
+|------|------|------|
+| 组件文件 | PascalCase.vue | `UserProfile.vue` |
+| 测试文件 | PascalCase.test.ts | `UserProfile.test.ts` |
+| 样式文件 | 内联 `<style scoped>` | `UserProfile.vue` |
+| Composable | use + PascalCase.ts | `useUserProfile.ts` |
+| 工具函数 | camelCase.ts | `formatDate.ts` |
+
+## Props 接口
+
+```typescript
+// ✅ Good: use JSDoc typedef for props-like structure
+/**
+ * @typedef {Object} UserProfileProps
+ */
+
+// ❌ Bad: ambiguous generic name
+/** @typedef {Object} Props */
+```
+
+## 组件类型
+
+| 类型 | 目录 | 特征 |
+|------|------|------|
+| UI 组件 | `components/ui/` | 无业务逻辑，纯展示 |
+| Feature 组件 | `components/features/` | 包含业务逻辑 |
+| Layout 组件 | `components/layout/` | 页面布局 |
+| Form 组件 | `components/forms/` | 表单及验证 |
diff --git a/.cursor/skills/component-scaffold/references/vue-api-reference.md b/.cursor/skills/component-scaffold/references/vue-api-reference.md
new file mode 100644
index 0000000..f8b193f
--- /dev/null
+++ b/.cursor/skills/component-scaffold/references/vue-api-reference.md
@@ -0,0 +1,481 @@
+# Vue.ts 3 API Reference
+
+Quick reference with links to official Vue.ts documentation.
+
+## Official Documentation
+
+**Main Site:** https://vuejs.org
+
+## Table of Contents
+
+1. [Getting Started](#getting-started)
+2. [Essentials](#essentials)
+3. [Components In-Depth](#components-in-depth)
+4. [Reusability](#reusability)
+5. [Built-in Components](#built-in-components)
+6. [API Reference](#api-reference)
+7. [TypeScript Patterns](#typescript-patterns)
+
+---
+
+## Getting Started
+
+### Introduction
+**URL:** https://vuejs.org/guide/introduction.html
+- What is Vue?
+- Progressive Framework
+- Single-File Components
+- API Styles (Options vs Composition)
+- Which to choose?
+
+### Quick Start
+**URL:** https://vuejs.org/guide/quick-start.html
+- Creating a Vue Application
+- Using Vue from CDN
+- With build tools (Vite)
+- IDE Setup
+
+### Creating an Application
+**URL:** https://vuejs.org/guide/essentials/application.html
+- Application instance
+- Root component
+- Mounting the app
+- App configurations
+
+---
+
+## Essentials
+
+### Template Syntax
+**URL:** https://vuejs.org/guide/essentials/template-syntax.html
+- Text interpolation
+- Raw HTML (v-html)
+- Attribute bindings (v-bind)
+- TypeScript expressions
+- Directives
+
+### Reactivity Fundamentals
+**URL:** https://vuejs.org/guide/essentials/reactivity-fundamentals.html
+- `ref()` - Reactive state for primitives
+- `reactive()` - Reactive objects
+- Reactive proxy vs original
+- `nextTick()` - DOM update timing
+
+### Computed Properties
+**URL:** https://vuejs.org/guide/essentials/computed.html
+- Basic usage
+- Computed caching vs methods
+- Writable computed
+- Best practices
+
+### Class and Style Bindings
+**URL:** https://vuejs.org/guide/essentials/class-and-style.html
+- Binding HTML classes
+- Binding inline styles
+- Object syntax
+- Array syntax
+
+### Conditional Rendering
+**URL:** https://vuejs.org/guide/essentials/conditional.html
+- `v-if`, `v-else-if`, `v-else`
+- `v-show`
+- v-if vs v-show
+- v-if with v-for
+
+### List Rendering
+**URL:** https://vuejs.org/guide/essentials/list.html
+- `v-for` with arrays
+- `v-for` with objects
+- `v-for` with ranges
+- Maintaining state with `key`
+- Array change detection
+
+### Event Handling
+**URL:** https://vuejs.org/guide/essentials/event-handling.html
+- Listening to events (`v-on` / `@`)
+- Method handlers
+- Inline handlers
+- Event modifiers (.stop, .prevent, etc.)
+- Key modifiers
+
+### Form Input Bindings
+**URL:** https://vuejs.org/guide/essentials/forms.html
+- `v-model` basics
+- Text, textarea inputs
+- Checkboxes, radio buttons
+- Select dropdowns
+- Modifiers (.lazy, .number, .trim)
+
+### Lifecycle Hooks
+**URL:** https://vuejs.org/guide/essentials/lifecycle.html
+- Lifecycle diagram
+- `onMounted()`, `onUpdated()`, `onUnmounted()`
+- `onBeforeMount()`, `onBeforeUpdate()`, `onBeforeUnmount()`
+- `onErrorCaptured()`, `onActivated()`, `onDeactivated()`
+
+### Watchers
+**URL:** https://vuejs.org/guide/essentials/watchers.html
+- `watch()` - Watch specific sources
+- `watchEffect()` - Auto-track dependencies
+- Deep watchers
+- Eager watchers (immediate)
+- Callback flush timing
+- Stopping watchers
+
+### Template Refs
+**URL:** https://vuejs.org/guide/essentials/template-refs.html
+- Accessing DOM elements
+- Refs inside v-for
+- Function refs
+- Component refs
+
+### Components Basics
+**URL:** https://vuejs.org/guide/essentials/component-basics.html
+- Defining components
+- Using components
+- Passing props
+- Listening to events
+- Slots
+
+---
+
+## Components In-Depth
+
+### Registration
+**URL:** https://vuejs.org/guide/components/registration.html
+- Global registration
+- Local registration
+- Component name casing
+
+### Props
+**URL:** https://vuejs.org/guide/components/props.html
+- Props declaration
+- Prop types and validation
+- Prop passing details
+- One-way data flow
+- Boolean casting
+- Prop validation
+
+### Events
+**URL:** https://vuejs.org/guide/components/events.html
+- Emitting and listening to events
+- Event arguments
+- Declaring emitted events
+- Events validation
+- Usage with v-model
+
+### Component v-model
+**URL:** https://vuejs.org/guide/components/v-model.html
+- Basic usage
+- v-model arguments
+- Multiple v-model bindings
+- Custom modifiers
+
+### Fallthrough Attributes
+**URL:** https://vuejs.org/guide/components/attrs.html
+- Attribute inheritance
+- Disabling inheritance
+- Accessing fallthrough attributes
+- Multi-root nodes
+
+### Slots
+**URL:** https://vuejs.org/guide/components/slots.html
+- Default slot content
+- Named slots
+- Scoped slots
+- Renderless components
+
+### Provide / Inject
+**URL:** https://vuejs.org/guide/components/provide-inject.html
+- Basic usage
+- App-level provide
+- Working with reactivity
+- Working with Symbol keys
+
+### Async Components
+**URL:** https://vuejs.org/guide/components/async.html
+- Basic usage
+- Loading and error states
+- Using with Suspense
+
+---
+
+## Reusability
+
+### Composables
+**URL:** https://vuejs.org/guide/reusability/composables.html
+- What is a composable?
+- Mouse tracker example
+- Async state example
+- Conventions and best practices
+- Usage restrictions
+- Extracting composables
+
+### Custom Directives
+**URL:** https://vuejs.org/guide/reusability/custom-directives.html
+- Introduction
+- Directive hooks
+- Hook arguments
+- Function shorthand
+- Object literals
+- Usage on components
+
+### Plugins
+**URL:** https://vuejs.org/guide/reusability/plugins.html
+- Introduction
+- Writing a plugin
+- Plugin options
+- Provide / inject with plugins
+
+---
+
+## Built-in Components
+
+### Transition
+**URL:** https://vuejs.org/guide/built-ins/transition.html
+- Basic usage
+- CSS-based transitions
+- TypeScript hooks
+- Reusable transitions
+- Appear on initial render
+- Transition between elements
+- Transition modes
+
+### TransitionGroup
+**URL:** https://vuejs.org/guide/built-ins/transition-group.html
+- Basic usage
+- Move transitions
+- Staggering list transitions
+
+### KeepAlive
+**URL:** https://vuejs.org/guide/built-ins/keep-alive.html
+- Basic usage
+- Include / exclude
+- Max cached instances
+- Lifecycle of cached instance
+
+### Teleport
+**URL:** https://vuejs.org/guide/built-ins/teleport.html
+- Basic usage
+- Using with components
+- Multiple teleports on same target
+- Disabling teleport
+
+### Suspense
+**URL:** https://vuejs.org/guide/built-ins/suspense.html
+- Async dependencies
+- Loading state
+- Error handling
+- Combining with Transitions
+- **Note:** Experimental feature
+
+---
+
+## API Reference
+
+### Global API
+**URL:** https://vuejs.org/api/application.html
+- Application API
+- General API
+
+### Composition API - Setup
+**URL:** https://vuejs.org/api/composition-api-setup.html
+- `setup()` function
+- `<script setup>` syntax
+
+### Composition API - Reactivity Core
+**URL:** https://vuejs.org/api/reactivity-core.html
+- `ref()`, `computed()`, `reactive()`, `readonly()`
+- `watchEffect()`, `watchPostEffect()`, `watchSyncEffect()`
+- `watch()`
+- `isRef()`, `unref()`, `toRef()`, `toRefs()`, `toValue()`
+- `isProxy()`, `isReactive()`, `isReadonly()`
+
+### Composition API - Reactivity Utilities
+**URL:** https://vuejs.org/api/reactivity-utilities.html
+- `isRef()`, `unref()`, `toRef()`, `toRefs()`, `toValue()`
+- `isProxy()`, `isReactive()`, `isReadonly()`
+- `shallowRef()`, `triggerRef()`, `customRef()`
+- `shallowReactive()`, `shallowReadonly()`
+
+### Composition API - Reactivity Advanced
+**URL:** https://vuejs.org/api/reactivity-advanced.html
+- `shallowRef()`, `triggerRef()`, `customRef()`
+- `shallowReactive()`, `shallowReadonly()`
+- `toRaw()`, `markRaw()`
+- `effectScope()`, `getCurrentScope()`, `onScopeDispose()`
+
+### Composition API - Lifecycle Hooks
+**URL:** https://vuejs.org/api/composition-api-lifecycle.html
+- `onMounted()`, `onUpdated()`, `onUnmounted()`
+- `onBeforeMount()`, `onBeforeUpdate()`, `onBeforeUnmount()`
+- `onErrorCaptured()`, `onRenderTracked()`, `onRenderTriggered()`
+- `onActivated()`, `onDeactivated()`, `onServerPrefetch()`
+
+### Composition API - Dependency Injection
+**URL:** https://vuejs.org/api/composition-api-dependency-injection.html
+- `provide()`, `inject()`
+- `hasInjectionContext()`
+
+### Composition API - Helpers
+**URL:** https://vuejs.org/api/composition-api-helpers.html
+- `useAttrs()`, `useSlots()`
+- `useModel()`, `useTemplateRef()`
+- `useId()`, `useCssModule()`
+
+### Options API - State
+**URL:** https://vuejs.org/api/options-state.html
+- `data`, `props`, `computed`
+- `methods`, `watch`, `emits`
+- `expose`
+
+### Options API - Rendering
+**URL:** https://vuejs.org/api/options-rendering.html
+- `template`, `render`
+- `compilerOptions`
+
+### Options API - Lifecycle
+**URL:** https://vuejs.org/api/options-lifecycle.html
+- `beforeCreate`, `created`
+- `beforeMount`, `mounted`
+- `beforeUpdate`, `updated`
+- `beforeUnmount`, `unmounted`
+- `errorCaptured`, `renderTracked`, `renderTriggered`
+- `activated`, `deactivated`, `serverPrefetch`
+
+### Options API - Composition
+**URL:** https://vuejs.org/api/options-composition.html
+- `provide`, `inject`
+- `mixins`, `extends`
+
+### Options API - Misc
+**URL:** https://vuejs.org/api/options-misc.html
+- `name`, `inheritAttrs`, `components`, `directives`
+
+### Component Instance
+**URL:** https://vuejs.org/api/component-instance.html
+- `$data`, `$props`, `$el`, `$refs`
+- `$parent`, `$root`, `$slots`, `$attrs`
+- `$watch()`, `$emit()`, `$forceUpdate()`, `$nextTick()`
+
+### Built-in Directives
+**URL:** https://vuejs.org/api/built-in-directives.html
+- `v-text`, `v-html`, `v-show`, `v-if`, `v-else`, `v-else-if`, `v-for`
+- `v-on`, `v-bind`, `v-model`
+- `v-slot`, `v-pre`, `v-once`, `v-memo`, `v-cloak`
+
+### Built-in Components
+**URL:** https://vuejs.org/api/built-in-components.html
+- `<Transition>`, `<TransitionGroup>`
+- `<KeepAlive>`, `<Teleport>`, `<Suspense>`
+
+### Built-in Special Elements
+**URL:** https://vuejs.org/api/built-in-special-elements.html
+- `<component>`, `<slot>`
+
+### Built-in Special Attributes
+**URL:** https://vuejs.org/api/built-in-special-attributes.html
+- `key`, `ref`, `is`
+
+### Single-File Component Syntax
+**URL:** https://vuejs.org/api/sfc-syntax.html
+- Language blocks
+- Automatic name inference
+- Pre-processors
+- Src imports
+- Custom blocks
+
+### SFC `<script setup>`
+**URL:** https://vuejs.org/api/sfc-script-setup.html
+- Basic syntax
+- Top-level bindings
+- Using components
+- Using custom directives
+- defineProps(), defineEmits()
+- defineExpose(), defineOptions(), defineSlots(), defineModel()
+- useSlots(), useAttrs()
+- Normal `<script>` alongside `<script setup>`
+
+### SFC CSS Features
+**URL:** https://vuejs.org/api/sfc-css-features.html
+- Scoped CSS
+- CSS modules
+- `v-bind()` in CSS
+- `<style>` with `src` imports
+
+---
+
+## TypeScript Patterns
+
+### TypeScript with Composition API
+**URL:** https://vuejs.org/guide/extras/composition-api-faq.html
+- Define props with runtime object syntax
+- Define emits with array/object syntax
+- Use JSDoc for complex shapes
+- Keep composables in `use*.ts`
+- Prefer clear runtime validation for public component APIs
+
+### TypeScript with Options API
+**URL:** https://vuejs.org/guide/essentials/component-basics.html
+- Use `props` runtime validation
+- Keep event names explicit in `emits`
+- Avoid implicit global properties where possible
+- Prefer composition API for new code
+
+### Overview
+**URL:** https://vuejs.org/guide/scaling-up/tooling.html
+- IDE support
+- Linting and formatting integration
+- Volar extension basics
+- Build-tool and plugin usage notes
+
+---
+
+## Additional Resources
+
+### Best Practices
+**URL:** https://vuejs.org/guide/best-practices/production-deployment.html
+- Production deployment
+- Performance
+- Accessibility
+- Security
+
+### Scaling Up
+**URL:** https://vuejs.org/guide/scaling-up/sfc.html
+- Single-File Components
+- Tooling
+- Routing
+- State management
+- Testing
+- Server-Side Rendering (SSR)
+
+### Style Guide
+**URL:** https://vuejs.org/style-guide/
+- Priority A: Essential (Error Prevention)
+- Priority B: Strongly Recommended
+- Priority C: Recommended
+- Priority D: Use with Caution
+
+### Vue Router
+**URL:** https://router.vuejs.org/
+- Official routing library
+
+### Pinia
+**URL:** https://pinia.vuejs.org/
+- Official state management library
+
+### Vite
+**URL:** https://vitejs.dev/
+- Recommended build tool
+
+---
+
+## Quick Search Tips
+
+When searching official docs:
+1. Use the search bar at https://vuejs.org
+2. For API details, go directly to https://vuejs.org/api/
+3. For guides and concepts, start at https://vuejs.org/guide/
+4. For examples, check https://vuejs.org/examples/
+
+All documentation is available in multiple languages using the language selector.
diff --git a/.cursor/skills/database-migration/SKILL.md b/.cursor/skills/database-migration/SKILL.md
new file mode 100644
index 0000000..d23014c
--- /dev/null
+++ b/.cursor/skills/database-migration/SKILL.md
@@ -0,0 +1,87 @@
+---
+name: database-migration
+version: 3.0.0
+description: "使用 Hyperf Migrations 安全管理数据库 Schema 变更。当需要创建表、添加字段或修改索引时使用。确保迁移安全可回滚。"
+---
+
+> ⚠️ 核心执行流程已在 `.cursor/rules/skill-database-migration.mdc` 中由 Cursor 自动注入。
+> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
+
+# Hyperf Database Migration
+
+## ⚠️ 安全等级：ORANGE — 执行前必须确认
+
+## 迁移核心原则
+
+1. **每次变更都是迁移** — 禁止手动 DDL
+2. **Schema 与 Data 严格分离** — DDL 和 DML 分文件
+3. **迁移部署后不可变** — 已执行迁移禁止修改
+4. **生产前向原则** — 回滚用新前向迁移修正
+5. **新字段安全** — 新增字段必须 nullable 或有默认值
+6. **迁移前测试** — 大表先在副本验证
+
+## 目录约定
+
+```
+Case-Database-Backend/
+├── database/
+│   ├── migrations/    ← 迁移文件（已通过 DI 工厂注册到 Migrator）
+│   └── seeders/       ← 种子文件（已通过 DI 工厂注册到 Seed）
+```
+
+路径配置说明：
+- Hyperf 默认迁移路径为 `migrations/`，本项目通过 `App\Database\MigratorFactory` 覆盖为 `database/migrations/`
+- Seeder 路径通过 `App\Database\SeedFactory` 覆盖为 `database/seeders/`
+- `gen:migration` / `gen:seeder` 路径在 `config/autoload/devtool.php` 中配置
+
+## 触发条件
+
+用户要求修改数据库结构、添加/删除字段、创建/删除表、修改索引或关联。
+
+## 执行流程
+
+### 0. 加载规范
+
+读取 `.cursor/rules/014-database.mdc`，提取表设计、索引规则、Migration 写法、高并发注意事项。
+
+### 1. 理解变更需求
+
+确认：变更什么、是否涉及数据迁移、是否可逆、是否有线上数据、数据量级、环境阶段。
+
+### 2. 生成迁移
+
+```bash
+php bin/hyperf.php gen:migration create_{{table_name}}_table
+# 文件自动生成到 database/migrations/ 目录
+# 命名: create_orders_table | add_status_to_orders | remove_legacy_field_from_users
+```
+
+### 3. 编写迁移
+
+Schema::create / Schema::table，含 id、audit 字段、索引。down() 必须完整可逆。幂等、Expand-Contract、批量迁移见 **Tier 3**。
+
+### 4. 高并发表设计检查
+
+主键 BIGINT UNSIGNED、utf8mb4、金额 DECIMAL、状态 VARCHAR/TINYINT、外键索引、常用 WHERE 索引、复合索引最左前缀、单表索引 ≤6、JSON 仅非查询、避免过多 TEXT。
+
+### 5. 执行与更新
+
+`php bin/hyperf.php migrate`、`migrate:status`、`migrate:rollback`。`gen:model {{table_name}}`。更新 Model、Service、Repository、`docs/architecture/data-model.md`。
+
+## 验证
+
+1. [ ] `migrate` 无错误
+2. [ ] `migrate:rollback` 可回滚（开发）
+3. [ ] Model `$fillable` / `$casts` 正确
+4. [ ] 外键有索引
+5. [ ] 新字段 nullable 或有默认值
+6. [ ] Schema 与 Data 迁移分文件
+7. [ ] 幂等检查通过
+8. [ ] SQL 人工审查
+9. [ ] data-model.md 已更新
+
+## Tier 3 深度参考
+
+| 文件 | 内容 |
+|------|------|
+| `references/migration-patterns.md` | 幂等、Expand-Contract、批量迁移、大表策略、危险操作 |
diff --git a/.cursor/skills/database-migration/references/migration-patterns.md b/.cursor/skills/database-migration/references/migration-patterns.md
new file mode 100644
index 0000000..4804200
--- /dev/null
+++ b/.cursor/skills/database-migration/references/migration-patterns.md
@@ -0,0 +1,73 @@
+# Database Migration — 迁移模式与示例
+
+> 主流程见 SKILL.md，本文档为幂等迁移、Expand-Contract、批量迁移、大表策略的完整实现。
+
+## 幂等迁移
+
+```php
+public function up(): void
+{
+    if (!Schema::hasTable('production_orders')) {
+        Schema::create('production_orders', function (Blueprint $table) {
+            $table->bigIncrements('id');
+            $table->string('order_no', 50)->unique();
+            $table->timestamps();
+            $table->softDeletes();
+        });
+    }
+    if (!Schema::hasColumn('production_orders', 'priority')) {
+        Schema::table('production_orders', function (Blueprint $table) {
+            $table->tinyInteger('priority')->default(0)->after('status');
+        });
+    }
+    if (!$this->hasIndex('production_orders', 'idx_orders_priority')) {
+        Schema::table('production_orders', function (Blueprint $table) {
+            $table->index('priority', 'idx_orders_priority');
+        });
+    }
+}
+```
+
+## Expand-Contract 三阶段示例（字段重命名 username → display_name）
+
+Phase 1 EXPAND: 添加 display_name  nullable。部署 v2 双写。  
+Phase 2 MIGRATE: 独立迁移文件批量 UPDATE 回填。部署 v3 读新写双。验证一致性。  
+Phase 3 CONTRACT: 删除 username。部署 v4 仅新字段。
+
+时间线：Day 1 加字段+双写，Day 2 回填，Day 3 读新写双+验证，Day 7 删旧字段。
+
+## 批量数据迁移模板
+
+```php
+$batchSize = 2000;
+$lastId = 0;
+while (true) {
+    $affected = Db::update("UPDATE users SET normalized_email = LOWER(email) WHERE id > ? AND normalized_email IS NULL ORDER BY id LIMIT ?", [$lastId, $batchSize]);
+    if ($affected === 0) break;
+    $lastId = Db::selectOne("SELECT MAX(id) AS max_id FROM users WHERE normalized_email IS NOT NULL AND id > ?", [$lastId])->max_id ?? $lastId + $batchSize;
+    usleep(100_000);
+}
+```
+
+规则：1000–5000 行/批、批次间 sleep、游标 WHERE id > ?、低峰期执行。
+
+## 大表变更策略（百万级+）
+
+| 操作 | 风险 | 方案 |
+|------|------|------|
+| ADD COLUMN | 低 | 直接执行，nullable 或有默认值 |
+| ADD INDEX | 中 | ALGORITHM=INPLACE, LOCK=NONE |
+| DROP COLUMN | 高 | 先移除代码→部署→下版本迁移删除 |
+| ALTER TYPE | 高 | Expand-Contract |
+| RENAME COLUMN | 高 | Expand-Contract |
+| DROP TABLE | 极高 | 先重命名→观察一周→删除 |
+
+## 危险操作清单
+
+| 操作 | 缓解 |
+|------|------|
+| DROP TABLE | 先备份 |
+| DROP COLUMN | 先移除代码引用 |
+| ALTER TYPE | Expand-Contract |
+| TRUNCATE | 禁止生产 |
+| NOT NULL 无默认值 | 先 nullable→回填→再加约束 |
diff --git a/.cursor/skills/database-migration/references/rollback-patterns.md b/.cursor/skills/database-migration/references/rollback-patterns.md
new file mode 100644
index 0000000..7962023
--- /dev/null
+++ b/.cursor/skills/database-migration/references/rollback-patterns.md
@@ -0,0 +1,57 @@
+# 数据库回滚模式 (Hyperf Migration)
+
+## 安全回滚策略
+
+### 添加字段（可回滚）
+```php
+// Migration up()
+Schema::table('users', function (Blueprint $table) {
+    $table->string('avatar_url')->nullable()->after('email');
+});
+
+// Migration down()
+Schema::table('users', function (Blueprint $table) {
+    $table->dropColumn('avatar_url');
+});
+```
+
+### 删除字段（不可逆 — 需预备份）
+```sql
+-- 删除前先备份
+CREATE TABLE _backup_users_phone AS
+SELECT id, phone FROM users WHERE phone IS NOT NULL;
+```
+
+### 重命名字段（分步迁移）
+```php
+// Step 1: 添加新列
+Schema::table('users', function (Blueprint $table) {
+    $table->string('display_name')->nullable()->after('name');
+});
+
+// Step 2: 迁移数据
+DB::statement('UPDATE users SET display_name = name');
+
+// Step 3: 删除旧列（下一个迁移文件）
+Schema::table('users', function (Blueprint $table) {
+    $table->dropColumn('name');
+});
+```
+
+### 类型变更（分步迁移）
+```
+Step 1: 添加新列 → Step 2: 迁移数据 → Step 3: 删除旧列
+```
+
+## 回滚命令
+
+```bash
+# 回滚最近一次迁移
+php bin/hyperf.php migrate:rollback
+
+# 回滚最近 N 次迁移
+php bin/hyperf.php migrate:rollback --step=3
+
+# 查看迁移状态
+php bin/hyperf.php migrate:status
+```
diff --git a/.cursor/skills/debugging/SKILL.md b/.cursor/skills/debugging/SKILL.md
new file mode 100644
index 0000000..f851238
--- /dev/null
+++ b/.cursor/skills/debugging/SKILL.md
@@ -0,0 +1,184 @@
+---
+name: debugging
+version: 2.0.0
+description: "七步法系统化调试工作流。当用户报告 Bug、错误、异常、截图指出界面问题或功能与预期不符时使用。含信号解析和结构化调试报告。"
+---
+
+> ⚠️ 核心执行流程已在 `.cursor/rules/skill-debugging.mdc` 中由 Cursor 自动注入。
+> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
+
+# Debugging Workflow
+
+## 触发条件
+
+用户报告错误、异常、意外行为，或请求排查问题。包含但不限于：
+
+| 来源 | 典型表现 | 示例 |
+|---|---|---|
+| 运行时错误 | 控制台报错、崩溃、白屏 | "点击按钮报 500" |
+| 视觉/UI 异常 | 组件显示与预期不符 | "暗色模式下输入框是白色" |
+| 截图指出问题 | 用户提供截图标注异常区域 | 附图 + "这里不对" |
+| 功能失效 | 操作无响应或结果错误 | "筛选没有效果" |
+| 样式回归 | 改动后样式错乱 | "更新后布局乱了" |
+
+> ⚠️ **截图 = Bug 报告**：用户提供截图并指出问题，本质是视觉 Bug 报告，必须激活本技能。
+
+## 七步法
+
+### -1. 截图前置守卫 (Screenshot Guard)
+
+收到用户消息时，**先检查输入形式**，再分析文字意图：
+
+| 输入形式 | 问题关键词 | 判定 |
+|---------|-----------|------|
+| 包含截图/图片 | 不合理 / 不对 / 有问题 / 调整 / 修复 / 偏了 / 太大 / 太小 / 空白 / 溢出 / 错位 | → 视觉 Bug，激活完整调试流程 |
+| 包含截图/图片 | 新增 / 添加 / 改为 / 参考这个 / 照着做 | → 需求变更，走正常开发流程 |
+
+**硬规则**：无论判定结果是哪条路径，都**必须在回复开头输出守卫判定块**：
+
+```
+## 截图守卫判定
+- 输入形式：包含截图 ✓
+- 关键词扫描：「XXX」→ 命中 [视觉 Bug / 需求变更] 类
+- 判定：[激活调试流程 / 走正常开发流程]
+```
+
+**视觉 Bug 路径规则**：
+- 截图 + 问题描述 = 视觉 Bug，**不得降级为 L1 直接执行**，最低 L2
+- 必须走完信号解析 → 修复 → 回归验证（含 chrome-devtools 截图对比）全流程
+
+**需求变更路径规则**：
+- 截图用于"参考设计"或"说明改动目标"，走正常开发流程
+- 复杂度按 001-workflow 标准判定（可为 L1）
+
+### 0. 信号解析 (Parse Signals)
+
+从用户描述中**主动提取**以下关键信号（缺失的主动追问）：
+
+| 信号 | 来源 | 重要性 |
+|---|---|---|
+| 错误消息 / 堆栈追踪 | 控制台、日志、浏览器 DevTools | 🔴 必需 |
+| 复现步骤 | 用户操作序列 | 🔴 必需 |
+| 截图标注的异常区域 | 用户截图 + 文字描述 | 🔴 必需（有截图时） |
+| 影响区域 | 后端服务 / 前端组件 / API / DB | 🟠 重要 |
+| 环境信息 | PHP 版本 / 浏览器 / OS | 🟡 有用 |
+| 上次正常的时间/版本 | Git log / 部署记录 | 🟡 有用 |
+| 偶发 vs 稳定 | 复现概率 | 🟡 有用 |
+
+### 0.5 路由到调试策略 (Route to Debug Strategy)
+
+根据影响区域选择最高效的调试工具：
+
+| 影响区域 | 首选调试方式 | 测试工具 | 关键位置 |
+|---|---|---|---|
+| PHP Service 逻辑 | 断点 + 日志 | PHPUnit | `Case-Database-Backend/test/Unit/` |
+| API 端点 | Postman / curl + 日志 | Hyperf HttpClient | `Case-Database-Backend/test/Feature/` |
+| 数据库查询 | SQL 日志 + `EXPLAIN` | PHPUnit + SQLite | `Case-Database-Backend/test/Unit/` |
+| Vue 组件渲染 | Vue DevTools | Vitest + VTU | `frontend-*/src/**/*.test.ts` |
+| Vue 状态管理 | Pinia DevTools | Vitest | `frontend-*/src/**/*.test.ts` |
+| API 请求/响应 | 浏览器 Network 面板 | Mock + Vitest | `frontend-*/src/**/*.test.ts` |
+| 样式/布局 | Chrome DevTools Elements | 视觉回归 | — |
+| Swoole 协程 | `var_dump` + Hyperf 日志 | PHPUnit | `Case-Database-Backend/test/` |
+| WebSocket | 浏览器 WS 面板 + 服务端日志 | Swoole Testing | `Case-Database-Backend/test/` |
+
+### 1. 复现 (Reproduce)
+
+- 获取准确的错误信息、堆栈追踪
+- 确认可稳定复现的步骤
+- 确认环境：浏览器/Node 版本、OS
+- **关键**：如果无法稳定复现，记录复现概率和条件
+
+### 2. 收集 (Collect)
+
+- 读取相关源码文件
+- 检查最近的 git 变更：`git log --oneline -10 -- <affected-path>`
+- 查看相关日志
+- 检查环境变量配置
+- **新增**：查看该区域的已有测试，了解预期行为
+
+### 3. 假设 (Hypothesize)
+
+列出 2-3 个最可能的原因，按概率排序：
+```
+假设 A (70%): <描述> — 因为 <证据>
+假设 B (20%): <描述> — 因为 <证据>
+假设 C (10%): <描述> — 因为 <证据>
+```
+
+每个假设必须指向**具体文件和代码行**。
+
+### 4. 验证 (Verify)
+
+从最高概率假设开始验证。每次只验证一个假设：
+- 添加 `console.log` / 断点 / Hyperf 日志
+- 写最小复现测试用例（参考 `bug-reproduce` 技能）
+- 检查相关数据状态
+
+### 5. 修复 (Fix)
+
+- 修复根因，不是症状
+- 修改尽可能小
+- 添加防御性代码防止复发
+
+### 6. 回归 (Regress)
+
+- 确认原始问题已修复
+- 运行相关测试套件
+- 检查是否引入新问题
+- **新增**：编写回归测试防止复发
+
+## 硬停止条件
+
+遇到以下情况时**立即停止调试**，告知用户需要额外条件：
+
+| 条件 | 原因 | 建议 |
+|---|---|---|
+| 需要真实第三方 API 凭证 | 无法在本地模拟 | 提供测试凭证或 Mock 服务 |
+| 竞态条件/时序依赖 | 不可靠的复现 | 添加日志收集并发数据 |
+| 需要生产数据 | 本地无法重建状态 | 导出脱敏数据子集 |
+| 需要特定基础设施 | 本地无法模拟 | 在测试环境调试 |
+| 超过 3 次假设全部否定 | 信息不足 | 收集更多日志和上下文 |
+
+## 调试报告模板
+
+```markdown
+## 🔧 调试报告
+
+**问题**: [一句话描述]
+**状态**: ✅ 已修复 | ⏳ 进行中 | ❌ 需要更多信息
+
+### 信号
+- 错误: [错误消息]
+- 区域: [影响区域]
+- 复现: [步骤]
+
+### 根因
+[1-2 句话解释 Bug 产生的机制]
+
+### 修复
+| 文件 | 修改 |
+|---|---|
+| `path/to/file` | [修改说明] |
+
+### 回归测试
+- `path/to/test` — [测试说明]
+
+### 验证
+- [ ] 原始问题已修复
+- [ ] 回归测试通过
+- [ ] 无新问题引入
+```
+
+## 常见问题速查
+
+详见 `references/common-errors.md`。
+
+## 验证
+
+1. [ ] 提取了所有关键信号（错误消息、复现步骤、影响区域）
+2. [ ] 选择了正确的调试策略和工具
+3. [ ] 原始问题已修复
+4. [ ] 所有现有测试通过
+5. [ ] 添加了防止复发的回归测试
+6. [ ] 修复范围最小化
+7. [ ] 输出了结构化调试报告
diff --git a/.cursor/skills/debugging/references/common-errors.md b/.cursor/skills/debugging/references/common-errors.md
new file mode 100644
index 0000000..21fc383
--- /dev/null
+++ b/.cursor/skills/debugging/references/common-errors.md
@@ -0,0 +1,37 @@
+# 常见错误速查表
+
+## Vue 3
+
+| 错误 | 原因 | 修复 |
+|------|------|------|
+| `[Vue warn] Missing required prop` | 必填 prop 未传入 | 检查父组件传参或设置默认值 |
+| `Maximum recursive updates` | 响应式数据在 watch 中循环修改 | 添加条件判断或用 `watchEffect` 替代 |
+| `inject() can only be called inside setup()` | 依赖注入在非 setup 中调用 | 移入 `<script setup>` 或 `setup()` 函数 |
+| `Extraneous non-props attributes` | 组件未声明 `inheritAttrs: false` | 添加 `defineOptions({ inheritAttrs: false })` |
+| `Component is missing template` | 组件缺少 template 或 render | 检查 .vue 文件是否有 `<template>` |
+
+## TypeScript
+
+| 错误 | 原因 | 修复 |
+|------|------|------|
+| `Cannot read properties of undefined` | 访问未定义对象属性 | 增加空值判断或使用可选链 `?.` |
+| `Unexpected token 'export'` | 运行环境与模块格式不匹配 | 检查 ESM/CJS 配置与运行命令 |
+| `x is not a function` | 导入或变量类型错误 | 检查导出方式与调用处参数 |
+
+## PHP Hyperf
+
+| 错误 | 原因 | 修复 |
+|------|------|------|
+| `Class not found` | DI 容器未注册或命名空间错误 | 检查 namespace、运行 `composer dump-autoload` |
+| `Connection pool exhausted` | 连接池已满，协程等待超时 | 增大 `max_connections` 或减少连接占用时间 |
+| `Coroutine context destroyed` | 在协程外访问协程上下文 | 使用 `Context::get()` 前确保在协程环境 |
+| `Table not found` | 迁移未执行 | 运行 `php bin/hyperf.php migrate` |
+| `Allowed memory exhausted` | 内存泄漏或大数据未分块 | 使用 `chunk()` 处理大数据集 |
+
+## MySQL
+
+| 错误 | 原因 | 修复 |
+|------|------|------|
+| Duplicate entry (1062) | 插入重复唯一键数据 | 用 `INSERT ... ON DUPLICATE KEY UPDATE` 或先查询 |
+| Lock wait timeout (1205) | 事务死锁或长事务 | 缩短事务范围，添加合适索引 |
+| Too many connections (1040) | 连接数超限 | 检查连接池配置，增大 `max_connections` |
diff --git a/.cursor/skills/documentation/SKILL.md b/.cursor/skills/documentation/SKILL.md
new file mode 100644
index 0000000..5445226
--- /dev/null
+++ b/.cursor/skills/documentation/SKILL.md
@@ -0,0 +1,73 @@
+---
+name: documentation
+version: 1.0.0
+description: "生成并更新项目文档。当需要撰写技术文档、README、API 文档或架构决策记录时使用。"
+---
+
+# Documentation Generator
+
+## 触发条件
+
+用户要求创建、更新或改进项目文档。
+
+## 执行流程
+
+### 1. 确定文档类型
+
+| 类型 | 输出位置 | 模板来源 |
+|------|---------|---------|
+| PRD | `docs/vision/PRD.md` | 已有模板，直接填写 |
+| README | `README.md` | 项目概述 + 安装 + 使用 |
+| API 文档 | `docs/architecture/api-contracts.md` | 端点 + 请求/响应 |
+| 架构文档 | `docs/architecture/system-design.md` | 已有模板，直接填写 |
+| 数据模型 | `docs/architecture/data-model.md` | 已有模板，直接填写 |
+| ADR | `docs/architecture/decisions/NNN-*.md` | 复制 `_template.md` 后填写 |
+| 组件文档 | JSDoc / Storybook | Props + 示例 |
+| 变更日志 | `CHANGELOG.md` | Conventional Changelog |
+
+> **模板路径**: 创建 ADR 时，先读取 `docs/architecture/decisions/_template.md` 作为基础。
+> PRD、架构文档、数据模型已在 `docs/` 下有完整模板，优先填充而非重新创建。
+
+### 2. 收集上下文
+
+1. 读取相关源码理解功能
+2. 读取已有文档确认风格
+3. 读取 `package.json` 获取项目信息
+4. 读取 `docs/guides/style-guide.md` 确认文档规范
+
+### 3. 生成文档
+
+遵循以下写作原则：
+- **简明**：一句话说清楚，不要冗余描述
+- **可执行**：代码示例必须可运行
+- **可维护**：避免写死版本号和路径
+- **受众明确**：新人 onboarding vs 日常参考 vs 架构决策
+
+### 4. ADR 创建流程
+
+1. 复制模板：`docs/architecture/decisions/_template.md` → `docs/architecture/decisions/NNN-title.md`
+2. 替换 `XXX` 为递增编号（检查已有 ADR 文件确定下一个编号）
+3. 填写所有章节：状态、上下文（含问题陈述和约束）、决策、备选方案、理由、影响
+4. 标注记录人和审核人
+
+### 5. JSDoc 规范
+
+```typescript
+/**
+ * 一句话描述。
+ *
+ * @param paramName - 参数说明
+ * @returns 返回值说明
+ * @throws {ErrorType} 何时抛出
+ *
+ * @example
+ * const result = functionName('input');
+ */
+```
+
+## 验证
+
+1. [ ] 文档无拼写错误
+2. [ ] 代码示例可运行
+3. [ ] 链接有效
+4. [ ] 遵循项目文档风格
diff --git a/.cursor/skills/documentation/references/writing-guide.md b/.cursor/skills/documentation/references/writing-guide.md
new file mode 100644
index 0000000..5187279
--- /dev/null
+++ b/.cursor/skills/documentation/references/writing-guide.md
@@ -0,0 +1,31 @@
+# 文档写作指南
+
+## 写作原则
+
+1. **一句话规则**：每个概念用一句话解释清楚
+2. **Show, Don't Tell**：用代码示例代替文字描述
+3. **链接优于重复**：引用已有文档而非复制粘贴
+4. **面向受众**：明确文档读者是谁
+
+## Markdown 规范
+
+- 标题层级不超过 4 级（`#` 到 `####`）
+- 代码块指定语言（```typescript / ```php / ```bash 等，而非 ```）
+- 表格对齐（使用 Prettier）
+- 链接使用相对路径
+
+## README 结构
+
+```markdown
+# 项目名
+
+一句话描述。
+
+## 快速开始
+## 功能特性
+## 安装
+## 使用
+## 配置
+## 贡献指南
+## 许可证
+```
diff --git a/.cursor/skills/env-setup/SKILL.md b/.cursor/skills/env-setup/SKILL.md
new file mode 100644
index 0000000..88db79b
--- /dev/null
+++ b/.cursor/skills/env-setup/SKILL.md
@@ -0,0 +1,250 @@
+---
+name: env-setup
+version: 2.0.0
+description: "初始化 PHP Hyperf + Vue 3 双栈开发环境。当需要项目初始化、环境配置或安装依赖时使用。含 Docker Compose 和数据库初始化。"
+---
+
+# 🔧 Environment Setup (PHP Hyperf + Vue 3 Dual Stack)
+
+## 触发条件
+
+用户要求初始化项目环境、配置开发工具链、设置环境变量。
+
+## 执行流程
+
+### 1. 检测系统依赖
+
+```bash
+echo "=== System Dependencies ==="
+
+# PHP
+php -v 2>/dev/null && echo "✅ PHP installed" || echo "❌ PHP not found (need >= 8.1)"
+
+# Swoole
+php -m 2>/dev/null | grep -i swoole && echo "✅ Swoole installed" || echo "❌ Swoole not found (need >= 5.0)"
+
+# Composer
+composer --version 2>/dev/null && echo "✅ Composer installed" || echo "❌ Composer not found"
+
+# Node.js
+node -v 2>/dev/null && echo "✅ Node.js installed" || echo "❌ Node.js not found (need >= 20)"
+
+# npm
+npm -v 2>/dev/null && echo "✅ npm installed" || echo "❌ npm not found"
+
+# Docker
+docker --version 2>/dev/null && echo "✅ Docker installed" || echo "⚠️ Docker not found (optional for local dev)"
+
+# Docker Compose
+docker compose version 2>/dev/null && echo "✅ Docker Compose installed" || echo "⚠️ Docker Compose not found"
+```
+
+### 2. 后端初始化 (PHP Hyperf)
+
+```bash
+cd Case-Database-Backend
+
+# 安装 PHP 依赖
+composer install
+
+# 复制环境变量
+if [ ! -f ".env" ] && [ -f ".env.example" ]; then
+    cp .env.example .env
+    echo "✅ .env created from .env.example"
+    echo "⚠️ Please fill in required values: DB_HOST, DB_DATABASE, REDIS_HOST, JWT_SECRET"
+fi
+
+# 验证 Hyperf 启动
+php bin/hyperf.php start --dry-run 2>/dev/null || php bin/hyperf.php di:init-proxy
+```
+
+### 3. 前端初始化 (Vue 3 + Vite)
+
+```bash
+for dir in Case-Database-Frontend-user Case-Database-Frontend-admin; do
+  echo "=== $dir ==="
+  cd $dir
+  
+  # 安装 Node 依赖
+  npm install
+  
+  # 复制环境变量
+  if [ ! -f ".env.local" ] && [ -f ".env.example" ]; then
+      cp .env.example .env.local
+      echo "✅ .env.local created from .env.example"
+  fi
+  cd ..
+done
+```
+
+### 4. 数据库初始化
+
+```bash
+cd Case-Database-Backend
+
+# 运行迁移
+php bin/hyperf.php migrate
+
+# 运行种子（如有）
+php bin/hyperf.php db:seed
+```
+
+### 5. Docker Compose 启动（可选）
+
+```bash
+# 一键启动全部服务
+docker compose up -d
+
+# 验证服务状态
+docker compose ps
+```
+
+### 6. 初始化工具链
+
+| 工具 | 配置文件 | 前端/后端 |
+|------|---------|---------|
+| jsconfig | `jsconfig.json` | 前端 |
+| ESLint | `.eslintrc.*` / `eslint.config.*` | 前端 |
+| Prettier | `.prettierrc` | 前端 |
+| Husky | `.husky/` | 全栈 |
+| PHPStan | `phpstan.neon` | 后端 |
+| PHP CS Fixer | `.php-cs-fixer.php` | 后端 |
+
+### 7. 验证环境
+
+```bash
+echo "=== Backend Verification ==="
+cd Case-Database-Backend
+php -v
+composer --version
+php bin/hyperf.php --version 2>/dev/null || echo "Run: php bin/hyperf.php start"
+
+echo ""
+echo "=== Frontend Verification ==="
+for dir in Case-Database-Frontend-user Case-Database-Frontend-admin; do
+  echo "=== $dir Verification ==="
+  cd $dir
+  node -v
+  npm -v
+  npm run build --dry-run 2>/dev/null || echo "Run: npm run dev"
+  cd ..
+done
+
+echo ""
+echo "=== Services ==="
+docker compose ps 2>/dev/null || echo "Docker Compose not running"
+```
+
+## 关键环境变量
+
+### 后端 (.env)
+
+| 变量 | 说明 | 示例 |
+|------|------|------|
+| `APP_NAME` | 应用名称 | `MyApp` |
+| `APP_ENV` | 环境 | `dev` / `production` |
+| `DB_HOST` | MySQL 主机 | `127.0.0.1` |
+| `DB_PORT` | MySQL 端口 | `3306` |
+| `DB_DATABASE` | 数据库名 | `myapp` |
+| `DB_USERNAME` | 数据库用户 | `root` |
+| `DB_PASSWORD` | 数据库密码 | *(Secret)* |
+| `REDIS_HOST` | Redis 主机 | `127.0.0.1` |
+| `REDIS_PORT` | Redis 端口 | `6379` |
+| `JWT_SECRET` | JWT 密钥 | *(auto-generate)* |
+
+### 前端 (.env.local)
+
+| 变量 | 说明 | 示例 |
+|------|------|------|
+| `VITE_API_BASE_URL` | API 地址 | `http://localhost:9501` |
+| `VITE_WS_URL` | WebSocket 地址 | `ws://localhost:9502` |
+| `VITE_APP_TITLE` | 应用标题 | `MyApp` |
+
+## 密钥管理最佳实践
+
+### 原则
+
+- **永不硬编码** — 密钥不进入代码仓库
+- **运行时注入** — 密钥在部署/启动时注入，不写入磁盘文件
+- **最小权限** — 每个服务只拥有必需的密钥访问权限
+- **定期轮换** — 密钥和 Token 设置过期时间并定期轮换
+
+### 推荐方案（按场景选择）
+
+| 场景 | 方案 | 复杂度 |
+|---|---|---|
+| 本地开发 | `.env` 文件 (已在 .gitignore) | 🟢 低 |
+| CI/CD | GitHub Secrets / GitLab Variables | 🟡 中 |
+| 生产环境 | HashiCorp Vault / 云 KMS | 🔴 高 |
+| Docker 部署 | Docker Secrets / Compose env_file | 🟡 中 |
+
+### 本地开发密钥管理
+
+```bash
+# ✅ .env 文件必须在 .gitignore 中
+echo ".env" >> .gitignore
+echo ".env.local" >> .gitignore
+
+# ✅ 提供 .env.example 作为模板（无真实密钥）
+cp .env .env.example
+# 手动清空 .env.example 中的敏感值
+```
+
+### Docker 部署密钥注入
+
+```yaml
+# ❌ BAD: docker-compose.yml 中硬编码密钥
+services:
+  app:
+    environment:
+      DB_PASSWORD: "my_secret_password"
+
+# ✅ GOOD: 通过 .env 文件注入
+services:
+  app:
+    env_file:
+      - .env
+    environment:
+      DB_PASSWORD: ${DB_PASSWORD}
+```
+
+### JWT 密钥生成
+
+```bash
+# 生成强随机 JWT 密钥
+openssl rand -base64 64
+
+# 或使用 PHP
+php -r "echo bin2hex(random_bytes(32));"
+```
+
+### 检查密钥安全
+
+```bash
+# 检查是否有密钥意外提交到仓库
+rg -rn "(?i)(api.?key|secret|password|token)\s*[=:]\s*['\"][a-zA-Z0-9]{8,}" \
+  --glob '!vendor/**' --glob '!node_modules/**' --glob '!*.lock' --glob '!.env*'
+```
+
+## 常见问题排查
+
+| 问题 | 解决方案 |
+|------|---------|
+| Swoole 未安装 | `pecl install swoole` 或使用 Docker |
+| Composer 依赖失败 | `composer clear-cache && composer install` |
+| Node 版本不匹配 | 使用 `nvm use 20` 切换版本 |
+| MySQL 连接失败 | 检查 `.env` 中 DB_HOST 和端口，确认 MySQL 正在运行 |
+| Redis 连接失败 | 检查 `.env` 中 REDIS_HOST，确认 Redis 正在运行 |
+| Hyperf 启动失败 | 检查 `runtime/` 目录权限，运行 `php bin/hyperf.php di:init-proxy` |
+| 端口冲突 9501 | `lsof -i :9501` 查看占用进程 |
+
+## 验证清单
+
+- [ ] PHP >= 8.1 且 Swoole >= 5.0 扩展已安装
+- [ ] Composer 依赖安装成功
+- [ ] Node.js >= 20 且 npm 安装成功
+- [ ] `php bin/hyperf.php start` 可正常启动 (HTTP 9501)
+- [ ] `npm run dev` 可正常启动 (Vite dev server)
+- [ ] MySQL 和 Redis 连接正常
+- [ ] 数据库迁移成功
+- [ ] 所有环境变量已配置
diff --git a/.cursor/skills/full-feature/SKILL.md b/.cursor/skills/full-feature/SKILL.md
new file mode 100644
index 0000000..b684a63
--- /dev/null
+++ b/.cursor/skills/full-feature/SKILL.md
@@ -0,0 +1,128 @@
+---
+name: full-feature
+version: 2.1.0
+description: "Vue 3 + Hyperf 端到端功能开发工作流。当需要从数据库到 API 到 UI 全链路开发完整功能时使用。编排多个技能协同工作。"
+requires: [component-scaffold, vue-testing]
+---
+
+> ⚠️ 核心执行流程已在 `.cursor/rules/skill-full-feature.mdc` 中由 Cursor 自动注入。
+> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
+
+# Full Feature Workflow (Vue 3 + Hyperf)
+
+## 触发条件
+
+用户要求开发一个完整功能（前端 + 后端 + 数据库 + 测试）。
+
+## 执行流程
+
+### Phase 1: 规划
+
+1. **拆分功能为子任务**：
+   - 数据层：需要什么数据模型和数据库变更？
+   - 后端 API：需要哪些 Controller/Service/Repository？
+   - 前端 UI：需要哪些组件和页面？
+   - 测试：每层需要什么测试？
+
+2. **确认技术决策**（向用户确认有争议的选择）
+
+3. **输出执行计划**：
+
+```
+## 功能: <功能名称>
+
+### 数据层
+- [ ] Hyperf Migration — 创建/修改表
+- [ ] Model 定义 — 关联、Casts、Fillable
+
+### 后端 API 层
+- [ ] POST /admin/<resources> — 创建
+- [ ] GET /admin/<resources> — 列表
+- [ ] GET /admin/<resources>/:id — 详情
+- [ ] PUT /admin/<resources>/:id — 更新
+- [ ] DELETE /admin/<resources>/:id — 删除
+- [ ] Service 业务逻辑
+- [ ] FormRequest 参数验证
+- [ ] 路由注册 + 中间件
+
+### 前端 UI 层
+- [ ] API 接口封装 (src/api/<module>)
+- [ ] 列表页 (src/views/<module>/<resource>/index.vue)
+- [ ] 表单组件 (src/components/custom/<Resource>Form.vue)
+- [ ] 详情页 (可选)
+- [ ] 路由配置 (src/router/routes/<module>.ts)
+- [ ] Store 模块 (如需跨页面状态)
+
+### 测试
+- [ ] PHPUnit — Service 层测试
+- [ ] Vitest — 组件渲染测试
+```
+
+### Phase 2: 数据层（使用 database-migration 技能）
+
+1. 生成迁移: `php bin/hyperf.php gen:migration create_<table>_table`
+2. 编写迁移（遵循高并发表设计规范）
+3. 执行迁移: `php bin/hyperf.php migrate`
+4. 生成 Model: `php bin/hyperf.php gen:model <table>`
+5. 补充 Model 关联和类型转换
+
+### Phase 3: 后端 API 层（使用 api-scaffold + hyperf-service 技能）
+
+1. 创建 Controller（接收请求、调用 Service）
+2. 创建 Service（核心业务逻辑、事务管理）
+3. 创建 Repository（可选，复杂查询时使用）
+4. 创建 FormRequest（输入验证）
+5. 注册路由 + 挂载中间件
+6. 编写 PHPUnit 测试
+
+### Phase 4: 前端 UI 层（使用 component-scaffold + vue-page 技能）
+
+1. 封装 API 接口
+
+```typescript
+// src/api/<module>/<resource>.ts
+import request from '@/utils/request'
+
+export const {{resource}}Api = {
+  list: (params) => request.get('/admin/{{resources}}', { params }),
+  getById: (id) => request.get(`/admin/{{resources}}/${id}`),
+  create: (data) => request.post('/admin/{{resources}}', data),
+  update: (id, data) => request.put(`/admin/{{resources}}/${id}`, data),
+  delete: (id) => request.delete(`/admin/{{resources}}/${id}`),
+}
+```
+
+2. 创建列表页（管理端：Element Plus 表格 + 分页；用户端：Tailwind 卡片/表格 + 自定义分页，禁止 Element Plus）
+3. 创建表单组件（管理端：Element Plus Form + 验证；用户端：Headless UI + Tailwind 表单，禁止 Element Plus）
+4. 创建详情页（如需要）
+5. 配置 Vue Router 路由
+6. 连接 API 到 Pinia Store（如需跨页面状态）
+
+### Phase 5: 集成验证
+
+1. 后端测试: `composer test`
+2. 后端静态分析: `composer analyse`
+3. 前端 Lint 检查: `npm run lint`
+5. 手动测试功能流程（CRUD 全路径）
+
+### Phase 6: 收尾
+
+1. 更新相关文档（data-model.md、api-contracts.md）
+2. Git commit（遵循 Conventional Commits）
+3. 汇报完成状态
+
+## 执行原则
+
+- **自底向上**：先数据层，再后端 API，再前端 UI
+- **每步验证**：每个 Phase 完成后运行测试
+- **可中断**：每个 Phase 独立可提交
+- **用已有技能**：尽量调用其他 Skill 而非从零写
+- **前后端分离**：API 契约先行，前后端可并行开发
+
+## 验证
+
+1. [ ] 后端测试全部通过
+2. [ ] 前端 ESLint 无报错
+3. [ ] 功能端到端可用（创建、列表、详情、编辑、删除）
+4. [ ] 代码遵循项目现有模式
+5. [ ] 文档已更新
diff --git a/.cursor/skills/hyperf-service/SKILL.md b/.cursor/skills/hyperf-service/SKILL.md
new file mode 100644
index 0000000..06457ef
--- /dev/null
+++ b/.cursor/skills/hyperf-service/SKILL.md
@@ -0,0 +1,69 @@
+---
+name: hyperf-service
+version: 2.0.0
+description: "生成 Hyperf 后端服务模块脚手架（Controller/Service/Repository/Model）。当需要新建后端业务模块时使用。支持 DI 注入和事务管理。"
+---
+
+> ⚠️ 核心执行流程已在 `.cursor/rules/skill-backend-scaffold.mdc` 中由 Cursor 自动注入。
+> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
+
+# Hyperf Service Module Scaffold
+
+## 触发条件
+
+用户要求创建后端服务模块、业务 Service 类、或完整的后端业务层。
+
+## 执行流程
+
+### 0. 加载规范（⚠️ 必须最先执行）
+
+依次读取 `.cursor/rules/013-backend.mdc`、`016-swoole.mdc`、`019-modular.mdc`，提取 DI、事务、协程安全、依赖方向、事件解耦。
+
+### 1. 确认模块规格
+
+| 字段 | 必填 | 默认值 |
+|------|------|--------|
+| 模块名称 | ✅ | — |
+| 所属业务域 | ❌ | 推断 |
+| 需要 Repository？ | ❌ | 复杂查询时 true |
+| 需要事件？ | ❌ | false |
+| 需要数据权限？ | ❌ | true |
+| 需要缓存？ | ❌ | false |
+
+### 2. 生成文件结构
+
+Controller/Admin、Service、Repository、Model、Request、Event、Listener（可选）。
+
+### 3. Service / Repository
+
+Service 使用 `Db::transaction` 包裹写操作，Repository 实现 `applyFilters`、`applyDataScope`、分页上限。完整模板见 **Tier 3**。
+
+### 4. 结构化日志
+
+Service 集成 HasLogger Trait，create/update/delete 至少 info 级别。RequestId 中间件全局注入 request_id。
+
+### 5. 重试机制
+
+外部 API 调用使用 RetryHelper 指数退避重试，retryOn 指定可重试异常类型。
+
+### 6. 遵循项目约定
+
+扫描 `app/Service/`、AbstractService、BusinessException、数据权限、事件注册、HasLogger、RetryHelper。
+
+## 验证
+
+1. [ ] `php -l` 无错误
+2. [ ] 依赖注入正确
+3. [ ] 写操作使用 `Db::transaction()`
+4. [ ] 分页有 page_size 上限
+5. [ ] 异常使用 BusinessException
+6. [ ] applyDataScope 已实现（如需）
+7. [ ] 关键操作有结构化日志
+8. [ ] 外部 API 用 RetryHelper
+9. [ ] Logger channel 使用类名
+
+## Tier 3 深度参考
+
+| 文件 | 内容 |
+|------|------|
+| `references/service-templates.md` | Service/Repository/Event/Logger/Retry 完整代码 |
diff --git a/.cursor/skills/hyperf-service/references/service-templates.md b/.cursor/skills/hyperf-service/references/service-templates.md
new file mode 100644
index 0000000..59c8809
--- /dev/null
+++ b/.cursor/skills/hyperf-service/references/service-templates.md
@@ -0,0 +1,120 @@
+# Hyperf Service — 代码模板
+
+> 主流程见 SKILL.md，本文档为 Service/Repository/Event/Logger/Retry 完整实现。
+
+## Service 模板
+
+```php
+<?php
+namespace App\Service\{{Domain}};
+
+use App\Model\{{Domain}}\{{Module}};
+use App\Repository\{{Domain}}\{{Module}}Repository;
+use App\Exception\BusinessException;
+use Hyperf\DbConnection\Db;
+use Hyperf\Di\Annotation\Inject;
+
+class {{Module}}Service
+{
+    #[Inject]
+    protected {{Module}}Repository $repository;
+
+    public function getPageList(array $params): array { return $this->repository->getPageList($params); }
+
+    public function getById(int $id): {{Module}} {
+        $record = {{Module}}::find($id);
+        if (!$record) throw new BusinessException(404, '{{Module}} not found');
+        return $record;
+    }
+
+    public function create(array $data): {{Module}} {
+        return Db::transaction(function () use ($data) {
+            $record = {{Module}}::create($data);
+            return $record;
+        });
+    }
+
+    public function update(int $id, array $data): {{Module}} {
+        $record = $this->getById($id);
+        return Db::transaction(function () use ($record, $data) {
+            $record->update($data);
+            return $record->refresh();
+        });
+    }
+
+    public function delete(int $id): void {
+        $record = $this->getById($id);
+        Db::transaction(fn () => $record->delete());
+    }
+}
+```
+
+## Repository 模板（含 applyFilters / applyDataScope）
+
+```php
+class {{Module}}Repository
+{
+    public function getPageList(array $params): array {
+        $query = {{Module}}::query();
+        $this->applyFilters($query, $params);
+        $this->applyDataScope($query);
+        $page = (int) ($params['page'] ?? 1);
+        $pageSize = min((int) ($params['page_size'] ?? 10), 100);
+        $total = $query->count();
+        $items = $query->with($this->getDefaultRelations())->orderByDesc('id')
+            ->offset(($page - 1) * $pageSize)->limit($pageSize)->get();
+        return ['items' => $items, 'total' => $total];
+    }
+
+    protected function applyFilters(Builder $query, array $params): void {
+        if (!empty($params['keyword'])) $query->where('name', 'like', "%{$params['keyword']}%");
+        if (!empty($params['status'])) $query->where('status', $params['status']);
+    }
+
+    protected function applyDataScope(Builder $query): void { /* 数据权限 */ }
+    protected function getDefaultRelations(): array { return []; }
+}
+```
+
+## Event + Listener 模板
+
+```php
+// Event
+class {{Module}}Created { public function __construct(public readonly {{Module}} $record) {} }
+
+// Listener
+#[Listener]
+class {{Module}}CreatedListener implements ListenerInterface
+{
+    public function listen(): array { return [{{Module}}Created::class]; }
+    public function process(object $event): void { /* 发送通知、更新缓存等 */ }
+}
+```
+
+## HasLogger Trait
+
+```php
+trait HasLogger {
+    protected ?LoggerInterface $logger = null;
+    protected function logger(): LoggerInterface { /* 按类名获取 channel */ }
+    protected function logContext(array $extra = []): array { return array_merge(['request_id' => Context::get('request_id'), 'user_id' => Context::get('current_user_id')], $extra); }
+}
+```
+
+## RetryHelper
+
+```php
+public static function withRetry(callable $fn, int $maxRetries = 3, int $baseDelayMs = 1000, array $retryOn = []): mixed {
+    for ($attempt = 0; $attempt <= $maxRetries; $attempt++) {
+        try { return $fn(); }
+        catch (\Throwable $e) {
+            if ($attempt < $maxRetries) Coroutine::sleep(($baseDelayMs * (2 ** $attempt) + jitter) / 1000);
+            else throw $e;
+        }
+    }
+}
+```
+
+## RequestIdMiddleware
+
+在 process 中：`Context::set('request_id', $requestId)`，响应头加 `X-Request-ID`。
diff --git a/.cursor/skills/i18n/SKILL.md b/.cursor/skills/i18n/SKILL.md
new file mode 100644
index 0000000..454085c
--- /dev/null
+++ b/.cursor/skills/i18n/SKILL.md
@@ -0,0 +1,253 @@
+---
+name: i18n
+version: 3.0.0
+description: "使用 vue-i18n 管理 Vue 3 应用的国际化。当需要添加多语言支持或管理翻译时使用。含语言包管理和路由国际化。"
+---
+
+> ⚠️ 核心执行流程已在 `.cursor/rules/skill-i18n.mdc` 中由 Cursor 自动注入。
+> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
+
+# Internationalization (i18n) — Vue 3 + vue-i18n
+
+## 触发条件
+
+用户要求添加多语言支持、翻译内容、配置国际化路由。
+
+## 执行流程
+
+### 1. 检测现有 i18n 方案
+
+```bash
+# 检查是否已有 i18n 库
+grep -E "vue-i18n|@intlify" package.json 2>/dev/null
+ls src/i18n* src/locales* 2>/dev/null
+```
+
+### 2. 初始化 i18n（如未配置）
+
+推荐方案：`vue-i18n`（Vue 3 官方国际化方案）
+
+```bash
+npm install vue-i18n@9
+```
+
+创建目录结构：
+```
+src/locales/
+├── index.ts              # i18n 实例配置
+├── zh-CN.ts              # 中文（简体）— 使用 JS 扁平对象格式
+├── en.ts                 # 英文 — 使用 JS 扁平对象格式
+└── modules/              # 按模块拆分（大型项目，同样使用 JS 格式）
+    ├── common.zh-CN.ts
+    └── common.en.ts
+```
+
+> **格式选择**：统一使用 `.ts` 文件（`export default { 'key': 'value' }`），
+> 而非 `.json`。原因：JS 格式支持注释、支持函数（复数规则）、支持扁平键名中的特殊字符，
+> 且与 vue-i18n v9 的 Composition API 配合更灵活。
+> 若项目已使用 `.json`，保持现有格式，不强制迁移。
+
+### 3. i18n 配置
+
+```typescript
+// src/locales/index.ts
+import { createI18n } from 'vue-i18n'
+import zhCN from './zh-CN.ts'
+import en from './en.ts'
+
+const i18n = createI18n({
+  legacy: false,
+  locale: localStorage.getItem('locale') || 'zh-CN',
+  fallbackLocale: 'en',
+  messages: {
+    'zh-CN': zhCN,
+    en,
+  },
+})
+
+export default i18n
+```
+
+```typescript
+// src/main.ts
+import i18n from './locales'
+app.use(i18n)
+```
+
+### 4. 翻译键命名规范
+
+**使用扁平 dot notation**（不使用嵌套对象），避免深层路径冲突：
+
+```typescript
+// ✅ 扁平 dot notation — 清晰、无歧义、工具友好
+export default {
+  'common.action.save': '保存',
+  'common.action.cancel': '取消',
+  'common.action.delete': '删除',
+  'common.status.loading': '加载中...',
+  'auth.action.login': '登录',
+  'auth.action.logout': '退出登录',
+  'auth.action.signUp': '注册',
+  'home.hero.title': '欢迎',
+  'home.hero.description': '...',
+}
+
+// ❌ 嵌套对象 — 容易产生路径冲突
+export default {
+  common: { save: '保存' },
+  pages: { home: { title: '...' } },
+}
+```
+
+**命名公式**：`{feature}.{context}.{action|status|label}`
+
+| 段 | 含义 | 示例 |
+|---|---|---|
+| `feature` | 业务功能/模块 | `order`、`user`、`common` |
+| `context` | 所在 UI 区域 | `list`、`form`、`dialog`、`action` |
+| `action\|status\|label` | 具体语义 | `submit`、`loading`、`title` |
+
+```typescript
+// 示例
+'order.list.title': '订单列表',
+'order.form.submit': '提交订单',
+'order.status.pending': '待处理',
+'order.dialog.deleteConfirm': '确认删除该订单？',
+'user.profile.edit': '编辑资料',
+```
+
+**键冲突预防**：
+
+```typescript
+// ❌ 冲突：'order.edit' 同时是叶子节点和父节点前缀
+'order.edit': '编辑',
+'order.edit.title': '编辑订单',
+
+// ✅ 修正：给叶子节点加上语义后缀
+'order.edit.action': '编辑',
+'order.edit.title': '编辑订单',
+```
+
+**参数化翻译**：
+
+```typescript
+// 语言包
+'order.total': '共 {count} 件商品，合计 {amount}',
+'user.greeting': '你好，{name}',
+
+// 组件中使用
+t('order.total', { count: 5, amount: '¥100.00' })
+t('user.greeting', { name: user.name })
+```
+
+**标准命名空间**（根据项目模块预定义，禁止随意创建）：
+
+| 命名空间 | 用途 | 文件 |
+|----------|------|------|
+| `common` | 通用 UI（按钮、状态、提示） | `common.ts` |
+| `auth` | 登录/注册/权限 | `auth.ts` |
+| `menu` | 侧边栏/导航菜单 | `menu.ts` |
+| `validation` | 表单校验提示 | `validation.ts` |
+| `error` | 错误码/错误提示 | `error.ts` |
+| `{module}` | 各业务模块 (order/user/...) | `{module}.ts` |
+
+新增命名空间时必须在此表中登记。
+
+### 5. 组件中使用
+
+```vue
+<script setup>
+import { useI18n } from 'vue-i18n'
+
+const { t, locale } = useI18n()
+
+function switchLanguage(lang) {
+  locale.value = lang
+  localStorage.setItem('locale', lang)
+}
+</script>
+
+<template>
+  <!-- 管理端 -->
+  <el-button @click="switchLanguage('en')">English</el-button>
+  <el-button @click="switchLanguage('zh-CN')">中文</el-button>
+
+  <!-- 用户端（禁止 Element Plus） -->
+  <button class="px-3 py-1 rounded border" @click="switchLanguage('en')">English</button>
+  <button class="px-3 py-1 rounded border" @click="switchLanguage('zh-CN')">中文</button>
+
+  <!-- 基础用法 -->
+  <p>{{ t('common.action.save') }}</p>
+
+  <!-- 参数化翻译 -->
+  <p>{{ t('order.total', { count: orderCount, amount: totalAmount }) }}</p>
+
+  <!-- 管理端：在 Element Plus 组件中使用 -->
+  <el-button type="primary">{{ t('common.action.save') }}</el-button>
+  <el-input :placeholder="t('order.form.searchPlaceholder')" />
+
+  <!-- 用户端：在 Tailwind 组件中使用 -->
+  <button class="bg-blue-600 text-white px-4 py-2 rounded-lg">{{ t('common.action.save') }}</button>
+  <input class="border rounded-lg px-3 py-2" :placeholder="t('order.form.searchPlaceholder')" />
+</template>
+```
+
+### 6. Element Plus 国际化（仅管理端）
+
+> 以下内容仅适用于 `Case-Database-Frontend-admin/`，用户端无需配置 Element Plus 国际化。
+
+`main.ts` 不在 setup 上下文中，无法使用 `computed` 做响应式切换。正确方案：`main.ts` 静态初始化，`App.vue` 中通过 `computed` + `ElConfigProvider` 动态响应：
+
+```typescript
+// src/main.ts
+import ElementPlus from 'element-plus'
+import zhCn from 'element-plus/es/locale/lang/zh-cn'
+import en from 'element-plus/es/locale/lang/en'
+
+// 初始化时根据 locale 选择语言包
+const elLocaleMap = { 'zh-CN': zhCn, en }
+const initLocale = localStorage.getItem('locale') || 'zh-CN'
+
+app.use(ElementPlus, { locale: elLocaleMap[initLocale] ?? zhCn })
+```
+
+```vue
+<!-- 在根组件 App.vue 中动态响应语言切换 -->
+<script setup>
+import { useI18n } from 'vue-i18n'
+import { computed } from 'vue'
+import zhCn from 'element-plus/es/locale/lang/zh-cn'
+import en from 'element-plus/es/locale/lang/en'
+
+const { locale } = useI18n()
+const elLocaleMap = { 'zh-CN': zhCn, en }
+
+// 通过 ElConfigProvider 的 locale prop 动态切换
+const elLocale = computed(() => elLocaleMap[locale.value] ?? zhCn)
+</script>
+
+<template>
+  <el-config-provider :locale="elLocale">
+    <router-view />
+  </el-config-provider>
+</template>
+```
+
+### 7. 添加新语言
+
+1. 在 `src/locales/` 下创建新的 locale JS 文件（如 `fr.ts`）
+2. 在 `src/locales/index.ts` 中注册新语言
+3. 翻译所有已有 key
+4. 管理端：同步 Element Plus 对应的 locale（用户端跳过此步）
+
+## 验证
+
+1. [ ] 所有 locale 文件的 key 结构一致（无遗漏）
+2. [ ] 切换语言后页面正确翻译
+3. [ ] 管理端：Element Plus 组件语言同步切换（用户端不适用）
+4. [ ] 日期/数字格式随 locale 变化
+5. [ ] 键命名遵循 `{feature}.{context}.{action|status|label}` 公式
+6. [ ] 使用扁平 dot notation，不使用嵌套对象
+7. [ ] 无键冲突（同一前缀不同时作为叶子节点和父节点前缀）
+8. [ ] 参数化翻译使用 `{variableName}` 语法
+9. [ ] 新命名空间已在标准命名空间表中登记
diff --git a/.cursor/skills/mcp-builder/SKILL.md b/.cursor/skills/mcp-builder/SKILL.md
new file mode 100644
index 0000000..ad719a9
--- /dev/null
+++ b/.cursor/skills/mcp-builder/SKILL.md
@@ -0,0 +1,144 @@
+---
+name: mcp-builder
+version: 1.1.0
+description: "构建 MCP Server，让 LLM 通过 Tool 与外部服务交互。当需要创建 MCP 工具或封装 API 为 MCP 时使用。推荐 TypeScript + MCP SDK。"
+---
+
+# MCP Server 开发指南
+
+## 触发条件
+
+用户需要构建自定义 MCP Server 以封装 API 或服务为 LLM 可调用的 Tool。
+
+## 执行流程
+
+### Phase 1：研究与规划
+
+#### 1.1 理解目标 API
+
+- 梳理目标服务的 API 端点、认证方式、数据模型
+- 使用 WebFetch 或 WebSearch 获取 API 文档
+- 列出需要封装的端点，按优先级排序（最常用操作优先）
+
+#### 1.2 学习 MCP 协议
+
+**加载 MCP 规范**：
+- 起始页：`https://modelcontextprotocol.io/sitemap.xml`
+- 获取特定页面时添加 `.md` 后缀获取 Markdown 格式
+
+**加载 MCP SDK 文档**：
+- WebFetch: `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
+- SDK 名称虽含 "typescript"，但完全支持纯 TypeScript 项目
+
+#### 1.3 设计 Tool
+
+| 设计原则 | 说明 |
+|---|---|
+| 命名清晰 | 使用 `prefix_action_target` 格式，如 `github_create_issue` |
+| 描述精准 | 简洁说明功能 + 参数含义 + 返回值结构 |
+| 错误可操作 | 错误信息应引导 LLM 找到解决方案 |
+| 结果聚焦 | 返回精准、相关的数据，支持分页/过滤 |
+| API 覆盖优先 | 不确定时优先提供全面的 API 覆盖，而非少量高层 Workflow Tool |
+
+---
+
+### Phase 2：实现
+
+**推荐技术栈**：
+- **语言**：TypeScript（MCP SDK 原生支持，无需编译，直接运行）
+- **传输**：远程服务用 Streamable HTTP（无状态 JSON），本地用 stdio
+
+#### 2.1 项目结构
+
+```
+mcp-server-{{name}}/
+├── src/
+│   ├── index.ts           # Server entry + tool registration
+│   ├── client.ts          # API client with auth
+│   └── tools/             # One file per tool group
+│       ├── resources.ts
+│       └── actions.ts
+├── package.json
+└── README.md
+```
+
+#### 2.2 基础设施
+
+实现共享工具：
+- API Client（认证、请求头、Base URL）
+- 错误处理 Helper（统一格式，包含 actionable 信息）
+- 响应格式化（JSON 结构化 + 文本摘要）
+- 分页支持
+
+#### 2.3 Tool 实现
+
+每个 Tool 需要：
+
+**输入 Schema**（Zod）：
+- Zod 在纯 TypeScript 中同样可用，提供运行时参数校验
+- 包含约束和清晰的字段描述
+- 在 description 中添加示例值
+
+**输出 Schema**（推荐定义）：
+- 使用 `outputSchema` + `structuredContent` 返回结构化数据
+
+**Tool 注解**：
+- `readOnlyHint`: 是否只读
+- `destructiveHint`: 是否有破坏性
+- `idempotentHint`: 是否幂等
+
+---
+
+### Phase 3：审查与测试
+
+#### 3.1 代码质量检查
+- 无重复代码（DRY）
+- 一致的错误处理
+- 关键函数和参数有 JSDoc 注释
+- 清晰的 Tool 描述
+
+#### 3.2 测试
+
+```bash
+# 直接运行验证语法
+node src/index.ts
+
+# 使用 MCP Inspector 交互式测试
+npx @modelcontextprotocol/inspector
+```
+
+---
+
+### Phase 4：集成到项目
+
+将构建好的 MCP Server 注册到 `.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "{{name}}": {
+      "command": "node",
+      "args": ["path/to/mcp-server-{{name}}/src/index.ts"],
+      "env": {
+        "API_KEY": "{{env_var}}"
+      }
+    }
+  }
+}
+```
+
+## 验证
+
+1. [ ] `node src/index.ts` 启动无错误
+2. [ ] MCP Inspector 可以列出所有 Tool
+3. [ ] 每个 Tool 的输入 Schema 有 Zod 校验
+4. [ ] 每个 Tool 的 description 清晰、包含参数说明
+5. [ ] 错误信息包含具体的修复建议（actionable）
+6. [ ] 需要分页的 Tool 支持 `cursor`/`limit` 参数
+7. [ ] 环境变量用于凭证/密钥，不硬编码
+8. [ ] `.cursor/mcp.json` 注册正确
+
+## Tier 3 参考资料（按需读取）
+
+- `references/mcp_best_practices.md` — MCP 最佳实践指南
+- `references/node_mcp_server.md` — TypeScript/Node.js 实现详细指南
diff --git a/.cursor/skills/mcp-builder/references/mcp_best_practices.md b/.cursor/skills/mcp-builder/references/mcp_best_practices.md
new file mode 100644
index 0000000..b9d343c
--- /dev/null
+++ b/.cursor/skills/mcp-builder/references/mcp_best_practices.md
@@ -0,0 +1,249 @@
+# MCP Server Best Practices
+
+## Quick Reference
+
+### Server Naming
+- **Python**: `{service}_mcp` (e.g., `slack_mcp`)
+- **Node/TypeScript**: `{service}-mcp-server` (e.g., `slack-mcp-server`)
+
+### Tool Naming
+- Use snake_case with service prefix
+- Format: `{service}_{action}_{resource}`
+- Example: `slack_send_message`, `github_create_issue`
+
+### Response Formats
+- Support both JSON and Markdown formats
+- JSON for programmatic processing
+- Markdown for human readability
+
+### Pagination
+- Always respect `limit` parameter
+- Return `has_more`, `next_offset`, `total_count`
+- Default to 20-50 items
+
+### Transport
+- **Streamable HTTP**: For remote servers, multi-client scenarios
+- **stdio**: For local integrations, command-line tools
+- Avoid SSE (deprecated in favor of streamable HTTP)
+
+---
+
+## Server Naming Conventions
+
+Follow these standardized naming patterns:
+
+**Python**: Use format `{service}_mcp` (lowercase with underscores)
+- Examples: `slack_mcp`, `github_mcp`, `jira_mcp`
+
+**Node/TypeScript**: Use format `{service}-mcp-server` (lowercase with hyphens)
+- Examples: `slack-mcp-server`, `github-mcp-server`, `jira-mcp-server`
+
+The name should be general, descriptive of the service being integrated, easy to infer from the task description, and without version numbers.
+
+---
+
+## Tool Naming and Design
+
+### Tool Naming
+
+1. **Use snake_case**: `search_users`, `create_project`, `get_channel_info`
+2. **Include service prefix**: Anticipate that your MCP server may be used alongside other MCP servers
+   - Use `slack_send_message` instead of just `send_message`
+   - Use `github_create_issue` instead of just `create_issue`
+3. **Be action-oriented**: Start with verbs (get, list, search, create, etc.)
+4. **Be specific**: Avoid generic names that could conflict with other servers
+
+### Tool Design
+
+- Tool descriptions must narrowly and unambiguously describe functionality
+- Descriptions must precisely match actual functionality
+- Provide tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
+- Keep tool operations focused and atomic
+
+---
+
+## Response Formats
+
+All tools that return data should support multiple formats:
+
+### JSON Format (`response_format="json"`)
+- Machine-readable structured data
+- Include all available fields and metadata
+- Consistent field names and types
+- Use for programmatic processing
+
+### Markdown Format (`response_format="markdown"`, typically default)
+- Human-readable formatted text
+- Use headers, lists, and formatting for clarity
+- Convert timestamps to human-readable format
+- Show display names with IDs in parentheses
+- Omit verbose metadata
+
+---
+
+## Pagination
+
+For tools that list resources:
+
+- **Always respect the `limit` parameter**
+- **Implement pagination**: Use `offset` or cursor-based pagination
+- **Return pagination metadata**: Include `has_more`, `next_offset`/`next_cursor`, `total_count`
+- **Never load all results into memory**: Especially important for large datasets
+- **Default to reasonable limits**: 20-50 items is typical
+
+Example pagination response:
+```json
+{
+  "total": 150,
+  "count": 20,
+  "offset": 0,
+  "items": [...],
+  "has_more": true,
+  "next_offset": 20
+}
+```
+
+---
+
+## Transport Options
+
+### Streamable HTTP
+
+**Best for**: Remote servers, web services, multi-client scenarios
+
+**Characteristics**:
+- Bidirectional communication over HTTP
+- Supports multiple simultaneous clients
+- Can be deployed as a web service
+- Enables server-to-client notifications
+
+**Use when**:
+- Serving multiple clients simultaneously
+- Deploying as a cloud service
+- Integration with web applications
+
+### stdio
+
+**Best for**: Local integrations, command-line tools
+
+**Characteristics**:
+- Standard input/output stream communication
+- Simple setup, no network configuration needed
+- Runs as a subprocess of the client
+
+**Use when**:
+- Building tools for local development environments
+- Integrating with desktop applications
+- Single-user, single-session scenarios
+
+**Note**: stdio servers should NOT log to stdout (use stderr for logging)
+
+### Transport Selection
+
+| Criterion | stdio | Streamable HTTP |
+|-----------|-------|-----------------|
+| **Deployment** | Local | Remote |
+| **Clients** | Single | Multiple |
+| **Complexity** | Low | Medium |
+| **Real-time** | No | Yes |
+
+---
+
+## Security Best Practices
+
+### Authentication and Authorization
+
+**OAuth 2.1**:
+- Use secure OAuth 2.1 with certificates from recognized authorities
+- Validate access tokens before processing requests
+- Only accept tokens specifically intended for your server
+
+**API Keys**:
+- Store API keys in environment variables, never in code
+- Validate keys on server startup
+- Provide clear error messages when authentication fails
+
+### Input Validation
+
+- Sanitize file paths to prevent directory traversal
+- Validate URLs and external identifiers
+- Check parameter sizes and ranges
+- Prevent command injection in system calls
+- Use schema validation (Pydantic/Zod) for all inputs
+
+### Error Handling
+
+- Don't expose internal errors to clients
+- Log security-relevant errors server-side
+- Provide helpful but not revealing error messages
+- Clean up resources after errors
+
+### DNS Rebinding Protection
+
+For streamable HTTP servers running locally:
+- Enable DNS rebinding protection
+- Validate the `Origin` header on all incoming connections
+- Bind to `127.0.0.1` rather than `0.0.0.0`
+
+---
+
+## Tool Annotations
+
+Provide annotations to help clients understand tool behavior:
+
+| Annotation | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `readOnlyHint` | boolean | false | Tool does not modify its environment |
+| `destructiveHint` | boolean | true | Tool may perform destructive updates |
+| `idempotentHint` | boolean | false | Repeated calls with same args have no additional effect |
+| `openWorldHint` | boolean | true | Tool interacts with external entities |
+
+**Important**: Annotations are hints, not security guarantees. Clients should not make security-critical decisions based solely on annotations.
+
+---
+
+## Error Handling
+
+- Use standard JSON-RPC error codes
+- Report tool errors within result objects (not protocol-level errors)
+- Provide helpful, specific error messages with suggested next steps
+- Don't expose internal implementation details
+- Clean up resources properly on errors
+
+Example error handling:
+```typescript
+try {
+  const result = performOperation();
+  return { content: [{ type: "text", text: result }] };
+} catch (error) {
+  return {
+    isError: true,
+    content: [{
+      type: "text",
+      text: `Error: ${error.message}. Try using filter='active_only' to reduce results.`
+    }]
+  };
+}
+```
+
+---
+
+## Testing Requirements
+
+Comprehensive testing should cover:
+
+- **Functional testing**: Verify correct execution with valid/invalid inputs
+- **Integration testing**: Test interaction with external systems
+- **Security testing**: Validate auth, input sanitization, rate limiting
+- **Performance testing**: Check behavior under load, timeouts
+- **Error handling**: Ensure proper error reporting and cleanup
+
+---
+
+## Documentation Requirements
+
+- Provide clear documentation of all tools and capabilities
+- Include working examples (at least 3 per major feature)
+- Document security considerations
+- Specify required permissions and access levels
+- Document rate limits and performance characteristics
diff --git a/.cursor/skills/mcp-builder/references/node_mcp_server.md b/.cursor/skills/mcp-builder/references/node_mcp_server.md
new file mode 100644
index 0000000..91bb0db
--- /dev/null
+++ b/.cursor/skills/mcp-builder/references/node_mcp_server.md
@@ -0,0 +1,970 @@
+# Node/TypeScript MCP Server Implementation Guide
+
+## Overview
+
+This document provides Node/TypeScript-specific best practices and examples for implementing MCP servers using the MCP TypeScript SDK. It covers project structure, server setup, tool registration patterns, input validation with Zod, error handling, and complete working examples.
+
+---
+
+## Quick Reference
+
+### Key Imports
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.ts";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.ts";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.ts";
+import express from "express";
+import { z } from "zod";
+```
+
+### Server Initialization
+```typescript
+const server = new McpServer({
+  name: "service-mcp-server",
+  version: "1.0.0"
+});
+```
+
+### Tool Registration Pattern
+```typescript
+server.registerTool(
+  "tool_name",
+  {
+    title: "Tool Display Name",
+    description: "What the tool does",
+    inputSchema: { param: z.string() },
+    outputSchema: { result: z.string() }
+  },
+  async ({ param }) => {
+    const output = { result: `Processed: ${param}` };
+    return {
+      content: [{ type: "text", text: JSON.stringify(output) }],
+      structuredContent: output // Modern pattern for structured data
+    };
+  }
+);
+```
+
+---
+
+## MCP TypeScript SDK
+
+The official MCP TypeScript SDK provides:
+- `McpServer` class for server initialization
+- `registerTool` method for tool registration
+- Zod schema integration for runtime input validation
+- Type-safe tool handler implementations
+
+**IMPORTANT - Use Modern APIs Only:**
+- **DO use**: `server.registerTool()`, `server.registerResource()`, `server.registerPrompt()`
+- **DO NOT use**: Old deprecated APIs such as `server.tool()`, `server.setRequestHandler(ListToolsRequestSchema, ...)`, or manual handler registration
+- The `register*` methods provide better type safety, automatic schema handling, and are the recommended approach
+
+See the MCP SDK documentation in the references for complete details.
+
+## Server Naming Convention
+
+Node/TypeScript MCP servers must follow this naming pattern:
+- **Format**: `{service}-mcp-server` (lowercase with hyphens)
+- **Examples**: `github-mcp-server`, `jira-mcp-server`, `stripe-mcp-server`
+
+The name should be:
+- General (not tied to specific features)
+- Descriptive of the service/API being integrated
+- Easy to infer from the task description
+- Without version numbers or dates
+
+## Project Structure
+
+Create the following structure for Node/TypeScript MCP servers:
+
+```
+{service}-mcp-server/
+├── package.json
+├── tsconfig.json
+├── README.md
+├── src/
+│   ├── index.ts          # Main entry point with McpServer initialization
+│   ├── types.ts          # TypeScript type definitions and interfaces
+│   ├── tools/            # Tool implementations (one file per domain)
+│   ├── services/         # API clients and shared utilities
+│   ├── schemas/          # Zod validation schemas
+│   └── constants.ts      # Shared constants (API_URL, CHARACTER_LIMIT, etc.)
+└── dist/                 # Built TypeScript files (entry point: dist/index.ts)
+```
+
+## Tool Implementation
+
+### Tool Naming
+
+Use snake_case for tool names (e.g., "search_users", "create_project", "get_channel_info") with clear, action-oriented names.
+
+**Avoid Naming Conflicts**: Include the service context to prevent overlaps:
+- Use "slack_send_message" instead of just "send_message"
+- Use "github_create_issue" instead of just "create_issue"
+- Use "asana_list_tasks" instead of just "list_tasks"
+
+### Tool Structure
+
+Tools are registered using the `registerTool` method with the following requirements:
+- Use Zod schemas for runtime input validation and type safety
+- The `description` field must be explicitly provided - JSDoc comments are NOT automatically extracted
+- Explicitly provide `title`, `description`, `inputSchema`, and `annotations`
+- The `inputSchema` must be a Zod schema object (not a JSON schema)
+- Type all parameters and return values explicitly
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.ts";
+import { z } from "zod";
+
+const server = new McpServer({
+  name: "example-mcp",
+  version: "1.0.0"
+});
+
+// Zod schema for input validation
+const UserSearchInputSchema = z.object({
+  query: z.string()
+    .min(2, "Query must be at least 2 characters")
+    .max(200, "Query must not exceed 200 characters")
+    .describe("Search string to match against names/emails"),
+  limit: z.number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(20)
+    .describe("Maximum results to return"),
+  offset: z.number()
+    .int()
+    .min(0)
+    .default(0)
+    .describe("Number of results to skip for pagination"),
+  response_format: z.nativeEnum(ResponseFormat)
+    .default(ResponseFormat.MARKDOWN)
+    .describe("Output format: 'markdown' for human-readable or 'json' for machine-readable")
+}).strict();
+
+// Type definition from Zod schema
+type UserSearchInput = z.infer<typeof UserSearchInputSchema>;
+
+server.registerTool(
+  "example_search_users",
+  {
+    title: "Search Example Users",
+    description: `Search for users in the Example system by name, email, or team.
+
+This tool searches across all user profiles in the Example platform, supporting partial matches and various search filters. It does NOT create or modify users, only searches existing ones.
+
+Args:
+  - query (string): Search string to match against names/emails
+  - limit (number): Maximum results to return, between 1-100 (default: 20)
+  - offset (number): Number of results to skip for pagination (default: 0)
+  - response_format ('markdown' | 'json'): Output format (default: 'markdown')
+
+Returns:
+  For JSON format: Structured data with schema:
+  {
+    "total": number,           // Total number of matches found
+    "count": number,           // Number of results in this response
+    "offset": number,          // Current pagination offset
+    "users": [
+      {
+        "id": string,          // User ID (e.g., "U123456789")
+        "name": string,        // Full name (e.g., "John Doe")
+        "email": string,       // Email address
+        "team": string,        // Team name (optional)
+        "active": boolean      // Whether user is active
+      }
+    ],
+    "has_more": boolean,       // Whether more results are available
+    "next_offset": number      // Offset for next page (if has_more is true)
+  }
+
+Examples:
+  - Use when: "Find all marketing team members" -> params with query="team:marketing"
+  - Use when: "Search for John's account" -> params with query="john"
+  - Don't use when: You need to create a user (use example_create_user instead)
+
+Error Handling:
+  - Returns "Error: Rate limit exceeded" if too many requests (429 status)
+  - Returns "No users found matching '<query>'" if search returns empty`,
+    inputSchema: UserSearchInputSchema,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
+  },
+  async (params: UserSearchInput) => {
+    try {
+      // Input validation is handled by Zod schema
+      // Make API request using validated parameters
+      const data = await makeApiRequest<any>(
+        "users/search",
+        "GET",
+        undefined,
+        {
+          q: params.query,
+          limit: params.limit,
+          offset: params.offset
+        }
+      );
+
+      const users = data.users || [];
+      const total = data.total || 0;
+
+      if (!users.length) {
+        return {
+          content: [{
+            type: "text",
+            text: `No users found matching '${params.query}'`
+          }]
+        };
+      }
+
+      // Prepare structured output
+      const output = {
+        total,
+        count: users.length,
+        offset: params.offset,
+        users: users.map((user: any) => ({
+          id: user.id,
+          name: user.name,
+          email: user.email,
+          ...(user.team ? { team: user.team } : {}),
+          active: user.active ?? true
+        })),
+        has_more: total > params.offset + users.length,
+        ...(total > params.offset + users.length ? {
+          next_offset: params.offset + users.length
+        } : {})
+      };
+
+      // Format text representation based on requested format
+      let textContent: string;
+      if (params.response_format === ResponseFormat.MARKDOWN) {
+        const lines = [`# User Search Results: '${params.query}'`, "",
+          `Found ${total} users (showing ${users.length})`, ""];
+        for (const user of users) {
+          lines.push(`## ${user.name} (${user.id})`);
+          lines.push(`- **Email**: ${user.email}`);
+          if (user.team) lines.push(`- **Team**: ${user.team}`);
+          lines.push("");
+        }
+        textContent = lines.join("\n");
+      } else {
+        textContent = JSON.stringify(output, null, 2);
+      }
+
+      return {
+        content: [{ type: "text", text: textContent }],
+        structuredContent: output // Modern pattern for structured data
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: "text",
+          text: handleApiError(error)
+        }]
+      };
+    }
+  }
+);
+```
+
+## Zod Schemas for Input Validation
+
+Zod provides runtime type validation:
+
+```typescript
+import { z } from "zod";
+
+// Basic schema with validation
+const CreateUserSchema = z.object({
+  name: z.string()
+    .min(1, "Name is required")
+    .max(100, "Name must not exceed 100 characters"),
+  email: z.string()
+    .email("Invalid email format"),
+  age: z.number()
+    .int("Age must be a whole number")
+    .min(0, "Age cannot be negative")
+    .max(150, "Age cannot be greater than 150")
+}).strict();  // Use .strict() to forbid extra fields
+
+// Enums
+enum ResponseFormat {
+  MARKDOWN = "markdown",
+  JSON = "json"
+}
+
+const SearchSchema = z.object({
+  response_format: z.nativeEnum(ResponseFormat)
+    .default(ResponseFormat.MARKDOWN)
+    .describe("Output format")
+});
+
+// Optional fields with defaults
+const PaginationSchema = z.object({
+  limit: z.number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(20)
+    .describe("Maximum results to return"),
+  offset: z.number()
+    .int()
+    .min(0)
+    .default(0)
+    .describe("Number of results to skip")
+});
+```
+
+## Response Format Options
+
+Support multiple output formats for flexibility:
+
+```typescript
+enum ResponseFormat {
+  MARKDOWN = "markdown",
+  JSON = "json"
+}
+
+const inputSchema = z.object({
+  query: z.string(),
+  response_format: z.nativeEnum(ResponseFormat)
+    .default(ResponseFormat.MARKDOWN)
+    .describe("Output format: 'markdown' for human-readable or 'json' for machine-readable")
+});
+```
+
+**Markdown format**:
+- Use headers, lists, and formatting for clarity
+- Convert timestamps to human-readable format
+- Show display names with IDs in parentheses
+- Omit verbose metadata
+- Group related information logically
+
+**JSON format**:
+- Return complete, structured data suitable for programmatic processing
+- Include all available fields and metadata
+- Use consistent field names and types
+
+## Pagination Implementation
+
+For tools that list resources:
+
+```typescript
+const ListSchema = z.object({
+  limit: z.number().int().min(1).max(100).default(20),
+  offset: z.number().int().min(0).default(0)
+});
+
+async function listItems(params: z.infer<typeof ListSchema>) {
+  const data = await apiRequest(params.limit, params.offset);
+
+  const response = {
+    total: data.total,
+    count: data.items.length,
+    offset: params.offset,
+    items: data.items,
+    has_more: data.total > params.offset + data.items.length,
+    next_offset: data.total > params.offset + data.items.length
+      ? params.offset + data.items.length
+      : undefined
+  };
+
+  return JSON.stringify(response, null, 2);
+}
+```
+
+## Character Limits and Truncation
+
+Add a CHARACTER_LIMIT constant to prevent overwhelming responses:
+
+```typescript
+// At module level in constants.ts
+export const CHARACTER_LIMIT = 25000;  // Maximum response size in characters
+
+async function searchTool(params: SearchInput) {
+  let result = generateResponse(data);
+
+  // Check character limit and truncate if needed
+  if (result.length > CHARACTER_LIMIT) {
+    const truncatedData = data.slice(0, Math.max(1, data.length / 2));
+    response.data = truncatedData;
+    response.truncated = true;
+    response.truncation_message =
+      `Response truncated from ${data.length} to ${truncatedData.length} items. ` +
+      `Use 'offset' parameter or add filters to see more results.`;
+    result = JSON.stringify(response, null, 2);
+  }
+
+  return result;
+}
+```
+
+## Error Handling
+
+Provide clear, actionable error messages:
+
+```typescript
+import axios, { AxiosError } from "axios";
+
+function handleApiError(error: unknown): string {
+  if (error instanceof AxiosError) {
+    if (error.response) {
+      switch (error.response.status) {
+        case 404:
+          return "Error: Resource not found. Please check the ID is correct.";
+        case 403:
+          return "Error: Permission denied. You don't have access to this resource.";
+        case 429:
+          return "Error: Rate limit exceeded. Please wait before making more requests.";
+        default:
+          return `Error: API request failed with status ${error.response.status}`;
+      }
+    } else if (error.code === "ECONNABORTED") {
+      return "Error: Request timed out. Please try again.";
+    }
+  }
+  return `Error: Unexpected error occurred: ${error instanceof Error ? error.message : String(error)}`;
+}
+```
+
+## Shared Utilities
+
+Extract common functionality into reusable functions:
+
+```typescript
+// Shared API request function
+async function makeApiRequest<T>(
+  endpoint: string,
+  method: "GET" | "POST" | "PUT" | "DELETE" = "GET",
+  data?: any,
+  params?: any
+): Promise<T> {
+  try {
+    const response = await axios({
+      method,
+      url: `${API_BASE_URL}/${endpoint}`,
+      data,
+      params,
+      timeout: 30000,
+      headers: {
+        "Content-Type": "application/json",
+        "Accept": "application/json"
+      }
+    });
+    return response.data;
+  } catch (error) {
+    throw error;
+  }
+}
+```
+
+## Async/Await Best Practices
+
+Always use async/await for network requests and I/O operations:
+
+```typescript
+// Good: Async network request
+async function fetchData(resourceId: string): Promise<ResourceData> {
+  const response = await axios.get(`${API_URL}/resource/${resourceId}`);
+  return response.data;
+}
+
+// Bad: Promise chains
+function fetchData(resourceId: string): Promise<ResourceData> {
+  return axios.get(`${API_URL}/resource/${resourceId}`)
+    .then(response => response.data);  // Harder to read and maintain
+}
+```
+
+## TypeScript Best Practices
+
+1. **Use Strict TypeScript**: Enable strict mode in tsconfig.json
+2. **Define Interfaces**: Create clear interface definitions for all data structures
+3. **Avoid `any`**: Use proper types or `unknown` instead of `any`
+4. **Zod for Runtime Validation**: Use Zod schemas to validate external data
+5. **Type Guards**: Create type guard functions for complex type checking
+6. **Error Handling**: Always use try-catch with proper error type checking
+7. **Null Safety**: Use optional chaining (`?.`) and nullish coalescing (`??`)
+
+```typescript
+// Good: Type-safe with Zod and interfaces
+interface UserResponse {
+  id: string;
+  name: string;
+  email: string;
+  team?: string;
+  active: boolean;
+}
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  team: z.string().optional(),
+  active: z.boolean()
+});
+
+type User = z.infer<typeof UserSchema>;
+
+async function getUser(id: string): Promise<User> {
+  const data = await apiCall(`/users/${id}`);
+  return UserSchema.parse(data);  // Runtime validation
+}
+
+// Bad: Using any
+async function getUser(id: string): Promise<any> {
+  return await apiCall(`/users/${id}`);  // No type safety
+}
+```
+
+## Package Configuration
+
+### package.json
+
+```json
+{
+  "name": "{service}-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for {Service} API integration",
+  "type": "module",
+  "main": "dist/index.ts",
+  "scripts": {
+    "start": "node dist/index.ts",
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "axios": "^1.7.9",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}
+```
+
+### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+## Complete Example
+
+```typescript
+#!/usr/bin/env node
+/**
+ * MCP Server for Example Service.
+ *
+ * This server provides tools to interact with Example API, including user search,
+ * project management, and data export capabilities.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.ts";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.ts";
+import { z } from "zod";
+import axios, { AxiosError } from "axios";
+
+// Constants
+const API_BASE_URL = "https://api.example.com/v1";
+const CHARACTER_LIMIT = 25000;
+
+// Enums
+enum ResponseFormat {
+  MARKDOWN = "markdown",
+  JSON = "json"
+}
+
+// Zod schemas
+const UserSearchInputSchema = z.object({
+  query: z.string()
+    .min(2, "Query must be at least 2 characters")
+    .max(200, "Query must not exceed 200 characters")
+    .describe("Search string to match against names/emails"),
+  limit: z.number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(20)
+    .describe("Maximum results to return"),
+  offset: z.number()
+    .int()
+    .min(0)
+    .default(0)
+    .describe("Number of results to skip for pagination"),
+  response_format: z.nativeEnum(ResponseFormat)
+    .default(ResponseFormat.MARKDOWN)
+    .describe("Output format: 'markdown' for human-readable or 'json' for machine-readable")
+}).strict();
+
+type UserSearchInput = z.infer<typeof UserSearchInputSchema>;
+
+// Shared utility functions
+async function makeApiRequest<T>(
+  endpoint: string,
+  method: "GET" | "POST" | "PUT" | "DELETE" = "GET",
+  data?: any,
+  params?: any
+): Promise<T> {
+  try {
+    const response = await axios({
+      method,
+      url: `${API_BASE_URL}/${endpoint}`,
+      data,
+      params,
+      timeout: 30000,
+      headers: {
+        "Content-Type": "application/json",
+        "Accept": "application/json"
+      }
+    });
+    return response.data;
+  } catch (error) {
+    throw error;
+  }
+}
+
+function handleApiError(error: unknown): string {
+  if (error instanceof AxiosError) {
+    if (error.response) {
+      switch (error.response.status) {
+        case 404:
+          return "Error: Resource not found. Please check the ID is correct.";
+        case 403:
+          return "Error: Permission denied. You don't have access to this resource.";
+        case 429:
+          return "Error: Rate limit exceeded. Please wait before making more requests.";
+        default:
+          return `Error: API request failed with status ${error.response.status}`;
+      }
+    } else if (error.code === "ECONNABORTED") {
+      return "Error: Request timed out. Please try again.";
+    }
+  }
+  return `Error: Unexpected error occurred: ${error instanceof Error ? error.message : String(error)}`;
+}
+
+// Create MCP server instance
+const server = new McpServer({
+  name: "example-mcp",
+  version: "1.0.0"
+});
+
+// Register tools
+server.registerTool(
+  "example_search_users",
+  {
+    title: "Search Example Users",
+    description: `[Full description as shown above]`,
+    inputSchema: UserSearchInputSchema,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
+  },
+  async (params: UserSearchInput) => {
+    // Implementation as shown above
+  }
+);
+
+// Main function
+// For stdio (local):
+async function runStdio() {
+  if (!process.env.EXAMPLE_API_KEY) {
+    console.error("ERROR: EXAMPLE_API_KEY environment variable is required");
+    process.exit(1);
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("MCP server running via stdio");
+}
+
+// For streamable HTTP (remote):
+async function runHTTP() {
+  if (!process.env.EXAMPLE_API_KEY) {
+    console.error("ERROR: EXAMPLE_API_KEY environment variable is required");
+    process.exit(1);
+  }
+
+  const app = express();
+  app.use(express.json());
+
+  app.post('/mcp', async (req, res) => {
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+      enableJsonResponse: true
+    });
+    res.on('close', () => transport.close());
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  });
+
+  const port = parseInt(process.env.PORT || '3000');
+  app.listen(port, () => {
+    console.error(`MCP server running on http://localhost:${port}/mcp`);
+  });
+}
+
+// Choose transport based on environment
+const transport = process.env.TRANSPORT || 'stdio';
+if (transport === 'http') {
+  runHTTP().catch(error => {
+    console.error("Server error:", error);
+    process.exit(1);
+  });
+} else {
+  runStdio().catch(error => {
+    console.error("Server error:", error);
+    process.exit(1);
+  });
+}
+```
+
+---
+
+## Advanced MCP Features
+
+### Resource Registration
+
+Expose data as resources for efficient, URI-based access:
+
+```typescript
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/types.ts";
+
+// Register a resource with URI template
+server.registerResource(
+  {
+    uri: "file://documents/{name}",
+    name: "Document Resource",
+    description: "Access documents by name",
+    mimeType: "text/plain"
+  },
+  async (uri: string) => {
+    // Extract parameter from URI
+    const match = uri.match(/^file:\/\/documents\/(.+)$/);
+    if (!match) {
+      throw new Error("Invalid URI format");
+    }
+
+    const documentName = match[1];
+    const content = await loadDocument(documentName);
+
+    return {
+      contents: [{
+        uri,
+        mimeType: "text/plain",
+        text: content
+      }]
+    };
+  }
+);
+
+// List available resources dynamically
+server.registerResourceList(async () => {
+  const documents = await getAvailableDocuments();
+  return {
+    resources: documents.map(doc => ({
+      uri: `file://documents/${doc.name}`,
+      name: doc.name,
+      mimeType: "text/plain",
+      description: doc.description
+    }))
+  };
+});
+```
+
+**When to use Resources vs Tools:**
+- **Resources**: For data access with simple URI-based parameters
+- **Tools**: For complex operations requiring validation and business logic
+- **Resources**: When data is relatively static or template-based
+- **Tools**: When operations have side effects or complex workflows
+
+### Transport Options
+
+The TypeScript SDK supports two main transport mechanisms:
+
+#### Streamable HTTP (Recommended for Remote Servers)
+
+```typescript
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.ts";
+import express from "express";
+
+const app = express();
+app.use(express.json());
+
+app.post('/mcp', async (req, res) => {
+  // Create new transport for each request (stateless, prevents request ID collisions)
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+    enableJsonResponse: true
+  });
+
+  res.on('close', () => transport.close());
+
+  await server.connect(transport);
+  await transport.handleRequest(req, res, req.body);
+});
+
+app.listen(3000);
+```
+
+#### stdio (For Local Integrations)
+
+```typescript
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.ts";
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+**Transport selection:**
+- **Streamable HTTP**: Web services, remote access, multiple clients
+- **stdio**: Command-line tools, local development, subprocess integration
+
+### Notification Support
+
+Notify clients when server state changes:
+
+```typescript
+// Notify when tools list changes
+server.notification({
+  method: "notifications/tools/list_changed"
+});
+
+// Notify when resources change
+server.notification({
+  method: "notifications/resources/list_changed"
+});
+```
+
+Use notifications sparingly - only when server capabilities genuinely change.
+
+---
+
+## Code Best Practices
+
+### Code Composability and Reusability
+
+Your implementation MUST prioritize composability and code reuse:
+
+1. **Extract Common Functionality**:
+   - Create reusable helper functions for operations used across multiple tools
+   - Build shared API clients for HTTP requests instead of duplicating code
+   - Centralize error handling logic in utility functions
+   - Extract business logic into dedicated functions that can be composed
+   - Extract shared markdown or JSON field selection & formatting functionality
+
+2. **Avoid Duplication**:
+   - NEVER copy-paste similar code between tools
+   - If you find yourself writing similar logic twice, extract it into a function
+   - Common operations like pagination, filtering, field selection, and formatting should be shared
+   - Authentication/authorization logic should be centralized
+
+## Building and Running
+
+Always build your TypeScript code before running:
+
+```bash
+# Build the project
+npm run build
+
+# Run the server
+npm start
+
+# Development with auto-reload
+npm run dev
+```
+
+Always ensure `npm run build` completes successfully before considering the implementation complete.
+
+## Quality Checklist
+
+Before finalizing your Node/TypeScript MCP server implementation, ensure:
+
+### Strategic Design
+- [ ] Tools enable complete workflows, not just API endpoint wrappers
+- [ ] Tool names reflect natural task subdivisions
+- [ ] Response formats optimize for agent context efficiency
+- [ ] Human-readable identifiers used where appropriate
+- [ ] Error messages guide agents toward correct usage
+
+### Implementation Quality
+- [ ] FOCUSED IMPLEMENTATION: Most important and valuable tools implemented
+- [ ] All tools registered using `registerTool` with complete configuration
+- [ ] All tools include `title`, `description`, `inputSchema`, and `annotations`
+- [ ] Annotations correctly set (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
+- [ ] All tools use Zod schemas for runtime input validation with `.strict()` enforcement
+- [ ] All Zod schemas have proper constraints and descriptive error messages
+- [ ] All tools have comprehensive descriptions with explicit input/output types
+- [ ] Descriptions include return value examples and complete schema documentation
+- [ ] Error messages are clear, actionable, and educational
+
+### TypeScript Quality
+- [ ] TypeScript interfaces are defined for all data structures
+- [ ] Strict TypeScript is enabled in tsconfig.json
+- [ ] No use of `any` type - use `unknown` or proper types instead
+- [ ] All async functions have explicit Promise<T> return types
+- [ ] Error handling uses proper type guards (e.g., `axios.isAxiosError`, `z.ZodError`)
+
+### Advanced Features (where applicable)
+- [ ] Resources registered for appropriate data endpoints
+- [ ] Appropriate transport configured (stdio or streamable HTTP)
+- [ ] Notifications implemented for dynamic server capabilities
+- [ ] Type-safe with SDK interfaces
+
+### Project Configuration
+- [ ] Package.json includes all necessary dependencies
+- [ ] Build script produces working TypeScript in dist/ directory
+- [ ] Main entry point is properly configured as dist/index.ts
+- [ ] Server name follows format: `{service}-mcp-server`
+- [ ] tsconfig.json properly configured with strict mode
+
+### Code Quality
+- [ ] Pagination is properly implemented where applicable
+- [ ] Large responses check CHARACTER_LIMIT constant and truncate with clear messages
+- [ ] Filtering options are provided for potentially large result sets
+- [ ] All network operations handle timeouts and connection errors gracefully
+- [ ] Common functionality is extracted into reusable functions
+- [ ] Return types are consistent across similar operations
+
+### Testing and Build
+- [ ] `npm run build` completes successfully without errors
+- [ ] dist/index.ts created and executable
+- [ ] Server runs: `node dist/index.ts --help`
+- [ ] All imports resolve correctly
+- [ ] Sample tool calls work as expected
\ No newline at end of file
diff --git a/.cursor/skills/message-queue/SKILL.md b/.cursor/skills/message-queue/SKILL.md
new file mode 100644
index 0000000..9a6ba3f
--- /dev/null
+++ b/.cursor/skills/message-queue/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: message-queue
+version: 1.0.0
+description: "配置 Hyperf AsyncQueue + Redis 实现后台任务处理。当需要异步任务、消息队列或延迟队列时使用。含重试策略和事件驱动模式。"
+---
+
+# Hyperf Async Queue (Message Queue)
+
+## 触发条件
+
+用户需要异步处理任务：通知发送、数据同步、超时检测、日志记录、批量操作。
+
+## 执行流程
+
+### Phase 0: 加载规范
+
+读取 `.cursor/rules/013-backend.mdc`、`016-swoole.mdc`，提取 Job 命名、DI、协程安全、连接池。
+
+### Phase 1: 队列配置
+
+`config/autoload/async_queue.php`：Redis 驱动、channel、retry_seconds 指数退避、handle_timeout、processes、concurrent。可配置 default 与 notification 等多队列。
+
+### Phase 2: Job 类
+
+继承 `Hyperf\AsyncQueue\Job`，`maxAttempts`、幂等检查、`handle()` 内 try-catch 记录日志后 re-throw 触发重试。
+
+### Phase 3: 投递任务
+
+QueueService 封装 `dispatch`、`dispatchNotification`、`dispatchDelayed`。从 DriverFactory 获取 driver 后 push。
+
+### Phase 4: 使用场景
+
+通知发送、超时检测（延迟 30 分钟）、批量处理（chunk 后逐批 dispatch）。
+
+### Phase 5: 事件驱动
+
+Event → Listener → QueueService.dispatch。Service 更新数据后 event() 触发，Listener 内异步投递多个 Job。
+
+### Phase 6: 监控
+
+队列 health check 命令：Redis 统计 waiting/delayed/failed/timeout，failed > 100 告警。
+
+完整实现见 **Tier 3**。
+
+## 验证
+
+1. [ ] 配置使用环境变量
+2. [ ] Job 幂等
+3. [ ] maxAttempts、retry_seconds 合理
+4. [ ] handle_timeout 大于 Job 最大执行时间
+5. [ ] 关键 Job 有错误日志
+6. [ ] 延迟队列用于超时检测
+7. [ ] 消费进程在 supervisor 注册
+
+## Tier 3 深度参考
+
+| 文件 | 内容 |
+|------|------|
+| `references/queue-implementation.md` | 配置、Job、投递、事件驱动、监控完整代码 |
diff --git a/.cursor/skills/message-queue/references/queue-implementation.md b/.cursor/skills/message-queue/references/queue-implementation.md
new file mode 100644
index 0000000..5418463
--- /dev/null
+++ b/.cursor/skills/message-queue/references/queue-implementation.md
@@ -0,0 +1,46 @@
+# Message Queue — 实现细节
+
+> 主流程见 SKILL.md，本文档为配置、Job、投递、事件驱动、监控的完整代码。
+
+## 队列配置
+
+```php
+// config/autoload/async_queue.php
+return [
+    'default' => [
+        'driver' => Hyperf\AsyncQueue\Driver\RedisDriver::class,
+        'redis' => ['pool' => 'default'],
+        'channel' => env('QUEUE_CHANNEL', '{queue}'),
+        'timeout' => 2,
+        'retry_seconds' => [1, 5, 10, 30, 60],
+        'handle_timeout' => 60,
+        'processes' => 1,
+        'concurrent' => ['limit' => 10],
+    ],
+    'notification' => [ /* 独立队列，更高优先级 */ ],
+];
+```
+
+## Job 类模板
+
+```php
+class {{JobName}}Job extends Job
+{
+    protected int $maxAttempts = 3;
+    public function __construct(protected readonly int $resourceId, protected readonly array $payload = []) {}
+    public function handle(): void {
+        $resource = $this->getResource();
+        if (!$resource || $this->isAlreadyProcessed($resource)) return;
+        try { $this->process($resource); }
+        catch (\Throwable $e) { logger()->error(...); throw $e; }
+    }
+}
+```
+
+## 投递与事件驱动
+
+QueueService：`dispatch($job, $delay)`、`dispatchNotification($job)`、`dispatchDelayed($job, $delaySeconds)`。事件驱动：Event → Listener → QueueService->dispatch。示例：OrderStatusChanged → 异步通知、同步外部、更新统计缓存（debounce 5s）。
+
+## 监控命令
+
+Redis `{queue}:waiting`、`{queue}:delayed`、`{queue}:failed`、`{queue}:timeout`。failed > 100 告警。
diff --git a/.cursor/skills/module-scaffold/SKILL.md b/.cursor/skills/module-scaffold/SKILL.md
new file mode 100644
index 0000000..dbf52de
--- /dev/null
+++ b/.cursor/skills/module-scaffold/SKILL.md
@@ -0,0 +1,386 @@
+---
+name: module-scaffold
+version: 2.1.0
+description: "生成 Hyperf 模块化业务模块脚手架（ConfigProvider/Controller/Service/Model）。当需要新建业务模块、创建 module、添加模块化功能时使用。基于 ModuleLoader 自动发现 + ConfigProvider 机制，无需修改 composer.json。"
+requires: [hyperf-service]
+---
+
+> ⚠️ 核心执行流程已在 `.cursor/rules/skill-module-scaffold.mdc` 中由 Cursor 自动注入。
+> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
+
+# Hyperf Module Scaffold
+
+## 触发条件
+
+用户要求创建新的业务模块、在 `modules/` 下新建功能模块、或提到"模块化"、"新模块"、"module"。
+
+## 前置条件
+
+项目已完成模块化架构初始化：
+- `Case-Database-Backend/modules/` 目录存在
+- `app/Support/ModuleLoader.php` 已存在并注册到 `composer.json` `autoload.files`
+- `config/autoload/annotations.php` 已包含 `BASE_PATH . '/modules'` 扫描路径
+
+若未初始化，先引导用户完成架构搭建。
+
+## 工作原理
+
+`ModuleLoader.php` 在 `vendor/autoload.php` 加载时（Hyperf DI 容器初始化之前）自动执行：
+1. 扫描 `modules/*/composer.json`
+2. 读取每个模块的 `extra.hyperf.config`
+3. 通过反射注入 `Hyperf\Support\Composer::$extra`
+4. 同时注册模块的 PSR-4 命名空间到 Composer ClassLoader
+
+这使得 `ProviderConfig::load()` 能发现所有模块的 ConfigProvider，**无需将模块添加到主项目 `composer.json` 的 `require` 中**。
+
+## 执行流程
+
+### 1. 确认模块规格
+
+| 字段 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| 模块名称 | ✅ | — | PascalCase，如 `Order`、`UserCenter` |
+| 模块描述 | ❌ | 推断 | 一句话说明模块职责 |
+| 接口类型 | ❌ | `api` | `api`（用户端）/ `admin`（管理端）/ `both`（两者都有） |
+| 需要 Service？ | ❌ | true | 业务逻辑层 |
+| 需要 Model？ | ❌ | false | 数据模型 |
+| 需要 Repository？ | ❌ | false | 复杂查询时 |
+| 需要 Middleware？ | ❌ | false | 模块级中间件 |
+| 需要 Request？ | ❌ | false | 表单验证 |
+| 路由前缀 | ❌ | 见下方规则 | 自动推断，也可手动指定 |
+
+### 2. Controller 与 Request 目录结构规则（核心）
+
+根据接口类型，Controller 和 Request **均放入对应子目录**，命名空间随之变更：
+
+| 接口类型 | 路由前缀 | Controller 目录 | Request 目录 | PHP 命名空间（Controller） |
+|----------|----------|-----------------|--------------|--------------------------|
+| 用户端 API（`/api/*`） | `/api/{module-kebab}` | `Http/Controller/Api/` | `Http/Request/Api/` | `Modules\{Name}\Http\Controller\Api` |
+| 管理端 API（`/admin/*`） | `/admin/{module-kebab}` | `Http/Controller/Admin/` | `Http/Request/Admin/` | `Modules\{Name}\Http\Controller\Admin` |
+| 两者都有（`both`） | 各自前缀 | 两个 Controller 子目录 | 两个 Request 子目录 | 各自命名空间 |
+
+**判断规则**：
+- 路由前缀包含 `/api/` → Controller 放 `Controller/Api/`，Request 放 `Request/Api/`
+- 路由前缀包含 `/admin/` → Controller 放 `Controller/Admin/`，Request 放 `Request/Admin/`
+- 用户未指定接口类型时，优先询问，或根据模块职责推断
+- 若模块同时有用户端和管理端接口，两组子目录都创建
+- **类名不需要加接口类型前缀**，子目录本身已区分，类名保持简洁
+
+### 3. 生成目录结构
+
+**仅有用户端 API（最常见）**：
+```
+modules/{ModuleName}/
+├── composer.json
+└── src/
+    ├── ConfigProvider.php
+    ├── Http/
+    │   ├── Controller/
+    │   │   └── Api/                   # 用户端控制器
+    │   │       └── {Name}Controller.php
+    │   ├── Request/
+    │   │   └── Api/                   # 用户端请求验证
+    │   │       └── {Name}Request.php
+    │   └── Middleware/                # 模块中间件（按需）
+    ├── Service/
+    ├── Model/                         # 按需
+    ├── Repository/                    # 按需
+    ├── Event/                         # 按需
+    ├── Listener/                      # 按需
+    └── Constants/                     # 按需
+```
+
+**仅有管理端 API**：
+```
+modules/{ModuleName}/
+└── src/
+    ├── Http/
+    │   ├── Controller/
+    │   │   └── Admin/                 # 管理端控制器
+    │   │       └── {Name}Controller.php
+    │   ├── Request/
+    │   │   └── Admin/                 # 管理端请求验证
+    │   │       └── {Name}Request.php
+    ...
+```
+
+**同时有用户端 + 管理端（both）**：
+```
+modules/{ModuleName}/
+└── src/
+    ├── Http/
+    │   ├── Controller/
+    │   │   ├── Api/                   # 用户端控制器
+    │   │   │   └── {Name}Controller.php
+    │   │   └── Admin/                 # 管理端控制器
+    │   │       └── {Name}Controller.php
+    │   ├── Request/
+    │   │   ├── Api/                   # 用户端请求验证
+    │   │   │   └── {Name}Request.php
+    │   │   └── Admin/                 # 管理端请求验证
+    │   │       └── {Name}Request.php
+    ...
+```
+
+### 4. 生成 composer.json
+
+```json
+{
+    "name": "modules/{module-kebab}",
+    "description": "{模块描述}",
+    "type": "library",
+    "autoload": {
+        "psr-4": {
+            "Modules\\{ModuleName}\\": "src/"
+        }
+    },
+    "extra": {
+        "hyperf": {
+            "config": "Modules\\{ModuleName}\\ConfigProvider"
+        }
+    }
+}
+```
+
+**命名规则**：
+- Composer 包名：`modules/{kebab-case}`，如 `modules/user-center`
+- PHP 命名空间：`Modules\{PascalCase}`，如 `Modules\UserCenter`
+
+如模块有独立的第三方依赖，可在模块 `composer.json` 的 `require` 中声明，`wikimedia/composer-merge-plugin` 会在下次 `composer update` 时合并到主项目。
+
+### 5. 生成 ConfigProvider.php
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\{ModuleName};
+
+class ConfigProvider
+{
+    public function __invoke(): array
+    {
+        return [
+            'dependencies' => [
+                // Interface::class => Implementation::class,
+            ],
+            'annotations' => [
+                'scan' => [
+                    'paths' => [
+                        __DIR__,
+                    ],
+                ],
+            ],
+            'publish' => [],
+        ];
+    }
+}
+```
+
+**ConfigProvider 职责**：
+- `dependencies`：注册模块的 DI 绑定（接口 → 实现）
+- `annotations.scan.paths`：注册注解扫描路径（`__DIR__` 指向 `src/`）
+- `publish`：可发布的配置文件（可选）
+
+### 6. 生成 Controller 模板
+
+**用户端 API Controller**（放在 `Http/Controller/Api/`）：
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\{ModuleName}\Http\Controller\Api;
+
+use App\Controller\AbstractController;
+use App\Support\ResponseTrait;
+use Hyperf\Di\Annotation\Inject;
+use Hyperf\HttpServer\Annotation\Controller;
+use Hyperf\HttpServer\Annotation\GetMapping;
+use Modules\{ModuleName}\Service\{ModuleName}Service;
+use Psr\Http\Message\ResponseInterface;
+
+#[Controller(prefix: '/api/{module-kebab}')]
+class {ModuleName}Controller extends AbstractController
+{
+    use ResponseTrait;
+
+    #[Inject]
+    protected {ModuleName}Service ${moduleName}Service;
+
+    #[GetMapping(path: '')]
+    public function index(): ResponseInterface
+    {
+        return $this->success([]);
+    }
+}
+```
+
+**管理端 API Controller**（放在 `Http/Controller/Admin/`）：
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\{ModuleName}\Http\Controller\Admin;
+
+use App\Controller\AbstractController;
+use App\Middleware\JwtAuthMiddleware;
+use App\Support\ResponseTrait;
+use Hyperf\Di\Annotation\Inject;
+use Hyperf\HttpServer\Annotation\Controller;
+use Hyperf\HttpServer\Annotation\GetMapping;
+use Hyperf\HttpServer\Annotation\Middleware;
+use Modules\{ModuleName}\Service\{ModuleName}Service;
+use Psr\Http\Message\ResponseInterface;
+
+#[Controller(prefix: '/admin/{module-kebab}')]
+#[Middleware(JwtAuthMiddleware::class)]
+class {ModuleName}Controller extends AbstractController
+{
+    use ResponseTrait;
+
+    #[Inject]
+    protected {ModuleName}Service ${moduleName}Service;
+
+    #[GetMapping(path: '')]
+    public function index(): ResponseInterface
+    {
+        return $this->success([]);
+    }
+}
+```
+
+**关键区别**：
+- `Api/` 下：前缀 `/api/`，命名空间含 `\Api\`
+- `Admin/` 下：前缀 `/admin/`，命名空间含 `\Admin\`，自动加 `JwtAuthMiddleware`
+- **两者类名相同**（均为 `{Name}Controller`），由命名空间区分，无需加接口类型前缀
+
+### 7. 生成 Request 模板
+
+**用户端 Request**（放在 `Http/Request/Api/`）：
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\{ModuleName}\Http\Request\Api;
+
+use Hyperf\Validation\Request\FormRequest;
+
+class {Name}Request extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            // 'field' => 'required|string|max:255',
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [];
+    }
+}
+```
+
+**管理端 Request**（放在 `Http/Request/Admin/`）：
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\{ModuleName}\Http\Request\Admin;
+
+use Hyperf\Validation\Request\FormRequest;
+
+class {Name}Request extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            // 'field' => 'required|string|max:255',
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [];
+    }
+}
+```
+
+**关键区别**：
+- `Api/` 下：命名空间含 `\Request\Api\`，类名 `{Name}Request`
+- `Admin/` 下：命名空间含 `\Request\Admin\`，类名 `{Name}Request`
+- **两者类名相同**，由命名空间区分，无需加接口类型前缀
+- Controller 中 `use` 路径需对应各自子命名空间
+
+### 8. 验证模块自动发现
+
+创建文件后**无需任何 composer 操作**，直接验证：
+
+```bash
+docker exec hyperf-skeleton php -r "
+define('BASE_PATH', '/opt/www');
+require '/opt/www/vendor/autoload.php';
+\$extra = Hyperf\Support\Composer::getMergedExtra('hyperf');
+echo in_array('Modules\\{ModuleName}\\ConfigProvider', \$extra['config'] ?? []) ? 'OK' : 'FAIL';
+"
+```
+
+## 模块间依赖
+
+若模块 A 依赖模块 B 的类：
+- 通过 DI 注入模块 B 的 Service（不直接依赖 Controller/Model）
+- 遵循依赖方向：上层模块 → 下层模块，禁止循环依赖
+- ModuleLoader 的 glob 扫描天然支持多模块并存，无需额外配置
+
+## 已有模块示例参考
+
+当前项目 `modules/Auth/` 的实际结构（**参考标准**）：
+
+```
+modules/Auth/src/Http/Controller/
+├── Api/                          # 用户端接口（推荐新规范）
+│   ├── AuthController.php        # prefix: /api/auth
+│   ├── CaptchaController.php     # prefix: /api/auth/captcha
+│   └── SmsController.php         # prefix: /api/auth/sms
+└── Admin/                        # 管理端接口（推荐新规范）
+    └── AdminAuthController.php   # prefix: /admin/auth
+```
+
+> 注：当前 Auth 模块尚未按此规范重构（所有 Controller 平铺在 `Controller/` 下），新模块应从一开始遵循子目录规范。
+
+## 验证
+
+1. [ ] 模块目录结构完整（composer.json + src/ConfigProvider.php + Http/Controller/）
+2. [ ] **Controller 按接口类型放入正确子目录**：`/api/*` → `Controller/Api/`，`/admin/*` → `Controller/Admin/`
+3. [ ] Controller 命名空间包含正确子层级：`...\Http\Controller\Api\` 或 `...\Http\Controller\Admin\`
+4. [ ] `Admin/` 下的 Controller 自动添加 `JwtAuthMiddleware`；类名与 `Api/` 下保持一致，无需加前缀
+5. [ ] **Request 按接口类型放入正确子目录**：`/api/*` → `Request/Api/`，`/admin/*` → `Request/Admin/`
+6. [ ] Request 命名空间包含正确子层级：`...\Http\Request\Api\` 或 `...\Http\Request\Admin\`
+7. [ ] Controller 中 `use` 的 Request 路径与子目录一致
+8. [ ] composer.json 的 `name` 使用 `modules/{kebab-case}` 格式
+9. [ ] namespace 使用 `Modules\{PascalCase}` 格式
+10. [ ] ConfigProvider 注册了 `__DIR__` 注解扫描路径
+11. [ ] `extra.hyperf.config` 指向正确的 ConfigProvider 类
+12. [ ] 无需修改主项目 `composer.json`，模块被 ModuleLoader 自动发现
+13. [ ] `ProviderConfig::load()` 能发现模块 ConfigProvider
+14. [ ] `php -l` 所有 PHP 文件语法正确
+15. [ ] Controller 路由前缀遵循 RESTful 命名（kebab-case）
diff --git a/.cursor/skills/nginx-config/SKILL.md b/.cursor/skills/nginx-config/SKILL.md
new file mode 100644
index 0000000..d1a0dac
--- /dev/null
+++ b/.cursor/skills/nginx-config/SKILL.md
@@ -0,0 +1,216 @@
+---
+name: nginx-config
+version: 2.0.0
+description: "配置 Nginx 作为 Hyperf + Vue 3 的反向代理和静态文件服务。当需要 SSL、负载均衡或 Nginx 优化时使用。"
+---
+
+# 🔧 Nginx Config (Hyperf + Vue 3 SPA)
+
+## 触发条件
+
+用户需要配置 Nginx 作为 Hyperf API + Vue 3 SPA 前端的反向代理、SSL 终端、静态文件服务器或负载均衡器。
+
+## Phase 0：场景确认
+
+| 场景 | 对应配置 |
+|------|---------|
+| 开发环境反向代理 | 基础 proxy_pass |
+| 生产环境单机部署 | proxy_pass + SSL + 安全头 |
+| 多实例负载均衡 | upstream + health check |
+| 前端 SPA 静态资源 | try_files + 长期缓存 |
+| WebSocket 支持 | upgrade + connection 头 |
+| API 反向代理 | /api -> Hyperf 9501 |
+
+---
+
+## Phase 1：基础架构配置 (Hyperf + Vue 3 SPA)
+
+```nginx
+# /etc/nginx/sites-available/myapp.conf
+
+# ── 后端 Upstream ─────────────────────────
+upstream hyperf_backend {
+    server 127.0.0.1:9501;
+    keepalive 32;
+}
+
+upstream hyperf_websocket {
+    server 127.0.0.1:9502;
+}
+
+# ── HTTP -> HTTPS 重定向 ──────────────────
+server {
+    listen 80;
+    server_name example.com www.example.com;
+    return 301 https://$server_name$request_uri;
+}
+
+# ── 主配置 ────────────────────────────────
+server {
+    listen 443 ssl http2;
+    server_name example.com www.example.com;
+
+    # ── SSL 证书 ──────────────────────────
+    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
+    ssl_protocols       TLSv1.2 TLSv1.3;
+    ssl_ciphers         HIGH:!aNULL:!MD5;
+    ssl_session_cache   shared:SSL:10m;
+    ssl_session_timeout 10m;
+
+    # ── 安全头 ────────────────────────────
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+    add_header X-Content-Type-Options     nosniff always;
+    add_header X-Frame-Options            DENY always;
+    add_header X-XSS-Protection           "1; mode=block" always;
+    add_header Referrer-Policy            "strict-origin-when-cross-origin" always;
+
+    # ── 文件上传限制 ──────────────────────
+    client_max_body_size 20M;
+
+    # ── Gzip 压缩 ────────────────────────
+    gzip on;
+    gzip_min_length 1k;
+    gzip_comp_level 6;
+    gzip_vary on;
+    gzip_types
+        text/plain
+        text/css
+        application/json
+        application/typescript
+        text/xml
+        application/xml
+        image/svg+xml;
+
+    # ── Vue 3 SPA 前端 ───────────────────
+    root /var/www/myapp/Case-Database-Frontend-user/dist;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # ── Vite 产物静态资源（带 hash 长期缓存）──
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+        access_log off;
+    }
+
+    location /favicon.ico {
+        expires 30d;
+        access_log off;
+    }
+
+    # ── Hyperf API 反向代理 ──────────────
+    location /admin/ {
+        proxy_pass http://hyperf_backend;
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+        proxy_set_header Host              $host;
+        proxy_set_header X-Real-IP         $remote_addr;
+        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        proxy_connect_timeout 60s;
+        proxy_send_timeout    60s;
+        proxy_read_timeout    60s;
+    }
+
+    # ── WebSocket 代理 ───────────────────
+    location /ws {
+        proxy_pass http://hyperf_websocket;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade    $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host              $host;
+        proxy_set_header X-Real-IP         $remote_addr;
+        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+
+        proxy_connect_timeout 3600s;
+        proxy_send_timeout    3600s;
+        proxy_read_timeout    3600s;
+    }
+
+    # ── 文件上传/下载 ────────────────────
+    location /admin/upload {
+        proxy_pass http://hyperf_backend;
+        client_max_body_size 50M;
+        proxy_request_buffering off;
+    }
+
+    # ── 拒绝隐藏文件 ────────────────────
+    location ~ /\. {
+        deny all;
+        access_log off;
+        log_not_found off;
+    }
+}
+```
+
+---
+
+## Phase 2：负载均衡配置
+
+```nginx
+# 多 Hyperf 实例
+upstream hyperf_backend {
+    least_conn;
+    server 10.0.0.1:9501 weight=3;
+    server 10.0.0.2:9501 weight=3;
+    server 10.0.0.3:9501 backup;
+    keepalive 64;
+}
+
+# 健康检查（需要 nginx-upstream-check 模块或商业版）
+# 替代方案：K8s Ingress + Pod 健康检查
+```
+
+---
+
+## Phase 3：Let's Encrypt SSL
+
+```bash
+# 安装 Certbot
+sudo apt install certbot python3-certbot-nginx
+
+# 自动获取证书
+sudo certbot --nginx -d example.com -d www.example.com
+
+# 自动续期（Certbot 自动添加 cron）
+sudo certbot renew --dry-run
+```
+
+---
+
+## Phase 4：Docker Compose 中的 Nginx
+
+```yaml
+# docker-compose.yml 中 Nginx 服务
+services:
+  nginx:
+    image: nginx:1.25-alpine
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx/conf.d:/etc/nginx/conf.d
+      - ./Case-Database-Frontend-user/dist:/var/www/myapp/Case-Database-Frontend-user/dist:ro
+      - ./certbot/conf:/etc/letsencrypt:ro
+    depends_on:
+      - hyperf
+    restart: unless-stopped
+```
+
+---
+
+## 验证
+
+1. [ ] `nginx -t` 配置语法检查通过
+2. [ ] HTTPS 证书有效
+3. [ ] SPA 路由刷新正常 (try_files -> /index.html)
+4. [ ] API 代理 `/admin/*` 正常
+5. [ ] WebSocket `/ws` 连接正常
+6. [ ] 静态资源 `/assets/*` 带 Cache-Control
+7. [ ] 安全头通过 securityheaders.com 检查
+8. [ ] Gzip 压缩生效
diff --git a/.cursor/skills/performance-audit/SKILL.md b/.cursor/skills/performance-audit/SKILL.md
new file mode 100644
index 0000000..0f76200
--- /dev/null
+++ b/.cursor/skills/performance-audit/SKILL.md
@@ -0,0 +1,79 @@
+---
+name: performance-audit
+version: 1.0.0
+description: "分析并优化应用性能。当用户报告页面慢、加载卡或包体积大时使用。涵盖前端渲染、网络、打包和数据库四个维度。"
+---
+
+> ⚠️ 核心执行流程已在 `.cursor/rules/022-performance.mdc` 中由 Cursor 自动注入。
+> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
+
+# Performance Audit
+
+## 触发条件
+
+用户报告性能问题、请求性能优化或要求性能审计。
+
+## 执行流程
+
+### 1. 性能基线
+
+收集当前数据：
+```bash
+# 前端打包分析 (Vite)
+for dir in Case-Database-Frontend-user Case-Database-Frontend-admin; do
+  echo "=== $dir ==="
+  cd $dir && npm run build 2>&1 | tail -20
+  du -sh dist/
+  cd ..
+done
+
+# 后端状态
+cd Case-Database-Backend && php bin/hyperf.php describe:routes | wc -l
+```
+
+### 2. 四维度审计
+
+**前端渲染**
+- Vue DevTools 分析不必要的重渲染
+- 检查大列表是否缺少 `v-memo` / `shallowRef`
+- 检查大列表是否使用虚拟化（`@tanstack/vue-virtual`）
+- 检查图片是否压缩（WebP 格式 + CDN）
+- 管理端：Element Plus 是否按需导入（用户端不使用 Element Plus）
+
+**网络请求**
+- 是否有瀑布式请求（串行 → 并行）
+- API 响应是否有 Redis 缓存策略
+- Axios 是否配置请求/响应拦截
+- 静态内容是否配置 Nginx 缓存
+
+**打包体积**
+- 是否有不必要的大依赖
+- 是否使用 dynamic import 进行代码分割
+- 是否 tree-shaking 有效
+- 检查 barrel exports 是否导致全量导入
+
+**数据库查询**
+- N+1 查询检测
+- 缺少索引的慢查询
+- 未使用 `select` 限制字段
+- 大数据集未分页
+
+### 3. Core Web Vitals 目标
+
+| 指标 | 目标 | 说明 |
+|------|------|------|
+| LCP | < 2.5s | Largest Contentful Paint |
+| INP | < 200ms | Interaction to Next Paint |
+| CLS | < 0.1 | Cumulative Layout Shift |
+| FCP | < 1.8s | First Contentful Paint |
+| TTFB | < 800ms | Time to First Byte |
+
+### 4. 输出优化建议
+
+按影响力排序，每个建议包含：预期收益 + 实施难度 + 具体代码。
+
+## 验证
+
+1. [ ] 优化前后有可量化对比
+2. [ ] 未引入功能回归
+3. [ ] Core Web Vitals 达标
diff --git a/.cursor/skills/performance-audit/references/optimization-patterns.md b/.cursor/skills/performance-audit/references/optimization-patterns.md
new file mode 100644
index 0000000..785d19b
--- /dev/null
+++ b/.cursor/skills/performance-audit/references/optimization-patterns.md
@@ -0,0 +1,87 @@
+# 性能优化模式
+
+## Vue 3 前端优化
+
+```vue
+<!-- 1. v-memo — 防止不必要的重渲染 -->
+<template>
+  <div v-memo="[item.id, item.name]">
+    {{ item.name }}
+  </div>
+</template>
+
+<!-- 2. computed — 缓存计算结果 -->
+<script setup>
+const sorted = computed(() => [...items.value].sort(compareFn))
+
+// 3. shallowRef — 大型对象避免深层响应
+const heavyData = shallowRef(null)
+
+// 4. 异步组件 — 代码分割
+const HeavyChart = defineAsyncComponent(() => import('./HeavyChart.vue'))
+
+// 5. 虚拟化 — 大列表
+import { useVirtualizer } from '@tanstack/vue-virtual'
+
+// 6. keep-alive — 页面缓存
+// <keep-alive :include="cachedViews"><router-view /></keep-alive>
+</script>
+```
+
+## Vite 构建优化
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  build: {
+    target: 'es2015',
+    minify: 'terser',
+    terserOptions: {
+      compress: { drop_console: true, drop_debugger: true },
+    },
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          'vue-vendor': ['vue', 'vue-router', 'pinia'],
+          // 仅管理端：'element-plus': ['element-plus'],
+          'echarts': ['echarts'],
+        },
+      },
+    },
+  },
+})
+```
+
+## Hyperf 后端优化
+
+```php
+// 1. 协程并发 — 并行无依赖 I/O
+$parallel = new Parallel(10);
+$parallel->add(fn() => $this->orderService->getStatistics($id));
+$parallel->add(fn() => $this->paymentService->getPayments($id));
+[$stats, $payments] = $parallel->wait();
+
+// 2. 连接池调优
+'pool' => [
+    'min_connections' => 5,
+    'max_connections' => 50,
+    'wait_timeout'    => 3.0,
+],
+
+// 3. 缓存注解
+#[Cacheable(prefix: 'user', ttl: 3600)]
+public function getById(int $id): ?User { ... }
+```
+
+## 数据库优化
+
+```sql
+-- 复合索引：遵循最左前缀原则
+CREATE INDEX idx_orders_status_created ON production_orders(status, created_at);
+
+-- 覆盖索引：避免回表
+CREATE INDEX idx_orders_cover ON production_orders(status, total_amount, paid_amount);
+
+-- 游标分页（百万级数据）
+SELECT * FROM orders WHERE id > ? ORDER BY id ASC LIMIT 20;
+```
diff --git a/.cursor/skills/redis-cache/SKILL.md b/.cursor/skills/redis-cache/SKILL.md
new file mode 100644
index 0000000..6e24caf
--- /dev/null
+++ b/.cursor/skills/redis-cache/SKILL.md
@@ -0,0 +1,67 @@
+---
+name: redis-cache
+version: 3.0.0
+description: "为 Hyperf/Swoole 应用设计 Redis 缓存策略。当需要缓存、限流或 Session 存储时使用。涵盖 TTL 设计、缓存失效和高并发模式。"
+---
+
+# 🔴 Redis Cache (Hyperf + Swoole)
+
+## 触发条件
+
+用户需要为应用添加缓存层、会话存储、限流计数器或消息队列。
+
+## Phase 0：场景确认
+
+| 场景 | 数据结构 | 说明 |
+|------|---------|------|
+| API 响应 | STRING | key-value + TTL |
+| Session/Token | HASH | 多字段 |
+| 排行榜 | ZSET | 范围查询 |
+| 限流 | ZSET 滑动窗口 | 精准窗口 |
+| 标签/权限 | SET | 集合运算 |
+| 消息队列 | LIST/STREAM | FIFO |
+| 分布式锁 | STRING + SET NX | 原子性 |
+| WebSocket | HASH | fd→userId |
+
+## Phase 1：连接配置
+
+`config/autoload/redis.php`：default 与 cache 独立连接池，环境变量 REDIS_HOST/PORT/AUTH/DB/CACHE_DB。
+
+## Phase 2：缓存策略
+
+Cache-Aside：`withCache($key, $ttl, $fetcher)`，fetcher 内查 DB，setex 加 jitter。invalidate/invalidatePattern。
+
+CachedRepository：装饰器包装 Repository，getById/getPageList 走缓存，写后 invalidateAll。读写比 > 10:1 用装饰器，< 10:1 用 Service 内 CacheService，热点数据用 Redis 原生。完整实现见 **Tier 3**。
+
+## Phase 3：TTL 与 Key 规范
+
+Profile 30m、列表 5m、配置 1h、JWT 2h、Session 24h。Key 格式：`namespace:entity:id:field`。
+
+## Phase 4：分布式锁
+
+withLock($lockKey, $ttlMs, $fn)，SET NX PX，释放用 Lua 原子校验 value 后 DEL。
+
+## Phase 5：穿透/击穿防护
+
+穿透：空值缓存 NULL_PLACEHOLDER。击穿：热点 key 用 withLock 互斥 + double-check。
+
+## Phase 6：监控
+
+cache hit/miss 计数，redis-cli INFO stats。
+
+## 验证
+
+1. [ ] 连接使用环境变量
+2. [ ] Key 命名规范
+3. [ ] 所有 Key 有 TTL
+4. [ ] 失效与更新逻辑同步
+5. [ ] 锁用 Lua 原子释放
+6. [ ] 使用连接池
+7. [ ] 百万级有穿透/击穿防护
+8. [ ] CachedRepository 写后 invalidateAll
+
+## Tier 3 深度参考
+
+| 文件 | 内容 |
+|------|------|
+| `references/cache-implementation.md` | 连接、Cache-Aside、CachedRepository、TTL、锁、穿透/击穿完整代码 |
diff --git a/.cursor/skills/redis-cache/references/cache-implementation.md b/.cursor/skills/redis-cache/references/cache-implementation.md
new file mode 100644
index 0000000..1b25f66
--- /dev/null
+++ b/.cursor/skills/redis-cache/references/cache-implementation.md
@@ -0,0 +1,41 @@
+# Redis Cache — 实现细节
+
+> 主流程见 SKILL.md，本文档为连接、Cache-Aside、CachedRepository、TTL、分布式锁、穿透/击穿防护的完整代码。
+
+## 连接配置
+
+```php
+// config/autoload/redis.php
+return [
+    'default' => ['host' => env('REDIS_HOST'), 'auth' => env('REDIS_AUTH'), 'port' => (int) env('REDIS_PORT', 6379), 'db' => (int) env('REDIS_DB', 0), 'pool' => ['min_connections' => 5, 'max_connections' => 30, ...]],
+    'cache' => ['db' => (int) env('REDIS_CACHE_DB', 1), 'pool' => [...]]  // 独立连接池
+];
+```
+
+## Cache-Aside 模式
+
+CacheService：`withCache($key, $ttl, $fetcher)` — get 命中则返回，否则 fetcher() 后 setex，TTL 加 jitter 防 stampede。`invalidate($keys)`、`invalidatePattern($pattern)` 用 scan 分批 del。
+
+## CachedRepository 装饰器
+
+实现 RepositoryInterface，包装 baseRepo。getById/getPageList 用 withCache，key 格式 `{entity}:{id}` 和 `{entity}:list:{params_hash}`。invalidateDetail/invalidateList/invalidateAll。DI 注册时用 closure 返回 new CachedRepository(baseRepo, cacheService, 'order', detailTtl, listTtl)。Service 写操作后判断 `$repository instanceof CachedRepository` 则 invalidateAll。
+
+## TTL 规范
+
+Profile 30m、列表 5m、配置 1h、JWT 2h、Session 24h、限流与窗口对齐、验证码 5m、锁 任务时长+30s。
+
+## Key 命名
+
+`<namespace>:<entity>:<id>:<field>`，如 user:profile:123、orders:list:page:1、rate:limit:ip:api、session:user:456、lock:order:789、ws:connection:fd:100。
+
+## 分布式锁
+
+RedisLockService：withLock($lockKey, $ttlMs, $fn)。SET NX PX。释放用 Lua 脚本原子校验 value 后 DEL。
+
+## 缓存穿透/击穿
+
+穿透：不存在 key 缓存 NULL_PLACEHOLDER（TTL 30s）。击穿：热点 key 用 withLock 互斥，double-check 后 fetcher 再 setex。
+
+## 装饰器 vs 直接缓存 决策
+
+读写比 > 10:1 → CachedRepository。读写比 < 10:1 → Service 内 CacheService。热点数据（排行榜）→ Redis 原生 ZSET/INCR。
diff --git a/.cursor/skills/refactoring/SKILL.md b/.cursor/skills/refactoring/SKILL.md
new file mode 100644
index 0000000..5191323
--- /dev/null
+++ b/.cursor/skills/refactoring/SKILL.md
@@ -0,0 +1,73 @@
+---
+name: refactoring
+version: 1.1.0
+description: "基于测试保障的安全重构工作流，行为不变前提下改善代码结构。当需要重构、清理代码或消除技术债时使用。"
+requires: [vue-testing]
+---
+
+> ⚠️ 核心执行流程已在 `.cursor/rules/033-refactoring.mdc` 中由 Cursor 自动注入。
+> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
+
+# Refactoring Workflow
+
+## 触发条件
+
+用户要求重构代码、清理技术债、优化代码结构或简化复杂逻辑。
+
+## 核心原则
+
+**重构 = 不改变外部行为的前提下改善内部结构**
+
+- 每一步都要小到"显然正确"
+- 每一步之后测试必须全部通过
+- 如果测试不足，先补测试再重构
+
+## 执行流程
+
+### 1. 评估现状
+
+1. 读取目标代码，识别"代码坏味道"
+2. 运行现有测试确认基线：`npm test -- --related`
+3. 如果测试覆盖不足，**先补充测试**
+
+### 2. 制定重构计划
+
+常见重构模式：
+
+| 坏味道 | 重构手法 | 风险 |
+|--------|---------|------|
+| 函数过长（>50行） | Extract Function | 低 |
+| 重复代码 | Extract + Consolidate | 低 |
+| 过长参数列表 | Introduce Parameter Object | 低 |
+| Switch/If 过多 | Replace with Polymorphism | 中 |
+| 大类 | Extract Class | 中 |
+| Feature Envy | Move Method | 中 |
+| 深层嵌套 | Replace Nested with Guard Clauses | 低 |
+
+### 3. 小步执行
+
+对每一步：
+1. 做一个**原子级**的重构变更
+2. 运行测试 → 全部通过
+3. Git commit（可选，但建议频繁提交）
+4. 继续下一步
+
+### 4. 验证
+
+1. 运行完整测试套件
+2. ESLint 无报错
+3. 功能行为未改变
+
+## 禁止事项
+
+- ❌ 不要在重构中同时添加新功能
+- ❌ 不要一次改太多（改完跑不了测试）
+- ❌ 不要在没有测试的情况下重构核心逻辑
+- ❌ 不要重构正在被其他人修改的代码
+
+## 验证
+
+1. [ ] 所有测试通过
+2. [ ] ESLint 无报错
+3. [ ] 外部行为未改变
+4. [ ] 代码可读性提升（主观判断）
diff --git a/.cursor/skills/security-audit/SKILL.md b/.cursor/skills/security-audit/SKILL.md
new file mode 100644
index 0000000..53e670f
--- /dev/null
+++ b/.cursor/skills/security-audit/SKILL.md
@@ -0,0 +1,81 @@
+---
+name: security-audit
+version: 3.0.0
+description: "遵循 OWASP Top 10 对 PHP Hyperf + Vue 3 应用进行安全审查和加固。当需要安全扫描、漏洞检测或安全加固时使用。"
+---
+
+> ⚠️ 核心执行流程已在 `.cursor/rules/skill-security-audit.mdc` 中由 Cursor 自动注入。
+> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
+
+# 🔒 Security Audit (PHP Hyperf + Vue 3)
+
+## ⚠️ 安全等级：RED — 审计结果包含敏感信息
+
+## 触发条件
+
+用户要求安全审查、漏洞扫描、安全加固或合规性检查。
+
+## 执行流程
+
+### 1. 依赖安全扫描
+
+`npm audit --audit-level=high`、`composer audit`。
+
+### 2. OWASP Top 10 检查
+
+| # | 风险 | 检查方法 |
+|---|------|---------|
+| A01 | 访问控制失效 | auth middleware + 数据权限 |
+| A02 | 加密失败 | bcrypt/Argon2id、HTTPS、JWT 强度 |
+| A03 | 注入 | 参数化查询、ORM、用户输入 |
+| A04 | 不安全设计 | 业务逻辑、并发、分布式锁 |
+| A05 | 安全配置 | CORS、headers、debug 关闭 |
+| A06 | 过时组件 | npm/composer audit |
+| A07 | 认证失败 | JWT 双 Token、密码策略、登录限流 |
+| A08 | 数据完整性 | 反序列化、CI/CD |
+| A09 | 日志监控 | 覆盖率和告警 |
+| A10 | SSRF | HTTP 请求目标验证 |
+
+### 3–5. PHP / 前端 / 密钥扫描
+
+PHPStan、危险函数（eval/exec/system 等）、反序列化、文件包含、SQL 拼接。前端 v-html、eval、innerHTML、localStorage Token、target=_blank 无 noopener。密钥格式：AWS/GitHub/Stripe/Google/JWT/私钥/连接串。完整命令见 **Tier 3**。
+
+### 6. 安全头与 CORS
+
+CSP、HSTS、X-Content-Type-Options、X-Frame-Options、X-XSS-Protection、Referrer-Policy。CORS 必须在中间件集中配置，生产无 Allow-Origin: *。
+
+### 6.5–6.7. CodeGuard 增强
+
+密码哈希 Argon2id、IDOR、Mass Assignment、Session Cookie、禁用算法、文件上传、SSRF。完整检查与示例见 **Tier 3**。
+
+### 7. 中间件链验证
+
+CorsMiddleware → TraceId → RequestLog → Auth → Permission → RateLimit → RequestSign。
+
+### 8. 输出报告
+
+Critical/High/Medium/Low 分级。
+
+## 验证
+
+1. [ ] OWASP Top 10 逐项完成
+2. [ ] npm/composer audit 无 critical/high
+3. [ ] PHPStan 无错误
+4. [ ] 无硬编码密钥
+5. [ ] 安全头已配置
+6. [ ] 中间件链完整
+7. [ ] 无危险函数
+8. [ ] 无 IDOR、Mass Assignment
+9. [ ] 无禁用算法，密码 Argon2id
+10. [ ] Session Cookie Secure+HttpOnly+SameSite
+11. [ ] 文件上传 UUID + magic bytes
+12. [ ] 外部请求有白名单
+13. [ ] CORS 集中配置
+
+## Tier 3 深度参考
+
+| 文件 | 内容 |
+|------|------|
+| `references/audit-commands.md` | PHP/前端/密钥/CodeGuard 完整检查命令与最佳实践 |
+| `references/codeguard/*` | CodeGuard 各维度详细策略 |
+| `references/security-headers.md` | Nginx 安全响应头 |
diff --git a/.cursor/skills/security-audit/references/audit-commands.md b/.cursor/skills/security-audit/references/audit-commands.md
new file mode 100644
index 0000000..28419b1
--- /dev/null
+++ b/.cursor/skills/security-audit/references/audit-commands.md
@@ -0,0 +1,56 @@
+# Security Audit — 检查命令与代码示例
+
+> 主流程见 SKILL.md，本文档为 PHP/前端/密钥/CodeGuard 的完整检查命令和最佳实践。
+
+## 依赖扫描
+
+```bash
+npm audit --audit-level=high
+composer audit
+```
+
+## PHP 检查命令
+
+```bash
+vendor/bin/phpstan analyse --level=max
+rg -n "eval\(|exec\(|system\(|passthru\(|shell_exec\(|popen\(" --type php --glob '!vendor/**'
+rg -n "unserialize\(" --type php --glob '!vendor/**'
+rg -n "include\s*\\\$|require\s*\\\$" --type php --glob '!vendor/**'
+rg -n "Db::raw\(|DB::select\(.*\\\$" --type php --glob '!vendor/**'
+```
+
+## 前端检查命令
+
+```bash
+rg -n "v-html" --glob '*.vue' --glob '*.ts'
+rg -n "eval\(|new Function\(" --glob '*.ts' --glob '!node_modules/**'
+rg -n "\.innerHTML\s*=|\.outerHTML\s*=" --glob '*.vue' --glob '!node_modules/**'
+rg -n "localStorage\.(set|get)Item.*[Tt]oken" --glob '*.ts' --glob '!node_modules/**'
+rg -n "target=\"_blank\"" --glob '*.vue' | rg -v "noopener"
+```
+
+## 密钥扫描命令
+
+```bash
+# 通用、AWS、GitHub、Stripe、Google、JWT、私钥、数据库连接串
+rg -rn "(?i)(api.?key|secret|password|token)\s*[=:]\s*['\"][a-zA-Z0-9]{8,}" --glob '!vendor/**' --glob '!node_modules/**'
+rg -rn "A(KIA|GPA|IDA|ROA)[0-9A-Z]{16}" ...
+rg -rn "gh[pousr]_[a-zA-Z0-9]{36}" ...
+rg -rn "sk_live_|pk_live_|sk_test_[a-zA-Z0-9]{24}" ...
+rg -rn "AIza[a-zA-Z0-9_\-]{35}" ...
+rg -rn "eyJ[a-zA-Z0-9_\-]+\.[a-zA-Z0-9_\-]+\.[a-zA-Z0-9_\-]+" ...
+rg -rn "BEGIN\s+(RSA\s+)?PRIVATE\s+KEY" ...
+rg -rn "(mysql|mongodb|redis|postgres)://[^:]+:[^@]+" ...
+```
+
+## CORS 集中配置
+
+❌ Controller 内单独设置 Allow-Origin: *。✅ CorsMiddleware 集中配置，env('CORS_ORIGIN')，Allow-Credentials 与 Allow-Origin: * 不共存。
+
+## 密码哈希
+
+❌ md5/sha1、PASSWORD_BCRYPT 无 cost。✅ PASSWORD_ARGON2ID（memory_cost 65536, time_cost 4）或 PASSWORD_BCRYPT cost=12。验证用 password_verify，升级用 password_needs_rehash。
+
+## CodeGuard 增强
+
+IDOR：find/findOrFail($request/$id) 未附加所有权 → 应 $user->orders()->findOrFail($id)。Mass Assignment：fill($request->all())、create/update($request->all())。Session：setcookie 需 Secure+HttpOnly+SameSite。禁用算法：md5/sha1、AES-ECB。文件上传：不用 getClientFilename() 原始名，用 UUID；MIME 用 finfo magic bytes。SSRF：Guzzle/curl 对用户 URL 需域名白名单。
diff --git a/.cursor/skills/security-audit/references/codeguard/codeguard-0-api-web-services.md b/.cursor/skills/security-audit/references/codeguard/codeguard-0-api-web-services.md
new file mode 100644
index 0000000..45c1016
--- /dev/null
+++ b/.cursor/skills/security-audit/references/codeguard/codeguard-0-api-web-services.md
@@ -0,0 +1,82 @@
+---
+description: API & Web services security (REST/GraphQL/SOAP), schema validation, authn/z, SSRF
+languages:
+- c
+- go
+- java
+- typescript
+- php
+- python
+- ruby
+- xml
+- yaml
+alwaysApply: false
+---
+
+rule_id: codeguard-0-api-web-services
+
+## API & Web Services Security
+
+Secure REST, GraphQL, and SOAP/WS services end‑to‑end: transport, authn/z, schema validation, SSRF controls, DoS limits, and microservice‑safe patterns.
+
+### Transport and TLS
+- HTTPS only; consider mTLS for high‑value/internal services. Validate certs (CN/SAN, revocation) and prevent mixed content.
+
+### Authentication and Tokens
+- Use standard flows (OAuth2/OIDC) for clients; avoid custom schemes. For services, use mTLS or signed service tokens.
+- JWTs: pin algorithms; validate iss/aud/exp/nbf; short lifetimes; rotation; denylist on logout/revoke. Prefer opaque tokens when revocation is required and central store is available.
+- API keys: scope narrowly; rate limit; monitor usage; do not use alone for sensitive operations.
+
+### Authorization
+- Enforce per‑endpoint, per‑resource checks server‑side; deny by default.
+- For microservices, authorize at gateway (coarse) and service (fine) layers; propagate signed internal identity, not external tokens.
+
+### Input and Content Handling
+- Validate inputs via contracts: OpenAPI/JSON Schema, GraphQL SDL, XSD. Reject unknown fields and oversize payloads; set limits.
+- Content types: enforce explicit Content‑Type/Accept; reject unsupported combinations. Harden XML parsers against XXE/expansion.
+
+### SQL/Injection Safety in Resolvers and Handlers
+- Use parameterized queries/ORM bind parameters; never concatenate user input into queries or commands.
+
+### GraphQL‑Specific Controls
+- Limit query depth and overall complexity; enforce pagination; timeouts on execution; disable introspection and IDEs in production.
+- Implement field/object‑level authorization to prevent IDOR/BOLA; validate batching and rate limit per object type.
+
+### SSRF Prevention for Outbound Calls
+- Do not accept raw URLs. Validate domains/IPs using libraries; restrict to HTTP/HTTPS only (block file://, gopher://, ftp://, etc.).
+- Case 1 (fixed partners): strict allow‑lists; disable redirects; network egress allow‑lists.
+- Case 2 (arbitrary): block private/link‑local/localhost ranges; resolve and verify all IPs are public; require signed tokens from the target where feasible.
+
+### SOAP/WS and XML Safety
+- Validate SOAP payloads with XSD; limit message sizes; enable XML signatures/encryption where required.
+- Configure parsers against XXE, entity expansion, and recursive payloads; scan attachments.
+
+### Rate Limiting and DoS
+- Apply per‑IP/user/client limits, circuit breakers, and timeouts. Use server‑side batching and caching to reduce load.
+
+### Management Endpoints
+- Do not expose over the Internet. Require strong auth (MFA), network restrictions, and separate ports/hosts.
+
+### Testing and Assessment
+- Maintain formal API definitions; drive contract tests and fuzzing from specs.
+- Assess endpoints for authn/z bypass, SSRF, injection, and information leakage; log token validation failures.
+
+### Microservices Practices
+- Policy‑as‑code with embedded decision points; sidecar or library PDPs.
+- Service identity via mTLS or signed tokens; never reuse external tokens internally.
+- Centralized structured logging with correlation IDs; sanitize sensitive data.
+
+### Implementation Checklist
+- HTTPS/mTLS configured; certs managed; no mixed content.
+- Contract validation at the edge and service; unknown fields rejected; size/time limits enforced.
+- Strong authn/z per endpoint; GraphQL limits applied; introspection disabled in prod.
+- SSRF protections at app and network layers; redirects disabled; allow‑lists where possible.
+- Rate limiting, circuit breakers, and resilient patterns in place.
+- Management endpoints isolated and strongly authenticated.
+- Logs structured and privacy‑safe with correlation IDs.
+
+### Test Plan
+- Contract tests for schema adherence; fuzzing with schema‑aware tools.
+- Pen tests for SSRF, IDOR/BOLA, and authz bypass; performance tests for DoS limits.
+- Test all HTTP methods per endpoint; discover parameters in URL paths, headers, and structured data beyond obvious query strings.
+- Automated checks for token validation and revocation behavior.
diff --git a/.cursor/skills/security-audit/references/codeguard/codeguard-0-authentication-mfa.md b/.cursor/skills/security-audit/references/codeguard/codeguard-0-authentication-mfa.md
new file mode 100644
index 0000000..d3d3f9f
--- /dev/null
+++ b/.cursor/skills/security-audit/references/codeguard/codeguard-0-authentication-mfa.md
@@ -0,0 +1,103 @@
+---
+description: Authentication and MFA best practices (passwords, MFA, OAuth/OIDC, SAML, recovery, tokens)
+languages:
+- c
+- go
+- java
+- typescript
+- kotlin
+- matlab
+- php
+- python
+- ruby
+- swift
+alwaysApply: false
+---
+
+rule_id: codeguard-0-authentication-mfa
+
+## Authentication & MFA
+
+Build a resilient, user-friendly authentication system that resists credential attacks, protects secrets, and supports strong, phishing-resistant MFA and secure recovery.
+
+### Account Identifiers and UX
+- Use non-public, random, and unique internal user identifiers. Allow login via verified email or username.
+- Always return generic error messages (e.g., "Invalid username or password"). Keep timing consistent to prevent account enumeration.
+- Support password managers: `<input type="password">`, allow paste, no JS blocks.
+
+### Password Policy
+- Accept passphrases and full Unicode; minimum 8 characters; avoid composition rules. Set only a reasonable maximum length (64+).
+- Check new passwords against breach corpora (e.g., k‑anonymity APIs); reject breached/common passwords.
+
+### Password Storage (Hashing)
+- Hash, do not encrypt. Use slow, memory‑hard algorithms with unique per‑user salts and constant‑time comparison.
+- Preferred order and parameters (tune to your hardware; target <1s on server):
+  - Argon2id: m=19–46 MiB, t=2–1, p=1 (or equivalent security trade‑offs)
+  - scrypt: N=2^17, r=8, p=1 (or equivalent)
+  - bcrypt (legacy only): cost ≥10, be aware of 72‑byte input limit
+  - PBKDF2 (FIPS): PBKDF2‑HMAC‑SHA‑256 ≥600k, or SHA‑1 ≥1.3M
+- Optional pepper: store outside DB (KMS/HSM); if used, apply via HMAC or pre‑hashing. Plan for user resets if pepper rotates.
+- Unicode and null bytes must be supported end‑to‑end by the library.
+
+### Authentication Flow Hardening
+- Enforce TLS for all auth endpoints and token transport; enable HSTS.
+- Implement rate limits per IP, account, and globally; add proof‑of‑work or CAPTCHA only as last resort.
+- Lockouts/throttling: progressive backoff; avoid permanent lockout via resets/alerts.
+- Uniform responses and code paths to reduce oracle/timing signals.
+
+### Multi‑Factor Authentication (MFA)
+- Adopt phishing‑resistant factors by default for sensitive accounts: passkeys/WebAuthn (FIDO2) or hardware U2F.
+- Acceptable: TOTP (app‑based), smart cards with PIN. Avoid for sensitive use: SMS/voice, email codes; never rely on security questions.
+- Require MFA for: login, password/email changes, disabling MFA, privilege elevation, high‑value transactions, new devices/locations.
+- Risk‑based MFA signals: new device, geo‑velocity, IP reputation, unusual time, breached credentials.
+- MFA recovery: provide single‑use backup codes, encourage multiple factors, and require strong identity verification for resets.
+- Handle failed MFA: offer alternative enrolled methods, notify users of failures, and log context (no secrets).
+
+### Federation and Protocols (OAuth 2.0 / OIDC / SAML)
+- Use standard protocols only; do not build your own.
+- OAuth 2.0/OIDC:
+  - Prefer Authorization Code with PKCE for public/native apps; avoid Implicit and ROPC.
+  - Validate state and nonce; use exact redirect URI matching; prevent open redirects.
+  - Constrain tokens to audience/scope; use DPoP or mTLS for sender‑constraining when possible.
+  - Rotate refresh tokens; revoke on logout or risk signals.
+- SAML:
+  - TLS 1.2+; sign responses/assertions; encrypt sensitive assertions.
+  - Validate issuers, InResponseTo, timestamps (NotBefore/NotOnOrAfter), Recipient; verify against trusted keys.
+  - Prevent XML signature wrapping with strict schema validation and hardened XPath selection.
+  - Keep response lifetimes short; prefer SP‑initiated flows; validate RelayState; implement replay detection.
+
+### Tokens (JWT and Opaque)
+- Prefer opaque server‑managed tokens for simplicity and revocation. If using JWTs:
+  - Explicitly pin algorithms; reject "none"; validate iss/aud/exp/iat/nbf; use short lifetimes and rotation.
+  - Store secrets/keys securely (KMS/HSM). Use strong HMAC secrets or asymmetric keys; never hardcode.
+  - Consider binding tokens to a client context (e.g., fingerprint hash in cookie) to reduce replay.
+  - Implement denylist/allowlist for revocation on logout and critical events.
+
+### Recovery and Reset
+- Return the same response for existing and non‑existing accounts (no enumeration). Normalize timing.
+- Generate 32+ byte, CSPRNG tokens; single‑use; store as hashes; short expiry.
+- Use HTTPS reset links to pinned, trusted domains; add referrer policy (no‑referrer) on UI.
+- After reset: require re‑authentication, rotate sessions, and do not auto‑login.
+- Never lock accounts due to reset attempts; rate‑limit and monitor instead.
+
+### Administrative and Internal Accounts
+- Separate admin login from public forms; enforce stronger MFA, device posture checks, IP allowlists, and step‑up auth.
+- Use distinct session contexts and stricter timeouts for admin operations.
+
+### Monitoring and Signals
+- Log auth events (failures/successes, MFA enroll/verify, resets, lockouts) with stable fields and correlation IDs; never log secrets or raw tokens.
+- Detect credential stuffing: high failure rates, many IPs/agents, impossible travel. Notify users of new device logins.
+
+### Implementation Checklist
+- Passwords: Argon2id (preferred) with per‑user salt, constant‑time verify; breached password checks on change/set.
+- MFA: WebAuthn/passkeys or hardware tokens for high‑risk; TOTP as fallback; secure recovery with backup codes.
+- Federation: Authorization Code + PKCE; strict redirect URI validation; audience/scope enforced; token rotation.
+- Tokens: short‑lived, sender‑constrained where possible; revocation implemented; secrets in KMS/HSM.
+- Recovery: single‑use, hashed, time‑boxed tokens; consistent responses; re‑auth required after reset; sessions rotated.
+- Abuse: rate limits, throttling, and anomaly detection on auth endpoints; uniform error handling.
+- Admin: isolated flows with stricter policies and device checks.
+
+### Test Plan
+- Unit/integration tests for login, MFA enroll/verify, resets, and lockouts with uniform errors.
+- Protocol tests: PKCE, state/nonce, redirect URI validation, token audience/scope.
+- Dynamic tests for credential stuffing resistance and token replay; validate revocation after logout and role change.
diff --git a/.cursor/skills/security-audit/references/codeguard/codeguard-0-authorization-access-control.md b/.cursor/skills/security-audit/references/codeguard/codeguard-0-authorization-access-control.md
new file mode 100644
index 0000000..e38518f
--- /dev/null
+++ b/.cursor/skills/security-audit/references/codeguard/codeguard-0-authorization-access-control.md
@@ -0,0 +1,59 @@
+---
+description: Authorization and access control (RBAC/ABAC/ReBAC, IDOR, mass assignment, transaction auth)
+languages:
+- c
+- go
+- java
+- typescript
+- php
+- python
+- ruby
+- yaml
+alwaysApply: false
+---
+
+rule_id: codeguard-0-authorization-access-control
+
+## Authorization & Access Control
+
+Enforce least privilege and precise access decisions for every request and resource, prevent IDOR and mass assignment, and provide strong transaction authorization where necessary.
+
+### Core Principles
+1.  Deny by Default: The default for any access request should be 'deny'. Explicitly grant permissions to roles or users rather than explicitly denying them. When no allow rule matches, return HTTP 403 Forbidden.
+2.  Principle of Least Privilege: Grant users the minimum level of access required to perform their job functions. Regularly audit permissions to ensure they are not excessive.
+3.  Validate Permissions on Every Request: Check authorization for every single request, regardless of source (AJAX, API, direct). Use middleware/filters to ensure consistent enforcement.
+4.  Prefer ABAC/ReBAC over RBAC: Use Attribute-Based Access Control (ABAC) or Relationship-Based Access Control (ReBAC) for fine-grained permissions instead of simple role-based access control.
+
+### Systemic Controls
+- Centralize authorization at service boundaries via middleware/policies/filters.
+- Model permissions at the resource level (ownership/tenancy) and enforce scoping in data queries.
+- Return generic 403/404 responses to avoid leaking resource existence.
+- Log all denials with user, action, resource identifier (non-PII), and rationale code.
+
+### Preventing IDOR
+- Never trust user-supplied identifiers alone. Always verify access to each object instance.
+- Resolve resources through user-scoped queries or server-side lookups. Example: `currentUser.projects.find(id)` instead of `Project.find(id)`.
+- Use non-enumerable identifiers (UUIDs/random) as defense-in-depth. Do not rely on obscurity alone.
+
+### Preventing Mass Assignment
+- Do not bind request bodies directly to domain objects containing sensitive fields.
+- Expose only safe, editable fields via DTOs. Maintain explicit allow-lists for patch/update.
+- Use framework features to block-list sensitive fields if allow-listing is infeasible.
+
+### Transaction Authorization (Step-Up)
+- Require a second factor for sensitive actions (wire transfers, privilege elevation, data export). Apply What‑You‑See‑Is‑What‑You‑Sign: show critical fields for user confirmation.
+- Use unique, time‑limited authorization credentials per transaction; reject on data changes mid‑flow.
+- Enforce the chosen authorization method server-side; prevent client‑side downgrades.
+- Protect against brute-force with throttling and complete flow restarts after failures.
+
+### Testing and Automation
+- Maintain an authorization matrix (YAML/JSON) listing endpoints/resources, roles/attributes, and expected outcomes.
+- Automate integration tests that iterate the matrix, mint role tokens, and assert allow/deny results—including token expiry/revocation cases.
+- Exercise negative tests: swapped IDs, downgraded roles, missing scopes, and bypass attempts.
+
+### Implementation Checklist
+- Middleware/policies enforce deny-by-default and resource checks on every endpoint.
+- Query scoping ensures users only access permitted rows/objects.
+- DTOs and allow-lists prevent mass assignment; sensitive fields never bindable.
+- Step-up authorization in place for sensitive operations with unique, short-lived credentials.
+- Authorization matrix drives CI tests; failures block merges.
diff --git a/.cursor/skills/security-audit/references/codeguard/codeguard-0-client-side-web-security.md b/.cursor/skills/security-audit/references/codeguard/codeguard-0-client-side-web-security.md
new file mode 100644
index 0000000..b2b9843
--- /dev/null
+++ b/.cursor/skills/security-audit/references/codeguard/codeguard-0-client-side-web-security.md
@@ -0,0 +1,111 @@
+---
+description: Client-side web security (XSS/DOM XSS, CSP, CSRF, clickjacking, XS-Leaks, third-party JS)
+languages:
+- c
+- html
+- typescript
+- php
+- vlang
+alwaysApply: false
+---
+
+rule_id: codeguard-0-client-side-web-security
+
+## Client‑side Web Security
+
+Protect browser clients against code injection, request forgery, UI redress, cross‑site leaks, and unsafe third‑party scripts with layered, context‑aware controls.
+
+### XSS Prevention (Context‑Aware)
+- HTML context: prefer `textContent`. If HTML is required, sanitize with a vetted library (e.g., DOMPurify) and strict allow‑lists.
+- Attribute context: always quote attributes and encode values.
+- TypeScript context: do not build JS from untrusted strings; avoid inline event handlers; use `addEventListener`.
+- URL context: validate protocol/domain and encode; block `typescript:` and data URLs where inappropriate.
+- Redirects/forwards: never use user input directly for destinations; use server-side mapping (ID→URL) or validate against trusted domain allowlists.
+- CSS context: allow‑list values; never inject raw style text from users.
+
+Example sanitization:
+```typescript
+const clean = DOMPurify.sanitize(userHtml, {
+  ALLOWED_TAGS: ['b','i','p','a','ul','li'],
+  ALLOWED_ATTR: ['href','target','rel'],
+  ALLOW_DATA_ATTR: false
+});
+```
+
+### DOM‑based XSS and Dangerous Sinks
+- Prohibit `innerHTML`, `outerHTML`, `document.write` with untrusted data.
+- Prohibit `eval`, `new Function`, string‑based `setTimeout/Interval`.
+- Validate and encode data before assigning to `location` or event handler properties.
+- Use strict mode and explicit variable declarations to prevent global namespace pollution from DOM clobbering.
+- Adopt Trusted Types and enforce strict CSP to prevent DOM sinks exploitation.
+
+Trusted Types + CSP:
+```http
+Content-Security-Policy: script-src 'self' 'nonce-{random}'; object-src 'none'; base-uri 'self'; require-trusted-types-for 'script'
+```
+
+### Content Security Policy (CSP)
+- Prefer nonce‑based or hash‑based CSP over domain allow‑lists.
+- Start with Report‑Only mode; collect violations; then enforce.
+- Baseline to aim for: `default-src 'self'; style-src 'self' 'unsafe-inline'; frame-ancestors 'self'; form-action 'self'; object-src 'none'; base-uri 'none'; upgrade-insecure-requests`.
+
+### CSRF Defense
+- Fix XSS first; then layer CSRF defenses.
+- Use framework‑native CSRF protections and synchronizer tokens on all state‑changing requests.
+- Cookie settings: `SameSite=Lax` or `Strict`; sessions `Secure` and `HttpOnly`; use `__Host-` prefix when possible.
+- Validate Origin/Referer; require custom headers for API mutations in SPA token models.
+- Never use GET for state changes; validate tokens on POST/PUT/DELETE/PATCH only. Enforce HTTPS for all token transmission.
+
+### Clickjacking Defense
+- Primary: `Content-Security-Policy: frame-ancestors 'none'` or a specific allow‑list.
+- Fallback for legacy browsers: `X-Frame-Options: DENY` or `SAMEORIGIN`.
+- Consider UX confirmations for sensitive actions when framing is required.
+
+### Cross‑Site Leaks (XS‑Leaks) Controls
+- Use `SameSite` cookies appropriately; prefer `Strict` for sensitive actions.
+- Adopt Fetch Metadata protections to block suspicious cross‑site requests.
+- Isolate browsing contexts: COOP/COEP and CORP where applicable.
+- Disable caching and add user‑unique tokens for sensitive responses to prevent cache probing.
+
+### Third‑Party TypeScript
+- Minimize and isolate: prefer sandboxed iframes with `sandbox` and postMessage origin checks.
+- Use Subresource Integrity (SRI) for external scripts and monitor for changes.
+- Provide a first‑party, sanitized data layer; deny direct DOM access from tags where possible.
+- Govern via tag manager controls and vendor contracts; keep libraries updated.
+
+SRI example:
+```html
+<script src="https://cdn.vendor.com/app.ts"
+  integrity="sha384-..." crossorigin="anonymous"></script>
+```
+
+### HTML5, CORS, WebSockets, Storage
+- postMessage: always specify exact target origin; verify `event.origin` on receive.
+- CORS: avoid `*`; allow‑list origins; validate preflights; do not rely on CORS for authz.
+- WebSockets: require `wss://`, origin checks, auth, message size limits, and safe JSON parsing.
+- Client storage: never store secrets in `localStorage`/`sessionStorage`; prefer HttpOnly cookies; if unavoidable, isolate via Web Workers.
+- Links: add `rel="noopener noreferrer"` to external `target=_blank` links.
+
+### HTTP Security Headers (Client Impact)
+- HSTS: enforce HTTPS everywhere.
+- X‑Content‑Type‑Options: `nosniff`.
+- Referrer‑Policy and Permissions‑Policy: restrict sensitive signals and capabilities.
+
+### AJAX and Safe DOM APIs
+- Avoid dynamic code execution; use function callbacks, not strings.
+- Build JSON with `JSON.stringify`; never via string concatenation.
+- Prefer creating elements and setting `textContent`/safe attributes over raw HTML insertion.
+
+### Implementation Checklist
+- Contextual encoding/sanitization for every sink; no dangerous APIs without guards.
+- Strict CSP with nonces and Trusted Types; violations monitored.
+- CSRF tokens on all state‑changing requests; secure cookie attributes.
+- Frame protections set; XS‑Leak mitigations enabled (Fetch Metadata, COOP/COEP/CORP).
+- Third‑party JS isolated with SRI and sandbox; vetted data layer only.
+- HTML5/CORS/WebSocket usage hardened; no secrets in web storage.
+- Security headers enabled and validated.
+
+### Test Plan
+- Automated checks for dangerous DOM/API patterns.
+- E2E tests for CSRF and clickjacking; CSP report monitoring.
+- Manual probes for XS‑Leaks (frame count, timing, cache) and open redirect behavior.
diff --git a/.cursor/skills/security-audit/references/codeguard/codeguard-0-file-handling-and-uploads.md b/.cursor/skills/security-audit/references/codeguard/codeguard-0-file-handling-and-uploads.md
new file mode 100644
index 0000000..8e0b6ef
--- /dev/null
+++ b/.cursor/skills/security-audit/references/codeguard/codeguard-0-file-handling-and-uploads.md
@@ -0,0 +1,74 @@
+---
+description: Secure file handling & uploads (validation, storage isolation, scanning, safe delivery)
+languages:
+- c
+- go
+- java
+- typescript
+- php
+- python
+- ruby
+alwaysApply: false
+---
+
+rule_id: codeguard-0-file-handling-and-uploads
+
+## File Upload Security Guidelines
+
+This rule advises on secure file upload practices to prevent malicious file attacks and protect system integrity:
+
+- Extension Validation
+  - List allowed extensions only for business-critical functionality.
+  - Ensure input validation is applied before validating extensions.
+  - Avoid double extensions (e.g., `.jpg.php`) and null byte injection (e.g., `.php%00.jpg`).
+  - Use allowlist approach rather than denylist for file extensions.
+  - Validate extensions after decoding filename to prevent bypass attempts.
+
+- Content Type and File Signature Validation
+  - Never trust client-supplied Content-Type headers as they can be spoofed.
+  - Validate file signatures (magic numbers) in conjunction with Content-Type checking.
+  - Implement allowlist approach for MIME types as a quick protection layer.
+  - Use file signature validation but not as a standalone security measure.
+
+- Filename Security
+  - Generate random filenames (UUID/GUID) instead of using user-supplied names.
+  - If user filenames required, implement maximum length limits.
+  - Restrict characters to alphanumeric, hyphens, spaces, and periods only.
+  - Prevent leading periods (hidden files) and sequential periods (directory traversal).
+  - Avoid leading hyphens or spaces for safer shell script processing.
+
+- File Content Validation
+  - For images, apply image rewriting techniques to destroy malicious content.
+  - For Microsoft documents, use Apache POI for validation.
+  - Avoid ZIP files due to numerous attack vectors.
+  - Implement manual file review in sandboxed environments when resources allow.
+  - Integrate antivirus scanning and Content Disarm & Reconstruct (CDR) for applicable file types.
+
+- Storage Security
+  - Store files on different servers for complete segregation when possible.
+  - Store files outside webroot with administrative access only.
+  - If storing in webroot, set write-only permissions with proper access controls.
+  - Use application handlers that map IDs to filenames for public access.
+  - Consider database storage for specific use cases with DBA expertise.
+
+- Access Control and Authentication
+  - Require user authentication before allowing file uploads.
+  - Implement proper authorization levels for file access and modification.
+  - Set filesystem permissions on principle of least privilege.
+  - Scan files before execution if execution permission is required.
+
+- Upload and Download Limits
+  - Set proper file size limits for upload protection.
+  - Consider post-decompression size limits for compressed files.
+  - Implement request limits for download services to prevent DoS attacks.
+  - Use secure methods to calculate ZIP file sizes safely.
+
+- Additional Security Measures
+  - Protect file upload endpoints from CSRF attacks.
+  - Keep all file processing libraries securely configured and updated.
+  - Implement logging and monitoring for upload activities.
+  - Provide user reporting mechanisms for illegal content.
+  - Use secure extraction methods for compressed files.
+
+Summary:  
+Implement defense-in-depth for file uploads through multi-layered validation, secure storage practices, proper access controls, and comprehensive monitoring. Never rely on single validation methods and always generate safe filenames to prevent attacks.
diff --git a/.cursor/skills/security-audit/references/codeguard/codeguard-0-input-validation-injection.md b/.cursor/skills/security-audit/references/codeguard/codeguard-0-input-validation-injection.md
new file mode 100644
index 0000000..ed34b5e
--- /dev/null
+++ b/.cursor/skills/security-audit/references/codeguard/codeguard-0-input-validation-injection.md
@@ -0,0 +1,107 @@
+---
+description: Input validation and injection defense (SQL/SOQL/LDAP/OS), parameterization, prototype pollution
+languages:
+- apex
+- c
+- go
+- html
+- java
+- typescript
+- php
+- powershell
+- python
+- ruby
+- shell
+- sql
+alwaysApply: false
+---
+
+rule_id: codeguard-0-input-validation-injection
+
+## Input Validation & Injection Defense
+
+Ensure untrusted input is validated and never interpreted as code. Prevent injection across SQL, LDAP, OS commands, templating, and TypeScript runtime object graphs.
+
+### Core Strategy
+- Validate early at trust boundaries with positive (allow‑list) validation and canonicalization.
+- Treat all untrusted input as data, never as code. Use safe APIs that separate code from data.
+- Parameterize queries/commands; escape only as last resort and context‑specific.
+
+### Validation Playbook
+- Syntactic validation: enforce format, type, ranges, and lengths for each field.
+- Semantic validation: enforce business rules (e.g., start ≤ end date, enum allow‑lists).
+- Normalization: canonicalize encodings before validation; validate complete strings (regex anchors ^$); beware ReDoS.
+- Free‑form text: define character class allow‑lists; normalize Unicode; set length bounds.
+- Files: validate by content type (magic), size caps, and safe extensions; server‑generate filenames; scan; store outside web root.
+
+### SQL Injection Prevention
+- Use prepared statements and parameterized queries for 100% of data access.
+- Use bind variables for any dynamic SQL construction within stored procedures and never concatenate user input into SQL.
+- Prefer least‑privilege DB users and views; never grant admin to app accounts.
+- Escaping is fragile and discouraged; parameterization is the primary defense.
+
+Example (Java PreparedStatement):
+```java
+String custname = request.getParameter("customerName");
+String query = "SELECT account_balance FROM user_data WHERE user_name = ? ";  
+PreparedStatement pstmt = connection.prepareStatement( query );
+pstmt.setString( 1, custname);
+ResultSet results = pstmt.executeQuery( );
+```
+
+### SOQL/SOSL Injection (Salesforce)
+
+SOQL and SOSL are query/search languages (no SQL-style DDL/DML). Data changes are performed via Apex DML or Database methods. Note: SOQL can lock rows via `FOR UPDATE`.
+
+- Primary risk: data exfiltration by bypassing intended query filters/business logic; impact is amplified when Apex runs with elevated access (system mode) or when CRUD/FLS aren't enforced.
+- Second-order risk (conditional): if queried records are passed to DML, injection can broaden the record set and cause unintended mass updates/deletes.
+- Prefer static SOQL/SOSL with bind variables: `[SELECT Id FROM Account WHERE Name = :userInput]` or `FIND :term`.
+- For dynamic SOQL, use `Database.queryWithBinds()`; for dynamic SOSL, use `Search.query()`. Allow‑list any dynamic identifiers. If concatenation is unavoidable, escape string values with `String.escapeSingleQuotes()`.
+- Enforce CRUD/FLS with `WITH USER_MODE` or `WITH SECURITY_ENFORCED` (don't combine both). Enforce record sharing with `with sharing` or user-mode operations. Use `Security.stripInaccessible()` before DML.
+
+### LDAP Injection Prevention
+- Always apply context‑appropriate escaping:
+  - DN escaping for `\ # + < > , ; " =` and leading/trailing spaces
+  - Filter escaping for `* ( ) \ NUL`
+- Validate inputs with allow‑lists before constructing queries; use libraries that provide DN/filter encoders.
+- Use least‑privilege LDAP connections with bind authentication; avoid anonymous binds for application queries.
+
+### OS Command Injection Defense
+- Prefer built‑in APIs instead of shelling out (e.g., library calls over `exec`).
+- If unavoidable, use structured execution that separates command and arguments (e.g., ProcessBuilder). Do not invoke shells.
+- Strictly allow‑list commands and validate arguments with allow‑list regex; exclude metacharacters (& | ; $ > < ` \ ! ' " ( ) and whitespace as needed).
+- Use `--` to delimit arguments where supported to prevent option injection.
+
+Example (Java ProcessBuilder):
+```java
+ProcessBuilder pb = new ProcessBuilder("TrustedCmd", "Arg1", "Arg2");
+Map<String,String> env = pb.environment();
+pb.directory(new File("TrustedDir"));
+Process p = pb.start();
+```
+
+### Query Parameterization Guidance
+- Use the platform’s parameterization features (JDBC PreparedStatement, .NET SqlCommand, Ruby ActiveRecord bind params, PHP PDO, SQLx bind, etc.).
+- For stored procedures, ensure parameters are bound; never build dynamic SQL via string concatenation inside procedures.
+
+### Prototype Pollution (TypeScript)
+- Developers should use `new Set()` or `new Map()` instead of using object literals
+- When objects are required, create with `Object.create(null)` or `{ __proto__: null }` to avoid inherited prototypes.
+- Freeze or seal objects that should be immutable; consider Node `--disable-proto=delete` as defense‑in‑depth.
+- Avoid unsafe deep merge utilities; validate keys against allow‑lists and block `__proto__`, `constructor`, `prototype`.
+
+### Caching and Transport
+- Apply `Cache-Control: no-store` on responses containing sensitive data; enforce HTTPS across data flows.
+
+### Implementation Checklist
+- Central validators: types, ranges, lengths, enums; canonicalization before checks.
+- 100% parameterization coverage for SQL; dynamic identifiers via allow‑lists only.
+- LDAP DN/filter escaping in use; inputs validated prior to query.
+- No shell invocation for untrusted input; if unavoidable, structured exec + allow‑list + regex validation.
+- JS object graph hardened: safe constructors, blocked prototype paths, safe merge utilities.
+- File uploads validated by content, size, and extension; stored outside web root and scanned.
+
+### Test Plan
+- Static checks for string concatenation in queries/commands and dangerous DOM/merge sinks.
+- Fuzzing for SQL/LDAP/OS injection vectors; unit tests for validator edge cases.
+- Negative tests exercising blocked prototype keys and deep merge behavior.
diff --git a/.cursor/skills/security-audit/references/codeguard/codeguard-0-logging.md b/.cursor/skills/security-audit/references/codeguard/codeguard-0-logging.md
new file mode 100644
index 0000000..c79a31b
--- /dev/null
+++ b/.cursor/skills/security-audit/references/codeguard/codeguard-0-logging.md
@@ -0,0 +1,45 @@
+---
+description: Logging & monitoring (structured telemetry, redaction, integrity, detection & alerting)
+languages:
+- c
+- typescript
+- yaml
+alwaysApply: false
+---
+
+rule_id: codeguard-0-logging
+
+## Logging & Monitoring
+
+Produce structured, privacy‑aware telemetry that supports detection, response, and forensics without exposing secrets.
+
+### What to Log
+- Authn/authz events; admin actions; config changes; sensitive data access; input validation failures; security errors.
+- Include correlation/request IDs, user/session IDs (non‑PII), source IP, user agent, timestamps (UTC, RFC3339).
+
+### How to Log
+- Structured logs (JSON) with stable field names; avoid free‑form text for critical signals.
+- Sanitize all log inputs to prevent log injection (strip CR/LF/delimiters); validate data from other trust zones.
+- Redact/tokenize secrets and sensitive fields; never log credentials, tokens, recovery codes, or raw session IDs.
+- Ensure integrity: append‑only or WORM storage; tamper detection; centralized aggregation; access controls and retention policies.
+
+### Detection & Alerting
+- Build alerts for auth anomalies (credential stuffing patterns, impossible travel), privilege changes, excessive failures, SSRF indicators, and data exfil patterns.
+- Tune thresholds; provide runbooks; ensure on‑call coverage; test alert flows.
+
+### Storage & Protection
+- Isolate log storage (separate partition/database); strict file/directory permissions; store outside web‑accessible locations.
+- Synchronize time across systems; use secure protocols for transmission; implement tamper detection and monitoring.
+
+### Privacy & Compliance
+- Maintain data inventory and classification; minimize personal data in logs; honor retention and deletion policies.
+- Provide mechanisms to trace and delete user‑linked log data where required by policy.
+
+### Implementation Checklist
+- JSON logging enabled; log injection sanitization active; redaction filters active; correlation IDs on all requests.
+- Isolated log storage with tamper detection; centralized log pipeline with integrity protections; retention configured.
+- Security alerts defined and tested; dashboards and reports in place.
+
+### Validation
+- Unit/integration tests assert presence/absence of key fields; redaction unit tests.
+- Periodic audits for secret/PII leakage; tabletop exercises for incident workflows.
diff --git a/.cursor/skills/security-audit/references/codeguard/codeguard-0-session-management-and-cookies.md b/.cursor/skills/security-audit/references/codeguard/codeguard-0-session-management-and-cookies.md
new file mode 100644
index 0000000..5d90ad3
--- /dev/null
+++ b/.cursor/skills/security-audit/references/codeguard/codeguard-0-session-management-and-cookies.md
@@ -0,0 +1,78 @@
+---
+description: Session management and secure cookies (rotation, fixation, timeouts, theft detection)
+languages:
+- c
+- go
+- html
+- java
+- typescript
+- php
+- python
+- ruby
+alwaysApply: false
+---
+
+rule_id: codeguard-0-session-management-and-cookies
+
+## Session Management & Cookies
+
+Implement robust, attack-resistant session handling that prevents fixation, hijacking, and theft while maintaining usability.
+
+### Session ID Generation and Properties
+- Generate session IDs with a CSPRNG; ≥64 bits of entropy (prefer 128+). Opaque, unguessable, and free of meaning.
+- Use generic cookie names (e.g., `id`) rather than framework defaults. Reject any incoming ID not created by the server.
+- Store all session data server-side; never embed PII or privileges in the token. If sensitive, encrypt server-side session store at rest.
+
+### Cookie Security Configuration
+- Set `Secure`, `HttpOnly`, `SameSite=Strict` (or `Lax` if necessary for flows) on session cookies.
+- Scope cookies narrowly with `Path` and `Domain`. Avoid cross-subdomain exposure.
+- Prefer non-persistent session cookies (no Expires/Max-Age). Require full HTTPS; enable HSTS site-wide.
+
+Example header:
+```
+Set-Cookie: id=<opaque>; Secure; HttpOnly; SameSite=Strict; Path=/
+```
+
+### Session Lifecycle and Rotation
+- Create sessions only server-side; treat provided IDs as untrusted input.
+- Regenerate session ID on authentication, password changes, and any privilege elevation. Invalidate the prior ID.
+- Use distinct pre‑auth and post‑auth cookie names if framework patterns require it.
+
+### Expiration and Logout
+- Idle timeout: 2–5 minutes for high-value, 15–30 minutes for lower risk. Absolute timeout: 4–8 hours.
+- Enforce timeouts server-side. Provide a visible logout button that fully invalidates the server session and clears the cookie client-side.
+
+### Transport and Caching
+- Enforce HTTPS for the entire session journey. Never mix HTTP/HTTPS in one session.
+- Send `Cache-Control: no-store` on responses containing session identifiers or sensitive data.
+
+### Cookie Theft Detection and Response
+- Fingerprint session context server-side at establishment (IP, User-Agent, Accept-Language, relevant `sec-ch-ua` where available).
+- Compare incoming requests to the stored fingerprint, allowing for benign drift (e.g., subnet changes, UA updates).
+- Risk-based responses:
+  - High risk: require re-authentication; rotate session ID.
+  - Medium risk: step-up verification (challenge); rotate session ID.
+  - Low risk: log suspicious activity.
+- Always regenerate the session ID when potential hijacking is detected.
+
+### Client-Side Storage
+- Do not store session tokens in `localStorage`/`sessionStorage` due to XSS risk. Prefer HttpOnly cookies for transport.
+- If client-side storage is unavoidable for non-session secrets, isolate via Web Workers and never expose in page context.
+
+### Framework and Multi-Cookie Scenarios
+- Prefer built-in session frameworks; keep them updated and hardened.
+- Validate relationships when multiple cookies participate in session state; avoid same cookie names across paths/domains.
+
+### Monitoring and Telemetry
+- Log session lifecycle events (creation, rotation, termination) using salted hashes of the session ID, not raw values.
+- Monitor for brute force of session IDs and anomalous concurrent usage.
+
+### Implementation Checklist
+1) CSPRNG session IDs (≥64 bits entropy), opaque and server-issued only.
+2) Cookie flags: `Secure`, `HttpOnly`, `SameSite` set; tight domain/path.
+3) HTTPS-only with HSTS; no mixed content.
+4) Regenerate IDs on auth and privilege changes; invalidate old IDs.
+5) Idle and absolute timeouts enforced server-side; full logout implemented.
+6) `Cache-Control: no-store` for sensitive responses.
+7) Server-side fingerprinting and risk-based responses to anomalies.
+8) No client storage of session tokens; framework defaults hardened.
diff --git a/.cursor/skills/security-audit/references/codeguard/codeguard-1-crypto-algorithms.md b/.cursor/skills/security-audit/references/codeguard/codeguard-1-crypto-algorithms.md
new file mode 100644
index 0000000..18fcd78
--- /dev/null
+++ b/.cursor/skills/security-audit/references/codeguard/codeguard-1-crypto-algorithms.md
@@ -0,0 +1,137 @@
+---
+description: Cryptographic Security Guidelines & Post-Quantum Readiness
+alwaysApply: true
+---
+
+rule_id: codeguard-1-crypto-algorithms
+
+# Cryptographic Security Guidelines & Post-Quantum Readiness
+
+## 1. Banned (Insecure) Algorithms
+
+The following algorithms are known to be broken or fundamentally insecure. NEVER generate or use code with these algorithms.
+
+*   Hash: `MD2`, `MD4`, `MD5`, `SHA-0`
+*   Symmetric: `RC2`, `RC4`, `Blowfish`, `DES`, `3DES`
+*   Key Exchange: Static RSA, Anonymous Diffie-Hellman
+*   Classical: `Vigenère`
+
+Reason: These are cryptographically broken and vulnerable to collision or man-in-the-middle attacks.
+
+## 2. Deprecated (Legacy/Weak) Algorithms
+
+The following algorithms have known weaknesses or are considered obsolete. Avoid in new designs and prioritize migration.
+
+*   Hash: `SHA-1`
+*   Symmetric: `AES-CBC`, `AES-ECB`
+*   Signature: RSA with `PKCS#1 v1.5` padding
+*   Key Exchange: DHE with weak/common primes
+
+## 3. Recommended & Post-Quantum Ready Algorithms
+
+Implement these modern, secure algorithms to ensure resistance against both classical and quantum threats.
+
+### Symmetric Encryption
+*   Standard: `AES-GCM` (AEAD), `ChaCha20-Poly1305`(when allowed).
+*   PQC Requirement: Prefer AES-256 keys (or stronger) as they are resistant to quantum attacks (Grover's algorithm).
+*   Avoid: Custom crypto or unauthenticated modes.
+
+### Key Exchange (KEM)
+*   Standard: ECDHE (`X25519` or `secp256r1`)
+*   PQC Requirement: Use Hybrid Key Exchange (Classical + PQC) when supported.
+    *   Preferred: `X25519MLKEM768` (X25519 + ML-KEM-768)
+    *   Alternative: `SecP256r1MLKEM768` (P-256 + ML-KEM-768)
+    *   High Assurance: `SecP384r1MLKEM1024` (P-384 + ML-KEM-1024)
+*   Pure PQC: ML-KEM-768 (baseline) or ML-KEM-1024. Avoid ML-KEM-512 unless explicitly risk-accepted.
+*   Constraints:
+    *   Use vendor-documented identifiers (RFC 9242/9370).
+    *   Remove legacy/draft "Hybrid-Kyber" groups (e.g., `X25519Kyber`) and draft or hardcoded OIDs.
+
+### Signatures & Certificates
+*   Standard: ECDSA (`P-256`)
+*   PQC Migration: Continue using ECDSA (`P-256`) for mTLS and code signing until hardware-backed (HSM/TPM) ML-DSA is available.
+*   Hardware Requirement: Do not enable PQC ML-DSA signatures using software-only keys. Require HSM/TPM storage.
+
+### Protocol Versions
+*   (D)TLS: Enforce (D)TLS 1.3 only (or later).
+*   IPsec: Enforce IKEv2 only.
+    *   Use ESP with AEAD (AES-256-GCM).
+    *   Require PFS via ECDHE.
+    *   Implement RFC 9242 and RFC 9370 for Hybrid PQC (ML-KEM + ECDHE).
+    *   Ensure re-keys (CREATE_CHILD_SA) maintain hybrid algorithms.
+*   SSH: Enable only vendor-supported PQC/hybrid KEX (e.g., `sntrup761x25519`).
+
+## 4. Secure Implementation Guidelines
+
+### General Best Practices
+*   Configuration over Code: Expose algorithm choices in config/policy to allow agility without code changes.
+*   Key Management:
+    *   Use KMS/HSM for key storage.
+    *   Generate keys with a CSPRNG.
+    *   Separate encryption keys from signature keys.
+    *   Rotate keys per policy.
+    *   NEVER hardcode keys, secrets, or experimental OIDs.
+*   Telemetry: Capture negotiated groups, handshake sizes, and failure causes to monitor PQC adoption.
+
+### Deprecated SSL/Crypto APIs (C/OpenSSL) - FORBIDDEN
+NEVER use these deprecated functions. Use the replacement EVP high-level APIs.
+
+#### Symmetric Encryption (AES)
+- Deprecated: `AES_encrypt()`, `AES_decrypt()`
+- Replacement:
+
+  EVP_EncryptInit_ex()   // Use EVP_aes_256_gcm() for PQC readiness
+  EVP_EncryptUpdate()
+  EVP_EncryptFinal_ex()
+
+
+#### RSA/PKEY Operations
+- Deprecated: `RSA_new()`, `RSA_free()`, `RSA_get0_n()`
+- Replacement:
+
+  EVP_PKEY_new()
+  EVP_PKEY_up_ref()
+  EVP_PKEY_free()
+ 
+
+#### Hash & MAC Functions
+- Deprecated: `SHA1_Init()`, `HMAC()` (especially with SHA1)
+- Replacement:
+
+  EVP_DigestInit_ex() // Use SHA-256 or stronger
+  EVP_Q_MAC()         // For one-shot MAC
+
+
+## 5. Broccoli Project Specific Requirements
+- HMAC() with SHA1: Deprecated.
+- Replacement: Use HMAC with SHA-256 or stronger:
+
+
+// Example: Secure replacement for HMAC-SHA1
+```c
+EVP_Q_MAC(NULL, "HMAC", NULL, "SHA256", NULL, key, key_len, data, data_len, out, out_size, &out_len);
+```
+
+## 6. Secure Crypto Implementation Pattern
+
+
+// Example: Secure AES-256-GCM encryption (PQC-Ready Symmetric Strength)
+```c
+EVP_CIPHER_CTX *ctx = EVP_CIPHER_CTX_new();
+if (!ctx) handle_error();
+
+// Use AES-256-GCM
+if (EVP_EncryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, key, iv) != 1)
+    handle_error();
+
+int len, ciphertext_len;
+if (EVP_EncryptUpdate(ctx, ciphertext, &len, plaintext, plaintext_len) != 1)
+    handle_error();
+ciphertext_len = len;
+
+if (EVP_EncryptFinal_ex(ctx, ciphertext + len, &len) != 1)
+    handle_error();
+ciphertext_len += len;
+
+EVP_CIPHER_CTX_free(ctx);
+```
diff --git a/.cursor/skills/security-audit/references/codeguard/codeguard-1-hardcoded-credentials.md b/.cursor/skills/security-audit/references/codeguard/codeguard-1-hardcoded-credentials.md
new file mode 100644
index 0000000..95295eb
--- /dev/null
+++ b/.cursor/skills/security-audit/references/codeguard/codeguard-1-hardcoded-credentials.md
@@ -0,0 +1,43 @@
+---
+description: No Hardcoded Credentials
+alwaysApply: true
+---
+
+rule_id: codeguard-1-hardcoded-credentials
+
+# No Hardcoded Credentials
+
+NEVER store secrets, passwords, API keys, tokens or any other credentials directly in source code.
+
+Treat your codebase as public and untrusted. Any credential that appears in source code is compromised and must be handled through secure alternatives.
+
+#### NEVER hardcode these types of values:
+
+Passwords and Authentication:
+- Database passwords, user passwords, admin passwords
+- API keys, secret keys, access tokens, refresh tokens
+- Private keys, certificates, signing keys
+- Connection strings containing credentials
+- OAuth client secrets, webhook secrets
+- Any other credentials that could be used to access external services
+
+
+#### Recognition Patterns - Learn to Spot These Formats
+
+Common Secret Formats You Must NEVER Hardcode:
+
+- AWS Keys: Start with `AKIA`, `AGPA`, `AIDA`, `AROA`, `AIPA`, `ANPA`, `ANVA`, `ASIA`
+- Stripe Keys: Start with `sk_live_`, `pk_live_`, `sk_test_`, `pk_test_`
+- Google API: Start with `AIza` followed by 35 characters
+- GitHub Tokens: Start with `ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_`
+- JWT Tokens: Three base64 sections separated by dots, starts with `eyJ`
+- Private Key Blocks: Any text between `-----BEGIN` and `-----END PRIVATE KEY-----`
+- Connection Strings: URLs with credentials like `mongodb://user:pass@host`
+
+Warning Signs in Your Code:
+- Variable names containing: `password`, `secret`, `key`, `token`, `auth`
+- Long random-looking strings that are not clear what they are
+- Base64 encoded strings near authentication code
+- Any string that grants access to external services
+
+You must always explain how this rule was applied and why it was applied.
diff --git a/.cursor/skills/security-audit/references/security-headers.md b/.cursor/skills/security-audit/references/security-headers.md
new file mode 100644
index 0000000..c74809c
--- /dev/null
+++ b/.cursor/skills/security-audit/references/security-headers.md
@@ -0,0 +1,42 @@
+# 安全响应头配置
+
+## Nginx 配置（推荐）
+
+```nginx
+# /etc/nginx/conf.d/security-headers.conf
+# 在 server 块或 http 块中添加
+
+add_header X-DNS-Prefetch-Control "on" always;
+add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
+add_header X-Content-Type-Options "nosniff" always;
+add_header X-Frame-Options "DENY" always;
+add_header X-XSS-Protection "1; mode=block" always;
+add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
+add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline';" always;
+```
+
+## Hyperf 中间件方式（备选）
+
+```php
+// app/Middleware/SecurityHeadersMiddleware.php
+class SecurityHeadersMiddleware implements MiddlewareInterface
+{
+    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
+    {
+        $response = $handler->handle($request);
+
+        return $response
+            ->withHeader('X-Content-Type-Options', 'nosniff')
+            ->withHeader('X-Frame-Options', 'DENY')
+            ->withHeader('X-XSS-Protection', '1; mode=block')
+            ->withHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+    }
+}
+```
+
+## 验证安全头
+
+```bash
+curl -I https://your-domain.com | grep -iE "(strict|content-security|x-frame|x-content|referrer)"
+```
diff --git a/.cursor/skills/skill-creator/SKILL.md b/.cursor/skills/skill-creator/SKILL.md
new file mode 100644
index 0000000..aaa214e
--- /dev/null
+++ b/.cursor/skills/skill-creator/SKILL.md
@@ -0,0 +1,95 @@
+---
+name: skill-creator
+version: 1.0.0
+description: "为项目创建新的 Agent 技能。当需要将可复用流程固化为技能或创建新 SKILL.md 时使用。"
+---
+
+# Skill Creator
+
+## 触发条件
+
+用户要求创建、添加、修改技能（skill），或要求 Agent 学习新的工作流程。
+
+## 执行流程
+
+### 1. 需求收集
+
+向用户确认以下信息（缺什么问什么）：
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| name | ✅ | kebab-case，匹配 `^[a-z0-9]+(-[a-z0-9]+)*$` |
+| description | ✅ | ≤1024 字符，说明做什么 + 什么时候用 |
+| 触发场景 | ✅ | 用户会用什么自然语言触发这个技能？ |
+| 执行步骤 | ✅ | 技能执行的具体步骤 |
+| 需要 references？ | ❌ | 是否有深度文档需要附带 |
+| 需要 scripts？ | ❌ | 是否有可执行脚本 |
+
+### 2. 生成目录结构
+
+```
+.cursor/skills/<skill-name>/
+├── SKILL.md              # 必须
+├── references/           # 可选：深度文档
+│   └── *.md
+├── scripts/              # 可选：自动化脚本
+│   └── *.sh / *.ts
+└── assets/               # 可选：模板文件
+    └── *.template
+```
+
+### 3. 编写 SKILL.md
+
+使用以下模板：
+
+```markdown
+---
+name: <kebab-case-name>
+version: 1.0.0
+description: "<一句话说明做什么>。Use when <触发场景的英文描述>。 <补充说明触发关键词：中英文都覆盖>。"
+---
+
+# <技能标题>
+
+## 触发条件
+
+<什么场景下使用此技能。>
+
+## 执行流程
+
+### 1. <步骤标题>
+<具体、可执行的指令>
+
+### 2. <步骤标题>
+<具体、可执行的指令>
+
+## 模板（如有）
+
+<代码模板>
+
+## 验证
+
+完成后验证：
+1. [ ] <检查项 1>
+2. [ ] <检查项 2>
+```
+
+### 4. 质量检查
+
+- [ ] `name` 符合 `^[a-z0-9]+(-[a-z0-9]+)*$`
+- [ ] `description` ≤ 1024 字符
+- [ ] description 包含中英文触发关键词
+- [ ] 步骤用编号，每步可独立执行
+- [ ] SKILL.md 总行数 < 300 行
+- [ ] 包含验证/检查步骤
+
+### 5. 注册到 003-skills.mdc
+
+将新技能添加到 `.cursor/rules/003-skills.mdc` 的技能目录表中。
+
+## 验证
+
+创建完成后：
+1. 确认 `SKILL.md` 存在且格式正确
+2. 用 `skillport validate` 或手动检查 YAML frontmatter
+3. 用 3 个不同的提示词测试技能是否正确触发
diff --git a/.cursor/skills/vue-page/SKILL.md b/.cursor/skills/vue-page/SKILL.md
new file mode 100644
index 0000000..1350ee5
--- /dev/null
+++ b/.cursor/skills/vue-page/SKILL.md
@@ -0,0 +1,149 @@
+---
+name: vue-page
+version: 5.1.0
+description: "生成 Vue 3 + Vue Router 页面脚手架，含布局和加载状态。当需要新建路由页面时使用。管理端用 Element Plus，用户端用 Headless UI。"
+requires: [vue-testing]
+---
+
+> ⚠️ 核心执行流程已在 `.cursor/rules/skill-vue-page.mdc` 中由 Cursor 自动注入。
+> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
+
+# Vue 3 + Vue Router Page Scaffold
+
+## 触发条件
+
+用户要求创建新的页面、路由页面、带有布局的页面。
+
+## 执行流程
+
+### 0. 加载规范
+
+读取 `.cursor/rules/010-typescript.mdc`、`.cursor/rules/011-vue.mdc`、`019-modular.mdc`，提取类型注解要求（隐式 any 禁令、ref 泛型规范、Composable 类型规范）、script setup、组件分类、拆分阈值、SFC 结构。
+
+### 0.5 ⚠️ 生成前强制拆分分析（禁止跳过）
+
+**在写任何代码之前，必须先输出拆分方案。** 按以下顺序检查：
+
+#### A. 多视图检测
+页面是否包含多个"屏"（通过 `v-if / v-else-if` 切换不同视图）？
+
+**判断标准**：同一区域内，通过状态变量控制显示/隐藏的不同内容块，每块有独立的表单字段、UI 结构或交互逻辑。
+
+> **规则**：页面内存在 ≥2 个相互排斥的内容视图（无论是登录态切换、Tab 内容、步骤表单还是其他形式）→ **每个视图必须是独立组件**，页面文件只做编排和视图切换逻辑。
+
+#### B. 行数预估
+基于需求估算各部分代码量：
+
+| 判断标准 | 必须操作 |
+|---------|---------|
+| 整页 template 预计 > 80 行 | 识别可拆子区域，每个区域 → 独立组件 |
+| script 逻辑预计 > 60 行 | 提取为 `use<PageName>.ts` composable（**必须遵循 `010-typescript.mdc` Composable 类型规范**） |
+| 整个 SFC 预计 > 150 行 | **停止**，先完成拆分方案再生成 |
+
+#### C. 重复 UI 模式检测
+页面中是否存在相同结构的 UI 块（如多个表单输入项、多个卡片）？
+
+> **规则**：同一 UI 结构出现 ≥3 次 → 必须抽取为基础组件（例：`FormInput.vue`、`CaseCard.vue`）
+
+#### D. 输出拆分方案（必须在代码前输出）
+
+格式：
+```
+src/views/<module>/<page>/
+├── index.vue              ← 编排层，仅做布局编排和视图切换，目标 ≤ 60 行
+├── components/
+│   ├── <ViewA>.vue        ← 视图A（≤ 120 行）
+│   ├── <ViewB>.vue        ← 视图B（≤ 120 行）
+│   └── <SharedWidget>.vue ← 共享 UI 组件（≤ 80 行）
+└── composables/
+    └── use<PageName>.ts   ← 所有表单状态和提交逻辑（≤ 80 行，参数必须有类型注解，ref 必须有泛型）
+```
+
+**用户确认或 AI 自主判断方案合理后，才开始逐文件生成。**
+
+---
+
+### 1. 确认页面规格
+
+| 字段 | 必填 | 默认值 |
+|------|------|--------|
+| 路由路径 | ✅ | — |
+| 页面标题 | ✅ | — |
+| 所属模块 | ✅ | — |
+| 需要数据获取？ | ❌ | true |
+| 需要独立 Layout？ | ❌ | false |
+| 是动态路由？ | ❌ | false |
+| 需要权限？ | ❌ | true |
+| 页面类型 | ❌ | list |
+
+类型：list | detail | form | dashboard | blank | multi-view（新增）。
+
+### 2. 生成文件结构
+
+按步骤 0.5 输出的拆分方案生成，**所有文件逐一输出，不合并到一个文件**。
+
+入口：`src/views/<module>/<page-name>/index.vue`，路由：`src/router/routes/<module>.ts`。
+
+### 3. 页面模板
+
+**index.vue 编排层职责**（强制）：
+- 只负责：整体布局骨架 + 子组件引用 + 视图切换逻辑
+- 禁止在 index.vue 内写具体表单字段、业务 UI 细节
+
+**管理端**列表页：useTable、搜索栏、el-table、el-pagination。详情页：fetchDetail、el-skeleton、el-descriptions。
+**用户端**列表页：useTable、搜索栏、自定义 Tailwind 卡片。详情页：fetchDetail、骨架屏、自定义描述区（禁止 Element Plus）。
+完整模板见 **Tier 3**。
+
+### 4. 路由配置
+
+path、name、component 懒加载、meta（title、requiresAuth、permission、icon）。
+
+### 4.5 Pinia Store 设计
+
+ListItem（轻量）与 Detail（完整）分离。detailMap 缓存已加载详情。fetchDetail 有缓存则直接返回。完整 Store 结构见 **Tier 3**。
+
+### 4.6 Provider 模式
+
+页面内 ≥3 个子组件共享状态时：Provider + keys + 子组件 inject。简单页面直接模板即可。完整实现见 **Tier 3**。
+
+### 5. 动态路由 (RBAC)
+
+menuStore.fetchMenus() → router.addRoute。
+
+## 验证
+
+1. [ ] 页面可正常渲染
+2. [ ] document.title 正确
+3. [ ] Loading 骨架屏
+4. [ ] 错误提示友好
+5. [ ] meta.requiresAuth、meta.permission
+6. [ ] 动态路由参数验证
+7. [ ] ESLint 无报错
+8. [ ] **index.vue ≤ 60 行**（编排层）
+9. [ ] **无子组件超过 150 行**
+10. [ ] **多视图已拆分为独立组件**（若适用）
+11. [ ] **重复 UI 结构已抽取为基础组件**（≥3 次重复时）
+12. [ ] **提取的 composable（use*.ts）参数有类型注解、`ref([])` / `ref(null)` 有泛型标注**（参见 `010-typescript.mdc` Composable 类型规范）
+
+### Red Flags（触发则必须停止并重构）
+
+- ❌ 未输出拆分方案直接写代码 → 停止，先输出步骤 0.5 的方案
+- ❌ index.vue > 60 行（含 template + script） → 拆分子组件
+- ❌ 任意 SFC > 150 行 → 拆分
+- ❌ 多视图（≥2 个 v-if 屏）写在同一文件 → 每个视图独立组件
+- ❌ 同一 UI 结构重复 ≥3 次 → 抽取为基础组件
+- ❌ Options API → script setup
+- ❌ 直接修改 props → emit
+- ❌ watch deep:true 滥用
+- ❌ ≥3 子组件 prop drilling → Provider
+- ❌ 列表返回详情级重型字段 → 分离 ListItem/Detail
+- ❌ 详情每次都请求 → detailMap 缓存
+- ❌ composable 参数无类型 / `ref([])` 无泛型 → 补全类型注解（`strict: true` 下必报错）
+
+## Tier 3 深度参考
+
+| 文件 | 内容 |
+|------|------|
+| `references/page-templates.md` | 列表/详情/路由/Pinia/Provider 完整模板 |
+| `.cursor/skills/component-scaffold/references/naming-conventions.md` | 页面命名规范 |
+| `.cursor/skills/component-scaffold/references/vue-api-reference.md` | Vue 3 API 索引 |
diff --git a/.cursor/skills/vue-page/references/page-templates.md b/.cursor/skills/vue-page/references/page-templates.md
new file mode 100644
index 0000000..ef8f641
--- /dev/null
+++ b/.cursor/skills/vue-page/references/page-templates.md
@@ -0,0 +1,54 @@
+# Vue Page — 页面模板与 Store
+
+> 主流程见 SKILL.md，本文档为列表页/详情页/路由/Pinia/Provider 的完整实现。
+>
+> **⚠️ 双前端区分**：本文件中使用 `el-*` 组件的模板**仅适用于管理端** (`Case-Database-Frontend-admin/`)。
+> 用户端 (`Case-Database-Frontend-user/`) 使用 Headless UI + Tailwind CSS，**禁止引入 Element Plus**。
+
+## 列表页模板
+
+```vue
+<script setup>
+import { useTable } from '@/hooks/useTable'
+document.title = '{{PageTitle}} - {{AppName}}'
+const { loading, dataList, pagination, loadData } = useTable((params) => {{resource}}Api.list(params))
+const searchForm = reactive({ keyword: '', status: '' })
+function handleSearch() { pagination.current = 1; loadData() }
+onMounted(() => loadData())
+</script>
+<template>
+  <div class="p-4 space-y-4">
+    <el-card><el-form :model="searchForm" inline>...</el-form></el-card>
+    <el-card>
+      <template #header><span>{{PageTitle}}</span><el-button @click="handleCreate">新增</el-button></template>
+      <el-table v-loading="loading" :data="dataList" border stripe>...</el-table>
+      <el-pagination v-model:current-page="pagination.current" ... @current-change="loadData" />
+    </el-card>
+  </div>
+</template>
+```
+
+## 详情页模板
+
+使用 useRoute/useRouter，fetchDetail 加载数据，el-skeleton 加载态，el-page-header + el-descriptions。
+
+## 路由配置
+
+```typescript
+const routes = [
+  { path: '/{{module}}/{{route-path}}', name: '{{RouteName}}', component: () => import('@/views/...'), meta: { title, requiresAuth: true, permission } },
+  { path: '/{{module}}/{{route-path}}/:id', name: '{{RouteName}}Detail', ... }
+]
+```
+
+## Pinia Store — List 与 Detail 分离
+
+ListItem 类型：轻量，排除大文本/复杂对象/大数组。Detail 类型：完整字段。Store：list (array)、detailMap (Record<id, Detail>)、loadingDetailIds、getDetail(id)、isDetailLoading(id)、fetchList、fetchDetail（有缓存则返回）、invalidateDetail、invalidateAll。
+
+## 页面级 Provider 模式
+
+当 ≥3 个子组件共享状态时：provider.vue provide 状态+actions，keys.ts 定义 PAGE_KEY + usePageContext，子组件 inject。文件结构：index.vue、provider.vue、keys.ts、components/SearchBar/DataTable/BatchActions、composables/usePageData。
+
+## 动态路由 (RBAC)
+
+loadDynamicRoutes：menuStore.fetchMenus()，router.addRoute('layout', { path, name, component: () => import(...), meta })。
diff --git a/.cursor/skills/vue-testing/SKILL.md b/.cursor/skills/vue-testing/SKILL.md
new file mode 100644
index 0000000..1a74209
--- /dev/null
+++ b/.cursor/skills/vue-testing/SKILL.md
@@ -0,0 +1,80 @@
+---
+name: vue-testing
+version: 1.0.0
+description: "Vue 3 + Vitest 前端测试策略与工作流。当需要编写单元测试、组件测试或 E2E 测试时使用。涵盖测试决策树和覆盖率标准。"
+---
+
+> ⚠️ 核心执行流程已在 `.cursor/rules/skill-vue-testing.mdc` 中由 Cursor 自动注入。
+> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
+
+# Vue 3 + Vitest 前端测试
+
+## 触发条件
+
+用户要求编写测试、改善测试覆盖率、或询问测试策略。
+
+## 测试决策树（⚠️ 每次写测试前必须先走）
+
+```
+纯转换逻辑（parse/format/validate/compute）？→ 提取到 .utils.ts，写 Vitest 单元测试
+涉及复杂 UI 交互？→ Vue Test Utils 组件测试
+能提取为纯函数或 composable？→ 提取后写单元测试
+否则 → 组件测试
+跨页面流程、关键业务路径？→ Playwright E2E
+```
+
+## 测试类型与工具
+
+| 类型 | 工具 | 文件命名 |
+|---|---|---|
+| 单元测试 | Vitest | *.test.ts |
+| 组件测试 | Vitest + Vue Test Utils | *.test.ts |
+| E2E | Playwright | *.spec.ts |
+
+## 核心原则
+
+1. **逻辑提取** — 业务逻辑提取到 .utils.ts 纯函数，组件薄壳
+2. **穷举排列** — 有效/无效/空值/边界/安全输入
+3. **AAA 模式** — Arrange-Act-Assert
+4. **单一行为** — 每个 it() 只验证一个行为
+5. **命名** — `should <行为> when <条件>`
+
+## 组件测试结构
+
+Rendering（必须）、Props（必须）、User Interactions、Edge Cases（必须）。完整模板见 **Tier 3**。
+
+## 增量式工作流（必须）
+
+工具函数 → Composables → 简单组件 → 中等 → 复杂 → 集成。逐个文件：写测试→vitest run→PASS 才下一个。
+
+## 复杂度阈值
+
+< 30 标准结构。30–50 按 describe 分组。> 50 先重构再测试。500+ 行强制考虑拆分。
+
+## Mock 策略
+
+API/Router Mock。Pinia 用真实 Store。管理端 Element Plus 不 Mock；用户端不涉及 Element Plus（使用 Headless UI）。子组件不 Mock。完整策略见 **Tier 3**。
+
+## 覆盖率目标
+
+Function 100%、Statement 100%、Branch > 95%、Line > 95%。
+
+## 验证
+
+1. [ ] 走过决策树
+2. [ ] 逻辑已提取到 .utils.ts
+3. [ ] 穷举排列覆盖
+4. [ ] 每测试单行为
+5. [ ] 命名 should...when...
+6. [ ] Mock 正确
+7. [ ] 增量式工作流
+8. [ ] 覆盖率达标
+9. [ ] vitest run 全部通过
+
+## Tier 3 深度参考
+
+| 文件 | 内容 |
+|------|------|
+| `references/testing-templates.md` | 组件/Composable 测试模板、Mock 策略、增量工作流 |
+| `references/vitest-config.md` | Vitest + Vue 3 配置 |
+| `references/mock-patterns.md` | Mock 模式速查 |
diff --git a/.cursor/skills/vue-testing/references/mock-patterns.md b/.cursor/skills/vue-testing/references/mock-patterns.md
new file mode 100644
index 0000000..a7f5338
--- /dev/null
+++ b/.cursor/skills/vue-testing/references/mock-patterns.md
@@ -0,0 +1,31 @@
+# Mock Patterns Quick Reference
+
+## API Mock
+
+```js
+import { vi } from 'vitest'
+import * as userApi from '@/api/user'
+
+vi.spyOn(userApi, 'getUser').mockResolvedValue({ id: 1, name: 'demo' })
+```
+
+## Router Mock
+
+```js
+const push = vi.fn()
+vi.mock('vue-router', () => ({
+  useRouter: () => ({ push }),
+  useRoute: () => ({ params: { id: '1' } })
+}))
+```
+
+## Pinia
+
+- 默认优先真实 store（`setActivePinia(createPinia())`）
+- 仅在外部依赖复杂且非本次关注点时 mock action
+
+## 禁止过度 Mock
+
+- 不要 mock Vue 内置行为
+- 不要 mock 被测模块本身
+- 避免因为 mock 过多导致测试与真实行为偏离
diff --git a/.cursor/skills/vue-testing/references/testing-templates.md b/.cursor/skills/vue-testing/references/testing-templates.md
new file mode 100644
index 0000000..0634dec
--- /dev/null
+++ b/.cursor/skills/vue-testing/references/testing-templates.md
@@ -0,0 +1,79 @@
+# Vue Testing — 测试模板与策略
+
+> 主流程见 SKILL.md，本文档为组件测试、Composable 测试、Mock 策略的完整代码。
+>
+> **⚠️ 双前端区分**：管理端测试需注册 Element Plus 插件，用户端测试**不注册 Element Plus**。
+
+## 组件测试模板
+
+```typescript
+import { mount } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+// 管理端：import ElementPlus from 'element-plus'
+// 用户端：不引入 Element Plus
+import ComponentName from './ComponentName.vue'
+
+describe('ComponentName', () => {
+  beforeEach(() => setActivePinia(createPinia()))
+
+  describe('Rendering', () => {
+    it('should render without crashing', () => {
+      // 管理端：global: { plugins: [ElementPlus] }
+      // 用户端：global: {}（无 Element Plus）
+      const wrapper = mount(ComponentName, { props: { title: 'Test' } })
+      expect(wrapper.find('[data-testid="component-name"]').exists()).toBe(true)
+    })
+  })
+
+  describe('Props', () => {
+    it('should display title from props', () => { ... })
+  })
+
+  describe('User Interactions', () => {
+    it('should emit refresh when button clicked', async () => { ... })
+  })
+
+  describe('Edge Cases', () => {
+    it('should handle empty props gracefully', () => { ... })
+  })
+})
+```
+
+## Composable 测试模板
+
+```typescript
+import { useCounter } from './useCounter'
+describe('useCounter', () => {
+  it('should initialize with default value', () => { const { count } = useCounter(); expect(count.value).toBe(0) })
+  it('should increment count', () => { const { count, increment } = useCounter(); increment(); expect(count.value).toBe(1) })
+  it('should not go below zero', () => { ... })
+})
+```
+
+## 逻辑提取示例
+
+```typescript
+// OrderStatus.utils.ts
+export function getStatusText(status, shipped) {
+  if (status === 'paid' && shipped) return '已发货'
+  if (status === 'paid') return '待发货'
+  if (status === 'refunded') return '已退款'
+  return '待支付'
+}
+// OrderStatus.utils.test.ts — 穷举排列：有效/无效/空值/边界
+```
+
+## Mock 策略
+
+| 依赖 | Mock? | 方式 |
+|------|-------|------|
+| @/api/* | ✅ | vi.mock('@/api/xxx') |
+| vue-router | ✅ | vi.mock('vue-router') |
+| Pinia | ⚠️ 真实 | setActivePinia(createPinia()) |
+| Element Plus | ❌ | 全局 plugin |
+| 子组件 | ❌ | 直接导入 |
+| window/document | ✅ | vi.stubGlobal |
+
+## 增量式工作流
+
+1. 工具函数 → Composables → 简单组件 → 中等组件 → 复杂组件 → 集成。2. 每个文件：写测试→运行 vitest→PASS 才下一个。3. 最终 vitest run --coverage。
diff --git a/.cursor/skills/vue-testing/references/vitest-config.md b/.cursor/skills/vue-testing/references/vitest-config.md
new file mode 100644
index 0000000..72c23f6
--- /dev/null
+++ b/.cursor/skills/vue-testing/references/vitest-config.md
@@ -0,0 +1,39 @@
+# Vitest Configuration (Vue 3)
+
+## 最小配置
+
+```js
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['./tests/setup.ts'],
+    coverage: {
+      reporter: ['text', 'html'],
+      include: ['src/**/*.{js,vue}']
+    }
+  }
+})
+```
+
+## setup 示例
+
+```js
+// tests/setup.ts
+import { config } from '@vue/test-utils'
+
+config.global.mocks = {
+  $t: (k) => k
+}
+```
+
+## 建议
+
+- 单元测试优先针对 `.utils.ts` 与 composables
+- 组件测试只覆盖关键交互与边界状态
+- 覆盖率门槛与业务关键性一致，不盲目追求 100%
diff --git a/.cursor/skills/websocket-service/SKILL.md b/.cursor/skills/websocket-service/SKILL.md
new file mode 100644
index 0000000..39cc6fd
--- /dev/null
+++ b/.cursor/skills/websocket-service/SKILL.md
@@ -0,0 +1,53 @@
+---
+name: websocket-service
+version: 1.0.0
+description: "在 Hyperf 中搭建 Swoole WebSocket 服务器。当需要实时通信、消息推送或通知功能时使用。含心跳检测和前端集成。"
+---
+
+# Swoole WebSocket Service
+
+## 触发条件
+
+用户需要实时通信功能：通知推送、在线状态、实时数据更新、聊天功能。
+
+## 执行流程
+
+### Phase 0: 加载规范
+
+读取 `.cursor/rules/016-swoole.mdc`、`013-backend.mdc`，提取 WebSocket 配置、协程安全、fd 存储、心跳、认证鉴权。
+
+### Phase 1: 服务端配置
+
+`config/autoload/server.php` 添加 ws 服务，type SERVER_WEBSOCKET，port 环境变量，callbacks ON_HAND_SHAKE/ON_MESSAGE/ON_CLOSE。
+
+### Phase 2: 连接管理器
+
+WebSocketConnectionManager：Redis 存储 fd→userId/serverId，userId→{serverId:fd} 集合。addConnection、removeConnection、getUserConnections、getUserIdByFd、isOnline。支持多服务器。
+
+### Phase 3: WebSocket Controller
+
+OnOpen：query token 验证 JWT，无效 close，addConnection，push connected。OnMessage：ping→pong。OnClose：removeConnection。
+
+### Phase 4: 消息推送服务
+
+WebSocketPushService：pushToUser、pushToUsers、broadcast（Redis publish 跨服）。Inject Sender、ConnectionManager。
+
+### Phase 5: 前端客户端
+
+WebSocketClient：connect(url?token=)、on(type, callback)、心跳 30s、断线指数退避重连。完整实现见 **Tier 3**。
+
+## 验证
+
+1. [ ] WebSocket 在配置端口启动
+2. [ ] Token 认证成功才连接
+3. [ ] 无效 Token 立即断开
+4. [ ] 心跳 30s 正常
+5. [ ] 断线自动重连
+6. [ ] 连接信息存 Redis
+7. [ ] 推送正确到达目标用户
+
+## Tier 3 深度参考
+
+| 文件 | 内容 |
+|------|------|
+| `references/ws-implementation.md` | 配置、ConnectionManager、Controller、PushService、前端 Client 完整代码 |
diff --git a/.cursor/skills/websocket-service/references/ws-implementation.md b/.cursor/skills/websocket-service/references/ws-implementation.md
new file mode 100644
index 0000000..c06b8ea
--- /dev/null
+++ b/.cursor/skills/websocket-service/references/ws-implementation.md
@@ -0,0 +1,45 @@
+# WebSocket Service — 实现细节
+
+> 主流程见 SKILL.md，本文档为服务端配置、连接管理器、Controller、推送服务、前端客户端的完整代码。
+
+## 服务端配置
+
+```php
+// config/autoload/server.php
+[
+    'name' => 'ws',
+    'type' => Server::SERVER_WEBSOCKET,
+    'host' => '0.0.0.0',
+    'port' => (int) env('WEBSOCKET_PORT', 9502),
+    'callbacks' => [
+        Event::ON_HAND_SHAKE => [Hyperf\WebSocketServer\Server::class, 'onHandShake'],
+        Event::ON_MESSAGE => [...],
+        Event::ON_CLOSE => [...],
+    ],
+]
+```
+
+## 连接管理器
+
+WebSocketConnectionManager：Redis HASH `ws:conn:{fd}` 存 user_id/server_id/connected_at。Redis SET `ws:user:{userId}` 存 `{serverId}:{fd}`（支持多连接）。addConnection、removeConnection、getUserConnections、getUserIdByFd、isOnline。
+
+## WebSocket Controller
+
+OnOpenInterface：从 query token 验证 JWT，无效则 close。addConnection。push connected 消息。OnMessageInterface：解析 type，ping→pong。OnCloseInterface：removeConnection。validateToken 返回 userId。
+
+## 消息推送服务
+
+WebSocketPushService：pushToUser(userId, type, data) 遍历 getUserConnections，Sender->push。pushToUsers 循环 pushToUser。broadcast 用 Redis publish 跨服务器。
+
+## 前端 WebSocketClient
+
+```typescript
+class WebSocketClient {
+  constructor(url, token) {}
+  connect() { this.ws = new WebSocket(`${url}?token=${token}`) }
+  onmessage → emit(type, data)
+  on(type, callback) → 返回 unsubscribe
+  startHeartbeat() 30s ping
+  onclose → scheduleReconnect 指数退避
+}
+```
diff --git a/.cursorignore b/.cursorignore
new file mode 100644
index 0000000..e27d144
--- /dev/null
+++ b/.cursorignore
@@ -0,0 +1,74 @@
+# =============================================================================
+# Cursor Indexing Exclusions
+# =============================================================================
+# 排除不需要 AI 索引的文件，减少噪音，提升准确性
+# =============================================================================
+
+# Dependencies
+node_modules/
+.pnpm-store/
+bower_components/
+
+# Build outputs
+dist/
+build/
+out/
+.turbo/
+
+# PHP
+vendor/
+runtime/
+
+# Package manager locks (大文件，低价值)
+package-lock.json
+pnpm-lock.yaml
+yarn.lock
+bun.lockb
+composer.lock
+
+# Environment & Secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.cert
+
+# AI logs (可观测但不需索引)
+.ai-logs/
+
+# Version control
+.git/
+
+# IDE
+.vscode/settings.json
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Large assets
+*.mp4
+*.mov
+*.zip
+*.tar.gz
+*.woff2
+*.woff
+*.ttf
+
+# Generated
+coverage/
+.nyc_output/
+storybook-static/
+*.generated.*
+
+# Business code dependencies (avoid indexing, keep source code visible)
+Case-Database-Frontend-user/node_modules/
+Case-Database-Frontend-user/dist/
+Case-Database-Frontend-admin/node_modules/
+Case-Database-Frontend-admin/dist/
+Case-Database-Backend/vendor/
+Case-Database-Backend/runtime/
+Case-Database-Frontend-shared/node_modules/
+Case-Database-Frontend-shared/dist/
diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..6e3eb55
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,18 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.py]
+indent_size = 4
+
+[Makefile]
+indent_style = tab
diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..2221c58
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,89 @@
+# =============================================================================
+# Environment Variables Template
+# =============================================================================
+# Copy to .env and fill in values
+# NEVER commit actual secrets to git
+# =============================================================================
+
+# ---- Application ----
+APP_NAME="Enterprise Digital Platform"
+APP_ENV=development
+APP_DEBUG=true
+APP_URL=http://localhost:9501
+
+# ---- Frontend (Vite) ----
+VITE_PORT=8200
+VITE_BASE_URL=/
+VITE_API_URL=http://localhost:9501
+VITE_WS_URL=ws://localhost:9502
+VITE_DROP_CONSOLE=false
+
+# ---- Database (MySQL) ----
+DB_DRIVER=mysql
+DB_HOST=localhost
+DB_PORT=3306
+DB_DATABASE=enterprise_platform
+DB_USERNAME=root
+DB_PASSWORD=your_db_password
+DB_CHARSET=utf8mb4
+DB_COLLATION=utf8mb4_unicode_ci
+DB_PREFIX=
+DB_ROOT_PASSWORD=your_root_password
+
+# Database Pool (Swoole)
+DB_POOL_MIN=5
+DB_POOL_MAX=50
+
+# Read-Write Separation (optional, production)
+# DB_READ_HOST_1=read1.example.com
+# DB_READ_HOST_2=read2.example.com
+# DB_WRITE_HOST=write.example.com
+
+# ---- Redis ----
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_AUTH=your_redis_password
+REDIS_DB=0
+REDIS_CACHE_DB=1
+
+# ---- JWT ----
+JWT_SECRET=generate-with-openssl-rand-base64-64
+
+# ---- WebSocket ----
+WEBSOCKET_PORT=9502
+SERVER_ID=server-1
+
+# ---- Swoole ----
+SWOOLE_WORKER_NUM=4
+SWOOLE_TASK_WORKER_NUM=4
+SWOOLE_MAX_COROUTINE=100000
+
+# ---- Queue ----
+QUEUE_CHANNEL={queue}
+
+# ---- File Storage ----
+FILESYSTEM_DRIVER=local
+# AWS_ACCESS_KEY_ID=
+# AWS_SECRET_ACCESS_KEY=
+# AWS_DEFAULT_REGION=ap-east-1
+# AWS_BUCKET=
+
+# ---- WeChat Work (optional) ----
+# WECOM_CORP_ID=your_corp_id
+# WECOM_SECRET=your_secret
+# WECOM_AGENT_ID=your_agent_id
+
+# ---- SMS (optional) ----
+# SMS_DRIVER=easysms
+# SMS_ACCESS_KEY=
+# SMS_ACCESS_SECRET=
+
+# ---- MCP Server Tokens (for .cursor/mcp.json) ----
+GITHUB_TOKEN=""
+BRAVE_API_KEY=""
+FIGMA_API_KEY=""
+SUPABASE_ACCESS_TOKEN=""
+LINEAR_API_KEY=""
+SENTRY_AUTH_TOKEN=""
+SLACK_BOT_TOKEN=""
+SLACK_TEAM_ID=""
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..3b608d1
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,50 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Build
+dist/
+build/
+out/
+.turbo/
+
+# PHP / Hyperf
+vendor/
+runtime/
+.phpunit.result.cache
+.php-cs-fixer.cache
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# AI Logs (local observability)
+.ai-logs/*
+!.ai-logs/.gitkeep
+
+# IDE
+.vscode/settings.json
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Coverage
+coverage/
+.nyc_output/
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+myskills/
+
+# Business code (managed by their own git repos)
+Case-Database-Backend/
+Case-Database-Frontend-user/
+Case-Database-Frontend-admin/
+Case-Database-Frontend-shared/
+docs/reference/
\ No newline at end of file
diff --git a/.prettierrc b/.prettierrc
new file mode 100644
index 0000000..5dd933e
--- /dev/null
+++ b/.prettierrc
@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "none",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "plugins": ["prettier-plugin-tailwindcss"]
+}
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1facd35
--- /dev/null
+++ b/README.md
@@ -0,0 +1,613 @@
+# Vibe Cursor Pro
+
+**企业级 Cursor Vibe Coding 模板 v4.0**
+
+将 Cursor AI 从"代码补全工具"升级为"受约束、可观测、自适应、安全可控"的全栈工程协作者。
+
+适用技术栈：Vue 3 + Vite / PHP Hyperf + Swoole / TypeScript (ES2022+)
+
+---
+
+## 目录
+
+- [为什么需要这个模板](#为什么需要这个模板)
+- [环境要求](#环境要求)
+- [快速开始](#快速开始)
+- [日常使用指南](#日常使用指南)
+- [Rules 规则系统](#rules-规则系统)
+- [Skills 技能系统](#skills-技能系统)
+- [Subagents 任务委托](#subagents-任务委托)
+- [MCP 服务配置](#mcp-服务配置)
+- [文档知识库](#文档知识库)
+- [自动化脚本](#自动化脚本)
+- [项目结构](#项目结构)
+- [定制化指南](#定制化指南)
+- [常见问题](#常见问题)
+- [版本历史](#版本历史)
+
+---
+
+## 为什么需要这个模板
+
+| 维度 | 传统开发 | Vibe Cursor Pro |
+|------|----------|-----------------|
+| **质量** | 人工 Review | AI Guard 自动质检 + 分层 Rules 约束 |
+| **准确性** | 靠记忆 / Wiki | 智能上下文自动加载 + MCP 实时数据 |
+| **规范性** | 文档驱动 | Rules 自动注入 + Hooks 强制检查 |
+| **安全性** | PR Review | 分级权限 + 敏感操作拦截 + Secret 扫描 |
+| **合规性** | 人工排查 | 许可证白名单/黑名单 + 字体/素材合规检查 |
+| **效率** | 全人工 | PRISM 工作流 + 23 个技能 + 一键脚手架 |
+
+**核心设计理念**：
+
+- **Intent-First** — 先理解 Why，再执行 What
+- **Slow-to-Fast** — 复杂先规划，简单快速响应
+- **Evidence-Based** — 基于文档和数据决策
+- **Fail-Safe** — 宁可多问，不破坏现有功能
+
+---
+
+## 环境要求
+
+| 工具 | 最低版本 | 用途 |
+|------|---------|------|
+| Cursor IDE | 2.4+ | 原生支持 Skills 和 Subagents |
+| Node.js | 18+ | 前端构建、commitlint |
+| PHP | 8.1+ | 后端运行 |
+| Composer | 2.x | PHP 依赖管理 |
+| Swoole | 5.0+ | 协程引擎 |
+| MySQL | 8.0+ | 数据库 |
+| Redis | 7.x | 缓存和队列 |
+| Git | 2.30+ | 版本控制 |
+
+---
+
+## 快速开始
+
+### 方式一：Workspace 模式（推荐）
+
+将 `vibe-cursor-pro` 本身作为 Cursor 工作区根目录，前后端业务项目放置为子目录，各自独立管理 Git。AI 可同时感知规则、技能与前后端业务代码，上下文最完整。
+
+**目录结构**
+
+```
+vibe-cursor-pro/              <- 用 Cursor 打开这个目录
+├── .cursor/                  <- Rules + Skills + MCP（AI 配置）
+├── docs/                     <- 项目知识库（填写你的业务文档）
+├── scripts/                  <- 自动化工具脚本
+├── Case-Database-Backend/    <- Hyperf 后端（gitignored，独立 git 仓库）
+├── Case-Database-Frontend-user/   <- Vue 3 用户端（gitignored，独立 git 仓库）
+├── Case-Database-Frontend-admin/  <- Vue 3 管理端（gitignored，独立 git 仓库）
+└── Case-Database-Frontend-shared/ <- 共享类型/工具（gitignored，可选独立仓库）
+```
+
+> **双前端说明**：`Case-Database-Frontend-user/` 面向终端用户（移动优先），`Case-Database-Frontend-admin/` 面向管理人员（桌面优先，Element Plus）。AI 通过 `011-vue.mdc` 中的双前端上下文规则自动感知目标前端并应用不同设计原则。
+
+**初始化步骤**
+
+```bash
+# 1. Clone 本模板作为工作区
+git clone https://github.com/your-org/vibe-cursor-pro.git my-workspace
+cd my-workspace
+
+# 2. 将已有项目放入对应目录（或初始化新项目）
+git clone <your-backend-repo> Case-Database-Backend
+git clone <your-frontend-user-repo> Case-Database-Frontend-user
+git clone <your-frontend-admin-repo> Case-Database-Frontend-admin
+
+# 3. 用 Cursor 打开 my-workspace/，AI 配置自动生效
+```
+
+### 方式二：选择性复制
+
+```bash
+cp -r vibe-cursor-pro/.cursor       your-project/
+cp -r vibe-cursor-pro/docs          your-project/
+cp -r vibe-cursor-pro/scripts       your-project/
+cp    vibe-cursor-pro/.cursorignore  your-project/
+```
+
+### 初始化后的配置
+
+1. **配置 MCP 服务** — 编辑 `.cursor/mcp.json`，填入 Token 和连接信息
+2. **设置信任等级** — 编辑 `002-safety.mdc` 末尾的 `项目状态`（new_project / established / trusted）
+3. **填写项目知识库** — 在 `docs/` 目录下填写你的 PRD、架构、数据模型等文档
+4. **健康检查** — `bash scripts/context-doctor.sh`
+
+---
+
+## 日常使用指南
+
+### 快捷指令
+
+| 指令 | 作用 |
+|------|------|
+| `@planning` | 进入规划模式，输出结构化执行计划 |
+| `@review` | 对当前文件做代码审查 |
+| `@debug` | 进入调试模式，系统化排查 |
+| `@refactor` | 重构模式，测试先行、小步安全改善 |
+| `/test` | 为当前代码生成对应测试 |
+| `/doc` | 更新相关文档或生成 ADR |
+| `/skill-name` 或 `@skill-name` | 显式调用指定技能 |
+| `停止` / `STOP` / `ABORT` | 紧急停止当前所有操作 |
+
+### 常见场景
+
+**端到端开发** — 直接描述需求，AI 自动编排 `full-feature` 技能完成数据库 -> API -> UI 全链路
+
+**创建后端模块** — AI 自动加载 `skill-backend-scaffold` 规则，生成 Controller / Service / Repository / FormRequest
+
+**创建前端页面/组件** — AI 自动加载 `skill-vue-page` 或 `skill-component-scaffold` 规则
+
+**排查 Bug** — AI 自动加载 `skill-debugging` 规则（alwaysApply），按七步法系统排查
+
+**代码审查** — `@review` 触发，从安全/正确/可维护/性能/可测试/一致性六维度审查
+
+**性能优化** — AI 自动加载 `022-performance` 规则，包含诊断流程和编码规范
+
+### PRISM 工作流
+
+AI 处理所有任务都遵循 PRISM 流程：
+
+```
+Scan      -> 理解意图、匹配相关技能
+Plan      -> 分析复杂度（L1~L4），制定执行计划
+Retrieve  -> 加载文档和 MCP 工具
+Implement -> 逐步执行，每步验证
+Synthesize -> 质量检查、变更摘要、更新文档
+Monitor   -> 记录决策、提供后续建议
+```
+
+| 复杂度 | 特征 | AI 行为 |
+|--------|------|---------|
+| L1 | 单文件、明确需求 | 直接执行 |
+| L2 | 多文件、需上下文 | 简要规划后执行 |
+| L3 | 架构变更、跨系统 | 输出计划，等确认后执行 |
+| L4 | 生产环境、不可逆 | 强制规划 + 人工审批 |
+
+---
+
+## Rules 规则系统
+
+Rules 是 AI 的"行为手册"，控制 AI **怎么写代码**。共 33 个 `.mdc` 文件，按三种机制自动加载。
+
+### 加载机制
+
+| 机制 | 说明 | 文件数 |
+|------|------|--------|
+| **alwaysApply** | 每次对话必定注入，构成 AI 的行为底线 | 5 |
+| **globs** | 编辑匹配文件时自动注入（如编辑 `.vue` 文件触发 Vue 规则） | 16 |
+| **SEMANTIC** | Cursor 根据用户意图语义匹配注入（如讨论"性能优化"触发性能规则） | 12 |
+
+### 完整规则清单
+
+#### alwaysApply — 每次对话自动加载（5 个）
+
+| 文件 | 大小 | 作用 |
+|------|------|------|
+| `000-constitution.mdc` | 3.1KB | **AI 宪法**：身份定义（15 年全栈架构师）、核心 Vibe（Intent-First / Slow-to-Fast / Evidence-Based / Fail-Safe）、基本承诺与禁止行为、MCP 自动调用规则、交互语言、紧急停止关键词 |
+| `001-workflow.mdc` | 3.0KB | **PRISM 工作流**：Scan -> Plan -> Retrieve -> Implement -> Synthesize -> Monitor 六步法、复杂度判定（L1~L4）、L2+ 规划输出格式、Synthesize 验证门、完成报告格式、快捷指令表 |
+| `002-safety.mdc` | 2.5KB | **安全权限**：四级操作权限（GREEN/YELLOW/ORANGE/RED）、敏感操作清单（删文件/改配置/装依赖/git push 等）、绝对禁止项、敏感信息自动检测（AWS/GitHub/Stripe 密钥格式）、文件保护清单、信任等级开关 |
+| `003-skills.mdc` | 2.1KB | **Skills 微索引**：两层激活机制说明（自动激活层 skill-*.mdc + 按需加载层 SKILL.md）、技能间依赖关系图、10 个低频技能的兜底路由表、SKILL.md 标准格式、验证门规则 |
+| `skill-debugging.mdc` | 1.9KB | **调试技能（始终可用）**：信号解析（错误消息/复现步骤/影响区域/环境信息）、调试策略路由（PHP/API/DB/Vue/样式各有首选方式）、七步法核心流程（复现->收集->假设->验证->修复->回归）、硬停止条件、验证清单 |
+
+#### globs — 按文件类型自动注入（16 个）
+
+**编码规范类**（编辑对应类型文件时自动加载）：
+
+| 文件 | 匹配 globs | 作用 |
+|------|-----------|------|
+| `010-typescript.mdc` | `*.ts` `*.mjs` `*.vue` | **TypeScript 规范**：ES2022+ 语法、JSDoc 类型注释、命名约定（camelCase 变量/PascalCase 类型/UPPER_CASE 常量）、错误处理模式、import 排序 |
+| `011-vue.mdc` | `*.vue` `*/src/**/*.ts` | **Vue 3 规范 + 双前端上下文**：Composition API / Pinia / Composable 规范、Props 数据流模式（禁止直接修改 prop）、Emits camelCase 命名、单向数据流。内含双前端上下文规则：自动识别用户端（Headless UI + Tailwind，禁止 Element Plus）vs 管理端（Element Plus，权限守卫/二次确认/表单验证/分页），以及共享层约束（纯 TS，无 UI 依赖） |
+| `012-tailwind.mdc` | `*.vue` | **Tailwind CSS 规范**：类名排序、响应式设计、暗色模式、管理端 Element Plus 主题桥接、用户端纯 Tailwind |
+| `013-backend.mdc` | `*.php` | **Hyperf 后端规范**：分层架构（Controller->Service->Repository->Model）、依赖注入、RESTful API、认证授权、Swoole 协程安全 |
+| `014-database.mdc` | 数据库相关文件 | **数据库规范**：Hyperf ORM 使用、Migration 规范、查询优化、索引策略、高并发表设计 |
+| `015-testing.mdc` | `*.test.*` `*.spec.*` `__tests__/**` `phpunit.xml` | **测试规范（后端为主）**：通用测试原则（测行为/单一职责/不为覆盖率写无意义测试）、后端 PHPUnit 金字塔（Unit 60% / Integration 30% / Static 持续）、PHPStan 配置、AAA 模式、覆盖率目标。前端测试的具体工作流由 `skill-vue-testing.mdc` 负责 |
+| `016-swoole.mdc` | `*.php` | **Swoole 规范**：协程安全（禁止全局变量、static 状态）、连接池管理、Channel 通信、defer 用法、内存泄漏防护 |
+| `018-responsive.mdc` | `*.vue` | **响应式设计**：断点体系、移动优先策略、触摸目标尺寸、管理端 Element Plus 适配 |
+| `021-deployment.mdc` | `docker-compose*` `Dockerfile*` `.github/workflows/**` `.env*` | **部署规范**：Docker Compose 配置、CI/CD 流程、环境管理、蓝绿部署、PHP+Vue 双栈构建 |
+| `023-accessibility.mdc` | `*.vue` `*.html` | **无障碍规范**：WCAG AA 标准、语义化 HTML、ARIA 属性、键盘导航、Vue 3 无障碍实践 |
+| `026-secure-coding.mdc` | `*.php` `*.ts` `*.vue` | **安全编码**：SQL 注入防护、XSS 防护、禁用加密算法、IDOR/Mass Assignment 防护、Session 安全、文件上传校验 |
+
+**技能规则类**（编辑对应类型文件时自动加载执行摘要）：
+
+| 文件 | 匹配 globs | 作用 |
+|------|-----------|------|
+| `skill-backend-scaffold.mdc` | `**/Controller/**/*.php` `**/Service/**/*.php` `**/Repository/**/*.php` | **后端模块脚手架**（合并了原 api-scaffold + hyperf-service）：新建 API 端点或 Service 模块时激活。含完整执行流程（加载规范->确认规格->生成文件->事务/日志/重试）、分层约定、异常体系（Business/Validation/System）、验证清单 |
+| `skill-component-scaffold.mdc` | `**/components/**/*.vue` `**/composables/**/*.ts` | **Vue 组件脚手架**：新建组件或重大组件拆分时激活。含前端识别（管理端 Element Plus / 用户端 Headless UI）、文件结构输出、行数限制（SFC <= 150 行）、设计决策树 |
+| `skill-database-migration.mdc` | `**/migrations/**/*.php` | **数据库迁移**：Schema 变更时激活。安全等级 ORANGE。核心原则（每次变更都是迁移/Schema 与 Data 分离/迁移部署后不可变/新字段 nullable）、执行流程、验证清单 |
+| `skill-vue-page.mdc` | `**/router/**/*.ts` `**/views/**/*.vue` | **Vue 页面脚手架**：新建路由页面时激活。含强制拆分分析（多视图检测/行数预估/重复 UI 检测）、文件结构输出、页面类型（list/detail/form/dashboard/multi-view） |
+| `skill-vue-testing.mdc` | `**/*.test.*` `**/__tests__/**` | **前端测试工作流**：新建或更新测试文件时激活。含测试决策树（纯函数->单元/UI 交互->组件/跨页面->E2E）、核心原则（逻辑提取/穷举排列/AAA/单一行为）、增量式工作流、覆盖率目标 |
+
+#### SEMANTIC — 按用户意图语义匹配（12 个）
+
+Cursor 根据用户消息的语义自动判断是否注入，无需文件匹配。
+
+**编码规范类**：
+
+| 文件 | 触发场景 | 作用 |
+|------|---------|------|
+| `017-architecture.mdc` | 讨论水平扩展、限流降级、熔断、高可用架构 | **百万级并发架构**：无状态服务、读写分离、缓存策略、队列削峰、灰度发布 |
+| `019-modular.mdc` | 新建模块、讨论架构设计、模块划分、依赖方向 | **模块化架构**：DDD 边界、依赖方向单向、循环依赖检测、文件拆分阈值 |
+| `020-git.mdc` | 讨论 Git 操作、分支策略、提交规范 | **Git 规范**：分支策略（Git Flow）、Conventional Commits、PR 模板 |
+| `022-performance.mdc` | 报告页面慢、打包体积大、性能优化、Core Web Vitals | **性能规范 + 审计流程**（合并了原 skill-performance-audit）：诊断流程（基线收集->四维度审计->输出建议）+ 编码规范（Vite 构建/Swoole 调优/数据库查询/缓存/Nginx/连接池） |
+| `024-monitoring.mdc` | 讨论日志、监控、告警、Sentry | **日志与监控**：Hyperf Monolog 配置、Vue 3 错误处理、Swoole 监控、告警策略 |
+| `025-licensing.mdc` | 讨论版权、许可证、素材合规 | **版权合规**：许可证白名单/黑名单、字体/图标/图片素材选用规范 |
+
+**技能规则类**：
+
+| 文件 | 触发场景 | 作用 |
+|------|---------|------|
+| `030-subagents.mdc` | 需要委托子任务给独立 Agent 并行执行 | **Subagent 编排**：调用方式（Read agents/*.md -> Task 工具）、3 个可用 Subagent（repo-scout/test-runner/security-sentinel）、使用模式（清洁上下文/并行/链式/扇出） |
+| `033-refactoring.mdc` | 重构代码、清理技术债、优化代码结构 | **安全重构工作流**（合并了 SKILL.md 内容）：黄金规则（行为不变/小步快跑/测试先行）、坏味道与重构手法对照表（10 种模式）、禁止事项、验证清单 |
+| `skill-code-review.mdc` | 要求 review 代码、检查质量、审查 PR | **六维度代码审查**：安全性->正确性->可维护性->性能->可测试性->一致性，含预提交检查命令和结构化输出格式 |
+| `skill-full-feature.mdc` | 端到端功能开发（数据库到 API 到 UI） | **全链路功能开发**：Phase 1 规划 -> Phase 2 数据层 -> Phase 3 后端 API -> Phase 4 前端 UI -> Phase 5 集成验证 -> Phase 6 收尾。自动编排其他技能协同 |
+| `skill-i18n.mdc` | 添加多语言支持、翻译、vue-i18n | **国际化**：i18n 初始化流程、键命名公式（{feature}.{context}.{action}）、标准命名空间、验证清单 |
+| `skill-security-audit.mdc` | 安全审查、漏洞扫描、OWASP 检查 | **安全审计**：安全等级 RED、依赖扫描、OWASP Top 10 逐项检查、PHP/前端/密钥扫描、中间件链验证、分级输出报告 |
+
+### 两层架构说明
+
+v4.0 引入两层技能激活机制，解决了技能命中率低的问题：
+
+```
+自动激活层（skill-*.mdc）— Cursor 通过 globs/description 自动注入
+  ↓ 精简执行摘要，Agent 直接遵循
+  ↓ 需要完整模板时...
+按需加载层（SKILL.md）— Agent 主动 Read 获取完整详情
+```
+
+每个 `skill-*.mdc` 顶部都标注了对应 SKILL.md 的路径，Agent 需要深度参考时可自行 Read。
+
+---
+
+## Skills 技能系统
+
+Skills 定义**可复用的任务工作流**，控制 AI **怎么完成任务**。共 23 个技能，位于 `.cursor/skills/`。
+
+### 与 Rules 的区别
+
+| | Rules (.mdc) | Skills (SKILL.md) |
+|---|---|---|
+| **职责** | 编码规范 + 执行摘要 | 完整任务工作流 + 模板 |
+| **加载** | Cursor 平台自动注入 | Agent 按需 Read |
+| **解决** | "代码怎么写" | "任务怎么完成（完整版）" |
+
+### 两层加载
+
+```
+Tier 1 — 自动激活:  skill-*.mdc 精简摘要，Cursor 自动注入  (~1-2KB/个)
+Tier 2 — 按需深入:  SKILL.md 完整流程 + references/ 深度参考 (~2-8KB/个)
+```
+
+13 个高频技能有 `.mdc` 自动激活入口（见上方 Rules 清单），其余 10 个低频技能需要 Agent 手动 Read。
+
+### 技能清单
+
+**已有 .mdc 自动激活入口的技能（13 个）**：
+
+| 技能 | 激活方式 | 说明 |
+|------|---------|------|
+| `debugging` | alwaysApply | 七步法系统化调试 |
+| `component-scaffold` | globs | Vue 3 SFC 组件脚手架 |
+| `vue-page` | globs | Vue Router 页面脚手架 |
+| `api-scaffold` | globs（via backend-scaffold） | Hyperf API 端点脚手架 |
+| `hyperf-service` | globs（via backend-scaffold） | Hyperf Service 模块脚手架 |
+| `database-migration` | globs | Hyperf 数据库迁移 |
+| `vue-testing` | globs | Vitest 前端测试工作流 |
+| `code-review` | SEMANTIC | 六维度代码审查 |
+| `full-feature` | SEMANTIC | 端到端功能开发 |
+| `refactoring` | SEMANTIC（via 033-refactoring） | 安全重构工作流 |
+| `security-audit` | SEMANTIC | OWASP 安全审计 |
+| `performance-audit` | SEMANTIC（via 022-performance） | 性能审计流程 |
+| `i18n` | SEMANTIC | 国际化工作流 |
+
+> `api-scaffold` 和 `hyperf-service` 合并为 `skill-backend-scaffold.mdc`；`performance-audit` 合并到 `022-performance.mdc`；`refactoring` 合并到 `033-refactoring.mdc`。
+
+**仅 SKILL.md 按需加载的技能（10 个）**：
+
+| 技能 | 触发场景 | 说明 |
+|------|---------|------|
+| `anti-scraping` | 反爬虫/Bot 防护 | T1~T5 五级反爬虫策略 |
+| `bug-reproduce` | 复现 Bug/回归测试 | 结构化复现框架，不修复 |
+| `documentation` | 写文档/README/ADR | 结构化文档生成 |
+| `env-setup` | 环境配置/项目初始化 | PHP+Node 双栈环境初始化 |
+| `mcp-builder` | 构建 MCP Server | TypeScript MCP SDK 封装 |
+| `message-queue` | 消息队列/异步任务 | Hyperf AsyncQueue + Redis |
+| `nginx-config` | 配置 Nginx/反向代理 | SSL/Gzip/安全头/负载均衡 |
+| `redis-cache` | 添加 Redis 缓存 | Cache-Aside/分布式锁/连接池 |
+| `skill-creator` | 创建新技能 | 生成符合规范的 SKILL.md |
+| `websocket-service` | WebSocket/实时通信 | Swoole WebSocket 服务 |
+
+### 使用方式
+
+**自然语言触发**（推荐）— 直接描述任务，AI 自动匹配技能
+
+**显式调用** — `/skill-name` 或 `@skill-name`
+
+**管理脚本**：
+
+```bash
+bash scripts/skill-manager.sh list       # 列出所有技能
+bash scripts/skill-manager.sh validate   # 验证格式合规性
+bash scripts/skill-manager.sh stats      # 查看统计信息
+bash scripts/skill-manager.sh create <name>  # 创建新技能
+```
+
+### 创建自定义技能
+
+```
+.cursor/skills/my-skill/
+├── SKILL.md          # 必须：主流程 + 验证，含 YAML frontmatter
+├── references/       # 可选：深度内容（模板、示例）
+├── scripts/          # 可选：自动化脚本
+└── assets/           # 可选：模板文件
+```
+
+```yaml
+---
+name: my-skill
+description: "做什么 + 什么时候用（< 250 字符）"
+requires: [dep-skill]  # 可选：声明依赖
+---
+```
+
+---
+
+## Subagents 任务委托
+
+Subagents 通过 `Task` 工具将子任务委托给独立 Agent 执行，实现上下文隔离和并行处理。
+
+### 内置 3 个委托模板
+
+位于 `.cursor/agents/`：
+
+| Agent | 职责 | 模式 |
+|-------|------|------|
+| `repo-scout` | 代码库探索、文件定位 | 只读 |
+| `test-runner` | 运行测试、分析失败 | 读写（后台） |
+| `security-sentinel` | 安全扫描、密钥泄漏检测 | 只读 |
+
+### 编排模式
+
+- **链式**：Repo Scout 探索 -> 主 Agent 实现 -> Test Runner 验证
+- **扇出**：同一任务拆分给多个 Agent 并行处理
+
+---
+
+## MCP 服务配置
+
+`.cursor/mcp.json` 配置 AI 可调用的外部工具。
+
+### 已启用服务
+
+| 服务 | 用途 |
+|------|------|
+| `context7` | 获取最新库/框架文档 |
+| `filesystem` | 文件系统读写 |
+| `git` | Git 仓库操作 |
+| `fetch` | 网络请求 |
+| `memory` | 跨对话知识图谱记忆 |
+| `sequential-thinking` | 复杂问题分步推理 |
+
+### 按需启用（需凭证）
+
+| 服务 | 用途 | 配置项 |
+|------|------|--------|
+| `github` | PR / Issue 管理 | `GITHUB_TOKEN` |
+| `mysql` | 直接查询数据库 | 连接信息 |
+| `brave-search` | 网页搜索 | `BRAVE_API_KEY` |
+| `playwright` | 浏览器自动化 | 按需 |
+
+---
+
+## 文档知识库
+
+`docs/` 目录是项目的结构化知识库，AI 按需读取以理解业务背景。
+
+```
+docs/
+├── vision/
+│   ├── PRD.md                    # 产品需求
+│   └── roadmap.md                # 路线图
+├── architecture/
+│   ├── system-design.md          # 系统架构
+│   ├── data-model.md             # 数据模型
+│   ├── api-contracts.md          # API 契约
+│   ├── frontend-strategy.md      # 双前端架构策略
+│   └── decisions/                # ADR 架构决策记录
+├── guides/
+│   ├── style-guide.md            # 代码风格
+│   ├── ui-specs-user.md          # 用户端 UI 规范
+│   ├── ui-specs-admin.md         # 管理端 UI 规范
+│   └── testing-strategy.md       # 测试策略
+├── reference/                    # 参考文档
+└── runbooks/                     # 运维手册
+```
+
+---
+
+## 自动化脚本
+
+所有脚本位于 `scripts/`，纯 Bash 实现。
+
+| 脚本 | 用途 |
+|------|------|
+| `setup.sh` | 一键初始化：创建目录结构、配置 Git Hooks |
+| `ai-guard.sh` | 质量门禁：Lint + 类型检查 + 测试 + 安全扫描 |
+| `skill-manager.sh` | Skills 管理：列出/验证/统计/创建 |
+| `pre-commit` | Git pre-commit Hook |
+| `context-doctor.sh` | 健康检查：验证规则/技能/MCP 配置 |
+
+---
+
+## 项目结构
+
+```text
+vibe-cursor-pro/
+│
+├── .cursor/                              # Cursor 配置中心
+│   ├── rules/                            # 33 个 .mdc 规则文件
+│   │   ├── 000-constitution.mdc          # [alwaysApply] AI 宪法
+│   │   ├── 001-workflow.mdc              # [alwaysApply] PRISM 工作流
+│   │   ├── 002-safety.mdc               # [alwaysApply] 安全权限
+│   │   ├── 003-skills.mdc               # [alwaysApply] Skills 微索引
+│   │   ├── 010-typescript.mdc            # [globs] TypeScript 规范
+│   │   ├── 011-vue.mdc                   # [globs] Vue 3 规范 + 双前端上下文
+│   │   ├── 012-tailwind.mdc              # [globs] Tailwind CSS 规范
+│   │   ├── 013-backend.mdc              # [globs] Hyperf 后端规范
+│   │   ├── 014-database.mdc             # [globs] 数据库规范
+│   │   ├── 015-testing.mdc              # [globs] 测试规范（后端为主）
+│   │   ├── 016-swoole.mdc               # [globs] Swoole 协程规范
+│   │   ├── 017-architecture.mdc          # [SEMANTIC] 并发架构设计
+│   │   ├── 018-responsive.mdc            # [globs] 响应式设计
+│   │   ├── 019-modular.mdc              # [SEMANTIC] 模块化架构
+│   │   ├── 020-git.mdc                  # [SEMANTIC] Git 规范
+│   │   ├── 021-deployment.mdc            # [globs] 部署规范
+│   │   ├── 022-performance.mdc           # [SEMANTIC] 性能规范+审计流程
+│   │   ├── 023-accessibility.mdc         # [globs] 无障碍规范
+│   │   ├── 024-monitoring.mdc            # [SEMANTIC] 日志与监控
+│   │   ├── 025-licensing.mdc             # [SEMANTIC] 版权合规
+│   │   ├── 026-secure-coding.mdc         # [globs] 安全编码
+│   │   ├── 030-subagents.mdc             # [SEMANTIC] Subagent 编排
+│   │   ├── 033-refactoring.mdc           # [SEMANTIC] 安全重构工作流
+│   │   ├── skill-backend-scaffold.mdc    # [globs] 后端模块脚手架
+│   │   ├── skill-code-review.mdc         # [SEMANTIC] 代码审查
+│   │   ├── skill-component-scaffold.mdc  # [globs] Vue 组件脚手架
+│   │   ├── skill-database-migration.mdc  # [globs] 数据库迁移
+│   │   ├── skill-debugging.mdc           # [alwaysApply] 调试技能
+│   │   ├── skill-full-feature.mdc        # [SEMANTIC] 全链路功能开发
+│   │   ├── skill-i18n.mdc               # [SEMANTIC] 国际化
+│   │   ├── skill-security-audit.mdc      # [SEMANTIC] 安全审计
+│   │   ├── skill-vue-page.mdc            # [globs] Vue 页面脚手架
+│   │   ├── skill-vue-testing.mdc         # [globs] 前端测试工作流
+│   │   └── references/                   # 规则深度内容（Tier 3）
+│   │
+│   ├── skills/                           # 23 个技能（SKILL.md + references/）
+│   │   ├── api-scaffold/                 # API 端点脚手架
+│   │   ├── anti-scraping/                # 反爬虫防护
+│   │   ├── bug-reproduce/                # Bug 复现框架
+│   │   ├── code-review/                  # 代码审查
+│   │   ├── component-scaffold/           # Vue 组件脚手架
+│   │   ├── database-migration/           # 数据库迁移
+│   │   ├── debugging/                    # 调试工作流
+│   │   ├── documentation/                # 文档生成
+│   │   ├── env-setup/                    # 环境初始化
+│   │   ├── full-feature/                 # 全链路功能开发
+│   │   ├── hyperf-service/               # Hyperf Service 模块
+│   │   ├── i18n/                         # 国际化
+│   │   ├── mcp-builder/                  # MCP Server 构建
+│   │   ├── message-queue/                # 消息队列
+│   │   ├── nginx-config/                 # Nginx 配置
+│   │   ├── performance-audit/            # 性能审计
+│   │   ├── redis-cache/                  # Redis 缓存
+│   │   ├── refactoring/                  # 重构工作流
+│   │   ├── security-audit/               # 安全审计
+│   │   ├── skill-creator/                # 创建新技能
+│   │   ├── vue-page/                     # Vue 页面脚手架
+│   │   ├── vue-testing/                  # 前端测试
+│   │   └── websocket-service/            # WebSocket 服务
+│   │
+│   ├── agents/                           # 3 个 Subagent 模板
+│   │   ├── repo-scout.md                 # 代码库探索
+│   │   ├── test-runner.md                # 测试执行
+│   │   └── security-sentinel.md          # 安全扫描
+│   │
+│   └── mcp.json                          # MCP 服务配置
+│
+├── docs/                                 # 项目知识库
+├── scripts/                              # 自动化脚本
+│
+├── Case-Database-Backend/                # Hyperf 后端（gitignored）
+├── Case-Database-Frontend-user/          # Vue 3 用户端（gitignored）
+├── Case-Database-Frontend-admin/         # Vue 3 管理端（gitignored）
+├── Case-Database-Frontend-shared/        # 共享层（gitignored）
+│
+├── .cursorignore                         # Cursor 索引排除
+├── .gitignore
+├── .editorconfig
+├── .prettierrc
+├── commitlint.config.ts
+└── README.md
+```
+
+---
+
+## 定制化指南
+
+### 适配不同技术栈
+
+宪法级规则（000-003）和大部分技能都是技术栈无关的。
+
+**需要替换的文件**：
+
+| 文件 | 修改内容 |
+|------|---------|
+| `010-typescript.mdc` | 替换为对应语言规范 |
+| `011-vue.mdc` | 替换为 React / Svelte / Angular 规范 |
+| `012-tailwind.mdc` | 替换为你的 CSS 方案 |
+| `013-backend.mdc` | 替换为 Node.js / Go / Java 后端规范 |
+| `014-database.mdc` | 替换为 PostgreSQL / MongoDB 规范 |
+| `016-swoole.mdc` | 不使用 Swoole 可删除 |
+
+**不需要修改**：000-003 宪法级、020-git、023-accessibility、debugging/code-review/refactoring 等通用技能。
+
+### 添加新规则
+
+在 `.cursor/rules/` 下创建 `.mdc` 文件：
+
+```yaml
+---
+description: "规则描述（用于 SEMANTIC 匹配）"
+globs:                    # 可选：文件匹配模式
+  - "**/*.vue"
+alwaysApply: false        # 可选：是否始终加载
+---
+
+# 规则内容（Markdown）
+```
+
+### 添加新技能
+
+```bash
+bash scripts/skill-manager.sh create my-new-skill
+```
+
+---
+
+## 常见问题
+
+### Rules 没有生效？
+
+1. 确认扩展名为 `.mdc`
+2. 确认 YAML frontmatter 格式正确
+3. 运行 `bash scripts/context-doctor.sh`
+4. 重启 Cursor
+
+### Skills 没有自动触发？
+
+v4.0 引入了两层激活机制，13 个高频技能已有 `.mdc` 自动入口，应能自动触发。如仍未触发：
+
+1. 尝试显式调用：`/skill-name` 或 `@skill-name`
+2. 检查对应 `skill-*.mdc` 的 `description` 是否覆盖了你的使用场景
+3. 检查 SKILL.md 的 `description` 字段
+
+### Token 消耗太高？
+
+1. 检查 `alwaysApply: true` 的规则数量 — 仅保留 5 个（000/001/002/003/debugging）
+2. 当前 alwaysApply 总量约 12.6KB（~3,600 tokens），在合理范围内
+3. globs 触发的规则仅在编辑匹配文件时注入
+4. SEMANTIC 规则仅在用户意图匹配时注入
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| v4.0 | 2026-03-01 | **Skill 命中率优化三轮迭代**：引入两层激活机制（skill-*.mdc 自动注入 + SKILL.md 按需加载）；alwaysApply 从 32KB 降至 12.6KB（-60%）；消除 available_skills 幻觉概念；合并冗余规则（api-scaffold + hyperf-service -> backend-scaffold / 022-performance 吸收 audit / 011-vue 吸收 context / 015-testing 去重前端）；019-modular 和 017-architecture 从 globs 改 SEMANTIC 降低注入量；13 个技能有 .mdc 自动入口，10 个低频技能按需 Read；策略 B 双向标注（.mdc 指向 SKILL.md，SKILL.md 标注 .mdc）|
+| v3.7 | 2026-02-26 | 双前端架构适配：新增用户端/管理端/共享层目录和规则 |
+| v3.6 | 2026-02-26 | Workspace 模式（推荐）：vibe-cursor-pro 作为主工作区 |
+| v3.5 | 2026-02-24 | 全栈防爬（T1~T5）；新增 018/019/025 规则；版权合规 |
+| v3.4 | 2026-02-24 | 深度对齐旧项目分析报告 |
+| v3.3 | 2026-02-24 | PHPbase：迁移至 Vue 3 + PHP Hyperf + Swoole |
+| v3.0 | 2026-02-12 | Cursor 专属重构 |
diff --git a/commitlint.config.ts b/commitlint.config.ts
new file mode 100644
index 0000000..f71bf07
--- /dev/null
+++ b/commitlint.config.ts
@@ -0,0 +1,11 @@
+export default {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [2, 'always', [
+      'feat', 'fix', 'refactor', 'test', 'docs',
+      'chore', 'style', 'perf', 'ci', 'build', 'revert',
+    ]],
+    'subject-max-length': [2, 'always', 100],
+    'body-max-line-length': [1, 'always', 200],
+  },
+};
diff --git a/docs/architecture/api-contracts.md b/docs/architecture/api-contracts.md
new file mode 100644
index 0000000..a3d65d3
--- /dev/null
+++ b/docs/architecture/api-contracts.md
@@ -0,0 +1,869 @@
+# API Contracts — Hyperf RESTful API 契约
+
+> 定义 API 设计规范和端点文档。AI Agent 在生成 Controller 和前端 API 调用时参考本文档。
+>
+> **服务对象标注说明**：
+> - 🟦 `[user]` — 仅用户端（`Case-Database-Frontend-user/`）调用
+> - 🟧 `[admin]` — 仅管理端（`Case-Database-Frontend-admin/`）调用
+> - 🟩 `[both]` — 两个前端均可调用
+
+---
+
+## 1. 通用规范
+
+### Base URL
+```
+# 管理端 API
+开发: http://localhost:9501/admin
+生产: https://api.example.com/admin
+
+# 用户端 API
+开发: http://localhost:9501/api
+生产: https://api.example.com/api
+```
+
+### 统一响应格式
+
+**成功**
+```json
+{
+  "code": 200,
+  "message": "ok",
+  "data": {}
+}
+```
+
+**列表（带分页）**
+```json
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "items": [],
+    "total": 100
+  }
+}
+```
+
+**错误**
+```json
+{
+  "code": 422,
+  "message": "Validation failed",
+  "data": {
+    "errors": {
+      "email": ["The email field is required."]
+    }
+  }
+}
+```
+
+### HTTP 状态码
+
+| 状态码 | 含义 |
+|--------|------|
+| 200 | 成功 |
+| 201 | 创建成功 |
+| 400 | 请求参数错误 |
+| 401 | 未认证 (Token 无效/过期) |
+| 403 | 无权限 |
+| 404 | 资源不存在 |
+| 409 | 资源冲突 (锁定) |
+| 422 | 验证失败 |
+| 429 | 请求频率过高 |
+| 500 | 服务器内部错误 |
+
+### 认证
+
+所有需要认证的接口在 Header 中携带：
+```
+Authorization: Bearer <access_token>
+```
+
+Token 过期返回 `401`，客户端用 Refresh Token 刷新。
+
+### 分页参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `page` | int | 1 | 页码 |
+| `page_size` | int | 10 | 每页数量 (max: 100) |
+
+### 排序参数
+
+```
+?sort=created_at&order=desc
+```
+
+---
+
+## 2. 核心 API 端点
+
+### 2.1 🟦 用户端认证 `[user]` — 16 端点
+
+| 方法 | 路径 | 说明 | 认证 |
+|------|------|------|------|
+| POST | `/api/auth/captcha/challenge` | 获取图形验证码挑战（返回 `captcha_token`, `width`, `target_x`） | 否 |
+| POST | `/api/auth/captcha/verify` | 校验滑块位置（`captcha_token` + `answer_x`，tolerance=10px） | 否 |
+| POST | `/api/auth/register` | 用户注册 | 否 |
+| POST | `/api/auth/login` | 账号密码登录 | 否 |
+| POST | `/api/auth/sms/send` | 发送短信验证码 | 否 |
+| POST | `/api/auth/sms/login` | 短信验证码登录 | 否 |
+| POST | `/api/auth/forgot-password` | 忘记密码（账号/手机号校验后重置） | 否 |
+| POST | `/api/auth/logout` | 登出 | 是 |
+| POST | `/api/auth/refresh` | 刷新 Token | 否（需 Refresh Token） |
+| GET  | `/api/auth/profile` | 当前用户信息 | 是 |
+| PUT  | `/api/auth/profile` | 更新个人信息 | 是 |
+| GET  | `/api/auth/sessions` | 获取当前账号会话列表 | 是 |
+| POST | `/api/auth/sessions/:sessionId/revoke` | 踢出指定会话 | 是 |
+| GET  | `/api/auth/enterprise-sso/redirect` | 企业 SSO 跳转入口 | 否 |
+| POST | `/api/auth/enterprise-sso/callback` | 企业 SSO 回调登录 | 否 |
+| POST | `/api/auth/enterprise-sso/direct-login` | 企业平台直达登录（签名票据） | 否 |
+
+#### 认证请求字段约定
+
+- `/api/auth/register` 必填字段：`username`, `phone`, `sms_code`, `password`, `password_confirm`, `captcha_token`, `agree`。
+- `/api/auth/login` 必填字段：`username_or_phone`, `password`, `captcha_token`。
+- `/api/auth/sms/send` 必填字段：`phone`, `captcha_token`。
+- `/api/auth/sms/login` 必填字段：`phone`, `code`, `captcha_token`。
+- `/api/auth/forgot-password` 必填字段：`username_or_phone`, `phone`, `sms_code`, `new_password`, `new_password_confirm`, `captcha_token`。
+- 协议同意字段：`agree=true`，并由后端记录 `agree_at` 与 `agreement_version`。
+
+#### 认证限流策略
+
+| 接口 | 限流规则 |
+|------|----------|
+| 登录 `/api/auth/login` | 同 IP 5 次/分钟；同账号 10 次/小时 |
+| 短信发送 `/api/auth/sms/send` | 同手机号 1 次/分钟，5 次/天 |
+| 注册 `/api/auth/register` | 同 IP 3 次/小时 |
+| 找回密码 `/api/auth/forgot-password` | 同账号 3 次/天 |
+
+#### 第三方登录
+
+| 方法 | 路径 | 说明 | 认证 |
+|------|------|------|------|
+| GET  | `/api/auth/oauth/:provider` | OAuth 跳转（provider: wechat / qq） | 否 |
+| GET  | `/api/auth/oauth/:provider/callback` | OAuth 回调 | 否 |
+
+---
+
+### 2.2 🟦 用户端案例 `[user]` — 8 端点
+
+| 方法 | 路径 | 说明 | 认证 |
+|------|------|------|------|
+| GET  | `/api/cases` | 案例列表（支持多维筛选） | 否 |
+| GET  | `/api/cases/:id` | 案例详情 | 否 |
+| GET  | `/api/cases/:id/comments` | 案例评论列表 | 否 |
+| POST | `/api/cases/:id/comments` | 发表评论 | 是 |
+| POST | `/api/cases/:id/favorite` | 收藏 / 取消收藏 (toggle) | 是 |
+| POST | `/api/cases/:id/like` | 点赞 / 取消点赞 (toggle) | 是 |
+| GET  | `/api/cases/:id/related` | 相关推荐案例 | 否 |
+| GET  | `/api/cases/:id/files` | 案例文件列表（按阶段分组） | 否 |
+
+#### 案例列表筛选参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `category_id` | int | 建筑类型分类 |
+| `style` | string | 风格标签 slug |
+| `keyword` | string | 搜索关键词（标题 / 编号） |
+| `area_min` | number | 最小占地面积 |
+| `area_max` | number | 最大占地面积 |
+| `cost_min` | number | 最低造价 |
+| `cost_max` | number | 最高造价 |
+| `floors` | int | 层数 |
+| `bedroom_count` | int | 卧室数量 |
+| `site_width_min` | number | 最小面宽 |
+| `site_depth_min` | number | 最小进深 |
+| `tag_ids` | string | 标签 ID（逗号分隔） |
+| `is_featured` | boolean | 仅看精选 |
+| `sort` | string | 排序字段：`created_at` / `view_count` / `like_count` |
+| `order` | string | `asc` / `desc` |
+
+---
+
+### 2.3 🟦 用户端设计师 `[user]` — 4 端点
+
+| 方法 | 路径 | 说明 | 认证 |
+|------|------|------|------|
+| GET  | `/api/designers/:id` | 设计师详情 | 否 |
+| GET  | `/api/designers/:id/cases` | 设计师作品集 | 否 |
+| POST | `/api/designers/:id/follow` | 关注 / 取消关注 (toggle) | 是 |
+| GET  | `/api/designers/:id/awards` | 设计师荣誉奖项 | 否 |
+
+---
+
+### 2.4 🟦 用户端内容 `[user]` — 8 端点
+
+| 方法 | 路径 | 说明 | 认证 |
+|------|------|------|------|
+| GET  | `/api/banners` | 首页轮播列表 | 否 |
+| GET  | `/api/categories` | 分类列表 | 否 |
+| GET  | `/api/tags` | 标签列表（支持 `?type=style` 筛选） | 否 |
+| GET  | `/api/tags/hot` | 热门标签 | 否 |
+| GET  | `/api/topics` | 专题列表 | 否 |
+| GET  | `/api/topics/:id` | 专题详情（含关联案例列表） | 否 |
+| POST | `/api/newsletter/subscribe` | 邮箱订阅 | 否 |
+| GET  | `/api/my/favorites` | 我的收藏列表 | 是 |
+
+---
+
+### 2.5 🟧 管理端认证 `[admin]` — 4 端点
+
+| 方法 | 路径 | 说明 | 认证 |
+|------|------|------|------|
+| POST | `/admin/auth/login` | 管理员登录 | 否 |
+| POST | `/admin/auth/logout` | 登出 | 是 |
+| POST | `/admin/auth/refresh` | 刷新 Token | 否（需 Refresh Token） |
+| GET  | `/admin/auth/info` | 当前管理员信息（含角色权限） | 是 |
+
+---
+
+### 2.6 🟧 管理端案例管理 `[admin]` — 9 端点
+
+| 方法 | 路径 | 说明 | 权限 |
+|------|------|------|------|
+| GET  | `/admin/cases` | 案例列表（含草稿 / 待审 / 已发布 / 已归档筛选） | `case:list` |
+| GET  | `/admin/cases/:id` | 案例详情 | `case:detail` |
+| POST | `/admin/cases` | 创建案例 | `case:create` |
+| PUT  | `/admin/cases/:id` | 更新案例 | `case:update` |
+| DELETE | `/admin/cases/:id` | 删除案例（软删除） | `case:delete` |
+| PUT  | `/admin/cases/:id/status` | 变更案例状态 | `case:status` |
+| PUT  | `/admin/cases/:id/featured` | 精选标记 toggle | `case:feature` |
+| POST | `/admin/cases/:id/files` | 上传案例文件（分阶段） | `case:upload` |
+| DELETE | `/admin/cases/:id/files/:fileId` | 删除案例文件 | `case:upload` |
+
+---
+
+### 2.7 🟧 管理端轮播管理 `[admin]` — 5 端点
+
+| 方法 | 路径 | 说明 | 权限 |
+|------|------|------|------|
+| GET  | `/admin/banners` | 轮播列表 | `banner:list` |
+| POST | `/admin/banners` | 创建轮播 | `banner:create` |
+| PUT  | `/admin/banners/:id` | 更新轮播 | `banner:update` |
+| DELETE | `/admin/banners/:id` | 删除轮播 | `banner:delete` |
+| PUT  | `/admin/banners/sort` | 批量排序 | `banner:update` |
+
+---
+
+### 2.8 🟧 管理端专题管理 `[admin]` — 6 端点
+
+| 方法 | 路径 | 说明 | 权限 |
+|------|------|------|------|
+| GET  | `/admin/topics` | 专题列表 | `topic:list` |
+| POST | `/admin/topics` | 创建专题 | `topic:create` |
+| PUT  | `/admin/topics/:id` | 更新专题 | `topic:update` |
+| DELETE | `/admin/topics/:id` | 删除专题 | `topic:delete` |
+| POST | `/admin/topics/:id/cases` | 关联案例到专题 | `topic:update` |
+| DELETE | `/admin/topics/:id/cases/:caseId` | 取消关联案例 | `topic:update` |
+
+---
+
+### 2.9 🟧 管理端分类标签 `[admin]` — 7 端点
+
+| 方法 | 路径 | 说明 | 权限 |
+|------|------|------|------|
+| GET  | `/admin/categories` | 分类列表 | `category:list` |
+| POST | `/admin/categories` | 创建分类 | `category:create` |
+| PUT  | `/admin/categories/:id` | 更新分类 | `category:update` |
+| DELETE | `/admin/categories/:id` | 删除分类（需判断无关联案例） | `category:delete` |
+| GET  | `/admin/tags` | 标签列表（支持 `?type=` 筛选） | `tag:list` |
+| POST | `/admin/tags` | 创建标签 | `tag:create` |
+| PUT  | `/admin/tags/:id` | 更新标签 | `tag:update` |
+| DELETE | `/admin/tags/:id` | 删除标签 | `tag:delete` |
+
+---
+
+### 2.10 🟧 管理端设计师管理 `[admin]` — 5 端点
+
+| 方法 | 路径 | 说明 | 权限 |
+|------|------|------|------|
+| GET  | `/admin/designers` | 设计师列表 | `designer:list` |
+| POST | `/admin/designers` | 创建设计师 | `designer:create` |
+| PUT  | `/admin/designers/:id` | 更新设计师 | `designer:update` |
+| DELETE | `/admin/designers/:id` | 删除设计师 | `designer:delete` |
+| PUT  | `/admin/designers/:id/active` | 启用/停用设计师 | `designer:update` |
+
+---
+
+### 2.11 🟧 管理端评论管理 `[admin]` — 4 端点
+
+| 方法 | 路径 | 说明 | 权限 |
+|------|------|------|------|
+| GET  | `/admin/comments` | 评论列表（支持 `?status=pending` 筛选） | `comment:list` |
+| PUT  | `/admin/comments/:id/approve` | 审核通过 | `comment:audit` |
+| PUT  | `/admin/comments/:id/reject` | 审核拒绝 | `comment:audit` |
+| DELETE | `/admin/comments/:id` | 删除评论 | `comment:delete` |
+
+---
+
+### 2.12 🟧 管理端用户与权限 `[admin]` — 8 端点
+
+| 方法 | 路径 | 说明 | 权限 |
+|------|------|------|------|
+| GET  | `/admin/users` | 用户列表 | `user:list` |
+| POST | `/admin/users` | 创建管理员 | `user:create` |
+| PUT  | `/admin/users/:id` | 更新用户 | `user:update` |
+| PUT  | `/admin/users/:id/status` | 启用/禁用用户 | `user:update` |
+| GET  | `/admin/roles` | 角色列表 | `role:list` |
+| POST | `/admin/roles` | 创建角色（含菜单权限分配） | `role:create` |
+| PUT  | `/admin/roles/:id` | 更新角色 | `role:update` |
+| GET  | `/admin/menus` | 菜单权限树 | `menu:list` |
+
+---
+
+### 2.13 🟧 管理端系统配置 `[admin]` — 2 端点
+
+| 方法 | 路径 | 说明 | 权限 |
+|------|------|------|------|
+| GET  | `/admin/configs` | 获取系统配置（支持 `?group=site` 筛选） | `config:list` |
+| PUT  | `/admin/configs` | 批量更新系统配置 | `config:update` |
+
+---
+
+### 2.14 🟧 管理端数据仪表盘 `[admin]` — 3 端点
+
+| 方法 | 路径 | 说明 | 权限 |
+|------|------|------|------|
+| GET  | `/admin/dashboard/overview` | 概览统计（总案例数 / 总用户数 / 今日浏览量等） | `dashboard:view` |
+| GET  | `/admin/dashboard/trends` | 趋势数据（按日/周/月的浏览 / 注册曲线） | `dashboard:view` |
+| GET  | `/admin/dashboard/rankings` | 热门排行（案例浏览 TOP / 下载 TOP / 活跃设计师） | `dashboard:view` |
+
+---
+
+### 2.15 🟧 管理端日志 `[admin]` — 2 端点
+
+| 方法 | 路径 | 说明 | 权限 |
+|------|------|------|------|
+| GET  | `/admin/logs/operations` | 操作日志列表 | `log:list` |
+| GET  | `/admin/logs/downloads` | 下载日志列表 | `log:list` |
+
+---
+
+### 2.16 🟩 通用上传 `[both]` — 1 端点
+
+| 方法 | 路径 | 说明 | 认证 |
+|------|------|------|------|
+| POST | `/api/upload/image` | 上传图片（头像/封面/banner） | 是 |
+
+---
+
+## 3. 请求/响应示例
+
+### 3.1 管理端登录
+
+```bash
+POST /admin/auth/login
+Content-Type: application/json
+
+{
+  "username": "admin",
+  "password": "password123"
+}
+
+# Response 200
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "access_token": "eyJhbGci...",
+    "refresh_token": "eyJhbGci...",
+    "expires_in": 7200,
+    "user": {
+      "id": 1,
+      "username": "admin",
+      "nickname": "超级管理员",
+      "avatar": "https://cdn.example.com/avatars/admin.jpg",
+      "roles": ["super_admin"],
+      "permissions": ["case:*", "banner:*", "topic:*"]
+    }
+  }
+}
+```
+
+### 3.2 用户端登录（账号密码）
+
+```bash
+POST /api/auth/login
+Content-Type: application/json
+
+{
+  "phone": "13800138000",
+  "password": "password123"
+}
+
+# Response 200
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "access_token": "eyJhbGci...",
+    "refresh_token": "eyJhbGci...",
+    "expires_in": 7200,
+    "user": {
+      "id": 42,
+      "nickname": "建筑师小李",
+      "avatar": "https://cdn.example.com/avatars/42.jpg",
+      "phone": "138****8000",
+      "role_label": "Architect"
+    }
+  }
+}
+```
+
+### 3.3 用户端短信登录
+
+```bash
+# Step 1: 发送验证码
+POST /api/auth/sms/send
+Content-Type: application/json
+
+{
+  "phone": "13800138000"
+}
+
+# Response 200
+{
+  "code": 200,
+  "message": "验证码已发送",
+  "data": {
+    "expires_in": 300
+  }
+}
+
+# Step 2: 验证码登录
+POST /api/auth/sms/login
+Content-Type: application/json
+
+{
+  "phone": "13800138000",
+  "code": "123456"
+}
+
+# Response 200 (同 3.2 登录响应)
+```
+
+### 3.4 案例列表（多维筛选）
+
+```bash
+GET /api/cases?category_id=1&style=modern&area_min=100&area_max=300&cost_max=60&floors=3&sort=created_at&order=desc&page=1&page_size=12
+Authorization: Bearer eyJhbGci...  (可选)
+
+# Response 200
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "items": [
+      {
+        "id": 88,
+        "title": "云端墅 The Cloud Villa",
+        "code": "P-2024-8839",
+        "cover_image": "https://cdn.example.com/cases/88/cover.jpg",
+        "category": {
+          "id": 1,
+          "name": "别墅",
+          "slug": "villa"
+        },
+        "layout": "3室2厅3卫",
+        "floors_above": 3,
+        "site_area": 128.50,
+        "total_building_area": 340.00,
+        "cost_min": 45.00,
+        "cost_max": 55.00,
+        "architecture_style": "现代主义",
+        "is_featured": true,
+        "tags": [
+          { "id": 1, "name": "现代", "type": "style" },
+          { "id": 5, "name": "落地窗", "type": "feature" }
+        ],
+        "lead_designer": {
+          "id": 12,
+          "name_cn": "张明远",
+          "title_badge": "Lead Architect"
+        },
+        "view_count": 1234,
+        "like_count": 56,
+        "favorite_count": 23,
+        "is_liked": false,
+        "is_favorited": true,
+        "published_at": "2024-12-15T10:00:00Z"
+      }
+    ],
+    "total": 156
+  }
+}
+```
+
+### 3.5 案例详情
+
+```bash
+GET /api/cases/88
+Authorization: Bearer eyJhbGci...  (可选)
+
+# Response 200
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "id": 88,
+    "title": "云端墅 The Cloud Villa",
+    "code": "P-2024-8839",
+    "cover_image": "https://cdn.example.com/cases/88/cover.jpg",
+    "category": { "id": 1, "name": "别墅", "slug": "villa" },
+    "status": "published",
+    "is_featured": true,
+    "layout": "3室2厅3卫",
+    "floor_height": "3.6/3.3/3.3m",
+
+    "dimensions": {
+      "site": {
+        "site_width": "面宽 ≥ 10.5m",
+        "site_depth": "进深 ≥ 12.2m",
+        "site_area": 128.50,
+        "lighting_restriction": "南侧无遮挡",
+        "site_shape": "规则矩形"
+      },
+      "scale": {
+        "floors_above": 3,
+        "floors_below": 1,
+        "cost_min": 45.00,
+        "cost_max": 55.00,
+        "total_building_area": 340.00,
+        "bedroom_count": 5,
+        "bedroom_note": "含1主卧套房"
+      },
+      "function": {
+        "stair_type": "旋转楼梯 + 电梯",
+        "special_space": "地下影音室 / 露台花园",
+        "bedroom_config": "主卧套房含衣帽间",
+        "leisure_space": "屋顶露台 / 下沉式客厅",
+        "kitchen_dining": "开放式西厨 + 独立中厨",
+        "bathroom_config": "5卫 (含2套干湿分离)"
+      },
+      "appearance": {
+        "architecture_style": "现代主义",
+        "roof_type": "平屋顶 + 局部坡屋顶",
+        "facade_material": "白色真石漆 + 深灰铝板"
+      },
+      "structure": {
+        "structure_type": "框架结构",
+        "foundation_type": "筏板基础",
+        "layout_logic": "南北通透 / 动静分区",
+        "wall_thickness": "240mm (外) + 120mm (内)",
+        "seismic_rating": "7度设防",
+        "insulation_type": "外墙外保温 EPS",
+        "roof_structure": "SBS防水 + 挤塑板保温"
+      }
+    },
+
+    "design_concept": "<p>设计理念正文...</p>",
+    "concept_style": "现代主义",
+    "concept_material": "混凝土 / 玻璃 / 石材",
+    "concept_target": "追求品质生活的年轻家庭",
+    "meta": {},
+
+    "images": {
+      "effect": [
+        { "id": 1, "url": "https://cdn.example.com/cases/88/effect-1.jpg", "thumbnail_url": "..." }
+      ],
+      "floor_plan": [
+        { "id": 2, "url": "https://cdn.example.com/cases/88/plan-1f.jpg", "thumbnail_url": "..." }
+      ],
+      "elevation": [
+        { "id": 3, "url": "https://cdn.example.com/cases/88/elev-south.jpg", "thumbnail_url": "..." }
+      ]
+    },
+
+    "files": {
+      "floor_plan": [
+        { "id": 1, "file_name": "一层平面图.dwg", "file_ext": "dwg", "file_size": 2048000 }
+      ],
+      "exterior": [],
+      "construction": [
+        { "id": 2, "file_name": "施工图全套.pdf", "file_ext": "pdf", "file_size": 15360000 }
+      ],
+      "structure": [],
+      "interior": [],
+      "courtyard": []
+    },
+
+    "team": [
+      {
+        "designer": {
+          "id": 12,
+          "name_cn": "张明远",
+          "name_en": "Zhang Mingyuan",
+          "title": "方案主创设计师",
+          "title_badge": "Lead Architect",
+          "portrait": "https://cdn.example.com/designers/12/portrait.jpg"
+        },
+        "role": "scheme",
+        "is_lead": true
+      },
+      {
+        "designer": {
+          "id": 15,
+          "name_cn": "李结构",
+          "title": "结构工程师",
+          "title_badge": "Structural Eng."
+        },
+        "role": "structure",
+        "is_lead": false
+      }
+    ],
+
+    "tags": [
+      { "id": 1, "name": "现代", "type": "style" },
+      { "id": 5, "name": "落地窗", "type": "feature" }
+    ],
+
+    "stats": {
+      "view_count": 1234,
+      "like_count": 56,
+      "favorite_count": 23,
+      "download_count": 8,
+      "comment_count": 12
+    },
+
+    "user_interaction": {
+      "is_liked": false,
+      "is_favorited": true
+    },
+
+    "published_at": "2024-12-15T10:00:00Z",
+    "created_at": "2024-12-10T08:00:00Z"
+  }
+}
+```
+
+### 3.6 管理端文件上传（分阶段）
+
+```bash
+POST /admin/cases/88/files
+Authorization: Bearer eyJhbGci...
+Content-Type: multipart/form-data
+
+# Form Data
+stage: construction
+file: (binary) 施工图全套.pdf
+
+# Response 201
+{
+  "code": 201,
+  "message": "上传成功",
+  "data": {
+    "id": 156,
+    "case_id": 88,
+    "stage": "construction",
+    "file_name": "施工图全套.pdf",
+    "file_path": "cases/88/construction/施工图全套.pdf",
+    "file_size": 15360000,
+    "file_ext": "pdf",
+    "mime_type": "application/pdf"
+  }
+}
+```
+
+### 3.7 管理端创建案例
+
+```bash
+POST /admin/cases
+Authorization: Bearer eyJhbGci...
+Content-Type: application/json
+
+{
+  "title": "云端墅 The Cloud Villa",
+  "code": "P-2024-8839",
+  "category_id": 1,
+  "cover_image": "https://cdn.example.com/cases/88/cover.jpg",
+  "layout": "3室2厅3卫",
+  "floor_height": "3.6/3.3/3.3m",
+  "site_width": "面宽 ≥ 10.5m",
+  "site_depth": "进深 ≥ 12.2m",
+  "site_area": 128.50,
+  "floors_above": 3,
+  "floors_below": 1,
+  "cost_min": 45.00,
+  "cost_max": 55.00,
+  "total_building_area": 340.00,
+  "bedroom_count": 5,
+  "bedroom_note": "含1主卧套房",
+  "architecture_style": "现代主义",
+  "structure_type": "框架结构",
+  "design_concept": "<p>设计理念正文...</p>",
+  "tag_ids": [1, 5, 12],
+  "team": [
+    { "designer_id": 12, "role": "scheme", "is_lead": true },
+    { "designer_id": 15, "role": "structure", "is_lead": false }
+  ]
+}
+
+# Response 201
+{
+  "code": 201,
+  "message": "创建成功",
+  "data": {
+    "id": 88,
+    "code": "P-2024-8839",
+    "status": "draft"
+  }
+}
+```
+
+### 3.8 管理端案例状态变更
+
+```bash
+PUT /admin/cases/88/status
+Authorization: Bearer eyJhbGci...
+Content-Type: application/json
+
+{
+  "status": "published"
+}
+
+# Response 200
+{
+  "code": 200,
+  "message": "状态已更新",
+  "data": {
+    "id": 88,
+    "status": "published",
+    "published_at": "2024-12-15T10:00:00Z"
+  }
+}
+```
+
+### 3.9 设计师详情
+
+```bash
+GET /api/designers/12
+
+# Response 200
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "id": 12,
+    "name_cn": "张明远",
+    "name_en": "Zhang Mingyuan",
+    "title": "方案主创设计师",
+    "title_badge": "Lead Architect",
+    "company": "ZM 建筑事务所",
+    "city": "上海",
+    "portrait": "https://cdn.example.com/designers/12/portrait.jpg",
+    "portrait_caption": "STUDIO PORTRAIT © 2023",
+    "years_of_experience": 15,
+    "project_count": 42,
+    "design_philosophy_quote": "建筑是凝固的音乐",
+    "design_philosophy": "<p>设计理念详述...</p>",
+    "specialties": [
+      { "id": 20, "name": "参数化设计" },
+      { "id": 21, "name": "可持续建筑" }
+    ],
+    "awards": [
+      {
+        "year": 2023,
+        "title": "红点设计大奖 Red Dot Award",
+        "description": "最佳室内设计类 - The Cloud Villa"
+      },
+      {
+        "year": 2022,
+        "title": "Architizer A+ Awards",
+        "description": "住宅建筑类 - 山水间"
+      }
+    ],
+    "stats": {
+      "follower_count": 326,
+      "view_count": 8920,
+      "project_count": 42
+    },
+    "user_interaction": {
+      "is_followed": true
+    }
+  }
+}
+```
+
+### 3.10 管理端创建轮播
+
+```bash
+POST /admin/banners
+Authorization: Bearer eyJhbGci...
+Content-Type: application/json
+
+{
+  "title": "云端墅 — 现代都市别墅的极致诠释",
+  "description": "三层框架结构，340㎡ 全功能空间",
+  "image": "https://cdn.example.com/banners/cloud-villa.jpg",
+  "label": "精选项目",
+  "link_type": "case",
+  "link_url": "/cases/88",
+  "sort": 1,
+  "is_active": true
+}
+
+# Response 201
+{
+  "code": 201,
+  "message": "创建成功",
+  "data": {
+    "id": 5,
+    "title": "云端墅 — 现代都市别墅的极致诠释",
+    "sort": 1,
+    "is_active": true
+  }
+}
+```
+
+### 3.11 管理端仪表盘概览
+
+```bash
+GET /admin/dashboard/overview
+Authorization: Bearer eyJhbGci...
+
+# Response 200
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "total_cases": 256,
+    "published_cases": 198,
+    "total_designers": 42,
+    "total_users": 3680,
+    "today_views": 1250,
+    "today_registers": 15,
+    "pending_comments": 8,
+    "pending_cases": 3
+  }
+}
+```
+
+---
+
+## 4. 端点汇总统计
+
+| 分组 | 服务对象 | 端点数 |
+|------|----------|--------|
+| 用户端认证 | 🟦 user | 16 |
+| 用户端案例 | 🟦 user | 8 |
+| 用户端设计师 | 🟦 user | 4 |
+| 用户端内容 | 🟦 user | 8 |
+| 管理端认证 | 🟧 admin | 4 |
+| 管理端案例管理 | 🟧 admin | 9 |
+| 管理端轮播管理 | 🟧 admin | 5 |
+| 管理端专题管理 | 🟧 admin | 6 |
+| 管理端分类标签 | 🟧 admin | 8 |
+| 管理端设计师管理 | 🟧 admin | 5 |
+| 管理端评论管理 | 🟧 admin | 4 |
+| 管理端用户权限 | 🟧 admin | 8 |
+| 管理端系统配置 | 🟧 admin | 2 |
+| 管理端仪表盘 | 🟧 admin | 3 |
+| 管理端日志 | 🟧 admin | 2 |
+| 通用上传 | 🟩 both | 1 |
+| **合计** | | **93** |
+
+---
+
+*最后更新: 2026-02-28*
diff --git a/docs/architecture/data-model.md b/docs/architecture/data-model.md
new file mode 100644
index 0000000..7aa805c
--- /dev/null
+++ b/docs/architecture/data-model.md
@@ -0,0 +1,748 @@
+# Data Model — MySQL 数据建模
+
+> 定义数据库表结构、关系和设计约定。AI Agent 在生成 Migration 和 Model 时参考本文档。
+
+---
+
+## 1. 设计原则
+
+- 主键统一使用 `BIGINT UNSIGNED AUTO_INCREMENT`
+- 字符集 `utf8mb4`，排序规则 `utf8mb4_unicode_ci`
+- 所有表包含 `created_at`, `updated_at`, `deleted_at` (软删除)
+- 外键字段命名 `<table_singular>_id`，必须有索引
+- 金额字段使用 `DECIMAL(10,2)`
+- 状态字段使用 `VARCHAR(20)` 或 `TINYINT`（避免 ENUM）
+- 时间字段使用 `TIMESTAMP`
+- 排序字段使用 `INT UNSIGNED DEFAULT 0`
+
+## 2. 命名规范
+
+### 2.1 表命名规则
+
+**表名必须以所属模块名作为前缀**（snake_case），格式：`<module>_<entity_plural>`。
+
+| 模块 | 前缀 | 说明 |
+|------|------|------|
+| 用户与权限 | `auth_` | 用户、角色、菜单、OAuth 等 |
+| 案例核心 | `case_` | 案例主表、图库、文件、分类等 |
+| 设计师 | `designer_` | 设计师档案、奖项、标签关联等 |
+| 运营内容 | `operation_` | 轮播图、专题、标签字典等 |
+| 用户互动 | `interaction_` | 收藏、点赞、评论、关注、订阅等 |
+| 日志 | `log_` | 登录日志、操作日志、下载日志等 |
+| 安全风控 | `security_` | 黑名单、风控事件、会话等 |
+| 系统配置 | `system_` | 系统参数配置等 |
+
+> **规则说明**：
+> - 同一业务域下的所有表使用相同前缀，避免不同模块表名冲突
+> - 多对多关联表同样需要加模块前缀：`<module>_<a>_belongs_<b>`
+> - 跨模块关联的中间表，以**主体模块**的前缀命名
+
+### 2.2 通用命名约定
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 表名 | `<module>_` 前缀 + snake_case 复数 | `case_cases`, `auth_users` |
+| 字段名 | snake_case | `total_building_area` |
+| 主键 | `id` | `BIGINT UNSIGNED` |
+| 外键 | `<singular>_id` | `case_id`, `designer_id` |
+| 索引 | `idx_<table>_<cols>` | `idx_case_cases_status` |
+| 唯一索引 | `uk_<table>_<cols>` | `uk_case_cases_code` |
+| 多对多关联表 | `<module>_<a>_belongs_<b>` | `case_case_belongs_tag` |
+| 布尔字段 | `is_<adj>` | `is_featured`, `is_active` |
+| 计数缓存 | `<noun>_count` | `view_count`, `like_count` |
+
+### 2.3 各模块表名对照
+
+| 当前表名 | 所属模块 | 规范表名 |
+|----------|----------|----------|
+| `users` | 用户与权限 | `auth_users` |
+| `oauth_bindings` | 用户与权限 | `auth_oauth_bindings` |
+| `roles` | 用户与权限 | `auth_roles` |
+| `menus` | 用户与权限 | `auth_menus` |
+| `user_belongs_role` | 用户与权限 | `auth_user_belongs_role` |
+| `role_belongs_menu` | 用户与权限 | `auth_role_belongs_menu` |
+| `categories` | 案例核心 | `case_categories` |
+| `tags` | 运营内容 | `operation_tags` |
+| `cases` | 案例核心 | `case_cases` |
+| `case_images` | 案例核心 | `case_images`（已有前缀） |
+| `case_files` | 案例核心 | `case_files`（已有前缀） |
+| `case_belongs_tag` | 案例核心 | `case_belongs_tag`（已有前缀） |
+| `case_team_members` | 案例核心 | `case_team_members`（已有前缀） |
+| `designers` | 设计师 | `designer_profiles` |
+| `designer_awards` | 设计师 | `designer_awards`（已有前缀） |
+| `designer_belongs_tag` | 设计师 | `designer_belongs_tag`（已有前缀） |
+| `banners` | 运营内容 | `operation_banners` |
+| `topics` | 运营内容 | `operation_topics` |
+| `topic_belongs_case` | 运营内容 | `operation_topic_belongs_case` |
+| `favorites` | 用户互动 | `interaction_favorites` |
+| `likes` | 用户互动 | `interaction_likes` |
+| `comments` | 用户互动 | `interaction_comments` |
+| `follows` | 用户互动 | `interaction_follows` |
+| `newsletter_subscriptions` | 用户互动 | `interaction_newsletter_subscriptions` |
+| `user_login_logs` | 日志 | `log_user_logins` |
+| `admin_operation_logs` | 日志 | `log_admin_operations` |
+| `download_logs` | 日志 | `log_downloads` |
+| `user_sessions` | 安全风控 | `security_user_sessions` |
+| `security_risk_events` | 安全风控 | `security_risk_events`（已有前缀） |
+| `security_blacklists` | 安全风控 | `security_blacklists`（已有前缀） |
+| `system_configs` | 系统配置 | `system_configs`（已有前缀） |
+
+---
+
+## 3. ER 关系总览
+
+```
+用户与权限
+─────────
+users ←→ user_belongs_role ←→ roles
+  │                              │
+  └→ oauth_bindings        role_belongs_menu ←→ menus
+
+案例核心
+────────
+categories ←── cases ──→ case_images
+                │   └──→ case_files
+                │   └──→ case_belongs_tag ←── tags
+                │   └──→ case_team_members ──→ designers
+                │                               │
+                │                               └→ designer_awards
+                │                               └→ designer_belongs_tag ←── tags
+                │
+                └──→ favorites ←── users
+                └──→ likes ←── users
+                └──→ comments ←── users
+
+运营内容
+────────
+banners (独立)
+topics ←→ topic_belongs_case ←→ cases
+
+会话与安全
+──────────
+users ──→ user_sessions
+users ──→ security_risk_events
+security_blacklists (独立)
+
+日志与系统
+──────────
+user_login_logs
+admin_operation_logs
+download_logs
+system_configs
+newsletter_subscriptions
+```
+
+---
+
+## 4. 核心数据表
+
+### 4.1 用户与权限域
+
+#### `users` — 统一用户表
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK, AUTO_INCREMENT | |
+| `user_type` | VARCHAR(20) | NOT NULL, DEFAULT 'user' | user / admin |
+| `username` | VARCHAR(50) | NULL, UNIQUE | 登录账号 |
+| `phone` | VARCHAR(20) | NULL, UNIQUE | 手机号 |
+| `password` | VARCHAR(255) | NULL | bcrypt 哈希 |
+| `enterprise_user_id` | VARCHAR(100) | NULL, UNIQUE | 企业平台用户唯一标识 |
+| `source` | VARCHAR(20) | NOT NULL, DEFAULT 'local' | local / enterprise / wechat / qq |
+| `is_enterprise_linked` | TINYINT | NOT NULL, DEFAULT 0 | 是否已绑定企业账号 |
+| `nickname` | VARCHAR(50) | NULL | 显示昵称 |
+| `avatar` | VARCHAR(500) | NULL | 头像 URL |
+| `role_label` | VARCHAR(50) | NULL | 展示角色标签（如 Architect） |
+| `previous_password_hash` | VARCHAR(255) | NULL | 上次密码哈希（防重复使用） |
+| `agree_at` | TIMESTAMP | NULL | 用户同意协议时间 |
+| `agreement_version` | VARCHAR(30) | NULL | 同意时协议版本 |
+| `status` | TINYINT | NOT NULL, DEFAULT 1 | 1=启用, 0=禁用 |
+| `deactivation_requested_at` | TIMESTAMP | NULL | 注销申请时间（冷静期起始） |
+| `scheduled_deletion_at` | TIMESTAMP | NULL | 计划删除时间（冷静期结束） |
+| `last_login_at` | TIMESTAMP | NULL | |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+| `deleted_at` | TIMESTAMP | NULL | |
+
+索引：`uk_users_username`, `uk_users_phone`, `uk_users_enterprise_user_id`, `idx_users_user_type`, `idx_users_status`
+
+#### `oauth_bindings` — 第三方登录绑定
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `user_id` | BIGINT UNSIGNED | FK → users | |
+| `provider` | VARCHAR(20) | NOT NULL | wechat / qq / enterprise |
+| `provider_user_id` | VARCHAR(100) | NOT NULL | 第三方平台用户 ID |
+| `access_token` | VARCHAR(500) | NULL | |
+| `refresh_token` | VARCHAR(500) | NULL | |
+| `expires_at` | TIMESTAMP | NULL | |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+
+索引：`uk_oauth_provider_uid (provider, provider_user_id)`, `idx_oauth_user_id`
+
+#### `roles` — 角色表
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `name` | VARCHAR(50) | NOT NULL, UNIQUE | 角色标识：super_admin / content_ops / reviewer |
+| `display_name` | VARCHAR(50) | NOT NULL | 超级管理员 / 内容运营 / 审核员 |
+| `description` | VARCHAR(200) | NULL | |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+
+#### `menus` — 菜单/权限表
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `parent_id` | BIGINT UNSIGNED | DEFAULT 0 | 树形结构 |
+| `name` | VARCHAR(50) | NOT NULL | 权限标识 `case:create` |
+| `display_name` | VARCHAR(50) | NOT NULL | 菜单显示名 |
+| `type` | VARCHAR(10) | NOT NULL | menu / button |
+| `path` | VARCHAR(200) | NULL | 前端路由路径 |
+| `icon` | VARCHAR(50) | NULL | 图标名 |
+| `sort` | INT UNSIGNED | DEFAULT 0 | |
+| `is_visible` | TINYINT | DEFAULT 1 | |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+
+#### `user_belongs_role` — 用户-角色关联
+
+| 字段 | 类型 | 约束 |
+|------|------|------|
+| `user_id` | BIGINT UNSIGNED | PK(联合), FK → users |
+| `role_id` | BIGINT UNSIGNED | PK(联合), FK → roles |
+
+#### `role_belongs_menu` — 角色-菜单关联
+
+| 字段 | 类型 | 约束 |
+|------|------|------|
+| `role_id` | BIGINT UNSIGNED | PK(联合), FK → roles |
+| `menu_id` | BIGINT UNSIGNED | PK(联合), FK → menus |
+
+---
+
+### 4.2 案例核心域
+
+#### `categories` — 建筑类型分类
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `name` | VARCHAR(50) | NOT NULL, UNIQUE | 别墅 / 民宿 / 室内 / 景观 / 农村自建房 / 庭院 |
+| `slug` | VARCHAR(50) | NOT NULL, UNIQUE | villa / homestay / interior / landscape |
+| `icon` | VARCHAR(50) | NULL | |
+| `sort` | INT UNSIGNED | DEFAULT 0 | |
+| `case_count` | INT UNSIGNED | DEFAULT 0 | 缓存引用计数 |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+
+#### `tags` — 统一标签字典
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `type` | VARCHAR(20) | NOT NULL | style / feature / specialty |
+| `name` | VARCHAR(50) | NOT NULL | 现代 / 落地窗 / 参数化设计 |
+| `sort` | INT UNSIGNED | DEFAULT 0 | |
+| `reference_count` | INT UNSIGNED | DEFAULT 0 | 被引用次数 |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+
+索引：`uk_tags_type_name (type, name)`, `idx_tags_type`
+
+#### `cases` — 案例主表
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `category_id` | BIGINT UNSIGNED | FK → categories | 建筑类型 |
+| `title` | VARCHAR(200) | NOT NULL | 项目名称 |
+| `code` | VARCHAR(30) | NOT NULL, UNIQUE | 项目编号 P-2024-8839 |
+| `cover_image` | VARCHAR(500) | NULL | 封面图 URL |
+| `status` | VARCHAR(20) | NOT NULL, DEFAULT 'draft' | draft / pending / published / archived |
+| `is_featured` | TINYINT | DEFAULT 0 | 是否精选 |
+| `featured_sort` | INT UNSIGNED | DEFAULT 0 | 精选排序 |
+| — **户型布局** — | | | |
+| `layout` | VARCHAR(50) | NULL | 3室2厅3卫 |
+| `floor_height` | VARCHAR(50) | NULL | 3.6/3.3/3.3m |
+| — **用地条件** — | | | |
+| `site_width` | VARCHAR(50) | NULL | 面宽 ≥ 10.5m |
+| `site_depth` | VARCHAR(50) | NULL | 进深 ≥ 12.2m |
+| `site_area` | DECIMAL(10,2) | NULL | 占地面积 m² |
+| `lighting_restriction` | VARCHAR(100) | NULL | 采光限制 |
+| `site_shape` | VARCHAR(50) | NULL | 用地形状 |
+| — **规模造价** — | | | |
+| `floors_above` | TINYINT UNSIGNED | NULL | 地上层数 |
+| `floors_below` | TINYINT UNSIGNED | NULL | 地下层数 |
+| `cost_min` | DECIMAL(12,2) | NULL | 造价预估下限（万元） |
+| `cost_max` | DECIMAL(12,2) | NULL | 造价预估上限（万元） |
+| `total_building_area` | DECIMAL(10,2) | NULL | 建筑总面积 m² |
+| `bedroom_count` | TINYINT UNSIGNED | NULL | 卧室数量 |
+| `bedroom_note` | VARCHAR(100) | NULL | 含1主卧套房 |
+| — **平面功能** — | | | |
+| `stair_type` | VARCHAR(100) | NULL | 楼梯类型 |
+| `special_space` | VARCHAR(200) | NULL | 特色空间 / 农村特色 |
+| `bedroom_config` | VARCHAR(200) | NULL | 卧室配置 |
+| `leisure_space` | VARCHAR(200) | NULL | 休闲空间 |
+| `kitchen_dining` | VARCHAR(200) | NULL | 厨房餐厅 |
+| `bathroom_config` | VARCHAR(100) | NULL | 卫生间配置 |
+| — **外观风格** — | | | |
+| `architecture_style` | VARCHAR(100) | NULL | 建筑风格 |
+| `roof_type` | VARCHAR(100) | NULL | 屋顶形式 |
+| `facade_material` | VARCHAR(200) | NULL | 外立面材料 |
+| — **结构与性能** — | | | |
+| `structure_type` | VARCHAR(100) | NULL | 结构类型 |
+| `foundation_type` | VARCHAR(100) | NULL | 基础类型 |
+| `layout_logic` | VARCHAR(200) | NULL | 户型逻辑 |
+| `wall_thickness` | VARCHAR(100) | NULL | 墙体厚度 |
+| `seismic_rating` | VARCHAR(100) | NULL | 抗震设防 |
+| `insulation_type` | VARCHAR(100) | NULL | 保温形式 |
+| `roof_structure` | VARCHAR(200) | NULL | 屋面构造 |
+| — **设计理念** — | | | |
+| `design_concept` | TEXT | NULL | 设计理念富文本 |
+| `concept_style` | VARCHAR(100) | NULL | 风格提炼 |
+| `concept_material` | VARCHAR(100) | NULL | 材质提炼 |
+| `concept_target` | VARCHAR(100) | NULL | 受众提炼 |
+| — **分类特有扩展** — | | | |
+| `meta` | JSON | NULL | 分类特有参数（景观面积 / 客房数 / 主材等） |
+| — **统计计数** — | | | |
+| `view_count` | INT UNSIGNED | DEFAULT 0 | |
+| `like_count` | INT UNSIGNED | DEFAULT 0 | |
+| `favorite_count` | INT UNSIGNED | DEFAULT 0 | |
+| `download_count` | INT UNSIGNED | DEFAULT 0 | |
+| `comment_count` | INT UNSIGNED | DEFAULT 0 | |
+| — **时间** — | | | |
+| `published_at` | TIMESTAMP | NULL | 发布时间 |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+| `deleted_at` | TIMESTAMP | NULL | |
+
+索引：`uk_cases_code`, `idx_cases_category_id`, `idx_cases_status`, `idx_cases_is_featured`, `idx_cases_status_created (status, created_at)`, `idx_cases_status_featured (status, is_featured, featured_sort)`
+
+> `meta` JSON 用于存储不同分类的特有参数。例如：
+> - 景观类案例：`{"landscape_area": 270, "main_vegetation": "黑松/苔藓", "paving_material": "花岗岩/白砂"}`
+> - 民宿类案例：`{"room_count": 12, "room_note": "12间套房"}`
+> - 室内类案例：`{"main_material": "微水泥/钢构"}`
+> - 商业类案例：`{"building_height": "120m", "function_layout": "办公/商业"}`
+
+#### `case_images` — 案例图库
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `case_id` | BIGINT UNSIGNED | FK → cases | |
+| `type` | VARCHAR(20) | NOT NULL | effect / floor_plan / elevation |
+| `url` | VARCHAR(500) | NOT NULL | 图片 URL |
+| `thumbnail_url` | VARCHAR(500) | NULL | 缩略图 URL |
+| `sort` | INT UNSIGNED | DEFAULT 0 | |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+
+索引：`idx_case_images_case_type (case_id, type)`
+
+#### `case_files` — 案例文件资产
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `case_id` | BIGINT UNSIGNED | FK → cases | |
+| `stage` | VARCHAR(20) | NOT NULL | floor_plan / exterior / construction / structure / interior / courtyard |
+| `file_name` | VARCHAR(200) | NOT NULL | 原始文件名 |
+| `file_path` | VARCHAR(500) | NOT NULL | 存储路径 / OSS key |
+| `file_size` | BIGINT UNSIGNED | NOT NULL | 字节数 |
+| `file_ext` | VARCHAR(20) | NOT NULL | dwg / pdf / rvt / jpg / png / zip |
+| `mime_type` | VARCHAR(100) | NULL | |
+| `uploader_id` | BIGINT UNSIGNED | FK → users | 上传者 |
+| `sort` | INT UNSIGNED | DEFAULT 0 | |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+
+索引：`idx_case_files_case_stage (case_id, stage)`
+
+> `stage` 枚举值对应 PRD F5.1 的 6 个设计阶段：
+> - `floor_plan` — 平面阶段
+> - `exterior` — 外观阶段
+> - `construction` — 施工图阶段
+> - `structure` — 结构阶段
+> - `interior` — 室内阶段
+> - `courtyard` — 庭院阶段
+
+#### `case_belongs_tag` — 案例-标签关联
+
+| 字段 | 类型 | 约束 |
+|------|------|------|
+| `case_id` | BIGINT UNSIGNED | PK(联合), FK → cases |
+| `tag_id` | BIGINT UNSIGNED | PK(联合), FK → tags |
+
+#### `case_team_members` — 案例主创团队
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `case_id` | BIGINT UNSIGNED | FK → cases | |
+| `designer_id` | BIGINT UNSIGNED | FK → designers | |
+| `role` | VARCHAR(30) | NOT NULL | scheme / structure / mep (方案/结构/水电) |
+| `is_lead` | TINYINT | DEFAULT 0 | 是否主创 |
+| `sort` | INT UNSIGNED | DEFAULT 0 | |
+| `created_at` | TIMESTAMP | | |
+
+索引：`uk_case_team_case_designer_role (case_id, designer_id, role)`, `idx_case_team_designer_id`
+
+---
+
+### 4.3 设计师域
+
+#### `designers` — 设计师档案
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `name_cn` | VARCHAR(50) | NOT NULL | 中文姓名 |
+| `name_en` | VARCHAR(100) | NULL | 英文姓名 |
+| `title` | VARCHAR(50) | NULL | 职位：方案主创设计师 |
+| `title_badge` | VARCHAR(50) | NULL | 职位徽章：Lead Architect |
+| `company` | VARCHAR(100) | NULL | 所属机构 |
+| `city` | VARCHAR(50) | NULL | 所在城市 |
+| `portrait` | VARCHAR(500) | NULL | 个人写真 URL |
+| `portrait_caption` | VARCHAR(100) | NULL | STUDIO PORTRAIT © 2023 |
+| `years_of_experience` | TINYINT UNSIGNED | NULL | 从业年限 |
+| `project_count` | INT UNSIGNED | DEFAULT 0 | 完成项目数 |
+| `design_philosophy_quote` | TEXT | NULL | 设计理念引用语 |
+| `design_philosophy` | TEXT | NULL | 设计理念详述（富文本） |
+| `follower_count` | INT UNSIGNED | DEFAULT 0 | 关注者数量 |
+| `view_count` | INT UNSIGNED | DEFAULT 0 | 主页浏览量 |
+| `is_active` | TINYINT | DEFAULT 1 | 是否公开展示 |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+| `deleted_at` | TIMESTAMP | NULL | |
+
+索引：`idx_designers_is_active`
+
+#### `designer_awards` — 设计师荣誉奖项
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `designer_id` | BIGINT UNSIGNED | FK → designers | |
+| `year` | SMALLINT UNSIGNED | NOT NULL | 获奖年份 |
+| `title` | VARCHAR(200) | NOT NULL | 红点设计大奖 Red Dot Award |
+| `description` | VARCHAR(300) | NULL | 最佳室内设计类 - The Cloud Villa |
+| `sort` | INT UNSIGNED | DEFAULT 0 | |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+
+索引：`idx_awards_designer_year (designer_id, year DESC)`
+
+#### `designer_belongs_tag` — 设计师-专长标签
+
+| 字段 | 类型 | 约束 |
+|------|------|------|
+| `designer_id` | BIGINT UNSIGNED | PK(联合), FK → designers |
+| `tag_id` | BIGINT UNSIGNED | PK(联合), FK → tags (type=specialty) |
+
+---
+
+### 4.4 运营内容域
+
+#### `banners` — 首页轮播
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `title` | VARCHAR(200) | NOT NULL | 大标题 |
+| `description` | TEXT | NULL | 描述摘要 |
+| `image` | VARCHAR(500) | NOT NULL | 背景大图 URL |
+| `label` | VARCHAR(50) | NULL | 标签文字：精选项目 |
+| `link_type` | VARCHAR(20) | NOT NULL, DEFAULT 'case' | case / topic / external |
+| `link_url` | VARCHAR(500) | NOT NULL | 跳转链接 |
+| `sort` | INT UNSIGNED | DEFAULT 0 | |
+| `is_active` | TINYINT | DEFAULT 1 | 启用/停用 |
+| `published_at` | TIMESTAMP | NULL | 展示日期 |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+
+索引：`idx_banners_active_sort (is_active, sort)`
+
+#### `topics` — 专题合集
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `title` | VARCHAR(200) | NOT NULL | 专题标题 |
+| `cover_image` | VARCHAR(500) | NULL | 封面图 |
+| `description` | TEXT | NULL | 富文本描述 |
+| `status` | VARCHAR(20) | NOT NULL, DEFAULT 'draft' | draft / published |
+| `case_count` | INT UNSIGNED | DEFAULT 0 | 关联案例数 |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+| `deleted_at` | TIMESTAMP | NULL | |
+
+#### `topic_belongs_case` — 专题-案例关联
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `topic_id` | BIGINT UNSIGNED | PK(联合), FK → topics | |
+| `case_id` | BIGINT UNSIGNED | PK(联合), FK → cases | |
+| `sort` | INT UNSIGNED | DEFAULT 0 | 专题内排序 |
+
+---
+
+### 4.5 用户互动域
+
+#### `favorites` — 收藏
+
+| 字段 | 类型 | 约束 |
+|------|------|------|
+| `id` | BIGINT UNSIGNED | PK |
+| `user_id` | BIGINT UNSIGNED | FK → users |
+| `case_id` | BIGINT UNSIGNED | FK → cases |
+| `created_at` | TIMESTAMP | |
+
+索引：`uk_favorites_user_case (user_id, case_id)`, `idx_favorites_case_id`
+
+#### `likes` — 点赞
+
+| 字段 | 类型 | 约束 |
+|------|------|------|
+| `id` | BIGINT UNSIGNED | PK |
+| `user_id` | BIGINT UNSIGNED | FK → users |
+| `case_id` | BIGINT UNSIGNED | FK → cases |
+| `created_at` | TIMESTAMP | |
+
+索引：`uk_likes_user_case (user_id, case_id)`, `idx_likes_case_id`
+
+#### `comments` — 评论
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `case_id` | BIGINT UNSIGNED | FK → cases | |
+| `user_id` | BIGINT UNSIGNED | FK → users | |
+| `parent_id` | BIGINT UNSIGNED | NULL, FK → comments | 回复嵌套 |
+| `content` | TEXT | NOT NULL | 评论内容 |
+| `status` | VARCHAR(20) | DEFAULT 'pending' | pending / approved / rejected |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+| `deleted_at` | TIMESTAMP | NULL | |
+
+索引：`idx_comments_case_status (case_id, status)`, `idx_comments_user_id`, `idx_comments_parent_id`
+
+#### `follows` — 关注设计师
+
+| 字段 | 类型 | 约束 |
+|------|------|------|
+| `id` | BIGINT UNSIGNED | PK |
+| `user_id` | BIGINT UNSIGNED | FK → users |
+| `designer_id` | BIGINT UNSIGNED | FK → designers |
+| `created_at` | TIMESTAMP | |
+
+索引：`uk_follows_user_designer (user_id, designer_id)`, `idx_follows_designer_id`
+
+#### `newsletter_subscriptions` — 邮箱订阅
+
+| 字段 | 类型 | 约束 |
+|------|------|------|
+| `id` | BIGINT UNSIGNED | PK |
+| `email` | VARCHAR(200) | NOT NULL, UNIQUE |
+| `created_at` | TIMESTAMP | |
+
+---
+
+### 4.6 日志与系统域
+
+#### `user_login_logs` — 登录日志
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `user_id` | BIGINT UNSIGNED | FK → users | |
+| `login_type` | VARCHAR(20) | NOT NULL | password / sms / qr / wechat / qq / enterprise_sso |
+| `ip` | VARCHAR(45) | NULL | |
+| `login_location` | VARCHAR(100) | NULL | 登录地理位置（由 IP 库反查填充） |
+| `device_fingerprint` | VARCHAR(128) | NULL | 设备指纹 |
+| `risk_level` | VARCHAR(10) | NULL | L1 / L2 / L3 / L4 |
+| `risk_reason` | VARCHAR(255) | NULL | 命中策略摘要 |
+| `result` | VARCHAR(20) | NOT NULL, DEFAULT 'success' | success / failed / blocked |
+| `user_agent` | VARCHAR(500) | NULL | |
+| `created_at` | TIMESTAMP | | |
+
+索引：`idx_login_logs_user_created (user_id, created_at)`, `idx_login_logs_ip_created (ip, created_at)`
+
+#### `user_sessions` — 活跃会话
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `user_id` | BIGINT UNSIGNED | FK → users | |
+| `session_token` | VARCHAR(255) | NOT NULL, UNIQUE | Refresh Token 标识（哈希值） |
+| `device_name` | VARCHAR(100) | NULL | 设备名称（如 Chrome on macOS） |
+| `device_fingerprint` | VARCHAR(128) | NULL | 设备指纹 |
+| `ip` | VARCHAR(45) | NULL | 登录 IP |
+| `login_location` | VARCHAR(100) | NULL | 登录地理位置 |
+| `is_current` | TINYINT | NOT NULL, DEFAULT 0 | 是否为当前请求会话 |
+| `last_active_at` | TIMESTAMP | NULL | 最近活跃时间 |
+| `expires_at` | TIMESTAMP | NOT NULL | 会话过期时间 |
+| `revoked_at` | TIMESTAMP | NULL | 被踢出/注销时间（非空即失效） |
+| `created_at` | TIMESTAMP | | |
+
+索引：`idx_sessions_user_active (user_id, revoked_at, expires_at)`, `uk_sessions_token (session_token)`
+
+> 活跃会话表用于 F1.9 多端会话管理。创建会话时写入，Token 刷新时更新 `last_active_at`，退出/踢出时设置 `revoked_at`。定期清理过期记录。
+
+#### `security_risk_events` — 风控事件日志
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `user_id` | BIGINT UNSIGNED | NULL, FK → users | 可为空（未登录攻击流量） |
+| `event_type` | VARCHAR(30) | NOT NULL | login / sms_send / register / reset_password / sso_callback |
+| `risk_level` | VARCHAR(10) | NOT NULL | L1 / L2 / L3 / L4 |
+| `action` | VARCHAR(30) | NOT NULL | captcha_upgrade / rate_limit / temporary_block / blacklist |
+| `ip` | VARCHAR(45) | NULL | |
+| `device_fingerprint` | VARCHAR(128) | NULL | |
+| `user_agent` | VARCHAR(500) | NULL | |
+| `payload` | JSON | NULL | 事件上下文 |
+| `created_at` | TIMESTAMP | | |
+
+索引：`idx_risk_events_user_created (user_id, created_at)`, `idx_risk_events_level_created (risk_level, created_at)`, `idx_risk_events_ip_created (ip, created_at)`
+
+> 风控事件日志不可编辑、不可删除，无 `updated_at` 和 `deleted_at`。
+
+#### `security_blacklists` — 安全黑名单
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `target_type` | VARCHAR(20) | NOT NULL | ip / device / account |
+| `target_value` | VARCHAR(255) | NOT NULL | IP、设备指纹或账号标识 |
+| `reason` | VARCHAR(255) | NULL | 拉黑原因 |
+| `source` | VARCHAR(20) | NOT NULL, DEFAULT 'system' | system / manual |
+| `status` | VARCHAR(20) | NOT NULL, DEFAULT 'active' | active / released / expired |
+| `expire_at` | TIMESTAMP | NULL | 为空表示永久 |
+| `created_by` | BIGINT UNSIGNED | NULL, FK → users | 手动操作人（系统自动为空） |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+
+索引：`uk_blacklists_target (target_type, target_value)`, `idx_blacklists_status_expire (status, expire_at)`
+
+#### `admin_operation_logs` — 管理端操作日志
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `user_id` | BIGINT UNSIGNED | FK → users | 操作人 |
+| `action` | VARCHAR(30) | NOT NULL | create / update / delete / status_change |
+| `resource_type` | VARCHAR(50) | NOT NULL | case / banner / topic / designer / comment |
+| `resource_id` | BIGINT UNSIGNED | NOT NULL | 操作对象 ID |
+| `before_value` | JSON | NULL | 变更前值 |
+| `after_value` | JSON | NULL | 变更后值 |
+| `ip` | VARCHAR(45) | NULL | |
+| `created_at` | TIMESTAMP | | |
+
+索引：`idx_op_logs_user_created (user_id, created_at)`, `idx_op_logs_resource (resource_type, resource_id)`
+
+> 操作日志不可编辑、不可删除，无 `updated_at` 和 `deleted_at`。
+
+#### `download_logs` — 文件下载日志
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `user_id` | BIGINT UNSIGNED | FK → users | |
+| `case_id` | BIGINT UNSIGNED | FK → cases | |
+| `case_file_id` | BIGINT UNSIGNED | FK → case_files | |
+| `ip` | VARCHAR(45) | NULL | |
+| `created_at` | TIMESTAMP | | |
+
+索引：`idx_dl_logs_user_created (user_id, created_at)`, `idx_dl_logs_case_id`
+
+#### `system_configs` — 系统配置
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| `id` | BIGINT UNSIGNED | PK | |
+| `group` | VARCHAR(50) | NOT NULL | site / seo / upload / comment / watermark / security |
+| `key` | VARCHAR(100) | NOT NULL | |
+| `value` | TEXT | NULL | |
+| `created_at` | TIMESTAMP | | |
+| `updated_at` | TIMESTAMP | | |
+
+索引：`uk_configs_group_key (group, key)`
+
+---
+
+## 5. 索引策略
+
+### 必须索引
+- 所有外键字段
+- `status` 字段
+- `created_at` 字段
+- 唯一业务标识（`cases.code`、`tags.type+name`、`users.phone`）
+
+### 核心复合索引
+```sql
+-- 案例列表查询（分类 + 状态 + 时间）
+idx_cases_category_status_created (category_id, status, created_at)
+
+-- 案例精选排序
+idx_cases_featured_sort (status, is_featured, featured_sort)
+
+-- 文件按阶段查询
+idx_case_files_case_stage (case_id, stage)
+
+-- 评论列表
+idx_comments_case_status (case_id, status, created_at)
+```
+
+### 索引限制
+- 单表索引不超过 6 个
+- 避免冗余索引
+- 定期检查未使用的索引
+
+---
+
+## 6. 百万级数据表设计
+
+### 分页优化
+```sql
+-- 游标分页（案例列表推荐使用）
+SELECT * FROM cases WHERE status = 'published' AND id > :last_id ORDER BY id DESC LIMIT 20;
+```
+
+### 大表 COUNT 优化
+```sql
+-- 使用 categories.case_count / tags.reference_count 缓存计数
+-- 使用 cases.view_count / like_count / favorite_count 避免 COUNT JOIN
+```
+
+### 分区策略（日志表）
+```sql
+-- 管理操作日志
+ALTER TABLE admin_operation_logs PARTITION BY RANGE (YEAR(created_at) * 100 + MONTH(created_at)) (
+    PARTITION p202601 VALUES LESS THAN (202602),
+    PARTITION p202602 VALUES LESS THAN (202603),
+    PARTITION pmax VALUES LESS THAN MAXVALUE
+);
+
+-- 用户登录日志（数据量最大，优先分区）
+ALTER TABLE user_login_logs PARTITION BY RANGE (YEAR(created_at) * 100 + MONTH(created_at)) (
+    PARTITION p202601 VALUES LESS THAN (202602),
+    PARTITION p202602 VALUES LESS THAN (202603),
+    PARTITION pmax VALUES LESS THAN MAXVALUE
+);
+
+-- 风控事件日志
+ALTER TABLE security_risk_events PARTITION BY RANGE (YEAR(created_at) * 100 + MONTH(created_at)) (
+    PARTITION p202601 VALUES LESS THAN (202602),
+    PARTITION p202602 VALUES LESS THAN (202603),
+    PARTITION pmax VALUES LESS THAN MAXVALUE
+);
+```
+
+---
+
+*最后更新: 2026-02-28*
diff --git a/docs/architecture/decisions/_template.md b/docs/architecture/decisions/_template.md
new file mode 100644
index 0000000..caa36cc
--- /dev/null
+++ b/docs/architecture/decisions/_template.md
@@ -0,0 +1,76 @@
+# ADR-XXX: [决策标题]
+
+> Architecture Decision Record (架构决策记录)
+
+## 状态
+
+**[提议中 | 已接受 | 已废弃 | 已取代 → ADR-YYY]**
+
+## 日期
+
+YYYY-MM-DD
+
+## 上下文
+
+描述促使此决策的背景、问题或需求。
+
+**问题陈述**:
+我们需要解决 [什么问题]...
+
+**约束条件**:
+- 约束1
+- 约束2
+
+## 决策
+
+我们决定采用 [方案]。
+
+**选定方案的详细描述**:
+...
+
+## 考虑的备选方案
+
+### 方案 A: [名称]
+**描述**: ...
+**优点**:
+- 优点1
+- 优点2
+
+**缺点**:
+- 缺点1
+- 缺点2
+
+### 方案 B: [名称]
+**描述**: ...
+**优点**:
+- 优点1
+
+**缺点**:
+- 缺点1
+
+## 为什么选择此方案
+
+解释选择该方案而非其他方案的理由。
+
+## 影响
+
+### 正面影响
+- 影响1
+- 影响2
+
+### 负面影响/权衡
+- 权衡1
+
+### 需要的后续行动
+- [ ] 行动1
+- [ ] 行动2
+
+## 相关文档
+
+- [系统架构](../system-design.md)
+- [相关 ADR](./xxx.md)
+
+---
+
+*记录人: [姓名]*
+*审核人: [姓名]*
diff --git a/docs/architecture/frontend-strategy.md b/docs/architecture/frontend-strategy.md
new file mode 100644
index 0000000..be0d29e
--- /dev/null
+++ b/docs/architecture/frontend-strategy.md
@@ -0,0 +1,128 @@
+# 🖥️ 双前端架构策略
+
+> AI Agent 在生成前端代码时必须先阅读本文档，明确目标前端的职责边界、技术约束和设计原则。
+
+---
+
+## 1. 整体架构
+
+本项目采用「一后端 + 双前端 + 共享层」架构：
+
+```
+vibe-cursor-pro/（Cursor 工作区）
+├── Case-Database-Backend/          ← PHP Hyperf + Swoole 后端（统一 API 服务）
+├── Case-Database-Frontend-user/    ← Vue 3 用户端（面向终端用户）
+├── Case-Database-Frontend-admin/   ← Vue 3 管理端（面向运营/管理人员）
+└── Case-Database-Frontend-shared/           ← 共享类型定义、工具函数、API 契约常量
+```
+
+---
+
+## 2. 前端职责边界
+
+### Case-Database-Frontend-user/（用户端）
+
+| 维度 | 说明 |
+|---|---|
+| **目标用户** | 普通终端用户（公开访问 + 登录用户） |
+| **核心体验** | 性能优先、流畅交互、移动端友好 |
+| **设计风格** | 品牌化、轻量、视觉吸引力强 |
+| **页面规模** | 中小型页面，单页功能聚焦 |
+| **权限模型** | 简单（登录/未登录、会员等级） |
+| **SEO 需求** | 有（落地页、详情页考虑 SSG/SSR） |
+| **API 前缀** | `/api/`（用户端接口） |
+
+**典型页面**：首页、商品详情、购物车、个人中心、订单查询
+
+### Case-Database-Frontend-admin/（管理端）
+
+| 维度 | 说明 |
+|---|---|
+| **目标用户** | 内部运营人员、管理员 |
+| **核心体验** | 功能完整、信息密度高、操作高效 |
+| **设计风格** | 专业、实用、Element Plus 标准组件优先（仅管理端） |
+| **页面规模** | 复杂页面（多 Tab、嵌套表单、数据大表格） |
+| **权限模型** | 精细（RBAC：角色、菜单、按钮级权限） |
+| **SEO 需求** | 无（内部系统，登录后访问） |
+| **API 前缀** | `/admin/`（管理端接口） |
+
+**典型页面**：数据看板、订单管理、用户管理、权限配置、系统设置
+
+---
+
+## 3. 共享层（Case-Database-Frontend-shared/）
+
+仅包含**纯 TypeScript**内容（配合 JSDoc 类型注释），不引入任何 UI 框架：
+
+```
+Case-Database-Frontend-shared/
+├── constants/      ← 业务枚举（订单状态、权限码等）
+├── utils/          ← 纯函数工具（日期格式化、金额计算等）
+└── api-schema/     ← API 请求/响应的 JSDoc 类型定义
+```
+
+> **规则**：Case-Database-Frontend-shared/ 中的代码必须可被两个前端同时使用，不得包含平台特定代码。
+
+---
+
+## 4. 技术差异对比
+
+| 技术点 | Case-Database-Frontend-user/ | Case-Database-Frontend-admin/ |
+|---|---|---|
+| **UI 框架** | 自定义组件 + Tailwind | Element Plus（优先使用标准组件） |
+| **响应式** | 移动优先（xs → xl） | 桌面优先（≥ 1280px 为主） |
+| **路由** | Vue Router（History 模式） | Vue Router（History 模式 + 权限守卫） |
+| **状态管理** | Pinia（轻量 Store） | Pinia（含权限 Store、菜单 Store） |
+| **打包优化** | 激进代码分割、图片优化、SSG 评估 | 按需分割（菜单级懒加载） |
+| **错误处理** | 用户友好提示（Toast） | 详细错误码 + 日志上报 |
+| **主题** | 品牌色（见 ui-specs-user.md） | 专业蓝灰（见 ui-specs-admin.md） |
+
+---
+
+## 5. AI Agent 工作约定
+
+### 目录前缀约定
+
+**每次前端相关任务，必须在 prompt 中明确指定目标目录**：
+
+```
+✅ 正确：在 Case-Database-Frontend-user/ 中创建商品详情页
+✅ 正确：在 Case-Database-Frontend-admin/ 中创建订单管理页
+❌ 错误：创建商品详情页（未指定前端）
+```
+
+### 设计原则差异
+
+当 Agent 在 `Case-Database-Frontend-user/` 工作时：
+- 移动端优先（先写 xs 断点，再扩展到 lg）
+- 组件必须考虑骨架屏 / 懒加载
+- 图片必须有 alt 属性、考虑 WebP 格式
+- 交互反馈必须流畅（避免页面跳动）
+
+当 Agent 在 `Case-Database-Frontend-admin/` 工作时：
+- 桌面端优先（以 1280px 为基准设计）
+- 优先使用 Element Plus 标准组件（`el-table`、`el-form`、`el-dialog` 等）
+- 页面操作必须有权限守卫（`v-permission` 指令 或 `hasPermission()` 检查）
+- 数据操作必须有二次确认（删除、批量操作等危险操作）
+
+### 共享代码优先
+
+在生成 API 调用代码时：
+1. 先检查 `Case-Database-Frontend-shared/constants/` 是否已有对应枚举或常量
+2. 先检查 `Case-Database-Frontend-shared/api-schema/` 是否已有接口契约
+3. 有则复用，无则在 Case-Database-Frontend-shared/ 中新建后再引用
+
+---
+
+## 6. 部署架构
+
+```
+用户端:   https://www.example.com       → Nginx → Case-Database-Frontend-user/dist/
+管理端:   https://admin.example.com     → Nginx → Case-Database-Frontend-admin/dist/
+API:      https://api.example.com       → Nginx → Hyperf (9501)
+WebSocket: wss://api.example.com/ws    → Nginx → Swoole (9502)
+```
+
+---
+
+*最后更新: 2026-02-26*
diff --git a/docs/architecture/system-design.md b/docs/architecture/system-design.md
new file mode 100644
index 0000000..cd3f5de
--- /dev/null
+++ b/docs/architecture/system-design.md
@@ -0,0 +1,133 @@
+# 🏗️ System Design — 百万级并发企业数字化平台
+
+> 填写本文档，为 AI Agent 提供系统架构上下文。
+
+---
+
+## 1. 技术栈
+
+| 层级 | 技术 | 版本 |
+|------|------|------|
+| 前端框架 | Vue 3 + Vite | 3.5+ / 7.x |
+| UI 库 (管理端) | Element Plus + Tailwind CSS | 2.x / 4.x |
+| UI 库 (用户端) | Headless UI + Tailwind CSS | 1.x / 4.x |
+| 状态管理 | Pinia | 3.x |
+| 路由 | Vue Router | 4.x |
+| HTTP 客户端 | Axios | 1.x |
+| 后端框架 | Hyperf | 3.1 |
+| 协程引擎 | Swoole | 5.0+ |
+| 编程语言 | PHP | 8.1+ |
+| 数据库 | MySQL | 8.1 |
+| 缓存 | Redis | 7.x |
+| 反向代理 | Nginx | 1.25+ |
+| 容器化 | Docker + Docker Compose | - |
+
+## 2. 架构总览
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                          用户层                                   │
+│   PC 浏览器   │   移动端 (响应式)   │   平板   │   管理后台        │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │
+                            ▼
+┌───────────────────────────────────────────────────────────────────┐
+│                    CDN + WAF (可选)                                │
+└───────────────────────────┬───────────────────────────────────────┘
+                            │
+                            ▼
+┌───────────────────────────────────────────────────────────────────┐
+│              Nginx 集群 (负载均衡 + SSL + 静态资源)                  │
+│              - upstream hyperf_cluster                             │
+│              - WebSocket proxy                                    │
+└───────────────────────────┬───────────────────────────────────────┘
+                            │
+              ┌─────────────┼─────────────┐
+              ▼             ▼             ▼
+       ┌──────────┐  ┌──────────┐  ┌──────────┐
+       │ Hyperf-1 │  │ Hyperf-2 │  │ Hyperf-N │  (水平扩展)
+       │ HTTP:9501│  │ HTTP:9501│  │ HTTP:9501│
+       │ WS:9502  │  │ WS:9502  │  │ WS:9502  │
+       └────┬─────┘  └────┬─────┘  └────┬─────┘
+            │              │              │
+            └──────┬───────┴──────┬───────┘
+                   │              │
+            ┌──────┴──────┐ ┌────┴────────┐
+            │   Redis     │ │   MySQL     │
+            │  Sentinel/  │ │  Master     │
+            │  Cluster    │ │   ├─Slave 1 │
+            │             │ │   └─Slave 2 │
+            └─────────────┘ └─────────────┘
+```
+
+## 3. 分层架构
+
+```
+请求 → Nginx → Hyperf HTTP Server → 中间件链 → Controller
+                                                    │
+                                                    ▼
+                                              Service 层
+                                                    │
+                                    ┌───────────────┼───────────────┐
+                                    ▼               ▼               ▼
+                              Repository        Redis Cache      Event Bus
+                                    │                               │
+                                    ▼                               ▼
+                                  MySQL                       Async Queue
+```
+
+## 4. 核心模块
+
+<!-- 根据实际项目填写 -->
+
+| 模块 | 说明 | 关键接口 |
+|------|------|---------|
+| 用户认证 | JWT + RBAC 权限 | `/admin/auth/login`, `/admin/auth/refresh` |
+| 权限管理 | 用户/角色/菜单/数据权限 | `/admin/users`, `/admin/roles`, `/admin/menus` |
+| 生产管理 | 订单/子订单/发货/收款 | `/admin/production-orders`, `/admin/sub-orders` |
+| 工作流 | 审批流程定义与执行 | `/admin/workflows`, `/admin/tasks` |
+| 通知中心 | WebSocket + 站内消息 + 短信 | `/admin/notifications`, `ws://9502` |
+| 客户管理 | 客户/平台/店铺 | `/admin/customers`, `/admin/platforms` |
+
+## 5. 并发设计要点
+
+| 设计要点 | 实现方式 |
+|---------|---------|
+| 无状态服务 | Session/Token 存 Redis，文件存对象存储 |
+| 数据库高可用 | MySQL 主从 + 读写分离 + 连接池 |
+| 缓存策略 | Cache-Aside + 穿透/击穿/雪崩防护 |
+| 异步削峰 | Hyperf AsyncQueue (Redis 驱动) |
+| 分布式锁 | Redis SET NX + Lua 脚本 |
+| 限流 | 令牌桶 (API) + 滑动窗口 (用户) |
+| 实时通信 | Swoole WebSocket + Redis Pub/Sub |
+| 水平扩展 | Docker Compose → K8s HPA |
+
+## 6. 部署拓扑
+
+<!-- 根据实际部署环境填写 -->
+
+### 开发环境
+- 单机 Docker Compose (Nginx + Hyperf + MySQL + Redis)
+
+### 生产环境
+- Nginx 集群 (2+ 节点)
+- Hyperf 应用 (4+ 实例)
+- MySQL 主从 (1 写 + 2 读)
+- Redis Sentinel (3 节点)
+
+## 7. 决策记录
+
+<!-- 重要架构决策记录在 docs/architecture/decisions/ -->
+
+| 决策 | 选择 | 原因 |
+|------|------|------|
+| 后端框架 | Hyperf + Swoole | 协程高性能，连接池，与旧项目技术栈一致 |
+| 数据库 | MySQL 8.1 | 成熟稳定，JSON 支持，与旧项目一致 |
+| 缓存 | Redis 7 | 数据结构丰富，连接池，队列支持 |
+| 前端框架 | Vue 3 + Vite | 生态成熟，与旧项目一致，Composition API |
+| UI 库 | 管理端 Element Plus + Tailwind / 用户端 Headless UI + Tailwind | 管理端企业级组件 + 用户端轻量交互 |
+| 部署 | Docker Compose → K8s | 渐进式扩展 |
+
+---
+
+*最后更新: YYYY-MM-DD*
diff --git a/docs/guides/style-guide.md b/docs/guides/style-guide.md
new file mode 100644
index 0000000..f9a7af6
--- /dev/null
+++ b/docs/guides/style-guide.md
@@ -0,0 +1,138 @@
+# 📐 Code Style Guide
+
+> 团队代码风格约定，AI 在生成代码时自动遵循
+
+---
+
+## 通用
+
+- 缩进: 2 spaces (前端) / 4 spaces (PHP)
+- 行宽: 100 chars (前端) / 120 chars (PHP)
+- 行尾: LF
+- 文件末尾: 空行
+- 字符编码: UTF-8
+
+---
+
+## TypeScript / Vue 3 前端
+
+- 分号: 使用 (`;`)
+- 引号: 单引号 (`'`)
+- 尾逗号: 无 (`trailing comma: none`)
+- 箭头函数参数: 始终括号 (`(x) => x`)
+
+### 导入顺序
+
+```typescript
+// 1. Vue 运行时和内置组合式
+import { ref, computed, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+
+// 2. 第三方库
+// 管理端：import { ElMessage } from 'element-plus'
+// 用户端：import { Dialog } from '@headlessui/vue'
+import dayjs from 'dayjs'
+
+// 3. 内部模块 (绝对路径)
+import AppButton from '@/components/ui/AppButton.vue'
+import { useUserStore } from '@/store/modules/user'
+
+// 4. 相对路径
+import { helper } from './utils'
+
+// 5. JSDoc 类型引用（JS 项目无需 import type）
+// @typedef {import('@/types').User} User
+
+// 6. 样式
+import './styles.css'
+```
+
+### 文件命名
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 组件 | PascalCase | `UserProfile.vue` |
+| Composable | camelCase + use | `useAuth.ts` |
+| 工具函数 | kebab-case | `format-date.ts` |
+| 常量 | kebab-case | `api-routes.ts` |
+| 类型文件 | kebab-case | `user.types.ts` |
+| 测试 | 同源 + .test | `UserProfile.test.ts` |
+| Store | camelCase | `user.ts` (in store/modules/) |
+| 指令 | camelCase | `auth.ts` (in directives/) |
+| API | camelCase | `production.ts` (in api/) |
+
+---
+
+## PHP 后端 (PSR-12)
+
+- 分号: 必须
+- 引号: 单引号优先，含变量用双引号
+- 缩进: 4 spaces
+- 行宽: 120 chars
+- 大括号: 类/方法 `{` 换行，控制流 `{` 同行
+
+### PHP 命名规范
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 类 | PascalCase | `OrderService` |
+| 方法 | camelCase | `createOrder()` |
+| 变量 | camelCase | `$orderData` |
+| 常量 | SCREAMING_SNAKE | `MAX_RETRY_COUNT` |
+| 数据库字段 | snake_case | `created_at` |
+| 路由 | kebab-case 复数 | `/admin/production-orders` |
+| 迁移文件 | snake_case 时间戳 | `2026_02_24_100000_create_orders_table.php` |
+
+### PHP 文件结构
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Service\Production;
+
+use App\Model\Production\ProductionOrder;
+use App\Repository\Production\OrderRepository;
+use Hyperf\Di\Annotation\Inject;
+
+class OrderService
+{
+    #[Inject]
+    protected OrderRepository $orderRepository;
+
+    public function create(array $data): ProductionOrder
+    {
+        // ...
+    }
+}
+```
+
+### PHP 必须遵循
+
+- `declare(strict_types=1);` — 所有 PHP 文件
+- 类属性使用类型声明
+- 方法参数和返回值使用类型声明
+- 使用 PHPStan Level max 进行静态分析
+- 使用 PHP CS Fixer 格式化代码
+
+---
+
+## Prettier 配置 (.prettierrc)
+
+```json
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "none",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "plugins": ["prettier-plugin-tailwindcss"]
+}
+```
+
+---
+
+*最后更新: 2026-02-24*
diff --git a/docs/guides/testing-strategy.md b/docs/guides/testing-strategy.md
new file mode 100644
index 0000000..79ad268
--- /dev/null
+++ b/docs/guides/testing-strategy.md
@@ -0,0 +1,125 @@
+# 🧪 Testing Strategy
+
+> 测试策略指南，AI 在编写测试时参考 (PHP Hyperf + Vue 3 双栈)
+
+---
+
+## 前端测试框架
+
+| 类型 | 框架 | 配置文件 |
+|------|------|----------|
+| 单元测试 | Vitest | `vitest.config.ts` |
+| 集成测试 | Vitest + MSW | — |
+| E2E 测试 | Playwright | `playwright.config.ts` |
+
+## 后端测试框架
+
+| 类型 | 框架 | 配置文件 |
+|------|------|----------|
+| 单元测试 | PHPUnit | `phpunit.xml` |
+| 功能测试 | PHPUnit (HTTP) | `phpunit.xml` |
+| 静态分析 | PHPStan | `phpstan.neon` |
+| 代码规范 | PHP CS Fixer | `.php-cs-fixer.php` |
+
+---
+
+## 测试金字塔目标
+
+### 前端
+- Unit: 70% (快速、大量)
+- Integration: 20% (模块协作)
+- E2E: 10% (关键用户路径)
+
+### 后端
+- Unit: 60% (Service、Repository、工具类)
+- Integration: 30% (API 端点、数据库交互)
+- Static Analysis: 持续 (PHPStan Level max)
+
+---
+
+## 覆盖率目标
+
+| 维度 | 前端 | 后端 |
+|------|------|------|
+| 行覆盖 | ≥ 80% | ≥ 75% |
+| 分支覆盖 | ≥ 75% | ≥ 70% |
+| 关键路径 | 100% | 100% |
+| Service 层 | — | 100% |
+
+---
+
+## 运行命令
+
+### 前端
+
+```bash
+npm run test              # 运行所有单元测试
+npm run test:watch        # 监听模式
+npm run test:coverage     # 覆盖率报告
+npm run test:e2e          # E2E 测试 (Playwright)
+```
+
+### 后端
+
+```bash
+composer test             # PHPUnit 所有测试
+composer test:unit        # 仅单元测试
+composer test:feature     # 仅功能测试 (API)
+composer test:coverage    # PHPUnit + 覆盖率报告
+composer analyse          # PHPStan 静态分析
+composer cs-fix           # PHP CS Fixer 格式化
+```
+
+---
+
+## 后端测试目录结构
+
+```
+tests/
+├── Unit/                    # 纯单元测试（不依赖框架）
+│   ├── Service/
+│   │   ├── OrderServiceTest.php
+│   │   └── PaymentServiceTest.php
+│   ├── Repository/
+│   └── Utils/
+├── Feature/                 # 功能测试（HTTP API 级别）
+│   ├── Auth/
+│   │   ├── LoginTest.php
+│   │   └── PermissionTest.php
+│   ├── Production/
+│   │   └── OrderApiTest.php
+│   └── System/
+│       └── HealthCheckTest.php
+├── bootstrap.php
+└── phpunit.xml
+```
+
+---
+
+## CI/CD 中的测试
+
+```yaml
+# .github/workflows/ci.yml 中双栈测试
+jobs:
+  frontend-test:
+    steps:
+      - npm ci
+      - npm run lint
+      - npm run type-check
+      - npm run test:coverage
+
+  backend-test:
+    services:
+      mysql:
+        image: mysql:8
+      redis:
+        image: redis:7-alpine
+    steps:
+      - composer install
+      - composer analyse     # PHPStan
+      - composer test        # PHPUnit
+```
+
+---
+
+*最后更新: 2026-02-24*
diff --git a/docs/guides/ui-specs-admin.md b/docs/guides/ui-specs-admin.md
new file mode 100644
index 0000000..caf15de
--- /dev/null
+++ b/docs/guides/ui-specs-admin.md
@@ -0,0 +1,228 @@
+# 🖥️ UI 规范 — 管理端（Case-Database-Frontend-admin）
+
+> 管理端设计规范。AI 在 `Case-Database-Frontend-admin/` 中新建页面或组件时参考本文档。
+> 核心原则：**桌面优先、功能完整、Element Plus 标准优先**
+
+---
+
+## 1. 设计系统
+
+| 项目 | 选型 |
+|---|---|
+| UI 组件库 | Element Plus（优先使用标准组件，不自定义重复造轮子） |
+| CSS 方案 | Tailwind CSS（辅助布局，不覆盖 Element Plus 样式） |
+| 图标 | Element Plus Icons（`@element-plus/icons-vue`） |
+| 字体 | 系统字体栈 |
+| 布局框架 | 侧边导航 + 顶部栏 + 内容区（标准后台布局） |
+
+---
+
+## 2. 色彩系统
+
+```css
+:root {
+  /* 主色（Element Plus 默认蓝） */
+  --el-color-primary: #409EFF;
+
+  /* 管理端背景层级 */
+  --admin-bg-sidebar:  #001529;   /* 深色侧边栏 */
+  --admin-bg-header:   #FFFFFF;   /* 白色顶栏 */
+  --admin-bg-content:  #F0F2F5;   /* 内容区浅灰 */
+  --admin-bg-card:     #FFFFFF;   /* 卡片/表格白 */
+
+  /* 状态色 */
+  --status-active:   #52C41A;  /* 启用/正常 */
+  --status-inactive: #D9D9D9;  /* 停用/禁用 */
+  --status-pending:  #FAAD14;  /* 待处理 */
+  --status-danger:   #FF4D4F;  /* 危险/错误 */
+}
+```
+
+Element Plus 主题色配置（`src/styles/element-vars.scss`）：
+```scss
+@forward 'element-plus/theme-chalk/src/common/var.scss' with (
+  $colors: (
+    'primary': ('base': #409EFF),
+  )
+);
+```
+
+---
+
+## 3. 布局规范
+
+### 整体框架
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  顶栏（60px 固定）：Logo + 面包屑 + 用户信息 + 通知     │
+├──────────────┬──────────────────────────────────────────┤
+│              │  内容区（padding: 16px）                  │
+│  侧边栏      │  ┌──────────────────────────────────────┐ │
+│  （220px）   │  │  页面标题 + 操作按钮（顶部工具栏）    │ │
+│              │  ├──────────────────────────────────────┤ │
+│  折叠后      │  │  主内容（表格/表单/卡片）             │ │
+│  → 64px     │  │                                      │ │
+│              │  └──────────────────────────────────────┘ │
+└──────────────┴──────────────────────────────────────────┘
+```
+
+### 响应式
+
+管理端以桌面端为主，但需支持：
+- `≥ 1280px`：完整布局（侧边栏展开）
+- `1024px ~ 1279px`：侧边栏折叠（64px 图标模式）
+- `< 1024px`：侧边栏收起为抽屉（移动端兜底）
+
+---
+
+## 4. Element Plus 组件使用规范
+
+### 数据表格（el-table）
+
+```vue
+<el-table
+  v-loading="loading"
+  :data="tableData"
+  stripe
+  border
+  highlight-current-row
+  style="width: 100%"
+>
+  <!-- 数据列 -->
+  <el-table-column prop="id" label="ID" width="80" sortable />
+  <el-table-column prop="name" label="名称" min-width="180" show-overflow-tooltip />
+  
+  <!-- 状态列（Tag） -->
+  <el-table-column label="状态" width="100">
+    <template #default="{ row }">
+      <el-tag :type="row.status === 1 ? 'success' : 'danger'">
+        {{ row.status === 1 ? '启用' : '停用' }}
+      </el-tag>
+    </template>
+  </el-table-column>
+
+  <!-- 操作列（固定右侧） -->
+  <el-table-column label="操作" fixed="right" width="160">
+    <template #default="{ row }">
+      <el-button v-permission="'module:edit'" link type="primary" @click="handleEdit(row)">编辑</el-button>
+      <el-popconfirm title="确定删除？" @confirm="handleDelete(row.id)">
+        <template #reference>
+          <el-button v-permission="'module:delete'" link type="danger">删除</el-button>
+        </template>
+      </el-popconfirm>
+    </template>
+  </el-table-column>
+</el-table>
+
+<!-- 分页（固定格式） -->
+<el-pagination
+  v-model:current-page="query.page"
+  v-model:page-size="query.page_size"
+  :page-sizes="[10, 20, 50, 100]"
+  :total="total"
+  layout="total, sizes, prev, pager, next, jumper"
+  class="mt-4 justify-end"
+  @change="fetchData"
+/>
+```
+
+### 搜索表单
+
+```vue
+<!-- 搜索栏（折叠设计，超过 3 个条件可折叠） -->
+<el-card class="mb-4" shadow="never">
+  <el-form :model="query" inline @keyup.enter="handleSearch">
+    <el-form-item label="关键词">
+      <el-input v-model="query.keyword" placeholder="请输入" clearable style="width: 200px" />
+    </el-form-item>
+    <el-form-item>
+      <el-button type="primary" @click="handleSearch">搜索</el-button>
+      <el-button @click="handleReset">重置</el-button>
+    </el-form-item>
+  </el-form>
+</el-card>
+```
+
+### 弹窗表单
+
+```vue
+<el-dialog v-model="dialogVisible" :title="isEdit ? '编辑' : '新建'" width="600px" @close="handleDialogClose">
+  <el-form ref="formRef" :model="form" :rules="rules" label-width="80px">
+    <el-form-item label="名称" prop="name">
+      <el-input v-model="form.name" />
+    </el-form-item>
+  </el-form>
+  <template #footer>
+    <el-button @click="dialogVisible = false">取消</el-button>
+    <el-button type="primary" :loading="submitting" @click="handleSubmit">确定</el-button>
+  </template>
+</el-dialog>
+```
+
+规则：
+- 弹窗宽度：简单表单 500px，复杂表单 700-900px
+- 弹窗关闭时必须调用 `formRef.value?.resetFields()`
+- 提交按钮加 `:loading` 防重复提交
+
+---
+
+## 5. 页面标准结构
+
+每个管理端页面遵循以下结构：
+
+```vue
+<template>
+  <div class="admin-page">
+    <!-- 页面头部：标题 + 主要操作按钮 -->
+    <div class="mb-4 flex items-center justify-between">
+      <h2 class="text-lg font-semibold text-gray-800">页面标题</h2>
+      <el-button v-permission="'module:create'" type="primary" @click="handleCreate">
+        <el-icon><Plus /></el-icon> 新建
+      </el-button>
+    </div>
+
+    <!-- 搜索区 -->
+    <!-- 表格区 -->
+    <!-- 分页区 -->
+    <!-- 弹窗区 -->
+  </div>
+</template>
+
+<script setup>
+// 1. 导入
+// 2. 响应式状态
+// 3. 表单/验证规则
+// 4. 数据获取
+// 5. 事件处理（CRUD）
+// 6. 生命周期
+</script>
+```
+
+---
+
+## 6. 间距规范
+
+| 场景 | 间距 |
+|---|---|
+| 内容区内边距 | `p-4`（16px） |
+| 卡片间距 | `mb-4`（16px） |
+| 表单项间距 | Element Plus 默认（`el-form` 管理） |
+| 操作按钮间距 | `ml-2`（8px，同行按钮） |
+
+---
+
+## 7. 状态规范
+
+| 状态 | 实现方式 |
+|---|---|
+| 加载中 | `v-loading="loading"`（`el-table`、`el-card`） |
+| 空状态 | `el-empty`（有描述、有图） |
+| 错误状态 | `el-result` type="error"（提供重试按钮） |
+| 操作成功 | `ElMessage.success('操作成功')` |
+| 操作失败 | `ElMessage.error(error.message)` |
+| 危险操作确认 | `el-popconfirm`（行内）/ `ElMessageBox.confirm`（批量） |
+
+---
+
+*最后更新: 2026-02-26*
diff --git a/docs/guides/ui-specs-user.md b/docs/guides/ui-specs-user.md
new file mode 100644
index 0000000..3a8b067
--- /dev/null
+++ b/docs/guides/ui-specs-user.md
@@ -0,0 +1,157 @@
+# 🎨 UI 规范 — 用户端（Case-Database-Frontend-user）
+
+> 用户端设计规范。AI 在 `Case-Database-Frontend-user/` 中还原设计稿或新建页面时参考本文档。
+> 核心原则：**移动优先、性能优先、品牌一致**
+
+---
+
+## 1. 设计系统
+
+| 项目 | 选型 |
+|---|---|
+| CSS 方案 | Tailwind CSS v3 |
+| 图标 | Lucide Icons（`lucide-vue-next`） |
+| 字体 | 系统字体栈（中文优先）|
+| 动效 | CSS Transition（避免 JS 动画影响性能） |
+
+---
+
+## 2. 色彩系统
+
+```css
+:root {
+  /* 品牌主色 — 根据实际品牌替换 */
+  --color-primary: #3B82F6;       /* blue-500 */
+  --color-primary-dark: #1D4ED8;  /* blue-700（hover） */
+  --color-primary-light: #EFF6FF; /* blue-50（背景） */
+
+  /* 功能色 */
+  --color-success: #10B981;  /* green-500 */
+  --color-warning: #F59E0B;  /* amber-500 */
+  --color-danger:  #EF4444;  /* red-500 */
+  --color-info:    #6B7280;  /* gray-500 */
+
+  /* 文本层级 */
+  --color-text-primary:   #111827;  /* gray-900 */
+  --color-text-secondary: #6B7280;  /* gray-500 */
+  --color-text-disabled:  #D1D5DB;  /* gray-300 */
+
+  /* 背景 */
+  --color-bg-page:  #F9FAFB;  /* gray-50 */
+  --color-bg-card:  #FFFFFF;
+  --color-border:   #E5E7EB;  /* gray-200 */
+}
+```
+
+---
+
+## 3. 字体规范
+
+| 用途 | 大小 | 字重 | Tailwind 类 |
+|---|---|---|---|
+| 页面大标题 | 24px / 1.5rem | 700 | `text-2xl font-bold` |
+| 卡片标题 | 18px / 1.125rem | 600 | `text-lg font-semibold` |
+| 正文 | 14px / 0.875rem | 400 | `text-sm` |
+| 辅助/标签 | 12px / 0.75rem | 400 | `text-xs` |
+| 按钮文字 | 14px / 0.875rem | 500 | `text-sm font-medium` |
+
+---
+
+## 4. 间距系统（4px 基准）
+
+| 场景 | 间距 | Tailwind 类 |
+|---|---|---|
+| 行内元素间距 | 8px | `gap-2` / `space-x-2` |
+| 卡片内边距 | 16px | `p-4` |
+| 区块间间距 | 24px | `gap-6` / `mb-6` |
+| 页面两侧边距 | 16px（移动）/ 24px（桌面） | `px-4 md:px-6` |
+| 页面顶部安全区 | 16px | `pt-4` |
+
+---
+
+## 5. 响应式断点（移动优先）
+
+| 断点 | 最小宽度 | 典型设备 | 设计优先级 |
+|---|---|---|---|
+| `默认` | 375px | 手机（主力） | ⭐⭐⭐⭐⭐ |
+| `sm` | 640px | 大屏手机 | ⭐⭐⭐⭐ |
+| `md` | 768px | 平板竖屏 | ⭐⭐⭐ |
+| `lg` | 1024px | 平板横屏/小桌面 | ⭐⭐ |
+| `xl` | 1280px | 桌面 | ⭐ |
+
+**断点使用顺序**（必须从小写起）：
+```html
+<!-- ✅ 正确：移动端默认，再扩展 -->
+<div class="w-full md:w-1/2 lg:w-1/3">
+
+<!-- ❌ 错误：桌面优先写法 -->
+<div class="w-1/3 lg:w-full">
+```
+
+---
+
+## 6. 组件规范
+
+### 按钮
+
+```html
+<!-- 主要操作 -->
+<button class="w-full rounded-lg bg-primary py-3 text-sm font-medium text-white active:opacity-80">
+  立即购买
+</button>
+
+<!-- 次要操作 -->
+<button class="w-full rounded-lg border border-gray-300 py-3 text-sm font-medium text-gray-700">
+  加入购物车
+</button>
+```
+
+规则：
+- 移动端主操作按钮通常 `w-full`，高度 ≥ 44px
+- 按钮文字简短（≤ 6 字）
+- 加载中禁用按钮并显示 Spinner
+
+### 卡片
+
+```html
+<div class="rounded-xl bg-white p-4 shadow-sm">
+  <!-- 内容 -->
+</div>
+```
+
+### 空状态 / 错误状态（必须实现）
+
+```html
+<!-- 空状态 -->
+<div class="flex flex-col items-center py-16 text-gray-400">
+  <LucidePackageOpen class="mb-3 h-12 w-12" />
+  <p class="text-sm">暂无数据</p>
+</div>
+
+<!-- 骨架屏（优先于 Loading Spinner） -->
+<div class="animate-pulse rounded-xl bg-gray-100 h-24 w-full" />
+```
+
+---
+
+## 7. 触摸交互规范
+
+- 所有可点击元素最小尺寸：**44 × 44px**
+- 相邻可点击元素间距 ≥ **8px**
+- 列表项点击区域铺满整行
+- 避免 hover 专属交互（移动端无 hover）
+
+---
+
+## 8. 视觉还原流程
+
+1. 识别所属前端（用户端 = 本文档）
+2. 分析设计稿的色彩、间距（对齐上方规范）
+3. 移动端布局先行，再添加 md/lg 断点适配
+4. 使用 Tailwind 语义类（避免任意值 `w-[123px]`）
+5. 实现空状态、加载状态、错误状态
+6. 验证触摸目标尺寸
+
+---
+
+*最后更新: 2026-02-26*
diff --git a/docs/guides/ui-specs.md b/docs/guides/ui-specs.md
new file mode 100644
index 0000000..8a9460b
--- /dev/null
+++ b/docs/guides/ui-specs.md
@@ -0,0 +1,47 @@
+# 🎨 UI Specifications
+
+> 通用 UI 设计规范。具体以 `ui-specs-user.md`（用户端）和 `ui-specs-admin.md`（管理端）为准。
+
+---
+
+## 设计系统
+
+| 维度 | 用户端 (Case-Database-Frontend-user/) | 管理端 (Case-Database-Frontend-admin/) |
+|---|---|---|
+| **组件方案** | Tailwind CSS + 自定义组件 | Element Plus + Tailwind CSS |
+| **图标** | Lucide Icons | @element-plus/icons-vue |
+| **字体** | 系统字体栈 (system-ui) | 系统字体栈 (system-ui) |
+| **设计风格** | 品牌化、轻量、视觉吸引力 | 专业、实用、信息密度高 |
+| **响应式** | 移动优先 (xs → xl) | 桌面优先 (≥ 1280px) |
+
+## 间距
+
+使用 Tailwind 默认间距 (4px 基准):
+- 紧凑: `gap-2` (8px)
+- 标准: `gap-4` (16px)
+- 宽松: `gap-6` (24px)
+- 区块: `gap-8` (32px)
+
+## 响应式断点
+
+| 断点 | 宽度 | 说明 |
+|------|------|------|
+| sm | 640px | 大手机 |
+| md | 768px | 平板 |
+| lg | 1024px | 小桌面 |
+| xl | 1280px | 桌面 |
+| 2xl | 1536px | 大屏 |
+
+## 视觉还原流程
+
+当提供设计稿截图时:
+1. 确认目标前端（用户端 or 管理端）
+2. 分析颜色、间距、字体
+3. 识别组件层级
+4. 用户端：使用 Tailwind CSS 还原；管理端：优先使用 Element Plus 组件
+5. 注意细节: 阴影、圆角、边框
+6. 如不确定，列出选项询问
+
+---
+
+*最后更新: 2026-02-26*
diff --git a/docs/runbooks/backend-debug.md b/docs/runbooks/backend-debug.md
new file mode 100644
index 0000000..2d032c2
--- /dev/null
+++ b/docs/runbooks/backend-debug.md
@@ -0,0 +1,304 @@
+# Backend Debug Runbook
+
+## 常见问题排查
+
+### 1. 登录返回 401 "账号或密码错误"
+
+#### 症状
+```bash
+curl -X POST http://127.0.0.1:9501/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username": "superadmin", "password": "Admin@2026"}'
+# 返回: {"code": 401, "message": "账号或密码错误"}
+```
+
+#### 排查步骤
+
+1. **检查数据库是否有用户**
+```bash
+docker exec hyperf-mysql mysql -uroot -p123456 case_db \
+  -e "SELECT id, username, phone FROM auth_users WHERE deleted_at IS NULL;"
+```
+
+2. **如果用户不存在，运行 Seeder**
+```bash
+docker exec hyperf-skeleton php bin/hyperf.php db:seed --class=DatabaseSeeder
+```
+
+3. **验证密码比对逻辑**
+```bash
+# 检查 User Model 是否使用 password_hash 和 password_verify
+# 确保 Seeder 中的密码也是用 password_hash 加密的
+```
+
+### 2. 返回 500 "Internal Server Error" - env() 未定义
+
+#### 症状
+```bash
+curl -X POST http://127.0.0.1:9501/api/auth/sms/send \
+  -H "Content-Type: application/json" \
+  -d '{"phone": "18970867739", "purpose": "login"}'
+# 返回: {"code": 500, "message": "Internal Server Error"}
+```
+
+#### 日志错误
+```
+[ERROR] Call to undefined function env()[43] in /opt/www/modules/Auth/src/Service/SmsService.php
+[ERROR] #0 /opt/www/runtime/container/proxy/Modules_Auth_Http_Controller_Api_SmsController.proxy.php(42): 
+    Modules\Auth\Service\SmsService->send()
+```
+
+#### 根因
+PHP CLI 和 Swoole Worker 环境中**不提供全局 `env()` 函数**（这是 Laravel 特有的），会导致 `Call to undefined function env()` 错误。
+
+#### 解决方案
+
+**修改前（错误）**：
+```php
+// ❌ 在 Service/Middleware 中直接使用 env()
+if (env('APP_ENV', 'development') !== 'production') {
+    // ...
+}
+$secret = env('JWT_SECRET', 'default');
+```
+
+**修改后（正确）**：
+```php
+// ✅ 使用 Hyperf 的 config() 函数读取配置
+$appEnv = \Hyperf\Config\config('app.env', 'development');
+if ($appEnv !== 'production') {
+    // ...
+}
+$secret = \Hyperf\Config\config('jwt.secret', 'default-secret');
+```
+
+**配置文件正确写法**（在配置文件中可以使用 env()）：
+```php
+// config/autoload/jwt.php
+use function Hyperf\Support\env;
+
+return [
+    'secret' => env('JWT_SECRET', 'dev-fallback-secret'),
+    'ttl' => (int) env('JWT_TTL', 7200),
+];
+```
+
+**常见错误场景**：
+```php
+// ❌ Service 层中使用 env()
+class SmsService {
+    public function send() {
+        if (env('APP_ENV') !== 'production') { // 报错
+            // ...
+        }
+    }
+}
+
+// ❌ Middleware 层中使用 env()
+class JwtAuthMiddleware {
+    public function process() {
+        $secret = env('JWT_SECRET'); // 报错
+    }
+}
+
+// ❌ 即使添加命名空间前缀也不行
+if (\env('APP_ENV') !== 'production') { // 仍然报错
+```
+
+**正确实践**：
+```php
+// ✅ Service 层使用 config()
+use Hyperf\Config\config;
+
+class SmsService {
+    public function send() {
+        $appEnv = config('app.env', 'development');
+        if ($appEnv !== 'production') {
+            // ...
+        }
+    }
+}
+
+// ✅ 配置文件中使用 env()（正确位置）
+// config/autoload/app.php
+use function Hyperf\Support\env;
+
+return [
+    'env' => env('APP_ENV', 'development'),
+    'debug' => env('APP_DEBUG', false),
+];
+```
+
+### 3. Token 验证失败 - Secret 不一致
+
+#### 症状
+```bash
+# 登录成功
+TOKEN=$(curl -s -X POST http://127.0.0.1:9501/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username": "superadmin", "password": "Admin@2026"}' | jq -r '.data.access_token')
+
+# 但 profile 接口返回 40102
+curl -X GET "http://127.0.0.1:9501/api/auth/profile" \
+  -H "Authorization: Bearer $TOKEN"
+# 返回: {"code": 40102, "message": "Token invalid"}
+```
+
+#### 根因
+AuthService 和 JwtAuthMiddleware 使用不同的 JWT secret。
+
+#### 解决方案
+
+**确保两处使用相同的 secret**：
+
+```php
+// AuthService.php
+protected function generateToken(User $user, string $type = 'access', ?int $ttlOverride = null): string
+{
+    $secret = 'dev-only-insecure-secret-20260304'; // 固定值，不要用 md5(__DIR__)
+    // ...
+}
+
+// JwtAuthMiddleware.php
+public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
+{
+    // ...
+    $secret = 'dev-only-insecure-secret-20260304'; // 与 AuthService 完全相同
+    $decoded = JWT::decode($token, new Key($secret, 'HS256'));
+    // ...
+}
+```
+
+**禁止的做法**：
+```php
+// ❌ 使用 md5(__DIR__) 会导致路径不一致
+$secret = 'dev-only-insecure-key-' . md5(__DIR__);
+```
+
+### 4. 服务启动失败 - 异步队列配置缺失
+
+#### 症状
+```bash
+docker compose restart hyperf-skeleton
+docker logs hyperf-skeleton --tail 50
+```
+
+#### 日志错误
+```
+[ERROR] Entry "Modules\Security\Listener\SecurityEventListener" cannot be resolved: 
+Entry "Hyperf\AsyncQueue\Driver\DriverFactory" cannot be resolved
+```
+
+或
+
+```
+[ERROR] [Error] default is a invalid driver
+```
+
+#### 根因
+使用了异步队列，但缺少 `config/autoload/async_queue.php` 配置。
+
+#### 解决方案
+
+创建配置文件：
+```php
+<?php
+
+declare(strict_types=1);
+
+use function Hyperf\Support\env;
+
+return [
+    'default' => [
+        'driver' => env('ASYNC_QUEUE_DRIVER', 'redis'),
+        'channel' => 'queue',
+        'retry_after' => 60,
+        'block_seconds' => 5,
+        'max_messages' => 100,
+        'redis' => [
+            'pool' => 'default',
+        ],
+    ],
+];
+```
+
+### 5. 服务启动失败 - Config 对象未注入
+
+#### 症状
+```
+[ERROR] Entry "Hyperf\Config\Config" cannot be resolved: 
+Parameter $configs of __construct() has no value defined or guessable
+```
+
+#### 根因
+Hyperf Config 对象未在 dependencies.php 中注册。
+
+#### 解决方案
+
+**检查 `config/autoload/dependencies.php`**：
+```php
+return [
+    Hyperf\Database\Migrations\Migrator::class => App\Database\MigratorFactory::class,
+    Hyperf\Database\Seeders\Seed::class => App\Database\SeedFactory::class,
+    // 确保 Config 不在这里注册（Hyperf 会自动注册）
+];
+```
+
+## 验证清单
+
+### 新模块开发前
+- [ ] 检查是否需要队列配置
+- [ ] 检查是否需要缓存配置
+- [ ] 检查是否需要 JWT 配置
+- [ ] 所有 `env()` 都有默认值
+
+### 代码修改后
+- [ ] 不在 Service/Middleware 中使用 `config()`
+- [ ] JWT secret 使用固定值或环境变量
+- [ ] AuthService 和 JwtAuthMiddleware 使用相同 secret
+- [ ] 重启服务并测试关键路径
+
+### 部署前
+- [ ] 生产环境设置 `JWT_SECRET` 环境变量
+- [ ] 检查 .env.example 是否包含所有必要的环境变量
+- [ ] 运行 Seeder 确保初始数据正确
+
+## 调试命令
+
+### 查看日志
+```bash
+# Hyperf 应用日志
+docker logs hyperf-skeleton --tail 100 -f
+
+# 数据库日志
+docker logs hyperf-mysql --tail 50
+
+# Redis 日志
+docker logs hyperf-redis --tail 50
+```
+
+### 进入容器调试
+```bash
+docker exec -it hyperf-skeleton bash
+
+# 运行迁移
+php bin/hyperf.php migrate
+
+# 运行 Seeder
+php bin/hyperf.php db:seed
+
+# 检查 PHP 语法
+php -l modules/Auth/src/Service/AuthService.php
+```
+
+### 测试 API
+```bash
+# 登录
+curl -X POST http://127.0.0.1:9501/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username": "superadmin", "password": "Admin@2026"}'
+
+# 使用 token 访问受保护接口
+TOKEN="your-access-token-here"
+curl -X GET "http://127.0.0.1:9501/api/auth/profile" \
+  -H "Authorization: Bearer $TOKEN"
diff --git a/docs/runbooks/deployment.md b/docs/runbooks/deployment.md
new file mode 100644
index 0000000..a251426
--- /dev/null
+++ b/docs/runbooks/deployment.md
@@ -0,0 +1,226 @@
+# 🚢 Deployment Runbook
+
+> PHP Hyperf + Swoole + Vue 3 部署流程指南
+
+---
+
+## 环境
+
+| 环境 | URL | 触发 |
+|------|-----|------|
+| Development | `localhost:8200` (前端) / `localhost:9501` (后端) | 本地开发 |
+| Staging | `staging.example.com` | merge to `develop` |
+| Production | `www.example.com` | merge to `main` |
+
+## Docker Compose 模板
+
+```yaml
+version: '3.8'
+
+services:
+  # Nginx — 负载均衡 + 静态资源 + SSL
+  nginx:
+    image: nginx:1.25-alpine
+    container_name: app_nginx
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./docker/nginx/nginx.conf:/etc/nginx/nginx.conf
+      - ./docker/nginx/conf.d:/etc/nginx/conf.d
+      - ./Case-Database-Frontend-user/dist:/usr/share/nginx/html/user
+      - ./Case-Database-Frontend-admin/dist:/usr/share/nginx/html/admin
+      - ./docker/nginx/ssl:/etc/nginx/ssl
+    depends_on:
+      - hyperf
+    networks:
+      - app_network
+    restart: unless-stopped
+
+  # Hyperf — PHP 8.1 + Swoole (HTTP + WebSocket)
+  hyperf:
+    build:
+      context: ./Case-Database-Backend
+      dockerfile: Dockerfile
+    container_name: app_backend
+    ports:
+      - "9501:9501"   # HTTP API
+      - "9502:9502"   # WebSocket
+    volumes:
+      - ./Case-Database-Backend:/opt/www
+    environment:
+      - APP_ENV=${APP_ENV:-production}
+      - DB_HOST=mysql
+      - DB_PORT=3306
+      - DB_DATABASE=${DB_DATABASE}
+      - DB_USERNAME=${DB_USERNAME}
+      - DB_PASSWORD=${DB_PASSWORD}
+      - REDIS_HOST=redis
+      - REDIS_PORT=6379
+      - REDIS_AUTH=${REDIS_AUTH}
+    depends_on:
+      mysql:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    networks:
+      - app_network
+    restart: unless-stopped
+
+  # MySQL 8.1 — 主数据库
+  mysql:
+    image: mysql:8.1
+    container_name: app_mysql
+    ports:
+      - "${DB_PORT:-3307}:3306"
+    environment:
+      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
+      MYSQL_DATABASE: ${DB_DATABASE}
+      MYSQL_USER: ${DB_USERNAME}
+      MYSQL_PASSWORD: ${DB_PASSWORD}
+    volumes:
+      - mysql_data:/var/lib/mysql
+      - ./docker/mysql/conf.d:/etc/mysql/conf.d
+      - ./docker/mysql/init:/docker-entrypoint-initdb.d
+    command: >
+      --default-authentication-plugin=caching_sha2_password
+      --character-set-server=utf8mb4
+      --collation-server=utf8mb4_unicode_ci
+      --max-connections=500
+      --innodb-buffer-pool-size=1G
+      --slow-query-log=ON
+      --long-query-time=1
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - app_network
+    restart: unless-stopped
+
+  # Redis 7 — 缓存 + 队列 + Session
+  redis:
+    image: redis:7.2-alpine
+    container_name: app_redis
+    ports:
+      - "${REDIS_PORT:-6379}:6379"
+    command: redis-server --requirepass ${REDIS_AUTH} --maxmemory 512mb --maxmemory-policy allkeys-lru
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "-a", "${REDIS_AUTH}", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - app_network
+    restart: unless-stopped
+
+volumes:
+  mysql_data:
+    driver: local
+  redis_data:
+    driver: local
+
+networks:
+  app_network:
+    driver: bridge
+```
+
+## Backend Dockerfile
+
+```dockerfile
+FROM hyperf/hyperf:8.1-alpine-v3.18-swoole
+
+LABEL maintainer="Enterprise Digital Platform"
+
+ENV TIMEZONE=Asia/Shanghai
+ENV APP_ENV=production
+
+WORKDIR /opt/www
+
+COPY composer.json composer.lock ./
+RUN composer install --no-dev --optimize-autoloader --no-scripts
+
+COPY . .
+RUN composer dump-autoload -o
+
+EXPOSE 9501 9502
+
+ENTRYPOINT ["php", "/opt/www/bin/hyperf.php", "start"]
+```
+
+## 部署检查清单
+
+### 部署前
+- [ ] 所有后端测试通过 (`composer test`)
+- [ ] 所有前端测试通过 (`npm test`)
+- [ ] 代码审查已批准
+- [ ] 数据库迁移已准备 (`php bin/hyperf.php migrate:status`)
+- [ ] 环境变量已配置 (`.env`)
+- [ ] Redis 连接正常
+- [ ] 静态分析通过 (`composer analyse`)
+
+### 部署步骤
+```bash
+# 1. 拉取最新代码
+git pull origin main
+
+# 2. 后端依赖更新
+cd Case-Database-Backend && composer install --no-dev -o
+
+# 3. 数据库迁移
+php bin/hyperf.php migrate
+
+# 4. 前端构建
+cd Case-Database-Frontend-user && npm ci && npm run build
+cd ../Case-Database-Frontend-admin && npm ci && npm run build
+
+# 5. 重启服务
+docker-compose restart hyperf
+docker-compose restart nginx
+
+# 6. 验证
+curl -s https://your-domain.com/admin/health | jq
+```
+
+### 部署后
+- [ ] 健康检查通过
+- [ ] 监控无异常 (CPU/内存/连接数)
+- [ ] 数据库迁移成功
+- [ ] WebSocket 连接正常
+- [ ] 队列消费进程运行中
+
+## 回滚
+
+```bash
+# 代码回滚
+git revert HEAD
+git push origin main
+
+# 数据库回滚
+php bin/hyperf.php migrate:rollback --step=1
+
+# Docker 容器回滚到上一个镜像
+docker-compose pull hyperf
+docker-compose up -d hyperf
+```
+
+## 扩展到多实例
+
+```bash
+# 水平扩展 Hyperf 实例
+docker-compose up -d --scale hyperf=3
+
+# Nginx upstream 配置多后端
+upstream hyperf_cluster {
+    server hyperf_1:9501;
+    server hyperf_2:9501;
+    server hyperf_3:9501;
+}
+```
+
+---
+
+*最后更新: YYYY-MM-DD*
diff --git a/docs/runbooks/incident-response.md b/docs/runbooks/incident-response.md
new file mode 100644
index 0000000..8b1c9eb
--- /dev/null
+++ b/docs/runbooks/incident-response.md
@@ -0,0 +1,54 @@
+# 🚨 Incident Response
+
+> 事故响应流程 (PHP Hyperf + Vue 3)
+
+---
+
+## 严重等级
+
+| 等级 | 定义 | 响应时间 |
+|------|------|----------|
+| P0 | 服务完全不可用 | 15 分钟内 |
+| P1 | 核心功能受损 | 1 小时内 |
+| P2 | 非核心功能受损 | 4 小时内 |
+| P3 | 轻微问题 | 1 工作日 |
+
+## 响应流程
+
+1. **确认**: 确认问题、评估影响范围和严重等级
+2. **通知**: 通知相关人员 (企业微信 / Slack #incidents)
+3. **修复**: 定位问题、实施修复或回滚
+4. **验证**: 确认修复有效
+5. **复盘**: 编写事后分析报告
+
+## 常用命令
+
+```bash
+# 查看后端日志
+tail -f runtime/logs/hyperf.log
+
+# Docker 查看日志
+docker compose logs -f hyperf
+
+# 检查数据库连接
+php bin/hyperf.php tinker --execute="Db::select('SELECT 1')"
+
+# 检查 Swoole 状态
+curl http://localhost:9501/admin/health
+
+# 快速回滚代码
+git revert HEAD && git push origin main
+
+# 回滚数据库迁移
+php bin/hyperf.php migrate:rollback --step=1
+
+# Docker 回滚到上一版本
+docker compose pull && docker compose up -d
+
+# 重启服务
+docker compose restart hyperf
+```
+
+---
+
+*最后更新: 2026-02-24*
diff --git a/docs/specs/F1-认证与账户.md b/docs/specs/F1-认证与账户.md
new file mode 100644
index 0000000..c5db683
--- /dev/null
+++ b/docs/specs/F1-认证与账户.md
@@ -0,0 +1,483 @@
+# F1 统一认证与账户中心
+
+> **涉及端**：用户端（`Case-Database-Frontend-user`）+ 后端（`Case-Database-Backend`）
+>
+> **关联文档**：
+> - API 契约：[api-contracts.md §2.1 用户端认证](../architecture/api-contracts.md)
+> - 数据模型：[data-model.md §4.1 用户与权限域](../architecture/data-model.md)
+> - UI 规范：[ui-specs-user.md](../guides/ui-specs-user.md)
+> - 参考原型：`docs/reference/登录页.html`
+
+---
+
+## 目标与边界
+
+- 在保持本系统独立账号体系前提下，实现与企业数字化平台便捷互通登录
+- 覆盖账号登录、短信登录、扫码登录、OAuth 登录、企业 SSO、注册、找回密码与个人中心
+- 完善验证码、风控、审计、会话安全与协议合规，不在前端和日志中存储敏感明文
+
+---
+
+## 开发状态说明
+
+> - 🟢 已完成 — 前后端均已联调可用
+> - 🟡 前端已完成 — 前端 UI 和交互已实现，待后端对接
+> - 🟠 前端部分完成 — 前端 UI 存在但逻辑为占位/模拟，需补全
+> - ⚪ 待开发 — 前后端均未开发
+
+## 功能清单
+
+| 编号 | 功能 | 优先级 | 状态 |
+|------|------|--------|------|
+| F1.1 | 多模式登录（账号 / 短信 / 扫码） | P0 | 🟠 部分完成 |
+| F1.2 | 第三方授权登录（微信 / QQ） | P1 | 🟠 仅入口 UI |
+| F1.3 | 账户辅助功能（自动登录 / 忘记密码） | P0 | 🟠 部分完成 |
+| F1.4 | 全局主题切换（深色 / 浅色） | P1 | 🟢 已完成 |
+| F1.5 | 简易个人中心 | P1 | 🟠 仅基础展示 |
+| F1.6 | 用户注册 | P0 | 🟠 仅 UI 框架 |
+| F1.7 | 安全管理后台 | P1 | ⚪ 待开发 |
+| F1.8 | 企业 SSO 集成 | P1 | ⚪ 待开发 |
+| F1.9 | 多端会话管理 | P2 | ⚪ 待开发 |
+
+---
+
+## F1.1 多模式登录（P0） — 🟠 部分完成
+
+### 开发现状
+
+| 子功能 | 前端 | 后端 | 说明 |
+|--------|------|------|------|
+| 左右分屏布局 | ✅ | — | `LoginView.vue` + `LoginBanner.vue` |
+| 账号密码登录 | ✅ | ✅ | `LoginTabPanel.vue` → `useLoginForms.handleLogin` → `authApi.login` 已联调 |
+| 短信登录表单 | ✅ | ❌ | UI 已实现（Headless UI TabPanel），但逻辑仅 Toast 提示"短信登录未实现" |
+| 密码明文切换 | ✅ | — | `AppInput.vue` 已支持 |
+| 账号/短信标签页切换 | ✅ | — | Headless UI `TabGroup` 实现 |
+| 扫码登录 | ❌ | ❌ | 未实现（无二维码图标入口、无二维码区域） |
+| 图形验证码 | ✅ | ✅ | 拼图滑块验证码已实现，登录/注册/发短信前触发 |
+| 登录成功跳转 redirect | ✅ | — | 路由守卫已携带 `redirect` 参数，登录后跳转已实现 |
+| Loading 态 | ✅ | — | 提交时按钮 Loading 态已实现 |
+| 错误提示统一 | ❌ | ❌ | 当前直接暴露后端原始错误，未做统一化处理 |
+
+### 用户故事
+
+作为用户，我希望通过账号、短信和扫码三种方式快速登录，并在异常场景下得到明确、可恢复的提示。
+
+### 功能描述
+
+- 登录页采用左右分屏：左侧品牌展示，右侧认证功能区
+- 账号登录与短信登录通过表单内顶部标签页切换（仅两个标签：账号登录 / 短信登录）
+- 账号登录：`username` 或手机号 + 密码，支持明文切换
+- 短信登录：手机号 + 短信验证码
+- 扫码登录：点击输入区右上角二维码图标切换到二维码区域（独立于标签页）
+
+### 交互细节
+
+- 账号/短信切换：两个标签页原地切换，共享底部区域（第三方登录入口、协议勾选）
+- 扫码切换：点击二维码图标后，整个表单区（含标签页）执行 `fade + slide` 过渡替换为二维码区；二维码区右上角提供"返回账号登录"图标，点击后恢复表单
+- 二维码区包含：二维码、刷新按钮、剩余有效时间（180 秒）和状态文本
+- 扫码状态流转：等待扫描 → 待用户确认 → 确认中 → 登录成功
+- 二维码过期自动刷新并提示"二维码已更新，请重新扫码"
+- "登录"与"发送短信"前，均需通过图形验证码挑战
+
+### 表单与校验规则
+
+- `username`：4-20 位，字母数字下划线
+- `phone`：符合中国大陆手机号格式
+- `password`：8-20 位，必须同时包含字母和数字，拒绝常见弱口令（后端维护弱口令黑名单，如 `12345678`、`password`、`qwerty123`）
+- `sms_code`：6 位数字，5 分钟有效
+- 密码强度指示（注册和修改密码场景显示）：弱 = 仅满足最低长度和字符要求；中 = 含大小写混合或特殊字符；强 = 12 位以上且含大小写 + 数字 + 特殊字符
+- 登录错误提示统一为"账号或密码错误"或"账号或校验信息不匹配"
+
+### 错误与加载态
+
+- 提交按钮进入 Loading 态，防重复点击
+- 网络超时：提示"网络异常，请稍后重试"
+- 验证码过期：提示并自动刷新验证码挑战
+- 风控限流：返回剩余重试时间，并提示稍后再试
+- 账号锁定：提示锁定时长和解锁路径（短信解锁或等待）
+
+### 登录成功跳转
+
+- 如果用户登录前访问了需认证的页面（被拦截跳转到登录页），登录成功后自动跳回该页面
+- 前端通过 URL query 参数 `redirect` 携带原始路径，登录成功后读取并跳转
+- `redirect` 值必须为站内相对路径，禁止跳转到外部 URL（防开放重定向攻击）
+- 无 `redirect` 参数时默认跳转首页
+
+### 验收标准
+
+- [x] 账号密码登录可认证并跳转首页
+- [x] 账号/短信标签页可正常切换，共享底部区域
+- [x] 登录成功后跳回 `redirect` 指定的站内页面
+- [x] 密码输入支持明文/密文切换
+- [x] 提交按钮有 Loading 态
+- [ ] 短信登录对接后端 API（当前为占位）
+- [ ] 扫码登录功能完整实现
+- [x] 登录/发送短信均经过图形验证码验证
+- [ ] 二维码支持倒计时与自动刷新
+- [ ] 错误提示统一化处理（不暴露后端原始错误）
+
+---
+
+## F1.2 第三方授权登录（P1） — 🟠 仅入口 UI
+
+### 开发现状
+
+| 子功能 | 前端 | 后端 | 说明 |
+|--------|------|------|------|
+| 微信/QQ 登录入口展示 | ✅ | — | `ThirdPartyLogin.vue` 已渲染图标 |
+| OAuth 跳转 | ❌ | ❌ | 按钮无点击事件 |
+| 回调处理 | ❌ | ❌ | 无回调页面和逻辑 |
+| 手机号绑定引导 | ❌ | ❌ | |
+
+### 用户故事
+
+作为用户，我希望使用微信或 QQ 一键登录，避免重复注册。
+
+### 功能描述
+
+- 登录区底部展示微信、QQ 登录入口
+- 首次授权自动创建账号并建立绑定，后续直接登录
+
+### 交互细节
+
+- OAuth 流程：跳转授权页 → 授权 → 回调 → 绑定或登录 → 跳转原页面
+- 未绑定用户引导补充手机号（若第三方未提供可靠手机号）
+- 已绑定用户直接签发本系统会话 Token
+
+### 数据约定
+
+- 首次 OAuth 创建账号时，`users.source` 设为对应 provider（`wechat` / `qq`）
+- 手机号冲突处理：若 OAuth 返回的手机号已被其他本地账号绑定，提示用户"该手机号已注册，请用该手机号登录后在个人中心绑定"，不自动合并
+
+### 验收标准
+
+- [x] 微信/QQ 登录入口 UI 已展示
+- [ ] 微信 OAuth 跳转和回调流程完整可用
+- [ ] QQ OAuth 跳转和回调流程完整可用
+- [ ] 已绑定用户直接登录，未绑定用户进入绑定流程
+
+---
+
+## F1.3 账户辅助功能（P0） — 🟠 部分完成
+
+### 开发现状
+
+| 子功能 | 前端 | 后端 | 说明 |
+|--------|------|------|------|
+| 自动登录勾选 UI | ✅ | ❌ | `LoginTabPanel.vue` 勾选框已实现，但未真正影响会话有效期 |
+| 忘记密码表单 UI | ✅ | ❌ | `ForgotPanel.vue` 表单已实现，含用户名/手机号/验证码/新密码字段 |
+| 忘记密码提交逻辑 | ❌ | ❌ | `useLoginForms.handleForgot` 为 `setTimeout` 模拟，无 API 调用 |
+| 验证码发送 | ❌ | ❌ | `sendCode` 仅 Toast 提示，无真实发送 |
+
+### 用户故事
+
+作为用户，我希望系统记住登录状态并在忘记密码时快速恢复访问。
+
+### 功能描述
+
+- 自动登录：勾选后延长会话有效期（30 天）
+- 忘记密码：账号/手机号 + 短信验证码 + 新密码重置
+
+### 找回密码流程
+
+1. 输入账号或手机号（至少填一项；OAuth 用户可能无 username，此时仅填手机号即可）
+2. 验证关联手机号并发送短信验证码
+3. 校验验证码后设置新密码并确认
+4. 重置成功后跳转登录页
+
+### 安全规则
+
+- 错误提示统一为"账号或校验信息不匹配"，避免账号枚举
+- 新密码不可与最近一次密码相同
+- 重置成功后主动使历史会话失效
+
+### 验收标准
+
+- [x] 自动登录勾选 UI 可用
+- [x] 忘记密码表单 UI 完整（含用户名、手机号、验证码、新密码字段）
+- [ ] 自动登录勾选后真正延长会话有效期
+- [ ] 忘记密码对接后端 API
+- [ ] 短信验证码发送对接后端 API
+- [ ] 重置密码后旧会话失效
+
+---
+
+## F1.4 全局主题切换（P1） — 🟢 已完成
+
+### 开发现状
+
+| 子功能 | 前端 | 后端 | 说明 |
+|--------|------|------|------|
+| 主题切换图标 | ✅ | — | 登录页已实现切换按钮 |
+| 深色/浅色双主题 | ✅ | — | 使用 `@vueuse/core` 的 `useDark` + `useToggle` |
+| 偏好持久化 | ✅ | — | `useDark` 自动持久化到 `localStorage` |
+| 系统偏好跟随 | ✅ | — | `useDark` 默认跟随 `prefers-color-scheme` |
+
+### 用户故事
+
+作为用户，我希望在深色模式和浅色模式间切换，以适配不同使用环境。
+
+### 功能描述
+
+- 顶部导航栏提供主题切换图标
+- 支持浅色/深色两套主题，并在本地持久化
+- 支持 `prefers-color-scheme` 初次自动跟随
+
+### 验收标准
+
+- [x] 切换后全局 UI 立即生效
+- [x] 刷新页面后主题偏好保持
+- [ ] 核心页面在深色模式下可读性正常（需全页面回归验证）
+
+---
+
+## F1.5 简易个人中心（P1） — 🟠 仅基础展示
+
+### 开发现状
+
+| 子功能 | 前端 | 后端 | 说明 |
+|--------|------|------|------|
+| 导航栏用户信息展示 | ✅ | ✅ | `AppNavbar.vue` 展示昵称或"用户"，已登录/未登录切换正常 |
+| 下拉菜单 | ❌ | — | 无下拉菜单组件，无个人信息/修改密码/绑定管理入口 |
+| 退出登录 | ❌ | ❌ | 导航栏无退出入口，`userStore.logout` 方法已存在但未绑定到 UI |
+| 账号注销 | ❌ | ❌ | |
+
+### 用户故事
+
+作为已登录用户，我希望查看自身信息并管理账户安全相关操作。
+
+### 功能描述
+
+- 顶部导航右侧展示头像、昵称、角色标签
+- 下拉菜单：个人信息、修改密码、绑定管理、退出登录
+- 支持账号注销入口（7 天冷静期，可撤销）
+
+### 验收标准
+
+- [x] 登录态展示用户昵称，未登录态展示"登录"链接
+- [ ] 导航栏增加下拉菜单（个人信息、修改密码、绑定管理、退出登录）
+- [ ] 退出登录功能可用
+- [ ] 账号注销流程含冷静期提示与撤销能力
+
+---
+
+## F1.6 用户注册（P0） — 🟠 仅 UI 框架
+
+### 开发现状
+
+| 子功能 | 前端 | 后端 | 说明 |
+|--------|------|------|------|
+| 注册表单 UI | ✅ | — | `RegisterPanel.vue` 已实现（用户名、手机号、验证码、密码、确认密码） |
+| 昵称字段 | ❌ | — | 当前注册表单缺少昵称输入项 |
+| 密码强度指示 | ❌ | — | 未实现 |
+| 协议勾选 | ❌ | — | 未实现 |
+| 注册提交逻辑 | ❌ | ❌ | `useLoginForms.handleRegister` 为 `setTimeout` 模拟，无 API 调用 |
+| 验证码发送 | ❌ | ❌ | 仅 Toast，无真实发送 |
+| `auth.ts` 注册 API | ❌ | ❌ | 未定义 `register` 方法 |
+
+### 用户故事
+
+作为新用户，我希望通过账号注册快速完成开户并进入系统。
+
+### 功能描述
+
+- 注册字段：账号（username）、昵称（nickname）、手机号、短信验证码、密码、确认密码
+- 昵称为选填，留空时系统自动生成默认昵称（如"用户\_" + 随机 6 位字符）
+- 页面实时显示密码强度（弱/中/强）
+- 注册前必须确认协议（默认未勾选）
+
+### 校验规则
+
+- 账号唯一，手机号唯一
+- 账号不允许使用系统保留词（`admin`、`system`、`root`、`test`、`api`、`null`、`undefined` 等），后端维护保留词列表
+- 账号须通过敏感词过滤，拒绝包含违规内容的用户名
+- 昵称长度限制 2-30 字符，同样需通过敏感词过滤
+- 密码复杂度：8-20 位，必须同时包含字母和数字，拒绝常见弱口令（如 `12345678`、`password`、`qwerty123`），后端维护弱口令黑名单
+- 短信验证码 5 分钟有效，错误次数达到阈值后触发风控
+
+### 数据约定
+
+- 注册创建账号时，`users.source` 设为 `local`
+- `users.user_type` 注册时固定为 `user`，管理员仅由后台创建
+
+### 验收标准
+
+- [x] 注册表单基础 UI 已实现（用户名、手机号、验证码、密码、确认密码）
+- [ ] 注册表单补充昵称字段
+- [ ] 密码强度实时指示
+- [ ] 协议勾选组件及拦截逻辑
+- [ ] 注册对接后端 API（`authApi.register`）
+- [ ] 短信验证码对接后端 API
+- [ ] 系统保留词和敏感词被拒绝并给出明确提示
+- [ ] 协议未同意时不可提交注册
+
+---
+
+## F1.7 安全管理后台（P1） — ⚪ 待开发
+
+### 功能描述
+
+- 黑名单管理：IP、设备指纹、账号维度封禁/解封
+- 登录日志：时间、IP、设备、登录类型、成功/失败、风控命中原因
+- 账号锁定记录：支持检索与手动解锁
+- 风控策略配置：阈值、封禁时长、白名单
+
+### 验收标准
+
+- [ ] 可查看和检索登录审计日志
+- [ ] 可配置限流和锁定策略
+- [ ] 支持手动解封和白名单管理
+
+---
+
+## F1.8 企业 SSO 集成（P1） — ⚪ 待开发
+
+### 用户故事
+
+作为企业内部用户，我希望从企业数字化平台无感知进入本系统。
+
+### 设计原则
+
+- 本系统保持独立账号池和会话体系
+- 企业平台作为外部 IdP，通过桥接流程完成认证
+- 协议优先级：OIDC/OAuth2（首选）> 自定义签名票据（兜底）
+
+### 账号映射策略
+
+1. 优先按 `enterprise_user_id` 绑定本地账号
+2. 未绑定时按手机号/邮箱进行二次确认绑定
+3. 仍无匹配账号则创建外部来源账号并标记来源
+
+### 直达登录要求
+
+- 支持企业平台深链：`state` + `nonce` + 回调白名单
+- 凭据短时效、一次性使用，防重放
+- SSO 登录失败可回退本地登录
+
+### 验收标准
+
+- [ ] 企业用户可从外部平台直达登录
+- [ ] 首次登录自动完成绑定或创建
+- [ ] 企业平台不可用时，本地登录路径不受影响
+
+---
+
+## F1.9 多端会话管理（P2） — ⚪ 待开发
+
+### 功能描述
+
+- 个人中心展示当前账号在线会话列表（设备、地区、最近活跃时间）
+- 支持手动踢出指定会话
+- 系统可配置是否允许多端同时在线（单点挤占）
+
+### 验收标准
+
+- [ ] 可查看在线会话并识别当前设备
+- [ ] 支持踢出其他设备并即时生效
+- [ ] 单点挤占模式下，新登录会使旧会话失效
+
+---
+
+## 图形验证码与协议合规 — ⚪ 待开发
+
+### 图形验证码规范
+
+- 挑战类型：拼图滑块（slider puzzle）
+- 触发点：登录提交、发送短信、注册提交、找回密码关键步骤
+- 交互流程：
+  1. 前端调用 `POST /api/auth/captcha/challenge`，后端生成随机 `target_x` 位置（60 ~ width-60），连同 `captcha_token`、`width`、`target_x` 一起返回
+  2. 前端展示拼图区域：上方为带有缺口（target gap）的背景图案，缺口位于 `target_x` 处；滑块控制一个拼图块在背景上水平移动
+  3. 用户拖动滑块将拼图块对齐缺口位置，松手后前端提交 `answer_x` 到 `POST /api/auth/captcha/verify`
+  4. 后端校验 `abs(answer_x - target_x) <= tolerance`（tolerance = 10px），通过后标记 `captcha_verified:{token}`
+  5. 验证通过后前端获得一次性 `captcha_token`（5 分钟有效），提交业务请求时携带，后端校验后立即销毁
+- 视觉反馈：拼图块接近缺口时（误差 ≤ 10px），缺口和拼图块同步变为绿色，提示用户已对齐
+- 校验数据存储于 Redis（非 MySQL），防止数据库压力
+
+### 协议同意规范
+
+- 登录和注册页展示"我已阅读并同意《用户协议》《隐私政策》"
+- 默认不勾选；未勾选提交时弹窗提醒并提供"一键同意并继续"
+- 服务端记录 `agree_at` 与 `agreement_version`
+
+---
+
+## 安全与风控策略 — ⚪ 待开发
+
+### 限流规则
+
+- 登录：同 IP 5 次/分钟；同账号 10 次/小时
+- 短信：同手机号 1 次/分钟，5 次/天
+- 注册：同 IP 3 次/小时
+- 密码重置：同账号 3 次/天
+
+### 分级响应
+
+- L1 轻度异常：提升验证码难度
+- L2 中度异常：账号/IP/设备短期限流
+- L3 重度异常：冻结高风险动作并触发人机复核
+- L4 确认恶意：自动拉黑并进入观察名单
+
+### 防攻击要求
+
+- 防撞库：统一错误提示，不暴露账号存在性
+- 防暴力破解：连续 5 次密码错误锁定 30 分钟
+- 防重放：SSO 一次性状态值 + 回调校验
+- 会话安全：Access Token 2h，Refresh Token 7d，支持轮换与吊销
+
+### Token 存储方案
+
+- Access Token 通过 `httpOnly`、`Secure`、`SameSite=Strict` Cookie 下发，前端不可通过 JS 读取，防止 XSS 窃取
+- Refresh Token 同样存储在 `httpOnly` Cookie 中，路径限制为 `/api/auth/refresh`
+- 禁止将 Token 存储在 `localStorage` 或 `sessionStorage`
+
+> **当前实现差异**：`userStore` 当前将 Token 存储在 `localStorage` 中，需在后端 Cookie 方案就绪后迁移。
+
+### 退出登录范围
+
+- 常规退出（F1.5 下拉菜单"退出登录"）：仅使当前设备的 Access Token 和 Refresh Token 失效
+- 全部退出（F1.9 会话管理"退出所有设备"）：使账号下所有会话 Token 失效
+- 密码重置（F1.3）和账号锁定触发时：自动使所有会话 Token 失效
+
+---
+
+## 已开发代码索引
+
+> 供研发快速定位已有实现，避免重复开发。
+
+| 文件路径 | 职责 |
+|----------|------|
+| `src/views/login/LoginView.vue` | 登录主页面：左右分屏、视图切换（login/register/forgot）、主题切换 |
+| `src/views/login/components/LoginTabPanel.vue` | 账号登录 + 短信登录标签页、自动登录勾选 |
+| `src/views/login/components/RegisterPanel.vue` | 注册表单 UI |
+| `src/views/login/components/ForgotPanel.vue` | 忘记密码表单 UI |
+| `src/views/login/components/ThirdPartyLogin.vue` | 微信/QQ 第三方登录入口 UI |
+| `src/views/login/components/LoginBanner.vue` | 左侧品牌展示区 |
+| `src/views/login/composables/useLoginForms.ts` | 表单状态和提交逻辑（账号登录已联调，其余为占位） |
+| `src/components/ui/AppInput.vue` | 通用输入框（含密码明文切换） |
+| `src/components/auth/useCaptchaSlider.ts` | 拼图滑块验证码核心逻辑（拖拽、对齐检测、验证提交） |
+| `src/api/auth.ts` | 认证 API（login / logout / refresh / getProfile / updateProfile / captcha） |
+| `src/stores/user.ts` | 用户状态管理（token / userInfo / login / logout） |
+| `src/router/index.ts` | 路由守卫（未登录 → /login?redirect=xxx） |
+| `src/components/layout/AppNavbar.vue` | 导航栏（登录态展示昵称，未登录展示登录链接） |
+
+---
+
+## 分阶段落地建议
+
+- Phase A（P0）：短信登录对接、注册对接、忘记密码对接、图形验证码、协议勾选、注册补昵称/密码强度
+- Phase B（P0）：企业 SSO 桥接、账号映射与直达登录
+- Phase C（P0/P1）：风控引擎、自动拉黑、安全后台、Token 存储迁移至 httpOnly Cookie
+- Phase D（P1）：个人中心下拉菜单、退出登录、OAuth 对接、多端会话管理、监控告警
+
+---
+
+## 验收指标
+
+- 正常用户登录成功率 ≥ 98%
+- 短信接口恶意触发量按周下降
+- 企业用户无感登录成功率持续提升且不影响外部用户路径
+- 协议同意和风控决策具备可审计追溯能力
+
+---
+
+*最后更新: 2026-03-04*
diff --git a/docs/specs/F2-首页.md b/docs/specs/F2-首页.md
new file mode 100644
index 0000000..f68d184
--- /dev/null
+++ b/docs/specs/F2-首页.md
@@ -0,0 +1,303 @@
+# F2 首页
+
+> **涉及端**：用户端（`Case-Database-Frontend-user`）+ 后端（`Case-Database-Backend`）
+>
+> **关联文档**：
+> - API 契约：[api-contracts.md §2.2 用户端案例](../architecture/api-contracts.md) / [§2.4 用户端内容](../architecture/api-contracts.md)
+> - 数据模型：[data-model.md §4.2 案例核心域](../architecture/data-model.md) / [§4.4 运营内容域](../architecture/data-model.md)
+> - UI 规范：[ui-specs-user.md](../guides/ui-specs-user.md)
+> - 参考原型：`docs/reference/首页.html`
+
+---
+
+## 功能清单
+
+| 编号 | 功能 | 优先级 | 状态 |
+|------|------|--------|------|
+| F2.1 | 顶部导航与分类频道 | P0 | 🟢 已实现 |
+| F2.2 | 全局模糊搜索 | P0 | 🟡 部分实现 |
+| F2.3 | Hero 焦点推荐位 | P0 | 🟢 已实现 |
+| F2.4 | 多维条件过滤与收藏夹 | P0 | 🟡 部分实现 |
+| F2.5 | 富数据项目卡片 | P0 | 🟢 已实现 |
+| F2.6 | 底部全局模块 | P2 | ⚪ 待开发 |
+
+> **状态说明**：🟢 已实现 = 前端 UI 与核心交互已完成；🟡 部分实现 = UI 框架已有，部分子功能待开发；⚪ 待开发 = 尚未启动。
+
+---
+
+## F2.1 顶部导航与分类频道（P0 · 🟢 已实现）
+
+### 用户故事
+
+作为用户，我希望通过分类频道快速定位感兴趣的案例类型，并在右上角管理个人账户和主题偏好。
+
+### 功能描述
+
+- 顶部固定导航栏：Logo + 分类频道 + 搜索 + 用户区
+- 分类频道标签：全部 / 别墅 / 室内 / 民宿 / 景观 / 专题 / 设计师
+- 切换频道后内容区实时过滤更新
+- **用户区（右上角）**：
+  - 未登录：显示「登录」按钮
+  - 已登录：显示用户头像，点击展开下拉菜单（个人信息 / 我的收藏 / 退出登录）
+  - 主题切换按钮：暗色 ↔ 亮色模式切换，偏好持久化至 `localStorage`
+- 登录成功后默认跳转至首页
+
+### 交互细节
+
+- **导航栏滚动行为**：初始透明背景，页面滚动超过 80px 后过渡为实色背景（带阴影）
+- **频道切换过渡动效**：当前激活频道下方显示指示线，切换时指示线平滑滑动
+- **主题切换**：图标在 `SunIcon`（亮色）与 `MoonIcon`（暗色）之间切换，带旋转过渡动效
+
+### 验收标准
+
+- [x] 频道切换时内容区无刷新更新（SPA 路由）
+- [x] 当前激活频道高亮显示，带下方指示线
+- [x] 导航栏滚动时保持固定（sticky），透明 → 实色背景过渡
+- [x] 频道标签顺序：全部 / 别墅 / 室内 / 民宿 / 景观 / 专题 / 设计师
+- [x] 右上角未登录显示登录按钮，已登录显示头像及下拉菜单
+- [x] 暗色 / 亮色主题可切换，偏好持久化
+
+---
+
+## F2.2 全局模糊搜索（P0 · 🟡 部分实现）
+
+### 用户故事
+
+作为用户，我希望通过关键词快速找到目标案例，以便提高检索效率。
+
+### 功能描述
+
+- 全局搜索框，支持搜索：项目名称、项目编号、建筑师姓名
+- 搜索框位置：导航栏右侧（桌面端）
+- 搜索结果实时展示联想下拉，或回车跳转搜索结果页
+
+### 交互细节
+
+- **实时联想下拉**：输入关键词后 300ms 防抖触发搜索请求，下拉面板最多展示 8 条匹配结果，匹配关键词高亮
+- **搜索历史记录**：持久化至 `localStorage`，保留最近 10 条搜索词，支持一键清除全部历史
+- **搜索结果页**：回车后跳转至搜索结果页，结果按相关度排序，支持分页
+- **空结果**：展示友好的空状态插图 + 推荐搜索词
+
+### 验收标准
+
+- [x] 搜索框在导航栏中可见
+- [ ] 输入关键词后 300ms 防抖触发联想下拉
+- [ ] 联想下拉最多展示 8 条，匹配关键词高亮
+- [ ] 搜索历史持久化，支持清除
+- [ ] 空结果展示空状态插图与推荐词
+
+---
+
+## F2.3 Hero 焦点推荐位（P0 · 🟢 已实现）
+
+### 用户故事
+
+作为运营，我希望在管理端自定义首页大图的内容（图片、标题、描述等），以便灵活引导用户注意力。
+
+### 功能描述
+
+首页顶部全宽大图轮播区域，支持两种内容源（管理端创建轮播条目时选择）：
+
+- **`image`（单图模式）**：上传背景图 + 自定义标题 / 描述 / 标签文字 / 跳转链接
+- **`topic`（专题模式）**：选择已有专题，自动继承专题封面、标题、描述，点击跳转专题详情页
+
+#### 自定义字段（均由管理端配置，前端不硬编码）
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| `label` | 左上角标签文字 | "精选项目" / "本周专题" |
+| `title` | 大标题 | "云端墅 — 现代都市别墅的极致诠释" |
+| `description` | 描述摘要 | "三层框架结构，340㎡ 全功能空间" |
+| `cta_text` | 行动按钮文字 | "阅读全文" / "查看专题" |
+| `link_url` | 点击跳转地址 | "/cases/88" / "/topics/3" |
+| `image` | 背景图片 URL | — |
+
+#### 轮播行为
+
+- 自动播放，间隔 5s，鼠标 hover 时暂停自动播放
+- 手动切换：左右箭头按钮 + 底部圆点指示器
+- 过渡动效：淡入淡出 + 轻微水平位移
+- 背景图片带灰度滤镜处理
+
+### 交互细节
+
+- **轮播指示器**：底部圆点，当前项高亮，点击可跳转到对应条目
+- **左右箭头**：默认隐藏，鼠标 hover 轮播区域时显示，点击切换上/下一条
+- **骨架屏**：轮播数据加载前显示骨架屏占位，避免布局抖动
+
+### 验收标准
+
+- [x] 轮播支持自动播放（5s 间隔）与手动切换
+- [x] 管理端配置的标题 / 描述 / 标签在前端实时呈现
+- [x] `image` 类型条目支持自定义跳转任意内链
+- [x] `topic` 类型条目点击后跳转专题详情页
+- [x] 热门标签点击后跳转至对应筛选结果
+
+---
+
+## F2.4 多维条件过滤与收藏夹（P0 · 🟡 部分实现）
+
+### 用户故事
+
+作为设计师，我希望通过多个维度交叉筛选案例，或快速查看我收藏的项目，以便精准定位参考案例。
+
+### 功能描述
+
+- **快捷风格 Tab**（🟢 已实现）：横向风格标签切换（全部风格 / 现代 / 中式 / 新中式 / 欧式 / 田园 / 其它）
+- **高级筛选器**（🟢 已实现）：下拉面板，支持多维度交叉筛选（面积范围、造价范围、层数、结构类型等）
+- **视图切换**（🟢 已实现）：网格视图（Grid）与列表视图（List）双模式切换
+- **收藏夹入口**（⚪ 待开发）：快捷筛选"我收藏的"案例
+
+### 收藏夹交互流程
+
+1. 点击筛选栏中的「收藏夹」按钮 → 卡片列表切换为仅展示当前用户已收藏的案例
+2. 再次点击「收藏夹」按钮或刷新页面 → 退出收藏夹模式，恢复全量列表
+3. 收藏夹模式激活时，按钮高亮显示以区分状态
+4. 未登录用户点击「收藏夹」 → 弹出登录引导弹窗
+5. 收藏夹模式下无收藏内容 → 显示空状态引导（"去发现喜欢的案例"）
+
+### 交互细节
+
+- **筛选条件 URL 同步**：所有筛选参数（`category`、`style`、`keyword`、`favorites` 等）写入 URL query string，支持浏览器前进/后退和分享链接
+- **已选条件展示**：以「标签胶囊」形式显示在筛选栏下方，支持单项点击清除或一键全部重置
+- **筛选面板动效**：展开/折叠使用从顶部向下滑入的过渡
+- **筛选变更后的刷新策略**：清空现有卡片，重新加载首屏数据（非追加）
+
+### 验收标准
+
+- [x] 风格 Tab 切换实时过滤卡片内容
+- [x] 高级筛选器支持多条件叠加且可一键重置
+- [x] 视图切换（网格 / 列表）保持筛选状态不丢失
+- [ ] 收藏夹按钮点击后切换到已收藏内容，再次点击或刷新退出
+- [ ] 收藏夹按钮激活时高亮区分
+- [ ] 未登录用户点击收藏夹弹出登录引导
+- [ ] 筛选参数同步至 URL query string
+
+---
+
+## F2.5 富数据项目卡片（P0 · 🟢 已实现）
+
+### 用户故事
+
+作为用户，我希望在卡片上一眼获取案例的核心参数，并通过悬浮操作快速收藏或点赞。
+
+### F2.5a 卡片结构与字段自定义
+
+- 卡片封面图（支持 Hover 缩放动效）
+- 基础信息：项目名称（`title`）、项目编号（`code`）
+- 业务标签：建筑类型角标（`category`，如别墅/民宿等）、特色标签（`tags`，如落地窗、工业风等）
+- 状态标识：精选徽章（金色角标，由 `is_featured` 字段驱动）
+- **核心参数网格（6 项外显）**：在管理端上传案例时，运营人员可自定义选择展示哪 6 项参数
+  - 字段选项池来自案例的 `dimensions` 数据（约 15+ 个维度字段：开间、进深、占地面积、建筑总面积、户型布局、预估造价、结构类型、设计师、层数等）
+  - 标题、标签、角标均读取案例对应字段，前端不硬编码
+
+### F2.5b 卡片加载策略（动态加载）
+
+- **首屏加载**：6 行 × 当前视图列数
+  - 网格模式（3 列）= 18 条
+  - 列表模式 = 6 条
+- **触底追加加载**：用户向下滚动触底时，每次追加 2 行
+  - 网格模式 = 追加 6 条
+  - 列表模式 = 追加 2 条
+- **加载中状态**：显示骨架屏（Skeleton UI）占位
+- **加载完毕**：全部数据加载完成后显示「已加载全部内容」底部提示
+- 不使用传统分页器，采用无限滚动 + 触底加载模式
+
+### F2.5c Hover 悬浮操作层
+
+- 鼠标移入卡片封面图区域 → 图片上方叠加半透明操作层，显示：
+  - **收藏按钮**（心形图标）：未收藏时空心，已收藏时实心红色
+  - **点赞按钮**（拇指图标）：显示当前点赞数
+- 鼠标移出 → 操作层淡出消失
+- **已收藏卡片的常驻标识**：封面右上角始终显示实心心形徽标（不依赖 hover 状态），方便用户一眼识别已收藏内容
+
+### F2.5d 登录拦截与跳转
+
+- 未登录用户点击收藏 / 点赞按钮 → 弹出登录引导弹窗
+- 登录成功后自动重定向回首页（通过 `redirect` 参数）
+- 点击卡片本体 → 跳转至户型详情页（无需登录）
+
+### 交互细节
+
+- **卡片 Hover**：封面图放大至 1.05 倍，卡片阴影加深，过渡时长 300ms
+- **骨架屏**：卡片加载时显示与真实卡片等尺寸的骨架占位，避免布局抖动
+- **图片懒加载**：封面图使用 `loading="lazy"` 属性，优先使用 WebP 格式
+- **视图一致性**：网格视图与列表视图展示相同的字段和操作按钮
+
+### 验收标准
+
+- [x] 卡片 Hover 时封面图平滑缩放
+- [x] 精选徽章仅对 `is_featured=true` 的案例显示
+- [x] 点击卡片跳转至户型详情页
+- [x] 支持网格视图（3 列）与列表视图
+- [x] 卡片底部 6 个参数字段由管理端自定义配置
+- [x] Hover 时显示收藏/点赞悬浮按钮，移出时消失
+- [x] 已收藏卡片封面右上角常驻心形徽标
+- [x] 首屏加载 6 行，触底追加 2 行，非一次全部加载
+- [ ] 未登录用户点击收藏/点赞弹出登录引导
+
+---
+
+## F2.6 底部全局模块（P2）
+
+### 用户故事
+
+作为用户，我希望在页面底部获取平台信息和快捷入口。
+
+### 功能描述
+
+- 订阅资讯模块：邮箱输入 + 订阅按钮
+- 分类快速链接：按建筑类型分组的快捷导航
+- 版权与协议说明
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 订阅成功/失败的反馈提示 -->
+<!-- - 邮箱重复订阅的处理 -->
+
+### 验收标准
+
+- [ ] 邮箱格式校验通过后可提交订阅
+- [ ] 分类链接跳转至对应频道页
+
+---
+
+## 补充说明
+
+### 暗色模式持久化
+
+- 主题偏好存储至 `localStorage` key `theme`，值为 `light` 或 `dark`
+- 页面初始化时读取 `localStorage`，无记录则跟随系统偏好（`prefers-color-scheme`）
+- 切换后立即生效，无需刷新页面
+
+### 骨架屏（Skeleton UI）
+
+- **Hero 轮播区**：数据加载前显示与轮播等高的灰色骨架占位
+- **卡片列表区**：加载时显示与真实卡片等尺寸的骨架卡片（含图片区 + 文字行占位）
+- 骨架屏使用 `animate-pulse` 动画，视觉上提示加载中状态
+- 避免因数据加载导致的布局累积偏移（CLS）
+
+### 图片懒加载
+
+- 卡片封面图统一使用 `loading="lazy"` 原生懒加载
+- 图片优先使用 WebP 格式，对不支持的浏览器回退到 JPEG
+- Hero 轮播首屏图片不懒加载（`loading="eager"`），确保首屏加载速度
+
+### 筛选条件 URL 同步
+
+- 所有筛选参数（`category`、`style`、`keyword`、`favorites`、`view` 等）写入 URL query string
+- 用户可通过浏览器前进/后退还原筛选状态
+- 分享 URL 后，其他用户打开可直接看到相同的筛选结果
+
+### 空状态
+
+| 场景 | 展示内容 |
+|------|----------|
+| 搜索无结果 | 空状态插图 + "未找到相关案例，试试其他关键词" |
+| 收藏夹为空 | 空状态插图 + "还没有收藏，去发现喜欢的案例" + 跳转首页按钮 |
+| 筛选无结果 | 空状态插图 + "当前条件无匹配结果，试试调整筛选" + 重置筛选按钮 |
+
+---
+
+*最后更新: 2026-03-02*
diff --git a/docs/specs/F3-案例详情.md b/docs/specs/F3-案例详情.md
new file mode 100644
index 0000000..67268e9
--- /dev/null
+++ b/docs/specs/F3-案例详情.md
@@ -0,0 +1,255 @@
+# F3 标准化案例资产详情引擎
+
+> **涉及端**：用户端（`Case-Database-Frontend-user`）+ 后端（`Case-Database-Backend`）
+>
+> **关联文档**：
+> - API 契约：[api-contracts.md §2.2 用户端案例](../architecture/api-contracts.md)（案例详情、评论、文件、相关推荐）
+> - 数据模型：[data-model.md §4.2 案例核心域](../architecture/data-model.md) / [§4.3 设计师域](../architecture/data-model.md) / [§4.5 用户互动域](../architecture/data-model.md)
+> - UI 规范：[ui-specs-user.md](../guides/ui-specs-user.md)
+> - 参考原型：`docs/reference/户型详情页.html`
+
+---
+
+## 功能清单
+
+| 编号 | 功能 | 优先级 | 状态 |
+|------|------|--------|------|
+| F3.1 | 面包屑导航 | P0 | ⚪ 待开发 |
+| F3.2 | 富媒体多维图库 | P0 | ⚪ 待开发 |
+| F3.3 | 专业级参数看板 | P0 | ⚪ 待开发 |
+| F3.4 | 侧边栏核心信息聚合 | P0 | ⚪ 待开发 |
+| F3.5 | 设计理念与主创团队 | P1 | ⚪ 待开发 |
+| F3.6 | 数字资产分发中心 | P0 | ⚪ 待开发 |
+| F3.7 | 互动与裂变闭环 | P1 | ⚪ 待开发 |
+| F3.8 | 智能推荐 | P2 | ⚪ 待开发 |
+
+---
+
+## F3.1 面包屑导航（P0）
+
+### 用户故事
+
+作为用户，我希望通过面包屑快速回到上一层级。
+
+### 功能描述
+
+- 页面顶部路径导航：首页 > 分类 > 当前项目名称
+- 支持点击任一层级跳转
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 面包屑在不同来源页面的路径生成逻辑（从首页 vs 从搜索结果） -->
+<!-- - 长标题的截断处理 -->
+
+### 验收标准
+
+- [ ] 面包屑路径正确反映当前导航层级
+- [ ] 各层级链接可正常跳转
+
+---
+
+## F3.2 富媒体多维图库（P0）
+
+### 用户故事
+
+作为用户，我希望从多个视角浏览案例的视觉资料，以便全面了解设计方案。
+
+### 功能描述
+
+- 画廊式主图展示区，支持左右切换和页码指示
+- 底部缩略图列表轮播（可横向滚动选取）
+- 快捷视图分类切换按钮：主效果图 / 平面图 / 立面图
+- 主图支持点击放大全屏浏览
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 图片预加载策略（当前 + 前后各 1 张） -->
+<!-- - 全屏模式的手势操作（滑动切换、捏合缩放） -->
+<!-- - 缩略图列表的滚动对齐逻辑 -->
+<!-- - 图片加载失败的降级显示 -->
+
+### 验收标准
+
+- [ ] 图片切换流畅无闪烁
+- [ ] 缩略图点击后主图同步更新
+- [ ] 视图分类切换后图库内容对应过滤
+- [ ] 大图模式支持键盘左右箭头切换
+
+---
+
+## F3.3 专业级参数看板（P0）
+
+### 用户故事
+
+作为设计师，我希望快速获取案例的详细技术参数，以便评估设计方案的可行性。
+
+### 功能描述
+
+5 大维度强结构化数据展示（4 列网格布局）：
+
+| 维度 | 参数项 |
+|------|--------|
+| 用地条件 | 面宽、进深、占地面积、采光限制、用地形状 |
+| 规模造价 | 建筑层数、造价预估、建筑总面积、卧室数量 |
+| 平面功能 | 楼梯类型、特色空间、卧室配置、休闲空间、厨卫配置 |
+| 外观风格 | 建筑风格、屋顶形式、外立面材料 |
+| 结构与性能 | 结构类型、基础类型、户型逻辑、墙体厚度、抗震设防、保温形式、屋面构造 |
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 各维度的折叠/展开交互（默认全部展开 vs 逐个展开） -->
+<!-- - 参数值的格式化规则（面积带单位、造价带范围） -->
+<!-- - 响应式布局（4列 → 2列 → 1列） -->
+
+### 验收标准
+
+- [ ] 5 个维度分组清晰，每组参数完整展示
+- [ ] 参数值缺失时显示"-"占位而非空白
+- [ ] 4 列网格在不同分辨率下自适应调整
+
+---
+
+## F3.4 侧边栏核心信息聚合（P0）
+
+### 用户故事
+
+作为用户，我希望在页面右侧始终看到项目的核心摘要信息。
+
+### 功能描述
+
+- 固定宽度侧边栏（约 440px），滚动时保持可见
+- 项目信息卡片：项目名称、项目 ID（支持一键复制）、收藏按钮
+- 核心数据速览：户型布局、建筑面积、面宽进深、结构类型、层高、采光限制
+- 预估造价醒目展示（大字号突出）
+- 操作按钮：分享、下载
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - Sticky 定位的起止位置（跟随区域的上下边界） -->
+<!-- - 项目 ID 复制成功的 Toast 提示 -->
+<!-- - 分享弹窗的分享渠道和链接生成逻辑 -->
+
+### 验收标准
+
+- [ ] 侧边栏随页面滚动保持固定（sticky 定位）
+- [ ] 项目 ID 一键复制到剪贴板并提示成功
+- [ ] 造价数字使用醒目样式突出显示
+
+---
+
+## F3.5 设计理念与主创团队（P1）
+
+### 用户故事
+
+作为用户，我希望了解案例背后的设计思路和创作团队。
+
+### 功能描述
+
+- 设计理念区：富文本描述 + 核心提炼标签（风格、材质、受众）
+- 主创团队区：按专业分列（方案设计、结构设计、水电设计等）的设计师名单，支持点击跳转设计师主页
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 富文本内容的最大高度和"展开/收起"逻辑 -->
+<!-- - 团队成员卡片的 Hover 效果和跳转行为 -->
+
+### 验收标准
+
+- [ ] 设计理念支持富文本渲染（段落、加粗、列表）
+- [ ] 设计师姓名可点击跳转至 F4 设计师主页
+
+---
+
+## F3.6 数字资产分发中心（P0）
+
+### 用户故事
+
+作为设计师，我希望按类别下载案例的专业源文件，以便用于实际项目参考。
+
+### 功能描述
+
+- 文件按类别归纳展示：
+  - 平面图 / CAD / PDF
+  - 外观图集 / JPG
+  - 施工图
+  - 其它
+- 每个文件显示：文件名、文件大小、下载按钮
+- 文件下载需登录认证
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 文件分类的折叠面板交互 -->
+<!-- - 下载进度的反馈方式 -->
+<!-- - 未登录用户点击下载的弹窗引导逻辑 -->
+<!-- - 大文件下载的断点续传体验 -->
+
+### 验收标准
+
+- [ ] 文件列表按类别分组，每组可展开/折叠
+- [ ] 文件大小格式化显示（KB / MB）
+- [ ] 未登录用户点击下载引导登录
+- [ ] 下载操作记录日志（审计需要）
+
+---
+
+## F3.7 互动与裂变闭环（P1）
+
+### 用户故事
+
+作为用户，我希望对感兴趣的案例进行点赞、收藏和分享，并与其他用户交流。
+
+### 功能描述
+
+- 悬浮操作栏（右下角固定）：点赞、收藏、返回顶部
+- 分享功能：生成分享链接 / 复制到剪贴板
+- 用户评论区：发表评论、查看评论列表、回复评论
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 悬浮操作栏的出现/隐藏时机（滚动方向判断） -->
+<!-- - 点赞/收藏的微动效（心跳、弹跳） -->
+<!-- - 评论的实时追加 vs 刷新策略 -->
+<!-- - 评论嵌套层级限制（最多 2 层） -->
+
+### 验收标准
+
+- [ ] 点赞 / 收藏状态实时切换并持久化
+- [ ] 评论支持分页加载
+- [ ] 评论发布后实时出现在列表顶部
+- [ ] 未登录用户操作时引导登录
+
+---
+
+## F3.8 智能推荐（P2）
+
+### 用户故事
+
+作为用户，我希望在浏览完一个案例后发现更多相似案例。
+
+### 功能描述
+
+- 详情页底部"相似推荐"卡片流（3 列网格）
+- 基于建筑类型、风格、面积等维度匹配推荐
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 推荐算法的匹配维度和权重 -->
+<!-- - 推荐卡片的懒加载时机（滚动到底部触发） -->
+
+### 验收标准
+
+- [ ] 推荐卡片至少展示 3 个相关案例
+- [ ] 点击推荐卡片跳转至对应详情页
+- [ ] 当前案例不出现在推荐列表中
+
+---
+
+*最后更新: 2026-03-02*
diff --git a/docs/specs/F4-设计师档案.md b/docs/specs/F4-设计师档案.md
new file mode 100644
index 0000000..0b67fb1
--- /dev/null
+++ b/docs/specs/F4-设计师档案.md
@@ -0,0 +1,131 @@
+# F4 设计师数字档案
+
+> **涉及端**：用户端（`Case-Database-Frontend-user`）+ 后端（`Case-Database-Backend`）
+>
+> **关联文档**：
+> - API 契约：[api-contracts.md §2.3 用户端设计师](../architecture/api-contracts.md)
+> - 数据模型：[data-model.md §4.3 设计师域](../architecture/data-model.md) / [§4.5 用户互动域（follows）](../architecture/data-model.md)
+> - UI 规范：[ui-specs-user.md](../guides/ui-specs-user.md)
+> - 参考原型：`docs/reference/个人主页.html`
+
+---
+
+## 功能清单
+
+| 编号 | 功能 | 优先级 | 状态 |
+|------|------|--------|------|
+| F4.1 | 设计师名片档案 | P0 | ⚪ 待开发 |
+| F4.2 | 背景与履历 | P1 | ⚪ 待开发 |
+| F4.3 | 商业互动通路 | P2 | ⚪ 待开发 |
+| F4.4 | 作品集矩阵 | P0 | ⚪ 待开发 |
+
+---
+
+## F4.1 设计师名片档案（P0）
+
+### 用户故事
+
+作为用户，我希望了解设计师的专业背景，以便评估其设计能力。
+
+### 功能描述
+
+- 个人信息区：
+  - 左侧：职位标签、中英文姓名、职位 / 所属机构 / 所在城市
+  - 右侧：设计师个人写真（Hover 去灰动效）
+- 资历统计：从业经验年限、完成项目数量
+- 专长标签库：如商业空间、参数化设计、现代简约、工业风等
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 写真图片的灰度 → 彩色过渡效果参数 -->
+<!-- - 资历数字的计数动画（数字滚动效果） -->
+<!-- - 标签过多时的展开/折叠逻辑 -->
+
+### 验收标准
+
+- [ ] 中英文姓名完整显示
+- [ ] 资历数据使用醒目的数字展示（大字号 + 单位标注）
+- [ ] 标签支持多个平铺展示
+
+---
+
+## F4.2 背景与履历（P1）
+
+### 用户故事
+
+作为用户，我希望深入了解设计师的设计理念和荣誉资历。
+
+### 功能描述
+
+- 设计理念深度阐述区（富文本段落）
+- 荣誉奖项时间轴列表（年份 + 奖项名称，按时间倒序）
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 时间轴的视觉样式（左侧年份 + 右侧内容卡片） -->
+<!-- - 奖项内容的展开/折叠逻辑 -->
+
+### 验收标准
+
+- [ ] 设计理念支持多段落富文本
+- [ ] 荣誉奖项按年份分组排列
+- [ ] 内容为空时展示优雅的空状态
+
+---
+
+## F4.3 商业互动通路（P2）
+
+### 用户故事
+
+作为业主，我希望关注心仪的设计师并发起商业咨询。
+
+### 功能描述
+
+- "关注"按钮：关注 / 取消关注状态切换
+- "联系设计师"按钮：展示联系方式或跳转咨询表单
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 关注按钮的状态切换动效 -->
+<!-- - 联系方式的展示形式（弹窗 vs 侧面板） -->
+<!-- - 未登录用户的引导逻辑 -->
+
+### 验收标准
+
+- [ ] 关注状态持久化，再次访问保持
+- [ ] 联系入口需登录后可用
+- [ ] 关注数量在设计师档案中可见
+
+---
+
+## F4.4 作品集矩阵（P0）
+
+### 用户故事
+
+作为用户，我希望浏览设计师的所有精选作品。
+
+### 功能描述
+
+- 3 列网格展示设计师名下的项目卡片
+- 卡片信息：封面缩略图、项目标题、建筑类型角标、面积、年份
+- 底部"加载更多"按钮（分页）
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 作品卡片与首页卡片的差异（简化版 vs 完整版） -->
+<!-- - 空作品集的展示逻辑 -->
+<!-- - 分页加载的骨架屏过渡 -->
+
+### 验收标准
+
+- [ ] 作品按发布时间倒序排列
+- [ ] 点击卡片跳转至 F3 详情页
+- [ ] "加载更多"追加卡片而非全页刷新
+
+---
+
+*最后更新: 2026-03-02*
diff --git a/docs/specs/F5-内容运营.md b/docs/specs/F5-内容运营.md
new file mode 100644
index 0000000..0f8a8ac
--- /dev/null
+++ b/docs/specs/F5-内容运营.md
@@ -0,0 +1,180 @@
+# F5 内容运营管理（F5.1 ~ F5.4）
+
+> **涉及端**：管理端（`Case-Database-Frontend-admin`）+ 后端（`Case-Database-Backend`）
+>
+> **关联文档**：
+> - API 契约：[api-contracts.md §2.6 案例管理](../architecture/api-contracts.md) / [§2.7 轮播管理](../architecture/api-contracts.md) / [§2.8 专题管理](../architecture/api-contracts.md) / [§2.9 分类标签](../architecture/api-contracts.md)
+> - 数据模型：[data-model.md §4.2 案例核心域](../architecture/data-model.md) / [§4.4 运营内容域](../architecture/data-model.md)
+> - UI 规范：[ui-specs-admin.md](../guides/ui-specs-admin.md)
+>
+> 管理端基于 Element Plus 标准后台布局，所有页面遵循**搜索栏 → 数据表格 → 分页 → 弹窗表单**的标准结构。
+
+---
+
+## 功能清单
+
+| 编号 | 功能 | 优先级 | 状态 |
+|------|------|--------|------|
+| F5.1 | 案例全生命周期管理 | P0 | ⚪ 待开发 |
+| F5.2 | 首页轮播管理 | P0 | ⚪ 待开发 |
+| F5.3 | 专题与精选管理 | P0 | ⚪ 待开发 |
+| F5.4 | 分类与标签字典 | P0 | ⚪ 待开发 |
+
+---
+
+## F5.1 案例全生命周期管理（P0）
+
+### 用户故事
+
+作为运营人员，我希望创建、编辑、发布和管理设计案例，以便持续丰富平台内容库。
+
+### 功能描述
+
+**案例 CRUD**:
+- 案例列表页：搜索（名称 / 编号 / 设计师）、按分类 / 风格 / 状态筛选、分页表格
+- 创建 / 编辑案例：多步表单或分区表单，包含基础信息、参数录入、文件上传、团队关联
+- 案例状态流转：草稿 → 待审核 → 已发布 → 已下架
+- 批量操作：批量发布、批量下架、批量删除（二次确认）
+
+**分阶段文件上传体系**:
+- 将案例的数字资产按设计阶段组织上传，阶段划分：
+
+| 阶段 | 典型文件 |
+|------|----------|
+| 平面阶段 | 平面图 CAD (.dwg)、平面布局 PDF、户型分析图 |
+| 外观阶段 | 效果图 (JPG/PNG)、外立面 CAD、鸟瞰图 |
+| 施工图阶段 | 施工图 CAD (.dwg)、施工说明 PDF |
+| 结构阶段 | 结构图 CAD、结构计算书 PDF、Revit 模型 (.rvt) |
+| 室内阶段 | 室内效果图、室内施工图、软装清单 |
+| 庭院阶段 | 庭院景观图、绿化方案、庭院施工图 |
+
+- 每个阶段支持上传多种文件类型：PDF、CAD (.dwg)、Revit (.rvt)、图片 (JPG/PNG)、压缩包 (ZIP/RAR)
+- 上传方式：批量上传 + 拖拽上传
+- 文件元数据自动提取与手动补充：文件名、大小、上传时间、上传者、阶段归属、文件类型标签
+- 单文件大小限制：图片 ≤ 20MB、文档 ≤ 100MB、模型 ≤ 500MB
+- 上传进度条 + 断点续传（大文件场景）
+
+**案例结构化参数录入**:
+- 与 F3.3 参数看板对应的 5 大维度表单（用地条件 / 规模造价 / 平面功能 / 外观风格 / 结构与性能）
+- 表单字段类型：数值输入（面宽 / 进深）、下拉选择（结构类型 / 风格）、多选标签（特色空间）、富文本（设计理念）
+- 封面图设置：从已上传图片中选取或单独上传
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 案例状态流转状态机图（draft ↔ pending → published ↔ archived） -->
+<!-- - 多步表单的步骤导航和数据暂存逻辑 -->
+<!-- - 文件上传的并发数限制和队列管理 -->
+<!-- - 大文件上传的分片策略 -->
+<!-- - 批量操作的全选/部分选中逻辑 -->
+<!-- - 表单校验规则（必填项、数值范围、字符长度） -->
+
+### 验收标准
+
+- [ ] 案例创建表单包含所有 5 大维度参数字段
+- [ ] 分阶段上传区域按 Tab 或折叠面板组织，各阶段独立管理
+- [ ] 拖拽上传支持多文件同时拖入
+- [ ] 文件超出大小限制时前端即时提示
+- [ ] 案例状态流转有明确的操作按钮（发布 / 下架 / 删除）和状态标签
+- [ ] 草稿状态的案例不在用户端展示
+- [ ] 删除操作需二次确认，已发布案例需先下架才能删除
+
+---
+
+## F5.2 首页轮播管理（P0）
+
+### 用户故事
+
+作为运营人员，我希望管理首页 Hero 大图轮播内容，以便控制用户端的首屏焦点展示。
+
+### 功能描述
+
+- 轮播项 CRUD：上传背景图、设置标题、描述摘要、跳转链接（案例详情 / 专题页 / 外部链接）
+- 排序：拖拽排序调整轮播顺序
+- 启停控制：每个轮播项支持启用 / 停用开关
+- 预览：保存前可预览轮播效果（模拟用户端展示）
+- 轮播数量限制：建议最多 5 条，超出提示
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 拖拽排序的交互实现（Sortable.js / Vue Draggable） -->
+<!-- - 背景图裁剪组件的交互（比例锁定、预览区域） -->
+<!-- - 链接类型切换时表单字段的联动变化 -->
+<!-- - 预览弹窗的模拟展示效果 -->
+
+### 验收标准
+
+- [ ] 拖拽排序后自动保存新顺序
+- [ ] 停用的轮播项不在用户端首页展示
+- [ ] 背景图上传支持裁剪（建议比例 16:9）
+- [ ] 跳转链接支持站内路由和外部 URL
+- [ ] 至少保留 1 条启用状态的轮播项
+
+---
+
+## F5.3 专题与精选管理（P0）
+
+### 用户故事
+
+作为运营人员，我希望创建专题合集并标记精选案例，以便策划内容运营活动。
+
+### 功能描述
+
+**专题管理**:
+- 专题 CRUD：标题、封面图、富文本描述、关联案例列表
+- 关联案例：从案例库中搜索并添加，支持拖拽排序
+- 专题状态：草稿 / 已发布
+
+**精选标记**:
+- 在案例列表中一键标记 / 取消精选徽章
+- 精选案例排序：拖拽调整精选展示顺序
+- 精选案例在用户端首页"精选"频道和卡片金色徽章中体现
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 关联案例的搜索选择器交互（弹窗搜索 + 已选列表） -->
+<!-- - 精选排序的可视化拖拽面板 -->
+<!-- - 专题封面图的推荐尺寸和裁剪逻辑 -->
+
+### 验收标准
+
+- [ ] 专题可关联多个案例，案例可被多个专题引用
+- [ ] 精选标记后用户端卡片立即显示金色徽章
+- [ ] 精选排序支持拖拽且保存后即时生效
+
+---
+
+## F5.4 分类与标签字典（P0）
+
+### 用户故事
+
+作为运营人员，我希望统一管理分类和标签体系，以便保持平台内容的结构化一致性。
+
+### 功能描述
+
+- **建筑类型分类**: 别墅 / 民宿 / 室内 / 景观 / 农村自建房 / 庭院等，支持 CRUD + 排序
+- **风格标签**: 现代 / 中式 / 新中式 / 欧式 / 田园 / 工业风 / 极简等，支持 CRUD + 排序
+- **特色标签**: 自由标签（落地窗 / 大露台 / 双车库等），支持 CRUD
+- 标签去重校验：创建时检查是否已存在同名标签
+- 标签引用统计：显示每个标签被多少案例引用
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 分类列表的拖拽排序交互 -->
+<!-- - 标签类型（style / feature / specialty）的分 Tab 管理 -->
+<!-- - 删除已引用标签的警告弹窗（显示关联案例数量） -->
+<!-- - 批量导入标签的功能（可选） -->
+
+### 验收标准
+
+- [ ] 分类和标签的增删改查操作正常
+- [ ] 被案例引用的标签删除时提示关联数量并要求确认
+- [ ] 排序支持拖拽且保存后用户端同步更新
+- [ ] 同名标签创建时提示重复
+
+---
+
+*最后更新: 2026-03-02*
diff --git a/docs/specs/F5-用户权限.md b/docs/specs/F5-用户权限.md
new file mode 100644
index 0000000..1fe9d6b
--- /dev/null
+++ b/docs/specs/F5-用户权限.md
@@ -0,0 +1,120 @@
+# F5 用户与权限管理（F5.5 ~ F5.7）
+
+> **涉及端**：管理端（`Case-Database-Frontend-admin`）+ 后端（`Case-Database-Backend`）
+>
+> **关联文档**：
+> - API 契约：[api-contracts.md §2.10 设计师管理](../architecture/api-contracts.md) / [§2.11 评论管理](../architecture/api-contracts.md) / [§2.12 用户与权限](../architecture/api-contracts.md)
+> - 数据模型：[data-model.md §4.1 用户与权限域](../architecture/data-model.md) / [§4.3 设计师域](../architecture/data-model.md) / [§4.5 用户互动域](../architecture/data-model.md)
+> - UI 规范：[ui-specs-admin.md](../guides/ui-specs-admin.md)
+>
+> 管理端基于 Element Plus 标准后台布局，所有页面遵循**搜索栏 → 数据表格 → 分页 → 弹窗表单**的标准结构。
+
+---
+
+## 功能清单
+
+| 编号 | 功能 | 优先级 | 状态 |
+|------|------|--------|------|
+| F5.5 | 设计师档案管理 | P1 | ⚪ 待开发 |
+| F5.6 | 评论审核 | P1 | ⚪ 待开发 |
+| F5.7 | 用户管理与权限分配 | P1 | ⚪ 待开发 |
+
+---
+
+## F5.5 设计师档案管理（P1）
+
+### 用户故事
+
+作为运营人员，我希望管理设计师的数字档案，以便维护平台设计师资源池。
+
+### 功能描述
+
+- 设计师档案 CRUD：
+  - 基础信息：中英文姓名、职位、机构、城市、个人写真
+  - 专业信息：从业年限、专长标签、设计理念（富文本）
+  - 荣誉奖项：年份 + 奖项名称，支持多条录入
+- 案例关联：将设计师绑定到案例的主创团队（方案 / 结构 / 水电等专业角色）
+- 公开展示控制：启用 / 停用设计师主页的前台可见性
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 设计师表单的分步或分区布局 -->
+<!-- - 荣誉奖项的动态表单行（新增/删除行） -->
+<!-- - 专长标签的选择器交互（从标签字典中选取 vs 自由输入） -->
+<!-- - 设计师写真的上传和裁剪规格 -->
+<!-- - 案例关联的搜索选择器 -->
+
+### 验收标准
+
+- [ ] 设计师信息编辑后在用户端 F4 主页实时更新
+- [ ] 同一设计师可关联多个案例，同一案例可关联多个设计师
+- [ ] 停用后用户端无法访问该设计师主页，但案例中仍显示姓名
+
+---
+
+## F5.6 评论审核（P1）
+
+### 用户故事
+
+作为运营人员，我希望审核用户评论，以便维护平台内容质量和社区氛围。
+
+### 功能描述
+
+- 评论列表：支持按案例 / 用户 / 时间范围 / 审核状态筛选
+- 审核操作：通过（上线展示）/ 拒绝（不展示并通知用户）/ 删除
+- 举报处理：查看被举报评论，处理举报（标记违规 / 驳回举报）
+- 审核模式配置：先审后发 / 先发后审（系统配置项）
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 评论列表的批量审核操作 -->
+<!-- - 审核通过/拒绝的快捷键操作 -->
+<!-- - 评论原文的上下文预览（关联案例信息） -->
+<!-- - 审核模式切换的影响说明弹窗 -->
+
+### 验收标准
+
+- [ ] 评论列表支持多维筛选和分页
+- [ ] 审核通过的评论在用户端 F3.7 评论区可见
+- [ ] 拒绝或删除评论后用户端实时移除
+- [ ] 先审后发模式下新评论默认不展示，待审核通过后上线
+
+---
+
+## F5.7 用户管理与权限分配（P1）
+
+### 用户故事
+
+作为管理员，我希望管理平台用户和管理员权限，以便保障平台安全运营。
+
+### 功能描述
+
+**前台用户管理**:
+- 用户列表：搜索（姓名 / 手机号）、按注册时间 / 状态筛选
+- 用户详情：注册信息、登录记录、收藏列表、下载记录、评论记录
+- 状态操作：启用 / 禁用用户账号
+
+**管理员权限管理**:
+- 管理员 CRUD：创建管理员账号、分配角色
+- RBAC 角色管理：预设角色（超级管理员 / 内容运营 / 审核员）
+- 权限粒度：按模块（案例 / 设计师 / 评论 / 用户 / 系统）分配读写权限
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 用户详情页的 Tab 布局（基础信息 / 登录记录 / 收藏 / 下载 / 评论） -->
+<!-- - 禁用用户的二次确认和影响说明（Token 立即失效） -->
+<!-- - 角色权限分配的树形菜单勾选交互 -->
+<!-- - 角色变更时的即时生效机制说明 -->
+
+### 验收标准
+
+- [ ] 禁用用户后该用户无法登录，已登录 Token 立即失效
+- [ ] 非超级管理员无法访问用户管理和系统配置模块
+- [ ] 角色权限变更后立即生效，无需重新登录
+
+---
+
+*最后更新: 2026-03-02*
diff --git a/docs/specs/F5-系统运维.md b/docs/specs/F5-系统运维.md
new file mode 100644
index 0000000..5896d73
--- /dev/null
+++ b/docs/specs/F5-系统运维.md
@@ -0,0 +1,116 @@
+# F5 系统配置与监控（F5.8 ~ F5.10）
+
+> **涉及端**：管理端（`Case-Database-Frontend-admin`）+ 后端（`Case-Database-Backend`）
+>
+> **关联文档**：
+> - API 契约：[api-contracts.md §2.13 系统配置](../architecture/api-contracts.md) / [§2.14 数据仪表盘](../architecture/api-contracts.md) / [§2.15 日志](../architecture/api-contracts.md)
+> - 数据模型：[data-model.md §4.6 日志与系统域](../architecture/data-model.md)
+> - UI 规范：[ui-specs-admin.md](../guides/ui-specs-admin.md)
+>
+> 管理端基于 Element Plus 标准后台布局，所有页面遵循**搜索栏 → 数据表格 → 分页 → 弹窗表单**的标准结构。
+
+---
+
+## 功能清单
+
+| 编号 | 功能 | 优先级 | 状态 |
+|------|------|--------|------|
+| F5.8 | 系统配置 | P1 | ⚪ 待开发 |
+| F5.9 | 数据仪表盘 | P2 | ⚪ 待开发 |
+| F5.10 | 操作日志与审计 | P2 | ⚪ 待开发 |
+
+---
+
+## F5.8 系统配置（P1）
+
+### 用户故事
+
+作为管理员，我希望配置平台的基础信息和运营参数。
+
+### 功能描述
+
+- 站点信息：平台名称、Logo、版权信息、备案号
+- SEO 配置：首页标题、描述、关键词
+- 文件上传配置：允许的文件类型、单文件大小限制
+- 评论配置：审核模式切换（先审后发 / 先发后审）
+- 水印配置：图片下载是否添加水印、水印文字 / 位置
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 配置项的分组 Tab 布局（站点 / SEO / 上传 / 评论 / 水印） -->
+<!-- - 配置修改后的即时预览（Logo / 水印） -->
+<!-- - 配置保存的确认和生效机制 -->
+<!-- - 配置变更的操作日志自动记录 -->
+
+### 验收标准
+
+- [ ] 站点信息修改后用户端全局生效
+- [ ] 文件上传限制修改后在案例管理的上传组件中即时生效
+- [ ] 配置变更记录操作日志
+
+---
+
+## F5.9 数据仪表盘（P2）
+
+### 用户故事
+
+作为运营人员，我希望通过数据看板了解平台运营状况，以便制定运营策略。
+
+### 功能描述
+
+- 概览卡片：案例总数、设计师总数、注册用户总数、今日浏览量、今日下载量
+- 热门案例排行 Top 10（按浏览 / 收藏 / 下载量排序，支持切换维度）
+- 热门设计师排行 Top 10（按关注 / 主页浏览量排序）
+- 下载统计：按文件类型分布饼图、按设计阶段分布柱状图
+- 趋势图：近 7 天 / 30 天的浏览量、注册量、下载量折线图
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 概览卡片的数据刷新策略（实时 vs 缓存） -->
+<!-- - 图表组件选型（ECharts / Chart.js） -->
+<!-- - 排行榜的时间范围选择器交互 -->
+<!-- - 趋势图的日期范围切换（7天/30天/自定义） -->
+<!-- - 仪表盘的响应式布局（2列 vs 1列） -->
+
+### 验收标准
+
+- [ ] 概览数据实时刷新（或 5 分钟缓存）
+- [ ] 排行榜支持时间范围切换（今日 / 本周 / 本月 / 全部）
+- [ ] 图表支持鼠标悬停查看具体数值
+- [ ] 大数据量下仪表盘加载时间 < 3s
+
+---
+
+## F5.10 操作日志与审计（P2）
+
+### 用户故事
+
+作为管理员，我希望查看所有管理员的操作记录，以便追溯问题和保障安全。
+
+### 功能描述
+
+- 自动记录所有管理端的写操作（创建 / 编辑 / 删除 / 状态变更）
+- 日志内容：操作时间、操作人、操作类型、操作对象、变更前后值
+- 日志列表支持按操作人 / 时间范围 / 操作类型筛选
+- 日志不可编辑、不可删除（只读）
+
+### 交互细节
+
+<!-- TODO: 补充以下内容 -->
+<!-- - 日志详情的变更对比展示（diff 视图） -->
+<!-- - 日志导出的格式和字段选择 -->
+<!-- - 日志分页的性能优化（游标分页 vs offset 分页） -->
+<!-- - 日志保留策略的配置入口 -->
+
+### 验收标准
+
+- [ ] 所有 CRUD 操作自动记录日志
+- [ ] 日志详情可展开查看变更前后对比
+- [ ] 日志数据保留至少 180 天
+- [ ] 支持按条件导出日志（CSV）
+
+---
+
+*最后更新: 2026-03-02*
diff --git a/docs/vision/PRD.md b/docs/vision/PRD.md
new file mode 100644
index 0000000..137f6b6
--- /dev/null
+++ b/docs/vision/PRD.md
@@ -0,0 +1,228 @@
+# Product Requirements Document (PRD)
+
+> **设计库** — 建筑与室内设计案例资产管理平台
+>
+> 本文档是 AI Agent 理解项目需求的核心入口。功能总览在此，各模块详规见 `docs/specs/`。
+
+---
+
+## 1. 项目概述
+
+### 1.1 项目名称
+
+**设计库** — 面向别墅、民宿、农村自建房、庭院等建筑类型的标准化设计案例数字资产平台
+
+### 1.2 项目愿景
+
+建筑与室内设计行业的案例资产高度碎片化：设计师的作品散落在各类社交平台、本地硬盘和企业内网中，缺乏统一的结构化沉淀；业主在选型时缺少专业、可信赖的案例参考源。
+
+**设计库**致力于构建一个标准化、强结构化的设计案例数字资产平台，让每一个设计案例都成为可检索、可对比、可复用的数字资产，同时为设计师提供专业的作品展示与商机转化通路。
+
+### 1.3 目标用户
+
+| 用户类型 | 描述 | 核心需求 |
+|----------|------|----------|
+| 设计师（建筑/室内） | 专业设计从业者，需要检索参考案例、沉淀个人作品集 | 高效检索、专业源文件下载、个人品牌展示 |
+| 业主 / 建房者 | 计划建房或装修的个人用户，需要灵感参考与设计师对接 | 浏览灵感、筛选户型、了解造价、联系设计师 |
+| 平台运营 | 负责案例审核、内容运营、用户管理的后台管理人员 | 案例 CRUD、内容审核、数据统计、用户管理 |
+
+---
+
+## 2. 终端与平台规划
+
+基于业务场景的多样性，采取**分阶段多端覆盖**策略：
+
+| 版本 | 终端 | 定位 | 状态 |
+|------|------|------|------|
+| V1.0 | PC Web 端 | **生产力中心** — 沉浸式大屏浏览、高阶多维筛选、大体积源文件下载 | 🔵 当前版本 |
+| V2.0 | 微信小程序 | **传播与裂变中心** — 碎片化浏览、扫码协同、一键转发、轻量社区互动 | ⚪ 远期规划 |
+| V3.0 | Revit / CAD 插件 | **专业工具集成** — 打破信息孤岛、设计资产复用、降低重复设计成本 | ⚪ 远期规划 |
+
+> V1.0 聚焦 PC Web 端，对应脚手架：`Case-Database-Backend`（后端）+ `Case-Database-Frontend-user`（用户端）+ `Case-Database-Frontend-admin`（管理端）+ `Case-Database-Frontend-shared`（共享层）。
+
+---
+
+## 3. 核心功能
+
+> **终端归属说明**：F1 ~ F4 为用户端功能（`Case-Database-Frontend-user`），F5 为管理端功能（`Case-Database-Frontend-admin`）。后端 API（`Case-Database-Backend`）同时服务两端，共享层（`Case-Database-Frontend-shared`）提供类型定义与公共逻辑。
+>
+> **详规入口**：每个模块的用户故事、功能描述、交互细节、验收标准见对应详规文件。
+
+| 优先级 | 模块 | 功能 | 状态 | 详规 |
+|--------|------|------|------|------|
+| P0 | F1 认证 | 账号密码登录 | ⚪ 待开发 | [F1-认证与账户](../specs/F1-认证与账户.md) |
+| P0 | F1 认证 | 短信验证码登录 | ⚪ 待开发 | [F1-认证与账户](../specs/F1-认证与账户.md) |
+| P0 | F1 认证 | 扫码登录 | ⚪ 待开发 | [F1-认证与账户](../specs/F1-认证与账户.md) |
+| P1 | F1 认证 | 微信 / QQ 第三方授权 | ⚪ 待开发 | [F1-认证与账户](../specs/F1-认证与账户.md) |
+| P1 | F1 认证 | 自动登录保持 / 忘记密码 | ⚪ 待开发 | [F1-认证与账户](../specs/F1-认证与账户.md) |
+| P1 | F1 认证 | 深色 / 浅色主题切换 | ⚪ 待开发 | [F1-认证与账户](../specs/F1-认证与账户.md) |
+| P0 | F2 首页 | 分类频道导航 | ⚪ 待开发 | [F2-首页](../specs/F2-首页.md) |
+| P0 | F2 首页 | 全局模糊搜索 | ⚪ 待开发 | [F2-首页](../specs/F2-首页.md) |
+| P0 | F2 首页 | Hero 焦点推荐位 | ⚪ 待开发 | [F2-首页](../specs/F2-首页.md) |
+| P0 | F2 首页 | 富数据项目卡片网格 | ⚪ 待开发 | [F2-首页](../specs/F2-首页.md) |
+| P0 | F2 首页 | 风格 Tab 快捷筛选 | ⚪ 待开发 | [F2-首页](../specs/F2-首页.md) |
+| P1 | F2 首页 | 高级多维筛选器 | ⚪ 待开发 | [F2-首页](../specs/F2-首页.md) |
+| P1 | F2 首页 | 网格 / 列表视图切换 | ⚪ 待开发 | [F2-首页](../specs/F2-首页.md) |
+| P1 | F2 首页 | 收藏夹快捷入口 | ⚪ 待开发 | [F2-首页](../specs/F2-首页.md) |
+| P2 | F2 首页 | 热门标签 / 搜索预设热词 | ⚪ 待开发 | [F2-首页](../specs/F2-首页.md) |
+| P2 | F2 首页 | 底部订阅资讯（邮箱收集） | ⚪ 待开发 | [F2-首页](../specs/F2-首页.md) |
+| P0 | F3 详情 | 富媒体多维图库 | ⚪ 待开发 | [F3-案例详情](../specs/F3-案例详情.md) |
+| P0 | F3 详情 | 5 维专业参数看板 | ⚪ 待开发 | [F3-案例详情](../specs/F3-案例详情.md) |
+| P0 | F3 详情 | 侧边栏核心信息聚合 | ⚪ 待开发 | [F3-案例详情](../specs/F3-案例详情.md) |
+| P0 | F3 详情 | 数字资产分发中心（文件下载） | ⚪ 待开发 | [F3-案例详情](../specs/F3-案例详情.md) |
+| P1 | F3 详情 | 用户评论区 | ⚪ 待开发 | [F3-案例详情](../specs/F3-案例详情.md) |
+| P1 | F3 详情 | 点赞 / 收藏 / 分享 | ⚪ 待开发 | [F3-案例详情](../specs/F3-案例详情.md) |
+| P1 | F3 详情 | 设计理念 & 主创团队展示 | ⚪ 待开发 | [F3-案例详情](../specs/F3-案例详情.md) |
+| P2 | F3 详情 | 智能相似推荐 | ⚪ 待开发 | [F3-案例详情](../specs/F3-案例详情.md) |
+| P0 | F4 设计师 | 设计师名片档案 | ⚪ 待开发 | [F4-设计师档案](../specs/F4-设计师档案.md) |
+| P0 | F4 设计师 | 作品集矩阵展示 | ⚪ 待开发 | [F4-设计师档案](../specs/F4-设计师档案.md) |
+| P1 | F4 设计师 | 资历标签 / 设计理念 / 荣誉奖项 | ⚪ 待开发 | [F4-设计师档案](../specs/F4-设计师档案.md) |
+| P2 | F4 设计师 | 关注按钮 / 联系设计师入口 | ⚪ 待开发 | [F4-设计师档案](../specs/F4-设计师档案.md) |
+| P0 | F5 管理端 | 案例 CRUD（创建 / 编辑 / 发布 / 下架） | ⚪ 待开发 | [F5-内容运营](../specs/F5-内容运营.md) |
+| P0 | F5 管理端 | 分阶段文件上传体系 | ⚪ 待开发 | [F5-内容运营](../specs/F5-内容运营.md) |
+| P0 | F5 管理端 | 案例结构化参数录入 | ⚪ 待开发 | [F5-内容运营](../specs/F5-内容运营.md) |
+| P0 | F5 管理端 | 首页轮播管理 | ⚪ 待开发 | [F5-内容运营](../specs/F5-内容运营.md) |
+| P0 | F5 管理端 | 专题与精选管理 | ⚪ 待开发 | [F5-内容运营](../specs/F5-内容运营.md) |
+| P0 | F5 管理端 | 分类与标签字典 | ⚪ 待开发 | [F5-内容运营](../specs/F5-内容运营.md) |
+| P1 | F5 管理端 | 设计师档案管理 | ⚪ 待开发 | [F5-用户权限](../specs/F5-用户权限.md) |
+| P1 | F5 管理端 | 评论审核 | ⚪ 待开发 | [F5-用户权限](../specs/F5-用户权限.md) |
+| P1 | F5 管理端 | 用户管理与权限分配 | ⚪ 待开发 | [F5-用户权限](../specs/F5-用户权限.md) |
+| P1 | F5 管理端 | 系统配置（站点信息 / SEO / 水印） | ⚪ 待开发 | [F5-系统运维](../specs/F5-系统运维.md) |
+| P2 | F5 管理端 | 数据仪表盘 | ⚪ 待开发 | [F5-系统运维](../specs/F5-系统运维.md) |
+| P2 | F5 管理端 | 操作日志与审计 | ⚪ 待开发 | [F5-系统运维](../specs/F5-系统运维.md) |
+
+---
+
+## 4. 非功能需求
+
+### 4.1 性能要求
+
+| 指标 | 目标 |
+|------|------|
+| 首屏加载（FCP） | < 2s |
+| API 响应（P95） | < 200ms |
+| 图片加载策略 | 懒加载 + WebP 格式优先 |
+| 列表渲染 | 虚拟滚动（长列表场景） |
+| 并发用户 | 1000+ |
+
+### 4.2 安全要求
+
+- [ ] JWT + Refresh Token 双令牌认证机制
+- [ ] RBAC 角色权限控制（管理端）
+- [ ] HTTPS 全站强制
+- [ ] 敏感操作审计日志（登录、下载、删除）
+- [ ] 文件下载防盗链
+- [ ] API 接口限流（令牌桶 / 滑动窗口）
+
+### 4.3 兼容性
+
+- 浏览器：Chrome 90+、Firefox 88+、Safari 14+、Edge 90+
+- 分辨率：最小支持 1280px 宽度（PC 端优先）
+
+### 4.4 设计系统
+
+| 项目 | 规范 |
+|------|------|
+| 主色 | `#C41E3A`（红色系） |
+| 金色辅助 | `#C5A059`（精选标识） |
+| 标题字体 | Noto Serif SC |
+| 正文字体 | Inter / Noto Sans SC |
+| 数据字体 | IBM Plex Mono |
+| 主题 | 支持深色模式（Dark Mode） |
+
+---
+
+## 5. 技术约束
+
+### 5.1 技术栈
+
+- **前端**: Vue 3 + Vite + TypeScript + Tailwind CSS + Pinia
+  - 管理端：Element Plus（标准后台）
+  - 用户端：Headless UI + 自定义组件（品牌化设计）
+- **后端**: PHP 8.1+ / Hyperf 3.1 / Swoole 5.0+
+- **数据库**: MySQL 8.1 + Redis 7.x
+- **部署**: Docker Compose / Nginx
+
+> 详见 [系统架构](../architecture/system-design.md)
+
+### 5.2 第三方服务
+
+| 服务 | 用途 | 状态 |
+|------|------|------|
+| 微信开放平台 | OAuth 登录授权 | ⚪ 待集成 |
+| QQ 互联 | OAuth 登录授权 | ⚪ 待集成 |
+| 阿里云 SMS | 短信验证码 | ⚪ 待集成 |
+| 阿里云 OSS / MinIO | 文件存储（CAD / PDF / 图片） | ⚪ 待集成 |
+| CDN | 静态资源与图片加速 | ⚪ 待集成 |
+
+---
+
+## 6. 里程碑
+
+| 里程碑 | 用户端交付物 | 管理端交付物 |
+|--------|-------------|-------------|
+| Alpha | 登录 + 首页（频道 / 搜索 / 卡片 / 筛选）+ 详情页（图库 / 参数 / 下载） | 案例 CRUD + 分阶段文件上传 + 轮播管理 + 分类标签字典 |
+| Beta | 设计师主页 + 收藏体系 + 评论系统 + 高级筛选 + 主题切换 | 专题精选管理 + 设计师管理 + 评论审核 + 用户管理 + 系统配置 |
+| GA | 性能优化 + 安全加固 + 第三方登录 + 智能推荐 | 数据仪表盘 + 操作日志审计 + 全链路安全加固 |
+
+---
+
+## 7. 术语表
+
+| 术语 | 定义 |
+|------|------|
+| 面宽（开间） | 建筑物主要朝向的外墙面宽度，通常为房屋正面的宽度 |
+| 进深 | 建筑物垂直于面宽方向的深度，即从前墙到后墙的距离 |
+| 占地面积 | 建筑物底层（首层）的外墙外围水平投影面积 |
+| 建筑总面积 | 各楼层建筑面积之和 |
+| 户型布局 | 房屋的功能房间配置，通常以"X 室 X 厅 X 卫"表示 |
+| 户型逻辑 | 房间功能分区与动线组织的设计合理性 |
+| 结构类型 | 建筑的主体承重结构形式（如框架结构、砖混结构、钢结构等） |
+| 基础类型 | 建筑地基的构造形式（如条形基础、筏板基础、独立基础等） |
+| 抗震设防 | 建筑设计中针对地震灾害所采取的结构措施等级 |
+| 外立面材料 | 建筑外墙的饰面材料（如真石漆、文化石、面砖等） |
+| 屋面构造 | 屋顶的结构组成和防水保温做法 |
+| 造价预估 | 建筑施工的预计总费用（不含土地成本） |
+| 数字资产 | 案例相关的可下载专业文件（CAD 图纸、PDF 方案、高清效果图等） |
+| 设计阶段 | 案例数字资产的生产环节分类，包括平面、外观、施工图、结构、室内、庭院等阶段 |
+| 数字资产包 | 一个案例按设计阶段归集的全部可下载文件的集合 |
+| CAD (.dwg) | AutoCAD 原生图纸格式，建筑设计行业的标准工程图文件 |
+| Revit (.rvt) | Autodesk Revit 建筑信息模型文件，包含三维参数化建筑数据 |
+| 精选标记 | 运营人员在管理端为优质案例添加的推荐标识，在用户端显示为金色徽章 |
+| 专题 | 运营策划的主题内容合集，关联多个案例并附带编辑性描述 |
+| RBAC | 基于角色的访问控制（Role-Based Access Control），通过角色分配管理端操作权限 |
+
+---
+
+## 8. 参考文档
+
+### 架构与技术
+
+- [系统架构](../architecture/system-design.md)
+- [数据模型](../architecture/data-model.md)
+- [API 契约](../architecture/api-contracts.md)
+- [双前端架构策略](../architecture/frontend-strategy.md)
+
+### 设计规范
+
+- [管理端 UI 规范](../guides/ui-specs-admin.md)
+- [用户端 UI 规范](../guides/ui-specs-user.md)
+
+### 功能模块详规
+
+- [F1 — 认证与账户中心](../specs/F1-认证与账户.md)
+- [F2 — 首页](../specs/F2-首页.md)
+- [F3 — 案例详情引擎](../specs/F3-案例详情.md)
+- [F4 — 设计师数字档案](../specs/F4-设计师档案.md)
+- [F5 — 内容运营管理](../specs/F5-内容运营.md)
+- [F5 — 用户与权限管理](../specs/F5-用户权限.md)
+- [F5 — 系统配置与监控](../specs/F5-系统运维.md)
+
+### 参考原型
+
+- `docs/reference/` 目录下 HTML 文件
+
+---
+
+*最后更新: 2026-03-02*
+*文档负责人: 产品团队*
diff --git a/docs/vision/roadmap.md b/docs/vision/roadmap.md
new file mode 100644
index 0000000..c7d2b64
--- /dev/null
+++ b/docs/vision/roadmap.md
@@ -0,0 +1,20 @@
+# 🗺️ Product Roadmap
+
+> 产品路线图，帮助 AI 理解项目长期方向
+
+---
+
+## 当前阶段: [Phase Name]
+
+### 近期 (本月)
+- [ ] ...
+
+### 中期 (本季度)
+- [ ] ...
+
+### 远期 (半年+)
+- [ ] ...
+
+---
+
+*最后更新: YYYY-MM-DD*
diff --git a/scripts/ai-guard.sh b/scripts/ai-guard.sh
new file mode 100644
index 0000000..82010f3
--- /dev/null
+++ b/scripts/ai-guard.sh
@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+# =============================================================================
+# AI Guard — 质量门禁脚本 (PHP Hyperf + Vue 3 双栈)
+# =============================================================================
+# 用法:
+#   bash scripts/ai-guard.sh          # 运行所有检查
+#   bash scripts/ai-guard.sh --pre    # 预提交检查
+#   bash scripts/ai-guard.sh --post   # 后执行检查
+#   bash scripts/ai-guard.sh --quick  # 快速检查 (lint + types)
+# =============================================================================
+
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+PASS=0
+FAIL=0
+WARN=0
+
+LOG_DIR=".ai-logs/guard"
+mkdir -p "$LOG_DIR"
+LOG_FILE="$LOG_DIR/$(date +%Y-%m-%d).log"
+
+HAS_NODE=false
+HAS_PHP=false
+
+# Detect project stacks
+[ -f "package.json" ] && HAS_NODE=true
+[ -f "composer.json" ] && HAS_PHP=true
+
+# Also check subdirectories
+[ -f "Case-Database-Frontend-user/package.json" ] && HAS_NODE=true
+[ -f "Case-Database-Frontend-admin/package.json" ] && HAS_NODE=true
+[ -f "Case-Database-Backend/composer.json" ] && HAS_PHP=true
+
+log() {
+  echo "[$(date +%H:%M:%S)] $*" >> "$LOG_FILE"
+}
+
+check() {
+  local name="$1"
+  local cmd="$2"
+  local required="${3:-true}"
+
+  printf "  %-30s" "$name"
+
+  if eval "$cmd" > /dev/null 2>&1; then
+    echo -e "${GREEN}✅ PASS${NC}"
+    PASS=$((PASS + 1))
+    log "PASS: $name"
+  else
+    if [ "$required" = "true" ]; then
+      echo -e "${RED}❌ FAIL${NC}"
+      FAIL=$((FAIL + 1))
+      log "FAIL: $name"
+    else
+      echo -e "${YELLOW}⚠️  WARN${NC}"
+      WARN=$((WARN + 1))
+      log "WARN: $name"
+    fi
+  fi
+}
+
+# ----- 敏感信息扫描 -----
+check_secrets() {
+  local name="Secret Scan"
+  printf "  %-30s" "$name"
+
+  local patterns=(
+    'AKIA[0-9A-Z]{16}'
+    'password\s*=\s*["'\''"][^"'\''"]+'
+    'api[_-]?key\s*=\s*["'\''"][^"'\''"]+'
+    'BEGIN\s+(RSA\s+)?PRIVATE\s+KEY'
+    'ghp_[a-zA-Z0-9]{36}'
+    'sk-[a-zA-Z0-9]{48}'
+  )
+
+  local found=false
+  for pattern in "${patterns[@]}"; do
+    if git diff --cached --diff-filter=d -U0 2>/dev/null | grep -qiE "$pattern"; then
+      found=true
+      break
+    fi
+  done
+
+  if [ "$found" = "true" ]; then
+    echo -e "${RED}❌ FAIL — 检测到疑似密钥/凭证!${NC}"
+    FAIL=$((FAIL + 1))
+    log "FAIL: $name — secrets detected"
+  else
+    echo -e "${GREEN}✅ PASS${NC}"
+    PASS=$((PASS + 1))
+    log "PASS: $name"
+  fi
+}
+
+# ----- Context Doctor (lite) -----
+check_context_lite() {
+  local name="Context Doctor Lite"
+  printf "  %-30s" "$name"
+
+  if bash scripts/context-doctor.sh --lite --strict > /dev/null 2>&1; then
+    echo -e "${GREEN}✅ PASS${NC}"
+    PASS=$((PASS + 1))
+    log "PASS: $name"
+  else
+    echo -e "${RED}❌ FAIL${NC}"
+    FAIL=$((FAIL + 1))
+    log "FAIL: $name"
+    echo -e "    ${YELLOW}↳ 运行 'bash scripts/context-doctor.sh --lite --strict' 查看详情${NC}"
+  fi
+}
+
+# ----- Frontend checks -----
+run_frontend_checks() {
+  if [ "$HAS_NODE" = "true" ]; then
+    for dir in Case-Database-Frontend-user Case-Database-Frontend-admin; do
+      if [ -f "$dir/package.json" ]; then
+        echo -e "\n  ${BLUE}── Frontend ($dir) ──${NC}"
+        check "ESLint ($dir)"      "cd $dir && npm run lint --silent"          "${1:-true}"
+        if [ "${2:-false}" = "true" ]; then
+          check "Frontend Tests ($dir)" "cd $dir && npm run test --silent"     "false"
+          check "Frontend Build ($dir)" "cd $dir && npm run build --silent"    "false"
+        fi
+      fi
+    done
+  fi
+}
+
+# ----- Backend checks -----
+run_backend_checks() {
+  if [ "$HAS_PHP" = "true" ]; then
+    echo -e "\n  ${BLUE}── Backend (PHP Hyperf / Swoole) ──${NC}"
+
+    local BACKEND_DIR="."
+    [ -d "Case-Database-Backend" ] && BACKEND_DIR="Case-Database-Backend"
+
+    check "PHPStan"     "cd $BACKEND_DIR && composer analyse --no-progress 2>/dev/null || vendor/bin/phpstan analyse --no-progress" "${1:-true}"
+    if [ "${2:-false}" = "true" ]; then
+      check "PHPUnit"  "cd $BACKEND_DIR && composer test --no-interaction 2>/dev/null || vendor/bin/phpunit" "false"
+    fi
+  fi
+}
+
+# ----- 主逻辑 -----
+MODE="${1:---post}"
+
+echo ""
+echo -e "${BLUE}🛡️  AI Guard — Quality Gateway (Dual Stack)${NC}"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+if [ "$HAS_NODE" = "true" ]; then
+  echo -e "  ${GREEN}✓${NC} Frontend detected (package.json)"
+fi
+if [ "$HAS_PHP" = "true" ]; then
+  echo -e "  ${GREEN}✓${NC} Backend detected (composer.json)"
+fi
+
+log "=== AI Guard Run: mode=$MODE node=$HAS_NODE php=$HAS_PHP ==="
+
+case "$MODE" in
+  --pre)
+    echo -e "\n${BLUE}Mode: Pre-Commit${NC}"
+    check_secrets
+    check "File count (≤10)" "[ $(git diff --cached --name-only | wc -l) -le 10 ]" "false"
+    check_context_lite
+    ;;
+  --post)
+    echo -e "\n${BLUE}Mode: Post-Execute${NC}"
+    run_frontend_checks "true"
+    run_backend_checks "true"
+    check_secrets
+    ;;
+  --quick)
+    echo -e "\n${BLUE}Mode: Quick Check${NC}"
+    run_frontend_checks "true"
+    run_backend_checks "true"
+    ;;
+  *)
+    echo -e "\n${BLUE}Mode: Full Check${NC}"
+    run_frontend_checks "true" "true"
+    run_backend_checks "true" "true"
+
+    if [ "$HAS_NODE" = "true" ]; then
+      for dir in Case-Database-Frontend-user Case-Database-Frontend-admin; do
+        if [ -f "$dir/package.json" ]; then
+          check "npm audit ($dir)" "cd $dir && npm audit --audit-level=high" "false"
+        fi
+      done
+    fi
+    if [ "$HAS_PHP" = "true" ]; then
+      BD="."
+      [ -d "Case-Database-Backend" ] && BD="Case-Database-Backend"
+      check "composer audit" "cd $BD && composer audit" "false"
+    fi
+
+    check_secrets
+    ;;
+esac
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo -e "  ${GREEN}✅ $PASS passed${NC}  ${RED}❌ $FAIL failed${NC}  ${YELLOW}⚠️  $WARN warnings${NC}"
+echo ""
+
+log "Summary: pass=$PASS fail=$FAIL warn=$WARN"
+
+if [ "$FAIL" -gt 0 ]; then
+  echo -e "${RED}💥 有必须修复的问题!${NC}"
+  exit 1
+else
+  echo -e "${GREEN}🎉 所有必要检查已通过!${NC}"
+  exit 0
+fi
diff --git a/scripts/context-doctor.sh b/scripts/context-doctor.sh
new file mode 100644
index 0000000..3ebcebc
--- /dev/null
+++ b/scripts/context-doctor.sh
@@ -0,0 +1,347 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Context Doctor — 检查项目上下文健康状态
+# =============================================================================
+# 用法:
+#   bash scripts/context-doctor.sh                # 全量检查
+#   bash scripts/context-doctor.sh --lite         # 轻量检查（提交前）
+#   bash scripts/context-doctor.sh --lite --strict
+# 功能: 检查规则文件/MCP配置/文档完整性/索引排除等
+# =============================================================================
+
+set -euo pipefail
+
+BLUE='\033[0;34m'
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+PASS=0
+WARN=0
+FAIL=0
+LITE_MODE=false
+STRICT_MODE=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --lite)
+      LITE_MODE=true
+      ;;
+    --strict)
+      STRICT_MODE=true
+      ;;
+  esac
+done
+
+check_exists() {
+  local label="$1"
+  local path="$2"
+  local required="${3:-true}"
+  
+  printf "  %-40s" "$label"
+  if [ -e "$path" ]; then
+    echo -e "${GREEN}✅${NC}"
+    PASS=$((PASS + 1))
+  elif [ "$required" = "true" ]; then
+    echo -e "${RED}❌ Missing${NC}"
+    FAIL=$((FAIL + 1))
+  else
+    echo -e "${YELLOW}⚠️  Optional${NC}"
+    WARN=$((WARN + 1))
+  fi
+}
+
+check_mcp_enabled() {
+  local server="$1"
+  local required="${2:-true}"
+
+  printf "  %-40s" "  $server"
+  if [ ! -f ".cursor/mcp.json" ]; then
+    if [ "$required" = "true" ]; then
+      echo -e "${RED}❌ mcp.json missing${NC}"
+      FAIL=$((FAIL + 1))
+    else
+      echo -e "${YELLOW}⚠️  mcp.json missing${NC}"
+      WARN=$((WARN + 1))
+    fi
+    return
+  fi
+
+  if grep -q "\"$server\"" .cursor/mcp.json; then
+    if python3 - <<PY >/dev/null 2>&1
+import json
+with open(".cursor/mcp.json", "r", encoding="utf-8") as f:
+    data = json.load(f)
+srv = data.get("mcpServers", {}).get("$server", {})
+raise SystemExit(0 if srv.get("disabled") is False else 1)
+PY
+    then
+      echo -e "${GREEN}✅ enabled${NC}"
+      PASS=$((PASS + 1))
+    else
+      if [ "$required" = "true" ]; then
+        echo -e "${YELLOW}⚠️  found but disabled${NC}"
+        WARN=$((WARN + 1))
+      else
+        echo -e "${YELLOW}⚠️  disabled${NC}"
+        WARN=$((WARN + 1))
+      fi
+    fi
+  else
+    if [ "$required" = "true" ]; then
+      echo -e "${YELLOW}⚠️  not configured${NC}"
+      WARN=$((WARN + 1))
+    else
+      echo -e "${YELLOW}⚠️  optional / not configured${NC}"
+      WARN=$((WARN + 1))
+    fi
+  fi
+}
+
+echo ""
+echo -e "${BLUE}🩺 Context Doctor — Health Check${NC}"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+echo ""
+echo -e "${BLUE}📐 Cursor Rules${NC}"
+check_exists "Constitution"   ".cursor/rules/000-constitution.mdc"
+check_exists "Workflow"       ".cursor/rules/001-workflow.mdc"
+check_exists "Safety"         ".cursor/rules/002-safety.mdc"
+check_exists "TypeScript"     ".cursor/rules/010-typescript.mdc"     "false"
+check_exists "Vue 3"          ".cursor/rules/011-vue.mdc"            "false"
+check_exists "Testing"        ".cursor/rules/015-testing.mdc"        "false"
+check_exists "Monitoring"     ".cursor/rules/024-monitoring.mdc"     "false"
+
+echo ""
+echo -e "${BLUE}🔌 MCP Configuration${NC}"
+check_exists "MCP Config"     ".cursor/mcp.json"
+
+if [ -f ".cursor/mcp.json" ]; then
+  MCP_COUNT=$(grep -c '"command"' .cursor/mcp.json 2>/dev/null || echo 0)
+  ENABLED_COUNT=$(grep -c '"disabled": false' .cursor/mcp.json 2>/dev/null || echo 0)
+  printf "  %-40s" "MCP Servers (total/enabled)"
+  echo -e "${GREEN}$MCP_COUNT / $ENABLED_COUNT${NC}"
+
+  printf "  %-40s" "Core MCP status"
+  echo ""
+  # Core servers for this template's workflow quality
+  check_mcp_enabled "filesystem" "true"
+  check_mcp_enabled "git" "true"
+  check_mcp_enabled "context7" "true"
+  check_mcp_enabled "fetch" "true"
+  check_mcp_enabled "memory" "true"
+  check_mcp_enabled "sequential-thinking" "true"
+fi
+
+echo ""
+echo -e "${BLUE}📚 Documentation${NC}"
+if [ "$LITE_MODE" = "false" ]; then
+  check_exists "PRD"            "docs/vision/PRD.md"
+  check_exists "System Design"  "docs/architecture/system-design.md"   "false"
+  check_exists "Data Model"     "docs/architecture/data-model.md"      "false"
+  check_exists "ADR Template"   "docs/architecture/decisions/_template.md" "false"
+else
+  check_exists "PRD"            "docs/vision/PRD.md"
+fi
+
+echo ""
+echo -e "${BLUE}🧠 Agent Skills${NC}"
+check_exists "Skills Directory"  ".cursor/skills"
+check_exists "Skills Rule"       ".cursor/rules/003-skills.mdc"
+if [ -d ".cursor/skills" ] && [ "$LITE_MODE" = "false" ]; then
+  SKILL_COUNT=0
+  SKILL_ERRORS=0
+  for skill_dir in .cursor/skills/*/; do
+    [ -d "$skill_dir" ] || continue
+    skill_name=$(basename "$skill_dir")
+    if [ -f "$skill_dir/SKILL.md" ]; then
+      SKILL_COUNT=$((SKILL_COUNT + 1))
+      skill_ok=true
+      # 检查 frontmatter 起始符
+      if ! head -1 "$skill_dir/SKILL.md" | grep -q "^---$"; then
+        printf "  %-40s" "  $skill_name"
+        echo -e "${RED}❌ Missing frontmatter (---)${NC}"
+        SKILL_ERRORS=$((SKILL_ERRORS + 1))
+        FAIL=$((FAIL + 1))
+        skill_ok=false
+      fi
+      # 检查 name 字段
+      if ! grep -q "^name:" "$skill_dir/SKILL.md"; then
+        printf "  %-40s" "  $skill_name"
+        echo -e "${RED}❌ Missing 'name:' field${NC}"
+        SKILL_ERRORS=$((SKILL_ERRORS + 1))
+        FAIL=$((FAIL + 1))
+        skill_ok=false
+      fi
+      # 检查 description 字段
+      if ! grep -q "^description:" "$skill_dir/SKILL.md"; then
+        printf "  %-40s" "  $skill_name"
+        echo -e "${RED}❌ Missing 'description:' field${NC}"
+        SKILL_ERRORS=$((SKILL_ERRORS + 1))
+        FAIL=$((FAIL + 1))
+        skill_ok=false
+      fi
+      # 检查 description 长度不超过 1024 字符
+      if grep -q "^description:" "$skill_dir/SKILL.md"; then
+        desc_len=$(awk '/^description:/,/^[a-z]/' "$skill_dir/SKILL.md" | wc -c)
+        if [ "$desc_len" -gt 1024 ]; then
+          printf "  %-40s" "  $skill_name"
+          echo -e "${YELLOW}⚠️  description > 1024 chars ($desc_len)${NC}"
+          WARN=$((WARN + 1))
+        fi
+      fi
+    else
+      printf "  %-40s" "  $skill_name"
+      echo -e "${RED}❌ Missing SKILL.md${NC}"
+      SKILL_ERRORS=$((SKILL_ERRORS + 1))
+      FAIL=$((FAIL + 1))
+    fi
+  done
+  printf "  %-40s" "Skills installed"
+  if [ "$SKILL_ERRORS" -eq 0 ]; then
+    echo -e "${GREEN}$SKILL_COUNT skills (all valid)${NC}"
+  else
+    echo -e "${YELLOW}$SKILL_COUNT skills ($SKILL_ERRORS with errors)${NC}"
+  fi
+  # Token 成本估算
+  SKILL_TOTAL_LINES=0
+  for f in .cursor/skills/*/SKILL.md; do
+    [ -f "$f" ] || continue
+    lines=$(wc -l < "$f" 2>/dev/null || echo 0)
+    SKILL_TOTAL_LINES=$((SKILL_TOTAL_LINES + lines))
+  done
+  printf "  %-40s" "Total skill lines (SKILL.md only)"
+  if [ "$SKILL_TOTAL_LINES" -lt 3000 ]; then
+    echo -e "${GREEN}$SKILL_TOTAL_LINES lines${NC}"
+  else
+    echo -e "${YELLOW}$SKILL_TOTAL_LINES lines (consider trimming)${NC}"
+  fi
+fi
+
+echo ""
+echo -e "${BLUE}🛠️ Tooling${NC}"
+check_exists "AI Guard"       "scripts/ai-guard.sh"
+check_exists ".cursorignore"  ".cursorignore"
+check_exists ".editorconfig"  ".editorconfig"                        "false"
+check_exists ".gitignore"     ".gitignore"
+
+echo ""
+echo -e "${BLUE}🔗 Reference Integrity${NC}"
+if command -v python3 >/dev/null 2>&1; then
+  REF_CHECK=$(
+    python3 - <<'PY'
+from pathlib import Path
+import re
+
+root = Path(".")
+broken = []
+skill_refs = 0
+rule_refs = 0
+
+# Skills: check references/*.md links in SKILL.md
+for skill in (root / ".cursor" / "skills").glob("*/SKILL.md"):
+    text = skill.read_text(encoding="utf-8")
+    refs = re.findall(r'`(references/[^`*]+\.md)`', text)
+    for ref in refs:
+        skill_refs += 1
+        target = skill.parent / ref
+        if not target.exists():
+            broken.append((str(skill), ref))
+
+# Rules: check .cursor/rules/references/*.md links in .mdc
+for rule in (root / ".cursor" / "rules").glob("*.mdc"):
+    text = rule.read_text(encoding="utf-8")
+    refs = re.findall(r'`(\.cursor/rules/references/[^`*]+\.md)`', text)
+    for ref in refs:
+        rule_refs += 1
+        target = root / ref
+        if not target.exists():
+            broken.append((str(rule), ref))
+
+print(f"SKILL_REFS={skill_refs}")
+print(f"RULE_REFS={rule_refs}")
+print(f"BROKEN={len(broken)}")
+for path, ref in broken[:10]:
+    print(f"MISS:{path} -> {ref}")
+PY
+  )
+
+  SKILL_REFS=$(echo "$REF_CHECK" | awk -F= '/^SKILL_REFS=/{print $2}')
+  RULE_REFS=$(echo "$REF_CHECK" | awk -F= '/^RULE_REFS=/{print $2}')
+  BROKEN_REFS=$(echo "$REF_CHECK" | awk -F= '/^BROKEN=/{print $2}')
+
+  printf "  %-40s" "Skill reference links checked"
+  echo -e "${GREEN}${SKILL_REFS:-0}${NC}"
+  PASS=$((PASS + 1))
+
+  printf "  %-40s" "Rule reference links checked"
+  echo -e "${GREEN}${RULE_REFS:-0}${NC}"
+  PASS=$((PASS + 1))
+
+  printf "  %-40s" "Broken reference links"
+  if [ "${BROKEN_REFS:-0}" -eq 0 ]; then
+    echo -e "${GREEN}0${NC}"
+    PASS=$((PASS + 1))
+  else
+    echo -e "${RED}${BROKEN_REFS} (see below)${NC}"
+    FAIL=$((FAIL + 1))
+    echo "$REF_CHECK" | awk '/^MISS:/ { sub(/^MISS:/, "  - "); print }'
+  fi
+else
+  printf "  %-40s" "Reference link check"
+  echo -e "${YELLOW}⚠️  skipped (python3 not found)${NC}"
+  WARN=$((WARN + 1))
+fi
+
+if [ "$LITE_MODE" = "false" ]; then
+  echo ""
+  echo -e "${BLUE}📊 Rule File Sizes${NC}"
+fi
+if [ -d ".cursor/rules" ] && [ "$LITE_MODE" = "false" ]; then
+  TOTAL_LINES=0
+  for f in .cursor/rules/*.mdc; do
+    lines=$(wc -l < "$f" 2>/dev/null || echo 0)
+    TOTAL_LINES=$((TOTAL_LINES + lines))
+  done
+  RULE_REF_COUNT=0
+  if [ -d ".cursor/rules/references" ]; then
+    RULE_REF_COUNT=$(find .cursor/rules/references -name "*.md" | wc -l)
+  fi
+  printf "  %-40s" "Total rule lines"
+  # New baseline after core/deep split:
+  # <1500: lean core rules
+  # <2500: healthy for medium projects
+  # <3500: still usable, but consider more split
+  if [ "$TOTAL_LINES" -lt 1500 ]; then
+    echo -e "${GREEN}$TOTAL_LINES lines (Lean — core rules only)${NC}"
+  elif [ "$TOTAL_LINES" -lt 2500 ]; then
+    echo -e "${GREEN}$TOTAL_LINES lines (Healthy — split mode)${NC}"
+  elif [ "$TOTAL_LINES" -lt 3500 ]; then
+    echo -e "${YELLOW}$TOTAL_LINES lines (Manageable — consider more split)${NC}"
+  else
+    echo -e "${RED}$TOTAL_LINES lines (Heavy — may waste tokens)${NC}"
+  fi
+  if [ "$RULE_REF_COUNT" -gt 0 ]; then
+    printf "  %-40s" "Rule deep references"
+    echo -e "${GREEN}$RULE_REF_COUNT files${NC}"
+  fi
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo -e "  ${GREEN}✅ $PASS${NC}  ${RED}❌ $FAIL${NC}  ${YELLOW}⚠️  $WARN${NC}"
+
+if [ "$FAIL" -gt 0 ]; then
+  echo ""
+  echo -e "${RED}Some critical files are missing. Run: bash scripts/setup.sh${NC}"
+fi
+echo ""
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi
+
+if [ "$STRICT_MODE" = "true" ] && [ "$WARN" -gt 0 ]; then
+  exit 1
+fi
diff --git a/scripts/pre-commit b/scripts/pre-commit
new file mode 100644
index 0000000..d61164e
--- /dev/null
+++ b/scripts/pre-commit
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# Git pre-commit hook — 调用 AI Guard 预提交检查
+bash scripts/ai-guard.sh --pre
diff --git a/scripts/setup.sh b/scripts/setup.sh
new file mode 100644
index 0000000..565a480
--- /dev/null
+++ b/scripts/setup.sh
@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Vibe Cursor Pro — 一键初始化脚本 (PHP Hyperf + Vue 3 双栈)
+# =============================================================================
+# 用法: bash scripts/setup.sh
+# =============================================================================
+
+set -euo pipefail
+
+BLUE='\033[0;34m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+echo ""
+echo -e "${BLUE}🚀 Vibe Cursor Pro — Setup (Dual Stack)${NC}"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# 1. 创建日志目录
+echo -e "${BLUE}📁 Creating directories...${NC}"
+mkdir -p .ai-logs/{decisions,costs,sessions,errors,guard}
+echo "   ✅ .ai-logs/"
+
+# 2. 确保脚本可执行
+chmod +x scripts/*.sh 2>/dev/null || true
+
+# 3. 设置 Git Hooks
+if [ -d ".git" ]; then
+  echo -e "${BLUE}🔗 Setting up Git hooks...${NC}"
+
+  mkdir -p .husky
+  git config core.hooksPath .husky
+
+  # Pre-commit hook
+  cat > .husky/pre-commit << 'EOF'
+#!/usr/bin/env bash
+bash scripts/ai-guard.sh --pre
+EOF
+  chmod +x .husky/pre-commit
+
+  # Commit-msg hook (Conventional Commits)
+  cat > .husky/commit-msg << 'EOF'
+#!/usr/bin/env bash
+commit_regex='^(feat|fix|refactor|test|docs|chore|style|perf|ci|build|revert)(\(.+\))?: .{1,100}'
+if ! grep -qE "$commit_regex" "$1"; then
+  echo "❌ Invalid commit message format!"
+  echo "   Expected: type(scope): description"
+  echo "   Example:  feat(auth): add OAuth login"
+  exit 1
+fi
+EOF
+  chmod +x .husky/commit-msg
+
+  echo "   ✅ Git hooks installed (.husky, core.hooksPath set)"
+else
+  echo -e "${YELLOW}⚠️  Not a git repository, skipping hooks${NC}"
+fi
+
+# 4. 验证 Skills
+echo -e "${BLUE}🧠 Validating Agent Skills...${NC}"
+if [ -d ".cursor/skills" ]; then
+  SKILL_COUNT=0
+  for skill_dir in .cursor/skills/*/; do
+    [ -d "$skill_dir" ] && [ -f "$skill_dir/SKILL.md" ] && ((SKILL_COUNT++))
+  done
+  echo "   ✅ $SKILL_COUNT skills found"
+
+  find .cursor/skills -name "*.sh" -exec chmod +x {} \; 2>/dev/null || true
+else
+  echo -e "${YELLOW}   ⚠️  No skills directory — creating .cursor/skills/${NC}"
+  mkdir -p .cursor/skills
+fi
+
+# 5. 检测前端环境
+echo -e "${BLUE}🌐 Checking frontend environment...${NC}"
+if command -v node &> /dev/null; then
+  NODE_VER=$(node --version)
+  echo -e "${GREEN}   ✅ Node.js ${NODE_VER} detected${NC}"
+else
+  echo -e "${YELLOW}   ⚠️  Node.js not found — frontend needs Node.js 20+${NC}"
+fi
+
+if command -v npm &> /dev/null; then
+  NPM_VER=$(npm --version)
+  echo -e "${GREEN}   ✅ npm ${NPM_VER} detected${NC}"
+else
+  echo -e "${YELLOW}   ⚠️  npm not found${NC}"
+fi
+
+# 6. 检测后端环境
+echo -e "${BLUE}🐘 Checking backend environment...${NC}"
+if command -v php &> /dev/null; then
+  PHP_VER=$(php -r 'echo PHP_VERSION;')
+  echo -e "${GREEN}   ✅ PHP ${PHP_VER} detected${NC}"
+
+  # Check minimum version
+  PHP_MAJOR=$(echo "$PHP_VER" | cut -d. -f1)
+  PHP_MINOR=$(echo "$PHP_VER" | cut -d. -f2)
+  if [ "$PHP_MAJOR" -lt 8 ] || ([ "$PHP_MAJOR" -eq 8 ] && [ "$PHP_MINOR" -lt 1 ]); then
+    echo -e "${RED}   ❌ PHP >= 8.1 required, found ${PHP_VER}${NC}"
+  fi
+else
+  echo -e "${YELLOW}   ⚠️  PHP not found — backend needs PHP >= 8.1${NC}"
+fi
+
+if command -v composer &> /dev/null; then
+  COMPOSER_VER=$(composer --version 2>/dev/null | head -1)
+  echo -e "${GREEN}   ✅ ${COMPOSER_VER}${NC}"
+else
+  echo -e "${YELLOW}   ⚠️  Composer not found — install from https://getcomposer.org${NC}"
+fi
+
+# Check Swoole extension
+if php -m 2>/dev/null | grep -qi swoole; then
+  SWOOLE_VER=$(php -r 'echo swoole_version();' 2>/dev/null || echo 'unknown')
+  echo -e "${GREEN}   ✅ Swoole ${SWOOLE_VER} detected${NC}"
+else
+  echo -e "${YELLOW}   ⚠️  Swoole extension not found — install via: pecl install swoole${NC}"
+fi
+
+# 7. 检测 Docker 环境
+echo -e "${BLUE}🐳 Checking Docker environment...${NC}"
+if command -v docker &> /dev/null; then
+  DOCKER_VER=$(docker --version 2>/dev/null | head -1)
+  echo -e "${GREEN}   ✅ ${DOCKER_VER}${NC}"
+else
+  echo -e "${YELLOW}   ⚠️  Docker not found (optional for local dev)${NC}"
+fi
+
+if docker compose version &> /dev/null; then
+  COMPOSE_VER=$(docker compose version 2>/dev/null | head -1)
+  echo -e "${GREEN}   ✅ ${COMPOSE_VER}${NC}"
+else
+  echo -e "${YELLOW}   ⚠️  Docker Compose not found (optional)${NC}"
+fi
+
+# 8. 安装依赖（如果目录存在）
+for dir in Case-Database-Frontend-user Case-Database-Frontend-admin; do
+  if [ -f "$dir/package.json" ]; then
+    echo -e "${BLUE}📦 Installing $dir dependencies...${NC}"
+    (cd "$dir" && npm install) && echo "   ✅ $dir dependencies installed" || echo -e "${RED}   ❌ $dir install failed${NC}"
+  fi
+done
+
+if [ -f "Case-Database-Backend/composer.json" ]; then
+  echo -e "${BLUE}📦 Installing backend dependencies...${NC}"
+  (cd Case-Database-Backend && composer install --no-interaction) && echo "   ✅ Backend dependencies installed" || echo -e "${RED}   ❌ Backend install failed${NC}"
+fi
+
+# 9. 添加到 .gitignore
+if [ -f ".gitignore" ]; then
+  for pattern in ".ai-logs/" ".env*" "!.env.example"; do
+    if ! grep -qF "$pattern" .gitignore; then
+      echo "$pattern" >> .gitignore
+    fi
+  done
+  echo "   ✅ .gitignore updated"
+fi
+
+echo ""
+echo -e "${GREEN}🎉 Setup complete!${NC}"
+echo ""
+echo "Next steps:"
+echo "  1. Edit .cursor/mcp.json — fill in your API tokens"
+echo "  2. Edit docs/vision/PRD.md — describe your project"
+echo "  3. Open the project in Cursor"
+echo "  4. Tell Cursor: 读取 docs/vision/PRD.md，制定开发计划"
+echo ""
+echo "Development:"
+echo "  • Frontend: cd Case-Database-Frontend-user (or Case-Database-Frontend-admin) && npm run dev"
+echo "  • Backend:  cd Case-Database-Backend && php bin/hyperf.php start"
+echo "  • Docker:   docker compose up -d"
+echo ""
+echo "Skills system:"
+echo "  • Skills in .cursor/skills/"
+echo "  • Run 'bash scripts/skill-manager.sh validate' to validate skills"
+echo "  • Create new skills: ask Cursor \"创建新技能\""
+echo ""
diff --git a/scripts/skill-manager.sh b/scripts/skill-manager.sh
new file mode 100644
index 0000000..ed4b7b3
--- /dev/null
+++ b/scripts/skill-manager.sh
@@ -0,0 +1,271 @@
+#!/usr/bin/env bash
+# ================================================================
+# Skill Manager — Agent Skills 管理工具
+# 用法: bash scripts/skill-manager.sh <command> [args]
+# ================================================================
+
+set -euo pipefail
+
+SKILLS_DIR=".cursor/skills"
+AGENTS_DIR=".cursor/agents"
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# ================================================================
+# Commands
+# ================================================================
+
+cmd_list() {
+  echo -e "${BLUE}📦 Agent Skills${NC}"
+  echo "─────────────────────────────────────────────"
+  
+  if [ ! -d "$SKILLS_DIR" ]; then
+    echo -e "${RED}  ✗ Skills 目录不存在${NC}"
+    return 1
+  fi
+
+  local count=0
+  for skill_dir in "$SKILLS_DIR"/*/; do
+    [ -d "$skill_dir" ] || continue
+    local skill_file="$skill_dir/SKILL.md"
+    if [ -f "$skill_file" ]; then
+      local name=$(grep -m1 '^name:' "$skill_file" | sed 's/name:\s*//')
+      local desc=$(grep -A2 '^description:' "$skill_file" | tail -1 | sed 's/^\s*//')
+      local lines=$(wc -l < "$skill_file")
+      local has_refs=$( [ -d "${skill_dir}references" ] && echo "📚" || echo "  " )
+      local has_scripts=$( [ -d "${skill_dir}scripts" ] && echo "⚡" || echo "  " )
+      
+      printf "  ${GREEN}%-22s${NC} ${has_refs}${has_scripts} (%3d lines) %s\n" \
+        "$name" "$lines" "$desc"
+      count=$((count + 1))
+    fi
+  done
+  
+  echo "─────────────────────────────────────────────"
+  echo -e "  共 ${GREEN}${count}${NC} 个技能"
+  
+  echo ""
+  echo -e "${BLUE}🤖 Subagents${NC}"
+  echo "─────────────────────────────────────────────"
+  
+  if [ -d "$AGENTS_DIR" ]; then
+    for agent_file in "$AGENTS_DIR"/*.md; do
+      [ -f "$agent_file" ] || continue
+      local name=$(grep -m1 '^name:' "$agent_file" | sed 's/name:\s*//')
+      local desc=$(grep -A1 '^description:' "$agent_file" | tail -1 | sed 's/^\s*//')
+      local readonly_flag=$(grep -m1 '^readonly:' "$agent_file" | sed 's/readonly:\s*//')
+      local mode=$( [ "$readonly_flag" = "true" ] && echo "🔒只读" || echo "✏️读写" )
+      printf "  ${GREEN}%-22s${NC} ${mode}  %s\n" "$name" "$desc"
+    done
+  else
+    echo -e "  ${YELLOW}⚠ Agents 目录不存在${NC}"
+  fi
+}
+
+cmd_validate() {
+  echo -e "${BLUE}🔍 验证 Agent Skills 规范合规性${NC}"
+  echo "─────────────────────────────────────────────"
+  
+  local errors=0
+  local warnings=0
+  
+  for skill_dir in "$SKILLS_DIR"/*/; do
+    [ -d "$skill_dir" ] || continue
+    local skill_name=$(basename "$skill_dir")
+    local skill_file="$skill_dir/SKILL.md"
+    
+    # Check SKILL.md exists
+    if [ ! -f "$skill_file" ]; then
+      echo -e "  ${RED}✗${NC} ${skill_name}: 缺少 SKILL.md"
+      errors=$((errors + 1))
+      continue
+    fi
+    
+    # Check name field
+    if ! grep -q '^name:' "$skill_file"; then
+      echo -e "  ${RED}✗${NC} ${skill_name}: 缺少 name 字段"
+      errors=$((errors + 1))
+    fi
+    
+    # Check description field
+    if ! grep -q '^description:' "$skill_file"; then
+      echo -e "  ${RED}✗${NC} ${skill_name}: 缺少 description 字段"
+      errors=$((errors + 1))
+    fi
+    
+    # Check name format (kebab-case)
+    local name_val=$(grep -m1 '^name:' "$skill_file" | sed 's/name:[[:space:]]*//')
+    if ! echo "$name_val" | grep -qE '^[a-z0-9]+(-[a-z0-9]+)*$'; then
+      echo -e "  ${RED}✗${NC} ${skill_name}: name 不符合 kebab-case 格式: '${name_val}'"
+      errors=$((errors + 1))
+    fi
+    
+    # Check description length
+    local desc_len=$(sed -n '/^description:/,/^---/{/^description:/d;/^---/d;p;}' "$skill_file" | wc -c)
+    if [ "$desc_len" -gt 1024 ]; then
+      echo -e "  ${YELLOW}⚠${NC} ${skill_name}: description 超过 1024 字符 (${desc_len})"
+      warnings=$((warnings + 1))
+    fi
+    
+    # Check file length
+    local lines=$(wc -l < "$skill_file")
+    if [ "$lines" -gt 300 ]; then
+      echo -e "  ${YELLOW}⚠${NC} ${skill_name}: SKILL.md 超过 300 行 (${lines})，建议拆分到 references/"
+      warnings=$((warnings + 1))
+    fi
+    
+    # Check YAML frontmatter
+    local fm_count=$(grep -c '^---$' "$skill_file")
+    if [ "$fm_count" -lt 2 ]; then
+      echo -e "  ${RED}✗${NC} ${skill_name}: YAML frontmatter 格式不完整"
+      errors=$((errors + 1))
+    fi
+    
+    # All checks passed
+    if [ "$errors" -eq 0 ] && [ "$warnings" -eq 0 ]; then
+      echo -e "  ${GREEN}✓${NC} ${skill_name}"
+    fi
+  done
+  
+  echo "─────────────────────────────────────────────"
+  if [ "$errors" -gt 0 ]; then
+    echo -e "  ${RED}✗ ${errors} 个错误${NC}, ${YELLOW}${warnings} 个警告${NC}"
+    return 1
+  elif [ "$warnings" -gt 0 ]; then
+    echo -e "  ${GREEN}✓ 全部通过${NC}, ${YELLOW}${warnings} 个警告${NC}"
+  else
+    echo -e "  ${GREEN}✓ 全部验证通过${NC}"
+  fi
+}
+
+cmd_stats() {
+  echo -e "${BLUE}📊 Skills 统计${NC}"
+  echo "─────────────────────────────────────────────"
+  
+  local total_skills=0
+  local total_lines=0
+  local total_refs=0
+  local total_scripts=0
+  
+  for skill_dir in "$SKILLS_DIR"/*/; do
+    [ -d "$skill_dir" ] || continue
+    local skill_file="$skill_dir/SKILL.md"
+    [ -f "$skill_file" ] || continue
+    
+    total_skills=$((total_skills + 1))
+    total_lines=$((total_lines + $(wc -l < "$skill_file")))
+    
+    if [ -d "${skill_dir}references" ]; then
+      total_refs=$((total_refs + $(find "${skill_dir}references" -name "*.md" | wc -l)))
+    fi
+    if [ -d "${skill_dir}scripts" ]; then
+      total_scripts=$((total_scripts + $(find "${skill_dir}scripts" -type f | wc -l)))
+    fi
+  done
+  
+  local agents=0
+  if [ -d "$AGENTS_DIR" ]; then
+    agents=$(find "$AGENTS_DIR" -name "*.md" | wc -l)
+  fi
+  
+  echo "  Skills:      ${total_skills}"
+  echo "  Subagents:   ${agents}"
+  echo "  总行数:      ${total_lines} lines"
+  echo "  平均行数:    $((total_lines / (total_skills > 0 ? total_skills : 1))) lines/skill"
+  echo "  参考文档:    ${total_refs} files"
+  echo "  脚本:        ${total_scripts} files"
+  echo ""
+  echo "  预估 Token (Tier 1 发现): ~$((total_skills * 40)) tokens"
+  echo "  预估 Token (全量加载):    ~$((total_lines * 2)) tokens"
+}
+
+cmd_create() {
+  local name="${1:-}"
+  if [ -z "$name" ]; then
+    echo -e "${RED}用法: skill-manager.sh create <skill-name>${NC}"
+    echo "  名称必须是 kebab-case 格式"
+    return 1
+  fi
+  
+  # Validate name format
+  if ! echo "$name" | grep -qE '^[a-z0-9]+(-[a-z0-9]+)*$'; then
+    echo -e "${RED}✗ 名称必须是 kebab-case: a-z, 0-9, 连字符${NC}"
+    return 1
+  fi
+  
+  local dir="$SKILLS_DIR/$name"
+  if [ -d "$dir" ]; then
+    echo -e "${RED}✗ 技能已存在: $dir${NC}"
+    return 1
+  fi
+  
+  mkdir -p "$dir"
+  cat > "$dir/SKILL.md" << 'TEMPLATE'
+---
+name: SKILL_NAME
+description: >
+  Describe what this skill does and when to use it.
+  Include trigger keywords in both English and Chinese.
+---
+
+# Skill Title
+
+## 触发条件
+
+Describe when this skill should be activated.
+
+## 执行流程
+
+### 1. Step One
+
+Specific, actionable instructions.
+
+### 2. Step Two
+
+More instructions.
+
+## 验证
+
+1. [ ] Check item 1
+2. [ ] Check item 2
+TEMPLATE
+
+  sed "s/SKILL_NAME/$name/g" "$dir/SKILL.md" > "$dir/SKILL.md.tmp" && mv "$dir/SKILL.md.tmp" "$dir/SKILL.md"
+  
+  echo -e "${GREEN}✓ 技能已创建: $dir${NC}"
+  echo "  编辑 $dir/SKILL.md 完善技能内容"
+}
+
+# ================================================================
+# Main
+# ================================================================
+
+cmd="${1:-help}"
+shift || true
+
+case "$cmd" in
+  list|ls)     cmd_list ;;
+  validate|v)  cmd_validate ;;
+  stats|s)     cmd_stats ;;
+  create|new)  cmd_create "$@" ;;
+  help|--help|-h)
+    echo "Skill Manager — Agent Skills 管理工具"
+    echo ""
+    echo "用法: bash scripts/skill-manager.sh <command>"
+    echo ""
+    echo "命令:"
+    echo "  list      列出所有 Skills 和 Subagents"
+    echo "  validate  验证 SKILL.md 规范合规性"
+    echo "  stats     显示 Skills 统计信息"
+    echo "  create    创建新技能脚手架"
+    echo "  help      显示此帮助信息"
+    ;;
+  *)
+    echo -e "${RED}未知命令: $cmd${NC}"
+    echo "运行 'bash scripts/skill-manager.sh help' 查看帮助"
+    exit 1
+    ;;
+esac