# Ineed Core

> 企业级 Java 应用框架；文档适用 3.0.0-SNAPSHOT。工作区文档快照，不代表正式发行。

先阅读 AI 编码入口和规则索引；按任务加载专题。实际编码必须核对同版本源码、AGENTS.md 与任务约束。

## 开发文档

- [环境与依赖准备](/docs/prerequisites/): 准备 JDK、Maven 与同版本依赖，分清编译目标和实际运行环境。
- [第一个业务模块：从分类定义走通 Core](/docs/first-module/): 沿真实分类模块，理解 AO、实体、仓储、转换、Manager、Service 与 Controller。
- [应用运行、验证与排错](/docs/run-and-verify/): 从框架测试进入隔离数据库、应用装配、身份和 HTTP 验证。
- [可执行例子索引](/docs/examples/): 查找各技术栈的可执行框架链路和真实业务参考。
- [Ineed-Core 文档](/docs/documentation-map/): Core 文档的完整导航与不同读者的阅读路线。
- [架构与开发边界](/docs/architecture/): 用能力接口组合业务，明确 Web、Service、Manager 与持久化的职责。
- [业务对象与能力组合](/docs/object-model/): 区分 AO、Query、VO、DTO、Entity 与 Converter，明确字段的读写边界。
- [请求、事务与生命周期](/docs/request-lifecycle/): 跟随请求经过校验、事务、实体生命周期和提交后的动作。
- [运行时与能力验证矩阵](/docs/runtime-matrix/): 查看两种运行时、四条关系型路径的实现状态与验证边界。
- [规范与权威来源](/docs/standards/): 按规则编号查找唯一正文，明确跨仓规范与冲突处理。
- [基于 Ineed-Core 的项目开发文档](/docs/development-map/): 从业务开发视角查找骨架、CRUD、格式、分层及数据栈指南。
- [业务模块骨架与目录结构约定](/docs/business-module-layout-guide/): 确定 Maven 分层、业务子模块与跨技术栈对齐范围。
- [代码格式与源码风格指南](/docs/code-style-guide/): 统一 Java 格式、Javadoc、字段、日志和局部格式保护。
- [CRUD / Query 开发主路径](/docs/crud-query-guide/): 按能力组合创建、更新、查询和扩展条件，保持生命周期一致。
- [自定义业务与分层扩展指南](/docs/custom-business-layering-guide/): 在既有分层中组织业务动作，明确事务和多实体协作。
- [删除钩子、分层日志与异常追踪规范](/docs/delete-hook-and-logging-guide/): 区分逻辑删除、物理删除、恢复、引用保护与日志责任。
- [契约、错误与国际化](/docs/contract-and-error/): 保持输入输出、异常、错误码与国际化契约一致。
- [业务需求文档模板](/docs/module-requirements-template/): 在编码前填写对象、行为、状态、数据归属和验收条件。
- [开发约定反模式清单](/docs/convention-anti-patterns/): 对照常见反例定位分层、上下文、数据访问与验证问题。
- [测试与交付证据](/docs/testing/): 分清契约测试、数据库、应用 HTTP 与前端端到端证据。
- [业务集成测试编写指南](/docs/business-integration-test-guide/): 按可观察业务结果组织正向、失败、权限与多栈验证。
- [前端接入与联调指南](/docs/frontend-integration-guide/): 核对接口、权限、状态能力、查询、分页和前端交互。
- [开发模式登录与权限诊断](/docs/development-login-guide/): 在开发环境中建立真实身份，定位登录与权限接入问题。
- [JDBC 业务代码指南](/docs/jdbc/): 使用 JDBC 仓储、QueryDSL SQL、Q 表与查询扩展点。
- [JPA QueryDSL 代码编写指南](/docs/jpa-querydsl-code-guide/): 遵守 JPA 与 QueryDSL 实体、仓储及条件表达式约定。
- [MyBatis-Flex 代码编写指南](/docs/mybatis-flex-code-guide/): 按 Mapper、实体、转换与查询约定接入 MyBatis-Flex。
- [R2DBC 代码编写指南](/docs/r2dbc-code-guide/): 保持 R2DBC 查询、订阅期语义、上下文和事务一致。
- [租户、操作身份与上下文](/docs/tenant-and-context/): 区分身份、目标租户、实体归属与数据范围，核对读写隔离。
- [身份与权限接入](/docs/authorization-integration/): 复用安全模块的身份、API 权限和数据范围，避免以租户代替授权。
- [事务、并发与副作用](/docs/transaction-and-concurrency/): 检查真实事务代理、订阅链、回滚、幂等与外部副作用。
- [数据状态能力与业务状态](/docs/data-status/): 显式声明状态能力，区分通用状态位与业务状态机。
- [服务缓存接入](/docs/cache/): 按运行时接入服务缓存，核对租户键与提交后的失效。
- [业务事件接入路线](/docs/integration-events/): 选择内部或蒸馏事件，进入具体发布、监听与提交时序规范。
- [HTTP Client、Socket 与数据库元数据](/docs/clients-and-metadata/): 查找 HTTP Client、Socket 和数据库元数据入口及适用边界。
- [AI 编码入口](/docs/ai-entry/): 给 AI 一个明确入口：先识别任务，再加载相关规则和真实样例。
- [按任务读取与验证](/docs/task-routing/): 按新模块、字段、查询、动作、缓存或前端任务选择规范与验证。
- [编码任务输入模板](/docs/task-input-template/): 明确业务目标、技术栈、允许修改范围、上下文与验收要求。
- [交付检查](/docs/delivery-checklist/): 交付前核对行为、分层、数据边界、测试证据与未覆盖范围。
- [项目开发契约](/docs/development-contract/): 从旧开发契约入口转到当前 AI 路由、规则正文和交付清单。
- [Ineed-Core 内部文档](/docs/framework-map/): 从框架维护视角进入模块、能力、事件和兼容性文档。
- [Ineed-Core 真实模块清单](/docs/module-inventory/): 按 Maven 聚合查阅真实模块，不把工作区统计当作 Core 数量。
- [Ineed-Core 模块能力地图](/docs/module-capability-map/): 查找核心能力、主要接口与所属模块。
- [Ineed-Core 当前实现状态](/docs/current-implementation-status/): 区分已有实现、默认构建和仍需验证的可选能力。
- [Java 模块目录结构指南](/docs/java-module-directory-guide/): 统一 Java 模块与 Maven 工程的目录命名和职责。
- [配置参考](/docs/configuration/): 查阅配置默认值、外部设施前提和配置不生效的排查顺序。
- [扩展点速查](/docs/extension-points/): 按扩展目标定位 Controller、Service、Manager 与仓储入口。
- [Ineed-Core 集成事件接入指南](/docs/integration-event-guide/): 查看内部事件、蒸馏事件、开关和监听器的具体接入契约。
- [Constant、ErrorCode 与 I18n 约定](/docs/constant-errorcode-i18n-guide/): 遵守常量、错误码和语言资源约定，业务号段以全局登记为准。
- [模块 Constant 与 I18n 样板](/docs/module-constant-i18n-template/): 参考模块常量与 I18n 样板，替换占位业务名称和资源。
- [API 文档使用指南](/docs/api-documentation-guide/): 接入 OpenAPI 与 Scalar，核对展示开关和安全链。
- [API 兼容性治理策略](/docs/api-compatibility-policy/): 维护公共 API、兼容边界与迁移约定。
- [文档维护与验证约定](/docs/documentation-policy/): 维护单一规范来源，按变更核对链接、源码和实际验证。
- [文档入口迁移说明](/docs/migration-notes/): 理解文档入口迁移及旧路径的过渡关系。
- [文档核验记录：2026-09-19](/docs/verification-2026-09-19/): 阅读历史文档建设的工具链、测试命令和验证范围。

完整正文：[llms-full.txt](/llms-full.txt)