Files
dacli/src/commands/app/context.ts
T

275 lines
11 KiB
TypeScript

/**
* commands/app/context.ts — `dacli app context`
*
* AI 环境快照 (P0.1, 详见 doc/ai-optimization-plan.md §2.1 + doc/ai-error-analysis.md §B)
*
* 设计要点:
* - 单次调用产出 AI 干活的最小依赖集: dbLinkId / 已有 enCode / 草稿 vs 发布 / 已有表 / 菜单 / token 状态
* - 内部直接调 JnpfClient.get/postJson, 不 shell out 调子命令
* - 失败容错: form/dm/menu 任一 API 失败时不抛错, 仅写入 warnings, 其他部分继续输出
* - --json 走单行 JSON (AI 友好, 不带换行缩进)
*
* 输出接口: src/core/types.ts AppContext
*/
import { Command } from 'commander'
import { JnpfClient } from '../../core/client.ts'
import { installAiHelpHook } from '../../core/help.ts'
import { log } from '../../core/log.ts'
import { loadToken } from '../../core/config.ts'
import type { AppContext, FormSummary } from '../../core/types.ts'
import {
checkSystemExists,
formatSystemMissingHint,
} from './_check_system.ts'
// 复用 cli.ts 的 VERSION 常量 — 避免重复硬编码, 也避免外部依赖 (cat package.json)
// 路径相对 src/commands/app/context.ts → ../../../src/cli.ts
// 不直接 import cli.ts 是为避免循环依赖 (cli.ts 启动时 import 各 command)
// 用 fileURL + 文本扫描 + 正则提 VERSION
import { readFileSync } from 'node:fs'
import { fileURLToPath } from 'node:url'
import { dirname, resolve } from 'node:path'
const PAGE_SIZE = 500 // 一次拉完, 避免分页遗漏
interface ContextOpts {
json?: boolean
app?: string
}
/** 从 src/cli.ts 源码中提取 const VERSION = '...' */
function readCliVersion(): string {
try {
const here = dirname(fileURLToPath(import.meta.url))
// src/commands/app/context.ts → src/cli.ts
const cliPath = resolve(here, '../../cli.ts')
const src = readFileSync(cliPath, 'utf-8')
const m = src.match(/const\s+VERSION\s*=\s*['"]([^'"]+)['"]/)
return m?.[1] || 'unknown'
} catch {
return 'unknown'
}
}
/** token 7 天过期 (与 JNPF 后端一致, 详见 doc/jnpf-token-expiry.md) */
function calcTokenExpiry(loginAt?: string): string | undefined {
if (!loginAt) return undefined
try {
const t = new Date(loginAt)
t.setUTCDate(t.getUTCDate() + 7)
return t.toISOString()
} catch {
return undefined
}
}
/**
* P1.2: 公开的 AppContext 加载函数 (供 pre-check 等复用)
*
* 设计: 拉 token → 构造 client → 拉 form/dm/menu → 组装 AppContext
* 失败容错: 任何 API 失败写入 warnings, 不抛错
* 不抛异常, 失败尽量返回部分填充的对象 + warnings
*/
export async function loadAppContext(opts?: { appCode?: string }): Promise<AppContext> {
const cached = loadToken()
const appCode = opts?.appCode || cached?.appCode || ''
const dbLinkId = cached?.dbLinkId || ''
const tokenStatus: AppContext['tokenStatus'] = cached ? 'valid' : 'expired'
const tokenExpiry = calcTokenExpiry(cached?.loginAt)
const warnings: string[] = []
let forms: FormSummary[] = []
let tables: string[] = []
let menus: string[] = []
let systemExists: boolean | null | undefined = undefined
let systemMissingError: string | undefined = undefined
try {
const c = await JnpfClient.fromToken(opts?.appCode ? { appCode: opts.appCode } : {})
if (opts?.appCode) c.appCode = opts.appCode
// v0.11e+ Phase E: 早期检测 base_system 缺失, 避免后续 form/dm/menu 返间接错误
// (P0 经验: dacli app clear 后, 旧版返 'System abnormality' / 'No permission',
// 用户以为是 token 问题, 实际是 app 不存在)
if (appCode) {
systemExists = await checkSystemExists(c, appCode)
if (systemExists === false) {
const hint = formatSystemMissingHint(appCode, cached?.appName)
warnings.push(hint)
systemMissingError = hint
}
}
const f = await tryFetchForms(c)
forms = f.forms
if (f.warning) warnings.push(f.warning)
const t = await tryFetchTables(c)
tables = t.tables
if (t.warning) warnings.push(t.warning)
const m = await tryFetchMenus(c)
menus = m.menus
if (m.warning) warnings.push(m.warning)
} catch (e) {
warnings.push(`client 初始化失败: ${(e as Error).message}`)
}
const existingEnCodes = Array.from(
new Set(forms.map((f) => f.enCode).filter((s): s is string => !!s)),
)
const unreleasedForms = forms
.filter((f) => f.state === 0)
.map((f) => `${f.id}:${f.enCode || '(no-enCode)'}`)
const releasedForms = forms
.filter((f) => f.state === 1)
.map((f) => `${f.id}:${f.enCode || '(no-enCode)'}`)
// BS-53 (2026-06-23): 收集 state=2 — 发布后被编辑过, 前端 web 看不到直到 re-release.
// JNPF 后端 VisualdevController#update line 488-491 已发布表单被 PUT 自动 state 1→2.
// dacli form update 等 PUT 类命令触发. 现象: 用户实测表单"空白/无按钮"但
// summary.html 误写 "Form state=1 ✅" (实际全部 state=2).
const modifiedAfterPublishForms = forms
.filter((f) => f.state === 2)
.map((f) => `${f.id}:${f.enCode || '(no-enCode)'}`)
return {
appCode,
dbLinkId,
tokenStatus,
tokenExpiry,
existingEnCodes,
unreleasedForms,
releasedForms,
modifiedAfterPublishForms,
existingTables: tables,
menus,
currentVersion: readCliVersion(),
warnings,
systemExists,
error: systemMissingError,
}
}
/** 安全拉 form list — 失败返回 null + 警告 */
async function tryFetchForms(c: JnpfClient): Promise<{ forms: FormSummary[]; warning?: string }> {
try {
const r = await c.get<{ list: FormSummary[]; pagination?: { total: number } }>('/visualdev/Base', {
currentPage: 1,
pageSize: PAGE_SIZE,
})
if (r.code !== 200) {
return { forms: [], warning: `form list 失败 (code=${r.code}): ${r.msg}` }
}
return { forms: r.data?.list || [] }
} catch (e) {
return { forms: [], warning: `form list 异常: ${(e as Error).message}` }
}
}
/** 安全拉 dm list — 失败返回 null + 警告 */
async function tryFetchTables(
c: JnpfClient,
): Promise<{ tables: string[]; warning?: string }> {
try {
const dbLinkId = c.dbLinkId || '0'
const r = await c.get<{ list: { table: string }[] }>(
`/system/DataModel/${dbLinkId}/Tables`,
{ currentPage: 1, pageSize: PAGE_SIZE },
)
if (r.code !== 200) {
return { tables: [], warning: `dm list 失败 (code=${r.code}): ${r.msg}` }
}
const list = r.data?.list || []
return { tables: list.map((t) => t.table) }
} catch (e) {
return { tables: [], warning: `dm list 异常: ${(e as Error).message}` }
}
}
/** 安全拉 menu list — 失败返回 null + 警告 */
async function tryFetchMenus(
c: JnpfClient,
): Promise<{ menus: string[]; warning?: string }> {
try {
const r = await c.get<unknown>('/system/Menu/ModuleBySystem')
if (r.code !== 200) {
return { menus: [], warning: `menu list 失败 (code=${r.code}): ${r.msg}` }
}
const list = (Array.isArray(r.data) ? r.data : (r.data as { list?: unknown[] })?.list) || []
const encs = (list as Array<{ enCode?: string }>).map((m) => m.enCode).filter((s): s is string => !!s)
return { menus: encs }
} catch (e) {
return { menus: [], warning: `menu list 异常: ${(e as Error).message}` }
}
}
export function buildAppContextCommand(): Command {
const cmd = new Command('context')
.description('输出当前应用环境快照 (dbLinkId/enCode/表/菜单/token 状态). AI 新会话第一步先跑此命令.')
.option('--json', '单行 JSON 输出 (AI 友好)', false)
.option('--app <appCode>', '覆盖 token 中的 appCode (供快速切换测试)')
.action(async (opts: ContextOpts) => {
// P1.2: 复用 loadAppContext 提取的核心采集逻辑
const ctx = await loadAppContext(opts.app ? { appCode: opts.app } : undefined)
// v0.11e+ Phase E: system 缺失时退出码 2 (AI/脚本可据此停下, 不要继续 CRUD)
// 仍输出 JSON 便于消费方诊断
const exitCode = ctx.systemExists === false ? 2 : 0
// 输出
if (opts.json) {
// 单行 JSON (AI 友好, 便于 grep/管道)
console.log(JSON.stringify(ctx))
if (exitCode !== 0) process.exit(exitCode)
return
}
// 人读友好模式
if (ctx.systemExists === false) {
log.error(`appCode=${ctx.appCode} 在 base_system 不存在`)
log.warn(` 可能原因: 该应用已被删除 (dacli app clear --app-code=${ctx.appCode}), 或 DB 还原失败`)
log.info(` 重建命令: dacli app create --appCode=${ctx.appCode} --appName="未知应用"`)
log.info(` 自动恢复: dacli app init --appCode=${ctx.appCode} --auto-recover (v0.11e+, 自动重建+重登)`)
log.dim(` ↑ 不要继续 form/menu CRUD, 会触发后端 NPE (Phase 4 复盘 2026-06-27)`)
process.exit(exitCode)
}
log.info(`app : ${ctx.appCode || '(未登录)'}`)
log.info(`dbLinkId: ${ctx.dbLinkId || '(unknown)'}`)
log.info(`token : ${ctx.tokenStatus}${ctx.tokenExpiry ? ' (expires ' + ctx.tokenExpiry + ')' : ''}`)
log.info(`version : ${ctx.currentVersion}`)
log.info(`enCodes : ${ctx.existingEnCodes.length} 个`)
log.info(`forms : ${ctx.releasedForms.length} 发布 / ${ctx.modifiedAfterPublishForms.length} 待重发布 / ${ctx.unreleasedForms.length} 草稿`)
log.info(`tables : ${ctx.existingTables.length} 张`)
log.info(`menus : ${ctx.menus.length} 个`)
if (ctx.warnings.length) {
log.warn(`采集警告 ${ctx.warnings.length} 条:`)
for (const w of ctx.warnings) log.dim(` - ${w}`)
}
})
installAiHelpHook(cmd, {
purpose:
'输出当前应用环境快照 (appCode/dbLinkId/token 状态/enCode/表/菜单). ' +
'AI 新会话第一步先跑此命令, 所有参数从此快照取, 不要猜测.',
optional: {
'--json': '单行 JSON 输出 (推荐 AI 使用)',
'--app': '覆盖 token 中的 appCode (供快速切换测试)',
},
example: ['dacli app context --json', 'dacli app context --app=tds --json'],
source: {
api: 'GET /api/visualdev/Base, /api/system/DataModel/{dbLinkId}/Tables, /api/system/Menu/ModuleBySystem',
ref: 'doc/ai-optimization-plan.md §2.1, doc/ai-error-analysis.md §B',
},
notes: [
'AI 新会话第一步先跑此命令',
'所有参数从此快照取, 不要猜测 (尤其 dbLinkId / enCode 唯一性 / 表存在性)',
'输出含 warnings 字段: 任一 API 失败时会填入, AI 据此判断上下文是否完整',
'**v0.11e+ Phase E**: 检测 base_system 是否含 appCode, 缺失时 systemExists=false + error 含重建命令 + 退出码 2',
' (修复盲点: dacli app clear 后旧版返间接错误 "System abnormality"/"No permission" 误导用户)',
],
})
return cmd
}