{"id":"67ed1b4d-10cf-4b98-8d94-e6caf143afb1","entityType":"agent","slug":"clawhub-jermyn-zmj-bie-zheng-luan-prototype","name":"别整乱七八糟的原型","canonicalUrl":"https://www.xpersona.co/agent/clawhub-jermyn-zmj-bie-zheng-luan-prototype","canonicalPath":"/agent/clawhub-jermyn-zmj-bie-zheng-luan-prototype","generatedAt":"2026-10-11T07:43:36.017Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T05:29:58.448Z","emptyReason":null},"description":"将产品原型转换为详细技术规范的技能。深度解析HTML原型，提取完整的菜单结构、筛选条件、表格列、操作按钮等信息。支持URL原型、本地HTML文件、图片原型、XMind文件四种输入类型。输出包含前端组件描述、后端接口设计、数据库表设计的完整技术文档。增强版包含智能路由推断、业务API接口推断、完整数据库表结构设计、... Skill: 别整乱七八糟的原型 Owner: jermyn-zmj Summary: 将产品原型转换为详细技术规范的技能。深度解析HTML原型，提取完整的菜单结构、筛选条件、表格列、操作按钮等信息。支持URL原型、本地HTML文件、图片原型、XMind文件四种输入类型。输出包含前端组件描述、后端接口设计、数据库表设计的完整技术文档。增强版包含智能路由推断、业务API接口推断、完整数据库表结构设计、... Tags: latest:2.3.3 Version history: v2.3.3 | 2026-05-18T10:30:00.234Z | user **Version 2.3.3 Changelog** - 新增 scripts/html_extractor/analyzer.py 核心模块。 - 补充并上线 scripts/html_extractor/ 包的各个 Python 字节码缓存（__pycache__）文件","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17amrmvhq1brb5t8e6n3ced2h85c1v1:bie-zheng-luan-prototype","sourceUrl":"https://clawhub.ai/jermyn-zmj/bie-zheng-luan-prototype","homepage":"https://clawhub.ai/jermyn-zmj/skills/bie-zheng-luan-prototype","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/jermyn-zmj/bie-zheng-luan-prototype","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/jermyn-zmj/skills/bie-zheng-luan-prototype","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"将产品原型转换为详细技术规范的技能。深度解析HTML原型，提取完整的菜单结构、筛选条件、表格列、操作按钮等信息。支持URL原型、本地HTML文件、图片原型、XMind文件四种输入类型。输出包含前端组件描述、后端接口设计、数据库表设计的完整技术文档。增强版包含智能路由推断、业务API接口推断、完整数据库表结构设计、..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T05:29:58.448Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T05:29:58.448Z","emptyReason":null},"stars":null,"forks":null,"downloads":1146,"packageName":null,"latestVersion":"2.3.3","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T05:29:58.376Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T05:29:58.448Z","lastCrawledAt":"2026-10-11T05:29:58.376Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T05:29:58.376Z","lastVerifiedAt":null,"highlights":[{"version":"2.3.3","createdAt":"2026-05-18T10:30:00.234Z","changelog":"**Version 2.3.3 Changelog** - 新增 scripts/html_extractor/analyzer.py 核心模块。 - 补充并上线 scripts/html_extractor/ 包的各个 Python 字节码缓存（__pycache__）文件。 - 提升 HTML 原型的解析能力，为后续业务流程分析器和交互分析功能铺垫基础。 - 代码结构调整，更好支持模块化分析和数据结构定义。 - 版本升级未涉及接口和使用方法的变更，仅为后续功能增强准备。","fileCount":24,"zipByteSize":113962},{"version":"2.3.2","createdAt":"2026-04-29T06:49:13.511Z","changelog":"No changes detected in this version. - No file changes were made in version 2.3.2. - No new features, bugfixes, or documentation updates reported. - Behavior and instructions remain the same as the previous release.","fileCount":22,"zipByteSize":103401},{"version":"2.3.1","createdAt":"2026-04-29T06:35:46.387Z","changelog":"- 新增核心模块 scripts/html_extractor/，实现深度HTML解析及结构信息提取。 - 支持从HTML原型完整提取菜单结构、筛选条件、表格列、操作按钮等，并自动推断数据类型。 - 技能描述细化，突出“深度解析HTML结构”与智能路由、API、数据库设计等增强输出能力。 - 所有主要新功能通过独立模块（config, models, detector, extractor, utils, main）实现，结构清晰便于扩展。 - 原有功能和安全策略不变，增强本地HTML文件和URL原型的结构化技术文档输出能力。","fileCount":22,"zipByteSize":102791},{"version":"2.3.0","createdAt":"2026-04-23T08:24:46.264Z","changelog":"Version 2.3.0 - 强化安全措施：默认拒绝内网URL访问，需手动传参确认（--allow-internal）；外部API视觉增强分析默认禁用，需设置环境变量主动激活。 - 明确脚本依赖：所有Shell脚本不再自动安装Python依赖，用户需手动执行pip install。 - SSRF防护升级：内网地址默认阻止，检测范围包含169.254.x等常见私网段。 - 默认图片分析不外传：视觉增强仅在用户明确授权后启用，数据传输机制更透明。 - 安全说明和用户指引进一步细化，减少误用和默认风险。 - 无核心分析能力变更，主要为安全策略与用户体验改进。","fileCount":15,"zipByteSize":74866},{"version":"2.2.0","createdAt":"2026-04-23T08:06:18.448Z","changelog":"**2.2.0 introduces enhanced security protections.** - 新增多项安全措施，包括命令注入、路径遍历、输入验证与SSRF告警。 - URL、文件路径输入现有限制长度、过滤危险字符、特殊路径监测与手动确认提示。 - 内网URL自动发出风险警报但不强制阻断，便于内网原型分析。 - 明确各解析子流程采用安全参数传递与标准文件操作。 - 其它说明文字、结构无变更。","fileCount":15,"zipByteSize":74763},{"version":"2.1.0","createdAt":"2026-04-23T05:40:23.182Z","changelog":"Version 2.1.0 introduces important security guidance and visual analysis option. - Added a dedicated security warning section about URL/SSRF risks, external API data transfer, and local file handling. - Enhanced documentation on image prototype analysis: now clearly distinguishes between local/basic and external/vision-model-enhanced analysis, including environment variable usage and explicit data transmission warnings. - LICENSE file added. - No functional changes to analysis workflow or supported input types.","fileCount":15,"zipByteSize":71828},{"version":"2.0.1","createdAt":"2026-04-23T03:47:01.068Z","changelog":"- 无功能或实现变更，仅文档标题更新：将技能名称由“别整乱原型分析技能”改为“别整乱七八糟原型分析技能” - 其它说明、使用方法、能力列表以及内容未变 - 版本号为2.0.1 安全增强版","fileCount":15,"zipByteSize":68167},{"version":"2.0.0","createdAt":"2026-04-23T03:03:42.913Z","changelog":"Version 2.0.0 – Major rewrite with full-format support and detailed technical spec output - Now supports four input types: prototype URLs (Figma/Moquu/Axure), local HTML files, design images (PNG/JPG/WebP/etc.), and XMind mindmapping files. - For each type, extracts and analyzes layouts, components, navigation, functionality modules, and UI/interaction elements. - Generates comprehensive technical spec documents, including front-end components, back-end interfaces, and database table designs. - Adds workflow automation: input type auto-detection, multi-step analysis, and structured output via built-in scripts. - Includes best-practice templates and clear standards for documentation, components, APIs, and database schemas. - Enhanced guidance for combining vision models for image-based prototypes and for leveraging AI assistants in parsing results.","fileCount":15,"zipByteSize":68159}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17amrmvhq1brb5t8e6n3ced2h85c1v1:bie-zheng-luan-prototype","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jermyn-zmj-bie-zheng-luan-prototype/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jermyn-zmj-bie-zheng-luan-prototype/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jermyn-zmj-bie-zheng-luan-prototype/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-jermyn-zmj-bie-zheng-luan-prototype/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-jermyn-zmj-bie-zheng-luan-prototype/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-jermyn-zmj-bie-zheng-luan-prototype/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T07:43:36.015Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jermyn-zmj-bie-zheng-luan-prototype/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jermyn-zmj-bie-zheng-luan-prototype/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jermyn-zmj-bie-zheng-luan-prototype/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jermyn-zmj-bie-zheng-luan-prototype/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T05:29:58.448Z","emptyReason":null},"readme":"Skill: 别整乱七八糟的原型\n\nOwner: jermyn-zmj\n\nSummary: 将产品原型转换为详细技术规范的技能。深度解析HTML原型，提取完整的菜单结构、筛选条件、表格列、操作按钮等信息。支持URL原型、本地HTML文件、图片原型、XMind文件四种输入类型。输出包含前端组件描述、后端接口设计、数据库表设计的完整技术文档。增强版包含智能路由推断、业务API接口推断、完整数据库表结构设计、...\n\nTags: latest:2.3.3\n\nVersion history:\n\nv2.3.3 | 2026-05-18T10:30:00.234Z | user\n\n**Version 2.3.3 Changelog**\n\n- 新增 scripts/html_extractor/analyzer.py 核心模块。\n- 补充并上线 scripts/html_extractor/ 包的各个 Python 字节码缓存（__pycache__）文件。\n- 提升 HTML 原型的解析能力，为后续业务流程分析器和交互分析功能铺垫基础。\n- 代码结构调整，更好支持模块化分析和数据结构定义。\n- 版本升级未涉及接口和使用方法的变更，仅为后续功能增强准备。\n\nv2.3.2 | 2026-04-29T06:49:13.511Z | user\n\nNo changes detected in this version.\n\n- No file changes were made in version 2.3.2. \n- No new features, bugfixes, or documentation updates reported. \n- Behavior and instructions remain the same as the previous release.\n\nv2.3.1 | 2026-04-29T06:35:46.387Z | user\n\n- 新增核心模块 scripts/html_extractor/，实现深度HTML解析及结构信息提取。\n- 支持从HTML原型完整提取菜单结构、筛选条件、表格列、操作按钮等，并自动推断数据类型。\n- 技能描述细化，突出“深度解析HTML结构”与智能路由、API、数据库设计等增强输出能力。\n- 所有主要新功能通过独立模块（config, models, detector, extractor, utils, main）实现，结构清晰便于扩展。\n- 原有功能和安全策略不变，增强本地HTML文件和URL原型的结构化技术文档输出能力。\n\nv2.3.0 | 2026-04-23T08:24:46.264Z | user\n\nVersion 2.3.0\n\n- 强化安全措施：默认拒绝内网URL访问，需手动传参确认（--allow-internal）；外部API视觉增强分析默认禁用，需设置环境变量主动激活。\n- 明确脚本依赖：所有Shell脚本不再自动安装Python依赖，用户需手动执行pip install。\n- SSRF防护升级：内网地址默认阻止，检测范围包含169.254.x等常见私网段。\n- 默认图片分析不外传：视觉增强仅在用户明确授权后启用，数据传输机制更透明。\n- 安全说明和用户指引进一步细化，减少误用和默认风险。\n- 无核心分析能力变更，主要为安全策略与用户体验改进。\n\nv2.2.0 | 2026-04-23T08:06:18.448Z | user\n\n**2.2.0 introduces enhanced security protections.**\n\n- 新增多项安全措施，包括命令注入、路径遍历、输入验证与SSRF告警。\n- URL、文件路径输入现有限制长度、过滤危险字符、特殊路径监测与手动确认提示。\n- 内网URL自动发出风险警报但不强制阻断，便于内网原型分析。\n- 明确各解析子流程采用安全参数传递与标准文件操作。\n- 其它说明文字、结构无变更。\n\nv2.1.0 | 2026-04-23T05:40:23.182Z | user\n\nVersion 2.1.0 introduces important security guidance and visual analysis option.\n\n- Added a dedicated security warning section about URL/SSRF risks, external API data transfer, and local file handling.\n- Enhanced documentation on image prototype analysis: now clearly distinguishes between local/basic and external/vision-model-enhanced analysis, including environment variable usage and explicit data transmission warnings.\n- LICENSE file added.\n- No functional changes to analysis workflow or supported input types.\n\nv2.0.1 | 2026-04-23T03:47:01.068Z | user\n\n- 无功能或实现变更，仅文档标题更新：将技能名称由“别整乱原型分析技能”改为“别整乱七八糟原型分析技能”\n- 其它说明、使用方法、能力列表以及内容未变\n- 版本号为2.0.1 安全增强版\n\nv2.0.0 | 2026-04-23T03:03:42.913Z | user\n\nVersion 2.0.0 – Major rewrite with full-format support and detailed technical spec output\n\n- Now supports four input types: prototype URLs (Figma/Moquu/Axure), local HTML files, design images (PNG/JPG/WebP/etc.), and XMind mindmapping files.\n- For each type, extracts and analyzes layouts, components, navigation, functionality modules, and UI/interaction elements.\n- Generates comprehensive technical spec documents, including front-end components, back-end interfaces, and database table designs.\n- Adds workflow automation: input type auto-detection, multi-step analysis, and structured output via built-in scripts.\n- Includes best-practice templates and clear standards for documentation, components, APIs, and database schemas.\n- Enhanced guidance for combining vision models for image-based prototypes and for leveraging AI assistants in parsing results.\n\nArchive index:\n\nArchive v2.3.3: 24 files, 113962 bytes\n\nFiles: assets/sample-output/sample-user-management.md (24840b), README.md (14314b), references/api-design.md (15083b), references/component-catalog.md (9260b), references/template-spec.md (12944b), requirements.txt (1033b), scripts/html_extractor/__init__.py (1870b), scripts/html_extractor/analyzer.py (16902b), scripts/html_extractor/config.py (6872b), scripts/html_extractor/detector.py (1353b), scripts/html_extractor/extractor.py (111169b), scripts/html_extractor/main.py (2065b), scripts/html_extractor/models.py (11369b), scripts/html_extractor/utils.py (874b), scripts/html-extractor.py (424b), scripts/image-prototype-analyzer.py (18581b), scripts/run_analysis.sh (1820b), scripts/spec-generator.py (38911b), scripts/url-prototype-analyzer.sh (13855b), scripts/xmind-analyzer.py (22415b), skill-card.md (2410b), skill.json (8139b), SKILL.md (24364b), _meta.json (143b)\n\nFile v2.3.3:SKILL.md\n\n---\nname: bie-zheng-luan-prototype\ndescription: \"将产品原型转换为详细技术规范的技能。深度解析HTML原型，提取完整的菜单结构、筛选条件、表格列、操作按钮等信息。支持URL原型、本地HTML文件、图片原型、XMind文件四种输入类型。输出包含前端组件描述、后端接口设计、数据库表设计的完整技术文档。增强版包含智能路由推断、业务API接口推断、完整数据库表结构设计、实体关系图、状态枚举定义。新增交互式业务分析功能，可从原型推断业务流程、状态流转，生成问题让用户确认。\"\n---\n\n# 别整乱七八糟原型分析技能 (bie-zheng-luan-prototype)\n\n本技能将产品原型转换为详细的技术实现规范文档，**深度解析HTML结构**，提取完整的界面信息，并通过**交互式分析**推断业务流程。\n\n## ✨ 核心能力\n\n### 深度HTML解析\n本技能可从HTML原型中完整提取：\n\n| 提取内容 | 说明 | 输出格式 |\n|---------|------|---------|\n| **菜单结构** | 侧边栏菜单分组、菜单项、图标、页面标识 | 表格形式，含分组信息 |\n| **筛选条件** | 字段名、类型（select/input）、下拉选项列表 | 表格形式，含完整选项 |\n| **表格列** | 列名、数据类型推断（text/number/date/link等） | 表格形式 |\n| **操作按钮** | 按钮名、分类（search/action/delete等）、样式、位置 | 表格形式 |\n| **统计卡片** | 卡片标题、数值、说明 | 表格形式 |\n| **页面视图** | 多页面识别，每个页面独立分析 | 按页面分章节输出 |\n| **状态Tab** | 状态名称、数量、颜色类型 | 表格形式 |\n| **抽屉/弹窗** | 标题、锚点导航、表单字段、统计信息 | 分章节输出 |\n\n### 数据类型智能推断\n表格列数据类型自动推断：\n- `text` - 普通文本\n- `number` - 数值（含逗号分隔）\n- `date` - 日期格式（YYYY-MM-DD）\n- `link` - 可点击链接/单号\n- `badge` - 状态标签\n- `progress` - 进度条\n- `image` - 图片列\n- `currency` - 金额（含¥符号）\n- `percentage` - 百分比\n\n### 交互式业务分析（v3.0 新增）\n从HTML原型自动推断业务逻辑，生成问题让用户确认：\n\n| 分析内容 | 说明 |\n|---------|------|\n| **页面角色推断** | 识别入口页面、处理页面、查看页面、配置页面 |\n| **业务流程推断** | 基于菜单顺序、字段关联推断页面流转顺序 |\n| **状态流转推断** | 从按钮操作和状态Tab推断状态值和流转规则 |\n| **操作条件推断** | 推断操作是否需要勾选记录、特定状态等条件 |\n| **生成确认问题** | 按优先级生成问题，让用户确认或修正推断 |\n\n> ⚠️ **安全警告（重要）**\n>\n> 使用本技能前请阅读以下安全注意事项：\n>\n> 1. **内网URL需确认**：内网URL默认被阻止。如需分析内部原型，需使用 `--allow-internal` 参数确认风险。请勿分析不应被访问的内部系统。\n>\n> 2. **外部API默认禁用**：视觉增强分析功能需要设置 `ANTHROPIC_API_KEY` 环境变量才会启用。**默认情况下不调用外部API**，图片分析仅使用本地基础功能（颜色提取、布局推断）。启用外部API会将图片发送到Anthropic服务器，请确认图片不含敏感内容。\n>\n> 3. **手动安装依赖**：Shell脚本**不会自动安装Python依赖**。请在运行前手动执行：`pip install beautifulsoup4 pillow lxml`\n>\n> 4. **本地文件访问**：技能会读取您指定的本地文件。请确保文件路径指向预期内容。\n\n## 🛡️ 已实施的安全措施\n\n本技能实施了以下安全防护措施：\n\n### 命令注入防护\n- URL验证：只允许 `http://` 和 `https://` 协议\n- 危险字符检测：阻止Shell特殊字符（`;|&$`'\\\"()<>`）\n- 长度限制：URL最大2048字符\n\n### SSRF防护（用户确认模式）\n- **默认阻止内网URL**：检测私有网络地址自动拒绝\n- **用户确认机制**：需使用 `--allow-internal` 参数才能访问内网\n- 检测范围：`localhost`、`127.x`、`10.x`、`172.16-31.x`、`192.168.x`、`169.254.x`\n\n### 外部API控制\n- **默认禁用**：未设置 `ANTHROPIC_API_KEY` 时，不调用任何外部API\n- **用户触发**：仅在用户主动设置环境变量后启用\n- **数据传输明确**：启用后图片会通过base64发送到Anthropic\n\n### 无自动安装\n- Shell脚本**不执行** `pip install`\n- 仅检查依赖并提示用户手动安装\n- 避免运行时写入操作\n\n### 路径安全验证\n- 检测敏感路径关键词并发出警告\n- 限制路径长度\n- 验证文件存在性\n\n## 🎯 技能用途\n\n当产品经理提供以下任意形式的原型时，使用本技能：\n\n1. **URL原型** - Figma、墨刀、Axure、蓝湖、内网分享链接等\n2. **本地HTML文件** - 导出的HTML原型文件、本地保存的网页原型\n3. **图片原型** - 设计稿截图、高保真原型图\n4. **XMind文件** - 产品功能脑图、信息架构\n\n**输出目标**：生成一份详细的技术规范文档，让大模型能据此生成相似度90%以上的系统。\n\n## 🔧 当前版本能力（v3.1.0）\n\n### ✅ 已支持\n- **URL原型分析**：支持Figma、墨刀、Axure等主流工具的公开/内网URL\n- **本地HTML文件分析**：支持本地导出的HTML原型文件，直接读取文件系统路径\n- **网页内容解析**：提取DOM结构、样式信息、交互元素\n- **图片原型分析**：支持PNG、JPG、JPEG、GIF、WebP、BMP等格式，提取颜色方案、布局区域，生成分析报告\n- **XMind文件分析**：解析.xmind文件（zip格式），提取思维导图节点层级，推断功能模块、页面结构、功能点\n- **交互式业务分析**：从原型推断业务流程，生成问题让用户确认，循环迭代直到理解完整业务逻辑\n- **多UI框架适配**：自动检测并适配企业后台、标准后台、移动端H5等UI框架\n\n## 📋 工作流程\n\n### 第1步：原型内容解析\n根据输入类型选择合适的解析方式：\n\n#### A. URL原型解析\n```bash\n# 使用 web_fetch 获取页面内容\n# 分析HTML结构，提取关键信息\n```\n\n**提取内容**：\n- 页面整体布局（头部、侧边栏、主内容区、底部）\n- 导航菜单结构（一级菜单、二级菜单）\n- 功能模块划分（卡片、表单、列表、图表等）\n- 交互元素（按钮、输入框、下拉框、链接等）\n- 文本内容（标题、描述、标签、按钮文字）\n\n#### B. 本地HTML文件解析\n```bash\n# 使用 read 工具直接读取本地HTML文件\n# 分析DOM结构，提取关键信息\n```\n\n**适用场景**：\n- 从原型工具（Figma/墨刀/Axure等）导出的HTML文件\n- 本地保存的网页原型\n- 需要离线分析的原型文件\n\n**输入方式**：\n- 文件路径（如 `/path/to/prototype.html`）\n- 文件内容粘贴（用户直接粘贴HTML代码）\n\n**提取内容**（与URL原型相同）：\n- 页面整体布局（头部、侧边栏、主内容区、底部）\n- 导航菜单结构（一级菜单、二级菜单）\n- 功能模块划分（卡片、表单、列表、图表等）\n- 交互元素（按钮、输入框、下拉框、链接等）\n- 文本内容（标题、描述、标签、按钮文字）\n- CSS设计系统（颜色变量、字体、间距等设计Token）\n\n#### C. 图片原型解析\n\n**适用场景**：\n- 产品设计稿截图\n- 高保真原型图\n- UI设计文件导出图片\n- 线框图/草图\n\n**输入方式**：\n- 图片文件路径（如 `/path/to/design.png`）\n- 支持格式：PNG, JPG, JPEG, GIF, WebP, BMP\n\n**基础分析功能**（当前实现）：\n```bash\n# 使用 image-prototype-analyzer.py 进行基础分析\npython scripts/image-prototype-analyzer.py design.png markdown\n```\n\n**提取内容**：\n- 图片尺寸和比例\n- 主要颜色方案（提取前10种主色）\n- 布局区域推断（基于尺寸比例）\n - 头部区域（顶部10-15%）\n - 侧边栏区域（左侧15-20%）\n - 主内容区\n - 底部区域\n- 颜色统计和配色建议\n\n**增强分析方案**（可选，需配置API密钥）：\n\n> ⚠️ **数据传输警告**：使用视觉增强分析会将图片数据发送到外部API服务。请确认图片不含敏感信息后再启用。\n\n图片原型分析建议配合视觉大模型获得精确结果。需设置环境变量 `ANTHROPIC_API_KEY`：\n\n```python\n# 使用Claude Vision进行精确UI识别\n# 注意：此功能会将图片发送到Anthropic服务器\nimport anthropic\nimport base64\nimport os\n\n# 需要设置环境变量: ANTHROPIC_API_KEY\napi_key = os.environ.get('ANTHROPIC_API_KEY')\nif not api_key:\n print(\"警告: 未设置ANTHROPIC_API_KEY，无法使用视觉增强分析\")\n print(\"将使用本地基础分析（颜色提取、布局推断）\")\n\nclient = anthropic.Anthropic(api_key=api_key)\n\nwith open('design.png', 'rb') as f:\n image_data = base64.b64encode(f.read()).decode()\n\nresponse = client.messages.create(\n model='claude-3-opus-20240229',\n max_tokens=4096,\n messages=[{\n 'role': 'user',\n 'content': [\n {'type': 'image', 'source': {'type': 'base64', 'media_type': 'image/png', 'data': image_data}},\n {'type': 'text', 'text': '''分析这张UI设计稿，提取：\n1. 页面布局结构（头部、侧边栏、主内容区、底部）\n2. UI组件类型（按钮、输入框、表格、卡片等）\n3. 交互元素（可点击、可输入）\n4. 颜色方案（主色、辅助色、背景色）\n5. 文本内容（标题、描述、按钮文案）\n请以结构化格式输出。'''}\n ]\n }]\n)\n```\n\n**视觉模型分析输出**：\n- 精确的UI元素位置和类型\n- 完整的文本内容提取\n- 交互元素识别（按钮、链接、输入框）\n- 样式细节（颜色、字体大小推断）\n- 组件层级关系\n\n#### D. XMind原型解析\n\n**适用场景**：\n- 产品功能脑图\n- 信息架构图\n- 业务流程图\n- 需求结构图\n\n**输入方式**：\n- XMind文件路径（如 `/path/to/product.xmind`）\n- 支持XMind 8和XMind 2020+格式\n\n**技术原理**：\nXMind文件是zip压缩包，包含：\n- `content.json` (XMind 2020+格式)\n- `content.xml` (XMind 8格式)\n- `manifest.xml` (元数据)\n\n```bash\n# 使用 xmind-analyzer.py 进行分析\npython scripts/xmind-analyzer.py product.xmind markdown\n```\n\n**提取内容**：\n- 思维导图完整结构\n- 所有节点标题和层级\n- 节点属性（颜色、图标、备注）\n- 统计信息（节点总数、最大层级）\n\n**智能推断功能**：\n基于节点标题关键词，自动推断：\n1. **功能模块**（包含\"模块\"、\"管理\"、\"系统\"）\n2. **页面结构**（包含\"页面\"、\"列表\"、\"详情\"）\n3. **功能点**（包含\"功能\"、\"操作\"、\"按钮\"）\n\n**输出内容**：\n- YAML格式的思维导图结构\n- 功能模块清单（含子节点）\n- 页面结构建议（含功能点）\n- 前端路由规划建议\n- 后端API接口规划\n- 数据库表设计建议\n\n### 第2步：交互式业务分析（v3.0 新增）\n\n当分析HTML原型时，技能会自动进入交互式分析模式：\n\n1. **页面角色推断**：识别每个页面是入口页面、处理页面还是查看页面\n2. **业务流程推断**：基于菜单顺序和字段关联推断页面流转顺序\n3. **状态流转推断**：从按钮操作和状态Tab推断状态值和流转规则\n4. **生成确认问题**：按优先级生成问题，让用户确认或修正推断\n5. **循环迭代**：用户回答后继续深入分析，直到理解完整业务逻辑\n\n**分析输出包含**：\n- 业务流程顺序（页面流转图）\n- 每个页面的操作列表和执行条件\n- 状态流转规则（状态机图）\n- 关键字段和筛选维度\n- 需要用户确认的问题清单\n\n### 第3步：功能拆解与职责划分\n将解析出的元素拆解为细小功能单元，并判断实现方式：\n\n#### 前端职责（纯前端实现）\n- 页面布局和样式\n- 交互效果（悬停、点击动画）\n- 本地数据操作（排序、过滤、分页）\n- 表单验证（前端规则）\n- 组件内部状态管理\n\n#### 后端职责（需要接口支持）\n- 数据持久化（增删改查）\n- 业务逻辑处理（计算、验证、流程）\n- 外部系统集成（支付、消息、文件）\n- 权限控制和安全性\n- 批量操作和复杂查询\n\n**判断标准**：\n- 是否需要保存数据？ → 后端接口\n- 是否需要复杂计算？ → 后端接口 \n- 是否涉及用户权限？ → 后端接口\n- 是否只是UI交互？ → 前端实现\n\n### 第4步：技术文档生成\n生成结构化技术规范文档，包含：\n\n#### 4.1 系统概览\n- 原型来源和类型\n- 分析时间和版本\n- 总体功能描述\n\n#### 4.2 页面结构分析\n- 布局分解（头部、侧边栏、主内容区、底部）\n- 功能模块清单（每个模块的位置、内容、交互）\n\n#### 4.3 前端实现方案\n- 页面路由规划\n- 组件清单（名称、props、状态、交互逻辑）\n- 样式方案（CSS框架、设计系统）\n- 交互细节（按钮点击、表单提交、数据展示）\n\n#### 4.4 后端实现方案\n- API接口设计（路由、HTTP方法、参数、返回值）\n- 业务逻辑伪代码（关键算法、流程控制）\n- 数据库表设计（表名、字段、类型、关系）\n- 第三方服务集成\n\n#### 4.5 开发注意事项\n- 技术栈建议\n- 特殊依赖说明\n- 性能和安全考虑\n- 测试要点\n\n## 🛠️ 工具和资源\n\n### 内置脚本\n- `scripts/url-prototype-analyzer.sh` - URL原型解析主脚本\n- `scripts/html-extractor.py` - HTML内容提取工具入口（调用 html_extractor 包）\n- `scripts/html_extractor/` - HTML解析核心模块包\n - `config.py` - UI框架配置\n - `models.py` - 数据结构定义\n - `detector.py` - UI框架检测器\n - `extractor.py` - 核心解析器\n - `analyzer.py` - 业务流程分析器（v3.0 新增）\n - `utils.py` - 辅助函数\n - `main.py` - 入口函数\n- `scripts/spec-generator.py` - 技术文档生成工具\n- `scripts/image-prototype-analyzer.py` - 图片原型分析工具\n- `scripts/xmind-analyzer.py` - XMind文件分析工具\n- `scripts/run_analysis.sh` - 综合分析入口脚本\n\n### 参考模板\n- `references/template-spec.md` - 技术规范文档模板\n- `references/component-catalog.md` - 前端组件目录\n- `references/api-design.md` - API设计规范\n\n### 输出示例\n- `assets/sample-output/` - 示例输出文档\n\n## 📝 使用方法\n\n### 基本调用\n当用户提供原型URL或本地HTML文件路径时，直接使用本技能：\n\n```bash\n# 技能会自动识别输入类型并启动相应流程\n```\n\n### 输出格式\nHTML分析支持三种输出格式：\n\n```bash\n# 标准分析报告（默认）\npython scripts/html-extractor.py prototype.html markdown\n\n# JSON格式数据\npython scripts/html-extractor.py prototype.html json\n\n# 交互式业务分析（包含流程推断和问题）\npython scripts/html-extractor.py prototype.html interactive\n```\n\n### 手动触发\n如果需要特定分析模式，可指定参数：\n\n```bash\n# URL原型分析\n分析这个Figma原型：https://www.figma.com/file/xxx\n\n# 本地HTML文件分析\n分析这个HTML原型文件：/path/to/prototype.html\n分析这个HTML原型文件：[直接粘贴HTML内容]\n\n# 图片原型分析\n分析这张设计稿截图：/path/to/design.png\n# 配合视觉模型增强分析：\n使用Claude Vision分析这张设计稿：/path/to/design.png\n\n# XMind原型分析\n分析这个产品脑图：/path/to/product.xmind\n分析这个信息架构：/path/to/architecture.xmind\n```\n\n### 输入类型自动识别\n技能会根据输入内容自动判断解析方式：\n\n| 输入内容 | 识别方式 | 解析方式 |\n|---------|---------|---------|\n| `https://...` | 以http/https开头 | URL原型解析 |\n| `/path/to/file.html` | 文件路径，以.html结尾 | 本地HTML文件解析 |\n| `...` | 以HTML标签开头 | 直接解析粘贴的HTML内容 |\n| `/path/to/file.png/.jpg/.jpeg/.gif/.webp/.bmp` | 图片格式文件路径 | 图片原型解析 |\n| `/path/to/file.xmind` | .xmind后缀文件路径 | XMind文件解析 |\n\n### 分析助手执行流程\n作为AI助手，当用户提供本地HTML文件时，按照以下流程执行：\n\n1. **读取文件**：使用 `read` 工具读取HTML文件内容\n2. **解析结构**：调用 html_extractor 包解析HTML的DOM结构，提取：\n - 页面布局框架\n - 导航和菜单\n - 功能模块卡片\n - 表单和交互元素\n - 数据表格\n - CSS设计系统（变量、颜色、字体）\n3. **业务分析**：调用 BusinessFlowAnalyzer 推断业务流程和状态流转\n4. **交互确认**：生成问题让用户确认，循环迭代\n5. **生成文档**：按照技能模板生成技术规范文档\n6. **输出结果**：保存到指定路径或直接展示\n\n## 📊 输出文档标准\n\n### 前端组件描述标准\n对于每个页面组件，需要描述：\n\n1. **组件位置**：在页面哪个区域（头部/侧边栏/主内容区）\n2. **内容来源**：\n - 静态内容（写死在代码中）\n - 动态内容（从后端API获取）\n - 用户输入（表单字段）\n3. **展示样式**：\n - 布局方式（Flex/Grid/绝对定位）\n - 尺寸和间距\n - 颜色和字体\n - 响应式行为\n4. **交互逻辑**：\n - 按钮点击触发什么操作\n - 按钮名称和文案\n - 操作类型（导航/提交/删除/等）\n - 成功/失败反馈方式\n\n### 后端接口描述标准\n对于每个API接口，需要描述：\n\n1. **路由信息**：\n - HTTP方法（GET/POST/PUT/DELETE）\n - URL路径（/api/resource/:id）\n - 接口名称和用途\n2. **参数说明**：\n - 路径参数（:id）\n - 查询参数（?page=1&size=10）\n - 请求体（JSON结构）\n - 必填/选填字段\n3. **返回值**：\n - 成功响应（HTTP 200，JSON结构）\n - 错误响应（HTTP 4xx/5xx，错误信息）\n - 分页结构（如果需要）\n4. **业务逻辑伪代码**：\n - 主要处理步骤\n - 数据库操作（查询/插入/更新/删除）\n - 业务规则验证\n - 异常处理逻辑\n\n### 数据库设计标准\n对于每个业务实体，需要设计：\n\n1. **表结构**：\n - 表名（复数形式，小写加下划线）\n - 主键字段（id，自增或UUID）\n - 业务字段（名称、类型、长度、默认值）\n - 索引字段（查询优化）\n2. **表关系**：\n - 一对一关系\n - 一对多关系（外键）\n - 多对多关系（中间表）\n3. **约束条件**：\n - 唯一约束\n - 非空约束\n - 外键约束\n\n## 🔍 示例场景\n\n### 示例1：用户管理系统原型\n**输入**：Figma用户管理后台URL\n\n**输出包含**：\n- 前端：用户列表组件、用户表单组件、权限选择组件\n- 后端：用户CRUD接口、权限验证接口、搜索接口\n- 数据库：users表、roles表、user_roles关联表\n\n### 示例2：电商商品页面原型 \n**输入**：墨刀电商商品详情页URL\n\n**输出包含**：\n- 前端：商品展示组件、购物车组件、评价组件\n- 后端：商品查询接口、购物车接口、下单接口\n- 数据库：products表、categories表、orders表\n\n### 示例3：业务流程分析（交互式模式）\n**输入**：本地HTML原型文件\n\n**输出包含**：\n- 业务流程顺序（页面流转图）\n- 每个页面的操作列表和执行条件\n- 状态流转规则（状态机图）\n- 关键字段和筛选维度\n- 需要用户确认的问题清单\n\n## ⚠️ 安全注意事项\n\n> 🔴 **高风险操作警告**：请在理解以下风险后使用本技能\n\n### 1. 网络访问与SSRF风险\n- **支持内网URL**：本技能可以访问内网链接（如 `http://internal.company.com/prototype`）\n- **SSRF风险**：恶意或错误的URL可能触发服务器端请求伪造，访问未预期的内部资源\n- **安全建议**：\n - 仅提供您有权访问且明确需要分析的原型链接\n - 不要提供包含敏感数据的内部系统URL（如管理后台、API端点）\n - 在受控网络环境中分析内部原型\n\n### 2. 外部API数据传输\n- **视觉增强分析**：使用Claude Vision需要将图片发送到Anthropic服务器\n- **数据泄露风险**：设计稿可能包含敏感业务信息、知识产权内容\n- **安全建议**：\n - 启用视觉增强前确认图片不含敏感信息\n - 不设置 `ANTHROPIC_API_KEY` 时使用本地基础分析（不传输数据）\n - 对敏感设计稿仅使用本地分析功能\n\n### 3. 本地文件访问\n- **读取范围**：技能会读取您指定的本地文件路径\n- **误操作风险**：错误路径可能读取非预期的敏感文件\n- **安全建议**：\n - 确保文件路径准确指向目标原型文件\n - 不要将技能指向包含密钥、配置文件的目录\n\n### 4. 首次使用安全检查\n- **脚本审查**：首次使用前建议检查 `scripts/` 目录下的Python脚本\n- **隔离测试**：建议在虚拟环境或沙箱中首次运行\n- **依赖安装**：在虚拟环境中安装requirements.txt的依赖\n\n## ⚠️ 技术限制\n\n1. **访问限制**：\n - 需要登录的工具（如私有Figma项目）可能无法访问完整内容\n - 动态加载的内容可能无法完全捕获\n - 复杂交互可能难以通过静态分析完全理解\n\n2. **输出质量**：\n - 文档详细程度直接影响生成系统的准确性\n - 需要人工复核关键业务逻辑\n - 建议与产品经理确认技术方案\n\n## 📞 支持与反馈\n\n- **GitHub仓库**: https://github.com/jermyn-zmj/bie-zheng-luan-prototype\n- **问题反馈**: 通过GitHub Issues提交\n- **功能建议**: 通过GitHub Discussions讨论\n\n## 📄 许可证\n\n本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。\n\n## 🤝 贡献\n\n欢迎提交Issue和Pull Request！\n\n1. Fork 本仓库\n2. 创建功能分支 (`git checkout -b feature/amazing-feature`)\n3. 提交更改 (`git commit -m 'Add some amazing feature'`)\n4. 推送到分支 (`git push origin feature/amazing-feature`)\n5. 开启 Pull Request\n\n---\n\n*最后更新：2026-05-18*\n*版本：v3.1.0*\n*作者：杰哥*\n\n**更新日志**：\n- v3.1.0 (2026-05-18): 优化交互式分析：改进页面名称匹配（通过菜单page_id匹配view_id）、过滤无效按钮（去重和过滤纯图标按钮）、清理状态Tab名称（分离名称和数量）、增强UI框架适配（新增scm-view容器模式）\n- v3.0.0 (2026-05-18): 新增交互式业务分析功能：从原型推断业务流程和状态流转、生成问题让用户确认、循环迭代直到理解完整业务逻辑。新增BusinessFlowAnalyzer模块。\n- v2.9.2 (2026-04-29): 增强文档透明度：补充脚本功能详细说明表格（网络访问、文件操作、安全措施）、补充作者信息和项目链接，响应平台安全审查建议\n- v2.9.1 (2026-04-29): 修复spec-generator.py的Python 3.7兼容性问题（`str | None`改为`Optional[str]`）\n- v2.9.0 (2026-04-29): 完全通用化重构：移除所有硬编码的业务专有名词，使skill可适配任何业务领域。动态生成路由、API接口、数据库表，不依赖特定业务词汇映射。\n- v2.8.0 (2026-04-29): 增强技术实现推断能力：智能路由解析（处理javascript:void(0)等特殊值）、增强按钮位置识别（多层级父元素检查）、业务API接口推断、完整数据库表设计、实体关系图、状态枚举定义\n- v2.7.0 (2026-04-29): 模块化重构：将 html-extractor.py (2000+行) 拆分为 html_extractor 包（7个模块），提高可维护性\n- v2.6.0 (2026-04-24): 补充弹窗/抽屉面板解析：弹窗内表单字段、锚点导航、统计信息、状态筛选Tab、进度条组件\n- v2.5.0 (2026-04-24): 补充缺失解析模块：消息通知卡片、人员进度卡片、页面标签栏、用户信息区、子标签切换；优化表格层级识别和数据类型推断\n- v2.4.0 (2026-04-24): 重写HTML解析器，深度提取菜单结构、筛选条件、表格列、操作按钮、多页面视图\n- v2.3.0 (2026-04-23): 内网URL默认阻止需用户确认、禁止自动pip安装、外部API默认禁用\n- v2.2.0 (2026-04-23): 实施命令注入防护、URL/路径输入验证\n- v2.1.0 (2026-04-23): 增加安全警告、声明可选API凭证\n- v2.0.0 (2026-04-22): 新增图片/XMind分析功能\n- v1.0.0 (2026-04-21): 初始版本\n\nFile v2.3.3:README.md\n\n# bie-zheng-luan-prototype (别整乱原型分析技能)\n\n> **作者**: 杰哥 | **主页**: https://clawhub.ai/skills/bie-zheng-luan-prototype | **源码**: https://github.com/jermyn-zmj/bie-zheng-luan-prototype\n\n将产品原型转换为详细技术规范的技能，支持4种输入类型：URL原型、本地HTML文件、图片原型、XMind文件。新增交互式业务分析功能，可从原型推断业务流程。\n\n## 🎯 功能特性\n\n### ✅ 支持的输入类型\n1. **URL原型** - Figma、墨刀、Axure、蓝湖等设计工具的公开/内网链接\n2. **本地HTML文件** - 导出的HTML原型文件、本地保存的网页原型\n3. **图片原型** - 设计稿截图、高保真原型图（PNG/JPG/WebP等）\n4. **XMind文件** - 产品功能脑图、信息架构图\n\n### ✅ 核心能力\n- **智能解析**：自动识别输入类型并选择相应解析方式\n- **深度HTML解析**：提取菜单、筛选条件、表格列、操作按钮、状态Tab、抽屉面板等完整信息\n- **多UI框架适配**：自动检测并适配企业后台、标准后台、移动端H5等UI框架\n- **交互式业务分析**：从原型推断业务流程、状态流转，生成问题让用户确认\n- **功能拆解**：将原型元素拆解为前端组件、后端接口、数据库设计\n- **技术文档生成**：输出完整的技术规范文档\n- **多格式支持**：HTML、图片、思维导图全面覆盖\n\n## 📦 安装\n\n### 通过OpenClaw安装\n```bash\nopenclaw skills install https://clawhub.ai/skills/bie-zheng-luan-prototype\n```\n\n### 手动安装\n```bash\n# 克隆仓库\ngit clone https://github.com/[your-username]/bie-zheng-luan-prototype.git\n\n# 复制到技能目录\ncp -r bie-zheng-luan-prototype ~/.openclaw/workspace/skills/\n```\n\n## 🚀 使用方法\n\n### 基本调用\n当用户提供原型时，直接使用本技能：\n\n```bash\n# 分析URL原型\n分析这个Figma原型：https://www.figma.com/file/xxx\n\n# 分析本地HTML文件\n分析这个HTML原型文件：/path/to/prototype.html\n\n# 分析图片原型\n分析这张设计稿截图：/path/to/design.png\n\n# 分析XMind文件\n分析这个产品脑图：/path/to/product.xmind\n```\n\n### HTML分析输出格式\n```bash\n# 标准分析报告（默认）\npython scripts/html-extractor.py prototype.html markdown\n\n# JSON格式数据\npython scripts/html-extractor.py prototype.html json\n\n# 交互式业务分析（包含流程推断和问题）\npython scripts/html-extractor.py prototype.html interactive\n```\n\n### 输入类型自动识别\n技能会根据输入内容自动判断解析方式：\n\n| 输入内容 | 识别方式 | 解析方式 |\n|---------|---------|---------|\n| `https://...` 或 `http://...` | 以http/https开头 | URL原型解析 |\n| `/path/to/file.html` | 文件路径，以.html结尾 | 本地HTML文件解析 |\n| `...` | 以HTML标签开头 | 直接解析粘贴的HTML内容 |\n| `/path/to/file.png/.jpg/.jpeg/.gif/.webp/.bmp` | 图片格式文件路径 | 图片原型解析 |\n| `/path/to/file.xmind` | .xmind后缀文件路径 | XMind文件解析 |\n\n## 📋 输出文档\n\n技能会生成包含以下内容的技术规范文档：\n\n### 1. 系统概览\n- 原型来源和类型\n- 分析时间和版本\n- 总体功能描述\n- 技术栈建议\n\n### 2. 页面结构分析\n- 布局分解（头部、侧边栏、主内容区、底部）\n- 功能模块清单\n- 交互元素识别\n\n### 3. 业务流程分析（交互式模式）\n- 业务流程顺序（页面流转图）\n- 每个页面的操作列表和执行条件\n- 状态流转规则（状态机图）\n- 关键字段和筛选维度\n- 需要用户确认的问题清单\n\n### 4. 前端实现方案\n- 页面路由规划\n- 组件清单（名称、props、状态、交互逻辑）\n- 样式方案（CSS框架、设计系统）\n- 交互细节\n\n### 5. 后端实现方案\n- API接口设计（路由、HTTP方法、参数、返回值）\n- 业务逻辑伪代码\n- 数据库表设计\n- 第三方服务集成\n\n### 6. 开发注意事项\n- 技术栈建议\n- 特殊依赖说明\n- 性能和安全考虑\n- 测试要点\n\n## 🔧 内置工具\n\n### 脚本文件及功能说明\n\n| 脚本文件 | 功能 | 网络访问 | 文件操作 | 安全措施 |\n|---------|------|---------|---------|---------|\n| `url-prototype-analyzer.sh` | URL原型解析主脚本 | curl/wget下载公开URL | 读取HTML、写入输出文件 | URL验证、SSRF检测、命令注入防护 |\n| `run_analysis.sh` | 本地HTML综合分析入口 | 无 | 读取本地HTML、写入输出文件 | 路径验证、敏感路径警告 |\n| `html-extractor.py` | HTML内容深度提取 | 无 | 读取HTML文件 | 纯Python解析，无外部调用 |\n| `html_extractor/analyzer.py` | 业务流程分析 | 无 | 无 | 纯Python分析 |\n| `spec-generator.py` | 技术文档生成 | 无 | 写入输出文件 | 纯Python生成 |\n| `image-prototype-analyzer.py` | 图片原型分析 | 仅在设置ANTHROPIC_API_KEY时调用Claude API | 读取图片文件 | 默认本地分析，外部API需手动启用 |\n| `xmind-analyzer.py` | XMind文件分析 | 无 | 读取.xmind文件（zip解压） | 纯Python解析 |\n\n**脚本详细行为说明：**\n\n1. **url-prototype-analyzer.sh**\n - 仅下载用户提供的原型URL（http/https协议）\n - 内网URL默认阻止，需 `--allow-internal` 参数确认\n - 不执行任何 pip install 命令\n - 所有输入参数经过严格验证\n\n2. **run_analysis.sh**\n - 仅处理本地文件，无网络访问\n - 路径验证防止命令注入\n - 敏感路径（.ssh/.env/.git等）会发出警告\n\n3. **image-prototype-analyzer.py**\n - 默认使用本地分析（颜色提取、布局推断），无数据传输\n - 设置 `ANTHROPIC_API_KEY` 后可启用视觉增强分析（图片会发送到Anthropic服务器）\n\n### 参考模板\n- `references/template-spec.md` - 技术规范文档模板\n- `references/component-catalog.md` - 前端组件目录\n- `references/api-design.md` - API设计规范\n\n### 示例输出\n- `assets/sample-output/sample-user-management.md` - 用户管理系统示例\n\n## 📊 技术架构\n\n### 解析流程\n```\n输入识别 → 内容解析 → 业务分析 → 功能拆解 → 文档生成 → 输出保存\n```\n\n### 依赖要求\n- **Python 3.8+**\n- **Python包（核心）**：\n - `beautifulsoup4` (HTML解析)\n - `lxml` (HTML解析器)\n - `Pillow` (图片处理)\n- **Python包（可选，用于增强功能）**：\n - `anthropic` (Claude Vision API，用于图片原型精确分析) — 需设置 `ANTHROPIC_API_KEY`\n - `opencv-python` (高级图像处理)\n\n### 文件结构\n```\nbie-zheng-luan-prototype/\n├── SKILL.md # 技能主文件\n├── README.md # 说明文档\n├── LICENSE # MIT许可证\n├── skill.json # 技能元数据\n├── scripts/ # 分析脚本\n│ ├── url-prototype-analyzer.sh\n│ ├── html-extractor.py # HTML提取入口\n│ ├── html_extractor/ # HTML解析核心模块包\n│ │ ├── config.py # UI框架配置\n│ │ ├── models.py # 数据结构定义\n│ │ ├── detector.py # UI框架检测器\n│ │ ├── extractor.py # 核心解析器\n│ │ ├── analyzer.py # 业务流程分析器\n│ │ ├── utils.py # 辅助函数\n│ │ └── main.py # 入口函数\n│ ├── spec-generator.py # 技术文档生成工具\n│ ├── image-prototype-analyzer.py\n│ ├── xmind-analyzer.py\n│ └── run_analysis.sh\n├── references/ # 参考模板\n│ ├── template-spec.md\n│ ├── component-catalog.md\n│ └── api-design.md\n├── assets/ # 资源文件\n│ └── sample-output/\n│ └── sample-user-management.md\n└── requirements.txt # Python依赖\n```\n\n## 🎨 示例场景\n\n### 示例1：用户管理系统原型\n**输入**：Figma用户管理后台URL\n\n**输出包含**：\n- 前端：用户列表组件、用户表单组件、权限选择组件\n- 后端：用户CRUD接口、权限验证接口、搜索接口\n- 数据库：users表、roles表、user_roles关联表\n\n### 示例2：电商商品页面原型 \n**输入**：墨刀电商商品详情页URL\n\n**输出包含**：\n- 前端：商品展示组件、购物车组件、评价组件\n- 后端：商品查询接口、购物车接口、下单接口\n- 数据库：products表、categories表、orders表\n\n### 示例3：业务流程分析（交互式模式）\n**输入**：本地HTML原型文件\n\n**输出包含**：\n- 业务流程顺序（页面流转图）\n- 每个页面的操作列表和执行条件\n- 状态流转规则（状态机图）\n- 关键字段和筛选维度\n- 需要用户确认的问题清单\n\n## 🛡️ 安全措施\n\n本技能实施了严格的安全防护：\n\n### 内网URL控制\n- **默认阻止**：私有网络地址自动拒绝\n- **用户确认**：需 `--allow-internal` 参数才能访问内网\n- 检测范围：localhost、127.x、10.x、172.16-31.x、192.168.x\n\n### 外部API控制\n- **默认禁用**：未设置 `ANTHROPIC_API_KEY` 不调用外部API\n- **主动触发**：仅在用户设置环境变量后启用\n- 图片分析默认使用本地基础功能\n\n### 无自动安装\n- Shell脚本**不执行** `pip install`\n- 仅检查依赖，提示用户手动安装\n- 避免运行时写入操作\n\n### 命令注入防护\n- URL验证：只允许http/https协议\n- 阻止Shell特殊字符\n- 长度限制：URL最大2048字符\n\n---\n\n## ⚠️ 安全注意事项\n\n> 🔴 **使用前必读**：本技能涉及网络访问和可选外部API调用，请理解以下风险：\n\n### 内网URL访问控制\n- 内网URL**默认被阻止**\n- 需使用 `--allow-internal` 参数确认后才能访问\n- 请勿分析不应访问的内部系统\n\n### 外部API数据传输\n- 视觉增强分析需设置 `ANTHROPIC_API_KEY`\n- **默认禁用**：未设置环境变量时不调用外部API\n- 启用后图片会发送到Anthropic服务器\n\n### 本地文件访问\n- 技能会读取您指定的本地文件路径\n- 请确保路径指向预期文件\n\n### 首次使用建议\n- **手动安装依赖**：`pip install beautifulsoup4 pillow lxml`（脚本不会自动安装）\n- 检查 `scripts/` 目录下的脚本内容\n- 在隔离环境中首次测试\n\n## 🔄 版本历史\n\n### v3.1.0 (2026-05-18)\n- ✅ 优化交互式分析：改进页面名称匹配（通过菜单page_id匹配view_id）\n- ✅ 过滤无效按钮（去重和过滤纯图标按钮）\n- ✅ 清理状态Tab名称（分离名称和数量）\n- ✅ 增强UI框架适配（新增scm-view容器模式）\n\n### v3.0.0 (2026-05-18)\n- ✅ **新增交互式业务分析功能**\n- ✅ 从原型推断业务流程和状态流转\n- ✅ 生成问题让用户确认，循环迭代直到理解完整业务逻辑\n- ✅ 新增BusinessFlowAnalyzer模块\n\n### v2.9.2 (2026-04-29)\n- ✅ 增强文档透明度：补充脚本功能详细说明表格（网络访问、文件操作、安全措施）\n- ✅ 补充作者信息和项目链接在README顶部\n- ✅ 响应平台安全审查建议，提高脚本行为透明度\n\n### v2.9.1 (2026-04-29)\n- ✅ 修复spec-generator.py的Python 3.7兼容性问题（`str | None`改为`Optional[str]`）\n\n### v2.9.0 (2026-04-29)\n- ✅ **完全通用化重构**：移除所有硬编码的业务专有名词\n- ✅ 动态生成路由、API接口、数据库表，不依赖特定业务词汇映射\n- ✅ 可适配任何业务领域原型（仓储、ERP、WMS、CMS、CRM等）\n\n### v2.8.0 (2026-04-29)\n- ✅ **增强技术实现推断**：智能路由解析（处理javascript:void(0)等特殊值）\n- ✅ 增强按钮位置识别（多层级父元素检查）\n- ✅ 业务API接口推断、完整数据库表设计、实体关系图、状态枚举定义\n\n### v2.7.0 (2026-04-29)\n- ✅ **模块化重构**：将 html-extractor.py (2000+行) 拆分为 html_extractor 包（7个模块）\n- ✅ 提高代码可维护性和可读性\n\n### v2.6.0 (2026-04-24)\n- ✅ 补充弹窗/抽屉面板解析：弹窗内表单字段、锚点导航、统计信息\n- ✅ 补充状态筛选Tab、进度条组件解析\n\n### v2.5.0 (2026-04-24)\n- ✅ 补充缺失解析模块：消息通知卡片、人员进度卡片、页面标签栏\n- ✅ 优化表格层级识别和数据类型推断\n\n### v2.4.0 (2026-04-24)\n- ✅ 重写HTML解析器，深度提取菜单结构、筛选条件、表格列、操作按钮\n- ✅ 支持多页面视图识别和独立分析\n\n### v2.3.0 (2026-04-23)\n- ✅ **内网URL默认阻止**，需 `--allow-internal` 参数确认\n- ✅ **禁止自动pip安装**，改为提示用户手动安装\n- ✅ **外部API默认禁用**，仅在设置 `ANTHROPIC_API_KEY` 后启用\n- ✅ 在skill.json中完善安全措施声明\n\n### v2.2.0 (2026-04-23)\n- ✅ 实施命令注入防护（URL/路径输入验证）\n- ✅ 添加SSRF检测警告（私有网络地址检测）\n- ✅ 添加路径遍历防护（敏感路径检测）\n- ✅ 在skill.json中声明安全缓解措施\n\n### v2.1.0 (2026-04-23)\n- ✅ 增加安全警告声明（SSRF、数据泄露风险）\n- ✅ 在skill.json中声明可选环境变量 `ANTHROPIC_API_KEY`\n- ✅ 增加外部服务数据传输警告\n- ✅ 提供首次使用安全建议\n\n### v2.0.0 (2026-04-22)\n- ✅ 新增本地HTML文件解析支持\n- ✅ 新增图片原型分析功能\n- ✅ 新增XMind文件解析功能\n- ✅ 修复spec-generator.py中的bug\n- ✅ 完善技能文档和示例\n\n### v1.0.0 (2026-04-21)\n- ✅ 初始版本：URL原型分析功能\n- ✅ 基础HTML解析和文档生成\n\n## 📄 许可证\n\n本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。\n\n## 🤝 贡献\n\n欢迎提交Issue和Pull Request！\n\n1. Fork 本仓库\n2. 创建功能分支 (`git checkout -b feature/amazing-feature`)\n3. 提交更改 (`git commit -m 'Add some amazing feature'`)\n4. 推送到分支 (`git push origin feature/amazing-feature`)\n5. 开启 Pull Request\n\n## 📞 支持\n\n- 问题反馈：[GitHub Issues](https://github.com/jermyn-zmj/bie-zheng-luan-prototype/issues)\n- 功能建议：[GitHub Discussions](https://github.com/jermyn-zmj/bie-zheng-luan-prototype/discussions)\n\n---\n\n*让产品原型不再\"别整乱\"，一键生成技术规范！*\n\nFile v2.3.3:_meta.json\n\n{\n \"ownerId\": \"kn73wmmkp7pzethhh52mkcsb6n85c3h4\",\n \"slug\": \"bie-zheng-luan-prototype\",\n \"version\": \"2.3.3\",\n \"publishedAt\": 1779100200234\n}\n\nFile v2.3.3:references/api-design.md\n\n# API设计规范参考\r\n\r\n本文档提供RESTful API设计的标准规范，用于技术文档生成时的参考。\r\n\r\n## 设计原则\r\n\r\n### 1. RESTful原则\r\n- **资源导向**：API围绕资源设计，而非操作\r\n- **统一接口**：使用标准HTTP方法\r\n- **无状态**：每个请求包含所有必要信息\r\n- **可缓存**：适当使用缓存头\r\n- **分层系统**：客户端不依赖直接连接\r\n- **按需代码**：可选支持客户端代码扩展\r\n\r\n### 2. 版本管理\r\n- URL路径包含版本：`/api/v1/resource`\r\n- 使用Accept头：`Accept: application/vnd.company.v1+json`\r\n- **推荐**：URL路径版本控制，简单明确\r\n\r\n### 3. 安全原则\r\n- 所有API强制HTTPS\r\n- 身份验证和授权分离\r\n- 输入验证和输出过滤\r\n- 速率限制和配额管理\r\n\r\n## API结构规范\r\n\r\n### 1. 资源命名\r\n- 使用名词复数形式：`/users` 而非 `/user`\r\n- 小写字母，单词间用连字符：`/user-roles`\r\n- 避免动词：使用HTTP方法表示操作\r\n\r\n### 2. HTTP方法使用\r\n| 方法 | 用途 | 幂等性 | 安全性 |\r\n|------|------|--------|--------|\r\n| GET | 获取资源 | 是 | 是 |\r\n| POST | 创建资源 | 否 | 否 |\r\n| PUT | 全量更新资源 | 是 | 否 |\r\n| PATCH | 部分更新资源 | 否 | 否 |\r\n| DELETE | 删除资源 | 是 | 否 |\r\n\r\n### 3. 端点设计示例\r\n```\r\n# 资源集合操作\r\nGET /api/v1/users # 获取用户列表\r\nPOST /api/v1/users # 创建新用户\r\n\r\n# 单个资源操作\r\nGET /api/v1/users/{id} # 获取指定用户\r\nPUT /api/v1/users/{id} # 全量更新用户\r\nPATCH /api/v1/users/{id} # 部分更新用户\r\nDELETE /api/v1/users/{id} # 删除用户\r\n\r\n# 子资源操作\r\nGET /api/v1/users/{id}/orders # 获取用户的订单\r\nPOST /api/v1/users/{id}/orders # 为用户创建订单\r\nGET /api/v1/users/{id}/orders/{orderId} # 获取用户特定订单\r\n```\r\n\r\n## 请求与响应规范\r\n\r\n### 1. 请求头标准\r\n```http\r\n# 必需头\r\nContent-Type: application/json\r\nAuthorization: Bearer {token}\r\nAccept: application/json\r\n\r\n# 推荐头\r\nX-Request-ID: {uuid} # 请求跟踪\r\nX-Client-Version: 1.0.0 # 客户端版本\r\nX-Device-Info: {device_info} # 设备信息\r\n```\r\n\r\n### 2. 请求参数类型\r\n| 参数位置 | 用途 | 示例 |\r\n|----------|------|------|\r\n| 路径参数 | 资源标识 | `/users/{id}` |\r\n| 查询参数 | 筛选、排序、分页 | `?page=1&size=10` |\r\n| 请求体 | 创建/更新数据 | JSON对象 |\r\n| 请求头 | 元数据、认证 | `Authorization` |\r\n\r\n### 3. 响应格式标准\r\n\r\n#### 成功响应 (HTTP 2xx)\r\n```json\r\n{\r\n \"code\": 200,\r\n \"message\": \"success\",\r\n \"data\": {\r\n // 业务数据\r\n },\r\n \"meta\": {\r\n // 分页、时间戳等元数据\r\n }\r\n}\r\n```\r\n\r\n#### 分页响应\r\n```json\r\n{\r\n \"code\": 200,\r\n \"message\": \"success\",\r\n \"data\": {\r\n \"items\": [...], // 当前页数据\r\n \"total\": 100, // 总记录数\r\n \"page\": 1, // 当前页码\r\n \"size\": 10, // 每页大小\r\n \"pages\": 10 // 总页数\r\n }\r\n}\r\n```\r\n\r\n#### 错误响应 (HTTP 4xx/5xx)\r\n```json\r\n{\r\n \"code\": 400,\r\n \"message\": \"参数验证失败\",\r\n \"errors\": [\r\n {\r\n \"field\": \"username\",\r\n \"code\": \"REQUIRED\",\r\n \"message\": \"用户名不能为空\"\r\n },\r\n {\r\n \"field\": \"email\",\r\n \"code\": \"INVALID_FORMAT\",\r\n \"message\": \"邮箱格式不正确\"\r\n }\r\n ],\r\n \"request_id\": \"req_123456\",\r\n \"timestamp\": \"2026-04-21T10:00:00Z\"\r\n}\r\n```\r\n\r\n### 4. HTTP状态码使用\r\n| 状态码 | 含义 | 使用场景 |\r\n|--------|------|----------|\r\n| 200 | OK | 成功获取或更新资源 |\r\n| 201 | Created | 资源创建成功 |\r\n| 204 | No Content | 成功但无返回内容 |\r\n| 400 | Bad Request | 请求参数错误 |\r\n| 401 | Unauthorized | 未认证或认证失败 |\r\n| 403 | Forbidden | 无访问权限 |\r\n| 404 | Not Found | 资源不存在 |\r\n| 409 | Conflict | 资源冲突（如重复创建） |\r\n| 422 | Unprocessable Entity | 业务逻辑验证失败 |\r\n| 429 | Too Many Requests | 请求过于频繁 |\r\n| 500 | Internal Server Error | 服务器内部错误 |\r\n| 503 | Service Unavailable | 服务暂时不可用 |\r\n\r\n## 分页、排序和筛选\r\n\r\n### 1. 分页参数\r\n```http\r\nGET /api/v1/users?page=1&size=10\r\n```\r\n- `page`: 页码（从1开始）\r\n- `size`: 每页记录数（默认10，最大100）\r\n- **注意**: 避免使用 `limit` 和 `offset`，语义不如 `page` 和 `size` 明确\r\n\r\n### 2. 排序参数\r\n```http\r\nGET /api/v1/users?sort=created_at:desc,username:asc\r\n```\r\n格式：`字段名:方向`\r\n- 方向：`asc`（升序）或 `desc`（降序）\r\n- 多个排序字段用逗号分隔\r\n\r\n### 3. 筛选参数\r\n```http\r\nGET /api/v1/users?status=active&role=admin&created_after=2026-01-01\r\n```\r\n- 使用查询参数进行筛选\r\n- 支持范围查询：`created_after`、`created_before`\r\n- 支持部分匹配：`name_like=john`\r\n- 支持IN查询：`status=active,inactive`\r\n\r\n## 业务逻辑伪代码规范\r\n\r\n### 1. 标准结构\r\n```python\r\ndef api_endpoint(request):\r\n \"\"\"\r\n 函数文档字符串：描述接口功能\r\n \r\n Args:\r\n request: 请求对象，包含参数、用户信息等\r\n \r\n Returns:\r\n 响应数据或错误\r\n \r\n Raises:\r\n 可能抛出的异常\r\n \"\"\"\r\n \r\n # 1. 参数验证\r\n validate_request(request)\r\n \r\n # 2. 权限检查\r\n check_permission(request.user)\r\n \r\n # 3. 业务逻辑处理\r\n result = process_business_logic(request)\r\n \r\n # 4. 数据持久化\r\n save_to_database(result)\r\n \r\n # 5. 返回响应\r\n return format_response(result)\r\n```\r\n\r\n### 2. CRUD操作模板\r\n\r\n#### 创建资源\r\n```python\r\ndef create_resource(request):\r\n # 1. 解析请求数据\r\n data = parse_request_body(request)\r\n \r\n # 2. 验证数据完整性\r\n errors = validate_create_data(data)\r\n if errors:\r\n return validation_error_response(errors)\r\n \r\n # 3. 检查唯一性约束\r\n if resource_exists(data['unique_field']):\r\n return conflict_error('资源已存在')\r\n \r\n # 4. 业务逻辑处理\r\n processed_data = apply_business_rules(data)\r\n \r\n # 5. 创建资源\r\n resource = Resource.create(**processed_data)\r\n \r\n # 6. 触发后续操作（异步）\r\n trigger_async_tasks(resource)\r\n \r\n # 7. 返回创建结果\r\n return created_response(resource.to_dict())\r\n```\r\n\r\n#### 获取资源列表\r\n```python\r\ndef list_resources(request):\r\n # 1. 解析查询参数\r\n page = request.query.get('page', 1)\r\n size = request.query.get('size', 10)\r\n filters = extract_filters(request.query)\r\n \r\n # 2. 构建查询\r\n query = Resource.query.filter_by(is_deleted=False)\r\n \r\n # 3. 应用筛选条件\r\n if filters:\r\n query = apply_filters(query, filters)\r\n \r\n # 4. 应用排序\r\n sort_fields = parse_sort_fields(request.query.get('sort'))\r\n if sort_fields:\r\n query = apply_sorting(query, sort_fields)\r\n \r\n # 5. 执行分页查询\r\n total = query.count()\r\n items = query.paginate(page, size).all()\r\n \r\n # 6. 格式化数据\r\n formatted_items = [item.to_summary_dict() for item in items]\r\n \r\n # 7. 返回分页结果\r\n return paginated_response(formatted_items, total, page, size)\r\n```\r\n\r\n#### 更新资源\r\n```python\r\ndef update_resource(request, resource_id):\r\n # 1. 查找资源\r\n resource = Resource.find_or_404(resource_id)\r\n \r\n # 2. 权限验证（资源级权限）\r\n if not can_edit_resource(request.user, resource):\r\n return forbidden_error('无权修改此资源')\r\n \r\n # 3. 解析更新数据\r\n update_data = parse_request_body(request)\r\n \r\n # 4. 验证更新数据\r\n errors = validate_update_data(update_data, resource)\r\n if errors:\r\n return validation_error_response(errors)\r\n \r\n # 5. 应用更新\r\n before_update = resource.to_dict()\r\n resource.update(**update_data)\r\n after_update = resource.to_dict()\r\n \r\n # 6. 记录变更日志\r\n log_change(request.user, 'update', before_update, after_update)\r\n \r\n # 7. 返回更新结果\r\n return success_response(resource.to_dict())\r\n```\r\n\r\n#### 删除资源\r\n```python\r\ndef delete_resource(request, resource_id):\r\n # 1. 查找资源\r\n resource = Resource.find_or_404(resource_id)\r\n \r\n # 2. 权限验证（删除权限）\r\n if not can_delete_resource(request.user, resource):\r\n return forbidden_error('无权删除此资源')\r\n \r\n # 3. 检查关联约束\r\n if has_dependent_resources(resource):\r\n return conflict_error('存在关联资源，无法删除')\r\n \r\n # 4. 执行软删除（或物理删除）\r\n resource.mark_as_deleted()\r\n # 或: resource.delete()\r\n \r\n # 5. 清理关联数据\r\n cleanup_related_data(resource)\r\n \r\n # 6. 返回成功响应（无内容）\r\n return no_content_response()\r\n```\r\n\r\n### 3. 复杂业务逻辑示例\r\n\r\n#### 订单创建流程\r\n```python\r\ndef create_order(request):\r\n \"\"\"\r\n 创建订单的完整流程\r\n \r\n 业务规则：\r\n 1. 验证用户账户状态\r\n 2. 检查商品库存\r\n 3. 计算价格和优惠\r\n 4. 扣减库存\r\n 5. 创建订单记录\r\n 6. 扣款或生成待支付订单\r\n 7. 发送订单确认通知\r\n \"\"\"\r\n \r\n # 1. 验证用户和权限\r\n user = get_current_user(request)\r\n if not user.is_active:\r\n return bad_request('用户账户已冻结')\r\n \r\n # 2. 解析订单数据\r\n order_data = request.json\r\n items = order_data['items']\r\n \r\n # 3. 检查商品库存（事务性）\r\n with transaction.atomic():\r\n # 锁定库存记录\r\n product_stocks = ProductStock.select_for_update().filter(\r\n product_id__in=[item['product_id'] for item in items]\r\n )\r\n \r\n # 验证库存充足\r\n for item in items:\r\n stock = next(s for s in product_stocks if s.product_id == item['product_id'])\r\n if stock.quantity < item['quantity']:\r\n return insufficient_stock_error(stock.product.name)\r\n \r\n # 4. 计算订单金额\r\n order_amount = calculate_order_amount(items, user)\r\n \r\n # 5. 扣减库存\r\n for item in items:\r\n stock = next(s for s in product_stocks if s.product_id == item['product_id'])\r\n stock.quantity -= item['quantity']\r\n stock.save()\r\n \r\n # 6. 创建订单\r\n order = Order.create(\r\n user_id=user.id,\r\n amount=order_amount,\r\n status='pending_payment',\r\n items=items\r\n )\r\n \r\n # 7. 记录库存变更日志\r\n log_inventory_changes(order, product_stocks)\r\n \r\n # 8. 异步处理后续操作\r\n async_tasks = [\r\n send_order_confirmation_email(order),\r\n update_user_purchase_stats(user),\r\n trigger_inventory_replenishment_check(product_stocks)\r\n ]\r\n execute_async_tasks(async_tasks)\r\n \r\n # 9. 返回订单信息\r\n return created_response(order.to_detail_dict())\r\n```\r\n\r\n## 数据库设计参考\r\n\r\n### 1. 表设计规范\r\n```sql\r\n-- 基础表结构模板\r\nCREATE TABLE table_name (\r\n id VARCHAR(36) PRIMARY KEY DEFAULT UUID(), -- 主键使用UUID\r\n -- 业务字段\r\n name VARCHAR(100) NOT NULL,\r\n status VARCHAR(20) NOT NULL DEFAULT 'active',\r\n -- 元数据字段\r\n created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,\r\n updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,\r\n created_by VARCHAR(36) NOT NULL,\r\n updated_by VARCHAR(36),\r\n is_deleted BOOLEAN NOT NULL DEFAULT FALSE,\r\n deleted_at TIMESTAMP,\r\n deleted_by VARCHAR(36),\r\n -- 约束\r\n UNIQUE KEY uk_name (name),\r\n INDEX idx_status (status),\r\n INDEX idx_created_at (created_at)\r\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;\r\n```\r\n\r\n### 2. 关联关系设计\r\n```sql\r\n-- 一对一关系\r\nALTER TABLE profile \r\n ADD CONSTRAINT fk_profile_user \r\n FOREIGN KEY (user_id) REFERENCES users(id) \r\n ON DELETE CASCADE;\r\n\r\n-- 一对多关系 \r\nALTER TABLE orders\r\n ADD CONSTRAINT fk_order_user\r\n FOREIGN KEY (user_id) REFERENCES users(id)\r\n ON DELETE RESTRICT;\r\n\r\n-- 多对多关系（中间表）\r\nCREATE TABLE user_roles (\r\n id VARCHAR(36) PRIMARY KEY DEFAULT UUID(),\r\n user_id VARCHAR(36) NOT NULL,\r\n role_id VARCHAR(36) NOT NULL,\r\n created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,\r\n UNIQUE KEY uk_user_role (user_id, role_id),\r\n FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,\r\n FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE\r\n);\r\n```\r\n\r\n## 错误处理规范\r\n\r\n### 1. 错误代码定义\r\n```json\r\n{\r\n \"code\": \"VALIDATION_ERROR\",\r\n \"message\": \"参数验证失败\",\r\n \"details\": [\r\n {\r\n \"field\": \"email\",\r\n \"code\": \"INVALID_FORMAT\",\r\n \"message\": \"邮箱格式不正确\"\r\n }\r\n ]\r\n}\r\n```\r\n\r\n### 2. 常见错误代码\r\n| 错误代码 | HTTP状态码 | 含义 |\r\n|----------|------------|------|\r\n| `VALIDATION_ERROR` | 400 | 参数验证失败 |\r\n| `AUTHENTICATION_FAILED` | 401 | 认证失败 |\r\n| `PERMISSION_DENIED` | 403 | 权限不足 |\r\n| `RESOURCE_NOT_FOUND` | 404 | 资源不存在 |\r\n| `RESOURCE_CONFLICT` | 409 | 资源冲突 |\r\n| `RATE_LIMIT_EXCEEDED` | 429 | 请求频率超限 |\r\n| `INTERNAL_ERROR` | 500 | 服务器内部错误 |\r\n| `SERVICE_UNAVAILABLE` | 503 | 服务不可用 |\r\n\r\n## 性能优化建议\r\n\r\n### 1. 数据库优化\r\n- 合理使用索引（查询字段、排序字段）\r\n- 避免N+1查询问题（使用JOIN或批量查询）\r\n- 分页查询使用游标分页（Cursor-based Pagination）替代偏移分页\r\n\r\n### 2. 缓存策略\r\n```python\r\n# Redis缓存示例\r\nCACHE_KEYS = {\r\n 'user': 'user:{id}',\r\n 'user_products': 'user:{id}:products',\r\n 'product_detail': 'product:{id}:detail'\r\n}\r\n\r\n# 缓存读取策略\r\ndef get_user_with_cache(user_id):\r\n cache_key = CACHE_KEYS['user'].format(id=user_id)\r\n cached_data = redis.get(cache_key)\r\n \r\n if cached_data:\r\n return json.loads(cached_data)\r\n \r\n # 缓存未命中，查询数据库\r\n user = User.get(user_id)\r\n if user:\r\n # 设置缓存，过期时间30分钟\r\n redis.setex(cache_key, 1800, json.dumps(user.to_dict()))\r\n \r\n return user\r\n```\r\n\r\n### 3. 异步处理\r\n- 耗时操作异步执行（邮件发送、文件处理等）\r\n- 使用消息队列解耦服务\r\n- 实现重试和死信队列机制\r\n\r\n## 文档要求\r\n\r\n在技术文档中描述API时，应为每个接口提供：\r\n\r\n1. **接口基本信息**：URL、方法、功能描述\r\n2. **请求参数**：路径参数、查询参数、请求体\r\n3. **响应格式**：成功响应、错误响应\r\n4. **业务逻辑**：详细处理步骤（伪代码）\r\n5. **权限要求**：需要的角色和权限\r\n6. **性能考虑**：缓存、索引、异步处理建议\r\n7. **错误处理**：可能出现的错误和应对措施\r\n\r\n确保描述准确完整，便于大模型理解和实现。\n\nFile v2.3.3:references/component-catalog.md\n\n# 前端组件目录参考\r\n\r\n本文档提供前端组件的标准描述格式和常见组件模式，用于技术文档生成时的参考。\r\n\r\n## 组件描述标准格式\r\n\r\n### 1. 基础信息\r\n```markdown\r\n**组件名**: [组件名称]\r\n**位置**: [在页面中的位置]\r\n**功能**: [简要描述组件功能]\r\n```\r\n\r\n### 2. Props接口\r\n```javascript\r\ninterface ComponentProps {\r\n // 数据相关\r\n data?: any; // 组件显示的数据\r\n loading?: boolean; // 加载状态\r\n \r\n // 交互回调\r\n onClick?: () => void; // 点击事件\r\n onChange?: (value) => void; // 值变化事件\r\n onSubmit?: (data) => void; // 提交事件\r\n \r\n // 样式控制\r\n className?: string; // 自定义样式类\r\n style?: React.CSSProperties; // 内联样式\r\n \r\n // 配置选项\r\n options?: any[]; // 下拉选项等配置\r\n disabled?: boolean; // 是否禁用\r\n required?: boolean; // 是否必填\r\n \r\n // 子内容\r\n children?: React.ReactNode;\r\n}\r\n```\r\n\r\n### 3. 状态管理\r\n```javascript\r\ninterface ComponentState {\r\n // 数据状态\r\n selectedItems: any[]; // 选中的项\r\n currentPage: number; // 当前页码\r\n \r\n // UI状态\r\n isOpen: boolean; // 是否展开/打开\r\n isLoading: boolean; // 加载状态\r\n error: string | null; // 错误信息\r\n \r\n // 表单状态\r\n formData: object; // 表单数据\r\n validationErrors: object; // 验证错误\r\n}\r\n```\r\n\r\n### 4. 交互逻辑\r\n```markdown\r\n- **初始化**: 组件挂载时执行的操作\r\n- **用户交互**: 用户操作触发的行为\r\n- **数据变化**: props变化时的响应\r\n- **清理**: 组件卸载时的清理操作\r\n```\r\n\r\n## 常见组件模式\r\n\r\n### 1. 数据展示组件\r\n\r\n#### 表格组件 (DataTable)\r\n```markdown\r\n**组件名**: DataTable\r\n**功能**: 展示结构化数据，支持排序、筛选、分页\r\n\r\n**Props**:\r\n- `columns`: Column[] - 列配置\r\n- `dataSource`: any[] - 数据源\r\n- `pagination`: Pagination - 分页配置\r\n- `rowKey`: string - 行唯一键\r\n- `onRowClick`: (record) => void - 行点击事件\r\n\r\n**交互逻辑**:\r\n1. 表头点击切换排序\r\n2. 筛选器输入实时过滤\r\n3. 分页器切换页面\r\n4. 行选择/取消选择\r\n```\r\n\r\n#### 卡片组件 (Card)\r\n```markdown\r\n**组件名**: Card\r\n**功能**: 信息卡片容器，支持标题、内容、操作区\r\n\r\n**Props**:\r\n- `title`: string | ReactNode - 卡片标题\r\n- `extra`: ReactNode - 额外内容（通常为操作按钮）\r\n- `cover`: ReactNode - 封面图片\r\n- `actions`: ReactNode[] - 底部操作按钮\r\n\r\n**样式特点**:\r\n- 阴影效果增强层次感\r\n- 圆角边框\r\n- 悬停效果（可选）\r\n```\r\n\r\n### 2. 表单组件\r\n\r\n#### 输入框 (Input)\r\n```markdown\r\n**组件名**: Input\r\n**功能**: 文本输入控件\r\n\r\n**Props**:\r\n- `type`: 'text' | 'password' | 'email' | 'number' - 输入类型\r\n- `placeholder`: string - 占位文本\r\n- `value`: string - 当前值\r\n- `onChange`: (e) => void - 值变化事件\r\n- `prefix`: ReactNode - 前缀图标\r\n- `suffix`: ReactNode - 后缀图标\r\n- `allowClear`: boolean - 是否显示清除按钮\r\n\r\n**验证规则**:\r\n- 必填验证\r\n- 格式验证（邮箱、手机号等）\r\n- 长度限制\r\n```\r\n\r\n#### 下拉选择 (Select)\r\n```markdown\r\n**组件名**: Select\r\n**功能**: 下拉选择控件\r\n\r\n**Props**:\r\n- `options`: Option[] - 选项列表\r\n- `value`: string | string[] - 当前值\r\n- `onChange`: (value) => void - 值变化事件\r\n- `mode`: 'single' | 'multiple' - 单选/多选模式\r\n- `placeholder`: string - 占位文本\r\n- `loading`: boolean - 加载状态\r\n\r\n**交互逻辑**:\r\n1. 点击触发下拉菜单\r\n2. 搜索框输入过滤选项\r\n3. 选项点击选中\r\n4. 多选模式下标签展示\r\n```\r\n\r\n### 3. 布局组件\r\n\r\n#### 栅格布局 (Grid)\r\n```markdown\r\n**组件名**: Grid\r\n**功能**: 响应式栅格布局系统\r\n\r\n**Props**:\r\n- `cols`: number - 列数（默认24）\r\n- `gutter`: number | [number, number] - 栅格间距\r\n- `span`: number - 栅格占位格数\r\n- `offset`: number - 栅格左侧偏移格数\r\n\r\n**响应式规则**:\r\n- xs (<576px): 1-4列\r\n- sm (≥576px): 1-8列 \r\n- md (≥768px): 1-12列\r\n- lg (≥992px): 1-16列\r\n- xl (≥1200px): 1-24列\r\n```\r\n\r\n#### 布局容器 (Layout)\r\n```markdown\r\n**组件名**: Layout\r\n**功能**: 页面整体布局容器\r\n\r\n**结构**:\r\n- `Header`: 顶部导航\r\n- `Sider`: 侧边栏\r\n- `Content`: 主内容区\r\n- `Footer`: 底部区域\r\n\r\n**Props**:\r\n- `collapsed`: boolean - 侧边栏是否折叠\r\n- `collapsedWidth`: number - 折叠时宽度\r\n- `width`: number - 侧边栏宽度\r\n```\r\n\r\n### 4. 反馈组件\r\n\r\n#### 模态框 (Modal)\r\n```markdown\r\n**组件名**: Modal\r\n**功能**: 模态对话框\r\n\r\n**Props**:\r\n- `visible`: boolean - 是否显示\r\n- `title`: string | ReactNode - 标题\r\n- `onOk`: () => void - 确定按钮点击\r\n- `onCancel`: () => void - 取消按钮点击\r\n- `footer`: ReactNode - 自定义底部\r\n- `maskClosable`: boolean - 点击遮罩是否关闭\r\n\r\n**交互逻辑**:\r\n1. 打开时禁止背景滚动\r\n2. 键盘ESC键关闭\r\n3. 确定按钮提交表单\r\n4. 关闭时执行清理\r\n```\r\n\r\n#### 消息提示 (Message)\r\n```markdown\r\n**组件名**: Message\r\n**功能**: 全局消息提示\r\n\r\n**方法**:\r\n- `success(content, duration)`: 成功提示\r\n- `error(content, duration)`: 错误提示\r\n- `warning(content, duration)`: 警告提示\r\n- `info(content, duration)`: 信息提示\r\n- `loading(content, duration)`: 加载提示\r\n\r\n**位置选项**:\r\n- `top`: 顶部居中\r\n- `topLeft`: 左上角\r\n- `topRight`: 右上角\r\n- `bottom`: 底部居中\r\n- `bottomLeft`: 左下角\r\n- `bottomRight`: 右下角\r\n```\r\n\r\n## 组件交互模式\r\n\r\n### 1. 数据获取模式\r\n```javascript\r\n// 组件内数据获取\r\nuseEffect(() => {\r\n const fetchData = async () => {\r\n setLoading(true);\r\n try {\r\n const data = await api.getData(params);\r\n setData(data);\r\n } catch (error) {\r\n setError(error.message);\r\n } finally {\r\n setLoading(false);\r\n }\r\n };\r\n fetchData();\r\n}, [params]);\r\n```\r\n\r\n### 2. 表单处理模式\r\n```javascript\r\n// 受控表单组件\r\nconst [formData, setFormData] = useState(initialData);\r\n\r\nconst handleChange = (field, value) => {\r\n setFormData(prev => ({\r\n ...prev,\r\n [field]: value\r\n }));\r\n};\r\n\r\nconst handleSubmit = async () => {\r\n // 验证表单\r\n const errors = validateForm(formData);\r\n if (Object.keys(errors).length > 0) {\r\n setValidationErrors(errors);\r\n return;\r\n }\r\n \r\n // 提交数据\r\n await api.submit(formData);\r\n};\r\n```\r\n\r\n### 3. 事件处理模式\r\n```javascript\r\n// 防抖处理\r\nconst handleSearch = useDebounce((keyword) => {\r\n searchApi(keyword);\r\n}, 300);\r\n\r\n// 节流处理 \r\nconst handleScroll = useThrottle(() => {\r\n checkScrollPosition();\r\n}, 100);\r\n\r\n// 事件委托\r\nconst handleListClick = (e) => {\r\n if (e.target.matches('.item')) {\r\n const id = e.target.dataset.id;\r\n selectItem(id);\r\n }\r\n};\r\n```\r\n\r\n## 样式规范参考\r\n\r\n### 1. 命名规范\r\n- BEM命名法：`block__element--modifier`\r\n- 示例：`user-card__avatar--large`\r\n\r\n### 2. 颜色系统\r\n```css\r\n/* 主色调 */\r\n--primary-color: #1890ff;\r\n--primary-hover: #40a9ff;\r\n--primary-active: #096dd9;\r\n\r\n/* 功能色 */\r\n--success-color: #52c41a;\r\n--warning-color: #faad14;\r\n--error-color: #f5222d;\r\n--info-color: #1890ff;\r\n\r\n/* 中性色 */\r\n--text-color: rgba(0, 0, 0, 0.85);\r\n--text-color-secondary: rgba(0, 0, 0, 0.45);\r\n--border-color: #d9d9d9;\r\n--background-color: #f0f2f5;\r\n```\r\n\r\n### 3. 间距系统\r\n```css\r\n/* 基于8px基数 */\r\n--spacing-xs: 4px; /* 0.25rem */\r\n--spacing-sm: 8px; /* 0.5rem */\r\n--spacing-md: 16px; /* 1rem */\r\n--spacing-lg: 24px; /* 1.5rem */\r\n--spacing-xl: 32px; /* 2rem */\r\n```\r\n\r\n### 4. 动画曲线\r\n```css\r\n--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);\r\n--ease-out: cubic-bezier(0, 0, 0.2, 1);\r\n--ease-in: cubic-bezier(0.4, 0, 1, 1);\r\n```\r\n\r\n## 性能优化提示\r\n\r\n### 1. 减少重渲染\r\n- 使用 `React.memo()` 包裹纯展示组件\r\n- 使用 `useMemo()` 缓存计算结果\r\n- 使用 `useCallback()` 缓存函数引用\r\n\r\n### 2. 代码分割\r\n```javascript\r\n// 动态导入组件\r\nconst HeavyComponent = React.lazy(() => import('./HeavyComponent'));\r\n\r\n// 使用时包裹Suspense\r\n}>\r\n \r\n\r\n```\r\n\r\n### 3. 图片优化\r\n- 使用 WebP 格式（兼容性考虑提供回退）\r\n- 实现懒加载\r\n- 使用响应式图片（srcset）\r\n- 预加载关键图片\r\n\r\n## 可访问性要求\r\n\r\n### 1. 键盘导航\r\n- 所有交互元素支持键盘访问\r\n- 合理的 Tab 顺序\r\n- 快捷键支持\r\n\r\n### 2. 屏幕阅读器\r\n- 语义化 HTML 标签\r\n- ARIA 属性正确使用\r\n- 焦点管理合理\r\n\r\n### 3. 颜色对比度\r\n- 文本与背景对比度 ≥ 4.5:1\r\n- 大文本对比度 ≥ 3:1\r\n- 非文本元素对比度 ≥ 3:1\r\n\r\n---\r\n\r\n## 使用说明\r\n\r\n在技术文档中描述组件时，应参考以下结构：\r\n\r\n1. **组件基本信息**：名称、位置、功能\r\n2. **Props接口**：所有可配置属性\r\n3. **状态管理**：组件内部状态\r\n4. **交互逻辑**：用户操作响应\r\n5. **样式特点**：外观和动画\r\n6. **性能考虑**：优化建议\r\n7. **可访问性**：无障碍支持\r\n\r\n确保描述准确、完整，便于大模型理解并生成对应代码。\n\nFile v2.3.3:references/template-spec.md\n\n# 产品原型技术分析文档\r\n\r\n## 文档信息\r\n- **原型来源**: [URL/图片/XMind文件路径]\r\n- **分析时间**: [YYYY-MM-DD HH:MM:SS]\r\n- **文档版本**: v1.0\r\n- **技能版本**: bie-zheng-luan-prototype v1.0.0\r\n\r\n## 1. 系统概览\r\n\r\n### 1.1 产品简介\r\n[用1-2句话描述产品的核心功能和目标用户]\r\n\r\n### 1.2 技术栈建议\r\n- **前端**: [React/Vue/Angular + TypeScript]\r\n- **UI框架**: [Ant Design/Element UI/Tailwind CSS]\r\n- **后端**: [Node.js/.NET/Spring Boot/Go]\r\n- **数据库**: [MySQL/PostgreSQL/MongoDB]\r\n- **部署**: [Docker/Kubernetes]\r\n\r\n### 1.3 核心业务流程\r\n```\r\n[用流程图或文字描述主要业务流程]\r\n```\r\n\r\n## 2. 页面结构分析\r\n\r\n### 2.1 整体布局\r\n| 区域 | 位置 | 包含内容 | 宽度占比 | 固定/滚动 |\r\n|------|------|----------|----------|-----------|\r\n| 头部 | 顶部 | 品牌Logo、用户信息、通知中心 | 100% | 固定 |\r\n| 侧边栏 | 左侧 | 导航菜单、快捷操作 | 15-20% | 固定 |\r\n| 主内容区 | 中间 | 功能模块、数据展示 | 80-85% | 滚动 |\r\n| 底部 | 底部 | 版权信息、备案号 | 100% | 固定 |\r\n\r\n### 2.2 导航菜单结构\r\n```yaml\r\n一级菜单:\r\n - 菜单1:\r\n icon: [图标名称]\r\n path: /menu1\r\n 二级菜单:\r\n - 子菜单1.1: /menu1/sub1\r\n - 子菜单1.2: /menu1/sub2\r\n - 菜单2:\r\n icon: [图标名称]\r\n path: /menu2\r\n 无子菜单\r\n```\r\n\r\n### 2.3 功能模块清单\r\n| 模块名称 | 所在页面 | 位置坐标 | 主要功能 | 数据来源 |\r\n|----------|----------|----------|----------|----------|\r\n| [模块A] | [/dashboard] | 主内容区左上 | 数据概览卡片 | 后端API |\r\n| [模块B] | [/dashboard] | 主内容区右上 | 统计图表 | 后端API |\r\n| [模块C] | [/users] | 主内容区全宽 | 用户列表表格 | 后端API |\r\n\r\n## 3. 前端实现方案\r\n\r\n### 3.1 页面路由规划\r\n```javascript\r\nconst routes = [\r\n {\r\n path: '/',\r\n component: Layout,\r\n children: [\r\n { path: 'dashboard', component: Dashboard },\r\n { path: 'users', component: UserList },\r\n { path: 'users/:id', component: UserDetail },\r\n { path: 'settings', component: Settings },\r\n ]\r\n }\r\n];\r\n```\r\n\r\n### 3.2 组件清单\r\n\r\n#### 3.2.1 布局组件\r\n**组件名**: `MainLayout`\r\n- **位置**: 根组件\r\n- **Props**: \r\n - `children`: React.ReactNode (页面内容)\r\n - `title`: string (页面标题)\r\n- **状态**: \r\n - `collapsed`: boolean (侧边栏是否折叠)\r\n - `userInfo`: object (用户信息)\r\n- **交互逻辑**:\r\n - 侧边栏折叠/展开切换\r\n - 用户头像点击显示下拉菜单\r\n - 通知图标点击显示通知列表\r\n\r\n#### 3.2.2 业务组件\r\n**组件名**: `UserTable`\r\n- **位置**: `/users` 页面\r\n- **Props**:\r\n - `dataSource`: User[] (用户数据)\r\n - `loading`: boolean (加载状态)\r\n - `onEdit`: (user: User) => void (编辑回调)\r\n - `onDelete`: (id: string) => void (删除回调)\r\n- **状态**:\r\n - `selectedRows`: User[] (选中的行)\r\n - `pagination`: { current: number, pageSize: number }\r\n- **交互逻辑**:\r\n - 表格行点击选中/取消\r\n - 分页器切换页面\r\n - 搜索框输入实时过滤\r\n - 批量操作按钮点击\r\n\r\n### 3.3 样式规范\r\n```css\r\n/* 设计令牌 */\r\n:root {\r\n --primary-color: #1890ff;\r\n --success-color: #52c41a;\r\n --warning-color: #faad14;\r\n --error-color: #f5222d;\r\n \r\n --font-size-base: 14px;\r\n --border-radius-base: 4px;\r\n \r\n --spacing-xs: 4px;\r\n --spacing-sm: 8px;\r\n --spacing-md: 16px;\r\n --spacing-lg: 24px;\r\n}\r\n\r\n/* 组件样式示例 */\r\n.user-table {\r\n background: white;\r\n border-radius: var(--border-radius-base);\r\n box-shadow: 0 2px 8px rgba(0,0,0,0.1);\r\n padding: var(--spacing-md);\r\n}\r\n```\r\n\r\n### 3.4 交互细节\r\n\r\n#### 按钮交互示例\r\n**按钮**: \"新建用户\"\r\n- **位置**: 用户列表页面右上角\r\n- **样式**: 主按钮（蓝色背景，白色文字）\r\n- **点击行为**:\r\n 1. 打开用户表单弹窗\r\n 2. 重置表单为初始状态\r\n 3. 设置表单模式为\"创建\"\r\n- **成功反馈**: 显示\"创建成功\"提示，刷新用户列表\r\n- **失败反馈**: 显示错误信息，保持表单打开\r\n\r\n#### 表单交互示例\r\n**表单**: 用户信息表单\r\n- **提交行为**:\r\n 1. 前端验证必填字段\r\n 2. 显示加载状态\r\n 3. 调用后端API\r\n 4. 根据响应显示结果\r\n- **验证规则**:\r\n - 用户名：必填，2-20字符\r\n - 邮箱：必填，邮箱格式\r\n - 手机号：可选，11位数字\r\n\r\n## 4. 后端实现方案\r\n\r\n### 4.1 API接口设计\r\n\r\n#### 4.1.1 用户管理接口\r\n**接口名称**: 获取用户列表\r\n- **HTTP方法**: GET\r\n- **URL**: `/api/users`\r\n- **认证**: 需要Bearer Token\r\n- **权限**: 管理员权限\r\n\r\n**请求参数**:\r\n```json\r\n{\r\n \"page\": 1, // 页码（必填，默认1）\r\n \"size\": 10, // 每页数量（必填，默认10）\r\n \"keyword\": \"\", // 搜索关键词（可选）\r\n \"status\": \"active\" // 状态过滤（可选：active/inactive）\r\n}\r\n```\r\n\r\n**成功响应** (HTTP 200):\r\n```json\r\n{\r\n \"code\": 200,\r\n \"message\": \"success\",\r\n \"data\": {\r\n \"items\": [\r\n {\r\n \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\r\n \"username\": \"zhangsan\",\r\n \"email\": \"zhangsan@example.com\",\r\n \"phone\": \"13800138000\",\r\n \"status\": \"active\",\r\n \"createdAt\": \"2026-04-21T10:00:00Z\",\r\n \"updatedAt\": \"2026-04-21T10:00:00Z\"\r\n }\r\n ],\r\n \"total\": 100,\r\n \"page\": 1,\r\n \"size\": 10,\r\n \"pages\": 10\r\n }\r\n}\r\n```\r\n\r\n**错误响应** (HTTP 400):\r\n```json\r\n{\r\n \"code\": 400,\r\n \"message\": \"参数验证失败\",\r\n \"errors\": [\r\n {\r\n \"field\": \"page\",\r\n \"message\": \"页码必须大于0\"\r\n }\r\n ]\r\n}\r\n```\r\n\r\n**业务逻辑伪代码**:\r\n```python\r\ndef get_user_list(request):\r\n # 1. 验证用户权限\r\n if not request.user.has_permission('user:read'):\r\n return unauthorized_response()\r\n \r\n # 2. 解析和验证参数\r\n page = request.query.get('page', 1)\r\n size = request.query.get('size', 10)\r\n keyword = request.query.get('keyword', '')\r\n status = request.query.get('status')\r\n \r\n if page < 1 or size < 1 or size > 100:\r\n return bad_request('分页参数无效')\r\n \r\n # 3. 构建查询条件\r\n query = User.objects.filter(is_deleted=False)\r\n \r\n if keyword:\r\n query = query.filter(\r\n Q(username__icontains=keyword) |\r\n Q(email__icontains=keyword) |\r\n Q(phone__icontains=keyword)\r\n )\r\n \r\n if status in ['active', 'inactive']:\r\n query = query.filter(status=status)\r\n \r\n # 4. 执行分页查询\r\n total = query.count()\r\n items = query.order_by('-created_at') \\\r\n .offset((page - 1) * size) \\\r\n .limit(size) \\\r\n .all()\r\n \r\n # 5. 格式化返回数据\r\n return success_response({\r\n 'items': [user.to_dict() for user in items],\r\n 'total': total,\r\n 'page': page,\r\n 'size': size,\r\n 'pages': math.ceil(total / size)\r\n })\r\n```\r\n\r\n#### 4.1.2 其他接口\r\n[按照相同格式描述其他接口]\r\n\r\n### 4.2 服务层设计\r\n\r\n#### 用户服务 (UserService)\r\n```java\r\npublic class UserService {\r\n /**\r\n * 创建用户\r\n */\r\n public User createUser(CreateUserRequest request) {\r\n // 1. 验证用户名唯一性\r\n // 2. 密码加密\r\n // 3. 保存到数据库\r\n // 4. 发送欢迎邮件\r\n // 5. 记录操作日志\r\n }\r\n \r\n /**\r\n * 更新用户\r\n */\r\n public User updateUser(String userId, UpdateUserRequest request) {\r\n // 1. 查询用户是否存在\r\n // 2. 验证更新权限\r\n // 3. 更新用户信息\r\n // 4. 清除用户缓存\r\n }\r\n}\r\n```\r\n\r\n### 4.3 第三方服务集成\r\n- **短信服务**: 阿里云短信（用户注册验证）\r\n- **邮件服务**: SendGrid（通知邮件）\r\n- **文件存储**: AWS S3/MinIO（用户上传文件）\r\n- **消息队列**: RabbitMQ/Kafka（异步任务）\r\n\r\n## 5. 数据库设计\r\n\r\n### 5.1 数据库表清单\r\n\r\n#### 表名: `users` (用户表)\r\n| 字段名 | 数据类型 | 长度 | 必填 | 默认值 | 说明 |\r\n|--------|----------|------|------|--------|------|\r\n| id | varchar | 36 | ✓ | UUID | 主键 |\r\n| username | varchar | 50 | ✓ | | 用户名，唯一 |\r\n| email | varchar | 100 | ✓ | | 邮箱，唯一 |\r\n| phone | varchar | 20 | | | 手机号 |\r\n| password_hash | varchar | 255 | ✓ | | 密码哈希 |\r\n| status | varchar | 20 | ✓ | 'active' | 状态：active/inactive |\r\n| avatar_url | varchar | 255 | | | 头像URL |\r\n| last_login_at | datetime | | | NULL | 最后登录时间 |\r\n| created_at | datetime | | ✓ | CURRENT_TIMESTAMP | 创建时间 |\r\n| updated_at | datetime | | ✓ | CURRENT_TIMESTAMP | 更新时间 |\r\n| is_deleted | tinyint | 1 | ✓ | 0 | 软删除标记 |\r\n\r\n**索引**:\r\n- PRIMARY KEY (`id`)\r\n- UNIQUE KEY `uk_username` (`username`)\r\n- UNIQUE KEY `uk_email` (`email`)\r\n- INDEX `idx_status` (`status`)\r\n- INDEX `idx_created_at` (`created_at`)\r\n\r\n#### 表名: `roles` (角色表)\r\n| 字段名 | 数据类型 | 长度 | 必填 | 默认值 | 说明 |\r\n|--------|----------|------|------|--------|------|\r\n| id | varchar | 36 | ✓ | UUID | 主键 |\r\n| name | varchar | 50 | ✓ | | 角色名称 |\r\n| description | varchar | 200 | | | 角色描述 |\r\n| permissions | json | | ✓ | '[]' | 权限列表 |\r\n| created_at | datetime | | ✓ | CURRENT_TIMESTAMP | 创建时间 |\r\n\r\n#### 表名: `user_roles` (用户角色关联表)\r\n| 字段名 | 数据类型 | 长度 | 必填 | 默认值 | 说明 |\r\n|--------|----------|------|------|--------|------|\r\n| id | varchar | 36 | ✓ | UUID | 主键 |\r\n| user_id | varchar | 36 | ✓ | | 用户ID，外键 |\r\n| role_id | varchar | 36 | ✓ | | 角色ID，外键 |\r\n| created_at | datetime | | ✓ | CURRENT_TIMESTAMP | 创建时间 |\r\n\r\n**外键约束**:\r\n- FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON DELETE CASCADE\r\n- FOREIGN KEY (`role_id`) REFERENCES `roles`(`id`) ON DELETE CASCADE\r\n\r\n### 5.2 实体关系图\r\n```mermaid\r\nerDiagram\r\n users ||--o{ user_roles : has\r\n roles ||--o{ user_roles : assigned\r\n users {\r\n varchar id PK\r\n varchar username UK\r\n varchar email UK\r\n varchar phone\r\n varchar password_hash\r\n varchar status\r\n datetime created_at\r\n datetime updated_at\r\n }\r\n roles {\r\n varchar id PK\r\n varchar name\r\n varchar description\r\n json permissions\r\n datetime created_at\r\n }\r\n user_roles {\r\n varchar id PK\r\n varchar user_id FK\r\n varchar role_id FK\r\n datetime created_at\r\n }\r\n```\r\n\r\n## 6. 部署与运维\r\n\r\n### 6.1 环境配置\r\n```yaml\r\n# docker-compose.yml\r\nversion: '3.8'\r\nservices:\r\n backend:\r\n build: ./backend\r\n ports:\r\n - \"8080:8080\"\r\n environment:\r\n - DATABASE_URL=postgresql://user:pass@db:5432/app\r\n - REDIS_URL=redis://redis:6379\r\n depends_on:\r\n - db\r\n - redis\r\n \r\n frontend:\r\n build: ./frontend\r\n ports:\r\n - \"3000:3000\"\r\n \r\n db:\r\n image: postgres:15\r\n environment:\r\n - POSTGRES_USER=user\r\n - POSTGRES_PASSWORD=pass\r\n - POSTGRES_DB=app\r\n \r\n redis:\r\n image: redis:7-alpine\r\n```\r\n\r\n### 6.2 监控指标\r\n- API响应时间（P95 < 500ms）\r\n- 错误率（< 0.1%）\r\n- 数据库连接池使用率（< 80%）\r\n- 内存使用率（< 70%）\r\n\r\n### 6.3 日志规范\r\n```json\r\n{\r\n \"timestamp\": \"2026-04-21T10:00:00Z\",\r\n \"level\": \"INFO\",\r\n \"service\": \"user-service\",\r\n \"trace_id\": \"abc123\",\r\n \"user_id\": \"user123\",\r\n \"operation\": \"user.create\",\r\n \"duration_ms\": 150,\r\n \"status\": \"success\",\r\n \"message\": \"用户创建成功\"\r\n}\r\n```\r\n\r\n## 7. 测试要点\r\n\r\n### 7.1 单元测试\r\n- 用户服务逻辑测试\r\n- 权限验证测试\r\n- 数据验证测试\r\n\r\n### 7.2 集成测试\r\n- API接口端到端测试\r\n- 数据库操作测试\r\n- 第三方服务集成测试\r\n\r\n### 7.3 性能测试\r\n- 并发用户创建测试\r\n- 大数据量查询测试\r\n- API压力测试\r\n\r\n## 8. 开发注意事项\r\n\r\n### 8.1 安全性\r\n- 所有用户输入必须验证和过滤\r\n- 密码使用bcrypt加密存储\r\n- API接口需要身份验证和授权\r\n- 敏感操作需要二次确认\r\n\r\n### 8.2 性能优化\r\n- 数据库查询使用索引优化\r\n- 频繁访问的数据使用缓存\r\n- 大文件上传使用分片上传\r\n- 列表接口支持分页查询\r\n\r\n### 8.3 可维护性\r\n- 代码遵循一致的命名规范\r\n- 重要业务逻辑添加注释\r\n- 配置项集中管理\r\n- 错误处理统一规范\r\n\r\n---\r\n\r\n## 文档生成信息\r\n- **生成工具**: bie-zheng-luan-prototype v1.0.0\r\n- **生成时间**: [YYYY-MM-DD HH:MM:SS]\r\n- **置信度评估**: [高/中/低] (基于原型分析完整性)\r\n- **建议复核**: [需要/不需要] 与产品经理确认业务逻辑\r\n\r\n> **注意**: 本文档为技术分析结果，实际开发前应与产品经理确认需求细节。\n\nFile v2.3.3:assets/sample-output/sample-user-management.md\n\n# 产品原型技术分析文档\r\n\r\n## 文档信息\r\n- **原型来源**: Figma URL (https://www.figma.com/file/example/user-management)\r\n- **分析时间**: 2026-04-21 18:30:00\r\n- **文档版本**: v1.0\r\n- **技能版本**: bie-zheng-luan-prototype v1.0.0\r\n\r\n## 1. 系统概览\r\n\r\n### 1.1 产品简介\r\n用户管理系统，用于管理平台用户信息，支持用户的增删改查、角色分配、状态管理等功能。\r\n\r\n### 1.2 技术栈建议\r\n- **前端**: React 18 + TypeScript\r\n- **UI框架**: Ant Design 5.x\r\n- **状态管理**: Redux Toolkit + React Query\r\n- **后端**: Node.js + Express 或 .NET Core 6\r\n- **数据库**: PostgreSQL 15\r\n- **认证**: JWT + Refresh Token\r\n- **部署**: Docker + Nginx\r\n\r\n### 1.3 核心业务流程\r\n```\r\n用户访问 → 登录验证 → 查看用户列表 → 搜索/筛选用户 → 查看用户详情 → \r\n编辑用户信息 → 保存更改 → 更新列表显示\r\n```\r\n\r\n## 2. 页面结构分析\r\n\r\n### 2.1 整体布局\r\n| 区域 | 位置 | 包含内容 | 宽度占比 | 固定/滚动 |\r\n|------|------|----------|----------|-----------|\r\n| 头部 | 顶部 | Logo、用户头像、通知图标、退出按钮 | 100% | 固定 |\r\n| 侧边栏 | 左侧 | 系统菜单（用户管理、角色管理、日志管理） | 240px | 固定 |\r\n| 主内容区 | 中间 | 用户列表表格、搜索栏、操作按钮 | 剩余宽度 | 滚动 |\r\n| 底部 | 底部 | 版权信息、备案号 | 100% | 固定 |\r\n\r\n### 2.2 导航菜单结构\r\n```yaml\r\n一级菜单:\r\n - 仪表盘:\r\n icon: Dashboard\r\n path: /dashboard\r\n 无子菜单\r\n - 用户管理:\r\n icon: User\r\n path: /users\r\n 二级菜单:\r\n - 用户列表: /users\r\n - 角色管理: /users/roles\r\n - 系统设置:\r\n icon: Setting\r\n path: /settings\r\n 二级菜单:\r\n - 日志管理: /settings/logs\r\n - 参数配置: /settings/config\r\n```\r\n\r\n### 2.3 功能模块清单\r\n| 模块名称 | 所在页面 | 位置坐标 | 主要功能 | 数据来源 |\r\n|----------|----------|----------|----------|----------|\r\n| 用户搜索栏 | /users | 顶部左侧 | 按用户名/邮箱搜索用户 | 前端筛选 |\r\n| 状态筛选器 | /users | 顶部中部 | 按用户状态筛选 | 前端筛选 |\r\n| 操作按钮组 | /users | 顶部右侧 | 新建、导入、导出按钮 | 前端交互 |\r\n| 用户列表表格 | /users | 中部全宽 | 展示用户信息表格 | 后端API |\r\n| 分页控件 | /users | 底部居中 | 表格分页导航 | 后端API |\r\n\r\n## 3. 前端实现方案\r\n\r\n### 3.1 页面路由规划\r\n```typescript\r\n// src/routes/index.tsx\r\nconst routes = [\r\n {\r\n path: '/',\r\n element: ,\r\n children: [\r\n { index: true, element: },\r\n { path: 'dashboard', element: },\r\n {\r\n path: 'users',\r\n children: [\r\n { index: true, element: },\r\n { path: ':id', element: },\r\n { path: ':id/edit', element: },\r\n { path: 'roles', element: },\r\n ],\r\n },\r\n {\r\n path: 'settings',\r\n children: [\r\n { path: 'logs', element: },\r\n { path: 'config', element: },\r\n ],\r\n },\r\n ],\r\n },\r\n { path: '/login', element: },\r\n { path: '*', element: },\r\n];\r\n```\r\n\r\n### 3.2 组件清单\r\n\r\n#### 3.2.1 用户列表页面组件\r\n**组件名**: `UserListPage`\r\n- **位置**: `/users` 页面容器\r\n- **Props**: 无\r\n- **状态**:\r\n - `searchParams`: object (搜索参数)\r\n - `selectedRows`: string[] (选中的用户ID)\r\n- **交互逻辑**:\r\n - 挂载时加载用户列表\r\n - 搜索参数变化时重新加载\r\n - 批量操作按钮状态管理\r\n\r\n**组件名**: `UserSearchBar`\r\n- **位置**: `UserListPage` 顶部\r\n- **Props**:\r\n - `onSearch`: (params) => void (搜索回调)\r\n - `loading`: boolean (加载状态)\r\n- **状态**:\r\n - `keyword`: string (搜索关键词)\r\n - `status`: string (筛选状态)\r\n- **交互逻辑**:\r\n - 输入框输入实时搜索（防抖500ms）\r\n - 状态筛选器选择立即触发搜索\r\n - 重置按钮清空搜索条件\r\n\r\n**组件名**: `UserTable`\r\n- **位置**: `UserListPage` 中部\r\n- **Props**:\r\n - `data`: User[] (用户数据)\r\n - `loading`: boolean (加载状态)\r\n - `pagination`: PaginationProps (分页信息)\r\n - `onChange`: (pagination, filters, sorter) => void (表格变化回调)\r\n - `rowSelection`: object (行选择配置)\r\n- **状态**: 无（受控组件）\r\n- **交互逻辑**:\r\n - 行点击跳转到用户详情\r\n - 操作列按钮点击触发相应操作\r\n - 分页变化触发数据重新加载\r\n - 排序变化触发数据重新排序\r\n\r\n#### 3.2.2 用户表单组件\r\n**组件名**: `UserForm`\r\n- **位置**: 用户创建/编辑模态框\r\n- **Props**:\r\n - `initialValues`: User (初始值)\r\n - `onSubmit`: (values) => Promise (提交回调)\r\n - `onCancel`: () => void (取消回调)\r\n- **状态**:\r\n - `formData`: UserFormData (表单数据)\r\n - `submitting`: boolean (提交中状态)\r\n - `errors`: ValidationError[] (验证错误)\r\n- **交互逻辑**:\r\n - 表单字段变化实时验证\r\n - 邮箱输入后检查唯一性\r\n - 提交时显示加载状态\r\n - 成功/失败显示相应提示\r\n\r\n### 3.3 样式规范\r\n```css\r\n/* 用户列表页面样式 */\r\n.user-list-page {\r\n padding: 24px;\r\n background: #f5f5f5;\r\n min-height: calc(100vh - 64px); /* 减去头部高度 */\r\n}\r\n\r\n.user-search-bar {\r\n background: white;\r\n padding: 16px 24px;\r\n margin-bottom: 16px;\r\n border-radius: 8px;\r\n box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06);\r\n display: flex;\r\n gap: 16px;\r\n align-items: center;\r\n}\r\n\r\n.user-table-container {\r\n background: white;\r\n padding: 24px;\r\n border-radius: 8px;\r\n box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06);\r\n}\r\n\r\n/* 用户状态标签样式 */\r\n.status-tag {\r\n padding: 2px 8px;\r\n border-radius: 12px;\r\n font-size: 12px;\r\n font-weight: 500;\r\n}\r\n\r\n.status-active {\r\n background: #f6ffed;\r\n border: 1px solid #b7eb8f;\r\n color: #52c41a;\r\n}\r\n\r\n.status-inactive {\r\n background: #fff2e8;\r\n border: 1px solid #ffd591;\r\n color: #fa8c16;\r\n}\r\n\r\n.status-locked {\r\n background: #fff1f0;\r\n border: 1px solid #ffa39e;\r\n color: #f5222d;\r\n}\r\n```\r\n\r\n### 3.4 交互细节\r\n\r\n#### 按钮交互示例\r\n**按钮**: \"新建用户\"（主按钮）\r\n- **位置**: 用户列表页面右上角\r\n- **样式**: 蓝色背景，白色文字，右侧有加号图标\r\n- **点击行为**:\r\n 1. 打开用户创建模态框\r\n 2. 重置表单为初始状态\r\n 3. 设置表单模式为\"create\"\r\n- **成功反馈**: 显示\"用户创建成功\"提示，刷新用户列表\r\n- **失败反馈**: 显示错误信息，保持表单打开\r\n\r\n**按钮**: \"编辑\"（行操作按钮）\r\n- **位置**: 用户表格每行操作列\r\n- **样式**: 链接样式，蓝色文字\r\n- **点击行为**:\r\n 1. 获取当前行用户数据\r\n 2. 打开用户编辑模态框\r\n 3. 表单预填充用户信息\r\n- **成功反馈**: 显示\"用户信息已更新\"提示，更新当前行数据\r\n- **失败反馈**: 显示错误信息，保持表单打开\r\n\r\n**按钮**: \"删除\"（行操作按钮）\r\n- **位置**: 用户表格每行操作列\r\n- **样式**: 链接样式，红色文字\r\n- **点击行为**:\r\n 1. 显示确认对话框（\"确定删除该用户吗？\"）\r\n 2. 用户确认后调用删除API\r\n 3. 删除成功后从表格中移除该行\r\n- **确认对话框**: 二次确认，防止误操作\r\n- **批量删除**: 支持多选后批量删除\r\n\r\n#### 搜索交互示例\r\n**搜索框**: \"请输入用户名或邮箱\"\r\n- **位置**: 搜索栏左侧\r\n- **行为**: \r\n - 输入时实时搜索（防抖500ms）\r\n - 清空按钮一键清除\r\n - 支持键盘Enter键触发搜索\r\n- **搜索逻辑**: \r\n - 后端支持模糊搜索\r\n - 前端高亮显示匹配关键词\r\n\r\n**状态筛选器**: 下拉选择\r\n- **选项**: 全部、活跃、未激活、已锁定\r\n- **行为**: \r\n - 选择后立即触发筛选\r\n - 多选支持（待定）\r\n- **URL同步**: 筛选状态同步到URL查询参数\r\n\r\n## 4. 后端实现方案\r\n\r\n### 4.1 API接口设计\r\n\r\n#### 4.1.1 获取用户列表\r\n**接口名称**: 获取用户列表\r\n- **HTTP方法**: GET\r\n- **URL**: `/api/v1/users`\r\n- **认证**: 需要Bearer Token\r\n- **权限**: `user:read` 或更高\r\n\r\n**请求参数**:\r\n| 参数名 | 位置 | 类型 | 必填 | 说明 | 示例 |\r\n|--------|------|------|------|------|------|\r\n| page | query | integer | 否 | 页码，从1开始 | 1 |\r\n| size | query | integer | 否 | 每页数量，1-100 | 10 |\r\n| keyword | query | string | 否 | 搜索关键词（用户名/邮箱） | \"john\" |\r\n| status | query | string | 否 | 状态过滤（active/inactive/locked） | \"active\" |\r\n| role | query | string | 否 | 角色过滤 | \"admin\" |\r\n| sort | query | string | 否 | 排序字段（created_at:desc） | \"username:asc\" |\r\n\r\n**成功响应** (HTTP 200):\r\n```json\r\n{\r\n \"code\": 200,\r\n \"message\": \"success\",\r\n \"data\": {\r\n \"items\": [\r\n {\r\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\r\n \"username\": \"zhangsan\",\r\n \"email\": \"zhangsan@example.com\",\r\n \"phone\": \"13800138000\",\r\n \"avatar\": \"https://example.com/avatar.jpg\",\r\n \"status\": \"active\",\r\n \"role\": \"user\",\r\n \"last_login_at\": \"2026-04-21T10:00:00Z\",\r\n \"created_at\": \"2026-04-20T10:00:00Z\",\r\n \"updated_at\": \"2026-04-20T10:00:00Z\"\r\n }\r\n ],\r\n \"total\": 100,\r\n \"page\": 1,\r\n \"size\": 10,\r\n \"pages\": 10\r\n }\r\n}\r\n```\r\n\r\n**业务逻辑伪代码**:\r\n```python\r\ndef get_user_list(request):\r\n \"\"\"\r\n 获取用户列表\r\n \r\n 业务规则：\r\n 1. 仅管理员可以查看所有用户\r\n 2. 普通用户只能查看自己\r\n 3. 支持按状态、角色、关键词筛选\r\n 4. 支持分页和排序\r\n 5. 敏感字段脱敏处理\r\n \"\"\"\r\n \r\n # 1. 验证用户权限\r\n current_user = get_current_user(request)\r\n if not current_user.has_permission('user:read'):\r\n return unauthorized_response('权限不足')\r\n \r\n # 2. 解析查询参数\r\n query_params = parse_query_params(request)\r\n page = query_params.get('page', 1)\r\n size = min(query_params.get('size', 10), 100) # 限制每页最多100条\r\n keyword = query_params.get('keyword', '').strip()\r\n status = query_params.get('status')\r\n role = query_params.get('role')\r\n sort_field, sort_order = parse_sort_param(query_params.get('sort', 'created_at:desc'))\r\n \r\n # 3. 构建查询基础（根据权限限制数据范围）\r\n if current_user.is_admin:\r\n query = User.query.filter_by(is_deleted=False)\r\n else:\r\n # 普通用户只能查看自己的信息\r\n query = User.query.filter_by(id=current_user.id, is_deleted=False)\r\n \r\n # 4. 应用筛选条件\r\n if keyword:\r\n # 支持用户名、邮箱、手机号模糊搜索\r\n search_pattern = f'%{keyword}%'\r\n query = query.filter(\r\n (User.username.ilike(search_pattern)) |\r\n (User.email.ilike(search_pattern)) |\r\n (User.phone.ilike(search_pattern))\r\n )\r\n \r\n if status in ['active', 'inactive', 'locked']:\r\n query = query.filter_by(status=status)\r\n \r\n if role:\r\n query = query.filter_by(role=role)\r\n \r\n # 5. 应用排序\r\n if sort_field in ['username', 'email', 'created_at', 'updated_at', 'last_login_at']:\r\n if sort_order == 'asc':\r\n query = query.order_by(getattr(User, sort_field).asc())\r\n else:\r\n query = query.order_by(getattr(User, sort_field).desc())\r\n else:\r\n # 默认按创建时间倒序\r\n query = query.order_by(User.created_at.desc())\r\n \r\n # 6. 执行分页查询\r\n total_count = query.count()\r\n offset = (page - 1) * size\r\n users = query.offset(offset).limit(size).all()\r\n \r\n # 7. 数据脱敏处理（对非管理员隐藏敏感信息）\r\n safe_users = []\r\n for user in users:\r\n user_data = user.to_dict()\r\n if not current_user.is_admin:\r\n # 非管理员看不到其他用户的手机号和邮箱（除自己）\r\n if user.id != current_user.id:\r\n user_data['phone'] = '***'\r\n user_data['email'] = user_data['email'][0] + '***' + user_data['email'].split('@')[1]\r\n safe_users.append(user_data)\r\n \r\n # 8. 返回分页结果\r\n return success_response({\r\n 'items': safe_users,\r\n 'total': total_count,\r\n 'page': page,\r\n 'size': size,\r\n 'pages': math.ceil(total_count / size)\r\n })\r\n```\r\n\r\n#### 4.1.2 创建用户接口\r\n**接口名称**: 创建用户\r\n- **HTTP方法**: POST\r\n- **URL**: `/api/v1/users`\r\n- **认证**: 需要Bearer Token\r\n- **权限**: `user:create` 或 `admin` 角色\r\n\r\n**请求体**:\r\n```json\r\n{\r\n \"username\": \"zhangsan\",\r\n \"email\": \"zhangsan@example.com\",\r\n \"phone\": \"13800138000\",\r\n \"password\": \"Password123!\",\r\n \"role\": \"user\",\r\n \"status\": \"active\"\r\n}\r\n```\r\n\r\n**成功响应** (HTTP 201):\r\n```json\r\n{\r\n \"code\": 201,\r\n \"message\": \"用户创建成功\",\r\n \"data\": {\r\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\r\n \"username\": \"zhangsan\",\r\n \"email\": \"zhangsan@example.com\",\r\n \"role\": \"user\",\r\n \"status\": \"active\",\r\n \"created_at\": \"2026-04-21T10:00:00Z\"\r\n }\r\n}\r\n```\r\n\r\n**业务逻辑伪代码**:\r\n```python\r\ndef create_user(request):\r\n \"\"\"\r\n 创建新用户\r\n \r\n 业务规则：\r\n 1. 用户名、邮箱必须唯一\r\n 2. 密码强度验证\r\n 3. 邮箱格式验证\r\n 4. 手机号格式验证\r\n 5. 创建成功后发送欢迎邮件\r\n \"\"\"\r\n \r\n # 1. 权限验证\r\n if not request.user.has_permission('user:create'):\r\n return forbidden_response('无权创建用户')\r\n \r\n # 2. 解析和验证请求数据\r\n user_data = request.json\r\n \r\n # 必填字段验证\r\n required_fields = ['username', 'email', 'password']\r\n for field in required_fields:\r\n if field not in user_data or not user_data[field]:\r\n return validation_error(f'{field}不能为空')\r\n \r\n # 用户名验证（3-20位，字母数字下划线）\r\n if not re.match(r'^[a-zA-Z0-9_]{3,20}$', user_data['username']):\r\n return validation_error('用户名格式不正确')\r\n \r\n # 邮箱格式验证\r\n if not is_valid_email(user_data['email']):\r\n return validation_error('邮箱格式不正确')\r\n \r\n # 密码强度验证（至少8位，包含大小写字母和数字）\r\n if not is_strong_password(user_data['password']):\r\n return validation_error('密码强度不足')\r\n \r\n # 手机号验证（可选）\r\n if 'phone' in user_data and user_data['phone']:\r\n if not is_valid_phone(user_data['phone']):\r\n return validation_error('手机号格式不正确')\r\n \r\n # 3. 检查唯一性约束\r\n if User.query.filter_by(username=user_data['username']).first():\r\n return conflict_error('用户名已存在')\r\n \r\n if User.query.filter_by(email=user_data['email']).first():\r\n return conflict_error('邮箱已存在')\r\n \r\n if user_data.get('phone') and User.query.filter_by(phone=user_data['phone']).first():\r\n return conflict_error('手机号已存在')\r\n \r\n # 4. 密码加密\r\n hashed_password = bcrypt.hash(user_data['password'])\r\n \r\n # 5. 创建用户（事务操作）\r\n with transaction.atomic():\r\n new_user = User(\r\n username=user_data['username'],\r\n email=user_data['email'],\r\n phone=user_data.get('phone'),\r\n password_hash=hashed_password,\r\n role=user_data.get('role', 'user'),\r\n status=user_data.get('status', 'active'),\r\n created_by=request.user.id\r\n )\r\n new_user.save()\r\n \r\n # 6. 记录操作日志\r\n log_operation(\r\n user_id=request.user.id,\r\n action='user.create',\r\n target_id=new_user.id,\r\n details={'data': sanitize_user_data(user_data)}\r\n )\r\n \r\n # 7. 异步发送欢迎邮件\r\n send_welcome_email.delay(\r\n to_email=new_user.email,\r\n username=new_user.username\r\n )\r\n \r\n # 8. 返回创建结果（敏感信息脱敏）\r\n return created_response(new_user.to_safe_dict())\r\n```\r\n\r\n### 4.2 其他重要接口\r\n\r\n#### 4.2.1 更新用户接口\r\n- **URL**: `PUT /api/v1/users/{id}`\r\n- **权限**: `user:update` 或自己的信息\r\n\r\n#### 4.2.2 删除用户接口\r\n- **URL**: `DELETE /api/v1/users/{id}`\r\n- **权限**: `user:delete` 或 `admin` 角色\r\n- **注意**: 软删除，标记is_deleted=true\r\n\r\n#### 4.2.3 批量操作用户接口\r\n- **URL**: `POST /api/v1/users/batch`\r\n- **支持操作**: 批量激活、批量禁用、批量删除、批量分配角色\r\n\r\n## 5. 数据库设计\r\n\r\n### 5.1 表结构设计\r\n\r\n#### 表名: `users` (用户表)\r\n| 字段名 | 数据类型 | 长度 | 必填 | 默认值 | 说明 |\r\n|--------|----------|------|------|--------|------|\r\n| id | VARCHAR | 36 | ✓ | UUID() | 主键 |\r\n| username | VARCHAR | 50 | ✓ | | 用户名，唯一 |\r\n| email | VARCHAR | 100 | ✓ | | 邮箱，唯一 |\r\n| phone | VARCHAR | 20 | | NULL | 手机号，唯一 |\r\n| password_hash | VARCHAR | 255 | ✓ | | 密码哈希 |\r\n| avatar_url | VARCHAR | 255 | | NULL | 头像URL |\r\n| status | VARCHAR | 20 | ✓ | 'active' | 状态：active/inactive/locked |\r\n| role | VARCHAR | 20 | ✓ | 'user' | 角色：admin/user/guest |\r\n| last_login_at | TIMESTAMP | | | NULL | 最后登录时间 |\r\n| login_failures | INTEGER | | ✓ | 0 | 连续登录失败次数 |\r\n| locked_until | TIMESTAMP | | | NULL | 锁定直到时间 |\r\n| created_at | TIMESTAMP | | ✓ | CURRENT_TIMESTAMP | 创建时间 |\r\n| updated_at | TIMESTAMP | | ✓ | CURRENT_TIMESTAMP | 更新时间 |\r\n| created_by | VARCHAR | 36 | ✓ | | 创建者ID |\r\n| updated_by | VARCHAR | 36 | | NULL | 更新者ID |\r\n| is_deleted | BOOLEAN | | ✓ | FALSE | 软删除标记 |\r\n| deleted_at | TIMESTAMP | | | NULL | 删除时间 |\r\n| deleted_by | VARCHAR | 36 | | NULL | 删除者ID |\r\n\r\n**索引**:\r\n```sql\r\nPRIMARY KEY (id),\r\nUNIQUE KEY uk_username (username),\r\nUNIQUE KEY uk_email (email),\r\nUNIQUE KEY uk_phone (phone) WHERE phone IS NOT NULL,\r\nINDEX idx_status (status),\r\nINDEX idx_role (role),\r\nINDEX idx_created_at (created_at),\r\nINDEX idx_is_deleted (is_deleted)\r\n```\r\n\r\n#### 表名: `user_profiles` (用户档案表)\r\n| 字段名 | 数据类型 | 长度 | 必填 | 默认值 | 说明 |\r\n|--------|----------|------|------|--------|------|\r\n| id | VARCHAR | 36 | ✓ | UUID() | 主键 |\r\n| user_id | VARCHAR | 36 | ✓ | | 用户ID，外键 |\r\n| real_name | VARCHAR | 50 | | NULL | 真实姓名 |\r\n| gender | VARCHAR | 10 | | NULL | 性别：male/female/other |\r\n| birth_date | DATE | | | NULL | 出生日期 |\r\n| address | VARCHAR | 200 | | NULL | 地址 |\r\n| company | VARCHAR | 100 | | NULL | 公司 |\r\n| position | VARCHAR | 50 | | NULL | 职位 |\r\n| bio | TEXT | | | NULL | 个人简介 |\r\n| created_at | TIMESTAMP | | ✓ | CURRENT_TIMESTAMP | 创建时间 |\r\n| updated_at | TIMESTAMP | | ✓ | CURRENT_TIMESTAMP | 更新时间 |\r\n\r\n**外键约束**:\r\n```sql\r\nPRIMARY KEY (id),\r\nUNIQUE KEY uk_user_id (user_id),\r\nFOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE\r\n```\r\n\r\n#### 表名: `login_logs` (登录日志表)\r\n| 字段名 | 数据类型 | 长度 | 必填 | 默认值 | 说明 |\r\n|--------|----------|------|------|--------|------|\r\n| id | VARCHAR | 36 | ✓ | UUID() | 主键 |\r\n| user_id | VARCHAR | 36 | ✓ | | 用户ID |\r\n| ip_address | VARCHAR | 45 | ✓ | | IP地址 |\r\n| user_agent | VARCHAR | 500 | | NULL | 用户代理 |\r\n| login_type | VARCHAR | 20 | ✓ | 'password' | 登录方式 |\r\n| success | BOOLEAN | | ✓ | FALSE | 是否成功 |\r\n| fail_reason | VARCHAR | 100 | | NULL | 失败原因 |\r\n| login_at | TIMESTAMP | | ✓ | CURRENT_TIMESTAMP | 登录时间 |\r\n\r\n**索引**:\r\n```sql\r\nPRIMARY KEY (id),\r\nINDEX idx_user_id (user_id),\r\nINDEX idx_login_at (login_at),\r\nINDEX idx_success (success)\r\n```\r\n\r\n### 5.2 实体关系图\r\n```mermaid\r\nerDiagram\r\n users ||--|| user_profiles : has\r\n users ||--o{ login_logs : creates\r\n users ||--o{ operation_logs : performs\r\n \r\n users {\r\n VARCHAR id PK\r\n VARCHAR username UK\r\n VARCHAR email UK\r\n VARCHAR phone UK\r\n VARCHAR password_hash\r\n VARCHAR status\r\n VARCHAR role\r\n TIMESTAMP last_login_at\r\n INTEGER login_failures\r\n TIMESTAMP locked_until\r\n TIMESTAMP created_at\r\n TIMESTAMP updated_at\r\n VARCHAR created_by\r\n VARCHAR updated_by\r\n BOOLEAN is_deleted\r\n TIMESTAMP deleted_at\r\n VARCHAR deleted_by\r\n }\r\n \r\n user_profiles {\r\n VARCHAR id PK\r\n VARCHAR user_id FK\r\n VARCHAR real_name\r\n VARCHAR gender\r\n DATE birth_date\r\n VARCHAR address\r\n VARCHAR company\r\n VARCHAR position\r\n TEXT bio\r\n TIMESTAMP created_at\r\n TIMESTAMP updated_at\r\n }\r\n \r\n login_logs {\r\n VARCHAR id PK\r\n VARCHAR user_id FK\r\n VARCHAR ip_address\r\n VARCHAR user_agent\r\n VARCHAR login_type\r\n BOOLEAN success\r\n VARCHAR fail_reason\r\n TIMESTAMP login_at\r\n }\r\n```\r\n\r\n## 6. 部署与运维\r\n\r\n### 6.1 环境配置\r\n```yaml\r\n# docker-compose.prod.yml\r\nversion: '3.8'\r\nservices:\r\n postgres:\r\n image: postgres:15-alpine\r\n environment:\r\n POSTGRES_USER: ${DB_USER}\r\n POSTGRES_PASSWORD: ${DB_PASSWORD}\r\n POSTGRES_DB: ${DB_NAME}\r\n volumes:\r\n - postgres_data:/var/lib/postgresql/data\r\n ports:\r\n - \"5432:5432\"\r\n restart: unless-stopped\r\n\r\n redis:\r\n image: redis:7-alpine\r\n ports:\r\n - \"6379:6379\"\r\n restart: unless-stopped\r\n\r\n backend:\r\n build:\r\n context: ./backend\r\n dockerfile: Dockerfile.prod\r\n environment:\r\n NODE_ENV: production\r\n DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}\r\n REDIS_URL: redis://redis:6379\r\n JWT_SECRET: ${JWT_SECRET}\r\n ports:\r\n - \"8080:8080\"\r\n depends_on:\r\n - postgres\r\n - redis\r\n restart: unless-stopped\r\n\r\n frontend:\r\n build:\r\n context: ./frontend\r\n dockerfile: Dockerfile.prod\r\n ports:\r\n - \"3000:3000\"\r\n restart: unless-stopped\r\n\r\n nginx:\r\n image: nginx:alpine\r\n ports:\r\n - \"80:80\"\r\n - \"443:443\"\r\n volumes:\r\n - ./nginx.conf:/etc/nginx/nginx.conf\r\n - ./ssl:/etc/nginx/ssl\r\n depends_on:\r\n - backend\r\n - frontend\r\n restart: unless-stopped\r\n\r\nvolumes:\r\n postgres_data:\r\n```\r\n\r\n### 6.2 监控指标\r\n- API响应时间P95 < 300ms\r\n- 用户登录成功率 > 99.5%\r\n- 数据库连接池使用率 < 80%\r\n- 系统错误率 < 0.1%\r\n\r\n### 6.3 备份策略\r\n- 数据库每日全量备份，保留30天\r\n- 日志文件每日压缩归档，保留90天\r\n- 用户上传文件实时备份到对象存储\r\n\r\n## 7. 测试要点\r\n\r\n### 7.1 单元测试\r\n- 用户密码加密验证测试\r\n- 用户名/邮箱唯一性验证测试\r\n- 用户角色权限验证测试\r\n- 分页查询逻辑测试\r\n\r\n### 7.2 集成测试\r\n- 用户注册完整流程测试\r\n- 用户登录认证流程测试\r\n- 用户信息更新流程测试\r\n- 批量操作用户流程测试\r\n\r\n### 7.3 性能测试\r\n- 并发用户登录测试（1000用户/秒）\r\n- 大数据量用户列表查询测试（100万用户）\r\n- API压力测试（持续高并发请求）\r\n\r\n## 8. 开发注意事项\r\n\r\n### 8.1 安全性\r\n- 所有用户输入必须进行XSS过滤和SQL注入防护\r\n- 密码使用bcrypt算法加密存储，强度至少12轮\r\n- JWT令牌设置合理过期时间（access token: 15分钟，refresh token: 7天）\r\n- 敏感操作（删除、修改权限）需要二次确认\r\n- 登录失败次数限制和账户锁定机制\r\n\r\n### 8.2 性能优化\r\n- 用户列表查询使用复合索引（status, created_at）\r\n- 频繁访问的用户信息使用Redis缓存（过期时间5分钟）\r\n- 分页查询使用keyset分页优化大数据量性能\r\n- 头像等静态资源使用CDN加速\r\n\r\n### 8.3 可维护性\r\n- 遵循RESTful API设计规范\r\n- 统一的错误处理中间件\r\n- 详细的API文档（Swagger/OpenAPI）\r\n- 完整的日志记录（操作日志、错误日志、访问日志）\r\n\r\n---\r\n\r\n## 文档生成信息\r\n- **生成工具**: bie-zheng-luan-prototype v1.0.0\r\n- **生成时间**: 2026-04-21 18:30:00\r\n- **置信度评估**: 高（原型清晰，功能明确）\r\n- **建议复核**: 需要与产品经理确认用户角色和权限设计细节\r\n\r\n> **注意**: 本文档为技术分析结果，实际开发前应与产品经理确认以下细节：\r\n> 1. 用户角色具体权限划分\r\n> 2. 用户状态流转规则\r\n> 3. 密码重置流程设计\r\n> 4. 用户导入导出格式要求\n\nFile v2.3.3:skill-card.md\n\n## Description:\n\nConverts product prototypes from URLs, local HTML files, images, and XMind files into technical specifications covering UI structure, API design, database design, and business-flow questions.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[jermyn-zmj](https://clawhub.ai/user/jermyn-zmj)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, product engineers, and implementation teams use this skill to analyze prototype inputs and produce a draft implementation specification for building a similar product experience.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: URL prototype analysis can create SSRF exposure if redirects or network access reach private addresses.\n\nMitigation: Run the skill in an isolated environment, restrict outbound access where possible, avoid untrusted URLs, and use --allow-internal only for URLs you control.\n\nRisk: Optional vision workflows can transmit screenshots to an external service when a vision API key is configured.\n\nMitigation: Leave vision API credentials unset unless external transfer is approved, and do not analyze screenshots containing sensitive information.\n\nRisk: Generated API and database specifications may be incomplete or inaccurate.\n\nMitigation: Treat generated specifications as drafts and require human review before implementation.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/jermyn-zmj/skills/bie-zheng-luan-prototype)\n- [Template Specification](references/template-spec.md)\n- [Component Catalog](references/component-catalog.md)\n- [API Design Reference](references/api-design.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown technical specification with optional JSON analysis data and command examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include generated frontend component descriptions, API endpoint drafts, database schema drafts, and follow-up questions for human confirmation.]\n\n## Skill Version(s):\n\n2.3.3 (source: ClawHub release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v2.3.3:skill.json\n\n{\n \"name\": \"bie-zheng-luan-prototype\",\n \"displayName\": \"别整乱原型分析技能\",\n \"version\": \"3.1.0\",\n \"description\": \"将产品原型转换为详细技术规范的技能。深度解析HTML原型，提取完整的菜单结构、筛选条件、表格列、操作按钮等信息。支持URL原型、本地HTML文件、图片原型、XMind文件四种输入类型。完全通用化设计，不硬编码任何业务专有名词，可适配任何业务领域的原型系统。新增交互式业务分析功能，可从原型推断业务流程、状态流转，生成问题让用户确认。\",\n \"author\": \"杰哥\",\n \"license\": \"MIT\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/jermyn-zmj/bie-zheng-luan-prototype\"\n },\n \"homepage\": \"https://clawhub.ai/skills/bie-zheng-luan-prototype\",\n \"keywords\": [\n \"prototype\",\n \"analysis\",\n \"html\",\n \"xmind\",\n \"design\",\n \"figma\",\n \"technical-spec\",\n \"frontend\",\n \"backend\",\n \"database\"\n ],\n \"categories\": [\n \"development\",\n \"design\",\n \"productivity\",\n \"automation\"\n ],\n \"requirements\": {\n \"runtime\": [\n \"python3\",\n \"beautifulsoup4\",\n \"pillow\"\n ],\n \"tools\": [\n \"curl 或 wget（用于URL下载）\"\n ],\n \"optional\": [\n {\n \"name\": \"anthropic\",\n \"description\": \"Claude Vision API客户端，用于图片原型的精确UI识别（增强分析模式）\",\n \"useCase\": \"图片原型视觉增强分析\",\n \"envRequired\": \"ANTHROPIC_API_KEY\"\n },\n {\n \"name\": \"opencv-python\",\n \"description\": \"图像处理库，用于高级图片分析\",\n \"useCase\": \"高级图像处理\"\n }\n ],\n \"installNote\": \"Shell脚本不会自动安装依赖。请在运行前手动安装: pip install beautifulsoup4 pillow lxml\"\n },\n \"compatibility\": {\n \"openclaw\": \">=1.0.0\"\n },\n \"envVars\": {\n \"required\": [],\n \"optional\": [\n {\n \"name\": \"ANTHROPIC_API_KEY\",\n \"description\": \"Anthropic Claude API密钥，用于图片原型的视觉增强分析。设置此变量会启用外部API调用，将图片数据发送到Anthropic服务器。如果不设置，将使用本地基础图像分析（颜色提取、布局推断），不传输数据。\",\n \"required\": false,\n \"sensitive\": true,\n \"dataTransmission\": \"启用此变量后，图片数据将通过base64编码发送到Anthropic Claude API（外部服务）\"\n }\n ]\n },\n \"permissions\": {\n \"network\": {\n \"required\": true,\n \"description\": \"需要网络访问来下载公开URL的原型内容。\",\n \"allowIntranet\": false,\n \"intranetRequiresConfirmation\": true,\n \"warning\": \"内网URL默认被阻止。如需分析内部原型，需使用 --allow-internal 参数确认SSRF风险。\",\n \"internalUrlHandling\": \"检测内网/私有IP地址，默认拒绝访问，需用户通过命令行参数明确确认\"\n },\n \"filesystem\": {\n \"required\": true,\n \"description\": \"需要读取本地文件（HTML文件、图片文件、XMind文件）。\",\n \"operations\": [\"read\"],\n \"writeOperations\": \"仅写入用户指定的输出文件，不修改系统文件\"\n },\n \"externalServices\": {\n \"required\": false,\n \"optional\": [\n {\n \"name\": \"Anthropic Claude Vision API\",\n \"description\": \"用于图片原型的精确UI元素识别（可选增强功能）。\",\n \"dataTransmitted\": \"图片二进制数据（base64编码）\",\n \"warning\": \"启用此功能会将本地设计图片发送到Anthropic服务器。请确保图片不包含敏感信息。\",\n \"trigger\": \"用户设置ANTHROPIC_API_KEY环境变量后，通过代码调用启用\",\n \"default\": \"默认禁用（未设置环境变量时不调用外部API）\"\n }\n ]\n }\n },\n \"security\": {\n \"warnings\": [\n \"内网URL默认被阻止，需使用 --allow-internal 参数确认风险后才能访问\",\n \"设置ANTHROPIC_API_KEY会启用外部API调用，图片数据将发送到Anthropic服务器\",\n \"Shell脚本不会自动安装依赖，需手动pip install\"\n ],\n \"recommendations\": [\n \"首次使用前在虚拟环境中安装依赖: pip install beautifulsoup4 pillow lxml\",\n \"分析内网原型时，确认URL指向预期的内部资源\",\n \"使用视觉API前确认图片不含敏感内容\",\n \"建议在隔离环境中首次测试\"\n ],\n \"mitigations\": {\n \"commandInjection\": {\n \"implemented\": true,\n \"description\": \"Shell脚本对URL和路径参数进行严格验证，阻止shell特殊字符\"\n },\n \"ssrf\": {\n \"implemented\": true,\n \"description\": \"检测私有网络地址，默认拒绝访问，需用户通过--allow-internal参数明确确认\",\n \"userConfirmationRequired\": true\n },\n \"pathTraversal\": {\n \"implemented\": true,\n \"description\": \"文件路径验证，检测敏感路径关键词\"\n },\n \"inputValidation\": {\n \"implemented\": true,\n \"description\": \"Python脚本使用标准库处理输入，避免eval/exec\"\n },\n \"noAutoInstall\": {\n \"implemented\": true,\n \"description\": \"Shell脚本不自动执行pip install，仅检查依赖并提示用户手动安装\"\n },\n \"externalApiDefaultOff\": {\n \"implemented\": true,\n \"description\": \"外部API调用默认禁用，仅在用户设置ANTHROPIC_API_KEY后启用\"\n }\n }\n },\n \"tags\": [\n \"原型分析\",\n \"技术规范\",\n \"产品设计\",\n \"前端开发\",\n \"后端开发\",\n \"数据库设计\"\n ],\n \"features\": [\n \"深度HTML解析：提取菜单结构（分组+菜单项+页面标识+图标描述）\",\n \"深度HTML解析：提取侧边栏用户信息（头像+姓名+角色）\",\n \"深度HTML解析：提取页面标签栏（已打开的页面标签）\",\n \"深度HTML解析：提取消息通知卡片（标题+正文+时间+参与人数+评论数）\",\n \"深度HTML解析：提取人员工作进度卡片（姓名+标签+统计数据）\",\n \"深度HTML解析：提取筛选条件（字段名+类型+下拉选项+默认值）\",\n \"深度HTML解析：提取表格列（列名+数据类型推断+主表/明细表区分）\",\n \"深度HTML解析：提取操作按钮（按钮名+分类+样式+位置）\",\n \"深度HTML解析：识别多页面视图，按页面独立输出\",\n \"深度HTML解析：识别子标签切换（如工作台切换）\",\n \"深度HTML解析：提取状态筛选Tab（状态名称+数量+颜色类型）\",\n \"深度HTML解析：提取进度条组件（名称+详情+状态标签+日期）\",\n \"深度HTML解析：提取弹窗/抽屉面板（标题+锚点导航+表单字段+统计信息）\",\n \"深度HTML解析：提取弹窗内表单（字段名+类型+是否必填+下拉选项）\",\n \"深度HTML解析：提取弹窗内统计信息（分项数量汇总）\",\n \"深度HTML解析：提取弹窗内按钮（添加行+批量导入+关闭+保存+审核）\",\n \"支持公开URL原型分析（Figma/墨刀/Axure等）\",\n \"支持本地HTML文件解析\",\n \"支持图片原型分析（PNG/JPG/WebP等）\",\n \"支持XMind文件解析\",\n \"自动识别输入类型\",\n \"生成完整技术文档（含API/数据库设计建议）\",\n \"内网URL需用户确认 (--allow-internal)\",\n \"可选视觉增强分析（需ANTHROPIC_API_KEY，默认禁用）\",\n \"不自动安装依赖，需手动pip install\"\n ],\n \"usage\": {\n \"examples\": [\n \"分析Figma原型：$0 https://www.figma.com/file/xxx\",\n \"分析本地HTML：$0 /path/to/prototype.html\",\n \"分析内网原型（需确认）：$0 --allow-internal http://internal.company.com/proto\",\n \"分析设计图片：$0 /path/to/design.png\"\n ]\n },\n \"output\": {\n \"format\": \"markdown\",\n \"sections\": [\n \"系统概览\",\n \"页面结构分析\",\n \"前端实现方案\",\n \"后端实现方案\",\n \"数据库设计\",\n \"开发注意事项\"\n ]\n },\n \"created\": \"2026-04-22\",\n \"updated\": \"2026-04-23\",\n \"maintainers\": [\n \"杰哥\"\n ]\n}\n\nFile v2.3.3:requirements.txt\n\n# bie-zheng-luan-prototype 技能依赖\r\n\r\n# 核心依赖（必须安装）\r\nbeautifulsoup4>=4.12.0 # HTML解析\r\nPillow>=10.0.0 # 图片处理（基础分析）\r\n\r\n# 可选依赖（用于增强功能，需按需安装）\r\n# ============================================\r\n# anthropic>=0.25.0 # Claude Vision API客户端\r\n# # 用途：图片原型的精确UI元素识别\r\n# # 注意：使用此功能会将图片发送到Anthropic服务器\r\n# # 要求：设置环境变量 ANTHROPIC_API_KEY\r\n#\r\n# opencv-python>=4.8.0 # 图像处理库\r\n# # 用途：高级图像处理（边缘检测、区域分割）\r\n#\r\n# lxml>=4.9.0 # XML解析库\r\n# # 用途：XMind 8格式文件解析（备用）\r\n\r\n# 开发依赖（仅开发时需要）\r\n# ============================================\r\n# pytest>=7.0.0 # 测试框架\r\n# black>=23.0.0 # 代码格式化\r\n# flake8>=6.0.0 # 代码检查\n\nArchive v2.3.2: 22 files, 103401 bytes\n\nFiles: assets/sample-output/sample-user-management.md (24840b), README.md (12190b), references/api-design.md (15083b), references/component-catalog.md (9260b), references/template-spec.md (12944b), requirements.txt (1033b), scripts/html_extractor/__init__.py (1496b), scripts/html_extractor/config.py (6856b), scripts/html_extractor/detector.py (1353b), scripts/html_extractor/extractor.py (101503b), scripts/html_extractor/main.py (1467b), scripts/html_extractor/models.py (9293b), scripts/html_extractor/utils.py (874b), scripts/html-extractor.py (424b), scripts/image-prototype-analyzer.py (18581b), scripts/run_analysis.sh (1820b), scripts/spec-generator.py (38915b), scripts/url-prototype-analyzer.sh (13855b), scripts/xmind-analyzer.py (22415b), skill.json (8036b), SKILL.md (21993b), _meta.json (143b)\n\nFile v2.3.2:SKILL.md\n\n---\r\nname: bie-zheng-luan-prototype\r\ndescription: \"将产品原型转换为详细技术规范的技能。深度解析HTML原型，提取完整的菜单结构、筛选条件、表格列、操作按钮等信息。支持URL原型、本地HTML文件、图片原型、XMind文件四种输入类型。输出包含前端组件描述、后端接口设计、数据库表设计的完整技术文档。增强版包含智能路由推断、业务API接口推断、完整数据库表结构设计、实体关系图、状态枚举定义。\"\r\n---\r\n\r\n# 别整乱七八糟原型分析技能 (bie-zheng-luan-prototype)\r\n\r\n本技能将产品原型转换为详细的技术实现规范文档，**深度解析HTML结构**，提取完整的界面信息。\r\n\r\n## ✨ 核心能力（v2.4.0 新增）\r\n\r\n### 深度HTML解析\r\n本技能可从HTML原型中完整提取：\r\n\r\n| 提取内容 | 说明 | 输出格式 |\r\n|---------|------|---------|\r\n| **菜单结构** | 侧边栏菜单分组、菜单项、图标、页面标识 | 表格形式，含分组信息 |\r\n| **筛选条件** | 字段名、类型（select/input）、下拉选项列表 | 表格形式，含完整选项 |\r\n| **表格列** | 列名、数据类型推断（text/number/date/link等） | 表格形式 |\r\n| **操作按钮** | 按钮名、分类（search/action/delete等）、样式 | 表格形式 |\r\n| **统计卡片** | 卡片标题、数值、说明 | 表格形式 |\r\n| **页面视图** | 多页面识别，每个页面独立分析 | 按页面分章节输出 |\r\n\r\n### 数据类型智能推断\r\n表格列数据类型自动推断：\r\n- `text` - 普通文本\r\n- `number` - 数值（含逗号分隔）\r\n- `date` - 日期格式（YYYY-MM-DD）\r\n- `link` - 可点击链接/单号\r\n- `badge` - 状态标签\r\n- `progress` - 进度条\r\n- `image` - 图片列\r\n- `currency` - 金额（含¥符号）\r\n- `percentage` - 百分比\r\n\r\n> ⚠️ **安全警告（重要）**\r\n>\r\n> 使用本技能前请阅读以下安全注意事项：\r\n>\r\n> 1. **内网URL需确认**：内网URL默认被阻止。如需分析内部原型，需使用 `--allow-internal` 参数确认风险。请勿分析不应被访问的内部系统。\r\n>\r\n> 2. **外部API默认禁用**：视觉增强分析功能需要设置 `ANTHROPIC_API_KEY` 环境变量才会启用。**默认情况下不调用外部API**，图片分析仅使用本地基础功能（颜色提取、布局推断）。启用外部API会将图片发送到Anthropic服务器，请确认图片不含敏感内容。\r\n>\r\n> 3. **手动安装依赖**：Shell脚本**不会自动安装Python依赖**。请在运行前手动执行：`pip install beautifulsoup4 pillow lxml`\r\n>\r\n> 4. **本地文件访问**：技能会读取您指定的本地文件。请确保文件路径指向预期内容。\r\n\r\n## 🛡️ 已实施的安全措施\r\n\r\n本技能实施了以下安全防护措施：\r\n\r\n### 命令注入防护\r\n- URL验证：只允许 `http://` 和 `https://` 协议\r\n- 危险字符检测：阻止Shell特殊字符（`;|&$`'\\\"()<>`）\r\n- 长度限制：URL最大2048字符\r\n\r\n### SSRF防护（用户确认模式）\r\n- **默认阻止内网URL**：检测私有网络地址自动拒绝\r\n- **用户确认机制**：需使用 `--allow-internal` 参数才能访问内网\r\n- 检测范围：`localhost`、`127.x`、`10.x`、`172.16-31.x`、`192.168.x`、`169.254.x`\r\n\r\n### 外部API控制\r\n- **默认禁用**：未设置 `ANTHROPIC_API_KEY` 时，不调用任何外部API\r\n- **用户触发**：仅在用户主动设置环境变量后启用\r\n- **数据传输明确**：启用后图片会通过base64发送到Anthropic\r\n\r\n### 无自动安装\r\n- Shell脚本**不执行** `pip install`\r\n- 仅检查依赖并提示用户手动安装\r\n- 避免运行时写入操作\r\n\r\n### 路径安全验证\r\n- 检测敏感路径关键词并发出警告\r\n- 限制路径长度\r\n- 验证文件存在性\r\n\r\n## 🎯 技能用途\r\n\r\n当产品经理提供以下任意形式的原型时，使用本技能：\r\n\r\n1. **URL原型** - Figma、墨刀、Axure、蓝湖、内网分享链接等\r\n2. **本地HTML文件** - 导出的HTML原型文件、本地保存的网页原型\r\n3. **图片原型** - 设计稿截图、高保真原型图\r\n4. **XMind文件** - 产品功能脑图、信息架构\r\n\r\n**输出目标**：生成一份详细的技术规范文档，让大模型能据此生成相似度90%以上的系统。\r\n\r\n## 🔧 当前版本能力\r\n\r\n### ✅ 已支持\r\n- **URL原型分析**：支持Figma、墨刀、Axure等主流工具的公开/内网URL\r\n- **本地HTML文件分析**：支持本地导出的HTML原型文件，直接读取文件系统路径\r\n- **网页内容解析**：提取DOM结构、样式信息、交互元素\r\n- **图片原型分析**：支持PNG、JPG、JPEG、GIF、WebP、BMP等格式，提取颜色方案、布局区域，生成分析报告\r\n- **XMind文件分析**：解析.xmind文件（zip格式），提取思维导图节点层级，推断功能模块、页面结构、功能点\r\n\r\n## 📋 工作流程\r\n\r\n### 第1步：原型内容解析\r\n根据输入类型选择合适的解析方式：\r\n\r\n#### A. URL原型解析\r\n```bash\r\n# 使用 web_fetch 获取页面内容\r\n# 分析HTML结构，提取关键信息\r\n```\r\n\r\n**提取内容**：\r\n- 页面整体布局（头部、侧边栏、主内容区、底部）\r\n- 导航菜单结构（一级菜单、二级菜单）\r\n- 功能模块划分（卡片、表单、列表、图表等）\r\n- 交互元素（按钮、输入框、下拉框、链接等）\r\n- 文本内容（标题、描述、标签、按钮文字）\r\n\r\n#### B. 本地HTML文件解析\r\n```bash\r\n# 使用 read 工具直接读取本地HTML文件\r\n# 分析DOM结构，提取关键信息\r\n```\r\n\r\n**适用场景**：\r\n- 从原型工具（Figma/墨刀/Axure等）导出的HTML文件\r\n- 本地保存的网页原型\r\n- 需要离线分析的原型文件\r\n\r\n**输入方式**：\r\n- 文件路径（如 `/path/to/prototype.html`）\r\n- 文件内容粘贴（用户直接粘贴HTML代码）\r\n\r\n**提取内容**（与URL原型相同）：\r\n- 页面整体布局（头部、侧边栏、主内容区、底部）\r\n- 导航菜单结构（一级菜单、二级菜单）\r\n- 功能模块划分（卡片、表单、列表、图表等）\r\n- 交互元素（按钮、输入框、下拉框、链接等）\r\n- 文本内容（标题、描述、标签、按钮文字）\r\n- CSS设计系统（颜色变量、字体、间距等设计Token）\r\n\r\n#### C. 图片原型解析\r\n\r\n**适用场景**：\r\n- 产品设计稿截图\r\n- 高保真原型图\r\n- UI设计文件导出图片\r\n- 线框图/草图\r\n\r\n**输入方式**：\r\n- 图片文件路径（如 `/path/to/design.png`）\r\n- 支持格式：PNG, JPG, JPEG, GIF, WebP, BMP\r\n\r\n**基础分析功能**（当前实现）：\r\n```bash\r\n# 使用 image-prototype-analyzer.py 进行基础分析\r\npython scripts/image-prototype-analyzer.py design.png markdown\r\n```\r\n\r\n**提取内容**：\r\n- 图片尺寸和比例\r\n- 主要颜色方案（提取前10种主色）\r\n- 布局区域推断（基于尺寸比例）\r\n - 头部区域（顶部10-15%）\r\n - 侧边栏区域（左侧15-20%）\r\n - 主内容区\r\n - 底部区域\r\n- 颜色统计和配色建议\r\n\r\n**增强分析方案**（可选，需配置API密钥）：\r\n\r\n> ⚠️ **数据传输警告**：使用视觉增强分析会将图片数据发送到外部API服务。请确认图片不含敏感信息后再启用。\r\n\r\n图片原型分析建议配合视觉大模型获得精确结果。需设置环境变量 `ANTHROPIC_API_KEY`：\r\n\r\n```python\r\n# 使用Claude Vision进行精确UI识别\r\n# 注意：此功能会将图片发送到Anthropic服务器\r\nimport anthropic\r\nimport base64\r\nimport os\r\n\r\n# 需要设置环境变量: ANTHROPIC_API_KEY\r\napi_key = os.environ.get('ANTHROPIC_API_KEY')\r\nif not api_key:\r\n print(\"警告: 未设置ANTHROPIC_API_KEY，无法使用视觉增强分析\")\r\n print(\"将使用本地基础分析（颜色提取、布局推断）\")\r\n\r\nclient = anthropic.Anthropic(api_key=api_key)\r\n\r\nwith open('design.png', 'rb') as f:\r\n image_data = base64.b64encode(f.read()).decode()\r\n\r\nresponse = client.messages.create(\r\n model='claude-3-opus-20240229',\r\n max_tokens=4096,\r\n messages=[{\r\n 'role': 'user',\r\n 'content': [\r\n {'type': 'image', 'source': {'type': 'base64', 'media_type': 'image/png', 'data': image_data}},\r\n {'type': 'text', 'text': '''分析这张UI设计稿，提取：\r\n1. 页面布局结构（头部、侧边栏、主内容区、底部）\r\n2. UI组件类型（按钮、输入框、表格、卡片等）\r\n3. 交互元素（可点击、可输入）\r\n4. 颜色方案（主色、辅助色、背景色）\r\n5. 文本内容（标题、描述、按钮文案）\r\n请以结构化格式输出。'''}\r\n ]\r\n }]\r\n)\r\n```\r\n\r\n**视觉模型分析输出**：\r\n- 精确的UI元素位置和类型\r\n- 完整的文本内容提取\r\n- 交互元素识别（按钮、链接、输入框）\r\n- 样式细节（颜色、字体大小推断）\r\n- 组件层级关系\r\n\r\n#### D. XMind原型解析\r\n\r\n**适用场景**：\r\n- 产品功能脑图\r\n- 信息架构图\r\n- 业务流程图\r\n- 需求结构图\r\n\r\n**输入方式**：\r\n- XMind文件路径（如 `/path/to/product.xmind`）\r\n- 支持XMind 8和XMind 2020+格式\r\n\r\n**技术原理**：\r\nXMind文件是zip压缩包，包含：\r\n- `content.json` (XMind 2020+格式)\r\n- `content.xml` (XMind 8格式)\r\n- `manifest.xml` (元数据)\r\n\r\n```bash\r\n# 使用 xmind-analyzer.py 进行分析\r\npython scripts/xmind-analyzer.py product.xmind markdown\r\n```\r\n\r\n**提取内容**：\r\n- 思维导图完整结构\r\n- 所有节点标题和层级\r\n- 节点属性（颜色、图标、备注）\r\n- 统计信息（节点总数、最大层级）\r\n\r\n**智能推断功能**：\r\n基于节点标题关键词，自动推断：\r\n1. **功能模块**（包含\"模块\"、\"管理\"、\"系统\"）\r\n2. **页面结构**（包含\"页面\"、\"列表\"、\"详情\"）\r\n3. **功能点**（包含\"功能\"、\"操作\"、\"按钮\"）\r\n\r\n**输出内容**：\r\n- YAML格式的思维导图结构\r\n- 功能模块清单（含子节点）\r\n- 页面结构建议（含功能点）\r\n- 前端路由规划建议\r\n- 后端API接口规划\r\n- 数据库表设计建议\r\n\r\n### 第2步：功能拆解与职责划分\r\n将解析出的元素拆解为细小功能单元，并判断实现方式：\r\n\r\n#### 前端职责（纯前端实现）\r\n- 页面布局和样式\r\n- 交互效果（悬停、点击动画）\r\n- 本地数据操作（排序、过滤、分页）\r\n- 表单验证（前端规则）\r\n- 组件内部状态管理\r\n\r\n#### 后端职责（需要接口支持）\r\n- 数据持久化（增删改查）\r\n- 业务逻辑处理（计算、验证、流程）\r\n- 外部系统集成（支付、消息、文件）\r\n- 权限控制和安全性\r\n- 批量操作和复杂查询\r\n\r\n**判断标准**：\r\n- 是否需要保存数据？ → 后端接口\r\n- 是否需要复杂计算？ → 后端接口 \r\n- 是否涉及用户权限？ → 后端接口\r\n- 是否只是UI交互？ → 前端实现\r\n\r\n### 第3步：技术文档生成\r\n生成结构化技术规范文档，包含：\r\n\r\n#### 3.1 系统概览\r\n- 原型来源和类型\r\n- 分析时间和版本\r\n- 总体功能描述\r\n\r\n#### 3.2 页面结构分析\r\n- 布局分解（头部、侧边栏、主内容区、底部）\r\n- 功能模块清单（每个模块的位置、内容、交互）\r\n\r\n#### 3.3 前端实现方案\r\n- 页面路由规划\r\n- 组件清单（名称、props、状态、交互逻辑）\r\n- 样式方案（CSS框架、设计系统）\r\n- 交互细节（按钮点击、表单提交、数据展示）\r\n\r\n#### 3.4 后端实现方案\r\n- API接口设计（路由、HTTP方法、参数、返回值）\r\n- 业务逻辑伪代码（关键算法、流程控制）\r\n- 数据库表设计（表名、字段、类型、关系）\r\n- 第三方服务集成\r\n\r\n#### 3.5 开发注意事项\r\n- 技术栈建议\r\n- 特殊依赖说明\r\n- 性能和安全考虑\r\n- 测试要点\r\n\r\n## 🛠️ 工具和资源\r\n\r\n### 内置脚本\r\n- `scripts/url-prototype-analyzer.sh` - URL原型解析主脚本\r\n- `scripts/html-extractor.py` - HTML内容提取工具入口（调用 html_extractor 包）\r\n- `scripts/html_extractor/` - HTML解析核心模块包\r\n - `config.py` - UI框架配置\r\n - `models.py` - 数据结构定义\r\n - `detector.py` - UI框架检测器\r\n - `extractor.py` - 核心解析器\r\n - `utils.py` - 辅助函数\r\n - `main.py` - 入口函数\r\n- `scripts/spec-generator.py` - 技术文档生成工具\r\n- `scripts/image-prototype-analyzer.py` - 图片原型分析工具\r\n- `scripts/xmind-analyzer.py` - XMind文件分析工具\r\n- `scripts/run_analysis.sh` - 综合分析入口脚本\r\n\r\n### 参考模板\r\n- `references/template-spec.md` - 技术规范文档模板\r\n- `references/component-catalog.md` - 前端组件目录\r\n- `references/api-design.md` - API设计规范\r\n\r\n### 输出示例\r\n- `assets/sample-output/` - 示例输出文档\r\n\r\n## 📝 使用方法\r\n\r\n### 基本调用\r\n当用户提供原型URL或本地HTML文件路径时，直接使用本技能：\r\n\r\n```bash\r\n# 技能会自动识别输入类型并启动相应流程\r\n```\r\n\r\n### 手动触发\r\n如果需要特定分析模式，可指定参数：\r\n\r\n```bash\r\n# URL原型分析\r\n分析这个Figma原型：https://www.figma.com/file/xxx\r\n\r\n# 本地HTML文件分析\r\n分析这个HTML原型文件：/path/to/prototype.html\r\n分析这个HTML原型文件：[直接粘贴HTML内容]\r\n\r\n# 图片原型分析\r\n分析这张设计稿截图：/path/to/design.png\r\n# 配合视觉模型增强分析：\r\n使用Claude Vision分析这张设计稿：/path/to/design.png\r\n\r\n# XMind原型分析\r\n分析这个产品脑图：/path/to/product.xmind\r\n分析这个信息架构：/path/to/architecture.xmind\r\n```\r\n\r\n### 输入类型自动识别\r\n技能会根据输入内容自动判断解析方式：\r\n\r\n| 输入内容 | 识别方式 | 解析方式 |\r\n|---------|---------|---------|\r\n| `https://...` | 以http/https开头 | URL原型解析 |\r\n| `/path/to/file.html` | 文件路径，以.html结尾 | 本地HTML文件解析 |\r\n| `...` | 以HTML标签开头 | 直接解析粘贴的HTML内容 |\r\n| `/path/to/file.png/.jpg/.jpeg/.gif/.webp/.bmp` | 图片格式文件路径 | 图片原型解析 |\r\n| `/path/to/file.xmind` | .xmind后缀文件路径 | XMind文件解析 |\r\n\r\n### 分析助手（手上有钱）执行流程\r\n作为AI助手，当用户提供本地HTML文件时，按照以下流程执行：\r\n\r\n1. **读取文件**：使用 `read` 工具读取HTML文件内容\r\n2. **解析结构**：手动解析HTML的DOM结构，提取：\r\n - 页面布局框架\r\n - 导航和菜单\r\n - 功能模块卡片\r\n - 表单和交互元素\r\n - 数据表格\r\n - CSS设计系统（变量、颜色、字体）\r\n3. **生成文档**：按照技能模板生成技术规范文档\r\n4. **输出结果**：保存到指定路径或直接展示\r\n\r\n## 📊 输出文档标准\r\n\r\n### 前端组件描述标准\r\n对于每个页面组件，需要描述：\r\n\r\n1. **组件位置**：在页面哪个区域（头部/侧边栏/主内容区）\r\n2. **内容来源**：\r\n - 静态内容（写死在代码中）\r\n - 动态内容（从后端API获取）\r\n - 用户输入（表单字段）\r\n3. **展示样式**：\r\n - 布局方式（Flex/Grid/绝对定位）\r\n - 尺寸和间距\r\n - 颜色和字体\r\n - 响应式行为\r\n4. **交互逻辑**：\r\n - 按钮点击触发什么操作\r\n - 按钮名称和文案\r\n - 操作类型（导航/提交/删除/等）\r\n - 成功/失败反馈方式\r\n\r\n### 后端接口描述标准\r\n对于每个API接口，需要描述：\r\n\r\n1. **路由信息**：\r\n - HTTP方法（GET/POST/PUT/DELETE）\r\n - URL路径（/api/resource/:id）\r\n - 接口名称和用途\r\n2. **参数说明**：\r\n - 路径参数（:id）\r\n - 查询参数（?page=1&size=10）\r\n - 请求体（JSON结构）\r\n - 必填/选填字段\r\n3. **返回值**：\r\n - 成功响应（HTTP 200，JSON结构）\r\n - 错误响应（HTTP 4xx/5xx，错误信息）\r\n - 分页结构（如果需要）\r\n4. **业务逻辑伪代码**：\r\n - 主要处理步骤\r\n - 数据库操作（查询/插入/更新/删除）\r\n - 业务规则验证\r\n - 异常处理逻辑\r\n\r\n### 数据库设计标准\r\n对于每个业务实体，需要设计：\r\n\r\n1. **表结构**：\r\n - 表名（复数形式，小写加下划线）\r\n - 主键字段（id，自增或UUID）\r\n - 业务字段（名称、类型、长度、默认值）\r\n - 索引字段（查询优化）\r\n2. **表关系**：\r\n - 一对一关系\r\n - 一对多关系（外键）\r\n - 多对多关系（中间表）\r\n3. **约束条件**：\r\n - 唯一约束\r\n - 非空约束\r\n - 外键约束\r\n\r\n## 🔍 示例场景\r\n\r\n### 示例1：用户管理系统原型\r\n**输入**：Figma用户管理后台URL\r\n\r\n**输出包含**：\r\n- 前端：用户列表组件、用户表单组件、权限选择组件\r\n- 后端：用户CRUD接口、权限验证接口、搜索接口\r\n- 数据库：users表、roles表、user_roles关联表\r\n\r\n### 示例2：电商商品页面原型 \r\n**输入**：墨刀电商商品详情页URL\r\n\r\n**输出包含**：\r\n- 前端：商品展示组件、购物车组件、评价组件\r\n- 后端：商品查询接口、购物车接口、下单接口\r\n- 数据库：products表、categories表、orders表\r\n\r\n## ⚠️ 安全注意事项\r\n\r\n> 🔴 **高风险操作警告**：请在理解以下风险后使用本技能\r\n\r\n### 1. 网络访问与SSRF风险\r\n- **支持内网URL**：本技能可以访问内网链接（如 `http://internal.company.com/prototype`）\r\n- **SSRF风险**：恶意或错误的URL可能触发服务器端请求伪造，访问未预期的内部资源\r\n- **安全建议**：\r\n - 仅提供您有权访问且明确需要分析的原型链接\r\n - 不要提供包含敏感数据的内部系统URL（如管理后台、API端点）\r\n - 在受控网络环境中分析内部原型\r\n\r\n### 2. 外部API数据传输\r\n- **视觉增强分析**：使用Claude Vision需要将图片发送到Anthropic服务器\r\n- **数据泄露风险**：设计稿可能包含敏感业务信息、知识产权内容\r\n- **安全建议**：\r\n - 启用视觉增强前确认图片不含敏感信息\r\n - 不设置 `ANTHROPIC_API_KEY` 时使用本地基础分析（不传输数据）\r\n - 对敏感设计稿仅使用本地分析功能\r\n\r\n### 3. 本地文件访问\r\n- **读取范围**：技能会读取您指定的本地文件路径\r\n- **误操作风险**：错误路径可能读取非预期的敏感文件\r\n- **安全建议**：\r\n - 确保文件路径准确指向目标原型文件\r\n - 不要将技能指向包含密钥、配置文件的目录\r\n\r\n### 4. 首次使用安全检查\r\n- **脚本审查**：首次使用前建议检查 `scripts/` 目录下的Python脚本\r\n- **隔离测试**：建议在虚拟环境或沙箱中首次运行\r\n- **依赖安装**：在虚拟环境中安装requirements.txt的依赖\r\n\r\n## ⚠️ 技术限制\r\n\r\n1. **访问限制**：\r\n - 需要登录的工具（如私有Figma项目）可能无法访问完整内容\r\n - 动态加载的内容可能无法完全捕获\r\n - 复杂交互可能难以通过静态分析完全理解\r\n\r\n2. **输出质量**：\r\n - 文档详细程度直接影响生成系统的准确性\r\n - 需要人工复核关键业务逻辑\r\n - 建议与产品经理确认技术方案\r\n\r\n## 📈 后续扩展计划\r\n\r\n1. **V2.1**：集成视觉模型API，实现图片原型精确UI识别\r\n2. **V2.2**：支持多原型合并分析，生成完整系统架构\r\n3. **V2.3**：添加Figma API直接解析（需授权）\r\n4. **V3.0**：自动化测试用例生成，一键生成可运行原型代码\r\n\r\n## 📞 支持与反馈\r\n\r\n- **GitHub仓库**: https://github.com/jermyn-zmj/bie-zheng-luan-prototype\r\n- **问题反馈**: 通过GitHub Issues提交\r\n- **功能建议**: 通过GitHub Discussions讨论\r\n\r\n## 📄 许可证\r\n\r\n本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。\r\n\r\n## 🤝 贡献\r\n\r\n欢迎提交Issue和Pull Request！\r\n\r\n1. Fork 本仓库\r\n2. 创建功能分支 (`git checkout -b feature/amazing-feature`)\r\n3. 提交更改 (`git commit -m 'Add some amazing feature'`)\r\n4. 推送到分支 (`git push origin feature/amazing-feature`)\r\n5. 开启 Pull Request\r\n\r\n---\r\n\r\n*最后更新：2026-04-29*\r\n*作者：杰哥*\r\n\r\n**更新日志**：\r\n- v2.9.2 (2026-04-29): 增强文档透明度：补充脚本功能详细说明表格（网络访问、文件操作、安全措施）、补充作者信息和项目链接，响应平台安全审查建议\r\n- v2.9.1 (2026-04-29): 修复spec-generator.py的Python 3.7兼容性问题（`str | None`改为`Optional[str]`）\r\n- v2.9.0 (2026-04-29): 完全通用化重构：移除所有硬编码的业务专有名词（如\"采购\"、\"供应商\"、\"质检\"、\"入库\"等），使skill可适配任何业务领域（仓储、ERP、WMS、CMS等）。动态生成路由、API接口、数据库表，不依赖特定业务词汇映射。\r\n- v2.8.0 (2026-04-29): 增强技术实现推断能力：智能路由解析（处理javascript:void(0)等特殊值）、增强按钮位置识别（多层级父元素检查）、业务API接口推断、完整数据库表设计、实体关系图、状态枚举定义\r\n- v2.7.0 (2026-04-29): 模块化重构：将 html-extractor.py (2000+行) 拆分为 html_extractor 包（7个模块），提高可维护性\r\n- v2.6.0 (2026-04-24): 补充弹窗/抽屉面板解析：弹窗内表单字段、锚点导航、统计信息、状态筛选Tab、进度条组件\r\n- v2.5.0 (2026-04-24): 补充缺失解析模块：消息通知卡片、采购员进度卡片、页面标签栏、用户信息区、子标签切换；优化表格层级识别和数据类型推断\r\n- v2.4.0 (2026-04-24): 重写HTML解析器，深度提取菜单结构、筛选条件、表格列、操作按钮、多页面视图\r\n- v2.3.0 (2026-04-23): 内网URL默认阻止需用户确认、禁止自动pip安装、外部API默认禁用\r\n- v2.2.0 (2026-04-23): 实施命令注入防护、URL/路径输入验证\r\n- v2.1.0 (2026-04-23): 增加安全警告、声明可选API凭证\r\n- v2.0.0 (2026-04-22): 新增图片/XMind分析功能\r\n- v1.0.0 (2026-04-21): 初始版本\n\nFile v2.3.2:README.md\n\n# bie-zheng-luan-prototype (别整乱原型分析技能)\r\n\r\n> **作者**: 杰哥 | **主页**: https://clawhub.ai/skills/bie-zheng-luan-prototype | **源码**: https://github.com/jermyn-zmj/bie-zheng-luan-prototype\r\n\r\n将产品原型转换为详细技术规范的技能，支持4种输入类型：URL原型、本地HTML文件、图片原型、XMind文件。\r\n\r\n## 🎯 功能特性\r\n\r\n### ✅ 支持的输入类型\r\n1. **URL原型** - Figma、墨刀、Axure、蓝湖等设计工具的公开/内网链接\r\n2. **本地HTML文件** - 导出的HTML原型文件、本地保存的网页原型\r\n3. **图片原型** - 设计稿截图、高保真原型图（PNG/JPG/WebP等）\r\n4. **XMind文件** - 产品功能脑图、信息架构图\r\n\r\n### ✅ 核心能力\r\n- **智能解析**：自动识别输入类型并选择相应解析方式\r\n- **功能拆解**：将原型元素拆解为前端组件、后端接口、数据库设计\r\n- **技术文档生成**：输出完整的技术规范文档\r\n- **多格式支持**：HTML、图片、思维导图全面覆盖\r\n\r\n## 📦 安装\r\n\r\n### 通过OpenClaw安装\r\n```bash\r\nopenclaw skills install https://clawhub.ai/skills/bie-zheng-luan-prototype\r\n```\r\n\r\n### 手动安装\r\n```bash\r\n# 克隆仓库\r\ngit clone https://github.com/[your-username]/bie-zheng-luan-prototype.git\r\n\r\n# 复制到技能目录\r\ncp -r bie-zheng-luan-prototype ~/.openclaw/workspace/skills/\r\n```\r\n\r\n## 🚀 使用方法\r\n\r\n### 基本调用\r\n当用户提供原型时，直接使用本技能：\r\n\r\n```bash\r\n# 分析URL原型\r\n分析这个Figma原型：https://www.figma.com/file/xxx\r\n\r\n# 分析本地HTML文件\r\n分析这个HTML原型文件：/path/to/prototype.html\r\n\r\n# 分析图片原型\r\n分析这张设计稿截图：/path/to/design.png\r\n\r\n# 分析XMind文件\r\n分析这个产品脑图：/path/to/product.xmind\r\n```\r\n\r\n### 输入类型自动识别\r\n技能会根据输入内容自动判断解析方式：\r\n\r\n| 输入内容 | 识别方式 | 解析方式 |\r\n|---------|---------|---------|\r\n| `https://...` 或 `http://...` | 以http/https开头 | URL原型解析 |\r\n| `/path/to/file.html` | 文件路径，以.html结尾 | 本地HTML文件解析 |\r\n| `...` | 以HTML标签开头 | 直接解析粘贴的HTML内容 |\r\n| `/path/to/file.png/.jpg/.jpeg/.gif/.webp/.bmp` | 图片格式文件路径 | 图片原型解析 |\r\n| `/path/to/file.xmind` | .xmind后缀文件路径 | XMind文件解析 |\r\n\r\n## 📋 输出文档\r\n\r\n技能会生成包含以下内容的技术规范文档：\r\n\r\n### 1. 系统概览\r\n- 原型来源和类型\r\n- 分析时间和版本\r\n- 总体功能描述\r\n- 技术栈建议\r\n\r\n### 2. 页面结构分析\r\n- 布局分解（头部、侧边栏、主内容区、底部）\r\n- 功能模块清单\r\n- 交互元素识别\r\n\r\n### 3. 前端实现方案\r\n- 页面路由规划\r\n- 组件清单（名称、props、状态、交互逻辑）\r\n- 样式方案（CSS框架、设计系统）\r\n- 交互细节\r\n\r\n### 4. 后端实现方案\r\n- API接口设计（路由、HTTP方法、参数、返回值）\r\n- 业务逻辑伪代码\r\n- 数据库表设计\r\n- 第三方服务集成\r\n\r\n### 5. 开发注意事项\r\n- 技术栈建议\r\n- 特殊依赖说明\r\n- 性能和安全考虑\r\n- 测试要点\r\n\r\n## 🔧 内置工具\r\n\r\n### 脚本文件及功能说明\r\n\r\n| 脚本文件 | 功能 | 网络访问 | 文件操作 | 安全措施 |\r\n|---------|------|---------|---------|---------|\r\n| `url-prototype-analyzer.sh` | URL原型解析主脚本 | curl/wget下载公开URL | 读取HTML、写入输出文件 | URL验证、SSRF检测、命令注入防护 |\r\n| `run_analysis.sh` | 本地HTML综合分析入口 | 无 | 读取本地HTML、写入输出文件 | 路径验证、敏感路径警告 |\r\n| `html-extractor.py` | HTML内容深度提取 | 无 | 读取HTML文件 | 纯Python解析，无外部调用 |\r\n| `spec-generator.py` | 技术文档生成 | 无 | 写入输出文件 | 纯Python生成 |\r\n| `image-prototype-analyzer.py` | 图片原型分析 | 仅在设置ANTHROPIC_API_KEY时调用Claude API | 读取图片文件 | 默认本地分析，外部API需手动启用 |\r\n| `xmind-analyzer.py` | XMind文件分析 | 无 | 读取.xmind文件（zip解压） | 纯Python解析 |\r\n\r\n**脚本详细行为说明：**\r\n\r\n1. **url-prototype-analyzer.sh**\r\n - 仅下载用户提供的原型URL（http/https协议）\r\n - 内网URL默认阻止，需 `--allow-internal` 参数确认\r\n - 不执行任何 pip install 命令\r\n - 所有输入参数经过严格验证\r\n\r\n2. **run_analysis.sh**\r\n - 仅处理本地文件，无网络访问\r\n - 路径验证防止命令注入\r\n - 敏感路径（.ssh/.env/.git等）会发出警告\r\n\r\n3. **image-prototype-analyzer.py**\r\n - 默认使用本地分析（颜色提取、布局推断），无数据传输\r\n - 设置 `ANTHROPIC_API_KEY` 后可启用视觉增强分析（图片会发送到Anthropic服务器）\r\n\r\n### 参考模板\r\n- `references/template-spec.md` - 技术规范文档模板\r\n- `references/component-catalog.md` - 前端组件目录\r\n- `references/api-design.md` - API设计规范\r\n\r\n### 示例输出\r\n- `assets/sample-output/sample-user-management.md` - 用户管理系统示例\r\n\r\n## 📊 技术架构\r\n\r\n### 解析流程\r\n```\r\n输入识别 → 内容解析 → 功能拆解 → 文档生成 → 输出保存\r\n```\r\n\r\n### 依赖要求\r\n- **Python 3.8+**\r\n- **Python包（核心）**：\r\n - `beautifulsoup4` (HTML解析)\r\n - `Pillow` (图片处理)\r\n- **Python包（可选，用于增强功能）**：\r\n - `anthropic` (Claude Vision API，用于图片原型精确分析) — 需设置 `ANTHROPIC_API_KEY`\r\n - `opencv-python` (高级图像处理)\r\n\r\n### 文件结构\r\n```\r\nbie-zheng-luan-prototype/\r\n├── SKILL.md # 技能主文件\r\n├── README.md # 说明文档\r\n├── LICENSE # MIT许可证\r\n├── skill.json # 技能元数据\r\n├── scripts/ # 分析脚本\r\n│ ├── url-prototype-analyzer.sh\r\n│ ├── html-extractor.py\r\n│ ├── spec-generator.py\r\n│ ├── image-prototype-analyzer.py\r\n│ ├── xmind-analyzer.py\r\n│ └── run_analysis.sh\r\n├── references/ # 参考模板\r\n│ ├── template-spec.md\r\n│ ├── component-catalog.md\r\n│ └── api-design.md\r\n├── assets/ # 资源文件\r\n│ └── sample-output/\r\n│ └── sample-user-management.md\r\n└── requirements.txt # Python依赖\r\n```\r\n\r\n## 🎨 示例场景\r\n\r\n### 示例1：用户管理系统原型\r\n**输入**：Figma用户管理后台URL\r\n\r\n**输出包含**：\r\n- 前端：用户列表组件、用户表单组件、权限选择组件\r\n- 后端：用户CRUD接口、权限验证接口、搜索接口\r\n- 数据库：users表、roles表、user_roles关联表\r\n\r\n### 示例2：电商商品页面原型 \r\n**输入**：墨刀电商商品详情页URL\r\n\r\n**输出包含**：\r\n- 前端：商品展示组件、购物车组件、评价组件\r\n- 后端：商品查询接口、购物车接口、下单接口\r\n- 数据库：products表、categories表、orders表\r\n\r\n## 🛡️ 安全措施\r\n\r\n本技能实施了严格的安全防护：\r\n\r\n### 内网URL控制\r\n- **默认阻止**：私有网络地址自动拒绝\r\n- **用户确认**：需 `--allow-internal` 参数才能访问内网\r\n- 检测范围：localhost、127.x、10.x、172.16-31.x、192.168.x\r\n\r\n### 外部API控制\r\n- **默认禁用**：未设置 `ANTHROPIC_API_KEY` 不调用外部API\r\n- **主动触发**：仅在用户设置环境变量后启用\r\n- 图片分析默认使用本地基础功能\r\n\r\n### 无自动安装\r\n- Shell脚本**不执行** `pip install`\r\n- 仅检查依赖，提示用户手动安装\r\n- 避免运行时写入操作\r\n\r\n### 命令注入防护\r\n- URL验证：只允许http/https协议\r\n- 阻止Shell特殊字符\r\n- 长度限制：URL最大2048字符\r\n\r\n---\r\n\r\n## ⚠️ 安全注意事项\r\n\r\n> 🔴 **使用前必读**：本技能涉及网络访问和可选外部API调用，请理解以下风险：\r\n\r\n### 内网URL访问控制\r\n- 内网URL**默认被阻止**\r\n- 需使用 `--allow-internal` 参数确认后才能访问\r\n- 请勿分析不应访问的内部系统\r\n\r\n### 外部API数据传输\r\n- 视觉增强分析需设置 `ANTHROPIC_API_KEY`\r\n- **默认禁用**：未设置环境变量时不调用外部API\r\n- 启用后图片会发送到Anthropic服务器\r\n\r\n### 本地文件访问\r\n- 技能会读取您指定的本地文件路径\r\n- 请确保路径指向预期文件\r\n\r\n### 首次使用建议\r\n- **手动安装依赖**：`pip install beautifulsoup4 pillow lxml`（脚本不会自动安装）\r\n- 检查 `scripts/` 目录下的脚本内容\r\n- 在隔离环境中首次测试\r\n\r\n## 🔄 版本历史\r\n\r\n### v2.9.2 (2026-04-29)\r\n- ✅ 增强文档透明度：补充脚本功能详细说明表格（网络访问、文件操作、安全措施）\r\n- ✅ 补充作者信息和项目链接在README顶部\r\n- ✅ 响应平台安全审查建议，提高脚本行为透明度\r\n\r\n### v2.9.1 (2026-04-29)\r\n- ✅ 修复spec-generator.py的Python 3.7兼容性问题（`str | None`改为`Optional[str]`）\r\n\r\n### v2.9.0 (2026-04-29)\r\n- ✅ **完全通用化重构**：移除所有硬编码的业务专有名词\r\n- ✅ 动态生成路由、API接口、数据库表，不依赖特定业务词汇映射\r\n- ✅ 可适配任何业务领域原型（仓储、ERP、WMS、CMS、CRM等）\r\n\r\n### v2.8.0 (2026-04-29)\r\n- ✅ **增强技术实现推断**：智能路由解析（处理javascript:void(0)等特殊值）\r\n- ✅ 增强按钮位置识别（多层级父元素检查）\r\n- ✅ 业务API接口推断、完整数据库表设计、实体关系图、状态枚举定义\r\n\r\n### v2.7.0 (2026-04-29)\r\n- ✅ **模块化重构**：将 html-extractor.py (2000+行) 拆分为 html_extractor 包（7个模块）\r\n- ✅ 提高代码可维护性和可读性\r\n\r\n### v2.6.0 (2026-04-24)\r\n- ✅ 补充弹窗/抽屉面板解析：弹窗内表单字段、锚点导航、统计信息\r\n- ✅ 补充状态筛选Tab、进度条组件解析\r\n\r\n### v2.5.0 (2026-04-24)\r\n- ✅ 补充缺失解析模块：消息通知卡片、采购员进度卡片、页面标签栏\r\n- ✅ 优化表格层级识别和数据类型推断\r\n\r\n### v2.4.0 (2026-04-24)\r\n- ✅ 重写HTML解析器，深度提取菜单结构、筛选条件、表格列、操作按钮\r\n- ✅ 支持多页面视图识别和独立分析\r\n\r\n### v2.3.0 (2026-04-23)\r\n- ✅ **内网URL默认阻止**，需 `--allow-internal` 参数确认\r\n- ✅ **禁止自动pip安装**，改为提示用户手动安装\r\n- ✅ **外部API默认禁用**，仅在设置 `ANTHROPIC_API_KEY` 后启用\r\n- ✅ 在skill.json中完善安全措施声明\r\n\r\n### v2.2.0 (2026-04-23)\r\n- ✅ 实施命令注入防护（URL/路径输入验证）\r\n- ✅ 添加SSRF检测警告（私有网络地址检测）\r\n- ✅ 添加路径遍历防护（敏感路径检测）\r\n- ✅ 在skill.json中声明安全缓解措施\r\n\r\n### v2.1.0 (2026-04-23)\r\n- ✅ 增加安全警告声明（SSRF、数据泄露风险）\r\n- ✅ 在skill.json中声明可选环境变量 `ANTHROPIC_API_KEY`\r\n- ✅ 增加外部服务数据传输警告\r\n- ✅ 提供首次使用安全建议\r\n\r\n### v2.0.0 (2026-04-22)\r\n- ✅ 新增本地HTML文件解析支持\r\n- ✅ 新增图片原型分析功能\r\n- ✅ 新增XMind文件解析功能\r\n- ✅ 修复spec-generator.py中的bug\r\n- ✅ 完善技能文档和示例\r\n\r\n### v1.0.0 (2026-04-21)\r\n- ✅ 初始版本：URL原型分析功能\r\n- ✅ 基础HTML解析和文档生成\r\n\r\n## 📄 许可证\r\n\r\n本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。\r\n\r\n## 🤝 贡献\r\n\r\n欢迎提交Issue和Pull Request！\r\n\r\n1. Fork 本仓库\r\n2. 创建功能分支 (`git checkout -b feature/amazing-feature`)\r\n3. 提交更改 (`git commit -m 'Add some amazing feature'`)\r\n4. 推送到分支 (`git push origin feature/amazing-feature`)\r\n5. 开启 Pull Request\r\n\r\n## 📞 支持\r\n\r\n- 问题反馈：[GitHub Issues](https://github.com/[your-username]/bie-zheng-luan-prototype/issues)\r\n- 功能建议：[GitHub Discussions](https://github.com/[your-username]/bie-zheng-luan-prototype/discussions)\r\n\r\n---\r\n\r\n*让产品原型不再\"别整乱\"，一键生成技术规范！*\n\nFile v2.3.2:_meta.json\n\n{\n \"ownerId\": \"kn73wmmkp7pzethhh52mkcsb6n85c3h4\",\n \"slug\": \"bie-zheng-luan-prototype\",\n \"version\": \"2.3.2\",\n \"publishedAt\": 1777445353511\n}\n\nFile v2.3.2:references/api-design.md\n\n# API设计规范参考\r\n\r\n本文档提供RESTful API设计的标准规范，用于技术文档生成时的参考。\r\n\r\n## 设计原则\r\n\r\n### 1. RESTful原则\r\n- **资源导向**：API围绕资源设计，而非操作\r\n- **统一接口**：使用标准HTTP方法\r\n- **无状态**：每个请求包含所有必要信息\r\n- **可缓存**：适当使用缓存头\r\n- **分层系统**：客户端不依赖直接连接\r\n- **按需代码**：可选支持客户端代码扩展\r\n\r\n### 2. 版本管理\r\n- URL路径包含版本：`/api/v1/resource`\r\n- 使用Accept头：`Accept: application/vnd.company.v1+json`\r\n- **推荐**：URL路径版本控制，简单明确\r\n\r\n### 3. 安全原则\r\n- 所有API强制HTTPS\r\n- 身份验证和授权分离\r\n- 输入验证和输出过滤\r\n- 速率限制和配额管理\r\n\r\n## API结构规范\r\n\r\n### 1. 资源命名\r\n- 使用名词复数形式：`/users` 而非 `/user`\r\n- 小写字母，单词间用连字符：`/user-roles`\r\n- 避免动词：使用HTTP方法表示操作\r\n\r\n### 2. HTTP方法使用\r\n| 方法 | 用途 | 幂等性 | 安全性 |\r\n|------|------|--------|--------|\r\n| GET | 获取资源 | 是 | 是 |\r\n| POST | 创建资源 | 否 | 否 |\r\n| PUT | 全量更新资源 | 是 | 否 |\r\n| PATCH | 部分更新资源 | 否 | 否 |\r\n| DELETE | 删除资源 | 是 | 否 |\r\n\r\n### 3. 端点设计示例\r\n```\r\n# 资源集合操作\r\nGET /api/v1/users # 获取用户列表\r\nPOST /api/v1/users # 创建新用户\r\n\r\n# 单个资源操作\r\nGET /api/v1/users/{id} # 获取指定用户\r\nPUT /api/v1/users/{id} # 全量更新用户\r\nPATCH /api/v1/users/{id} # 部分更新用户\r\nDELETE /api/v1/users/{id} # 删除用户\r\n\r\n# 子资源操作\r\nGET /api/v1/users/{id}/orders # 获取用户的订单\r\nPOST /api/v1/users/{id}/orders # 为用户创建订单\r\nGET /api/v1/users/{id}/orders/{orderId} # 获取用户特定订单\r\n```\r\n\r\n## 请求与响应规范\r\n\r\n### 1. 请求头标准\r\n```http\r\n# 必需头\r\nContent-Type: application/json\r\nAuthorization: Bearer {token}\r\nAccept: application/json\r\n\r\n# 推荐头\r\nX-Request-ID: {uuid} # 请求跟踪\r\nX-Client-Version: 1.0.0 # 客户端版本\r\nX-Device-Info: {device_info} # 设备信息\r\n```\r\n\r\n### 2. 请求参数类型\r\n| 参数位置 | 用途 | 示例 |\r\n|----------|------|------|\r\n| 路径参数 | 资源标识 | `/users/{id}` |\r\n| 查询参数 | 筛选、排序、分页 | `?page=1&size=10` |\r\n| 请求体 | 创建/更新数据 | JSON对象 |\r\n| 请求头 | 元数据、认证 | `Authorization` |\r\n\r\n### 3. 响应格式标准\r\n\r\n#### 成功响应 (HTTP 2xx)\r\n```json\r\n{\r\n \"code\": 200,\r\n \"message\": \"success\",\r\n \"data\": {\r\n // 业务数据\r\n },\r\n \"meta\": {\r\n // 分页、时间戳等元数据\r\n }\r\n}\r\n```\r\n\r\n#### 分页响应\r\n```json\r\n{\r\n \"code\": 200,\r\n \"message\": \"success\",\r\n \"data\": {\r\n \"items\": [...], // 当前页数据\r\n \"total\": 100, // 总记录数\r\n \"page\": 1, // 当前页码\r\n \"size\": 10, // 每页大小\r\n \"pages\": 10 // 总页数\r\n }\r\n}\r\n```\r\n\r\n#### 错误响应 (HTTP 4xx/5xx)\r\n```json\r\n{\r\n \"code\": 400,\r\n \"message\": \"参数验证失败\",\r\n \"errors\": [\r\n {\r\n \"field\": \"username\",\r\n \"code\": \"REQUIRED\",\r\n \"message\": \"用户名不能为空\"\r\n },\r\n {\r\n \"field\": \"email\",\r\n \"code\": \"INVALID_FORMAT\",\r\n \"message\": \"邮箱格式不正确\"\r\n }\r\n ],\r\n \"request_id\": \"req_123456\",\r\n \"timestamp\": \"2026-04-21T10:00:00Z\"\r\n}\r\n```\r\n\r\n### 4. HTTP状态码使用\r\n| 状态码 | 含义 | 使用场景 |\r\n|--------|------|----------|\r\n| 200 | OK | 成功获取或更新资源 |\r\n| 201 | Created | 资源创建成功 |\r\n| 204 | No Content | 成功但无返回内容 |\r\n| 400 | Bad Request | 请求参数错误 |\r\n| 401 | Unauthorized | 未认证或认证失败 |\r\n| 403 | Forbidden | 无访问权限 |\r\n| 404 | Not Found | 资源不存在 |\r\n| 409 | Conflict | 资源冲突（如重复创建） |\r\n| 422 | Unprocessable Entity | 业务逻辑验证失败 |\r\n| 429 | Too Many Requests | 请求过于频繁 |\r\n| 500 | Internal Server Error | 服务器内部错误 |\r\n| 503 | Service Unavailable | 服务暂时不可用 |\r\n\r\n## 分页、排序和筛选\r\n\r\n### 1. 分页参数\r\n```http\r\nGET /api/v1/users?page=1&size=10\r\n```\r\n- `page`: 页码（从1开始）\r\n- `size`: 每页记录数（默认10，最大100）\r\n- **注意**: 避免使用 `limit` 和 `offset`，语义不如 `page` 和 `size` 明确\r\n\r\n### 2. 排序参数\r\n```http\r\nGET /api/v1/users?sort=created_at:desc,username:asc\r\n```\r\n格式：`字段名:方向`\r\n- 方向：`asc`（升序）或 `desc`（降序）\r\n- 多个排序字段用逗号分隔\r\n\r\n### 3. 筛选参数\r\n```http\r\nGET /api/v1/users?status=active&role=admin&created_after=2026-01-01\r\n```\r\n- 使用查询参数进行筛选\r\n- 支持范围查询：`created_after`、`created_before`\r\n- 支持部分匹配：`name_like=john`\r\n- 支持IN查询：`status=active,inactive`\r\n\r\n## 业务逻辑伪代码规范\r\n\r\n### 1. 标准结构\r\n```python\r\ndef api_endpoint(request):\r\n \"\"\"\r\n 函数文档字符串：描述接口功能\r\n \r\n Args:\r\n request: 请求对象，包含参数、用户信息等\r\n \r\n Returns:\r\n 响应数据或错误\r\n \r\n Raises:\r\n 可能抛出的异常\r\n \"\"\"\r\n \r\n # 1. 参数验证\r\n validate_request(request)\r\n \r\n # 2. 权限检查\r\n check_permission(request.user)\r\n \r\n # 3. 业务逻辑处理\r\n result = process_business_logic(request)\r\n \r\n # 4. 数据持久化\r\n save_to_database(result)\r\n \r\n # 5. 返回响应\r\n return format_response(result)\r\n```\r\n\r\n### 2. CRUD操作模板\r\n\r\n#### 创建资源\r\n```python\r\ndef create_resource(request):\r\n # 1. 解析请求数据\r\n data = parse_request_body(request)\r\n \r\n # 2. 验证数据完整性\r\n errors = validate_create_data(data)\r\n if errors:\r\n return validation_error_response(errors)\r\n \r\n # 3. 检查唯一性约束\r\n if resource_exists(data['unique_field']):\r\n return conflict_error('资源已存在')\r\n \r\n # 4. 业务逻辑处理\r\n processed_data = apply_business_rules(data)\r\n \r\n # 5. 创建资源\r\n resource = Resource.create(**processed_data)\r\n \r\n # 6. 触发后续操作（异步）\r\n trigger_async_tasks(resource)\r\n \r\n # 7. 返回创建结果\r\n return created_response(resource.to_dict())\r\n```\r\n\r\n#### 获取资源列表\r\n```python\r\ndef list_resources(request):\r\n # 1. 解析查询参数\r\n page = request.query.get('page', 1)\r\n size = request.query.get('size', 10)\r\n filters = extract_filters(request.query)\r\n \r\n # 2. 构建查询\r\n query = Resource.query.filter_by(is_deleted=False)\r\n \r\n # 3. 应用筛选条件\r\n if filters:\r\n query = apply_filters(query, filters)\r\n \r\n # 4. 应用排序\r\n sort_fields = parse_sort_fields(request.query.get('sort'))\r\n if sort_fields:\r\n query = apply_sorting(query, sort_fields)\r\n \r\n # 5. 执行分页查询\r\n total = query.count()\r\n items = query.paginate(page, size).all()\r\n \r\n # 6. 格式化数据\r\n formatted_items = [item.to_summary_dict() for item in items]\r\n \r\n # 7. 返回分页结果\r\n return paginated_response(formatted_items, total, page, size)\r\n```\r\n\r\n#### 更新资源\r\n```python\r\ndef update_resource(request, resource_id):\r\n # 1. 查找资源\r\n resource = Resource.find_or_404(resource_id)\r\n \r\n # 2. 权限验证（资源级权限）\r\n if not can_edit_resource(request.user, resource):\r\n return forbidden_error('无权修改此资源')\r\n \r\n # 3. 解析更新数据\r\n update_data = parse_request_body(request)\r\n \r\n # 4. 验证更新数据\r\n errors = validate_update_data(update_data, resource)\r\n if errors:\r\n return validation_error_response(errors)\r\n \r\n # 5. 应用更新\r\n before_update = resource.to_dict()\r\n resource.update(**update_data)\r\n after_update = resource.to_dict()\r\n \r\n # 6. 记录变更日志\r\n log_change(request.user, 'update', before_update, after_update)\r\n \r\n # 7. 返回更新结果\r\n return success_response(resource.to_dict())\r\n```\r\n\r\n#### 删除资源\r\n```python\r\ndef delete_resource(request, resource_id):\r\n # 1. 查找资源\r\n resource = Resource.find_or_404(resource_id)\r\n \r\n # 2. 权限验证（删除权限）\r\n if not can_delete_resource(request.user, resource):\r\n return forbidden_error('无权删除此资源')\r\n \r\n # 3. 检查关联约束\r\n if has_dependent_resources(resource):\r\n return conflict_error('存在关联资源，无法删除')\r\n \r\n # 4. 执行软删除（或物理删除）\r\n resource.mark_as_deleted()\r\n # 或: resource.delete()\r\n \r\n # 5. 清理关联数据\r\n cleanup_related_data(resource)\r\n \r\n # 6. 返回成功响应（无内容）\r\n return no_content_response()\r\n```\r\n\r\n### 3. 复杂业务逻辑示例\r\n\r\n#### 订单创建流程\r\n```python\r\ndef create_order(request):\r\n \"\"\"\r\n 创建订单的完整流程\r\n \r\n 业务规则：\r\n 1. 验证用户账户状态\r\n 2. 检查商品库存\r\n 3. 计算价格和优惠\r\n 4. 扣减库存\r\n 5. 创建订单记录\r\n 6. 扣款或生成待支付订单\r\n 7. 发送订单确认通知\r\n \"\"\"\r\n \r\n # 1. 验证用户和权限\r\n user = get_current_user(request)\r\n if not user.is_active:\r\n return bad_request('用户账户已冻结')\r\n \r\n # 2. 解析订单数据\r\n order_data = request.json\r\n items = order_data['items']\r\n \r\n # 3. 检查商品库存（事务性）\r\n with transaction.atomic():\r\n # 锁定库存记录\r\n product_stocks = ProductStock.select_for_update().filter(\r\n product_id__in=[item['product_id'] for item in items]\r\n )\r\n \r\n # 验证库存充足\r\n for item in items:\r\n stock = next(s for s in product_stocks if s.product_id == item['product_id'])\r\n if stock.quantity < item['quantity']:\r\n return insufficient_stock_error(stock.product.name)\r\n \r\n # 4. 计算订单金额\r\n order_amount = calculate_order_amount(items, user)\r\n \r\n # 5. 扣减库存\r\n for item in items:\r\n stock = next(s for s in product_stocks if s.product_id == item['product_id'])\r\n stock.quantity -= item['quantity']\r\n stock.save()\r\n \r\n # 6. 创建订单\r\n order = Order.create(\r\n user_id=user.id,\r\n amount=order_amount,\r\n status='pending_payment',\r\n items=items\r\n )\r\n \r\n # 7. 记录库存变更日志\r\n log_inventory_changes(order, product_stocks)\r\n \r\n # 8. 异步处理后续操作\r\n async_tasks = [\r\n send_order_confirmation_email(order),\r\n update_user_purchase_stats(user),\r\n trigger_inventory_replenishment_check(product_stocks)\r\n ]\r\n execute_async_tasks(async_tasks)\r\n \r\n # 9. 返回订单信息\r\n return created_response(order.to_detail_dict())\r\n```\r\n\r\n## 数据库设计参考\r\n\r\n### 1. 表设计规范\r\n```sql\r\n-- 基础表结构模板\r\nCREATE TABLE table_name (\r\n id VARCHAR(36) PRIMARY KEY DEFAULT UUID(), -- 主键使用UUID\r\n -- 业务字段\r\n name VARCHAR(100) NOT NULL,\r\n status VARCHAR(20) NOT NULL DEFAULT 'active',\r\n -- 元数据字段\r\n created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,\r\n updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,\r\n created_by VARCHAR(36) NOT NULL,\r\n updated_by VARCHAR(36),\r\n is_deleted BOOLEAN NOT NULL DEFAULT FALSE,\r\n deleted_at TIMESTAMP,\r\n deleted_by VARCHAR(36),\r\n -- 约束\r\n UNIQUE KEY uk_name (name),\r\n INDEX idx_status (status),\r\n INDEX idx_created_at (created_at)\r\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;\r\n```\r\n\r\n### 2. 关联关系设计\r\n```sql\r\n-- 一对一关系\r\nALTER TABLE profile \r\n ADD CONSTRAINT fk_profile_user \r\n FOREIGN KEY (user_id) REFERENCES users(id) \r\n ON DELETE CASCADE;\r\n\r\n-- 一对多关系 \r\nALTER TABLE orders\r\n ADD CONSTRAINT fk_order_user\r\n FOREIGN KEY (user_id) REFERENCES users(id)\r\n ON DELETE RESTRICT;\r\n\r\n-- 多对多关系（中间表）\r\nCREATE TABLE user_roles (\r\n id VARCHAR(36) PRIMARY KEY DEFAULT UUID(),\r\n user_id VARCHAR(36) NOT NULL,\r\n role_id VARCHAR(36) NOT NULL,\r\n created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,\r\n UNIQUE KEY uk_user_role (user_id, role_id),\r\n FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,\r\n FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE\r\n);\r\n```\r\n\r\n## 错误处理规范\r\n\r\n### 1. 错误代码定义\r\n```json\r\n{\r\n \"code\": \"VALIDATION_ERROR\",\r\n \"message\": \"参数验证失败\",\r\n \"details\": [\r\n {\r\n \"field\": \"email\",\r\n \"code\": \"INVALID_FORMAT\",\r\n \"message\": \"邮箱格式不正确\"\r\n }\r\n ]\r\n}\r\n```\r\n\r\n### 2. 常见错误代码\r\n| 错误代码 | HTTP状态码 | 含义 |\r\n|----------|------------|------|\r\n| `VALIDATION_ERROR` | 400 | 参数验证失败 |\r\n| `AUTHENTICATION_FAILED` | 401 | 认证失败 |\r\n| `PERMISSION_DENIED` | 403 | 权限不足 |\r\n| `RESOURCE_NOT_FOUND` | 404 | 资源不存在 |\r\n| `RESOURCE_CONFLICT` | 409 | 资源冲突 |\r\n| `RATE_LIMIT_EXCEEDED` | 429 | 请求频率超限 |\r\n| `INTERNAL_ERROR` | 500 | 服务器内部错误 |\r\n| `SERVICE_UNAVAILABLE` | 503 | 服务不可用 |\r\n\r\n## 性能优化建议\r\n\r\n### 1. 数据库优化\r\n- 合理使用索引（查询字段、排序字段）\r\n- 避免N+1查询问题（使用JOIN或批量查询）\r\n- 分页查询使用游标分页（Cursor-based Pagination）替代偏移分页\r\n\r\n### 2. 缓存策略\r\n```python\r\n# Redis缓存示例\r\nCACHE_KEYS = {\r\n 'user': 'user:{id}',\r\n 'user_products': 'user:{id}:products',\r\n 'product_detail': 'product:{id}:detail'\r\n}\r\n\r\n# 缓存读取策略\r\ndef get_user_with_cache(user_id):\r\n cache_key = CACHE_KEYS['user'].format(id=user_id)\r\n cached_data = redis.get(cache_key)\r\n \r\n if cached_data:\r\n return json.loads(cached_data)\r\n \r\n # 缓存未命中，查询数据库\r\n user = User.get(user_id)\r\n if user:\r\n # 设置缓存，过期时间30分钟\r\n redis.setex(cache_key, 1800, json.dumps(user.to_dict()))\r\n \r\n return user\r\n```\r\n\r\n### 3. 异步处理\r\n- 耗时操作异步执行（邮件发送、文件处理等）\r\n- 使用消息队列解耦服务\r\n- 实现重试和死信队列机制\r\n\r\n## 文档要求\r\n\r\n在技术文档中描述API时，应为每个接口提供：\r\n\r\n1. **接口基本信息**：URL、方法、功能描述\r\n2. **请求参数**：路径参数、查询参数、请求体\r\n3. **响应格式**：成功响应、错误响应\r\n4. **业务逻辑**：详细处理步骤（伪代码）\r\n5. **权限要求**：需要的角色和权限\r\n6. **性能考虑**：缓存、索引、异步处理建议\r\n7. **错误处理**：可能出现的错误和应对措施\r\n\r\n确保描述准确完整，便于大模型理解和实现。\n\nFile v2.3.2:references/component-catalog.md\n\n# 前端组件目录参考\r\n\r\n本文档提供前端组件的标准描述格式和常见组件模式，用于技术文档生成时的参考。\r\n\r\n## 组件描述标准格式\r\n\r\n### 1. 基础信息\r\n```markdown\r\n**组件名**: [组件名称]\r\n**位置**: [在页面中的位置]\r\n**功能**: [简要描述组件功能]\r\n```\r\n\r\n### 2. Props接口\r\n```javascript\r\ninterface ComponentProps {\r\n // 数据相关\r\n data?: any; // 组件显示的数据\r\n loading?: boolean; // 加载状态\r\n \r\n // 交互回调\r\n onClick?: () => void; // 点击事件\r\n onChange?: (value) => void; // 值变化事件\r\n onSubmit?: (data) => void; // 提交事件\r\n \r\n // 样式控制\r\n className?: string; // 自定义样式类\r\n style?: React.CSSProperties; // 内联样式\r\n \r\n // 配置选项\r\n options?: any[]; // 下拉选项等配置\r\n disabled?: boolean; // 是否禁用\r\n required?: boolean; // 是否必填\r\n \r\n // 子内容\r\n children?: React.ReactNode;\r\n}\r\n```\r\n\r\n### 3. 状态管理\r\n```javascript\r\ninterface ComponentState {\r\n // 数据状态\r\n selectedItems: any[]; // 选中的项\r\n currentPage: number; // 当前页码\r\n \r\n // UI状态\r\n isOpen: boolean; // 是否展开/打开\r\n isLoading: boolean; // 加载状态\r\n error: string | null; // 错误信息\r\n \r\n // 表单状态\r\n formData: object; // 表单数据\r\n validationErrors: object; // 验证错误\r\n}\r\n```\r\n\r\n### 4. 交互逻辑\r\n```markdown\r\n- **初始化**: 组件挂载时执行的操作\r\n- **用户交互**: 用户操作触发的行为\r\n- **数据变化**: props变化时的响应\r\n- **清理**: 组件卸载时的清理操作\r\n```\r\n\r\n## 常见组件模式\r\n\r\n### 1. 数据展示组件\r\n\r\n#### 表格组件 (DataTable)\r\n```markdown\r\n**组件名**: DataTable\r\n**功能**: 展示结构化数据，支持排序、筛选、分页\r\n\r\n**Props**:\r\n- `columns`: Column[] - 列配置\r\n- `dataSource`: any[] - 数据源\r\n- `pagination`: Pagination - 分页配置\r\n- `rowKey`: string - 行唯一键\r\n- `onRowClick`: (record) => void - 行点击事件\r\n\r\n**交互逻辑**:\r\n1. 表头点击切换排序\r\n2. 筛选器输入实时过滤\r\n3. 分页器切换页面\r\n4. 行选择/取消选择\r\n```\r\n\r\n#### 卡片组件 (Card)\r\n```markdown\r\n**组件名**: Card\r\n**功能**: 信息卡片容器，支持标题、内容、操作区\r\n\r\n**Props**:\r\n- `title`: string | ReactNode - 卡片标题\r\n- `extra`: ReactNode - 额外内容（通常为操作按钮）\r\n- `cover`: ReactNode - 封面图片\r\n- `actions`: ReactNode[] - 底部操作按钮\r\n\r\n**样式特点**:\r\n- 阴影效果增强层次感\r\n- 圆角边框\r\n- 悬停效果（可选）\r\n```\r\n\r\n### 2. 表单组件\r\n\r\n#### 输入框 (Input)\r\n```markdown\r\n**组件名**: Input\r\n**功能**: 文本输入控件\r\n\r\n**Props**:\r\n- `type`: 'text' | 'password' | 'email' | 'number' - 输入类型\r\n- `placeholder`: string - 占位文本\r\n- `value`: string - 当前值\r\n- `onChange`: (e) => void - 值变化事件\r\n- `prefix`: ReactNode - 前缀图标\r\n- `suffix`: ReactNode - 后缀图标\r\n- `allowClear`: boolean - 是否显示清除按钮\r\n\r\n**验证规则**:\r\n- 必填验证\r\n- 格式验证（邮箱、手机号等）\r\n- 长度限制\r\n```\r\n\r\n#### 下拉选择 (Select)\r\n```markdown\r\n**组件名**: Select\r\n**功能**: 下拉选择控件\r\n\r\n**Props**:\r\n- `options`: Option[] - 选项列表\r\n- `value`: string | string[] - 当前值\r\n- `onChange`: (value) => void - 值变化事件\r\n- `mode`: 'single' | 'multiple' - 单选/多选模式\r\n- `placeholder`: string - 占位文本\r\n- `loading`: boolean - 加载状态\r\n\r\n**交互逻辑**:\r\n1. 点击触发下拉菜单\r\n2. 搜索框输入过滤选项\r\n3. 选项点击选中\r\n4. 多选模式下标签展示\r\n```\r\n\r\n### 3. 布局组件\r\n\r\n#### 栅格布局 (Grid)\r\n```markdown\r\n**组件名**: Grid\r\n**功能**: 响应式栅格布局系统\r\n\r\n**Props**:\r\n- `cols`: number - 列数（默认24）\r\n- `gutter`: number | [number, number] - 栅格间距\r\n- `span`: number - 栅格占位格数\r\n- `offset`: number - 栅格左侧偏移格数\r\n\r\n**响应式规则**:\r\n- xs (<576px): 1-4列\r\n- sm (≥576px): 1-8列 \r\n- md (≥768px): 1-12列\r\n- lg (≥992px): 1-16列\r\n- xl (≥1200px): 1-24列\r\n```\r\n\r\n#### 布局容器 (Layout)\r\n```markdown\r\n**组件名**: Layout\r\n**功能**: 页面整体布局容器\r\n\r\n**结构**:\r\n- `Header`: 顶部导航\r\n- `Sider`: 侧边栏\r\n- `Content`: 主内容区\r\n- `Footer`: 底部区域\r\n\r\n**Props**:\r\n- `collapsed`: boolean - 侧边栏是否折叠\r\n- `collapsedWidth`: number - 折叠时宽度\r\n- `width`: number - 侧边栏宽度\r\n```\r\n\r\n### 4. 反馈组件\r\n\r\n#### 模态框 (Modal)\r\n```markdown\r\n**组件名**: Modal\r\n**功能**: 模态对话框\r\n\r\n**Props**:\r\n- `visible`: boolean - 是否显示\r\n- `title`: string | ReactNode - 标题\r\n- `onOk`: () => void - 确定按钮点击\r\n- `onCancel`: () => void - 取消按钮点击\r\n- `footer`: ReactNode - 自定义底部\r\n- `maskClosable`: boolean - 点击遮罩是否关闭\r\n\r\n**交互逻辑**:\r\n1. 打开时禁止背景滚动\r\n2. 键盘ESC键关闭\r\n3. 确定按钮提交表单\r\n4. 关闭时执行清理\r\n```\r\n\r\n#### 消息提示 (Message)\r\n```markdown\r\n**组件名**: Message\r\n**功能**: 全局消息提示\r\n\r\n**方法**:\r\n- `success(content, duration)`: 成功提示\r\n- `error(content, duration)`: 错误提示\r\n- `warning(content, duration)`: 警告提示\r\n- `info(content, duration)`: 信息提示\r\n- `loading(content, duration)`: 加载提示\r\n\r\n**位置选项**:\r\n- `top`: 顶部居中\r\n- `topLeft`: 左上角\r\n- `topRight`: 右上角\r\n- `bottom`: 底部居中\r\n- `bottomLeft`: 左下角\r\n- `bottomRight`: 右下角\r\n```\r\n\r\n## 组件交互模式\r\n\r\n### 1. 数据获取模式\r\n```javascript\r\n// 组件内数据获取\r\nuseEffect(() => {\r\n const fetchData = async () => {\r\n setLoading(true);\r\n try {\r\n const data = await api.getData(params);\r\n setData(data);\r\n } catch (error) {\r\n setError(error.message);\r\n } finally {\r\n setLoading(false);\r\n }\r\n };\r\n fetchData();\r\n}, [params]);\r\n```\r\n\r\n### 2. 表单处理模式\r\n```javascript\r\n// 受控表单组件\r\nconst [formData, setFormData] = useState(initialData);\r\n\r\nconst handleChange = (field, value) => {\r\n setFormData(prev => ({\r\n ...prev,\r\n [field]: value\r\n }));\r\n};\r\n\r\nconst handleSubmit = async () => {\r\n // 验证表单\r\n const errors = validateForm(formData);\r\n if (Object.keys(errors).length > 0) {\r\n setValidationErrors(errors);\r\n return;\r\n }\r\n \r\n // 提交数据\r\n await api.submit(formData);\r\n};\r\n```\r\n\r\n### 3. 事件处理模式\r\n```javascript\r\n// 防抖处理\r\nconst handleSearch = useDebounce((keyword) => {\r\n searchApi(keyword);\r\n}, 300);\r\n\r\n// 节流处理 \r\nconst handleScroll = useThrottle(() => {\r\n checkScrollPosition();\r\n}, 100);\r\n\r\n// 事件委托\r\nconst handleListClick = (e) => {\r\n if (e.target.matches('.item')) {\r\n const id = e.target.dataset.id;\r\n selectItem(id);\r\n }\r\n};\r\n```\r\n\r\n## 样式规范参考\r\n\r\n### 1. 命名规范\r\n- BEM命名法：`block__element--modifier`\r\n- 示例：`user-card__avatar--large`\r\n\r\n### 2. 颜色系统\r\n```css\r\n/* 主色调 */\r\n--primary-color: #1890ff;\r\n--primary-hover: #40a9ff;\r\n--primary-active: #096dd9;\r\n\r\n/* 功能色 */\r\n--success-color: #52c41a;\r\n--warning-color: #faad14;\r\n--error-color: #f5222d;\r\n--info-color: #1890ff;\r\n\r\n/* 中性色 */\r\n--text-color: rgba(0, 0, 0, 0.85);\r\n--text-color-secondary: rgba(0, 0, 0, 0.45);\r\n--border-color: #d9d9d9;\r\n--background-color: #f0f2f5;\r\n```\r\n\r\n### 3. 间距系统\r\n```css\r\n/* 基于8px基数 */\r\n--spacing-xs: 4px; /* 0.25rem */\r\n--spacing-sm: 8px; /* 0.5rem */\r\n--spacing-md: 16px; /* 1rem */\r\n--spacing-lg: 24px; /* 1.5rem */\r\n--spacing-xl: 32px; /* 2rem */\r\n```\r\n\r\n### 4. 动画曲线\r\n```css\r\n--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);\r\n--ease-out: cubic-bezier(0, 0, 0.2, 1);\r\n--ease-in: cubic-bezier(0.4, 0, 1, 1);\r\n```\r\n\r\n## 性能优化提示\r\n\r\n### 1. 减少重渲染\r\n- 使用 `React.memo()` 包裹纯展示组件\r\n- 使用 `useMemo()` 缓存计算结果\r\n- 使用 `useCallback()` 缓存函数引用\r\n\r\n### 2. 代码分割\r\n```javascript\r\n// 动态导入组件\r\nconst HeavyComponent = React.lazy(() => import('./HeavyComponent'));\r\n\r\n// 使用时包裹Suspense\r\n}>\r\n \r\n\r\n```\r\n\r\n### 3. 图片优化\r\n- 使用 WebP 格式（兼容性考虑提供回退）\r\n- 实现懒加载\r\n- 使用响应式图片（srcset）\r\n- 预加载关键图片\r\n\r\n## 可访问性要求\r\n\r\n### 1. 键盘导航\r\n- 所有交互元素支持键盘访问\r\n- 合理的 Tab 顺序\r\n- 快捷键支持\r\n\r\n### 2. 屏幕阅读器\r\n- 语义化 HTML 标签\r\n- ARIA 属性正确使用\r\n- 焦点管理合理\r\n\r\n### 3. 颜色对比度\r\n- 文本与背景对比度 ≥ 4.5:1\r\n- 大文本对比度 ≥ 3:1\r\n- 非文本元素对比度 ≥ 3:1\r\n\r\n---\r\n\r\n## 使用说明\r\n\r\n在技术文档中描述组件时，应参考以下结构：\r\n\r\n1. **组件基本信息**：名称、位置、功能\r\n2. **Props接口**：所有可配置属性\r\n3. **状态管理**：组件内部状态\r\n4. **交互逻辑**：用户操作响应\r\n5. **样式特点**：外观和动画\r\n6. **性能考虑**：优化建议\r\n7. **可访问性**：无障碍支持\r\n\r\n确保描述准确、完整，便于大模型理解并生成对应代码。\n\nFile v2.3.2:references/template-spec.md\n\n# 产品原型技术分析文档\r\n\r\n## 文档信息\r\n- **原型来源**: [URL/图片/XMind文件路径]\r\n- **分析时间**: [YYYY-MM-DD HH:MM:SS]\r\n- **文档版本**: v1.0\r\n- **技能版本**: bie-zheng-luan-prototype v1.0.0\r\n\r\n## 1. 系统概览\r\n\r\n### 1.1 产品简介\r\n[用1-2句话描述产品的核心功能和目标用户]\r\n\r\n### 1.2 技术栈建议\r\n- **前端**: [React/Vue/Angular + TypeScript]\r\n- **UI框架**: [Ant Design/Element UI/Tailwind CSS]\r\n- **后端**: [Node.js/.NET/Spring Boot/Go]\r\n- **数据库**: [MySQL/PostgreSQL/MongoDB]\r\n- **部署**: [Docker/Kubernetes]\r\n\r\n### 1.3 核心业务流程\r\n```\r\n[用流程图或文字描述主要业务流程]\r\n```\r\n\r\n## 2. 页面结构分析\r\n\r\n### 2.1 整体布局\r\n| 区域 | 位置 | 包含内容 | 宽度占比 | 固定/滚动 |\r\n|------|------|----------|----------|-----------|\r\n| 头部 | 顶部 | 品牌Logo、用户信息、通知中心 | 100% | 固定 |\r\n| 侧边栏 | 左侧 | 导航菜单、快捷操作 | 15-20% | 固定 |\r\n| 主内容区 | 中间 | 功能模块、数据展示 | 80-85% | 滚动 |\r\n| 底部 | 底部 | 版权信息、备案号 | 100% | 固定 |\r\n\r\n### 2.2 导航菜单结构\r\n```yaml\r\n一级菜单:\r\n - 菜单1:\r\n icon: [图标名称]\r\n path: /menu1\r\n 二级菜单:\r\n - 子菜单1.1: /menu1/sub1\r\n - 子菜单1.2: /menu1/sub2\r\n - 菜单2:\r\n icon: [图标名称]\r\n path: /menu2\r\n 无子菜单\r\n```\r\n\r\n### 2.3 功能模块清单\r\n| 模块名称 | 所在页面 | 位置坐标 | 主要功能 | 数据来源 |\r\n|----------|----------|----------|----------|----------|\r\n| [模块A] | [/dashboard] | 主内容区左上 | 数据概览卡片 | 后端API |\r\n| [模块B] | [/dashboard] | 主内容区右上 | 统计图表 | 后端API |\r\n| [模块C] | [/users] | 主内容区全宽 | 用户列表表格 | 后端API |\r\n\r\n## 3. 前端实现方案\r\n\r\n### 3.1 页面路由规划\r\n```javascript\r\nconst routes = [\r\n {\r\n path: '/',\r\n component: Layout,\r\n children: [\r\n { path: 'dashboard', component: Dashboard },\r\n { path: 'users', component: UserList },\r\n { path: 'users/:id', component: UserDetail },\r\n { path: 'settings', component: Settings },\r\n ]\r\n }\r\n];\r\n```\r\n\r\n### 3.2 组件清单\r\n\r\n#### 3.2.1 布局组件\r\n**组件名**: `MainLayout`\r\n- **位置**: 根组件\r\n- **Props**: \r\n - `children`: React.ReactNode (页面内容)\r\n - `title`: string (页面标题)\r\n- **状态**: \r\n - `collapsed`: boolean (侧边栏是否折叠)\r\n - `userInfo`: object (用户信息)\r\n- **交互逻辑**:\r\n - 侧边栏折叠/展开切换\r\n - 用户头像点击显示下拉菜单\r\n - 通知图标点击显示通知列表\r\n\r\n#### 3.2.2 业务组件\r\n**组件名**: `UserTable`\r\n- **位置**: `/users` 页面\r\n- **Props**:\r\n - `dataSource`: User[] (用户数据)\r\n - `loading`: boolean (加载状态)\r\n - `onEdit`: (user: User) => void (编辑回调)\r\n - `onDelete`: (id: string) => void (删除回调)\r\n- **状态**:\r\n - `selectedRows`: User[] (选中的行)\r\n - `pagination`: { current: number, pageSize: number }\r\n- **交互逻辑**:\r\n - 表格行点击选中/取消\r\n - 分页器切换页面\r\n - 搜索框输入实时过滤\r\n - 批量操作按钮点击\r\n\r\n### 3.3 样式规范\r\n```css\r\n/* 设计令牌 */\r\n:root {\r\n --primary-color: #1890ff;\r\n --success-color: #52c41a;\r\n --warning-color: #faad14;\r\n --error-color: #f5222d;\r\n \r\n --font-size-base: 14px;\r\n --border-radius-base: 4px;\r\n \r\n --spacing-xs: 4px;\r\n --spacing-sm: 8px;\r\n --spacing-md: 16px;\r\n --spacing-lg: 24px;\r\n}\r\n\r\n/* 组件样式示例 */\r\n.user-table {\r\n background: white;\r\n border-radius: var(--border-radius-base);\r\n box-shadow: 0 2px 8px rgba(0,0,0,0.1);\r\n padding: var(--spacing-md);\r\n}\r\n```\r\n\r\n### 3.4 交互细节\r\n\r\n#### 按钮交互示例\r\n**按钮**: \"新建用户\"\r\n- **位置**: 用户列表页面右上角\r\n- **样式**: 主按钮（蓝色背景，白色文字）\r\n- **点击行为**:\r\n 1. 打开用户表单弹窗\r\n 2. 重置表单为初始状态\r\n 3. 设置表单模式为\"创建\"\r\n- **成功反馈**: 显示\"创建成功\"提示，刷新用户列表\r\n- **失败反馈**: 显示错误信息，保持表单打开\r\n\r\n#### 表单交互示例\r\n**表单**: 用户信息表单\r\n- **提交行为**:\r\n 1. 前端验证必填字段\r\n 2. 显示加载状态\r\n 3. 调用后端API\r\n 4. 根据响应显示结果\r\n- **验证规则**:\r\n - 用户名：必填，2-20字符\r\n - 邮箱：必填，邮箱格式\r\n - 手机号：可选，11位数字\r\n\r\n## 4. 后端实现方案\r\n\r\n### 4.1 API接口设计\r\n\r\n#### 4.1.1 用户管理接口\r\n**接口名称**: 获取用户列表\r\n- **HTTP方法**: GET\r\n- **URL**: `/api/users`\r\n- **认证**: 需要Bearer Token\r\n- **权限**: 管理员权限\r\n\r\n**请求参数**:\r\n```json\r\n{\r\n \"page\": 1, // 页码（必填，默认1）\r\n \"size\": 10, // 每页数量（必填，默认10）\r\n \"keyword\": \"\", // 搜索关键词（可选）\r\n \"status\": \"active\" // 状态过滤（可选：active/inactive）\r\n}\r\n```\r\n\r\n**成功响应** (HTTP 200):\r\n```json\r\n{\r\n \"code\": 200,\r\n \"message\": \"success\",\r\n \"data\": {\r\n \"items\": [\r\n {\r\n \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\r\n \"username\": \"zhangsan\",\r\n \"email\": \"zhangsan@example.com\",\r\n \"phone\": \"13800138000\",\r\n \"status\": \"active\",\r\n \"createdAt\": \"2026-04-21T10:00:00Z\",\r\n \"updatedAt\": \"2026-04-21T10:00:00Z\"\r\n }\r\n ],\r\n \"total\": 100,\r\n \"page\": 1,\r\n \"size\": 10,\r\n \"pages\": 10\r\n }\r\n}\r\n```\r\n\r\n**错误响应** (HTTP 400):\r\n```json\r\n{\r\n \"code\": 400,\r\n \"message\": \"参数验证失败\",\r\n \"errors\": [\r\n {\r\n \"field\": \"page\",\r\n \"message\": \"页码必须大于0\"\r\n }\r\n ]\r\n}\r\n```\r\n\r\n**业务逻辑伪代码**:\r\n```python\r\ndef get_user_list(request):\r\n # 1. 验证用户权限\r\n if not request.user.has_permission('user:read'):\r\n return unauthorized_response()\r\n \r\n # 2. 解析和验证参数\r\n page = request.query.get('page', 1)\r\n size = request.query.get('size', 10)\r\n keyword = request.query.get('keyword', '')\r\n status = request.query.get('status')\r\n \r\n if page < 1 or size < 1 or size > 100:\r\n return bad_request('分页参数无效')\r\n \r\n # 3. 构建查询条件\r\n query = User.objects.filter(is_deleted=False)\r\n \r\n if keyword:\r\n query = query.filter(\r\n Q(username__icontains=keyword) |\r\n Q(email__icontains=keyword) |\r\n Q(phone__icontains=keyword)\r\n )\r\n \r\n if status in ['active', 'inactive']:\r\n query = query.filter(status=status)\r\n \r\n # 4. 执行分页查询\r\n total = query.count()\r\n items = query.order_by('-created_at') \\\r\n .offset((page - 1) * size) \\\r\n .limit(size) \\\r\n .all()\r\n \r\n # 5. 格式化返回数据\r\n return success_response({\r\n 'items': [user.to_dict() for user in items],\r\n 'total': total,\r\n 'page': page,\r\n 'size': size,\r\n 'pages': math.ceil(total / size)\r\n })\r\n```\r\n\r\n#### 4.1.2 其他接口\r\n[按照相同格式描述其他接口]\r\n\r\n### 4.2 服务层设计\r\n\r\n#### 用户服务 (UserService)\r\n```java\r\npublic class UserService {\r\n /**\r\n * 创建用户\r\n */\r\n public User createUser(CreateUserRequest request) {\r\n // 1. 验证用户名唯一性\r\n // 2. 密码加密\r\n // 3. 保存到数据库\r\n // 4. 发送欢迎邮件\r\n // 5. 记录操作日志\r\n }\r\n \r\n /**\r\n * 更新用户\r\n */\r\n public User updateUser(String userId, UpdateUserRequest request) {\r\n // 1. 查询用户是否存在\r\n // 2. 验证更新权限\r\n // 3. 更新用户信息\r\n // 4. 清除用户缓存\r\n }\r\n}\r\n```\r\n\r\n### 4.3 第三方服务集成\r\n- **短信服务**: 阿里云短信（用户注册验证）\r\n- **邮件服务**: SendGrid（通知邮件）\r\n- **文件存储**: AWS S3/MinIO（用户上传文件）\r\n- **消息队列**: RabbitMQ/Kafka（异步任务）\r\n\r\n## 5. 数据库设计\r\n\r\n### 5.1 数据库表清单\r\n\r\n#### 表名: `users` (用户表)\r\n| 字段名 | 数据类型 | 长度 | 必填 | 默认值 | 说明 |\r\n|--------|----------|------|------|--------|------|\r\n| id | varchar | 36 | ✓ | UUID | 主键 |\r\n| username | varchar | 50 | ✓ | | 用户名，唯一 |\r\n| email | varchar | 100 | ✓ | | 邮箱，唯一 |\r\n| phone | varchar | 20 | | | 手机号 |\r\n| password_hash | varchar | 255 | ✓ | | 密码哈希 |\r\n| status | varchar | 20 | ✓ | 'active' | 状态：active/inactive |\r\n| avatar_url | varchar | 255 | | | 头像URL |\r\n| last_login_at | datetime | | | NULL | 最后登录时间 |\r\n| created_at | datetime | | ✓ | CURRENT_TIMESTAMP | 创建时间 |\r\n| updated_at | datetime | | ✓ | CURRENT_TIMESTAMP | 更新时间 |\r\n| is_deleted | tinyint | 1 | ✓ | 0 | 软删除标记 |\r\n\r\n**索引**:\r\n- PRIMARY KEY (`id`)\r\n- UNIQUE KEY `uk_username` (`username`)\r\n- UNIQUE KEY `uk_email` (`email`)\r\n- INDEX `idx_status` (`status`)\r\n- INDEX `idx_created_at` (`created_at`)\r\n\r\n#### 表名: `roles` (角色表)\r\n| 字段名 | 数据类型 | 长度 | 必填 | 默认值 | 说明 |\r\n|--------|----------|------|------|--------|------|\r\n| id | varchar | 36 | ✓ | UUID | 主键 |\r\n| name | varchar | 50 | ✓ | | 角色名称 |\r\n| description | varchar | 200 | | | 角色描述 |\r\n| permissions | json | | ✓ | '[]' | 权限列表 |\r\n| created_at | datetime | | ✓ | CURRENT_TIMESTAMP | 创建时间 |\r\n\r\n#### 表名: `user_roles` (用户角色关联表)\r\n| 字段名 | 数据类型 | 长度 | 必填 | 默认值 | 说明 |\r\n|--------|----------|------|------|--------|------|\r\n| id | varchar | 36 | ✓ | UUID | 主键 |\r\n| user_id | varchar | 36 | ✓ | | 用户ID，外键 |\r\n| role_id | varchar | 36 | ✓ | | 角色ID，外键 |\r\n| created_at | datetime | | ✓ | CURRENT_TIMESTAMP | 创建时间 |\r\n\r\n**外键约束**:\r\n- FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON DELETE CASCADE\r\n- FOREIGN KEY (`role_id`) REFERENCES `roles`(`id`) ON DELETE CASCADE\r\n\r\n### 5.2 实体关系图\r\n```mermaid\r\nerDiagram\r\n users ||--o{ user_roles : has\r\n roles ||--o{ user_roles : assigned\r\n users {\r\n varchar id PK\r\n varchar username UK\r\n varchar email UK\r\n varchar phone\r\n varchar password_hash\r\n varchar status\r\n datetime created_at\r\n datetime updated_at\r\n }\r\n roles {\r\n varchar id PK\r\n varchar name\r\n varchar description\r\n json permissions\r\n datetime created_at\r\n }\r\n user_roles {\r\n varchar id PK\r\n varchar user_id FK\r\n varchar role_id FK\r\n datetime created_at\r\n }\r\n```\r\n\r\n## 6. 部署与运维\r\n\r\n### 6.1 环境配置\r\n```yaml\r\n# docker-compose.yml\r\nversion: '3.8'\r\nservices:\r\n backend:\r\n build: ./backend\r\n ports:\r\n - \"8080:8080\"\r\n environment:\r\n - DATABASE_URL=postgresql://user:pass@db:5432/app\r\n - REDIS_URL=redis://redis:6379\r\n depends_on:\r\n - db\r\n - redis\r\n \r\n frontend:\r\n build: ./frontend\r\n ports:\r\n - \"3000:3000\"\r\n \r\n db:\r\n image: postgres:15\r\n environment:\r\n - POSTGRES_USER=user\r\n - POSTGRES_PASSWORD=pass\r\n - POSTGRES_DB=app\r\n \r\n redis:\r\n image: redis:7-alpine\r\n```\r\n\r\n### 6.2 监控指标\r\n- API响应时间（P95 < 500ms）\r\n- 错误率（< 0.1%）\r\n- 数据库连接池使用率（< 80%）\r\n- 内存使用率（< 70%）\r\n\r\n### 6.3 日志规范\r\n```json\r\n{\r\n \"timestamp\": \"2026-04-21T10:00:00Z\",\r\n \"level\": \"INFO\",\r\n \"service\": \"user-service\",\r\n \"trace_id\": \"abc123\",\r\n \"user_id\": \"user123\",\r\n \"operation\": \"user.create\",\r\n \"duration_ms\": 150,\r\n \"status\": \"success\",\r\n \"message\": \"用户创建成功\"\r\n}\r\n```\r\n\r\n## 7. 测试要点\r\n\r\n### 7.1 单元测试\r\n- 用户服务逻辑测试\r\n- 权限验证测试\r\n- 数据验证测试\r\n\r\n### 7.2 集成测试\r\n- API接口端到端测试\r\n- 数据库操作测试\r\n- 第三方服务集成测试\r\n\r\n### 7.3 性能测试\r\n- 并发用户创建测试\r\n- 大数据量查询测试\r\n- API压力测试\r\n\r\n## 8. 开发注意事项\r\n\r\n### 8.1 安全性\r\n- 所有用户输入必须验证和过滤\r\n- 密码使用bcrypt加密存储\r\n- API接口需要身份验证和授权\r\n- 敏感操作需要二次确认\r\n\r\n### 8.2 性能优化\r\n- 数据库查询使用索引优化\r\n- 频繁访问的数据使用缓存\r\n- 大文件上传使用分片上传\r\n- 列表接口支持分页查询\r\n\r\n### 8.3 可维护性\r\n- 代码遵循一致的命名规范\r\n- 重要业务逻辑添加注释\r\n- 配置项集中管理\r\n- 错误处理统一规范\r\n\r\n---\r\n\r\n## 文档生成信息\r\n- **生成工具**: bie-zheng-luan-prototype v1.0.0\r\n- **生成时间**: [YYYY-MM-DD HH:MM:SS]\r\n- **置信度评估**: [高/中/低] (基于原型分析完整性)\r\n- **建议复核**: [需要/不需要] 与产品经理确认业务逻辑\r\n\r\n> **注意**: 本文档为技术分析结果，实际开发前应与产品经理确认需求细节。\n\nFile v2.3.2:assets/sample-output/sample-user-management.md\n\n# 产品原型技术分析文档\r\n\r\n## 文档信息\r\n- **原型来源**: Figma URL (https://www.figma.com/file/example/user-management)\r\n- **分析时间**: 2026-04-21 18:30:00\r\n- **文档版本**: v1.0\r\n- **技能版本**: bie-zheng-luan-prototype v1.0.0\r\n\r\n## 1. 系统概览\r\n\r\n### 1.1 产品简介\r\n用户管理系统，用于管理平台用户信息，支持用户的增删改查、角色分配、状态管理等功能。\r\n\r\n### 1.2 技术栈建议\r\n- **前端**: React 18 + TypeScript\r\n- **UI框架**: Ant Design 5.x\r\n- **状态管理**: Redux Toolkit + React Query\r\n- **后端**: Node.js + Express 或 .NET Core 6\r\n- **数据库**: PostgreSQL 15\r\n- **认证**: JWT + Refresh Token\r\n- **部署**: Docker + Nginx\r\n\r\n### 1.3 核心业务流程\r\n```\r\n用户访问 → 登录验证 → 查看用户列表 → 搜索/筛选用户 → 查看用户详情 → \r\n编辑用户信息 → 保存更改 → 更新列表显示\r\n```\r\n\r\n## 2. 页面结构分析\r\n\r\n### 2.1 整体布局\r\n| 区域 | 位置 | 包含内容 | 宽度占比 | 固定/滚动 |\r\n|------|------|----------|----------|-----------|\r\n| 头部 | 顶部 | Logo、用户头像、通知图标、退出按钮 | 100% | 固定 |\r\n| 侧边栏 | 左侧 | 系统菜单（用户管理、角色管理、日志管理） | 240px | 固定 |\r\n| 主内容区 | 中间 | 用户列表表格、搜索栏、操作按钮 | 剩余宽度 | 滚动 |\r\n| 底部 | 底部 | 版权信息、备案号 | 100% | 固定 |\r\n\r\n### 2.2 导航菜单结构\r\n```yaml\r\n一级菜单:\r\n - 仪表盘:\r\n icon: Dashboard\r\n path: /dashboard\r\n 无子菜单\r\n - 用户管理:\r\n icon: User\r\n path: /users\r\n 二级菜单:\r\n - 用户列表: /users\r\n - 角色管理: /users/roles\r\n - 系统设置:\r\n icon: Setting\r\n path: /settings\r\n 二级菜单:\r\n - 日志管理: /settings/logs\r\n - 参数配置: /settings/config\r\n```\r\n\r\n### 2.3 功能模块清单\r\n| 模块名称 | 所在页面 | 位置坐标 | 主要功能 | 数据来源 |\r\n|----------|----------|----------|----------|----------|\r\n| 用户搜索栏 | /users | 顶部左侧 | 按用户名/邮箱搜索用户 | 前端筛选 |\r\n| 状态筛选器 | /users | 顶部中部 | 按用户状态筛选 | 前端筛选 |\r\n| 操作按钮组 | /users | 顶部右侧 | 新建、导入、导出按钮 | 前端交互 |\r\n| 用户列表表格 | /users | 中部全宽 | 展示用户信息表格 | 后端API |\r\n| 分页控件 | /users | 底部居中 | 表格分页导航 | 后端API |\r\n\r\n## 3. 前端实现方案\r\n\r\n### 3.1 页面路由规划\r\n```typescript\r\n// src/routes/index.tsx\r\nconst routes = [\r\n {\r\n path: '/',\r\n element: ,\r\n children: [\r\n { index: true, element: },\r\n { path: 'dashboard', element: },\r\n {\r\n path: 'users',\r\n children: [\r\n { index: true, element: },\r\n { path: ':id', element: },\r\n { path: ':id/edit', element: },\r\n { path: 'roles', element: },\r\n ],\r\n },\r\n {\r\n path: 'settings',\r\n children: [\r\n { path: 'logs', element: },\r\n { path: 'config', element: },\r\n ],\r\n },\r\n ],\r\n },\r\n { path: '/login', element: },\r\n { path: '*', element: },\r\n];\r\n```\r\n\r\n### 3.2 组件清单\r\n\r\n#### 3.2.1 用户列表页面组件\r\n**组件名**: `UserListPage`\r\n- **位置**: `/users` 页面容器\r\n- **Props**: 无\r\n- **状态**:\r\n - `searchParams`: object (搜索参数)\r\n - `selectedRows`: string[] (选中的用户ID)\r\n- **交互逻辑**:\r\n - 挂载时加载用户列表\r\n - 搜索参数变化时重新加载\r\n - 批量操作按钮状态管理\r\n\r\n**组件名**: `UserSearchBar`\r\n- **位置**: `UserListPage` 顶部\r\n- **Props**:\r\n - `onSearch`: (params) => void (搜索回调)\r\n - `loading`: boolean (加载状态)\r\n- **状态**:\r\n - `keyword`: string (搜索关键词)\r\n - `status`: string (筛选状态)\r\n- **交互逻辑**:\r\n - 输入框输入实时搜索（防抖500ms）\r\n - 状态筛选器选择立即触发搜索\r\n - 重置按钮清空搜索条件\r\n\r\n**组件名**: `UserTable`\r\n- **位置**: `UserListPage` 中部\r\n- **Props**:\r\n - `data`: User[] (用户数据)\r\n - `loading`: boolean (加载状态)\r\n - `pagination`: PaginationProps (分页信息)\r\n - `onChange`: (pagination, filters, sorter) => void (表格变化回调)\r\n - `rowSelection`: object (行选择配置)\r\n- **状态**: 无（受控组件）\r\n- **交互逻辑**:\r\n - 行点击跳转到用户详情\r\n - 操作列按钮点击触发相应操作\r\n - 分页变化触发数据重新加载\r\n - 排序变化触发数据重新排序\r\n\r\n#### 3.2.2 用户表单组件\r\n**组件名**: `UserForm`\r\n- **位置**: 用户创建/编辑模态框\r\n- **Props**:\r\n - `initialValues`: User (初始值)\r\n - `onSubmit`: (values) => Promise (提交回调)\r\n - `onCancel`: () => void (取消回调)\r\n- **状态**:\r\n - `formData`: UserFormData (表单数据)\r\n - `submitting`: boolean (提交中状态)\r\n - `errors`: ValidationError[] (验证错误)\r\n- **交互逻辑**:\r\n - 表单字段变化实时验证\r\n - 邮箱输入后检查唯一性\r\n - 提交时显示加载状态\r\n - 成功/失败显示相应提示\r\n\r\n### 3.3 样式规范\r\n```css\r\n/* 用户列表页面样式 */\r\n.user-list-page {\r\n padding: 24px;\r\n background: #f5f5f5;\r\n min-height: calc(100vh - 64px); /* 减去头部高度 */\r\n}\r\n\r\n.user-search-bar {\r\n background: white;\r\n padding: 16px 24px;\r\n margin-bottom: 16px;\r\n border-radius: 8px;\r\n box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06);\r\n display: flex;\r\n gap: 16px;\r\n align-items: center;\r\n}\r\n\r\n.user-table-container {\r\n background: white;\r\n padding: 24px;\r\n border-radius: 8px;\r\n box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06);\r\n}\r\n\r\n/* 用户状态标签样式 */\r\n.status-tag {\r\n padding: 2px 8px;\r\n border-radius: 12px;\r\n font-size: 12px;\r\n font-weight: 500;\r\n}\r\n\r\n.status-active {\r\n background: #f6ffed;\r\n border: 1px solid #b7eb8f;\r\n color: #52c41a;\r\n}\r\n\r\n.status-inactive {\r\n background: #fff2e8;\r\n border: 1px solid #ffd591;\r\n color: #fa8c16;\r\n}\r\n\r\n.status-locked {\r\n background: #fff1f0;\r\n border: 1px solid #ffa39e;\r\n color: #f5222d;\r\n}\r\n```\r\n\r\n### 3.4 交互细节\r\n\r\n#### 按钮交互示例\r\n**按钮**: \"新建用户\"（主按钮）\r\n- **位置**: 用户列表页面右上角\r\n- **样式**: 蓝色背景，白色文字，右侧有加号图标\r\n- **点击行为**:\r\n 1. 打开用户创建模态框\r\n 2. 重置表单为初始状态\r\n 3. 设置表单模式为\"create\"\r\n- **成功反馈**: 显示\"用户创建成功\"提示，刷新用户列表\r\n- **失败反馈**: 显示错误信息，保持表单打开\r\n\r\n**按钮**: \"编辑\"（行操作按钮）\r\n- **位置**: 用户表格每行操作列\r\n- **样式**: 链接样式，蓝色文字\r\n- **点击行为**:\r\n 1. 获取当前行用户数据\r\n 2. 打开用户编辑模态框\r\n 3. 表单预填充用户信息\r\n- **成功反馈**: 显示\"用户信息已更新\"提示，更新当前行数据\r\n- **失败反馈**: 显示错误信息，保持表单打开\r\n\r\n**按钮**: \"删除\"（行操作按钮）\r\n- **位置**: 用户表格每行操作列\r\n- **样式**: 链接样式，红色文字\r\n- **点击行为**:\r\n 1. 显示确认对话框（\"确定删除该用户吗？\"）\r\n 2. 用户确认后调用删除API\r\n 3. 删除成功后从表格中移除该行\r\n- **确认对话框**: 二次确认，防止误操作\r\n- **批量删除**: 支持多选后批量删除\r\n\r\n#### 搜索交互示例\r\n**搜索框**: \"请输入用户名或邮箱\"\r\n- **位置**: 搜索栏左侧\r\n- **行为**: \r\n - 输入时实时搜索（防抖500ms）\r\n - 清空按钮一键清除\r\n - 支持键盘Enter键触发搜索\r\n- **搜索逻辑**: \r\n - 后端支持模糊搜索\r\n - 前端高亮显示匹配关键词\r\n\r\n**状态筛选器**: 下拉选择\r\n- **选项**: 全部、活跃、未激活、已锁定\r\n- **行为**: \r\n - 选择后立即触发筛选\r\n - 多选支持（待定）\r\n- **URL同步**: 筛选状态同步到URL查询参数\r\n\r\n## 4. 后端实现方案\r\n\r\n### 4.1 API接口设计\r\n\r\n#### 4.1.1 获取用户列表\r\n**接口名称**: 获取用户列表\r\n- **HTTP方法**: GET\r\n- **URL**: `/api/v1/users`\r\n- **认证**: 需要Bearer Token\r\n- **权限**: `user:read` 或更高\r\n\r\n**请求参数**:\r\n| 参数名 | 位置 | 类型 | 必填 | 说明 | 示例 |\r\n|--------|------|------|------|------|------|\r\n| page | query | integer | 否 | 页码，从1开始 | 1 |\r\n| size | query | integer | 否 | 每页数量，1-100 | 10 |\r\n| keyword | query | string | 否 | 搜索关键词（用户名/邮箱） | \"john\" |\r\n| status | query | string | 否 | 状态过滤（active/inactive/locked） | \"active\" |\r\n| role | query | string | 否 | 角色过滤 | \"admin\" |\r\n| sort | query | string | 否 | 排序字段（created_at:desc） | \"username:asc\" |\r\n\r\n**成功响应** (HTTP 200):\r\n```json\r\n{\r\n \"code\": 200,\r\n \"message\": \"success\",\r\n \"data\": {\r\n \"items\": [\r\n {\r\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\r\n \"username\": \"zhangsan\",\r\n \"email\": \"zhangsan@example.com\",\r\n \"phone\": \"13800138000\",\r\n \"avatar\": \"https://example.com/avatar.jpg\",\r\n \"status\": \"active\",\r\n \"role\": \"user\",\r\n \"last_login_at\": \"2026-04-21T10:00:00Z\",\r\n \"created_at\": \"2026-04-20T10:00:00Z\",\r\n \"updated_at\": \"2026-04-20T10:00:00Z\"\r\n }\r\n ],\r\n \"total\": 100,\r\n \"page\": 1,\r\n \"size\": 10,\r\n \"pages\": 10\r\n }\r\n}\r\n```\r\n\r\n**业务逻辑伪代码**:\r\n```python\r\ndef get_user_list(request):\r\n \"\"\"\r\n 获取用户列表\r\n \r\n 业务规则：\r\n 1. 仅管理员可以查看所有用户\r\n 2. 普通用户只能查看自己\r\n 3. 支持按状态、角色、关键词筛选\r\n 4. 支持分页和排序\r\n 5. 敏感字段脱敏处理\r\n \"\"\"\r\n \r\n # 1. 验证用户权限\r\n current_user = get_current_user(request)\r\n if not current_user.has_permission('user:read'):\r\n return unauthorized_response('权限不足')\r\n \r\n # 2. 解析查询参数\r\n query_params = parse_query_params(request)\r\n page = query_params.get('page', 1)\r\n size = min(query_params.get('size', 10), 100) # 限制每页最多100条\r\n keyword = query_params.get('keyword', '').strip()\r\n status = query_params.get('status')\r\n role = query_params.get('role')\r\n sort_field, sort_order = parse_sort_param(query_params.get('sort', 'created_at:desc'))\r\n \r\n # 3. 构建查询基础（根据权限限制数据范围）\r\n if current_user.is_admin:\r\n query = User.query.filter_by(is_deleted=False)\r\n else:\r\n # 普通用户只能查看自己的信息\r\n query = User.query.filter_by(id=current_user.id, is_deleted=False)\r\n \r\n # 4. 应用筛选条件\r\n if keyword:\r\n # 支持用户名、邮箱、手机号模糊搜索\r\n search_pattern = f'%{keyword}%'\r\n query = query.filter(\r\n (User.username.ilike(search_pattern)) |\r\n (User.email.ilike(search_pattern)) |\r\n (User.phone.ilike(search_pattern))\r\n )\r\n \r\n if status in ['active', 'inactive', 'locked']:\r\n query = query.filter_by(status=status)\r\n \r\n if role:\r\n query = query.filter_by(role=role)\r\n \r\n # 5. 应用排序\r\n if sort_field in ['username', 'email', 'created_at', 'updated_at', 'last_login_at']:\r\n if sort_order == 'asc':\r\n query = query.order_by(getattr(User, sort_field).asc())\r\n else:\r\n query = query.order_by(getattr(User, sort_field).desc())\r\n else:\r\n # 默认按创建时间倒序\r\n query = query.order_by(User.created_at.desc())\r\n \r\n # 6. 执行分页查询\r\n total_count = query.count()\r\n offset = (page - 1) * size\r\n users = query.offset(offset).limit(size).all()\r\n \r\n # 7. 数据脱敏处理（对非管理员隐藏敏感信息）\r\n safe_users = []\r\n for user in users:\r\n user_data = user.to_dict()\r\n if not current_user.is_admin:\r\n # 非管理员看不到其他用户的手机号和邮箱（除自己）\r\n if user.id != current_user.id:\r\n user_data['phone'] = '***'\r\n user_data['email'] = user_data['email'][0] + '***' + user_data['email'].split('@')[1]\r\n safe_users.append(user_data)\r\n \r\n # 8. 返回分页结果\r\n return success_response({\r\n 'items': safe_users,\r\n 'total': total_count,\r\n 'page': page,\r\n 'size': size,\r\n 'pages': math.ceil(total_count / size)\r\n })\r\n```\r\n\r\n#### 4.1.2 创建用户接口\r\n**接口名称**: 创建用户\r\n- **HTTP方法**: POST\r\n- **URL**: `/api/v1/users`\r\n- **认证**: 需要Bearer Token\r\n- **权限**: `user:create` 或 `admin` 角色\r\n\r\n**请求体**:\r\n```json\r\n{\r\n \"username\": \"zhangsan\",\r\n \"email\": \"zhangsan@example.com\",\r\n \"phone\": \"13800138000\",\r\n \"password\": \"Password123!\",\r\n \"role\": \"user\",\r\n \"status\": \"active\"\r\n}\r\n```\r\n\r\n**成功响应** (HTTP 201):\r\n```json\r\n{\r\n \"code\": 201,\r\n \"message\": \"用户创建成功\",\r\n \"data\": {\r\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\r\n \"username\": \"zhangsan\",\r\n \"email\": \"zhangsan@example.com\",\r\n \"role\": \"user\",\r\n \"status\": \"active\",\r\n \"created_at\": \"2026-04-21T10:00:00Z\"\r\n }\r\n}\r\n```\r\n\r\n**业务逻辑伪代码**:\r\n```python\r\ndef create_user(request):\r\n \"\"\"\r\n 创建新用户\r\n \r\n 业务规则：\r\n 1. 用户名、邮箱必须唯一\r\n 2. 密码强度验证\r\n 3. 邮箱格式验证\r\n 4. 手机号格式验证\r\n 5. 创建成功后发送欢迎邮件\r\n \"\"\"\r\n \r\n # 1. 权限验证\r\n if not request.user.has_permission('user:create'):\r\n return forbidden_response('无权创建用户')\r\n \r\n # 2. 解析和验证请求数据\r\n user_data = request.json\r\n \r\n # 必填字段验证\r\n required_fields = ['username', 'email', 'password']\r\n for field in required_fields:\r\n if field not in user_data or not user_data[field]:\r\n return validation_error(f'{field}不能为空')\r\n \r\n # 用户名验证（3-20位，字母数字下划线）\r\n if not re.match(r'^[a-zA-Z0-9_]{3,20}$', user_data['username']):\r\n return validation_error('用户名格式不正确')\r\n \r\n # 邮箱格式验证\r\n if not is_valid_email(user_data['email']):\r\n return validation_error('邮箱格式不正确')\r\n \r\n # 密码强度验证（至少8位，包含大小写字母和数字）\r\n if not is_strong_password(user_data['password']):\r\n return validation_error('密码强度不足')\r\n \r\n # 手机号验证（可选）\r\n if 'phone' in user_data and user_data['phone']:\r\n if not is_valid_phone(user_data['phone']):\r\n return validation_error('手机号格式不正确')\r\n \r\n # 3. 检查唯一性约束\r\n if User.query.filter_by(username=user_data['username']).first():\r\n return conflict_error('用户名已存在')\r\n \r\n if User.query.filter_by(email=user_data['email']).first():\r\n return conflict_error('邮箱已存在')\r\n \r\n if user_data.get('phone') and User.query.filter_by(phone=user_data['phone']).first():\r\n return conflict_error('手机号已存在')\r\n \r\n # 4. 密码加密\r\n hashed_password = bcrypt.hash(user_data['password'])\r\n \r\n # 5. 创建用户（事务操作）\r\n with transaction.atomic():\r\n new_user = User(\r\n username=user_data['username'],\r\n email=user_data['email'],\r\n phone=user_data.get('phone'),\r\n password_hash=hashed_password,\r\n role=user_data.get('role', 'user'),\r\n status=user_data.get('status', 'active'),\r\n created_by=request.user.id\r\n )\r\n new_user.save()\r\n \r\n # 6. 记录操作日志\r\n log_operation(\r\n user_id=request.user.id,\r\n action='user.create',\r\n target_id=new_user.id,\r\n details={'data': sanitize_user_data(user_data)}\r\n )\r\n \r\n # 7. 异步发送欢迎邮件\r\n send_welcome_email.delay(\r\n to_email=new_user.email,\r\n username=new_user.username\r\n )\r\n \r\n # 8. 返回创建结果（敏感信息脱敏）\r\n return created_response(new_user.to_safe_dict())\r\n```\r\n\r\n### 4.2 其他重要接口\r\n\r\n#### 4.2.1 更新用户接口\r\n- **URL**: `PUT /api/v1/users/{id}`\r\n- **权限**: `user:update` 或自己的信息\r\n\r\n#### 4.2.2 删除用户接口\r\n- **URL**: `DELETE /api/v1/users/{id}`\r\n- **权限**: `user:delete` 或 `admin` 角色\r\n- **注意**: 软删除，标记is_deleted=true\r\n\r\n#### 4.2.3 批量操作用户接口\r\n- **URL**: `POST /api/v1/users/batch`\r\n- **支持操作**: 批量激活、批量禁用、批量删除、批量分配角色\r\n\r\n## 5. 数据库设计\r\n\r\n### 5.1 表结构设计\r\n\r\n#### 表名: `users` (用户表)\r\n| 字段名 | 数据类型 | 长度 | 必填 | 默认值 | 说明 |\r\n|--------|----------|------|------|--------|------|\r\n| id | VARCHAR | 36 | ✓ | UUID() | 主键 |\r\n| username | VARCHAR | 50 | ✓ | | 用户名，唯一 |\r\n| email | VARCHAR | 100 | ✓ | | 邮箱，唯一 |\r\n| phone | VARCHAR | 20 | | NULL | 手机号，唯一 |\r\n| password_hash | VARCHAR | 255 | ✓ | | 密码哈希 |\r\n| avatar_url | VARCHAR | 255 | | NULL | 头像URL |\r\n| status | VARCHAR | 20 | ✓ | 'active' | 状态：active/inactive/locked |\r\n| role | VARCHAR | 20 | ✓ | 'user' | 角色：admin/user/guest |\r\n| last_login_at | TIMESTAMP | | | NULL | 最后登录时间 |\r\n| login_failures | INTEGER | | ✓ | 0 | 连续登录失败次数 |\r\n| locked_until | TIMESTAMP | | | NULL | 锁定直到时间 |\r\n| created_at | TIMESTAMP | | ✓ | CURRENT_TIMESTAMP | 创建时间 |\r\n| updated_at | TIMESTAMP | | ✓ | CURRENT_TIMESTAMP | 更新时间 |\r\n| created_by | VARCHAR | 36 | ✓ | | 创建者ID |\r\n| updated_by | VARCHAR | 36 | | NULL | 更新者ID |\r\n| is_deleted | BOOLEAN | | ✓ | FALSE | 软删除标记 |\r\n| deleted_at | TIMESTAMP | | | NULL | 删除时间 |\r\n| deleted_by | VARCHAR | 36 | | NULL | 删除者ID |\r\n\r\n**索引**:\r\n```sql\r\nPRIMARY KEY (id),\r\nUNIQUE KEY uk_username (username),\r\nUNIQUE KEY uk_email (email),\r\nUNIQUE KEY uk_phone (phone) WHERE phone IS NOT NULL,\r\nINDEX idx_status (status),\r\nINDEX idx_role (role),\r\nINDEX idx_created_at (created_at),\r\nINDEX idx_is_deleted (is_deleted)\r\n```\r\n\r\n#### 表名: `user_profiles` (用户档案表)\r\n| 字段名 | 数据类型 | 长度 | 必填 | 默认值 | 说明 |\r\n|--------|----------|------|------|--------|------|\r\n| id | VARCHAR | 36 | ✓ | UUID() | 主键 |\r\n| user_id | VARCHAR | 36 | ✓ | | 用户ID，外键 |\r\n| real_name | VAR\n\nArchive v2.3.1: 22 files, 102791 bytes\n\nFiles: assets/sample-output/sample-user-management.md (24840b), README.md (10526b), references/api-design.md (15083b), references/component-catalog.md (9260b), references/template-spec.md (12944b), requirements.txt (1033b), scripts/html_extractor/__init__.py (1496b), scripts/html_extractor/config.py (6856b), scripts/html_extractor/detector.py (1353b), scripts/html_extractor/extractor.py (101503b), scripts/html_extractor/main.py (1467b), scripts/html_extractor/models.py (9293b), scripts/html_extractor/utils.py (874b), scripts/html-extractor.py (424b), scripts/image-prototype-analyzer.py (18581b), scripts/run_analysis.sh (1820b), scripts/spec-generator.py (38915b), scripts/url-prototype-analyzer.sh (13855b), scripts/xmind-analyzer.py (22415b), skill.json (8036b), SKILL.md (21791b), _meta.json (143b)\n\nArchive v2.3.0: 15 files, 74866 bytes\n\nFiles: assets/sample-output/sample-user-management.md (24840b), README.md (9145b), references/api-design.md (15083b), references/component-catalog.md (9260b), references/template-spec.md (12944b), requirements.txt (1033b), scripts/html-extractor.py (21958b), scripts/image-prototype-analyzer.py (18581b), scripts/run_analysis.sh (1820b), scripts/spec-generator.py (38899b), scripts/url-prototype-analyzer.sh (13757b), scripts/xmind-analyzer.py (22415b), skill.json (6376b), SKILL.md (19357b), _meta.json (143b)\n\nArchive v2.2.0: 15 files, 74763 bytes\n\nFiles: assets/sample-output/sample-user-management.md (24840b), README.md (8866b), references/api-design.md (15083b), references/component-catalog.md (9260b), references/template-spec.md (12944b), requirements.txt (1033b), scripts/html-extractor.py (21958b), scripts/image-prototype-analyzer.py (18581b), scripts/run_analysis.sh (1820b), scripts/spec-generator.py (38899b), scripts/url-prototype-analyzer.sh (12341b), scripts/xmind-analyzer.py (22415b), skill.json (6300b), SKILL.md (19546b), _meta.json (143b)\n\nArchive v2.1.0: 15 files, 71828 bytes\n\nFiles: assets/sample-output/sample-user-management.md (24840b), README.md (7961b), references/api-design.md (15083b), references/component-catalog.md (9260b), references/template-spec.md (12944b), requirements.txt (1033b), scripts/html-extractor.py (21958b), scripts/image-prototype-analyzer.py (18581b), scripts/run_analysis.sh (933b), scripts/spec-generator.py (38899b), scripts/url-prototype-analyzer.sh (9679b), scripts/xmind-analyzer.py (22415b), skill.json (4507b), SKILL.md (18328b), _meta.json (143b)\n\nArchive v2.0.1: 15 files, 68167 bytes\n\nFiles: assets/sample-output/sample-user-management.md (24037b), README.md (6951b), references/api-design.md (14553b), references/component-catalog.md (8867b), references/template-spec.md (12464b), requirements.txt (505b), scripts/html-extractor.py (21412b), scripts/image-prototype-analyzer.py (17373b), scripts/run_analysis.sh (901b), scripts/spec-generator.py (37987b), scripts/url-prototype-analyzer.sh (9342b), scripts/xmind-analyzer.py (21836b), skill.json (1945b), SKILL.md (14562b), _meta.json (143b)\n\nArchive v2.0.0: 15 files, 68159 bytes\n\nFiles: assets/sample-output/sample-user-management.md (24037b), README.md (6951b), references/api-design.md (14553b), references/component-catalog.md (8867b), references/template-spec.md (12464b), requirements.txt (505b), scripts/html-extractor.py (21412b), scripts/image-prototype-analyzer.py (17373b), scripts/run_analysis.sh (901b), scripts/spec-generator.py (37987b), scripts/url-prototype-analyzer.sh (9342b), scripts/xmind-analyzer.py (21836b), skill.json (1945b), SKILL.md (14552b), _meta.json (143b)","readmeExcerpt":"Skill: 别整乱七八糟的原型 Owner: jermyn-zmj Summary: 将产品原型转换为详细技术规范的技能。深度解析HTML原型，提取完整的菜单结构、筛选条件、表格列、操作按钮等信息。支持URL原型、本地HTML文件、图片原型、XMind文件四种输入类型。输出包含前端组件描述、后端接口设计、数据库表设计的完整技术文档。增强版包含智能路由推断、业务API接口推断、完整数据库表结构设计、... Tags: latest:2.3.3 Version history: v2.3.3 | 2026-05-18T10:30:00.234Z | user **Version 2.3.3 Changelog** - 新增 scripts/html_extractor/analyzer.py 核心模块。 - 补充并上线 scripts/html_extractor/ 包的各个 Python 字节码缓存（__pycache__）文件","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# 使用 web_fetch 获取页面内容\n# 分析HTML结构，提取关键信息"},{"language":"bash","snippet":"# 使用 read 工具直接读取本地HTML文件\n# 分析DOM结构，提取关键信息"},{"language":"bash","snippet":"# 使用 image-prototype-analyzer.py 进行基础分析\npython scripts/image-prototype-analyzer.py design.png markdown"},{"language":"python","snippet":"# 使用Claude Vision进行精确UI识别\n# 注意：此功能会将图片发送到Anthropic服务器\nimport anthropic\nimport base64\nimport os\n\n# 需要设置环境变量: ANTHROPIC_API_KEY\napi_key = os.environ.get('ANTHROPIC_API_KEY')\nif not api_key:\n print(\"警告: 未设置ANTHROPIC_API_KEY，无法使用视觉增强分析\")\n print(\"将使用本地基础分析（颜色提取、布局推断）\")\n\nclient = anthropic.Anthropic(api_key=api_key)\n\nwith open('design.png', 'rb') as f:\n image_data = base64.b64encode(f.read()).decode()\n\nresponse = client.messages.create(\n model='claude-3-opus-20240229',\n max_tokens=4096,\n messages=[{\n 'role': 'user',\n 'content': [\n {'type': 'image', 'source': {'type': 'base64', 'media_type': 'image/png', 'data': image_data}},\n {'type': 'text', 'text': '''分析这张UI设计稿，提取：\n1. 页面布局结构（头部、侧边栏、主内容区、底部）\n2. UI组件类型（按钮、输入框、表格、卡片等）\n3. 交互元素（可点击、可输入）\n4. 颜色方案（主色、辅助色、背景色）\n5. 文本内容（标题、描述、按钮文案）\n请以结构化格式输出。'''}\n ]\n }]\n)"},{"language":"bash","snippet":"# 使用 xmind-analyzer.py 进行分析\npython scripts/xmind-analyzer.py product.xmind markdown"},{"language":"bash","snippet":"# 技能会自动识别输入类型并启动相应流程"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: bie-zheng-luan-prototype\ndescription: \"将产品原型转换为详细技术规范的技能。深度解析HTML原型，提取完整的菜单结构、筛选条件、表格列、操作按钮等信息。支持URL原型、本地HTML文件、图片原型、XMind文件四种输入类型。输出包含前端组件描述、后端接口设计、数据库表设计的完整技术文档。增强版包含智能路由推断、业务API接口推断、完整数据库表结构设计、实体关系图、状态枚举定义。新增交互式业务分析功能，可从原型推断业务流程、状态流转，生成问题让用户确认。\"\n---\n\n# 别整乱七八糟原型分析技能 (bie-zheng-luan-prototype)\n\n本技能将产品原型转换为详细的技术实现规范文档，**深度解析HTML结构**，提取完整的界面信息，并通过**交互式分析**推断业务流程。\n\n## ✨ 核心能力\n\n### 深度HTML解析\n本技能可从HTML原型中完整提取：\n\n| 提取内容 | 说明 | 输出格式 |\n|---------|------|---------|\n| **菜单结构** | 侧边栏菜单分组、菜单项、图标、页面标识 | 表格形式，含分组信息 |\n| **筛选条件** | 字段名、类型（select/input）、下拉选项列表 | 表格形式，含完整选项 |\n| **表格列** | 列名、数据类型推断（text/number/date/link等） | 表格形式 |\n| **操作按钮** | 按钮名、分类（search/action/delete等）、样式、位置 | 表格形式 |\n| **统计卡片** | 卡片标题、数值、说明 | 表格形式 |\n| **页面视图** | 多页面识别，每个页面独立分析 | 按页面分章节输出 |\n| **状态Tab** | 状态名称、数量、颜色类型 | 表格形式 |\n| **抽屉/弹窗** | 标题、锚点导航、表单字段、统计信息 | 分章节输出 |\n\n### 数据类型智能推断\n表格列数据类型自动推断：\n- `text` - 普通文本\n- `number` - 数值（含逗号分隔）\n- `date` - 日期格式（YYYY-MM-DD）\n- `link` - 可点击链接/单号\n- `badge` - 状态标签\n- `progress` - 进度条\n- `image` - 图片列\n- `currency` - 金额（含¥符号）\n- `percentage` - 百分比\n\n### 交互式业务分析（v3.0 新增）\n从HTML原型自动推断业务逻辑，生成问题让用户确认：\n\n| 分析内容 | 说明 |\n|---------|------|\n| **页面角色推断** | 识别入口页面、处理页面、查看页面、配置页面 |\n| **业务流程推断** | 基于菜单顺序、字段关联推断页面流转顺序 |\n| **状态流转推断** | 从按钮操作和状态Tab推断状态值和流转规则 |\n| **操作条件推断** | 推断操作是否需要勾选记录、特定状态等条件 |\n| **生成确认问题** | 按优先级生成问题，让用户确认或修正推断 |\n\n> ⚠️ **安全警告（重要）**\n>\n> 使用本技能前请阅读以下安全注意事项：\n>\n> 1. **内网URL需确认**：内网URL默认被阻止。如需分析内部原型，需使用 `--allow-internal` 参数确认风险。请勿分析不应被访问的内部系统。\n>\n> 2. **外部API默认禁用**：视觉增强分析功能需要设置 `ANTHROPIC_API_KEY` 环境变量才会启用。**默认情况下不调用外部API**，图片分析仅使用本地基础功能（颜色提取、布局推断）。启用外部API会将图片发送到Anthropic服务器，请确认图片不含敏感内容。\n>\n> 3. **手动安装依赖**：Shell脚本**不会自动安装Python依赖**。请在运行前手动执行：`pip install beautifulsoup4 pillow lxml`\n>\n> 4. **本地文件访问**：技能会读取您指定的本地文件。请确保文件路径指向预期内容。\n\n## 🛡️ 已实施的安全措施\n\n本技能实施了以下安全防护措施：\n\n### 命令注入防护\n- URL验证：只允许 `http://` 和 `https://` 协议\n- 危险字符检测：阻止Shell特殊字符（`;|&$`'\\\"()<>`）\n- 长度限制：URL最大2048字符\n\n### SSRF防护（用户确认模式）\n- **默认阻止内网URL**：检测私有网络地址自动拒绝\n- **用户确认机制**：需使用 `--allow-internal` 参数才能访问内网\n- 检测范围：`localhost`、`127.x`、`10.x`、`172.16-31.x`、`192.168.x`、`169.254.x`\n\n### 外部API控制\n- **默认禁用**：未设置 `ANTHROPIC_API_KEY` 时，不调用任何外部API\n- **用户触发**：仅在用户主动设置环境变量后启用\n- **数据传输明确**：启用后图片会通过base64发送到Anthropic\n\n### 无自动安装\n- Shell脚本**不执行** `pip install`\n- 仅检查依赖并提示用户手动安装\n- 避免运行时写入操作\n\n### 路径安全验证\n- 检测敏感路径关键词并发出警告\n- 限制路径长度\n- 验证文件存在性\n\n## 🎯 技能用途\n\n当产品经理提供以下任意形式的原型时，使用本技能：\n\n1. **URL原型** - Figma、墨刀、Axure、蓝湖、内网分享链接等\n2. **本地HTML文件** - 导出的HTML原型文件、本地保存的网页原型\n3. **图片原型** - 设计稿截图、高保真原型图\n4. **XMind文件** - 产品功能脑图、信息架构\n\n**输出目标**：生成一份详细的技术规范文档，让大模型能据此生成相似度90%以上的系统。\n\n## 🔧 当前版本能力（v3.1.0）\n\n### ✅ 已支持\n- **URL原型分析**：支持Figma、墨刀、Axure等主流工具的公开/内网URL\n- **本地HTML文件分析**：支持本地导出的HTML原型文件，直接读取文件系统路径\n- **网页内容解析**：提取DOM结构、样式信息、交互元素\n- **图片原型分析**：支持PNG、JPG、JPEG、GIF、WebP、BMP等格式，提取颜色方案、布局区域，生成分析报告\n- **XMind文件分析**：解析.xmind文件（zip格式），提取思维导图节点层级，推断功能模块、页面结构、功能点\n- **交互式业务分析**：从原型推断业务流程，生成问题让用户确认，循环迭代直到理解完整业务逻辑\n- **多UI框架适配**：自动检测并适配企业后台、标准后台、移动端H5等UI框架\n\n## 📋 工作流程\n\n### 第1步：原型内容解析\n根据输入类型选择合适的解析方式：\n\n#### A. URL原型解析\n```bash\n# 使用 web_fetch 获取页面内容\n# 分析HTML结构，提取关键信息\n```\n\n**提取"},{"path":"README.md","content":"# bie-zheng-luan-prototype (别整乱原型分析技能)\n\n> **作者**: 杰哥 | **主页**: https://clawhub.ai/skills/bie-zheng-luan-prototype | **源码**: https://github.com/jermyn-zmj/bie-zheng-luan-prototype\n\n将产品原型转换为详细技术规范的技能，支持4种输入类型：URL原型、本地HTML文件、图片原型、XMind文件。新增交互式业务分析功能，可从原型推断业务流程。\n\n## 🎯 功能特性\n\n### ✅ 支持的输入类型\n1. **URL原型** - Figma、墨刀、Axure、蓝湖等设计工具的公开/内网链接\n2. **本地HTML文件** - 导出的HTML原型文件、本地保存的网页原型\n3. **图片原型** - 设计稿截图、高保真原型图（PNG/JPG/WebP等）\n4. **XMind文件** - 产品功能脑图、信息架构图\n\n### ✅ 核心能力\n- **智能解析**：自动识别输入类型并选择相应解析方式\n- **深度HTML解析**：提取菜单、筛选条件、表格列、操作按钮、状态Tab、抽屉面板等完整信息\n- **多UI框架适配**：自动检测并适配企业后台、标准后台、移动端H5等UI框架\n- **交互式业务分析**：从原型推断业务流程、状态流转，生成问题让用户确认\n- **功能拆解**：将原型元素拆解为前端组件、后端接口、数据库设计\n- **技术文档生成**：输出完整的技术规范文档\n- **多格式支持**：HTML、图片、思维导图全面覆盖\n\n## 📦 安装\n\n### 通过OpenClaw安装\n```bash\nopenclaw skills install https://clawhub.ai/skills/bie-zheng-luan-prototype\n```\n\n### 手动安装\n```bash\n# 克隆仓库\ngit clone https://github.com/[your-username]/bie-zheng-luan-prototype.git\n\n# 复制到技能目录\ncp -r bie-zheng-luan-prototype ~/.openclaw/workspace/skills/\n```\n\n## 🚀 使用方法\n\n### 基本调用\n当用户提供原型时，直接使用本技能：\n\n```bash\n# 分析URL原型\n分析这个Figma原型：https://www.figma.com/file/xxx\n\n# 分析本地HTML文件\n分析这个HTML原型文件：/path/to/prototype.html\n\n# 分析图片原型\n分析这张设计稿截图：/path/to/design.png\n\n# 分析XMind文件\n分析这个产品脑图：/path/to/product.xmind\n```\n\n### HTML分析输出格式\n```bash\n# 标准分析报告（默认）\npython scripts/html-extractor.py prototype.html markdown\n\n# JSON格式数据\npython scripts/html-extractor.py prototype.html json\n\n# 交互式业务分析（包含流程推断和问题）\npython scripts/html-extractor.py prototype.html interactive\n```\n\n### 输入类型自动识别\n技能会根据输入内容自动判断解析方式：\n\n| 输入内容 | 识别方式 | 解析方式 |\n|---------|---------|---------|\n| `https://...` 或 `http://...` | 以http/https开头 | URL原型解析 |\n| `/path/to/file.html` | 文件路径，以.html结尾 | 本地HTML文件解析 |\n| `...` | 以HTML标签开头 | 直接解析粘贴的HTML内容 |\n| `/path/to/file.png/.jpg/.jpeg/.gif/.webp/.bmp` | 图片格式文件路径 | 图片原型解析 |\n| `/path/to/file.xmind` | .xmind后缀文件路径 | XMind文件解析 |\n\n## 📋 输出文档\n\n技能会生成包含以下内容的技术规范文档：\n\n### 1. 系统概览\n- 原型来源和类型\n- 分析时间和版本\n- 总体功能描述\n- 技术栈建议\n\n### 2. 页面结构分析\n- 布局分解（头部、侧边栏、主内容区、底部）\n- 功能模块清单\n- 交互元素识别\n\n### 3. 业务流程分析（交互式模式）\n- 业务流程顺序（页面流转图）\n- 每个页面的操作列表和执行条件\n- 状态流转规则（状态机图）\n- 关键字段和筛选维度\n- 需要用户确认的问题清单\n\n### 4. 前端实现方案\n- 页面路由规划\n- 组件清单（名称、props、状态、交互逻辑）\n- 样式方案（CSS框架、设计系统）\n- 交互细节\n\n### 5. 后端实现方案\n- API接口设计（路由、HTTP方法、参数、返回值）\n- 业务逻辑伪代码\n- 数据库表设计\n- 第三方服务集成\n\n### 6. 开发注意事项\n- 技术栈建议\n- 特殊依赖说明\n- 性能和安全考虑\n- 测试要点\n\n## 🔧 内置工具\n\n### 脚本文件及功能说明\n\n| 脚本文件 | 功能 | 网络访问 | 文件操作 | 安全措施 |\n|---------|------|---------|---------|---------|\n| `url-prototype-analyzer.sh` | URL原型解析主脚本 | curl/wget下载公开URL | 读取HTML、写入输出文件 | URL验证、SSRF检测、命令注入防护 |\n| `run_analysis.sh` | 本地HTML综合分析入口 | 无 | 读取本地HTML、写入输出文件 | 路径验证、敏感路径警告 |\n| `html-extractor.py` | HTML内容深度提取 | 无 | 读取HTML文件 | 纯Python解析，无外部调用 |\n| `html_extractor/analyzer.py` | 业务流程分析 | 无 | 无 | 纯Python分析 |\n| `spec-generator.py` | 技术文档生成 | 无 | 写入输出文件 | 纯Python生成 |\n| `image-prototype-analyzer.py` | 图片原型分析 | 仅在设置ANTHROPIC_API_KEY时调用Claude API | 读取图片文件 | 默认本地分析，外部API需手动启用 |\n| `xmind-analyzer.py` | XMind文件分析 | 无 | 读取.xmind文件（zip解压） | 纯Python解析 |\n\n**脚本详细行为说明：**\n\n1. **url-prototype-analyzer.sh**\n "},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn73wmmkp7pzethhh52mkcsb6n85c3h4\",\n \"slug\": \"bie-zheng-luan-prototype\",\n \"version\": \"2.3.3\",\n \"publishedAt\": 1779100200234\n}"},{"path":"references/api-design.md","content":"# API设计规范参考\r\n\r\n本文档提供RESTful API设计的标准规范，用于技术文档生成时的参考。\r\n\r\n## 设计原则\r\n\r\n### 1. RESTful原则\r\n- **资源导向**：API围绕资源设计，而非操作\r\n- **统一接口**：使用标准HTTP方法\r\n- **无状态**：每个请求包含所有必要信息\r\n- **可缓存**：适当使用缓存头\r\n- **分层系统**：客户端不依赖直接连接\r\n- **按需代码**：可选支持客户端代码扩展\r\n\r\n### 2. 版本管理\r\n- URL路径包含版本：`/api/v1/resource`\r\n- 使用Accept头：`Accept: application/vnd.company.v1+json`\r\n- **推荐**：URL路径版本控制，简单明确\r\n\r\n### 3. 安全原则\r\n- 所有API强制HTTPS\r\n- 身份验证和授权分离\r\n- 输入验证和输出过滤\r\n- 速率限制和配额管理\r\n\r\n## API结构规范\r\n\r\n### 1. 资源命名\r\n- 使用名词复数形式：`/users` 而非 `/user`\r\n- 小写字母，单词间用连字符：`/user-roles`\r\n- 避免动词：使用HTTP方法表示操作\r\n\r\n### 2. HTTP方法使用\r\n| 方法 | 用途 | 幂等性 | 安全性 |\r\n|------|------|--------|--------|\r\n| GET | 获取资源 | 是 | 是 |\r\n| POST | 创建资源 | 否 | 否 |\r\n| PUT | 全量更新资源 | 是 | 否 |\r\n| PATCH | 部分更新资源 | 否 | 否 |\r\n| DELETE | 删除资源 | 是 | 否 |\r\n\r\n### 3. 端点设计示例\r\n```\r\n# 资源集合操作\r\nGET /api/v1/users # 获取用户列表\r\nPOST /api/v1/users # 创建新用户\r\n\r\n# 单个资源操作\r\nGET /api/v1/users/{id} # 获取指定用户\r\nPUT /api/v1/users/{id} # 全量更新用户\r\nPATCH /api/v1/users/{id} # 部分更新用户\r\nDELETE /api/v1/users/{id} # 删除用户\r\n\r\n# 子资源操作\r\nGET /api/v1/users/{id}/orders # 获取用户的订单\r\nPOST /api/v1/users/{id}/orders # 为用户创建订单\r\nGET /api/v1/users/{id}/orders/{orderId} # 获取用户特定订单\r\n```\r\n\r\n## 请求与响应规范\r\n\r\n### 1. 请求头标准\r\n```http\r\n# 必需头\r\nContent-Type: application/json\r\nAuthorization: Bearer {token}\r\nAccept: application/json\r\n\r\n# 推荐头\r\nX-Request-ID: {uuid} # 请求跟踪\r\nX-Client-Version: 1.0.0 # 客户端版本\r\nX-Device-Info: {device_info} # 设备信息\r\n```\r\n\r\n### 2. 请求参数类型\r\n| 参数位置 | 用途 | 示例 |\r\n|----------|------|------|\r\n| 路径参数 | 资源标识 | `/users/{id}` |\r\n| 查询参数 | 筛选、排序、分页 | `?page=1&size=10` |\r\n| 请求体 | 创建/更新数据 | JSON对象 |\r\n| 请求头 | 元数据、认证 | `Authorization` |\r\n\r\n### 3. 响应格式标准\r\n\r\n#### 成功响应 (HTTP 2xx)\r\n```json\r\n{\r\n \"code\": 200,\r\n \"message\": \"success\",\r\n \"data\": {\r\n // 业务数据\r\n },\r\n \"meta\": {\r\n // 分页、时间戳等元数据\r\n }\r\n}\r\n```\r\n\r\n#### 分页响应\r\n```json\r\n{\r\n \"code\": 200,\r\n \"message\": \"success\",\r\n \"data\": {\r\n \"items\": [...], // 当前页数据\r\n \"total\": 100, // 总记录数\r\n \"page\": 1, // 当前页码\r\n \"size\": 10, // 每页大小\r\n \"pages\": 10 // 总页数\r\n }\r\n}\r\n```\r\n\r\n#### 错误响应 (HTTP 4xx/5xx)\r\n```json\r\n{\r\n \"code\": 400,\r\n \"message\": \"参数验证失败\",\r\n \"errors\": [\r\n {\r\n \"field\": \"username\",\r\n \"code\": \"REQUIRED\",\r\n \"message\": \"用户名不能为空\"\r\n },\r\n {\r\n \"field\": \"email\",\r\n \"code\": \"INVALID_FORMAT\",\r\n \"message\": \"邮箱格式不正确\"\r\n }\r\n ],\r\n \"request_id\": \"req_123456\",\r\n \"timestamp\": \"2026-04-21T10:00:00Z\"\r\n}\r\n```\r\n\r\n### 4. HTTP状态码使用\r\n| 状态码 | 含义 | 使用场景 |\r\n|--------|------|----------|\r\n| 200 | OK | 成功获取或更新资源 |\r\n| 201 | Created | 资源创建成功 |\r\n| 204 | No Content | 成功但无返回内容 |\r\n| 400 | Bad Request | 请求参数错误 |\r\n| 401 | Unauthorized | 未认证或认证失败 |\r\n| 403 | Forbidden | 无访问权限 |\r\n| 404 | Not Found | 资源不存在 |\r\n| 409 | Conflict | 资源冲突（如重复创建） |\r\n| 422 | Unprocessable Entity | 业务逻辑验证失败 |\r\n| 429 | Too Many Requests | 请求过于频繁 |\r\n| 500 | Internal Server Error | 服务器内部错误 |\r\n| 503 | Service Unavailable | 服务暂时不可用 |\r\n\r\n## 分页、排序和筛选\r\n\r\n### 1. 分页参数\r\n```http"},{"path":"references/component-catalog.md","content":"# 前端组件目录参考\r\n\r\n本文档提供前端组件的标准描述格式和常见组件模式，用于技术文档生成时的参考。\r\n\r\n## 组件描述标准格式\r\n\r\n### 1. 基础信息\r\n```markdown\r\n**组件名**: [组件名称]\r\n**位置**: [在页面中的位置]\r\n**功能**: [简要描述组件功能]\r\n```\r\n\r\n### 2. Props接口\r\n```javascript\r\ninterface ComponentProps {\r\n // 数据相关\r\n data?: any; // 组件显示的数据\r\n loading?: boolean; // 加载状态\r\n \r\n // 交互回调\r\n onClick?: () => void; // 点击事件\r\n onChange?: (value) => void; // 值变化事件\r\n onSubmit?: (data) => void; // 提交事件\r\n \r\n // 样式控制\r\n className?: string; // 自定义样式类\r\n style?: React.CSSProperties; // 内联样式\r\n \r\n // 配置选项\r\n options?: any[]; // 下拉选项等配置\r\n disabled?: boolean; // 是否禁用\r\n required?: boolean; // 是否必填\r\n \r\n // 子内容\r\n children?: React.ReactNode;\r\n}\r\n```\r\n\r\n### 3. 状态管理\r\n```javascript\r\ninterface ComponentState {\r\n // 数据状态\r\n selectedItems: any[]; // 选中的项\r\n currentPage: number; // 当前页码\r\n \r\n // UI状态\r\n isOpen: boolean; // 是否展开/打开\r\n isLoading: boolean; // 加载状态\r\n error: string | null; // 错误信息\r\n \r\n // 表单状态\r\n formData: object; // 表单数据\r\n validationErrors: object; // 验证错误\r\n}\r\n```\r\n\r\n### 4. 交互逻辑\r\n```markdown\r\n- **初始化**: 组件挂载时执行的操作\r\n- **用户交互**: 用户操作触发的行为\r\n- **数据变化**: props变化时的响应\r\n- **清理**: 组件卸载时的清理操作\r\n```\r\n\r\n## 常见组件模式\r\n\r\n### 1. 数据展示组件\r\n\r\n#### 表格组件 (DataTable)\r\n```markdown\r\n**组件名**: DataTable\r\n**功能**: 展示结构化数据，支持排序、筛选、分页\r\n\r\n**Props**:\r\n- `columns`: Column[] - 列配置\r\n- `dataSource`: any[] - 数据源\r\n- `pagination`: Pagination - 分页配置\r\n- `rowKey`: string - 行唯一键\r\n- `onRowClick`: (record) => void - 行点击事件\r\n\r\n**交互逻辑**:\r\n1. 表头点击切换排序\r\n2. 筛选器输入实时过滤\r\n3. 分页器切换页面\r\n4. 行选择/取消选择\r\n```\r\n\r\n#### 卡片组件 (Card)\r\n```markdown\r\n**组件名**: Card\r\n**功能**: 信息卡片容器，支持标题、内容、操作区\r\n\r\n**Props**:\r\n- `title`: string | ReactNode - 卡片标题\r\n- `extra`: ReactNode - 额外内容（通常为操作按钮）\r\n- `cover`: ReactNode - 封面图片\r\n- `actions`: ReactNode[] - 底部操作按钮\r\n\r\n**样式特点**:\r\n- 阴影效果增强层次感\r\n- 圆角边框\r\n- 悬停效果（可选）\r\n```\r\n\r\n### 2. 表单组件\r\n\r\n#### 输入框 (Input)\r\n```markdown\r\n**组件名**: Input\r\n**功能**: 文本输入控件\r\n\r\n**Props**:\r\n- `type`: 'text' | 'password' | 'email' | 'number' - 输入类型\r\n- `placeholder`: string - 占位文本\r\n- `value`: string - 当前值\r\n- `onChange`: (e) => void - 值变化事件\r\n- `prefix`: ReactNode - 前缀图标\r\n- `suffix`: ReactNode - 后缀图标\r\n- `allowClear`: boolean - 是否显示清除按钮\r\n\r\n**验证规则**:\r\n- 必填验证\r\n- 格式验证（邮箱、手机号等）\r\n- 长度限制\r\n```\r\n\r\n#### 下拉选择 (Select)\r\n```markdown\r\n**组件名**: Select\r\n**功能**: 下拉选择控件\r\n\r\n**Props**:\r\n- `options`: Option[] - 选项列表\r\n- `value`: string | string[] - 当前值\r\n- `onChange`: (value) => void - 值变化事件\r\n- `mode`: 'single' | 'multiple' - 单选/多选模式\r\n- `placeholder`: string - 占位文本\r\n- `loading`: boolean - 加载状态\r\n\r\n**交互逻辑**:\r\n1. 点击触发下拉菜单\r\n2. 搜索框输入过滤选项\r\n3. 选项点击选中\r\n4. 多选模式下标签展示\r\n```\r\n\r\n### 3. 布局组件\r\n\r\n#### 栅格布局 (Grid)\r\n```markdown\r\n**组件名**: Grid\r\n**功能**: 响应式栅格布局系统\r\n\r\n**Props**:\r\n- `cols`: number - 列数（默认24）\r\n- `gutter`: number | [number, number] - 栅格间距\r\n- `span`: number - 栅格占位格数\r\n- `offset`: number - 栅格左侧偏移格数\r\n\r\n**响应式规则**:\r\n- xs (<576px): 1-4列\r\n- sm (≥576px): 1-8列 \r\n- md (≥768px): 1-12列\r\n- lg (≥992px): 1-16列\r\n- xl (≥1200px): 1-24列\r\n```\r\n\r\n#### 布局容器 (Layout)\r\n```markdown\r\n**组件名**: Layout\r\n**功能**: 页面整体布局"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"将产品原型转换为详细技术规范的技能。深度解析HTML原型，提取完整的菜单结构、筛选条件、表格列、操作按钮等信息。支持URL原型、本地HTML文件、图片原型、XMind文件四种输入类型。输出包含前端组件描述、后端接口设计、数据库表设计的完整技术文档。增强版包含智能路由推断、业务API接口推断、完整数据库表结构设计、... Skill: 别整乱七八糟的原型 Owner: jermyn-zmj Summary: 将产品原型转换为详细技术规范的技能。深度解析HTML原型，提取完整的菜单结构、筛选条件、表格列、操作按钮等信息。支持URL原型、本地HTML文件、图片原型、XMind文件四种输入类型。输出包含前端组件描述、后端接口设计、数据库表设计的完整技术文档。增强版包含智能路由推断、业务API接口推断、完整数据库表结构设计、... Tags: latest:2.3.3 Version history: v2.3.3 | 2026-05-18T10:30:00.234Z | user **Version 2.3.3 Changelog** - 新增 scripts/html_extractor/analyzer.py 核心模块。 - 补充并上线 scripts/html_extractor/ 包的各个 Python 字节码缓存（__pycache__）文件","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1066,"uniquenessScore":59,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T05:29:58.448Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T05:29:58.448Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:43:36.017Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}