定期更新

.gitignore

@@ -9,3 +9,5 @@
 !/.nvmrc
 .vscode/
 *.DS_Store
+local_docs/
+.scannerwork/

README.md

@@ -1,31 +1,93 @@
-# Cloud Native
+# Cloud Native Configuration Management
 
-This repository contains a small full-stack workspace:
+Cloud Native Configuration Management is a full-stack configuration governance workspace for project, factory, environment, template, override, export, and change-history workflows.
 
-- `frontend/`: Vite + React application
-- `backend/`: Spring Boot API with PostgreSQL, Flyway, JPA, validation, and auth/configuration flows
-- `.github/workflows/`: CI definitions
+The repository is organized as a single workspace with a React frontend, a Spring Boot backend, PostgreSQL persistence, automated tests, coverage reports, and SonarQube quality analysis.
 
-## Quick Start
+## Project Overview
+
+The application helps teams manage reusable configuration templates and project-specific overrides across deployment scopes.
+
+Core capabilities:
+
+- user registration, login, JWT authentication, and role-aware screens;
+- configuration template creation, editing, inspection, import, export, and deletion;
+- project, factory, and environment scope browsing;
+- project scope configuration preview with inherited template values and overrides;
+- change-request and version-history support for configuration changes;
+- backend service tests and frontend component/page tests;
+- SonarQube quality gate validation with frontend and backend coverage.
+
+## Repository Structure
+
+```text
+.
+├── backend/                 Spring Boot API, domain logic, persistence, tests
+├── frontend/                Vite React UI, Vitest tests, frontend coverage
+├── deploy/                  Nginx and Docker Compose deployment references
+├── docs/                    Shared project documentation
+├── local_docs/              Local notes and presentation-only artifacts
+├── sonar-project.properties Root aggregate SonarQube scan configuration
+└── README.md                Main project guide
+```
+
+Important entry points:
+
+- [frontend/src](frontend/src): React application source
+- [frontend/tests](frontend/tests): frontend tests
+- [backend/src/main/java](backend/src/main/java): backend application source
+- [backend/src/test/java](backend/src/test/java): backend tests
+- [sonar-project.properties](sonar-project.properties): canonical SonarQube scan configuration
 
-### Requirements
+## Architecture
+
+Local development runs three main services:
+
+```text
+Browser
+  -> Vite dev server / frontend static build
+  -> Spring Boot backend API
+  -> PostgreSQL database
+```
+
+The production-oriented deployment model is stateless at the backend layer:
+
+```text
+Users
+  -> DNS / HTTPS
+  -> Load Balancer or Reverse Proxy
+      -> Frontend static app
+      -> Backend API replica pool
+          -> PostgreSQL / managed database
+```
+
+The backend uses JWT-based authentication and stores source-of-truth data in PostgreSQL, so backend replicas can be placed behind a load balancer without sticky sessions.
+
+Deployment references are in [deploy/README.md](deploy/README.md).
+
+## Requirements
 
 - Node.js `20.19+`
-- Java `21+` or newer
+- npm
+- Java `21+`
 - Maven
-- Docker, if you want to run PostgreSQL locally in a container
+- PostgreSQL `15+`, or Docker for local PostgreSQL
+- Optional: local or online SonarQube / SonarCloud access
 
 Default local ports:
 
 ```text
 Frontend:   http://127.0.0.1:5173
 Backend:    http://127.0.0.1:8080
 PostgreSQL: localhost:5432
+SonarQube:  http://localhost:9000, if running locally
 ```
 
+## Quick Start
+
 ### 1. Start PostgreSQL
 
-If you do not already have a local PostgreSQL database, start one with Docker:
+If PostgreSQL is not already available locally, start a Docker container:
 
 ```bash
 docker run --name cloud-native-postgres \
@@ -42,7 +104,7 @@ If the container already exists:
 docker start cloud-native-postgres
 ```
 
-The backend defaults to:
+The backend defaults are:
 
 ```text
 DATABASE_URL=jdbc:postgresql://localhost:5432/cloud_native_db
@@ -51,6 +113,8 @@ DATABASE_PASSWORD=cloudnative
 QUICK_ADMIN_PASSWORD=optional local quick-login password
 ```
 
+If your database runs on another port, export the variables before starting the backend.
+
 ### 2. Start Backend
 
 ```bash
@@ -60,15 +124,15 @@ mvn spring-boot:run -Dspring-boot.run.profiles=dev
 
 The backend runs on `http://127.0.0.1:8080`.
 
-Flyway applies database migrations on startup. Current seed data includes:
+Flyway applies database migrations on startup. The seed data includes template types, sample projects, factories, environments, and project scope template selections.
 
-- template types such as Application Config, Database Config, Cache Config, Security / Auth Config
-- an `AI Agent` project
-- 12 factories, `Factory A` through `Factory L`
-- 4 environments: Development, Testing, Staging, Production
-- sample template selections for project scope preview
+Health check:
 
-### Frontend
+```text
+GET http://127.0.0.1:8080/api/health
+```
+
+### 3. Start Frontend
 
 ```bash
 cd frontend
@@ -78,136 +142,155 @@ npm run dev
 
 The frontend runs on `http://127.0.0.1:5173`.
 
-### Backend Details
+## Application Flow
 
-See [backend/README.md](backend/README.md) for the full backend workflow, including PostgreSQL setup, Flyway notes, backend testing, and coverage usage.
+1. Open `http://127.0.0.1:5173`.
+2. Register or log in.
+3. Use `Search` to search configurations and templates.
+4. Use `Templates` to manage reusable configuration fragments.
+5. Use `Projects` to inspect project scope configuration by project, factory, and environment.
+6. Use export/import screens to move configuration data through supported formats.
 
-If you already have PostgreSQL ready:
+The main project inspection flow is:
 
-```bash
-cd backend
-mvn spring-boot:run -Dspring-boot.run.profiles=dev
+```text
+Project List -> Factory List -> Environment List -> Templates Used -> Effective Config Preview
 ```
 
-## How To Use The App
+The clone-source preview flow supports selecting a base project/factory/environment and optionally mixing individual template sources from other scopes before review.
 
-1. Open `http://127.0.0.1:5173`.
-2. Register or log in from the auth screen.
-3. Use `Search` to search backend configurations and templates.
-4. Use `Templates` to create, inspect, edit, and delete reusable config fragments.
-5. Use `Projects` to inspect project scope configuration.
+## Testing And Coverage
 
-The current Project flow is:
+### Frontend
 
-```text
-Project List -> Factory List -> Environment List -> Templates Used
+```bash
+cd frontend
+npm run test
+npm run test:coverage
 ```
 
-After selecting a project, factory, and environment, the right panel shows which template files are used by that scope.
-
-The `Clone Project` button opens a clone source picker:
+Coverage output:
 
 ```text
-Select base Project / Factory / Environment
-Review final config preview
-Optionally mix individual template sources from other Factory / Environment scopes
-View template details from each row
-Select Clone Source
+frontend/coverage/lcov.info
+frontend/coverage/coverage-summary.json
 ```
 
-The clone flow is currently a frontend workflow preview. It can compose and display a mixed clone source in the UI, but it does not yet persist a cloned project to the backend.
-
-## Testing
+The LCOV file is the frontend coverage input used by SonarQube.
 
-### Frontend tests
+### Backend
 
 ```bash
-cd frontend
-npm run test
+cd backend
+mvn clean verify
 ```
 
-### Backend tests
+This runs backend tests and generates JaCoCo coverage:
 
-```bash
-cd backend
-mvn verify
+```text
+backend/target/site/jacoco/index.html
+backend/target/site/jacoco/jacoco.xml
 ```
 
-This currently:
-
-- runs the regular backend test suite
-- generates a JaCoCo coverage report at `backend/target/site/jacoco/index.html`
+The XML report is the backend coverage input used by SonarQube.
 
-The backend PostgreSQL/Testcontainers integration test is intentionally tagged as `integration` and skipped by default for local runs. To include it:
+The PostgreSQL/Testcontainers integration test is tagged as `integration` and skipped by default. To include it:
 
 ```bash
 cd backend
 mvn verify -Dexcluded.test.tags=
 ```
 
-The detailed explanation and Docker-related notes live in [backend/README.md](backend/README.md).
+More backend setup details are in [backend/README.md](backend/README.md).
 
-## Deployment Architecture
+## SonarQube Quality Gate
 
-The target deployment architecture is:
+The canonical SonarQube project is the root aggregate project:
 
 ```text
-Users
-  -> DNS / HTTPS
-  -> Load Balancer / Reverse Proxy
-      -> Frontend static app
-      -> Backend API replica pool
-          -> PostgreSQL / Neon
+cloud-native
 ```
 
-The backend is designed to be stateless for request routing because it uses JWT
-authentication and stores source-of-truth data in PostgreSQL. That allows future
-backend replicas to sit behind a load balancer without sticky sessions.
+Run the scanner from the repository root after generating both frontend and backend coverage reports:
 
-Deployment references live in [deploy/README.md](deploy/README.md):
+```bash
+cd frontend
+npm run test:coverage
 
-- `deploy/nginx.production.conf`: production-oriented reverse proxy template
-- `deploy/production-like/`: runnable Docker Compose stack with frontend, backend replicas, reverse proxy, and PostgreSQL
-- `deploy/demo/`: local Docker Compose demo with Nginx and scaled backend replicas
+cd ../backend
+mvn clean verify
 
-The backend health endpoint for load balancers and uptime checks is:
+cd ..
+npx @sonar/scan \
+  -Dsonar.host.url=http://localhost:9000 \
+  -Dsonar.token=$SONAR_TOKEN
+```
+
+The root scan reads [sonar-project.properties](sonar-project.properties), including:
 
 ```text
-GET /api/health
+frontend/coverage/lcov.info
+backend/target/site/jacoco/jacoco.xml
 ```
 
-## Repository Structure
+Use the root `cloud-native` project for final quality gate evidence. Standalone project keys such as `cloud-native-frontend` and `cloud-native-backend` have separate baselines and issue history, so they can produce different results unless maintained intentionally.
 
-```text
-.
-├── .github/
-│   └── workflows/
-├── backend/
-│   ├── src/
-│   ├── target/
-│   └── README.md
-├── frontend/
-│   ├── src/
-│   └── tests/
-└── README.md
+Detailed SonarQube notes, online-scan requirements, and troubleshooting are in [docs/quality-and-sonarqube.md](docs/quality-and-sonarqube.md).
+
+## Code Quality Policy
+
+The project uses a conservative coverage and quality strategy:
+
+- test user-facing frontend flows and backend business logic
+- exclude low-value bootstrap, DTO, repository, controller, enum, static data, and framework-wiring files from coverage KPIs where appropriate
+- avoid committing generated output such as `coverage/`, `target/`, `.scannerwork/`, and `dist/`
+- treat security hotspots as review items that require either remediation or a clear explanation.
+
+Current local quality evidence should be regenerated from the commands above instead of relying on committed reports.
+
+## Security Scanning
+
+Dependency vulnerability scanning is documented as a manual workflow in [docs/security-scanning.md](docs/security-scanning.md).
+
+Common commands:
+
+```bash
+cd frontend
+npm audit --audit-level=high
+
+cd ../backend
+mvn org.owasp:dependency-check-maven:check
 ```
 
-## Documentation Guide
+These dependency scans complement application security tests for JWT authentication, role guards, and protected backend endpoints.
+
+## Deployment
+
+Deployment references live in [deploy/README.md](deploy/README.md):
+
+- `deploy/nginx.production.conf`: production-oriented reverse proxy template;
+- `deploy/production-like/`: Docker Compose stack with frontend, backend replicas, reverse proxy, and PostgreSQL;
+- `deploy/demo/`: local demo stack with Nginx and scaled backend replicas.
 
-- [backend/README.md](backend/README.md)
-  Backend setup, PostgreSQL, Flyway, local testing, and coverage
+The backend health endpoint for load balancers and uptime checks is:
 
-- [deploy/README.md](deploy/README.md)
-  Deployment topology, load balancing model, Nginx reverse proxy template, and production checklist
+```text
+GET /api/health
+```
+
+## Documentation Guide
 
-- [docs/security-scanning.md](docs/security-scanning.md)
-  Manual dependency vulnerability scanning commands for frontend and backend
+- [backend/README.md](backend/README.md): backend setup, PostgreSQL, Flyway, tests, and coverage
+- [deploy/README.md](deploy/README.md): deployment topology and production-like local stack
+- [docs/quality-and-sonarqube.md](docs/quality-and-sonarqube.md): coverage, SonarQube, online scan, and Quality Gate guidance
+- [docs/security-scanning.md](docs/security-scanning.md): manual dependency vulnerability scanning
 
 ## CI
 
-GitHub Actions runs separate frontend and backend jobs from [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+GitHub Actions runs separate frontend and backend jobs from [.github/workflows/ci.yml](.github/workflows/ci.yml).
 
-Today that means:
+The CI workflow currently covers:
 
-- frontend install, test, and build checks
-- backend Maven test execution
+- frontend dependency install, tests, and build;
+- backend Maven tests;
+- fast feedback for pull requests and branch updates.