文档模式前端：目录树展示方案演进说明

文档概述

本文档说明企业文档管理系统中目录树展示功能从依赖分类信息到基于标签系统 + 置顶帖配置的完整演进过程。

---

一、原始方案：依赖分类信息

1.1 方案描述

最初的目录树展示依赖于 Discuz 论坛的分类信息体系，通过版块的分类结构来组织文档目录。

1.2 存在的问题

1. 灵活性差：目录结构受限于版块分类，无法跨版块组织文档
2. 维护成本高：每次调整目录结构需要修改版块分类设置
3. 粒度粗糙：分类层级有限，难以满足复杂文档体系需求
4. 帖子归属单一：一个帖子只能属于一个分类，无法多维度归类

---

二、过渡方案：标签系统 + 文字路径配置

2.1 方案核心

引入标签系统，通过帖子标签与置顶配置帖配合，实现目录树的灵活配置。

2.2 配置格式

[doc_directory]
开发维护 = 网站开发维护.98
开发维护/社创开发 = 社创官网和社区开发.1
开发维护/利智官网 = 北京利智官网.2

[posts]
社创开发 = tid:118,tid:140,tid:137
[/posts]
[/doc_directory]

2.3 帖子标签

#目录_社创开发
#目录_开发维护

2.4 技术实现

2.4.1 标签解析函数

function extract_directory_tags($tags_str) {
    $dir_names = array();
    preg_match_all('/#目录_([^#,\s]+)/', $tags_str, $matches);
    if($matches[1]) {
        foreach($matches[1] as $name) {
            // 将路径分隔符统一转换为点号
            $name = preg_replace('/[\/\-、]/', '.', $name);
            $dir_names[] = $name;
        }
    }
    return $dir_names;
}

2.4.2 配置帖解析

function parse_config_message($message) {
    $config = array(
        'directories' => array(),
        'posts' => array()
    );

    // 解析 [doc_directory] 标签
    if(preg_match('/\[doc_directory\](.*?)\[\/doc_directory\]/s', $message, $matches)) {
        $content = $matches[1];
        // 解析目录定义
        preg_match_all('/^([^=\n]+)\s*=\s*([^.\n]+)\.(\d+)/m', $content, $dir_matches);
        // ...
    }

    // 解析 [posts] 标签
    if(preg_match('/\[posts\](.*?)\[\/posts\]/s', $content, $posts_matches)) {
        // ...
    }

    return $config;
}

2.4.3 目录树构建

function build_directory_tree(&$choices, $dir_path, $thread, $sort_order = 0) {
    $parts = explode('/', $dir_path);
    $current = &$choices;
    $num_path = '';

    foreach($parts as $index => $part) {
        $num = $index + 1;
        $num_path .= ($num_path ? '.' : '') . $num;
        // 创建目录节点
        // ...
        $current = &$current[$num_path]['list'];
    }

    // 添加帖子
    $current[$thread_key] = array(...);
}

2.5 方案局限性

1. 配置复杂：目录路径使用文字路径（如 开发维护/社创开发），层级关系不够直观
2. 匹配逻辑复杂：需要通过 find_dir_path_by_name 函数根据标签名反查完整路径
3. 排序依赖 [posts]：帖子排序完全依赖 [posts] 段落配置，不够灵活
4. 标签路径限制：标签名长度有限制，不适合配置过长的路径

---

三、优化方案：标签系统 + 序号配置

3.1 方案核心

采用序号路径代替文字路径，配置格式更加简洁清晰，目录层级由序号直接决定。

3.2 配置格式（新）

[doc_directory]
1 = 开发维护 = 网站开发维护
1-1 = 社创开发 = 社创官网和社区开发
1-2 = 利智官网 = 北京利智官网
1-3 = 社通活动宝 = 活动工具社通活动宝
2 = 产品文档 = 产品相关文档
2-1 = 用户手册 = 用户使用手册

[posts]
社创开发 = tid:118,tid:140,tid:137
[/posts]
[/doc_directory]

3.3 配置格式说明

部分	格式	说明
目录定义	序号 = 标签名 = 目录显示名	序号决定层级和排序
帖子排序	标签名 = tid:xxx,tid:yyy	可选，用于同标签下帖子排序

3.4 帖子标签（简化）

帖子只需要添加单层标签即可：

#目录_社创开发
#目录_开发维护
#目录_利智官网

3.5 技术实现

3.5.1 新格式解析

function parse_config_message($message) {
    $config = array(
        'directories' => array(),
        'posts' => array()
    );

    if(preg_match('/\[doc_directory\](.*?)\[\/doc_directory\]/s', $message, $matches)) {
        $content = $matches[1];

        // 新格式：序号 = 标签名 = 目录名
        preg_match_all('/^([\d\-]+)\s*=\s*([^=]+)\s*=\s*(.+)$/m', $content, $new_matches);
        if($new_matches[1]) {
            foreach($new_matches[1] as $index => $num_path) {
                $num_path = trim($new_matches[1][$index]);
                $tag_name = trim($new_matches[2][$index]);
                $dir_name = trim($new_matches[3][$index]);

                $config['directories'][$num_path] = array(
                    'tag_name' => $tag_name,      // 标签名称（用于匹配帖子）
                    'name' => $dir_name,          // 目录显示名称
                    'sort_order' => $index,       // 排序
                    'is_new_format' => true
                );
            }
        }
    }

    return $config;
}

3.5.2 标签匹配序号路径

function find_num_path_by_tag($directory_config, $tag_name) {
    foreach($directory_config['directories'] as $num_path => $config) {
        if($config['tag_name'] == $tag_name) {
            return $num_path;
        }
    }
    return '';
}

3.5.3 序号目录树构建

function create_directory_node_new(&$choices, $num_path, $name) {
    // 将 1-1-1 转换为数组 [1, 1, 1]
    $parts = explode('-', $num_path);
    $current = &$choices;
    $key_path = '';
    $num_path_dot = '';

    foreach($parts as $index => $part) {
        $key_path .= ($key_path ? '-' : '') . $part;
        $num_path_dot .= ($num_path_dot ? '.' : '') . $part;

        if(!isset($current[$num_path_dot])) {
            $current[$num_path_dot] = array(
                'key' => $key_path,
                'num' => $num_path_dot,
                'level' => $index + 1,
                'name' => $name,
                'type' => 'directory',
                'href' => generate_dir_link($num_path_dot),
                'list' => array(),
                'sort_order' => $index
            );
        }
        $current = &$current[$num_path_dot]['list'];
    }
}

3.5.4 帖子添加到目录

function add_thread_to_directory_new(&$choices, $num_path, $thread, $sort_order = 0) {
    $parts = explode('-', $num_path);
    $current = &$choices;
    $num_path_dot = implode('.', $parts);

    // 导航到最后的目录
    foreach($parts as $index => $part) {
        $path = implode('.', array_slice($parts, 0, $index + 1));
        if(isset($current[$path])) {
            $current = &$current[$path]['list'];
        } else {
            return; // 目录不存在，跳过
        }
    }

    // 添加帖子
    $thread_key = 'tid_' . $thread['tid'];
    if(!isset($current[$thread_key])) {
        $current[$thread_key] = array(
            'key' => $thread_key,
            'num' => $thread['tid'],
            'name' => $thread['subject'],
            'type' => 'thread',
            'href' => generate_thread_link($thread['tid']),
            'list' => array(),
            'sort_order' => $sort_order
        );
    }
}

3.6 方案优势

对比项	过渡方案	优化方案
配置格式	文字路径（开发维护/社创开发）	序号路径（1-1）
层级关系	需要通过 / 解析	直接通过 - 体现
标签要求	可使用单层或完整路径	仅需单层标签
匹配逻辑	需要反查路径	直接通过标签名匹配
目录排序	依赖配置顺序	序号自动决定
可维护性	较复杂	简洁清晰
扩展性	调整结构需修改多处	调整序号即可

3.7 目录层级示例

配置：
1 = 开发维护 = 网站开发维护
1-1 = 社创开发 = 社创官网和社区开发
1-1-1 = 前端开发 = 前端相关开发文档
1-2 = 利智官网 = 北京利智官网
2 = 产品文档 = 产品相关文档

生成的目录树：
├── 1. 网站开发维护
│   ├── 1.1 社创官网和社区开发
│   │   └── 1.1.1 前端开发
│   └── 1.2 北京利智官网
└── 2. 产品相关文档

---

四、两种格式兼容

4.1 自动识别机制

系统会自动识别配置格式，新格式优先：

// 检查是否使用新格式
$is_new_format = false;
foreach($directory_config['directories'] as $num_path => $config) {
    if(!empty($config['is_new_format'])) {
        $is_new_format = true;
        break;
    }
}

if($is_new_format) {
    // 新格式处理
} else {
    // 旧格式处理（兼容）
}

4.2 迁移建议

1. 新配置推荐使用新格式：序号配置更清晰易维护
2. 旧配置可逐步迁移：两种格式兼容，不影响现有功能
3. 混合使用不建议：同一配置帖中建议只使用一种格式

---

五、核心数据流

┌─────────────────────────────────────────────────────────────┐
│                       用户发帖/编辑                           │
│              添加标签：#目录_社创开发                           │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Discuz 标签系统                            │
│         pre_common_tag + pre_common_tagitem                 │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   置顶配置帖 [DIR]                            │
│  [doc_directory] 定义目录结构和序号                            │
│  [posts] 定义帖子排序（可选）                                  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  directory_tree.php                         │
│  1. parse_directory_config() - 解析配置帖                     │
│  2. get_directory_threads() - 获取带标签帖子                  │
│  3. find_num_path_by_tag() - 标签匹配序号                      │
│  4. create_directory_node_new() - 构建目录树                  │
│  5. add_thread_to_directory_new() - 添加帖子                  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    $flquery 全局变量                          │
│         包含完整的目录树结构（choices 数组）                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      模板文件渲染                             │
│            forumdisplay.htm / viewthread.htm                 │
│                   循环输出目录树                              │
└─────────────────────────────────────────────────────────────┘

---

六、文件清单

文件路径	说明	备注
template/xmyc_doc/php/directory_tree.php	PC 版目录树生成	核心逻辑
template/xmyc_touch_doc/touch/php/directory_tree.php	移动版目录树生成	核心逻辑
template/xmyc_doc/forum/forumdisplay.htm	PC 版版块列表页	目录树展示
template/xmyc_touch_doc/touch/forum/forumdisplay.htm	移动版版块列表页	目录树展示
template/xmyc_doc/static/js/tree.js	PC 版树形菜单 JS	折叠展开
template/xmyc_touch_doc/static/js/tree.js	移动版树形菜单 JS	折叠展开

---

七、总结

从依赖分类信息到标签系统 + 置顶帖配置，目录树展示方案经历了以下演进：

1. 解耦合：不再依赖 Discuz 版块分类，实现跨版块文档组织
2. 灵活性：通过标签和配置实现多维度文档归类
3. 可维护性：序号配置格式简洁直观，易于维护
4. 兼容性：新旧格式兼容，平滑迁移

优化后的方案核心特点：

• 配置简单：序号 = 标签名 = 目录名 三要素清晰明了
• 标签简洁：帖子只需单层标签，降低维护成本
• 层级清晰：序号直接体现目录层级关系
• 扩展容易：调整序号即可改变目录结构

---

文档版本：1.0
更新日期：2026-02-28