@wdyy/skills 0.1.18 → 0.1.19

package/.well-known/skills/index.json

@@ -13,7 +13,7 @@
     {
       "name": "wdyy-api-standard",
       "description": "根据“获取XX数据”“使用XX接口”“使用指定查询名称”等具体需求，定位已登记的接口 reference；对于 HIS SQL 查询，从远程查询目录按 name 精确匹配，并按已确认的接口契约将调用方式写入程序。Use when 需要查询或实现一个已登记接口或 HIS SQL 查询的数据调用时。",
-      "files": ["SKILL.md", "agents/openai.yaml", "reference/api-demo.md", "reference/api-his-sql.md", "reference/api-sms.md"]
+      "files": ["SKILL.md", "agents/openai.yaml", "reference/api-demo.md", "reference/api-his-sql.md", "reference/api-sms.md", "reference/api-sso.md", "scripts/ensure-sso-env-example.mjs", "scripts/ensure-sso-env-example.test.mjs"]
     },
     {
       "name": "wdyy-bug-record",

package/.well-known/skills/wdyy-api-standard/SKILL.md

@@ -20,9 +20,10 @@ disable-model-invocation: true
 
 1. 根据需求中的数据名称、业务对象或接口名称，在 `reference/api-*.md` 中查找候选业务接口，排除仅用于说明格式的 `api-demo.md`。
 2. 若需求为“使用 `<查询名称>`”且未直接匹配接口名称，则读取 `reference/api-his-sql.md`，按其中的远程目录和查询名称匹配规则处理。
-3. 仅在唯一匹配时读取对应 reference，使用其中的接口 URL、JSON 入参和 JSON 返回值编写调用方式。
-4. 按 reference 的“备注”实现特殊调用要求。
-5. 若没有匹配接口、存在多个候选接口，或 URL、入参、返回值不完整，先要求补充或确认接口信息；不得编造调用细节。
+3. 仅在唯一匹配时读取对应 reference。匹配 `api-sso` 时，在写入调用代码前运行 `node <Skill目录>/scripts/ensure-sso-env-example.mjs --target <目标项目根目录>`：目标 `.env.example` 缺失、`SSO_BASE_URL` 重复或已有不同值时，明确报告错误并等待工程师处理；工程师确认替换唯一的不同值后，才使用 `--replace-existing` 重试。不得创建或修改 `.env`。
+4. 使用对应 reference 的接口 URL、JSON 入参和 JSON 返回值编写调用方式。
+5. 按 reference 的“备注”实现特殊调用要求。
+6. 若没有匹配接口、存在多个候选接口，或 URL、入参、返回值不完整，先要求补充或确认接口信息；不得编造调用细节。
 
 ## 接口文档约定
 

package/.well-known/skills/wdyy-api-standard/reference/api-sso.md

@@ -0,0 +1,87 @@
+# 接口名称：api-sso
+
+# 接口用途：接入统一认证中心，完成外部系统登录、Token 状态校验和登录态用户修改密码
+
+# 接口URL：
+
+默认认证中心基础地址为 `http://172.26.1.80:9002`。使用本接口前，先运行 `node <Skill目录>/scripts/ensure-sso-env-example.mjs --target <目标项目根目录>`，把 `SSO_BASE_URL=http://172.26.1.80:9002` 写入目标项目已有的 `.env.example`。部署环境地址如有差异，以认证中心提供的实际地址为准；不得在代码中硬编码认证中心地址、端口或 JWT 签名密钥。接口路径如下：
+
+| 用途 | 方法 | 路径 |
+|---|---|---|
+| 外部系统登录 | `POST` | `/api/v1/auth/login` |
+| Token 验签 | `POST` | `/api/v1/auth/verify` |
+| 修改密码 | `POST` | `/api/v1/auth/change-password` |
+
+三者均使用 `application/json; charset=utf-8`。登录无需 Token；验签和改密请求使用 `Authorization: Bearer <JWT_TOKEN>` 传入登录成功后取得的 Token。
+
+# 入参格式：JSON
+
+登录请求：
+
+```json
+{
+  "employee_id": "<EMPLOYEE_ID>",
+  "password": "<PASSWORD>",
+  "sys_id": "<SYSTEM_ID>"
+}
+```
+
+- `employee_id` 与 `username` 二选一，均按用户工号处理。
+- `password`、`sys_id` 必填；`sys_id` 为已启用接入系统的 ID，可为 number 或 string。
+
+验签请求可使用空 JSON 请求体，并在请求头携带 Bearer Token。修改密码请求：
+
+```json
+{
+  "old_password": "<OLD_PASSWORD>",
+  "new_password": "<NEW_PASSWORD>"
+}
+```
+
+- 改密仍须在请求头携带 Bearer Token。
+- `new_password` 长度必须为 6 至 100 个字符。
+
+# 返回值：JSON
+
+外部系统登录成功时，响应结构为：
+
+```json
+{
+  "code": 200,
+  "message": "<DISPLAY_MESSAGE>",
+  "data": {
+    "allowed": true,
+    "user_id": "<USER_ID>",
+    "employee_id": "<EMPLOYEE_ID>",
+    "name": "<USER_NAME>",
+    "token": "<JWT_TOKEN>",
+    "permissions": [
+      {
+        "dept_id": "<DEPARTMENT_ID>",
+        "dept_name": "<DEPARTMENT_NAME>",
+        "roles": [
+          {
+            "role_id": "<ROLE_ID>",
+            "role_name": "<ROLE_NAME>",
+            "description": "<ROLE_DESCRIPTION>"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+验签成功时 `data` 含 `valid`、`allowed`、`user_id`、`employee_id`、`name` 和 `sys_id`。改密成功时 `data` 含 `user_id`、`employee_id` 和 `name`。
+
+所有接口使用 `{ code, message, data }` 结构。HTTP 状态码及 `code` 的含义：`200` 成功、`400` 参数错误、`401` 认证失败或 Token 无效/过期、`403` 无目标系统权限或权限已失效、`404` 接入系统不存在或已停用、`500` 服务端异常。
+
+# 备注：
+
+- 不得依赖 `message` 的精确文案；登录和验签根据 HTTP 状态码、`code`、`data.valid`、`data.allowed` 判断结果。
+- 登录成功后仅在需要的安全存储中保存 Token；日志、异常上报和前端状态中不得明文记录密码、Token、JWT 签名密钥或连接信息。
+- 仅当登录响应 `data.allowed` 为 `true` 才进入目标系统；根据 `permissions` 内按科室聚合的角色控制业务入口。
+- 服务端需要确认登录态或权限是否仍有效时调用验签接口。验签返回 `valid: false` 或 `allowed: false` 时，清除本地登录态并要求重新登录或联系管理员。
+- 用户改密成功后，清除旧 Token 并提示用户使用新密码重新登录。
+- 不得用管理端 `/api/auth/*` 接口替代本 reference 中的外部系统 `/api/v1/auth/*` 接口。
+- `.env.example` 缺失时明确报错，不得创建该文件或修改 `.env`。已有相同 `SSO_BASE_URL` 时不重复写入；已有不同值时保留原值并等待工程师确认。工程师确认替换唯一的不同值后，才使用 `--replace-existing`；重复定义时始终报错。

package/.well-known/skills/wdyy-api-standard/scripts/ensure-sso-env-example.mjs

@@ -0,0 +1,76 @@
+import { access, readFile, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { resolve } from 'node:path';
+
+const DEFAULT_SSO_BASE_URL = 'http://172.26.1.80:9002';
+
+function usage() {
+  throw new Error('Usage: node ensure-sso-env-example.mjs --target <project-root> [--replace-existing]');
+}
+
+function parseArguments(argumentsList) {
+  let target;
+  let replaceExisting = false;
+
+  for (let index = 0; index < argumentsList.length; index += 1) {
+    const argument = argumentsList[index];
+    if (argument === '--target') {
+      if (target || index + 1 >= argumentsList.length) usage();
+      target = argumentsList[index + 1];
+      index += 1;
+    } else if (argument === '--replace-existing') {
+      if (replaceExisting) usage();
+      replaceExisting = true;
+    } else {
+      usage();
+    }
+  }
+
+  if (!target) usage();
+  return { target: resolve(target), replaceExisting };
+}
+
+function findSsoBaseUrlLines(content) {
+  return content.split(/(?<=\n)/).flatMap((line, index) => {
+    const match = line.match(/^SSO_BASE_URL=([^\r\n]*)(\r?\n)?$/);
+    return match ? [{ index, value: match[1], line, newline: match[2] ?? '' }] : [];
+  });
+}
+
+async function main() {
+  const { target, replaceExisting } = parseArguments(process.argv.slice(2));
+  const examplePath = resolve(target, '.env.example');
+
+  try {
+    await access(examplePath, constants.F_OK);
+  } catch {
+    throw new Error(`Missing required configuration file: ${examplePath}`);
+  }
+
+  const content = await readFile(examplePath, 'utf8');
+  const entries = findSsoBaseUrlLines(content);
+  if (entries.length > 1) throw new Error('Duplicate SSO_BASE_URL definitions in .env.example');
+
+  if (entries.length === 0) {
+    const separator = content.length === 0 || content.endsWith('\n') ? '' : '\n';
+    await writeFile(examplePath, `${content}${separator}SSO_BASE_URL=${DEFAULT_SSO_BASE_URL}\n`);
+    process.stdout.write(`Added SSO_BASE_URL to ${examplePath}\n`);
+    return;
+  }
+
+  const [entry] = entries;
+  if (entry.value === DEFAULT_SSO_BASE_URL) {
+    process.stdout.write(`SSO_BASE_URL is already configured in ${examplePath}\n`);
+    return;
+  }
+
+  if (!replaceExisting) {
+    throw new Error('SSO_BASE_URL already has a different value; retain it and obtain engineer confirmation before using --replace-existing');
+  }
+
+  const replacement = `SSO_BASE_URL=${DEFAULT_SSO_BASE_URL}${entry.newline}`;
+  await writeFile(examplePath, content.replace(entry.line, replacement));
+  process.stdout.write(`Replaced SSO_BASE_URL in ${examplePath}\n`);
+}
+
+await main();

package/.well-known/skills/wdyy-api-standard/scripts/ensure-sso-env-example.test.mjs

@@ -0,0 +1,66 @@
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+const script = join(dirname(fileURLToPath(import.meta.url)), 'ensure-sso-env-example.mjs');
+const defaultValue = 'SSO_BASE_URL=http://172.26.1.80:9002';
+const created = [];
+
+async function fixture(content) {
+  const root = await mkdtemp(join(tmpdir(), 'wdyy-api-sso-'));
+  created.push(root);
+  if (content !== undefined) await writeFile(join(root, '.env.example'), content);
+  return root;
+}
+
+async function invoke(root, ...argumentsList) {
+  return run(process.execPath, [script, '--target', root, ...argumentsList]);
+}
+
+test.after(async () => {
+  await Promise.all(created.map((path) => rm(path, { recursive: true, force: true })));
+});
+
+test('缺少 .env.example 时明确失败且不创建文件', async () => {
+  const root = await fixture();
+  await assert.rejects(invoke(root), /Missing required configuration file/);
+  await assert.rejects(readFile(join(root, '.env.example')));
+});
+
+test('追加默认 SSO 地址且保持 .env.example 其他内容', async () => {
+  const root = await fixture('API_URL=/api\n');
+  await invoke(root);
+  assert.equal(await readFile(join(root, '.env.example'), 'utf8'), `API_URL=/api\n${defaultValue}\n`);
+});
+
+test('已存在默认 SSO 地址时不重复写入', async () => {
+  const root = await fixture(`${defaultValue}\n`);
+  await invoke(root);
+  assert.equal(await readFile(join(root, '.env.example'), 'utf8'), `${defaultValue}\n`);
+});
+
+test('不同 SSO 地址默认保留且明确失败', async () => {
+  const root = await fixture('SSO_BASE_URL=http://sso.internal:9002\n');
+  const before = await readFile(join(root, '.env.example'));
+  await assert.rejects(invoke(root), /different value/);
+  assert.deepEqual(await readFile(join(root, '.env.example')), before);
+});
+
+test('重复 SSO 地址明确失败且不修改文件', async () => {
+  const root = await fixture(`${defaultValue}\nSSO_BASE_URL=http://sso.internal:9002\n`);
+  const before = await readFile(join(root, '.env.example'));
+  await assert.rejects(invoke(root), /Duplicate SSO_BASE_URL definitions/);
+  assert.deepEqual(await readFile(join(root, '.env.example')), before);
+});
+
+test('明确替换后更新唯一的不同 SSO 地址', async () => {
+  const root = await fixture('SSO_BASE_URL=http://sso.internal:9002\n');
+  await invoke(root, '--replace-existing');
+  assert.equal(await readFile(join(root, '.env.example'), 'utf8'), `${defaultValue}\n`);
+});

package/lib/wdyy-cli.js

@@ -43,19 +43,19 @@ BACKEND_URL=0.0.0.0
 BACKEND_PORT=3000
 
 # 数据库
-DB_URL=
+DB_URL=localhost
 DB_PORT=5432
-DB_USER=
+DB_USER=lhy
 DB_PASSWORD=
-DB_NAME=
-DB_SCHEMA=
+DB_NAME=hospital
+DB_SCHEMA=api_platform
 
 # API
 
 # 部署
 `;
 
-const defaultProjectLayout = [...defaultProjectDirectories, '.env', '.env.example'];
+const defaultProjectLayout = [...defaultProjectDirectories, '.env.example'];
 
 const generatedAgentsContent = `# 企业开发规则
 
@@ -72,6 +72,8 @@ const generatedAgentsContent = `# 企业开发规则
 
 所有 URL、端口和 IP 地址必须从项目根目录的 \`.env\` 文件读取，禁止在代码中硬编码；不得提交秘密或生产环境 \`.env\`。
 
+\`.env.example\` 是配置模板。需要本地配置时，必须先手工复制 \`.env.example\` 为 \`.env\`；后续修改配置文件时，必须先修改 \`.env.example\`，再同步修改 \`.env\`。不得将真实密码、密钥或生产配置写入 \`.env.example\`。
+
 项目开发完成后必须创建 \`README.md\`，内容包括项目技术栈、目录结构和安装部署说明。
 
 ## Skill 路由
@@ -181,18 +183,16 @@ async function createDefaultProjectLayout(targetRoot, writtenPaths) {
     if (!existed) writtenPaths.push(destination);
   }
 
-  for (const environmentFile of ['.env', '.env.example']) {
-    const environmentPath = join(targetRoot, environmentFile);
-    try {
-      await access(environmentPath);
-    } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
-      await writeFile(environmentPath, defaultEnvironmentContent, {
-        encoding: 'utf8',
-        mode: environmentFile === '.env' ? 0o600 : 0o644
-      });
-      writtenPaths.push(environmentPath);
-    }
+  const environmentExamplePath = join(targetRoot, '.env.example');
+  try {
+    await access(environmentExamplePath);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    await writeFile(environmentExamplePath, defaultEnvironmentContent, {
+      encoding: 'utf8',
+      mode: 0o644
+    });
+    writtenPaths.push(environmentExamplePath);
   }
   console.log(`已准备默认项目目录: ${defaultProjectDirectories.join('、')}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wdyy/skills",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "企业内部开发 Skill 与项目初始化命令",
   "type": "module",
   "bin": {