make-app-service

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

make-app-service

Use this skill for Make App Service API work in

apps/service

make-app-service

owns the Service API contract between

apps/ui

and

apps/service

, thin Make Data API orchestration, Service route shape, Make adapter runtime config semantics, direct Make response passthrough, Service-side validation, boundary logging, and Service API tests.

It does not own record-action behavior (

make-app-actions

), sorting behavior (

make-app-sort

), filtering behavior (

make-app-filter

), grouping behavior (

make-app-group

), Make AI 助手 transport semantics (

make-ai-assistant

), UI layout (

makeui

), authentication implementation (

make-app-auth

), single-app permission logic (

make-app-permission

), runtime build/start contracts (

make-app-runtime

), DSL modeling (

makedsl

), Make CLI execution (

makecli

), or CanvasTable rendering/editing (

canvas-table-integration

此技能用于

apps/service

目录下的Make App Service API开发工作。

make-app-service

负责

apps/ui

与

apps/service

之间的Service API契约、轻量Make Data API编排、Service路由形态、Make适配器运行时配置语义、Make响应直接透传、Service端校验、边界日志及Service API测试。

它不负责记录动作行为（

make-app-actions

）、排序行为（

make-app-sort

）、过滤行为（

make-app-filter

）、分组行为（

make-app-group

）、Make AI 助手传输语义（

make-ai-assistant

）、UI布局（

makeui

）、认证实现（

make-app-auth

）、单应用权限逻辑（

make-app-permission

）、运行时构建/启动契约（

make-app-runtime

）、DSL建模（

makedsl

）、Make CLI执行（

makecli

）或CanvasTable渲染/编辑（

canvas-table-integration

）。

Quick start

快速开始

Inspect
```
apps/docs/api.md
```
,
```
apps/service/src
```
,
```
apps/service/src/config.ts
```
or host-equivalent config entry, existing tests, and the host project's declared data flow.
Preserve the host API contract. Update
```
apps/docs/api.md
```
before or with any Service route or response-shape change.
For Make Deploy's default route split, treat published browser-facing Service routes as
```
/api/**
```
. Prefix-free
```
/app/**
```
,
```
/auth/**
```
, or
```
/health
```
routes may be local compatibility only; do not document them as the published UI contract unless the deploy route actually exposes them.
Classify every route before implementation. Ordinary direct Make proxies preserve completed 2xx, 4xx, and 5xx status, Content-Type, and body; file downloads also preserve Content-Disposition and stream bytes. Make AI assistant is an explicit exception for errors: apply the selected adapter's safe public-error contract below, not generic raw-error passthrough. A genuine aggregation/normalization route may define its own successful result only when
```
apps/docs/api.md
```
names it as non-proxy; ordinary completed Make errors remain unchanged.
For a new Make POC Service, use the platform layered source tree by default:
```
app.ts
```
,
```
server.ts
```
,
```
config.ts
```
,
```
logger.ts
```
,
```
make-client/
```
,
```
services/
```
,
```
utils/
```
, with tests beside the route/adapter/helper they cover.
Do not read local DSL/YAML as a published runtime data source. Runtime schema and data come from Make/backend APIs or the host Service adapter.
Use shared adapters for Make Meta/Data/Preset calls, candidate APIs, lookup, files, and schema normalization. Build Make adapter URLs and
```
appKey
```
from normalized runtime config, not from route-local domains or UI input.
Implement the default single-app permission proxy through
```
make-app-permission
```
, including
```
/api/make/app/principal/permission
```
; do not omit it from a generated or refactored Make App.
Preserve permission-trimmed Schema collections independently: normalize
```
fields
```
and
```
createFields
```
separately; missing
```
createFields
```
means an empty create collection with no fallback to
```
fields
```
. Preserve unknown response properties, including
```
editableFields
```
, but leave their permission semantics to
```
make-app-permission
```
.
If Schema is cached, isolate permission-trimmed results by tenant, principal/session, App, and access generation, and expose explicit invalidation for permission refresh.
For Make record actions, implement the documented
```
record-write-permission
```
route before edit UI and the
```
records/bulk
```
route for batch edit; use
```
make-app-actions
```
for target, permission, one-request semantics, and the established complete UI-Service response contract. Do not apply generic passthrough/normalization rules to alter either action route's successful or failed response shape.
For cancellable or supersedable requests, propagate a request-scoped
```
AbortSignal
```
from the Service boundary into every downstream adapter; read
```
references/service-api-contracts.md
```
before implementation.
If the Make App Service change is for Make AI 助手, AI助手, AI 对话框, SSE, Agent Gateway, or
```
@qfei-design/make-ai-assistant
```
, use
```
make-ai-assistant
```
for the Make App AI Chat protocol first. Service then implements only its documented route handlers, proxy adapter, config validation, logging, cancellation, and tests.
Add or update Service tests for every changed route, adapter, validation path, and error path.
Read only the needed reference files from the map below.

查看
```
apps/docs/api.md
```
、
```
apps/service/src
```
、
```
apps/service/src/config.ts
```
或宿主等效配置入口、现有测试，以及宿主项目声明的数据流。
保留宿主API契约。在更改任何Service路由或响应形态之前或同时更新
```
apps/docs/api.md
```
。
对于Make Deploy的默认路由拆分，将发布的面向浏览器的Service路由视为
```
/api/**
```
。无前缀的
```
/app/**
```
、
```
/auth/**
```
或
```
/health
```
路由可能仅为本地兼容；不要将它们记录为发布的UI契约，除非部署路由确实暴露了这些接口。
在实现前对每个路由进行分类。普通的直接Make代理会保留完整的2xx、4xx和5xx状态码、Content-Type和响应体；文件下载还会保留Content-Disposition和流字节。Make AI助手是错误处理的显式例外： 应用下方选定适配器的安全公共错误契约，而非通用的原始错误透传。真正的聚合/规范化路由仅当
```
apps/docs/api.md
```
将其标记为非代理时，才可定义自己的成功结果；普通的已完成Make错误保持不变。
对于新的Make POC Service，默认使用平台分层源码结构：
```
app.ts
```
、
```
server.ts
```
、
```
config.ts
```
、
```
logger.ts
```
、
```
make-client/
```
、
```
services/
```
、
```
utils/
```
，测试文件与所覆盖的路由/适配器/工具函数放在同一目录下。
不要将本地DSL/YAML作为发布版的运行时数据源。运行时Schema和数据来自Make/后端API或宿主Service适配器。
Make Meta/Data/Preset调用、候选API、查找、文件及Schema规范化使用共享适配器。根据规范化的运行时配置构建Make适配器URL和
```
appKey
```
，不要从路由本地域名或UI输入构建。
通过
```
make-app-permission
```
实现默认的单应用权限代理，包括
```
/api/make/app/principal/permission
```
接口；在生成或重构的Make App中不得省略该接口。
独立保留权限裁剪后的Schema集合：分别规范化
```
fields
```
和
```
createFields
```
；若
```
createFields
```
缺失，则表示创建集合为空，不得回退到
```
fields
```
。保留未知的响应属性（包括
```
editableFields
```
），但其权限语义由
```
make-app-permission
```
负责。
若Schema被缓存，需按租户、主体/会话、应用及访问世代隔离权限裁剪后的结果，并提供明确的失效接口供权限刷新使用。
对于Make记录动作，在编辑UI之前实现已文档化的
```
record-write-permission
```
路由，以及用于批量编辑的
```
records/bulk
```
路由；使用
```
make-app-actions
```
处理目标、权限、单请求语义及已确立的完整UI-Service响应契约。不要应用通用透传/规范化规则来修改任何一个动作路由的成功或失败响应形态。
对于可取消或可被取代的请求，将请求作用域的
```
AbortSignal
```
从Service边界传播到每个下游适配器；实现前请阅读
```
references/service-api-contracts.md
```
。
若Make App Service的变更涉及Make AI 助手、AI助手、AI 对话框、SSE、Agent Gateway或
```
@qfei-design/make-ai-assistant
```
，优先使用
```
make-ai-assistant
```
的Make App AI Chat协议。Service仅实现其文档化的路由处理器、代理适配器、配置校验、日志、取消逻辑及测试。
为每个变更的路由、适配器、校验路径和错误路径添加或更新Service测试。
仅从下方的映射表中读取所需的参考文件。

Topic reference map

主题参考映射

Task / topic	Read
Service route shapes and UI-Service response contracts	`references/service-api-contracts.md`
Request cancellation, client disconnect handling, downstream `AbortSignal` propagation	`references/service-api-contracts.md`
Service folder structure, layering, logging, errors	`references/service-layering.md`
Make Data API adapter rules, schema `fields` / `createFields` , records, files, lookup, candidates	`references/make-data-adapter.md`
Test requirements, contract checks, safety review	`references/testing-and-safety.md`
Single-app permission proxy, Make IAM principal permission, app-scope permission payloads	Use `make-app-permission`
Auth proxy, cookies, unified login, 401/403 behavior	Use `make-app-auth`
Service build output, port `3000` , `dist/server.js` , package scripts, publish readiness	Use `make-app-runtime`
UI layout, forms, detail display, visual states	Use `makeui`
Make field/table rendering in CanvasTable	Use `canvas-table-integration`
Record sorting, sortable capabilities, Preset sort, records sort	Use `make-app-sort`
Advanced filter package behavior and Preset filter	Use `make-app-filter`
Record grouping, groupable capabilities, Preset group, record-groups, groupFilter	Use `make-app-group`
Record action precheck, strict selection target, one-request batch update	Use `make-app-actions`
Make App AI 助手, AI助手, AI 对话框, SSE, Agent Gateway, assistant capabilities, interface domain config	Use `make-ai-assistant` for the confirmed `/api/make/app/ai/v1/**` 18-operation protocol. Service owns routes, validation, logs, cancellation, and runtime config consumption

任务/主题	参考文档
Service路由形态与UI-Service响应契约	`references/service-api-contracts.md`
请求取消、客户端断开处理、下游 `AbortSignal` 传播	`references/service-api-contracts.md`
Service目录结构、分层、日志、错误	`references/service-layering.md`
Make Data API适配器规则、Schema `fields` / `createFields` 、记录、文件、查找、候选	`references/make-data-adapter.md`
测试要求、契约检查、安全审查	`references/testing-and-safety.md`
单应用权限代理、Make IAM主体权限、应用范围权限载荷	使用 `make-app-permission`
认证代理、Cookie、统一登录、401/403行为	使用 `make-app-auth`
Service构建输出、端口 `3000` 、 `dist/server.js` 、包脚本、发布就绪	使用 `make-app-runtime`
UI布局、表单、详情展示、视觉状态	使用 `makeui`
CanvasTable中的Make字段/表格渲染	使用 `canvas-table-integration`
记录排序、可排序能力、Preset排序、记录排序	使用 `make-app-sort`
高级过滤包行为与Preset过滤	使用 `make-app-filter`
记录分组、可分组能力、Preset分组、记录组、groupFilter	使用 `make-app-group`
记录动作预检查、严格选择目标、单请求批量更新	使用 `make-app-actions`
Make App AI 助手、AI助手、AI 对话框、SSE、Agent Gateway、助手能力、接口域配置	使用 `make-ai-assistant` 的已确认 `/api/make/app/ai/v1/**` 18个操作协议。Service负责路由、校验、日志、取消及运行时配置消费

Scope boundary

范围边界

```
make-app-service
```
defines Service-owned app APIs such as schema, records, candidates, lookup options, file proxy, and thin custom orchestration.
Every new Make App Service uses
```
make-app-observability
```
for the default request Trace ID: validate or create it at the boundary, return
```
X-Log-Id
```
, carry safe context into logs, and forward only validated trace headers to Make Gateway. This Skill owns the route and adapter implementation, while
```
make-app-observability
```
owns the cross-boundary invariant and audit.
It may document route names, query/body shapes, response envelopes, and adapter behavior.
It may define Service-side Make adapter config semantics and environment variable names used by Service source, such as
```
MAKE_APP_KEY
```
and
```
MAKE_API_BASE_URL
```
, while leaving deployment injection to runtime/operations.
It must not decide authentication implementation or OAuth/session mechanics; those belong to
```
make-app-auth
```
. It may still mount and document the App Service auth proxy path required by the host contract, normally
```
/api/make/auth/**
```
and
```
/api/make/oauth/**
```
for Make Deploy Service-fronted Apps that use
```
gatewayBaseUrl: "/api/make"
```
.
It must not define single-app permission logic, IAM permission matching, route guards, operation buttons, or field editability; those belong to
```
make-app-permission
```
. It should still provide the Service layering, logging, tests, and docs needed by that permission proxy.
It must not decide build output, Service port, Docker/K8s entrypoint, package scripts, workspace manifests, or publish readiness; those belong to
```
make-app-runtime
```
.
It must not define business models, entities, field meanings, relations, or DSL YAML; those belong to
```
makedsl
```
.
It must not decide UI layout, component choice, Drawer layout, or CanvasTable rendering; those belong to
```
makeui
```
and
```
canvas-table-integration
```
.
It must not define Make AI 助手 SSE event semantics or capability negotiation; those belong to
```
make-ai-assistant
```
. The current Make App AI adapter does not carry Artifact payloads.
It must not hard-code environment-to-domain mapping. Make API base URL, gateway routing, and secret injection come from runtime config, backend/operations, or Make tooling.

```
make-app-service
```
定义Service负责的应用API，如Schema、记录、候选、查找选项、文件代理及轻量自定义编排。
每个新的Make App Service都使用
```
make-app-observability
```
提供默认请求Trace ID：在边界处校验或生成Trace ID，返回
```
X-Log-Id
```
，将安全上下文带入日志，仅将经过校验的追踪头转发到Make Gateway。此技能负责路由和适配器实现，而
```
make-app-observability
```
负责跨边界的不变量和审计。
它可以记录路由名称、查询/请求体形态、响应信封及适配器行为。
它可以定义Service端Make适配器配置语义及Service源码使用的环境变量名称，如
```
MAKE_APP_KEY
```
和
```
MAKE_API_BASE_URL
```
，但部署注入由运行时/运维负责。
它不得决定认证实现或OAuth/会话机制；这些属于
```
make-app-auth
```
。它仍可挂载并记录宿主契约要求的App Service认证代理路径，对于使用
```
gatewayBaseUrl: "/api/make"
```
的Make Deploy Service前置应用，通常为
```
/api/make/auth/**
```
和
```
/api/make/oauth/**
```
。
它不得定义单应用权限逻辑、IAM权限匹配、路由守卫、操作按钮或字段可编辑性；这些属于
```
make-app-permission
```
。它仍应提供该权限代理所需的Service分层、日志、测试和文档。
它不得决定构建输出、Service端口、Docker/K8s入口点、包脚本、工作区清单或发布就绪状态；这些属于
```
make-app-runtime
```
。
它不得定义业务模型、实体、字段含义、关系或DSL YAML；这些属于
```
makedsl
```
。
它不得决定UI布局、组件选择、Drawer布局或CanvasTable渲染；这些属于
```
makeui
```
和
```
canvas-table-integration
```
。
它不得定义Make AI 助手SSE事件语义或能力协商；这些属于
```
make-ai-assistant
```
。当前的Make App AI适配器不承载Artifact载荷。
它不得硬编码环境到域名的映射。Make API基础URL、网关路由和密钥注入来自运行时配置、后端/运维或Make工具。

Default Service responsibilities

默认Service职责

Generated or refactored Make App Service code should provide these capabilities when the UI needs them and the host project does not already have equivalent routes:

public health/config:
```
/api/health
```
,
```
/api/config
```
for published UI access;
```
/health
```
may exist as local or k8s-probe compatibility

runtime schema:

/api/schema

/api/entities/:entityKey/fields

default single-app permissions:

/api/make/app/principal/permission

through

make-app-permission

Make App AI assistant routes only when requested by the host and specified by
```
make-ai-assistant
```
: expose the exact
```
/api/make/app/ai/v1/**
```
18-operation allowlist for capabilities, paginated Agents, multi-session chats, feedback, messages/history, response events/snapshot/cancel, uploads/parts/complete, and content bytes; never a generic proxy
records: list, get, create, update, delete, cell update
record actions when the list is writable: row-write permission precheck and one-request batch field update through
```
make-app-actions
```
current-user Entity Preset: get and sparse filter/sort update when filtering or sorting is enabled
lookup options and safe lookup relation updates
user candidates and department candidates
file upload/delete/download proxy
thin custom orchestration when requested, for example OCR result creation

Keep route handlers small. Put Make/backend calls in adapter modules, cross-route business orchestration in

services/

, and pure schema/value helpers in

utils/

当UI需要且宿主项目尚未提供等效路由时，生成或重构的Make App Service代码应提供以下能力：

公共健康检查/配置：供发布版UI访问的
```
/api/health
```
、
```
/api/config
```
；
```
/health
```
可能作为本地或k8s探针兼容接口存在

运行时Schema：

/api/schema

、

/api/entities/:entityKey/fields

默认单应用权限：通过

make-app-permission

提供的

/api/make/app/principal/permission

仅当宿主要求且
```
make-ai-assistant
```
指定时才提供Make App AI助手路由：暴露精确的
```
/api/make/app/ai/v1/**
```
18个操作白名单，涵盖能力、分页Agent、多会话聊天、反馈、消息/历史、响应事件/快照/取消、上传/分片/完成及内容字节；绝不能是通用代理
记录：列表、查询、创建、更新、删除、单元格更新
列表可写时的记录动作：通过
```
make-app-actions
```
提供行写入权限预检查和单请求批量字段更新
当前用户Entity Preset：启用过滤或排序时，支持查询及稀疏过滤/排序更新
查找选项及安全的查找关系更新
用户候选与部门候选
文件上传/删除/下载代理
按需提供轻量自定义编排，例如OCR结果创建

保持路由处理器精简。将Make/后端调用放在适配器模块中，跨路由业务编排放在

services/

目录下，纯Schema/值工具函数放在

utils/

目录下。

Hard rules

硬性规则

```
apps/docs/api.md
```
is the UI-Service contract source. Do not change Service route behavior without updating it.
For Make Deploy Service-fronted Apps that use
```
gatewayBaseUrl: "/api/make"
```
,
```
apps/docs/api.md
```
must document published browser paths under
```
/api/make/**
```
, for example
```
/api/make/auth/**
```
,
```
/api/make/oauth/**
```
, and
```
/api/make/app/**
```
. Do not document prefix-free
```
/app/**
```
as the published path unless the deploy HTTPRoute exposes it. Older
```
/api
```
projects may keep
```
/api/auth/**
```
and
```
/api/app/**
```
only as an explicit legacy contract.
New generated Make POC Services and non-trivial generated/refactored
```
apps/service
```
code must use a layered, componentized source structure instead of flat route/adapter/helper files. For new Make POC Services, default to the platform tree:
```
app.ts
```
,
```
server.ts
```
,
```
config.ts
```
,
```
logger.ts
```
,
```
make-client/
```
for Make/backend adapters,
```
services/
```
for multi-step orchestration,
```
utils/
```
for pure helpers, and colocated tests.
A flat
```
apps/service/src
```
tree is a readiness defect for generated POC work when it mixes route registration, Make request construction, schema normalization, lookup/file orchestration, config parsing, logging, and helpers side by side. Split it before reporting the Service as complete.
Route handlers in
```
app.ts
```
or
```
routes/
```
only validate input, call a service/adapter, map Service-owned preflight errors, log safe boundary context, and send the documented response. Ordinary direct Make proxies preserve completed HTTP status, Content-Type, and body for 2xx, 4xx, and 5xx; the selected Make AI assistant adapter instead follows its explicit safe-error contract. Do not put raw Make payload construction, schema variant parsing, record lookup orchestration, file proxy mapping, or custom workflow steps directly into route handlers.
A UI-facing aggregation route may use a documented normalized success shape only when
```
apps/docs/api.md
```
explicitly marks it as non-proxy. Start from the default route-response-mode table in
```
references/service-api-contracts.md
```
, then document any host-specific exception and its migration. Ordinary completed Make errors remain unchanged; the selected Make AI assistant error contract is a separately documented exception.
Service route handlers validate query/body/path params before calling Make adapters and return 400 for invalid client input.
Service adapters own Make request details such as
```
appKey
```
,
```
X-Make-Target
```
, Make response code checks, pagination translation, file body mapping, and consuming a prepared login/session forwarding context. Auth/session mechanics and shared forwarding helpers belong to
```
make-app-auth
```
; publish/runtime proxy header contracts belong to
```
make-app-runtime
```
.
Make-backed record read APIs must call Make gateway Data API through the Service Make adapter. Published runtime uses k8s-internal
```
/make/data/v1/record
```
; local preview with
```
MAKE_APP_LOCAL_PREVIEW=true
```
uses
```
makecli configure resolve --target local-preview --output=json
```
field
```
make_api_origin
```
plus
```
/api/make/data/v1/record
```
. This applies to record list, record detail, lookup target-record reads, and any custom Service route that reads Make records.
Service Make adapters must forward the incoming request's established login context to Make gateway for Make-backed data reads and writes. At minimum, preserve the browser
```
Cookie
```
session header when the host uses cookie/unified-login auth, preserve an existing
```
Authorization
```
header only when the host contract already uses bearer auth, and apply the host gateway context headers such as
```
X-Forwarded-Host
```
and
```
X-Forwarded-Proto
```
through the shared auth/runtime helper. Do not invent auth policy here; use
```
make-app-auth
```
for auth mechanics, but do not drop the login context before calling gateway.
Published/runtime Service APIs must never use
```
makecli
```
as a data source. Do not shell out to
```
makecli
```
,
```
npx makecli
```
, local makecli config, or makecli JSON stdout to serve schema, records, candidates, lookup options, files, or custom API data. Online Service containers do not have makecli, so runtime data must come from Make gateway/API adapters.
Make-backed Service config must read its authoritative
```
appKey
```
from deployment-injected
```
MAKE_APP_KEY
```
; generated production code must not invent, hard-code, or let UI input override that scope. A documented protocol route may carry
```
appKey
```
in its query or body only when the Service validates exact equality with
```
MAKE_APP_KEY
```
before calling an adapter.
If
```
MAKE_APP_KEY
```
is missing for a Service that calls Make Meta/Data APIs, config loading must fail with a clear non-secret error before the Service is reported ready. Local test fixtures may inject
```
MAKE_APP_KEY
```
explicitly.
New generated Service code reads Make adapter runtime config from
```
apps/service/src/config.ts
```
or the host equivalent.
```
MAKE_API_BASE_URL
```
is the preferred published gateway-origin env var;
```
MAKE_SERVER_URL
```
is a compatibility alias only. Local preview derives its public gateway origin from
```
makecli configure resolve --target local-preview --output=json
```
instead of deployment env.
If neither
```
MAKE_API_BASE_URL
```
nor
```
MAKE_SERVER_URL
```
is configured for a Make-backed Service, config loading must fail with a clear non-secret error before the Service is reported ready.
Published
```
MAKE_API_BASE_URL
```
/
```
MAKE_SERVER_URL
```
values are strict k8s gateway origins such as
```
http://make-gateway.make-dev
```
. New generated Service code must not put
```
/make
```
,
```
/api/make
```
,
```
/meta
```
,
```
/data
```
,
```
/auth
```
, or another service path scope in this env var. Local-preview resolve output must be consumed as
```
make_api_origin
```
; if older makecli fallback returns or reads a path-scoped public
```
/api/make
```
API base, normalize that only inside the local-preview adapter.
Make platform adapters own the service path scope. Generated Service code derives upstream URLs from an explicit runtime mode: local preview uses public gateway origin +
```
/api/make/**
```
; published uses k8s gateway origin +
```
/make/**
```
, such as
```
http://make-gateway.make-dev/make/meta/**
```
and
```
http://make-gateway.make-dev/make/data/**
```
.
For the Make App AI assistant adapter, follow
```
make-ai-assistant
```
: the browser calls the fixed
```
/api/make/app/ai/v1/**
```
18-operation family through same origin; local preview Service upstreams use
```
make_api_origin
```
plus
```
/api/make/app/ai/v1/**
```
; published Service upstreams use the strict origin from
```
MAKE_API_BASE_URL
```
or its compatibility alias
```
MAKE_SERVER_URL
```
plus
```
/make/app/ai/v1/**
```
. Service must read deployed scope from
```
MAKE_APP_KEY
```
and reject every query/body
```
appKey
```
that differs from it; every non-GET/HEAD request requires one HTTP(S) same-origin
```
Origin
```
checked against the selected Host. Do not add an assistant-only/AI Gateway/Agent Gateway origin, token, environment variable, or hard-coded domain. Preserve bare JSON objects, empty 204 responses,
```
Make-AI-Api-Version
```
, SSE, and bytes as separate success modes, and do not narrow valid protocol DTOs in a host validator. For AI errors, preserve bounded schema-valid flat
```
{code,message,requestId?,details?}
```
with its HTTP status, including extensible unknown codes; malformed/non-public upstream errors become a safe Service error without leaking raw diagnostics. Never remap a valid public typed error to 502.
If the same Service calls other gateway services, those adapters define their own explicit service scopes from the same gateway origin. Do not strip
```
/make
```
out of
```
MAKE_API_BASE_URL
```
, and do not overload a path-scoped base URL to reach unrelated services.
Service-to-gateway calls inside the cluster must not use the browser-facing
```
/api/make
```
prefix.
```
/api/make/**
```
belongs to same-origin browser access, Service ingress, and local-preview public gateway calls; published Service internal upstream URLs use gateway-origin plus
```
/make
```
.
Service source must not hard-code concrete Make dev/test/prod domains, infer namespace-local gateway addresses, or map deployment environments to domains.
Runtime Service code must not require
```
apps/dsl/**
```
,
```
/dsl/**
```
, or copied
```
*.yaml
```
files to start or serve schema/data in published Apps.
Schema APIs normalize backend schema variants before UI sees them. Handle known variants such as
```
entity.properties.fields
```
,
```
entity.fields
```
, or the host-documented equivalent at the Service/API boundary, and preserve field
```
capabilities.sortable
```
/
```
capabilities.groupable
```
for sorting and grouping.
Permission-trimmed Schema normalization keeps
```
fields
```
and
```
createFields
```
as separate collections. Normalize each collection independently; a missing or invalid
```
createFields
```
becomes
```
[]
```
and never falls back to
```
fields
```
. Preserve
```
editableFields
```
as response metadata when the host contract requires lossless forwarding, but do not use it to derive current edit behavior.
Schema caches and in-flight reuse must not share permission-trimmed entities across principals. Key by tenant, principal/session identity, App, and access generation (or use a request-local cache), and provide an invalidation/reload path that permission refresh can call before data refresh.
Record list and detail are separate contracts. Do not implement detail by calling list and guessing the first row when a single-record Make call exists.
Entity Preset GET/PATCH routes must use the Make Preset
```
/preset/v1/entity
```
adapter with
```
MakeService.GetResource
```
/
```
MakeService.UpdateResource
```
, preserve the established login context, and update only submitted dimensions. Use
```
make-app-sort
```
,
```
make-app-filter
```
, and
```
make-app-group
```
for dimension semantics.
Preset sort and records sort must share shape validation and authoritatively validate fields against current runtime schema
```
capabilities.sortable === true
```
. Reject invalid, duplicate, non-sortable, or more-than-five rules before Make calls.
Sparse Preset updates must preserve sibling dimensions; saving sort must not send filter/group, saving filter must not send sort/group, and saving group must not send filter/sort.
User and department candidates come from Service routes such as
```
GET /api/users
```
and
```
GET /api/departments
```
or the host equivalent; do not use local demo arrays in generated Service.
Lookup option APIs must resolve target object/field from schema metadata and return
```
{ options, total }
```
. Do not expose full target records to selector UIs by default.
File routes proxy upload/delete/download through Service. UI should not expose raw backend file URLs when a Service download proxy is available.
Browser resource tags such as
```
<img src>
```
cannot attach
```
Authorization
```
. When Make file downloads require a bearer token, keep the URL browser-facing through a Service download proxy, verify the current App session first, and let only the Service adapter attach the deployment-injected token. Do not put Make tokens or raw
```
/data/v1/download/**
```
URLs in UI state, public config, JSX, or logs.
Add boundary logs at route/adapter entry, success, and failure. Redact tokens, cookies, Authorization, API keys, signed download query strings, and unnecessary personal data.
For cancellable or supersedable work, a client disconnect must abort downstream work through a request-scoped
```
AbortSignal
```
. Do not stop at ignoring a stale response, and do not treat an expected
```
AbortError
```
as a user-visible 5xx failure.
Tests are required for route contracts, invalid input, adapter payloads, direct Make response status/body passthrough, and any schema/value normalization added by this skill.
Do not report a generated or refactored Make App Service complete without the default principal permission proxy from
```
make-app-permission
```
and its required tests.
For
```
record-write-permission
```
and
```
records/bulk
```
, follow
```
make-app-actions
```
: precheck the complete target with one Make
```
/data/v1/permission
```
call, parse the explicit-selection HTTP 200 / business-code
```
20000032
```
denial and its
```
noPermissionRecordIds
```
losslessly from the raw response before JavaScript
```
Number
```
coercion and generic Make error mapping, keep select-all 403 denial ID-less, reuse the target for one Make
```
/data/v1/field
```
call, and never split diagnostics or loop single-record updates.

```
apps/docs/api.md
```
是UI-Service契约的来源。未更新该文档不得更改Service路由行为。
对于使用
```
gatewayBaseUrl: "/api/make"
```
的Make Deploy Service前置应用，
```
apps/docs/api.md
```
必须记录
```
/api/make/**
```
下的发布版浏览器路径，例如
```
/api/make/auth/**
```
、
```
/api/make/oauth/**
```
和
```
/api/make/app/**
```
。除非部署的HTTPRoute暴露了无前缀的
```
/app/**
```
，否则不得将其记录为发布路径。较旧的
```
/api
```
项目可仅将
```
/api/auth/**
```
和
```
/api/app/**
```
作为显式遗留契约保留。
新生成的Make POC Service及非平凡的生成/重构
```
apps/service
```
代码必须使用分层、组件化的源码结构，而非扁平的路由/适配器/工具文件。对于新的Make POC Service，默认使用平台目录结构：
```
app.ts
```
、
```
server.ts
```
、
```
config.ts
```
、
```
logger.ts
```
、用于Make/后端适配器的
```
make-client/
```
、用于多步编排的
```
services/
```
、用于纯工具函数的
```
utils/
```
，以及同位置的测试文件。
若生成的POC工作中
```
apps/service/src
```
目录结构扁平，混合了路由注册、Make请求构建、Schema规范化、查找/文件编排、配置解析、日志和工具函数，则属于就绪缺陷。在报告Service完成前必须拆分。
```
app.ts
```
或
```
routes/
```
中的路由处理器仅负责校验输入、调用服务/适配器、映射Service侧的前置校验错误、记录安全边界上下文并发送文档化的响应。普通的直接Make代理会保留2xx、4xx和5xx的完整HTTP状态、Content-Type和响应体；而选定的Make AI助手适配器则遵循其明确的安全错误契约。不要将原始Make载荷构建、Schema变体解析、记录查找编排、文件代理映射或自定义工作流步骤直接放在路由处理器中。
面向UI的聚合路由仅当
```
apps/docs/api.md
```
显式标记为非代理时，才可使用文档化的规范化成功形态。从
```
references/service-api-contracts.md
```
中的默认路由-响应模式表开始，然后记录任何宿主特定的异常及其迁移方式。普通的已完成Make错误保持不变；选定的Make AI助手错误契约是单独记录的例外。
Service路由处理器在调用Make适配器前校验查询/请求体/路径参数，对无效的客户端输入返回400。
Service适配器负责Make请求细节，如
```
appKey
```
、
```
X-Make-Target
```
、Make响应码检查、分页转换、文件体映射，以及使用准备好的登录/会话转发上下文。认证/会话机制和共享转发助手属于
```
make-app-auth
```
；发布/运行时代理头契约属于
```
make-app-runtime
```
。
基于Make的记录读取API必须通过Service Make适配器调用Make网关Data API。发布版运行时使用k8s内部的
```
/make/data/v1/record
```
；设置了
```
MAKE_APP_LOCAL_PREVIEW=true
```
的本地预览使用
```
makecli configure resolve --target local-preview --output=json
```
输出的
```
make_api_origin
```
字段加上
```
/api/make/data/v1/record
```
。这适用于记录列表、记录详情、查找目标记录读取，以及任何读取Make记录的自定义Service路由。
Service Make适配器必须将传入请求的已建立登录上下文转发到Make网关，以供基于Make的数据读写使用。至少，当宿主使用Cookie/统一登录认证时保留浏览器
```
Cookie
```
会话头，仅当宿主契约已使用Bearer认证时保留现有的
```
Authorization
```
头，并通过共享的认证/运行时助手应用宿主网关上下文头（如
```
X-Forwarded-Host
```
和
```
X-Forwarded-Proto
```
）。不要在此处发明认证策略；认证机制使用
```
make-app-auth
```
，但在调用网关前不得丢弃登录上下文。
发布版/运行时Service API绝不能将
```
makecli
```
用作数据源。不要通过shell调用
```
makecli
```
、
```
npx makecli
```
、本地makecli配置或makecli JSON标准输出来提供Schema、记录、候选、查找选项、文件或自定义API数据。在线Service容器没有makecli，因此运行时数据必须来自Make网关/API适配器。
基于Make的Service配置必须从部署注入的
```
MAKE_APP_KEY
```
中读取其权威
```
appKey
```
；生成的生产代码不得发明、硬编码或让UI输入覆盖该范围。仅当Service在调用适配器前校验了查询或请求体中的
```
appKey
```
与
```
MAKE_APP_KEY
```
完全相等时，文档化的协议路由才可在查询或请求体中携带
```
appKey
```
。
若调用Make Meta/Data API的Service缺少
```
MAKE_APP_KEY
```
，配置加载必须在Service报告就绪前失败，并返回清晰的非涉密错误。本地测试夹具可显式注入
```
MAKE_APP_KEY
```
。
新生成的Service代码从
```
apps/service/src/config.ts
```
或宿主等效文件读取Make适配器运行时配置。
```
MAKE_API_BASE_URL
```
是首选的发布版网关源环境变量；
```
MAKE_SERVER_URL
```
仅是兼容别名。本地预览从
```
makecli configure resolve --target local-preview --output=json
```
派生其公共网关源，而非部署环境变量。
若基于Make的Service既未配置
```
MAKE_API_BASE_URL
```
也未配置
```
MAKE_SERVER_URL
```
，配置加载必须在Service报告就绪前失败，并返回清晰的非涉密错误。
发布版的
```
MAKE_API_BASE_URL
```
/
```
MAKE_SERVER_URL
```
值是严格的k8s网关源，如
```
http://make-gateway.make-dev
```
。新生成的Service代码不得在此环境变量中放入
```
/make
```
、
```
/api/make
```
、
```
/meta
```
、
```
/data
```
、
```
/auth
```
或其他服务路径作用域。本地预览解析输出必须作为
```
make_api_origin
```
使用；若较旧的makecli回退返回或读取了带路径作用域的公共
```
/api/make
```
API基础路径，仅在本地预览适配器内部进行规范化。
Make平台适配器负责服务路径作用域。生成的Service代码根据显式运行时模式派生出上游URL：本地预览使用公共网关源 +
```
/api/make/**
```
；发布版使用k8s网关源 +
```
/make/**
```
，例如
```
http://make-gateway.make-dev/make/meta/**
```
和
```
http://make-gateway.make-dev/make/data/**
```
。
对于Make App AI助手适配器，遵循
```
make-ai-assistant
```
：浏览器通过同源调用固定的
```
/api/make/app/ai/v1/**
```
18个操作系列；本地预览Service上游使用
```
make_api_origin
```
加上
```
/api/make/app/ai/v1/**
```
；发布版Service上游使用
```
MAKE_API_BASE_URL
```
或其兼容别名
```
MAKE_SERVER_URL
```
中的严格源加上
```
/make/app/ai/v1/**
```
。Service必须从
```
MAKE_APP_KEY
```
读取已部署的范围，并拒绝所有与之不同的查询/请求体
```
appKey
```
；每个非GET/HEAD请求都需要检查一个HTTP(S)同源
```
Origin
```
是否与选定的Host匹配。不得添加仅用于助手的/AI Gateway/Agent Gateway源、令牌、环境变量或硬编码域名。将裸JSON对象、空204响应、
```
Make-AI-Api-Version
```
、SSE和字节作为单独的成功模式保留，不要在宿主校验器中缩小有效协议DTO的范围。对于AI错误，保留带HTTP状态的、符合Schema的有限扁平
```
{code,message,requestId?,details?}
```
结构，包括可扩展的未知代码；格式错误/非公开的上游错误将转换为安全的Service错误，不会泄露原始诊断信息。绝不能将有效的公共类型化错误重映射为502。
若同一Service调用其他网关服务，这些适配器从同一网关源定义自己的显式服务作用域。不要从
```
MAKE_API_BASE_URL
```
中剥离
```
/make
```
，也不要重载带路径作用域的基础URL来访问不相关的服务。
集群内的Service到网关调用不得使用面向浏览器的
```
/api/make
```
前缀。
```
/api/make/**
```
属于同源浏览器访问、Service入口和本地预览公共网关调用；发布版Service内部上游URL使用网关源加上
```
/make
```
。
Service源码不得硬编码具体的Make开发/测试/生产域名，不得推断命名空间本地网关地址，也不得将部署环境映射到域名。
运行时Service代码在发布版应用中启动或提供Schema/数据时，不得依赖
```
apps/dsl/**
```
、
```
/dsl/**
```
或复制的
```
*.yaml
```
文件。
Schema API在UI看到后端Schema变体之前对其进行规范化。在Service/API边界处理已知变体，如
```
entity.properties.fields
```
、
```
entity.fields
```
或宿主文档化的等效变体，并保留字段的
```
capabilities.sortable
```
/
```
capabilities.groupable
```
以供排序和分组使用。
权限裁剪后的Schema规范化将
```
fields
```
和
```
createFields
```
作为独立集合保留。分别规范化每个集合；缺失或无效的
```
createFields
```
将变为
```
[]
```
，绝不会回退到
```
fields
```
。当宿主契约要求无损转发时，保留
```
editableFields
```
作为响应元数据，但不要用它来推导当前编辑行为。
Schema缓存与处理中请求的复用不得在不同主体间共享权限裁剪后的实体。按租户、主体/会话身份、应用和访问世代（或使用请求本地缓存）作为键，并提供失效/重载路径，供权限刷新在数据刷新前调用。
记录列表和详情是独立的契约。当存在单记录Make调用时，不得通过调用列表接口并猜测第一条记录来实现详情接口。
Entity Preset GET/PATCH路由必须使用Make Preset
```
/preset/v1/entity
```
适配器，配合
```
MakeService.GetResource
```
/
```
MakeService.UpdateResource
```
，保留已建立的登录上下文，且仅更新提交的维度。使用
```
make-app-sort
```
、
```
make-app-filter
```
和
```
make-app-group
```
处理维度语义。
Preset排序和记录排序必须共享形态校验，并根据当前运行时Schema的
```
capabilities.sortable === true
```
权威地校验字段。在调用Make前，拒绝无效、重复、不可排序或超过五条的规则。
稀疏Preset更新必须保留兄弟维度；保存排序时不得发送过滤/分组，保存过滤时不得发送排序/分组，保存分组时不得发送过滤/排序。
用户和部门候选数据来自Service路由，如
```
GET /api/users
```
和
```
GET /api/departments
```
或宿主等效路由；不要在生成的Service中使用本地演示数组。
查找选项API必须从Schema元数据解析目标对象/字段，并返回
```
{ options, total }
```
。默认情况下，不得向选择器UI暴露完整的目标记录。
文件路由通过Service代理上传/删除/下载。当存在Service下载代理时，UI不应暴露原始后端文件URL。
浏览器资源标签（如
```
<img src>
```
）无法附加
```
Authorization
```
。当Make文件下载需要Bearer令牌时，通过Service下载代理保持URL面向浏览器，首先验证当前应用会话，仅让Service适配器附加部署注入的令牌。不要将Make令牌或原始
```
/data/v1/download/**
```
URL放在UI状态、公共配置、JSX或日志中。
在路由/适配器入口、成功和失败时添加边界日志。对令牌、Cookie、Authorization、API密钥、签名下载查询字符串及不必要的个人数据进行脱敏。
对于可取消或可被取代的工作，客户端断开必须通过请求作用域的
```
AbortSignal
```
中止下游工作。不要仅忽略过期响应，也不要将预期的
```
AbortError
```
视为用户可见的5xx失败。
必须为路由契约、无效输入、适配器载荷、直接Make响应状态/体透传以及此技能添加的任何Schema/值规范化编写测试。
若没有
```
make-app-permission
```
提供的默认主体权限代理及其所需测试，不得报告生成或重构的Make App Service已完成。
对于
```
record-write-permission
```
和
```
records/bulk
```
，遵循
```
make-app-actions
```
：通过一次Make
```
/data/v1/permission
```
调用预检查完整目标，在JavaScript
```
Number
```
强制转换和通用Make错误映射之前，从原始响应中无损地解析显式选择的HTTP 200 / 业务码
```
20000032
```
拒绝及其
```
noPermissionRecordIds
```
，保持全选403拒绝无ID，将目标复用于一次Make
```
/data/v1/field
```
调用，绝不能拆分诊断信息或循环执行单记录更新。

Default route baseline

默认路由基线

Prefer these UI-Service contracts for new Make App Service projects unless the host project already documents equivalent routes:

text

GET    /api/health
GET    /health
GET    /api/config
GET    /api/make/app/principal/permission
GET    /api/schema
GET    /api/entities/:entityKey/fields
GET    /api/entities/:entityKey/preset
PATCH  /api/entities/:entityKey/preset
GET    /api/entities/:entityKey/records
GET    /api/entities/:entityKey/records/:recordID
POST   /api/entities/:entityKey/records
POST   /api/make/app/entities/:objectKey/record-write-permission
POST   /api/make/app/entities/:objectKey/records/bulk
PATCH  /api/entities/:entityKey/records/:recordID
DELETE /api/entities/:entityKey/records/:recordID
PATCH  /api/entities/:entityKey/records/:recordID/cells/:fieldKey
GET    /api/users
GET    /api/departments
GET    /api/lookup-options
POST   /api/entities/:entityKey/records/:recordID/files/:fieldKey
DELETE /api/entities/:entityKey/records/:recordID/files/:fieldKey
GET    /api/files/download/*

Lookup relation update routes are optional and should be generated only when the UI needs editable lookup relationships and the Service can preserve a full

qfei_relation

snapshot safely.

对于新的Make App Service项目，优先使用以下UI-Service契约，除非宿主项目已经记录了等效路由：

text

GET    /api/health
GET    /health
GET    /api/config
GET    /api/make/app/principal/permission
GET    /api/schema
GET    /api/entities/:entityKey/fields
GET    /api/entities/:entityKey/preset
PATCH  /api/entities/:entityKey/preset
GET    /api/entities/:entityKey/records
GET    /api/entities/:entityKey/records/:recordID
POST   /api/entities/:entityKey/records
POST   /api/make/app/entities/:objectKey/record-write-permission
POST   /api/make/app/entities/:objectKey/records/bulk
PATCH  /api/entities/:entityKey/records/:recordID
DELETE /api/entities/:entityKey/records/:recordID
PATCH  /api/entities/:entityKey/records/:recordID/cells/:fieldKey
GET    /api/users
GET    /api/departments
GET    /api/lookup-options
POST   /api/entities/:entityKey/records/:recordID/files/:fieldKey
DELETE /api/entities/:entityKey/records/:recordID/files/:fieldKey
GET    /api/files/download/*

查找关系更新路由是可选的，仅当UI需要可编辑的查找关系且Service能够安全地保留完整的

qfei_relation

快照时才应生成。

Collaboration rules

协作规则

With
```
makeui
```
: this skill provides Service contracts and normalized API shapes;
```
makeui
```
decides how UI renders them.
With
```
make-app-permission
```
: this skill provides Service layering and tests;
```
make-app-permission
```
owns the principal permission route, IAM upstream path, App scope payload, and frontend permission contract.
With
```
canvas-table-integration
```
: this skill provides schema/records/candidate APIs and owns Service-side disconnect-to-downstream cancellation; table rendering, editing UI, and browser-side virtual-page scheduling stay in the canvas skill.
With
```
make-app-sort
```
: this skill implements and tests Preset/records routes and Make adapters;
```
make-app-sort
```
owns sortable rules, draft/save timing, and header linkage.
With
```
make-app-filter
```
: this skill implements and tests Preset/records routes and Make adapters;
```
make-app-filter
```
owns package filter behavior, hydration, and save timing.
With
```
make-app-group
```
: this skill implements and tests Preset group, record-groups, records groupFilter, and Make adapters;
```
make-app-group
```
owns groupable rules, groupFilter composition, grouped data timing, and CanvasTable grouped-flow coordination.
With
```
make-app-actions
```
: this skill implements and tests
```
record-write-permission
```
,
```
records/bulk
```
, strict target parsing, Make adapters, and error mapping;
```
make-app-actions
```
owns selection intent, action timing, permission-key choice, frozen snapshots, and UI feedback.
With
```
make-ai-assistant
```
: this skill implements Make App AI route handlers, proxy adapters, runtime config validation, safe logs, AbortSignal propagation, and Service tests;
```
make-ai-assistant
```
owns package integration, the v1 18-operation DTO/response/stream semantics, multi-session behavior, and interface-domain rules.
With
```
make-app-auth
```
: this skill may preserve Service-fronted app route shape, but auth proxy and session behavior stay in auth.
With
```
make-app-runtime
```
: this skill writes Service source and tests; runtime build/start/port checks stay in runtime.

与
```
makeui
```
协作：此技能提供Service契约和规范化API形态；
```
makeui
```
决定UI如何渲染它们。
与
```
make-app-permission
```
协作：此技能提供Service分层和测试；
```
make-app-permission
```
负责主体权限路由、IAM上游路径、应用范围载荷及前端权限契约。
与
```
canvas-table-integration
```
协作：此技能提供Schema/记录/候选API，并负责Service端的断连到下游取消；表格渲染、编辑UI和浏览器端虚拟页调度保留在canvas技能中。
与
```
make-app-sort
```
协作：此技能实现并测试Preset/记录路由和Make适配器；
```
make-app-sort
```
负责可排序规则、草稿/保存时机及表头联动。
与
```
make-app-filter
```
协作：此技能实现并测试Preset/记录路由和Make适配器；
```
make-app-filter
```
负责过滤包行为、hydration及保存时机。
与
```
make-app-group
```
协作：此技能实现并测试Preset分组、记录组、记录groupFilter及Make适配器；
```
make-app-group
```
负责可分组规则、groupFilter组合、分组数据时机及CanvasTable分组流协调。
与
```
make-app-actions
```
协作：此技能实现并测试
```
record-write-permission
```
、
```
records/bulk
```
、严格目标解析、Make适配器及错误映射；
```
make-app-actions
```
负责选择意图、动作时机、权限键选择、冻结快照及UI反馈。
与
```
make-ai-assistant
```
协作：此技能实现Make App AI路由处理器、代理适配器、运行时配置校验、安全日志、AbortSignal传播及Service测试；
```
make-ai-assistant
```
负责包集成、v1 18个操作的DTO/响应/流语义、多会话行为及接口域规则。
与
```
make-app-auth
```
协作：此技能可保留Service前置应用的路由形态，但认证代理和会话行为由auth负责。
与
```
make-app-runtime
```
协作：此技能编写Service源码和测试；运行时构建/启动/端口检查由runtime负责。