@hupan56/wlkj 2.7.12 → 3.1.2

package/templates/qoder/scripts/{gen_design_doc.py → domain/design/gen_design_doc.py}

@@ -1,394 +1,406 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""
-gen_design_doc.py - 自动生成 DESIGN.md (给 AI 的设计系统说明书)
-
-从 ui-style.json + ref-vben-style.json + ref-icon.json 等索引数据
-组装成一个单一文件，AI 出原型前必须先读这个文件。
-
-解决了业界最佳实践的核心思路:
-  - v0.dev: AI 读 Registry → 用正确 token 生成
-  - design.md (GitHub): 从 URL 提取 → DESIGN.md → AI 读
-  - 我们: 从真实代码索引 → DESIGN.md → AI 读 → 不再猜风格
-
-Usage:
-    python gen_design_doc.py              # 生成到 data/design/DESIGN.md
-    python gen_design_doc.py --stdout     # 输出到 stdout (给 AI 直接读)
-"""
-
-import os
-import sys
-import json
-import re
-import time
-
-# UTF-8 stdio
-try:
-    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
-except (AttributeError, TypeError, OSError, IOError):
-    try:
-        sys.stdout.reconfigure(encoding='utf-8')
-    except Exception:
-        pass
-
-BASE = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-INDEX_DIR = os.path.join(BASE, 'data', 'index')
-OUTPUT_DIR = os.path.join(BASE, 'data', 'design')
-
-
-def load_json(filename):
-    path = os.path.join(INDEX_DIR, filename)
-    if not os.path.isfile(path):
-        return {}
-    try:
-        with open(path, encoding='utf-8') as f:
-            return json.load(f)
-    except Exception:
-        return {}
-
-
-def gen_design_doc():
-    """生成 DESIGN.md 内容。返回字符串。"""
-    # 加载数据源
-    ui_style = load_json('ui-style.json')
-    vben = load_json('ref-vben-style.json')
-    icon = load_json('ref-icon.json')
-    chart_style = load_json('ref-chart-style.json')
-
-    lines = []
-    lines.append('# DESIGN.md - AI Prototype Design System Reference')
-    lines.append('')
-    lines.append('> **This file is the SINGLE SOURCE OF TRUTH for AI when generating prototypes.')
-    lines.append('> AI MUST read this file before generating ANY prototype. Do NOT invent styles.**')
-    lines.append('')
-    lines.append('> Auto-generated by gen_design_doc.py from real code indexes.')
-    lines.append(f'> Generated: {time.strftime("%Y-%m-%d %H:%M")}')
-    lines.append('')
-    lines.append('---')
-    lines.append('')
-
-    # ========== 1. Layout Fingerprint ==========
-    lines.append('## 1. Layout Fingerprint (from real pages)')
-    lines.append('')
-    for proj_name, pdata in (ui_style.get('projects') or {}).items():
-        fp = pdata.get('layout_fingerprint')
-        if not fp:
-            continue
-        lines.append(f'### {proj_name}')
-        lines.append('')
-        sidebar_w = fp.get('sidebar_width') or '?'
-        radius_v = fp.get('radius') or '?'
-        lines.append(f'- **Layout mode**: {fp.get("layout", "unknown")} (determines sidebar/header structure)')
-        lines.append(f'- **Stack**: {fp.get("stack", "unknown")}')
-        lines.append(f'- **Theme**: {fp.get("theme_mode", "light")}')
-        lines.append(f'- **Sidebar**: width={sidebar_w}px, semi_dark={fp.get("semi_dark_sidebar", False)}')
-        lines.append(f'- **Topbar**: dark header with logo + tools')
-        lines.append(f'- **Access mode**: {fp.get("access_mode", "unknown")} (menus come from backend API)')
-        lines.append(f'- **Border radius**: {radius_v}rem')
-
-        if fp.get('layout') == 'mixed-nav':
-            lines.append('')
-            lines.append('**mixed-nav layout means:**')
-            lines.append('- Top bar: logo + notification + avatar (dark background)')
-            lines.append('- Left sidebar: module-level menus (with icons)')
-            lines.append('- Content area: breadcrumb + page header + content')
-            lines.append('- Menu depth: 3-4 levels supported (ParentView nesting)')
-        lines.append('')
-
-    # ========== 2. Design Tokens ==========
-    lines.append('## 2. Design Tokens (CSS Variables)')
-    lines.append('')
-    lines.append('**MUST use these exact values. NEVER hardcode #1890ff (Ant Design default).**')
-    lines.append('')
-
-    # From vben reference
-    dt = vben.get('design_tokens', {})
-    if dt:
-        lines.append('### Color Tokens (from vben-style-reference)')
-        lines.append('')
-        color_tokens = {k: v for k, v in dt.items()
-                        if 'color' in k.lower() or 'background' in k.lower()
-                        or 'foreground' in k.lower() or 'primary' in k.lower()
-                        or 'destructive' in k.lower() or 'success' in k.lower()
-                        or 'warning' in k.lower() or 'border' in k.lower()
-                        or 'input' in k.lower() or 'muted' in k.lower()
-                        or 'card' in k.lower() or 'popover' in k.lower()
-                        or 'radius' in k.lower() or 'font' in k.lower()}
-        for k, v in color_tokens.items():
-            lines.append(f'  {k}: {v}')
-        lines.append('')
-
-    # From layout fingerprint (authoritative)
-    fp_primary = None
-    fp_destructive = None
-    fp_success = None
-    fp_warning = None
-    # 优先取有 color_primary 的指纹 (fywl-ui 有完整颜色, Carmg-H5 可能没有)
-    for proj_name, pdata in (ui_style.get('projects') or {}).items():
-        fp = pdata.get('layout_fingerprint', {})
-        if fp and fp.get('color_primary'):
-            fp_primary = fp.get('color_primary')
-            fp_destructive = fp.get('color_destructive')
-            fp_success = fp.get('color_success')
-            fp_warning = fp.get('color_warning')
-            break
-
-    lines.append('### Authoritative Colors (from layout_fingerprint - HIGHEST priority)')
-    lines.append('')
-    lines.append('```css')
-    lines.append(':root {')
-    if fp_primary:
-        lines.append(f'  --primary: {fp_primary}')
-    if fp_destructive:
-        lines.append(f'  --destructive: {fp_destructive}')
-    if fp_success:
-        lines.append(f'  --success: {fp_success}')
-    if fp_warning:
-        lines.append(f'  --warning: {fp_warning}')
-    lines.append('  --background-deep: hsl(216, 20.11%, 95.47%)')
-    lines.append('  --font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif')
-    lines.append('  --radius: 0.25rem')
-    lines.append('}')
-    lines.append('```')
-    lines.append('')
-
-    lines.append('### FORBIDDEN Colors (NEVER use)')
-    lines.append('')
-    lines.append('- `#1890ff` - Ant Design default, NOT this project\'s primary')
-    lines.append('- Any color not listed above without citing a source file')
-    lines.append('')
-
-    # ========== 3. Page Types ==========
-    lines.append('## 3. Page Types (how this system structures pages)')
-    lines.append('')
-    for proj_name, pdata in (ui_style.get('projects') or {}).items():
-        pt = pdata.get('page_types', {})
-        if not pt:
-            continue
-        lines.append(f'### {proj_name} page type distribution')
-        lines.append('')
-        for page_type, count in sorted(pt.items(), key=lambda x: -x[1]):
-            lines.append(f'- **{page_type}**: {count} pages')
-        lines.append('')
-
-    lines.append('### Common page patterns (extracted from real pages)')
-    lines.append('')
-    # 从 page_examples 动态提取每种页面类型的真实布局模式
-    _page_type_labels = {
-        'table-page': 'Table page (search + grid + pagination)',
-        'form-page': 'Form page (structured input, NOT a fixed template)',
-        'detail-page': 'Detail page (read-only data display)',
-        'modal': 'Modal/Drawer (popup form or detail)',
-        'dashboard': 'Dashboard (summary cards + charts)',
-    }
-    # 统计每种类型的真实布局模式
-    for proj_name, pdata in (ui_style.get('projects') or {}).items():
-        pe = pdata.get('page_examples') or {}
-        for pt_key in ['table-page', 'form-page', 'detail-page', 'modal', 'dashboard']:
-            examples = pe.get(pt_key, [])
-            real_examples = [e for e in examples if isinstance(e, dict) and (e.get('layout') or e.get('form_fields') or e.get('table_columns') or e.get('behaviors') or e.get('form_components'))]
-            if not real_examples:
-                continue
-            label = _page_type_labels.get(pt_key, pt_key)
-            lines.append(f'- **{label}** ({proj_name}, {len(real_examples)} examples)')
-            # 提取布局模式
-            ex0 = real_examples[0]
-            layout = ex0.get('layout', {})
-            if layout:
-                if layout.get('grid_cols'):
-                    lines.append(f'  - Grid columns: {layout["grid_cols"]} (real pattern from {ex0["file"].split("/")[-1]})')
-                if layout.get('label_width'):
-                    lines.append(f'  - Label width: {layout["label_width"]}px')
-            # 表单组件
-            fc = ex0.get('form_components', [])
-            if fc:
-                lines.append(f'  - Form components: {", ".join(fc[:6])}')
-            # 交互行为 (侧边栏折叠/表格分页/表单模式)
-            behaviors = ex0.get('behaviors', {})
-            if behaviors:
-                bh_strs = []
-                for bk, bv in behaviors.items():
-                    bh_strs.append(f'{bk}={bv}')
-                lines.append(f'  - Behaviors: {", ".join(bh_strs)}')
-            # 表单字段数
-            ff_count = len(ex0.get('form_fields', []))
-            if ff_count:
-                lines.append(f'  - Field count: {ff_count} fields (typical)')
-                sample_fields = [f.get('label', f.get('field', '')) for f in ex0.get('form_fields', [])[:5]]
-                lines.append(f'  - Sample fields: {", ".join(sample_fields)}')
-            # 表格列数
-            tc_count = len(ex0.get('table_columns', []))
-            if tc_count:
-                lines.append(f'  - Column count: {tc_count} columns (typical)')
-                sample_cols = [c.get('title', c.get('field', '')) for c in ex0.get('table_columns', [])[:5]]
-                lines.append(f'  - Sample columns: {", ".join(sample_cols)}')
-            lines.append(f'  - Reference file: {ex0.get("file", "?")}')
-            lines.append('')
-        break  # 只取第一个有数据的项目 (通常是 fywl-ui)
-
-    lines.append('### Form page behavior modes (NOT a fixed template - choose by requirement)')
-    lines.append('')
-    lines.append('Form pages vary by section count. DO NOT use one fixed template. Match the mode to the requirement:')
-    lines.append('- **Single-section form**: one form, 2-3 grid columns, label 80-140px, bottom save/reset buttons')
-    lines.append('- **Multi-section form**: tabs or accordion separating sections, each section 2-3 columns')
-    lines.append('- **Step wizard form**: horizontal step indicator + per-step form + back/next buttons')
-    lines.append('- **Drawer form**: right-side drawer popup, single column, compact layout')
-    lines.append('')
-    lines.append('> fill_prototype.py extracts real grid_cols/label_width from page_examples.')
-    lines.append('> The form layout adapts to the matched example, NOT a hardcoded shell.')
-    lines.append('')
-
-    # ========== 4. Top Fields ==========
-    lines.append('## 4. Top Used Fields (real field names -> Chinese labels)')
-    lines.append('')
-    lines.append('These are the most common fields across all pages. Use them for new pages.')
-    lines.append('')
-    fm = ui_style.get('field_map') or {}
-    top_fields = sorted(fm.items(), key=lambda x: len(x[1].get('titles', set()) if isinstance(x[1].get('titles'), set) else x[1].get('titles', [])), reverse=True)[:30]
-    for field_name, info in top_fields:
-        titles = info.get('titles', set())
-        if isinstance(titles, set):
-            title = next(iter(titles), field_name)
-        elif isinstance(titles, list) and titles:
-            title = titles[0]
-        else:
-            title = field_name
-        count = info.get('count', 0)
-        lines.append(f'- `{field_name}` -> {title} (used {count}x)')
-    lines.append('')
-
-    # ========== 4.5 Feature Modules (from prd-features.json) ==========
-    pf = load_json('prd-features.json')
-    features = pf.get('features', {}) if isinstance(pf, dict) else {}
-    if features:
-        lines.append('## 4.5 Feature Modules (系统有哪些功能模块)')
-        lines.append('')
-        lines.append('出原型时, 先确定需求属于哪个模块, 参考该模块的现有页面。')
-        lines.append('')
-        for feat_key, feat_info in list(features.items())[:12]:
-            cn = feat_info.get('cn', feat_key)
-            page_count = feat_info.get('page_count', 0)
-            api_count = feat_info.get('api_count', 0)
-            pages = feat_info.get('pages', [])
-            sample_pages = ', '.join(pages[:2]) if pages else ''
-            lines.append(f'- **{cn}** ({feat_key}): {page_count} pages, {api_count} APIs')
-            if sample_pages:
-                lines.append(f'  - 标杆页面: {sample_pages}')
-        lines.append('')
-
-    # ========== 4.6 Real Buttons (from entity-registry.json) ==========
-    er = load_json('entity-registry.json')
-    entities = er.get('entities', {}) if isinstance(er, dict) else {}
-    button_samples = []
-    for eid, info in list(entities.items())[:500]:
-        if not eid.startswith('B:'):
-            continue
-        props = info.get('properties', {}) if isinstance(info, dict) else {}
-        btn_text = props.get('button_text', '')
-        if btn_text and btn_text not in [b['text'] for b in button_samples]:
-            button_samples.append({'text': btn_text, 'endpoint': props.get('endpoint', '')})
-        if len(button_samples) >= 15:
-            break
-    if button_samples:
-        lines.append('## 4.6 Real Button Texts (系统里真实的按钮文案)')
-        lines.append('')
-        lines.append('出原型时, 按钮文案用这些真实的, 不要编"新增/编辑"。')
-        lines.append('')
-        for b in button_samples:
-            ep = ' -> ' + b['endpoint'] if b['endpoint'] else ''
-            lines.append(f'- {b["text"]}{ep}')
-        lines.append('')
-
-    # ========== 5. Components ==========
-    lines.append('## 5. UI Components (from real code)')
-    lines.append('')
-    cc = ui_style.get('common_components') or {}
-    lines.append('### Most used Ant Design Vue components')
-    lines.append('')
-    for comp, count in list(cc.items())[:15]:
-        lines.append(f'- {comp}: {count}')
-    lines.append('')
-
-    fc = ui_style.get('form_components') or {}
-    lines.append('### Form components')
-    lines.append('')
-    for comp, count in list(fc.items())[:10]:
-        lines.append(f'- {comp}: {count}')
-    lines.append('')
-
-    # ========== 6. Icons ==========
-    lines.append('## 6. Icons')
-    lines.append('')
-    lines.append('**MUST use real icon system. NEVER use emoji.**')
-    lines.append('')
-    lines.append('- **Web (fywl-ui)**: Ant Design inline SVG icons')
-    lines.append('  - Source: `data/index/ref-icon.json`')
-    lines.append('  - Usage: `<svg viewBox="0 0 1024 1024" fill="currentColor">...</svg>`')
-    lines.append('  - Size: 14-16px for menu items, 18-20px for actions')
-    lines.append('- **APP (Carmg-H5)**: Vant font icons')
-    lines.append('  - CDN: https://cdn.jsdelivr.net/npm/vant@4/lib/index.css')
-    lines.append('  - Usage: `<i class="van-icon van-icon-xxx"></i>`')
-    lines.append('')
-
-    # ========== 7. Dashboard / Chart styles ==========
-    chart_data = chart_style
-    if chart_data:
-        lines.append('## 7. Dashboard / Chart Styles')
-        lines.append('')
-        lines.append('Two in-system chart idioms:')
-        lines.append('- **Dark screen** (monitor): background `#011845`, accent `#53CFF0`/`#FFE646`')
-        lines.append('- **Light card** (workbench): white cards, blue accent `#2E61E0`')
-        lines.append('')
-        lines.append('Source: `data/index/ref-chart-style.json`')
-        lines.append('')
-
-    # ========== 8. Prototype Rules ==========
-    lines.append('## 8. Prototype Rules (AI MUST follow)')
-    lines.append('')
-    lines.append('1. **Token priority**: layout_fingerprint > vben-style-reference > code > PDF')
-    lines.append('2. **Only change the diff**: everything else identical to existing page')
-    lines.append('3. **Single file**: one HTML with all CSS and JS inline')
-    lines.append('4. **Interactive**: buttons click, forms fill, tables scroll')
-    lines.append('5. **Icons**: real SVG/Webfont only, NEVER emoji')
-    lines.append('6. **Colors**: from this file only, NEVER invent')
-    lines.append('7. **Layout**: sidebar_width/topbar_height from layout_fingerprint')
-    lines.append('8. **Source citation**: header comment MUST cite which files provided the style')
-    lines.append('')
-
-    # ========== 9. How to generate ==========
-    lines.append('## 9. How to Generate a Prototype')
-    lines.append('')
-    lines.append('```bash')
-    lines.append('# Step 1: Run fill_prototype (generates 80% draft with real data)')
-    lines.append('python .qoder/scripts/fill_prototype.py <keyword> --platform <web|app>')
-    lines.append('')
-    lines.append('# Step 2: AI reads the draft + this DESIGN.md, does 20% adjustment')
-    lines.append('# - Confirm table columns match requirement')
-    lines.append('# - Add interaction details (sidebar collapse, modal, tab switch)')
-    lines.append('# - Do NOT change tokens/colors/layout parameters')
-    lines.append('```')
-    lines.append('')
-
-    return '\n'.join(lines)
-
-
-def main():
-    stdout_mode = '--stdout' in sys.argv
-    content = gen_design_doc()
-
-    if stdout_mode:
-        print(content)
-        return 0
-
-    # 写到 data/design/DESIGN.md
-    os.makedirs(OUTPUT_DIR, exist_ok=True)
-    output_path = os.path.join(OUTPUT_DIR, 'DESIGN.md')
-    with open(output_path, 'w', encoding='utf-8') as f:
-        f.write(content)
-    print(f'DESIGN.md generated: {output_path}')
-    print(f'  Size: {len(content)} chars, {content.count(chr(10))} lines')
-    return 0
-
-
-if __name__ == '__main__':
-    sys.exit(main())
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
+import os as _o, sys as _s
+_f = _o.path.abspath(__file__)
+for _ in range(10):
+    _f = _o.path.dirname(_f)
+    _cp = _o.path.join(_f, 'foundation')
+    if _o.path.isfile(_o.path.join(_cp, 'bootstrap.py')):
+        break
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+from foundation.core.paths import get_repo_root
+
+"""
+gen_design_doc.py - 自动生成 DESIGN.md (给 AI 的设计系统说明书)
+
+从 ui-style.json + ref-vben-style.json + ref-icon.json 等索引数据
+组装成一个单一文件，AI 出原型前必须先读这个文件。
+
+解决了业界最佳实践的核心思路:
+  - v0.dev: AI 读 Registry → 用正确 token 生成
+  - design.md (GitHub): 从 URL 提取 → DESIGN.md → AI 读
+  - 我们: 从真实代码索引 → DESIGN.md → AI 读 → 不再猜风格
+
+Usage:
+    python gen_design_doc.py              # 生成到 data/design/DESIGN.md
+    python gen_design_doc.py --stdout     # 输出到 stdout (给 AI 直接读)
+"""
+
+import os
+import sys
+import json
+import re
+import time
+
+# UTF-8 stdio
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except (AttributeError, TypeError, OSError, IOError):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+BASE = get_repo_root()
+INDEX_DIR = os.path.join(BASE, 'data', 'index')
+OUTPUT_DIR = os.path.join(BASE, 'data', 'design')
+
+
+def load_json(filename):
+    path = os.path.join(INDEX_DIR, filename)
+    if not os.path.isfile(path):
+        return {}
+    try:
+        with open(path, encoding='utf-8') as f:
+            return json.load(f)
+    except Exception:
+        return {}
+
+
+def gen_design_doc():
+    """生成 DESIGN.md 内容。返回字符串。"""
+    # 加载数据源
+    ui_style = load_json('ui-style.json')
+    vben = load_json('ref-vben-style.json')
+    icon = load_json('ref-icon.json')
+    chart_style = load_json('ref-chart-style.json')
+
+    lines = []
+    lines.append('# DESIGN.md - AI Prototype Design System Reference')
+    lines.append('')
+    lines.append('> **This file is the SINGLE SOURCE OF TRUTH for AI when generating prototypes.')
+    lines.append('> AI MUST read this file before generating ANY prototype. Do NOT invent styles.**')
+    lines.append('')
+    lines.append('> Auto-generated by gen_design_doc.py from real code indexes.')
+    lines.append(f'> Generated: {time.strftime("%Y-%m-%d %H:%M")}')
+    lines.append('')
+    lines.append('---')
+    lines.append('')
+
+    # ========== 1. Layout Fingerprint ==========
+    lines.append('## 1. Layout Fingerprint (from real pages)')
+    lines.append('')
+    for proj_name, pdata in (ui_style.get('projects') or {}).items():
+        fp = pdata.get('layout_fingerprint')
+        if not fp:
+            continue
+        lines.append(f'### {proj_name}')
+        lines.append('')
+        sidebar_w = fp.get('sidebar_width') or '?'
+        radius_v = fp.get('radius') or '?'
+        lines.append(f'- **Layout mode**: {fp.get("layout", "unknown")} (determines sidebar/header structure)')
+        lines.append(f'- **Stack**: {fp.get("stack", "unknown")}')
+        lines.append(f'- **Theme**: {fp.get("theme_mode", "light")}')
+        lines.append(f'- **Sidebar**: width={sidebar_w}px, semi_dark={fp.get("semi_dark_sidebar", False)}')
+        lines.append(f'- **Topbar**: dark header with logo + tools')
+        lines.append(f'- **Access mode**: {fp.get("access_mode", "unknown")} (menus come from backend API)')
+        lines.append(f'- **Border radius**: {radius_v}rem')
+
+        if fp.get('layout') == 'mixed-nav':
+            lines.append('')
+            lines.append('**mixed-nav layout means:**')
+            lines.append('- Top bar: logo + notification + avatar (dark background)')
+            lines.append('- Left sidebar: module-level menus (with icons)')
+            lines.append('- Content area: breadcrumb + page header + content')
+            lines.append('- Menu depth: 3-4 levels supported (ParentView nesting)')
+        lines.append('')
+
+    # ========== 2. Design Tokens ==========
+    lines.append('## 2. Design Tokens (CSS Variables)')
+    lines.append('')
+    lines.append('**MUST use these exact values. NEVER hardcode #1890ff (Ant Design default).**')
+    lines.append('')
+
+    # From vben reference
+    dt = vben.get('design_tokens', {})
+    if dt:
+        lines.append('### Color Tokens (from vben-style-reference)')
+        lines.append('')
+        color_tokens = {k: v for k, v in dt.items()
+                        if 'color' in k.lower() or 'background' in k.lower()
+                        or 'foreground' in k.lower() or 'primary' in k.lower()
+                        or 'destructive' in k.lower() or 'success' in k.lower()
+                        or 'warning' in k.lower() or 'border' in k.lower()
+                        or 'input' in k.lower() or 'muted' in k.lower()
+                        or 'card' in k.lower() or 'popover' in k.lower()
+                        or 'radius' in k.lower() or 'font' in k.lower()}
+        for k, v in color_tokens.items():
+            lines.append(f'  {k}: {v}')
+        lines.append('')
+
+    # From layout fingerprint (authoritative)
+    fp_primary = None
+    fp_destructive = None
+    fp_success = None
+    fp_warning = None
+    # 优先取有 color_primary 的指纹 (fywl-ui 有完整颜色, Carmg-H5 可能没有)
+    for proj_name, pdata in (ui_style.get('projects') or {}).items():
+        fp = pdata.get('layout_fingerprint', {})
+        if fp and fp.get('color_primary'):
+            fp_primary = fp.get('color_primary')
+            fp_destructive = fp.get('color_destructive')
+            fp_success = fp.get('color_success')
+            fp_warning = fp.get('color_warning')
+            break
+
+    lines.append('### Authoritative Colors (from layout_fingerprint - HIGHEST priority)')
+    lines.append('')
+    lines.append('```css')
+    lines.append(':root {')
+    if fp_primary:
+        lines.append(f'  --primary: {fp_primary}')
+    if fp_destructive:
+        lines.append(f'  --destructive: {fp_destructive}')
+    if fp_success:
+        lines.append(f'  --success: {fp_success}')
+    if fp_warning:
+        lines.append(f'  --warning: {fp_warning}')
+    lines.append('  --background-deep: hsl(216, 20.11%, 95.47%)')
+    lines.append('  --font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif')
+    lines.append('  --radius: 0.25rem')
+    lines.append('}')
+    lines.append('```')
+    lines.append('')
+
+    lines.append('### FORBIDDEN Colors (NEVER use)')
+    lines.append('')
+    lines.append('- `#1890ff` - Ant Design default, NOT this project\'s primary')
+    lines.append('- Any color not listed above without citing a source file')
+    lines.append('')
+
+    # ========== 3. Page Types ==========
+    lines.append('## 3. Page Types (how this system structures pages)')
+    lines.append('')
+    for proj_name, pdata in (ui_style.get('projects') or {}).items():
+        pt = pdata.get('page_types', {})
+        if not pt:
+            continue
+        lines.append(f'### {proj_name} page type distribution')
+        lines.append('')
+        for page_type, count in sorted(pt.items(), key=lambda x: -x[1]):
+            lines.append(f'- **{page_type}**: {count} pages')
+        lines.append('')
+
+    lines.append('### Common page patterns (extracted from real pages)')
+    lines.append('')
+    # 从 page_examples 动态提取每种页面类型的真实布局模式
+    _page_type_labels = {
+        'table-page': 'Table page (search + grid + pagination)',
+        'form-page': 'Form page (structured input, NOT a fixed template)',
+        'detail-page': 'Detail page (read-only data display)',
+        'modal': 'Modal/Drawer (popup form or detail)',
+        'dashboard': 'Dashboard (summary cards + charts)',
+    }
+    # 统计每种类型的真实布局模式
+    for proj_name, pdata in (ui_style.get('projects') or {}).items():
+        pe = pdata.get('page_examples') or {}
+        for pt_key in ['table-page', 'form-page', 'detail-page', 'modal', 'dashboard']:
+            examples = pe.get(pt_key, [])
+            real_examples = [e for e in examples if isinstance(e, dict) and (e.get('layout') or e.get('form_fields') or e.get('table_columns') or e.get('behaviors') or e.get('form_components'))]
+            if not real_examples:
+                continue
+            label = _page_type_labels.get(pt_key, pt_key)
+            lines.append(f'- **{label}** ({proj_name}, {len(real_examples)} examples)')
+            # 提取布局模式
+            ex0 = real_examples[0]
+            layout = ex0.get('layout', {})
+            if layout:
+                if layout.get('grid_cols'):
+                    lines.append(f'  - Grid columns: {layout["grid_cols"]} (real pattern from {ex0["file"].split("/")[-1]})')
+                if layout.get('label_width'):
+                    lines.append(f'  - Label width: {layout["label_width"]}px')
+            # 表单组件
+            fc = ex0.get('form_components', [])
+            if fc:
+                lines.append(f'  - Form components: {", ".join(fc[:6])}')
+            # 交互行为 (侧边栏折叠/表格分页/表单模式)
+            behaviors = ex0.get('behaviors', {})
+            if behaviors:
+                bh_strs = []
+                for bk, bv in behaviors.items():
+                    bh_strs.append(f'{bk}={bv}')
+                lines.append(f'  - Behaviors: {", ".join(bh_strs)}')
+            # 表单字段数
+            ff_count = len(ex0.get('form_fields', []))
+            if ff_count:
+                lines.append(f'  - Field count: {ff_count} fields (typical)')
+                sample_fields = [f.get('label', f.get('field', '')) for f in ex0.get('form_fields', [])[:5]]
+                lines.append(f'  - Sample fields: {", ".join(sample_fields)}')
+            # 表格列数
+            tc_count = len(ex0.get('table_columns', []))
+            if tc_count:
+                lines.append(f'  - Column count: {tc_count} columns (typical)')
+                sample_cols = [c.get('title', c.get('field', '')) for c in ex0.get('table_columns', [])[:5]]
+                lines.append(f'  - Sample columns: {", ".join(sample_cols)}')
+            lines.append(f'  - Reference file: {ex0.get("file", "?")}')
+            lines.append('')
+        break  # 只取第一个有数据的项目 (通常是 fywl-ui)
+
+    lines.append('### Form page behavior modes (NOT a fixed template - choose by requirement)')
+    lines.append('')
+    lines.append('Form pages vary by section count. DO NOT use one fixed template. Match the mode to the requirement:')
+    lines.append('- **Single-section form**: one form, 2-3 grid columns, label 80-140px, bottom save/reset buttons')
+    lines.append('- **Multi-section form**: tabs or accordion separating sections, each section 2-3 columns')
+    lines.append('- **Step wizard form**: horizontal step indicator + per-step form + back/next buttons')
+    lines.append('- **Drawer form**: right-side drawer popup, single column, compact layout')
+    lines.append('')
+    lines.append('> fill_prototype.py extracts real grid_cols/label_width from page_examples.')
+    lines.append('> The form layout adapts to the matched example, NOT a hardcoded shell.')
+    lines.append('')
+
+    # ========== 4. Top Fields ==========
+    lines.append('## 4. Top Used Fields (real field names -> Chinese labels)')
+    lines.append('')
+    lines.append('These are the most common fields across all pages. Use them for new pages.')
+    lines.append('')
+    fm = ui_style.get('field_map') or {}
+    top_fields = sorted(fm.items(), key=lambda x: len(x[1].get('titles', set()) if isinstance(x[1].get('titles'), set) else x[1].get('titles', [])), reverse=True)[:30]
+    for field_name, info in top_fields:
+        titles = info.get('titles', set())
+        if isinstance(titles, set):
+            title = next(iter(titles), field_name)
+        elif isinstance(titles, list) and titles:
+            title = titles[0]
+        else:
+            title = field_name
+        count = info.get('count', 0)
+        lines.append(f'- `{field_name}` -> {title} (used {count}x)')
+    lines.append('')
+
+    # ========== 4.5 Feature Modules (from prd-features.json) ==========
+    pf = load_json('prd-features.json')
+    features = pf.get('features', {}) if isinstance(pf, dict) else {}
+    if features:
+        lines.append('## 4.5 Feature Modules (系统有哪些功能模块)')
+        lines.append('')
+        lines.append('出原型时, 先确定需求属于哪个模块, 参考该模块的现有页面。')
+        lines.append('')
+        for feat_key, feat_info in list(features.items())[:12]:
+            cn = feat_info.get('cn', feat_key)
+            page_count = feat_info.get('page_count', 0)
+            api_count = feat_info.get('api_count', 0)
+            pages = feat_info.get('pages', [])
+            sample_pages = ', '.join(pages[:2]) if pages else ''
+            lines.append(f'- **{cn}** ({feat_key}): {page_count} pages, {api_count} APIs')
+            if sample_pages:
+                lines.append(f'  - 标杆页面: {sample_pages}')
+        lines.append('')
+
+    # ========== 4.6 Real Buttons (from entity-registry.json) ==========
+    er = load_json('entity-registry.json')
+    entities = er.get('entities', {}) if isinstance(er, dict) else {}
+    button_samples = []
+    for eid, info in list(entities.items())[:500]:
+        if not eid.startswith('B:'):
+            continue
+        props = info.get('properties', {}) if isinstance(info, dict) else {}
+        btn_text = props.get('button_text', '')
+        if btn_text and btn_text not in [b['text'] for b in button_samples]:
+            button_samples.append({'text': btn_text, 'endpoint': props.get('endpoint', '')})
+        if len(button_samples) >= 15:
+            break
+    if button_samples:
+        lines.append('## 4.6 Real Button Texts (系统里真实的按钮文案)')
+        lines.append('')
+        lines.append('出原型时, 按钮文案用这些真实的, 不要编"新增/编辑"。')
+        lines.append('')
+        for b in button_samples:
+            ep = ' -> ' + b['endpoint'] if b['endpoint'] else ''
+            lines.append(f'- {b["text"]}{ep}')
+        lines.append('')
+
+    # ========== 5. Components ==========
+    lines.append('## 5. UI Components (from real code)')
+    lines.append('')
+    cc = ui_style.get('common_components') or {}
+    lines.append('### Most used Ant Design Vue components')
+    lines.append('')
+    for comp, count in list(cc.items())[:15]:
+        lines.append(f'- {comp}: {count}')
+    lines.append('')
+
+    fc = ui_style.get('form_components') or {}
+    lines.append('### Form components')
+    lines.append('')
+    for comp, count in list(fc.items())[:10]:
+        lines.append(f'- {comp}: {count}')
+    lines.append('')
+
+    # ========== 6. Icons ==========
+    lines.append('## 6. Icons')
+    lines.append('')
+    lines.append('**MUST use real icon system. NEVER use emoji.**')
+    lines.append('')
+    lines.append('- **Web (fywl-ui)**: Ant Design inline SVG icons')
+    lines.append('  - Source: `data/index/ref-icon.json`')
+    lines.append('  - Usage: `<svg viewBox="0 0 1024 1024" fill="currentColor">...</svg>`')
+    lines.append('  - Size: 14-16px for menu items, 18-20px for actions')
+    lines.append('- **APP (Carmg-H5)**: Vant font icons')
+    lines.append('  - CDN: https://cdn.jsdelivr.net/npm/vant@4/lib/index.css')
+    lines.append('  - Usage: `<i class="van-icon van-icon-xxx"></i>`')
+    lines.append('')
+
+    # ========== 7. Dashboard / Chart styles ==========
+    chart_data = chart_style
+    if chart_data:
+        lines.append('## 7. Dashboard / Chart Styles')
+        lines.append('')
+        lines.append('Two in-system chart idioms:')
+        lines.append('- **Dark screen** (monitor): background `#011845`, accent `#53CFF0`/`#FFE646`')
+        lines.append('- **Light card** (workbench): white cards, blue accent `#2E61E0`')
+        lines.append('')
+        lines.append('Source: `data/index/ref-chart-style.json`')
+        lines.append('')
+
+    # ========== 8. Prototype Rules ==========
+    lines.append('## 8. Prototype Rules (AI MUST follow)')
+    lines.append('')
+    lines.append('1. **Token priority**: layout_fingerprint > vben-style-reference > code > PDF')
+    lines.append('2. **Only change the diff**: everything else identical to existing page')
+    lines.append('3. **Single file**: one HTML with all CSS and JS inline')
+    lines.append('4. **Interactive**: buttons click, forms fill, tables scroll')
+    lines.append('5. **Icons**: real SVG/Webfont only, NEVER emoji')
+    lines.append('6. **Colors**: from this file only, NEVER invent')
+    lines.append('7. **Layout**: sidebar_width/topbar_height from layout_fingerprint')
+    lines.append('8. **Source citation**: header comment MUST cite which files provided the style')
+    lines.append('')
+
+    # ========== 9. How to generate ==========
+    lines.append('## 9. How to Generate a Prototype')
+    lines.append('')
+    lines.append('```bash')
+    lines.append('# Step 1: Run fill_prototype (generates 80% draft with real data)')
+    lines.append('python .qoder/scripts/fill_prototype.py <keyword> --platform <web|app>')
+    lines.append('')
+    lines.append('# Step 2: AI reads the draft + this DESIGN.md, does 20% adjustment')
+    lines.append('# - Confirm table columns match requirement')
+    lines.append('# - Add interaction details (sidebar collapse, modal, tab switch)')
+    lines.append('# - Do NOT change tokens/colors/layout parameters')
+    lines.append('```')
+    lines.append('')
+
+    return '\n'.join(lines)
+
+
+def main():
+    stdout_mode = '--stdout' in sys.argv
+    content = gen_design_doc()
+
+    if stdout_mode:
+        print(content)
+        return 0
+
+    # 写到 data/design/DESIGN.md
+    os.makedirs(OUTPUT_DIR, exist_ok=True)
+    output_path = os.path.join(OUTPUT_DIR, 'DESIGN.md')
+    with open(output_path, 'w', encoding='utf-8') as f:
+        f.write(content)
+    print(f'DESIGN.md generated: {output_path}')
+    print(f'  Size: {len(content)} chars, {content.count(chr(10))} lines')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())