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

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` 再写代码。