# java-study

**Repository Path**: shilei15926/java-demo

## Basic Information

- **Project Name**: java-study
- **Description**: 一个值得学习的java项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-28
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Java CRUD 练习项目

基于 Spring Boot 3.5、MyBatis/JDBC、MySQL 的后端 API 服务（纯接口，无前端页面），包含五个业务模块：商品目录、员工与额度、电子档案、薪资、后台日志，以及一套完整的登录与用户/角色/菜单权限管理。

**首次启动需要设置初始超管密码，未登录的请求一律 401。** 新手入门请先读[项目导读](docs/项目导读-零基础看懂本项目.md)。

## 环境要求

- JDK 21。
- Maven 3.9.x。
- MySQL 8，本机默认端口 3306。
- 能访问 Maven Central（或阿里云镜像）。

项目只依赖 Spring Boot 官方组件与公共开源库，不需要公司 Maven 仓库。

## 准备数据库

默认连接配置在 `src/main/resources/application.yml`：

```text
地址：localhost:3306
数据库：demo
账号：demo
密码：demo
```

这组配置用于本机隔离练习，不用于生产环境。可由 MySQL 管理员执行：

```sql
CREATE DATABASE IF NOT EXISTS demo
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_0900_ai_ci;

CREATE USER IF NOT EXISTS 'demo'@'localhost'
    IDENTIFIED BY 'demo';

GRANT SELECT, INSERT, UPDATE, DELETE,
      CREATE, ALTER, INDEX, REFERENCES
ON demo.* TO 'demo'@'localhost';
```

如果账号已经存在，确认其密码与配置一致。读、写两个数据源默认都使用同一个 `demo` 数据库。

应用启动时由 Flyway 自动执行 `src/main/resources/db/migration` 下的迁移：

- V1：创建目录表。
- V2：写入两条初始数据。
- V3：增加 `remark` 备注字段。
- V4：创建移企付员工、额度账户、额度流水三张表。
- V5：增加员工新增请求号及租户内唯一约束，支持新增请求安全重试。
- V6：扩展额度流水 SET 类型，支持单人调额和冻结/启用。
- V7：增加批次幂等记录，支持批量调额与批量员工导入。
- V8～V10：员工逻辑删除、银行卡及两级开卡审批。
- V11～V12：用户、角色、菜单、关联关系、登录会话、审计及登录限速表；启动后初始化当前企业的内置角色与资源。
- V13：后台异常日志表，配合 `backendTraceId` 追踪单次请求。
- V14～V16：薪资批次、薪资明细、资金划拨与银行流水。
- V17～V19：电子档案员工表（V18/V19 为演示数据的写入与清除，实测表内数据已清零）。

迁移由应用管理，无需在 Navicat 重复执行。已执行的迁移保持原样，后续表结构变更新建版本文件。

## IntelliJ IDEA 运行

1. 作为 Maven 项目打开根目录的 `pom.xml`。
2. 项目 SDK、模块 SDK 和语言级别设置为普通 Java 21。
3. 配置 Maven 的设置文件与本地仓库，重新加载 Maven 项目。
4. 本地首次运行先执行 `powershell -NoProfile -ExecutionPolicy Bypass -File scripts/Initialize-LocalIam.ps1`，再选择共享运行配置 **ECP 本地开发**。它会读取不提交到Git的 `.local/iam.yml` 并生成初始超管密码。若使用自行创建的运行配置，需手动提供环境变量 `IAM_BOOTSTRAP_PASSWORD`。
5. 等待 `Started ComponentExampleApplication`。

共享运行配置使用项目的 JDK，不绑定某台电脑的 JDK 安装路径。运行前停止其他占用 8092 端口的应用实例。

本次后端提供的真实登录API根地址：

```text
http://localhost:8092/training/api/v1
```

本项目不含前端页面，请先用登录接口拿到令牌，再携带访问令牌调用业务接口。前端工程在同级的 `vue3-study` 目录。

## Maven 测试和打包

在项目根目录执行：

```powershell
mvn test
mvn package
java -jar target/ecp-app-component-example-1.0.0-exec.jar
```

默认使用 `mybatis` profile。需要切换 JDBC 实现时可启动：

```powershell
java -jar target/ecp-app-component-example-1.0.0-exec.jar --spring.profiles.active=jdbc
```

## 项目目录

```text
src/main/java/com/ecp/component/
  ComponentExampleApplication.java  启动入口
  module/                           业务模块，每个模块内部横向分层
    catalog/                        商品目录（最简增删改查，入门看这个）
      controller/  service/  domain/  infra/  model/  exception/
    employee/                       员工、额度、批量导入、开卡审批
    archive/                        电子档案（列表 + 新增）
    payroll/                        薪资批次、明细、看板
    iam/                            登录、用户/角色/菜单、权限、审计
    backendlog/                     统一异常日志与请求追踪
  platform/                         全模块公用能力
    config/                         数据源与 Mapper 扫描
    id/                             雪花 ID 生成
    tenant/                         多租户上下文
    web/                            统一响应 ApiResponse
src/main/resources/
  application.yml                   应用配置
  db/migration/                     Flyway 数据库迁移（已执行的不可修改）
  mapper/                           MyBatis XML SQL
scripts/                            本机 IAM 初始化脚本
.run/                               IDEA 共享运行配置
docs/                              项目导读与学习资料
```

分层调用方向永远是单向的：`controller → service → domain(接口) ← infra(实现)`。

移企付员工的新增、分页查询、删除、调额冻结、批量调额与导入均已实现，接口路径见各模块的 Controller 类；分页查询的完整链路讲解见[项目导读](docs/项目导读-零基础看懂本项目.md)。

## 备注字段验收

1. 新增记录，输入备注并保存。
2. 刷新页面，确认备注仍然显示。
3. 编辑记录，确认备注回填且可修改。
4. 清空备注后保存，列表显示“—”。
5. 备注支持换行，最多 255 个字符。

可在 Navicat 查询真实保存值：

```sql
SELECT item_code, item_name, remark
FROM demo.catalog_item
WHERE tenant_id = 'training-tenant';
```

## 当前已知问题

查询不存在的记录 ID 时，当前 ECP 调用链可能返回通用 `500 / INVOCATION_FAILED`；该错误响应还需要后续修正。