📝 Chart account phone-login spec and implementation tickets

Requirements gathering for replacing email with a phone-number account
identifier (format-only validation, no SMS). Spec and five expand-migrate
-contract tickets ready for implementation.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
eust-w 2026-09-22 11:58:20 +08:00
parent 6bc3127228
commit 63df4f4bf3
6 changed files with 149 additions and 0 deletions

View File

@ -0,0 +1,15 @@
# 01: 新增手机号字段与校验(Expand)
**What to build:** `UserRecord` 新增 `Phone` 字段,Mongo 新增 `phone_unique` 唯一索引,新增中国大陆手机号格式校验(`^1[3-9]\d{9}$`)与 `FindUserByPhone` 查找方法。与现有 `Email` 字段/`email_unique` 索引/`FindUserByEmail` 并存,不改变任何现有登录、账号创建/编辑行为——这一张纯粹是"打地基",跑完之后系统对外表现应该和改动前完全一样。
**Blocked by:** None (can start immediately)
**Status:** ready-for-agent
- [ ] `internal/domain/types.go` 的 `UserRecord` 新增 `Phone string` 字段(`Email` 字段保留不动)
- [ ] Mongo 索引新增 `phone_unique`(`internal/store/mongo_indexes.go`),与 `email_unique` 并存
- [ ] 新增手机号格式校验辅助函数,正则 `^1[3-9]\d{9}$`
- [ ] `internal/store`(mongo.go / memory.go / store.go 接口)新增 `FindUserByPhone`,实现对齐现有 `FindUserByEmail` 的行为(trim/查找语义一致)
- [ ] 新增手机号唯一性检查辅助函数(对齐现有 `ensureUserEmailAvailableLocked` / `validateUserEmailAvailable` 的模式)
- [ ] 现有全部测试保持通过;新增针对手机号校验/唯一性/查找的单元测试
- [ ] 手动或自动验证:改动前后,登录、账号管理页面创建/编辑账号的行为无任何变化(`Phone` 字段此时应为空,不影响现有流程)

View File

@ -0,0 +1,15 @@
# 02: 账号管理改用手机号 + 存量账号迁移
**What to build:** 管理员在"账号管理"页面创建新账号、编辑已有账号时,用手机号替代邮箱作为身份标识(前端表单 + 后端校验/唯一性检查),并把 Fanyu 现网现有账号真实迁移到手机号——包括规格参考表里列出的 6 个账号,以及"默认供应商"下此前未逐一核对邮箱的 4 个账号(需要先重新拉取完整清单再迁移,不能照抄参考表)。完成后,账号管理页面里每个账号都有一个合法、唯一的手机号;`Email` 字段此时仍然保留在库里(供登录过渡期使用),只是不再是创建/编辑账号时的必填/主要字段。
**Blocked by:** 01(需要 `Phone` 字段、校验、唯一性检查已经存在)
**Status:** ready-for-agent
- [ ] 账号管理页面(`src/pages/Users.tsx`)创建/编辑表单的输入框从邮箱改为手机号(`type="tel"`,前端即时校验 `^1[3-9]\d{9}$`),文案同步改为"手机号"
- [ ] 后端创建/编辑账号接口(`internal/api/server.go` 相关 handler)改用手机号校验与唯一性检查,重复手机号建账号应被拒绝且错误信息不应出现"邮箱"字样
- [ ] 账号列表/搜索(`src/pages/Users.tsx` 表格列、搜索框)展示与检索手机号
- [ ] 拉取当前 Fanyu 生产环境完整账号清单(含"默认供应商"下 4 个账号),确认没有遗漏
- [ ] 按规格 [.scratch/account-phone-login/spec.md](../spec.md) 的迁移策略执行真实迁移:测试/系统账号用生成的占位手机号,`wangziyu1`(34329439971@qq.com)用规格里指定的真实手机号 `13800000006`,"默认供应商"下未核对过的账号视情况用占位号或联系本人确认
- [ ] 迁移后每个账号的手机号唯一、格式合法,账号原有角色/供应商归属/权限不受影响
- [ ] 现有测试保持通过;新增创建/编辑账号手机号校验与唯一性的测试用例

View File

@ -0,0 +1,15 @@
# 03: 登录改用手机号
**What to build:** 登录页改成"手机号 + 密码",后端登录查找改用手机号(`FindUserByPhone`)。因为这一步依赖存量账号已全部迁移完手机号(02),切换后不会有任何账号被锁在外面。邮箱字段此时仍保留在库里(供 05 收尾清理),但不再是任何登录路径的凭据。
**Blocked by:** 02(必须所有账号都已迁移到合法手机号,否则切换登录会把还没迁移的账号锁死)
**Status:** ready-for-agent
- [ ] 登录页(`src/services/api/auth.ts` 请求载荷、对应登录表单组件)输入框从邮箱改为手机号,文案同步
- [ ] 后端 `handleAuthLogin`(`internal/api/auth.go`)改用 `store.FindUserByPhone` 查找用户,密码校验逻辑不变
- [ ] 会话/Cookie 创建逻辑(`createSessionCookie`)不变(本来就只携带 `user.ID`/`organization.ID`,不含身份标识字段)
- [ ] `bootstrap-super-admin` 路径(`internal/api/auth.go:452`)同步改用手机号校验(该路径已在 Fanyu 通过 `DROBOTICFLOW_ENABLE_LEGACY_ORGANIZATION_ADMIN=false` 关闭,仅需保证代码不再依赖 `net/mail.ParseAddress` 校验邮箱,不要求额外功能验证)
- [ ] 现网五类角色账号(管理员、供应商管理员、标注员、质检审核员、最终验收员)均可用迁移后的手机号 + 原密码正常登录,登录后权限/会话行为与改动前一致
- [ ] 用旧邮箱尝试登录应失败(邮箱已不是登录凭据)
- [ ] 现有登录相关测试保持通过;新增手机号登录成功/失败路径的测试

View File

@ -0,0 +1,16 @@
# 04: 其余前端展示位替换
**What to build:** 除账号管理页面(02 已处理)和登录页(03 处理)之外,其余引用邮箱字段/文案的前端位置全部换成手机号:项目成员列表、侧边栏、账号自助资料面板、全局用户上下文。这一张只依赖手机号字段本身存在(01),跟登录路径切换(03)互相独立,可以并行。
**Blocked by:** 01(只需要 `Phone` 字段已存在并已在部分账号上填充;不依赖 03 的登录切换)
**Status:** ready-for-agent
- [ ] `src/context/UserContext.tsx`:`login`、`createUser`、`updateCurrentUser` 等签名与内部引用从 email 改为 phone
- [ ] `src/components/ProjectMembersPanel.tsx`:项目成员列表展示手机号而非邮箱
- [ ] `src/components/Sidebar.tsx`:当前登录用户信息展示手机号而非邮箱
- [ ] `src/components/UserBootstrapPanel.tsx`:文案与字段引用改为手机号(该面板对应的 bootstrap 流程在 Fanyu 已关闭,仅需保证前端不再引用邮箱字段/校验,不要求功能验证)
- [ ] `src/types.ts`:共享类型定义中的字段改名
- [ ] `src/services/api/users.ts`:请求/响应载荷字段改名(与 02 的账号管理改动衔接一致)
- [ ] 全仓库搜索确认前端不再有面向用户可见的"邮箱"文案残留(历史审计日志展示等只读存量数据除外)
- [ ] 现有前端测试保持通过

View File

@ -0,0 +1,16 @@
# 05: 收尾:彻底删除 Email 字段(Contract)
**What to build:** 全仓库移除 `Email` 字段、`email_unique` 索引、`net/mail.ParseAddress` 相关校验代码。此时登录、账号管理、所有前端展示位都已经在用手机号(03、04 均已完成),删除邮箱字段是安全的收尾清理,不应改变任何用户可见行为。
**Blocked by:** 03、04(登录路径与所有前端展示位都必须已经完全脱离邮箱字段)
**Status:** ready-for-agent
- [ ] `internal/domain/types.go`:`UserRecord.Email` 字段删除
- [ ] `internal/store/mongo_indexes.go`:`email_unique` 索引删除
- [ ] `internal/store`(mongo.go / memory.go / store.go 接口):`FindUserByEmail`、`ensureUserEmailAvailableLocked`、`validateUserEmailAvailable` 等邮箱专属函数删除或确认已无调用方
- [ ] `internal/api/auth.go`、`internal/api/server.go`:`net/mail.ParseAddress` 相关校验代码删除(若 `net/mail` 已无其他用途,一并移除 import)
- [ ] 全仓库(含测试)grep 确认已无 `.Email` / `Email` 字段引用(历史审计日志等只读存量数据结构除外,若存量数据结构本身也叫 `Email` 需单独确认是否属于本次范围)
- [ ] `go build ./...` 与全量测试套件通过,且失败数量不高于改动前基线
- [ ] 前端 `npm run lint:web` / `npm run test:frontend` 通过,失败数量不高于改动前基线
- [ ] 端到端验证:现网五类角色账号仅用手机号 + 密码即可完成登录、账号管理全部增删改查操作,邮箱在任何地方都不再可用/不再展示

View File

@ -0,0 +1,72 @@
Status: needs-plan
# 账号标识由邮箱改为手机号
## 背景
当前所有账号(管理员、供应商管理员、标注员、质检审核员、最终验收员)以邮箱作为登录标识和唯一键。业务要求改为手机号,且只做格式校验,不引入短信验证码流程。
代码现状(本次需求梳理时的实测结果,作为改动基线):
- `UserRecord`(`internal/domain/types.go:960-977`)已有独立稳定 `ID`(`domain.NewID` 生成,与邮箱无关),`Email` 只是另一个带唯一索引的字段(`internal/store/mongo_indexes.go:253-257`,索引名 `email_unique`),不是账号主键。删除 `Email`、换成 `Phone` 不影响账号本身的身份连续性。
- 登录查找:`handleAuthLogin`(`internal/api/auth.go:532`)通过 `store.FindUserByEmail`(`internal/api/auth.go:541`)按邮箱查用户再校验密码。会话/Cookie(`createSessionCookie`,`auth.go:502`)只携带 `user.ID` 和 `organization.ID`,不含邮箱,替换字段不影响会话机制。
- **当前没有任何"通过邮箱找回密码"的功能**:全仓库搜不到 SMTP/发信相关代码,密码重置目前是管理员在账号管理页面手动改(`handleAdminUserResetPassword`,`auth.go:946`)。因此本次改动不会削弱任何现有的找回密码能力——因为原本就没有。
- 邮箱格式校验用标准库 `net/mail.ParseAddress`,出现在 5 处:`internal/api/auth.go:452`(bootstrap-super-admin,已在 Fanyu 通过 `DROBOTICFLOW_ENABLE_LEGACY_ORGANIZATION_ADMIN=false` 关闭)、`auth.go:646`(用户自助改资料)、`auth.go:884`、`internal/api/server.go:7845`、`server.go:8000`(管理员建/改账号)。
- 共享校验/唯一性检查:`normalizeUserInput(name, email)`(`server.go:7785`)、`validateUserEmailAvailable`(`server.go:7789`,内部调用 `FindUserByEmail`)。
- 前端涉及邮箱的文件共 7 个:`src/types.ts`、`src/context/UserContext.tsx`、`src/components/ProjectMembersPanel.tsx`、`src/components/Sidebar.tsx`、`src/components/UserBootstrapPanel.tsx`、`src/services/api/users.ts`、`src/services/api/auth.ts`、`src/pages/Users.tsx`(账号管理主页面,邮箱输入框在 `src/pages/Users.tsx:675-679`)。
- 目前**没有任何手机号相关字段或 UI**——是从零新增,不是在已有基础上扩展。
## 决策(已锁定)
1. **产出形式**:本文档是需求/规格文档,供后续排期实现,不在本次会话里直接改代码或改生产数据。
2. **替换而非并存**:手机号完全取代邮箱作为登录标识;不做邮箱/手机号双轨过渡。
3. **校验规则**:仅做中国大陆手机号格式校验,正则 `^1[3-9]\d{9}$`(11 位,首位 1,第二位 3-9)。不做短信验证码,不支持国际号码/座机。
4. **数据模型**:`UserRecord.Email` 字段整体删除,替换为 `Phone` 字段;Mongo 唯一索引 `email_unique` 相应改为 `phone_unique`。`FindUserByEmail` 改名/替换为 `FindUserByPhone`,所有调用点、校验逻辑(`normalizeUserInput`、`validateUserEmailAvailable` 等)同步改造为手机号版本。
5. **安全模型**:手机号在系统里的作用等同于"格式受限但不验证真实性的账号标识",延续现有"管理员手动建账号、手动设初始密码"的模式,不引入验证码发送/校验环节。
6. **改动范围**:只在 `dev` 分支上实现。仓库里 `dev`/`poc`/`wjzh` 对应不同分支各自路由到不同部署环境(`dev`→Fanyu,POC 类分支→POC,参见 `scripts/load-deploy-env.sh`),因此在 `dev` 分支实现即可自然把改动限制在 Fanyu 和本地开发环境,**不需要**额外的运行时环境变量开关。POC/WJZH 所在分支不受影响(除非未来专门把改动合并过去)。
7. **迁移策略**:现有账号迁移到手机号时,测试/系统账号使用系统生成的占位手机号(示例见下表),后续可由管理员编辑成真实号码;有真实业务联系人的账号(如下表 `wangziyu1`)使用其本人真实手机号,不用占位号。**本次会话不执行任何生产数据迁移**,迁移在代码实现并验收后按正式发布流程执行。
8. **Legacy 兼容**:`bootstrap-super-admin` 路径(`auth.go:452`)沿用同一个账号字段,自动继承手机号校验,无需单独处理;该路径本身已在 Fanyu 通过 `DROBOTICFLOW_ENABLE_LEGACY_ORGANIZATION_ADMIN=false` 关闭,不是本次改动的重点。
## 现有账号 → 手机号迁移参考表
仅供实现/迁移脚本参考,本次未写入任何数据库;真正执行前需要重新拉取完整账号清单(当前"默认供应商"下还有 4 个账号未逐一核对邮箱)。
| 现有邮箱 | 角色 | 迁移手机号 | 性质 |
|---|---|---|---|
| fanyu-ops-admin@droboticflow.local | 管理员 | 13800000001 | 占位(测试/系统账号) |
| fanyu-org-admin@droboticflow.local | 供应商管理员 | 13800000002 | 占位 |
| fanyu-full-annotator@droboticflow.local | 标注员 | 13800000003 | 占位 |
| fanyu-full-qc@droboticflow.local | 质检审核员 | 13800000004 | 占位 |
| fanyu-full-acceptance@droboticflow.local | 最终验收员 | 13800000005 | 占位 |
| 34329439971@qq.com(wangziyu1) | 标注员 | 13800000006 | 真实联系人号码(用户指定) |
## 改动清单(供实现排期用,非本文档的产出物)
**后端**
- `internal/domain/types.go`:`UserRecord.Email` → `Phone`。
- `internal/store/mongo_indexes.go`:`email_unique` → `phone_unique`。
- `internal/store/store.go` / `mongo.go` / `memory.go`:`FindUserByEmail` → `FindUserByPhone`,`ensureUserEmailAvailableLocked` 同步改名改逻辑。
- `internal/api/auth.go`:`handleAuthLogin` 查找逻辑、`auth.go:646`/`884` 处校验改用手机号正则,去掉 `net/mail.ParseAddress` 依赖(若无其他用途可整体移除)。
- `internal/api/server.go`:`normalizeUserInput`、`validateUserEmailAvailable`、`7845`/`8000` 两处管理员建/改账号校验,改造为手机号版本。
**前端**
- `src/types.ts`:类型定义字段改名。
- `src/pages/Users.tsx`:输入框 `type="email"` → 手机号输入(`type="tel"` + 前端正则),搜索、表格列、创建/编辑表单同步改名改文案。
- `src/services/api/auth.ts`、`src/services/api/users.ts`:请求/响应载荷字段改名。
- `src/context/UserContext.tsx`、`src/components/ProjectMembersPanel.tsx`、`src/components/Sidebar.tsx`、`src/components/UserBootstrapPanel.tsx`:字段引用同步改名,UI 文案"邮箱"改"手机号"。
## 明确排除(不在本次范围)
- 短信验证码发送/校验。
- 邮箱找回密码(本来就不存在,不新增)。
- POC / WJZH 环境(不同分支,天然不受影响)。
- 国际号码 / 座机号码格式支持。
- 邮箱与手机号双轨并存。
## 验收标准草案
- 新建账号:手机号不符合 `^1[3-9]\d{9}$` 时创建/编辑请求应被拒绝,返回明确校验错误。
- 手机号唯一性:重复手机号建账号应被拒绝,错误信息不应还提到"邮箱"字样。
- 登录:使用手机号 + 密码可正常登录,会话/权限行为与改动前一致。
- 全仓库不应再有面向用户的"邮箱"文案残留(除非是历史审计日志等只读存量数据,允许保留原样不回填)。
- 现有 5 类角色账号迁移后,各自原有权限范围、供应商归属不变(用手机号替换邮箱视为纯身份标识变更,不影响角色/权限逻辑)。