wangsli/hyb-oa
1
0
派生 0
代码 工单 合并请求 工作流 5 软件包 项目 发布 百科 活动

增加 PC 企业微信扫码登录（07-30-pc-wecom-qr-login）
ci-e2e / e2e (push) Canceled after 0s
详情
ci-minimal / check-minimal (push) Canceled after 0s
详情

浏览代码
这个提交包含在：
wangsli
2026-07-30 17:16:22 +08:00
父节点 45dc206a4c
当前提交 fb164eb690
共修改 21 个文件，包含 959 行新增和 22 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
.trellis/tasks/07-30-pc-wecom-qr-login/check.jsonl
+1
查看文件
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
.trellis/tasks/07-30-pc-wecom-qr-login/design.md
+143
查看文件
@@ -0,0 +1,143 @@
# PC 企业微信扫码登录设计
## 1. Design Goal
在普通 PC 浏览器提供企业微信托管 Web 登录入口，同时复用现有身份映射、会话签发和回调错误处理。首版不向 OA 登录页注入企微脚本，不改变工作台免登、绑定或 onboard 流程。
官方依据：
- 企业微信《开始开发》：新版 Web 登录支持移动端企微扫码和企微桌面端快速登录，并要求自建应用开启“企业微信授权登录”。
- <https://developer.work.weixin.qq.com/document/path/98151>
- 企业微信《Web登录组件》：托管页链接为 `https://login.work.weixin.qq.com/wwlogin/sso/login`，自建应用使用 `login_type=CorpApp`、CorpID、AgentID、URL 编码后的回调地址和 state。
- <https://developer.work.weixin.qq.com/document/path/98152>
- 企业微信《获取用户登录身份》：Web 登录 code 继续由 `/cgi-bin/auth/getuserinfo` 消费，code 一次有效且 5 分钟过期。
- <https://developer.work.weixin.qq.com/document/path/98176>
## 2. Current Architecture
```text
企微工作台 WebView
-> /api/auth/wecom/login
-> open.weixin.qq.com/connect/oauth2/authorize
-> /api/auth/wecom/callback
-> auth/getuserinfo
-> userid 映射/自动映射
-> OA session + 审计 + returnTo
```
现有 `mode` 只表达 `login / bind / onboard`。回调会把未知 mode 收敛为 `login`，因此不能用 `mode=qr` 承担入口区分。
## 3. Target Architecture
```text
普通 PC 浏览器
-> 登录页“企业微信扫码登录”
-> /api/auth/wecom/login?entrySource=pc_qr
-> 写入短期浏览器关联 cookie
-> login.work.weixin.qq.com/wwlogin/sso/login
-> /api/auth/wecom/callback?code=...&state=...
-> 校验签名 state + 过期时间 + entrySource + cookie nonce
-> 清除关联 cookie
-> 复用 auth/getuserinfo、userid 映射、session 与安全回跳
企微工作台 WebView
-> 保持现有入口和授权 URL
-> callback 缺少旧版 entrySource 时兼容解释为 wecom_workbench
```
## 4. Contracts
### 4.1 Entry configuration
`GET /api/auth/wecom/config` 在现有返回中增加：
- `pcWebLoginEnabled: boolean`
- `pcLoginUrl: string | null`
新增非敏感生产开关 `WECOM_PC_WEB_LOGIN_ENABLED`，默认关闭。只有现有企微 OAuth 配置完整且该开关打开时返回 PC 登录 URL。该开关允许独立回滚扫码入口，不影响工作台免登。
现有 `loginUrl` 继续只代表工作台入口，避免客户端误把两种企微授权地址混用。
### 4.2 Entry source
- 请求白名单：`wecom_workbench | pc_qr`。
- `/wecom/login` 未传值时默认为 `wecom_workbench`，保持既有调用兼容。
- state 中写入白名单化 `entrySource`。
- 回调兼容部署前已经发出的 state：缺少 `entrySource` 时按 `wecom_workbench` 处理；存在未知值时失败关闭，不静默降级。
- `mode` 不增加新值，绑定与 onboard 不允许使用 `pc_qr`。
### 4.3 Hosted Web login URL
仅服务端构造：
```text
https://login.work.weixin.qq.com/wwlogin/sso/login
?login_type=CorpApp
&appid=<CorpID>
&agentid=<AgentID>
&redirect_uri=<encoded callback>
&state=<encoded signed state>
```
CorpID、AgentID 和回调地址复用现有配置；Secret 不进入 URL 或前端。
### 4.4 Browser correlation and replay boundary
现有 state 是 `base64url(payload).HMAC-SHA256`，具备完整性和过期校验，但 nonce 没有消费状态。PC 扫码增加浏览器关联 cookie：
- HttpOnly、Secure（生产）、SameSite=Lax。
- path 限制为 `/api/auth/wecom`。
- 生命周期不长于 state 的 10 分钟。
- cookie 保存服务端签名的 nonce/入口上下文，或保存与 state nonce 可恒定时间比较的不可伪造值。
- callback 在调用企微 token/code 接口前校验；缺失、篡改或不匹配时失败关闭。
- 无论回调成功还是已进入终止性失败，都清除关联 cookie；正常浏览器第二次回调因 cookie 已清除而在 OA 侧先失败。
- 关联 cookie 是浏览器相关性/CSRF 控制，不是服务端一次性 nonce 存储。恶意客户端若同时保存并重放 URL 与旧 cookie，最终单次消费边界由企微 code 的“一次有效、5 分钟过期”合同保证；OA 不创建第二个会话。
工作台既有入口不强制增加该 cookie，避免扩大本任务兼容风险。若实施测试证明企微 WebView 可无差别支持，仍不顺手改变其合同。
### 4.5 Audit and privacy
成功登录继续使用 `AUTH_WECOM_LOGIN_SUCCESS`，extra 增加：
- `bindingSource`
- `entrySource`
日志和审计不得记录 code、state、nonce、cookie、Secret、完整 userid 或企微原始响应。失败日志仅记录固定错误类别、request id、mode 和 entrySource。
### 4.6 Frontend behavior
- 普通浏览器在“企业入口”区域展示“企业微信扫码登录”按钮。
- 点击按钮沿用当前安全 `returnTo` 与设备指纹拼接工具，跳转服务端 `pcLoginUrl`。
- 企业微信 WebView 不展示该按钮，继续显示“一键进入”。
- PC 入口不可用时不展示失效按钮；密码和邮箱验证码始终不受影响。
- 不加载第三方 SDK、script 或 iframe。
## 5. Error Matrix
| Condition | Behavior |
| --- | --- |
| PC 开关关闭或基础配置缺失 | `pcLoginUrl=null`，登录页保留既有方式 |
| 非法 `entrySource` | 400 或认证失败关闭，不重定向企微 |
| `pc_qr` 搭配 bind/onboard | 参数校验失败，不进入外部授权 |
| state 篡改/过期 | 401，不兑换 code |
| PC 关联 cookie 缺失/篡改/nonce 不匹配 | 401，不兑换 code |
| 正常浏览器重复回调 | cookie 已清除，OA 关联校验失败 |
| 恶意客户端重放 URL 与旧 cookie | 企微拒绝重复 code；OA 不创建第二个会话 |
| returnTo 外域或协议相对 URL | 回落安全默认页 |
| 未映射/冲突/停用 | 复用现有结构化提示并失败关闭 |
| 企微托管页/CDN 不可达 | OA 登录页不受影响，用户返回后可用密码/邮箱验证码 |
## 6. Compatibility and Rollout
- 无数据库迁移。
- 缺少 `entrySource` 的短期旧 state 仍可完成工作台回调。
- 先在企微管理后台人工只读核对授权登录与可信域名，再部署代码。
- 部署后先保持 PC 开关关闭完成既有登录回归；经生产配置批准后开启并做一名已绑定 active 员工的真实扫码验收。
- 回滚优先关闭 `WECOM_PC_WEB_LOGIN_ENABLED`；必要时回滚应用版本。两种方式都不影响已有登录入口。
## 7. Explicit Non-Decisions
- 不引入 `@wecom/jssdk`。
- 不在本任务开启 CSP；托管页方案避免新增登录页第三方脚本，但不把既有 `contentSecurityPolicy: false` 宣称为已治理。
- 不新增 nonce 数据表、Redis 或通用 OAuth 状态服务。
- 不把 PC 扫码用于 bind/onboard。
.trellis/tasks/07-30-pc-wecom-qr-login/implement.jsonl
+1
查看文件
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
.trellis/tasks/07-30-pc-wecom-qr-login/implement.md
+98
查看文件
@@ -0,0 +1,98 @@
# PC 企业微信扫码登录实施计划
## 1. Preconditions
- [ ] 只读核对企微自建应用已开启“企业微信授权登录”。
- [ ] 只读核对 OA 公网域名已配置为 OAuth 可信域名或 Web 网页授权回调域名，且回调地址仍指向现有 `/api/auth/wecom/callback`。
- [x] 不在代码、日志、Trellis 或聊天中输出 CorpID、AgentID、Secret、真实 userid、code 或 state。
- [x] 用户批准本 PRD、设计和实施计划后，才运行 `task.py start` 并修改产品代码。
## 2. Backend Implementation
- [x] 在配置层增加默认关闭的 `WECOM_PC_WEB_LOGIN_ENABLED`，同步示例环境、部署检查和运行时 readiness 合同。
- [x] 扩展企微公开配置响应，分别返回工作台 `loginUrl` 与 PC `pcLoginUrl`，避免语义混用。
- [x] 在 `/wecom/login` 增加固定白名单 `entrySource`，拒绝 `pc_qr + bind/onboard`。
- [x] 增加企微托管 Web 登录 URL 构造函数，复用现有 CorpID、AgentID 和回调地址。
- [x] 为 `pc_qr` 写入短期 HttpOnly/SameSite=Lax 浏览器关联 cookie，并把白名单入口与 nonce 写入签名 state。
- [x] callback 在外部兑换前验证 state、entrySource、时效和 cookie nonce，并在终止路径清除 cookie；不把无状态 cookie 误报为服务端一次性 nonce 存储。
- [x] 成功审计增加脱敏 `entrySource`，保持既有 `bindingSource`、映射和会话合同。
## 3. Frontend Implementation
- [x] 扩展企微配置类型并在普通浏览器登录页展示“企业微信扫码登录”按钮。
- [x] 复用既有 returnTo 和设备指纹 URL 工具跳转服务端入口。
- [x] 企微 WebView 继续展示工作台一键进入；PC 开关关闭或配置缺失时保持密码/邮箱验证码入口可用。
- [x] 不安装、不加载 `@wecom/jssdk`，不加入第三方 script/iframe。
## 4. Automated Validation
### Backend focused tests
- [x] 配置 ready/disabled/misconfigured 与 `pcLoginUrl` 合同。
- [x] 托管页 URL 的 host/path、`CorpApp`、CorpID、AgentID、回调和签名 state。
- [x] `entrySource` 默认、白名单和非法组合。
- [x] state 篡改、过期、缺 code、非法 returnTo。
- [x] cookie 缺失、篡改、nonce 不匹配、回调后清除、正常浏览器重复回调，以及企微重复 code 不创建第二会话。
- [x] 成功、未映射、冲突、OA/企微停用以及审计脱敏。
- [x] 工作台、bind、onboard 回归。
建议命令：
```bash
cd server && npm test -- tests/unit/routes/wecomAuth.test.js tests/unit/routes/auth.login.test.js
cd server && npm run prisma:validate
```
### Frontend focused tests
- [x] 普通浏览器显示 PC 企微按钮并构造安全跳转。
- [x] 企微 WebView 不重复显示 PC 入口。
- [x] 配置关闭/失败时既有登录方式仍可用。
- [x] 既有错误提示不再要求用户先用密码绑定。
建议命令：
```bash
cd client && npm run typecheck
cd client && npm run build
```
### Project gates
```bash
node scripts/qa/check-process-contract.mjs --baseline --json
node scripts/qa/audit-docs.mjs --check-registry
node scripts/qa/check-trellis-governance.mjs
python3 ./.trellis/scripts/task.py validate 07-30-pc-wecom-qr-login
git diff --check
```
## 5. Review and Documentation
- [x] 认证改动完成后做只读安全/权限 review，不由 reviewer 修改代码。
- [x] 若实现形成稳定合同，更新 `.trellis/spec/hyb-oa/wecom-boundary.md`。
- [x] 仅在确有操作差异时更新现有管理员手册、部署 checklist/runbook；不新建平行文档。
- [ ] commit 使用中文并引用 `07-30-pc-wecom-qr-login`。
## 6. Production Gate
- [ ] 企微后台设置、生产环境配置、部署与真实扫码分别取得明确批准。
- [ ] 部署后公网 `/ready`、前端构建标识、现有工作台登录及既有密码/邮箱验证码冒烟通过。
- [ ] 开启 PC 开关后，由一名已映射 active 员工完成真实 PC 扫码或企微桌面端快速登录，并安全回跳原页面。
- [ ] 确认审计有 `entrySource=pc_qr` 且无敏感字段。
- [ ] 验证关闭 PC 开关后按钮消失、其他登录方式不受影响。
## 7. Interrupt and Rollback
- 真人报销链若出现阻断问题，本任务保持小步提交并可随时中断，优先处理真实业务阻断。
- 生产首选回滚：关闭 `WECOM_PC_WEB_LOGIN_ENABLED` 并重建/重启受控服务。
- 若后端回归异常，回滚本任务应用版本；不得删除既有企微绑定或会话数据。
## 8. Local Evidence (2026-07-30)
- 聚焦后端：`wecomAuth.test.js` 与 `check-wecom-runtime-ready.test.js` 共 37 项通过；补充重放断言后 `wecomAuth.test.js` 26 项通过。
- 完整后端：169 个测试文件、1091 项通过。
- Prisma schema validate 通过。
- 前端 typecheck、生产 build 通过；`wecom-entry.spec.ts` 2 项通过。
- 流程合同、文档审计（仅 22 个既有未注册文档 warning）、Trellis governance、task validate、敏感内容扫描和 `git diff --check` 通过。
- 未执行企微后台写入、生产环境配置、部署或真实扫码；对应 Production Gate 保持未勾选。
.trellis/tasks/07-30-pc-wecom-qr-login/prd.md
+87
查看文件
@@ -0,0 +1,87 @@
# PC 企业微信扫码登录
## Goal
让已经完成 OA 与企业微信 userid 映射的员工，在普通 PC 浏览器访问 OA 登录页时，可以使用企业微信完成扫码或桌面端快速登录，不必输入 OA 密码或邮箱验证码；同时保留现有企业微信工作台免登链路。
## Scope
- 普通 PC 浏览器登录页的企微托管 Web 登录入口。
- 服务端企微 Web 登录 URL、入口来源、短期浏览器关联 cookie、共享 callback 和登录审计。
- 默认关闭的独立生产开关、配置/readiness 合同、回滚和真实扫码验收。
- 现有工作台免登、绑定、onboard、密码和邮箱验证码登录的回归保护。
## Background and Confirmed Facts
- 当前普通浏览器登录页只提供账号密码和企业邮箱验证码；企业微信入口文案要求用户从企微工作台打开 OA。
- 当前后端已具备 `code -> userid -> OA 绑定/唯一自动映射 -> 会话签发` 全链路，并已覆盖未映射、映射冲突、账号停用和成功登录。
- 当前移动/工作台入口使用企业微信“网页授权登录”；PC 普通浏览器应使用企业微信“Web 登录”入口，二者不是同一个授权地址。
- 企业微信官方文档《Web登录组件》（2026-01-14）支持两种网站接入：使用 `@wecom/jssdk >= 2.3.2` 内嵌登录组件，或构造企微托管 Web 登录链接。
- 自建应用 Web 登录使用 `login_type=CorpApp`、企业 CorpID、应用 AgentID、回调地址和 state；成功后回调携带 `code` 与原样 state。
- 企业微信官方文档《获取用户登录身份》（2026-04-29）确认 Web 登录 code 仍由 `/cgi-bin/auth/getuserinfo` 消费，code 只能使用一次，5 分钟未使用自动过期；现有后端兑换接口可复用。
- 首版采用点击按钮后跳转企业微信托管 Web 登录页，不在 OA 登录页内嵌企微 JS-SDK 或第三方脚本。这样不扩大密码与邮箱验证码页面的脚本信任边界，并让企微 CDN 或组件异常不影响 OA 既有登录表单。
- 现有 state 是 HMAC 签名的短期 payload，不是 JWT；它包含过期时间和随机 nonce，但 nonce 当前没有持久化消费，实施时必须验证扫码入口的 CSRF 与重放边界，不能仅凭 nonce 字段宣称一次性防重放。
- 当前 `mode` 表示 `login / bind / onboard` 业务流程。PC 扫码入口不得引入 `mode=qr`；入口来源应使用独立、固定白名单字段，例如 `entrySource=pc_qr | wecom_workbench`。
## Requirements
### R1 普通 PC 浏览器入口
- 普通 PC 浏览器登录页展示清晰的“企业微信扫码登录”入口。
- 点击入口后跳转企业微信托管 Web 登录页；OA 登录页不加载 `@wecom/jssdk`、企微 CDN 脚本或内嵌二维码 iframe。
- 入口不得取代账号密码和邮箱验证码等应急方式。
- 企业微信内置 WebView 继续使用当前工作台一键进入，不重复展示 PC 扫码入口。
### R2 复用既有身份与会话链路
- Web 登录成功后的 code 复用现有 userid 获取、OA 绑定查找、唯一自动映射、会话签发、设备指纹和安全回跳逻辑。
- 已绑定且 active 的员工可直接登录；不要求先用 OA 用户名密码完成首次绑定。
- 未映射、映射冲突、OA/企微账号停用时继续失败关闭，并显示现有可理解提示。
- 不改变 `bind` 和 `onboard` 两条业务流程。
### R3 入口来源与审计
- `mode` 保持业务语义，不承担入口区分。
- `entrySource` 只接受服务端固定白名单值，未知值不得进入审计或影响授权地址选择。
- 成功登录审计记录入口来源和既有 binding source，但不记录 code、state、userid、Secret 或原始企微响应。
### R4 安全边界
- state 必须服务端签名、短时有效、校验回调来源上下文，并继续限制 returnTo，防止开放重定向。
- PC 扫码请求必须通过短期 HttpOnly、SameSite=Lax 同站关联 cookie 将随机 nonce 与发起浏览器绑定；回调校验后立即清除该 cookie，正常浏览器重复回调在 OA 侧失败关闭，不新增数据库 nonce 表。若恶意客户端同时重放回调 URL 与旧 cookie，则由企微一次性 code 阻止第二次兑换和会话创建。
- 实施前通过测试明确验证 state 篡改、过期、入口来源伪造、code 缺失、企微拒绝授权和重复回调行为。
- 前端不得接触应用 Secret；Web 登录 URL 由服务端按受控配置构造。
### R5 配置、上线与回滚
- 生产启用前只读核对现有自建应用是否已开启“企业微信授权登录”，以及 OA 域名是否满足 OAuth 可信域名或 Web 网页授权回调域名要求。
- 若需要修改企微后台、生产环境变量、部署或真实扫码验收，必须另行获得明确批准。
- 功能应具备独立开关或可安全退回现有登录页的配置边界；回滚不得影响工作台免登、密码登录和邮箱验证码登录。
## Acceptance Criteria
- [ ] 普通 PC 浏览器登录页出现明确的企业微信 Web 登录入口，企业微信内置 WebView 仍走原工作台入口。
- [ ] 已映射 active 员工使用手机企微扫码后进入原请求的安全 OA 页面，无需 OA 密码或首次绑定。
- [ ] 已登录企微桌面端时，可按企微官方组件能力完成快速登录或扫码登录。
- [ ] 未映射、冲突、OA 停用和企微停用账号均失败关闭，页面提示不引导用户先用密码绑定。
- [ ] 登录成功审计可区分 `pc_qr` 与 `wecom_workbench`，且不含 code、state、Secret、完整 userid 或原始 payload。
- [ ] state 篡改、过期、非法入口来源、缺 code、重复使用 code 和恶意 returnTo 的自动化负例通过。
- [ ] PC 扫码回调缺少、篡改或不匹配浏览器关联 cookie 时失败关闭且不调用企微 code 兑换接口；正常浏览器回调后 cookie 被清除，企微一次性 code 回归证明不会创建第二个会话。
- [ ] 现有工作台登录、绑定、onboard、账号密码和邮箱验证码回归通过。
- [ ] 本地后端/前端门禁通过；获得部署批准后，生产配置核验、公网构建标识、真实 PC 扫码和回滚检查通过，之后才通知用户可测试。
## Test Plan
- 后端单元测试覆盖 PC 配置和托管 URL、`entrySource` 白名单、state 和浏览器关联 cookie、安全回跳、成功/失败映射、审计脱敏及现有工作台/bind/onboard 回归。
- 前端测试与构建覆盖普通浏览器按钮、企微 WebView 入口隔离、配置关闭时降级，以及 returnTo/设备指纹传递。
- 执行 Prisma validate、前后端 typecheck/build、流程合同、文档审计、Trellis governance、task validate 和 `git diff --check`。
- 生产阶段另行批准后执行企微后台配置核验、公网 readiness/构建标识、现有登录回归、真实 PC 扫码、审计抽查和关闭开关回滚验证。
## Out of Scope
- 不建设新的 OA 账号体系，不要求逐人设置或分发初始密码。
- 不改变企微通讯录、userid 与 OA 账户的既有映射规则。
- 不扩展到微信个人号、第三方企业、外部联系人或多租户 SSO。
- 不在本任务重做找回密码、邮箱验证码或企业微信工作台页面体验。
- 不把 PC 扫码入口复用于绑定或新员工 onboard，除非后续任务单独批准。
- 不引入企微 JS-SDK、站内二维码 iframe，也不在本任务开启全站 CSP 改造；CSP 基线另行治理。
.trellis/tasks/07-30-pc-wecom-qr-login/task.json
+26
查看文件
@@ -0,0 +1,26 @@
{
"id": "pc-wecom-qr-login",
"name": "pc-wecom-qr-login",
"title": "PC 企业微信扫码登录",
"description": "为普通 PC 浏览器增加企业微信 Web 扫码登录入口，复用现有 userid 映射、会话签发和审计链路。",
"status": "in_progress",
"dev_type": null,
"scope": "server,client,deploy,docs",
"package": "hyb-oa",
"priority": "P2",
"creator": "shunli",
"assignee": "shunli",
"createdAt": "2026-07-30",
"completedAt": null,
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": null,
"relatedFiles": [],
"notes": "",
"meta": {}
}