# E10 / e-code 二次开发规则

本工具包提供 E10/e-code 本地二次开发流程与离线知识。以下内容由源规则完整生成；不得手工删减规则语义。所有路径已转换为本工具包的 `AGENTS.md + skills/` 结构。

## 路径与模块解析

- `ecode-development` 指 `skills/ecode-development/SKILL.md`。
- 原规则中的其他 Skill 名称均为逻辑模块名；先使用 `skills/e10-local-knowledge/scripts/route.mjs` 或开发总入口确定归属，再读取对应 `modules/<名称>/MODULE.md`。
- 原 `SKILL.md` 专题说明在运行包中统一改名为 `MODULE.md`；不得调用不存在的旧顶层 Skill。
- E10 基线从当前工程配置、构建文件或用户输入获取；无法确认时可分析，但选择平台 API 或生成业务代码前必须确认。

## 任务规格

拆解任务时必须明确：目标、业务对象、角色、E10 模块、技术域、子任务及依赖、约束、外部配置、验收标准、风险等级、风险原因、是否需要确认。

## 实现确认包

中高风险实现前必须给出：任务规格、证据及版本兼容性、实现方式、影响文件、验证计划、风险、回滚方式和确认状态。低风险明确小改可自动放行。

## 原规则：00-route-ecode-development.md

- 说明：E10/e-code 二次开发核心路由与交付门禁
- 加载：始终适用

除非用户明确要求其他语言，否则使用中文回复。

### 交付原则

实现请求默认直接交付可编译、配置后可运行的代码。除非用户明确要求只分析或只给方案，必须：

1. 读取 `当前项目配置与基线信息`，检查当前工程与已有同类实现。
2. 判定 `frontend`、`backend`、`fullstack` 或 `unknown` 技术域。
3. 通过对应工程门禁，完成最小必要的本地知识检索。
4. 创建或修改代码，执行相关测试、编译或构建。
5. 汇报修改文件、实际命令、验证结论、待配置项和剩余风险。

解释请求只回答原理；方案请求允许只输出方案；用户明确采用方案后，禁止重新探索替代方案，只允许一次缺口核验。

### 状态机与风险

`DISCOVER → DECOMPOSE → EVIDENCE → PROPOSE → CONFIRM? → IMPLEMENT ↔ VERIFY → ACCEPT → DONE`

- `DISCOVER`：定位工程、技术域和代码落点。
- `DECOMPOSE`：按 `本文件“任务规格”章节` 整理目标、约束、验收标准和风险。
- `EVIDENCE`：只补齐实现必需的 API、组件、表字段或平台约束。
- `PROPOSE`：按 `本文件“实现确认包”章节` 形成方案、影响文件和验证计划。
- `CONFIRM?`：中高风险编码前一次确认；低风险自动放行。
- `IMPLEMENT`：必须产生实际文件修改。
- `VERIFY`：失败时返回实现修复，最多三轮。
- `ACCEPT`：逐项映射验收标准；无法自动判断的业务正确性标为人工验收。

风险：已有文件局部修复为低；新增功能、接口、模块或外部契约为中；数据库写入、删除、权限、认证、事务、敏感数据、部署或不可逆行为为高。范围、证据或风险实质变化时返回方案阶段重新确认。

### 工程路由

先读取 `skills/ecode-development/SKILL.md`，再按技术域加载：

- 前端：`e10-frontend-local-tooling` 检查/初始化工程，再进入 `frontend-development`。
- 后端：`backend-project-init` 检查/初始化工程，再进入 `backend-development`。
- 全栈：分别执行前后端门禁；二者不互相替代。

纯前端不得触发 Gradle、Java 单测或 jar；后端依赖任务不得触发前端初始化。前端新需求或工程不完整时，必须用 `e10-frontend-local-tooling init` 创建完整前端项目工程；禁止只创建单个业务文件。业务源码只允许 `.js`；禁止创建或输出 `.jsx`、`.ts`、`.tsx`；`resources/` 只存静态资源。

### 本地知识路由

所有产品知识、案例、API 与数据字典检索均遵守 本文件“E10 本地知识证据门禁”章节：

1. 平台业务场景先用 `ecode-case-catalog` 本地 `search-case`，命中后按需 `search-code`。
2. 标准 API 先进入业务 Skill，用其 `scripts/search-api.mjs` 检索并加载单条结构化契约；需要原始上下文时再用 `scripts/search.mjs`。
3. 版本过滤使用 `当前项目配置与基线信息` 的 `e10Baseline`；基线为空时可分析，但选择平台 API 和生成业务代码前必须确认版本。
4. 每个实现单元最多加载 3 个 Skill、执行 3 次检索、加载 3 篇目标文档；只有具体标识仍缺失时允许第 4 个知识 Skill。
5. 连续两次检索没有新增 API、组件、文件位置或约束时立即进入实现。
6. 最多加载 1 个主要案例、1 个备选案例，每案例最多 2 个代码片段。
7. 单次工具输出最多 12288 bytes；超限时缩小到章节、符号或示例。

换言之，每个实现单元最多执行 3 次知识检索、最多加载 3 篇目标文档、最多更换 1 次关键词。工程检查、源码搜索、代码定位、测试和构建不计入知识检索预算。连续两次知识检索没有新增证据时立即结束检索。

禁止批量读取 `references/`、API 全集、组件全集、案例 ZIP、完整 `ecode.json` 或完整源码目录；禁止从用户目录或根目录开始无界搜索。

### 数据库硬门禁

涉及 SQL、表、字段、DAO、Repository、Mapper、JDBC、MyBatis、分页或数据写入时，进入实现前必须调用 `e10-data-dictionary`：先 `search`，再对目标表 `load --section columns`。

用户提供、历史代码存在的标识也必须验证。未命中目标表、缺少字段或存在未裁决冲突时，禁止生成或修改 SQL、映射和实体字段；输出缺少的表名、数据库、字段与来源，不得猜测。

### 证据不足

不得虚构平台 API、URL、类名、Hook、参数、表字段或返回值。资料未命中时依次：

1. 检查当前工程已有实现。
2. 复用已验证的同类代码模式。
3. 将未知平台标识设计为外部配置。
4. 实现不依赖未知信息的主体代码。

未知配置外置后，只能声明“可编译、配置后可运行”。鉴权、事务、删除、权限等关键逻辑不得用 TODO 代替。缺失信息影响安全、阻止运行或可能产生破坏性结果时，停止并列出唯一阻塞项。

## 原规则：05-route-local-knowledge.md

- 说明：E10 本地知识检索证据门禁与 fail-closed 规则
- 加载：按任务与文件条件适用

### E10 本地知识证据门禁

适用于 E10/e-code 产品知识、标准 API、SDK、页面地址、表名、字段名、类名、Hook、参数、返回值、枚举和调用链。

#### 总原则

1. 具体平台标识必须有证据。证据只接受本地 `skills/*/modules/*/references` 原文、本地 Skill 的 `load` 输出，或当前项目代码的实际命中。
2. `search` 结果只是候选。必须继续读取命中文档详情、原文章节或项目代码。
3. 先按业务对象路由到唯一主 Skill，再执行该 Skill 的本地检索脚本；不得跨 Skill 混排不可比较的分数。
4. 先按 `当前项目配置与基线信息` 的 E10 基线过滤，再按证据完整性和代码可运行性判断可采纳性。
5. 本地知识和项目代码均无可采纳证据时 fail closed：只能说明“当前本地知识未检索到可核验证据，不能确认该标识存在”。
6. 模块功能、配置可行性和低代码搭建评估先使用 `e10-module-knowledge`；其结论必须加载正文证据，且不得替代 API、案例、数据字典核验。

#### 检索顺序

1. 检查当前项目已有实现。
2. 读取目标业务模块的 `MODULE.md`。
3. API 契约用该 Skill 的 `scripts/search-api.mjs` 先 `search` 再 `load`。
4. 原始文档或案例用该 Skill 的 `scripts/search.mjs` 先 `search` 再 `load`。
5. 数据库表和字段必须用 `e10-data-dictionary` 的 `search` 与 `load --section columns` 核验。
6. 模块评估先用 `e10-module-knowledge` 的 `search` 与 `load`；业务模块优先，低代码需求再限定 `低代码平台e-builder`。

#### 禁止行为

- 禁止根据历史经验、命名习惯、相似系统、E9 记忆或旧 JSP 路径补写 E10 标识。
- 禁止把目录未命中升级为“接口不存在”；只能说当前本地知识未检索到完整匹配。
- 禁止混合不同来源拼接不存在的路径、类名、字段名或调用链。
- 禁止批量读取整个 `references/`、案例 ZIP、完整案例源码或全部 API 记录。

#### 输出要求

回答 E10 技术事实时，必须列出“证据来源：本地 Skill 原文 / 项目代码命中”，并说明命中文档、章节、表或文件；无可核验证据时明确声明，且不输出具体未证实标识。

涉及数据库、SQL、Mapper、DAO、Repository、JDBC、MyBatis、分页或数据写入时，必须验证目标表与字段；未验证时不得生成相关代码。

## 原规则：10-sync-api-documentation.md

- 说明：生成或修改接口实现后必须同步更新接口文档
- 加载：按任务与文件条件适用
- 文件条件：`**/controller/**/*.java`、`**/service/**/*.java`、`**/action/**/*.java`、`e10-tables/data/**/*`

当生成或修改 HTTP/Dubbo 接口代码时，必须同步生成或更新接口文档。

文档要求：
1. 文档路径：优先放在对应子模块 `docs/api/` 目录。
2. 至少包含：接口路径或服务名、请求方式、参数说明、返回示例、调用示例。
3. 接口前缀遵循平台规范：`/api/secondev/*`、`/sapi/secondev/*`，禁止 `/papi`。
4. 若本次变更未涉及接口，不强制生成接口文档。

数据字典更新：

5. 本运行包不携带数据字典生成器。运行时只执行
   `node skills/e10-local-knowledge/modules/e10-data-dictionary/scripts/search.mjs` 验证已发布索引。源 HTML 发生变化时，
   必须在数据字典源仓库运行其生成脚本，完成冲突审计后再发布新的 `references/`。

## 原规则：20-maintain-unit-tests.md

- 说明：业务代码变更后必须生成或更新单元测试
- 加载：按任务与文件条件适用
- 文件条件：`**/src/main/java/**/*.java`

当新增或修改 Java 业务代码时，必须同步生成或更新对应单元测试。

适用范围：
1. Controller、Service、Action、工具类、业务实体转换逻辑。
2. 涉及参数校验、异常处理、内部 API/SDK 调用、返回体封装的代码。
3. 修复缺陷时，必须补充能复现缺陷的回归用例。

生成要求：
1. 单元测试放在对应模块 `src/test/java` 下，包路径与被测类保持一致。
2. 测试类命名使用 `{被测类名}Test`。
3. 测试点必须覆盖：正常路径、参数为空/非法、平台 API 返回失败、异常分支、`WeaResult` 成功/失败结构。
4. 标准平台 API、Dubbo、数据库、缓存、HTTP 调用不得直接依赖真实环境；应通过 mock、接口封装或轻量替身隔离。
5. Controller 测试只做轻量参数与返回结构验证；复杂业务逻辑应下沉到 Service 并优先测试 Service。
6. 测试代码必须遵循 `skills/ecode-development/modules/backend-development/references/test-spec-full.md`。

允许不生成测试的情况：
1. 仅修改文档、提示词、规则、纯配置。
2. 仅新增无逻辑常量或无分支 DTO。
3. 当前工程缺少测试依赖且本次任务未允许初始化依赖。

若不生成测试，输出中必须说明“不适用原因”或“阻塞原因”，不得省略。

## 原规则：21-run-and-verify-tests.md

- 说明：实现后必须执行相关测试并验证结果
- 加载：按任务与文件条件适用
- 文件条件：`**/src/main/java/**/*.java`、`**/src/test/java/**/*.java`

当本次任务包含代码实现或测试变更时，必须执行相关测试或给出明确阻塞原因。

执行优先级：
1. 优先执行受影响模块测试：`./gradlew :secondev-xxx:test`。
2. 若只修改单个类且测试框架支持过滤，可执行目标测试类。
3. 若测试依赖不完整或当前模块无法跑测试，至少执行编译验证：`./gradlew :secondev-xxx:compileJava`。
4. 若任务要求打包，再执行：`./gradlew :secondev-xxx:jar`。
5. 多模块变更时，优先执行所有受影响模块测试；共享代码变更时执行全量 `./gradlew test` 或说明无法执行的原因。

执行要求：
1. 测试必须在代码实现和规范检查后执行。
2. 测试失败时，必须先回到实现或测试代码修复，再重新执行。
3. 不得把未执行的命令描述为已通过。
4. 若因缺少 `secDevLib`、`secDevClasses`、JUnit/Mockito 或基线依赖导致无法执行，必须列出缺失项和下一步处理建议。

输出要求：
1. 列出实际执行的命令。
2. 说明通过、失败、跳过情况。
3. 对失败用例给出失败原因和修复状态。
4. 读取控制台输出或测试报告，确认最终状态；不得只输出“已运行”。
5. 能获取时给出通过、失败、跳过数量；无法获取时说明原因。
6. 若只完成编译，明确说明“未完成单元测试执行”和阻塞原因。
7. 将验证结论映射回需求验收标准，说明覆盖的关键风险与剩余风险。
8. 测试失败或未执行时只能输出“验证失败”“验证阻塞”或“验证未完成”，禁止输出“验证通过”。

最终输出必须包含 `用例执行结果` 与 `结果验证结论`。
