@gadmin2n/schematics 0.0.118 → 0.0.120

package/dist/lib/application/files/gadmin2-game-angle-demo/age-sops-guides.md

@@ -0,0 +1,219 @@
+# Age + SOPS 使用指引（.env）
+
+## 目标
+
+使用 Age + SOPS 对 `.env` 加密，Git 中仅保存 `.env.enc`。
+
+## 安装
+
+``` bash
+brew install age sops
+```
+
+| 平台              | age                    | SOPS                     |
+| --------------- | ---------------------- | ------------------------ |
+| macOS           | `brew install age`     | `brew install sops`      |
+| Ubuntu / Debian | `sudo apt install age` | 下载官方 Release（二进制）        |
+| Rocky / CentOS  | `sudo dnf install age` | 下载官方 Release（二进制）        |
+| Alpine          | `apk add age`          | `apk add sops`           |
+| Docker          | `apt install age`      | 下载官方 Release（二进制）        |
+| GitHub Actions  | `apt install age`      | `getsops/sops-installer` |
+
+
+## 生成密钥（每人独立）
+
+每位团队成员在自己的机器上生成专属密钥：
+
+``` bash
+age-keygen -o key.txt
+mkdir -p ~/.config/sops/age
+mv key.txt ~/.config/sops/age/keys.txt
+```
+
+> 私钥只存在于本机，**绝不共享、绝不上传**。
+
+将自己的**公钥**（`# public key:` 那一行）告知团队（ 就是放入`.sops.yaml`，放在项目根目录）
+
+## 创建 `.sops.yaml`（多收件人）
+
+将所有团队成员的公钥列入，SOPS 加密时会同时为每个人加密，每人用自己的私钥均可解密：
+
+``` yaml
+creation_rules:
+  - path_regex: .*\.env$
+    age: >-
+      age1alice_PUBLIC_KEY,
+      age1bob_PUBLIC_KEY,
+      age1charlie_PUBLIC_KEY
+```
+
+> `.sops.yaml` **提交进 Git**，公钥可以公开。
+
+### 人员变更
+
+**新人加入：** 将其公钥追加到 `.sops.yaml`，然后执行：
+``` bash
+sops updatekeys .env.enc
+```
+
+**人员离职：** 从 `.sops.yaml` 删除其公钥，同样执行 `sops updatekeys .env.enc`。其旧私钥立即失去解密能力，无需重新分发任何密钥。
+
+## 首次加密
+
+``` bash
+vi .env
+sops encrypt .env > .env.enc
+```
+
+## 修改
+
+``` bash
+sops .env.enc
+```
+> 会自动用vi/vim打开，编辑完自动加密，不需要手工：`decrypt -> edit -> encrypt`
+
+## 本地运行
+
+### 方法一：生成临时 .env
+
+``` bash
+sops -d .env.enc > .env
+node server.js
+```
+
+> 需要严格禁止Coding agent访问 `.env` 文件
+
+### 方法二：导入环境变量
+
+``` bash
+set -a
+source <(sops -d .env.enc)
+set +a
+node server.js
+```
+
+应用继续使用：
+
+``` js
+process.env.XXX
+```
+
+## 准备部署专用密钥
+
+部署环境使用独立的 deploy key，**不使用任何个人私钥**，避免人员变更影响部署。
+
+``` bash
+# 生成 deploy key（在本地安全环境执行）
+age-keygen -o deploy-key.txt
+```
+
+将 deploy key 的公钥加入 `.sops.yaml`，然后重新加密：
+
+``` bash
+sops updatekeys .env.enc
+```
+
+> `deploy-key.txt` 私钥只上传到部署平台的 Secrets，不提交 Git，本地用完可删除。
+
+## 部署（VM / Linux）
+
+将 deploy 私钥放置：
+
+``` text
+/etc/sops/key.txt
+```
+
+设置权限：
+
+``` bash
+chmod 600 /etc/sops/key.txt
+export SOPS_AGE_KEY_FILE=/etc/sops/key.txt
+```
+
+启动：
+
+``` bash
+sops -d .env.enc > .env
+exec node server.js
+```
+
+## Kubernetes 部署
+
+### 创建 Secret
+
+``` bash
+kubectl create secret generic sops-age-key \
+  --from-file=key.txt=deploy-key.txt
+```
+
+### Deployment
+
+将 Secret 以 volume 挂载，通过 entrypoint 脚本启动：
+
+``` sh
+#!/bin/sh
+set -e
+
+export SOPS_AGE_KEY_FILE=/etc/sops/key.txt
+sops -d /app/.env.enc > /app/.env
+
+exec node server.js
+```
+
+Dockerfile：
+
+``` dockerfile
+ENTRYPOINT ["/app/entrypoint.sh"]
+```
+
+相关 Deployment yaml 片段：
+
+``` yaml
+volumes:
+  - name: sops-age-key
+    secret:
+      secretName: sops-age-key
+containers:
+  - name: app
+    volumeMounts:
+      - name: sops-age-key
+        mountPath: /etc/sops
+        readOnly: true
+```
+
+## GitHub Actions 部署
+
+将 deploy 私钥内容存入 GitHub Secrets（如 `SOPS_AGE_KEY`），在 workflow 中使用：
+
+``` yaml
+- name: Decrypt .env
+  run: |
+    echo "${{ secrets.SOPS_AGE_KEY }}" > /tmp/age-key.txt
+    export SOPS_AGE_KEY_FILE=/tmp/age-key.txt
+    sops -d .env.enc > .env
+```
+
+## Git 建议
+
+提交：
+
+-   `.env.enc`
+-   `.sops.yaml`
+
+不要提交：
+
+-   `.env`
+-   `keys.txt`
+
+`.gitignore`
+
+``` gitignore
+.env
+```
+
+## 最佳实践
+
+-   一个环境一个 `.env.enc`
+-   私钥绝不进入 Git
+-   业务代码始终通过 `process.env` 读取配置
+-   部署时解密，运行结束后如无需要可删除 `.env`

package/dist/lib/application/files/gadmin2-game-angle-demo/gitignore

@@ -16,6 +16,7 @@ yarn-debug.log*
 yarn-error.log*
 lerna-debug.log*
 .env.local
+keys.txt
 
 # OS
 .DS_Store
@@ -47,7 +48,8 @@ settings.local.json
 
 .agent/
 .claude-internal/
-.claude
+.claude/
+.codebuddy/
 docs/
 .frontend-slides/
 .agent

package/dist/lib/application/files/gadmin2-game-angle-demo/web/package.json

@@ -10,7 +10,7 @@
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^7.0.2",
     "@dnd-kit/utilities": "^3.2.2",
-    "@gadmin2n/charts": "^0.0.8",
+    "@gadmin2n/charts": "0.0.10",
     "@gadmin2n/react-common": "^0.0.70",
     "@monaco-editor/react": "^4.7.0",
     "@refinedev/antd": "^5.47.0",

package/dist/lib/application/files/gadmin2-game-angle-demo/web/src/hooks/useUserPageAccess.ts

@@ -82,23 +82,27 @@ function writeCache(key: string, value: unknown): void {
   }
 }
 
+// In dev mode, skip sessionStorage cache so menu changes after seed are
+// visible immediately without clearing browser storage manually.
+const IS_DEV = import.meta.env.DEV;
+
 export const useUserPageAccess = (): UseUserPageAccessResult => {
   const [isIdentityLoading, setIsIdentityLoading] = useState(true);
 
   // Role names — initialise from cache so first render is non-empty
-  const [roleNames, setRoleNames] = useState<string[]>(
-    () => readCache<string[]>(RoleCacheKey) ?? [],
+  const [roleNames, setRoleNames] = useState<string[]>(() =>
+    IS_DEV ? [] : (readCache<string[]>(RoleCacheKey) ?? []),
   );
 
   // Data states — initialise from cache for instant first render
   const [rolesData, setRolesData] = useState<Role[] | null>(() =>
-    readCache<Role[]>(RolesDataCacheKey),
+    IS_DEV ? null : readCache<Role[]>(RolesDataCacheKey),
   );
   const [rolePagesData, setRolePagesData] = useState<RolePage[] | null>(() =>
-    readCache<RolePage[]>(RolePagesCacheKey),
+    IS_DEV ? null : readCache<RolePage[]>(RolePagesCacheKey),
   );
   const [pagesData, setPagesData] = useState<Page[] | null>(() =>
-    readCache<Page[]>(PagesCacheKey),
+    IS_DEV ? null : readCache<Page[]>(PagesCacheKey),
   );
 
   // Track previous roles to detect changes
@@ -312,7 +316,8 @@ export const useUserPageAccess = (): UseUserPageAccessResult => {
   // Calculate loading state
   // If we have cached data, isLoading is false even while background-refreshing
   const hasCache = useMemo(
-    () => !!(readCache(PagesCacheKey) && readCache(RolePagesCacheKey)),
+    () =>
+      !IS_DEV && !!(readCache(PagesCacheKey) && readCache(RolePagesCacheKey)),
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [],
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gadmin2n/schematics",
-  "version": "0.0.118",
+  "version": "0.0.120",
   "description": "Gadmin - modern, fast, powerful node.js web framework (@schematics)",
   "main": "dist/index.js",
   "files": [