口译下单系统 · 接口与架构
Phase 1 数据层与接口已就绪，Phase 2 三端界面（客户下单 / 译员工作台 / 平台后台）已落地。
浏览器不持有任何密钥
接口层需要
x-app-key，那是服务端密钥，不能下发到浏览器。 浏览器只持有两个无密钥 cookie（im_actor / im_ref）， 由中间件在服务端翻译成完整鉴权头再内部重写到真实接口。 这套机制不构成真实身份认证，Phase 4 替换为手机号 + 短信验证码 / 企微 OAuth 会话。价差脱敏有两层，都要摘
第一层是价差（销售价 − 译员到手价 = 平台毛利），任一侧暴露都等于泄露； 第二层是税前申报额与公司税负，可反推出到手价进而反推出毛利。 价格接口按身份裁剪：管理侧拿两列 + 真实毛利，客户侧只拿销售价，译员侧只拿到手价。 译员侧流水还会把同单的「服务收入 + 代扣税」两条腿合并成一条到手记录， 否则「承诺到手 ¥1520」与「挣了 ¥1700 被扣 ¥180」会直接打架。
派单由平台掌握（支付后不自动公开）
订单支付后落在
PENDING_DISPATCH，由管理员二选一：公开（PUBLISH → OPEN）或定向指派（ASSIGN → ASSIGNED，只被指派者可见，并立即预占其当日档期）。 译员弃单（RELEASE）或拒单（UNASSIGN）都退回待派单，交由管理员重新决策，不自动回流公开池。个税：译员侧价格 = 到手价，税负由公司承担
公司是法定扣缴义务人，须按「劳务报酬所得」申报并代扣代缴。当前口径
bearer = PLATFORM： 给译员写的价格就是到手价，系统反算税前申报额，税负计入公司成本。 以英/日/韩档为例：销售价 ¥2000、到手价 ¥1520 → 反算税前申报额 ¥1700（减除费用 800 → 基数 900 → 20% → 代扣 ¥180），实付译员 1520。⚠️ 因此账面毛差不等于真实毛利：真实毛利 = 客户应付 − 税前申报额 （该单 2000 − 1700 = ¥300，而非 2000 − 1520 = 480）。 且月度累计预扣下，同一译员同月接得越多、公司单均税负越高（第二单税前升到 ¥1900，毛利降到 ¥100）， 这是法定结果，运营定价须计入。
价格两列独立配置，不由百分比派生
曾经按「到手 = 销售价 × 85%」派生，实测在包税口径下会亏：到手 ≤4000 时公司成本 = 1.25 × 到手 − 200， 代入即 1.0625 × 销售价 − 200，销售价 ¥3200 是盈亏平衡点，英日韩 2 天单（¥4000）直接亏损。 现在销售价与译员到手价在后台两列手工填，配置页实时显示真实毛利并在低于 10% 时标红 （亏损只警告不拦截——定价是平台自己的商业决策，系统只负责让你看见）。 当前三档到手价按保 15% 毛利设定：2000→1520 / 2500→1860 / 3000→2200。
接口清单
| 方法 | 路径 | 说明 | 所需身份 |
|---|---|---|---|
GET | /api/health | 健康检查（无需鉴权） | — |
POST | /api/quote | 实时试算报价（按身份脱敏） | 任意 |
GET | /api/pricing | 读价格配置（按身份裁剪：管理=两列+毛利／客户=销售价／译员=到手价） | 任意 |
PUT | /api/pricing | 保存价格配置（销售价与到手价两列独立；亏损只警告不拦截） | ADMIN |
GET | /api/tax | 读个税规则 + 法定预扣率表 | ADMIN |
PUT | /api/tax | 保存个税规则（含税负承担方 bearer） | ADMIN |
POST | /api/orders | 下单（金额服务端重算，前端传的 amount 被忽略） | CUSTOMER |
GET | /api/orders | 订单列表（按身份自动收敛范围） | 全部 |
GET | /api/orders/{code} | 订单详情 + 流转留痕（管理侧含税务快照） | 全部 |
GET | /api/orders/{code}/candidates | 派单候选译员（资质相符 + 当日档期可用） | ADMIN |
POST | /api/orders/{code}/transition | 状态机入口 PAY/PUBLISH/ASSIGN/UNASSIGN/ACCEPT/RELEASE/FINISH/CONFIRM/CANCEL | 按动作 |
GET | /api/hall | 订单大厅（仅 OPEN 单；译员端带可接单标记） | INTERPRETER / ADMIN |
GET | /api/interpreters | 译员名单 + 余额 | ADMIN / INTERPRETER |
POST | /api/interpreters | 新建译员（必须配语种；等级不参与定价与接单资格） | ADMIN |
GET | /api/interpreters/{id}/wallet | 译员工作台：余额/流水/档期/任务（译员侧流水已合并到手口径） | 本人 / ADMIN |
GET | /api/withdrawals | 提现列表 | 本人 / ADMIN |
POST | /api/withdrawals | 申请提现（申请即冻结） | INTERPRETER |
POST | /api/withdrawals/{id}/decide | 提现审核 APPROVE / REJECT | ADMIN |
GET | /api/admin/stats | 平台 KPI（含真实毛利拆解） | ADMIN |
GET | /api/admin/customers | 客户管理（按手机号聚合） | ADMIN |
GET | /api/admin/feedback | 评价汇总 | ADMIN |
POST | /api/auth/sms-code | 发送登录验证码（60 秒 / 1 小时 5 条 / 24 小时 10 条三道频控） | — |
POST | /api/auth/login | 验证码登录：按手机号判定身份并签发签名会话 | — |
POST | /api/auth/logout | 登出：清除会话 cookie | — |
GET | /api/session | 当前登录身份（会话 cookie 是 httpOnly，浏览器只能问服务端） | 会话 |
* | /api/proxy/{path} | 浏览器唯一入口：中间件验签后注入 x-app-key 与身份头 | 会话 |