@hupan56/wlkj 2.5.0 → 2.7.0

package/templates/qoder/scripts/gen_design_doc.py

@@ -0,0 +1,394 @@
+#!/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())

package/templates/qoder/scripts/git_sync.py

@@ -21,6 +21,7 @@ Config: .qoder/config.yaml -> git_sync section
 """
 
 import os
+from common.paths import BUILD_CACHE_DIR
 import sys
 import json
 import subprocess
@@ -306,7 +307,7 @@ def build_prd_index():
         return {}
 
     # Load keyword index for code matching
-    ki_path = os.path.join(INDEX_DIR, 'keyword-index.json')
+    ki_path = os.path.join(BUILD_CACHE_DIR, 'code-keyword.json')
     keyword_index = load_json(ki_path)
 
     prd_index = {}
@@ -341,7 +342,7 @@ def build_prd_index():
             print(f'  {f}: Error - {str(e)[:80]}')
 
     # Save index
-    save_json(os.path.join(INDEX_DIR, 'prd-index.json'), prd_index)
+    save_json(os.path.join(BUILD_CACHE_DIR, 'prd-index.json'), prd_index)
 
     print(f'\nPRD Index: {len(prd_index)} PRDs indexed')
     return prd_index
@@ -442,9 +443,9 @@ def update_indexes_incremental(changed_projects):
 
     os.makedirs(INDEX_DIR, exist_ok=True)
 
-    module_map = load_json(os.path.join(INDEX_DIR, 'module-map.json'))
-    keyword_index = load_json(os.path.join(INDEX_DIR, 'keyword-index.json'))
-    api_index = load_json(os.path.join(INDEX_DIR, 'api-index.json'))
+    module_map = load_json(os.path.join(BUILD_CACHE_DIR, 'code-stats.json'))
+    keyword_index = load_json(os.path.join(BUILD_CACHE_DIR, 'code-keyword.json'))
+    api_index = load_json(os.path.join(BUILD_CACHE_DIR, 'code-api.json'))
 
     total_files = 0
 
@@ -505,9 +506,9 @@ def update_indexes_incremental(changed_projects):
         module_map[proj]['files'] = list(set(module_map[proj]['files']))
 
     # Save
-    save_json(os.path.join(INDEX_DIR, 'module-map.json'), module_map)
-    save_json(os.path.join(INDEX_DIR, 'keyword-index.json'), keyword_index)
-    save_json(os.path.join(INDEX_DIR, 'api-index.json'), api_index)
+    save_json(os.path.join(BUILD_CACHE_DIR, 'code-stats.json'), module_map)
+    save_json(os.path.join(BUILD_CACHE_DIR, 'code-keyword.json'), keyword_index)
+    save_json(os.path.join(BUILD_CACHE_DIR, 'code-api.json'), api_index)
 
     print(f'\n  Updated: {total_files} files indexed')
     print(f'  Keywords: {len(keyword_index)}')
@@ -579,9 +580,9 @@ def build_full_indexes():
 
         print(f'    Files: {len(module_map[project_name]["files"])}')
 
-    save_json(os.path.join(INDEX_DIR, 'module-map.json'), module_map)
-    save_json(os.path.join(INDEX_DIR, 'keyword-index.json'), keyword_index)
-    save_json(os.path.join(INDEX_DIR, 'api-index.json'), api_index)
+    save_json(os.path.join(BUILD_CACHE_DIR, 'code-stats.json'), module_map)
+    save_json(os.path.join(BUILD_CACHE_DIR, 'code-keyword.json'), keyword_index)
+    save_json(os.path.join(BUILD_CACHE_DIR, 'code-api.json'), api_index)
 
     print(f'\n  Total: {total_files} files, {len(keyword_index)} keywords, {len(api_index)} APIs')
     return total_files
@@ -630,9 +631,9 @@ def build_prd_code_mapping():
     """Build bidirectional PRD to Code mapping with business term awareness"""
     print('\n=== Building PRD to Code Mapping ===\n')
 
-    prd_index = load_json(os.path.join(INDEX_DIR, 'prd-index.json'))
-    keyword_index = load_json(os.path.join(INDEX_DIR, 'keyword-index.json'))
-    module_map = load_json(os.path.join(INDEX_DIR, 'module-map.json'))
+    prd_index = load_json(os.path.join(BUILD_CACHE_DIR, 'prd-index.json'))
+    keyword_index = load_json(os.path.join(BUILD_CACHE_DIR, 'code-keyword.json'))
+    module_map = load_json(os.path.join(BUILD_CACHE_DIR, 'code-stats.json'))
 
     mapping = {'prd_to_code': {}, 'code_to_prd': {}}
 
@@ -691,7 +692,7 @@ def build_prd_code_mapping():
             if prd_file not in mapping['code_to_prd'][f]:
                 mapping['code_to_prd'][f].append(prd_file)
 
-    save_json(os.path.join(INDEX_DIR, 'prd-code-map.json'), mapping)
+    save_json(os.path.join(BUILD_CACHE_DIR, 'prd-code-map.json'), mapping)
 
     print(f'  PRD -> Code: {len(mapping["prd_to_code"])} PRDs mapped')
     print(f'  Code -> PRD: {len(mapping["code_to_prd"])} files with PRD links')
@@ -769,6 +770,17 @@ def main():
         if _n:
             print('  cache cleanup: %d stale files removed' % _n)
 
+    # Step 7: Generate DESIGN.md (AI prototype design system reference)
+    # 索引变了 → DESIGN.md 必须重新生成, 保证 AI 读到的风格规范是最新的
+    try:
+        import subprocess as _sp
+        _dd = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'gen_design_doc.py')
+        if os.path.isfile(_dd):
+            _sp.run([sys.executable, _dd], cwd=str(BASE), capture_output=True, timeout=30)
+            print('  DESIGN.md regenerated (AI prototype reference)')
+    except Exception:
+        pass  # 生成失败不阻塞索引更新
+
     print('\n' + '=' * 50)
     print('Update complete!')
     print('=' * 50)