@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/contracts/AGENTS.md

@@ -0,0 +1,17 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放契约优先相关模板，覆盖 OpenAPI、mock、client 生成和联调说明。
+
+## 结构索引
+
+- `openapi.yaml`：契约主文件模板。
+- `orval.config.ts`：client 生成配置。
+- `prism-usage.md`：mock / 联调说明。
+- `README.md`：契约目录使用说明。
+
+## 修改规则
+
+- 契约字段、错误码、分页和统一响应结构应与 `context/API_MAP.md`、`design/frontend-architecture.md` 保持一致。
+- 改动契约模板时，不要忘记 client 生成链路和 mock 使用说明。

package/package-source/docs/codex-harness-engineering/templates/contracts/README.md

@@ -1,16 +1,24 @@
-# Contracts Templates Guide
-
-本目录提供 contract-first 开发的最小模板组合。
-
-## 推荐文件
-
-- `openapi.yaml`: 前后端共享真相源的 OpenAPI 样例
-- `orval.config.ts`: 生成 types / client / mocks 的 Orval 配置模板
-- `prism-usage.md`: 本地 mock server 和 validation proxy 的 Prism 用法模板
-
-## 推荐顺序
-
-1. 先完善 `openapi.yaml`
-2. 再配置 `orval.config.ts`
-3. 生成 client / mocks
-4. 用 `prism-usage.md` 跑本地 mock 与 contract 验证
+# Contracts Templates Guide
+
+本目录提供 contract-first 开发的最小模板组合。
+
+## 推荐文件
+
+- `openapi.yaml`: 前后端共享真相源的 OpenAPI 样例
+- `orval.config.ts`: 生成 types / client / mocks 的 Orval 配置模板
+- `prism-usage.md`: 本地 mock server 和 validation proxy 的 Prism 用法模板
+
+## 推荐顺序
+
+1. 先完善 `openapi.yaml`
+2. 再配置 `orval.config.ts`
+3. 生成 client / mocks
+4. 用 `prism-usage.md` 跑本地 mock 与 contract 验证
+
+## 最低契约要求
+
+- 请求入口统一通过 generated client 或项目约定的 `apiClient/httpClient`，不要在页面里直接拼 `fetch/axios/baseURL`。
+- 分页字段默认统一为 `page/pageSize`；如果项目另有约定，必须在 contract 和 API_MAP 中明确。
+- 响应结构必须统一，例如 `code/message/data` 或项目定义的等价结构；不要让前端猜 `res.data` 还是 `res.result`。
+- 错误模型必须显式定义，至少覆盖校验失败、权限失败、冲突和服务错误。
+- 前端类型优先从 contract 生成，不手写猜测字段。

package/package-source/docs/codex-harness-engineering/templates/contracts/openapi.yaml

@@ -1,182 +1,182 @@
-openapi: 3.0.3
-info:
-  title: Ticket Views API
-  version: 0.1.0
-  description: Contract-first example for a ticket filter and saved views workflow.
-servers:
-  - url: https://api.example.com
-tags:
-  - name: tickets
-  - name: ticket-views
-paths:
-  /tickets:
-    get:
-      tags: [tickets]
-      summary: List tickets with filters
-      operationId: listTickets
-      parameters:
-        - in: query
-          name: status
-          schema:
-            type: string
-            enum: [open, pending, resolved]
-        - in: query
-          name: priority
-          schema:
-            type: string
-            enum: [low, medium, high]
-        - in: query
-          name: assigneeId
-          schema:
-            type: string
-        - in: query
-          name: page
-          schema:
-            type: integer
-            minimum: 1
-            default: 1
-        - in: query
-          name: pageSize
-          schema:
-            type: integer
-            minimum: 1
-            maximum: 100
-            default: 20
-      responses:
-        "200":
-          description: Ticket list
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/TicketListResponse"
-        "400":
-          description: Invalid query
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorResponse"
-        "403":
-          description: Permission denied
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorResponse"
-  /ticket-views:
-    get:
-      tags: [ticket-views]
-      summary: List saved ticket views
-      operationId: listTicketViews
-      responses:
-        "200":
-          description: Saved ticket views
-          content:
-            application/json:
-              schema:
-                type: object
-                required: [items]
-                properties:
-                  items:
-                    type: array
-                    items:
-                      $ref: "#/components/schemas/TicketView"
-    post:
-      tags: [ticket-views]
-      summary: Create a saved ticket view
-      operationId: createTicketView
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/CreateTicketViewRequest"
-      responses:
-        "201":
-          description: Created
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/TicketView"
-        "400":
-          description: Invalid payload
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorResponse"
-        "409":
-          description: View name already exists
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorResponse"
-components:
-  schemas:
-    Ticket:
-      type: object
-      required: [id, title, status, priority]
-      properties:
-        id:
-          type: string
-        title:
-          type: string
-        status:
-          type: string
-          enum: [open, pending, resolved]
-        priority:
-          type: string
-          enum: [low, medium, high]
-        assigneeId:
-          type: string
-          nullable: true
-    TicketListResponse:
-      type: object
-      required: [items, page, pageSize, total]
-      properties:
-        items:
-          type: array
-          items:
-            $ref: "#/components/schemas/Ticket"
-        page:
-          type: integer
-        pageSize:
-          type: integer
-        total:
-          type: integer
-    TicketFilter:
-      type: object
-      properties:
-        status:
-          type: string
-          enum: [open, pending, resolved]
-        priority:
-          type: string
-          enum: [low, medium, high]
-        assigneeId:
-          type: string
-    TicketView:
-      type: object
-      required: [id, name, filters]
-      properties:
-        id:
-          type: string
-        name:
-          type: string
-        filters:
-          $ref: "#/components/schemas/TicketFilter"
-    CreateTicketViewRequest:
-      type: object
-      required: [name, filters]
-      properties:
-        name:
-          type: string
-          minLength: 1
-          maxLength: 100
-        filters:
-          $ref: "#/components/schemas/TicketFilter"
-    ErrorResponse:
-      type: object
-      required: [code, message]
-      properties:
-        code:
-          type: string
-        message:
-          type: string
+openapi: 3.0.3
+info:
+  title: Ticket Views API
+  version: 0.1.0
+  description: Contract-first example for a ticket filter and saved views workflow.
+servers:
+  - url: https://api.example.com
+tags:
+  - name: tickets
+  - name: ticket-views
+paths:
+  /tickets:
+    get:
+      tags: [tickets]
+      summary: List tickets with filters
+      operationId: listTickets
+      parameters:
+        - in: query
+          name: status
+          schema:
+            type: string
+            enum: [open, pending, resolved]
+        - in: query
+          name: priority
+          schema:
+            type: string
+            enum: [low, medium, high]
+        - in: query
+          name: assigneeId
+          schema:
+            type: string
+        - in: query
+          name: page
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - in: query
+          name: pageSize
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+      responses:
+        "200":
+          description: Ticket list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TicketListResponse"
+        "400":
+          description: Invalid query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "403":
+          description: Permission denied
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /ticket-views:
+    get:
+      tags: [ticket-views]
+      summary: List saved ticket views
+      operationId: listTicketViews
+      responses:
+        "200":
+          description: Saved ticket views
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [items]
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/TicketView"
+    post:
+      tags: [ticket-views]
+      summary: Create a saved ticket view
+      operationId: createTicketView
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateTicketViewRequest"
+      responses:
+        "201":
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TicketView"
+        "400":
+          description: Invalid payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "409":
+          description: View name already exists
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+components:
+  schemas:
+    Ticket:
+      type: object
+      required: [id, title, status, priority]
+      properties:
+        id:
+          type: string
+        title:
+          type: string
+        status:
+          type: string
+          enum: [open, pending, resolved]
+        priority:
+          type: string
+          enum: [low, medium, high]
+        assigneeId:
+          type: string
+          nullable: true
+    TicketListResponse:
+      type: object
+      required: [items, page, pageSize, total]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/Ticket"
+        page:
+          type: integer
+        pageSize:
+          type: integer
+        total:
+          type: integer
+    TicketFilter:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [open, pending, resolved]
+        priority:
+          type: string
+          enum: [low, medium, high]
+        assigneeId:
+          type: string
+    TicketView:
+      type: object
+      required: [id, name, filters]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        filters:
+          $ref: "#/components/schemas/TicketFilter"
+    CreateTicketViewRequest:
+      type: object
+      required: [name, filters]
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+        filters:
+          $ref: "#/components/schemas/TicketFilter"
+    ErrorResponse:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string

package/package-source/docs/codex-harness-engineering/templates/contracts/orval.config.ts

@@ -1,20 +1,20 @@
-import { defineConfig } from "orval";
-
-export default defineConfig({
-  ticketApi: {
-    input: "./contracts/openapi.yaml",
-    output: {
-      target: "./packages/api-client/generated/ticket-api.ts",
-      schemas: "./packages/api-client/generated/model",
-      client: "react-query",
-      mock: true,
-      mode: "split",
-      override: {
-        mutator: {
-          path: "./packages/api-client/http-client.ts",
-          name: "httpClient",
-        },
-      },
-    },
-  },
-});
+import { defineConfig } from "orval";
+
+export default defineConfig({
+  ticketApi: {
+    input: "./contracts/openapi.yaml",
+    output: {
+      target: "./packages/api-client/generated/ticket-api.ts",
+      schemas: "./packages/api-client/generated/model",
+      client: "react-query",
+      mock: true,
+      mode: "split",
+      override: {
+        mutator: {
+          path: "./packages/api-client/http-client.ts",
+          name: "httpClient",
+        },
+      },
+    },
+  },
+});

package/package-source/docs/codex-harness-engineering/templates/contracts/prism-usage.md

@@ -1,34 +1,41 @@
-# Prism Usage 模板
-
-## 1. 目标
-
-用 Prism 在真实后端完成前提供:
-
-- mock server
-- request/response contract 验证
-- 异常态联调入口
-
-## 2. 安装
-
-```bash
-npm install -D @stoplight/prism-cli
-```
-
-## 3. 启动 mock server
-
-```bash
-npx prism mock contracts/openapi.yaml -h 0.0.0.0
-```
-
-## 4. 启动 validation proxy
-
-```bash
-npx prism proxy contracts/openapi.yaml https://api.example.com
-```
-
-## 5. 推荐联调顺序
-
-1. 先用 Prism mock 跑前端
-2. 再生成 Orval client / mocks
-3. 前端先围绕 generated client 写页面和测试
-4. 最后切真实后端并跑 Prism proxy
+# Prism Usage 模板
+
+## 1. 目标
+
+用 Prism 在真实后端完成前提供:
+
+- mock server
+- request/response contract 验证
+- 异常态联调入口
+
+## 2. 安装
+
+```bash
+npm install -D @stoplight/prism-cli
+```
+
+## 3. 启动 mock server
+
+```bash
+npx prism mock contracts/openapi.yaml -h 0.0.0.0
+```
+
+## 4. 启动 validation proxy
+
+```bash
+npx prism proxy contracts/openapi.yaml https://api.example.com
+```
+
+## 5. 推荐联调顺序
+
+1. 先用 Prism mock 跑前端
+2. 再生成 Orval client / mocks
+3. 前端先围绕 generated client 写页面和测试
+4. 最后切真实后端并跑 Prism proxy
+
+## 6. 联调检查点
+
+- request 参数名是否和 contract 一致，例如 `page/pageSize`
+- response 包装层是否和 contract 一致，例如 `code/message/data`
+- 错误响应是否都能命中 `ErrorResponse` 或项目定义的统一错误模型
+- 前端是否已经切到 generated client，而不是继续手写一套 request schema

package/package-source/docs/codex-harness-engineering/templates/design/AGENTS.md

@@ -0,0 +1,21 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放前端先行、图转前端和视觉评审链路的模板。
+
+## 结构索引
+
+- `design-brief.md`：设计约束说明。
+- `component-map.md`：组件映射。
+- `screen-states.md`：状态矩阵。
+- `image-to-frontend-spec.md`：图转前端规格。
+- `frontend-architecture.md`：前端实现边界。
+- `ui-image-review.md` / `visual-parity-review.md`：视觉评审模板。
+- `design-tokens.json`：视觉 token。
+- `assets/`：设计资产说明。
+
+## 修改规则
+
+- 这个目录关注“可编码设计真相源”，不是品牌展示稿仓库。
+- 页面状态、移动端、安全区、组件复用和视觉证据要求要与 `testing/`、`docs/frontend-quality-rules.md` 对齐。