购物车模板开发文档

目录结构

public/template/cart/{模板标识}/
├── {模板标识}.php               # 模板配置文件（必需）
├── cart.html                   # 商品列表页（必需）
├── product.html                # 商品详情页（必需）
├── header.html                 # 公共头部（可选）
├── footer.html                 # 公共底部（可选）
├── xxx.html                    # 自定义页面（可选）
└── assets/                     # 静态资源（可选）
    ├── css/
    ├── js/
    └── images/

核心文件说明

1. {模板标识}.php

<?php

function {模板标识}_MetaData()
{
    return [
        "DisplayName" => "模板显示名称",
        "APIVersion"  => "1.0.0",
        "HelpDoc"     => "http://example.com"
    ];
}

function {模板标识}_ConfigOptions()
{
    return [
        // 单行文本
        [
            'key'     => 'nav_title',
            'title'   => '导航标题',
            'type'    => 'input',
            'default' => '',
            'options' => [],
            'tip'     => '显示在导航栏的标题',
        ],
        // 下拉选择
        [
            'key'     => 'theme_color',
            'title'   => '主题颜色',
            'type'    => 'select',
            'default' => 'blue',
            'options' => [
                'blue'   => '蓝色主题',
                'red'    => '红色主题',
                'dark'   => '深色主题',
            ],
            'tip'     => '选择站点配色风格',
        ],
    ];
}

function {模板标识}_CartArea()
{
    return [
        // 单行文本
        [
            'key'     => 'product_slogan',
            'title'   => '产品标语',
            'type'    => 'input',
            'default' => '',
            'options' => [],
            'tip'     => '显示在商品名称下方的简短标语',
        ],
        // 下拉选择
        [
            'key'     => 'recommend_level',
            'title'   => '推荐等级',
            'type'    => 'select',
            'default' => 'normal',
            'options' => [
                'normal'   => '普通',
                'hot'      => '热销',
                'new'      => '新品',
            ],
            'tip'     => '商品标签展示级别',
        ],
    ];
}

配置访问：

{$config.cart.xxx} - ConfigOptions 配置
{$meta.xxx} - CartArea 扩展字段

字段类型：

类型	说明
`input`	单行文本
`textarea`	多行文本
`select`	下拉选择

2. 页面文件

cart.html - 商品列表页

路由：/cart

可用变量：

变量	类型	说明
`$site`	Array	站点信息
`$config`	Array	模板配置
`$user`	Array	当前用户
`$products`	Object	商品分页数据
`$topList`	Array	商品分类树
`$groupId`	Int	当前分类ID
`$keyword`	String	搜索关键词
`$sort`	String	排序方式

商品数据结构：

$p = [
    'id'            => 1,
    'product_name'  => '商品名称',
    'product_desc'  => '商品描述',
    'billing_type'  => 'cycle',  // free/oneoff/cycle
    'price_matrix'  => [
        'first_original' => 100.00,
        'first_discount' => 80.00,
        'first_cycle_txt'=> '月',
    ],
];

排序参数：

值	说明
`weigh`	综合排序（默认）
`new`	最新上架
`price_asc`	价格从低到高
`price_desc`	价格从高到低

product.html - 商品详情页

路由：/cart/product/{id}

可用变量：

变量	类型	说明
`$product`	Array	商品详细信息
`$price`	Array	价格配置信息
`$meta`	Array	商品扩展字段值
`$metaList`	Array	商品配置项列表

价格结构：

$price = [
    'type'            => 'cycle',  // free/oneoff/cycle
    'oneoff_original' => 100.00,
    'oneoff_discount' => '80.00',
    'cycles'          => [
        '1M'  => 10.00,
        '3M'  => 27.00,
        '6M'  => 50.00,
        '1Y'  => 90.00,
    ],
    'cycles_discount' => [
        '1M'  => '',
        '3M'  => '25.00',
        '6M'  => '',
        '1Y'  => '80.00',
    ],
];

配置项结构：

$metaList = [
    [
        'meta_key'    => 'os',
        'title'       => '操作系统',
        'value_type'  => 'select',  // select/switch/text/number
        'required'    => 1,
        'option_list' => ['CentOS', 'Ubuntu', 'Windows'],
        'meta_value'  => '',
        'prompt'      => '请选择操作系统',
    ],
];

创建订单 API：

fetch('/api/order/createProductOrder', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        product_id: '商品ID',
        period_key: '周期标识（如：1M, 3M, oneoff, free）',
        meta: {
            'os': 'CentOS',
            'hostname': 'myserver'
        }
    })
})
.then(res => res.json())
.then(json => {
    if (json.code === 1) {
        location.href = json.data.jump_url;
    } else {
        console.log(json.msg);
    }
});

响应说明：

code === 1：订单创建成功，data.jump_url 为跳转地址
msg 包含 "手机认证"/"绑定手机"：需要绑定手机
msg 包含 "实名认证"：需要实名认证

4. 辅助文件

header.html / footer.html

引用：{include file='cart/{模板标识}/header' /}

可用变量：$_h, $site, $config, $user, $topList

自定义页面

路由：/cart/page/{xxx} → xxx.html

5. 开发规范

文件命名

必需：{模板标识}.php, cart.html, product.html
小写字母，- 或 _ 分隔

页面结构

{php}
$_h['title'] = '页面标题';
{/php}
{include file='cart/{标识}/header' /}
<!-- 页面内容 -->
{include file="cart/{标识}/footer" /}

资源引用

路径：/template/cart/{标识}/assets/...
CSS 放 header，JS 放 footer

6. 模板语法

<!-- 变量 -->
{$var}

<!-- 条件 -->
{if $condition}...{else}...{/if}

<!-- 循环 -->
{volist name="list" id="item"}...{/volist}

<!-- 引入 -->
{include file='cart/{标识}/header' /}

<!-- 过滤器 -->
{$var|htmlspecialchars|date='Y-m-d'}

7. 调试

{php}var_dump($product);{/php}