important-new · important-new · Jun 14, 2026 · Jun 14, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -113,7 +113,7 @@ your contributions are licensed under the same terms.
 ### 运行测试
 
 项目提供跨平台测试套件（Windows / macOS / Linux），详见
-[`docs/LOCAL_TESTING.md`](docs/LOCAL_TESTING.md)：
+[`docs/zh-CN/LOCAL_TESTING.md`](docs/zh-CN/LOCAL_TESTING.md)：
 
 ```bash
 # 后端 —— pytest + moto（内存模拟 DynamoDB，无需 Docker / AWS）
@@ -151,7 +151,7 @@ CI 在每次 Pull Request 时运行二者，见 [`.github/workflows/`](.github/w
 - **Angular/TypeScript**：遵循现有 standalone 组件 + Material M3 模式，不要重新
   引入已废弃的包（如 `@angular/flex-layout`）。
 - **不提交敏感信息**：切勿提交 Cognito 池/客户端 ID、API URL、邮箱、密码或 AWS
-  账号 ID。使用占位符并在 [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) 中说明。
+  账号 ID。使用占位符并在 [`docs/zh-CN/CONFIGURATION.md`](docs/zh-CN/CONFIGURATION.md) 中说明。
 
 ### 贡献的许可
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -10,7 +10,7 @@
 
 本项目派生自 AWS 官方的 [AWS Serverless SaaS Workshop](https://github.com/aws-samples/aws-serverless-saas-workshop)（基于其 `Lab6`），并在其基础上做了**后端架构重构、数据模型简化、运行时与依赖升级、部署脚本增强**等大量修改，已作为独立衍生项目按 MIT-0 演进。
 
-- 完整的差异清单与原因：[`docs/CHANGES_FROM_WORKSHOP.md`](docs/CHANGES_FROM_WORKSHOP.md)
+- 完整的差异清单与原因：[`docs/zh-CN/CHANGES_FROM_WORKSHOP.md`](docs/zh-CN/CHANGES_FROM_WORKSHOP.md)
 - 版权溯源与署名：[`NOTICE`](NOTICE) ｜ 许可证：[`LICENSE`](LICENSE)（MIT-0）
 
 ## 核心特性
@@ -165,7 +165,7 @@ aws-serverless-saas-quickstart/
 - [`docs/zh-CN/TENANT_MANAGEMENT.md`](docs/zh-CN/TENANT_MANAGEMENT.md) —— 平台租户管理实现(生命周期、用户/租户关联、权限控制、分级)
 - [`docs/zh-CN/API_CONFIGURATION.md`](docs/zh-CN/API_CONFIGURATION.md) —— 管理端与租户端接口配置关系剖析
 - [`docs/zh-CN/THROTTLING_AND_MONITORING.md`](docs/zh-CN/THROTTLING_AND_MONITORING.md) —— 监控运维、使用计划限流,以及 CloudWatch 限流指标机制
-- [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) ｜ [`docs/LOCAL_TESTING.md`](docs/LOCAL_TESTING.md) ｜ [`docs/CHANGES_FROM_WORKSHOP.md`](docs/CHANGES_FROM_WORKSHOP.md) ｜ [`docs/DEPENDENCY_AUDIT.md`](docs/DEPENDENCY_AUDIT.md)
+- [`docs/zh-CN/CONFIGURATION.md`](docs/zh-CN/CONFIGURATION.md) ｜ [`docs/zh-CN/LOCAL_TESTING.md`](docs/zh-CN/LOCAL_TESTING.md) ｜ [`docs/zh-CN/CHANGES_FROM_WORKSHOP.md`](docs/zh-CN/CHANGES_FROM_WORKSHOP.md) ｜ [`docs/zh-CN/DEPENDENCY_AUDIT.md`](docs/zh-CN/DEPENDENCY_AUDIT.md)
 
 深度剖析的英文版位于 [`docs/`](docs/) 根目录。
 
@@ -303,7 +303,7 @@ ng serve
 
 ### 测试
 
-跨平台测试套件（Windows / macOS / Linux），详见 [`docs/LOCAL_TESTING.md`](docs/LOCAL_TESTING.md)：
+跨平台测试套件（Windows / macOS / Linux），详见 [`docs/zh-CN/LOCAL_TESTING.md`](docs/zh-CN/LOCAL_TESTING.md)：
 
 ```bash
 # 后端：pytest + moto（内存模拟 DynamoDB，无需 Docker / AWS）
@@ -349,7 +349,7 @@ CI 见 `.github/workflows/`：`backend-tests.yml`（三平台 pytest）、`front
 ## 许可证
 
 本项目基于 [MIT-0](LICENSE) 许可证开源。上游溯源与署名见 [`NOTICE`](NOTICE)，
-与上游 Workshop 的差异见 [`docs/CHANGES_FROM_WORKSHOP.md`](docs/CHANGES_FROM_WORKSHOP.md)。
+与上游 Workshop 的差异见 [`docs/zh-CN/CHANGES_FROM_WORKSHOP.md`](docs/zh-CN/CHANGES_FROM_WORKSHOP.md)。
 
 ## 相关资源
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -138,7 +138,7 @@ This project is distributed under the terms in [LICENSE](LICENSE).
 - **切勿将硬编码的凭据**（密码、API 密钥、令牌）提交到仓库。请使用环境变量、参数存储或
   密钥管理服务。
 - 已知的依赖安全公告及其修复方案记录在
-  [docs/DEPENDENCY_AUDIT.md](docs/DEPENDENCY_AUDIT.md) 中。例如，为避免 CVE-2024-33663
+  [docs/zh-CN/DEPENDENCY_AUDIT.md](docs/zh-CN/DEPENDENCY_AUDIT.md) 中。例如，为避免 CVE-2024-33663
   与 CVE-2024-33664，从无人维护的 `python-jose` 迁移到 `PyJWT[crypto]` 的过程便记录于此。
 
 本项目依据 [LICENSE](LICENSE) 中的条款进行分发。
diff --git a/docs/CHANGES_FROM_WORKSHOP.md b/docs/CHANGES_FROM_WORKSHOP.md
@@ -1,114 +1,154 @@
-# 与上游 AWS Serverless SaaS Workshop 的差异说明
+# Changes from the Upstream AWS Serverless SaaS Workshop
 
-本文件记录 **aws-serverless-saas-quickstart** 相对上游 **AWS Serverless SaaS
-Workshop**（`aws-samples/aws-serverless-saas-workshop`，对应其 `Lab6`）所做的
-修改及原因。
+[**English**](CHANGES_FROM_WORKSHOP.md) ｜ [中文](zh-CN/CHANGES_FROM_WORKSHOP.md)
 
-## 1. 血缘与定位
+[← Back to README](../README.md)
 
-- 本项目派生自上游 Workshop 的 **Lab6**（最终实验版本）。版权与许可证溯源见
-  仓库根目录的 [`NOTICE`](../NOTICE) 与 [`LICENSE`](../LICENSE)（MIT-0）。
-- 上游 Workshop 是一套**教学实验序列**（Lab1~Lab7，逐步引导搭建），定位是培训
-  材料；本项目则把 Lab6 重构为一个**可直接落地、结构精简的参考实现/快速启动模板**。
-- **本项目已作为独立衍生项目演进，不再向上游回馈改动**，原因见第 4 节。
+This document records the changes that **aws-serverless-saas-quickstart** makes
+relative to the upstream **AWS Serverless SaaS Workshop**
+(`aws-samples/aws-serverless-saas-workshop`, corresponding to its `Lab6`), and
+the reasons behind them.
 
-## 2. 差异概览
+## 1. Lineage and Positioning
 
-以 quickstart 对比 workshop/Lab6（已排除 `node_modules`、构建产物等）：
+- This project is derived from **Lab6** of the upstream Workshop (its final lab
+  version). For copyright and license provenance, see the [`NOTICE`](../NOTICE)
+  and [`LICENSE`](../LICENSE) (MIT-0) files in the repository root.
+- The upstream Workshop is a **teaching lab sequence** (Lab1–Lab7, building up
+  step by step), positioned as training material; this project instead
+  refactors Lab6 into a **directly deployable, streamlined reference
+  implementation / quick-start template**.
+- **This project has evolved as an independent derivative and no longer
+  contributes changes back upstream**; the reasons are given in Section 4.
 
-| 类别 | 文件数 | 说明 |
+## 2. Overview of Differences
+
+Comparing quickstart against workshop/Lab6 (excluding `node_modules`, build
+artifacts, etc.):
+
+| Category | File count | Notes |
 |---|---:|---|
-| 完全相同 | 184 | 多为前端 Angular 脚手架、Landing 页、未改动的模板 |
-| 同路径但已修改 | 24 | 依赖升级、配置、部分前端 service/model |
-| 仅 quickstart（新增） | 69 | 重构后的新结构、新增运维脚本、许可证文件等 |
-| 仅 Lab6（被替换/删除） | 38 | 旧的扁平 server 结构 |
-
-按文件数约 66% 相同，但相同部分集中在前端样板；**后端（项目核心）几乎被重写**。
-
-## 3. 主要变更与原因
-
-### 3.1 后端架构：单体模板 → 按服务拆分
-- **变更**：上游 server 下的扁平服务目录（`ProductService/`、`OrderService/`、
-  `TenantManagementService/`）与两个大模板（`shared-template.yaml`、
-  `tenant-template.yaml`）被重组为：
-  - `server/services/{product-service, order-service, tenant-api}/`——每个服务
-    拥有**独立**的 `template.yaml` + `samconfig.toml`（拆成可独立部署的微栈）；
-  - Python 代码引入 DAL 分层：`*_service.py` + `*_service_dal.py` + `*_models.py`。
-- **原因**：降低服务间耦合、支持服务独立部署、提升模板可维护性。
-- **相关提交**：`bcb1d1a` (restructure serverless SaaS architecture with service
-  separation)、`0805565`、`753aa67`、`666dd8b`。
-
-### 3.2 共享资源归集到 `server/shared/`
-- **变更**：`layers/`、`nested_templates/`、`custom_resources/`、`Auth/`、
-  `tenant-management/` 等由散落在 server 根目录，统一收纳到
-  `server/shared/{auth, layers, nested_templates, custom_resources, tenant-management}/`。
-- **原因**：明确区分「共享基础设施」与「业务服务」，目录职责更清晰。
-- **相关提交**：`0805565` (move tenant-management from infrastructure to shared)、
-  `753aa67` (restructure shared infrastructure directory layout)、
-  `b632860` (reorganize auth components)。
-
-### 3.3 数据模型：移除 `shardId` 分片，改用 `tenant_id` 分区键
-- **变更**：Order / Product 服务的 DynamoDB 设计由「`shardId` 分片 + 并行查询」
-  改为以 `tenant_id` 作为分区键的简化设计；同步更新数据模型、CRUD 与前端模板。
-- **原因**：消除复杂的分片/并行查询逻辑，数据分布更可预测，降低存储与查询成本
-  （详见 README「数据库设计规则」一节）。
-- **相关提交**：`37a2587` (use tenant_id instead of shardId)、`40ea9ff`。
-
-### 3.4 Python 运行时升级到 3.13
-- **变更**：Lambda 运行时与 CDK 流水线由旧版本统一升级到 **Python 3.13**，
-  CodeBuild 构建镜像改为 `STANDARD_7_0`。
-- **原因**：上游使用的旧运行时已接近/到达 EOL，升级以获得长期支持与安全更新。
-- **相关提交**：`7ea8533`。
-
-### 3.5 依赖修复与升级（含 AWS Lambda Powertools）
-- **变更**：修复并升级过时依赖，重点修正 Powertools 相关依赖。
-- **原因**：上游依赖版本过时，存在兼容性/安全问题。
-- **相关提交**：`b632860` (fix powertools dependencies)。
-
-### 3.6 前端：Angular 与 Amplify 调整
-- **变更**：初期尝试 Angular 16.2.12 + AWS Amplify v6（`51c412b`），后因兼容性
-  **回滚到 Angular 14.x**，并将认证逻辑改为更新后的 Amplify 调用方式（`184f5f9`）。
-- **原因**：版本兼容性与稳定性。
-- **相关提交**：`51c412b`、`184f5f9`、`40ea9ff`。
-
-### 3.7 部署与运维脚本增强
-- **变更**：
-  - 各前端 `package.json` 增加 `deploy` / `reset` 脚本（S3 sync + CloudFront 失效）；
-  - 新增一批 Node.js 运维工具脚本：`create-admin-user.js`、`manage-users.js`、
-    `set-admin-password.js`、`get-login-info.js`、`generate-env-config.js`；
-  - 新增 `scripts/DEPLOYMENT_GUIDE.md` 部署指南。
-- **原因**：简化部署流程与租户/管理员用户的日常管理。
-- **相关提交**：`5366935` 及上述新增文件。
-
-### 3.8 其他配置调整
-- 租户栈命名 `pooled-tenant-stack` → `stack-pooled`（`8634f86`）。
-- `LambdaReserveConcurrency` 默认值 `20` → `0`（`2a262ad`），避免在账号预留并发
-  配额受限的环境下部署失败。
-
-## 4. 为什么不再向上游回馈
-
-1. **结构性重构难以回馈**：目录改名、模板拆分、数据模型变更使绝大多数改动无法
-   干净地 cherry-pick 回上游——路径与结构都对不上，PR 会变成大规模的「删一片、
-   加一片」，评审与合并成本极高。
-2. **定位不同**：上游是分步教学的实验序列（Lab1~Lab7），刻意保留逐层演进的结构；
-   本项目是面向落地的精简产品，二者目标不一致。
-3. **维护独立**：因此本项目作为**独立衍生项目**维护，按 MIT-0 开源；上游署名与
-   来源在 `NOTICE` 中保留。
-
-> 注：仅有少量「同路径的窄改动」（如部署脚本修复、个别依赖升级）在技术上仍可回馈，
-> 但综合收益有限，当前不作为目标。
-
-## 5. 结构对照（旧 → 新）
-
-| 上游 Lab6 路径 | quickstart 路径 |
+| Identical | 184 | Mostly the Angular frontend scaffolding, landing page, and unmodified templates |
+| Same path but modified | 24 | Dependency upgrades, configuration, some frontend services/models |
+| quickstart only (added) | 69 | The refactored new structure, new operational scripts, license files, etc. |
+| Lab6 only (replaced/removed) | 38 | The old flat server structure |
+
+By file count roughly 66% is identical, but the identical portion is
+concentrated in frontend boilerplate; **the backend (the core of the project)
+is almost entirely rewritten**.
+
+## 3. Major Changes and Reasons
+
+### 3.1 Backend Architecture: Monolithic Templates → Per-Service Split
+- **Change**: The flat service directories under the upstream `server`
+  (`ProductService/`, `OrderService/`, `TenantManagementService/`) and the two
+  large templates (`shared-template.yaml`, `tenant-template.yaml`) were
+  reorganized into:
+  - `server/services/{product-service, order-service, tenant-api}/` — each
+    service has its **own** `template.yaml` + `samconfig.toml` (split into
+    independently deployable micro-stacks);
+  - The Python code introduces a DAL layering: `*_service.py` +
+    `*_service_dal.py` + `*_models.py`.
+- **Reason**: Reduce coupling between services, support independent service
+  deployment, and improve template maintainability.
+- **Related commits**: `bcb1d1a` (restructure serverless SaaS architecture with
+  service separation), `0805565`, `753aa67`, `666dd8b`.
+
+### 3.2 Shared Resources Consolidated into `server/shared/`
+- **Change**: `layers/`, `nested_templates/`, `custom_resources/`, `Auth/`,
+  `tenant-management/`, etc., which were scattered across the server root, were
+  consolidated into
+  `server/shared/{auth, layers, nested_templates, custom_resources, tenant-management}/`.
+- **Reason**: Clearly distinguish "shared infrastructure" from "business
+  services", giving directories clearer responsibilities.
+- **Related commits**: `0805565` (move tenant-management from infrastructure to
+  shared), `753aa67` (restructure shared infrastructure directory layout),
+  `b632860` (reorganize auth components).
+
+### 3.3 Data Model: Remove `shardId` Sharding, Switch to `tenant_id` Partition Key
+- **Change**: The DynamoDB design for the Order / Product services was changed
+  from "`shardId` sharding + parallel queries" to a simplified design that uses
+  `tenant_id` as the partition key; the data models, CRUD, and frontend
+  templates were updated accordingly.
+- **Reason**: Eliminate the complex sharding/parallel-query logic, make the data
+  distribution more predictable, and reduce storage and query costs (see the
+  "Database Design Rules" section of the README for details).
+- **Related commits**: `37a2587` (use tenant_id instead of shardId), `40ea9ff`.
+
+### 3.4 Python Runtime Upgraded to 3.13
+- **Change**: The Lambda runtime and the CDK pipeline were unified and upgraded
+  from older versions to **Python 3.13**, and the CodeBuild build image was
+  changed to `STANDARD_7_0`.
+- **Reason**: The older runtime used upstream was near/at EOL; the upgrade
+  obtains long-term support and security updates.
+- **Related commits**: `7ea8533`.
+
+### 3.5 Dependency Fixes and Upgrades (incl. AWS Lambda Powertools)
+- **Change**: Fixed and upgraded outdated dependencies, with a focus on
+  correcting Powertools-related dependencies.
+- **Reason**: The upstream dependency versions were outdated and had
+  compatibility/security issues.
+- **Related commits**: `b632860` (fix powertools dependencies).
+
+### 3.6 Frontend: Angular and Amplify Adjustments
+- **Change**: An initial attempt at Angular 16.2.12 + AWS Amplify v6
+  (`51c412b`) was later **rolled back to Angular 14.x** due to compatibility
+  issues, with the authentication logic changed to the updated Amplify call
+  style (`184f5f9`).
+- **Reason**: Version compatibility and stability.
+- **Related commits**: `51c412b`, `184f5f9`, `40ea9ff`.
+
+### 3.7 Deployment and Operations Script Enhancements
+- **Change**:
+  - Each frontend `package.json` gained `deploy` / `reset` scripts (S3 sync +
+    CloudFront invalidation);
+  - A batch of new Node.js operational tooling scripts was added:
+    `create-admin-user.js`, `manage-users.js`, `set-admin-password.js`,
+    `get-login-info.js`, `generate-env-config.js`;
+  - Added the `scripts/DEPLOYMENT_GUIDE.md` deployment guide.
+- **Reason**: Simplify the deployment process and the day-to-day management of
+  tenant/admin users.
+- **Related commits**: `5366935` and the new files listed above.
+
+### 3.8 Other Configuration Adjustments
+- Tenant stack naming `pooled-tenant-stack` → `stack-pooled` (`8634f86`).
+- `LambdaReserveConcurrency` default value `20` → `0` (`2a262ad`), to avoid
+  deployment failures in environments where the account's reserved-concurrency
+  quota is constrained.
+
+## 4. Why We No Longer Contribute Back Upstream
+
+1. **Structural refactoring is hard to contribute back**: directory renames,
+   template splits, and data-model changes make the vast majority of changes
+   impossible to cleanly cherry-pick back upstream — the paths and structure no
+   longer line up, and a PR would turn into a large-scale "delete one chunk, add
+   another chunk", making review and merge costs extremely high.
+2. **Different positioning**: the upstream is a step-by-step teaching lab
+   sequence (Lab1–Lab7) that deliberately preserves a layer-by-layer evolving
+   structure; this project is a streamlined product aimed at deployment, and the
+   two have inconsistent goals.
+3. **Independent maintenance**: this project is therefore maintained as an
+   **independent derivative**, open-sourced under MIT-0; the upstream attribution
+   and provenance are preserved in `NOTICE`.
+
+> Note: only a small number of "narrow same-path changes" (such as deployment
+> script fixes and a few dependency upgrades) are technically still
+> contributable, but the overall benefit is limited, so this is not a current
+> goal.
+
+## 5. Structure Mapping (Old → New)
+
+| Upstream Lab6 path | quickstart path |
 |---|---|
 | `server/ProductService/` | `server/services/product-service/src/` |
 | `server/OrderService/` | `server/services/order-service/src/` |
-| `server/TenantManagementService/` | `server/shared/tenant-management/`、`server/services/tenant-api/` |
+| `server/TenantManagementService/` | `server/shared/tenant-management/`, `server/services/tenant-api/` |
 | `server/Auth/` | `server/shared/auth/` |
 | `server/layers/` | `server/shared/layers/` |
 | `server/nested_templates/` | `server/shared/nested_templates/` |
 | `server/custom_resources/` | `server/shared/custom_resources/` |
-| `server/shared-template.yaml` + `server/tenant-template.yaml` | 拆分为各服务 `services/*/template.yaml` + `server/shared/**` + `server/services/template.yaml` |
+| `server/shared-template.yaml` + `server/tenant-template.yaml` | split into per-service `services/*/template.yaml` + `server/shared/**` + `server/services/template.yaml` |
 
-> 上表为目录级对应关系，文件在迁移过程中可能伴随重命名与代码重构，仅供溯源参考。
+> The table above shows directory-level correspondences; files may have been
+> renamed and code refactored during migration, so it is for provenance
+> reference only.