Files

T

JCAI Main AgentandClaude Opus 5 7cd664af3a M0: 工作区骨架 + 五道门禁 + 环境自举

- pnpm workspaces / tsconfig 双工程(node · web)/ 路径别名(§11.1)
- eslint flat(§11.3 + §12.5 可机检项)/ dependency-cruiser 基线八条 + JCAI 增补(§11.4)
- tools/module-tiers.json + gen-depcruise-tiers.ts 生成 tier-order 逐层规则
- tools/api-report.mjs 契约快照只留契约面(ADR-005)
- docker-compose(PG16)+ db/init 四 schema;种子数据五岗位五员工冻结为常量
- docs/debt.md · docs/adr/ADR-005

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KeDBx2PHLavbURXB8LJJ7m

2026-07-27 00:18:58 +08:00

2.5 KiB

Raw Blame History

ADR-005 · 工具链与门禁的落地形态

状态:已决(M0)
日期:2026-07-27
上下文:编码规范 §11 规定五道门禁(tsc / eslint / depcruise / api-report / test)必须存在且可执行, 但未规定 TypeScript 的运行与产出形态。§1 表内已定案的构建件只有 Vite(前端)与 tsup(§8.2 活动编译预设)。

决定

后端不引新的 TS 运行器。apps/api 以 tsup(§8.2 已定案的表内件,esbuild 内核,原生解析 tsconfig paths) 打包为 ESM 后由 Node 22+ 直跑;开发期 tsup --watch --onSuccess node dist/main.js。不引入 tsx / ts-node / swc 等表外依赖(§12.5#3)。
tsc 分两个工程:tsconfig.node.json(api / packages / activities / tools,lib ES2023)与 tsconfig.web.json(web / ui-kit,lib DOM + jsx)。二者共享 tsconfig.base.json 的严格开关与 §11.1 规定的 paths。根 tsconfig.json 只做 solution 引用。理由:一份 tsconfig 同时挂 DOM 与 Node 全局会让 §9.2「组件内禁裸 fetch」之类的门禁失去类型依据。
契约快照的范围(tools/api-report.mjs):tsc --emitDeclarationOnly 出全量声明后, 只保留契约面落 api-report/ —— packages/contracts/**、各 packages/<pkg>/src/index.d.ts、各 apps/api/src/modules/<m>/{index,contract,port}.d.ts。由此「改 internal/ 时 api-report 纹丝不动」(§11.5)成立。配套纪律:模块出口的公开签名必须由 contract.ts / port.ts 的显式类型承载, 不得依赖 internal/ 的推断类型泄漏(由 explicit-module-boundary-types 在 modules/ 下强制)。
§11.2 的解析层封装采用双保险:每个后端模块带 workspace package.json(exports 只开 index.ts), 同时保留 §11.1 的 @modules/* 路径别名;穿透 internal/ 的拦截由 ESLint no-restricted-imports 与 depcruise no-cross-module-internal 两道机检承担(§11.3 / §11.4)。
tier-order 生成物入库:tools/depcruise-tiers.generated.cjs 由 tools/gen-depcruise-tiers.ts 从 tools/module-tiers.json 生成并提交,pnpm gates 首步重新生成 —— 层级表与门禁的漂移在 diff 上可见。

后果

表外依赖为零;门禁全部可离线执行。
后端产物是打好的 bundle,栈帧靠 sourcemap 还原。
no-orphans 对契约面(index / contract / port)、app/、activities/、tools/ 与测试放行—— 这些是合法的无入边文件;其余孤儿一律 error。

2.5 KiB Raw Blame History

ADR-005 · 工具链与门禁的落地形态

决定

后果

2.5 KiB

Raw Blame History