Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
disputes.json · 10.8 KB · 163 lines
1{
2 "name": "disputes",
3 "title": "Disputes",
4 "version": 1,
5 "description": "A customer saying something went wrong, and what we did about it. The whole reason this collection exists rather than a `notes` field on the order is the OUTCOME: a dispute's ending is always a linked compensating record -- a refund, a replacement order, a wallet credit -- never an edit to the history it is arguing with (docs/logic-decisions.md #3). The parcel that left on the 3rd still left on the 3rd even when the customer says it never arrived; what changes is that a new document now says we gave the money back. kind tells the five arguments apart because they route to different people and different evidence: a shipment argument is with a carrier, a delivery argument is about a parcel the tracking says arrived, a payment argument is with a processor and has a chargeback clock on it, a product argument is with whoever bought the stock, and `other` is the honest bucket rather than a taxonomy nobody fills in truthfully. order_id/shipment_id/payment_id are all OPTIONAL relations on purpose -- a dispute references whichever thing it is about, and requiring all three would make the common case (a customer emails about an order before anybody has found the parcel) unrecordable, which is exactly when it needs recording. The load-bearing rule is enforced by hook_disputes, not by convention: a dispute may not reach `resolved` unless it NAMES its resolution, and for refund/replacement/credit that name has to resolve to a real record in the collection the kind implies. `no_action` is a legitimate ending -- some claims are simply not ours to compensate -- but it has to carry a reason in resolution_note, because a closed dispute with nothing behind it and nothing said is how a customer gets told 'it's sorted' when nothing happened, which is the failure this whole collection exists to make impossible. Deliberately NOT here, named so it reads as a decision: a review-freeze flag. plan/fulfillment-logistics-spec.md's merchandising notes never called for reviews and no reviews system exists on this server, so the field would be a column of blanks; when reviews land, a disputed order's review window should be frozen while the argument is open, and this collection is where that read comes from.",
6 "hooks": {
7 "before_write": "hook_disputes"
8 },
9 "fields": [
10 {
11 "name": "id"
12 },
13 {
14 "name": "kind",
15 "type": "enum",
16 "required": true,
17 "label": "Kind",
18 "enum": ["shipment", "delivery", "payment", "product", "other"],
19 "help": "What the argument is ABOUT, in five words that each change who picks it up. `shipment` is a parcel that went wrong in transit -- damaged, short, opened -- and the counterparty is a carrier. `delivery` is the parcel the tracking says arrived and the customer says did not, which is a different investigation with different evidence (a signature, a photo, a neighbour). `payment` is money: a charge the cardholder does not recognise, a double charge, a chargeback that has a clock on it nobody else's queue does. `product` is the goods themselves -- not as described, wrong item, faulty -- and it is the one the person who BUYS the stock needs to see. `other` is deliberately kept so nobody has to lie about a claim that fits none of the four; a longer enum would be a survey, and a survey nobody acts on is a field people stop filling in honestly."
20 },
21 {
22 "name": "order_id",
23 "type": "relation",
24 "relation": {
25 "collection": "orders",
26 "display_field": "number"
27 },
28 "label": "Order",
29 "help": "Optional, like all three references. A dispute points at whichever thing it is about, and the common case -- a customer emails about 'my order' before anybody has worked out which parcel or which payment they mean -- has an order and nothing else. Requiring more would make the moment a dispute most needs recording the moment it cannot be."
30 },
31 {
32 "name": "shipment_id",
33 "type": "relation",
34 "relation": {
35 "collection": "shipments",
36 "display_field": "tracking_number"
37 },
38 "label": "Shipment",
39 "help": "The parcel being argued about, when there is one. Set for shipment and delivery disputes; blank for a payment argument, which is about money that never had a box."
40 },
41 {
42 "name": "payment_id",
43 "type": "relation",
44 "relation": {
45 "collection": "payments",
46 "display_field": "reference"
47 },
48 "label": "Payment",
49 "help": "The money being argued about, when the argument is about money. Also what a refund resolution refunds AGAINST: money can only go back the way it came, so a payment dispute that names its payment lets action_resolve_dispute ask app-payments' ceiling directly instead of guessing which of several payments on an invoice the customer means."
50 },
51 {
52 "name": "opened_by",
53 "type": "text",
54 "label": "Opened By",
55 "help": "Who raised it -- a staff member taking the call, or blank when it arrived through a path that could not name one. Not the customer: the customer is customer_email, and conflating 'who typed this' with 'who is complaining' is how a dispute list stops being able to answer either question."
56 },
57 {
58 "name": "customer_email",
59 "type": "text",
60 "label": "Customer",
61 "validation": {
62 "max_length": 254
63 },
64 "help": "Stamped from the order when there is one, never re-read (docs/logic-decisions.md #1). The customer of THIS dispute is whoever was arguing at the time, and an order record edited next month must not silently redirect an old argument's correspondence."
65 },
66 {
67 "name": "summary",
68 "type": "text",
69 "required": true,
70 "label": "Summary",
71 "validation": {
72 "min_length": 1,
73 "max_length": 300
74 },
75 "help": "One line somebody can scan a queue by. Required because a dispute row with no summary is indistinguishable from a mis-click, and a queue of those teaches people to ignore the queue."
76 },
77 {
78 "name": "detail",
79 "type": "textarea",
80 "label": "Detail",
81 "help": "The customer's own words and everything found since, kept long-form next to the one-line summary. The summary is what a list shows; this is what the person picking it up actually reads."
82 },
83 {
84 "name": "status",
85 "type": "enum",
86 "required": true,
87 "label": "Status",
88 "default": "open",
89 "enum": ["open", "investigating", "resolved", "withdrawn"],
90 "transitions": {
91 "open": [
92 {"to": "investigating", "when": {"owner_id": "$user_id"}},
93 {"to": "resolved", "when": {"owner_id": "$user_id"}},
94 {"to": "withdrawn", "when": {"owner_id": "$user_id"}}
95 ],
96 "investigating": [
97 {"to": "resolved", "when": {"owner_id": "$user_id"}},
98 {"to": "withdrawn", "when": {"owner_id": "$user_id"}}
99 ]
100 },
101 "help": "open is a claim nobody has picked up -- the state the attention count exists to drain. investigating means a human has it and is finding out. resolved means we DID something, and what we did is named in resolution_kind and resolution_ref; hook_disputes refuses this move unless it is, because a dispute closed with nothing behind it is how a customer gets told it is sorted when nothing happened. withdrawn is the customer dropping it, which is a real and common ending and deliberately NOT the same as resolved -- filing it under resolved would salt every 'what did we pay out' report with claims that cost nothing. open -> resolved skips investigating on purpose: an obvious refund on a two-pound item should not need a bookkeeping hop nobody performs. resolved and withdrawn are terminal, for the same reason a refund is a new record and not an edited payment -- a second argument is a second dispute, never a reopened one."
102 },
103 {
104 "name": "resolution_kind",
105 "type": "enum",
106 "label": "Resolution",
107 "enum": ["refund", "replacement", "credit", "no_action"],
108 "help": "How it ended, and the field that decides which collection resolution_ref must point INTO: refund -> refunds, replacement -> orders, credit -> wallet_entries. Blank while the dispute is open, which is why this is not required at the schema level -- the requirement is conditional on status, and a schema cannot say that. hook_disputes says it instead. no_action is a first-class ending (a claim outside the return window, a carrier delay nobody owes for, a customer who found the parcel behind the bins) and needs no ref, but it does need a reason in resolution_note."
109 },
110 {
111 "name": "resolution_ref",
112 "type": "text",
113 "label": "Resolution Record",
114 "validation": {
115 "max_length": 200
116 },
117 "help": "'refunds/{id}' | 'orders/{id}' | 'wallet_entries/{id}' -- a pointer at the compensating record, never an amount. Two copies of one number is a disagreement waiting to be found by the customer, and the amount already lives on the record this points at. hook_disputes RESOLVES this: the collection has to match the resolution_kind and the id has to name a row that exists, because a plausible-looking reference to nothing is worse than a blank one -- a blank field is visibly unfinished, and 'refunds/abc123' reads as done."
118 },
119 {
120 "name": "resolution_note",
121 "type": "textarea",
122 "label": "Resolution Note",
123 "help": "Why it ended the way it did. Optional for a refund or a replacement, where the linked record already says what happened -- REQUIRED for no_action, because 'we are not compensating this' is a decision somebody will be asked to justify weeks later, usually by the customer and occasionally by a card processor, and a bare no_action with no sentence behind it is indistinguishable from a queue somebody cleared to make the number go down."
124 },
125 {
126 "name": "resolved_by",
127 "type": "text",
128 "label": "Resolved By",
129 "help": "Which human decided. The same second-person shape returns and expenses use: a resolution usually costs the shop money, so the record says who agreed to spend it."
130 },
131 {
132 "name": "resolved_at",
133 "type": "datetime",
134 "label": "Resolved"
135 },
136 {
137 "name": "owner_id",
138 "type": "text",
139 "label": "Owner"
140 },
141 {
142 "name": "created_at",
143 "type": "datetime",
144 "label": "Raised",
145 "read_only": true
146 }
147 ],
148 "forms": {
149 "default": {
150 "fields": ["kind", "order_id", "shipment_id", "payment_id", "opened_by",
151 "customer_email", "summary", "detail", "status",
152 "resolution_kind", "resolution_ref", "resolution_note"]
153 }
154 },
155 "views": {
156 "list_mode": "table",
157 "list_fields": ["created_at", "kind", "status", "summary", "resolution_kind"],
158 "filter_fields": ["status", "kind", "resolution_kind"]
159 },
160 "search": {
161 "fields": ["summary", "detail", "customer_email"]
162 }
163}