WMS_MAIN/script/method-doc-create.cjs

110 lines
4.0 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

'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));