# archive-system

**Repository Path**: uesugi-java/archive-system

## Basic Information

- **Project Name**: archive-system
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-10
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 档案动态表单系统

## 系统说明

档案动态表单系统用于管理档案类型、动态字段、字典项、档案业务数据以及 MySQL 到 Elasticsearch 的同步检索链路。系统采用接口先行开发方式，OpenAPI 契约位于 `docs/openapi/archive-system.yaml`，后端代码按契约实现 Controller、DTO、统一响应和错误码。

## 技术栈

- JDK 21，使用虚拟线程处理受控阻塞 I/O 和批量同步任务。
- Spring Boot 3.5.16，Spring Cloud 2025.0.3，Spring Cloud Alibaba 2025.0.0.0。
- MySQL 8.0，Flyway，MyBatis-Plus，ShardingSphere-JDBC。
- Elasticsearch 7.17.x，Redis，RocketMQ，Nacos。
- springdoc-openapi，Micrometer，Actuator。

## 模块职责

- `archive-common`：统一响应、错误码、异常处理、链路追踪、虚拟线程公共配置。
- `archive-api`：接口 DTO、枚举和契约对象。
- `archive-service`：档案类型、字典、档案数据、同步日志和检索路由核心服务。
- `archive-sync-service`：独立同步服务，负责同步补偿调度、消息消费和 Elasticsearch 写入链路。
- `archive-gateway`：统一入口、路由、鉴权、traceId 透传、限流和降级。

## 标准包结构

`archive-service` 新增代码必须按职责落位：

- `controller`：HTTP 接口入口，只依赖 Service 接口。
- `service`：业务服务接口。
- `service.impl`：业务服务实现。
- `router`：Elasticsearch 与 MySQL 查询路由、降级路由。
- `validation`：Schema、字段、字典值和查询条件校验。
- `constant`：业务状态和跨类共享常量。
- `sync`：核心服务内的同步日志投递和同步处理协调。
- `infrastructure`：数据库、Elasticsearch、缓存、消息等基础设施适配。
- `config`：Spring、线程池、安全和组件配置。

`archive-sync-service` 中定时任务必须放在 `scheduler` 包。禁止把 Service、路由、校验、常量或定时任务继续放入 `domain` 包。

## 接口说明

基础路径默认通过核心服务 `http://localhost:8080` 或网关 `http://localhost:18080` 访问。

- 档案类型：`/api/v1/archive/types`
- 档案数据：`/api/v1/archive/data`
- 字典管理：`/api/v1/dict/groups`、`/api/v1/dict/items`
- 同步管理：`/api/v1/sync/logs`、`/api/v1/sync/logs/{id}/retry`、`/api/v1/sync/logs/compensate`、`/api/v1/sync/backlog/stats`

所有接口返回统一结构：

```json
{
  "code": 0,
  "message": "success",
  "data": {},
  "timestamp": 1783670400000,
  "traceId": "trace-id",
  "path": "/api/v1/archive/types"
}
```

Swagger UI 默认地址：

- 核心服务：`http://localhost:8080/swagger-ui.html`
- 网关服务：`http://localhost:18080/swagger-ui.html`

## 数据库

默认数据库名为 `archive`。Flyway 初始化脚本位于 `archive-service/src/main/resources/db/migration`，核心表包括：

- `archive_type`：档案类型元数据。
- `archive_field`：档案动态字段配置。
- `dict_group`、`dict_item`：字典组和字典项。
- `archive_sync_log`：同步日志和补偿状态。
- `audit_log`：操作审计日志。
- `archive_data_0000` 到 `archive_data_0063`：开发拓扑下的 64 张档案数据分片表。

开发环境采用单库 64 表，按 `type_id % 64` 路由；生产可扩展为 16 库 4 表，分片规则通过 Nacos 配置覆盖。

### SQL 脚本

独立 SQL 脚本位于 `scripts/sql`，用于 DBA 审核、手工初始化、上线前预检、只读巡检和本地开发清理。脚本均为 UTF-8 编码，中文注释，禁止写入真实密码。

| 脚本 | 用途 | 适用环境 | 是否只读 |
|------|------|----------|----------|
| `00_create_database_and_user.sql` | 创建 `archive` 数据库和示例业务账号 | 本地、测试、生产审核后执行 | 否 |
| `01_init_schema.sql` | 创建完整表结构、索引、约束和 64 张开发分表 | 本地、测试、生产审核后执行 | 否 |
| `02_seed_demo_data.sql` | 写入本地联调用示例档案类型、字段、字典和示例档案数据 | 本地、测试 | 否 |
| `90_verify_schema.sql` | 校验字符集、核心表、关键字段和分表数量 | 本地、测试、生产 | 是 |
| `91_verify_indexes.sql` | 校验关键索引、唯一约束和分表索引一致性 | 本地、测试、生产 | 是 |
| `92_inspect_runtime_state.sql` | 巡检表行数、同步日志状态和审计概况 | 本地、测试、生产 | 是 |
| `99_dev_cleanup.sql` | 清理示例数据和开发验证数据 | 仅本地开发 | 否 |

推荐执行顺序：

```powershell
mysql -h <数据库地址> -P 3306 -u <管理员账号> -p < .\scripts\sql\00_create_database_and_user.sql
mysql -h <数据库地址> -P 3306 -u <业务账号> -p archive < .\scripts\sql\01_init_schema.sql
mysql -h <数据库地址> -P 3306 -u <业务账号> -p archive < .\scripts\sql\90_verify_schema.sql
mysql -h <数据库地址> -P 3306 -u <业务账号> -p archive < .\scripts\sql\91_verify_indexes.sql
```

本地联调可在结构初始化后执行：

```powershell
mysql -h 127.0.0.1 -P 3306 -u archive_user -p archive < .\scripts\sql\02_seed_demo_data.sql
mysql -h 127.0.0.1 -P 3306 -u archive_user -p archive < .\scripts\sql\92_inspect_runtime_state.sql
```

`99_dev_cleanup.sql` 默认不会清理数据。只有确认当前连接的是本地开发库后，才允许把脚本中的 `@confirm_dev_cleanup` 改为 `YES_I_AM_IN_DEV` 后执行。生产环境禁止执行该脚本。

Flyway 与独立 SQL 的关系：应用运行时迁移仍以 Flyway 为准；独立 SQL 用于部署审核、离线初始化和运维校验。二者的基线结构必须保持一致，不应在同一个空库中同时混用 Flyway 自动初始化和手工执行 `01_init_schema.sql`。

敏感参数处理：SQL 中的数据库密码、主机地址和环境差异参数必须使用占位符或命令行输入替换，禁止把真实 MySQL、Elasticsearch、Nacos 或其他外部依赖密码提交到仓库。

## Elasticsearch

Elasticsearch 使用 7.x 客户端和语法。同步文档以业务 ID 作为文档 ID，以 MySQL 版本作为外部版本，避免重复消息、乱序消息覆盖新数据。

当前指定地址为 `127.0.0.1:9200`，该地址只在应用服务与 Elasticsearch 部署在同一台机器时有效。跨主机部署必须在 Nacos 中把 `ELASTICSEARCH_URIS` 改为服务可访问的真实地址。

## Nacos 配置

仓库内只提交模板和占位符，不提交真实密码。三个 Data ID 位于 `config/nacos`：

- `archive-service.yaml`
- `archive-sync-service.yaml`
- `archive-gateway.yaml`

默认分组为 `DEFAULT_GROUP`。发布脚本：

```powershell
$mysqlPassword = Read-Host "请输入 MySQL 密码" -AsSecureString
$esPassword = Read-Host "请输入 Elasticsearch 密码" -AsSecureString

powershell -ExecutionPolicy Bypass -File .\scripts\publish-nacos-config.ps1 `
  -NacosBaseUrl "http://10.1.3.99:8848/nacos" `
  -MysqlHost "219.153.103.91" `
  -MysqlPort 3306 `
  -MysqlDatabase "archive" `
  -MysqlUsername "root" `
  -MysqlPassword $mysqlPassword `
  -ElasticsearchUris "http://127.0.0.1:9200" `
  -ElasticsearchUsername "elastic" `
  -ElasticsearchPassword $esPassword
```

脚本会先检查 Nacos 连通性，备份同名配置，发布后回读校验。Redis 与 RocketMQ 当前使用本地默认占位，生产部署前必须改为真实地址。

## 构建与启动

要求使用 JDK 21：

```powershell
$env:JAVA_HOME="C:\Java\jdk-21"
$env:Path="$env:JAVA_HOME\bin;$env:Path"
mvn clean test
```

启动顺序：

1. 启动 MySQL 8.0，并准备 `archive` 数据库。
2. 启动 Nacos，并发布三个 Data ID。
3. 启动 Redis、RocketMQ、Elasticsearch 7。
4. 启动核心服务：`mvn -pl archive-service spring-boot:run`
5. 启动同步服务：`mvn -pl archive-sync-service spring-boot:run`
6. 启动网关：`mvn -pl archive-gateway spring-boot:run`

## 健康检查

- 核心服务：`http://localhost:8080/actuator/health`
- 同步服务：`http://localhost:8081/actuator/health`
- 网关：`http://localhost:18080/actuator/health`

常用验证：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\verify-openapi.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\check-utf8.ps1
```

## 故障排查

- 启动时报 Nacos 连接失败：检查 `NACOS_SERVER_ADDR`、8848 端口以及 Nacos 3.x gRPC 端口是否可达。
- MySQL 连接失败：检查 Nacos 中数据库地址、账号、密码和 `archive` 库是否存在。
- Elasticsearch 同步失败：检查 ES 地址是否从服务所在机器可访问，尤其注意 `127.0.0.1` 只代表本机。
- Swagger UI 无法访问：确认服务已启动并引入 springdoc 依赖，检查 `/v3/api-docs`。
- 中文乱码：确认文件、终端、Maven 和日志均使用 UTF-8，执行 `scripts/check-utf8.ps1`。

## 验收记录

- 已使用 JDK 21 执行 Maven 测试。
- 已执行 OpenAPI 校验。
- 已执行 UTF-8 与中文乱码扫描。
- Docker 当前不可用时，Testcontainers 相关 MySQL 集成测试会跳过，需在具备 Docker 的环境补充执行。