scaffold-engine 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# Scaffold Monorepo
+
+多项目 monorepo 脚手架，包含 **api**、**admin**、**mobile**、**shared**、**shared-auth**。
+
+## 快速启动
+
+```bash
+# 1. 进入 scaffold 目录
+cd scaffold
+
+# 2. 安装依赖（首次或依赖变更后）
+pnpm install
+
+# 3. 初始化数据库（首次）
+pnpm init-db
+
+# 4. 启动 API 服务
+pnpm dev:api
+```
+
+**启动成功后访问：**
+- API 服务: http://localhost:3001
+- API 文档: http://localhost:3001/api
+
+**测试登录：**
+```bash
+curl -X POST http://localhost:3001/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin123"}'
+```
+
+## 目录结构
+
+```
+scaffold/
+├── packages/
+│   ├── api          # 后端 API（aiko-boot，当前实现用户登录）
+│   ├── shared       # 公共常量（API 基地址、存储 key 等）
+│   ├── shared-auth  # 前端鉴权公共模块（AuthProvider、useAuth、登录态持久化）
+│   ├── admin        # 管理端（Vite + React，共用 shared-auth 登录）
+│   └── mobile       # 移动端 H5（Next.js，共用 shared-auth 登录）
+├── docs/
+│   ├── auth-shared-design.md       # Auth 公共模块设计说明
+│   └── cli-auth-feature-boundary.md # CLI 生成时「是否需要系统功能」边界（供生成器排除登录用）
+└── package.json
+```
+
+## 只运行这一个项目
+
+可以。scaffold 依赖仓库内的 `@ai-partner-x/*` 等包，因此需要在 **ai-frist-framework 仓库内** 使用，但日常只需操作 scaffold 本身：
+
+1. 在仓库根 **执行一次** `pnpm install`（或进入 scaffold 后执行 `pnpm install`）。
+2. 之后所有开发、构建、启动都在 **scaffold 目录** 下完成，无需运行或构建仓库里其他项目（如 user-crud、其他 examples）。
+
+```bash
+cd scaffold
+pnpm init-db    # 首次
+pnpm dev        # 并行启动 api + admin + mobile
+```
+
+**测试登录**：mobile / admin 的登录页会请求 `http://localhost:3001/api/auth/login`，需先保证 API 已启动（`pnpm dev:api` 或 `pnpm dev` 已包含）。两端共用 **@scaffold/shared-auth** 的登录态与持久化（localStorage），详见 [Auth 公共模块设计](docs/auth-shared-design.md)。
+
+## 前置
+
+- Node 18+
+- pnpm
+
+**安装依赖**（在仓库根或 scaffold 目录下执行均可，会使用仓库根 workspace）：
+
+```bash
+cd /path/to/ai-frist-framework
+pnpm install
+# 或在 scaffold 目录下
+cd scaffold && pnpm install
+```
+
+`init-db` 使用纯 JS 的 sql.js，无需编译。**运行 API 服务**（`pnpm dev:api`）时依赖 better-sqlite3 原生模块；若报错找不到 bindings，在**仓库根**执行（会进入 better-sqlite3 目录执行 `node-gyp rebuild`）：
+
+```bash
+pnpm run rebuild:sqlite
+```
+
+## 开发
+
+依赖在仓库根安装完成后，在 **scaffold 目录** 下执行：
+
+```bash
+cd scaffold
+pnpm init-db    # 首次运行：初始化 SQLite 数据库
+pnpm dev        # 并行启动 api + admin + mobile
+```
+
+或分别启动：
+
+- `pnpm dev:api`    — API 默认 http://localhost:3001
+- `pnpm dev:admin`  — Admin 管理端（留空）
+- `pnpm dev:mobile` — Mobile 默认 http://localhost:3002
+
+**API 热更新**（与 user-crud 一致）：`pnpm dev:api` 会同时跑 **codegen watch** 与 **HTTP 服务**。修改 `entity/`、`dto/`、`controller/` 后会自动重新生成 `dist/client`，前端可即时引用新类型与接口；改 `src/server.ts` 会触发服务重启。
+
+## 构建
+
+```bash
+pnpm build
+# 或
+pnpm build:api
+pnpm build:admin
+pnpm build:mobile
+```
+
+## API 说明
+
+- **POST /api/auth/login**  
+  请求体：`{ "username": "admin", "password": "admin123" }`  
+  成功返回：`{ "success": true, "data": { "id", "username", "email" } }`
+
+默认测试账号（见 `packages/api` 的 init-db）：`admin` / `admin123`。

package/engine.project.example.json

@@ -0,0 +1,23 @@
+{
+  "projectRoot": "/absolute/path/to/your-empty-project",
+  "catalogs": {
+    "rootDir": "/Users/taishanglaojun/ai-frist-framework_owner/scaffold/specs/catalogs"
+  },
+  "rules": {
+    "rootDir": "/Users/taishanglaojun/ai-frist-framework_owner/scaffold/specs/rules"
+  },
+  "drafts": {
+    "rootDir": "/absolute/path/to/your-empty-project/.codex/scaffold-drafts"
+  },
+  "generatedSpecs": {
+    "rootDir": "/absolute/path/to/your-empty-project/.codex/generated-specs"
+  },
+  "targets": {
+    "adapter": "external-project",
+    "apiSrcDir": "/absolute/path/to/your-empty-project/src/generated/api",
+    "adminSrcDir": "/absolute/path/to/your-empty-project/src/generated/admin",
+    "toolCwd": "/Users/taishanglaojun/ai-frist-framework_owner/scaffold",
+    "pnpmCwd": "/Users/taishanglaojun/ai-frist-framework_owner",
+    "apiPackageDir": "/Users/taishanglaojun/ai-frist-framework_owner/scaffold/packages/api"
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "scaffold-engine",
+  "version": "0.1.0",
+  "description": "Requirement-driven scaffold engine for analyze, draft, validate, and generate workflows.",
+  "license": "MIT",
+  "main": "./tools/engine.cjs",
+  "bin": {
+    "scaffold-engine": "./tools/cli.cjs"
+  },
+  "exports": {
+    ".": "./tools/engine.cjs",
+    "./engine": "./tools/engine.cjs",
+    "./cli": "./tools/cli.cjs"
+  },
+  "files": [
+    "tools",
+    "specs",
+    "scripts/postinstall.cjs",
+    "engine.project.example.json"
+  ],
+  "keywords": [
+    "scaffold",
+    "generator",
+    "cursor",
+    "codex",
+    "requirements",
+    "cli"
+  ],
+  "scripts": {
+    "init": "node ./tools/cli.cjs init",
+    "draft:create": "node ./tools/create-draft.cjs",
+    "draft:patch": "node ./tools/patch-draft.cjs",
+    "draft:validate": "node ./tools/validate-draft.cjs",
+    "draft:generate": "node ./tools/generate-draft.cjs",
+    "requirement:analyze": "node ./tools/analyze-requirement.cjs",
+    "requirement:run": "node ./tools/run-requirement.cjs",
+    "model:validate": "node ./tools/validate-model.cjs",
+    "model:generate": "node ./tools/generate-module.cjs",
+    "verify:patterns": "node ./tools/verify-patterns.cjs"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "npm-packlist": "^9.0.0",
+    "typescript": "^5.3.0"
+  }
+}

package/scripts/postinstall.cjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require('node:child_process');
+
+function shouldSkip() {
+  if (process.env.SKIP_SQLITE_REBUILD === 'true') {
+    console.log('[postinstall] SKIP_SQLITE_REBUILD=true, skipping better-sqlite3 rebuild.');
+    return true;
+  }
+  if (process.env.CI === 'true') {
+    console.log('[postinstall] CI environment detected, skipping better-sqlite3 rebuild.');
+    return true;
+  }
+  return false;
+}
+
+function main() {
+  if (shouldSkip()) {
+    return;
+  }
+
+  const pkgManager = process.env.npm_execpath || 'pnpm';
+  console.log('[postinstall] Rebuilding better-sqlite3 via', pkgManager);
+
+  const result = spawnSync(
+    pkgManager,
+    ['rebuild', 'better-sqlite3'],
+    { stdio: 'inherit', shell: false }
+  );
+
+  if (result.error) {
+    console.warn('[postinstall] better-sqlite3 rebuild errored but is non-fatal:', result.error);
+    return;
+  }
+
+  if (result.status !== 0) {
+    console.warn('[postinstall] better-sqlite3 rebuild exited with code', result.status, '(treated as non-fatal).');
+  }
+}
+
+main();
+

package/specs/catalogs/action-templates.yaml

@@ -0,0 +1,189 @@
+templates:
+  crudBasic:
+    actions: [create, update, list, detail]
+    responseContract:
+      envelope: standard
+      listSchema: pagedList
+      detailSchema: object
+      mutationSchema: object
+    permissionProfile:
+      mode: inherit
+      resourceScope: object
+      actionPolicies:
+        - action: create
+          permission: create
+        - action: update
+          permission: update
+        - action: list
+          permission: list
+        - action: detail
+          permission: detail
+    validationRules:
+      - name: uniqueCode
+        scope: service
+        rule: unique
+        message: 编码必须唯一
+    errorCodes:
+      - code: VALIDATION_FAILED
+        message: 输入校验失败
+      - code: RECORD_NOT_FOUND
+        message: 记录不存在
+      - code: DUPLICATE_KEY
+        message: 唯一键冲突
+
+  crudWithToggle:
+    actions: [create, update, list, detail, activate, deactivate]
+    responseContract:
+      envelope: standard
+      listSchema: pagedList
+      detailSchema: object
+      mutationSchema: object
+    permissionProfile:
+      mode: inherit
+      resourceScope: object
+      actionPolicies:
+        - action: create
+          permission: create
+        - action: update
+          permission: update
+        - action: list
+          permission: list
+        - action: detail
+          permission: detail
+        - action: activate
+          permission: activate
+        - action: deactivate
+          permission: deactivate
+    statusFlow:
+      enabled: true
+      states: [draft, active, inactive]
+      transitions:
+        - action: activate
+          from: [draft, inactive]
+          to: active
+        - action: deactivate
+          from: [active]
+          to: inactive
+    validationRules:
+      - name: statusTransition
+        scope: workflow
+        rule: statusTransition
+        fields: [status]
+        message: 状态流转必须符合既定规则
+    errorCodes:
+      - code: VALIDATION_FAILED
+        message: 输入校验失败
+      - code: RECORD_NOT_FOUND
+        message: 记录不存在
+      - code: DUPLICATE_KEY
+        message: 唯一键冲突
+      - code: INVALID_STATUS_TRANSITION
+        message: 当前状态不允许执行该动作
+
+  crudWithStatusFlow:
+    actions: [create, update, list, detail, submit, approve, reject]
+    responseContract:
+      envelope: standard
+      listSchema: pagedList
+      detailSchema: object
+      mutationSchema: object
+    permissionProfile:
+      mode: inherit
+      resourceScope: object
+      actionPolicies:
+        - action: create
+          permission: create
+        - action: update
+          permission: update
+        - action: list
+          permission: list
+        - action: detail
+          permission: detail
+        - action: submit
+          permission: submit
+        - action: approve
+          permission: approve
+        - action: reject
+          permission: reject
+    statusFlow:
+      enabled: true
+      states: [draft, submitted, approved, rejected]
+      transitions:
+        - action: submit
+          from: [draft, rejected]
+          to: submitted
+        - action: approve
+          from: [submitted]
+          to: approved
+        - action: reject
+          from: [submitted]
+          to: rejected
+    validationRules:
+      - name: statusTransition
+        scope: workflow
+        rule: statusTransition
+        fields: [status]
+        message: 状态流转必须符合既定规则
+    errorCodes:
+      - code: VALIDATION_FAILED
+        message: 输入校验失败
+      - code: RECORD_NOT_FOUND
+        message: 记录不存在
+      - code: DUPLICATE_KEY
+        message: 唯一键冲突
+      - code: INVALID_STATUS_TRANSITION
+        message: 当前状态不允许执行该动作
+
+  crudWithSubmitApprove:
+    actions: [create, update, list, detail, submit, approve, reject]
+    responseContract:
+      envelope: standard
+      listSchema: pagedList
+      detailSchema: object
+      mutationSchema: object
+    permissionProfile:
+      mode: inherit
+      resourceScope: object
+      actionPolicies:
+        - action: create
+          permission: create
+        - action: update
+          permission: update
+        - action: list
+          permission: list
+        - action: detail
+          permission: detail
+        - action: submit
+          permission: submit
+        - action: approve
+          permission: approve
+        - action: reject
+          permission: reject
+    statusFlow:
+      enabled: true
+      states: [draft, submitted, approved, rejected]
+      transitions:
+        - action: submit
+          from: [draft, rejected]
+          to: submitted
+        - action: approve
+          from: [submitted]
+          to: approved
+        - action: reject
+          from: [submitted]
+          to: rejected
+    validationRules:
+      - name: statusTransition
+        scope: workflow
+        rule: statusTransition
+        fields: [status]
+        message: 状态流转必须符合既定规则
+    errorCodes:
+      - code: VALIDATION_FAILED
+        message: 输入校验失败
+      - code: RECORD_NOT_FOUND
+        message: 记录不存在
+      - code: DUPLICATE_KEY
+        message: 唯一键冲突
+      - code: INVALID_STATUS_TRANSITION
+        message: 当前状态不允许执行该动作

package/specs/catalogs/child-templates.yaml

@@ -0,0 +1,54 @@
+templates:
+  customerContacts:
+    name: contacts
+    label: 联系人
+    tableSuffix: contact
+    foreignKey: customerId
+    formGroupTitle: 联系人
+    detailSection: contacts
+    fields:
+      - name: contactName
+        label: 联系人姓名
+        type: string
+        required: true
+      - name: mobile
+        label: 手机号
+        type: string
+      - name: email
+        label: 邮箱
+        type: string
+      - name: isPrimary
+        label: 是否主联系人
+        type: boolean
+        default: false
+
+  documentLineItems:
+    name: lines
+    label: 明细行
+    tableSuffix: line
+    foreignKey: documentId
+    formGroupTitle: 明细行
+    detailSection: lines
+    fields:
+      - name: lineNo
+        label: 行号
+        type: string
+        required: true
+      - name: itemCode
+        label: 项目编码
+        type: string
+        required: true
+      - name: itemName
+        label: 项目名称
+        type: string
+        required: true
+      - name: quantity
+        label: 数量
+        type: number
+        required: true
+      - name: unitPrice
+        label: 单价
+        type: number
+      - name: amount
+        label: 金额
+        type: number

package/specs/catalogs/field-fragments.yaml

@@ -0,0 +1,203 @@
+fragments:
+  leadCode:
+    name: leadCode
+    label: 线索编号
+    type: string
+    required: true
+    unique: true
+
+  leadName:
+    name: leadName
+    label: 线索名称
+    type: string
+    required: true
+
+  customerCode:
+    name: customerCode
+    label: 客户编码
+    type: string
+    required: true
+    unique: true
+
+  customerName:
+    name: customerName
+    label: 客户名称
+    type: string
+    required: true
+
+  opportunityCode:
+    name: opportunityCode
+    label: 商机编号
+    type: string
+    required: true
+    unique: true
+
+  opportunityName:
+    name: opportunityName
+    label: 商机名称
+    type: string
+    required: true
+
+  quoteCode:
+    name: quoteCode
+    label: 报价编号
+    type: string
+    required: true
+    unique: true
+
+  quoteName:
+    name: quoteName
+    label: 报价名称
+    type: string
+    required: true
+
+  materialCode:
+    name: materialCode
+    label: 物料编码
+    type: string
+    required: true
+    unique: true
+
+  materialName:
+    name: materialName
+    label: 物料名称
+    type: string
+    required: true
+
+  customerNameOptional:
+    name: customerName
+    label: 客户名称
+    type: string
+
+  ownerName:
+    name: ownerName
+    label: 负责人
+    type: string
+
+  phone:
+    name: phone
+    label: 联系电话
+    type: string
+
+  sourceLead:
+    name: source
+    label: 线索来源
+    type: enum
+    options: [website, referral, campaign, manual]
+    default: manual
+
+  sourceCustomer:
+    name: source
+    label: 客户来源
+    type: enum
+    options: [manual, import, campaign]
+    default: manual
+
+  levelCustomer:
+    name: level
+    label: 客户等级
+    type: enum
+    options: [A, B, C]
+    default: B
+
+  stageOpportunity:
+    name: stage
+    label: 商机阶段
+    type: enum
+    options: [new, qualifying, proposal, won, lost]
+    default: new
+
+  stageQuote:
+    name: stage
+    label: 报价阶段
+    type: enum
+    options: [draft, reviewing, sent, accepted, rejected]
+    default: draft
+
+  statusCrmFollow:
+    name: status
+    label: 状态
+    type: enum
+    statusTemplateRef: crmFollow
+
+  statusCrmBase:
+    name: status
+    label: 状态
+    type: enum
+    statusTemplateRef: crmBase
+
+  statusCrmClosed:
+    name: status
+    label: 状态
+    type: enum
+    statusTemplateRef: crmClosed
+
+  materialType:
+    name: materialType
+    label: 物料类型
+    type: enum
+    options: [ROH, HALB, FERT, HIBE, NLAG]
+    default: FERT
+
+  materialGroup:
+    name: materialGroup
+    label: 物料组
+    type: string
+
+  baseUnit:
+    name: baseUnit
+    label: 基本计量单位
+    type: string
+
+  documentNo:
+    name: documentNo
+    label: 单据编号
+    type: string
+    required: true
+    unique: true
+
+  documentTitle:
+    name: documentTitle
+    label: 单据标题
+    type: string
+    required: true
+
+  bizDate:
+    name: bizDate
+    label: 业务日期
+    type: date
+    required: true
+
+  statusErpBase:
+    name: status
+    label: 状态
+    type: enum
+    statusTemplateRef: erpBase
+
+  categoryCode:
+    name: categoryCode
+    label: 节点编码
+    type: string
+    required: true
+    unique: true
+
+  categoryName:
+    name: categoryName
+    label: 节点名称
+    type: string
+    required: true
+
+  parentId:
+    name: parentId
+    label: 父节点ID
+    type: integer
+
+  parentName:
+    name: parentName
+    label: 父节点名称
+    type: string
+
+  sortOrder:
+    name: sortOrder
+    label: 排序号
+    type: integer

package/specs/catalogs/object-catalog.yaml

@@ -0,0 +1,35 @@
+objects:
+  - keywords: [线索管理, 线索]
+    domain: crm
+    object: lead
+    label: 线索
+    objectTemplateRef: crmRootCrud
+    fieldRefs: [leadCode, leadName, sourceLead, phone, statusCrmFollow]
+
+  - keywords: [客户管理, 客户]
+    domain: crm
+    object: customer
+    label: 客户
+    objectTemplateRef: crmCustomerObject
+    fieldRefs: [customerCode, customerName, levelCustomer, statusCrmBase]
+
+  - keywords: [商机管理, 商机]
+    domain: crm
+    object: opportunity
+    label: 商机
+    objectTemplateRef: crmRootCrud
+    fieldRefs: [opportunityCode, opportunityName, customerNameOptional, stageOpportunity, statusCrmClosed]
+
+  - keywords: [报价管理, 报价单, 报价]
+    domain: crm
+    object: quote
+    label: 报价
+    objectTemplateRef: crmRootCrud
+    fieldRefs: [quoteCode, quoteName, customerNameOptional, stageQuote, statusCrmClosed]
+
+  - keywords: [erp物料台账, ERP物料台账, 物料台账, 物料主数据, 物料]
+    domain: erp
+    object: material
+    label: 物料
+    objectTemplateRef: erpMasterData
+    fieldRefs: [materialCode, materialName, materialType, materialGroup, baseUnit, statusErpBase]