'use strict'; /** * 新建 API 方法文档(写入 wms_api_method_doc;建议完成后执行 method-doc-export.cjs 回写 methods/system.json)。 * * 用法: * node script/method-doc-create.cjs --method wechat.xxx --module wechat --group 微信模块 \ * --description "接口说明" [--login 1] [--auth 0] \ * [--headers @h.json] [--params @p.json] [--response @r.json] [--errors @e.json] \ * [--bump] [--doc system] [--env production] * * JSON 字段支持内联 JSON 或 @文件路径;--bump 时文档版本补丁位 +1 并更新 updatedAt。 */ const { resolveEnv, createConnection, parseArgs, readJsonArg, bumpVersion, today, fail, } = require('./method-doc-common.cjs'); (async () => { const args = parseArgs(); const env = resolveEnv(); const docName = args.get('doc') || 'system'; const method = args.get('method'); const module = args.get('module'); if (!method) fail('缺少 --method(方法名,如 wechat.xxx)'); if (!module) fail('缺少 --module(模块标识,如 wechat)'); const groupName = args.get('group') || ''; const description = args.get('description') || ''; const isNeedLogin = String(args.get('login') || '1') === '1' ? 1 : 0; const isNeedAuth = String(args.get('auth') || '0') === '1' ? 1 : 0; const headers = readJsonArg(args.get('headers')); const params = readJsonArg(args.get('params')); const response = readJsonArg(args.get('response')); const errors = readJsonArg(args.get('errors')); const bump = args.has('bump'); const conn = await createConnection(env); // 排序:同 module+group 沿用其 group_sort;否则取全局最大 group_sort+1 const [ groupRows ] = await conn.query( 'SELECT group_sort FROM wms_api_method_doc WHERE module=? AND group_name=? ORDER BY group_sort DESC LIMIT 1', [ module, groupName ] ); let groupSort; if (groupRows[0]) { groupSort = Number(groupRows[0].group_sort); } else { const [ maxRows ] = await conn.query('SELECT COALESCE(MAX(group_sort),0) AS m FROM wms_api_method_doc'); groupSort = Number(maxRows[0].m) + 1; } const [ itemRows ] = await conn.query( 'SELECT COALESCE(MAX(item_sort),0) AS m FROM wms_api_method_doc WHERE module=? AND group_name=?', [ module, groupName ] ); const itemSort = Number(itemRows[0].m) + 1; const item = { method, description, isNeedAuth: isNeedAuth === 1, isNeedLogin: isNeedLogin === 1, headers: headers || [], params: params || [], response: response || [], errors: errors || [], }; try { await conn.query( `INSERT INTO wms_api_method_doc (method, module, group_name, description, is_need_login, is_need_auth, headers, params, response, errors, group_sort, item_sort, status, payload) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?)`, [ method, module, groupName, description, isNeedLogin, isNeedAuth, JSON.stringify(headers || []), JSON.stringify(params || []), JSON.stringify(response || []), JSON.stringify(errors || []), groupSort, itemSort, JSON.stringify(item), ] ); } catch (e) { if (e && e.code === 'ER_DUP_ENTRY') { await conn.end(); fail(`method 已存在(${method}),请用 method-doc-update.cjs 更新`); } throw e; } if (bump) { const [ metaRows ] = await conn.query('SELECT version FROM wms_method_doc_meta WHERE doc_name=?', [ docName ]); const next = bumpVersion(metaRows[0] ? metaRows[0].version : '0.3.0'); await conn.query('UPDATE wms_method_doc_meta SET version=?, updated_at=? WHERE doc_name=?', [ next, today(), docName ]); console.log(`[method-doc] 文档版本已升至 ${next}`); } await conn.end(); console.log(`[method-doc] 已创建:${method}(module=${module} group=${groupName || '(空)'} sort=${groupSort}/${itemSort}${bump ? '' : ',未 --bump 版本未变'})(env=${env})`); })().catch(e => fail(e.message));