chore(backend): 落地 ADS 治理体系、升级日志并收录后端模板基线代码

abacus.springboot.example/.project.agents/AGENTS.md

@@ -0,0 +1,56 @@
+# Repository Guidelines
+
+AGENTS.md is the cross-vendor contributor guide (Claude, Codex, and others read it). Keep it in English by convention. It overlaps CLAUDE.md on purpose — this is the canonical version for non-Claude agents.
+
+## Authority & Required Reading
+Rules in `.project.agents/CLAUDE.md` apply to every agent working here. Direct user instructions still take precedence.
+
+The canonical contributor guide is `.project.agents/AGENTS.md`. Do not create or maintain a root-level `AGENTS.md` unless the user explicitly asks for one.
+
+Before any code-changing task, read `.project.agents/SELF_CONSTRAINTS.md` and `.project.agents/VIBECODING_GUIDE.md`, then run `git status --short`. For product work, also read the relevant sections of `PRD.md`, `ARCHITECTURE.md`, `ROADMAP.md`, and `CONVENTIONS.md` under `.project.agents/docs/context/`. Shared front-backend constraints live in the workspace-level `docs/` (see `../../../docs/coding-standards.md`) — read the referenced sections instead of duplicating them here.
+
+## Project Structure & Module Organization
+`abacus.springboot.example` is a Spring Boot Maven microservice template (multi-database + abacus framework), parent `abacus.framework:abacus.springcloud.pom:1.5.0`. Business code lives in `src/main/java/abacus/springboot.<app>.{api,controller,dao,esb,pi,impl,repository,wsi,config,util,vo}/` (reference template: the `example` JcBill vertical slice, copy-and-rewrite); config in `src/main/resources/config/{dev,test,prod}/`; SQL in `src/main/resources/sql/`. No automated tests.
+
+Target architecture is documented in `ARCHITECTURE.md`: layered packages (api/controller → esb/wsi → pi/impl/repository → dao) with unified response-body wrapping and BusinessException-based errors.
+
+## Source-of-Truth Rules
+`PRD.md` defines behavior and scope.
+`ARCHITECTURE.md` is the authority for modules, dependencies, contracts, and directory layout. Derived documents follow upstream changes, not the other way around.
+
+Feature changes must update `PRD.md`. Module, dependency, entity, or invariant changes must update `ARCHITECTURE.md` in the same commit. Do not let code and architecture drift for more than 24 hours.
+
+## Build, Test, and Development Commands
+
+```sh
+# Build (produces target/*-bin.zip: jar + doc + sql + html)
+mvn package -Pdev -DskipTests
+
+# Run
+mvn spring-boot:run
+
+# Test
+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 `<artifactId>` to `abacus.springboot.<app>`.
+
+## 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.
+
+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).
+
+UI/presentation code should consume state and send intents only — put business logic in services/use cases, and keep data-model types thin. Controllers must not write SQL or touch repositories directly; orchestration goes through `esb` services.
+
+## Testing Guidelines
+No automated test framework. Required validation from `ARCHITECTURE.md`: manual smoke per API (list / query / create / edit / export) plus real-environment checks. Multi-datasource routing, Kafka consumption, XXL-JOB scheduling, Nacos config pull, and real database migrations require real-environment validation; mock/simulator-only evidence is not enough for those claims.
+
+## Git, Logs, and PRs
+Do not pile new work onto unrelated dirty changes without calling it out. Prefer Conventional Commits such as `feat: ...`, `fix: ...`, `docs: ...`. This repository is part of a single git repo rooted at the workspace (`D:\workBuddySpace\member`); commit scope should stay within this subproject unless the change is cross-project (docs/).
+
+Each independently verifiable feature, milestone, non-trivial fix, or refactor needs an execution log in `.project.agents/log/YYYY-MM-DD-<slug>.md` unless it is only a minor documentation edit. Logs must include what changed, relevant commits (or "uncommitted" with reason), verification performed, and next steps. Feature updates also append to `src/main/resources/doc/升级日志.md` per the shared spec §5.11.
+
+Pull requests should include scope, linked issues, screenshots for UI changes, environment/device coverage, and any documentation updates.
+
+## Security & Configuration
+Do not commit secrets, credentials, build output, or personal IDE files. Nacos credentials and datasource settings live in `src/main/resources/config/<env>/` (git-tracked per team convention) — do not add new secrets outside those files. Agent configuration and generated agent notes belong under `.project.agents/`, not the repository root, `.claude/`, or a global home directory.

abacus.springboot.example/.project.agents/CLAUDE.md

@@ -0,0 +1,63 @@
+# CLAUDE.md
+
+This file guides Claude Code (and other agents) when working in this repository.
+**保持本文件最新**：它是项目级入口——项目是什么、怎么构建、门控一切变更的规则。
+
+## Project
+
+`abacus.springboot.example` 是 **Spring Boot Maven 微服务模板**（多数据库 + abacus 框架），父工程 `abacus.framework:abacus.springcloud.pom:1.5.0`。业务代码位于 `src/main/java/abacus/springboot.<应用名>.{api,controller,dao,esb,pi,impl,repository,wsi,config,util,vo}/`（参考模板：`example` 下的 JcBill 稽查示例，供复制改写）；配置位于 `src/main/resources/config/{dev,test,prod}/`，SQL 位于 `src/main/resources/sql/`。
+
+- Entry point: `src/main/java/abacus/springboot/example/Application.java`
+- **分层即契约**：`api(+api/view)` / `controller` / `dao`(Entity) / `esb`(Service 编排) / `pi`(数据访问 IF) / `impl`(原生 SQL 实现) / `repository`(Spring Data JPA) / `wsi`(ServiceIF) / `config` / `util` / `vo`；扫描配置 `springdoc.packages-to-scan=.api`、`abacus.entitypackages=.dao`、`abacus.controllerPackages=.controller`。
+- **统一响应体**由 `abacus.commons` 的 `ResultResponseBodyWrapper` 包装（`Application.java` 注册 `@Bean`），Controller 直接 return 业务对象；业务异常统一抛 `BusinessException`。
+- Known environment constraints: Nacos（bootstrap.yml 配置 server-addr/namespace，extension-configs 引入 abacus-database/discovery/acas/redis/actuator/xxljob 公共配置）；Maven profile `dev`（默认）/`test`/`prod` 决定加载 `config/<env>/`；多数据库驱动已内置（MySQL/jtds+mssql/Oracle/达梦）。
+
+## Common commands
+
+```sh
+# Build（产出 target/*-bin.zip：jar + doc + sql + html）
+mvn package -Pdev -DskipTests
+
+# Run
+mvn spring-boot:run
+
+# Test
+无自动化测试（人工冒烟验证）
+```
+
+环境注意：Nacos 需可达（配置中心/注册中心）；构建依赖公司 Maven 私服（abacus 二方框架 jar）；`pom.xml` `<artifactId>` 建议为 `abacus.springboot.<应用名>`。
+
+## Architecture
+
+实现遵循 `.project.agents/docs/context/ARCHITECTURE.md` 的模块边界；模块清单（职责一句话）：
+
+- **api / controller**：接口层（对外接口与前端/内部接口），Controller 只做参数校验与编排调用，直接 return 业务对象。
+- **esb / wsi**：Service 编排层（@Service）与对外服务接口（*ServiceIF），只编排不做 SQL。
+- **dao**：JPA 实体（表映射，含状态常量与 @Version 乐观锁）。
+- **pi / impl**：数据访问接口与实现（原生 SQL 全量参数化）。
+- **repository**：Spring Data JPA 仓储（派生查询 findByXxx）。
+- **config**：@Configuration（DaoIdGenerator、AbacusConfigNote 等基础设施 Bean）与配置常量。
+- 前后端共享约束见工作区 `docs/`（`../../../docs/coding-standards.md` §5 后端规范、§6 接口契约）。
+
+## Project-level rules
+
+- **动手前必读两文件**——它们编码了本项目所有门控决策的经验：
+  - `.project.agents/VIBECODING_GUIDE.md` — 实践指南（为什么 & 怎么做）
+  - `.project.agents/SELF_CONSTRAINTS.md` — 硬约束（什么禁止、什么必须、何时停下）
+
+  任何非平凡任务，编辑前先跑 `SELF_CONSTRAINTS.md §A`（开工前自检）。
+
+- **共享约束单一来源**：前后端共享的编码规范/接口契约/命名纪律，**只存在于工作区 `docs/`（`../../../docs/coding-standards.md`、`../../../docs/architecture.md`、`../../../docs/agent-guide.md`）**；本仓库 `.project.agents/docs/context/` 只写本仓库特有内容与指针，**禁止复制 docs/ 正文**。改共享内容先改 docs/ 再同步指针。
+
+- **Agent 配置**一律写在 `.project.agents/` 下（或子目录），禁止写到仓库根、`.claude/` 或全局目录。
+
+- **项目文档**位于 `.project.agents/docs/context/`（单层目录）：`PRD.md`（行为权威）、`ARCHITECTURE.md`（模块/依赖/契约）、`ROADMAP.md`（里程碑）、`CONVENTIONS.md`（命名/风格/提交）。
+
+- **源真相层级**（冲突时上游优先）：
+  ```
+  PRD.md > ARCHITECTURE.md > CONVENTIONS.md > 派生文档
+  仓库级 CONVENTIONS 再下接共享 docs/coding-standards.md（仅作全仓公共约定引用）
+  ```
+  上游变更须在同 commit 内回写受影响的派生文档；代码与架构漂移不得超过 24 小时。
+
+- **路线图执行规则**：按 `.project.agents/docs/context/ROADMAP.md` 顺序推进，勾选与完成同 commit；milestone 级/多文件任务先写 plan/spec 再动手；每个 milestone 后按 `.project.agents/log/` 模板写执行日志。

abacus.springboot.example/.project.agents/SELF_CONSTRAINTS.md

@@ -0,0 +1,130 @@
+# Agent 自我约束清单（本项目硬规则）
+
+> 这是 Agent 在本项目工作时必须遵守的硬约束。每次开工前自查本清单，违反任何一条都应**先停下**，与用户对齐后再继续。
+> 完整背景与原理请见 [`VIBECODING_GUIDE.md`](./VIBECODING_GUIDE.md)。本清单只列"不许做什么 / 必须做什么"。
+>
+> 文档约定（本项目）：上游文档位于 `.project.agents/docs/context`，依次为
+> `PRD.md`（行为与范围）、`ARCHITECTURE.md`（模块/依赖/契约/目录）、`CONVENTIONS.md`（命名/风格/提交）。
+> 派生文档不得反向修改上游。
+
+---
+
+## A. 开工前的强制自检（每个新会话开始时执行）
+
+在进行任何编辑动作之前，必须确认以下事项；任一项不满足则先暂停业务任务，处理掉再继续。
+
+- [ ] **A1. 仓库是否在版本控制下？** 若否：立即停下，先初始化仓库 + 配置 ignore + 初始 commit。
+- [ ] **A2. 工作区是否干净？** 有未提交的旧改动？先与用户确认是否要先提交/暂存，**不允许在脏工作区上叠加新改动**。
+- [ ] **A3. 是否已有 `ARCHITECTURE.md`？**
+  - 若否，且本次任务**涉及写业务代码**：先停下，按 `VIBECODING_GUIDE` 的流程产出架构文档，再写代码。
+  - 若否，且本次任务**只是文档/讨论**：可继续，但应主动提醒用户补架构文档。
+- [ ] **A4. 任务的归属模块清楚吗？** 我能否在 `ARCHITECTURE.md` 的模块清单里指出"这个改动属于哪个模块"？指不出来则停下补架构。
+- [ ] **A5. 上游文档是否已读？** `PRD.md` / `ARCHITECTURE.md` / `CONVENTIONS.md` 中与本任务相关的章节是否读过？没读过先读，不要凭印象动手。
+
+---
+
+## B. 写代码时的硬约束
+
+### B1. 模块边界
+- ❌ 不允许新增**未在 `ARCHITECTURE.md` 中登记**的模块；要新增必须先更新架构文档。
+- ❌ 不允许引入**反向依赖**（低层模块依赖高层模块）。需要时改为接口/回调倒置。
+- ❌ 不允许跨模块**直接访问私有实现**；只能走该模块对外暴露的接口。
+- ❌ 不允许出现 `Manager` / `Helper` / `Util` / `Common` / `Misc` / `Tools` 这类语义为空的新模块名；用动词+名词描述真实职责。
+
+### B2. 单一职责
+- ❌ 不允许在 UI/展示层写业务判断或副作用（仅消费状态、发送意图）。
+- ❌ 不允许在数据模型类里堆业务方法；模型保持瘦，逻辑放 Service / UseCase。
+- ❌ 不允许"顺手"修改不在任务范围内的模块；越界的改动走单独提交并明确告知用户。
+
+### B3. 文档同步（与代码改动**同一个 commit** 内）
+- 加/删/改功能 → 同步更新 `PRD.md`
+- 加/删/改模块或依赖 → 同步更新 `ARCHITECTURE.md`（模块清单 + 依赖图）
+- 派生文档发现与上游不一致 → 回去改上游，不能让派生文档自走
+
+### B4. 注释与命名
+- 默认不写注释；只在 WHY 不明显时写一行。
+- 不写解释 WHAT 的注释（命名应自解释）。
+- 不写"为某 issue/任务而加"这类会随时间失效的注释。
+- 严格遵守 `CONVENTIONS.md` 中的命名规范（不存在则先补）。
+
+### B5. 错误处理
+- 只在系统边界（用户输入、外部 API、文件 IO）做防御；内部模块互相信任。
+- 不为不可能发生的情况加 fallback。
+- 不引入向后兼容 shim，除非用户明确要求。
+
+### B6. 实施日志（execution log）
+- **每完成一个可独立验收的部分（milestone 或子任务），必须在 `.project.agents/log` 写日志**。格式与时机见 `VIBECODING_GUIDE`。
+- 日志内必须包含本段的版本控制提交列表；若本段未提交，明确写出"未提交"及原因。
+- 完成路线图任一 milestone → **必须**写日志，且与该 milestone 的提交同一会话完成。
+- 单次会话即将结束（用户表示收工 / 上下文将被压缩）→ **必须**写一份兜底日志记录当前状态与下一步。
+- ❌ 不允许只提交不写日志（除非属于豁免情况：纯文档微调 / 被回滚的实验性探索）。
+- ❌ 不允许写日志但跳过更新 `ARCHITECTURE.md` —— 若本段触发架构变更，先改架构、再提交、再写日志。
+
+---
+
+## C. 改动范围控制
+
+- ❌ 一次任务一个目的。不要"既加功能又重构又改样式"。
+- ❌ 不允许在 bug 修复任务中做无关清理。
+- ❌ 不允许引入"为未来准备"的抽象（YAGNI）；三处相似优于一处过度抽象。
+- ❌ 不允许半完成的实现（要么这次完成，要么不要开始）。
+
+---
+
+## D. 出问题时的排查纪律
+
+bug 处理必须按下列顺序，**严禁跳步**：
+
+1. 复现现象（明确触发路径）
+2. 在 `ARCHITECTURE.md` 上**圈出嫌疑模块**
+3. 检查跨模块**接口契约**
+4. 缩小到单模块后再读代码
+5. 修完后：若是架构问题，必须更新 `ARCHITECTURE.md` 或 `CONVENTIONS.md`
+
+**禁止行为**：bug 一来就全仓 grep、试改一行看效果、连续 try-fail 循环。出现这种倾向立刻停下，回到第 2 步。
+
+---
+
+## E. 与用户的协作约束
+
+- ❌ 不替用户做架构决策。涉及模块拆分、依赖方向、命名规范这类**长期影响**的决定，必须明确询问。
+- ❌ 不在用户没要求的时候主动创建文档（除非本清单或 `CLAUDE.md` 已要求）。
+- ❌ 不在没看代码的情况下凭推测回答 "X 是怎么实现的"。
+- ✅ 每次涉及架构/文档/规范变更，先告知影响面，再动手。
+- ✅ 用户的明确指示永远高于本清单和任何 skill。冲突时遵循用户。
+
+---
+
+## F. 触发"全员停车"的红线
+
+出现以下任一情况，**立即停止当前任务，与用户对齐后再决定下一步**：
+
+1. 发现自己在脏工作区上累积了大量未提交改动
+2. 发现自己正在新增一个"无处归属"的模块/文件
+3. 发现代码与 `ARCHITECTURE.md` 已经矛盾，且无法用小补丁同步
+4. 同一个 bug 连续 3 次尝试修复未果
+5. 用户的请求与本清单 / `CLAUDE.md` / 上游文档存在冲突 —— 必须先澄清，不能默默选边
+6. 即将做出"难以回滚"的动作（删除文件 / 重命名模块 / 调整目录结构 / 强制 push）
+
+---
+
+## G. 文件路径合规
+
+- Agent 的配置文件**只**写入 `.project.agents` 子树，禁止写入仓库根目录或其他非约定位置。
+- 项目文档**只**写入 `.project.agents/docs/context`（不允许再分子目录，除非用户明确要求）。
+- 本清单（`SELF_CONSTRAINTS.md`）与指南（`VIBECODING_GUIDE.md`）位于 `.project.agents` 根，与 `CLAUDE.md` 同级。
+
+---
+
+## H. 自查触发器（什么时候重读本清单）
+
+至少在以下时机重读本清单：
+
+- 新会话开始，且任务涉及代码改动
+- 用户要求"加新功能"/"修 bug"/"重构"
+- 自己感到"差不多可以直接动手了" —— 这种感觉本身就是触发器
+- 即将创建超过 1 个新文件
+- 即将修改 3 个以上文件
+- 即将修改任何 `.project.agents/docs/context` 下的文档
+- **完成一个路线图 milestone 或子任务前**（确认是否需要按 §B6 写日志）
+- **会话即将结束前**（确认兜底日志已写）

abacus.springboot.example/.project.agents/VIBECODING_GUIDE.md

@@ -0,0 +1,250 @@
+# 项目开发实践指南（VIBECODING GUIDE）
+
+> 本文档是基于"踩过的坑"沉淀下来的项目工作方式约定，适用于本仓库及后续所有同性质的项目。
+> 它的姊妹文件是 [`SELF_CONSTRAINTS.md`](./SELF_CONSTRAINTS.md) —— 那是 Agent 每次开工前必须自查的硬约束清单。
+> 本文回答 "为什么这么做"；`SELF_CONSTRAINTS.md` 回答 "具体不许做什么"。
+
+---
+
+## 0. 三条核心教训（本指南的来由，优先级严格递减）
+
+1. **版本控制必须从第 0 天开始。**
+   不是 "等做出点东西再说"，是写第一行代码之前先初始化仓库、写好 ignore 规则、提交一个空骨架。
+   理由：高频改动 + 频繁推翻是 AI 协作的常态，没有版本控制兜底就等于在悬崖边裸奔。
+
+2. **文档必须在写代码之前定下来。**
+   需求、架构、路线图、开发规范、目录结构、命名规范、模块边界 —— 这些不是"做完之后补的"，是"做之前定的"。
+   理由：一旦上下文被代码细节占满，后续每个新会话都只能 freestyle，项目会朝不可逆的方向漂移。
+
+3. **架构 > UI > 用户体验。**
+   最致命的不是界面丑、不是体验差，而是模块互相纠缠到无法定位问题。
+   一个出问题就能立刻指认 "是 X 模块的责任" 的项目，比一个好看但耦合一团的项目，存活率高一个数量级。
+   理由：耦合一旦发生，AI 协作模式会迅速放大它 —— 因为每次新会话都看不全全貌，只会在原有耦合上继续添乱。
+
+> 这三条的优先级是严格递减的：先有版本控制，再有文档，再谈架构；架构稳了之后才轮到 UI 和体验。
+
+---
+
+## 1. 项目启动 Checklist（Day 0）
+
+下列每一项都必须在写第一行业务代码之前完成。顺序即优先级。
+
+### 1.1 仓库与版本控制
+- [ ] 初始化版本控制并立即建立 ignore 规则（语言 / IDE / 系统三类至少齐全）
+- [ ] 提交一个 **空骨架 commit**（README + ignore 规则 + 空目录结构），作为"零点参照系"
+- [ ] 约定分支模型（最简：主干 + 短命的功能分支；不要等到分叉时才想）
+- [ ] 约定 commit message 风格（推荐 Conventional Commits，至少要求动词开头 + 一句话原因）
+
+### 1.2 文档骨架（必须先于代码存在）
+在 `.project.agents/docs/context` 下建立以下文件，**哪怕只有大纲也比没有强**：
+
+| 文件 | 角色 | 上下游关系 |
+|---|---|---|
+| `PRD.md` | 产品需求（要做什么） | 上游 |
+| `ARCHITECTURE.md` | 架构（怎么拆） | 上游 |
+| `ROADMAP.md` | 路线图（什么时候做哪一块） | 由需求 + 架构推导 |
+| `CONVENTIONS.md` | 开发规范（命名、目录、提交、风格） | 上游 |
+| 派生文档（实现 spec / 资产清单等） | 屏幕级实现 / 资产清单 | **派生**，由上游产生 |
+
+**判断标准**：如果一个新会话的 Agent 只读需求 + 架构 + 开发规范就能正确开始一个任务 —— 文档就算合格。
+
+### 1.3 Agent 协作配置
+- [ ] 在 `CLAUDE.md` 写明项目级规则（已有，保持更新）
+- [ ] 在本文件 + `SELF_CONSTRAINTS.md` 中固化经验
+- [ ] 在 `.project.agents/settings.json` 中配置必要的 hook / 权限（不要散落到根目录或全局）
+
+---
+
+## 2. 架构原则
+
+### 2.1 三条硬规则
+
+1. **单一职责到模块级**
+   每个模块只回答一个问题。
+   反例："一个模块既管数据持久化，又管网络请求，又管 UI 状态" —— 这种模块必须拆。
+
+2. **依赖方向单向**
+   高层依赖低层，UI 依赖业务，业务依赖数据；**反向依赖一律禁止**，遇到就用接口/事件/回调倒置。
+   依赖关系必须能画成一张**有向无环图（DAG）**，且这张图要在 `ARCHITECTURE.md` 里画出来。
+
+3. **跨模块只走"接口契约"**
+   模块 A 想用模块 B 的能力，只能通过 B 暴露的接口/协议，不能 reach into B 的内部实现。
+   接口契约必须在 `ARCHITECTURE.md` 中显式声明（哪怕只是函数签名清单）。
+
+### 2.2 判断架构是否健康的三个问句
+
+随时可以用这三个问句自检：
+
+1. **指认问题**：现在出 bug 了，我能否在 30 秒内指出"这是哪个模块的责任"？
+2. **替换实现**：如果要把模块 X 整体换掉（换数据库、换框架），改动是否能控制在 X 内部 + 一个接口适配层？
+3. **新增功能归属**：用户要加一个新功能，我能否立刻说出它"属于哪个模块、或需要新增哪个模块"？
+
+任何一个回答不出来，架构就有问题，**先停下修架构，再写代码**。
+
+### 2.3 反耦合纪律
+
+- **不在新功能开发时顺手重构无关模块**（重构走单独 commit + 单独会话）
+- **不在 UI 层做业务判断**（UI 只接收状态、发送意图）
+- **不让数据模型自己跑业务逻辑**（模型类保持瘦，业务放 Service / UseCase）
+- **不要"为了少写一个文件"把两个模块塞进同一个文件**
+
+---
+
+## 3. 项目架构文档生成流程
+
+这是从零到 `ARCHITECTURE.md` 的标准流程。每一步都有产出物，下一步必须基于上一步的产出物。
+
+### Step 1 — 需求收敛（产出 `PRD.md`）
+- 列功能清单，按 **核心 / 增强 / 可选** 三档分类
+- 每个核心功能写一句 "用户故事"（"作为 X，我想 Y，以便 Z"）
+- **冻结 MVP 范围**：圈出 MVP 包含哪些核心功能，其余明确标 "Out of MVP"
+
+### Step 2 — 领域建模（产出 `ARCHITECTURE.md` §1 领域模型）
+- 列出所有**名词实体**（用户、订单、会话…）
+- 标注每个实体的字段、关系、生命周期
+- 标记哪些是**持久化实体**，哪些是**瞬态状态**
+
+### Step 3 — 模块划分（产出 `ARCHITECTURE.md` §2 模块清单）
+对照领域模型与需求功能清单，拆分模块。每个模块写一张卡片：
+
+```
+## 模块名：<Name>
+- 职责：一句话
+- 不负责：明确写出"不做什么"（防止职责蔓延）
+- 输入：从哪些模块/外部来
+- 输出：暴露给谁
+- 关键类型/接口：列签名（不写实现）
+- 持有状态：有没有自己的状态？
+```
+
+**经验**：如果一个模块的"不负责"写不出来，说明它的职责还没想清楚，回到 Step 2。
+
+### Step 4 — 依赖图（产出 `ARCHITECTURE.md` §3 依赖图）
+- 画出模块间依赖箭头（推荐 Mermaid，纯文本可 diff）
+- **手动验证 DAG**：从任一节点 DFS 不应回到自己
+- 标出"接口边界"：哪些依赖是接口注入，哪些是直接调用
+
+### Step 5 — 路线图（产出 `ROADMAP.md`）
+按依赖图的拓扑顺序排开发节奏：
+- 先做被依赖最多的底层模块
+- 每个 milestone 必须能独立通过编译/构建并跑出某种"可见行为"
+- 写明每个 milestone 完成的"验收标准"（不是"做完了"，是"做完了之后能演示什么"）
+
+### Step 6 — 开发规范（产出 `CONVENTIONS.md`）
+- 命名（类型 / 文件 / 目录 / 资产）
+- 代码风格（缩进 / 注释策略 / 错误处理边界）
+- 提交规范
+- 测试策略（哪些必须有测试，哪些不要求）
+
+### Step 7 — 派生文档（产出实现 spec / 资产清单等）
+**只有上面 6 步都齐了，才能开始写派生文档**。
+派生文档必须显式引用上游章节（"对应 `ARCHITECTURE.md` §2.3 的 XxxService 模块"），方便后续 diff 校验。
+
+---
+
+## 4. 文档变更协议
+
+文档不是写完就锁死的，但变更必须**沿着上下游传播**：
+
+| 变更点 | 必须同步更新 |
+|---|---|
+| 需求加/删/改功能 | 架构模块清单、路线图、派生文档 |
+| 架构调整模块边界 | 依赖图、开发规范（如有命名调整）、派生文档 |
+| 加新模块 | 架构 §2 + §3、路线图、开发规范（如新目录） |
+
+**权威链**：`PRD.md > ARCHITECTURE.md > CONVENTIONS.md > 派生文档`。
+派生文档永远不能**反向**修改上游。如果在派生文档中发现矛盾，回去改上游，再让派生文档重新对齐。
+**代码与架构漂移 > 24 小时即违规。**
+
+---
+
+## 5. 实施日志（execution log）
+
+写代码 / 执行路线图期间，**每完成一个可独立验收的"部分"，必须在 `.project.agents/log` 写一份日志**。日志是给"下一个会话的我"看的 —— 让接手的会话能在不读所有代码的情况下知道：刚才完成了什么、哪些提交、下一步是什么。
+
+### 5.1 何时写日志
+- 完成一个路线图 milestone
+- 完成一个 milestone 内独立可验收的子任务
+- 完成一次非平凡的重构 / bug 修复
+- 当前会话即将结束时（兜底，把上下文沉淀下来）
+
+**判断标准**：如果这段工作下一个会话需要知道，就写。
+
+### 5.2 日志文件命名
+`.project.agents/log/YYYY-MM-DD-<slug>.md`
+- `<slug>` = 简短动词 + 范围，kebab-case
+- 同日多份日志按写作顺序累积（不覆盖、不合并），文件名加序号后缀：`-1`、`-2`…
+
+### 5.3 日志内容模板
+```markdown
+# <一句话标题：完成了什么>
+
+- **日期**：YYYY-MM-DD
+- **关联**：路线图 M<N> / 子任务名 / 关联文档
+- **会话上下文**：（可选）本会话从哪开始接手的
+
+## 做了什么
+- bullet 1
+- bullet 2
+
+## 提交
+- `<short hash>` <commit subject>
+
+（若本段未提交：明确写"未提交，工作树状态：…"并说明原因）
+
+## 状态变更
+- 架构文档：是否动过？动了哪一节？
+- 需求/UI 文档：是否触发回归？
+- 测试：跑了什么，结果
+
+## 下一步
+- 接下来要做的第一件事（具体到任务名）
+- 已知阻塞 / 待澄清项
+```
+
+### 5.4 与提交的关系
+日志**不替代** commit message，commit message 仍按 `CONVENTIONS.md` 写；日志是提交的**索引与解释**。
+
+### 5.5 不写日志的情况
+- 还没完成一个"可独立验收"的部分 —— 不要"写日志凑数"
+- 纯文档调整 —— commit 自身已足够说明
+- 实验性探索（最终被回滚的内容）—— 用 commit message 记录即可
+
+---
+
+## 6. 出问题时的排查流程
+
+bug 来了不要直接钻进代码。按下列顺序：
+
+1. **复现并定位现象**：能在哪个入口 / 哪个调用稳定复现？
+2. **回到架构图**：这个现象涉及哪些模块？沿着依赖图圈出可能责任方。
+3. **审查接口契约**：跨模块调用是否符合 `ARCHITECTURE.md` 中声明的接口？输入输出是否符合契约？
+4. **缩小到单模块**：把嫌疑缩小到一个模块后，再读该模块代码。
+5. **修复并回写经验**：如果发现是架构层面的漏洞，修完代码后**必须更新 `ARCHITECTURE.md` 或 `CONVENTIONS.md`**。
+
+**反模式**：bug 一来就 grep 关键字、改一行试一下、再改一行试一下 —— 这是死亡螺旋，必须用流程压下去。
+
+---
+
+## 7. 反模式清单（"看到这些立刻警觉"）
+
+- 出现语义为空的模块名（`Manager` / `Helper` / `Util` / `Common` / `Misc` / `Tools`）且行数 > 100 行
+- 一个文件 import 超过 10 个本地模块
+- 改一个 UI 改动需要动 3 个以上其他模块
+- 同一份业务逻辑在两个地方各写了一遍
+- PR 描述写"顺便修了 X"
+- 新增功能时发现"无处归属"，于是塞进入口文件或主组件
+- 文档与代码不一致超过 24 小时
+- 出现没有在 `ARCHITECTURE.md` 中登记的新模块/新依赖方向
+
+任何一条出现，**先停下来回到本指南或架构文档，不要继续往前推**。
+
+---
+
+## 8. 本项目当前阶段
+
+> 本节随项目演进，不是规则的一部分。由 Agent 在每个 milestone 后更新。
+
+<!-- 由 /ads:init（2026-08-19，Retrofit）填入：本项目为后端微服务模板，治理已入位。 -->
+- 当前状态：后端模板（`abacus.springboot.example`）已完成治理落地（Retrofit），分层以示例模块实际结构为准（api/controller/dao/esb/pi/impl/repository/wsi/config/util/vo）；前后端共享约束单源化于工作区 `docs/`（`../../../docs/coding-standards.md`）。
+- 下一步合规动作：新业务模块按 `docs/coding-standards.md §5`（后端规范）与 §7（AI 生成工作流）开发；任何新增包、依赖方向或 SQL 变更先回写本仓库 `ARCHITECTURE.md` 与 `sql/` 约定，再写代码。

abacus.springboot.example/.project.agents/docs/context/ARCHITECTURE.md

@@ -0,0 +1,178 @@
+# abacus.springboot.example — 架构文档（ARCHITECTURE）
+
+> 模块、依赖、契约、目录布局的**唯一权威**（本仓库视角）。新增/重命名/移动模块或调整依赖方向，必须先改本文，再改代码（同一个 commit）。
+> 上游：`PRD.md`（行为）。前后端共享约束见工作区 `docs/`（`../../../../docs/coding-standards.md` §5 后端规范、§6 接口契约），本文不复制其正文。
+
+## 0. 阅读指引
+
+本文描述后端模板的模块划分与依赖方向；§2 模块清单与 §6 目录一一对应，§3.2 是跨模块接口契约。新会话先读 §2 + §6 定位任务归属，再动手。
+
+## 1. 领域模型（Domain Model）
+
+### 1.1 实体
+
+模板自带示例纵切面（稽查 JcBill），供复制改写：
+
+| 实体 | 字段 | 关系 | 持久化？ |
+|---|---|---|---|
+| jc_bill（稽查主单） | id(@Id)/version(@Version)/status/… | 1:N 明细 | 是 |
+| jc_bill_item / jc_bill_photo / jc_bill_hg / jc_bill_hg_pay / jc_source_item / jc_bill_in_item / jc_bill_source_item | id/主单关联字段 | N:1 主单 | 是 |
+
+字段细节见 `dao/*.java` 与 `sql/upgrade.xml`（建表 DDL）。
+
+### 1.2 派生概念（非持久化）
+
+- `api/view/*`：请求/响应 DTO（ApiReq*/ApiResp*），编排层与 Controller 之间传递。
+- `@Transient` 字段：实体上的非持久化附加信息（如 `recsource`）。
+
+### 1.3 不变量（任何模块都必须维护）
+
+- I1. 业务主键一律由 `DaoIdGenerator` 生成（prefix+yyyyMMdd+serialLength），禁止手拼/UUID。
+- I2. 原生 SQL 全量 `?` 参数化，禁止字符串拼接。
+- I3. 分层依赖单向：api/controller → esb/wsi → {pi/impl, repository} → dao；禁止反向依赖。
+- I4. Controller 直接 return 业务对象，禁止手拼统一响应体。
+
+## 2. 模块清单
+
+按依赖层级从低到高排列。
+
+### Layer 0 — dao（实体层）
+```
+## 模块名：dao
+- 职责：JPA 实体（表映射、状态常量、@Version 乐观锁）
+- 不负责：查询逻辑、业务规则
+- 输入：无（被 repository/impl 引用）
+- 输出：实体类型
+- 关键类型/接口：@Entity 类（如 JcBill）
+- 持有状态：无（纯数据）
+```
+
+### Layer 0 — config（基础设施配置）
+```
+## 模块名：config
+- 职责：@Configuration（DaoIdGenerator、AbacusConfigNote 默认值）+ 配置 key 常量
+- 不负责：业务规则
+- 输入：application.yml / Nacos 配置
+- 输出：基础设施 Bean
+- 持有状态：无
+```
+
+### Layer 1 — repository / pi+impl（数据访问）
+```
+## 模块名：repository（Spring Data JPA）
+- 职责：标准 CRUD 与派生查询（findByXxx）
+- 不负责：复杂查询（走 pi/impl）
+- 输出：实体查询结果
+
+## 模块名：pi + impl（原生 SQL 访问）
+- 职责：复杂查询/批量写（pi 定义接口，impl 实现，SQL 参数化）
+- 不负责：业务编排
+- 输出：DTO/实体结果
+```
+
+### Layer 2 — esb / wsi（服务编排与接口）
+```
+## 模块名：esb + wsi
+- 职责：业务用例编排（esb/*BizService，@Service）、对外服务接口（wsi/*ServiceIF）
+- 不负责：直接 SQL、Controller 层参数解析
+- 输入：Controller 传入的 DTO/参数
+- 输出：编排结果（DTO/实体）
+- 持有状态：事务边界（@Transactional 按需）
+```
+
+### Layer 3 — api / controller（接口层）
+```
+## 模块名：api + controller
+- 职责：对外接口（api/，springdoc 扫描）与前端/内部接口（controller/，abacus.controllerPackages 扫描）
+- 不负责：业务编排与 SQL
+- 输入：HTTP 请求（@RequestParam/@RequestBody）
+- 输出：业务对象（由 ResultResponseBodyWrapper 包装）
+- 持有状态：无
+```
+
+## 3. 依赖图（DAG）
+
+```mermaid
+graph TD
+    api_controller[api / controller] --> esb_wsi[esb / wsi]
+    esb_wsi --> pi_impl[pi / impl]
+    esb_wsi --> repository[repository]
+    pi_impl --> dao[dao]
+    repository --> dao
+    esb_wsi --> dao
+    config -.注入.-> esb_wsi
+    config -.注入.-> pi_impl
+```
+
+### 3.1 依赖方向规则
+
+- 高层依赖低层，单向；**禁止** dao 依赖 repository、esb 依赖 controller 等反向依赖。
+- 跨层调用走接口（wsi ServiceIF / pi AccessIF），不 reach into 实现。
+
+### 3.2 跨模块接口契约（写代码时必须遵守的签名）
+
+```
+// module: controller
+//   @RequestMapping(value, method) -> 业务对象（throws Exception）   // 直接 return，I4
+
+// module: esb/wsi
+//   XxxServiceIF.method(dto...) throws Exception                   // 编排用例，事务边界
+
+// module: pi/impl
+//   XxxAccessIF.method(params...) -> List<DTO>                     // 原生 SQL，I2 参数化
+
+// module: repository
+//   XxxRepository extends JpaRepository<Entity, String>, JpaSpecificationExecutor<Entity>
+
+// module: config
+//   @Bean DaoIdGenerator（prefix/useDateFormat/yyyyMMdd/serialLength）  // I1
+```
+
+## 4. 持久化与边界
+
+- 数据源：Druid 连接池 + JPA；多数据源由 Nacos `abacus-database.yml` 提供（enableMultiSource / multidb0~9 / defaultDB / readDB / dynamicRelation）。
+- 外部边界：Nacos（注册+配置）、Kafka（消息）、XXL-JOB（调度）、Feign（服务间调用）、springdoc（接口文档）、Actuator（监控）。
+
+## 5. 测试边界
+
+- 无自动化单测（PRD 决策）；接口人工冒烟。
+- **必须真机验证**：多数据源路由、Kafka 消费、XXL-JOB 调度、Nacos 配置拉取、真实数据库迁移——mock/模拟器不算数。
+
+## 6. 目录结构（与 §2 模块清单一一对应）
+
+```
+src/main/java/abacus/springboot/<应用名>/
+├── Application.java                     # 入口（注册 ResultResponseBodyWrapper）
+├── api/                                 # 对外 Controller（springdoc 扫描）；api/view/ 放 DTO
+├── controller/                          # 前端/内部 Controller（abacus.controllerPackages 扫描）
+├── dao/                                 # JPA 实体（abacus.entitypackages 扫描）
+├── esb/                                 # Service 编排层（@Service）
+├── wsi/                                 # 服务接口 *ServiceIF
+├── pi/                                  # 数据访问接口 *AccessIF
+├── impl/                                # 数据访问实现（原生 SQL）
+├── repository/                          # Spring Data JPA Repository
+├── config/                              # @Configuration + 配置常量
+├── util/ vo/                            # 既有兼容（可引不可增）
+src/main/resources/
+├── config/{dev,test,prod}/              # 三套同构配置
+├── sql/{table,data}/ + upgrade.xml      # 建表双份/初始化/版本化升级
+├── html/vue/<应用名>/                   # 前端构建产物（打包入 *-bin.zip）
+└── doc/升级日志.md                       # 功能更新记录
+```
+
+## 7. 自检（架构健康度三问）
+
+1. 出 bug 了，能否 30 秒内指出是哪个包（controller/esb/impl/repository）的责任？
+2. 换数据库/换 JPA 实现，改动能否控制在 impl/repository + 配置内？
+3. 加新业务接口，能否立刻说出它落在 api 还是 controller、esb 是否要新增 BizService？
+
+## 8. 待办与已知技术负债
+
+- `springdoc-openapi-maven-plugin` 的 `apiDocsUrl` 硬编码 `http://localhost:8080/v3/api-docs`，与应用实际端口（9060）不一致，生成 openapi.json 时需手工修正。
+- `prod/application.yml` 引用 `abacus.springboot.example.springdoc` 扫描路径但该包不存在（模板未创建 springdoc 包）——新系统以实际包为准。
+
+## 9. 文档变更协议
+
+- 加/删模块或改依赖方向 → 改本文 §2 + §3，同一 commit。
+- 改对外签名 → 先改 §3.2，再改代码。
+- 与 `PRD.md` 冲突 → 以 `PRD.md` 为准，回改本文；与共享 `docs/coding-standards.md` 冲突 → 以 docs/ 为准并回改本文。

abacus.springboot.example/.project.agents/docs/context/CONVENTIONS.md

@@ -0,0 +1,94 @@
+# abacus.springboot.example — 开发规范（CONVENTIONS）
+
+> 命名、目录、提交、风格、测试的权威（本仓库视角）。前后端共享约束见工作区 `docs/coding-standards.md`（`../../../../docs/coding-standards.md`），本文只写后端特有内容 + 指针，**禁止复制 docs/ 正文**。
+
+## 0. 阅读指引
+
+- 适用范围：`src/main/java/abacus/springboot.<应用名>/**` 业务开发（模板基础结构 pom/assembly/config 原则上不动）。
+- 分工：ARCHITECTURE 管"拆成什么模块"；本文管"怎么命名/写"；共享编码规范、接口契约、SQL 约定、AI 生成工作流在 `docs/coding-standards.md` §5~§7。
+
+## 1. 命名
+
+### 1.1 标识符
+
+- 类：PascalCase；接口带后缀 `IF`（pi 层 `XxxAccessIF`、wsi 层 `XxxServiceIF`）；编排服务 `XxxBizService`；实现 `XxxAccess`。
+- Controller：`XxxController`（api 对外 / controller 内部）；基类 `BaseServlet`。
+- 实体：表名小写下划线（`jc_bill`），类名驼峰（`JcBill`）；DTO：请求 `ApiReqXxx`、响应 `ApiRespXxx` 或 `ApiXxx`（api/view）。
+- 配置：`XxxConfiguration`、`XxxConfigKey`（常量类）。
+
+### 1.2 模块命名（语义禁区）
+
+- 禁止 `Manager` / `Helper` / `Util` / `Common` / `Misc` / `Tools` 这类语义为空的名字；用"动词+名词"。
+- **util/ vo/ 兼容**：既有 `util/DateUtil`、`vo/BaiduToken` 等**可引不可增**——新代码禁止在 `util/`、`vo/` 包新增文件（共享规范 §8.4）。
+
+### 1.3 文件 / 1.4 目录 / 1.5 资产命名
+
+- 文件按类名命名（一文件一公共类）；目录即包名（分层见 ARCHITECTURE §6）。
+- SQL：`sql/table/{mysql,sqlserver}.sql`、`sql/upgrade.xml`、`sql/data/`；版本号 `yyyy-MM-dd[.count]`。
+
+### 1.6 字符串与本地化
+
+- 异常消息中文、可行动（"参数[x]为空！"）；不硬编码无意义字符串；状态常量用 `public final static int STATUS_*`。
+
+## 2. 代码风格
+
+### 2.1 排版
+
+- Java 4 空格缩进、行宽 ≤ 120；分号/括号按 Java 惯例。
+- 不使用 Lombok（手写 getter/setter，与示例一致）。
+
+### 2.2 分层纪律
+
+- Controller 只做参数校验 + 调编排，不写 SQL、不碰 Repository；esb 只编排不做 SQL。
+- 原生 SQL 在 `impl/`，**全量 `?` 参数化**；标准 CRUD/派生查询用 `repository`。
+- 业务主键一律 `DaoIdGenerator`，禁止手拼。
+
+### 2.3 并发 / 2.4 错误处理
+
+- 事务边界在 esb 编排方法（按需 `@Transactional`）；JPA 乐观锁用 `@Version`。
+- 业务错误抛 `BusinessException`（中文消息）；Controller 方法级 try/catch(Throwable) 记日志后 rethrow；**禁止吞异常**。
+
+### 2.5 注释
+
+- 默认不写注释；只在 WHY 不明显时写一行；不写解释 WHAT 的注释（命名应自解释）。
+
+## 3. 提交规范
+
+### 3.1 Commit message 风格
+
+Conventional Commits：`type(scope): subject`。允许 type：`feat` / `fix` / `docs` / `refactor` / `test` / `chore`。例：`feat(jcbill): 新增稽查收货保存接口`。
+
+### 3.2 提交粒度 / 3.3 工作区纪律 / 3.4 分支模型
+
+- 一次提交一个目的；不在脏工作区叠加不相关改动。
+- 分支模型：主干 + 短命功能分支（按需，单人开发可直推主干）。
+- 本仓库属于工作区单一 git 仓库（`D:\workBuddySpace\member`）；纯后端改动 commit 限定本目录，跨项目改动（docs/）单独 commit。
+
+### 3.5 实施日志
+
+- 规则见 `VIBECODING_GUIDE §5`：每个可独立验收的部分写 `.project.agents/log/YYYY-MM-DD-<slug>.md`。
+- 功能更新同步追加 `src/main/resources/doc/升级日志.md`（共享规范 §5.11 格式）。
+
+## 4. 测试策略
+
+### 4.1 框架 / 4.2 必须有测试的模块
+
+- 无自动化测试框架（PRD 决策）；接口人工冒烟。
+
+### 4.3 必须真机/真环境验证
+
+- **必须真机验证**（mock/模拟器不算数）：多数据源路由、Kafka 消费、XXL-JOB 调度、Nacos 配置拉取、真实数据库迁移。
+
+## 5. 与上游文档的同步矩阵
+
+| 变更点 | 必须同步更新 |
+|---|---|
+| 新增/改动业务功能 | `PRD.md`（功能定义）；共享规范如有涉及先改 `docs/coding-standards.md` |
+| 新增包/模块/依赖方向 | 本仓库 `ARCHITECTURE.md` §2+§3 |
+| 新增 SQL/表结构 | `sql/table/` 双份 + `sql/upgrade.xml`；`ARCHITECTURE.md §1` 实体清单 |
+| 配置项变更 | `config/{dev,test,prod}/` 三套同步 |
+| 依赖版本变更 | `pom.xml` + `doc/升级日志.md` |
+
+## 6. 不在本文范围（明确划清）
+
+- 模块拆分归 `ARCHITECTURE.md`；行为/范围归 `PRD.md`；前后端共享约束（响应体/异常码/分页/APP_NAME/打包）归 `docs/coding-standards.md`。

abacus.springboot.example/.project.agents/docs/context/PRD.md

@@ -0,0 +1,91 @@
+# abacus.springboot.example — 产品需求文档（PRD）
+
+> 行为与范围的**唯一权威**。功能的加/删/改必须先改本文，再动代码与下游文档。
+> 本文回答"做什么 / 给谁 / 为什么"，不回答"怎么实现"（那是 `ARCHITECTURE.md`）。
+
+## 1. 产品愿景
+
+为 abacus 微服务体系提供**可复用的 Spring Boot 微服务模板**：业务团队（人 + AI）在本模板上按分层规范添加业务模块（Controller / Service / 数据访问 / Entity / SQL / 配置），即可获得统一响应体、异常体系、多数据库支持、Nacos 注册配置、定时任务与动静分离打包能力，实现跨系统一致的后端工程结构与低成本复制开发。
+
+## 2. 目标用户与典型场景
+
+- 用户画像：公司内部业务系统后端开发团队（后端开发、全栈、AI 辅助开发人员）。
+- 场景 1：作为业务开发，我想复制本模板新建一个微服务，以便快速获得 Nacos / 多库 / 打包 / 日志等基础设施。
+- 场景 2：作为 AI 助手，我想依据 `docs/coding-standards.md §5/§7` 把界面需求直接生成 Controller→Service→数据访问→SQL 全链路代码。
+- 场景 3：作为发布负责人，我想让所有服务打出结构一致的 `*-bin.zip`（jar+doc+sql+html），以便统一发布流程。
+
+## 3. 范围（Scope）
+
+### 3.1 MVP 必含（In Scope）
+- 分层骨架（api/controller/dao/esb/pi/impl/repository/wsi/config）与扫描配置（springdoc/entitypackages/controllerPackages）。
+- 统一响应体包装（`ResultResponseBodyWrapper`）与业务异常（`BusinessException`）。
+- 多数据库（MySQL / SQL Server / Oracle / 达梦）+ Druid + JPA；Nacos 注册/配置中心。
+- SQL 三件套（table 双份 / upgrade.xml 版本化 / data 初始化）与动静分离打包（assembly.xml → *-bin.zip）。
+- 示例业务纵切面（JcBill 稽查示例：Controller + BizService + Access + Repository + Entity + 升级 SQL）。
+
+### 3.2 明确不做（Out of Scope）
+- 不包含具体生产业务（业务模块由团队基于模板复制开发）。
+- 不提供自动化测试框架与 CI（人工冒烟验证）。
+- 不维护前端页面（前端属 `abacus-static-framework` 仓库）。
+
+## 4. 核心功能定义
+
+### 4.1 统一响应体与异常（【核心】）
+- **用户故事**：作为前端/调用方，我想所有接口返回一致的 `{status, message, data, errorCode}`，以便统一处理。
+- **行为**：`Application.java` 注册 `ResultResponseBodyWrapper`；Controller 直接 return 业务对象；参数空校验抛 `BusinessException("参数[x]为空！")`。
+- **边界 / 异常**：`abacus.responseExcludePath` 配置的 URI 不被包装；业务异常码首位 9、系统异常码首位 5（共享规范 §6.2）。
+
+### 4.2 分层开发模型（【核心】）
+- **用户故事**：作为团队开发，我想按固定分层写代码，以便职责清晰、可评审、可复制。
+- **行为**：Controller（api/controller）→ esb 编排 → wsi/pi/repository 数据访问 → dao 实体；依赖单向。
+- **边界 / 异常**：Controller 不写 SQL、不碰 Repository；esb 只编排不做 SQL；原生 SQL 全量参数化。
+
+### 4.3 数据库多库支持（【核心】）
+- **用户故事**：作为实施，我想同一套代码跑 MySQL 与 SQL Server，以便一套系统多客户部署。
+- **行为**：建表脚本 `sql/table/{mysql,sqlserver}.sql` 双份同步；历史变更 `sql/upgrade.xml`（`translator="true"` 以 SQL Server 语法书写由框架翻译）。
+- **边界 / 异常**：多数据源路由、真实迁移必须真机验证。
+
+### 4.4 动静分离打包（【核心】）
+- **用户故事**：作为发布，我想一个发布包包含前后端全部产物，以便统一发版。
+- **行为**：前端产物输出到 `resources/html/vue/<应用名>/`，`mvn package` 经 `assembly.xml` 打出 `*-bin.zip`（jar+doc+sql+html）。
+- **边界 / 异常**：jar 内不含 html；`pom.xml` artifactId 建议 `abacus.springboot.<应用名>`。
+
+## 5. 信息架构与导航
+
+微服务间通过 Nacos 注册发现 + Feign 调用；接口文档由 springdoc 提供（扫描 `api` 包）；监控经 Actuator（base-path `/services/actuator`）暴露 Prometheus 指标；定时任务由 XXL-JOB（`application-xxljob.yml`）承载。
+
+## 6. 数据模型（概念级）
+
+业务数据实体集中在 `dao/` 包（JPA 映射）；概念级实体清单由各业务模块在 `ARCHITECTURE.md §1` 维护。模板自带示例实体：`jc_bill`（稽查主单）及其明细/关联表（见 `sql/upgrade.xml`）。
+
+## 7. 非功能性需求
+
+- 多环境配置 `config/{dev,test,prod}/` 三套同构；dev 端口 9060 / test、prod 9000（以实际为准）。
+- 上传限制 50MB；Druid 连接池（初始 10 / 最大 60）；Feign 超时 10s 连接 / 30s 读取。
+- JPA 与 Bean 延迟启动（`lazy-initialization`）以加速启动。
+
+## 8. 国际化与文案语气
+
+异常消息使用中文，直接面向用户可理解（如"参数[x]为空！"）；接口文档（@Operation summary）用中文。
+
+## 9. 隐私与合规
+
+- 数据库连接与 Nacos 凭据放在 `config/<env>/` 配置文件（git 跟踪按团队约定）；**不得**新增明文密钥到非约定位置。
+- 审计信息（菜单/模块/业务域）由前端 commonParam 提供，见共享规范 §6.7。
+
+## 10. 风险与缓解
+
+- **APP_NAME 四处漏配静默失败**：按共享规范 §3 四联检（bootstrap.yml / 扫描包 / URL 首段 / outDir）。
+- **多库语法差异**：新 SQL 以 SQL Server 语法编写并加 `translator="true"`，建表双份同步。
+- **框架 jar 版本升级**：`pom.xml` 依赖版本变更需在升级日志记录并回归验证。
+
+## 11. 发布里程碑（建议，待路线图细化）
+
+- M0：治理与规范落地（本次已完成）。
+- M1+：按 `ROADMAP.md` 以新业务模块验证模板可复制性（界面→代码全链路）。
+
+## 12. 假设与待澄清项（复核时请逐条回应）
+
+- Q1. 新业务是否一律采用 `abacus.springboot.<应用名>.<层>` 包前缀？（默认：是）
+- Q2. 是否引入后端单元测试（如 JUnit/Testcontainers）？（默认：否，人工冒烟 + 真机验证）
+- Q3. `util/`、`vo/` 包是否冻结不再新增？（默认：是，既有兼容、新增禁止）

abacus.springboot.example/.project.agents/docs/context/ROADMAP.md

@@ -0,0 +1,55 @@
+# abacus.springboot.example — 实施路线图（ROADMAP）
+
+> 由 `PRD.md` + `ARCHITECTURE.md` 推导。按依赖图拓扑顺序排开发节奏。每完成一个复选框，在**同一个 commit**里打勾；每完成一个 milestone，按 `.project.agents/log/` 模板写日志。
+
+## 0. 排序原则
+
+- 先基础设施（config/dao/repository 等底层）后接口（esb/api）。
+- 本仓库为**后端模板**：里程碑以"验证模板可复制性 + 治理可持续性"为主线，而非业务功能交付。
+
+## 1. 里程碑总览
+
+| Milestone | 目标 | 验收（能演示什么） |
+|---|---|---|
+| M0 | 治理落地（本次）：git 单一仓库、docs/ 文档中心、.project.agents 全套、共享规范 | 克隆仓库 → `mvn package -Pdev -DskipTests` 可出包；治理文档无残留 token |
+| M1 | 模板可复制性验证：按 `docs/coding-standards.md §7` 用第一个业务模块（界面→代码）跑通全链路 | 新业务接口可调用（springdoc 可见）、SQL 可在 MySQL/SQL Server 执行 |
+| M2 | 沉淀与回写：业务中发现的共性需求回写模板/规范 | 模板与规范有增量，升级日志有记录 |
+
+## 2. 里程碑详细
+
+### M0 — 治理与规范落地（已完成）
+- [x] 版本控制 + ignore + 骨架提交（工作区单一仓库 `D:\workBuddySpace\member`）
+- [x] docs/ 文档中心（README / architecture / coding-standards / agent-guide）
+- [x] 本仓库 .project.agents 治理文件（CLAUDE / AGENTS / SELF_CONSTRAINTS / VIBECODING_GUIDE / settings / context 四文档）
+- [x] 完成门禁（治理文档无残留模板 token / FILL 标记）
+- **验收**：克隆仓库 → `mvn package -Pdev -DskipTests` 可出包；治理文档无残留 token。
+
+### M1 — 模板可复制性验证（首个业务模块）
+- **依赖**：M0
+- [ ] 按 `docs/coding-standards.md §7` 从界面需求生成：Controller（api 或 controller）→ esb/wsi → pi/impl 或 repository → dao/DTO → SQL（table 双份 + upgrade.xml）
+- [ ] 扫描配置核对（`springdoc.packages-to-scan` / `abacus.entitypackages` / `abacus.controllerPackages` 覆盖新包）
+- [ ] APP_NAME 四联检 + 前后端 URL 逐字对齐
+- [ ] 多库验证：DDL 在 MySQL 与 SQL Server 均可执行；接口冒烟通
+- **验收**：新业务接口 springdoc 可见、可调用，SQL 双库可执行。
+
+### M2 — 沉淀与回写
+- **依赖**：M1
+- [ ] 收集业务开发中的共性需求（分层盲点/框架 jar 能力/规范补缺）
+- [ ] 规范盲点回写 `docs/coding-standards.md`（先改 docs/ 再同步各仓库指针）
+- [ ] `doc/升级日志.md` 记录模板演进
+- **验收**：模板与规范有可见增量，新业务直接复用。
+
+## 3. 并行轨道（与代码 milestone 解耦）
+
+- 无（CI 等暂不纳入；如团队需要可补充构建门禁脚本到 `.project.agents/scripts/`）。
+
+## 4. 完成定义（DoD）
+
+- 构建通过（`mvn package -Pdev -DskipTests` 无错）；涉及多库场景需真机验证。
+- 触及的架构变更已回写 `ARCHITECTURE.md`；共享约束变更先改 `docs/coding-standards.md`。
+- 已写执行日志（`.project.agents/log/YYYY-MM-DD-<slug>.md`）并追加 `doc/升级日志.md`。
+
+## 5. 跨 milestone 不变量
+
+- I1~I4（ARCHITECTURE §1.3）：主键走 DaoIdGenerator、SQL 参数化、依赖单向、Controller 不拼响应体。
+- 任何新增包/依赖方向先登记 `ARCHITECTURE.md` 再写代码。

abacus.springboot.example/.project.agents/log/2026-08-19-ads-governance.md

@@ -0,0 +1,30 @@
+# 治理体系落地（ADS Retrofit）
+
+- **日期**：2026-08-19
+- **关联**：ROADMAP M0
+- **会话上下文**：工作区两个参考模板（后端 abacus.springboot.example、前端 abacus-static-framework）此前无 git、无 docs/ 文档中心、无 .project.agents 治理。
+
+## 做了什么
+
+- 工作区根 `D:\workBuddySpace\member` 建单一 git 仓库 + `.gitignore`。
+- 创建 `docs/` 文档中心（单源化）：`README.md`、`architecture.md`、`coding-standards.md`（★前后端开发约束规范）、`agent-guide.md`。
+- 本仓库落地 `.project.agents/`：CLAUDE.md / AGENTS.md / SELF_CONSTRAINTS.md / VIBECODING_GUIDE.md / settings.json / log/README.md + `docs/context/{PRD,ARCHITECTURE,ROADMAP,CONVENTIONS}.md`（无 UIUX，include_uiux=false），全部填充无残留 token。
+- 分层以示例模块实际结构为准（api/controller/dao/esb/pi/impl/repository/wsi/config/util/vo）；`util`、`vo` 冻结（可引不可增）。
+- 共享内容以指针引用 `../../../../docs/`，未复制正文；`doc/升级日志.md` 追加 1.0.2(2026-08-19) 治理记录。
+- 分析过程使用 CodeGraph MCP 索引本仓库（82 文件）；符号级上下文工具受限，降级为关键文件定向读取。
+
+## 提交
+
+- 见工作区根 git 提交（docs/ 文档中心、前端治理、后端治理三个原子提交）。
+
+## 状态变更
+
+- ARCHITECTURE：本仓库 ARCHITECTURE.md 已按实际分层编写；不变量 I1~I4（主键 DaoIdGenerator / SQL 参数化 / 依赖单向 / Controller 不拼响应体）。
+- PRD：已填充（统一响应体/分层模型/多库/动静分离四核心）。
+- 测试：无代码改动，未触发。
+
+## 下一步
+
+- 按 ROADMAP M1 用第一个业务模块（界面→代码）验证模板可复制性。
+- 待澄清项见 PRD §12（包前缀 / 是否引入后端单测 / util、vo 冻结）。
+- 已知负债：`springdoc-openapi-maven-plugin` apiDocsUrl 硬编码 8080（ARCHITECTURE §8）。

abacus.springboot.example/.project.agents/log/README.md

@@ -0,0 +1,54 @@
+# 实施日志（execution log）
+
+本目录沉淀"做了什么 + 哪些提交 + 下一步"，供下一个会话接手用。
+规则与时机见 `../VIBECODING_GUIDE.md §5`；硬约束见 `../SELF_CONSTRAINTS.md §B6`。
+
+---
+
+## 文件命名
+
+`YYYY-MM-DD-<slug>.md`
+
+- `<slug>` = 简短动词 + 范围，kebab-case
+- 同日多份按写作顺序加 `-1`、`-2` 后缀
+
+## 模板
+
+```markdown
+# <一句话标题：完成了什么>
+
+- **日期**：YYYY-MM-DD
+- **关联**：ROADMAP M<N> / 子任务名 / 关联文档
+- **会话上下文**：（可选）本会话从哪开始接手的
+
+## 做了什么
+- bullet 1
+- bullet 2
+
+## 提交
+- `<short hash>` <commit subject>
+
+（若本段未提交：明确写"未提交，工作树状态：…"并说明原因）
+
+## 状态变更
+- ARCHITECTURE：是否动过？动了哪一节？
+- PRD：是否触发回归？
+- 测试：跑了什么，结果
+
+## 下一步
+- 接下来要做的第一件事（具体到任务名）
+- 已知阻塞 / 待澄清项
+```
+
+## 何时写
+
+- 完成一个 ROADMAP milestone
+- 完成一个独立可验收的子任务
+- 完成非平凡的重构 / bug 修复
+- 会话即将结束（兜底）
+
+## 何时不写
+
+- 还没完成一个"可独立验收"的部分（别凑数）
+- 纯文档微调（commit 自身已够说明）
+- 实验性探索且最终 revert（commit 即可）

abacus.springboot.example/.project.agents/settings.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [],
+    "deny": []
+  },
+  "hooks": {}
+}