From d8da9c7b1acc86b4d9733784e477d38e5f6fc514 Mon Sep 17 00:00:00 2001 From: zhoulei Date: Thu, 20 Aug 2026 09:21:07 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B3=A8=E9=87=8A=E7=BA=A6=E5=AE=9A?= =?UTF-8?q?=E6=94=B9=E4=B8=BA=E6=AF=8F=E6=96=B9=E6=B3=95=E5=BF=85=E5=86=99?= =?UTF-8?q?=EF=BC=88=E4=BE=BF=E4=BA=8E=E4=BA=BA=E5=B7=A5=E5=A4=8D=E6=A0=B8?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- abacus-static-framework/.project.agents/AGENTS.md | 2 +- abacus-static-framework/.project.agents/SELF_CONSTRAINTS.md | 4 ++-- .../.project.agents/docs/context/CONVENTIONS.md | 2 +- abacus.springboot.example/.project.agents/AGENTS.md | 2 +- abacus.springboot.example/.project.agents/SELF_CONSTRAINTS.md | 4 ++-- .../.project.agents/docs/context/CONVENTIONS.md | 2 +- docs/coding-standards.md | 4 ++-- 7 files changed, 10 insertions(+), 10 deletions(-) diff --git a/abacus-static-framework/.project.agents/AGENTS.md b/abacus-static-framework/.project.agents/AGENTS.md index 85fa8ed..be8ffda 100644 --- a/abacus-static-framework/.project.agents/AGENTS.md +++ b/abacus-static-framework/.project.agents/AGENTS.md @@ -37,7 +37,7 @@ No automated tests (manual smoke only) Environment: Node 18.20.7, npm mirror `https://registry.npmmirror.com`. Before local integration, adjust `vite.config.ts` (`build.outDir` → target service's `resources/html/vue//`; `server.proxy` → target backend) and `public/data/data.js` (`currentSubsystem`). After a framework upgrade, run `npm install`; never overwrite `public`, `vite.config.ts`, or `src/subsystem`. ## Architecture & Coding Style -Use TypeScript, 2-space indentation. Kebab-case files, PascalCase component names (must equal the route `name`), `getXxx`/`saveXxx` API function names. Do not add modules that are not registered in `ARCHITECTURE.md`. Preserve the dependency DAG; no reverse dependencies and no cross-module private access. Avoid empty names such as `Manager`, `Helper`, `Util`, `Common`, `Misc`, or `Tools`. +Use TypeScript, 2-space indentation. Kebab-case files, PascalCase component names (must equal the route `name`), `getXxx`/`saveXxx` API function names. **Every method/function must carry a one-line responsibility comment** (manual-review friendly). Do not add modules that are not registered in `ARCHITECTURE.md`. Preserve the dependency DAG; no reverse dependencies and no cross-module private access. Avoid empty names such as `Manager`, `Helper`, `Util`, `Common`, `Misc`, or `Tools`. UI/presentation code should consume state and send intents only — business logic goes into hooks/services; keep data-model types thin. Data access must go through the `request` wrapper (`src/framework/utils/request.ts`) — never raw `axios`/`fetch`; the wrapper handles service-alias mapping, token refresh, commonParam header, and response unwrapping (see shared spec §6). diff --git a/abacus-static-framework/.project.agents/SELF_CONSTRAINTS.md b/abacus-static-framework/.project.agents/SELF_CONSTRAINTS.md index 7dad999..31180a5 100644 --- a/abacus-static-framework/.project.agents/SELF_CONSTRAINTS.md +++ b/abacus-static-framework/.project.agents/SELF_CONSTRAINTS.md @@ -42,8 +42,8 @@ - 派生文档发现与上游不一致 → 回去改上游，不能让派生文档自走 ### B4. 注释与命名 -- 默认不写注释；只在 WHY 不明显时写一行。 -- 不写解释 WHAT 的注释（命名应自解释）。 +- 每个方法/函数必须写注释（一行职责说明，便于人工复核）。 +- 只在 WHY 不明显处补充 WHY 注释；不写会随时间失效的注释。 - 不写"为某 issue/任务而加"这类会随时间失效的注释。 - 严格遵守 `CONVENTIONS.md` 中的命名规范（不存在则先补）。 diff --git a/abacus-static-framework/.project.agents/docs/context/CONVENTIONS.md b/abacus-static-framework/.project.agents/docs/context/CONVENTIONS.md index 3b54e59..7d4b915 100644 --- a/abacus-static-framework/.project.agents/docs/context/CONVENTIONS.md +++ b/abacus-static-framework/.project.agents/docs/context/CONVENTIONS.md @@ -49,7 +49,7 @@ ### 2.5 注释 -- 默认不写注释；只在 WHY 不明显时写一行；不写解释 WHAT 的注释。 +- 每个方法/函数必须写一行职责注释（便于人工复核）；只在 WHY 不明显处补充 WHY 注释；不写会随时间失效的注释。 ## 3. 提交规范 diff --git a/abacus.springboot.example/.project.agents/AGENTS.md b/abacus.springboot.example/.project.agents/AGENTS.md index 6c22e2d..b9af1aa 100644 --- a/abacus.springboot.example/.project.agents/AGENTS.md +++ b/abacus.springboot.example/.project.agents/AGENTS.md @@ -36,7 +36,7 @@ No automated tests (manual smoke only) Environment: Nacos must be reachable (bootstrap.yml: server-addr/namespace; extension-configs pull abacus-database/discovery/acas/redis/actuator/xxljob); build depends on the company Maven private repo (abacus framework jars); set `` to `abacus.springboot.`. ## Architecture & Coding Style -Use Java, 4-space indentation, max line width 120. Controllers: `@RestController` + `@RequestMapping` + springdoc `@Tag`/`@Operation`; `throws Exception`; `@RequestParam(required=false)`; blank-param guard throws `BusinessException`; **return business objects directly** (the wrapper builds the unified response). Services orchestrate in `esb/`; raw SQL lives in `impl/` and MUST use `?` placeholders (no string concatenation). Entities: `@Entity @Table @JsonIgnoreProperties(ignoreUnknown=true) @Schema`, `@Id String`, `@Version Integer`, `STATUS_*` constants, hand-written getters/setters. Business IDs come from `DaoIdGenerator` beans — never hand-craft UUIDs. +Use Java, 4-space indentation, max line width 120. **Every method must carry a one-line responsibility comment** (Javadoc style preferred; manual-review friendly). Controllers: `@RestController` + `@RequestMapping` + springdoc `@Tag`/`@Operation`; `throws Exception`; `@RequestParam(required=false)`; blank-param guard throws `BusinessException`; **return business objects directly** (the wrapper builds the unified response). Services orchestrate in `esb/`; raw SQL lives in `impl/` and MUST use `?` placeholders (no string concatenation). Entities: `@Entity @Table @JsonIgnoreProperties(ignoreUnknown=true) @Schema`, `@Id String`, `@Version Integer`, `STATUS_*` constants, hand-written getters/setters. Business IDs come from `DaoIdGenerator` beans — never hand-craft UUIDs. Do not add modules that are not registered in `ARCHITECTURE.md`. Preserve the dependency DAG; no reverse dependencies, no cross-feature imports, and no direct access to another module's private implementation. Avoid empty names such as `Manager`, `Helper`, `Util`, or `Common` for new code (legacy `util/`/`vo/` files are reference-only — cite but do not add). diff --git a/abacus.springboot.example/.project.agents/SELF_CONSTRAINTS.md b/abacus.springboot.example/.project.agents/SELF_CONSTRAINTS.md index 7dad999..31180a5 100644 --- a/abacus.springboot.example/.project.agents/SELF_CONSTRAINTS.md +++ b/abacus.springboot.example/.project.agents/SELF_CONSTRAINTS.md @@ -42,8 +42,8 @@ - 派生文档发现与上游不一致 → 回去改上游，不能让派生文档自走 ### B4. 注释与命名 -- 默认不写注释；只在 WHY 不明显时写一行。 -- 不写解释 WHAT 的注释（命名应自解释）。 +- 每个方法/函数必须写注释（一行职责说明，便于人工复核）。 +- 只在 WHY 不明显处补充 WHY 注释；不写会随时间失效的注释。 - 不写"为某 issue/任务而加"这类会随时间失效的注释。 - 严格遵守 `CONVENTIONS.md` 中的命名规范（不存在则先补）。 diff --git a/abacus.springboot.example/.project.agents/docs/context/CONVENTIONS.md b/abacus.springboot.example/.project.agents/docs/context/CONVENTIONS.md index d92f1ea..578fb0b 100644 --- a/abacus.springboot.example/.project.agents/docs/context/CONVENTIONS.md +++ b/abacus.springboot.example/.project.agents/docs/context/CONVENTIONS.md @@ -50,7 +50,7 @@ ### 2.5 注释 -- 默认不写注释；只在 WHY 不明显时写一行；不写解释 WHAT 的注释（命名应自解释）。 +- 每个方法必须写注释（一行职责说明，复杂方法补充入参/出参/边界，便于人工复核）；只在 WHY 不明显处补充 WHY 注释；不写会随时间失效的注释。 ## 3. 提交规范 diff --git a/docs/coding-standards.md b/docs/coding-standards.md index 682c958..3625fc3 100644 --- a/docs/coding-standards.md +++ b/docs/coding-standards.md @@ -432,8 +432,8 @@ public DaoIdGenerator jcBillIdGenerator() { ### 8.2 代码风格 -- Java：4 空格缩进、行宽 ≤ 120；**默认不写注释**，仅在 WHY 不明显处写一行注释。 -- TS/Vue：遵循框架现有风格；组件选项式 `name` + `