openxiangda 1.0.91 → 1.0.93

package/README.md

@@ -31,9 +31,12 @@ openxiangda permission role-list --profile dev
 openxiangda settings get customer --profile dev
 openxiangda data-view list --profile dev
 openxiangda data-view status ticket_with_customer --profile dev
+openxiangda doctor --profile dev --json
+openxiangda design gates --topic public-access --json
 openxiangda resource validate --profile dev
 openxiangda resource plan --profile dev
 openxiangda resource publish --profile dev
+openxiangda resource explain public-access --json
 openxiangda runtime deploy --profile dev
 openxiangda inspect app --profile dev --json
 openxiangda app snapshot APP_XXXX --profile dev --json
@@ -69,6 +72,45 @@ openxiangda update install
 
 Domestic npm mirrors may lag and return an older OpenXiangda version. `openxiangda update check --json` is designed for AI agents: it returns the installed version, latest official npm version, whether an update is available, and the compatibility commands to run after updating. `openxiangda update install` installs from the official registry and refreshes OpenXiangda skills by default.
 
+## AI design gate and resource CLI
+
+Architecture-class requests are plan-gated by default. For new apps, complex pages, login/register, public/no-login access, role/data-scope design, workflow/automation, App Function, connector, notification, and external integration work, AI agents must plan first and implement only after the user confirms the design.
+
+Before confirmation, agents may read, inspect, snapshot, dry-run, ask questions, and output/write the architecture document. They must not edit source files, mutate platform resources, publish, deploy, send notifications, or call live write/delete endpoints.
+
+Use the discoverable gate commands:
+
+```bash
+openxiangda doctor --profile dev --json
+openxiangda design gates --topic new-app,public-access --json
+openxiangda design template --topic auth,public-access
+openxiangda commands --json
+```
+
+For formal multi-resource development, keep the repository as the source of truth and use `src/resources/**`:
+
+```bash
+openxiangda resource validate --profile dev
+openxiangda resource plan --profile dev
+openxiangda resource publish --profile dev
+```
+
+For small live fixes, diagnosis, or AI command discovery, use first-class resource commands. They all accept `--profile`, `--app-type`, `--json`, `--json-file`, `--dry-run`, and write commands can use `--write-manifest` to avoid repo/platform drift:
+
+```bash
+openxiangda route upsert --json-file src/resources/routes/public_register.json --dry-run
+openxiangda public-access upsert --json-file src/resources/public-access/public_register.json --write-manifest
+openxiangda public-access session-test public_register --path /view/APP_XXX/public/register --json
+openxiangda public-access grant-check public_register --form-code registration_form --json
+openxiangda auth-config methods --json
+openxiangda function invoke submit_public_registration --body-json '{"input":{}}'
+openxiangda connector invoke sms.sendCode --body-json '{"body":{"phone":"13800000000"}}'
+openxiangda notification preview public_register_notice --body-json '{"variables":{"title":"测试"}}'
+openxiangda permission audit --json
+```
+
+调用和测试类命令会检查 JSON envelope。HTTP 200 但 `code: "PUBLIC_GRANT_DENIED"`、`success: false` 或其他字符串业务错误码会被当作失败。
+
 Codex skills are installed separately from login/profile state. Run `openxiangda skill install` after installing or linking the CLI. It installs the `openxiangda` root skill plus the 8 top-level subskills into `${CODEX_HOME:-~/.codex}/skills` by default:
 
 - `openxiangda`
@@ -205,16 +247,26 @@ import {
   PublicAccessGate,
 } from "openxiangda/runtime/react"
 
+const PublicLoading = () => <div role="status">正在进入公开页面</div>
+const PublicAccessError = ({ error }: { error: { message?: string } }) => (
+  <div role="alert">{error.message || "公开链接不可用或已过期"}</div>
+)
+
 <OpenXiangdaProvider appType={appType} servicePrefix="/service">
   <OpenXiangdaPageProvider>
-    <PublicAccessGate policyCode="public_register" routeCode="public.register">
+    <PublicAccessGate
+      errorFallback={error => <PublicAccessError error={error} />}
+      fallback={<PublicLoading />}
+      policyCode="public_register"
+      routeCode="public.register"
+    >
       <PublicRegisterPage />
     </PublicAccessGate>
   </OpenXiangdaPageProvider>
 </OpenXiangdaProvider>
 ```
 
-不要把 `PublicAccessGate` 单独放在没有 `OpenXiangdaProvider` / `OpenXiangdaPageProvider` 的页面树下；否则 public session 不能注入后续 SDK 请求，`usePageSdk()` 也会抛出 `usePageSdkStore 必须在 PageProvider 内使用`。
+不要把 `PublicAccessGate` 单独放在没有 `OpenXiangdaProvider` / `OpenXiangdaPageProvider` 的页面树下；否则 public session 不能注入后续 SDK 请求，`usePageSdk()` 也会抛出 `usePageSdkStore 必须在 PageProvider 内使用`。公开页面必须给 `PublicAccessGate` 配 `fallback` 和 `errorFallback`，避免慢网、缺 ticket、ticket 过期时出现空白页。
 
 多表只读查询和固定口径统计优先声明 `src/resources/data-views/*.json` 数据视图，而不是在页面里手写多次单表查询再拼数据。默认 `storageMode: "materialized"` 会创建 PostgreSQL materialized view，适合读多写少和可接受刷新延迟的列表/报表；`storageMode: "live"` 每次查询实时编译逻辑视图，适合强实时但数据量可控的复杂查询。`viewType: "aggregate"` 是统计聚合视图，适合按客户、状态、月份等维度聚合 count/sum/avg/min/max。发布时 CLI 会把 `formCode` 解析为当前 profile 的 `formUuid`；页面通过 `sdk.dataView.query(code, params)` 查询行级视图，通过 `sdk.dataView.stats(code, params)` 查询聚合视图，也可以用 `sdk.dataSource.run()` 路由 `dataView.query` / `dataView.stats`。materialized 模式应为常用筛选、排序、统计维度和时间桶声明 `indexes`，并确认用户能接受的刷新延迟；live 模式忽略 `indexes`，不需要刷新。